Remove pset.ParticleFile alias

In favour of directly using the ParticleFile object

Author: VeckoTheGecko

parcels/particleset.py

@@ -15,7 +15,6 @@
 from parcels.basegrid import GridType
 from parcels.kernel import Kernel
 from parcels.particle import KernelParticle, Particle, create_particle_data
-from parcels.particlefile import ParticleFile
 from parcels.tools.converters import convert_to_flat_array
 from parcels.tools.loggers import logger
 from parcels.tools.statuscodes import StatusCode
@@ -392,10 +391,6 @@ def InteractionKernel(self, pyfunc_inter):
             return None
         return InteractionKernel(self.fieldset, self._ptype, pyfunc=pyfunc_inter)
 
-    def ParticleFile(self, *args, **kwargs):
-        """Wrapper method to initialise a :class:`parcels.particlefile.ParticleFile` object from the ParticleSet."""
-        return ParticleFile(*args, **kwargs)
-
     def data_indices(self, variable_name, compare_values, invert=False):
         """Get the indices of all particles where the value of `variable_name` equals (one of) `compare_values`.
 

tests/tools/test_warnings.py

@@ -11,6 +11,7 @@
     ParticleSet,
     ParticleSetWarning,
 )
+from parcels.particlefile import ParticleFile
 from tests.utils import TEST_DATA
 
 
@@ -30,7 +31,7 @@ def test_file_warnings(tmp_zarrfile):
         data={"U": np.zeros((1, 1)), "V": np.zeros((1, 1))}, dimensions={"lon": [0], "lat": [0]}
     )
     pset = ParticleSet(fieldset=fieldset, pclass=Particle, lon=[0, 0], lat=[0, 0], time=[0, 1])
-    pfile = pset.ParticleFile(name=tmp_zarrfile, outputdt=2)
+    pfile = ParticleFile(name=tmp_zarrfile, outputdt=2)
     with pytest.warns(ParticleSetWarning, match="Some of the particles have a start time difference.*"):
         pset.execute(AdvectionRK4, runtime=3, dt=1, output_file=pfile)
 

tests/v4/test_advection.py

@@ -17,6 +17,7 @@
 from parcels.field import Field, VectorField
 from parcels.fieldset import FieldSet
 from parcels.particle import Particle, Variable
+from parcels.particlefile import ParticleFile
 from parcels.particleset import ParticleSet
 from parcels.tools.statuscodes import StatusCode
 from parcels.xgrid import XGrid
@@ -64,7 +65,7 @@ def test_advection_zonal_with_particlefile(tmp_store):
     fieldset = FieldSet([U, V, UV])
 
     pset = ParticleSet(fieldset, lon=np.zeros(npart) + 20.0, lat=np.linspace(0, 80, npart))
-    pfile = pset.ParticleFile(tmp_store, outputdt=np.timedelta64(15, "m"))
+    pfile = ParticleFile(tmp_store, outputdt=np.timedelta64(15, "m"))
     pset.execute(AdvectionRK4, runtime=np.timedelta64(2, "h"), dt=np.timedelta64(15, "m"), output_file=pfile)
 
     assert (np.diff(pset.lon) < 1.0e-4).all()

tests/v4/test_interpolation.py

@@ -10,6 +10,7 @@
 from parcels.field import Field, VectorField
 from parcels.fieldset import FieldSet
 from parcels.particle import Particle, Variable
+from parcels.particlefile import ParticleFile
 from parcels.particleset import ParticleSet
 from parcels.tools.statuscodes import StatusCode
 from parcels.uxgrid import UxGrid
@@ -169,7 +170,7 @@ def DeleteParticle(particle, fieldset, time):
         if particle.state >= 50:
             particle.state = StatusCode.Delete
 
-    outfile = pset.ParticleFile(f"test_interpolation_v4_{interp_name}", outputdt=np.timedelta64(1, "s"))
+    outfile = ParticleFile(f"test_interpolation_v4_{interp_name}", outputdt=np.timedelta64(1, "s"))
     pset.execute(
         [AdvectionRK4_3D, DeleteParticle],
         runtime=np.timedelta64(4, "s"),

tests/v4/test_particlefile.py

@@ -36,7 +36,7 @@ def fieldset() -> FieldSet:  # TODO v4: Move into a `conftest.py` file and remov
 def test_metadata(fieldset, tmp_zarrfile):
     pset = ParticleSet(fieldset, pclass=Particle, lon=0, lat=0)
 
-    pset.execute(DoNothing, runtime=1, output_file=pset.ParticleFile(tmp_zarrfile, outputdt=np.timedelta64(1, "s")))
+    pset.execute(DoNothing, runtime=1, output_file=ParticleFile(tmp_zarrfile, outputdt=np.timedelta64(1, "s")))
 
     ds = xr.open_zarr(tmp_zarrfile, decode_cf=False)  # TODO v4: Fix metadata and re-enable decode_cf
     assert ds.attrs["parcels_kernels"].lower() == "ParticleDoNothing".lower()
@@ -53,7 +53,7 @@ def test_pfile_array_write_zarr_memorystore(fieldset):
         lat=0.5 * np.ones(npart),
         time=fieldset.time_interval.left,
     )
-    pfile = pset.ParticleFile(zarr_store, outputdt=np.timedelta64(1, "s"))
+    pfile = ParticleFile(zarr_store, outputdt=np.timedelta64(1, "s"))
     pfile.write(pset, time=fieldset.time_interval.left)
 
     ds = xr.open_zarr(zarr_store)
@@ -69,7 +69,7 @@ def test_pfile_array_remove_particles(fieldset, tmp_zarrfile):
         lat=0.5 * np.ones(npart),
         time=fieldset.time_interval.left,
     )
-    pfile = pset.ParticleFile(tmp_zarrfile, outputdt=np.timedelta64(1, "s"))
+    pfile = ParticleFile(tmp_zarrfile, outputdt=np.timedelta64(1, "s"))
     pset._data["time"][:] = fieldset.time_interval.left
     pset._data["time_nextloop"][:] = fieldset.time_interval.left
     pfile.write(pset, time=fieldset.time_interval.left)
@@ -97,7 +97,7 @@ def test_pfile_array_remove_all_particles(fieldset, chunks_obs, tmp_zarrfile):
         time=fieldset.time_interval.left,
     )
     chunks = (npart, chunks_obs) if chunks_obs else None
-    pfile = pset.ParticleFile(tmp_zarrfile, chunks=chunks, outputdt=np.timedelta64(1, "s"))
+    pfile = ParticleFile(tmp_zarrfile, chunks=chunks, outputdt=np.timedelta64(1, "s"))
     pfile.write(pset, time=fieldset.time_interval.left)
     for _ in range(npart):
         pset.remove_indices(-1)
@@ -123,7 +123,7 @@ def Update_lon(particle, fieldset, time):  # pragma: no cover
 
     particle = get_default_particle(np.float64)
     pset = ParticleSet(fieldset, pclass=particle, lon=[0], lat=[0])
-    ofile = pset.ParticleFile(tmp_zarrfile, outputdt=np.timedelta64(10, "us"))
+    ofile = ParticleFile(tmp_zarrfile, outputdt=np.timedelta64(10, "us"))
     pset.execute(
         pset.Kernel(Update_lon),
         runtime=np.timedelta64(1, "ms"),
@@ -155,7 +155,7 @@ def test_write_dtypes_pfile(fieldset, tmp_zarrfile):
     MyParticle = Particle.add_variable(extra_vars)
 
     pset = ParticleSet(fieldset, pclass=MyParticle, lon=0, lat=0, time=fieldset.time_interval.left)
-    pfile = pset.ParticleFile(tmp_zarrfile, outputdt=np.timedelta64(1, "s"))
+    pfile = ParticleFile(tmp_zarrfile, outputdt=np.timedelta64(1, "s"))
     pfile.write(pset, time=fieldset.time_interval.left)
 
     ds = xr.open_zarr(
@@ -196,7 +196,7 @@ def test_pset_repeated_release_delayed_adding_deleting(fieldset, tmp_zarrfile, d
         pclass=MyParticle,
         time=fieldset.time_interval.left + np.array([np.timedelta64(i, "s") for i in range(npart)]),
     )
-    pfile = pset.ParticleFile(tmp_zarrfile, outputdt=abs(dt), chunks=(1, 1))
+    pfile = ParticleFile(tmp_zarrfile, outputdt=abs(dt), chunks=(1, 1))
 
     def IncrLon(particle, fieldset, time):  # pragma: no cover
         particle.sample_var += 1.0
@@ -235,7 +235,7 @@ def Update_lon(particle, fieldset, time):  # pragma: no cover
         lon=[0, 0, 0],
         time=np.array([np.datetime64("2000-01-01") for _ in range(3)]),
     )
-    pfile = pset.ParticleFile(tmp_zarrfile, outputdt=np.timedelta64(1, "s"))
+    pfile = ParticleFile(tmp_zarrfile, outputdt=np.timedelta64(1, "s"))
     pset.execute(pset.Kernel(Update_lon), runtime=np.timedelta64(1, "s"), dt=-np.timedelta64(1, "s"), output_file=pfile)
     ds = xr.open_zarr(tmp_zarrfile)
     trajs = ds["trajectory"][:]
@@ -274,7 +274,7 @@ def SampleP(particle, fieldset, time):  # pragma: no cover
             _ = fieldset.P[particle]  # To trigger sampling of the P field
 
     pset = ParticleSet(fieldset, pclass=XiYiParticle, lon=[0, 0.2], lat=[0.2, 1])
-    pfile = pset.ParticleFile(tmp_zarrfile, outputdt=dt)
+    pfile = ParticleFile(tmp_zarrfile, outputdt=dt)
     pset.execute([SampleP, Get_XiYi, AdvectionRK4], endtime=10 * dt, dt=dt, output_file=pfile)
 
     ds = xr.open_zarr(tmp_zarrfile)
@@ -307,7 +307,7 @@ def Update_lon(particle, fieldset, time):  # pragma: no cover
 
     particle = get_default_particle(np.float64)
     pset = ParticleSet(fieldset, pclass=particle, lon=[0], lat=[0])
-    ofile = pset.ParticleFile(tmp_zarrfile, outputdt=np.timedelta64(50, "ms"))
+    ofile = ParticleFile(tmp_zarrfile, outputdt=np.timedelta64(50, "ms"))
     dt = np.timedelta64(20, "ms")
     pset.execute(pset.Kernel(Update_lon), runtime=6 * dt, dt=dt, output_file=ofile)
 
@@ -324,7 +324,7 @@ def Update_lon(particle, fieldset, time):  # pragma: no cover
 
     particle = get_default_particle(np.float64)
     pset = ParticleSet(fieldset, pclass=particle, lon=[0], lat=[0])
-    ofile = pset.ParticleFile(tmp_zarrfile, outputdt=np.timedelta64(3, "s"))
+    ofile = ParticleFile(tmp_zarrfile, outputdt=np.timedelta64(3, "s"))
     pset.execute(pset.Kernel(Update_lon), runtime=np.timedelta64(11, "s"), dt=np.timedelta64(2, "s"), output_file=ofile)
 
     ds = xr.open_zarr(tmp_zarrfile)
@@ -346,7 +346,7 @@ def setup_pset_execute(*, fieldset: FieldSet, outputdt: timedelta, execute_kwarg
 
     with tempfile.TemporaryDirectory() as dir:
         name = f"{dir}/test.zarr"
-        output_file = pset.ParticleFile(name, outputdt=outputdt)
+        output_file = ParticleFile(name, outputdt=outputdt)
 
         pset.execute(DoNothing, output_file=output_file, **execute_kwargs)
         ds = xr.open_zarr(name).load()

tests/v4/test_particleset_execute.py

@@ -17,6 +17,7 @@
 from parcels._datasets.structured.generated import simple_UV_dataset
 from parcels._datasets.structured.generic import datasets as datasets_structured
 from parcels._datasets.unstructured.generic import datasets as datasets_unstructured
+from parcels.particlefile import ParticleFile
 from parcels.tools.statuscodes import FieldInterpolationError, FieldOutOfBoundError, TimeExtrapolationError
 from parcels.uxgrid import UxGrid
 from parcels.xgrid import XGrid
@@ -433,7 +434,7 @@ def test_uxstommelgyre_pset_execute_output():
         time=[0.0],
         pclass=Particle,
     )
-    output_file = pset.ParticleFile(
+    output_file = ParticleFile(
         name="stommel_uxarray_particles.zarr",  # the file name
         outputdt=np.timedelta64(5, "m"),  # the time step of the outputs
     )

v3to4-breaking-changes.md

@@ -16,3 +16,7 @@
 - `repeatdt` and `lonlatdepth_dtype` have been removed from the ParticleSet.
 - ParticleSet.execute() expects `numpy.datetime64`/`numpy.timedelta.64` for `runtime`, `endtime` and `dt`.
 - `ParticleSet.from_field()`, `ParticleSet.from_line()`, `ParticleSet.from_list()` have been removed.
+
+## ParticleFile
+
+- Particlefiles should be created by `ParticleFile(...)` instead of `pset.ParticleFile(...)`