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/latest/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
orseconds
. Standard abbreviations, likem
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 inm s-1
for velocity,W m-2
for an energy flux, orkm2
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/latest/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
orseconds
. Standard abbreviations, likem
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 inm s-1
for velocity,W m-2
for an energy flux, orkm2
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.