emsarray.conventions.ugrid

Unstructured grid convention.

See also

UGRID conventions

class UGrid(dataset)

A Convention subclass to handle unstructured grid datasets.

property topology

The Mesh2DTopology of this dataset - which faces connect with which edges.

Indexing

UGRID datasets have three grids: face, edge and node. UGridKind represents this. Each grid is indexed by a single integer. The convention native index type is UGridIndex.

class UGridKind(value)

UGRID datasets can store data on faces, edges, or nodes.

face = 'face'

edge = 'edge'

node = 'node'

UGridIndex

UGRID indices are always single integers, for all index kinds.

alias of Tuple[UGridKind, int]

Topology

class Mesh2DTopology(dataset, topology_key=None)

A helper for extracting the topology data for a 2D unstructured mesh dataset. The dataset will contain a dummy variable with the attribute cf_role = "mesh_topology". The attributes of that variable explain the topology of the dataset. For example, the names of the variables that store the coordinates for nodes can be found in the node_coordinates attribute as the string "x_variable y_variable".

There are five possible connectivity variables on a UGRID dataset: face-node, face-edge, face-face, edge-node, and edge-face. Face-node is the only required variable. Each has a property to check whether it is defined (has_valid_foo), a property to get the variable if it is defined (foo_connectivity), and a property to get or derive a normalised connectivity array (foo_array):

Attribute	has_valid_foo	foo_connectivity	foo_array
face_node	has_valid_face_node_connectivity	face_node_connectivity	face_node_array
face_edge	has_valid_face_edge_connectivity	face_edge_connectivity	face_edge_array
face_face	has_valid_face_face_connectivity	face_face_connectivity	face_face_array
edge_node	has_valid_edge_node_connectivity	edge_node_connectivity	edge_node_array
edge_face	has_valid_edge_face_connectivity	edge_face_connectivity	edge_face_array

dataset

The UGRID dataset

topology_key = None

The name of the mesh topology variable. Optional. If not provided, the mesh topology dummy variable will be found by checking the cf_role attribute.

sensible_dtype

The default dtype to use for index data arrays. Hard coded to int32, which should be sufficient for all datasets. int16 is too small for many datasets, even after slicing.

alias of int32

property mesh_variable

Get the dummy variable that stores the mesh topology information. This is variable is either named using the topology_key argument to the contructor, or found by looking for a variable with the attribute cf_role of "mesh_topology".

property mesh_attributes

Get the mesh topology attributes from the dummy variable with the attribute cf_role of "mesh_topology".

property sensible_fill_value

A sensible value to use for _FillValue. This is all-nines number larger than each of node_count, edge_count, and face_count.

An alternate, simpler implementation would use numpy.iinfo(dtype).max (the maximum integer value for a given dtype), but using all-nines is traditional.

property node_x

Data array of node X / longitude coordinates.

property node_y

Data array of node Y / latitude coordinates.

property edge_x

Data array of characteristic edge X / longitude coordinates. Optional.

property edge_y

Data array of characteristic edge y / latitude coordinates. Optional.

property face_x

Data array of characteristic face x / longitude coordinates. Optional.

property face_y

Data array of characteristic face y / latitude coordinates. Optional.

property has_valid_edge_node_connectivity

Does the dataset contain a valid edge_node_connectivity variable? Some datasets have an attribute naming a edge_node_connectivity variable, but the variable doesn’t exist. Other times, the shape of the variable is incorrect.

property edge_node_connectivity

This data array defines unique indexes for each edge. This allows data to be stored ‘on’ an edge.

If this variable is not defined, data are not stored on the edges for this dataset.

property edge_node_array

An integer numpy array with shape (edge_dimension, 2), indicating which nodes each edge consists of. If data are stored on edges in this dataset, the ordering of these edges matches the ordering of the data.

If this variable is not defined, we can derive it from the existing data, arbitrarily assigning an index to each edge. This will allow us to derive other connectivity variables if required.

property has_valid_edge_face_connectivity

Does the dataset contain a valid edge_face_connectivity variable? Some datasets have an attribute naming a edge_face_connectivity variable, but the variable doesn’t exist. Other times, the shape of the variable is incorrect.

property edge_face_connectivity

This data array shows which faces an edge borders on.

property edge_face_array

An integer numpy array with shape (edge_dimension, 2), indicating which faces border each edge.

property has_valid_face_node_connectivity

Does the dataset contain a valid face_node_connectivity variable? If this is invalid, the entire dataset is invalid.

property face_node_connectivity

A variable that lists the nodes that make up the boundary of each face. This is the only required data variable in a UGRID dataset, all the others can be derived from this if required.

property face_node_array

An integer numpy array with shape (face_dimension, max_node_dimension), representing the node indices that make up each face.

property has_valid_face_edge_connectivity

Does the dataset contain a valid face_edge_connectivity variable? Some datasets have an attribute naming a face_edge_connectivity variable, but the variable doesn’t exist. Other times, the shape of the variable is incorrect.

property face_edge_connectivity

The face_edge_connectivity variable from the dataset, if present.

property face_edge_array

An integer numpy array with shape (face_dimension, max_node_dimension), representing the edge indices that border each face.

property has_valid_face_face_connectivity

Does the dataset contain a valid face_face_connectivity variable? Some datasets have an attribute naming a face_face_connectivity variable, but the variable doesn’t exist. Other times, the shape of the variable is incorrect.

property face_face_connectivity

The face_face_connectivity variable from the dataset, if present.

property face_face_array

An integer numpy array with shape (face_dimension, max_node_dimension), representing the indices of all faces that border a given face.

property dimension_for_grid_kind

Get the dimension names for each of the grid types in this dataset.

property two_dimension

Get the name of the dimension with size two, for things like edge connectivity. The standard name for this dimension is ‘Two’.

property node_dimension

The name of the dimension for the number of nodes.

property has_edge_dimension

Check whether this dataset has an edge dimension. If not, data are not stored on edges in this dataset.

property edge_dimension

The name of the dimension for the number of edges.

property face_dimension

The name of the dimension for the number of faces.

property max_node_dimension

The name of the dimension for the maximum nodes / edges per face.

property node_count

The number of nodes in the dataset.

property edge_count

The number of edges in the dataset.

property face_count

The number of faces in the dataset.

property max_node_count

The maximum number of nodes / edges per face.

class NoEdgeDimensionException

Raised when the dataset does not define a name for the edge dimension, and no dimension name can be derived from the available connectivity variables.

class NoConnectivityVariableException

Raised when the dataset does not have a particular connectivity variable defined.

Masking

mask_from_face_indices(face_indices, topology)

Make a mask dataset from a list of face indices. This mask can later be applied using apply_clip_mask().

A mask for a UGRID dataset indicates which nodes, edges, and faces (collectively ‘elements’) to include, and their new indices. When elements are dropped from the dataset, to keep the remaining data contiguous, all elements gain new indices.

The mask consists of three data arrays corresponding to nodes, edges, and faces. Each data array indicates the new index for that element, or whether that element should be dropped.

buffer_faces(face_indices, topology)

When clipping a dataset to a region, including a buffer of extra faces around the included faces is desired. Given an array of face indices, buffer_faces() will find all the faces required to form this buffer and return a new array of face indices that include both the input faces and the buffer faces

Specifically, this finds all faces that share a node with one of the included faces.