Cleaning up the documentation

docs/getting_started/explanation_concepts.md

@@ -143,23 +143,23 @@ def Age(particles, fieldset):
     particles.age += particles.dt
 
 # define all kernels to be executed on particles using an (ordered) list
-kernels = [Age, parcels.kernels.AdvectionRK4]
+kernels = [Age, parcels.kernels.AdvectionRK2]
 ```
 
 ```{note}
 Every Kernel must be a function with the following (and only those) arguments: `(particles, fieldset)`
 ```
 
 ```{warning}
-We have to be careful with writing kernels for vector fields on Curvilinear grids. While Parcels automatically rotates the "U" and "V" field when necessary, this is not the case for other fields such as Stokes drift. [This guide](../user_guide/examples/tutorial_nemo_curvilinear.ipynb) describes how to use a curvilinear grid in Parcels.
+We have to be careful with kernels that sample velocities on "spherical" grids (so with longitude and latitude in degrees). Parcels can automatically convert velocities from m s<sup>-1</sup> to degrees s<sup>-1</sup>, but only when using `VectorFields`. [This guide](../user_guide/examples/tutorial_velocityconversion.ipynb) describes how to use velocities on a "spherical" grid in Parcels.
 ```
 
 ```{admonition} 📖 Read more about the Kernel loop
 :class: seealso
 - [The Kernel loop](../user_guide/examples/explanation_kernelloop.md)
 ```
 
-```{admonition} 🖥️ Learn how to write kernels
+```{admonition} 🖥️ Learn how to write Kernels
 :class: seealso
 - [Sample fields like temperature](../user_guide/examples/tutorial_sampling.ipynb).
 - [Mimic the behaviour of ARGO floats](../user_guide/examples/tutorial_Argofloats.ipynb).

docs/getting_started/tutorial_output.ipynb

@@ -120,7 +120,7 @@
    "outputs": [],
    "source": [
     "pset.execute(\n",
-    "    parcels.kernels.AdvectionRK4,\n",
+    "    parcels.kernels.AdvectionRK2,\n",
     "    runtime=np.timedelta64(48, \"h\"),\n",
     "    dt=np.timedelta64(5, \"m\"),\n",
     "    output_file=output_file,\n",

docs/getting_started/tutorial_quickstart.md

@@ -54,6 +54,13 @@ ds_fset = parcels.convert.copernicusmarine_to_sgrid(fields=fields)
 fieldset = parcels.FieldSet.from_sgrid_conventions(ds_fset)
 ```
 
+You can inspect the `fieldset` by simply printing it:
+
+```{code-cell}
+:tags: [hide-output]
+print(fieldset)
+```
+
 The subset contains a region of the Agulhas current along the southeastern coast of Africa:
 
 ```{code-cell}
@@ -85,6 +92,15 @@ pset = parcels.ParticleSet(
 )
 ```
 
+Again, you can inspect the `pset` by printing it:
+
+```{code-cell}
+:tags: [hide-output]
+print(pset)
+```
+
+And you can plot the particles on top of the temperature and velocity field:
+
 ```{code-cell}
 temperature = ds_fields.isel(time=0, depth=0).thetao.plot(cmap="magma")
 velocity = ds_fields.isel(time=0, depth=0).plot.quiver(x="longitude", y="latitude", u="uo", v="vo")

docs/user_guide/examples/explanation_kernelloop.md

@@ -4,17 +4,17 @@ kernelspec:
   name: python3
 ---
 
-# 📖 The Parcels Kernel loop
+# 📖 Kernel loop
 
-On this page we discuss Parcels' execution loop, and what happens under the hood when you combine multiple Kernels.
+On this page we discuss how Parcels executes the Kernel loop, and what happens under the hood when you combine multiple Kernels.
 
-This is not very relevant when you only use the built-in Advection kernels, but can be important when you are writing and combining your own Kernels!
+This is not very relevant when you only use the built-in Advection Kernels, but can be important when you are writing and combining your own Kernels!
 
 ## Background
 
 When you run a Parcels simulation (i.e. a call to `pset.execute()`), the Kernel loop is the main part of the code that is executed. This part of the code loops through time and executes the Kernels for all particle.
 
-In order to make sure that the displacements of a particle in the different Kernels can be summed, all Kernels add to a _change_ in position (`particles.dlon`, `particles.dlat`, and `particles.dz`). This is important, because there are situations where movement kernels would otherwise not commute. Take the example of advecting particles by currents _and_ winds. If the particle would first be moved by the currents and then by the winds, the result could be different from first moving by the winds and then by the currents. Instead, by summing the _changes_ in position, the ordering of the Kernels has no consequence on the particle displacement.
+In order to make sure that the displacements of a particle in the different Kernels can be summed, all Kernels add to a _change_ in position (`particles.dlon`, `particles.dlat`, and `particles.dz`). This is important, because there are situations where movement Kernels would otherwise not commute. Take the example of advecting particles by currents _and_ winds. If the particle would first be moved by the currents and then by the winds, the result could be different from first moving by the winds and then by the currents. Instead, by summing the _changes_ in position, the ordering of the Kernels has no consequence on the particle displacement.
 
 ## Basic implementation
 
@@ -91,7 +91,7 @@ windvector = parcels.VectorField(
 fieldset.add_field(windvector)
 ```
 
-Now we define a wind kernel that uses a forward Euler method to apply the wind forcing. Note that we update the `particles.dlon` and `particles.dlat` variables, rather than `particles.lon` and `particles.lat` directly.
+Now we define a wind Kernel that uses a forward Euler method to apply the wind forcing. Note that we update the `particles.dlon` and `particles.dlat` variables, rather than `particles.lon` and `particles.lat` directly.
 
 ```{code-cell}
 def wind_kernel(particles, fieldset):
@@ -100,7 +100,7 @@ def wind_kernel(particles, fieldset):
     particles.dlat += vwind * particles.dt
 ```
 
-First run a simulation where we apply kernels as `[AdvectionRK4, wind_kernel]`
+First run a simulation where we apply Kernels as `[AdvectionRK2, wind_kernel]`
 
 ```{code-cell}
 :tags: [hide-output]
@@ -114,14 +114,14 @@ output_file = parcels.ParticleFile(
     store="advection_then_wind.zarr", outputdt=np.timedelta64(6,'h')
 )
 pset.execute(
-    [parcels.kernels.AdvectionRK4, wind_kernel],
+    [parcels.kernels.AdvectionRK2, wind_kernel],
     runtime=np.timedelta64(5,'D'),
     dt=np.timedelta64(1,'h'),
     output_file=output_file,
 )
 ```
 
-Then also run a simulation where we apply the kernels in the reverse order as `[wind_kernel, AdvectionRK4]`
+Then also run a simulation where we apply the Kernels in the reverse order as `[wind_kernel, AdvectionRK2]`
 
 ```{code-cell}
 :tags: [hide-output]
@@ -132,7 +132,7 @@ output_file_reverse = parcels.ParticleFile(
     store="wind_then_advection.zarr", outputdt=np.timedelta64(6,"h")
 )
 pset_reverse.execute(
-    [wind_kernel, parcels.kernels.AdvectionRK4],
+    [wind_kernel, parcels.kernels.AdvectionRK2],
     runtime=np.timedelta64(5,"D"),
     dt=np.timedelta64(1,"h"),
     output_file=output_file_reverse,

docs/user_guide/examples/tutorial_Argofloats.ipynb

@@ -15,7 +15,7 @@
    "source": [
     "This tutorial shows how simple it is to construct a Kernel in Parcels that mimics the [vertical movement of Argo floats](https://www.aoml.noaa.gov/phod/argo/images/argo_float_mission.jpg).\n",
     "\n",
-    "We first define the kernels for each phase of the Argo cycle."
+    "We first define the Kernel for the vertical movement cycle of the Argo float."
    ]
   },
   {
@@ -90,7 +90,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "And then we can run Parcels with this 'custom kernel'.\n",
+    "And then we can run Parcels with this `ArgoVerticalMovement` Kernel.\n",
     "\n",
     "Below we use the horizontal velocity fields of CopernicusMarine, which are provided as example_data with Parcels.\n"
    ]
@@ -152,10 +152,10 @@
     "    z=[fieldset.mindepth],\n",
     ")\n",
     "\n",
-    "# combine Argo vertical movement kernel with built-in Advection kernel\n",
+    "# combine Argo vertical movement Kernel with built-in Advection Kernel\n",
     "kernels = [\n",
     "    ArgoVerticalMovement,\n",
-    "    parcels.kernels.AdvectionRK4,\n",
+    "    parcels.kernels.AdvectionRK2,\n",
     "]\n",
     "\n",
     "# Create a ParticleFile object to store the output\n",
@@ -165,7 +165,7 @@
     "    chunks=(1, 500),  # setting to write in chunks of 500 observations\n",
     ")\n",
     "\n",
-    "# Now execute the kernels for 30 days, saving data every 30 minutes\n",
+    "# Now execute the Kernels for 30 days, saving data every 30 minutes\n",
     "pset.execute(\n",
     "    kernels,\n",
     "    runtime=timedelta(days=30),\n",
@@ -248,7 +248,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "test-notebooks",
+   "display_name": "docs",
    "language": "python",
    "name": "python3"
   },
@@ -262,7 +262,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.0"
+   "version": "3.14.2"
   }
  },
  "nbformat": 4,

docs/user_guide/examples/tutorial_delaystart.ipynb

@@ -120,7 +120,7 @@
     ")\n",
     "\n",
     "pset.execute(\n",
-    "    parcels.kernels.AdvectionRK4,\n",
+    "    parcels.kernels.AdvectionRK2,\n",
     "    runtime=np.timedelta64(24, \"h\"),\n",
     "    dt=np.timedelta64(5, \"m\"),\n",
     "    output_file=output_file,\n",
@@ -259,7 +259,7 @@
     ")\n",
     "\n",
     "pset.execute(\n",
-    "    parcels.kernels.AdvectionRK4,\n",
+    "    parcels.kernels.AdvectionRK2,\n",
     "    runtime=np.timedelta64(24, \"h\"),\n",
     "    dt=np.timedelta64(5, \"h\"),\n",
     "    output_file=output_file,\n",
@@ -366,7 +366,7 @@
     "\n",
     "output_file = parcels.ParticleFile(outfilepath, outputdt=np.timedelta64(2, \"h\"))\n",
     "pset.execute(\n",
-    "    parcels.kernels.AdvectionRK4,\n",
+    "    parcels.kernels.AdvectionRK2,\n",
     "    endtime=ds_fields.time.values[0] + np.timedelta64(4, \"h\"),\n",
     "    dt=np.timedelta64(1, \"h\"),\n",
     "    output_file=output_file,\n",
@@ -423,7 +423,7 @@
     "    )\n",
     "    output_file = parcels.ParticleFile(outfilepath, outputdt=np.timedelta64(2, \"h\"))\n",
     "    pset.execute(\n",
-    "        parcels.kernels.AdvectionRK4,\n",
+    "        parcels.kernels.AdvectionRK2,\n",
     "        runtime=np.timedelta64(4, \"h\"),\n",
     "        dt=np.timedelta64(1, \"h\"),\n",
     "        output_file=output_file,\n",

docs/user_guide/examples/tutorial_diffusion.ipynb

@@ -545,7 +545,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "In the example, particles are released at one location and simulated for 2 days using advection (`AdvectionRK4`) and diffusion (`smagdiff`) kernels."
+    "In the example, particles are released at one location and simulated for 2 days using advection (`AdvectionRK2`) and diffusion (`smagdiff`) kernels."
    ]
   },
   {
@@ -578,7 +578,7 @@
     "np.random.seed(1636)  # Random seed for reproducibility\n",
     "\n",
     "pset.execute(\n",
-    "    [parcels.kernels.AdvectionRK4, smagdiff],\n",
+    "    [parcels.kernels.AdvectionRK2, smagdiff],\n",
     "    runtime=np.timedelta64(2, \"D\"),\n",
     "    dt=np.timedelta64(5, \"m\"),\n",
     "    output_file=output_file,\n",

docs/user_guide/examples/tutorial_manipulating_field_data.ipynb

@@ -135,7 +135,7 @@
     "    store=\"summed_advection_wind.zarr\", outputdt=np.timedelta64(6, \"h\")\n",
     ")\n",
     "pset.execute(\n",
-    "    [parcels.kernels.AdvectionRK4],\n",
+    "    [parcels.kernels.AdvectionRK2],\n",
     "    runtime=np.timedelta64(5, \"D\"),\n",
     "    dt=np.timedelta64(1, \"h\"),\n",
     "    output_file=output_file,\n",