update user_guide/index and add interpolation explanation

Author: reint-fischer

docs/user_guide/examples/explanation_interpolation.md

@@ -0,0 +1,54 @@
+# Interpolator explanation
+Interpolation is an important functionality of Parcels. On this page we will discuss the way it is
+implemented in **Parcels** and how to write a custom interpolator function.
+
+```{note}
+TODO: expand explanation (similar to Kernel loop explanation)
+```
+
+When we want to know the state of particles in an environmental field, such as temperature or velocity,
+we _evaluate_ the `parcels.Field` at the particles real position in time and space (`t`, `z`, `lat`, `lon`). 
+In Parcels we can do this using square brackets:
+```
+particles.temperature = fieldset.temperature[particles.time, particles.z, particles.lat, particles.lon]
+```
+The values of the `temperature` field at the particles' positions are determined using an interpolation
+method. This interpolation method defines how the discretized values of the `parcels.Field` should 
+relate to the value at any point within a grid cell. 
+
+Each `parcels.Field` is defined on a (structured) `parcels.XGrid` or (unstructured) `parcels.UXGrid`.
+The interpolation function takes information about the particles position relative to this grid (`grid_positions`),
+as well as the `parcels.Field` values of the surrounding grid points in time and space, to calculate
+the requested value at the particles location.
+
+## Interpolator API
+The interpolators included in Parcels are designed for common interpolation schemes in Parcels simulations. 
+If we want to add a custom interpolation method, we need to look at the interpolator API:
+
+We can write an interpolator function that takes a  `parcels.Field`, a dictionary with the `particle_positions` 
+in real space and time, and a dictionary with the `grid_positions`.
+
+The `particle_positions` dictionary contains:
+```
+particle_positions = {"time", time, "z", z, "lat", lat, "lon", lon}
+```
+
+For structured (`X`) grids, the `grid_positions` dictionary looks like:
+```
+grid_positions = {
+    "T": {"index": ti, "bcoord": tau}, 
+    "Z": {"index": zi, "bcoord": zeta}, 
+    "Y": {"index": yi, "bcoord": eta}, 
+    "X": {"index": xi, "bcoord", xsi},
+}
+```
+where `index` is the grid index in the corresponding dimension, and `bcoord` is the barycentric coordinate in the grid cell.
+
+For unstructured (`UX`) grids, the same dictionary is defined as:
+```
+grid_positions = {
+    "T": {"index": ti, "bcoord": tau}, 
+    "Z": {"index": zi, "bcoord": zeta}, 
+    "FACE": {"index": fi, "bcoord": bcoord}
+}
+```

docs/user_guide/examples/tutorial_interpolation.ipynb

@@ -5,15 +5,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Configure Field Interpolation\n"
-   ]
-  },
-  {
-   "attachments": {},
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "Parcels comes with a number of different interpolation methods for tracer fields, such as temperature. Here, we will show how these work, in an idealised example. For more guidance on the sampling of such fields, check out the [sampling guide](./tutorial_sampling).\n",
+    "# Using `parcels.interpolators`\n",
+    "Parcels comes with a number of different interpolation methods for tracer fields, such as temperature. Here, we will look at a few common `parcels.interpolators` for structured (`X`) grids, and how to configure them in an idealised example. For more guidance on the sampling of such fields, check out the [sampling guide](./tutorial_sampling).\n",
     "\n",
     "We first import the relevant modules"
    ]
@@ -36,7 +29,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We create a small 2D grid where `P` is a tracer that we want to interpolate. In each grid cell, `P` has a random value between 0.1 and 1.1. We then set `P[1,1]` to `0`, which for Parcels specifies that this is a land cell\n"
+    "We create a small 2D structured grid where `P` is a tracer that we want to interpolate. In each grid cell, `P` has a random value between 0.1 and 1.1. We then set `P[1,1]` to `0`, which for Parcels specifies that this is a land cell\n"
    ]
   },
   {
@@ -111,7 +104,11 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "tags": [
+     "hide-output"
+    ]
+   },
    "outputs": [],
    "source": [
     "pset = {}\n",
@@ -217,13 +214,30 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "So in summary, Parcels has four different interpolation schemes for tracers:\n",
+    "So in summary, Parcels has four different interpolation schemes for tracers on structured grids:\n",
     "\n",
     "1. `interp_method=parcels.interpolators.XLinear`: compute linear interpolation\n",
     "2. `interp_method=parcels.interpolators.XLinearInvdistLandTracer`: compute linear interpolation except near land (where field value is zero). In that case, inverse distance weighting interpolation is computed, weighting by squares of the distance.\n",
     "3. `interp_method=parcels.interpolators.XNearest`: return nearest field value\n",
     "4. `interp_method=parcels.interpolators.CGridTracer`: return nearest field value supposing C cells\n"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "```{note}\n",
+    "TODO: link to reference API with all `parcels.interpolators`\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Write your own interpolator\n",
+    "The interpolators included in Parcels are designed for common interpolation schemes in Parcels simulations. If we want to add a custom interpolation method, we can write our own interpolator function (e.g. spline) using the [interpolator API](./explanation_interpolation.md#interpolator-api)."
+   ]
   }
  ],
  "metadata": {

docs/user_guide/index.md

@@ -49,6 +49,14 @@ examples/tutorial_gsw_density.ipynb
 examples/tutorial_Argofloats.ipynb
 ```
 
+```{toctree}
+:caption: Configure interpolation
+:titlesonly:
+
+examples/explanation_interpolation.md
+examples/tutorial_interpolation.ipynb
+```
+
 <!-- examples/tutorial_diffusion.ipynb -->
 <!-- examples/tutorial_particle_field_interaction.ipynb -->
 <!-- examples/tutorial_interaction.ipynb -->