Faster later calls of the generic interpolation path: memoize refactor and numpy flattening

CHANGELOG.rst

@@ -48,6 +48,24 @@ Unreleased
   in LV95) or miss parts of the domain (e.g. 28 km for IFS in LV95)
 * fixed ``set_grid_mapping`` with CF grid mappings holding numpy arrays or non-float64 numpy values (e.g. a
   ``standard_parallel`` array read from a netCDF file), which raised a ``TypeError``
+* changed ``memoize``: the least recently used result is evicted (instead of the oldest one), the cache key can be
+  computed by an optional ``key`` function (only when caching is active), a cache size of 0 deactivates caching
+  without overhead, and the cache is safe to use from several threads, also when the process forks (the fork waits
+  until no thread is using the cache). The ``hkey`` keyword argument still works
+* fixed the in-memory caches of the POI and grid reprojections, whose keys left out the source CRS, and the cache
+  of the regular grid nearest interpolation, which failed with a POI dimension name other than ``poi``
+  (``GRID_PROCESS__data_model__poi__dim``)
+* documented the in-memory caches of ``interp2poi`` and ``interp2grid`` and how to set their sizes or deactivate
+  them with the environment variables ``GRID_PROCESS__cache_size__<name>`` (Usage page)
+* changed ``interp2poi`` and ``interp2grid`` outside of the regular grid interpolation to flatten structured
+  grids with numpy instead of ``xarray.stack``, and ``interp2poi`` to look for the grid points with NaN in all
+  fields (excluded, as before) only among those with NaN in the middle field. Later calls with cached neighbors are
+  faster on large grids (e.g. 0.13 s to 0.05 s for a global 0.25 degree grid to 33 POIs, 1.6 s to 0.5 s from this
+  grid to a global 0.1 degree grid), with identical results
+* fixed ``interp2poi`` raising an ``IndexError`` when all POIs are outside an unstructured grid (no grid point left
+  after slicing): they now get NaN, as outside of the regular grid interpolation
+* made ``grid_interp.get_buffer`` public (renamed from ``_get_buffer``): the slicing buffer in grid points of an
+  interpolation method and its arguments, e.g. to slice the input data with ``slice_boundingbox`` beforehand
 
 1.0.0
 -----

doc/usage.rst

@@ -68,3 +68,41 @@ Use case: regridding::
 
 Returns a xarray.Dataset with the data of ds remapped to the coordinates of ds_dst. Same
 interpolation methods exist as for POI interpolation
+
+
+In-memory caching
+-----------------
+
+``interp2poi`` and ``interp2grid`` cache intermediate results in memory, so that later calls with the same grids
+and POIs (e.g. other variables or runs of the same model) are faster. Each cache keeps a fixed number of results
+(the least recently used one is evicted) for the lifetime of the Python process:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 18 8 74
+
+   * - Cache
+     - Default size
+     - Content
+   * - ``nn_lookup``
+     - 10
+     - nearest neighbor indices and distances (KDTree), outside of the regular grid interpolation
+   * - ``nn_lookup_regular``
+     - 10
+     - nearest grid indices of the regular grid interpolation (``try_reg=True``, chunked or non-float data)
+   * - ``reproject_poi``
+     - 6
+     - POI coordinates reprojected to the grid CRS
+   * - ``reproject_grid``
+     - 6
+     - grid coordinates reprojected to another CRS, and grid coordinates converted to earth-centered earth-fixed
+       coordinates (two separate caches of this size)
+
+The sizes are defined in ``grid_process/config/grid_process.yaml`` and can be overridden with the environment
+variables ``GRID_PROCESS__cache_size__<cache>``. A size of 0 deactivates a cache, without any overhead. This can be
+useful to limit the memory, e.g. for global grids where one cached result can take hundreds of MB, or when the grids
+and POIs differ at each call. The variables are read when ``grid_process`` is imported, so they must be set before,
+e.g. in the shell or the container environment::
+
+    export GRID_PROCESS__cache_size__nn_lookup=0
+    export GRID_PROCESS__cache_size__reproject_grid=0

grid_process/config/grid_process.yaml

@@ -1,3 +1,5 @@
+# number of results kept by each in-memory cache (least recently used evicted), 0 to deactivate it. Override with
+# the environment variables GRID_PROCESS__cache_size__<name>, set before importing grid_process
 cache_size:
   nn_lookup: 10
   nn_lookup_regular: 10