Merge branch 'main' into push-olvnoqnunqsz

Author: VeckoTheGecko

docs/user_guide/v4-migration.md

@@ -39,6 +39,7 @@ Version 4 of Parcels is unreleased at the moment. The information in this migrat
 - `ParticleFile` output is now in Parquet format
 - `ParticleFile` writing behaviour now errors out if there's existing output (this be being further discussed in https://github.com/Parcels-code/Parcels/issues/2593 )
 - A utility to read in ParticleFile output is now available. `parcels.read_particlefile()`
+- "trajectory" is now called "particle_id" in the particle file output
 
 ## Field
 

src/parcels/_core/particle.py

@@ -155,7 +155,7 @@ def get_default_particle(spatial_dtype: type[np.float32] | type[np.float64]) ->
                 },  # "units" and "calendar" gets updated/set if working with cftime time domain
             ),
             Variable(
-                "trajectory",
+                "particle_id",
                 dtype=np.int64,
                 to_write="once",
                 attrs={

src/parcels/_core/particlefile.py

@@ -177,7 +177,7 @@ def _to_write_particles(particle_data, time):
                 & np.equal(time, particle_data["time"], where=np.isfinite(particle_data["time"]), out=None)
             )  # or dt is NaN and time matches particle_data["time"]
         )
-        & (np.isfinite(particle_data["trajectory"]))
+        & (np.isfinite(particle_data["particle_id"]))
         & (np.isfinite(particle_data["time"]))
     )[0]
 

src/parcels/_core/particleset.py

@@ -49,8 +49,8 @@ class ParticleSet:
         Optional list of initial time values for particles. Default is fieldset.U.grid.time[0]
     repeatdt : datetime.timedelta or float, optional
         Optional interval on which to repeat the release of the ParticleSet. Either timedelta object, or float in seconds.
-    trajectory_ids :
-        Optional list of "trajectory" values (integers) for the particle IDs
+    particle_ids :
+        Optional list of "particle_id" values (integers) for the particle IDs
 
         Other Variables can be initialised using further arguments (e.g. v=... for a Variable named 'v')
     """
@@ -63,7 +63,7 @@ def __init__(
         lat=None,
         z=None,
         time=None,
-        trajectory_ids=None,
+        particle_ids=None,
         **kwargs,
     ):
         self._data = None
@@ -74,8 +74,8 @@ def __init__(
         lat = np.empty(shape=0) if lat is None else np.array(lat).flatten()
         time = np.empty(shape=0) if time is None else np.array(time).flatten()
 
-        if trajectory_ids is None:
-            trajectory_ids = np.arange(lon.size)
+        if particle_ids is None:
+            particle_ids = np.arange(lon.size)
 
         if z is None:
             minz = 0
@@ -116,7 +116,7 @@ def __init__(
                 lat=lat,
                 z=z,
                 time=time,
-                trajectory=trajectory_ids,
+                particle_id=particle_ids,
             ),
         )
         self._ptype = pclass
@@ -177,7 +177,7 @@ def __repr__(self):
         return particleset_repr(self)
 
     def __len__(self):
-        return len(self._data["trajectory"])
+        return len(self._data["particle_id"])
 
     def add(self, particles):
         """Add particles to the ParticleSet. Note that this is an
@@ -208,11 +208,11 @@ def add(self, particles):
             return
 
         if isinstance(particles, type(self)):
-            if len(self._data["trajectory"]) > 0:
-                offset = self._data["trajectory"].max() + 1
+            if len(self._data["particle_id"]) > 0:
+                offset = self._data["particle_id"].max() + 1
             else:
                 offset = 0
-            particles._data["trajectory"] = particles._data["trajectory"] + offset
+            particles._data["particle_id"] = particles._data["particle_id"] + offset
 
         for d in self._data:
             self._data[d] = np.concatenate((self._data[d], particles._data[d]))

tests/test_particlefile.py

@@ -111,7 +111,7 @@ def test_pfile_array_remove_all_particles(fieldset, tmp_parquet):
     pfile.close()
 
     df = pd.read_parquet(tmp_parquet)
-    assert df["trajectory"].nunique() == npart
+    assert df["particle_id"].nunique() == npart
 
 
 def test_write_dtypes_pfile(fieldset, tmp_parquet):
@@ -219,9 +219,9 @@ def test_write_timebackward(fieldset, tmp_parquet):
 
     df = pd.read_parquet(tmp_parquet)
 
-    assert df["trajectory"].dtype == "int64"
+    assert df["particle_id"].dtype == "int64"
     assert bool(
-        df.groupby("trajectory")
+        df.groupby("particle_id")
         .apply(
             lambda x: (np.diff(x["time"]) < 0).all()  # for each particle - set True if it has decreasing time
         )
@@ -302,8 +302,8 @@ def IncreaseAge(particles, fieldset):  # pragma: no cover
 
     df = parcels.read_particlefile(tmp_parquet)
 
-    # Map sorted trajectory IDs to release times (0, 1, ..., npart-1 seconds)
-    for index, df_traj in df.groupby("trajectory"):
+    # Map sorted particle IDs to release times (0, 1, ..., npart-1 seconds)
+    for index, df_traj in df.groupby("particle_id"):
         release_time = time[index]
         np.testing.assert_equal(df_traj["age"].astype("timedelta64[s]").values, (df_traj["time"] - release_time).values)
 
@@ -367,7 +367,7 @@ def test_pset_execute_outputdt_forwards(fieldset):
     dt = timedelta(minutes=5)
 
     df = setup_pset_execute(fieldset=fieldset, outputdt=outputdt, execute_kwargs=dict(runtime=runtime, dt=dt))
-    particle_0_times = df[df.trajectory == 0].time.values
+    particle_0_times = df[df["particle_id"] == 0].time.values
 
     np.testing.assert_equal(np.diff(particle_0_times), outputdt.seconds)
 
@@ -390,7 +390,7 @@ def test_pset_execute_outputdt_backwards(fieldset):
     dt = -timedelta(minutes=5)
 
     df = setup_pset_execute(fieldset=fieldset, outputdt=outputdt, execute_kwargs=dict(runtime=runtime, dt=dt))
-    particle_0_times = df[df.trajectory == 0].time.values
+    particle_0_times = df[df["particle_id"] == 0].time.values
     np.testing.assert_equal(np.diff(particle_0_times), -outputdt.seconds)
 
 
@@ -409,7 +409,7 @@ def test_pset_execute_outputdt_backwards_fieldset_timevarying():
     fieldset = FieldSet.from_sgrid_conventions(ds_fset)
 
     df = setup_pset_execute(outputdt=outputdt, execute_kwargs=dict(runtime=runtime, dt=dt), fieldset=fieldset)
-    particle_0_times = df[df.trajectory == 0].time.values
+    particle_0_times = df[df["particle_id"] == 0].time.values
     np.testing.assert_equal(np.diff(particle_0_times), -outputdt.seconds)
 
 

tests/test_particleset.py

@@ -52,8 +52,8 @@ def test_pset_with_pids(fieldset, offset, npart=100):
     lon = np.linspace(0, 1, npart)
     lat = np.linspace(1, 0, npart)
     trajectory_ids = np.arange(offset, npart + offset)
-    pset = ParticleSet(fieldset, lon=lon, lat=lat, trajectory_ids=trajectory_ids)
-    assert np.allclose([p.trajectory for p in pset], trajectory_ids, atol=1e-12)
+    pset = ParticleSet(fieldset, lon=lon, lat=lat, particle_ids=trajectory_ids)
+    assert np.allclose([p.particle_id for p in pset], trajectory_ids, atol=1e-12)
 
 
 @pytest.mark.parametrize("aslist", [True, False])
@@ -146,14 +146,14 @@ def test_pset_add_explicit(fieldset):
     assert len(pset) == npart
     assert np.allclose([p.lon for p in pset], lon, atol=1e-12)
     assert np.allclose([p.lat for p in pset], lat, atol=1e-12)
-    assert np.allclose(np.diff(pset._data["trajectory"]), np.ones(pset._data["trajectory"].size - 1), atol=1e-12)
+    assert np.allclose(np.diff(pset._data["particle_id"]), np.ones(pset._data["particle_id"].size - 1), atol=1e-12)
 
 
 def test_pset_add_implicit(fieldset):
     pset = ParticleSet(fieldset, lon=np.zeros(3), lat=np.ones(3), pclass=Particle)
     pset += ParticleSet(fieldset, lon=np.ones(4), lat=np.zeros(4), pclass=Particle)
     assert len(pset) == 7
-    assert np.allclose(np.diff(pset._data["trajectory"]), np.ones(6), atol=1e-12)
+    assert np.allclose(np.diff(pset._data["particle_id"]), np.ones(6), atol=1e-12)
 
 
 def test_pset_add_implicit_in_loop(fieldset, npart=10):
@@ -179,12 +179,12 @@ def test_pset_remove_index(fieldset, npart=100):
     indices_to_remove = [0, 10, 20]
     pset.remove_indices(indices_to_remove)
     assert pset.size == 97
-    assert not np.any(np.isin(pset.trajectory, indices_to_remove))
+    assert not np.any(np.isin(pset.particle_id, indices_to_remove))
 
 
 def test_pset_iterator(fieldset):
     npart = 10
     pset = ParticleSet(fieldset, lon=np.zeros(npart), lat=np.ones(npart))
     for i, particle in enumerate(pset):
-        assert particle.trajectory == i
+        assert particle.particle_id == i
     assert i == npart - 1

tests/test_particleset_execute.py

@@ -228,9 +228,9 @@ def DeleteKernel(particles, fieldset):  # pragma: no cover
 
     pset.execute(DeleteKernel, runtime=np.timedelta64(1, "s"), dt=np.timedelta64(1, "s"))
     indices = [i for i in range(npart) if not (40 <= i < 60)]
-    assert [p.trajectory for p in pset] == indices
-    assert pset[70].trajectory == 90
-    assert pset[-1].trajectory == npart - 1
+    assert [p.particle_id for p in pset] == indices
+    assert pset[70].particle_id == 90
+    assert pset[-1].particle_id == npart - 1
     assert pset.size == 80