Remove to_write="once" option

docs/user_guide/examples/tutorial_interaction.ipynb

@@ -112,7 +112,7 @@
     "# Create custom particle class with extra variable that indicates\n",
     "# whether the interaction kernel should be executed on this particle.\n",
     "InteractingParticle = parcels.Particle.add_variable(\n",
-    "    parcels.Variable(\"attractor\", dtype=np.bool_, to_write=\"once\"),\n",
+    "    parcels.Variable(\"attractor\", dtype=np.bool_),\n",
     ")\n",
     "\n",
     "attractor = [\n",

docs/user_guide/v4-migration.md

@@ -40,6 +40,7 @@ Version 4 of Parcels is unreleased at the moment. The information in this migrat
 - `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
+- The `to_write="once"`option has been removed. A variable can now only be either written at every output time step, or not written at all.
 
 ## Field
 

src/parcels/_core/particle.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import operator
-from typing import Any, Literal
+from typing import Any
 
 import numpy as np
 
@@ -11,7 +11,7 @@
 from parcels._reprs import particleclass_repr, variable_repr
 
 __all__ = ["Particle", "ParticleClass", "Variable"]
-_TO_WRITE_OPTIONS = [True, False, "once"]
+_TO_WRITE_OPTIONS = [True, False]
 
 
 class Variable:
@@ -26,9 +26,8 @@ class Variable:
     initial :
         Initial value of the variable. Note that this can also be a Field object,
         which will then be sampled at the location of the particle
-    to_write : bool, 'once', optional
-        Boolean or 'once'. Controls whether Variable is written to NetCDF file.
-        If to_write = 'once', the variable will be written as a time-independent 1D array
+    to_write : bool, optional
+        Controls whether Variable is written to output file.
     attrs : dict, optional
         Attributes to be stored with the variable when written to file. This can include metadata such as units, long_name, etc.
     """
@@ -38,7 +37,7 @@ def __init__(
         name,
         dtype: np.dtype[Any] | type[np.generic] = np.float32,
         initial=0,
-        to_write: bool | Literal["once"] = True,
+        to_write: bool = True,
         attrs: dict | None = None,
     ):
         _assert_str_and_python_varname(name)
@@ -157,7 +156,6 @@ def get_default_particle(spatial_dtype: type[np.float32] | type[np.float64]) ->
             Variable(
                 "particle_id",
                 dtype=np.int64,
-                to_write="once",
                 attrs={
                     "long_name": "Unique identifier for each particle",
                     "cf_role": "trajectory_id",

tests/test_particlefile.py

@@ -142,11 +142,6 @@ def test_write_dtypes_pfile(fieldset, tmp_parquet):
         assert tab[f"v_{d.__name__}"].type == pa.from_numpy_dtype(d)
 
 
-def test_variable_written_once():
-    # Test that a vaiable is only written once. This should also work with gradual particle release (so the written once time is actually after the release of the particle)
-    ...
-
-
 @pytest.mark.skip(reason="Pending ParticleFile refactor; see issue #2386")
 @pytest.mark.parametrize("dt", [-np.timedelta64(1, "s"), np.timedelta64(1, "s")])
 @pytest.mark.parametrize("maxvar", [2, 4, 10])
@@ -156,7 +151,7 @@ def test_pset_repeated_release_delayed_adding_deleting(fieldset, tmp_parquet, dt
     fieldset.add_constant("maxvar", maxvar)
 
     MyParticle = Particle.add_variable(
-        [Variable("sample_var", initial=0.0), Variable("v_once", dtype=np.float64, initial=0.0, to_write="once")]
+        [Variable("sample_var", initial=0.0), Variable("v_once", dtype=np.float64, initial=0.0)]
     )
 
     pset = ParticleSet(