Migrate to Parcels v4

docs/user-guide/index.md

@@ -18,4 +18,5 @@ documentation/full_sensor_list.md
 documentation/copernicus_products.md
 documentation/pre_download_data.md
 documentation/example_copernicus_download.ipynb
+documentation/full_sensor_list.md
 ```

pixi.toml

@@ -18,13 +18,12 @@ setuptools = "*"
 setuptools_scm = "*"
 
 [package.run-dependencies] # Keep in sync with `pyproject.toml` and feedstock recipe
-python = ">=3.10"
+python = "3.11.*"
 click = "*"
-parcels = ">3.1.0"
 pyproj = ">=3,<4"
 sortedcontainers = "==2.4.0"
 opensimplex = "==0.4.5"
-numpy = ">=1,<2"
+numpy = ">=2.1.0"
 pydantic = ">=2,<3"
 pyyaml = "*"
 copernicusmarine = ">=2.2.2"
@@ -33,15 +32,26 @@ textual = "*"
 
 [dependencies]
 virtualship = { path = "." }
+# Pre-install as conda packages to avoid PyPI source builds
+netcdf4 = "*"
+numpy = ">=2.1.0"
+dask = "*"
+zarr = ">=3"
+ipdb = ">=0.13.13,<0.14"
+cmocean = ">=4.0.3,<5"
 
-[feature.py310.dependencies]
-python = "3.10.*"
+[pypi-dependencies]
+parcels = { git = "https://github.com/Parcels-code/Parcels", branch = "main" }
 
-[feature.py311.dependencies]
-python = "3.11.*"
+# Commented out whilst parcels v4 alpha only supports Python 3.11 (?)
+# [feature.py310.dependencies]
+# python = "3.10.*"
+
+# [feature.py311.dependencies]
+# python = "3.11.*"
 
-[feature.py312.dependencies]
-python = "3.12.*"
+# [feature.py312.dependencies]
+# python = "3.12.*"
 
 [feature.test.dependencies]
 pytest = "*"
@@ -98,11 +108,8 @@ lxml = "*"
 typing = "mypy src/virtualship --install-types"
 
 [environments]
-default = { features = ["test", "notebooks", "typing", "pre-commit", "analysis"] }
+default = { features = ["test", "notebooks", "typing", "pre-commit", "analysis"] }
 test-latest = { features = ["test"], solve-group = "test" }
-test-py310 = { features = ["test", "py310"] }
-test-py311 = { features = ["test", "py311"] }
-test-py312 = { features = ["test", "py312"] }
 test-notebooks = { features = ["test", "notebooks"], solve-group = "test" }
 analysis = { features = ["analysis"], solve-group = "analysis" }
 docs = { features = ["docs"], solve-group = "docs" }

pyproject.toml

@@ -7,7 +7,7 @@ name = "virtualship"
 description = "Code for the Virtual Ship Classroom, where Marine Scientists can combine Copernicus Marine Data with an OceanParcels ship to go on a virtual expedition."
 readme = "README.md"
 dynamic = ["version"]
-authors = [{ name = "oceanparcels.org team" }]
+authors = [{ name = "parcels-code.org team" }]
 requires-python = ">=3.10"
 license = { file = "LICENSE" }
 classifiers = [
@@ -26,11 +26,11 @@ classifiers = [
 ]
 dependencies = [
     "click",
-    "parcels >3.1.0",
+    "parcels >=4.0.0alpha",
     "pyproj >= 3, < 4",
     "sortedcontainers == 2.4.0",
     "opensimplex == 0.4.5",
-    "numpy >=1, < 2",
+    "numpy >=2.1.0",
     "pydantic >=2, <3",
     "PyYAML",
     "copernicusmarine >= 2.2.2",
@@ -40,7 +40,7 @@ dependencies = [
 ]
 
 [project.urls]
-Homepage = "https://oceanparcels.org/" # TODO: Update this to just be repo?
+Homepage = "https://virtualship.parcels-code.org/"
 Repository = "https://github.com/OceanParcels/virtualship"
 Documentation = "https://virtualship.readthedocs.io/"
 "Bug Tracker" = "https://github.com/OceanParcels/virtualship/issues"
@@ -69,7 +69,8 @@ filterwarnings = [
   "error",
   "default::DeprecationWarning",
   "error::DeprecationWarning:virtualship",
-  "ignore:ParticleSet is empty.*:RuntimeWarning" # TODO: Probably should be ignored in the source code
+  "ignore:ParticleSet is empty.*:RuntimeWarning", # TODO: Probably should be ignored in the source code
+  "ignore:This is an alpha version of Parcels v4.*:UserWarning" # TODO: necessary whilst Parcels v4 is still alpha
 ]
 log_cli_level = "INFO"
 testpaths = [

src/virtualship/cli/_run.py

@@ -35,11 +35,9 @@
     get_instrument_class,
 )
 
-# parcels logger (suppress INFO messages to prevent log being flooded)
-external_logger = logging.getLogger("parcels.tools.loggers")
-external_logger.setLevel(logging.WARNING)
-
-# copernicusmarine logger (suppress INFO messages to prevent log being flooded)
+# suppress INFO messages from copernicusmarine and parcels loggers; prevent log flooding
+parcels_logger = logging.getLogger("parcels._logger")
+parcels_logger.setLevel(logging.WARNING)
 logging.getLogger("copernicusmarine").setLevel("ERROR")
 
 
@@ -204,7 +202,9 @@ def _run(
             # execute simulation
             instrument.execute(
                 measurements=measurements,
-                out_path=expedition_dir.joinpath(RESULTS, f"{itype.name.lower()}.zarr"),
+                out_path=expedition_dir.joinpath(
+                    RESULTS, f"{itype.name.lower()}.parquet"
+                ),
             )
         except Exception as e:
             # clean up if unexpected error occurs

src/virtualship/instruments/adcp.py

@@ -3,7 +3,7 @@
 from typing import ClassVar
 
 import numpy as np
-from parcels import ParticleSet, ScipyParticle
+from parcels import ParticleFile, ParticleSet
 
 from virtualship.instruments.base import Instrument
 from virtualship.instruments.sensors import SensorType
@@ -35,9 +35,13 @@ class ADCP:
 # =====================================================
 
 
-def _sample_velocity(particle, fieldset, time):
-    particle.U, particle.V = fieldset.UV.eval(
-        time, particle.depth, particle.lat, particle.lon, applyConversion=False
+def _sample_velocity(particles, fieldset):
+    particles.U, particles.V = fieldset.UV.eval(
+        particles.time,
+        particles.z,
+        particles.lat,
+        particles.lon,
+        applyConversion=False,
     )
 
 
@@ -96,23 +100,22 @@ def simulate(self, measurements, out_path) -> None:
         # build dynamic particle class from the active sensors
         adcp_config = self.expedition.instruments_config.adcp_config
         _ADCPParticle = build_particle_class_from_sensors(
-            adcp_config.sensors, _ADCP_NONSENSOR_VARIABLES, ScipyParticle
+            adcp_config.sensors, _ADCP_NONSENSOR_VARIABLES
         )
 
         bins = np.linspace(MAX_DEPTH, MIN_DEPTH, NUM_BINS)
         num_particles = len(bins)
-        particleset = ParticleSet.from_list(
+        particleset = ParticleSet(
             fieldset=fieldset,
             pclass=_ADCPParticle,
             lon=np.full(
                 num_particles, 0.0
             ),  # initial lat/lon are irrelevant and will be overruled later.s
             lat=np.full(num_particles, 0.0),
-            depth=bins,
-            time=0,
+            z=bins,
         )
 
-        out_file = particleset.ParticleFile(name=out_path, outputdt=np.inf)
+        out_file = ParticleFile(path=out_path, outputdt=np.inf)
 
         # build kernel list from active sensors only
         sampling_kernels = [
@@ -121,6 +124,9 @@ def simulate(self, measurements, out_path) -> None:
             if sc.enabled and sc.sensor_type in self.sensor_kernels
         ]
 
+        # TODO: need to overhaul ADCP/underway instruments generally... don't think this Parcels API works anymore
+        # TODO: a good time to implement https://github.com/Parcels-code/virtualship/issues/231
+
         for point in measurements:
             particleset.lon_nextloop[:] = point.location.lon
             particleset.lat_nextloop[:] = point.location.lat