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.

In this module:

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

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)[source]

Constructs a single connectivity.

Args:

  • 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.

Kwargs:

  • standard_name (str):

    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):

    Descriptive name of the connectivity.

  • var_name (str):

    The NetCDF variable name for the connectivity.

  • units (cf_units.Unit):

    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):

    A dictionary containing other cf and user-defined attributes.

  • start_index (int):

    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):

    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.

__binary_operator__(other, mode_constant)

Common code which is called by add, sub, mul and div

Mode constant is one of ADD, SUB, MUL, DIV, RDIV

Note

The unit is not changed when doing scalar operations on a metadata object. This means that a metadata object which represents “10 meters” when multiplied by a scalar i.e. “1000” would result in a metadata object of “10000 meters”. An alternative approach could be taken to multiply the unit by 1000 and the resultant metadata object would represent “10 kilometers”.

__getitem__(keys)

Returns a new dimensional metadata whose values are obtained by conventional array indexing.

Note

Indexing of a circular coordinate results in a non-circular coordinate if the overall shape of the coordinate changes after indexing.

convert_units(unit)

Change the units, converting the values of the metadata.

copy(values=None)

Returns a copy of this dimensional metadata object.

Kwargs:

  • values

    An array of values for the new dimensional metadata object. This may be a different shape to the original values array being copied.

core_indices()[source]

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

Returns

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

cube_dims(cube)[source]

Not available on Connectivity.

has_bounds()

Return a boolean indicating whether the current dimensional metadata object has a bounds array.

has_lazy_indices()[source]

Return a boolean indicating whether the connectivity’s indices array is a lazy Dask array or not.

Returns

boolean

indices_by_location(indices=None)[source]

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()).

Kwargs:

  • 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.

is_compatible(other, ignore=None)

Return whether the current dimensional metadata object is compatible with another.

lazy_indices()[source]

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.

Returns

A lazy array, representing the connectivity indices array.

lazy_location_lengths()[source]

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.

location_lengths()[source]

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.

name(default=None, token=False)

Returns a string name representing the identity of the metadata.

First it tries standard name, then it tries the long name, then the NetCDF variable name, before falling-back to a default value, which itself defaults to the string ‘unknown’.

Kwargs:

  • default:

    The fall-back string representing the default name. Defaults to the string ‘unknown’.

  • token:

    If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is raised. Defaults to False.

Returns

String.

rename(name)

Changes the human-readable name.

If ‘name’ is a valid standard name it will assign it to standard_name, otherwise it will assign it to long_name.

summary(shorten=False, max_values=None, edgeitems=2, linewidth=None, precision=None, convert_dates=True, _section_indices=None)

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 = 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

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.

transpose()[source]

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.

validate_indices()[source]

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)[source]

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

Args:

  • doc:

    The parent xml.dom.minidom.Document.

Returns

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

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 attributes
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 - 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 - 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.

property dtype

The NumPy dtype of the current dimensional metadata object, as specified by its values.

property indices

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.

property location

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 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.

property long_name

The CF Metadata long name for the object.

property metadata
property ndim

Return the number of dimensions of the current dimensional metadata object.

property shape

The fundamental shape of the metadata, expressed as a tuple.

property standard_name

The CF Metadata standard name for the object.

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.

property units

The S.I. unit of the object.

property var_name

The NetCDF variable name for the object.

↑ top ↑

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/

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)[source]

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.

add_connectivities(*connectivities)[source]

Add one or more Connectivity instances to the Mesh.

Args:

  • 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)[source]

Add one or more AuxCoord coordinates to the Mesh.

Kwargs:

  • node_x (object):

    The x-axis like node AuxCoord.

  • node_y (object):

    The y-axis like node AuxCoord.

  • edge_x (object):

    The x-axis like edge AuxCoord.

  • edge_y (object):

    The y-axis like edge AuxCoord.

  • face_x (object):

    The x-axis like face AuxCoord.

  • face_y (object):

    The y-axis like face AuxCoord.

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)[source]

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.

Kwargs:

  • item (str or object):

    Either,

  • standard_name (str):

    The CF standard name of the desired Connectivity. If None, does not check for standard_name.

  • long_name (str):

    An unconstrained description of the Connectivity. If None, does not check for long_name.

  • var_name (str):

    The NetCDF variable name of the desired Connectivity. If None, does not check for var_name.

  • attributes (dict):

    A dictionary of attributes desired on the Connectivity. If None, does not check for attributes.

  • cf_role (str):

    The UGRID cf_role of the desired Connectivity.

  • contains_node (bool):

    Contains the node element as part of the cf_role in the list of objects to be matched.

  • contains_edge (bool):

    Contains the edge element as part of the cf_role in the list of objects to be matched.

  • contains_face (bool):

    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.

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)[source]

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.

Kwargs:

  • item (str or object):

    Either,

  • standard_name (str):

    The CF standard name of the desired Connectivity. If None, does not check for standard_name.

  • long_name (str):

    An unconstrained description of the Connectivity. If None, does not check for long_name.

  • var_name (str):

    The NetCDF variable name of the desired Connectivity. If None, does not check for var_name.

  • attributes (dict):

    A dictionary of attributes desired on the Connectivity. If None, does not check for attributes.

  • cf_role (str):

    The UGRID cf_role of the desired Connectivity.

  • contains_node (bool):

    Contains the node element as part of the cf_role in the list of objects to be matched.

  • contains_edge (bool):

    Contains the edge element as part of the cf_role in the list of objects to be matched.

  • contains_face (bool):

    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.

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)[source]

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.

Kwargs:

  • item (str or object):

    Either,

  • standard_name (str):

    The CF standard name of the desired coordinate. If None, does not check for standard_name.

  • long_name (str):

    An unconstrained description of the coordinate. If None, does not check for long_name.

  • var_name (str):

    The NetCDF variable name of the desired coordinate. If None, does not check for var_name.

  • attributes (dict):

    A dictionary of attributes desired on the coordinates. If None, does not check for attributes.

  • axis (str):

    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):

    Include all node coordinates in the list of objects to be matched.

  • include_edge (bool):

    Include all edge coordinates in the list of objects to be matched.

  • include_face (bool):

    Include all face coordinates in the list of objects to be matched.

Returns

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

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)[source]

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.

Kwargs:

  • item (str or object):

    Either,

  • standard_name (str):

    The CF standard name of the desired coordinate. If None, does not check for standard_name.

  • long_name (str):

    An unconstrained description of the coordinate. If None, does not check for long_name.

  • var_name (str):

    The NetCDF variable name of the desired coordinate. If None, does not check for var_name.

  • attributes (dict):

    A dictionary of attributes desired on the coordinates. If None, does not check for attributes.

  • axis (str):

    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):

    Include all node coordinates in the list of objects to be matched.

  • include_edge (bool):

    Include all edge coordinates in the list of objects to be matched.

  • include_face (bool):

    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.

dimension_names(node=None, edge=None, face=None)[source]

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().

Kwargs:

  • node (str):

    The name to be used for the NetCDF variable representing the node dimension.

  • edge (str):

    The name to be used for the NetCDF variable representing the edge dimension.

  • face (str):

    The name to be used for the NetCDF variable representing the face dimension.

dimension_names_reset(node=False, edge=False, face=False)[source]

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

Kwargs:

  • node (bool):

    Reset the name of the node dimension if True. Default is False.

  • edge (bool):

    Reset the name of the edge dimension if True. Default is False.

  • face (bool):

    Reset the name of the face dimension if True. Default is False.

classmethod from_coords(*coords)[source]

Construct a Mesh by derivation from one or more Coords.

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

Args:

  • *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.

Returns

Mesh

Note

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

Note

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

For example:

# 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
name(default=None, token=False)

Returns a string name representing the identity of the metadata.

First it tries standard name, then it tries the long name, then the NetCDF variable name, before falling-back to a default value, which itself defaults to the string ‘unknown’.

Kwargs:

  • default:

    The fall-back string representing the default name. Defaults to the string ‘unknown’.

  • token:

    If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is raised. Defaults to False.

Returns

String.

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)[source]

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.

Kwargs:

  • item (str or object):

    Either,

  • standard_name (str):

    The CF standard name of the desired Connectivity. If None, does not check for standard_name.

  • long_name (str):

    An unconstrained description of the If ``None`, does not check for long_name.

  • var_name (str):

    The NetCDF variable name of the desired Connectivity. If None, does not check for var_name.

  • attributes (dict):

    A dictionary of attributes desired on the Connectivity. If None, does not check for attributes.

  • cf_role (str):

    The UGRID cf_role of the desired Connectivity.

  • contains_node (bool):

    Contains the node element as part of the cf_role in the list of objects to be matched for potential removal.

  • contains_edge (bool):

    Contains the edge element as part of the cf_role in the list of objects to be matched for potential removal.

  • contains_face (bool):

    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.

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)[source]

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.

Kwargs:

  • item (str or object):

    Either,

  • standard_name (str):

    The CF standard name of the desired coordinate. If None, does not check for standard_name.

  • long_name (str):

    An unconstrained description of the coordinate. If None, does not check for long_name.

  • var_name (str):

    The NetCDF variable name of the desired coordinate. If None, does not check for var_name.

  • attributes (dict):

    A dictionary of attributes desired on the coordinates. If None, does not check for attributes.

  • axis (str):

    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):

    Include all node coordinates in the list of objects to be matched for potential removal.

  • include_edge (bool):

    Include all edge coordinates in the list of objects to be matched for potential removal.

  • include_face (bool):

    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.

rename(name)

Changes the human-readable name.

If ‘name’ is a valid standard name it will assign it to standard_name, otherwise it will assign it to long_name.

summary(shorten=False)[source]

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)[source]

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.

Args:

  • location (str)

    The location argument for MeshCoord instantiation.

  • axis (str)

    The axis argument for MeshCoord instantiation.

Returns

A MeshCoord referencing the current Mesh.

to_MeshCoords(location)[source]

Generate a tuple of MeshCoords, 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.

Args:

  • location (str)

    The location argument for MeshCoord instantiation.

Returns

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

xml_element(doc)[source]

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

Args:

  • 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.

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.

property all_connectivities

All the Connectivity instances of the Mesh.

property all_coords

All the AuxCoord coordinates of the Mesh.

property attributes
property boundary_node_connectivity

The optional UGRID boundary_node_connectivity Connectivity of the Mesh.

property cf_role

The UGRID cf_role attribute of the Mesh.

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 of the Mesh.

property edge_node_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 optionally required UGRID NetCDF variable name for the face dimension.

property face_edge_connectivity

The optional UGRID face_edge_connectivity Connectivity of the Mesh.

property face_face_connectivity

The optional UGRID face_face_connectivity Connectivity of the Mesh.

property face_node_connectivity

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.

property long_name

The CF Metadata long name for the object.

property metadata
property node_coords

The required UGRID node AuxCoord coordinates of the Mesh.

property node_dimension

The NetCDF variable name for the node dimension.

property standard_name

The CF Metadata standard name for the object.

property topology_dimension

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

property units

The S.I. unit of the object.

property var_name

The NetCDF variable name for the object.

↑ top ↑

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.

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

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.

__binary_operator__(other, mode_constant)

Common code which is called by add, sub, mul and div

Mode constant is one of ADD, SUB, MUL, DIV, RDIV

Note

The unit is not changed when doing scalar operations on a metadata object. This means that a metadata object which represents “10 meters” when multiplied by a scalar i.e. “1000” would result in a metadata object of “10000 meters”. An alternative approach could be taken to multiply the unit by 1000 and the resultant metadata object would represent “10 kilometers”.

__deepcopy__(memo)[source]

Make this equivalent to “shallow” copy, returning 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().

cell(index)

Return the single Cell instance which results from slicing the points/bounds with the given index.

cells()

Returns an iterable of Cell instances for this Coord.

For example:

for cell in self.cells():
   ...
collapsed(dims_to_collapse=None)

Returns a copy of this coordinate, which has been collapsed along the specified dimensions.

Replaces the points & bounds with a simple bounded region.

contiguous_bounds()

Returns the N+1 bound values for a contiguous bounded 1D coordinate of length N, or the (N+1, M+1) bound values for a contiguous bounded 2D coordinate of shape (N, M).

Only 1D or 2D coordinates are supported.

Note

If the coordinate has bounds, this method assumes they are contiguous.

If the coordinate is 1D and does not have bounds, this method will return bounds positioned halfway between the coordinate’s points.

If the coordinate is 2D and does not have bounds, an error will be raised.

convert_units(unit)

Change the coordinate’s units, converting the values in its points and bounds arrays.

For example, if a coordinate’s units attribute is set to radians then:

coord.convert_units('degrees')

will change the coordinate’s units attribute to degrees and multiply each value in points and bounds by 180.0/\(\pi\).

copy(points=None, bounds=None)[source]

Make a copy of the MeshCoord.

Kwargs:

  • points, bounds (array):

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

core_bounds()

The points array at the core of this coord, which may be a NumPy array or a dask array.

core_points()

The points array at the core of this coord, which may be a NumPy array or a dask array.

cube_dims(cube)

Return the cube dimensions of this Coord.

Equivalent to “cube.coord_dims(self)”.

classmethod from_coord(coord)

Create a new Coord of this type, from the given coordinate.

guess_bounds(bound_position=0.5)

Add contiguous bounds to a coordinate, calculated from its points.

Puts a cell boundary at the specified fraction between each point and the next, plus extrapolated lowermost and uppermost bound points, so that each point lies within a cell.

With regularly spaced points, the resulting bounds will also be regular, and all points lie at the same position within their cell. With irregular points, the first and last cells are given the same widths as the ones next to them.

Kwargs:

  • bound_position:

    The desired position of the bounds relative to the position of the points.

Note

An error is raised if the coordinate already has bounds, is not one-dimensional, or is not monotonic.

Note

Unevenly spaced values, such from a wrapped longitude range, can produce unexpected results : In such cases you should assign suitable values directly to the bounds property, instead.

has_bounds()

Return a boolean indicating whether the coord has a bounds array.

has_lazy_bounds()

Return a boolean indicating whether the coord’s bounds array is a lazy dask array or not.

has_lazy_points()

Return a boolean indicating whether the coord’s points array is a lazy dask array or not.

intersect(other, return_indices=False)

Returns a new coordinate from the intersection of two coordinates.

Both coordinates must be compatible as defined by is_compatible().

Kwargs:

  • return_indices:

    If True, changes the return behaviour to return the intersection indices for the “self” coordinate.

is_compatible(other, ignore=None)

Return whether the coordinate is compatible with another.

Compatibility is determined by comparing iris.coords.Coord.name(), iris.coords.Coord.units, iris.coords.Coord.coord_system and iris.coords.Coord.attributes that are present in both objects.

Args:

  • other:

    An instance of iris.coords.Coord, iris.common.CoordMetadata or iris.common.DimCoordMetadata.

  • ignore:

    A single attribute key or iterable of attribute keys to ignore when comparing the coordinates. Default is None. To ignore all attributes, set this to other.attributes.

Returns

Boolean.

is_contiguous(rtol=1e-05, atol=1e-08)

Return True if, and only if, this Coord is bounded with contiguous bounds to within the specified relative and absolute tolerances.

1D coords are contiguous if the upper bound of a cell aligns, within a tolerance, to the lower bound of the next cell along.

2D coords, with 4 bounds, are contiguous if the lower right corner of each cell aligns with the lower left corner of the cell to the right of it, and the upper left corner of each cell aligns with the lower left corner of the cell above it.

Args:

  • rtol:

    The relative tolerance parameter (default is 1e-05).

  • atol:

    The absolute tolerance parameter (default is 1e-08).

Returns

Boolean.

is_monotonic()

Return True if, and only if, this Coord is monotonic.

lazy_bounds()

Return a lazy array representing the coord bounds.

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

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

Returns

A lazy array representing the coord bounds array or None if the coord does not have bounds.

lazy_points()

Return a lazy array representing the coord points.

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

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

Returns

A lazy array, representing the coord points array.

name(default=None, token=False)

Returns a string name representing the identity of the metadata.

First it tries standard name, then it tries the long name, then the NetCDF variable name, before falling-back to a default value, which itself defaults to the string ‘unknown’.

Kwargs:

  • default:

    The fall-back string representing the default name. Defaults to the string ‘unknown’.

  • token:

    If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is raised. Defaults to False.

Returns

String.

nearest_neighbour_index(point)

Returns the index of the cell nearest to the given point.

Only works for one-dimensional coordinates.

For example:

>>> cube = iris.load_cube(iris.sample_data_path('ostia_monthly.nc'))
>>> cube.coord('latitude').nearest_neighbour_index(0)
9
>>> cube.coord('longitude').nearest_neighbour_index(10)
12

Note

If the coordinate contains bounds, these will be used to determine the nearest neighbour instead of the point values.

Note

For circular coordinates, the ‘nearest’ point can wrap around to the other end of the values.

rename(name)

Changes the human-readable name.

If ‘name’ is a valid standard name it will assign it to standard_name, otherwise it will assign it to long_name.

summary(*args, **kwargs)[source]

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 = 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

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.

xml_element(doc)

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

Args:

  • doc:

    The parent xml.dom.minidom.Document.

Returns

The xml.dom.minidom.Element that will describe this DimCoord.

property attributes
property axis
property bounds

The coordinate bounds values, as a NumPy array, or None if no bound values are defined.

Note

The shape of the bound array should be: points.shape + (n_bounds, ).

property bounds_dtype

The NumPy dtype of the coord’s bounds. Will be None if the coord does not have bounds.

property climatological

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

property coord_system

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

property dtype

The NumPy dtype of the current dimensional metadata object, as specified by its values.

property location
property long_name

The CF Metadata long name for the object.

property mesh
property metadata
property nbounds

Return the number of bounds that this coordinate has (0 for no bounds).

property ndim

Return the number of dimensions of the current dimensional metadata object.

property points

The coordinate points values as a NumPy array.

property shape

The fundamental shape of the metadata, expressed as a tuple.

property standard_name

The CF Metadata standard name for the object.

property units

The S.I. unit of the object.

property var_name

The NetCDF variable name for the object.

↑ top ↑

iris.experimental.ugrid.PARSE_UGRID_ON_LOAD

↑ top ↑

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

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

↑ top ↑

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

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 Meshes 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 Meshes returned from each.

Return type

dict

↑ top ↑

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

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.

↑ top ↑

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

Save mesh(es) to a netCDF file.

Args:

Kwargs:

  • netcdf_format (string):

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