iris.experimental.ugrid

Infra-structure for unstructured mesh support.

Based on CF UGRID Conventions (v1.0), https://ugrid-conventions.github.io/ugrid-conventions/.

Note

For the docstring of PARSE_UGRID_ON_LOAD: see the original definition at iris.experimental.ugrid.load.PARSE_UGRID_ON_LOAD.

class iris.experimental.ugrid.Connectivity(indices, cf_role, standard_name=None, long_name=None, var_name=None, units=None, attributes=None, start_index=0, location_axis=0)

Bases: _DimensionalMetadata

CF-UGRID topology.

A CF-UGRID topology connectivity, describing the topological relationship between two types of mesh element. One or more connectivities make up a CF-UGRID topology - a constituent of a CF-UGRID mesh.

See: https://ugrid-conventions.github.io/ugrid-conventions

Construct a single connectivity.

Parameters:

• indices (numpy.ndarray or numpy.ma.core.MaskedArray or dask.array.Array) – 2D array giving the topological connection relationship between location elements and connected elements. The location_axis dimension indexes over the location dimension of the mesh - i.e. its length matches the total number of location elements in the mesh. The connected_axis dimension can be any length, corresponding to the highest number of connected elements connected to a location element. The array values are indices into the connected dimension of the mesh. If the number of connected elements varies between location elements: use a numpy.ma.core.MaskedArray and mask the location elements’ unused index ‘slots’. Use a dask.array.Array to keep indices ‘lazy’.

• cf_role (str) – Denotes the topological relationship that this connectivity describes. Made up of this array’s location, and the connected element type that is indexed by the array. See UGRID_CF_ROLES for valid arguments.

• standard_name (str, optional) – CF standard name of the connectivity. (NOTE: this is not expected by the UGRID conventions, but will be handled in Iris’ standard way if provided).

• long_name (str, optional) – Descriptive name of the connectivity.

• var_name (str, optional) – The NetCDF variable name for the connectivity.

• units (cf_units.Unit, optional) – The Unit of the connectivity’s values. Can be a string, which will be converted to a Unit object. (NOTE: this is not expected by the UGRID conventions, but will be handled in Iris’ standard way if provided).

• attributes (dict, optional) – A dictionary containing other cf and user-defined attributes.

• start_index (int, optional) – Either 0 or 1. Default is 0. Denotes whether indices uses 0-based or 1-based indexing (allows support for Fortran and legacy NetCDF files).

• location_axis (int, optional) – Either 0 or 1. Default is 0. Denotes which axis of indices varies over the location elements (the alternate axis therefore varying over connected elements). (This parameter allows support for fastest varying index being either first or last). E.g. for face_node_connectivity, for 10 faces: indices.shape[location_axis] == 10.

UGRID_CF_ROLES = ['edge_node_connectivity', 'face_node_connectivity', 'face_edge_connectivity', 'face_face_connectivity', 'edge_face_connectivity', 'boundary_node_connectivity', 'volume_node_connectivity', 'volume_edge_connectivity', 'volume_face_connectivity', 'volume_volume_connectivity']

property cf_role

The category of topological relationship that this connectivity describes.

Read-only - validity of indices is dependent on cf_role. A new Connectivity must therefore be defined if a different cf_role is needed.

property connected

Derived from the connectivity’s cf_role.

Derived from the connectivity’s cf_role - the second part, e.g. node in face_node_connectivity. Refers to the elements indexed by the values in the connectivity’s indices array.

property connected_axis

Derived as the alternate value of location_axis.

Derived as the alternate value of location_axis - each must equal either 0 or 1. The axis of the connectivity’s indices array that varies over the connected elements associated with each location element.

core_indices()

Return the indices array at the core of this connectivity.

The indices array at the core of this connectivity, which may be a NumPy array or a Dask array.

Return type:

numpy.ndarray or numpy.ma.core.MaskedArray or dask.array.Array

cube_dims(cube)

Not available on Connectivity.

has_lazy_indices()

Check if the connectivity’s indices array is a lazy Dask array or not.

Return type:

bool

property indices

The index values describing the topological relationship of the connectivity.

The index values describing the topological relationship of the connectivity, as a NumPy array. Masked points indicate a location element with fewer connected elements than other location elements described in this array - unused index ‘slots’ are masked.

Read-only - index values are only meaningful when combined with an appropriate cf_role, start_index and location_axis. A new Connectivity must therefore be defined if different indices are needed.

indices_by_location(indices=None)

Return a view of the indices array.

Return a view of the indices array with location_axis always as the first axis - transposed if necessary. Can optionally pass in an identically shaped array on which to perform this operation (e.g. the output from core_indices() or lazy_indices()).

Parameters:

indices (array) – The array on which to operate. If None, will operate on indices. Default is None.

Returns:

A view of the indices array Transposed - if necessary - to put location_axis first.

Return type:

result

lazy_indices()

Return a lazy array representing the connectivity’s indices.

Accessing this method will never cause the indices values to be loaded. Similarly, calling methods on, or indexing, the returned Array will not cause the connectivity to have loaded indices.

If the indices have already been loaded for the connectivity, the returned Array will be a new lazy array wrapper.

Return type:

A lazy array, representing the connectivity indices array.

lazy_location_lengths()

Return a lazy array representing the number of connected elements.

Return a lazy array representing the number of connected elements associated with each of the connectivity’s location elements, accounting for masks if present.

Accessing this method will never cause the indices values to be loaded. Similarly, calling methods on, or indexing, the returned Array will not cause the connectivity to have loaded indices.

The returned Array will be lazy regardless of whether the indices have already been loaded.

Returns:

A lazy array, representing the number of connected elements associated with each location element.

Return type:

lazy array

property location

Derived from the connectivity’s cf_role.

Derived from the connectivity’s cf_role - the first part, e.g. face in face_node_connectivity. Refers to the elements that vary along the location_axis of the connectivity’s indices array.

property location_axis

The axis of the connectivity’s indices array.

The axis of the connectivity’s indices array that varies over the connectivity’s location elements. Either 0 or 1. Read-only - validity of indices is dependent on location_axis. Use transpose() to create a new, transposed Connectivity if a different location_axis is needed.

location_lengths()

Return a NumPy array representing the number of connected elements.

Return a NumPy array representing the number of connected elements associated with each of the connectivity’s location elements, accounting for masks if present.

Returns:

A NumPy array, representing the number of connected elements associated with each location element.

Return type:

NumPy array

property start_index

The base value of the connectivity’s indices array; either 0 or 1.

Read-only - validity of indices is dependent on start_index. A new Connectivity must therefore be defined if a different start_index is needed.

transpose()

Transpose Connectivity.

Create a new Connectivity, identical to this one but with the indices array transposed and the location_axis value flipped.

Returns:

A new Connectivity that is the transposed equivalent of the original.

Return type:

Connectivity

validate_indices()

Perform a thorough validity check of this connectivity’s indices.

Perform a thorough validity check of this connectivity’s indices. Includes checking the number of connected elements associated with each location element (specified using masks on the indices array) against the cf_role.

Raises a ValueError if any problems are encountered, otherwise passes silently.

Note

While this uses lazy computation, it will still be a high resource demand for a large indices array.

xml_element(doc)

Create XML element.

Create the xml.dom.minidom.Element that describes this _DimensionalMetadata.

Parameters:

doc – The parent xml.dom.minidom.Document.

Returns:

xml.dom.minidom.Element that will describe this _DimensionalMetadata.

Return type:

xml.dom.minidom.Element

class iris.experimental.ugrid.Mesh(topology_dimension, node_coords_and_axes, connectivities, edge_coords_and_axes=None, face_coords_and_axes=None, standard_name=None, long_name=None, var_name=None, units=None, attributes=None, node_dimension=None, edge_dimension=None, face_dimension=None)

Bases: CFVariableMixin

A container representing the UGRID cf_role mesh_topology.

A container representing the UGRID cf_role mesh_topology, supporting 1D network, 2D triangular, and 2D flexible mesh topologies.

Note

The 3D layered and fully 3D unstructured mesh topologies are not supported at this time.

See also

The UGRID Conventions, https://ugrid-conventions.github.io/ugrid-conventions/

Mesh initialise.

Note

The purpose of the node_dimension, edge_dimension and face_dimension properties are to preserve the original NetCDF variable dimension names. Note that, only edge_dimension and face_dimension are UGRID attributes, and are only present for topology_dimension >=2.

AXES = ('x', 'y')

The supported mesh axes.

ELEMENTS = ('edge', 'node', 'face')

Valid mesh elements.

TOPOLOGY_DIMENSIONS = (1, 2)

Valid range of values for topology_dimension.

add_connectivities(*connectivities)

Add one or more Connectivity instances to the Mesh.

Parameters:

*connectivities (iterable of object) – A collection of one or more Connectivity instances to add to the Mesh.

add_coords(node_x=None, node_y=None, edge_x=None, edge_y=None, face_x=None, face_y=None)

Add one or more AuxCoord coordinates to the Mesh.

Parameters:

• (object) (face_y) – The x-axis like node AuxCoord.

• (object) – The y-axis like node AuxCoord.

• (object) – The x-axis like edge AuxCoord.

• (object) – The y-axis like edge AuxCoord.

• (object) – The x-axis like face AuxCoord.

• (object) – The y-axis like face AuxCoord.

property all_connectivities

All the Connectivity instances of the Mesh.

property all_coords

All the AuxCoord coordinates of the Mesh.

property boundary_node_connectivity

The optional UGRID boundary_node_connectivity Connectivity.

The optional UGRID boundary_node_connectivity Connectivity of the Mesh.

property cf_role

The UGRID cf_role attribute of the Mesh.

connectivities(item=None, standard_name=None, long_name=None, var_name=None, attributes=None, cf_role=None, contains_node=None, contains_edge=None, contains_face=None)

Return all Connectivity.

Return all Connectivity instances from the Mesh that match the provided criteria.

Criteria can be either specific properties or other objects with metadata to be matched.

See also

Mesh.connectivity() for matching exactly one connectivity.

Parameters:

• item (str or object) –

  Either,

  • a standard_name, long_name, or var_name which is compared against the name().

  • a connectivity or metadata instance equal to that of the desired objects e.g., Connectivity or ConnectivityMetadata.

• standard_name (str, optional, default=None) – The CF standard name of the desired Connectivity. If None, does not check for standard_name.

• long_name (str, optional, default=None) – An unconstrained description of the Connectivity. If None, does not check for long_name.

• var_name (str, optional, default=None) – The NetCDF variable name of the desired Connectivity. If None, does not check for var_name.

• attributes (dict, optional, default=None) – A dictionary of attributes desired on the Connectivity. If None, does not check for attributes.

• cf_role (str, optional, default=None) – The UGRID cf_role of the desired Connectivity.

• contains_node (bool, optional) – Contains the node element as part of the cf_role in the list of objects to be matched.

• contains_edge (bool, optional) – Contains the edge element as part of the cf_role in the list of objects to be matched.

• contains_face (bool, optional) – Contains the face element as part of the cf_role in the list of objects to be matched.

Returns:

A list of Connectivity instances from the Mesh that matched the given criteria.

Return type:

list of Connectivity

connectivity(item=None, standard_name=None, long_name=None, var_name=None, attributes=None, cf_role=None, contains_node=None, contains_edge=None, contains_face=None)

Return a single Connectivity.

Return a single Connectivity from the Mesh that matches the provided criteria.

Criteria can be either specific properties or other objects with metadata to be matched.

Note

If the given criteria do not return precisely one Connectivity, then a ConnectivityNotFoundError is raised.

See also

Mesh.connectivities() for matching zero or more connectivities.

Parameters:

• item (str or object) –

  Either,

  • a standard_name, long_name, or var_name which is compared against the name().

  • a connectivity or metadata instance equal to that of the desired object e.g., Connectivity or ConnectivityMetadata.

• standard_name (str, optional, default=None) – The CF standard name of the desired Connectivity. If None, does not check for standard_name.

• long_name (str, optional, default=None) – An unconstrained description of the Connectivity. If None, does not check for long_name.

• var_name (str, optional, default=None) – The NetCDF variable name of the desired Connectivity. If None, does not check for var_name.

• attributes (dict, optional, default=None) – A dictionary of attributes desired on the Connectivity. If None, does not check for attributes.

• cf_role (str, optional, default=None) – The UGRID cf_role of the desired Connectivity.

• contains_node (bool, optional) – Contains the node element as part of the cf_role in the list of objects to be matched.

• contains_edge (bool, optional) – Contains the edge element as part of the cf_role in the list of objects to be matched.

• contains_face (bool, optional) – Contains the face element as part of the cf_role in the list of objects to be matched.

Returns:

The Connectivity from the Mesh that matched the given criteria.

Return type:

Connectivity

coord(item=None, standard_name=None, long_name=None, var_name=None, attributes=None, axis=None, include_nodes=None, include_edges=None, include_faces=None)

Return a single AuxCoord coordinate.

Return a single AuxCoord coordinate from the Mesh that matches the provided criteria.

Criteria can be either specific properties or other objects with metadata to be matched.

Note

If the given criteria do not return precisely one coordinate, then a CoordinateNotFoundError is raised.

See also

Mesh.coords() for matching zero or more coordinates.

Parameters:

• item (str or object, optional, default=None) –

  Either,

  • a standard_name, long_name, or var_name which is compared against the name().

  • a coordinate or metadata instance equal to that of the desired coordinate e.g., AuxCoord or CoordMetadata.

• standard_name (str, optional, default=None) – The CF standard name of the desired coordinate. If None, does not check for standard_name.

• long_name (str, optional, default=None) – An unconstrained description of the coordinate. If None, does not check for long_name.

• var_name (str, optional, default=None) – The NetCDF variable name of the desired coordinate. If None, does not check for var_name.

• attributes (dict, optional, default=None) – A dictionary of attributes desired on the coordinates. If None, does not check for attributes.

• axis (str, optional, default=None) – The desired coordinate axis, see guess_coord_axis(). If None, does not check for axis. Accepts the values X, Y, Z and T (case-insensitive).

• include_node (bool, optional) – Include all node coordinates in the list of objects to be matched.

• include_edge (bool, optional) – Include all edge coordinates in the list of objects to be matched.

• include_face (bool, optional) – Include all face coordinates in the list of objects to be matched.

Returns:

The AuxCoord coordinate from the Mesh that matched the given criteria.

Return type:

AuxCoord

coords(item=None, standard_name=None, long_name=None, var_name=None, attributes=None, axis=None, include_nodes=None, include_edges=None, include_faces=None)

Return all AuxCoord coordinates from the Mesh.

Return all AuxCoord coordinates from the Mesh that match the provided criteria.

Criteria can be either specific properties or other objects with metadata to be matched.

See also

Mesh.coord() for matching exactly one coordinate.

Parameters:

• item (str or object, optional, default=None) –

  Either,

  • a standard_name, long_name, or var_name which is compared against the name().

  • a coordinate or metadata instance equal to that of the desired coordinates e.g., AuxCoord or CoordMetadata.

• standard_name (str, optional, default=None) – The CF standard name of the desired coordinate. If None, does not check for standard_name.

• long_name (str, optional, default=None) – An unconstrained description of the coordinate. If None, does not check for long_name.

• var_name (str, optional, default=None) – The NetCDF variable name of the desired coordinate. If None, does not check for var_name.

• attributes (dict, optional, default=None) – A dictionary of attributes desired on the coordinates. If None, does not check for attributes.

• axis (str, optional, default=None) – The desired coordinate axis, see guess_coord_axis(). If None, does not check for axis. Accepts the values X, Y, Z and T (case-insensitive).

• include_node (bool, optional) – Include all node coordinates in the list of objects to be matched.

• include_edge (bool, optional) – Include all edge coordinates in the list of objects to be matched.

• include_face (bool, optional) – Include all face coordinates in the list of objects to be matched.

Returns:

A list of AuxCoord coordinates from the Mesh that matched the given criteria.

Return type:

list of AuxCoord

dimension_names(node=None, edge=None, face=None)

Assign the name to be used for the NetCDF variable.

Assign the name to be used for the NetCDF variable representing the node, edge and face dimension.

The default value of None will not be assigned to clear the associated node, edge or face. Instead use Mesh.dimension_names_reset().

Parameters:

• node (str, optional, default=None) – The name to be used for the NetCDF variable representing the node dimension.

• edge (str, optional, default=None) – The name to be used for the NetCDF variable representing the edge dimension.

• face (str, optional, default=None) – The name to be used for the NetCDF variable representing the face dimension.

dimension_names_reset(node=False, edge=False, face=False)

Reset the name used for the NetCDF variable.

Reset the name used for the NetCDF variable representing the node, edge and/or face dimension to None.

Parameters:

• node (bool, optional, default=False) – Reset the name of the node dimension if True. Default is False.

• edge (bool, optional, default=False) – Reset the name of the edge dimension if True. Default is False.

• face (bool, optional, default=False) – Reset the name of the face dimension if True. Default is False.

property edge_coords

The optional UGRID edge AuxCoord coordinates of the Mesh.

property edge_dimension

The optionally required UGRID NetCDF variable name for the edge dimension.

property edge_face_connectivity

The optional UGRID edge_face_connectivity Connectivity.

The optional UGRID edge_face_connectivity Connectivity of the Mesh.

property edge_node_connectivity

The UGRID edge_node_connectivity Connectivity.

The UGRID edge_node_connectivity Connectivity of the Mesh, which is required for Mesh.topology_dimension of 1, and optionally required for Mesh.topology_dimension >=2.

property face_coords

The optional UGRID face AuxCoord coordinates of the Mesh.

property face_dimension

The optional UGRID NetCDF variable name for the face dimension.

property face_edge_connectivity

The optional UGRID face_edge_connectivityConnectivity.

The optional UGRID face_edge_connectivity Connectivity of the Mesh.

property face_face_connectivity

The optional UGRID face_face_connectivity Connectivity.

The optional UGRID face_face_connectivity Connectivity of the Mesh.

property face_node_connectivity

Return face_node_connectivityConnectivity.

The UGRID face_node_connectivity Connectivity of the Mesh, which is required for Mesh.topology_dimension of 2, and optionally required for Mesh.topology_dimension of 3.

classmethod from_coords(*coords)

Construct a Mesh by derivation from one or more Coord\ s.

The topology_dimension, Coord membership and Connectivity membership are all determined based on the shape of the first bounds:

• None or (n, <2):

  Not supported

• (n, 2):

  topology_dimension = 1. node_coords and edge_node_connectivity constructed from bounds. edge_coords constructed from points.

• (n, >=3):

  topology_dimension = 2. node_coords and face_node_connectivity constructed from bounds. face_coords constructed from points.

Parameters:

*coords (Iterable of Coord) – Coordinates to pass into the Mesh. All points must have the same shapes; all bounds must have the same shapes, and must not be None.

Return type:

Mesh

Notes

Note

Any resulting duplicate nodes are not currently removed, due to the computational intensity.

Note

Mesh currently requires X and Y Coord\ s specifically. iris.util.guess_coord_axis() is therefore attempted, else the first two Coord\ s are taken.

Examples

# Reconstruct a cube-with-mesh after subsetting it.

>>> print(cube_w_mesh.mesh.name())
Topology data of 2D unstructured mesh
>>> mesh_coord_names = [
...     coord.name() for coord in cube_w_mesh.coords(mesh_coords=True)
... ]
>>> print(f"MeshCoords: {mesh_coord_names}")
MeshCoords: ['latitude', 'longitude']

# Subsetting converts MeshCoords to AuxCoords.
>>> slices = [slice(None)] * cube_w_mesh.ndim
>>> slices[cube_w_mesh.mesh_dim()] = slice(-1)
>>> cube_sub = cube_w_mesh[tuple(slices)]
>>> print(cube_sub.mesh)
None
>>> orig_coords = [cube_sub.coord(c_name) for c_name in mesh_coord_names]
>>> for coord in orig_coords:
...     print(f"{coord.name()}: {type(coord).__name__}")
latitude: AuxCoord
longitude: AuxCoord

>>> new_mesh = Mesh.from_coords(*orig_coords)
>>> new_coords = new_mesh.to_MeshCoords(location=cube_w_mesh.location)

# Replace the AuxCoords with MeshCoords.
>>> for ix in range(2):
...     cube_sub.remove_coord(orig_coords[ix])
...     cube_sub.add_aux_coord(new_coords[ix], cube_w_mesh.mesh_dim())

>>> print(cube_sub.mesh.name())
Topology data of 2D unstructured mesh
>>> for coord_name in mesh_coord_names:
...     coord = cube_sub.coord(coord_name)
...     print(f"{coord_name}: {type(coord).__name__}")
latitude: MeshCoord
longitude: MeshCoord

property node_coords

The required UGRID node AuxCoord coordinates of the Mesh.

property node_dimension

The NetCDF variable name for the node dimension.

remove_connectivities(item=None, standard_name=None, long_name=None, var_name=None, attributes=None, cf_role=None, contains_node=None, contains_edge=None, contains_face=None)

Remove one or more Connectivity.

Remove one or more Connectivity from the Mesh that match the provided criteria.

Criteria can be either specific properties or other objects with metadata to be matched.

Parameters:

• item (str or object, optional, default=None) –

  Either,

  • a standard_name, long_name, or var_name which is compared against the name().

  • a connectivity or metadata instance equal to that of the desired objects e.g., Connectivity or ConnectivityMetadata.

• standard_name (str, optional, default=None) – The CF standard name of the desired Connectivity. If None, does not check for standard_name.

• long_name (str, optional, default=None) – An unconstrained description of the Connectivity. If None, does not check for long_name.

• var_name (str, optional, default=None) – The NetCDF variable name of the desired Connectivity. If None, does not check for var_name.

• attributes (dict, optional, default=None) – A dictionary of attributes desired on the Connectivity. If None, does not check for attributes.

• cf_role (str, optional, default=None) – The UGRID cf_role of the desired Connectivity.

• contains_node (bool, optional) – Contains the node element as part of the cf_role in the list of objects to be matched for potential removal.

• contains_edge (bool, optional) – Contains the edge element as part of the cf_role in the list of objects to be matched for potential removal.

• contains_face (bool, optional) – Contains the face element as part of the cf_role in the list of objects to be matched for potential removal.

Returns:

A list of Connectivity instances removed from the Mesh that matched the given criteria.

Return type:

list of Connectivity

remove_coords(item=None, standard_name=None, long_name=None, var_name=None, attributes=None, axis=None, include_nodes=None, include_edges=None, include_faces=None)

Remove one or more AuxCoord from the Mesh.

Remove one or more AuxCoord from the Mesh that match the provided criteria.

Criteria can be either specific properties or other objects with metadata to be matched.

Parameters:

• item (str or object, optional, default=None) –

  Either,

  • a standard_name, long_name, or var_name which is compared against the name().

  • a coordinate or metadata instance equal to that of the desired coordinates e.g., AuxCoord or CoordMetadata.

• standard_name (str, optional, default=None) – The CF standard name of the desired coordinate. If None, does not check for standard_name.

• long_name (str, optional, default=None) – An unconstrained description of the coordinate. If None, does not check for long_name.

• var_name (str, optional, default=None) – The NetCDF variable name of the desired coordinate. If None, does not check for var_name.

• attributes (dict, optional, default=None) – A dictionary of attributes desired on the coordinates. If None, does not check for attributes.

• axis (str, optional, default=None) – The desired coordinate axis, see guess_coord_axis(). If None, does not check for axis. Accepts the values X, Y, Z and T (case-insensitive).

• include_node (bool, optional) – Include all node coordinates in the list of objects to be matched for potential removal.

• include_edge (bool, optional) – Include all edge coordinates in the list of objects to be matched for potential removal.

• include_face (bool, optional) – Include all face coordinates in the list of objects to be matched for potential removal.

Returns:

A list of AuxCoord coordinates removed from the Mesh that matched the given criteria.

Return type:

list of AuxCoord

summary(shorten=False)

Return a string representation of the Mesh.

Parameters:

shorten (bool, default=False) – If True, produce a oneline string form of the form <Mesh: …>. If False, produce a multi-line detailed print output.

Returns:

result

Return type:

str

to_MeshCoord(location, axis)

Generate a MeshCoord.

Generate a MeshCoord that references the current Mesh, and passing through the location and axis arguments.

See also

to_MeshCoords() for generating a series of mesh coords.

Parameters:

• location (str) – The location argument for MeshCoord instantiation.

• axis (str) – The axis argument for MeshCoord instantiation.

Returns:

A MeshCoord referencing the current Mesh.

Return type:

MeshCoord

to_MeshCoords(location)

Generate a tuple of MeshCoord\ s.

Generate a tuple of MeshCoord\ s, each referencing the current Mesh, one for each AXES value, passing through the location argument.

See also

to_MeshCoord() for generating a single mesh coord.

Parameters:

location (str) – The location argument for MeshCoord instantiation.

Returns:

tuple of MeshCoord referencing the current Mesh. One for each value in AXES, using the value for the axis argument.

Return type:

tuple of MeshCoord

property topology_dimension

UGRID topology_dimension attribute.

The UGRID topology_dimension attribute represents the highest dimensionality of all the geometric elements (node, edge, face) represented within the Mesh.

xml_element(doc)

Create the xml.dom.minidom.Element that describes this Mesh.

Parameters:

doc (object) – The parent xml.dom.minidom.Document.

Returns:

The xml.dom.minidom.Element that will describe this Mesh, and the dictionary of attributes that require to be added to this element.

Return type:

xml.dom.minidom.Element

class iris.experimental.ugrid.MeshCoord(mesh, location, axis)

Bases: AuxCoord

Geographic coordinate values of data on an unstructured mesh.

A MeshCoord references a ~iris.experimental.ugrid.mesh.Mesh. When contained in a ~iris.cube.Cube it connects the cube to the Mesh. It records (a) which 1-D cube dimension represents the unstructured mesh, and (b) which mesh ‘location’ the cube data is mapped to – i.e. is it data on ‘face’s, ‘edge’s or ‘node’s.

A MeshCoord also specifies its ‘axis’ : ‘x’ or ‘y’. Its values are then, accordingly, longitudes or latitudes. The values are taken from the appropriate coordinates and connectivities in the Mesh, determined by its ‘location’ and ‘axis’.

Any cube with data on a mesh will have a MeshCoord for each axis, i.e. an ‘X’ and a ‘Y’.

The points and bounds contain coordinate values for the mesh elements, which depends on location. For ‘node’, the .points contains node locations. For ‘edge’, the .bounds contains edge endpoints, and the .points contain edge locations (typically centres), if the Mesh contains them (optional). For ‘face’, the .bounds contain the face corners, and the .points contain the face locations (typically centres), if the Mesh contains them (optional).

Note

As described above, it is possible for a MeshCoord to have bounds but no points. This is not possible for a regular AuxCoord or DimCoord.

Note

A MeshCoord can not yet actually be created with bounds but no points. This is intended in future, but for now it raises an error.

Create a coordinate with mutable points and bounds.

Parameters:

• points – The values (or value in the case of a scalar coordinate) for each cell of the coordinate.

• standard_name (optional) – CF standard name of the coordinate.

• long_name (optional) – Descriptive name of the coordinate.

• var_name (optional) – The netCDF variable name for the coordinate.

• unit (Unit, optional) – The Unit of the coordinate’s values. Can be a string, which will be converted to a Unit object.

• bounds (optional) – An array of values describing the bounds of each cell. Given n bounds for each cell, the shape of the bounds array should be points.shape + (n,). For example, a 1D coordinate with 100 points and two bounds per cell would have a bounds array of shape (100, 2) Note if the data is a climatology, climatological should be set.

• attributes (optional) – A dictionary containing other CF and user-defined attributes.

• coord_system (CoordSystem, optional) – A CoordSystem representing the coordinate system of the coordinate, e.g., a GeogCS for a longitude coordinate.

• bool (climatological) – When True: the coordinate is a NetCDF climatological time axis. When True: saving in NetCDF will give the coordinate variable a ‘climatology’ attribute and will create a boundary variable called ‘<coordinate-name>_climatology’ in place of a standard bounds attribute and bounds variable. Will set to True when a climatological time axis is loaded from NetCDF. Always False if no bounds exist.

• optional – When True: the coordinate is a NetCDF climatological time axis. When True: saving in NetCDF will give the coordinate variable a ‘climatology’ attribute and will create a boundary variable called ‘<coordinate-name>_climatology’ in place of a standard bounds attribute and bounds variable. Will set to True when a climatological time axis is loaded from NetCDF. Always False if no bounds exist.

__deepcopy__(memo)

Make this equivalent to “shallow” copy.

Returns a new MeshCoord based on the same Mesh.

Required to prevent cube copying from copying the Mesh, which would prevent “cube.copy() == cube” : see notes for copy().

property axis

property climatological

The ‘climatological’ of a MeshCoord is always ‘False’.

property coord_system

The coordinate-system of a MeshCoord is always ‘None’.

copy(points=None, bounds=None)

Make a copy of the MeshCoord.

Parameters:

• points (array)) – Provided solely for signature compatibility with other types of Coord. In this case, if either is not ‘None’, an error is raised.

• bounds (array)) – Provided solely for signature compatibility with other types of Coord. In this case, if either is not ‘None’, an error is raised.

property location

property mesh

summary(*args, **kwargs)

Make a printable text summary.

Parameters:

• shorten (bool, default = False) – If True, produce an abbreviated one-line summary. If False, produce a multi-line summary, with embedded newlines.

• max_values (int or None, default = None) – If more than this many data values, print truncated data arrays instead of full contents. If 0, print only the shape. The default is 5 if shorten=True, or 15 otherwise. This overrides numpy.get_printoptions['threshold'].

• linewidth (int or None, default = None) – Character-width controlling line splitting of array outputs. If unset, defaults to numpy.get_printoptions['linewidth'].

• edgeitems (int, default=2) – Controls truncated array output. Overrides numpy.getprintoptions['edgeitems'].

• precision (int or None, default = None) – Controls number decimal formatting. When shorten=True this is defaults to 3, in which case it overrides numpy.get_printoptions()['precision'].

• convert_dates (bool, default = True) – If the units has a calendar, then print array values as date strings instead of the actual numbers.

Returns:

result – Output text, with embedded newlines when shorten=False.

Return type:

str

Notes

Note

Arrays are formatted using numpy.array2string(). Some aspects of the array formatting are controllable in the usual way, via numpy.printoptions(), but others are overridden as detailed above. Control of those aspects is still available, but only via the call arguments.

iris.experimental.ugrid.load_mesh(uris, var_name=None)

Load a single Mesh object from one or more NetCDF files.

Raises an error if more/less than one Mesh is found.

Parameters:

• uris (str or iterable of str) –

  One or more filenames/URI’s. Filenames can include wildcards. Any URI’s

  must support OpenDAP.

• var_name (str, optional) –

  Only return a Mesh if its

  var_name matches this value.

Return type:

iris.experimental.ugrid.mesh.Mesh

iris.experimental.ugrid.load_meshes(uris, var_name=None)

Load Mesh objects from one or more NetCDF files.

Parameters:

• uris (str or iterable of str) –

  One or more filenames/URI’s. Filenames can include wildcards. Any URI’s

  must support OpenDAP.

• var_name (str, optional) –

  Only return Mesh\ es that have

  var_names matching this value.

Returns:

A dictionary mapping each mesh-containing file path/URL in the input

uris to a list of the Mesh\ es returned from each.

Return type:

dict

iris.experimental.ugrid.recombine_submeshes(mesh_cube, submesh_cubes, index_coord_name='i_mesh_index')

Put data from sub-meshes back onto the original full mesh.

The result is a cube like mesh_cube, but with its data replaced by a combination of the data in the submesh_cubes.

Parameters:

• mesh_cube (Cube) – Describes the mesh and mesh-location onto which the all the submesh-cubes’ data are mapped, and acts as a template for the result. Must have a Mesh.

• submesh_cubes (iterable of Cube, or Cube) – Cubes, each with data on a _subset_ of the mesh_cube datapoints (within the mesh dimension). The submesh cubes do not need to have a mesh. There must be at least 1 of them, to determine the result phenomenon. Their metadata (names, units and attributes) must all be the same, _except_ that ‘var_name’ is ignored. Their dtypes must all be the same. Their shapes and dimension-coords must all match those of mesh_cube, except in the mesh dimension, which can have different sizes between the submeshes, and from the mesh_cube. The mesh dimension of each must have a 1-D coord named by index_coord_name. These “index coords” can vary in length, but they must all have matching metadata (units, attributes and names except ‘var_name’), and must also match the coord of that name in mesh_cube, if there is one. The “.points” values of the index coords specify, for each datapoint, its location in the original mesh – i.e. they are indices into the relevant mesh-location dimension.

• index_coord_name (Cube) – Coord name of an index coord containing the mesh location indices, in every submesh cube.

Returns:

A cube with the same mesh, location, and shape as mesh_cube, but with its data replaced by that from the``submesh_cubes``. The result phenomeon identity is also that of the``submesh_cubes``, i.e. units, attributes and names (except ‘var_name’, which is None).

Return type:

result_cube

Notes

Where regions overlap, the result data comes from the submesh cube containing that location which appears _last_ in submesh_cubes.

Where no region contains a datapoint, it will be masked in the result. HINT: alternatively, values covered by no region can be set to the original ‘full_mesh_cube’ data value, if ‘full_mesh_cube’ is also passed as the first of the ‘region_cubes’.

The result_cube dtype is that of the submesh_cubes.

iris.experimental.ugrid.save_mesh(mesh, filename, netcdf_format='NETCDF4')

Save mesh(es) to a netCDF file.

Args:

• mesh (iris.experimental.ugrid.Mesh or iterable):

  mesh(es) to save.

• filename (string):

  Name of the netCDF file to create.

Kwargs:

• netcdf_format (string):

  Underlying netCDF file format, one of ‘NETCDF4’, ‘NETCDF4_CLASSIC’, ‘NETCDF3_CLASSIC’ or ‘NETCDF3_64BIT’. Default is ‘NETCDF4’ format.

Submodules

• iris.experimental.ugrid.cf
  • CFUGridAuxiliaryCoordinateVariable
    • CFUGridAuxiliaryCoordinateVariable.cf_identities
    • CFUGridAuxiliaryCoordinateVariable.cf_identity
    • CFUGridAuxiliaryCoordinateVariable.identify()
  • CFUGridConnectivityVariable
    • CFUGridConnectivityVariable.cf_identities
    • CFUGridConnectivityVariable.cf_identity
    • CFUGridConnectivityVariable.identify()
  • CFUGridGroup
    • CFUGridGroup.connectivities
    • CFUGridGroup.meshes
    • CFUGridGroup.non_data_variable_names
    • CFUGridGroup.ugrid_coords
  • CFUGridMeshVariable
    • CFUGridMeshVariable.cf_identity
    • CFUGridMeshVariable.identify()
  • CFUGridReader
    • CFUGridReader.CFGroup
• iris.experimental.ugrid.load
  • PARSE_UGRID_ON_LOAD
  • ParseUGridOnLoad
    • ParseUGridOnLoad.context()
  • load_mesh()
  • load_meshes()
• iris.experimental.ugrid.mesh
  • Connectivity
    • Connectivity.UGRID_CF_ROLES
    • Connectivity.cf_role
    • Connectivity.connected
    • Connectivity.connected_axis
    • Connectivity.core_indices()
    • Connectivity.cube_dims()
    • Connectivity.has_lazy_indices()
    • Connectivity.indices
    • Connectivity.indices_by_location()
    • Connectivity.lazy_indices()
    • Connectivity.lazy_location_lengths()
    • Connectivity.location
    • Connectivity.location_axis
    • Connectivity.location_lengths()
    • Connectivity.start_index
    • Connectivity.transpose()
    • Connectivity.validate_indices()
    • Connectivity.xml_element()
  • Mesh
    • Mesh.AXES
    • Mesh.ELEMENTS
    • Mesh.TOPOLOGY_DIMENSIONS
    • Mesh.add_connectivities()
    • Mesh.add_coords()
    • Mesh.all_connectivities
    • Mesh.all_coords
    • Mesh.boundary_node_connectivity
    • Mesh.cf_role
    • Mesh.connectivities()
    • Mesh.connectivity()
    • Mesh.coord()
    • Mesh.coords()
    • Mesh.dimension_names()
    • Mesh.dimension_names_reset()
    • Mesh.edge_coords
    • Mesh.edge_dimension
    • Mesh.edge_face_connectivity
    • Mesh.edge_node_connectivity
    • Mesh.face_coords
    • Mesh.face_dimension
    • Mesh.face_edge_connectivity
    • Mesh.face_face_connectivity
    • Mesh.face_node_connectivity
    • Mesh.from_coords()
    • Mesh.node_coords
    • Mesh.node_dimension
    • Mesh.remove_connectivities()
    • Mesh.remove_coords()
    • Mesh.summary()
    • Mesh.to_MeshCoord()
    • Mesh.to_MeshCoords()
    • Mesh.topology_dimension
    • Mesh.xml_element()
  • Mesh1DConnectivities
    • Mesh1DConnectivities.edge_node
  • Mesh1DCoords
    • Mesh1DCoords.edge_x
    • Mesh1DCoords.edge_y
    • Mesh1DCoords.node_x
    • Mesh1DCoords.node_y
  • Mesh1DNames
    • Mesh1DNames.edge_dimension
    • Mesh1DNames.node_dimension
  • Mesh2DConnectivities
    • Mesh2DConnectivities.boundary_node
    • Mesh2DConnectivities.edge_face
    • Mesh2DConnectivities.edge_node
    • Mesh2DConnectivities.face_edge
    • Mesh2DConnectivities.face_face
    • Mesh2DConnectivities.face_node
  • Mesh2DCoords
    • Mesh2DCoords.edge_x
    • Mesh2DCoords.edge_y
    • Mesh2DCoords.face_x
    • Mesh2DCoords.face_y
    • Mesh2DCoords.node_x
    • Mesh2DCoords.node_y
  • Mesh2DNames
    • Mesh2DNames.edge_dimension
    • Mesh2DNames.face_dimension
    • Mesh2DNames.node_dimension
  • MeshCoord
    • MeshCoord.__deepcopy__()
    • MeshCoord.axis
    • MeshCoord.climatological
    • MeshCoord.coord_system
    • MeshCoord.copy()
    • MeshCoord.location
    • MeshCoord.mesh
    • MeshCoord.summary()
  • MeshEdgeCoords
    • MeshEdgeCoords.edge_x
    • MeshEdgeCoords.edge_y
  • MeshFaceCoords
    • MeshFaceCoords.face_x
    • MeshFaceCoords.face_y
  • MeshNodeCoords
    • MeshNodeCoords.node_x
    • MeshNodeCoords.node_y
  • NP_PRINTOPTIONS_EDGEITEMS
  • NP_PRINTOPTIONS_THRESHOLD
• iris.experimental.ugrid.metadata
  • ConnectivityMetadata
    • ConnectivityMetadata.combine()
    • ConnectivityMetadata.difference()
    • ConnectivityMetadata.equal()
  • MeshCoordMetadata
    • MeshCoordMetadata.combine()
    • MeshCoordMetadata.difference()
    • MeshCoordMetadata.equal()
  • MeshMetadata
    • MeshMetadata.combine()
    • MeshMetadata.difference()
    • MeshMetadata.equal()
• iris.experimental.ugrid.save
  • save_mesh()
• iris.experimental.ugrid.utils
  • recombine_submeshes()