Scheme Comparison
=================

There are a number of objects which can be used to regrid Iris_ cubes.
These each have their own quirks which this page aims to describe.

Overview: Schemes
-----------------

The top level objects provided by iris-esmf-regrid as the *schemes*,
these are designed to behave the same as the *schemes* in
:py:mod:`iris.analysis`. The three schemes iris-esmf-regrid provides
are :class:`~esmf_regrid.schemes.ESMFAreaWeighted`,
:class:`~esmf_regrid.schemes.ESMFBilinear` and
:class:`~esmf_regrid.schemes.ESMFNearest`. These wrap the ESMF_
regrid methods :attr:`~esmpy.api.constants.RegridMethod.CONSERVE`,
:attr:`~esmpy.api.constants.RegridMethod.BILINEAR` or
:attr:`~esmpy.api.constants.RegridMethod.NEAREST_STOD` respectively.
The schemes can be by the pattern::

    result_cube = source_cube.regrid(target_cube, ESMFAreaWeighted())

These schemes are flexible and allow the source or target cube to be
defined on an unstructured mesh while the other cube is define on a
structured grid.

Overview: Regridders
--------------------

The *regridders* are objects one level down from schemes. A regridder
is a class which is designed to handle the regridding of data from
one specific source to one specific target. *Regridders* are useful
because regridding involves a computationally expensive intitialisation
step which can be avoided whenever a *regridder* is reused.
iris-esmf-regrid provides the regridders
:class:`~esmf_regrid.schemes.ESMFAreaWeightedRegridder`,
:class:`~esmf_regrid.schemes.ESMFBilinearRegridder` and
:class:`~esmf_regrid.schemes.ESMFNearestRegridder` which correspond to
the schemes :class:`~esmf_regrid.schemes.ESMFAreaWeighted`,
:class:`~esmf_regrid.schemes.ESMFBilinear` and
:class:`~esmf_regrid.schemes.ESMFNearest` respectively.
These can be initialised either by::

    regridder = ESMFAreaWeightedRegridder(source_cube, target_cube)

or equivalently by::

    regridder = ESMFAreaWeighted().regridder(source_cube, target_cube)

This regridder can then be called by::

    result_cube = regridder(source_cube, target_cube)

which can be reused on any cube defined on the same horizontal
coordinates as ``source_cube``.

There are also the experimental regridders
:class:`~esmf_regrid.experimental.unstructured_scheme.MeshToGridESMFRegridder` and
:class:`~esmf_regrid.experimental.unstructured_scheme.GridToMeshESMFRegridder`.
These were formerly the only way to do regridding with a source or
target cube defined on an unstructured mesh. These are less flexible and
require that the source/target be defined on a grid/mesh. Unlike the above
regridders whose method is fixed, these regridders take a ``method`` keyword
of ``conservative``, ``bilinear`` or ``nearest``. All the
functionality in these regridders has now been ported into the above schemes and
regridders. Before version 0.10, these were the only regridders capable of being
saved and loaded by :mod:`esmf_regrid.experimental.io`, so while the above generic
regridders are recomended, these regridders are still available for the sake of
consistency with regridders saved from older versions.


Overview: Miscellaneous Functions
---------------------------------

The functions :func:`~esmf_regrid.schemes.regrid_rectilinear_to_rectilinear`,
:func:`~esmf_regrid.experimental.unstructured_scheme.regrid_unstructured_to_rectilinear` and
:func:`~esmf_regrid.experimental.unstructured_scheme.regrid_rectilinear_to_unstructured`
exist as alternative ways to call the same regridding functionality::

    result = regrid_rectilinear_to_rectilinear(source_cube, target_cube)

This function also has a ``method`` keyword which can be ``conservative``, ``bilinear``
or ``nearest``, with ``conservative`` being the default.

Differences Between Methods
---------------------------

This section is under development, for more details see the
:doc:`API documentation<../_api_generated/modules>`.

.. _Iris: https://github.com/SciTools/iris
.. _ESMF: https://github.com/esmf-org/esmf