Merge remote-tracking branch 'origin/main' into v/refactor-interp

VeckoTheGecko · VeckoTheGecko · commit ebc6517cefe7 · 2025-01-16T19:04:08.000+01:00
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -2,7 +2,7 @@ name: ci
 on:
   push:
     branches:
-      - "master"
+      - "main"
       - "test-me/*"
   pull_request:
   schedule:
diff --git a/.github/workflows/pypi-release.yml b/.github/workflows/pypi-release.yml
@@ -106,5 +106,5 @@ jobs:
           channels: conda-forge
       - run: conda install -c conda-forge c-compiler pip
       - run: pip install parcels --no-cache
-      - run: curl https://raw.githubusercontent.com/OceanParcels/parcels/master/docs/examples/example_peninsula.py > example_peninsula.py
+      - run: curl https://raw.githubusercontent.com/OceanParcels/parcels/main/docs/examples/example_peninsula.py > example_peninsula.py
       - run: python example_peninsula.py
diff --git a/README.md b/README.md
@@ -5,13 +5,13 @@
 [![Zenodo](https://zenodo.org/badge/DOI/10.5281/zenodo.823561.svg)](https://doi.org/10.5281/zenodo.823561)
 [![Code style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/format.json)](https://github.com/astral-sh/ruff)
 [![unit-tests](https://github.com/OceanParcels/parcels/actions/workflows/ci.yml/badge.svg)](https://github.com/OceanParcels/parcels/actions/workflows/ci.yml)
-[![codecov](https://codecov.io/gh/OceanParcels/parcels/branch/master/graph/badge.svg)](https://codecov.io/gh/OceanParcels/parcels)
+[![codecov](https://codecov.io/gh/OceanParcels/parcels/branch/main/graph/badge.svg)](https://codecov.io/gh/OceanParcels/parcels)
 [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5353/badge)](https://bestpractices.coreinfrastructure.org/projects/5353)
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/OceanParcels/parcels/master?labpath=docs%2Fexamples%2Fparcels_tutorial.ipynb)
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/OceanParcels/parcels/main?labpath=docs%2Fexamples%2Fparcels_tutorial.ipynb)
 
 **Parcels** (**P**robably **A** **R**eally **C**omputationally **E**fficient **L**agrangian **S**imulator) is a set of Python classes and methods to create customisable particle tracking simulations using output from Ocean Circulation models. Parcels can be used to track passive and active particulates such as water, plankton, [plastic](http://www.topios.org/) and [fish](https://github.com/Jacketless/IKAMOANA).
 
-![Arctic-SO-medusaParticles](https://github.com/OceanParcels/oceanparcels_website/blob/master/images/homepage.gif)
+![Arctic-SO-medusaParticles](https://github.com/OceanParcels/oceanparcels_website/blob/main/images/homepage.gif)
 
 _Animation of virtual particles carried by ocean surface flow in the global oceans. The particles are advected with [Parcels](http://oceanparcels.org/) in data from the [NEMO Ocean Model](https://www.nemo-ocean.eu/)._
 
diff --git a/docs/community/contributing.rst b/docs/community/contributing.rst
@@ -25,7 +25,7 @@ What is open source?
 
 Open source is a category of software that is open to the public, meaning that anyone is able to look at, modify, and improve the software. Compare this to closed source software (e.g., Microsoft Word, or Gmail) where only those working for the company on the product are able to look at the source code, or make improvements.
 
-Software being open source allows bugs in the code to be quickly identified and fixed, as well as fosters communities of people involved on projects. Most open source software have permissible licenses making them free to modify, and use even in commercial settings. Parcels, for example, is open source and `licensed under the MIT License <https://github.com/OceanParcels/parcels/blob/master/LICENSE.md>`_.
+Software being open source allows bugs in the code to be quickly identified and fixed, as well as fosters communities of people involved on projects. Most open source software have permissible licenses making them free to modify, and use even in commercial settings. Parcels, for example, is open source and `licensed under the MIT License <https://github.com/OceanParcels/parcels/blob/main/LICENSE.md>`_.
 
 This visibility of the codebase results in a higher quality, as well as a more transparent and stable product. This is important in research for reproducibility, as well as in industry where stability is crucial. Open source is not some niche category of software, but in fact `forms the backbone of modern computing and computing infrastructure <https://www.newstatesman.com/science-tech/2016/08/how-linux-conquered-world-without-anyone-noticing>`_ and is used widely in industry. A lot of the digital services that you use (paid, or free) depend on open source code in one way or another.
 
@@ -72,7 +72,7 @@ Now you have a cloned repo that you have full control over, and a conda environm
 From there:
 
 - create a git branch, implement, commit, and push your changes
-- `create a pull request <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_ (PR) into ``master`` of the original repo making sure to link to the issue that you are working on. Not yet finished with your feature but still want feedback on how you're going? Then mark it as "draft" and ``@ping`` a maintainer. See our `maintainer notes <maintainer.md>`_ to see our PR review workflow.
+- `create a pull request <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_ (PR) into ``main`` of the original repo making sure to link to the issue that you are working on. Not yet finished with your feature but still want feedback on how you're going? Then mark it as "draft" and ``@ping`` a maintainer. See our `maintainer notes <maintainer.md>`_ to see our PR review workflow.
 
 If you made changes to the documentation, and want to render a local version, you can run the command ``sphinx-autobuild --ignore "*.zip" docs docs/_build`` to create a server to automatically rebuild the documentation when you make changes.
 
diff --git a/docs/conf.py b/docs/conf.py
@@ -212,7 +212,7 @@
 html_context = {
     "github_user": "OceanParcels",
     "github_repo": "parcels",
-    "github_version": "master",
+    "github_version": "main",
     "doc_path": "docs",
 }
 
@@ -295,7 +295,9 @@ def linkcode_resolve(domain, info):
     fn = os.path.relpath(fn, start=os.path.dirname(parcels.__file__))
 
     if "-" in parcels.__version__:
-        return f"https://github.com/OceanParcels/parcels/blob/master/parcels/{fn}{linespec}"
+        return (
+            f"https://github.com/OceanParcels/parcels/blob/main/parcels/{fn}{linespec}"
+        )
     else:
         return (
             f"https://github.com/OceanParcels/parcels/blob/"
diff --git a/docs/documentation/index.rst b/docs/documentation/index.rst
@@ -1,7 +1,7 @@
 Documentation and Tutorials
 ===========================
 
-Parcels has several documentation and tutorial Jupyter notebooks and scripts which go through various aspects of Parcels. Static versions of the notebooks are available below via the gallery in the site, with the interactive notebooks being available either completely online at the following `Binder link <https://mybinder.org/v2/gh/OceanParcels/parcels/master?labpath=docs%2Fexamples%2Fparcels_tutorial.ipynb>`_. Following the gallery of notebooks is a list of scripts which provide additional examples to users. You can work with the example notebooks and scripts locally by downloading :download:`parcels_tutorials.zip </_downloads/parcels_tutorials.zip>` and running with your own Parcels installation.
+Parcels has several documentation and tutorial Jupyter notebooks and scripts which go through various aspects of Parcels. Static versions of the notebooks are available below via the gallery in the site, with the interactive notebooks being available either completely online at the following `Binder link <https://mybinder.org/v2/gh/OceanParcels/parcels/main?labpath=docs%2Fexamples%2Fparcels_tutorial.ipynb>`_. Following the gallery of notebooks is a list of scripts which provide additional examples to users. You can work with the example notebooks and scripts locally by downloading :download:`parcels_tutorials.zip </_downloads/parcels_tutorials.zip>` and running with your own Parcels installation.
 
 .. warning::
    In v3.1.0 we updated kernels in the tutorials to use ``parcels.ParcelsRandom`` instead of ``from parcels import ParcelsRandom``. Due to our C-conversion code, using ``parcels.ParcelsRandom`` only works with v3.1.0+. When browsing/downloading the tutorials, it's important that you are using the documentation corresponding to the version of Parcels that you have installed. You can find which parcels version you have installed by doing ``import parcels`` followed by ``print(parcels.__version__)``. If you don't want to use the latest version of Parcels, you can browse prior versions of the documentation by using the version switcher in the bottom right of this page.
diff --git a/docs/examples/tutorial_analyticaladvection.ipynb b/docs/examples/tutorial_analyticaladvection.ipynb
@@ -33,7 +33,7 @@
     "3. Since Analytical Advection does not use timestepping, the `dt` parameter in `pset.execute()` should be set to `np.inf`. For backward-in-time simulations, it should be set to `-np.inf`. \n",
     "4. For time-varying fields, only the 'intermediate timesteps' scheme ([section 2.3 of Döös et al 2017](https://www.geosci-model-dev.net/10/1733/2017/gmd-10-1733-2017.pdf)) is implemented. While there is also a way to also analytically solve the time-evolving fields ([section 2.4 of Döös et al 2017](https://www.geosci-model-dev.net/10/1733/2017/gmd-10-1733-2017.pdf)), this is not yet implemented in Parcels.\n",
     "\n",
-    "We welcome contributions to the further development of this algorithm and in particular the analytical time-varying case. See [here](https://github.com/OceanParcels/parcels/blob/master/parcels/application_kernels/advection.py) for the code of the `AdvectionAnalytical` kernel.\n"
+    "We welcome contributions to the further development of this algorithm and in particular the analytical time-varying case. See [here](https://github.com/OceanParcels/parcels/blob/main/parcels/application_kernels/advection.py) for the code of the `AdvectionAnalytical` kernel.\n"
    ]
   },
   {
diff --git a/environment.yml b/environment.yml
@@ -5,7 +5,6 @@ dependencies:
   - python>=3.10
   - cgen
   - ffmpeg>=3.2.3
-  - git
   - jupyter
   - matplotlib-base>=2.0.2
   - netcdf4>=1.1.9
@@ -19,15 +18,11 @@ dependencies:
   - xarray>=0.10.8
   - cftime>=1.3.1
   - dask>=2.0
-  - nbval
   - scikit-learn
-  - zarr>=2.11.0,!=2.18.0
-
-  # Formatting
-  - black
-  - isort
+  - zarr>=2.11.0,!=2.18.0,<3
 
   # Testing
+  - nbval
   - pytest
   - pytest-html
   - coverage
diff --git a/parcels/_typing.py b/parcels/_typing.py
@@ -26,7 +26,6 @@ class ParcelsAST(ast.AST):
     "bgrid_w_velocity",
     "cgrid_velocity",
     "linear_invdist_land_tracer",
-    "nearest",
     "bgrid_tracer",
     "cgrid_tracer",
 ]  # corresponds with `tracer_interp_method`
diff --git a/parcels/particleset.py b/parcels/particleset.py
@@ -14,7 +14,7 @@
 from parcels._compat import MPI
 from parcels.application_kernels.advection import AdvectionRK4
 from parcels.compilation.codecompiler import GNUCompiler
-from parcels.field import NestedField
+from parcels.field import Field, NestedField
 from parcels.grid import CurvilinearGrid, GridType
 from parcels.interaction.interactionkernel import InteractionKernel
 from parcels.interaction.neighborsearch import (
@@ -32,7 +32,7 @@
 from parcels.tools.global_statics import get_package_dir
 from parcels.tools.loggers import logger
 from parcels.tools.statuscodes import StatusCode
-from parcels.tools.warnings import FileWarning
+from parcels.tools.warnings import ParticleSetWarning
 
 __all__ = ["ParticleSet"]
 
@@ -174,6 +174,8 @@ def ArrayClass_init(self, *args, **kwargs):
             raise NotImplementedError("If fieldset.time_origin is not a date, time of a particle must be a double")
         time = np.array([self.time_origin.reltime(t) if _convert_to_reltime(t) else t for t in time])
         assert lon.size == time.size, "time and positions (lon, lat, depth) do not have the same lengths."
+        if isinstance(fieldset.U, Field) and (not fieldset.U.allow_time_extrapolation):
+            _warn_particle_times_outside_fieldset_time_bounds(time, fieldset.U.grid.time_full)
 
         if lonlatdepth_dtype is None:
             lonlatdepth_dtype = self.lonlatdepth_dtype_from_field_interp_method(fieldset.U)
@@ -792,7 +794,7 @@ def from_particlefile(
                 f"Note that the `repeatdt` argument is not retained from {filename}, and that "
                 "setting a new repeatdt will start particles from the _new_ particle "
                 "locations.",
-                FileWarning,
+                ParticleSetWarning,
                 stacklevel=2,
             )
 
@@ -1247,6 +1249,22 @@ def _warn_outputdt_release_desync(outputdt: float, starttime: float, release_tim
             "Some of the particles have a start time difference that is not a multiple of outputdt. "
             "This could cause the first output of some of the particles that start later "
             "in the simulation to be at a different time than expected.",
-            FileWarning,
+            ParticleSetWarning,
             stacklevel=2,
         )
+
+
+def _warn_particle_times_outside_fieldset_time_bounds(release_times: np.ndarray, time_full: np.ndarray):
+    if np.any(release_times):
+        if np.any(release_times < time_full[0]):
+            warnings.warn(
+                "Some particles are set to be released before the fieldset's first time and allow_time_extrapolation is set to False.",
+                ParticleSetWarning,
+                stacklevel=2,
+            )
+        if np.any(release_times > time_full[-1]):
+            warnings.warn(
+                "Some particles are set to be released after the fieldset's last time and allow_time_extrapolation is set to False.",
+                ParticleSetWarning,
+                stacklevel=2,
+            )
diff --git a/parcels/tools/warnings.py b/parcels/tools/warnings.py
@@ -1,6 +1,6 @@
 import warnings
 
-__all__ = ["FieldSetWarning", "FileWarning", "KernelWarning"]
+__all__ = ["FieldSetWarning", "FileWarning", "KernelWarning", "ParticleSetWarning"]
 
 
 class FieldSetWarning(UserWarning):
@@ -13,6 +13,12 @@ class FieldSetWarning(UserWarning):
     pass
 
 
+class ParticleSetWarning(UserWarning):
+    """Warning that is raised when there are issues in the construction of the ParticleSet."""
+
+    pass
+
+
 class FileWarning(UserWarning):
     """Warning that is raised when there are issues with input or output files.
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -149,7 +149,7 @@ module = [
     "mpi4py",
     "scipy.spatial",
     "sklearn.cluster",
-    "zarr",
+    "zarr>=2.11.0,!=2.18.0,<3",
     "cftime",
     "pykdtree.kdtree",
     "netCDF4",
diff --git a/tests/test_advection.py b/tests/test_advection.py
@@ -73,7 +73,6 @@ def test_advection_zonal(lon, lat, depth, mode):
     }
     dimensions = {"lon": lon, "lat": lat}
     fieldset2D = FieldSet.from_data(data2D, dimensions, mesh="spherical", transpose=True)
-    assert fieldset2D.U._creation_log == "from_data"
 
     pset2D = ParticleSet(fieldset2D, pclass=ptype[mode], lon=np.zeros(npart) + 20.0, lat=np.linspace(0, 80, npart))
     pset2D.execute(AdvectionRK4, runtime=timedelta(hours=2), dt=timedelta(seconds=30))
diff --git a/tests/test_field.py b/tests/test_field.py
@@ -0,0 +1,70 @@
+import cftime
+import numpy as np
+import pytest
+import xarray as xr
+
+from parcels import Field
+from parcels.tools.converters import (
+    _get_cftime_calendars,
+    _get_cftime_datetimes,
+)
+from tests.utils import TEST_DATA
+
+
+def test_field_from_netcdf_variables():
+    filename = str(TEST_DATA / "perlinfieldsU.nc")
+    dims = {"lon": "x", "lat": "y"}
+
+    variable = "vozocrtx"
+    f1 = Field.from_netcdf(filename, variable, dims)
+    variable = ("U", "vozocrtx")
+    f2 = Field.from_netcdf(filename, variable, dims)
+    variable = {"U": "vozocrtx"}
+    f3 = Field.from_netcdf(filename, variable, dims)
+
+    assert np.allclose(f1.data, f2.data, atol=1e-12)
+    assert np.allclose(f1.data, f3.data, atol=1e-12)
+
+    with pytest.raises(AssertionError):
+        variable = {"U": "vozocrtx", "nav_lat": "nav_lat"}  # multiple variables will fail
+        f3 = Field.from_netcdf(filename, variable, dims)
+
+
+@pytest.mark.parametrize("with_timestamps", [True, False])
+def test_field_from_netcdf(with_timestamps):
+    filenames = {
+        "lon": str(TEST_DATA / "mask_nemo_cross_180lon.nc"),
+        "lat": str(TEST_DATA / "mask_nemo_cross_180lon.nc"),
+        "data": str(TEST_DATA / "Uu_eastward_nemo_cross_180lon.nc"),
+    }
+    variable = "U"
+    dimensions = {"lon": "glamf", "lat": "gphif"}
+    if with_timestamps:
+        timestamp_types = [[[2]], [[np.datetime64("2000-01-01")]]]
+        for timestamps in timestamp_types:
+            Field.from_netcdf(filenames, variable, dimensions, interp_method="cgrid_velocity", timestamps=timestamps)
+    else:
+        Field.from_netcdf(filenames, variable, dimensions, interp_method="cgrid_velocity")
+
+
+@pytest.mark.parametrize(
+    "calendar, cftime_datetime", zip(_get_cftime_calendars(), _get_cftime_datetimes(), strict=True)
+)
+def test_field_nonstandardtime(calendar, cftime_datetime, tmpdir):
+    xdim = 4
+    ydim = 6
+    filepath = tmpdir.join("test_nonstandardtime.nc")
+    dates = [getattr(cftime, cftime_datetime)(1, m, 1) for m in range(1, 13)]
+    da = xr.DataArray(
+        np.random.rand(12, xdim, ydim), coords=[dates, range(xdim), range(ydim)], dims=["time", "lon", "lat"], name="U"
+    )
+    da.to_netcdf(str(filepath))
+
+    dims = {"lon": "lon", "lat": "lat", "time": "time"}
+    try:
+        field = Field.from_netcdf(filepath, "U", dims)
+    except NotImplementedError:
+        field = None
+
+    if field is not None:
+        assert field.grid.time_origin.calendar == calendar
diff --git a/tests/test_fieldset.py b/tests/test_fieldset.py
diff --git a/tests/test_particlesets.py b/tests/test_particlesets.py
diff --git a/tests/tools/test_warnings.py b/tests/tools/test_warnings.py
diff --git a/tests/utils.py b/tests/utils.py

Original file line number	Diff line number	Diff line change
`@@ -33,7 +33,7 @@`
`33`	`33`	"3. Since Analytical Advection does not use timestepping, the `dt` parameter in `pset.execute()` should be set to `np.inf`. For backward-in-time simulations, it should be set to `-np.inf`. \n",
`34`	`34`	`"4. For time-varying fields, only the 'intermediate timesteps' scheme ([section 2.3 of Döös et al 2017](https://www.geosci-model-dev.net/10/1733/2017/gmd-10-1733-2017.pdf)) is implemented. While there is also a way to also analytically solve the time-evolving fields ([section 2.4 of Döös et al 2017](https://www.geosci-model-dev.net/10/1733/2017/gmd-10-1733-2017.pdf)), this is not yet implemented in Parcels.\n",`
`35`	`35`	`"\n",`
`36`		- "We welcome contributions to the further development of this algorithm and in particular the analytical time-varying case. See [here](https://github.com/OceanParcels/parcels/blob/master/parcels/application_kernels/advection.py) for the code of the `AdvectionAnalytical` kernel.\n"
	`36`	+ "We welcome contributions to the further development of this algorithm and in particular the analytical time-varying case. See [here](https://github.com/OceanParcels/parcels/blob/main/parcels/application_kernels/advection.py) for the code of the `AdvectionAnalytical` kernel.\n"
`37`	`37`	`]`
`38`	`38`	`},`
`39`	`39`	`{`