From f17f5ad9946bfc01abd097eb1b7a9b069fff5ca3 Mon Sep 17 00:00:00 2001
From: Patrick Peglar <patrick.peglar@metoffice.gov.uk>
Date: Thu, 24 Oct 2024 16:55:42 +0100
Subject: [PATCH] Add cubelist methods for 'combine' operations.

---
 lib/iris/cube.py | 61 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/lib/iris/cube.py b/lib/iris/cube.py
index ef879ccca0..7f95979a4d 100644
--- a/lib/iris/cube.py
+++ b/lib/iris/cube.py
@@ -634,6 +634,67 @@ def concatenate(
             check_derived_coords=check_derived_coords,
         )
 
+    def combine(self, options=None, merge_require_unique=False, **kwargs):
+        """Combine cubes according to :class:`iris~.io.loading.LoadPolicy` options.
+
+        Applies a :meth:`combine`.
+
+        Parameters
+        ----------
+        options : dict or str
+            Settings, as described for :meth:`iris.LOAD_POLICY.set`.
+            Defaults to current :meth:`iris.LOAD_POLICY.settings`.
+        merge_require_unique : bool
+            Value for the 'unique' keyword in any merge operations.
+        kwargs : dict
+            Individual settings, as described for :meth:`iris.LOAD_POLICY.set`.
+
+        Returns
+        -------
+        CubeList of :class:`~iris.cube.Cube`
+
+        .. Note::
+            The ``support_multiple_references`` keyword/property has no effect on the
+            :func:`combine_cubes` operation : it only takes effect during a load operation.
+
+        """
+        from iris.io.loading import combine_cubes
+
+        return combine_cubes(
+            self, options=options, merge_require_unique=merge_require_unique, **kwargs
+        )
+
+    def combine_cube(self, options=None, merge_require_unique=False, **kwargs):
+        """Combine cubes as for :meth:`combine`, expecting a single cube result.
+
+        Parameters
+        ----------
+        options : dict or str
+            Settings, as for :meth:`combine`.
+        merge_require_unique : bool
+            Value for the 'unique' keyword in any merge operations.
+        kwargs : dict
+            Individual settings, as for :meth:`combine`.
+
+        Returns
+        -------
+        CubeList of :class:`~iris.cube.Cube`
+
+        """
+        from iris.io.loading import combine_cubes
+
+        result = combine_cubes(
+            self, options=options, merge_require_unique=merge_require_unique, **kwargs
+        )
+        n_cubes = len(result)
+        if n_cubes == 1:
+            (result,) = result
+        elif n_cubes == 0:
+            raise ValueError("'combine' returned no cubes.")
+        else:
+            raise ValueError(f"'combine' result is not a single cube : {result!r}.")
+        return result
+
     def realise_data(self):
         """Fetch 'real' data for all cubes, in a shared calculation.