Model grids

The Basic Model Interface (BMI) supports several different grid types, described below. Depending on the grid type (as returned from the get_grid_type function), a model will implement a different set of grid functions.

Structured grids

For the BMI specification, a structured grid is formed in two dimensions by tiling a domain with quadrilateral cells so that every interior vertex is surrounded by four quadrilaterals. In three dimensions, six-sided polyhedral cells are stacked such that interior vertices are surrounded by eight cells.

In the BMI, dimensional information is ordered with “ij” indexing (as opposed to “xy”). For example, for the uniform rectilinear grid shown below, the get_grid_shape function would return the array [4, 5]. If there was a third dimension, its length would be listed first.


The grid shape is the number of nodes in the coordinate directions, 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


A uniform rectilinear grid is a special case of structured quadrilateral grid where the elements have equal width in each dimension. That is, for a two-dimensional 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 a raster or Catesian grid.

To completely specify a uniform rectilinear grid, only three pieces of information are needed: the number of elements in each dimension, the width of each element (in each dimension), and the location of the corner of the grid.

Uniform rectilinear grids use the following BMI functions:



In a rectilinear grid, the spacing between nodes in each dimension varies, as depicted above. Therefore, an array of coordinates for each row and column (for the two-dimensional case) is required.

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

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

Rectilinear grids use the following BMI functions:

Structured quadrilateral


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

The get_grid_y function returns an array (whose length is the number of total nodes returned by get_grid_size) of y-coordinates.

The get_grid_x function returns an array (whose length is the number of total nodes returned by get_grid_size) of x-coordinates.

Structured quadrilateral grids use the following BMI functions:

Unstructured grids

This category includes the unstructured type, as well as the special cases scalar, points, and vector. This is the most general grid type. It can be used for any type of grid. This grid type must be used if the grid consists of cells that are not quadrilaterals; this includes any grid of triangles (e.g. Delaunay triangles and Voronoi tesselations).


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

BMI uses the ugrid conventions to define unstructured grids.

Unstructured grids use the following BMI functions: