Skip to content

Further cleanup of the tutorials #2834

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
erikvansebille merged 15 commits into from
Aug 18, 2026
Merged

Further cleanup of the tutorials #2834

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
0b5da82
Further cleanup of the quickstart tutorial
erikvansebille Aug 17, 2026
6cf2fd3
adding myst tags to classes and functions
erikvansebille Aug 17, 2026
084528f
Merge branch 'main' into further-docs-clean
erikvansebille Aug 17, 2026
2d9ed75
Add check of py:func and py:obj links
erikvansebille Aug 17, 2026
bc03f6e
Fixing broken links
erikvansebille Aug 17, 2026
0118eda
Fixing API links for fieldset tutorials
erikvansebille Aug 17, 2026
ab7d066
More doc updates
erikvansebille Aug 17, 2026
421b4bd
Clean-up docs/index
erikvansebille Aug 17, 2026
7872a1c
Reduce use of bold-font Parcels in docs
erikvansebille Aug 17, 2026
9f24c4b
Adding figures for unstuck tutorial
erikvansebille Aug 18, 2026
5bcb273
Adding API links to tutorials
erikvansebille Aug 18, 2026
9037437
Moving stuck/unstuck tutorials to interpolation section
erikvansebille Aug 18, 2026
e4ffdbf
Update tutorial_stuck_particles.ipynb
erikvansebille Aug 18, 2026
7c1e661
Merge branch 'main' into further-docs-clean
erikvansebille Aug 18, 2026
30a7cd4
Implementing review suggestions
erikvansebille Aug 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added docs/_static/NEMO_ghost_vel.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/NEMO_latBC.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/community/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ Report a bug with an Issue
````{grid-item-card} Sharing user code
:shadow: md

Curious to see if someone has already written the custom `Kernel` you are thinking of or runs **Parcels** with the same hydrodynamic data? Check out the parcels_contributions repository and share examples with other users!
Curious to see if someone has already written the custom `Kernel` you are thinking of or runs Parcels with the same hydrodynamic data? Check out the parcels_contributions repository and share examples with other users!

```{image} https://img.shields.io/badge/maintainer_needed-red
:width: 40%
Expand Down
5 changes: 5 additions & 0 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -523,6 +523,11 @@ def linkcode_resolve(domain, info):
nb_execution_raise_on_error = True
nb_execution_timeout = 75
suppress_warnings = ["mystnb.unknown_mime_type"]
nitpicky = True
nitpick_ignore_regex = [
(r"py:class", r".*"),
(r"py:mod", r".*"),
]
Comment on lines +527 to +530

@VeckoTheGecko VeckoTheGecko Aug 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wondering about these ignores for class and mod?

@erikvansebille erikvansebille Aug 18, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These come from warnings in the docstrings themselves. If I don't add these ignore rules, I get the following output. I didn't want to deal with them in the PR - and am not sure we should in another?

/Users/erik/Codes/parcels/docs/reference/parcels/BaseGrid.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/BaseGrid.rst:2: WARNING: py:class reference target not found: default=False [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/BaseGrid.rst:2: WARNING: py:class reference target not found: np.ndarray [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/BaseGrid.rst:2: WARNING: py:class reference target not found: np.ndarray [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/BaseGrid.rst:2: WARNING: py:class reference target not found: default=False [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/BaseGrid.rst:2: WARNING: py:class reference target not found: default=False [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/BaseGrid.rst:2: WARNING: py:class reference target not found: parcels.spatialhash.SpatialHash [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/Field.rst:2: WARNING: py:class reference target not found: array-like [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/Field.rst:2: WARNING: py:class reference target not found: scalar [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/Field.rst:2: WARNING: py:class reference target not found: array-like [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/Field.rst:2: WARNING: py:class reference target not found: scalar [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/Field.rst:2: WARNING: py:class reference target not found: array-like [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/Field.rst:2: WARNING: py:class reference target not found: scalar [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/Field.rst:2: WARNING: py:class reference target not found: array-like [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/Field.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/Field.rst:2: WARNING: py:class reference target not found: array-like [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/FieldSet.rst:2: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/FieldSet.rst:2: WARNING: py:class reference target not found: uxarray.UxDataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/FieldSet.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/FieldSet.rst:139: WARNING: py:class reference target not found: parcels.field.Field [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/FieldSet.rst:194: WARNING: py:class reference target not found: parcels._core.basegrid.BaseGrid [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/FieldSet.rst:2: WARNING: py:class reference target not found: uxarray.UxDataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/FieldSet.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/FieldSet.rst:2: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/FieldSet.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/FieldSet.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/FieldSet.rst:2: WARNING: py:class reference target not found: file-like [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/FieldSet.rst:2: WARNING: py:class reference target not found: default: sys.stdout [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleFile.rst:2: WARNING: py:class reference target not found: PathLike [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleFile.rst:2: WARNING: py:class reference target not found: {"zstd" [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleFile.rst:2: WARNING: py:class reference target not found: "gzip" [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleFile.rst:2: WARNING: py:class reference target not found: "snappy" [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleFile.rst:2: WARNING: py:class reference target not found: "brotli" [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleFile.rst:2: WARNING: py:class reference target not found: None} [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleFile.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleFile.rst:2: WARNING: py:class reference target not found: {None [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleFile.rst:2: WARNING: py:class reference target not found: "w"} [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleFile.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:2: WARNING: py:class reference target not found: parcels.particle.Particle [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:15: WARNING: py:mod reference target not found: parcels.particle.Particle [ref.mod]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:2: WARNING: py:class reference target not found: datetime.timedelta [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:2: WARNING: py:class reference target not found: parcels.fieldset.FieldSet [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:2: WARNING: py:class reference target not found: datetime.timedelta [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:2: WARNING: py:class reference target not found: np.ndarray [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:240: WARNING: py:class reference target not found: parcels.kernel.Kernel [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:2: WARNING: py:class reference target not found: runtime [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:2: WARNING: py:class reference target not found: np.timedelta64 or [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:2: WARNING: py:class reference target not found: endtime [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/ParticleSet.rst:2: WARNING: py:class reference target not found: np.datetime64 or [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/UxGrid.rst:62: WARNING: py:class reference target not found: _UXGRID_AXES [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/UxGrid.rst:2: WARNING: py:class reference target not found: np.ndarray [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/UxGrid.rst:2: WARNING: py:class reference target not found: np.ndarray [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/UxGrid.rst:2: WARNING: py:class reference target not found: np.ndarray [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/UxGrid.rst:2: WARNING: py:class reference target not found: np.ndarray [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/UxGrid.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/UxGrid.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/Variable.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/Variable.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/VectorField.rst:50: WARNING: py:class reference target not found: parcels._typing.VectorType [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/VectorField.rst:2: WARNING: py:class reference target not found: array-like [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/VectorField.rst:2: WARNING: py:class reference target not found: scalar [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/VectorField.rst:2: WARNING: py:class reference target not found: array-like [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/VectorField.rst:2: WARNING: py:class reference target not found: scalar [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/VectorField.rst:2: WARNING: py:class reference target not found: array-like [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/VectorField.rst:2: WARNING: py:class reference target not found: scalar [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/VectorField.rst:2: WARNING: py:class reference target not found: array-like [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/VectorField.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/VectorField.rst:2: WARNING: py:class reference target not found: array-like [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/XGrid.rst:37: WARNING: py:class reference target not found: parcels._typing.XgridAxis [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/XGrid.rst:2: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/XGrid.rst:2: WARNING: py:class reference target not found: default=False [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/XGrid.rst:2: WARNING: py:class reference target not found: _XGRID_AXES [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xr.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xr.DataArray [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xr.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xr.DataArray [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xr.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xr.DataArray [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xr.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xr.DataArray [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: ux.UxDataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: ux.UxDataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: ux.UxDataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/convert/index.rst:37: WARNING: py:class reference target not found: ux.UxDataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/index.rst:106: WARNING: py:class reference target not found: PathLike [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/index.rst:106: WARNING: py:class reference target not found: optional [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/index.rst:106: WARNING: py:class reference target not found: pd.DataFrame [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/index.rst:106: WARNING: py:class reference target not found: Path [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/index.rst:106: WARNING: py:class reference target not found: Path [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/tutorial/index.rst:15:<autosummary>:1: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/tutorial/index.rst:49: WARNING: py:class reference target not found: xarray.Dataset [ref.class]
/Users/erik/Codes/parcels/docs/reference/parcels/tutorial/index.rst:17: WARNING: py:class reference target not found: xarray.Dataset [ref.class]


# -- Options for autoapi --------------------------------------------------
autoapi_dirs = ["../src/parcels"]
Expand Down
2 changes: 1 addition & 1 deletion docs/development/docsguide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ a table showing the latest notebook execution:
- **Prefer `import parcels` over `from parcels import class` in tutorials and how-to guides** so its obvious in later
code cells which classes and methods are part of Parcels.
- [**Avoid too much Repitition In Documentation**](https://www.writethedocs.org/guide/writing/docs-principles/#arid):
tutorials and how-to guides notebooks will often have repetition of the general **Parcels** steps, (e.g., imports ) -
tutorials and how-to guides notebooks will often have repetition of the general Parcels steps, (e.g., imports ) -
this is needed so that users have complete examples that they can copy and experiment with.`. We try to limit each page
in the documentation to a small number of examples.
- Introduce links and cross-references to maximize discoverability of documentation. This also reduces the necessity for
Expand Down
14 changes: 6 additions & 8 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,19 @@
# Parcels documentation

Welcome to the documentation of Parcels. **Parcels** provides a set of Python classes and methods to create customisable particle tracking simulations using gridded 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).
Welcome to the documentation of Parcels. **Parcels** provides a set of Python classes and methods to create customisable particle tracking simulations using gridded output from (ocean) circulation models. Parcels can be used to track passive and active particulates such as water, plankton, plastic, and fish.

```{figure} _static/homepage.gif
:class: dark-light
```

_Animation of virtual particles carried by ocean surface flow in the global oceans. The particles are advected with Parcels in data from the_ [NEMO Ocean Model](https://www.nemo-ocean.eu/).
_Animation of virtual particles carried by ocean surface flow in the global oceans. The particles are advected with Parcels in data from the [Copernicus Marine Service](https://marine.copernicus.eu). See [here](./user_guide/examples/tutorial_homepage_animation.md) for the script to create this animation yourself._

```{note}
You can browse the documentation for older versions by using the version switcher in the bottom right.
```

**Useful links**: [Installation instructions](user_guide/getting_started/installation) | [Discussions on GitHub](https://github.com/Parcels-code/parcels/discussions) | [Issue on GitHub](https://github.com/Parcels-code/parcels/issues) | [Parcels website](https://parcels-code.org/) | [CLAM community website](https://clam-community.github.io/) | [API reference](reference/parcels/index)

New to **Parcels**? Check out the [installation instructions](user_guide/getting_started/installation), run the [quickstart tutorial](user_guide/getting_started/tutorial_quickstart), and learn the [key concepts](user_guide/getting_started/explanation_concepts) to understand the package.

`````{grid} 1 2 2 2
:gutter: 4
:padding: 2 2 0 0
Expand All @@ -24,7 +22,7 @@ New to **Parcels**? Check out the [installation instructions](user_guide/getting
````{grid-item-card} Getting started
:shadow: md

New to **Parcels**? Check out the [installation instructions](user_guide/getting_started/installation), run the [quickstart tutorial](user_guide/getting_started/tutorial_quickstart), and learn the [key concepts](user_guide/getting_started/explanation_concepts) to understand the package.
New to Parcels? Check out the [installation instructions](user_guide/getting_started/installation), run the [quickstart tutorial](user_guide/getting_started/tutorial_quickstart), and learn the [key concepts](user_guide/getting_started/explanation_concepts) to understand the package.

+++

Expand All @@ -39,7 +37,7 @@ Get started!
````{grid-item-card} How to?
:shadow: md

Wondering how to load a `FieldSet` or write a `Kernel`? Find **tutorials** and explainers to these and other questions here.
Wondering how to load a `FieldSet` or write a `Kernel`? Find tutorials and explainers to these and other questions here.

+++

Expand All @@ -54,7 +52,7 @@ To the user guide
````{grid-item-card} Development
:shadow: md

We encourage anyone to help improve **Parcels**: read our guidelines to get started!
We encourage anyone to help improve Parcels: read our guidelines to get started!

+++

Expand All @@ -69,7 +67,7 @@ Contributing guidelines
````{grid-item-card} Community
:shadow: md

Want to interact with other users and **Parcels** developers?
Want to interact with other users and Parcels developers?

+++

Expand Down
6 changes: 3 additions & 3 deletions docs/user_guide/examples/explanation_grids.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,13 @@
"\n",
"In Lagrangian ocean analysis, virtual particle tracking requires the accurate interpolation of physical properties (flow velocities and tracer properties) to particle locations. The underlying data that forces the particle movement will likely be defined on a discretised grid. \n",
"\n",
"Parcels can natively handle two styles of grids; structured and unstructured, where Parcels `Field` objects exist on a (structured) `parcels.XGrid` and conform to [SGRID](https://sgrid.github.io/sgrid/) conventions, or on a (unstructured) `parcels.Uxgrid` and conform to [UGRID](https://ugrid-conventions.github.io/ugrid-conventions/) conventions. Here we describe these grids on a conceptual level.\n",
"Parcels can natively handle two styles of grids; structured and unstructured, where Parcels `Field` objects exist on a (structured) {py:obj}`parcels.XGrid` and conform to [SGRID](https://sgrid.github.io/sgrid/) conventions, or on a (unstructured) {py:obj}`parcels.UxGrid` and conform to [UGRID](https://ugrid-conventions.github.io/ugrid-conventions/) conventions. Here we describe these grids on a conceptual level.\n",
"\n",
"```{note}\n",
"Parcels comes ready with a range of `convert` functions which will convert your `xarray` dataset into a SGRID or UGRID compliant dataset. See [this list](../index.md#converting-model-data-to-fieldsets) for all the models we have `convert` functions for. If your model is not on that list, you can create your own `convert` function, or reach out on our discussion board for help.\n",
"```\n",
"\n",
"Under the hood, every `Field` in a `FieldSet` has a `grid` attribute. This `grid` stores the spatial and temporal information of the Field coordinates. The number of Grids in a FieldSet is thus always smaller or equal to the number of Field objects; and this is what the \"grid number\" column in `FieldSet.describe()` refers to.\n",
"Under the hood, every `Field` in a `FieldSet` has a `grid` attribute. This `grid` stores the spatial and temporal information of the Field coordinates. The number of Grids in a FieldSet is thus always smaller or equal to the number of Field objects; and this is what the \"grid number\" column in {py:func}`parcels.FieldSet.describe()` refers to.\n",
"\n",
"## Structured grids\n",
"\n",
Expand Down Expand Up @@ -229,7 +229,7 @@
"\n",
"For structured grids, [Blanke and Raynaud](<https://doi.org/10.1175/1520-0485(1997)027%3C1038:KOTPEU%3E2.0.CO;2>) proposed in 1997 to perform a 1D linear interpolation of the $i$ velocity in the $i$ direction, and similarly a 1D linear interpolation of the $j$ velocity in the $j$ direction. These velocities must then be rotated into zonal and meridional velocities, which Parcels handles under the hood. In such a case, your velocity field may look like figure 5.\n",
"\n",
"This (uni)linear velocity interpolation is now often referred to as the Analytical interpolation scheme; this is what the [Ariane](https://ariane-code.cnrs.fr) and [TRACMASS](https://www.tracmass.org/index.html) Lagrangian codes also use. In Parcels, the time-stepping version of this interpolation is provided in the `CGrid_Velocity` Interpolator function.\n",
"This (uni)linear velocity interpolation is now often referred to as the Analytical interpolation scheme; this is what the [Ariane](https://ariane-code.cnrs.fr) and [TRACMASS](https://www.tracmass.org/index.html) Lagrangian codes also use. In Parcels, the time-stepping version of this interpolation is provided in the {py:func}`parcels.interpolators.CGrid_Velocity` Interpolator function.\n",
"\n",
"```{note}\n",
"If you have a structured curvilinear grid, and your velocity field is oriented in the $i/j$-directions, then it is almost certain that your velocities are computed from fluxes across the cell edge, and that you will require the `CGrid_Velocity` Interpolator.\n",
Expand Down
6 changes: 3 additions & 3 deletions docs/user_guide/examples/explanation_interpolation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# 📖 Interpolators Overview and API

Interpolation is an important functionality of Parcels. On this page we will discuss the way it is
implemented in **Parcels** and how to write a custom interpolator function.
implemented in Parcels and how to write a custom interpolator function.

When we want to know the state of particles in an environmental field, such as temperature or velocity,
we _evaluate_ the `parcels.Field` at the particles real position in time and space (`t`, `z`, `y`, `x`).
we _evaluate_ the {py:obj}`parcels.Field` at the particles real position in time and space (`t`, `z`, `y`, `x`).
In Parcels we can do this using square brackets:

```
Expand Down Expand Up @@ -89,4 +89,4 @@ grid_positions = {

The `.interp()` method should return a float (in the case of a `ScalarInterpolator` or a tuple of three floats `(u, v, w)` in the case of a `VectorInterpolator`).

Writing custom interpolators is not trivial, so we recommend that you have a look at the built-in interpolators in {py:func}`parcels.interpolators._xinterpolators` or {py:func}`parcels.interpolators._uxinterpolators` to see how they are implemented.
Writing custom interpolators is not trivial, so we recommend that you have a look at the built-in [structured-grid interpolators](https://github.com/Parcels-code/Parcels/blob/main/src/parcels/interpolators/_xinterpolators.py) or the [unstructured-grid interpolators](https://github.com/Parcels-code/Parcels/blob/main/src/parcels/interpolators/_uxinterpolators.py) to see how they are implemented.
8 changes: 4 additions & 4 deletions docs/user_guide/examples/explanation_kernelloop.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,14 +18,14 @@ In order to make sure that the displacements of a particle in the different Kern

## Basic implementation

Below is a structured overview of how the Kernel loop is implemented. Note that this is for `time` and `x` only, but the process for `y` and `z` is also applied to `y` and `z`.
Below is a structured overview of how the Kernel loop is implemented. Note that this is for `t` and `x` only, but the process for `y` and `z` is also applied to `y` and `z`.

1. Initialise an extra Variable `particles.dx=0`

2. Within the Kernel loop, for each particle:
1. Update `particles.x += particles.dx`

2. Update `particles.time += particles.dt` (except for on the first iteration of the Kernel loop)<br>
2. Update `particles.t += particles.dt` (except for on the first iteration of the Kernel loop)<br>

3. Set variable `particles.dx = 0`

Expand All @@ -34,9 +34,9 @@ Below is a structured overview of how the Kernel loop is implemented. Note that

2. Update `particles.dx` by adding the change in x, if needed

5. If `outputdt` is a multiple of `particles.time`, write `particles.x` and `particles.time` to zarr output file
5. If `outputdt` is a multiple of `particles.t`, write `particles.x` and `particles.t` to zarr output file

Besides having commutable Kernels, the main advantage of this implementation is that, when using Field Sampling with e.g. `particles.temp = fieldset.Temp[particles.time, particles.z, particles.y, particles.x]`, the particle location stays the same throughout the entire Kernel loop. Additionally, this implementation ensures that the particle location is the same as the location of the sampled field in the output file.
Besides having commutable Kernels, the main advantage of this implementation is that, when using Field Sampling with e.g. `particles.var = fieldset.Var[particles.t, particles.z, particles.y, particles.x]`, the particle location stays the same throughout the entire Kernel loop. Additionally, this implementation ensures that the particle location is the same as the location of the sampled field in the output file.

## Example with currents and winds

Expand Down
6 changes: 3 additions & 3 deletions docs/user_guide/examples/explanation_performance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ In this tutorial, we will show how to squeeze performance in Parcels by using a
Note that the concept of Parcels Backends is different from [Xarray backends](https://docs.xarray.dev/en/latest/api/backends.html).

```{note}
You can check which Backend Parcels is using by calling `fieldset.describe()`. The last column shows the Backend that is used for each Field.
You can check which Backend Parcels is using by calling {py:func}`parcels.FieldSet.describe()`. The last column shows the Backend that is used for each Field.
```

## Option 1: load the full FieldSet into memory
Expand Down Expand Up @@ -42,7 +42,7 @@ This will make Parcels use `numpy` functions in the interpolation routines, whic

_Uses Parcels Backend: Zarr_

If your Dataset is too large to fit into memory, but your particles are only distributed over a small part of the domain, it could be efficient to use cached zarr files. This can be done by using the (experimental) `zarr.CacheStore` in combination with the `parcels.open_raw_zarr()` function. This will make Parcels only load the chunks that are needed for the particles, and cache these chunks in memory for future use.
If your Dataset is too large to fit into memory, but your particles are only distributed over a small part of the domain, it could be efficient to use cached zarr files. This can be done by using the (experimental) `zarr.CacheStore` in combination with the {py:func}`parcels.open_raw_zarr()` function. This will make Parcels only load the chunks that are needed for the particles, and cache these chunks in memory for future use.

```{code-block} python
source_store = zarr.storage.LocalStore(filenames)
Expand Down Expand Up @@ -71,7 +71,7 @@ _Uses Parcels Backend: WindowedArray_

**Best for: large Datasets (more than a few GB) and particles distributed over the entire domain**

If your Dataset is so large that it doesn't fit into memory, you can use the `fieldset.to_windowed_arrays()` method to make Parcels only hold two timeslices in memory. Note that this only works if the two timeslices still fit into memory.
If your Dataset is so large that it doesn't fit into memory, you can use the {py:func}`parcels.FieldSet.to_windowed_arrays()` method to make Parcels only hold two timeslices in memory. Note that this only works if the two timeslices still fit into memory.

The two timeslices (the current and the next) are fully loaded into memory, so this method is especially useful if your particles are distributed over the entire domain, as all data will then have to be accessed anyway.

Expand Down
2 changes: 1 addition & 1 deletion docs/user_guide/examples/tutorial_Argofloats.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -164,7 +164,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Now we can plot the trajectory of the Argo float with some simple calls to netCDF4 and matplotlib.\n",
"Now we can plot the trajectory of the Argo float with some simple calls to {py:obj}`parcels.read_particlefile()` and `matplotlib`.\n",
"\n",
"First plot the depth as a function of time, with the temperature as color (only on the upcast)."
]
Expand Down
7 changes: 1 addition & 6 deletions docs/user_guide/examples/tutorial_croco_3D.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Now we create a FieldSet object using the `convert.croco_to_sgrid()` function to first create an S-Grid compliant datatset, and then use that in `FieldSet.from_sgrid_conventions()` to create the FieldSet."
"Now we create a FieldSet object using the {py:func}`parcels.convert.croco_to_sgrid()` function to first create an S-Grid compliant datatset, and then use that in {py:func}`parcels.FieldSet.from_sgrid_conventions()` to create the FieldSet."
]
},
{
Expand Down Expand Up @@ -298,11 +298,6 @@
"z_new = sigma_new * fieldset.h[particles.t, 0, y_new, x_new, particles]\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": []
}
],
"metadata": {
Expand Down
Loading
Loading