iris.experimental.ugrid

Infra-structure for unstructured mesh support, based on CF UGRID Conventions (v1.0), https://ugrid-conventions.github.io/ugrid-conventions/

In this module:

This class allows the contents of a netCDF file to be interpreted according to the ‘NetCDF Climate and Forecast (CF) Metadata Conventions’.

Specialisation of CFReader that can also handle CF-UGRID-specific variable types.

class iris.experimental.ugrid.CFUGridReader(filename, warn=False, monotonic=False)[source]

This class allows the contents of a netCDF file to be interpreted according to the ‘NetCDF Climate and Forecast (CF) Metadata Conventions’.

Specialisation of CFReader that can also handle CF-UGRID-specific variable types.

CFGroup

Represents a collection of ‘NetCDF Climate and Forecast (CF) Metadata Conventions’ variables and netCDF global attributes.

Specialisation of CFGroup that includes extra collections for CF-UGRID-specific variable types.

alias of iris.experimental.ugrid.CFUGridGroup

cf_group

Collection of CF-netCDF variables associated with this netCDF file

↑ top ↑

A CF-UGRID topology connectivity, describing the topological relationship between two lists of dimensional locations. 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, src_dim=0)[source]

Constructs a single connectivity.

Args:

  • indices (numpy.ndarray or numpy.ma.core.MaskedArray or dask.array.Array):

    The index values describing a topological relationship. Constructed of 2 dimensions - the list of locations, and within each location: the indices of the ‘target locations’ it relates to. Use a numpy.ma.core.MaskedArray if src_location lengths vary - mask unused index ‘slots’ within each src_location. 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 locations, and the indexed ‘target location’ within each location. 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).

  • src_dim (int):

    Either 0 or 1. Default is 0. Denotes which dimension of indices varies over the src_location’s (the alternate dimension therefore varying within individual src_location’s). (This parameter allows support for fastest varying index being either first or last). E.g. for face_node_connectivity, for 10 faces: indices.shape[src_dim] = 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_src(indices=None)[source]

Return a view of the indices array with src_dim always as the first index - 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 src_dim 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_src_lengths()[source]

Return a lazy array representing the lengths of each src_location in the src_dim of the connectivity’s indices array, 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 lengths of each src_location.

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.

src_lengths()[source]

Return a NumPy array representing the lengths of each src_location in the src_dim of the connectivity’s indices array, accounting for masks if present.

Returns

A NumPy array, representing the lengths of each src_location.

transpose()[source]

Create a new Connectivity, identical to this one but with the indices array transposed and the src_dim 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 sizes of individual src_location’s (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 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 src_location shorter than the longest src_location 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 src_dim. A new Connectivity must therefore be defined if different indices are 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 src_dim

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

property src_location

Derived from the connectivity’s cf_role - the first part, e.g. face in face_node_connectivity. Refers to the locations listed by the src_dim of the connectivity’s indices array.

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 tgt_dim

Derived as the alternate value of src_dim - each must equal either 0 or 1. The dimension of the connectivity’s indices array that varies within the connectivity’s individual src_location’s.

property tgt_location

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

property units

The S.I. unit of the object.

property var_name

The NetCDF variable name for the object.

↑ top ↑

Metadata container for a Connectivity.

class iris.experimental.ugrid.ConnectivityMetadata(_cls, standard_name, long_name, var_name, units, attributes, cf_role, start_index, src_dim)[source]

Create new instance of ConnectivityMetadataNamedtuple(standard_name, long_name, var_name, units, attributes, cf_role, start_index, src_dim)

combine(other, lenient=None)[source]

Return a new metadata instance created by combining each of the associated metadata members.

Args:

  • other (metadata):

    A metadata instance of the same type.

Kwargs:

  • lenient (boolean):

    Enable/disable lenient combination. The default is to automatically detect whether this lenient operation is enabled.

Returns

Metadata instance.

count(value, /)

Return number of occurrences of value.

difference(other, lenient=None)[source]

Return a new metadata instance created by performing a difference comparison between each of the associated metadata members.

A metadata member returned with a value of “None” indicates that there is no difference between the members being compared. Otherwise, a tuple of the different values is returned.

Args:

  • other (metadata):

    A metadata instance of the same type.

Kwargs:

  • lenient (boolean):

    Enable/disable lenient difference. The default is to automatically detect whether this lenient operation is enabled.

Returns

Metadata instance of member differences or None.

equal(other, lenient=None)[source]

Determine whether the associated metadata members are equivalent.

Args:

  • other (metadata):

    A metadata instance of the same type.

Kwargs:

  • lenient (boolean):

    Enable/disable lenient equivalence. The default is to automatically detect whether this lenient operation is enabled.

Returns

Boolean.

classmethod from_metadata(other)

Convert the provided metadata instance from a different type to this metadata type, using only the relevant metadata members.

Non-common metadata members are set to None.

Args:

  • other (metadata):

    A metadata instance of any type.

Returns

New metadata instance.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

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.

classmethod token(name)

Determine whether the provided name is a valid NetCDF name and thus safe to represent a single parsable token.

Args:

  • name:

    The string name to verify

Returns

The provided name if valid, otherwise None.

DEFAULT_NAME = 'unknown'
attributes

Alias for field number 4

cf_role

Alias for field number 5

long_name

Alias for field number 1

src_dim

Alias for field number 7

standard_name

Alias for field number 0

start_index

Alias for field number 6

units

Alias for field number 3

var_name

Alias for field number 2

↑ 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 location as part of the ConnectivityMetadata.cf_role in the list of objects to be matched.

  • contains_edge (bool):

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

  • contains_face (bool):

    Contains the face location as part of the ConnectivityMetadata.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 location as part of the ConnectivityMetadata.cf_role in the list of objects to be matched.

  • contains_edge (bool):

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

  • contains_face (bool):

    Contains the face location as part of the ConnectivityMetadata.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.

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 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 location as part of the ConnectivityMetadata.cf_role in the list of objects to be matched for potential removal.

  • contains_edge (bool):

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

  • contains_face (bool):

    Contains the face location as part of the ConnectivityMetadata.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.

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

Args:

  • location (str)

    The location argument for MeshCoord instantiation.

Returns

tuple of MeshCoord’s 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.

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

Valid mesh locations.

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 ↑

Mesh1DConnectivities(edge_node,)

class iris.experimental.ugrid.Mesh1DConnectivities(_cls, edge_node)

Namedtuple for 1D mesh Connectivity instances.

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

edge_node

Alias for field number 0

↑ top ↑

Mesh1DCoords(node_x, node_y, edge_x, edge_y)

class iris.experimental.ugrid.Mesh1DCoords(_cls, node_x, node_y, edge_x, edge_y)

Namedtuple for 1D mesh AuxCoord coordinates.

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

edge_x

Alias for field number 2

edge_y

Alias for field number 3

node_x

Alias for field number 0

node_y

Alias for field number 1

↑ top ↑

Mesh1DNames(node_dimension, edge_dimension)

class iris.experimental.ugrid.Mesh1DNames(_cls, node_dimension, edge_dimension)

Namedtuple for 1D mesh topology NetCDF variable dimension names.

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

edge_dimension

Alias for field number 1

node_dimension

Alias for field number 0

↑ top ↑

Mesh2DConnectivities(face_node, edge_node, face_edge, face_face, edge_face, boundary_node)

class iris.experimental.ugrid.Mesh2DConnectivities(_cls, face_node, edge_node, face_edge, face_face, edge_face, boundary_node)

Namedtuple for 2D mesh Connectivity instances.

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

boundary_node

Alias for field number 5

edge_face

Alias for field number 4

edge_node

Alias for field number 1

face_edge

Alias for field number 2

face_face

Alias for field number 3

face_node

Alias for field number 0

↑ top ↑

Mesh2DCoords(node_x, node_y, edge_x, edge_y, face_x, face_y)

class iris.experimental.ugrid.Mesh2DCoords(_cls, node_x, node_y, edge_x, edge_y, face_x, face_y)

Namedtuple for 2D mesh AuxCoord coordinates.

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

edge_x

Alias for field number 2

edge_y

Alias for field number 3

face_x

Alias for field number 4

face_y

Alias for field number 5

node_x

Alias for field number 0

node_y

Alias for field number 1

↑ top ↑

Mesh2DNames(node_dimension, edge_dimension, face_dimension)

class iris.experimental.ugrid.Mesh2DNames(_cls, node_dimension, edge_dimension, face_dimension)

Namedtuple for 2D mesh topology NetCDF variable dimension names.

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

edge_dimension

Alias for field number 1

face_dimension

Alias for field number 2

node_dimension

Alias for field number 0

↑ top ↑

MeshEdgeCoords(edge_x, edge_y)

class iris.experimental.ugrid.MeshEdgeCoords(_cls, edge_x, edge_y)

Namedtuple for edge AuxCoord coordinates.

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

edge_x

Alias for field number 0

edge_y

Alias for field number 1

↑ top ↑

MeshFaceCoords(face_x, face_y)

class iris.experimental.ugrid.MeshFaceCoords(_cls, face_x, face_y)

Namedtuple for face AuxCoord coordinates.

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

face_x

Alias for field number 0

face_y

Alias for field number 1

↑ top ↑

MeshNodeCoords(node_x, node_y)

class iris.experimental.ugrid.MeshNodeCoords(_cls, node_x, node_y)

Namedtuple for node AuxCoord coordinates.

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

node_x

Alias for field number 0

node_y

Alias for field number 1

↑ top ↑

Metadata container for a Mesh.

class iris.experimental.ugrid.MeshMetadata(_cls, standard_name, long_name, var_name, units, attributes, topology_dimension, node_dimension, edge_dimension, face_dimension)[source]

Create new instance of MeshMetadataNamedtuple(standard_name, long_name, var_name, units, attributes, topology_dimension, node_dimension, edge_dimension, face_dimension)

combine(other, lenient=None)[source]

Return a new metadata instance created by combining each of the associated metadata members.

Args:

  • other (metadata):

    A metadata instance of the same type.

Kwargs:

  • lenient (boolean):

    Enable/disable lenient combination. The default is to automatically detect whether this lenient operation is enabled.

Returns

Metadata instance.

count(value, /)

Return number of occurrences of value.

difference(other, lenient=None)[source]

Return a new metadata instance created by performing a difference comparison between each of the associated metadata members.

A metadata member returned with a value of “None” indicates that there is no difference between the members being compared. Otherwise, a tuple of the different values is returned.

Args:

  • other (metadata):

    A metadata instance of the same type.

Kwargs:

  • lenient (boolean):

    Enable/disable lenient difference. The default is to automatically detect whether this lenient operation is enabled.

Returns

Metadata instance of member differences or None.

equal(other, lenient=None)[source]

Determine whether the associated metadata members are equivalent.

Args:

  • other (metadata):

    A metadata instance of the same type.

Kwargs:

  • lenient (boolean):

    Enable/disable lenient equivalence. The default is to automatically detect whether this lenient operation is enabled.

Returns

Boolean.

classmethod from_metadata(other)

Convert the provided metadata instance from a different type to this metadata type, using only the relevant metadata members.

Non-common metadata members are set to None.

Args:

  • other (metadata):

    A metadata instance of any type.

Returns

New metadata instance.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

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.

classmethod token(name)

Determine whether the provided name is a valid NetCDF name and thus safe to represent a single parsable token.

Args:

  • name:

    The string name to verify

Returns

The provided name if valid, otherwise None.

DEFAULT_NAME = 'unknown'
attributes

Alias for field number 4

edge_dimension

Alias for field number 7

face_dimension

Alias for field number 8

long_name

Alias for field number 1

node_dimension

Alias for field number 6

standard_name

Alias for field number 0

topology_dimension

Alias for field number 5

units

Alias for field number 3

var_name

Alias for field number 2

↑ top ↑

Geographic coordinate values of data on an unstructured mesh.

A MeshCoord references a ~iris.experimental.ugrid.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. 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.

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 ↑

Metadata container for a MeshCoord.

class iris.experimental.ugrid.MeshCoordMetadata(_cls, standard_name, long_name, var_name, units, attributes, location, axis)[source]

Create new instance of MeshCoordMetadataNamedtuple(standard_name, long_name, var_name, units, attributes, location, axis)

combine(other, lenient=None)[source]

Return a new metadata instance created by combining each of the associated metadata members.

Args:

  • other (metadata):

    A metadata instance of the same type.

Kwargs:

  • lenient (boolean):

    Enable/disable lenient combination. The default is to automatically detect whether this lenient operation is enabled.

Returns

Metadata instance.

count(value, /)

Return number of occurrences of value.

difference(other, lenient=None)[source]

Return a new metadata instance created by performing a difference comparison between each of the associated metadata members.

A metadata member returned with a value of “None” indicates that there is no difference between the members being compared. Otherwise, a tuple of the different values is returned.

Args:

  • other (metadata):

    A metadata instance of the same type.

Kwargs:

  • lenient (boolean):

    Enable/disable lenient difference. The default is to automatically detect whether this lenient operation is enabled.

Returns

Metadata instance of member differences or None.

equal(other, lenient=None)[source]

Determine whether the associated metadata members are equivalent.

Args:

  • other (metadata):

    A metadata instance of the same type.

Kwargs:

  • lenient (boolean):

    Enable/disable lenient equivalence. The default is to automatically detect whether this lenient operation is enabled.

Returns

Boolean.

classmethod from_metadata(other)

Convert the provided metadata instance from a different type to this metadata type, using only the relevant metadata members.

Non-common metadata members are set to None.

Args:

  • other (metadata):

    A metadata instance of any type.

Returns

New metadata instance.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

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.

classmethod token(name)

Determine whether the provided name is a valid NetCDF name and thus safe to represent a single parsable token.

Args:

  • name:

    The string name to verify

Returns

The provided name if valid, otherwise None.

DEFAULT_NAME = 'unknown'
attributes

Alias for field number 4

axis

Alias for field number 6

location

Alias for field number 5

long_name

Alias for field number 1

standard_name

Alias for field number 0

units

Alias for field number 3

var_name

Alias for field number 2

↑ top ↑

Thread-local data

class iris.experimental.ugrid.ParseUGridOnLoad[source]

A flag for dictating whether to use the experimental UGRID-aware version of Iris NetCDF loading. Object is thread-safe.

Use via the run-time switch PARSE_UGRID_ON_LOAD. Use context() to temporarily activate.

See also

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

context()[source]

Temporarily activate experimental UGRID-aware NetCDF loading.

Use the standard Iris loading API while within the context manager. If the loaded file(s) include any UGRID content, this will be parsed and attached to the resultant cube(s) accordingly.

Use via the run-time switch PARSE_UGRID_ON_LOAD.

For example:

with PARSE_UGRID_ON_LOAD.context():
    my_cube_list = iris.load([my_file_path, my_file_path2],
                             constraint=my_constraint,
                             callback=my_callback)

↑ top ↑

iris.experimental.ugrid.PARSE_UGRID_ON_LOAD

Run-time switch for experimental UGRID-aware NetCDF loading. See ParseUGridOnLoad.