Model grid functions

The functions in this section describe model grids. In the BMI, every exchange item is defined on a grid, and is referenced by a grid identifier returned from the get_var_grid function. This identifier is a required input to the functions listed below.

A model can have multiple grids. For example, consider modeling the diffusion of temperature over a flat plate. One grid could be a uniform rectilinear grid on which temperature is defined. A second grid could be a scalar, on which a constant thermal diffusivity is defined.

Not all grid functions are used by each type of grid. However, all BMI grid functions must be implemented. (See Model grids and BMI best practices.)

get_grid_type

int get_grid_type(in int grid, out string type);

def get_grid_type(self, grid: int) -> str:

int get_grid_type(void *self, int grid, char *type);

Given a grid identifier, get the type of that grid as a string. Valid grid types are:

  • scalar

  • points

  • vector

  • unstructured

  • structured_quadrilateral

  • rectilinear

  • uniform_rectilinear

A detailed description of the grid types supported in BMI is given in the Model grids section.

Implementation notes

  • In C++, Java, and Python, the type argument is omitted and the grid type name is returned from the function as a string.

  • In C and Fortran, an integer status code indicating success (zero) or failure (nonzero) is returned.

get_grid_rank

int get_grid_rank(in int grid, out int rank);

def get_grid_rank(self, grid: int) -> int:

int get_grid_rank(void *self, int grid, int *rank);

Given a grid identifier, get the rank (the number of dimensions) of that grid as an integer.

A grid’s rank determines the length of the return value of many of the following grid functions. For instance, get_grid_shape returns an array of length rank. Similarly, a grid’s rank determines which of get_grid_x, get_grid_y, etc. are implemented.

Implementation notes

  • This function is needed for every grid type.

  • In C++, Java, and Python, the rank argument is omitted and the grid rank is returned from the function.

  • In C and Fortran, an integer status code indicating success (zero) or failure (nonzero) is returned.

get_grid_size

int get_grid_size(in int grid, out int size);

def get_grid_size(self, grid: int) -> int:

int get_grid_size(void *self, int grid, int *size);

Given a grid identifier, get the total number of elements (or nodes) of that grid as an integer.

The grid size is used for, among other things, the length of arrays returned by get_grid_x and get_grid_y for unstructured and structured quad grids.

Implementation notes

  • This function is needed for every grid type.

  • In C++, Java, and Python, the size argument is omitted and the grid size is returned from the function.

  • In C and Fortran, an integer status code indicating success (zero) or failure (nonzero) is returned.

get_grid_shape

int get_grid_shape(in int grid, in array<int, 1> shape);

def get_grid_shape(self, grid: int, shape: NDArray[np.int_]) -> NDArray[np.int_]:

int get_grid_shape(void *self, int grid, int *shape);

Get the dimensions of the model grid.

Note that this function (as well as the other grid functions) returns information ordered with “ij” indexing (as opposed to “xy”). For example, consider a two-dimensional rectilinear grid with four columns (nx = 4) and three rows (ny = 3). The get_grid_shape function would return a shape of [ny, nx], or [3,4]. If there were a third dimension, the length of the z-dimension, nz, would be listed first.

Also note that the grid shape is the number of nodes in the coordinate directions and not the number of cells or elements. It is possible for grid values to be associated with the nodes or with the cells.

Implementation notes

  • This function is used for describing all structured grids.

  • In Python, the shape argument is a numpy array.

  • In C++ and Java, this is a void function.

  • In C and Fortran, an integer status code indicating success (zero) or failure (nonzero) is returned.

get_grid_spacing

int get_grid_spacing(in int grid, in array<double, 1> spacing);

def get_grid_spacing(
    self, grid: int, spacing: NDArray[np.float64]
) -> NDArray[np.float64]:

int get_grid_spacing(void *self, int grid, double *spacing);

Get the distance between the nodes of the model grid.

The get_grid_spacing function provides the width of each cell in the number of dimensions as returned by get_grid_rank. As with get_grid_shape, the spacing is given in “ij” indexing* order; e.g., for a two-dimensional grid, the spacing between rows is followed by spacing between columns, [dy, dx].

Implementation notes

  • This function is used for describing uniform rectilinear grids.

  • In Python, the spacing argument is a numpy array.

  • In C++ and Java, this is a void function.

  • In C and Fortran, an integer status code indicating success (zero) or failure (nonzero) is returned.

get_grid_origin

int get_grid_origin(in int grid, in array<double, 1> origin);

def get_grid_origin(
    self, grid: int, origin: NDArray[np.float64]
) -> NDArray[np.float64]:

int get_grid_origin(void *self, int grid, double *origin);

Get the coordinates of the lower-left corner of the model grid.

The origin parameter is a one-dimensional array of the size returned by get_grid_rank. As with get_grid_shape, the origin is given in “ij” indexing* order; e.g., for a two-dimensional grid, the origin is given in the column dimension, followed by the row dimension, [y0, x0].

Implementation notes

  • This function is used for describing uniform rectilinear grids.

  • In Python, the origin argument is a numpy array.

  • In C++ and Java, this is a void function.

  • In C and Fortran, an integer status code indicating success (zero) or failure (nonzero) is returned.

get_grid_x

int get_grid_x(in int grid, in array<double, 1> x);

def get_grid_x(self, grid: int, x: NDArray[np.float64]) -> NDArray[np.float64]:

int get_grid_x(void *self, int grid, double *x);

Get the locations of the grid nodes in the first coordinate direction.

The length of the resulting one-dimensional array depends on the grid type. (It will use a value from either get_grid_shape or get_grid_size.) See Model grids for more information.

Implementation notes

  • This function is used for describing rectilinear, structured quadrilateral, and all unstructured grids.

  • In Python, the x argument is a numpy array.

  • In C++ and Java, this is a void function.

  • In C and Fortran, an integer status code indicating success (zero) or failure (nonzero) is returned.

get_grid_y

int get_grid_y(in int grid, in array<double, 1> y);

def get_grid_y(self, grid: int, y: NDArray[np.float64]) -> NDArray[np.float64]:

int get_grid_y(void *self, int grid, double *y);

Get the locations of the grid nodes in the second coordinate direction.

The length of the resulting one-dimensional array depends on the grid type. (It will use a value from either get_grid_shape or get_grid_size.) See Model grids for more information.

Implementation notes

  • This function is used for describing rectilinear, structured quadrilateral, and all unstructured grids.

  • In Python, the y argument is a numpy array.

  • In C++ and Java, this is a void function.

  • In C and Fortran, an integer status code indicating success (zero) or failure (nonzero) is returned.

get_grid_z

int get_grid_z(in int grid, in array<double, 1> z);

def get_grid_z(self, grid: int, z: NDArray[np.float64]) -> NDArray[np.float64]:

int get_grid_z(void *self, int grid, double *z);

Get the locations of the grid nodes in the third coordinate direction.

The length of the resulting one-dimensional array depends on the grid type. (It will use a value from either get_grid_shape or get_grid_size.) See Model grids for more information.

Implementation notes

  • This function is used for describing rectilinear, structured quadrilateral, and all unstructured grids.

  • In Python, the z argument is a numpy array.

  • In C++ and Java, this is a void function.

  • In C and Fortran, an integer status code indicating success (zero) or failure (nonzero) is returned.

get_grid_node_count

int get_grid_node_count(in int grid, out int count);

def get_grid_node_count(self, grid: int) -> int:

int get_grid_node_count(void *self, int grid, int *count);

Get the number of nodes in the grid.

Implementation notes

  • This function is used for describing unstructured grids.

  • In C++, Java, and Python, the count argument is omitted and the node count is returned from the function.

  • In C and Fortran, an integer status code indicating success (zero) or failure (nonzero) is returned.

get_grid_edge_count

int get_grid_edge_count(in int grid, out int count);

def get_grid_edge_count(self, grid: int) -> int:

int get_grid_edge_count(void *self, int grid, int *count);

Get the number of edges in the grid.

Implementation notes

  • This function is used for describing unstructured grids.

  • In C++, Java, and Python, the count argument is omitted and the edge count is returned from the function.

  • In C and Fortran, an integer status code indicating success (zero) or failure (nonzero) is returned.

get_grid_face_count

int get_grid_face_count(in int grid, out int count);

def get_grid_face_count(self, grid: int) -> int:

int get_grid_face_count(void *self, int grid, int *count);

Get the number of faces in the grid.

Implementation notes

  • This function is used for describing unstructured grids.

  • In C++, Java, and Python, the count argument is omitted and the face count is returned from the function.

  • In C and Fortran, an integer status code indicating success (zero) or failure (nonzero) is returned.

get_grid_edge_nodes

int get_grid_edge_nodes(in int grid, in array<int, 1> edge_nodes);

def get_grid_edge_nodes(
    self, grid: int, edge_nodes: NDArray[np.int_]
) -> NDArray[np.int_]:

int get_grid_edge_nodes(void *self, int grid, int *edge_nodes);

Get the edge-node connectivity.

For each edge, connectivity is given as node at edge tail, followed by node at edge head. The total length of the array is 2 * get_grid_edge_count.

Implementation notes

  • This function is used for describing unstructured grids.

  • In Python, the edge_nodes argument is a numpy array.

  • In C++ and Java, this is a void function.

  • In C and Fortran, an integer status code indicating success (zero) or failure (nonzero) is returned.

get_grid_face_edges

int get_grid_face_edges(in int grid, in array<int, 1> face_edges);

def get_grid_face_edges(
    self, grid: int, face_edges: NDArray[np.int_]
) -> NDArray[np.int_]:

int get_grid_face_edges(void *self, int grid, int *face_edges);

Get the face-edge connectivity.

The length of the array returned is the sum of the values of get_grid_nodes_per_face.

Implementation notes

  • This function is used for describing unstructured grids.

  • In Python, the face_edges argument is a numpy array.

  • In C++ and Java, this is a void function.

  • In C and Fortran, an integer status code indicating success (zero) or failure (nonzero) is returned.

get_grid_face_nodes

int get_grid_face_nodes(in int grid, in array<int, 1> face_nodes);

def get_grid_face_nodes(
    self, grid: int, face_nodes: NDArray[np.int_]
) -> NDArray[np.int_]:

int get_grid_face_nodes(void *self, int grid, int *face_nodes);

Get the face-node connectivity.

For each face, the nodes (listed in a counter-clockwise direction) that form the boundary of the face. For a grid of quadrilaterals, the total length of the array is 4 * get_grid_face_count. More generally, the length of the array is the sum of the values of get_grid_nodes_per_face.

Implementation notes

  • This function is used for describing unstructured grids.

  • In Python, the face_nodes argument is a numpy array.

  • In C++ and Java, this is a void function.

  • In C and Fortran, an integer status code indicating success (zero) or failure (nonzero) is returned.

get_grid_nodes_per_face

int get_grid_nodes_per_face(in int grid, in array<int, 1> nodes_per_face);

def get_grid_nodes_per_face(
    self, grid: int, nodes_per_face: NDArray[np.int_]
) -> NDArray[np.int_]:

int get_grid_nodes_per_face(void *self, int grid, int *nodes_per_face);

Get the number of nodes for each face.

The returned array has a length of get_grid_face_count. The number of edges per face is equal to the number of nodes per face.

Implementation notes

  • This function is used for describing unstructured grids.

  • In Python, the nodes_per_face argument is a numpy array.

  • In C++ and Java, this is a void function.

  • In C and Fortran, an integer status code indicating success (zero) or failure (nonzero) is returned.