From 276f28cfc303391961d8169efea0a4b0c230fe13 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Mon, 16 Nov 2026 11:49:53 +0100 Subject: [PATCH 01/19] Implement TODO in field init --- src/parcels/_core/field.py | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/src/parcels/_core/field.py b/src/parcels/_core/field.py index 2ab059b28..994a9e49a 100644 --- a/src/parcels/_core/field.py +++ b/src/parcels/_core/field.py @@ -87,11 +87,10 @@ def __init__( name: str, model: ModelData, ): - # TODO PR: Enable isinstance check once ModelData is moved to abc.ModelData - # if not isinstance(model, "ModelData"): - # raise ValueError( - # f"Expected `model` to be a Parcels ModelData object. Got {type(model)}." - # ) + from parcels._core.model import ModelData + + if not isinstance(model, ModelData): + raise ValueError(f"Expected `model` to be a Parcels ModelData object. Got {type(model)}.") _assert_str_and_python_varname(name) From 2a9b9fef524797d14e99bbd841e0f81132ddefaa Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Mon, 16 Nov 2026 11:50:32 +0100 Subject: [PATCH 02/19] Fix TODOs in xgrid The lon, lat, depth are needed in the codebase - the z4d and gtype not --- src/parcels/_core/xgrid.py | 50 +------------------------------------- 1 file changed, 1 insertion(+), 49 deletions(-) diff --git a/src/parcels/_core/xgrid.py b/src/parcels/_core/xgrid.py index c96fee26b..9f8a412ae 100644 --- a/src/parcels/_core/xgrid.py +++ b/src/parcels/_core/xgrid.py @@ -1,7 +1,7 @@ import warnings from collections.abc import Hashable, Sequence from functools import cached_property -from typing import Literal, cast +from typing import cast import numpy as np import numpy.typing as npt @@ -179,12 +179,6 @@ def axes(self) -> list[ptyping.XgridAxis]: @property def lon(self): - """ - Notes - ----- - Included for compatibility with v3 codebase. May be removed in future. - TODO v4: Evaluate - """ if "X" not in self.axes: return np.zeros(1) x_coordinate_name = self.sgrid_metadata.node_coordinates[0] @@ -195,12 +189,6 @@ def lon(self): @property def lat(self): - """ - Notes - ----- - Included for compatibility with v3 codebase. May be removed in future. - TODO v4: Evaluate - """ if "Y" not in self.axes: return np.zeros(1) y_coordinate_name = self.sgrid_metadata.node_coordinates[1] @@ -211,12 +199,6 @@ def lat(self): @property def depth(self): - """ - Notes - ----- - Included for compatibility with v3 codebase. May be removed in future. - TODO v4: Evaluate - """ if "Z" not in self.axes: return np.zeros(1) return self._ds["depth"].values @@ -317,39 +299,9 @@ def localise( if axis in axis_to_var } - @property - def _z4d(self) -> Literal[0, 1]: - """ - Notes - ----- - Included for compatibility with v3 codebase. May be removed in future. - TODO v4: Evaluate - """ - return 1 if self.depth.shape == 4 else 0 - @property def zonal_periodic(self): ... # ? hmmm, from v3, do we still need this? - @property - def _gtype(self): - """This class is created *purely* for compatibility with v3 code and will be removed - or changed in future. - - TODO: Remove - """ - from parcels._core.basegrid import GridType - - if len(self.lon.shape) <= 1: - if self.depth is None or len(self.depth.shape) <= 1: - return GridType.RectilinearZGrid - else: - return GridType.RectilinearSGrid - else: - if self.depth is None or len(self.depth.shape) <= 1: - return GridType.CurvilinearZGrid - else: - return GridType.CurvilinearSGrid - def search(self, z, y, x, ei=None, ti=None, tau=None): ds = self._ds if self.sgrid_metadata.node_coordinates is not None: From 0cf48051545e933e9f947f348d88964ce53e1599 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Mon, 16 Nov 2026 11:52:43 +0100 Subject: [PATCH 03/19] Removing old lists of copernicus names Still leftover from before we had convert functions --- src/parcels/_core/fieldset.py | 36 ----------------------------------- 1 file changed, 36 deletions(-) diff --git a/src/parcels/_core/fieldset.py b/src/parcels/_core/fieldset.py index c87575ae5..e85efdb7c 100644 --- a/src/parcels/_core/fieldset.py +++ b/src/parcels/_core/fieldset.py @@ -446,39 +446,3 @@ def _datetime_to_msg(example_datetime: TimeLike) -> str: def _format_calendar_error_message(field: Field | VectorField, reference_datetime: TimeLike) -> str: return f"Expected field {field.name!r} to have calendar compatible with datetime object {_datetime_to_msg(reference_datetime)}. Got field with calendar {_datetime_to_msg(field.time_interval.left)}. Have you considered using xarray to update the time dimension of the dataset to have a compatible calendar?" - - -_COPERNICUS_MARINE_AXIS_VARNAMES = { - "T": "time", - "Z": "depth", - "Y": "lat", - "X": "lon", -} - - -_COPERNICUS_MARINE_CF_STANDARD_NAME_FALLBACKS = { - "UV": [ - ( - "eastward_sea_water_velocity", - "northward_sea_water_velocity", - ), # GLOBAL_ANALYSISFORECAST_PHY_001_024, MEDSEA_ANALYSISFORECAST_PHY_006_013, BALTICSEA_ANALYSISFORECAST_PHY_003_006, BLKSEA_ANALYSISFORECAST_PHY_007_001, IBI_ANALYSISFORECAST_PHY_005_001, NWSHELF_ANALYSISFORECAST_PHY_004_013, MULTIOBS_GLO_PHY_MYNRT_015_003, MULTIOBS_GLO_PHY_W_3D_REP_015_007 - ( - "surface_geostrophic_eastward_sea_water_velocity", - "surface_geostrophic_northward_sea_water_velocity", - ), # SEALEVEL_GLO_PHY_L4_MY_008_047, SEALEVEL_EUR_PHY_L4_NRT_008_060 - ( - "geostrophic_eastward_sea_water_velocity", - "geostrophic_northward_sea_water_velocity", - ), # MULTIOBS_GLO_PHY_TSUV_3D_MYNRT_015_012 - ( - "sea_surface_wave_stokes_drift_x_velocity", - "sea_surface_wave_stokes_drift_y_velocity", - ), # GLOBAL_ANALYSISFORECAST_WAV_001_027, MEDSEA_MULTIYEAR_WAV_006_012, ARCTIC_ANALYSIS_FORECAST_WAV_002_014, BLKSEA_ANALYSISFORECAST_WAV_007_003, IBI_ANALYSISFORECAST_WAV_005_005, NWSHELF_ANALYSISFORECAST_WAV_004_014 - ("sea_water_x_velocity", "sea_water_y_velocity"), # ARCTIC_ANALYSISFORECAST_PHY_002_001 - ( - "eastward_sea_water_velocity_vertical_mean_over_pelagic_layer", - "northward_sea_water_velocity_vertical_mean_over_pelagic_layer", - ), # GLOBAL_MULTIYEAR_BGC_001_033 - ], - "W": ["upward_sea_water_velocity", "vertical_sea_water_velocity"], -} From 0d7e7e9b0475627fd2c72004a109ea9b59859380 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Mon, 16 Nov 2026 12:00:33 +0100 Subject: [PATCH 04/19] Removing unnecessary/old TODOs --- docs/user_guide/kernels_write_in_kernel.ipynb | 4 +--- src/parcels/_compat_v3.py | 2 -- src/parcels/convert.py | 2 +- 3 files changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/user_guide/kernels_write_in_kernel.ipynb b/docs/user_guide/kernels_write_in_kernel.ipynb index 893b5a752..bc512c845 100644 --- a/docs/user_guide/kernels_write_in_kernel.ipynb +++ b/docs/user_guide/kernels_write_in_kernel.ipynb @@ -70,9 +70,7 @@ "# The file that will write when the `write_kernel` is executed.\n", "output_file_kernel = parcels.ParticleFile(\n", " \"output_kernel.parquet\",\n", - " outputdt=np.timedelta64(\n", - " 2, \"h\"\n", - " ), # TODO: this argument is not relevant for this file, since we will write to it manually in the kernel, but it still needs to be specified when creating the ParticleFile object\n", + " outputdt=np.timedelta64(2, \"h\"),\n", ")" ] }, diff --git a/src/parcels/_compat_v3.py b/src/parcels/_compat_v3.py index 1e1ca9299..f0e497639 100644 --- a/src/parcels/_compat_v3.py +++ b/src/parcels/_compat_v3.py @@ -59,8 +59,6 @@ def particlefile_to_v3_zarr(from_parquet: str | Path | io.BytesIO, to_zarr: str df = pl.read_parquet(from_parquet) table = pq.read_table(from_parquet) - # TODO: Check for available memory here and fail as a safeguard? - # Rename columns to v3 conventions rename_map = {"particle_id": "trajectory", "t": "time", "x": "lon", "y": "lat"} try: diff --git a/src/parcels/convert.py b/src/parcels/convert.py index 3ef433f58..34134791b 100644 --- a/src/parcels/convert.py +++ b/src/parcels/convert.py @@ -407,7 +407,7 @@ def nemo_to_sgrid(*, fields: dict[str, xr.Dataset | xr.DataArray], coords: xr.Da ds["gphif"].attrs["units"] = "degrees" # Update to use lon and lat for internal naming - ds = ds.sgrid.rename({"gphif": "lat", "glamf": "lon"}) # TODO: Logging message about rename + ds = ds.sgrid.rename({"gphif": "lat", "glamf": "lon"}) return ds From 693eec19c0e6edd0660ef0a62e03923e9b258282 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Mon, 16 Nov 2026 14:21:44 +0100 Subject: [PATCH 05/19] Removing not-relevant TODOs I don't think the code becomes clearer if we constantly have to use field.model.grid, instead of field.grid. I actually like the current implementation --- src/parcels/_core/field.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/parcels/_core/field.py b/src/parcels/_core/field.py index 994a9e49a..917083527 100644 --- a/src/parcels/_core/field.py +++ b/src/parcels/_core/field.py @@ -102,7 +102,7 @@ def data(self): return self.model.field_data(self.name) @property - def grid(self): # TODO PR: Remove in favour of referencing model grid directly + def grid(self): return self.model.grid @property @@ -114,7 +114,7 @@ def igrid(self, value): self._igrid = value @property - def time_interval(self): # TODO PR: Remove in favour of referencing model time_interval directly + def time_interval(self): if "time" not in self.model.data[self.name].dims: # This field does not have a time-dimension return None From 44b5953f1521143c783c8931cf01ab82b2b136e6 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Mon, 16 Nov 2026 14:27:25 +0100 Subject: [PATCH 06/19] Moving CalendarError to statuscodes --- src/parcels/_core/fieldset.py | 5 +---- src/parcels/_core/statuscodes.py | 5 +++++ tests/test_fieldset.py | 3 ++- 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/src/parcels/_core/fieldset.py b/src/parcels/_core/fieldset.py index e85efdb7c..b5df87cec 100644 --- a/src/parcels/_core/fieldset.py +++ b/src/parcels/_core/fieldset.py @@ -17,6 +17,7 @@ UnstructuredModelData, create_empty_constant_field_model, ) +from parcels._core.statuscodes import CalendarError from parcels._core.utils.string import _assert_str_and_python_varname from parcels._core.utils.time import get_datetime_type_calendar from parcels._core.utils.time import is_compatible as datetime_is_compatible @@ -415,10 +416,6 @@ def assert_models_have_same_mesh(models: list[ModelData]): ) -class CalendarError(Exception): # TODO: Move to a Parcels errors module - """Exception raised when the calendar of a field is not compatible with the rest of the Fields. The user should ensure that they only add fields to a FieldSet that have compatible CFtime calendars.""" - - def assert_compatible_calendars(fields: Iterable[Field | VectorField]): time_intervals = [f.time_interval for f in fields if f.time_interval is not None] diff --git a/src/parcels/_core/statuscodes.py b/src/parcels/_core/statuscodes.py index 9e39d15dc..4be027e3c 100644 --- a/src/parcels/_core/statuscodes.py +++ b/src/parcels/_core/statuscodes.py @@ -2,6 +2,7 @@ __all__ = [ "AllParcelsErrorCodes", + "CalendarError", "FieldOutOfBoundError", "FieldSamplingError", "KernelError", @@ -84,6 +85,10 @@ def _raise_grid_searching_error(z, y, x): raise GridSearchingError(f"Grid searching failed at (z={z}, y={y}, x={x})") +class CalendarError(ValueError): + """Exception raised when the calendar of a field is not compatible with the rest of the Fields. The user should ensure that they only add fields to a FieldSet that have compatible CFtime calendars.""" + + class GeneralError(RuntimeError): """Utility error class to propagate general errors.""" diff --git a/tests/test_fieldset.py b/tests/test_fieldset.py index 7fd63f5c9..3b76ddb89 100644 --- a/tests/test_fieldset.py +++ b/tests/test_fieldset.py @@ -13,9 +13,10 @@ import parcels.tutorial import tests from parcels import Particle, ParticleFile, ParticleSet, Variable, convert -from parcels._core.fieldset import CalendarError, FieldSet, IncompatibleMeshesException, _datetime_to_msg +from parcels._core.fieldset import FieldSet, IncompatibleMeshesException, _datetime_to_msg from parcels._core.mesh import SphericalMesh from parcels._core.model import _default_vector_field_components, _infer_mesh_from_sgrid_data +from parcels._core.statuscodes import CalendarError from parcels._core.utils.time import TimeInterval from parcels._datasets.structured.generated import simple_UV_dataset, simple_UV_sigma_dataset from parcels._datasets.structured.generic import datasets as datasets_structured From aec86d09f8fa4e4b61dd3736e92ec09f8bf9fc19 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Mon, 16 Nov 2026 14:31:53 +0100 Subject: [PATCH 07/19] Remove TODO on index_search --- src/parcels/_core/index_search.py | 1 - 1 file changed, 1 deletion(-) diff --git a/src/parcels/_core/index_search.py b/src/parcels/_core/index_search.py index bf44debb9..01a9a36e6 100644 --- a/src/parcels/_core/index_search.py +++ b/src/parcels/_core/index_search.py @@ -41,7 +41,6 @@ def _search_1d_array( array of float Barycentric coordinate. """ - # TODO v4: We probably rework this to deal with 0D arrays before this point (as we already know field dimensionality) if len(arr) < 2: return np.zeros(shape=x.shape, dtype=np.int32), np.zeros_like(x) index = np.clip(np.searchsorted(arr, x, side="left") - 1, 0, len(arr) - 2) From 3307fe82dfc6f0698e798381ba2a0861d52fc9bb Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Mon, 16 Nov 2026 14:33:48 +0100 Subject: [PATCH 08/19] Renaming assert_is_compatible function in kernels.py --- src/parcels/_core/kernel.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/parcels/_core/kernel.py b/src/parcels/_core/kernel.py index 5d2167494..68432da25 100644 --- a/src/parcels/_core/kernel.py +++ b/src/parcels/_core/kernel.py @@ -98,7 +98,7 @@ def __init__( self._pclass = pset._pclass for f in kernels: - self.check_fieldsets_in_kernels(f) + self.assert_is_compatible(f) self._kernels: list[Callable] = kernels @@ -131,7 +131,7 @@ def _position_update(self, particles, fieldset): # Update dt in case it's increased in RK45 kernel particles.dt = particles.next_dt - def check_fieldsets_in_kernels(self, kernel): # TODO v4: this can go into another method? assert_is_compatible()? + def assert_is_compatible(self, kernel): """ Checks the integrity of the fieldset with the kernels. From 7dc9d9d4fd195a3c6979740832bbe5d611dd11a2 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Mon, 16 Nov 2026 14:42:33 +0100 Subject: [PATCH 09/19] removing old kernel.funcname property --- src/parcels/_core/kernel.py | 7 ------- src/parcels/_core/particleset.py | 2 +- tests/test_kernel.py | 9 +++------ tests/test_particlefile.py | 4 ++-- 4 files changed, 6 insertions(+), 16 deletions(-) diff --git a/src/parcels/_core/kernel.py b/src/parcels/_core/kernel.py index 68432da25..3b3d77560 100644 --- a/src/parcels/_core/kernel.py +++ b/src/parcels/_core/kernel.py @@ -102,13 +102,6 @@ def __init__( self._kernels: list[Callable] = kernels - @property #! Ported from v3. To be removed in v4? (/find another way to name kernels in output file) - def funcname(self): - ret = "" - for f in self._kernels: - ret += f.__name__ - return ret - @property def pclass(self): return self._pclass diff --git a/src/parcels/_core/particleset.py b/src/parcels/_core/particleset.py index 9743f6263..37c57db8c 100644 --- a/src/parcels/_core/particleset.py +++ b/src/parcels/_core/particleset.py @@ -397,7 +397,7 @@ def execute( if output_file is not None: output_file.set_metadata(self.fieldset.gridset[0].mesh) output_file.set_time_interval(self.fieldset.time_interval) - output_file.metadata["parcels_kernels"] = self._kernel.funcname + output_file.metadata["parcels_kernels"] = " ".join(f.__name__ for f in self._kernel._kernels) dt, sign_dt = _convert_dt_to_float(dt) self._data["dt"][:] = dt diff --git a/tests/test_kernel.py b/tests/test_kernel.py index 4acf908f8..959da1274 100644 --- a/tests/test_kernel.py +++ b/tests/test_kernel.py @@ -64,12 +64,10 @@ def test_kernel_init(fieldset): def test_kernel_merging(fieldset): pset = ParticleSet(fieldset, x=[0.5], y=[0.5]) merged_kernel = Kernel(kernels=[AdvectionRK4, MoveEast, MoveNorth], pset=pset) - assert merged_kernel.funcname == "AdvectionRK4MoveEastMoveNorth" assert len(merged_kernel._kernels) == 3 assert merged_kernel._kernels == [AdvectionRK4, MoveEast, MoveNorth] merged_kernel = Kernel(kernels=[MoveEast, MoveNorth, AdvectionRK4], pset=pset) - assert merged_kernel.funcname == "MoveEastMoveNorthAdvectionRK4" assert len(merged_kernel._kernels) == 3 assert merged_kernel._kernels == [MoveEast, MoveNorth, AdvectionRK4] @@ -86,8 +84,8 @@ def test_kernel_from_list(fieldset): kernels_functions = Kernel(kernels=[AdvectionRK4, MoveEast, MoveNorth], pset=pset) # Check if the kernels were combined correctly - assert kernels_single.funcname == "AdvectionRK4" - assert kernels_functions.funcname == "AdvectionRK4MoveEastMoveNorth" + assert [f.__name__ for f in kernels_single._kernels] == ["AdvectionRK4"] + assert [f.__name__ for f in kernels_functions._kernels] == ["AdvectionRK4", "MoveEast", "MoveNorth"] def test_kernel_from_list_error_checking(fieldset): @@ -105,8 +103,7 @@ def test_kernel_from_list_error_checking(fieldset): Kernel(kernels=[AdvectionRK4, "something else"], pset=pset) with pytest.raises(TypeError, match=r".* should be a function or list of functions.*"): - kernels_mixed = Kernel(kernels=[Kernel(kernels=[AdvectionRK4], pset=pset), MoveEast, MoveNorth], pset=pset) - assert kernels_mixed.funcname == "AdvectionRK4MoveEastMoveNorth" + Kernel(kernels=[Kernel(kernels=[AdvectionRK4], pset=pset), MoveEast, MoveNorth], pset=pset) def test_RK45Kernel_error_no_next_dt(fieldset): diff --git a/tests/test_particlefile.py b/tests/test_particlefile.py index f5b13a865..7d188a9ad 100755 --- a/tests/test_particlefile.py +++ b/tests/test_particlefile.py @@ -44,10 +44,10 @@ def test_metadata(fieldset, tmp_parquet): pset = ParticleSet(fieldset, pclass=Particle, x=0, y=0) ofile = ParticleFile(tmp_parquet, outputdt=np.timedelta64(1, "s")) - pset.execute(DoNothing, runtime=np.timedelta64(1, "s"), dt=np.timedelta64(1, "s"), output_file=ofile) + pset.execute([DoNothing, DoNothing], runtime=np.timedelta64(1, "s"), dt=np.timedelta64(1, "s"), output_file=ofile) tab = pq.read_table(tmp_parquet) - assert tab.schema.metadata[b"parcels_kernels"].decode().lower() == "DoNothing".lower() + assert tab.schema.metadata[b"parcels_kernels"].decode().lower() == "DoNothing DoNothing".lower() @pytest.mark.parametrize("compression", ["zstd", "gzip", "snappy", "brotli", None]) From 17bd3ef888fa4983d0e2b955ff4976099b58f9e3 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Mon, 16 Nov 2026 14:54:07 +0100 Subject: [PATCH 10/19] Move custom Variables init to create_particle_data --- src/parcels/_core/particleset.py | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/src/parcels/_core/particleset.py b/src/parcels/_core/particleset.py index 37c57db8c..089ec55a8 100644 --- a/src/parcels/_core/particleset.py +++ b/src/parcels/_core/particleset.py @@ -135,17 +135,10 @@ def __init__( y=y, x=x, particle_id=particle_ids, + **kwargs, ), ) self._pclass = pclass - - # update initial values provided on ParticleSet creation # TODO: Wrap this into create_particle_data - particle_variables = [v.name for v in pclass.variables] - for kwvar, kwval in kwargs.items(): - if kwvar not in particle_variables: - raise RuntimeError(f"Particle class does not have Variable {kwvar}") - self._data[kwvar][:] = kwval - self._kernel = None def __del__(self): From 60cc9dce1391dacf2b7d84d66c80447feb22d68c Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Mon, 16 Nov 2026 14:58:53 +0100 Subject: [PATCH 11/19] Remove irrelevant TODO in uxgrid As we keep grid.depth (perhaps to be renamed to grid.z) --- src/parcels/_core/uxgrid.py | 6 ------ 1 file changed, 6 deletions(-) diff --git a/src/parcels/_core/uxgrid.py b/src/parcels/_core/uxgrid.py index 3927a8cea..d5510a643 100644 --- a/src/parcels/_core/uxgrid.py +++ b/src/parcels/_core/uxgrid.py @@ -70,12 +70,6 @@ def __init__(self, grid: ux.grid.Grid, z: ux.UxDataArray, mesh: TMesh) -> None: @property def depth(self): - """ - Notes - ----- - Included for compatibility with v3 codebase. May be removed in future. - TODO v4: Evaluate - """ try: _ = self.z.values except KeyError: From aacf7789635c5643978cab63c26338c26721200a Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Mon, 16 Nov 2026 14:59:04 +0100 Subject: [PATCH 12/19] Remove old TODO --- src/parcels/_datasets/remote.py | 1 - 1 file changed, 1 deletion(-) diff --git a/src/parcels/_datasets/remote.py b/src/parcels/_datasets/remote.py index 3dc8d402f..50facf585 100644 --- a/src/parcels/_datasets/remote.py +++ b/src/parcels/_datasets/remote.py @@ -261,7 +261,6 @@ class _Purpose(enum.Enum): ("NemoNorthSeaORCA025-N006_data/V", (_V3Dataset(_ODIE,"data/NemoNorthSeaORCA025-N006_data/ORCA025-N06_200001*05V.nc"), _Purpose.TUTORIAL)), ("NemoNorthSeaORCA025-N006_data/W", (_V3Dataset(_ODIE,"data/NemoNorthSeaORCA025-N006_data/ORCA025-N06_200001*05W.nc"), _Purpose.TUTORIAL)), ("NemoNorthSeaORCA025-N006_data/mesh_mask", (_V3Dataset(_ODIE,"data/NemoNorthSeaORCA025-N006_data/coordinates.nc", _preprocess_drop_time_from_mesh1), _Purpose.TUTORIAL)), - # "POPSouthernOcean_data/t.x1_SAMOC_flux.16900*.nc", # TODO v4: In v3 but should not be in v4 https://github.com/Parcels-code/Parcels/issues/2571#issuecomment-4214476973 # ("SWASH_data/data", (_V3Dataset(_ODIE,"data/SWASH_data/field_00655*.nc"), _Purpose.TUTORIAL)), # ("WOA_data/data", (_V3Dataset(_ODIE,"data/WOA_data/woa18_decav_t*_04.nc", _preprocess_set_cf_calendar_360_day), _Purpose.TUTORIAL)), ("CROCOoverflow_data/data", (_V3Dataset(_ODIE,"data/CROCOOverflow_data/over_his.nc"), _Purpose.TUTORIAL)), From 7750091d766db4ef367cbbc5e69565f6394f21d5 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Mon, 16 Nov 2026 15:22:12 +0100 Subject: [PATCH 13/19] Support for length-1 time --- tests/test_advection.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/test_advection.py b/tests/test_advection.py index e12b05b4b..a4aca57cf 100644 --- a/tests/test_advection.py +++ b/tests/test_advection.py @@ -250,7 +250,7 @@ def SubmergeParticle(particles, fieldset): # pragma: no cover ) def test_length1dimensions(u_value, x_slice, v_value, y_slice, w_value, z_slice): ds = datasets_sgrid["ds_2d_padded_high"].copy()[["U_A_grid", "grid"]] - ds = ds.isel(time=slice(2)) # TODO make this also work for length-1 time dimensions + ds = ds.isel(time=0) ds = ds.rename({"U_A_grid": "U"}) ds["U"] = xr.full_like(ds["U"], u_value) ds["V"] = xr.full_like(ds["U"], v_value) From 5cc0e3429897482ed0600ca2e27fb31fcb3c1722 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Mon, 16 Nov 2026 15:23:00 +0100 Subject: [PATCH 14/19] Moving tests to test_model.py --- tests/test_field.py | 10 ------ tests/test_fieldset.py | 40 --------------------- tests/test_model.py | 79 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 79 insertions(+), 50 deletions(-) create mode 100644 tests/test_model.py diff --git a/tests/test_field.py b/tests/test_field.py index 872bf4bcc..52ad85377 100644 --- a/tests/test_field.py +++ b/tests/test_field.py @@ -71,16 +71,6 @@ def test_field_init_fail_on_float_time_dim(): _ = model.time_interval -# TODO: Move to test_model.py as test_model_time_interval() ? -def test_field_time_interval(): - """Test that field.time_interval delegates correctly to model.time_interval.""" - data = datasets_structured["ds_2d_left"] - model = StructuredModelData.from_sgrid_conventions(data, vector_fields=NOTSET) - field = Field(name="data_g", model=model) - assert field.time_interval.left == np.datetime64("2000-01-01") - assert field.time_interval.right == np.datetime64("2001-01-01") - - def test_vectorfield_init_different_time_intervals(): # Tests that a VectorField raises a ValueError if the component fields have different time domains. dsU = simple_UV_dataset(mesh_str="flat")[["U", "grid"]] diff --git a/tests/test_fieldset.py b/tests/test_fieldset.py index 3b76ddb89..75d360f41 100644 --- a/tests/test_fieldset.py +++ b/tests/test_fieldset.py @@ -1,4 +1,3 @@ -from datetime import timedelta from io import StringIO import cf_xarray # noqa: F401 @@ -233,45 +232,6 @@ def test_default_vector_field_components(data_vars, expected): assert got == expected -def test_multi_model_time_interval(): - ds1 = datasets_structured["ds_2d_left"][["U_A_grid", "V_A_grid", "grid"]] - fieldset = FieldSet.from_sgrid_conventions(ds1) - - ds2 = ds1.copy().rename({"U_A_grid": "U2", "V_A_grid": "V2"}) - ds2["time"] = (ds2["time"].dims, ds2["time"].data + np.timedelta64(timedelta(days=1)), ds2["time"].attrs) - fieldset += FieldSet.from_sgrid_conventions(ds2) - - ds3 = ds1.copy().rename({"U_A_grid": "U3", "V_A_grid": "V3"}) - ds3["time"] = (ds3["time"].dims, ds3["time"].data + np.timedelta64(timedelta(days=2)), ds3["time"].attrs) - fieldset += FieldSet.from_sgrid_conventions(ds3) - - fieldset.add_constant_field("constant_field", 1.0) - - assert len(fieldset.models) == 3 - assert fieldset.constant_model is not None - assert fieldset.time_interval.left == np.datetime64("2000-01-03") - assert fieldset.time_interval.right == np.datetime64("2001-01-01") - - -def test_multi_model_nonoverlapping_time_interval(): - ds1 = datasets_structured["ds_2d_left"][["U_A_grid", "V_A_grid", "grid"]] - fieldset = FieldSet.from_sgrid_conventions(ds1) - - ds2 = ds1.copy().rename({"U_A_grid": "U2", "V_A_grid": "V2"}) - ds2["time"] = (ds2["time"].dims, ds2["time"].data + np.timedelta64(timedelta(days=1000)), ds2["time"].attrs) - fieldset += FieldSet.from_sgrid_conventions(ds2) - - ds3 = ds1.copy().rename({"U_A_grid": "U3", "V_A_grid": "V3"}) - ds3["time"] = (ds3["time"].dims, ds3["time"].data + np.timedelta64(timedelta(days=2000)), ds3["time"].attrs) - fieldset += FieldSet.from_sgrid_conventions(ds3) - - fieldset.add_constant_field("constant_field", 1.0) - - assert len(fieldset.models) == 3 - assert fieldset.constant_model is not None - assert fieldset.time_interval is None - - def test_fieldset_add_incompatible_calendars(): # tests the adding of fieldsets that have incompatible calendars ds1 = datasets_structured["ds_2d_left"][["U_A_grid", "V_A_grid", "grid"]] diff --git a/tests/test_model.py b/tests/test_model.py new file mode 100644 index 000000000..f2e7f8670 --- /dev/null +++ b/tests/test_model.py @@ -0,0 +1,79 @@ +from datetime import timedelta + +import numpy as np +import pytest + +from parcels import Field, FieldSet +from parcels._core.model import StructuredModelData +from parcels._datasets.structured.generic import T as T_structured +from parcels._datasets.structured.generic import datasets as datasets_structured +from parcels._python import NOTSET + + +def test_model_init_fail_on_float_time_dim(): + """Test that accessing time_interval fails when dataset has float time dimension. + + (users are expected to use timedelta64 or datetime). + Time validation has moved from Field.__init__ to ModelData.time_interval. + """ + ds = datasets_structured["ds_2d_left"].copy() + ds["time"] = ( + ds["time"].dims, + np.arange(0, T_structured, dtype="float64"), + ds["time"].attrs, + ) + + model = StructuredModelData.from_sgrid_conventions(ds, vector_fields=NOTSET) + with pytest.raises( + ValueError, + match=r"Are you sure that the time dimension on the xarray dataset is stored as timedelta, datetime or cftime datetime objects\?", + ): + _ = model.time_interval + + +def test_model_time_interval(): + """Test that field.time_interval delegates correctly to model.time_interval.""" + data = datasets_structured["ds_2d_left"] + model = StructuredModelData.from_sgrid_conventions(data, vector_fields=NOTSET) + field = Field(name="data_g", model=model) + assert field.time_interval.left == np.datetime64("2000-01-01") + assert field.time_interval.right == np.datetime64("2001-01-01") + + +def test_multi_model_time_interval(): + ds1 = datasets_structured["ds_2d_left"][["U_A_grid", "V_A_grid", "grid"]] + fieldset = FieldSet.from_sgrid_conventions(ds1) + + ds2 = ds1.copy().rename({"U_A_grid": "U2", "V_A_grid": "V2"}) + ds2["time"] = (ds2["time"].dims, ds2["time"].data + np.timedelta64(timedelta(days=1)), ds2["time"].attrs) + fieldset += FieldSet.from_sgrid_conventions(ds2) + + ds3 = ds1.copy().rename({"U_A_grid": "U3", "V_A_grid": "V3"}) + ds3["time"] = (ds3["time"].dims, ds3["time"].data + np.timedelta64(timedelta(days=2)), ds3["time"].attrs) + fieldset += FieldSet.from_sgrid_conventions(ds3) + + fieldset.add_constant_field("constant_field", 1.0) + + assert len(fieldset.models) == 3 + assert fieldset.constant_model is not None + assert fieldset.time_interval.left == np.datetime64("2000-01-03") + assert fieldset.time_interval.right == np.datetime64("2001-01-01") + + +def test_multi_model_nonoverlapping_time_interval(): + ds1 = datasets_structured["ds_2d_left"][["U_A_grid", "V_A_grid", "grid"]] + fieldset = FieldSet.from_sgrid_conventions(ds1) + + ds2 = ds1.copy().rename({"U_A_grid": "U2", "V_A_grid": "V2"}) + ds2["time"] = (ds2["time"].dims, ds2["time"].data + np.timedelta64(timedelta(days=1000)), ds2["time"].attrs) + fieldset += FieldSet.from_sgrid_conventions(ds2) + + ds3 = ds1.copy().rename({"U_A_grid": "U3", "V_A_grid": "V3"}) + ds3["time"] = (ds3["time"].dims, ds3["time"].data + np.timedelta64(timedelta(days=2000)), ds3["time"].attrs) + fieldset += FieldSet.from_sgrid_conventions(ds3) + + fieldset.add_constant_field("constant_field", 1.0) + + assert len(fieldset.models) == 3 + assert fieldset.constant_model is not None + assert fieldset.time_interval is None From 281df39ad6a274005041cc4a92ec865dc5e9e1a4 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Mon, 16 Nov 2026 15:26:53 +0100 Subject: [PATCH 15/19] Add describe ChunkCachedArray test --- tests/test_fieldset.py | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/tests/test_fieldset.py b/tests/test_fieldset.py index 75d360f41..25227e772 100644 --- a/tests/test_fieldset.py +++ b/tests/test_fieldset.py @@ -662,7 +662,26 @@ def test_fieldset_describe_backends(tmp_path): actual = io.getvalue() assert actual == expected - # TODO: Add test for the ChunkedArray backend (can also refactor this test at the same time) + # Also run with ChunkCachedArray backend (needs a new fieldset instance) + fieldset = FieldSet.from_sgrid_conventions(ds_fset) + fieldset = fieldset.to_chunk_cached_arrays() + + io = StringIO() + expected = """\ +| Name | Type | Grid number | Interp method / value | Parcels backend | +|:-------|:------------|--------------:|:------------------------|:------------------| +| U | Field | 0 | XLinear(...) | ChunkCachedArray | +| V | Field | 0 | XLinear(...) | ChunkCachedArray | +| W | Field | 0 | XLinear(...) | ChunkCachedArray | +| UV | VectorField | 0 | CGrid_Velocity(...) | - | +| UVW | VectorField | 0 | CGrid_Velocity(...) | - | + +mesh: SphericalMesh(radius=6366707.019493707) +time interval: (np.datetime64('2000-01-02T12:00:00.000000000'), np.datetime64('2000-01-12T12:00:00.000000000')) +""" + fieldset.describe(io) + actual = io.getvalue() + assert actual == expected @pytest.mark.filterwarnings("ignore:Time-varying \\(4D\\) z coordinates are experimental") From 58aaa8399a81bb254ae9bc95e54233d38fbef0ec Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Mon, 16 Nov 2026 15:43:41 +0100 Subject: [PATCH 16/19] updates to tests --- tests/test_field.py | 23 ----------------------- tests/test_particlefile.py | 1 - 2 files changed, 24 deletions(-) diff --git a/tests/test_field.py b/tests/test_field.py index 52ad85377..73797d457 100644 --- a/tests/test_field.py +++ b/tests/test_field.py @@ -10,7 +10,6 @@ from parcels._core.model import StructuredModelData from parcels._core.warnings import FieldEvalWarning from parcels._datasets.structured.generated import simple_UV_dataset -from parcels._datasets.structured.generic import T as T_structured from parcels._datasets.structured.generic import datasets as datasets_structured from parcels._datasets.unstructured.generic import _ux_constant_flow_face_centered_2D from parcels._datasets.unstructured.generic import datasets as datasets_unstructured @@ -49,28 +48,6 @@ def test_vectorfield_repr(fieldset): Matches(r"\<.*VectorField object at.*\>").assert_matches(repr(fieldset.UV)) -# TODO: Move to test_model.py ? -def test_field_init_fail_on_float_time_dim(): - """Test that accessing time_interval fails when dataset has float time dimension. - - (users are expected to use timedelta64 or datetime). - Time validation has moved from Field.__init__ to ModelData.time_interval. - """ - ds = datasets_structured["ds_2d_left"].copy() - ds["time"] = ( - ds["time"].dims, - np.arange(0, T_structured, dtype="float64"), - ds["time"].attrs, - ) - - model = StructuredModelData.from_sgrid_conventions(ds, vector_fields=NOTSET) - with pytest.raises( - ValueError, - match=r"Are you sure that the time dimension on the xarray dataset is stored as timedelta, datetime or cftime datetime objects\?", - ): - _ = model.time_interval - - def test_vectorfield_init_different_time_intervals(): # Tests that a VectorField raises a ValueError if the component fields have different time domains. dsU = simple_UV_dataset(mesh_str="flat")[["U", "grid"]] diff --git a/tests/test_particlefile.py b/tests/test_particlefile.py index 7d188a9ad..0c1f0f351 100755 --- a/tests/test_particlefile.py +++ b/tests/test_particlefile.py @@ -361,7 +361,6 @@ def test_pset_execute_outputdt_backwards_fieldset_timevarying(): runtime = timedelta(days=2) dt = -timedelta(minutes=5) - # TODO: Not ideal using the `open_dataset` here, but I'm struggling to recreate this error using the test suite fieldsets we have ds_in = parcels.tutorial.open_dataset("CopernicusMarine_data_for_Argo_tutorial/data") fields = {"U": ds_in["uo"], "V": ds_in["vo"]} ds_fset = convert.copernicusmarine_to_sgrid(fields=fields) From d5d21ec3ede71f35faba5f9df2f476ff1b8fb7c3 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Mon, 16 Nov 2026 15:44:44 +0100 Subject: [PATCH 17/19] Add N816 rule --- pyproject.toml | 7 ++++--- src/parcels/_core/index_search.py | 4 ++-- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 87150e047..18fa97c7a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -112,7 +112,6 @@ ignore = [ 'N802', # We use function names that are camelcased to denote functions 'N806', # We use capitalized variable names within functions in Parcels to denote fields, as well as multidimensional arrays 'N811', # Well, this just seems like a bad rule O_o - 'N816', # TODO: Enable for `src` and consider disabling for notebooks 'N818', # Not all Parcels exceptions should have an "Error" suffix # # TODO: ignore for now (requires more work). Remove ignore once fixed @@ -133,8 +132,10 @@ ignore = [ ] [tool.ruff.lint.per-file-ignores] -# No docstring linting outside the package source -"{tests,docs,tools}/**" = ["D"] +# No docstring or global variable naming linting outside the package source +"{tests,docs,tools}/**" = ["D", "N816"] +"ci/**" = ["N816"] +"*.ipynb" = ["N816"] [tool.ruff.lint.pydocstyle] convention = "numpy" diff --git a/src/parcels/_core/index_search.py b/src/parcels/_core/index_search.py index 01a9a36e6..af4a0cd3d 100644 --- a/src/parcels/_core/index_search.py +++ b/src/parcels/_core/index_search.py @@ -157,7 +157,7 @@ def curvilinear_point_in_cell(grid, y: np.ndarray, x: np.ndarray, yi: np.ndarray return is_in_cell, np.column_stack((xsi, eta)) -_invA = np.array( +_inv_a = np.array( [ [1, 0, 0, 0], [-1, 1, 0, 0], @@ -170,7 +170,7 @@ def curvilinear_point_in_cell(grid, y: np.ndarray, x: np.ndarray, yi: np.ndarray def _bilinear_inverse(px, py, xq, yq): """Solve for (xsi, eta) s.t. bilinear blend of (px, py) corners equals (xq, yq).""" eta_init = -1.0 * np.ones(len(xq), dtype=float) - a, b = np.dot(_invA, px), np.dot(_invA, py) + a, b = np.dot(_inv_a, px), np.dot(_inv_a, py) aa = a[3] * b[2] - a[2] * b[3] bb = a[3] * b[0] - a[0] * b[3] + a[1] * b[2] - a[2] * b[1] + xq * b[3] - yq * a[3] cc = a[1] * b[0] - a[0] * b[1] + xq * b[1] - yq * a[1] From 587eb871353fe5c980e3261d82866d39d6a971d4 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Mon, 16 Nov 2026 16:02:41 +0100 Subject: [PATCH 18/19] Add warning when variables not used in convert --- src/parcels/convert.py | 7 ++++++- tests/test_convert.py | 9 +++++++++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/src/parcels/convert.py b/src/parcels/convert.py index 34134791b..0e02ac8ff 100644 --- a/src/parcels/convert.py +++ b/src/parcels/convert.py @@ -307,7 +307,12 @@ def _normalize_fields(fields: dict[str, xr.Dataset | xr.DataArray]) -> dict[str, f"the DataArray instead (e.g., fields={{{name!r}: ds['']}})." ) normalized[name] = field[name] - # TODO: logging message, warn if multiple fields are in this dataset + ignored = [var for var in field.data_vars if var != name] + if ignored: + logger.warning( + f"fields[{name!r}] selects only {name!r} from the Dataset; " + f"other data variables are ignored for this entry: {ignored}." + ) else: normalized[name] = field.rename(name) return normalized diff --git a/tests/test_convert.py b/tests/test_convert.py index ac7f9ceae..93dbe827e 100644 --- a/tests/test_convert.py +++ b/tests/test_convert.py @@ -372,3 +372,12 @@ def test_mom6_to_sgrid_withdepth(): V = V.expand_dims(depth=[0], axis=1) with pytest.raises(ValueError, match="has more than 2 spatial dimensions"): convert.mom6_to_sgrid(fields={"U": U, "V": V}, coords=coords) + + +def test_normalize_fields_warns_about_other_variables(caplog): + ds = xr.Dataset({"U": ("x", [1.0]), "V": ("x", [2.0])}) + + result = convert._normalize_fields({"U": ds}) + + xr.testing.assert_identical(result["U"], ds["U"]) + assert "other data variables are ignored for this entry: ['V']" in caplog.text From ada53b5bc5aa4300c149a4c5b76ae3464799c0d6 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Wed, 18 Nov 2026 18:23:44 +0100 Subject: [PATCH 19/19] fix typing --- src/parcels/_core/model.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/parcels/_core/model.py b/src/parcels/_core/model.py index 714e444ca..d569ac78b 100644 --- a/src/parcels/_core/model.py +++ b/src/parcels/_core/model.py @@ -424,7 +424,7 @@ def from_ugrid_conventions( assert_vertical_dimensionality(ds, allowed_dimensionality=[1, 3]) - grid = UxGrid(ds.uxgrid, z=ds.coords["zf"], mesh=mesh) # type: ignore[arg-type] # uxarray coords typed as DataArray instead of UxDataArray + grid = UxGrid(ds.uxgrid, z=ds.coords["zf"], mesh=mesh) ds = _discover_ux_U_and_V(ds) vector_fields = resolve_vector_fields(ds, vector_fields)