Merge branch 'v4-dev' into curvilinear_index_search_without_while_loop

Author: fluidnumericsJoe

.github/ci/recipe.yaml

@@ -0,0 +1,71 @@
+# Recipe for https://github.com/prefix-dev/rattler-build used for nightly releases of Parcels
+# during version 4 alpha development
+#
+# Adapted from the conda forge recipe
+context:
+  name: parcels
+  version: 4.0.0alpha0 # The last number here needs to be bumped for each new alpha release
+
+package:
+  name: ${{ name|lower }}
+  version: ${{ version }}
+
+source:
+  path: ../..
+
+build:
+  number: 0
+  noarch: python
+  script:
+    - python -m pip install . -vv --no-deps --no-build-isolation
+
+requirements:
+  host:
+    - python 3.11.*
+    - pip
+    - setuptools
+    - setuptools_scm
+    - setuptools_scm_git_archive
+    - wheel
+  run:
+    - python >=3.11
+    - cftime
+    - dask
+    - matplotlib-base >=2.0.2
+    - netcdf4 >=1.1.9
+    - numpy >=1.11
+    - platformdirs
+    - psutil
+    - pymbolic
+    - pytest
+    - scipy >=0.16.0
+    - trajan
+    - tqdm
+    - xarray >=0.10.8
+    - zarr >=2.11.0,!=2.18.0,<3
+    - uxarray>=2025.3.0
+    - pyogrio # needed for geopandas (uxarray -> geoviews -> geopandas -> pyogrio, but for some reason conda doesn't pick it up automatically)
+    - pooch
+
+tests:
+  - python:
+      imports:
+        - parcels
+
+about:
+  homepage: https://github.com/OceanParcels/parcels
+  license: MIT
+  license_file: LICENSE.md
+  summary: Probably A Really Computationally Efficient Lagrangian Simulator
+  description: |
+    Parcels (Probably A Really Computationally Efficient Lagrangian Simulator)
+    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, nutrients, plankton, plastic and fish.
+  documentation: https://oceanparcels.org/
+  repository: https://github.com/OceanParcels/parcels
+
+extra:
+  recipe-maintainers:
+    - VeckoTheGecko

.github/workflows/nightly.yml

@@ -0,0 +1,28 @@
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build conda package
+        uses: prefix-dev/rattler-build-action@v0.2.19
+        with:
+          recipe-path: .github/ci/recipe.yaml
+
+      - name: Upload all packages
+        shell: bash
+        run: |
+          shopt -s nullglob
+          EXIT_CODE=0
+          for pkg in $(find output -type f \( -name "*.conda" -o -name "*.tar.bz2" \) ); do
+            if ! rattler-build upload prefix -c parcels "${pkg}"; then
+              EXIT_CODE=1
+            fi
+          done
+          exit $EXIT_CODE

.gitignore

@@ -1,6 +1,7 @@
 build/*
 docs/_build/*
 docs/_downloads
+output
 
 *.log
 *.nc

README.md

@@ -10,6 +10,9 @@
 [![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/main?labpath=docs%2Fexamples%2Fparcels_tutorial.ipynb)
 
+> [!WARNING]
+> This branch is `v4-dev` - version 4 of Parcels which is in active development. See `main` (or the tags) to browse stable versions of Parcels.
+
 **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/main/images/homepage.gif)

docs/community/v4-migration.md

@@ -11,7 +11,8 @@ Version 4 of Parcels is unreleased at the moment. The information in this migrat
 - Sharing state between kernels must be done via the particle data (as the kernels are not combined under the hood anymore).
 - `particl_dlon`, `particle_dlat` etc have been renamed to `particle.dlon` and `particle.dlat`.
 - `particle.dt` is a np.timedelta64 object; be careful when multiplying `particle.dt` with a velocity, as its value may be cast to nanoseconds.
-- The `time` argument in the Kernel signature is now standard `None` (and may be removed in the Kernel API before release of v4), so can't be used. Use `particle.time` instead.
+- The `time` argument in the Kernel signature has been removed in the Kernel API, so can't be used. Use `particle.time` instead.
+- The `particle` argument in the Kernel signature has been renamed to `particles`.
 - `math` functions should be replaced with array compatible equivalents (e.g., `math.sin` -> `np.sin`). Instead of `ParcelsRandom` you should use numpy's random functions.
 
 ## FieldSet

docs/v4/index.md

@@ -17,7 +17,7 @@ Collaboration on v4 development is happening on the [Parcels v4 Project Board](h
 The pages below provide further background on the development of Parcels v4. You can think of this page as a "living" document as we work towards the release of v4.
 
 ```{toctree}
-
+installation
 api
 nojit
 TODO

docs/v4/installation.md

@@ -0,0 +1,20 @@
+# Install an alpha version of Parcels v4
+
+During development of Parcels v4, we are uploading versions of the package to an [index on prefix.dev](https://prefix.dev/channels/parcels/packages/parcels). This allows users to easily install an unreleased version without having to do a [development install](../installation.rst)! Give it a spin!
+
+```{warning}
+Before installing an alpha version of Parcels, we *highly* recommend creating a new environment so that doesn't affect package versions in your current environment (which you may be using for your research).
+
+You can see what your current environment is by doing `conda env list` and seeing which environment has a `*` next to it. At any point, you can use `conda activate ...` (replacing `...` with the name that had the `*` next to it) to return to your environment with version 3 of Parcels.
+
+```
+
+Do the following to create a new environment (called `parcels-v4-alpha`) with an alpha version of Parcels installed:
+
+```sh
+conda create -n parcels-v4-alpha python=3.11
+conda activate parcels-v4-alpha
+conda install -c https://repo.prefix.dev/parcels parcels
+```
+
+During the development of Parcels v4 we will be occasionally releasing these alpha package versions so that users can try them out. If you're installing Parcels normally (i.e., via Conda forge) you will receive version 3 of Parcels as usual until version 4 is officially released.