emsarray.formats.ugrid

Unstructured grid format.

See also

UGRID conventions

class emsarray.formats.ugrid.UGrid(dataset)

A Format subclass to handle unstructured grid datasets.

UGRID datasets must be opened with mask_and_scale=False, as xarray does not handle masked integer variables well. UGrid.open_dataset() or emsarray.open_dataset() can be useful here.

classmethod open_dataset(path, **kwargs)

Open the dataset at path, setting mask_and_scale=False.

Example

from emsarray.formats.ugrid import UGrid
dataset = UGrid.open_dataset("./tests/datasets/ugrid_mesh2d.nc")

See also

emsarray.open_dataset()

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 format native index type is UGridIndex.

class emsarray.formats.ugrid.UGridKind(value)

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

face = 'face'

edge = 'edge'

node = 'node'

emsarray.formats.ugrid.UGridIndex

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

alias of Tuple[emsarray.formats.ugrid.UGridKind, int]

Topology

class emsarray.formats.ugrid.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”.

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

alias of numpy.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

Find a sensible value to use for _FillValue. This finds an all-nines number larger than each of node_count, edge_count, and face_count.

An alternate, simpler implementation would use np.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 dataset is _not_ defined, data are not stored on the edges for this dataset. We can derive it from the existing data, arbitrarily assigning an index to each edge. This will allow us to derive other datasets 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 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 dataset 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 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 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 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 edge_dimension

The name of the dimension for the number of edges.

Returns None if there is no such dimension. This implies that data are not stored on edges in this dataset.

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 emsarray.formats.ugrid.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.

Masking

emsarray.formats.ugrid.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.

emsarray.formats.ugrid.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.