scaffold explanation, complete guide, and add todo notes

Author: reint-fischer

docs/user_guide/examples/explanation_interpolation.md

@@ -1,4 +1,5 @@
 # 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.
 
@@ -7,48 +8,55 @@ 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`). 
+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. 
+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. 
+
+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` 
+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}, 
+    "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}, 
+    "T": {"index": ti, "bcoord": tau},
+    "Z": {"index": zi, "bcoord": zeta},
     "FACE": {"index": fi, "bcoord": bcoord}
 }
-```
+```

docs/user_guide/examples/tutorial_interpolation.ipynb

@@ -219,7 +219,11 @@
     "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"
+    "4. `interp_method=parcels.interpolators.CGridTracer`: return nearest field value supposing C cells\n",
+    "\n",
+    "In the special case where a `parcels.Field` is constant in time and space, such as implementing constant diffusion on a spherical mesh, we can use:\n",
+    "\n",
+    "5. `interp_method=parcels.interpolators.XConstantField`: return single value of a Constant Field"
    ]
   },
   {
@@ -231,6 +235,28 @@
     "```"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Interpolation on unstructured grids\n",
+    "```{note}\n",
+    "TODO: add example on simple unstructured fieldset\n",
+    "```\n",
+    "- UXPiecewiseConstantFace\n",
+    "- UXPiecewiseLinearNode"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Interpolation at boundaries\n",
+    "In some cases we need to implement specific boundary conditions, for example to prevent particles from \n",
+    "getting \"stuck\" near land. [This guide](../examples_v3/documentation_unstuck_Agrid.ipynb) describes \n",
+    "how to implement this in parcels using `parcels.interpolators.XFreeslip` and `parcels.interpolators.XPartialslip`."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},