Remove to_write="once" option (#2609)

* Removing to_write="once" option

* Update v4-migration.md

* Also remove the (empty) unit test

* Update docstring

* Removing section on initial values and to_write=once

---------

Co-authored-by: Vecko <36369090+VeckoTheGecko@users.noreply.github.com>

Author: erikvansebille

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/examples/tutorial_sampling.ipynb

@@ -303,97 +303,12 @@
     "Note that the Kernels above return the value of `U` and `V` in the units of the grid. That means that for a spherical grid, the velocities are in **degrees/s**. To convert these to **m/s**, see the [UnitConversion tutorial](https://docs.oceanparcels.org/en/latest/examples/tutorial_unitconverters.html).\n",
     "</div>"
    ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Sampling initial values\n"
-   ]
-  },
-  {
-   "attachments": {},
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "In some simulations only the particles initial value within the field is of interest: the variable does not need to be known along the entire trajectory. To reduce computing we can specify the `to_write` argument to the temperature `Variable`. This argument can have three values: `True`, `False` or `'once'`. It determines whether to write the `Variable` to the output file. If we want to know only the initial value, we can enter `'once'` and only the first value will be written to the output file.\n"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "SampleParticleOnce = parcels.Particle.add_variable(\n",
-    "    parcels.Variable(\"temperature\", initial=np.nan, to_write=\"once\")\n",
-    ")\n",
-    "\n",
-    "pset = parcels.ParticleSet(\n",
-    "    fieldset=fieldset,\n",
-    "    pclass=SampleParticleOnce,\n",
-    "    lon=lon,\n",
-    "    lat=lat,\n",
-    "    time=time,\n",
-    "    z=z,\n",
-    ")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "tags": [
-     "hide-output"
-    ]
-   },
-   "outputs": [],
-   "source": [
-    "output_file = parcels.ParticleFile(\"writeonce.zarr\", outputdt=timedelta(hours=1))\n",
-    "\n",
-    "pset.execute(\n",
-    "    [parcels.kernels.AdvectionRK2, SampleT],\n",
-    "    runtime=timedelta(hours=24),\n",
-    "    dt=timedelta(minutes=5),\n",
-    "    output_file=output_file,\n",
-    ")"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "We can compare the output where only the initial value is written to output, with the original simulation, where the temperature at each outputdt is written:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "ds_particles_once = xr.open_zarr(\"writeonce.zarr\")\n",
-    "\n",
-    "plt.figure()\n",
-    "ax = plt.axes()\n",
-    "ax.set_ylabel(\"Temperature [$^{\\\\circ}$C]\")\n",
-    "ax.set_xlabel(\"Observation Number (-)\")\n",
-    "ax.set_ylim(22.2, 24.5)\n",
-    "l1 = ax.plot(ds_particles.obs, ds_particles.temperature.T, color=\"red\")\n",
-    "l2 = ax.plot(\n",
-    "    ds_particles_once.obs,\n",
-    "    np.tile(ds_particles_once.temperature, (ds_particles_once.lon.shape[1], 1)),\n",
-    "    color=\"tab:blue\",\n",
-    ")\n",
-    "ax.legend([l1[0], l2[0]], [\"Write every outputdt\", \"Write once\"])\n",
-    "plt.show()"
-   ]
   }
  ],
  "metadata": {
   "celltoolbar": "Raw-celnotatie",
   "kernelspec": {
-   "display_name": "docs",
+   "display_name": "Parcels:docs (3.14.4)",
    "language": "python",
    "name": "python3"
   },
@@ -407,7 +322,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.14.2"
+   "version": "3.14.4"
   },
   "pycharm": {
    "stem_cell": {

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(