Merge branch 'main' into adopt-coc

tkknight · web-flow · commit d0ffbfcd86ba · 2023-05-02T10:34:08.000+01:00
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -29,5 +29,3 @@ python:
   install:
     - method: pip
       path: .
-      extra_requirements:
-        - docs
diff --git a/docs/src/conf.py b/docs/src/conf.py
@@ -235,6 +235,7 @@ def _dotv(version):
 # See https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
 intersphinx_mapping = {
     "cartopy": ("https://scitools.org.uk/cartopy/docs/latest/", None),
+    "dask": ("https://docs.dask.org/en/stable/", None),
     "matplotlib": ("https://matplotlib.org/stable/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
     "python": ("https://docs.python.org/3/", None),
diff --git a/docs/src/sphinxext/api_rst_formatting.py b/docs/src/sphinxext/api_rst_formatting.py
@@ -20,16 +20,17 @@ def main_api_rst_formatting(app):
     print(f"[{ntpath.basename(__file__)}] Processing RST files", end="")
 
     for file in src_dir.iterdir():
-        print(f".", end="")
+        if file.suffix == ".rst":
+            print(f".", end="")
 
-        with open(file, "r") as f:
-            lines = f.read()
+            with open(file, "r") as f:
+                lines = f.read()
 
-        lines = lines.replace(" package\n=", "\n")
-        lines = lines.replace(" module\n=", "\n")
+            lines = lines.replace(" package\n=", "\n")
+            lines = lines.replace(" module\n=", "\n")
 
-        with open(file, "w") as f:
-            f.write(lines)
+            with open(file, "w") as f:
+                f.write(lines)
     print("")
 
 def setup(app):
diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst
@@ -36,6 +36,9 @@ This document explains the changes made to Iris for this release
    Also with significant input from `@fnattino`_.
    (:pull:`5191`)
 
+#. `@rcomer`_ tweaked binary operations so that dask arrays may safely be passed
+   to arithmetic operations and :func:`~iris.util.mask_cube`. (:pull:`4929`)
+
 
 🐛 Bugs Fixed
 =============
diff --git a/lib/iris/analysis/maths.py b/lib/iris/analysis/maths.py
@@ -225,33 +225,35 @@ def _assert_is_cube(cube):
 @_lenient_client(services=SERVICES)
 def add(cube, other, dim=None, in_place=False):
     """
-    Calculate the sum of two cubes, or the sum of a cube and a
-    coordinate or scalar value.
+    Calculate the sum of two cubes, or the sum of a cube and a coordinate or
+    array or scalar value.
 
-    When summing two cubes, they must both have the same coordinate
-    systems & data resolution.
+    When summing two cubes, they must both have the same coordinate systems and
+    data resolution.
 
-    When adding a coordinate to a cube, they must both share the same
-    number of elements along a shared axis.
+    When adding a coordinate to a cube, they must both share the same number of
+    elements along a shared axis.
 
-    Args:
+    Parameters
+    ----------
 
-    * cube:
-        An instance of :class:`iris.cube.Cube`.
-    * other:
-        An instance of :class:`iris.cube.Cube` or :class:`iris.coords.Coord`,
-        or a number or :class:`numpy.ndarray`.
+    cube : iris.cube.Cube
+        First operand to add.
 
-    Kwargs:
+    other: iris.cube.Cube, iris.coords.Coord, number, numpy.ndarray or dask.array.Array
+        Second operand to add.
 
-    * dim:
-        If supplying a coord with no match on the cube, you must supply
-        the dimension to process.
-    * in_place:
-        Whether to create a new Cube, or alter the given "cube".
+    dim : int, optional
+        If `other` is a coord which does not exist on the cube, specify the
+        dimension to which it should be mapped.
 
-    Returns:
-        An instance of :class:`iris.cube.Cube`.
+    in_place : bool, default=False
+        If `True`, alters the input cube.  Otherwise a new cube is created.
+
+    Returns
+    -------
+
+    iris.cube.Cube
 
     Notes
     ------
@@ -280,32 +282,34 @@ def add(cube, other, dim=None, in_place=False):
 def subtract(cube, other, dim=None, in_place=False):
     """
     Calculate the difference between two cubes, or the difference between
-    a cube and a coordinate or scalar value.
+    a cube and a coordinate or array or scalar value.
 
-    When subtracting two cubes, they must both have the same coordinate
-    systems & data resolution.
+    When differencing two cubes, they must both have the same coordinate systems
+    and data resolution.
 
-    When subtracting a coordinate to a cube, they must both share the
-    same number of elements along a shared axis.
+    When subtracting a coordinate from a cube, they must both share the same
+    number of elements along a shared axis.
 
-    Args:
+    Parameters
+    ----------
 
-    * cube:
-        An instance of :class:`iris.cube.Cube`.
-    * other:
-        An instance of :class:`iris.cube.Cube` or :class:`iris.coords.Coord`,
-        or a number or :class:`numpy.ndarray`.
+    cube : iris.cube.Cube
+        Cube from which to subtract.
 
-    Kwargs:
+    other: iris.cube.Cube, iris.coords.Coord, number, numpy.ndarray or dask.array.Array
+        Object to subtract from the cube.
 
-    * dim:
-        If supplying a coord with no match on the cube, you must supply
-        the dimension to process.
-    * in_place:
-        Whether to create a new Cube, or alter the given "cube".
+    dim : int, optional
+        If `other` is a coord which does not exist on the cube, specify the
+        dimension to which it should be mapped.
 
-    Returns:
-        An instance of :class:`iris.cube.Cube`.
+    in_place : bool, default=False
+        If `True`, alters the input cube.  Otherwise a new cube is created.
+
+    Returns
+    -------
+
+    iris.cube.Cube
 
     Notes
     ------
@@ -348,8 +352,8 @@ def _add_subtract_common(
     operation_name       - the public name of the operation (e.g. 'divide')
     cube                 - the cube whose data is used as the first argument
                            to `operation_function`
-    other                - the cube, coord, ndarray or number whose data is
-                           used as the second argument
+    other                - the cube, coord, ndarray, dask array or number whose
+                           data is used as the second argument
     new_dtype            - the expected dtype of the output. Used in the
                            case of scalar masked arrays
     dim                  - dimension along which to apply `other` if it's a
@@ -384,24 +388,35 @@ def _add_subtract_common(
 @_lenient_client(services=SERVICES)
 def multiply(cube, other, dim=None, in_place=False):
     """
-    Calculate the product of a cube and another cube or coordinate.
+    Calculate the product of two cubes, or the product of a cube and a coordinate
+    or array or scalar value.
 
-    Args:
+    When multiplying two cubes, they must both have the same coordinate systems
+    and data resolution.
 
-    * cube:
-        An instance of :class:`iris.cube.Cube`.
-    * other:
-        An instance of :class:`iris.cube.Cube` or :class:`iris.coords.Coord`,
-        or a number or :class:`numpy.ndarray`.
+    When mulplying a cube by a coordinate, they must both share the same number
+    of elements along a shared axis.
 
-    Kwargs:
+    Parameters
+    ----------
 
-    * dim:
-        If supplying a coord with no match on the cube, you must supply
-        the dimension to process.
+    cube : iris.cube.Cube
+        First operand to multiply.
 
-    Returns:
-        An instance of :class:`iris.cube.Cube`.
+    other: iris.cube.Cube, iris.coords.Coord, number, numpy.ndarray or dask.array.Array
+        Second operand to multiply.
+
+    dim : int, optional
+        If `other` is a coord which does not exist on the cube, specify the
+        dimension to which it should be mapped.
+
+    in_place : bool, default=False
+        If `True`, alters the input cube.  Otherwise a new cube is created.
+
+    Returns
+    -------
+
+    iris.cube.Cube
 
     Notes
     ------
@@ -461,24 +476,35 @@ def _inplace_common_checks(cube, other, math_op):
 @_lenient_client(services=SERVICES)
 def divide(cube, other, dim=None, in_place=False):
     """
-    Calculate the division of a cube by a cube or coordinate.
+    Calculate the ratio of two cubes, or the ratio of a cube and a coordinate
+    or array or scalar value.
 
-    Args:
+    When dividing a cube by another cube, they must both have the same coordinate
+    systems and data resolution.
 
-    * cube:
-        An instance of :class:`iris.cube.Cube`.
-    * other:
-        An instance of :class:`iris.cube.Cube` or :class:`iris.coords.Coord`,
-        or a number or :class:`numpy.ndarray`.
+    When dividing a cube by a coordinate, they must both share the same number
+    of elements along a shared axis.
 
-    Kwargs:
+    Parameters
+    ----------
 
-    * dim:
-        If supplying a coord with no match on the cube, you must supply
-        the dimension to process.
+    cube : iris.cube.Cube
+        Numerator.
 
-    Returns:
-        An instance of :class:`iris.cube.Cube`.
+    other: iris.cube.Cube, iris.coords.Coord, number, numpy.ndarray or dask.array.Array
+        Denominator.
+
+    dim : int, optional
+        If `other` is a coord which does not exist on the cube, specify the
+        dimension to which it should be mapped.
+
+    in_place : bool, default=False
+        If `True`, alters the input cube.  Otherwise a new cube is created.
+
+    Returns
+    -------
+
+    iris.cube.Cube
 
     Notes
     ------
@@ -842,8 +868,8 @@ def _binary_op_common(
     operation_name       - the public name of the operation (e.g. 'divide')
     cube                 - the cube whose data is used as the first argument
                            to `operation_function`
-    other                - the cube, coord, ndarray or number whose data is
-                           used as the second argument
+    other                - the cube, coord, ndarray, dask array or number whose
+                           data is used as the second argument
     new_dtype            - the expected dtype of the output. Used in the
                            case of scalar masked arrays
     new_unit             - unit for the resulting quantity
@@ -883,7 +909,10 @@ def _binary_op_common(
         rhs = other.core_data()
     else:
         # The rhs must be an array.
-        rhs = np.asanyarray(other)
+        if iris._lazy_data.is_lazy_data(other):
+            rhs = other
+        else:
+            rhs = np.asanyarray(other)
 
     def unary_func(lhs):
         data = operation_function(lhs, rhs)
@@ -1194,7 +1223,7 @@ def __call__(
         Kwargs:
 
         * other
-            A cube, coord, ndarray or number whose data is used as the
+            A cube, coord, ndarray, dask array or number whose data is used as the
             second argument to the data function.
 
         * new_name:
diff --git a/lib/iris/tests/unit/analysis/maths/test__arith__dask_array.py b/lib/iris/tests/unit/analysis/maths/test__arith__dask_array.py
@@ -0,0 +1,29 @@
+# Copyright Iris contributors
+#
+# This file is part of Iris and is released under the LGPL license.
+# See COPYING and COPYING.LESSER in the root of the repository for full
+# licensing details.
+"""Unit tests for cube arithmetic with dask arrays."""
+
+# Import iris.tests first so that some things can be initialised before
+# importing anything else.
+import iris.tests as tests  # isort:skip
+
+from unittest import mock
+
+import dask
+import dask.array as da
+
+import iris.cube
+from iris.tests.unit.analysis.maths import MathsAddOperationMixin
+
+
+class TestArithDask(tests.IrisTest, MathsAddOperationMixin):
+    @mock.patch.object(dask.base, "compute", wraps=dask.base.compute)
+    def test_compute_not_called(self, mocked_compute):
+        # No data should be realised when adding a cube and a dask array.
+        cube = iris.cube.Cube(da.arange(4))
+        array = da.ones(4)
+
+        self.data_op(cube, array)
+        mocked_compute.assert_not_called()
diff --git a/lib/iris/util.py b/lib/iris/util.py
@@ -1977,17 +1977,17 @@ def mask_cube(cube, points_to_mask, in_place=False, dim=None):
     """
     Masks any cells in the cube's data array which correspond to cells marked
     ``True`` (or non zero) in ``points_to_mask``.  ``points_to_mask`` may be
-    specified as a :class:`numpy.ndarray`, :class:`iris.coords.Coord` or
-    :class:`iris.cube.Cube`, following the same broadcasting approach as cube
-    arithmetic (see :ref:`cube maths`).
+    specified as a :class:`numpy.ndarray`, :class:`dask.array.Array`,
+    :class:`iris.coords.Coord` or :class:`iris.cube.Cube`, following the same
+    broadcasting approach as cube arithmetic (see :ref:`cube maths`).
 
     Parameters
     ----------
 
     cube : iris.cube.Cube
         Cube containing data that requires masking.
 
-    points_to_mask : numpy.ndarray, iris.coords.Coord or iris.cube.Cube
+    points_to_mask : numpy.ndarray, dask.array.Array, iris.coords.Coord or iris.cube.Cube
         Specifies booleans (or ones and zeros) indicating which points will be masked.
 
     in_place : bool, default=False
