Merge branch 'v4-dev' into gsw_tutorial

Author: erikvansebille

.github/workflows/cache-pixi-lock.yml

@@ -17,7 +17,6 @@ jobs:
       - uses: actions/checkout@v5
         with:
           fetch-depth: 0
-          sparse-checkout: pixi.toml
       - name: Get current date
         id: date
         run: echo "date=$(date +'%Y-%m-%d')" >> "$GITHUB_OUTPUT"
@@ -30,7 +29,7 @@ jobs:
       - uses: prefix-dev/setup-pixi@v0.9.0
         if: ${{ !steps.restore.outputs.cache-hit }}
         with:
-          pixi-version: v0.49.0
+          pixi-version: v0.56.0
           run-install: false
       - name: Run pixi lock
         if: ${{ !steps.restore.outputs.cache-hit }}

.gitignore

@@ -20,7 +20,7 @@ Profile.prof
 .eggs/*
 parcels.egg-info/*
 dist/parcels*.egg
-parcels/_version_setup.py
+src/parcels/_version_setup.py
 .pytest_cache
 .hypothesis
 .coverage

docs/community/contributing.md

@@ -49,8 +49,6 @@ If you're having trouble using Parcels, feel free to create a discussion in our
 
 In the [Projects panel](https://github.com/OceanParcels/parcels/projects?query=is%3Aopen), you'll see the "Parcels development" project. This is used by the core development team for project management, as well as drafting up new ideas for the codebase that aren't mature enough to be issues themselves. Everything in "backlog" is not being actively worked on and is fair game for open source contributions.
 
-(editing-parcels-code)=
-
 ## Development
 
 ### Environment setup
@@ -77,7 +75,19 @@ Now you have a development installation of Parcels, as well as a bunch of develo
 
 ### Pixi workflows
 
-You can use the following Pixi commands to run common development tasks.
+**Typical development workflow**
+
+1. Make your code changes
+2. Run `pixi run lint` to ensure code formatting and style compliance
+3. Run `pixi run tests` to verify your changes don't break existing functionality
+4. If you've added new features, run `pixi run typing` to check type annotations
+5. If you've modified documentation, run `pixi run docs` to build and verify the docs
+
+```{tip}
+You can run `pixi info` to see all available environments and `pixi task list` to see all available tasks across environments.
+```
+
+See below for more Pixi commands relevant to development.
 
 **Testing**
 
@@ -99,21 +109,13 @@ You can use the following Pixi commands to run common development tasks.
 
 Parcels supports testing against different environments (e.g., different Python versions) with different feature sets. In CI we test against these environments, and you can too locally. For example:
 
-- `pixi run -e test-py311 tests` - Run tests using Python 3.11
-- `pixi run -e test-py312 tests` - Run tests using Python 3.12
+- `pixi run -e test-py311 tests` - Run tests in the environment containing Python 3.11
+- `pixi run -e test-py312 tests` - Run tests in the environment containing Python 3.12
 
 The name of the workflow on GitHub contains the command you have to run locally to recreate the workflow - making it super easy to reproduce CI failures locally.
 
-**Typical development workflow**
-
-1. Make your code changes
-2. Run `pixi run lint` to ensure code formatting and style compliance
-3. Run `pixi run tests` to verify your changes don't break existing functionality
-4. If you've added new features, run `pixi run typing` to check type annotations
-5. If you've modified documentation, run `pixi run docs` to build and verify the docs
-
 ```{tip}
-You can run `pixi info` to see all available environments and `pixi task list` to see all available tasks across environments.
+For those familiar with Conda, you are used to activating an environment. With Pixi, you can do the same by doing `pixi shell <env-name>`. For example, `pixi shell test-latest` will drop you into a shell where you can run commands such as `pytest` like normal. You can exit the shell with `exit` or `Ctrl+D`.
 ```
 
 ### Changing code

docs/community/v4-migration.md

@@ -14,6 +14,7 @@ Version 4 of Parcels is unreleased at the moment. The information in this migrat
 - 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.
+- `particle.depth` has been changed to `particles.z` to be consistent with the [CF conventions for trajectory data](https://cfconventions.org/cf-conventions/cf-conventions.html#trajectory-data), and to make Parcels also generalizable to atmospheric contexts.
 
 ## FieldSet
 

pixi.toml

@@ -7,9 +7,10 @@ platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"]
 [package]
 name = "parcels"
 version = "dynamic" # dynamic versioning needs better support in pixi https://github.com/prefix-dev/pixi/issues/2923#issuecomment-2598460666 . Putting `version = "dynamic"` here for now until pixi recommends something else.
+license = "MIT" # can remove this once https://github.com/prefix-dev/pixi-build-backends/issues/397 is resolved
 
 [package.build]
-backend = { name = "pixi-build-python", version = "==0.3.2" }
+backend = { name = "pixi-build-python", version = "==0.4.0" }
 
 [package.host-dependencies]
 setuptools = "*"
@@ -26,6 +27,7 @@ pre-commit = { features = ["pre-commit"], no-default-feature = true }
 
 [dependencies] # keep section in sync with pyproject.toml dependencies
 python = ">=3.11,<3.13"
+parcels = { path = "." }
 netcdf4 = ">=1.1.9"
 numpy = ">=1.9.1"
 tqdm = "*"
@@ -92,4 +94,4 @@ lxml = "*" # in CI
 types-tqdm = "*"
 
 [feature.typing.tasks]
-typing = "mypy parcels --install-types"
+typing = "mypy src/parcels --install-types"

pyproject.toml

@@ -42,10 +42,11 @@ Tracker = "https://github.com/OceanParcels/parcels/issues"
 
 
 [tool.setuptools]
+package-dir = { "" = "src" }
 packages = ["parcels"]
 
 [tool.setuptools_scm]
-write_to = "parcels/_version_setup.py"
+write_to = "src/parcels/_version_setup.py"
 local_scheme = "no-local-version"
 
 [tool.pytest.ini_options]