Merge branch 'main' into lazy-coord-cell-method

.github/workflows/benchmarks_run.yml

@@ -46,7 +46,7 @@ jobs:
 
       - name: Cache environment directories
         id: cache-env-dir
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: |
             .nox
@@ -56,7 +56,7 @@ jobs:
 
       - name: Cache test data directory
         id: cache-test-data
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         with:
           path: |
             ${{ env.IRIS_TEST_DATA_PATH }}

.pre-commit-config.yaml

@@ -29,7 +29,7 @@ repos:
     -   id: no-commit-to-branch
 
 -   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.1.11"
+    rev: "v0.1.13"
     hooks:
     -   id: ruff
         types: [file, python]

.readthedocs.yml

@@ -1,9 +1,9 @@
 version: 2
 
 build:
-  os: ubuntu-20.04
+  os: "ubuntu-22.04"
   tools:
-    python: mambaforge-4.10
+    python: "mambaforge-22.9"
   jobs:
     post_checkout:
       # The SciTools/iris repository is shallow i.e., has a .git/shallow,

.ruff.toml

@@ -29,8 +29,6 @@ lint.ignore = [
     "D102",  # Missing docstring in public method
     # (D-3) Temporary, before an initial review, either fix ocurrences or move to (2).
     "D103",  # Missing docstring in public function
-    "D205",  # 1 blank line required between summary line and description
-    "D401",  # First line of docstring should be in imperative mood: ...
 
     # pyupgrade (UP)
     # https://docs.astral.sh/ruff/rules/#pyupgrade-up

benchmarks/asv_delegated_conda.py

@@ -2,8 +2,9 @@
 #
 # 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.
-"""ASV plug-in providing an alternative :class:`asv.plugins.conda.Conda`
-subclass that manages the Conda environment via custom user scripts.
+"""ASV plug-in providing an alternative :class:`asv.plugins.conda.Conda` subclass.
+
+Manages the Conda environment via custom user scripts.
 
 """
 
@@ -42,7 +43,9 @@ def __init__(
         requirements: dict,
         tagged_env_vars: dict,
     ) -> None:
-        """Parameters
+        """__init__.
+
+        Parameters
         ----------
         conf : Config instance
 

benchmarks/benchmarks/__init__.py

@@ -10,7 +10,7 @@
 
 
 def disable_repeat_between_setup(benchmark_object):
-    """Decorator for benchmarks where object persistence would be inappropriate.
+    """Benchmarks where object persistence would be inappropriate (decorator).
 
     E.g:
         * Benchmarking data realisation
@@ -36,7 +36,9 @@ def disable_repeat_between_setup(benchmark_object):
 
 
 class TrackAddedMemoryAllocation:
-    """Context manager which measures by how much process resident memory grew,
+    """Measures by how much process resident memory grew, during execution.
+
+    Context manager which measures by how much process resident memory grew,
     during execution of its enclosed code block.
 
     Obviously limited as to what it actually measures : Relies on the current
@@ -84,7 +86,7 @@ def addedmem_mb(self):
 
     @staticmethod
     def decorator(decorated_func):
-        """Decorates this benchmark to track growth in resident memory during execution.
+        """Benchmark to track growth in resident memory during execution.
 
         Intended for use on ASV ``track_`` benchmarks. Applies the
         :class:`TrackAddedMemoryAllocation` context manager to the benchmark
@@ -105,7 +107,9 @@ def _wrapper(*args, **kwargs):
 
 
 def on_demand_benchmark(benchmark_object):
-    """Decorator. Disables these benchmark(s) unless ON_DEMAND_BENCHARKS env var is set.
+    """Disables these benchmark(s) unless ON_DEMAND_BENCHARKS env var is set.
+
+    This is a decorator.
 
     For benchmarks that, for whatever reason, should not be run by default.
     E.g:

benchmarks/benchmarks/aux_factory.py

@@ -16,7 +16,9 @@ class FactoryCommon:
     #       * make class an ABC
     #       * remove NotImplementedError
     #       * combine setup_common into setup
-    """A base class running a generalised suite of benchmarks for any factory.
+    """Run a generalised suite of benchmarks for any factory.
+
+    A base class running a generalised suite of benchmarks for any factory.
     Factory to be specified in a subclass.
 
     ASV will run the benchmarks within this class for any subclasses.

benchmarks/benchmarks/coords.py

@@ -23,7 +23,9 @@ class CoordCommon:
     #       * make class an ABC
     #       * remove NotImplementedError
     #       * combine setup_common into setup
-    """A base class running a generalised suite of benchmarks for any coord.
+    """Run a generalised suite of benchmarks for any coord.
+
+    A base class running a generalised suite of benchmarks for any coord.
     Coord to be specified in a subclass.
 
     ASV will run the benchmarks within this class for any subclasses.

benchmarks/benchmarks/cperf/equality.py

@@ -8,8 +8,11 @@
 
 
 class EqualityMixin(SingleDiagnosticMixin):
-    r"""Uses :class:`SingleDiagnosticMixin` as the realistic case will be comparing
+    r"""Use :class:`SingleDiagnosticMixin` as the realistic case.
+
+    Uses :class:`SingleDiagnosticMixin` as the realistic case will be comparing
     :class:`~iris.cube.Cube`\\ s that have been loaded from file.
+
     """
 
     # Cut down the parent parameters.
@@ -23,9 +26,7 @@ def setup(self, file_type, three_d=False, three_times=False):
 
 @on_demand_benchmark
 class CubeEquality(EqualityMixin):
-    r"""Benchmark time and memory costs of comparing LFRic and UM
-    :class:`~iris.cube.Cube`\\ s.
-    """
+    r"""Benchmark time & memory costs of comparing LFRic & UM :class:`~iris.cube.Cube`\\ s."""
 
     def _comparison(self):
         _ = self.cube == self.other_cube

benchmarks/benchmarks/cperf/load.py

@@ -10,7 +10,8 @@
 @on_demand_benchmark
 class SingleDiagnosticLoad(SingleDiagnosticMixin):
     def time_load(self, _, __, ___):
-        """The 'real world comparison'
+        """Perform a 'real world comparison'.
+
         * UM coords are always realised (DimCoords).
         * LFRic coords are not realised by default (MeshCoords).
 
@@ -25,7 +26,7 @@ def time_load(self, _, __, ___):
             assert coord.has_lazy_bounds() == expecting_lazy_coords
 
     def time_load_w_realised_coords(self, _, __, ___):
-        """A valuable extra comparison where both UM and LFRic coords are realised."""
+        """Valuable extra comparison where both UM and LFRic coords are realised."""
         cube = self.load()
         for coord_name in "longitude", "latitude":
             coord = cube.coord(coord_name)

benchmarks/benchmarks/cperf/save.py

@@ -14,6 +14,7 @@
 @on_demand_benchmark
 class NetcdfSave:
     """Benchmark time and memory costs of saving ~large-ish data cubes to netcdf.
+
     Parametrised by file type.
 
     """

benchmarks/benchmarks/cube.py

@@ -28,7 +28,9 @@ class ComponentCommon:
     #       * make class an ABC
     #       * remove NotImplementedError
     #       * combine setup_common into setup
-    """A base class running a generalised suite of benchmarks for cubes that
+    """Run a generalised suite of benchmarks for cubes.
+
+    A base class running a generalised suite of benchmarks for cubes that
     include a specified component (e.g. Coord, CellMeasure etc.). Component to
     be specified in a subclass.
 
@@ -43,7 +45,7 @@ def setup(self):
         raise NotImplementedError
 
     def create(self):
-        """Generic cube creation.
+        """Create a cube (generic).
 
         cube_kwargs allow dynamic inclusion of different components;
         specified in subclasses.

benchmarks/benchmarks/experimental/ugrid/__init__.py

@@ -15,7 +15,9 @@
 
 
 class UGridCommon:
-    """A base class running a generalised suite of benchmarks for any ugrid object.
+    """Run a generalised suite of benchmarks for any ugrid object.
+
+    A base class running a generalised suite of benchmarks for any ugrid object.
     Object to be specified in a subclass.
 
     ASV will run the benchmarks within this class for any subclasses.

benchmarks/benchmarks/experimental/ugrid/regions_combine.py

@@ -2,14 +2,18 @@
 #
 # 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.
-"""Benchmarks stages of operation of the function
+"""Benchmarks stages of operation.
+
+Benchmarks stages of operation of the function
 :func:`iris.experimental.ugrid.utils.recombine_submeshes`.
 
 Where possible benchmarks should be parameterised for two sizes of input data:
-  * minimal: enables detection of regressions in parts of the run-time that do
-             NOT scale with data size.
-  * large: large enough to exclusively detect regressions in parts of the
-           run-time that scale with data size.
+
+* minimal: enables detection of regressions in parts of the run-time that do
+  NOT scale with data size.
+
+* large: large enough to exclusively detect regressions in parts of the
+  run-time that scale with data size.
 
 """
 import os
@@ -88,7 +92,7 @@ def setup_cache(self):
             )
 
     def setup(self, n_cubesphere, imaginary_data=True, create_result_cube=True):
-        """The combine-tests "standard" setup operation.
+        """Combine-tests "standard" setup operation.
 
         Load the source cubes (full-mesh + region) from disk.
         These are specific to the cubesize parameter.
@@ -193,10 +197,13 @@ def track_addedmem_compute_data(self, n_cubesphere):
 
 
 class CombineRegionsSaveData(MixinCombineRegions):
-    """Test saving *only*, having replaced the input cube data with 'imaginary'
+    """Test saving *only*.
+
+    Test saving *only*, having replaced the input cube data with 'imaginary'
     array data, so that input data is not loaded from disk during the save
     operation.
 
+
     """
 
     def time_save(self, n_cubesphere):
@@ -219,6 +226,7 @@ def track_filesize_saved(self, n_cubesphere):
 
 class CombineRegionsFileStreamedCalc(MixinCombineRegions):
     """Test the whole cost of file-to-file streaming.
+
     Uses the combined cube which is based on lazy data loading from the region
     cubes on disk.
     """

benchmarks/benchmarks/generate_data/stock.py

@@ -49,7 +49,7 @@ def _external(func_name_, temp_file_dir, **kwargs_):
 def create_file__xios_2d_face_half_levels(
     temp_file_dir, dataset_name, n_faces=866, n_times=1
 ):
-    """Wrapper for :meth:`iris.tests.stock.netcdf.create_file__xios_2d_face_half_levels`.
+    """Create file wrapper for :meth:`iris.tests.stock.netcdf.create_file__xios_2d_face_half_levels`.
 
     Have taken control of temp_file_dir
 
@@ -67,7 +67,7 @@ def create_file__xios_2d_face_half_levels(
 def create_file__xios_3d_face_half_levels(
     temp_file_dir, dataset_name, n_faces=866, n_times=1, n_levels=38
 ):
-    """Wrapper for :meth:`iris.tests.stock.netcdf.create_file__xios_3d_face_half_levels`.
+    """Create file wrapper for :meth:`iris.tests.stock.netcdf.create_file__xios_3d_face_half_levels`.
 
     Have taken control of temp_file_dir
 
@@ -84,7 +84,7 @@ def create_file__xios_3d_face_half_levels(
 
 
 def sample_mesh(n_nodes=None, n_faces=None, n_edges=None, lazy_values=False):
-    """Wrapper for :meth:iris.tests.stock.mesh.sample_mesh`."""
+    """Sample mesh wrapper for :meth:iris.tests.stock.mesh.sample_mesh`."""
 
     def _external(*args, **kwargs):
         from iris.experimental.ugrid import save_mesh
@@ -112,7 +112,7 @@ def _external(*args, **kwargs):
 
 
 def sample_meshcoord(sample_mesh_kwargs=None, location="face", axis="x"):
-    """Wrapper for :meth:`iris.tests.stock.mesh.sample_meshcoord`.
+    """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

benchmarks/benchmarks/generate_data/ugrid.py

@@ -14,7 +14,9 @@
 
 
 def generate_cube_like_2d_cubesphere(n_cube: int, with_mesh: bool, output_path: str):
-    """Construct and save to file an LFRIc cubesphere-like cube for a given
+    """Construct and save to file an LFRIc cubesphere-like cube.
+
+    Construct and save to file an LFRIc cubesphere-like cube for a given
     cubesphere size, *or* a simpler structured (UM-like) cube of equivalent
     size.
 
@@ -54,7 +56,9 @@ def generate_cube_like_2d_cubesphere(n_cube: int, with_mesh: bool, output_path:
 
 
 def make_cube_like_2d_cubesphere(n_cube: int, with_mesh: bool):
-    """Generate an LFRIc cubesphere-like cube for a given cubesphere size,
+    """Generate an LFRIc cubesphere-like cube.
+
+    Generate an LFRIc cubesphere-like cube for a given cubesphere size,
     *or* a simpler structured (UM-like) cube of equivalent size.
 
     All the cube data, coords and mesh content are LAZY, and produced without
@@ -155,7 +159,9 @@ def _external(xy_dims_, save_path_):
 
 
 def make_cubesphere_testfile(c_size, n_levels=0, n_times=1):
-    """Build a C<c_size> cubesphere testfile in a given directory, with a standard naming.
+    """Build a C<c_size> cubesphere testfile in a given directory.
+
+    Build a C<c_size> cubesphere testfile in a given directory, with a standard naming.
     If n_levels > 0 specified: 3d file with the specified number of levels.
     Return the file path.
 

benchmarks/benchmarks/import_iris.py

@@ -31,8 +31,7 @@
 class Iris:
     @staticmethod
     def _import(module_name, reset_colormaps=False):
-        """Have experimented with adding sleep() commands into the imported
-        modules.
+        """Have experimented with adding sleep() commands into the imported modules.
 
         The results reveal:
 

benchmarks/benchmarks/sperf/combine_regions.py

@@ -83,7 +83,7 @@ def setup_cache(self):
             )
 
     def setup(self, n_cubesphere, imaginary_data=True, create_result_cube=True):
-        """The combine-tests "standard" setup operation.
+        """Combine-tests "standard" setup operation.
 
         Load the source cubes (full-mesh + region) from disk.
         These are specific to the cubesize parameter.
@@ -195,7 +195,9 @@ def track_addedmem_compute_data(self, n_cubesphere):
 
 @on_demand_benchmark
 class SaveData(Mixin):
-    """Test saving *only*, having replaced the input cube data with 'imaginary'
+    """Test saving *only*.
+
+    Test saving *only*, having replaced the input cube data with 'imaginary'
     array data, so that input data is not loaded from disk during the save
     operation.
 
@@ -217,8 +219,10 @@ def track_filesize_saved(self, n_cubesphere):
 @on_demand_benchmark
 class FileStreamedCalc(Mixin):
     """Test the whole cost of file-to-file streaming.
+
     Uses the combined cube which is based on lazy data loading from the region
     cubes on disk.
+
     """
 
     def setup(self, n_cubesphere, imaginary_data=False, create_result_cube=True):

benchmarks/benchmarks/sperf/equality.py

@@ -9,8 +9,10 @@
 
 @on_demand_benchmark
 class CubeEquality(FileMixin):
-    r"""Benchmark time and memory costs of comparing :class:`~iris.cube.Cube`\\ s
-     with attached :class:`~iris.experimental.ugrid.mesh.Mesh`\\ es.
+    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.Mesh`\\ es.
 
     Uses :class:`FileMixin` as the realistic case will be comparing
     :class:`~iris.cube.Cube`\\ s that have been loaded from file.