diff --git a/Changelog.rst b/Changelog.rst index 3f16f934d8..a2c1fa36b7 100644 --- a/Changelog.rst +++ b/Changelog.rst @@ -3,6 +3,9 @@ version 3.16.2 **2024-04-??** +* New keyword parameter to `cf.Field.regrids` and `cf.Field.regridc`: + ``return_esmpy_regrid_operator`` + (https://github.com/NCAS-CMS/cf-python/issues/766) * Allow a halo to be added by `cf.Field.indices` and `cf.Field.subspace` (https://github.com/NCAS-CMS/cf-python/issues/759) diff --git a/cf/docstring/docstring.py b/cf/docstring/docstring.py index 10d9d5c87a..6af7c6a315 100644 --- a/cf/docstring/docstring.py +++ b/cf/docstring/docstring.py @@ -651,6 +651,11 @@ operation and define a halo to be added to the subspaced axes. ============== ======================================""", + # return_esmpy_regrid_operator + "{{return_esmpy_regrid_operator: `bool`, optional}}": """return_esmpy_regrid_operator: `bool`, optional + If True then do not perform the regridding, rather + return the `esmpy.Regrid` instance that defines the + regridding operation.""", # ---------------------------------------------------------------- # Method description substitutions (4 levels of indentation) # ---------------------------------------------------------------- diff --git a/cf/field.py b/cf/field.py index f46bc0fa0b..7e55e6c979 100644 --- a/cf/field.py +++ b/cf/field.py @@ -13488,6 +13488,7 @@ def regrids( z=None, ln_z=None, verbose=None, + return_esmpy_regrid_operator=False, inplace=False, i=False, _compute_field_mass=None, @@ -13728,6 +13729,10 @@ def regrids( {{inplace: `bool`, optional}} + {{return_esmpy_regrid_operator: `bool`, optional}} + + .. versionadded:: 3.16.2 + axis_order: sequence, optional Deprecated at version 3.14.0. @@ -13744,7 +13749,8 @@ def regrids( `Field` or `None` or `RegridOperator` The regridded field construct; or `None` if the operation was in-place; or the regridding operator if - *return_operator* is True. + *return_operator* is True; or the `esmpy.Regrid` operator + object if *return_esmpy_regrid_operator* is True. **Examples** @@ -13819,6 +13825,7 @@ def regrids( dst_z=dst_z, z=z, ln_z=ln_z, + return_esmpy_regrid_operator=return_esmpy_regrid_operator, inplace=inplace, ) @@ -13842,6 +13849,7 @@ def regridc( dst_z=None, z=None, ln_z=None, + return_esmpy_regrid_operator=False, inplace=False, i=False, _compute_field_mass=None, @@ -14017,6 +14025,10 @@ def regridc( {{inplace: `bool`, optional}} + {{return_esmpy_regrid_operator: `bool`, optional}} + + .. versionadded:: 3.16.2 + axis_order: sequence, optional Deprecated at version 3.14.0. @@ -14033,7 +14045,8 @@ def regridc( `Field` or `None` or `RegridOperator` The regridded field construct; or `None` if the operation was in-place; or the regridding operator if - *return_operator* is True. + *return_operator* is True; or the `esmpy.Regrid` operator + object if *return_esmpy_regrid_operator* is True. **Examples** @@ -14107,6 +14120,7 @@ def regridc( dst_z=dst_z, z=z, ln_z=ln_z, + return_esmpy_regrid_operator=return_esmpy_regrid_operator, inplace=inplace, ) diff --git a/cf/query.py b/cf/query.py index b4567750c9..3c4d31d681 100644 --- a/cf/query.py +++ b/cf/query.py @@ -495,7 +495,6 @@ def __str__(self): if self.open_lower: repr_value = "(" + repr_value[1:] - if self.open_upper: repr_value = repr_value[:-1] + ")" @@ -1740,7 +1739,7 @@ def wi( bound so that value0 is excluded from the range. By default the interval is closed so that value0 is included. - + .. versionadded:: NEXTVERSION open_upper: `bool`, optional @@ -1748,7 +1747,7 @@ def wi( bound so that value1 is excluded from the range. By default the interval is closed so that value1 is included. - + .. versionadded:: NEXTVERSION units: `str` or `Units`, optional diff --git a/cf/test/test_regrid.py b/cf/test/test_regrid.py index e3cfaa9b8f..f171e83994 100644 --- a/cf/test/test_regrid.py +++ b/cf/test/test_regrid.py @@ -791,6 +791,25 @@ def test_Field_regrid_weights_file(self): src.regrids(r, method="linear", weights_file=tmpfile) ) + @unittest.skipUnless(esmpy_imported, "Requires esmpy/ESMF package.") + def test_return_esmpy_regrid_operator(self): + """esmpy regrid operator returns esmpy.Regrid in regrids and regridc""" + dst = self.dst + src = self.src + + opers = src.regrids( + dst, method="conservative", return_esmpy_regrid_operator=True + ) + operc = src.regridc( + dst, + axes=["Y", "X"], + method="conservative", + return_esmpy_regrid_operator=True, + ) + + self.assertIsInstance(opers, esmpy.api.regrid.Regrid) + self.assertIsInstance(operc, esmpy.api.regrid.Regrid) + if __name__ == "__main__": print("Run date:", datetime.datetime.now())