Update explanation_interpolation.md

Adding more information on Interpolator signature

Author: erikvansebille

docs/user_guide/examples/explanation_interpolation.md

@@ -3,10 +3,6 @@
 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:
@@ -26,7 +22,7 @@ If you want to sample at a different location, or time, that is not necessarily
 ```python
 particles.temperature = fieldset.temperature[time, depth, lat, lon]
 ```
-but this could be slower for curvilinear and unstructured because the entire grid needs to be searched.
+but this could be slower for curvilinear and unstructured Grids because the entire grid needs to be searched.
 ````
 
 The values of the `temperature` field at the particles' positions are determined using an interpolation
@@ -36,15 +32,23 @@ 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 values of the grid points of the `parcels.Field` in time and space, to calculate
-the requested value at the particles location. Note that all grid values are available so that higher-order interpolation is possible.
+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:
+The interpolators included in Parcels are designed for common interpolation schemes in Parcels simulations; see the [Using the built-in interpolators tutorial](./tutorial_interpolation.ipynb).
 
-We can write an interpolator function that takes a `parcels.Field` (or `parcels.VectorField`), a dictionary with the `particle_positions`
-in real space and time, and a dictionary with the `grid_positions`.
+If we want to create a custom interpolation method, we need to look at the interpolator API. Each interpolator is a class that inherits from either the `ScalarInterpolator` or `VectorInterpolator` class. The `ScalarInterpolator` class is used for scalar fields, such as temperature or salinity, while the `VectorInterpolator` class is used for vector fields, such as velocity. An interpolator class than has to have a `.interp()` method with the following signature:
+
+```python
+    def interp(
+        self,
+        particle_positions: dict[str, float | np.ndarray],
+        grid_positions: dict[ptyping.XgridAxis, dict[str, int | float | np.ndarray]],
+        field: Field,
+    ):
+        ...
+```
 
 The `particle_positions` dictionary contains:
 
@@ -74,3 +78,7 @@ grid_positions = {
     "FACE": {"index": fi, "bcoord": bcoord}
 }
 ```
+
+The `.interp()` method should return a float (in the case o a `ScalarInterpolator` or a tuple of three floats `(u, v, w)` in the case of a `VectorInterpolator`).
+
+Writing custom interpolators is not trivial, so we recommend that you have a look at the built-in interpolators in `parcels.interpolators._xinterpolators` or `parcels.interpolators._uxinterpolators` to see how they are implemented.