Merge pull request #4296 from trexfeathers/mesh-data-model_update

`mesh-data-model` update

.cirrus.yml

@@ -38,7 +38,7 @@ env:
  # Conda packages to be installed.
  CONDA_CACHE_PACKAGES: "nox pip"
  # Git commit hash for iris test data.
- IRIS_TEST_DATA_VERSION: "2.0.0"
+ IRIS_TEST_DATA_VERSION: "2.4"
  # Base directory for the iris-test-data.
  IRIS_TEST_DATA_DIR: ${HOME}/iris-test-data
 

MANIFEST.in

@@ -4,6 +4,7 @@ include CHANGES COPYING COPYING.LESSER
 # Files from setup.py package_data that are not automatically added to source distributions
 recursive-include lib/iris/tests/results *.cml *.cdl *.txt *.xml *.json
 recursive-include lib/iris/etc *
+include lib/iris/tests/stock/file_headers/*
 
 recursive-include requirements *
 

docs/src/sphinxext/generate_package_rst.py

@@ -13,7 +13,7 @@
 # list of tuples for modules to exclude. Useful if the documentation throws
 # warnings, especially for experimental modules.
 exclude_modules = [
- ("experimental/raster", "iris.experimental.raster") # gdal conflicts
+ ("experimental/raster", "iris.experimental.raster"), # gdal conflicts
 ]
 
 

docs/src/whatsnew/latest.rst

@@ -16,7 +16,8 @@ This document explains the changes made to Iris for this release
 
  The highlights for this minor release of Iris include:
 
- * N/A
+ * We've added support for `UGRID`_ meshes which can now be loaded and attached
+ to a cube.
 
  And finally, get in touch with us on `GitHub`_ if you have any issues or
  feature requests for improving Iris. Enjoy!
@@ -31,7 +32,25 @@ This document explains the changes made to Iris for this release
 ✨ Features
 ===========
 
-#. N/A
+#. `@bjlittle`_, `@pp-mo`_ and `@trexfeathers`_ added support for unstructured
+ meshes, as described by `UGRID`_. This involved adding a data model (:pull:`3968`,
+ :pull:`4014`, :pull:`4027`, :pull:`4036`, :pull:`4053`) and API (:pull:`4063`,
+ :pull:`4064`), and supporting representation (:pull:`4033`, :pull:`4054`) and
+ loading (:pull:`4058`) of data on meshes.
+ Most of this new API can be found in :mod:`iris.experimental.ugrid`. The key
+ objects introduced are :class:`iris.experimental.ugrid.Mesh`,
+ :class:`iris.experimental.ugrid.MeshCoord` and
+ :obj:`iris.experimental.ugrid.PARSE_UGRID_ON_LOAD`.
+ A :class:`iris.experimental.ugrid.Mesh` contains a full description of a UGRID
+ type mesh. :class:`~iris.experimental.ugrid.MeshCoord`\ s are coordinates that
+ reference and represent a :class:`~iris.experimental.ugrid.Mesh` for use
+ on a :class:`~iris.cube.Cube`. :class:`~iris.cube.Cube`\ s are also given the
+ property :attr:`~iris.cube.Cube.mesh` which returns a
+ :class:`~iris.experimental.ugrid.Mesh` if one is attached to the
+ :class:`~iris.cube.Cube` via a :class:`~iris.experimental.ugrid.MeshCoord`.
+ Finally, the context manager :obj:`~iris.experimental.ugrid.PARSE_UGRID_ON_LOAD`
+ provides a way to load UGRID files so that :class:`~iris.cube.Cube`\ s can be
+ returned with a :class:`~iris.experimental.ugrid.Mesh` attached.
 
 
 🐛 Bugs Fixed
@@ -87,3 +106,4 @@ This document explains the changes made to Iris for this release
  Whatsnew resources in alphabetical order:
 
 .. _GitHub: https://github.com/SciTools/iris/issues/new/choose
+.. _UGRID: https://ugrid-conventions.github.io/ugrid-conventions/

lib/iris/common/metadata.py

@@ -26,22 +26,26 @@
 from .lenient import _qualname as qualname
 
 __all__ = [
- "SERVICES_COMBINE",
- "SERVICES_DIFFERENCE",
- "SERVICES_EQUAL",
- "SERVICES",
  "AncillaryVariableMetadata",
  "BaseMetadata",
  "CellMeasureMetadata",
  "CoordMetadata",
  "CubeMetadata",
  "DimCoordMetadata",
  "hexdigest",
+ "metadata_filter",
  "metadata_manager_factory",
+ "SERVICES",
+ "SERVICES_COMBINE",
+ "SERVICES_DIFFERENCE",
+ "SERVICES_EQUAL",
 ]
 
 
 # https://www.unidata.ucar.edu/software/netcdf/docs/netcdf_data_set_components.html#object_name
+
+from ..util import guess_coord_axis
+
 _TOKEN_PARSE = re.compile(r"""^[a-zA-Z0-9][\w\.\+\-@]*$""")
 
 # Configure the logger.
@@ -193,9 +197,19 @@ def func(field):
  return result
 
  # Note that, for strict we use "_fields" not "_members".
- # The "circular" member does not participate in strict equivalence.
+ # TODO: refactor so that 'non-participants' can be held in their specific subclasses.
+ # Certain members never participate in strict equivalence, so
+ # are filtered out.
  fields = filter(
- lambda field: field != "circular", self._fields
+ lambda field: field
+ not in (
+ "circular",
+ "src_dim",
+ "node_dimension",
+ "edge_dimension",
+ "face_dimension",
+ ),
+ self._fields,
  )
  result = all([func(field) for field in fields])
 
@@ -1338,6 +1352,149 @@ def equal(self, other, lenient=None):
  return super().equal(other, lenient=lenient)
 
 
+def metadata_filter(
+ instances,
+ item=None,
+ standard_name=None,
+ long_name=None,
+ var_name=None,
+ attributes=None,
+ axis=None,
+):
+ """
+ Filter a collection of objects by their metadata to fit the given metadata
+ criteria.
+
+ Criteria can be either specific properties or other objects with metadata
+ to be matched.
+
+ Args:
+
+ * instances:
+ One or more objects to be filtered.
+
+ Kwargs:
+
+ * item:
+ Either,
+
+ * a :attr:`~iris.common.mixin.CFVariableMixin.standard_name`,
+ :attr:`~iris.common.mixin.CFVariableMixin.long_name`, or
+ :attr:`~iris.common.mixin.CFVariableMixin.var_name` which is compared
+ against the :meth:`~iris.common.mixin.CFVariableMixin.name`.
+
+ * a coordinate or metadata instance equal to that of
+ the desired objects e.g., :class:`~iris.coords.DimCoord`
+ or :class:`CoordMetadata`.
+
+ * standard_name:
+ The CF standard name of the desired object. If ``None``, does not
+ check for ``standard_name``.
+
+ * long_name:
+ An unconstrained description of the object. If ``None``, does not
+ check for ``long_name``.
+
+ * var_name:
+ The NetCDF variable name of the desired object. If ``None``, does
+ not check for ``var_name``.
+
+ * attributes:
+ A dictionary of attributes desired on the object. If ``None``,
+ does not check for ``attributes``.
+
+ * axis:
+ The desired object's axis, see :func:`~iris.util.guess_coord_axis`.
+ If ``None``, does not check for ``axis``. Accepts the values ``X``,
+ ``Y``, ``Z`` and ``T`` (case-insensitive).
+
+ Returns:
+ A list of the objects supplied in the ``instances`` argument, limited
+ to only those that matched the given criteria.
+
+ """
+ name = None
+ obj = None
+
+ if isinstance(item, str):
+ name = item
+ else:
+ obj = item
+
+ # apply de morgan's law for one less logical operation
+ if not (isinstance(instances, str) or isinstance(instances, Iterable)):
+ instances = [instances]
+
+ result = instances
+
+ if name is not None:
+ result = [instance for instance in result if instance.name() == name]
+
+ if standard_name is not None:
+ result = [
+ instance
+ for instance in result
+ if instance.standard_name == standard_name
+ ]
+
+ if long_name is not None:
+ result = [
+ instance for instance in result if instance.long_name == long_name
+ ]
+
+ if var_name is not None:
+ result = [
+ instance for instance in result if instance.var_name == var_name
+ ]
+
+ if attributes is not None:
+ if not isinstance(attributes, Mapping):
+ msg = (
+ "The attributes keyword was expecting a dictionary "
+ "type, but got a %s instead." % type(attributes)
+ )
+ raise ValueError(msg)
+
+ def attr_filter(instance):
+ return all(
+ k in instance.attributes
+ and hexdigest(instance.attributes[k]) == hexdigest(v)
+ for k, v in attributes.items()
+ )
+
+ result = [instance for instance in result if attr_filter(instance)]
+
+ if axis is not None:
+ axis = axis.upper()
+
+ def get_axis(instance):
+ if hasattr(instance, "axis"):
+ axis = instance.axis.upper()
+ else:
+ axis = guess_coord_axis(instance)
+ return axis
+
+ result = [
+ instance for instance in result if get_axis(instance) == axis
+ ]
+
+ if obj is not None:
+ if hasattr(obj, "__class__") and issubclass(
+ obj.__class__, BaseMetadata
+ ):
+ target_metadata = obj
+ else:
+ target_metadata = obj.metadata
+
+ result = [
+ instance
+ for instance in result
+ if instance.metadata == target_metadata
+ ]
+
+ return result
+
+
 @lru_cache(maxsize=None)
 def _factory_cache(cls):
  def __init__(self, cls, **kwargs):
@@ -1484,29 +1641,31 @@ def metadata_manager_factory(cls, **kwargs):
 
 
 #: Convenience collection of lenient metadata combine services.
-SERVICES_COMBINE = (
+# TODO: change lists back to tuples once CellMeasureMetadata is re-integrated
+# here (currently in experimental.ugrid).
+SERVICES_COMBINE = [
  AncillaryVariableMetadata.combine,
  BaseMetadata.combine,
  CellMeasureMetadata.combine,
  CoordMetadata.combine,
  CubeMetadata.combine,
  DimCoordMetadata.combine,
-)
+]
 
 
 #: Convenience collection of lenient metadata difference services.
-SERVICES_DIFFERENCE = (
+SERVICES_DIFFERENCE = [
  AncillaryVariableMetadata.difference,
  BaseMetadata.difference,
  CellMeasureMetadata.difference,
  CoordMetadata.difference,
  CubeMetadata.difference,
  DimCoordMetadata.difference,
-)
+]
 
 
 #: Convenience collection of lenient metadata equality services.
-SERVICES_EQUAL = (
+SERVICES_EQUAL = [
  AncillaryVariableMetadata.__eq__,
  AncillaryVariableMetadata.equal,
  BaseMetadata.__eq__,
@@ -1519,7 +1678,7 @@ def metadata_manager_factory(cls, **kwargs):
  CubeMetadata.equal,
  DimCoordMetadata.__eq__,
  DimCoordMetadata.equal,
-)
+]
 
 
 #: Convenience collection of lenient metadata services.

lib/iris/coords.py

@@ -18,6 +18,7 @@
 import zlib
 
 import cftime
+import dask.array as da
 import numpy as np
 import numpy.ma as ma
 
@@ -579,8 +580,7 @@ def xml_element(self, doc):
 
  Returns:
  The :class:`xml.dom.minidom.Element` that will describe this
- :class:`_DimensionalMetadata`, and the dictionary of attributes
- that require to be added to this element.
+ :class:`_DimensionalMetadata`.
 
  """
  # Create the XML element as the camelCaseEquivalent of the
@@ -627,6 +627,10 @@ def xml_element(self, doc):
  # otherwise.
  if isinstance(self, Coord):
  values_term = "points"
+ # TODO: replace with isinstance(self, Connectivity) once Connectivity
+ # is re-integrated here (currently in experimental.ugrid).
+ elif hasattr(self, "indices"):
+ values_term = "indices"
  else:
  values_term = "data"
  element.setAttribute(values_term, self._xml_array_repr(self._values))
@@ -1936,7 +1940,6 @@ def collapsed(self, dims_to_collapse=None):
 
  Replaces the points & bounds with a simple bounded region.
  """
- import dask.array as da
 
  # Ensure dims_to_collapse is a tuple to be able to pass
  # through to numpy
@@ -2262,8 +2265,7 @@ def xml_element(self, doc):
 
  Returns:
  The :class:`xml.dom.minidom.Element` that will describe this
- :class:`DimCoord`, and the dictionary of attributes that require
- to be added to this element.
+ :class:`DimCoord`.
 
  """
  # Create the XML element as the camelCaseEquivalent of the