API and implementation notes¶
The Basic Model Interface API defines a set of methods and attributes. These methods are implemented as detailed in the BMI specification
- class BMI_pyDeltaRCM.bmidelta.BmiDelta¶
Basic Model Interface implementation for pyDeltaRCM.
- __init__()¶
Create a BmiDelta model that is ready for initialization.
- finalize()¶
Finalize model.
- get_component_name()¶
Name of the component.
- get_current_time()¶
Current time of model.
- get_end_time()¶
End time of model.
- get_grid_edge_count(grid: int) int¶
Get the number of edges in the grid.
Warning
Not implemented.
Could be computed from the rectilinear type?
- 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.
Warning
Not implemented.
Could be computed from the rectilinear type?
- 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.
Note
Implemented as an alias to
get_grid_size.- 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_id)¶
Origin of uniform rectilinear grid.
- get_grid_rank(grid_id)¶
Rank of grid.
- Parameters
grid_id (int) – Identifier of a grid.
- Returns
Rank of grid.
- Return type
int
- get_grid_shape(grid_id)¶
Number of rows and columns of uniform rectilinear grid.
- get_grid_size(grid_id)¶
Size of grid.
- Parameters
grid_id (int) – Identifier of a grid.
- Returns
Size of grid.
- Return type
int
- get_grid_spacing(grid_id)¶
Spacing of rows and columns of uniform rectilinear grid.
- get_grid_type(grid_id)¶
Type of grid.
- get_grid_x(grid: int) numpy.ndarray¶
Get coordinates of grid nodes in the x direction.
Hint
Internally, the pyDeltaRCM model refers to the down-stream direction as x, which is the row-coordinate of the grid, and opposite the BMI specification.
- 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) numpy.ndarray¶
Get coordinates of grid nodes in the y direction.
Hint
Internally, the pyDeltaRCM model refers to the cross-stream direction as y, which is the column-coordinate of the grid, and opposite the BMI specification.
- Parameters
grid (int) – A grid identifier.
- Returns
The input numpy array that holds the grid’s row y-coordinates.
- Return type
ndarray of float
- get_grid_z(grid: int) 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()¶
Get names of input variables.
- 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()¶
Get names of output variables.
- get_start_time()¶
Start time of model.
- get_time_step()¶
Time step of model.
- get_time_units() str¶
Time units of the model.
Note
CSDMS uses the UDUNITS standard from Unidata.
- Returns
The model time unit; e.g., days or s.
- Return type
str
- get_value(var_name)¶
Copy of values.
- Parameters
var_name (str) – Name of variable as CSDMS Standard Name.
- Returns
Copy of values.
- Return type
array_like
- get_value_at_indices(var_name, indices)¶
Get values at particular indices.
- Parameters
var_name (str) – Name of variable as CSDMS Standard Name.
indices (array_like) – Array of indices.
- Returns
Values at indices.
- Return type
array_like
- get_value_ptr(var_name)¶
Reference to values.
Note
In implementation, we use self._values of the BMI wrapper as a dictionary storing the DeltaModel attribute name, rather than the actual pointer directly to the attribute. This is necessary so that numeric scalar attributes of the DeltaModel (i.e., boundary conditions) can be modified by the BMI set_value method.
Stille, the result of what is returned by this method is identical to the standard BMI.
- Parameters
var_name (str) – Name of variable as CSDMS Standard Name.
- Returns
Value array.
- Return type
array_like
- get_value_ref(var_name)¶
Reference to values, legacy BMI 1.0 api.
- Parameters
var_name (str) – Name of variable as CSDMS Standard Name.
- Returns
Value array.
- Return type
array_like
- get_var_grid(var_name)¶
Grid id for a variable.
- Parameters
var_name (str) – Name of variable as CSDMS Standard Name.
- Returns
Grid id.
- Return type
int
- get_var_itemsize(name: str) int¶
Get the size (in bytes) of one element of a variable.
- 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.
Note
CSDMS uses the ugrid conventions to define unstructured grids.
- 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
- get_var_nbytes(var_name)¶
Get units of variable.
- Parameters
var_name (str) – Name of variable as CSDMS Standard Name.
- Returns
Size of data array in bytes.
- Return type
int
- get_var_type(var_name)¶
Data type of variable.
- Parameters
var_name (str) – Name of variable as CSDMS Standard Name.
- Returns
Data type.
- Return type
str
- get_var_units(var_name)¶
Get units of variable.
- Parameters
var_name (str) – Name of variable as CSDMS Standard Name.
- Returns
Variable units.
- Return type
str
- initialize(filename=None)¶
Initialize the model.
- Parameters
filename (str, optional) – Path to name of input file. Use all pyDeltaRCM defaults, if not provided.
- set_value(var_name, src)¶
Set model values.
Note
In implementation, we use self._values of the BMI wrapper as a dictionary storing the DeltaModel attribute name, rather than the actual pointer directly to the attribute. This is necessary so that numeric scalar attributes of the DeltaModel (i.e., boundary conditions) can be modified by the BMI set_value method.
- Parameters
var_name (str) – Name of variable as CSDMS Standard Name.
src (array_like) – Array of new values.
- set_value_at_indices(var_name, src, indices)¶
Set model values at particular indices.
- Parameters
var_name (str) – Name of variable as CSDMS Standard Name.
src (array_like) – Array of new values.
indices (array_like) – Array of indices.
- update()¶
Advance model by one time step.
- update_frac(time_frac)¶
Update model by a fraction of a time step.
- Parameters
time_frac (float) – Fraction of a time step.
- update_until(then)¶
Update model until a particular time.
- Parameters
then (float) – Time to run model until.