Indexing

Each format defines some number of grids. Each location in that grid - whether it is a face, edge, or node - can be uniquely indexed.

Format native indexing

As each format may define a different number of grids, each format has a different method of indexing data in these grids. These are the format native indexes. Each Format implementation has its own Index type.

CF grid datasets have only one grid - faces. Each face can be indexed using two numbers x and y. Indexes for CF grids are two-tuples of (y, x)

SHOC datasets have four grids - faces, left edges, back edges, and nodes. Each of these grids can be indexed using two numbers i and j. Indexes for SHOC datasets are three-tuples of (kind, j, i).

UGRID datasets have three grids - faces, edges, and nodes. Each of these grids can be indexed using a single number. Indexes for UGRID datasets are two-tuples of (kind, index).

Linear indexing

Each grid can be flattened into a one dimensional array. Indexes in to this flattened array are called linear indexes. Linear indexes are used in many places. There are methods to convert between a linear index and a native index.

Using indexes

A format native index can be transformed in to a linear index by calling Format.ravel_index(native_index). A linear index can be transformed in to a native index by calling Format.unravel_index(linear_index, kind).

To find the correct native index kind for a data variable, call Format.get_grid_kind_and_size(). This will return a tuple of (kind, size). kind is the native index kind (face, edge, node, etc), while size is the length of the linear index space for that grid.

Looking up a location in the Format.spatial_index will return a SpatialIndexItem instance. These values have a linear_index attribute and a index attribute.

The cell polygons in Format.polygons are in linear index order. If you have the linear index for a cell, you can find its polygon by indexing directly in to this array.

Format.make_linear() will the surface dimensions of a data variable in to a linear one dimensional array. The order of this flattened array matches the linear index order. If you have the linear index for a cell, you can find its value by indexing directly in to this array.