Model Grids

Different models often use different computational grids. An application that calls a BMI needs a complete and standardized description of a model’s grid in order to automatically accommodate differences between model grids (via regridding) when coupled models share data. Currently, BMI supports four different grid types. Depending on the grid type, the model will implement a different set of grid functions. By calling a model’s Variables grids function, an application is able to determine which methods will be implemented for a particular grid.

Grid Type

string get_grid_type(in int id)

The type of grid as a string. Valid return values are:

  • uniform_rectilinear
  • rectilinear
  • structured_quadrilateral
  • unstructured

Grid rank

int get_grid_rank(in int id)

The number of dimension in the grid is its rank. A grid’s rank determines the length of many of the following grid functions. For instance, Grid shape will return an array that is of length rank. In a similar way, a grid’s rank determines which of get_grid_x, get_grid_y, etc. are implemented.

get_grid_rank returns the rank of a particular grid. 0 for scalar, 1 for 1D, etc.

Grid size

int get_grid_size(in int id)

get_grid_size returns the size of a grid as the number of elements. This is used for, among other things, to give the length of arrays returned by get_grid_x and get_grid_y for unstructured and structured quad grids.

Structured grids of quadrilaterals

Grid shape

array<int> get_grid_shape(in int id)

A structured grid of quadrilaterals is one formed by a stacked next one-another such that every vertex is surrounded by four quadrilaterals. A special case of such a grid is Uniform rectilinear where rectangles are stacked next to one another row-by-row.

For all quadrilateral grids, the get_grid_shape function is necessary to provide the number of rows and columns (for a 2D grid). Note that this function (as well as the other grid functions) returns information about each dimension ordered with “ij” indexing (as opposed to “xy”). For example, the get_grid_shape function for the uniform rectilinear grid shown below would return the array [4, 5]. If there were a third dimension, the length of the z-dimension would be listed first.

Note

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.

Uniform rectilinear

array<float> get_grid_origin(in int id)
array<int> get_grid_spacing(in int id)
_images/mesh_uniform_rectilinear.png

A uniform rectilinear (or Cartesian grid) is a special case of a grid of quadrilaterals such that the elements have equal width in each dimension. That is, for a 2D grid, elements have a constant width of dx in the x-direction` and ``dy`` in the *y-direction`. The case of ``dx == dy`` is oftentimes called as *raster grid.

To completely define points of a uniform rectilinear grid, one needs only three pieces of information. Namely, the number of elements in each dimension (Grid shape), the width of each element (in each dimension) and the location of the corner of the grid.

get_grid_spacing provides the width of each element in the number of dimension as returned by Grid rank. The spacing is ij-indexing order. That is spacing in rows followed by spacing in columns.

get_grid_origin provides the location of the lower-left corner of the grid (also in ij-indexing order).

Rectilinear

int get_grid_rank(in int id)
array<int> get_grid_size(in int id)
array<int> get_grid_shape(in int id)
array<float> get_grid_x(in int id)
array<float> get_grid_y(in int id)
array<float> get_grid_z(in int id)
_images/mesh_rectilinear.png

A rectilinear grid is simply a uniform rectilinear grid whose spacing in a single dimension varies (as shown in the above image). In this case, an array of coordinates for each row and column (for 2D) is required.

get_grid_y provides an array (whose length is the number of rows) that gives the y-coordinate for each row.

get_grid_x provides an array (whose length is the number of columns) that gives the y-coordinate for each column.

Structured quadrilaterals

int get_grid_rank(in int id)
array<int> get_grid_size(in int id)
array<int> get_grid_shape(in int id)
array<float> get_grid_x(in int id)
array<float> get_grid_y(in int id)
array<float> get_grid_z(in int id)
_images/mesh_structured_quad.png

The most general structured quadrilateral grid is one whose rows (and columns) do not share a common coordinate. In this case, coordinates are required for each grid element. For this more general case, get_grid_x and get_grid_y are repurposed to provide this information.

get_grid_y returns an array (whose length is the number of total nodes) of x-coordinates.

get_grid_x returns an array (whose length is the number of total nodes) of y-coordinates.

Unstructured

int get_grid_rank(in int id)
array<int> get_grid_size(in int id)
array<float> get_grid_x(in int id)
array<float> get_grid_y(in int id)
array<float> get_grid_z(in int id)
array<int> get_grid_connectivity(in int id)
array<int> get_grid_offset(in int id)

This is the most general grid type and can be used for any type of grid. However, most grids that consist of 4-sided polygons can be represented using one of the other grid types. This grid type must be used if the grid consists of any elements or cells that do not have four sides. This includes any grid of triangles (e.g. Delaunay triangles and a Voronoi tesselation.

Note that a grid of equilateral triangles, while is most certainly structured, would need to be represented as an unstructured grid. The same is true for a grid of hexagons.