iris.mesh#

Infra-structure for unstructured mesh support.

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

class iris.mesh.Connectivity(indices, cf_role, standard_name=None, long_name=None, var_name=None, units=None, attributes=None, start_index=0, location_axis=0)[source]#

Bases: _DimensionalMetadata

CF-UGRID topology.

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

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

Construct a single connectivity.

Parameters:

indices (numpy.ndarray or numpy.ma.core.MaskedArray or dask.array.Array) – 2D array giving the topological connection relationship between location elements and connected elements. The location_axis dimension indexes over the location dimension of the mesh - i.e. its length matches the total number of location elements in the mesh. The connected_axis dimension can be any length, corresponding to the highest number of connected elements connected to a location element. The array values are indices into the connected dimension of the mesh. If the number of connected elements varies between location elements: use a numpy.ma.core.MaskedArray and mask the location elements’ unused index ‘slots’. Use a dask.array.Array to keep indices ‘lazy’.
cf_role (str) – Denotes the topological relationship that this connectivity describes. Made up of this array’s location, and the connected element type that is indexed by the array. See UGRID_CF_ROLES for valid arguments.
standard_name (str, optional) – CF standard name of the connectivity. (NOTE: this is not expected by the UGRID conventions, but will be handled in Iris’ standard way if provided).
long_name (str, optional) – Descriptive name of the connectivity.
var_name (str, optional) – The NetCDF variable name for the connectivity.
units (cf_units.Unit, optional) – The Unit of the connectivity’s values. Can be a string, which will be converted to a Unit object. (NOTE: this is not expected by the UGRID conventions, but will be handled in Iris’ standard way if provided).
attributes (dict, optional) – A dictionary containing other cf and user-defined attributes.
start_index (int, optional) – Either 0 or 1. Default is 0. Denotes whether indices uses 0-based or 1-based indexing (allows support for Fortran and legacy NetCDF files).
location_axis (int, optional) – Either 0 or 1. Default is 0. Denotes which axis of indices varies over the location elements (the alternate axis therefore varying over connected elements). (This parameter allows support for fastest varying index being either first or last). E.g. for face_node_connectivity, for 10 faces: indices.shape[location_axis] == 10.

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

__binary_operator__(other, mode_constant)#

Perform 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)#: Return 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.

property attributes: LimitedAttributeDict#

property cf_role#

The category of topological relationship that this connectivity describes.

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

property connected#

Derived from the connectivity’s cf_role.

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

property connected_axis#

Derived as the alternate value of location_axis.

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

convert_units(unit)#: Change the units, converting the values of the metadata.

copy(values=None)#

Return a copy of this dimensional metadata object.

Parameters:: values (optional) – 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]#

Return the indices array at the core of this connectivity.

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

Return type:: numpy.ndarray or numpy.ma.core.MaskedArray or dask.array.Array

cube_dims(cube)[source]#: Not available on Connectivity.

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

has_bounds()#: Indicate whether the current dimensional metadata object has a bounds array.

has_lazy_indices()[source]#

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

Return type:: bool

property indices#

The index values describing the topological relationship of the connectivity.

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

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

indices_by_location(indices=None)[source]#

Return a view of the indices array.

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

Parameters:: indices (array, optional) – The array on which to operate. If None, will operate on indices. Default is None.
Returns:: A view of the indices array Transposed - if necessary - to put location_axis first.
Return type:: result

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.

Return type:: A lazy array, representing the connectivity indices array.

lazy_location_lengths()[source]#

Return a lazy array representing the number of connected elements.

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

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

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

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

property location#

Derived from the connectivity’s cf_role.

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

property location_axis#

The axis of the connectivity’s indices array.

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

location_lengths()[source]#

Return a NumPy array representing the number of connected elements.

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

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

property long_name: str | None#: The CF Metadata long name for the object.

property metadata#

name(default=None, token=False)#

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

Parameters:

default (str | None) – The fall-back string representing the default name. Defaults to the string ‘unknown’.
token (bool) – 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.

Return type:

str

property ndim#: Return the number of dimensions of the current dimensional metadata object.

rename(name)#

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

Parameters:: name (str | None)
Return type:: None

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

property standard_name: str | None#: 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.

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) – 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) – Character-width controlling line splitting of array outputs. If unset, defaults to numpy.get_printoptions['linewidth'].
edgeitems (int, default=2) – Controls truncated array output. Overrides numpy.getprintoptions['edgeitems'].
precision (int or None) – 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:

Output text, with embedded newlines when shorten=False.

Return type:

str

Notes

Note

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

transpose()[source]#

Transpose Connectivity.

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

Returns:: A new Connectivity that is the transposed equivalent of the original.
Return type:: Connectivity

property units: Unit#: The S.I. unit of the object.

validate_indices()[source]#

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

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

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

Note

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

property var_name: str | None#: The NetCDF variable name for the object.

xml_element(doc)[source]#

Create XML element.

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

Parameters:: doc – The parent xml.dom.minidom.Document.
Returns:: xml.dom.minidom.Element that will describe this _DimensionalMetadata.
Return type:: xml.dom.minidom.Element

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

Bases: AuxCoord

Geographic coordinate values of data on an unstructured mesh.

A MeshCoord references a ~iris.mesh.mesh.MeshXY. 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 MeshXY, 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 MeshXY contains them (optional). For ‘face’, the .bounds contain the face corners, and the .points contain the face locations (typically centres), if the MeshXY contains them (optional).

Note

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

Note

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

Create a coordinate with mutable points and bounds.

Parameters:

points – The values (or value in the case of a scalar coordinate) for each cell of the coordinate.
standard_name (optional) – CF standard name of the coordinate.
long_name (optional) – Descriptive name of the coordinate.
var_name (optional) – The netCDF variable name for the coordinate.
unit (Unit, optional) – The Unit of the coordinate’s values. Can be a string, which will be converted to a Unit object.
bounds (optional) – An array of values describing the bounds of each cell. Given n bounds for each cell, the shape of the bounds array should be points.shape + (n,). For example, a 1D coordinate with 100 points and two bounds per cell would have a bounds array of shape (100, 2) Note if the data is a climatology, climatological should be set.
attributes (optional) – A dictionary containing other CF and user-defined attributes.
coord_system (CoordSystem, optional) – A CoordSystem representing the coordinate system of the coordinate, e.g., a GeogCS for a longitude coordinate.
bool (climatological) – When True: the coordinate is a NetCDF climatological time axis. When True: saving in NetCDF will give the coordinate variable a ‘climatology’ attribute and will create a boundary variable called ‘<coordinate-name>_climatology’ in place of a standard bounds attribute and bounds variable. Will set to True when a climatological time axis is loaded from NetCDF. Always False if no bounds exist.
optional – When True: the coordinate is a NetCDF climatological time axis. When True: saving in NetCDF will give the coordinate variable a ‘climatology’ attribute and will create a boundary variable called ‘<coordinate-name>_climatology’ in place of a standard bounds attribute and bounds variable. Will set to True when a climatological time axis is loaded from NetCDF. Always False if no bounds exist.
mesh (MeshXY)
location (Literal['edge', 'node', 'face'])
axis (Literal['x', 'y'])

__binary_operator__(other, mode_constant)#

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

Returns a new MeshCoord based on the same MeshXY.

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

property attributes: LimitedAttributeDict#

property axis#

property bounds#

Coordinate bounds values.

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

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

cell(index)#

Point/bound cell at the given coordinate index.

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

cells()#

Return an iterable of Cell instances for this Coord.

For example:

for cell in self.cells():
   ...

property climatological#: The ‘climatological’ of a MeshCoord is always ‘False’.

collapsed(dims_to_collapse=None)[source]#

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

Replaces the points & bounds with a simple bounded region.

The coordinate that is collapsed is a AuxCoord copy of this MeshCoord, since a MeshCoord does not have its own points/bounds - they are derived from the associated MeshXY. See iris.coords.AuxCoord.collapsed().

contiguous_bounds()#

Contiguous bounds of 1D coordinate.

Return 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\).

Full list of supported units can be found in the UDUNITS-2 documentation https://docs.unidata.ucar.edu/udunits/current/#Database

property coord_system#

The coordinate-system of a MeshCoord.

It comes from the related location coordinate in the mesh.

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

Make a copy of the MeshCoord.

Parameters:

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

core_bounds()#: Core bounds. The points array at the core of this coord, which may be a NumPy array or a dask array.

core_points()#: Core 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)”.

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

classmethod from_coord(coord)#: Create a new Coord of this type, from the given coordinate.

guess_bounds(bound_position=0.5, monthly=False, yearly=False)#

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.

Parameters:

bound_position (float, default=0.5) – The desired position of the bounds relative to the position of the points.
monthly (bool, default=False) – If True, the coordinate must be monthly and bounds are set to the start and ends of each month.
yearly (bool, default=False) – If True, the coordinate must be yearly and bounds are set to the start and ends of each year.

Notes

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.

Note

Monthly and Yearly work differently from the standard case. They can work for single points but cannot be used together.

has_bounds()#: Return a boolean indicating whether the coord has a bounds array.

has_lazy_bounds()#

Whether coordinate bounds are lazy.

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

has_lazy_points()#: Return a boolean whether the coord’s points array is a lazy dask array or not.

property ignore_axis#

A boolean controlling if iris.util.guess_coord_axis acts on this coordinate.

Defaults to False, and when set to True it will be skipped by iris.util.guess_coord_axis().

intersect(other, return_indices=False)#

Return a new coordinate from the intersection of two coordinates.

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

Parameters:: return_indices (bool, default=False) – 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.

Parameters:

other – An instance of iris.coords.Coord, iris.common.CoordMetadata or iris.common.DimCoordMetadata.
ignore (optional) – 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.

Return type:

bool

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

Whether coordinate has contiguous bounds.

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.

Parameters:

rtol (float, default=1e-05) – The relative tolerance parameter (default is 1e-05).
atol (float, default=1e-08) – The absolute tolerance parameter (default is 1e-08).

Return type:

bool

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.
Return type:: lazy array

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.

Return type:: A lazy array, representing the coord points array.

property location: Literal['edge', 'node', 'face']#

property long_name: str | None#: The CF Metadata long name for the object.

property mesh#

property metadata#

name(default=None, token=False)#

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

Parameters:

default (str | None) – The fall-back string representing the default name. Defaults to the string ‘unknown’.
token (bool) – 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.

Return type:

str

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.

nearest_neighbour_index(point)#

Return 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)
np.int64(9)
>>> cube.coord('longitude').nearest_neighbour_index(10)
np.int64(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.

property points#: The coordinate points values as a NumPy array.

rename(name)#

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

Parameters:: name (str | None)
Return type:: None

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

property standard_name: str | None#: The CF Metadata standard name for the object.

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) – 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) – Character-width controlling line splitting of array outputs. If unset, defaults to numpy.get_printoptions['linewidth'].
edgeitems (int, default=2) – Controls truncated array output. Overrides numpy.getprintoptions['edgeitems'].
precision (int or None) – 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:

Output text, with embedded newlines when shorten=False.

Return type:

str

Notes

Note

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

property units: Unit#: The S.I. unit of the object.

property var_name: str | None#: The NetCDF variable name for the object.

xml_element(doc)#

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

Parameters:: doc – The parent xml.dom.minidom.Document.
Returns:: The xml.dom.minidom.Element that will describe this DimCoord.
Return type:: xml.dom.minidom.Element

class iris.mesh.MeshXY(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]#

Bases: Mesh

A container representing the UGRID cf_role mesh_topology.

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

Based on the assumption of 2 node_coords - one associated with the X-axis (e.g. longitude) and 1 with the Y-axis (e.g. latitude). UGRID describing alternative node coordinates (e.g. spherical) cannot be represented.

Notes

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

References

MeshXY initialise.

Note

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

AXES = ('x', 'y')#: The supported mesh axes.

ELEMENTS = ('edge', 'node', 'face')#: Valid mesh elements.

TOPOLOGY_DIMENSIONS = (1, 2)#: Valid range of values for topology_dimension.

add_connectivities(*connectivities)[source]#

Add one or more Connectivity instances to the MeshXY.

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

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

Parameters:

node_x (optional) – The x-axis like node AuxCoord.
node_y (optional) – The y-axis like node AuxCoord.
edge_x (optional) – The x-axis like edge AuxCoord.
edge_y (optional) – The y-axis like edge AuxCoord.
face_x (optional) – The x-axis like face AuxCoord.
face_y (optional) – The y-axis like face AuxCoord.

property all_connectivities#: All the Connectivity instances of the MeshXY.

property all_coords#: All the AuxCoord coordinates of the MeshXY.

property attributes: LimitedAttributeDict#

property boundary_node_connectivity#

The optional UGRID boundary_node_connectivity Connectivity.

The optional UGRID boundary_node_connectivity Connectivity of the MeshXY.

property cf_role#: The UGRID cf_role attribute of the MeshXY.

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

Return all Connectivity instances from the MeshXY which match the provided criteria.

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

See also

MeshXY.connectivity() for matching exactly one connectivity.

Parameters:

item (str or object) –
Either,
- a standard_name, long_name, or var_name which is compared against the name().
- a connectivity or metadata instance equal to that of the desired objects e.g., Connectivity or ConnectivityMetadata.
standard_name (str, optional) – The CF standard name of the desired Connectivity. If None, does not check for standard_name.
long_name (str, optional) – An unconstrained description of the Connectivity. If None, does not check for long_name.
var_name (str, optional) – The NetCDF variable name of the desired Connectivity. If None, does not check for var_name.
attributes (dict, optional) – A dictionary of attributes desired on the Connectivity. If None, does not check for attributes.
cf_role (str, optional) – The UGRID cf_role of the desired Connectivity.
contains_node (bool, optional) – Contains the node element as part of the cf_role in the list of objects to be matched.
contains_edge (bool, optional) – Contains the edge element as part of the cf_role in the list of objects to be matched.
contains_face (bool, optional) – Contains the face element as part of the cf_role in the list of objects to be matched.

Returns:

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

Return type:

list of Connectivity

connectivity(item=None, standard_name=None, long_name=None, var_name=None, attributes=None, cf_role=None, contains_node=None, contains_edge=None, contains_face=None)[source]#

Return a single Connectivity.

Return a single Connectivity from the MeshXY 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

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

Parameters:

item (str or object) –
Either,
- a standard_name, long_name, or var_name which is compared against the name().
- a connectivity or metadata instance equal to that of the desired object e.g., Connectivity or ConnectivityMetadata.
standard_name (str, optional) – The CF standard name of the desired Connectivity. If None, does not check for standard_name.
long_name (str, optional) – An unconstrained description of the Connectivity. If None, does not check for long_name.
var_name (str, optional) – The NetCDF variable name of the desired Connectivity. If None, does not check for var_name.
attributes (dict, optional) – A dictionary of attributes desired on the Connectivity. If None, does not check for attributes.
cf_role (str, optional) – The UGRID cf_role of the desired Connectivity.
contains_node (bool, optional) – Contains the node element as part of the cf_role in the list of objects to be matched.
contains_edge (bool, optional) – Contains the edge element as part of the cf_role in the list of objects to be matched.
contains_face (bool, optional) – Contains the face element as part of the cf_role in the list of objects to be matched.

Returns:

The Connectivity from the MeshXY that matched the given criteria.

Return type:

Connectivity

coord(item=None, standard_name=None, long_name=None, var_name=None, attributes=None, axis=None, location=None)[source]#

Return a single AuxCoord coordinate.

Return a single AuxCoord coordinate from the MeshXY 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

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

Parameters:

item (str or object, optional) –
Either,
- a standard_name, long_name, or var_name which is compared against the name().
- a coordinate or metadata instance equal to that of the desired coordinate e.g., AuxCoord or CoordMetadata.
standard_name (str, optional) – The CF standard name of the desired coordinate. If None, does not check for standard_name.
long_name (str, optional) – An unconstrained description of the coordinate. If None, does not check for long_name.
var_name (str, optional) – The NetCDF variable name of the desired coordinate. If None, does not check for var_name.
attributes (dict, optional) – A dictionary of attributes desired on the coordinates. If None, does not check for attributes.
axis (str, optional) – 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).
location (str, optional) – The desired location. Accepts the values node, edge or face.

Returns:

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

Return type:

AuxCoord

coords(item=None, standard_name=None, long_name=None, var_name=None, attributes=None, axis=None, location=None)[source]#

Return all AuxCoord coordinates from the MeshXY.

Return all AuxCoord coordinates from the MeshXY which match the provided criteria.

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

See also

MeshXY.coord() for matching exactly one coordinate.

Parameters:

item (str or object, optional) –
Either,
- a standard_name, long_name, or var_name which is compared against the name().
- a coordinate or metadata instance equal to that of the desired coordinates e.g., AuxCoord or CoordMetadata.
standard_name (str, optional) – The CF standard name of the desired coordinate. If None, does not check for standard_name.
long_name (str, optional) – An unconstrained description of the coordinate. If None, does not check for long_name.
var_name (str, optional) – The NetCDF variable name of the desired coordinate. If None, does not check for var_name.
attributes (dict, optional) – A dictionary of attributes desired on the coordinates. If None, does not check for attributes.
axis (str, optional) – 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).
location (str, optional) – The desired location. Accepts the values node, edge or face.

Returns:

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

Return type:

list of AuxCoord

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

Assign the name to be used for the NetCDF variable.

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

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

Parameters:

node (str, optional) – The name to be used for the NetCDF variable representing the node dimension.
edge (str, optional) – The name to be used for the NetCDF variable representing the edge dimension.
face (str, optional) – 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.

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

Parameters:

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

property edge_coords#: The optional UGRID edge AuxCoord coordinates of the MeshXY.

property edge_dimension#: The optionally required UGRID NetCDF variable name for the edge dimension.

property edge_face_connectivity#

The optional UGRID edge_face_connectivity Connectivity.

The optional UGRID edge_face_connectivity Connectivity of the MeshXY.

property edge_node_connectivity#

The UGRID edge_node_connectivity Connectivity.

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

property face_coords#: The optional UGRID face AuxCoord coordinates of the MeshXY.

property face_dimension#: The optional UGRID NetCDF variable name for the face dimension.

property face_edge_connectivity#

The optional UGRID face_edge_connectivityConnectivity.

The optional UGRID face_edge_connectivity Connectivity of the MeshXY.

property face_face_connectivity#

The optional UGRID face_face_connectivity Connectivity.

The optional UGRID face_face_connectivity Connectivity of the MeshXY.

property face_node_connectivity#

Return face_node_connectivityConnectivity.

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

classmethod from_coords(*coords)[source]#

Construct a MeshXY by derivation from 1/more Coord.

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

None or (n, <2):
Not supported
(n, 2):
topology_dimension = 1. node_coords and edge_node_connectivity constructed from bounds. edge_coords constructed from points.
(n, >=3):
topology_dimension = 2. node_coords and face_node_connectivity constructed from bounds. face_coords constructed from points.

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

Notes

Note

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

Note

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

Examples

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

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

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

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

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

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

property long_name: str | None#: The CF Metadata long name for the object.

property metadata#

name(default=None, token=False)#

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

Parameters:

default (str | None) – The fall-back string representing the default name. Defaults to the string ‘unknown’.
token (bool) – 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.

Return type:

str

property node_coords#: The required UGRID node AuxCoord coordinates of the MeshXY.

property node_dimension#: The NetCDF variable name for the node dimension.

remove_connectivities(item=None, standard_name=None, long_name=None, var_name=None, attributes=None, cf_role=None, contains_node=None, contains_edge=None, contains_face=None)[source]#

Remove one or more Connectivity.

Remove one or more Connectivity from the MeshXY which match the provided criteria.

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

Parameters:

item (str or object, optional) –
Either,
- a standard_name, long_name, or var_name which is compared against the name().
- a connectivity or metadata instance equal to that of the desired objects e.g., Connectivity or ConnectivityMetadata.
standard_name (str, optional) – The CF standard name of the desired Connectivity. If None, does not check for standard_name.
long_name (str, optional) – An unconstrained description of the Connectivity. If None, does not check for long_name.
var_name (str, optional) – The NetCDF variable name of the desired Connectivity. If None, does not check for var_name.
attributes (dict, optional) – A dictionary of attributes desired on the Connectivity. If None, does not check for attributes.
cf_role (str, optional) – The UGRID cf_role of the desired Connectivity.
contains_node (bool, optional) – Contains the node element as part of the cf_role in the list of objects to be matched for potential removal.
contains_edge (bool, optional) – Contains the edge element as part of the cf_role in the list of objects to be matched for potential removal.
contains_face (bool, optional) – Contains the face element as part of the cf_role in the list of objects to be matched for potential removal.

Returns:

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

Return type:

list of Connectivity

remove_coords(item=None, standard_name=None, long_name=None, var_name=None, attributes=None, axis=None, location=None)[source]#

Remove one or more AuxCoord from the MeshXY.

Remove one or more AuxCoord from the MeshXY which match the provided criteria.

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

Parameters:

item (str or object, optional) –
Either,
- a standard_name, long_name, or var_name which is compared against the name().
- a coordinate or metadata instance equal to that of the desired coordinates e.g., AuxCoord or CoordMetadata.
standard_name (str, optional) – The CF standard name of the desired coordinate. If None, does not check for standard_name.
long_name (str, optional) – An unconstrained description of the coordinate. If None, does not check for long_name.
var_name (str, optional) – The NetCDF variable name of the desired coordinate. If None, does not check for var_name.
attributes (dict, optional) – A dictionary of attributes desired on the coordinates. If None, does not check for attributes.
axis (str, optional) – 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).
location (str, optional) – The desired location. Accepts the values node, edge or face.

Returns:

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

Return type:

list of AuxCoord

rename(name)#

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

Parameters:: name (str | None)
Return type:: None

property standard_name: str | None#: The CF Metadata standard name for the object.

summary(shorten=False)[source]#

Return a string representation of the MeshXY.

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

to_MeshCoord(location, axis)[source]#

Generate a MeshCoord.

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

See also

to_MeshCoords() for generating a series of mesh coords.

Parameters:

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

Returns:

A MeshCoord referencing the current MeshXY.

Return type:

MeshCoord

to_MeshCoords(location)[source]#

Generate a tuple of MeshCoord.

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

See also

to_MeshCoord() for generating a single mesh coord.

Parameters:: location (str) – The location argument for MeshCoord instantiation.
Returns:: Tuple of MeshCoord referencing the current MeshXY. One for each value in AXES, using the value for the axis argument.
Return type:: tuple of MeshCoord

property topology_dimension#

UGRID topology_dimension attribute.

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

property units: Unit#: The S.I. unit of the object.

property var_name: str | None#: The NetCDF variable name for the object.

xml_element(doc)[source]#

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

Parameters:: doc (object) – The parent xml.dom.minidom.Document.
Returns:: The xml.dom.minidom.Element that will describe this MeshXY, and the dictionary of attributes that require to be added to this element.
Return type:: xml.dom.minidom.Element

iris.mesh.load_mesh(uris, var_name=None)[source]#

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

Raises an error if more/less than one MeshXY 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 MeshXY if its var_name matches this value.

Return type:

iris.mesh.MeshXY

iris.mesh.load_meshes(uris, var_name=None)[source]#

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

Return type:

dict

iris.mesh.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 MeshXY.
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 (str) – Coord name of an index coord containing the mesh location indices, in every submesh cube.

Returns:

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

Return type:

result_cube

Notes

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

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

The result_cube dtype is that of the submesh_cubes.

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

Save mesh(es) to a netCDF file.

Parameters:

mesh (iris.mesh.MeshXY or iterable) – Mesh(es) to save.
filename (str) – Name of the netCDF file to create.
netcdf_format (str, default="NETCDF4") – Underlying netCDF file format, one of ‘NETCDF4’, ‘NETCDF4_CLASSIC’, ‘NETCDF3_CLASSIC’ or ‘NETCDF3_64BIT’. Default is ‘NETCDF4’ format.

iris.mesh#

Submodules#

This Page