Merge branch 'v4-dev' into using_fieldset_from_sgrid_in_tutorials

Author: erikvansebille

docs/conf.py

@@ -533,7 +533,7 @@ def linkcode_resolve(domain, info):
 
 # -- Options for autoapi --------------------------------------------------
 autoapi_dirs = ["../src/parcels"]
-# autoapi_add_toctree_entry = False
+autoapi_add_toctree_entry = False
 autoapi_root = "reference"
 autoapi_options = [
     "members",

docs/development/policies.md

@@ -10,7 +10,7 @@ We accept that Parcels developers have their own motivation for using (or not us
 
 Remember that reviews are done by human maintainers - asking us to review code that an AI wrote but you don't understand isn't kind to these maintainers.
 
-The [CLAUDE.md](/CLAUDE.md) file in the repository has additional instructions for AI agents to follow when contributing to Parcels.
+The [CLAUDE.md](https://github.com/Parcels-code/Parcels/blob/HEAD/CLAUDE.md) file in the repository has additional instructions for AI agents to follow when contributing to Parcels.
 
 ## Versioning
 

docs/getting_started/explanation_concepts.md

@@ -17,7 +17,7 @@ A Parcels simulation is generally built up from four different components:
 3. [**Kernels**](#3-kernels). Kernels perform some specific operation on the particles every time step (e.g. advect the particles with the three-dimensional flow; or interpolate the temperature field to the particle location).
 4. [**Execute**](#4-execute). Execute the simulation. The core method which integrates the operations defined in Kernels for a given runtime and timestep, and writes output to a ParticleFile.
 
-We discuss each component in more detail below. The subsections titled **"Learn how to"** link to more detailed [how-to guide notebooks](../user_guide/index.md) and more detailed _explanations_ of Parcels functionality are included under **"Read more about"** subsections. The full list of classes and methods is in the [API reference](../reference.md). If you want to learn by doing, check out the [quickstart tutorial](./tutorial_quickstart.md) to start creating your first Parcels simulation.
+We discuss each component in more detail below. The subsections titled **"Learn how to"** link to more detailed [how-to guide notebooks](../user_guide/index.md) and more detailed _explanations_ of Parcels functionality are included under **"Read more about"** subsections. The full list of classes and methods is in the [API reference](../reference/parcels/index.rst). If you want to learn by doing, check out the [quickstart tutorial](./tutorial_quickstart.md) to start creating your first Parcels simulation.
 
 ```{figure} ../_static/concepts_diagram.png
 :alt: Parcels concepts diagram
@@ -190,6 +190,6 @@ There are many ways to analyze particle output, and although we provide [a short
 
 ```{admonition} 🖥️ Learn how to run a simulation
 :class: seealso
-- [Choose an appropriate timestep and integrator](../user_guide/examples/tutorial_numerical_accuracy.ipynb)
+- [Choose an appropriate timestep and integrator](../user_guide/examples/tutorial_dt_integrators.ipynb)
 - [Work with Parcels output](./tutorial_output.ipynb)
 ```

docs/getting_started/installation.md

@@ -33,7 +33,7 @@ conda activate parcels
 The next time you start a terminal and want to work with Parcels, activate the environment with `conda activate parcels`.
 ```
 
-**Step 4:** Create a Jupyter Notebook or Python script to set up your first Parcels simulation! The [quickstart tutorial](tutorial_quickstart.md) is a great way to get started immediately. You can also first read about the core [Parcels concepts](concepts_overview.md) to familiarize yourself with the classes and methods you will use.
+**Step 4:** Create a Jupyter Notebook or Python script to set up your first Parcels simulation! The [quickstart tutorial](tutorial_quickstart.md) is a great way to get started immediately. You can also first read about the core [Parcels concepts](./explanation_concepts.md) to familiarize yourself with the classes and methods you will use.
 
 ## Installation for developers
 

docs/getting_started/tutorial_quickstart.md

@@ -9,7 +9,7 @@ kernelspec:
 Welcome to the **Parcels** quickstart tutorial, in which we will go through all the necessary steps to run a simulation.
 The code in this notebook can be used as a starting point to run Parcels in your own environment. Along the way we will
 familiarize ourselves with some specific classes and methods. If you are ever confused about one of these and want to
-read more, we have a [concepts overview](concepts_overview.md) discussing them in more detail. Let's dive in!
+read more, we have a [concepts overview](./explanation_concepts.md) discussing them in more detail. Let's dive in!
 
 ## Imports
 

docs/user_guide/examples/tutorial_Argofloats.ipynb

@@ -26,70 +26,62 @@
    "source": [
     "import numpy as np\n",
     "\n",
-    "# Define the new Kernels that mimic Argo vertical movement\n",
+    "# Define the new Kernel that mimics Argo vertical movement\n",
     "driftdepth = 1000  # maximum depth in m\n",
     "maxdepth = 2000  # maximum depth in m\n",
     "vertical_speed = 0.10  # sink and rise speed in m/s\n",
     "cycletime = 10 * 86400  # total time of cycle in seconds\n",
     "drifttime = 9 * 86400  # time of deep drift in seconds\n",
     "\n",
     "\n",
-    "def ArgoPhase1(particles, fieldset):\n",
-    "    def SinkingPhase(p):\n",
-    "        \"\"\"Phase 0: Sinking with vertical_speed until depth is driftdepth\"\"\"\n",
-    "        p.dz += vertical_speed * particles.dt\n",
-    "        p.cycle_phase = np.where(p.z + p.dz >= driftdepth, 1, p.cycle_phase)\n",
-    "        p.dz = np.where(p.z + p.dz >= driftdepth, driftdepth - p.z, p.dz)\n",
+    "def ArgoVerticalMovement(particles, fieldset):\n",
+    "    # Split particles based on their current cycle_phase\n",
+    "    ptcls0 = particles[particles.cycle_phase == 0]\n",
+    "    ptcls1 = particles[particles.cycle_phase == 1]\n",
+    "    ptcls2 = particles[particles.cycle_phase == 2]\n",
+    "    ptcls3 = particles[particles.cycle_phase == 3]\n",
+    "    ptcls4 = particles[particles.cycle_phase == 4]\n",
+    "\n",
+    "    # Phase 0: Sinking with vertical_speed until depth is driftdepth\n",
+    "    ptcls0.dz += vertical_speed * ptcls0.dt\n",
+    "    ptcls0.cycle_phase = np.where(\n",
+    "        ptcls0.z + ptcls0.dz >= driftdepth, 1, ptcls0.cycle_phase\n",
+    "    )\n",
+    "    ptcls0.dz = np.where(\n",
+    "        ptcls0.z + ptcls0.dz >= driftdepth, driftdepth - ptcls0.z, ptcls0.dz\n",
+    "    )\n",
+    "\n",
+    "    # Phase 1: Drifting at depth for drifttime seconds\n",
+    "    ptcls1.drift_age += ptcls1.dt\n",
+    "    ptcls1.cycle_phase = np.where(ptcls1.drift_age >= drifttime, 2, ptcls1.cycle_phase)\n",
+    "    ptcls1.drift_age = np.where(ptcls1.drift_age >= drifttime, 0, ptcls1.drift_age)\n",
+    "\n",
+    "    # Phase 2: Sinking further to maxdepth\n",
+    "    ptcls2.dz += vertical_speed * ptcls2.dt\n",
+    "    ptcls2.cycle_phase = np.where(\n",
+    "        ptcls2.z + ptcls2.dz >= maxdepth, 3, ptcls2.cycle_phase\n",
+    "    )\n",
+    "    ptcls2.dz = np.where(\n",
+    "        ptcls2.z + ptcls2.dz >= maxdepth, maxdepth - ptcls2.z, ptcls2.dz\n",
+    "    )\n",
+    "\n",
+    "    # Phase 3: Rising with vertical_speed until at surface\n",
+    "    ptcls3.dz -= vertical_speed * ptcls3.dt\n",
+    "    ptcls3.temp = fieldset.thetao[ptcls3.time, ptcls3.z, ptcls3.lat, ptcls3.lon]\n",
+    "    ptcls3.cycle_phase = np.where(\n",
+    "        ptcls3.z + ptcls3.dz <= fieldset.mindepth, 4, ptcls3.cycle_phase\n",
+    "    )\n",
+    "    ptcls3.dz = np.where(\n",
+    "        ptcls3.z + ptcls3.dz <= fieldset.mindepth,\n",
+    "        fieldset.mindepth - ptcls3.z,\n",
+    "        ptcls3.dz,\n",
+    "    )\n",
+    "\n",
+    "    # Phase 4: Transmitting at surface until cycletime is reached\n",
+    "    ptcls4.cycle_phase = np.where(ptcls4.cycle_age >= cycletime, 0, ptcls4.cycle_phase)\n",
+    "    ptcls4.cycle_age = np.where(ptcls4.cycle_age >= cycletime, 0, ptcls4.cycle_age)\n",
+    "    ptcls4.temp = np.nan  # no temperature measurement when at surface\n",
     "\n",
-    "    SinkingPhase(particles[particles.cycle_phase == 0])\n",
-    "\n",
-    "\n",
-    "def ArgoPhase2(particles, fieldset):\n",
-    "    def DriftingPhase(p):\n",
-    "        \"\"\"Phase 1: Drifting at depth for drifttime seconds\"\"\"\n",
-    "        p.drift_age += particles.dt\n",
-    "        p.cycle_phase = np.where(p.drift_age >= drifttime, 2, p.cycle_phase)\n",
-    "        p.drift_age = np.where(p.drift_age >= drifttime, 0, p.drift_age)\n",
-    "\n",
-    "    DriftingPhase(particles[particles.cycle_phase == 1])\n",
-    "\n",
-    "\n",
-    "def ArgoPhase3(particles, fieldset):\n",
-    "    def SecondSinkingPhase(p):\n",
-    "        \"\"\"Phase 2: Sinking further to maxdepth\"\"\"\n",
-    "        p.dz += vertical_speed * particles.dt\n",
-    "        p.cycle_phase = np.where(p.z + p.dz >= maxdepth, 3, p.cycle_phase)\n",
-    "        p.dz = np.where(p.z + p.dz >= maxdepth, maxdepth - p.z, p.dz)\n",
-    "\n",
-    "    SecondSinkingPhase(particles[particles.cycle_phase == 2])\n",
-    "\n",
-    "\n",
-    "def ArgoPhase4(particles, fieldset):\n",
-    "    def RisingPhase(p):\n",
-    "        \"\"\"Phase 3: Rising with vertical_speed until at surface\"\"\"\n",
-    "        p.dz -= vertical_speed * particles.dt\n",
-    "        p.temp = fieldset.thetao[p.time, p.z, p.lat, p.lon]\n",
-    "        p.cycle_phase = np.where(p.z + p.dz <= fieldset.mindepth, 4, p.cycle_phase)\n",
-    "        p.dz = np.where(\n",
-    "            p.z + p.dz <= fieldset.mindepth,\n",
-    "            fieldset.mindepth - p.z,\n",
-    "            p.dz,\n",
-    "        )\n",
-    "\n",
-    "    RisingPhase(particles[particles.cycle_phase == 3])\n",
-    "\n",
-    "\n",
-    "def ArgoPhase5(particles, fieldset):\n",
-    "    def TransmittingPhase(p):\n",
-    "        \"\"\"Phase 4: Transmitting at surface until cycletime is reached\"\"\"\n",
-    "        p.cycle_phase = np.where(p.cycle_age >= cycletime, 0, p.cycle_phase)\n",
-    "        p.cycle_age = np.where(p.cycle_age >= cycletime, 0, p.cycle_age)\n",
-    "        p.temp = np.nan  # no temperature measurement when at surface\n",
-    "\n",
-    "    TransmittingPhase(particles[particles.cycle_phase == 4])\n",
-    "\n",
-    "\n",
-    "def ArgoPhase6(particles, fieldset):\n",
     "    particles.cycle_age += particles.dt  # update cycle_age"
    ]
   },
@@ -136,9 +128,7 @@
     "ArgoParticle = parcels.Particle.add_variable(\n",
     "    [\n",
     "        parcels.Variable(\"cycle_phase\", dtype=np.int32, initial=0.0),\n",
-    "        parcels.Variable(\n",
-    "            \"cycle_age\", dtype=np.float32, initial=0.0\n",
-    "        ),  # TODO update to \"timedelta64[s]\"\n",
+    "        parcels.Variable(\"cycle_age\", dtype=np.float32, initial=0.0),\n",
     "        parcels.Variable(\"drift_age\", dtype=np.float32, initial=0.0),\n",
     "        parcels.Variable(\"temp\", dtype=np.float32, initial=np.nan),\n",
     "    ]\n",
@@ -155,12 +145,7 @@
     "\n",
     "# combine Argo vertical movement kernel with built-in Advection kernel\n",
     "kernels = [\n",
-    "    ArgoPhase1,\n",
-    "    ArgoPhase2,\n",
-    "    ArgoPhase3,\n",
-    "    ArgoPhase4,\n",
-    "    ArgoPhase5,\n",
-    "    ArgoPhase6,\n",
+    "    ArgoVerticalMovement,\n",
     "    parcels.kernels.AdvectionRK4,\n",
     "]\n",
     "\n",