First batch of tutorial cleanups after #2719

Author: erikvansebille

docs/getting_started/explanation_concepts.md

@@ -13,7 +13,7 @@ Here, we will explain the most important classes and functions. This overview ca
 A Parcels simulation is generally built up from four different components:
 
 1. [**FieldSet**](#1-fieldset). The input dataset of gridded fields (e.g. ocean current velocity, temperature) in which virtual particles are defined.
-2. [**ParticleSet**](#2-particleset). The dataset of virtual particles. These always contain time, z, lat, and lon, for which initial values must be defined. The ParticleSet may also contain other, custom variables.
+2. [**ParticleSet**](#2-particleset). The dataset of virtual particles. These always contain time, z, y, and x, for which initial values must be defined. The ParticleSet may also contain other, custom variables.
 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.
 
@@ -82,16 +82,16 @@ Once the environment has a `parcels.FieldSet` object, you can start defining you
 
 1. The `parcels.FieldSet` object in which the particles will be released.
 2. The type of `parcels.Particle`: A default `Particle` or a custom `Particle`-type with additional `Variable`s (see the [custom kernel example](custom-kernel)).
-3. Initial conditions for each `Variable` defined in the `Particle`, most notably the release coordinates of `time`, `z`, `lat` and `lon`.
+3. Initial conditions for each `Variable` defined in the `Particle`, most notably the release coordinates of `time`, `z`, `y` and `x`.
 
 ```python
 time = np.array([0])
 z = np.array([0])
-lat = np.array([0])
-lon = np.array([0])
+y = np.array([0])
+x = np.array([0])
 
 # Create a ParticleSet
-pset = parcels.ParticleSet(fieldset=fieldset, pclass=parcels.Particle, time=time, z=z, lat=lat, lon=lon)
+pset = parcels.ParticleSet(fieldset=fieldset, pclass=parcels.Particle, time=time, z=z, y=y, x=x)
 ```
 
 ```{admonition} 🖥️ Learn more about how to create ParticleSets
@@ -103,7 +103,7 @@ pset = parcels.ParticleSet(fieldset=fieldset, pclass=parcels.Particle, time=time
 
 A **`parcels.Kernel`** object is a little snippet of code, which is applied to the particles in the `ParticleSet`, for every time step during a simulation. Kernels define the computation or numerical integration done by Parcels, and can represent many processes such as advection, ageing, growth, or simply the sampling of a field.
 
-Advection of a particle by the flow, the change in position $\mathbf{x}(t) = (lon(t), lat(t))$ at time $t$, can be described by the equation:
+Advection of a particle by the flow, the change in position $\mathbf{x}(t) = (x(t), y(t))$ at time $t$, can be described by the equation:
 
 $$
 \begin{aligned}
@@ -113,20 +113,20 @@ $$
 
 where $\mathbf{v}(\mathbf{x},t) = (u(\mathbf{x},t), v(\mathbf{x},t))$ describes the ocean velocity field at position $\mathbf{x}$ at time $t$.
 
-In Parcels, we can write a kernel function which integrates this equation at each timestep `particles.dt`. To do so, we need the ocean velocity field `fieldset.UV` at the `particles` location, and compute the change in position, `particles.dlon` and `particles.dlat`.
+In Parcels, we can write a kernel function which integrates this equation at each timestep `particles.dt`. To do so, we need the ocean velocity field `fieldset.UV` at the `particles` location, and compute the change in position, `particles.dx` and `particles.dy`.
 
 ```python
 def AdvectionEE(particles, fieldset):
     """Advection of particles using Explicit Euler (aka Euler Forward) integration."""
     (u1, v1) = fieldset.UV[particles]
-    particles.dlon += u1 * particles.dt
-    particles.dlat += v1 * particles.dt
+    particles.dx += u1 * particles.dt
+    particles.dy += v1 * particles.dt
 ```
 
 Basic kernels are included in Parcels to compute advection and diffusion. The standard advection kernel is `parcels.kernels.AdvectionRK2`, a [second-order Runge-Kutta integrator](https://en.wikipedia.org/wiki/Runge%E2%80%93Kutta_methods#The_Runge%E2%80%93Kutta_method) of the advection function.
 
 ```{warning}
-It is advised _not_ to update the particle coordinates (`particles.time`, `particles.z`, `particles.lat`, or `particles.lon`) directly within a Kernel, as that can negatively interfere with the way that particle movements by different kernels are vectorially added. Use a change in the coordinates: `particles.dlon`, `particles.dlat` and/or `particles.dz`. Read the [kernel loop tutorial](https://docs.oceanparcels.org/en/latest/examples/tutorial_kernelloop.html) to understand why.
+It is advised _not_ to update the particle coordinates (`particles.time`, `particles.z`, `particles.y`, or `particles.x`) directly within a Kernel, as that can negatively interfere with the way that particle movements by different kernels are vectorially added. Use a change in the coordinates: `particles.dy`, `particles.dx` and/or `particles.dz`. Read the [kernel loop tutorial](https://docs.oceanparcels.org/en/latest/examples/tutorial_kernelloop.html) to understand why.
 ```
 
 (custom-kernel)=
@@ -186,7 +186,7 @@ pset.execute(kernels=kernels, dt=dt, runtime=runtime)
 
 ### Output
 
-To analyse the particle data generated in the simulation, we need to define a `parcels.ParticleFile` and add it as an argument to `parcels.ParticleSet.execute()`. The output will be written in a [parquet format](https://parquet.apache.org/), which can be opened as a `polars.DataFrame`. The dataset will contain the particle data with at least `time`, `z`, `lat` and `lon`, for each particle at timesteps defined by the `outputdt` argument.
+To analyse the particle data generated in the simulation, we need to define a `parcels.ParticleFile` and add it as an argument to `parcels.ParticleSet.execute()`. The output will be written in a [parquet format](https://parquet.apache.org/), which can be opened as a `polars.DataFrame`. The dataset will contain the particle data with at least `time`, `z`, `y` and `x`, for each particle at timesteps defined by the `outputdt` argument.
 
 There are many ways to analyze particle output, and although we provide [a short tutorial to get started](./tutorial_output.ipynb), we recommend writing your own analysis code and checking out [related Lagrangian analysis projects in our community page](../community/index.md#analysis-code).
 

docs/getting_started/tutorial_output.ipynb

@@ -77,11 +77,11 @@
     "npart = 10  # number of particles to be released\n",
     "lon = 32 * np.ones(npart)\n",
     "lat = np.linspace(-32.5, -30.5, npart, dtype=np.float32)\n",
-    "time = ds_fields.time.values[0] + np.arange(0, npart) * np.timedelta64(2, \"h\")\n",
     "z = np.repeat(ds_fields.depth.values[0], npart)\n",
+    "time = ds_fields.time.values[0] + np.arange(0, npart) * np.timedelta64(2, \"h\")\n",
     "\n",
     "pset = parcels.ParticleSet(\n",
-    "    fieldset=fieldset, pclass=parcels.Particle, lon=lon, lat=lat, time=time, z=z\n",
+    "    fieldset=fieldset, pclass=parcels.Particle, x=lon, y=lat, z=z, time=time\n",
     ")\n",
     "\n",
     "output_file = parcels.ParticleFile(\"output.parquet\", outputdt=np.timedelta64(2, \"h\"))"
@@ -263,7 +263,7 @@
    "outputs": [],
    "source": [
     "fig, ax = plt.subplots(figsize=(5, 3))\n",
-    "ax.plot(df_particles[\"lon\"], df_particles[\"lat\"], \".-\")\n",
+    "ax.plot(df_particles[\"x\"], df_particles[\"y\"], \".-\")\n",
     "plt.show()"
    ]
   },
@@ -283,7 +283,7 @@
     "fig, ax = plt.subplots(figsize=(5, 3))\n",
     "for traj in df_particles.partition_by(\"particle_id\", maintain_order=True):\n",
     "    traj_id = traj[\"particle_id\"][0]\n",
-    "    ax.plot(traj[\"lon\"], traj[\"lat\"], \".-\", label=f\"P{traj_id}\")\n",
+    "    ax.plot(traj[\"x\"], traj[\"y\"], \".-\", label=f\"P{traj_id}\")\n",
     "ax.legend(loc=\"center left\", bbox_to_anchor=(1.02, 0.5), borderaxespad=0.0)\n",
     "plt.tight_layout()\n",
     "plt.show()"
@@ -307,7 +307,7 @@
     "particles = df_particles.filter(pl.col(\"time\") == pl.lit(time_to_plot))\n",
     "\n",
     "fig, ax = plt.subplots(figsize=(5, 3))\n",
-    "ax.plot(particles[\"lon\"], particles[\"lat\"], \"o\")\n",
+    "ax.plot(particles[\"x\"], particles[\"y\"], \"o\")\n",
     "title_time = pd.to_datetime(time_to_plot).strftime(\"%Y-%m-%d %H:%M:%S\")\n",
     "ax.set_title(f\"Particle locations at {title_time}\")\n",
     "plt.show()"
@@ -332,7 +332,7 @@
     ")\n",
     "\n",
     "fig, ax = plt.subplots(figsize=(5, 3))\n",
-    "ax.plot(particles[\"lon\"], particles[\"lat\"], \"o\")\n",
+    "ax.plot(particles[\"x\"], particles[\"y\"], \"o\")\n",
     "ax.set_title(f\"Particle locations {time_step} after their release\")\n",
     "plt.show()"
    ]
@@ -354,7 +354,7 @@
     "\n",
     "for traj in df_particles.partition_by(\"particle_id\", maintain_order=True):\n",
     "    distance = np.sqrt(\n",
-    "        (traj[\"lon\"] - traj[\"lon\"][0]) ** 2 + (traj[\"lat\"] - traj[\"lat\"][0]) ** 2\n",
+    "        (traj[\"x\"] - traj[\"x\"][0]) ** 2 + (traj[\"y\"] - traj[\"y\"][0]) ** 2\n",
     "    )\n",
     "    ax[0].plot(traj[\"time\"], distance, \".-\", label=f\"P{traj['particle_id'][0]}\")\n",
     "\n",
@@ -439,8 +439,8 @@
     "# --> plot first timestep\n",
     "particles = df_particles.filter(pl.col(\"time\") == pl.lit(timerange[0]))\n",
     "scatter = ax.scatter(\n",
-    "    particles[\"lon\"],\n",
-    "    particles[\"lat\"],\n",
+    "    particles[\"x\"],\n",
+    "    particles[\"y\"],\n",
     "    s=10,\n",
     "    c=[trajectory_to_color[p] for p in particles[\"particle_id\"]],\n",
     ")\n",
@@ -464,7 +464,7 @@
     "    particles = df_particles.filter(pl.col(\"time\") == pl.lit(timerange[i]))\n",
     "\n",
     "    if len(particles) > 0:\n",
-    "        scatter.set_offsets(np.c_[particles[\"lon\"], particles[\"lat\"]])\n",
+    "        scatter.set_offsets(np.c_[particles[\"x\"], particles[\"y\"]])\n",
     "        scatter.set_color([trajectory_to_color[p] for p in particles[\"particle_id\"]])\n",
     "\n",
     "        # --> reset trails\n",
@@ -481,8 +481,8 @@
     "                )\n",
     "                if len(traj_trail) > 1:\n",
     "                    (trail,) = ax.plot(\n",
-    "                        traj_trail[\"lon\"],\n",
-    "                        traj_trail[\"lat\"],\n",
+    "                        traj_trail[\"x\"],\n",
+    "                        traj_trail[\"y\"],\n",
     "                        color=trajectory_to_color[traj],\n",
     "                        linewidth=0.6,\n",
     "                        alpha=0.6,\n",
@@ -516,7 +516,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.14.4"
+   "version": "3.14.6"
   }
  },
  "nbformat": 4,

docs/getting_started/tutorial_quickstart.md

@@ -73,7 +73,7 @@ the virtual particles for which we will calculate the trajectories.
 
 We need to create a {py:obj}`parcels.ParticleSet` object with the particles' initial time and position. The `parcels.ParticleSet`
 object also needs to know about the `FieldSet` in which the particles "live". Finally, we need to specify the type of
-{py:obj}`parcels.ParticleClass` we want to use. The default particles have `time`, `z`, `lat`, and `lon`, but you can easily add
+{py:obj}`parcels.ParticleClass` we want to use. The default particles have `time`, `z`, `y`, and `x`, but you can easily add
 other {py:obj}`parcels.Variable`s such as size, temperature, or age to create your own particles to mimic plastic or an [ARGO float](../user_guide/examples/tutorial_Argofloats.ipynb).
 
 ```{code-cell}
@@ -86,7 +86,7 @@ time = np.repeat(ds_fields.time.values[0], npart) # at initial time of input dat
 z = np.repeat(ds_fields.depth.values[0], npart) # at the first depth (surface)
 
 pset = parcels.ParticleSet(
-    fieldset=fieldset, pclass=parcels.Particle, time=time, z=z, lat=lat, lon=lon
+    fieldset=fieldset, pclass=parcels.Particle, time=time, z=z, y=lat, x=lon
 )
 ```
 
@@ -168,8 +168,8 @@ Let's verify that Parcels has computed the advection of the virtual particles!
 import matplotlib.pyplot as plt
 
 # plot positions and color particles by time
-scatter = plt.scatter(df['lon'], df['lat'], c=df['time'])
-plt.scatter(df['lon'][:npart], df['lat'][:npart], facecolors="none", edgecolors='r') # starting positions
+scatter = plt.scatter(df['x'], df['y'], c=df['time'])
+plt.scatter(df['x'][:npart], df['y'][:npart], facecolors="none", edgecolors='r') # starting positions
 plt.scatter(lon, lat, facecolors="none", edgecolors='r') # starting positions
 plt.xlim(31,33)
 plt.ylabel("Latitude [deg N]")
@@ -211,9 +211,9 @@ When we check the output, we can see that the particles have returned to their o
 ```{code-cell}
 df_back = parcels.read_particlefile("output-backwards.parquet")
 
-scatter = plt.scatter(df_back['lon'], df_back['lat'], c=df_back['time'])
+scatter = plt.scatter(df_back['x'], df_back['y'], c=df_back['time'])
 particles_at_max_time = df_back.filter(pl.col("time") == df_back["time"].max())
-plt.scatter(particles_at_max_time['lon'], particles_at_max_time['lat'], facecolors="none", edgecolors='r') # starting positions
+plt.scatter(particles_at_max_time['x'], particles_at_max_time['y'], facecolors="none", edgecolors='r') # starting positions
 plt.xlabel("Longitude [deg E]")
 plt.xlim(31,33)
 plt.ylabel("Latitude [deg N]")
@@ -227,6 +227,6 @@ Using Euler forward advection, the final positions are equal to the original pos
 ```{code-cell}
 # testing that final location == original location
 particles_at_min_time = df_back.filter(pl.col("time") == df_back["time"].min())
-np.testing.assert_almost_equal(particles_at_min_time["lat"], lat, 2)
-np.testing.assert_almost_equal(particles_at_min_time['lon'], lon, 2)
+np.testing.assert_almost_equal(particles_at_min_time["y"], lat, 2)
+np.testing.assert_almost_equal(particles_at_min_time['x'], lon, 2)
 ```

docs/user_guide/examples/tutorial_Argofloats.ipynb

@@ -63,7 +63,7 @@
     "\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.temp = fieldset.thetao[ptcls3.time, ptcls3.z, ptcls3.y, ptcls3.x]\n",
     "    next_phase = ptcls3.z + ptcls3.dz <= mindepth\n",
     "    ptcls3.cycle_phase[next_phase] = 4\n",
     "    ptcls3.dz[next_phase] = mindepth - ptcls3.z[next_phase]  # avoid overshoot\n",
@@ -135,8 +135,8 @@
     "pset = parcels.ParticleSet(\n",
     "    fieldset=fieldset,\n",
     "    pclass=ArgoParticle,\n",
-    "    lon=[32],\n",
-    "    lat=[-31],\n",
+    "    x=[32],\n",
+    "    y=[-31],\n",
     "    z=[mindepth],\n",
     ")\n",
     "\n",
@@ -210,8 +210,8 @@
     "fig = plt.figure(figsize=(13, 8))\n",
     "ax = plt.axes(projection=\"3d\")\n",
     "ax.view_init(azim=-145)\n",
-    "ax.plot3D(df[\"lon\"], df[\"lat\"], df[\"z\"], color=\"gray\")\n",
-    "cb = ax.scatter(df[\"lon\"], df[\"lat\"], df[\"z\"], c=df[\"temp\"], s=20, marker=\"o\", zorder=2)\n",
+    "ax.plot3D(df[\"x\"], df[\"y\"], df[\"z\"], color=\"gray\")\n",
+    "cb = ax.scatter(df[\"x\"], df[\"y\"], df[\"z\"], c=df[\"temp\"], s=20, marker=\"o\", zorder=2)\n",
     "ax.set_xlabel(\"Longitude\")\n",
     "ax.set_ylabel(\"Latitude\")\n",
     "ax.set_zlabel(\"Depth (m)\")\n",
@@ -223,7 +223,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Parcels:test (3.14.4)",
+   "display_name": "Parcels:test (3.14.6)",
    "language": "python",
    "name": "python3"
   },
@@ -237,7 +237,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.14.4"
+   "version": "3.14.6"
   }
  },
  "nbformat": 4,