Mesh nonexperimental extra (SciTools#6077)

* Move all iris.experimental.ugrid to iris.ugrid.

Replace experiment.ugrid, including docstrings and imports.

Fix test_ParseUgridOnLoad

Fix ugrid.load.

Remove PARSE_UGRID from t/i/ugrid/test_ugrid_save

Remove PARSE_UGRID from t/u/ff/nc/saver/test_save

Remove PARSE_UGRID from t/i/exp/geovista/(both)

Remove PARSE_UGRID from t/u/tests/stock/test_netcdf

* Fix type of mesh in iris.tests.stock

* Fix Mesh -> MeshXY in experimental.ugrid

* Remove PARSE_UGRID_ON_LOAD and ParseUGridOnLoad, leave in iris.experimental.ugrid only.

missed

* Replace old-style mesh api in benchmarks.

* Move misplaced test + fix obsolete PARSE_UGRID usage.

* Minimal doctest fixes

* Remove obsolete PARSE_UGRID in iris.ugrid

* Move all ugrid.metadata into common.metadata.

Removed obsolete tests.unit.metadata

* Rename iris.ugrid to iris.mesh

fix

Fix iris.mesh import in tests/stock/__init__

* Move all iris.mesh.save into iris.fileformats.netcdf.save

Fix experimental.ugrid import of save_mesh

* Fix docs for iris.ugrid -> iris.mesh

* Rename iris.mesh.mesh as iris.mesh.components

* Tidy imports in experimental.ugrid

* Rebrand so mesh.MeshXY is presented as experimental.ugrid.Mesh.

* Move ugrid loading support code from iris.mesh to iris.netcdf, and its tests likewise

* Fix circular import.

* Move mesh.cf code into fileformats.cf, and tests likewise

Fix imports in cf ugrid tests.

* Reinclude mesh-load functions in iris.mesh; break circular imports

* Small fixes to mesh documentation

* Added whatsnew

* Complete+remove remaining 'TODO's from SciTools#6061

* Odd docstring and comment corrections.

benchmarks/benchmarks/cperf/__init__.py

@@ -14,9 +14,6 @@
 
 from iris import load_cube
 
-# TODO: remove uses of PARSE_UGRID_ON_LOAD once UGRID parsing is core behaviour.
-from iris.experimental.ugrid import PARSE_UGRID_ON_LOAD
-
 from ..generate_data import BENCHMARK_DATA
 from ..generate_data.ugrid import make_cubesphere_testfile
 
@@ -92,5 +89,4 @@ def setup(self, file_type, three_d, three_times):
         self.file_type = file_type
 
     def load(self):
-        with PARSE_UGRID_ON_LOAD.context():
-            return load_cube(str(self.file_path))
+        return load_cube(str(self.file_path))

benchmarks/benchmarks/generate_data/stock.py

@@ -14,7 +14,7 @@
 
 import iris
 from iris import cube
-from iris.experimental.ugrid import PARSE_UGRID_ON_LOAD, load_mesh
+from iris.mesh import load_mesh
 
 from . import BENCHMARK_DATA, REUSE_DATA, load_realised, run_function_elsewhere
 
@@ -90,7 +90,7 @@ def sample_mesh(n_nodes=None, n_faces=None, n_edges=None, lazy_values=False):
     """Sample mesh wrapper for :meth:iris.tests.stock.mesh.sample_mesh`."""
 
     def _external(*args, **kwargs):
-        from iris.experimental.ugrid import save_mesh
+        from iris.mesh import save_mesh
         from iris.tests.stock.mesh import sample_mesh
 
         save_path_ = kwargs.pop("save_path")
@@ -104,21 +104,20 @@ def _external(*args, **kwargs):
     save_path = (BENCHMARK_DATA / f"sample_mesh_{args_hash}").with_suffix(".nc")
     if not REUSE_DATA or not save_path.is_file():
         _ = run_function_elsewhere(_external, *arg_list, save_path=str(save_path))
-    with PARSE_UGRID_ON_LOAD.context():
-        if not lazy_values:
-            # Realise everything.
-            with load_realised():
-                mesh = load_mesh(str(save_path))
-        else:
+    if not lazy_values:
+        # Realise everything.
+        with load_realised():
             mesh = load_mesh(str(save_path))
+    else:
+        mesh = load_mesh(str(save_path))
     return mesh
 
 
 def sample_meshcoord(sample_mesh_kwargs=None, location="face", axis="x"):
     """Sample meshcoord wrapper for :meth:`iris.tests.stock.mesh.sample_meshcoord`.
 
     Parameters deviate from the original as cannot pass a
-    :class:`iris.experimental.ugrid.Mesh to the separate Python instance - must
+    :class:`iris.mesh.Mesh to the separate Python instance - must
     instead generate the Mesh as well.
 
     MeshCoords cannot be saved to file, so the _external method saves the
@@ -127,7 +126,7 @@ def sample_meshcoord(sample_mesh_kwargs=None, location="face", axis="x"):
     """
 
     def _external(sample_mesh_kwargs_, save_path_):
-        from iris.experimental.ugrid import save_mesh
+        from iris.mesh import save_mesh
         from iris.tests.stock.mesh import sample_mesh, sample_meshcoord
 
         if sample_mesh_kwargs_:
@@ -147,9 +146,8 @@ def _external(sample_mesh_kwargs_, save_path_):
             sample_mesh_kwargs_=sample_mesh_kwargs,
             save_path_=str(save_path),
         )
-    with PARSE_UGRID_ON_LOAD.context():
-        with load_realised():
-            source_mesh = load_mesh(str(save_path))
+    with load_realised():
+        source_mesh = load_mesh(str(save_path))
     # Regenerate MeshCoord from its Mesh, which we saved.
     return source_mesh.to_MeshCoord(location=location, axis=axis)
 
@@ -180,7 +178,6 @@ def _external(w_mesh_: str, save_path_: str):
     )
     if not REUSE_DATA or not save_path.is_file():
         _ = run_function_elsewhere(_external, w_mesh_=w_mesh, save_path_=str(save_path))
-    with PARSE_UGRID_ON_LOAD.context():
-        context = nullcontext() if lazy else load_realised()
-        with context:
-            return iris.load_cube(save_path, "air_potential_temperature")
+    context = nullcontext() if lazy else load_realised()
+    with context:
+        return iris.load_cube(save_path, "air_potential_temperature")

benchmarks/benchmarks/generate_data/ugrid.py

@@ -5,7 +5,6 @@
 """Scripts for generating supporting data for UGRID-related benchmarking."""
 
 from iris import load_cube as iris_loadcube
-from iris.experimental.ugrid import PARSE_UGRID_ON_LOAD
 
 from . import BENCHMARK_DATA, REUSE_DATA, load_realised, run_function_elsewhere
 from .stock import (
@@ -85,8 +84,7 @@ def make_cube_like_2d_cubesphere(n_cube: int, with_mesh: bool):
         )
 
     # File now *should* definitely exist: content is simply the desired cube.
-    with PARSE_UGRID_ON_LOAD.context():
-        cube = iris_loadcube(str(filepath))
+    cube = iris_loadcube(str(filepath))
 
     # Ensure correct laziness.
     _ = cube.data
@@ -155,9 +153,8 @@ def _external(xy_dims_, save_path_):
     )
     if not REUSE_DATA or not save_path.is_file():
         _ = run_function_elsewhere(_external, xy_dims, str(save_path))
-    with PARSE_UGRID_ON_LOAD.context():
-        with load_realised():
-            cube = iris_loadcube(str(save_path))
+    with load_realised():
+        cube = iris_loadcube(str(save_path))
 
     return cube
 

benchmarks/benchmarks/load/ugrid.py

@@ -5,8 +5,7 @@
 """Mesh data loading benchmark tests."""
 
 from iris import load_cube as iris_load_cube
-from iris.experimental.ugrid import PARSE_UGRID_ON_LOAD
-from iris.experimental.ugrid import load_mesh as iris_load_mesh
+from iris.mesh import load_mesh as iris_load_mesh
 
 from ..generate_data.stock import create_file__xios_2d_face_half_levels
 
@@ -18,13 +17,11 @@ def synthetic_data(**kwargs):
 
 
 def load_cube(*args, **kwargs):
-    with PARSE_UGRID_ON_LOAD.context():
-        return iris_load_cube(*args, **kwargs)
+    return iris_load_cube(*args, **kwargs)
 
 
 def load_mesh(*args, **kwargs):
-    with PARSE_UGRID_ON_LOAD.context():
-        return iris_load_mesh(*args, **kwargs)
+    return iris_load_mesh(*args, **kwargs)
 
 
 class BasicLoading:

benchmarks/benchmarks/experimental/__init__.py → benchmarks/benchmarks/mesh/__init__.py

@@ -2,4 +2,4 @@
 #
 # This file is part of Iris and is released under the BSD license.
 # See LICENSE in the root of the repository for full licensing details.
-"""Benchmark tests for the experimental module."""
+"""Benchmark tests for the iris.mesh module."""

lib/iris/tests/unit/ugrid/__init__.py → benchmarks/benchmarks/mesh/utils/__init__.py

@@ -2,4 +2,4 @@
 #
 # This file is part of Iris and is released under the BSD license.
 # See LICENSE in the root of the repository for full licensing details.
-"""Unit tests for the :mod:`iris.ugrid` package."""
+"""Benchmark tests for the iris.mesh.utils module."""

benchmarks/benchmarks/experimental/ugrid/regions_combine.py → benchmarks/benchmarks/mesh/utils/regions_combine.py

@@ -5,7 +5,7 @@
 """Benchmarks stages of operation.
 
 Benchmarks stages of operation of the function
-:func:`iris.experimental.ugrid.utils.recombine_submeshes`.
+:func:`iris.mesh.utils.recombine_submeshes`.
 
 """
 
@@ -15,8 +15,7 @@
 import numpy as np
 
 from iris import load, load_cube, save
-from iris.experimental.ugrid import PARSE_UGRID_ON_LOAD
-from iris.experimental.ugrid.utils import recombine_submeshes
+from iris.mesh.utils import recombine_submeshes
 
 from ... import TrackAddedMemoryAllocation
 from ...generate_data.ugrid import make_cube_like_2d_cubesphere
@@ -103,13 +102,12 @@ def setup(self, n_cubesphere, imaginary_data=True, create_result_cube=True):
 
         """
         # Load source cubes (full-mesh and regions)
-        with PARSE_UGRID_ON_LOAD.context():
-            self.full_mesh_cube = load_cube(
-                self._parametrised_cache_filename(n_cubesphere, "meshcube")
-            )
-            self.region_cubes = load(
-                self._parametrised_cache_filename(n_cubesphere, "regioncubes")
-            )
+        self.full_mesh_cube = load_cube(
+            self._parametrised_cache_filename(n_cubesphere, "meshcube")
+        )
+        self.region_cubes = load(
+            self._parametrised_cache_filename(n_cubesphere, "regioncubes")
+        )
 
         # Remove all var-names from loaded cubes, which can otherwise cause
         # problems.  Also implement 'imaginary' data.

benchmarks/benchmarks/save.py

@@ -5,7 +5,7 @@
 """File saving benchmarks."""
 
 from iris import save
-from iris.experimental.ugrid import save_mesh
+from iris.mesh import save_mesh
 
 from . import TrackAddedMemoryAllocation, on_demand_benchmark
 from .generate_data.ugrid import make_cube_like_2d_cubesphere

benchmarks/benchmarks/sperf/__init__.py

@@ -10,9 +10,6 @@
 
 from iris import load_cube
 
-# TODO: remove uses of PARSE_UGRID_ON_LOAD once UGRID parsing is core behaviour.
-from iris.experimental.ugrid import PARSE_UGRID_ON_LOAD
-
 from ..generate_data.ugrid import make_cubesphere_testfile
 
 
@@ -38,5 +35,4 @@ def setup(self, c_size, n_levels, n_times):
         )
 
     def load_cube(self):
-        with PARSE_UGRID_ON_LOAD.context():
-            return load_cube(str(self.file_path))
+        return load_cube(str(self.file_path))

benchmarks/benchmarks/sperf/combine_regions.py

@@ -10,8 +10,7 @@
 import numpy as np
 
 from iris import load, load_cube, save
-from iris.experimental.ugrid import PARSE_UGRID_ON_LOAD
-from iris.experimental.ugrid.utils import recombine_submeshes
+from iris.mesh.utils import recombine_submeshes
 
 from .. import TrackAddedMemoryAllocation, on_demand_benchmark
 from ..generate_data.ugrid import BENCHMARK_DATA, make_cube_like_2d_cubesphere
@@ -102,13 +101,12 @@ def setup(self, n_cubesphere, imaginary_data=True, create_result_cube=True):
 
         """
         # Load source cubes (full-mesh and regions)
-        with PARSE_UGRID_ON_LOAD.context():
-            self.full_mesh_cube = load_cube(
-                self._parametrised_cache_filename(n_cubesphere, "meshcube")
-            )
-            self.region_cubes = load(
-                self._parametrised_cache_filename(n_cubesphere, "regioncubes")
-            )
+        self.full_mesh_cube = load_cube(
+            self._parametrised_cache_filename(n_cubesphere, "meshcube")
+        )
+        self.region_cubes = load(
+            self._parametrised_cache_filename(n_cubesphere, "regioncubes")
+        )
 
         # Remove all var-names from loaded cubes, which can otherwise cause
         # problems.  Also implement 'imaginary' data.

benchmarks/benchmarks/sperf/equality.py

@@ -13,7 +13,7 @@ class CubeEquality(FileMixin):
     r"""Benchmark time and memory costs.
 
     Benchmark time and memory costs of comparing :class:`~iris.cube.Cube`\\ s
-    with attached :class:`~iris.experimental.ugrid.mesh.MeshXY`\\ es.
+    with attached :class:`~iris.mesh.MeshXY`\\ es.
 
     Uses :class:`FileMixin` as the realistic case will be comparing
     :class:`~iris.cube.Cube`\\ s that have been loaded from file.

benchmarks/benchmarks/sperf/save.py

@@ -7,7 +7,7 @@
 import os.path
 
 from iris import save
-from iris.experimental.ugrid import save_mesh
+from iris.mesh import save_mesh
 
 from .. import TrackAddedMemoryAllocation, on_demand_benchmark
 from ..generate_data.ugrid import make_cube_like_2d_cubesphere

benchmarks/benchmarks/unit_style/ugrid.py → benchmarks/benchmarks/unit_style/mesh.py

@@ -2,22 +2,22 @@
 #
 # This file is part of Iris and is released under the BSD license.
 # See LICENSE in the root of the repository for full licensing details.
-"""Benchmark tests for the experimental.ugrid module."""
+"""Benchmark tests for the iris.mesh module."""
 
 from copy import deepcopy
 
 import numpy as np
 
-from iris.experimental import ugrid
+from iris import mesh
 
 from .. import disable_repeat_between_setup
 from ..generate_data.stock import sample_mesh
 
 
 class UGridCommon:
-    """Run a generalised suite of benchmarks for any ugrid object.
+    """Run a generalised suite of benchmarks for any mesh object.
 
-    A base class running a generalised suite of benchmarks for any ugrid object.
+    A base class running a generalised suite of benchmarks for any mesh object.
     Object to be specified in a subclass.
 
     ASV will run the benchmarks within this class for any subclasses.
@@ -53,7 +53,7 @@ def setup(self, n_faces):
         super().setup(n_faces)
 
     def create(self):
-        return ugrid.Connectivity(indices=self.array, cf_role="face_node_connectivity")
+        return mesh.Connectivity(indices=self.array, cf_role="face_node_connectivity")
 
     def time_indices(self, n_faces):
         _ = self.object.indices
@@ -123,7 +123,7 @@ def get_coords_and_axes(location):
         self.eq_object = deepcopy(self.object)
 
     def create(self):
-        return ugrid.MeshXY(**self.mesh_kwargs)
+        return mesh.MeshXY(**self.mesh_kwargs)
 
     def time_add_connectivities(self, n_faces):
         self.object.add_connectivities(self.face_node)
@@ -170,7 +170,7 @@ def setup(self, n_faces, lazy=False):
         super().setup(n_faces)
 
     def create(self):
-        return ugrid.MeshCoord(mesh=self.mesh, location="face", axis="x")
+        return mesh.MeshCoord(mesh=self.mesh, location="face", axis="x")
 
     def time_points(self, n_faces):
         _ = self.object.points