Renaming time to t (#2732)

* Changing a few last lon/lat to x/y

* Changing time to t in _core and tests

* Changing time to t in tutorials

* Fixing particles.time in explanations

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, y, and x, 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 t, 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`, `y` and `x`.
+3. Initial conditions for each `Variable` defined in the `Particle`, most notably the release coordinates of `t`, `z`, `y` and `x`.
 
 ```python
-time = np.array([0])
+t = np.array([0])
 z = 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, y=y, x=x)
+pset = parcels.ParticleSet(fieldset=fieldset, pclass=parcels.Particle, t=t, z=z, y=y, x=x)
 ```
 
 ```{admonition} 🖥️ Learn more about how to create ParticleSets
@@ -126,7 +126,7 @@ def AdvectionEE(particles, fieldset):
 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.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](../user_guide/examples/explanation_kernelloop.md) to understand why.
+It is advised _not_ to update the particle coordinates (`particles.t`, `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](../user_guide/examples/explanation_kernelloop.md) 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`, `y` and `x`, 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 `t`, `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

@@ -80,7 +80,7 @@
     "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, x=lon, y=lat, z=z, time=time\n",
+    "    fieldset=fieldset, pclass=parcels.Particle, x=lon, y=lat, z=z, t=time\n",
     ")\n",
     "\n",
     "output_file = parcels.ParticleFile(\"output.parquet\", outputdt=np.timedelta64(2, \"h\"))"
@@ -194,7 +194,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "As you may have noticed above, the `time` is shown as a `float64` (in seconds) in `df_polars`. That is because `polars.read_parquet` does not automatically convert the cftime. To handle this, we also provide a helper function `parcels.read_particlefile` to read ParticleFiles, which does automatically convert the cftime. "
+    "As you may have noticed above, the `t` is shown as a `float64` (in seconds) in `df_polars`. That is because `polars.read_parquet` does not automatically convert the cftime. To handle this, we also provide a helper function `parcels.read_particlefile` to read ParticleFiles, which does automatically convert the cftime. "
    ]
   },
   {
@@ -226,7 +226,7 @@
    "source": [
     "for traj in df_particles.partition_by(\"particle_id\", maintain_order=True):\n",
     "    time_origin = pd.Timestamp(fieldset.time_interval.left).to_pydatetime()\n",
-    "    time_in_hour = (traj[\"time\"] - time_origin).dt.total_hours()\n",
+    "    time_in_hour = (traj[\"t\"] - time_origin).dt.total_hours()\n",
     "    traj_id = traj[\"particle_id\"][0]\n",
     "    print(f\"Particle {traj_id}: \" + \"\".join(f\"{int(t):2d}  \" for t in time_in_hour))"
    ]
@@ -303,7 +303,7 @@
    "source": [
     "time_step = np.timedelta64(18, \"h\")\n",
     "time_to_plot = fieldset.time_interval.left + time_step\n",
-    "particles = df_particles.filter(pl.col(\"time\") == pl.lit(time_to_plot))\n",
+    "particles = df_particles.filter(pl.col(\"t\") == pl.lit(time_to_plot))\n",
     "\n",
     "fig, ax = plt.subplots(figsize=(5, 3))\n",
     "ax.plot(particles[\"x\"], particles[\"y\"], \"o\")\n",
@@ -327,7 +327,7 @@
    "source": [
     "time_step = np.timedelta64(18, \"h\")\n",
     "particles = df_particles.filter(\n",
-    "    (pl.col(\"time\") - pl.col(\"time\").min().over(\"particle_id\")) == pl.lit(time_step)\n",
+    "    (pl.col(\"t\") - pl.col(\"t\").min().over(\"particle_id\")) == pl.lit(time_step)\n",
     ")\n",
     "\n",
     "fig, ax = plt.subplots(figsize=(5, 3))\n",
@@ -355,9 +355,9 @@
     "    distance = np.sqrt(\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",
+    "    ax[0].plot(traj[\"t\"], distance, \".-\", label=f\"P{traj['particle_id'][0]}\")\n",
     "\n",
-    "    rel_time = (traj[\"time\"] - traj[\"time\"][0]).dt.total_hours()\n",
+    "    rel_time = (traj[\"t\"] - traj[\"t\"][0]).dt.total_hours()\n",
     "    ax[1].plot(rel_time, distance, \".-\", label=f\"P{traj['particle_id'][0]}\")\n",
     "\n",
     "ax[0].set_xlabel(\"Date\")\n",
@@ -410,8 +410,8 @@
     "time_step = np.timedelta64(2, \"h\")  # time step for animation frames\n",
     "\n",
     "timerange = np.arange(\n",
-    "    np.nanmin(df_particles[\"time\"]),\n",
-    "    np.nanmax(df_particles[\"time\"]) + time_step,\n",
+    "    np.nanmin(df_particles[\"t\"]),\n",
+    "    np.nanmax(df_particles[\"t\"]) + time_step,\n",
     "    time_step,\n",
     ")\n",
     "\n",
@@ -436,7 +436,7 @@
     "ax.add_feature(cfeature.LAND)\n",
     "\n",
     "# --> plot first timestep\n",
-    "particles = df_particles.filter(pl.col(\"time\") == pl.lit(timerange[0]))\n",
+    "particles = df_particles.filter(pl.col(\"t\") == pl.lit(timerange[0]))\n",
     "scatter = ax.scatter(\n",
     "    particles[\"x\"],\n",
     "    particles[\"y\"],\n",
@@ -460,7 +460,7 @@
     "    title.set_text(f\"Particles at t = {t_str}\")\n",
     "\n",
     "    # Find particles at current time\n",
-    "    particles = df_particles.filter(pl.col(\"time\") == pl.lit(timerange[i]))\n",
+    "    particles = df_particles.filter(pl.col(\"t\") == pl.lit(timerange[i]))\n",
     "\n",
     "    if len(particles) > 0:\n",
     "        scatter.set_offsets(np.c_[particles[\"x\"], particles[\"y\"]])\n",
@@ -475,8 +475,8 @@
     "            for traj in particles[\"particle_id\"].unique():\n",
     "                traj_trail = df_particles.filter(\n",
     "                    (pl.col(\"particle_id\") == traj)\n",
-    "                    & (pl.col(\"time\") >= pl.lit(timerange[max(0, i - trail_length)]))\n",
-    "                    & (pl.col(\"time\") <= pl.lit(timerange[i]))\n",
+    "                    & (pl.col(\"t\") >= pl.lit(timerange[max(0, i - trail_length)]))\n",
+    "                    & (pl.col(\"t\") <= pl.lit(timerange[i]))\n",
     "                )\n",
     "                if len(traj_trail) > 1:\n",
     "                    (trail,) = ax.plot(\n",

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`, `y`, and `x`, but you can easily add
+{py:obj}`parcels.ParticleClass` we want to use. The default particles have `t`, `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, y=lat, x=lon
+    fieldset=fieldset, pclass=parcels.Particle, t=time, z=z, y=lat, x=lon
 )
 ```
 
@@ -168,7 +168,7 @@ 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['x'], df['y'], c=df['time'])
+scatter = plt.scatter(df['x'], df['y'], c=df['t'])
 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)
@@ -211,8 +211,8 @@ 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['x'], df_back['y'], c=df_back['time'])
-particles_at_max_time = df_back.filter(pl.col("time") == df_back["time"].max())
+scatter = plt.scatter(df_back['x'], df_back['y'], c=df_back['t'])
+particles_at_max_time = df_back.filter(pl.col("t") == df_back["t"].max())
 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)
@@ -226,7 +226,7 @@ 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())
+particles_at_min_time = df_back.filter(pl.col("t") == df_back["t"].min())
 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/explanation_interpolation.md

@@ -14,13 +14,13 @@ particles.temperature = fieldset.temperature[particles]
 ````{note}
 The statement above is shorthand for
 ```python
-particles.temperature = fieldset.temperature[particles.time, particles.z, particles.y, particles.x, particles]
+particles.temperature = fieldset.temperature[particles.t, particles.z, particles.y, particles.x, particles]
 ```
 where the `particles` argument at the end provides the grid search algorithm with a first guess for the element indices to interpolate on.
 
 If you want to sample at a different location, or time, that is not necessarily close to the particles location, you can use
 ```python
-particles.temperature = fieldset.temperature[time, z, y, x]
+particles.temperature = fieldset.temperature[t, z, y, x]
 ```
 but this could be slower for curvilinear and unstructured Grids because the entire grid needs to be searched.
 ````
@@ -53,7 +53,7 @@ If we want to create a custom interpolation method, we need to look at the inter
 The `particle_positions` dictionary contains:
 
 ```
-particle_positions = {"time", time, "z", z, "y", y, "x", x}
+particle_positions = {"t", t, "z", z, "y", y, "x", x}
 ```
 
 For structured (`X`) grids, the `grid_positions` dictionary contains:
@@ -63,7 +63,7 @@ grid_positions = {
     "T": {"index": ti, "bcoord": tau},
     "Z": {"index": zi, "bcoord": zeta},
     "Y": {"index": yi, "bcoord": eta},
-    "X": {"index": xi, "bcoord", xsi},
+    "X": {"index": xi, "bcoord": xsi},
 }
 ```
 

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.y, ptcls3.x]\n",
+    "    ptcls3.temp = fieldset.thetao[ptcls3.t, 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",
@@ -183,8 +183,8 @@
     "\n",
     "fig = plt.figure(figsize=(13, 6))\n",
     "ax = plt.axes()\n",
-    "ax.plot(df[\"time\"], df[\"z\"], color=\"gray\")\n",
-    "cb = ax.scatter(df[\"time\"], df[\"z\"], c=df[\"temp\"], s=20, marker=\"o\", zorder=2)\n",
+    "ax.plot(df[\"t\"], df[\"z\"], color=\"gray\")\n",
+    "cb = ax.scatter(df[\"t\"], df[\"z\"], c=df[\"temp\"], s=20, marker=\"o\", zorder=2)\n",
     "ax.set_xlabel(\"Time [days]\")\n",
     "ax.set_ylabel(\"Depth (m)\")\n",
     "ax.invert_yaxis()\n",

docs/user_guide/examples/tutorial_croco_3D.ipynb

@@ -265,8 +265,8 @@
     "```python\n",
     "def SampleTempCroco(particles, fieldset):\n",
     "    \"\"\"Sample temperature field on a CROCO sigma grid by first converting z to sigma levels.\"\"\"\n",
-    "    sigma = convert_z_to_sigma_croco(fieldset, particles.time, particles.z, particles.y, particles.x, particles)\n",
-    "    particles.temp = fieldset.T[particles.time, sigma, particles.y, particles.x, particles]"
+    "    sigma = convert_z_to_sigma_croco(fieldset, particles.t, particles.z, particles.y, particles.x, particles)\n",
+    "    particles.temp = fieldset.T[particles.t, sigma, particles.y, particles.x, particles]"
    ]
   },
   {
@@ -278,14 +278,14 @@
     "In particular, the following algorithm is used (note that the RK4 version is slightly more complex than this Euler-Forward version, but the idea is identical). Also note that the vertical velocity is linearly interpolated here, which gives much better results than the default C-grid interpolation.\n",
     "\n",
     "```python\n",
-    "sigma = particles.z / fieldset.h[particles.time, 0, particles.y, particles.x]\n",
+    "sigma = particles.z / fieldset.h[particles.t, 0, particles.y, particles.x]\n",
     "\n",
-    "sigma_levels = convert_z_to_sigma_croco(fieldset, particles.time, particles.z, particles.y, particles.x, particles)\n",
-    "(u, v) = fieldset.UV[time, sigma_levels, particles.y, particles.x, particles]\n",
-    "w = fieldset.W[time, sigma_levels, particles.y, particles.x, particles]\n",
+    "sigma_levels = convert_z_to_sigma_croco(fieldset, particles.t, particles.z, particles.y, particles.x, particles)\n",
+    "(u, v) = fieldset.UV[particles.t, sigma_levels, particles.y, particles.x, particles]\n",
+    "w = fieldset.W[particles.t, sigma_levels, particles.y, particles.x, particles]\n",
     "\n",
     "# scaling the w with the sigma level of the particle\n",
-    "w_sigma = w * sigma / fieldset.h[particles.time, 0, particles.y, particles.x, particles]\n",
+    "w_sigma = w * sigma / fieldset.h[particles.t, 0, particles.y, particles.x, particles]\n",
     "\n",
     "x_new = particles.x + u*particles.dt\n",
     "y_new = particles.y + v*particles.dt\n",
@@ -294,7 +294,7 @@
     "sigma_new = sigma + w_sigma*particles.dt \n",
     "\n",
     "# converting back from sigma to z, at _new_ location\n",
-    "z_new = sigma_new * fieldset.h[particles.time, 0, y_new, x_new, particles]\n",
+    "z_new = sigma_new * fieldset.h[particles.t, 0, y_new, x_new, particles]\n",
     "```"
    ]
   }