GeoTiff data component

The GeoTiff data component, pymt_geotiff, is a Python Modeling Toolkit (pymt) library for accessing data (and metadata) from a GeoTIFF file, through either a local filepath or a remote URL.

The pymt_geotiff component provides BMI-mediated access to GeoTIFF data as a service, allowing them to be coupled in pymt with other data or model components that expose a BMI.

Installation

pymt, and components that run within it, are distributed through Anaconda and the conda package manager. Instructions for installing Anaconda can be found on their website. In particular, pymt components are available through the community-led conda-forge organization.

Install the pymt and pymt_geotiff packages in a new environment with:

$ conda create -n pymt -c conda-forge python=3 pymt pymt_geotiff
$ conda activate pymt

conda automatically resolves and installs any required dependencies.

Use

The pymt_geotiff data component is designed to access data in a GeoTIFF file, with the user providing the location of the file through either a filepath or an URL. This information can be provided through a configuration file or specified through parameters.

With a configuration file

The pymt_geotiff configuration file is a YAML file containing keys that map to parameter names. An example is bmi-geotiff.yaml:

bmi-geotiff:
  filename: https://github.com/mapbox/rasterio/raw/master/tests/data/RGB.byte.tif

Download this file for use in the following example.

Start by importing the GeoTiff class from pymt.

from pymt.models import GeoTiff

Create an instance.

m = GeoTiff()

In this case, we’ll initialize the GeoTiff component with information from a configuration file. (This may take a moment as data are fetched from the internet.)

m.initialize("bmi-geotiff.yaml")

Note that the configurtation information has been read from the configuration file into the component as parameters.

What variables can be accessed from this component?

for var in m.output_var_names:
    print(var)

gis__raster_data
gis__coordinate_reference_system
gis__gdal_geotransform

Get the GDAL GeoTransform used by the data.

m.var["gis__gdal_geotransform"].data

array([  3.00037927e+02,   0.00000000e+00,   1.01985000e+05,
         0.00000000e+00,  -3.00041783e+02,   2.82691500e+06])

What are the units of the transformation?

m.var["gis__gdal_geotransform"].units

'm'

Finish by finalizing the component.

m.finalize()

With parameters

Configuration information can also be passed directly to pymt_geotiff as parameters.

Start by importing the GeoTiff class from pymt and creating an instance.

from pymt.models import GeoTiff
m = GeoTiff()

Next, use the setup method to assign values to the parameters needed by GeoTiff.

args = m.setup(
    "test",
    filename="https://github.com/mapbox/rasterio/raw/master/tests/data/RGB.byte.tif",
)

Pass the results from setup into the initialize method. (This step may take a moment as data are fetched from the internet.)

m.initialize(*args)

*** <xarray.Rectilinear>
Dimensions:     (rank: 3)
Dimensions without coordinates: rank
Data variables:
    mesh        int64 0
    node_shape  (rank) int32 3 718 791

Note that the parameters have been correctly assigned in the component:

for param in m.parameters:
    print(param)

('filename', 'https://github.com/mapbox/rasterio/raw/master/tests/data/RGB.byte.tif')

What variables can be accessed from this component?

for var in m.output_var_names:
    print(var)

gis__raster_data
gis__coordinate_reference_system
gis__gdal_geotransform

Get the raster data values.

raster = m.var["gis__raster_data"].data

Let’s visualize these data.

The pymt_geotiff component contains not only data values, but also the grid on which they’re located. Start by getting the identifier for the grid used for the raster data.

gid = m.var_grid("gis__raster_data")

Using the grid identifier, we can get the grid dimensions and the locations of the grid nodes.

shape = m.grid_shape(gid)
x = m.grid_x(gid)
y = m.grid_y(gid)
print("shape:", shape)
print("x:", x)
print("y:", y)

shape: [  3 718 791]
x: [ 102135.01896334  102435.05689001  102735.09481669  103035.13274336
  ...
  338564.90518331  338864.94310999  339164.98103666]
y: [ 2826764.97910863  2826464.93732591  2826164.89554318  2825864.85376045
  ...
  2611935.06267409  2611635.02089137]

We’re almost ready to make a plot. Note, however, that the default behavior of pymt components is to flatten data arrays.

raster.shape

(1703814,)

Make a new variable that restores the dimensionality of the data.

raster3D = raster.reshape(shape)
raster3D.shape

(3, 718, 791)

Extract the red band from the image.

red_band = raster3D[0,:,:]
red_band.shape

(718, 791)

What information do we have about how the data are projected?

projection = m.var["gis__coordinate_reference_system"].data
projection

array(['+init=epsg:32618'],
      dtype='<U16')

transform = m.var["gis__gdal_geotransform"].data
transform

array([  3.00037927e+02,   0.00000000e+00,   1.01985000e+05,
         0.00000000e+00,  -3.00041783e+02,   2.82691500e+06])

We’ll use cartopy to help display the data in a map projection.

import cartopy.crs as ccrs

The data are in UTM zone 18N, but the projection must be set manually. (A note in the xarray documentation describes this.)

crs = ccrs.UTM('18N')

Display the red band of the image in the appropriate projection.

import matplotlib.pyplot as plt

ax = plt.subplot(projection=crs)
ax.imshow(red_band, transform=crs, extent=[x.min(),x.max(),y.min(),y.max()], cmap="pink")

<matplotlib.image.AxesImage at 0x1a23b4be0>

Complete the example by finalizing the component.

m.finalize()

API documentation

Looking for information on a particular function, class, or method? This part of the documentation is for you.

pymt_geotiff

pymt_geotiff package

Submodules

pymt_geotiff.bmi module

class pymt_geotiff.bmi.GeoTiff

Bases: bmipy.bmi.Bmi

BMI-mediated access to data and metadata in a GeoTIFF file.

METADATA = '/home/docs/checkouts/readthedocs.org/user_builds/pymt-geotiff/checkouts/stable/pymt_geotiff/data/GeoTiff'

finalize() → None

Perform tear-down tasks for the model.

Perform all tasks that take place after exiting the model’s time loop. This typically includes deallocating memory, closing files and printing reports.

get_component_name() → str

Name of the component.

Returns

The name of the component.

Return type

str

get_current_time() → float

Current time of the model.

Returns

The current model time.

Return type

float

get_end_time() → float

End time of the model.

Returns

The maximum model time.

Return type

float

get_grid_edge_count(grid: int) → int

Get the number of edges in the grid.

Parameters

grid (int) – A grid identifier.

Returns

The total number of grid edges.

Return type

int

get_grid_edge_nodes(grid: int, edge_nodes: numpy.ndarray) → numpy.ndarray

Get the edge-node connectivity.

Parameters

• grid (int) – A grid identifier.

• edge_nodes (ndarray of int, shape (2 x nnodes,)) – A numpy array to place the edge-node connectivity. For each edge, connectivity is given as node at edge tail, followed by node at edge head.

Returns

The input numpy array that holds the edge-node connectivity.

Return type

ndarray of int

get_grid_face_count(grid: int) → int

Get the number of faces in the grid.

Parameters

grid (int) – A grid identifier.

Returns

The total number of grid faces.

Return type

int

get_grid_face_edges(grid: int, face_edges: numpy.ndarray) → numpy.ndarray

Get the face-edge connectivity.

Parameters

• grid (int) – A grid identifier.

• face_edges (ndarray of int) – A numpy array to place the face-edge connectivity.

Returns

The input numpy array that holds the face-edge connectivity.

Return type

ndarray of int

get_grid_face_nodes(grid: int, face_nodes: numpy.ndarray) → numpy.ndarray

Get the face-node connectivity.

Parameters

• grid (int) – A grid identifier.

• face_nodes (ndarray of int) – A numpy array to place the face-node connectivity. For each face, the nodes (listed in a counter-clockwise direction) that form the boundary of the face.

Returns

The input numpy array that holds the face-node connectivity.

Return type

ndarray of int

get_grid_node_count(grid: int) → int

Get the number of nodes in the grid.

Parameters

grid (int) – A grid identifier.

Returns

The total number of grid nodes.

Return type

int

get_grid_nodes_per_face(grid: int, nodes_per_face: numpy.ndarray) → numpy.ndarray

Get the number of nodes for each face.

Parameters

• grid (int) – A grid identifier.

• nodes_per_face (ndarray of int, shape (nfaces,)) – A numpy array to place the number of edges per face.

Returns

The input numpy array that holds the number of nodes per edge.

Return type

ndarray of int

get_grid_origin(grid: int, origin: numpy.ndarray) → numpy.ndarray

Get coordinates for the lower-left corner of the computational grid.

Parameters

• grid (int) – A grid identifier.

• origin (ndarray of float, shape (ndim,)) – A numpy array to hold the coordinates of the lower-left corner of the grid.

Returns

The input numpy array that holds the coordinates of the grid’s lower-left corner.

Return type

ndarray of float

get_grid_rank(grid: int) → int

Get number of dimensions of the computational grid.

Parameters

grid (int) – A grid identifier.

Returns

Rank of the grid.

Return type

int

get_grid_shape(grid: int, shape: numpy.ndarray) → numpy.ndarray

Get dimensions of the computational grid.

Parameters

• grid (int) – A grid identifier.

• shape (ndarray of int, shape (ndim,)) – A numpy array into which to place the shape of the grid.

Returns

The input numpy array that holds the grid’s shape.

Return type

ndarray of int

get_grid_size(grid: int) → int

Get the total number of elements in the computational grid.

Parameters

grid (int) – A grid identifier.

Returns

Size of the grid.

Return type

int

get_grid_spacing(grid: int, spacing: numpy.ndarray) → numpy.ndarray

Get distance between nodes of the computational grid.

Parameters

• grid (int) – A grid identifier.

• spacing (ndarray of float, shape (ndim,)) – A numpy array to hold the spacing between grid rows and columns.

Returns

The input numpy array that holds the grid’s spacing.

Return type

ndarray of float

get_grid_type(grid: int) → str

Get the grid type as a string.

Parameters

grid (int) – A grid identifier.

Returns

Type of grid as a string.

Return type

str

get_grid_x(grid: int, x: numpy.ndarray) → numpy.ndarray

Get coordinates of grid nodes in the x direction.

Parameters

• grid (int) – A grid identifier.

• x (ndarray of float, shape (nrows,)) – A numpy array to hold the x-coordinates of the grid node columns.

Returns

The input numpy array that holds the grid’s column x-coordinates.

Return type

ndarray of float

get_grid_y(grid: int, y: numpy.ndarray) → numpy.ndarray

Get coordinates of grid nodes in the y direction.

Parameters

• grid (int) – A grid identifier.

• y (ndarray of float, shape (ncols,)) – A numpy array to hold the y-coordinates of the grid node rows.

Returns

The input numpy array that holds the grid’s row y-coordinates.

Return type

ndarray of float

get_grid_z(grid: int, z: numpy.ndarray) → numpy.ndarray

Get coordinates of grid nodes in the z direction.

Parameters

• grid (int) – A grid identifier.

• z (ndarray of float, shape (nlayers,)) – A numpy array to hold the z-coordinates of the grid nodes layers.

Returns

The input numpy array that holds the grid’s layer z-coordinates.

Return type

ndarray of float

get_input_item_count() → int

Count of a model’s input variables.

Returns

The number of input variables.

Return type

int

get_input_var_names() → Tuple[str]

List of a model’s input variables.

Input variable names must be CSDMS Standard Names, also known as long variable names.

Returns

The input variables for the model.

Return type

list of str

Notes

Standard Names enable the CSDMS framework to determine whether an input variable in one model is equivalent to, or compatible with, an output variable in another model. This allows the framework to automatically connect components.

Standard Names do not have to be used within the model.

get_output_item_count() → int

Count of a model’s output variables.

Returns

The number of output variables.

Return type

int

get_output_var_names() → Tuple[str]

List of a model’s output variables.

Output variable names must be CSDMS Standard Names, also known as long variable names.

Returns

The output variables for the model.

Return type

list of str

get_start_time() → float

Start time of the model.

Model times should be of type float.

Returns

The model start time.

Return type

float

get_time_step() → float

Current time step of the model.

The model time step should be of type float.

Returns

The time step used in model.

Return type

float

get_time_units() → str

Time units of the model.

Returns

The model time unit; e.g., days or s.

Return type

float

Notes

CSDMS uses the UDUNITS standard from Unidata.

get_value(name: str, dest: numpy.ndarray) → numpy.ndarray

Get a copy of values of the given variable.

This is a getter for the model, used to access the model’s current state. It returns a copy of a model variable, with the return type, size and rank dependent on the variable.

Parameters

• name (str) – An input or output variable name, a CSDMS Standard Name.

• dest (ndarray) – A numpy array into which to place the values.

Returns

The same numpy array that was passed as an input buffer.

Return type

ndarray

get_value_at_indices(name: str, dest: numpy.ndarray, inds: numpy.ndarray) → numpy.ndarray

Get values at particular indices.

Parameters

• name (str) – An input or output variable name, a CSDMS Standard Name.

• dest (ndarray) – A numpy array into which to place the values.

• indices (array_like) – The indices into the variable array.

Returns

Value of the model variable at the given location.

Return type

array_like

get_value_ptr(name: str) → numpy.ndarray

Get a reference to values of the given variable.

This is a getter for the model, used to access the model’s current state. It returns a reference to a model variable, with the return type, size and rank dependent on the variable.

Parameters

name (str) – An input or output variable name, a CSDMS Standard Name.

Returns

A reference to a model variable.

Return type

array_like

get_var_grid(name: str) → int

Get grid identifier for the given variable.

Parameters

name (str) – An input or output variable name, a CSDMS Standard Name.

Returns

The grid identifier.

Return type

int

get_var_itemsize(name: str) → int

Get memory use for each array element in bytes.

Parameters

name (str) – An input or output variable name, a CSDMS Standard Name.

Returns

Item size in bytes.

Return type

int

get_var_location(name: str) → str

Get the grid element type that the a given variable is defined on.

The grid topology can be composed of nodes, edges, and faces.

node

A point that has a coordinate pair or triplet: the most basic element of the topology.

edge

A line or curve bounded by two nodes.

face

A plane or surface enclosed by a set of edges. In a 2D horizontal application one may consider the word “polygon”, but in the hierarchy of elements the word “face” is most common.

Parameters

name (str) – An input or output variable name, a CSDMS Standard Name.

Returns

The grid location on which the variable is defined. Must be one of “node”, “edge”, or “face”.

Return type

str

Notes

CSDMS uses the ugrid conventions to define unstructured grids.

get_var_nbytes(name: str) → int

Get size, in bytes, of the given variable.

Parameters

name (str) – An input or output variable name, a CSDMS Standard Name.

Returns

The size of the variable, counted in bytes.

Return type

int

get_var_type(name: str) → str

Get data type of the given variable.

Parameters

name (str) – An input or output variable name, a CSDMS Standard Name.

Returns

The Python variable type; e.g., str, int, float.

Return type

str

get_var_units(name: str) → str

Get units of the given variable.

Standard unit names, in lower case, should be used, such as meters or seconds. Standard abbreviations, like m for meters, are also supported. For variables with compound units, each unit name is separated by a single space, with exponents other than 1 placed immediately after the name, as in m s-1 for velocity, W m-2 for an energy flux, or km2 for an area.

Parameters

name (str) – An input or output variable name, a CSDMS Standard Name.

Returns

The variable units.

Return type

str

Notes

CSDMS uses the UDUNITS standard from Unidata.

initialize(config_file: str) → None

Perform startup tasks for the model.

Perform all tasks that take place before entering the model’s time loop, including opening files and initializing the model state. Model inputs are read from a text-based configuration file, specified by filename.

Parameters

config_file (str, optional) – The path to the model configuration file.

Notes

Models should be refactored, if necessary, to use a configuration file. CSDMS does not impose any constraint on how configuration files are formatted, although YAML is recommended. A template of a model’s configuration file with placeholder values is used by the BMI.

set_value(name: str, values: numpy.ndarray) → None

Specify a new value for a model variable.

This is the setter for the model, used to change the model’s current state. It accepts, through src, a new value for a model variable, with the type, size and rank of src dependent on the variable.

Parameters

• var_name (str) – An input or output variable name, a CSDMS Standard Name.

• src (array_like) – The new value for the specified variable.

set_value_at_indices(name: str, inds: numpy.ndarray, src: numpy.ndarray) → None

Specify a new value for a model variable at particular indices.

Parameters

• var_name (str) – An input or output variable name, a CSDMS Standard Name.

• indices (array_like) – The indices into the variable array.

• src (array_like) – The new value for the specified variable.

update() → None

Advance model state by one time step.

Perform all tasks that take place within one pass through the model’s time loop. This typically includes incrementing all of the model’s state variables. If the model’s state variables don’t change in time, then they can be computed by the initialize() method and this method can return with no action.

update_until(time: float) → None

Advance model state until the given time.

Parameters

time (float) – A model time later than the current model time.

Module contents

class pymt_geotiff.GeoTiff

Bases: bmipy.bmi.Bmi

BMI-mediated access to data and metadata in a GeoTIFF file.

METADATA = '/home/docs/checkouts/readthedocs.org/user_builds/pymt-geotiff/checkouts/stable/pymt_geotiff/data/GeoTiff'

finalize() → None

Perform tear-down tasks for the model.

Perform all tasks that take place after exiting the model’s time loop. This typically includes deallocating memory, closing files and printing reports.

get_component_name() → str

Name of the component.

Returns

The name of the component.

Return type

str

get_current_time() → float

Current time of the model.

Returns

The current model time.

Return type

float

get_end_time() → float

End time of the model.

Returns

The maximum model time.

Return type

float

get_grid_edge_count(grid: int) → int

Get the number of edges in the grid.

Parameters

grid (int) – A grid identifier.

Returns

The total number of grid edges.

Return type

int

get_grid_edge_nodes(grid: int, edge_nodes: numpy.ndarray) → numpy.ndarray

Get the edge-node connectivity.

Parameters

• grid (int) – A grid identifier.

• edge_nodes (ndarray of int, shape (2 x nnodes,)) – A numpy array to place the edge-node connectivity. For each edge, connectivity is given as node at edge tail, followed by node at edge head.

Returns

The input numpy array that holds the edge-node connectivity.

Return type

ndarray of int

get_grid_face_count(grid: int) → int

Get the number of faces in the grid.

Parameters

grid (int) – A grid identifier.

Returns

The total number of grid faces.

Return type

int

get_grid_face_edges(grid: int, face_edges: numpy.ndarray) → numpy.ndarray

Get the face-edge connectivity.

Parameters

• grid (int) – A grid identifier.

• face_edges (ndarray of int) – A numpy array to place the face-edge connectivity.

Returns

The input numpy array that holds the face-edge connectivity.

Return type

ndarray of int

get_grid_face_nodes(grid: int, face_nodes: numpy.ndarray) → numpy.ndarray

Get the face-node connectivity.

Parameters

• grid (int) – A grid identifier.

• face_nodes (ndarray of int) – A numpy array to place the face-node connectivity. For each face, the nodes (listed in a counter-clockwise direction) that form the boundary of the face.

Returns

The input numpy array that holds the face-node connectivity.

Return type

ndarray of int

get_grid_node_count(grid: int) → int

Get the number of nodes in the grid.

Parameters

grid (int) – A grid identifier.

Returns

The total number of grid nodes.

Return type

int

get_grid_nodes_per_face(grid: int, nodes_per_face: numpy.ndarray) → numpy.ndarray

Get the number of nodes for each face.

Parameters

• grid (int) – A grid identifier.

• nodes_per_face (ndarray of int, shape (nfaces,)) – A numpy array to place the number of edges per face.

Returns

The input numpy array that holds the number of nodes per edge.

Return type

ndarray of int

get_grid_origin(grid: int, origin: numpy.ndarray) → numpy.ndarray

Get coordinates for the lower-left corner of the computational grid.

Parameters

• grid (int) – A grid identifier.

• origin (ndarray of float, shape (ndim,)) – A numpy array to hold the coordinates of the lower-left corner of the grid.

Returns

The input numpy array that holds the coordinates of the grid’s lower-left corner.

Return type

ndarray of float

get_grid_rank(grid: int) → int

Get number of dimensions of the computational grid.

Parameters

grid (int) – A grid identifier.

Returns

Rank of the grid.

Return type

int

get_grid_shape(grid: int, shape: numpy.ndarray) → numpy.ndarray

Get dimensions of the computational grid.

Parameters

• grid (int) – A grid identifier.

• shape (ndarray of int, shape (ndim,)) – A numpy array into which to place the shape of the grid.

Returns

The input numpy array that holds the grid’s shape.

Return type

ndarray of int

get_grid_size(grid: int) → int

Get the total number of elements in the computational grid.

Parameters

grid (int) – A grid identifier.

Returns

Size of the grid.

Return type

int

get_grid_spacing(grid: int, spacing: numpy.ndarray) → numpy.ndarray

Get distance between nodes of the computational grid.

Parameters

• grid (int) – A grid identifier.

• spacing (ndarray of float, shape (ndim,)) – A numpy array to hold the spacing between grid rows and columns.

Returns

The input numpy array that holds the grid’s spacing.

Return type

ndarray of float

get_grid_type(grid: int) → str

Get the grid type as a string.

Parameters

grid (int) – A grid identifier.

Returns

Type of grid as a string.

Return type

str

get_grid_x(grid: int, x: numpy.ndarray) → numpy.ndarray

Get coordinates of grid nodes in the x direction.

Parameters

• grid (int) – A grid identifier.

• x (ndarray of float, shape (nrows,)) – A numpy array to hold the x-coordinates of the grid node columns.

Returns

The input numpy array that holds the grid’s column x-coordinates.

Return type

ndarray of float

get_grid_y(grid: int, y: numpy.ndarray) → numpy.ndarray

Get coordinates of grid nodes in the y direction.

Parameters

• grid (int) – A grid identifier.

• y (ndarray of float, shape (ncols,)) – A numpy array to hold the y-coordinates of the grid node rows.

Returns

The input numpy array that holds the grid’s row y-coordinates.

Return type

ndarray of float

get_grid_z(grid: int, z: numpy.ndarray) → numpy.ndarray

Get coordinates of grid nodes in the z direction.

Parameters

• grid (int) – A grid identifier.

• z (ndarray of float, shape (nlayers,)) – A numpy array to hold the z-coordinates of the grid nodes layers.

Returns

The input numpy array that holds the grid’s layer z-coordinates.

Return type

ndarray of float

get_input_item_count() → int

Count of a model’s input variables.

Returns

The number of input variables.

Return type

int

get_input_var_names() → Tuple[str]

List of a model’s input variables.

Input variable names must be CSDMS Standard Names, also known as long variable names.

Returns

The input variables for the model.

Return type

list of str

Notes

Standard Names enable the CSDMS framework to determine whether an input variable in one model is equivalent to, or compatible with, an output variable in another model. This allows the framework to automatically connect components.

Standard Names do not have to be used within the model.

get_output_item_count() → int

Count of a model’s output variables.

Returns

The number of output variables.

Return type

int

get_output_var_names() → Tuple[str]

List of a model’s output variables.

Output variable names must be CSDMS Standard Names, also known as long variable names.

Returns

The output variables for the model.

Return type

list of str

get_start_time() → float

Start time of the model.

Model times should be of type float.

Returns

The model start time.

Return type

float

get_time_step() → float

Current time step of the model.

The model time step should be of type float.

Returns

The time step used in model.

Return type

float

get_time_units() → str

Time units of the model.

Returns

The model time unit; e.g., days or s.

Return type

float

Notes

CSDMS uses the UDUNITS standard from Unidata.

get_value(name: str, dest: numpy.ndarray) → numpy.ndarray

Get a copy of values of the given variable.

This is a getter for the model, used to access the model’s current state. It returns a copy of a model variable, with the return type, size and rank dependent on the variable.

Parameters

• name (str) – An input or output variable name, a CSDMS Standard Name.

• dest (ndarray) – A numpy array into which to place the values.

Returns

The same numpy array that was passed as an input buffer.

Return type

ndarray

get_value_at_indices(name: str, dest: numpy.ndarray, inds: numpy.ndarray) → numpy.ndarray

Get values at particular indices.

Parameters

• name (str) – An input or output variable name, a CSDMS Standard Name.

• dest (ndarray) – A numpy array into which to place the values.

• indices (array_like) – The indices into the variable array.

Returns

Value of the model variable at the given location.

Return type

array_like

get_value_ptr(name: str) → numpy.ndarray

Get a reference to values of the given variable.

This is a getter for the model, used to access the model’s current state. It returns a reference to a model variable, with the return type, size and rank dependent on the variable.

Parameters

name (str) – An input or output variable name, a CSDMS Standard Name.

Returns

A reference to a model variable.

Return type

array_like

get_var_grid(name: str) → int

Get grid identifier for the given variable.

Parameters

name (str) – An input or output variable name, a CSDMS Standard Name.

Returns

The grid identifier.

Return type

int

get_var_itemsize(name: str) → int

Get memory use for each array element in bytes.

Parameters

name (str) – An input or output variable name, a CSDMS Standard Name.

Returns

Item size in bytes.

Return type

int

get_var_location(name: str) → str

Get the grid element type that the a given variable is defined on.

The grid topology can be composed of nodes, edges, and faces.

node

A point that has a coordinate pair or triplet: the most basic element of the topology.

edge

A line or curve bounded by two nodes.

face

A plane or surface enclosed by a set of edges. In a 2D horizontal application one may consider the word “polygon”, but in the hierarchy of elements the word “face” is most common.

Parameters

name (str) – An input or output variable name, a CSDMS Standard Name.

Returns

The grid location on which the variable is defined. Must be one of “node”, “edge”, or “face”.

Return type

str

Notes

CSDMS uses the ugrid conventions to define unstructured grids.

get_var_nbytes(name: str) → int

Get size, in bytes, of the given variable.

Parameters

name (str) – An input or output variable name, a CSDMS Standard Name.

Returns

The size of the variable, counted in bytes.

Return type

int

get_var_type(name: str) → str

Get data type of the given variable.

Parameters

name (str) – An input or output variable name, a CSDMS Standard Name.

Returns

The Python variable type; e.g., str, int, float.

Return type

str

get_var_units(name: str) → str

Get units of the given variable.

Standard unit names, in lower case, should be used, such as meters or seconds. Standard abbreviations, like m for meters, are also supported. For variables with compound units, each unit name is separated by a single space, with exponents other than 1 placed immediately after the name, as in m s-1 for velocity, W m-2 for an energy flux, or km2 for an area.

Parameters

name (str) – An input or output variable name, a CSDMS Standard Name.

Returns

The variable units.

Return type

str

Notes

CSDMS uses the UDUNITS standard from Unidata.

initialize(config_file: str) → None

Perform startup tasks for the model.

Perform all tasks that take place before entering the model’s time loop, including opening files and initializing the model state. Model inputs are read from a text-based configuration file, specified by filename.

Parameters

config_file (str, optional) – The path to the model configuration file.

Notes

Models should be refactored, if necessary, to use a configuration file. CSDMS does not impose any constraint on how configuration files are formatted, although YAML is recommended. A template of a model’s configuration file with placeholder values is used by the BMI.

set_value(name: str, values: numpy.ndarray) → None

Specify a new value for a model variable.

This is the setter for the model, used to change the model’s current state. It accepts, through src, a new value for a model variable, with the type, size and rank of src dependent on the variable.

Parameters

• var_name (str) – An input or output variable name, a CSDMS Standard Name.

• src (array_like) – The new value for the specified variable.

set_value_at_indices(name: str, inds: numpy.ndarray, src: numpy.ndarray) → None

Specify a new value for a model variable at particular indices.

Parameters

• var_name (str) – An input or output variable name, a CSDMS Standard Name.

• indices (array_like) – The indices into the variable array.

• src (array_like) – The new value for the specified variable.

update() → None

Advance model state by one time step.

Perform all tasks that take place within one pass through the model’s time loop. This typically includes incrementing all of the model’s state variables. If the model’s state variables don’t change in time, then they can be computed by the initialize() method and this method can return with no action.

update_until(time: float) → None

Advance model state until the given time.

Parameters

time (float) – A model time later than the current model time.

Help

Depending on your need, CSDMS can provide advice or consulting services. Feel free to contact us through the CSDMS Help Desk.

Acknowledgments

This work is supported by the National Science Foundation under Award No. 1831623, Community Facility Support: The Community Surface Dynamics Modeling System (CSDMS).

Indices and tables

• Index

• Module Index

• Search Page