From 1fc23b4bd53c089b5ca6ac88fc8a82253ddec852 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Wed, 8 Jul 2026 09:41:17 +0200 Subject: [PATCH 1/7] Adding Headers to User guide So that sections can directly be linked to --- docs/_static/custom.css | 3 +++ docs/conf.py | 1 + docs/user_guide/index.md | 34 +++++++++++++++++++++++++++------- 3 files changed, 31 insertions(+), 7 deletions(-) create mode 100644 docs/_static/custom.css diff --git a/docs/_static/custom.css b/docs/_static/custom.css new file mode 100644 index 0000000000..79e9aa7c86 --- /dev/null +++ b/docs/_static/custom.css @@ -0,0 +1,3 @@ +.bd-article .toctree-wrapper > p.caption { + display: none; +} diff --git a/docs/conf.py b/docs/conf.py index 470b7b7b90..45972eef74 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -187,6 +187,7 @@ # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] +html_css_files = ["custom.css"] html_theme_options = { "logo": { "alt_text": "Parcels - Home", diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md index fea2ca158f..846557823d 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -9,11 +9,14 @@ The tutorials written for Parcels v3 are currently being updated for Parcels v4. ## Getting started -🎓 [Quickstart Tutorial](../getting_started/tutorial_quickstart.md) - -🎓 [Output Tutorial](../getting_started/tutorial_output.ipynb) - -📖 [Conceptual workflow](../getting_started/explanation_concepts.md) +```{toctree} +:caption: Getting Started +:name: getting-started +:titlesonly: +../getting_started/tutorial_quickstart.md +../getting_started/tutorial_output.ipynb +../getting_started/explanation_concepts.md +``` ## How to @@ -21,8 +24,11 @@ The tutorials written for Parcels v3 are currently being updated for Parcels v4. **Migrate from v3 to v4** using [this migration guide](v4-migration.md) ``` +## Set up FieldSets + ```{toctree} :caption: Set up FieldSets +:name: setup-fieldsets :titlesonly: examples/explanation_grids.md examples/tutorial_nemo.ipynb @@ -38,14 +44,20 @@ examples/tutorial_manipulating_field_data.ipynb +## Create ParticleSets + ```{toctree} :caption: Create ParticleSets +:name: create-particlesets :titlesonly: examples/tutorial_delaystart.ipynb ``` +## Write Kernels + ```{toctree} :caption: Write Kernels +:name: write-kernels :titlesonly: examples/explanation_kernelloop.md @@ -54,8 +66,11 @@ examples/tutorial_statuscodes.ipynb examples/tutorial_write_in_kernel.ipynb ``` +## Set interpolation methods + ```{toctree} -:caption: Set interpolation method +:caption: Set interpolation methods +:name: interpolation-methods :titlesonly: examples/explanation_interpolation.md @@ -66,9 +81,11 @@ examples/tutorial_interpolation.ipynb +## Run a simulation + ```{toctree} :caption: Run a simulation -:name: tutorial-execute +:name: run-simulation :titlesonly: examples/tutorial_dt_integrators.ipynb @@ -88,8 +105,11 @@ examples/tutorial_dt_integrators.ipynb +## Example Kernels + ```{toctree} :caption: Example Kernels +:name: example-kernels :titlesonly: examples/tutorial_gsw_density.ipynb examples/tutorial_Argofloats.ipynb From 086aa98282df4165728a2b88fc5651df363fa80d Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Wed, 8 Jul 2026 11:36:30 +0200 Subject: [PATCH 2/7] Moving getting-started to within user-guide --- docs/getting_started/index.md | 11 ----------- .../getting_started/explanation_concepts.md | 0 .../getting_started/installation.md | 0 .../getting_started/tutorial_output.ipynb | 0 .../getting_started/tutorial_quickstart.md | 0 docs/user_guide/index.md | 19 +++++++++++++------ 6 files changed, 13 insertions(+), 17 deletions(-) delete mode 100644 docs/getting_started/index.md rename docs/{ => user_guide}/getting_started/explanation_concepts.md (100%) rename docs/{ => user_guide}/getting_started/installation.md (100%) rename docs/{ => user_guide}/getting_started/tutorial_output.ipynb (100%) rename docs/{ => user_guide}/getting_started/tutorial_quickstart.md (100%) diff --git a/docs/getting_started/index.md b/docs/getting_started/index.md deleted file mode 100644 index 3f3955d67c..0000000000 --- a/docs/getting_started/index.md +++ /dev/null @@ -1,11 +0,0 @@ -# Getting started - -Getting started with parcels is easy; here you will find: - -```{toctree} -:maxdepth: 1 -📦 Installation guide -🎓 Quickstart tutorial -🎓 Output tutorial -📖 Conceptual workflow -``` diff --git a/docs/getting_started/explanation_concepts.md b/docs/user_guide/getting_started/explanation_concepts.md similarity index 100% rename from docs/getting_started/explanation_concepts.md rename to docs/user_guide/getting_started/explanation_concepts.md diff --git a/docs/getting_started/installation.md b/docs/user_guide/getting_started/installation.md similarity index 100% rename from docs/getting_started/installation.md rename to docs/user_guide/getting_started/installation.md diff --git a/docs/getting_started/tutorial_output.ipynb b/docs/user_guide/getting_started/tutorial_output.ipynb similarity index 100% rename from docs/getting_started/tutorial_output.ipynb rename to docs/user_guide/getting_started/tutorial_output.ipynb diff --git a/docs/getting_started/tutorial_quickstart.md b/docs/user_guide/getting_started/tutorial_quickstart.md similarity index 100% rename from docs/getting_started/tutorial_quickstart.md rename to docs/user_guide/getting_started/tutorial_quickstart.md diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md index 846557823d..cd41054eea 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -7,21 +7,28 @@ The tutorials written for Parcels v3 are currently being updated for Parcels v4. [Feel free to post a Discussion on GitHub](https://github.com/Parcels-code/Parcels/discussions/categories/ideas) if you feel like v4 needs a specific tutorial that wasn't in v3, or [post an issue](https://github.com/Parcels-code/Parcels/issues/new?template=01_feature.md) if you feel that the notebooks below can be improved! ``` +## Installation + +```{toctree} +:caption: Installation instructions +:name: installation +:titlesonly: +getting_started/installation.md +``` + ## Getting started ```{toctree} :caption: Getting Started :name: getting-started :titlesonly: -../getting_started/tutorial_quickstart.md -../getting_started/tutorial_output.ipynb -../getting_started/explanation_concepts.md +getting_started/tutorial_quickstart.md +getting_started/tutorial_output.ipynb +getting_started/explanation_concepts.md ``` -## How to - ```{note} -**Migrate from v3 to v4** using [this migration guide](v4-migration.md) +Migrate from Parcels v3 to v4 using [this migration guide](v4-migration.md) ``` ## Set up FieldSets From 479e7bd91a40be4a1550b4549dc100de61e38ea6 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Wed, 8 Jul 2026 12:12:02 +0200 Subject: [PATCH 3/7] Updating links --- docs/index.md | 15 ++++------ docs/user_guide/examples/tutorial_fesom.ipynb | 4 +-- .../user_guide/examples/tutorial_schism.ipynb | 4 +-- .../examples/tutorial_write_in_kernel.ipynb | 2 +- .../getting_started/explanation_concepts.md | 30 +++++++++---------- .../getting_started/installation.md | 2 +- .../getting_started/tutorial_quickstart.md | 2 +- docs/v4/installation.md | 2 +- 8 files changed, 29 insertions(+), 32 deletions(-) diff --git a/docs/index.md b/docs/index.md index 5737dccbc5..f8c0c7e45f 100755 --- a/docs/index.md +++ b/docs/index.md @@ -12,7 +12,9 @@ _Animation of virtual particles carried by ocean surface flow in the global ocea You can browse the documentation for older versions by using the version switcher in the bottom right. ``` -**Useful links**: [Installation instructions](getting_started/installation.md) | [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) +**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 @@ -22,13 +24,12 @@ You can browse the documentation for older versions by using the version switche ````{grid-item-card} Getting started :shadow: md -New to **Parcels**? Check out the installation guide, run the quickstart tutorial, and learn the key 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. +++ -```{button-ref} getting_started/index +```{button-ref} user_guide/index :ref-type: doc -:click-parent: :color: secondary :expand: @@ -38,13 +39,12 @@ 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. +++ ```{button-ref} user_guide/index :ref-type: doc -:click-parent: :color: secondary :expand: @@ -60,7 +60,6 @@ We encourage anyone to help improve **Parcels**: read our guidelines to get star ```{button-ref} development/index :ref-type: doc -:click-parent: :color: secondary :expand: @@ -76,7 +75,6 @@ Want to interact with other users and **Parcels** developers? ```{button-ref} community/index :ref-type: doc -:click-parent: :color: secondary :expand: @@ -95,6 +93,5 @@ User guide Community Development API reference -v4 Parcels website ``` diff --git a/docs/user_guide/examples/tutorial_fesom.ipynb b/docs/user_guide/examples/tutorial_fesom.ipynb index 4f9d17e915..ff51e674e1 100644 --- a/docs/user_guide/examples/tutorial_fesom.ipynb +++ b/docs/user_guide/examples/tutorial_fesom.ipynb @@ -18,7 +18,7 @@ "3. Build a `FieldSet` with `parcels.FieldSet.from_ugrid_conventions`.\n", "4. Run the simulation as on any structured grid.\n", "\n", - "If you have not done so already, work through the [quickstart tutorial](../../getting_started/tutorial_quickstart.md) first to get familiar with `ParticleSet`, `Kernel`, and `ParticleFile`." + "If you have not done so already, work through the [quickstart tutorial](../getting_started/tutorial_quickstart.md) first to get familiar with `ParticleSet`, `Kernel`, and `ParticleFile`." ] }, { @@ -44,7 +44,7 @@ "source": [ "## Get the FESOM tutorial dataset\n", "\n", - "We use a small periodic-channel snapshot from a FESOM2 simulation that ships with Parcels' tutorial data registry. As in the [quickstart](../../getting_started/tutorial_quickstart.md), `parcels.tutorial.open_dataset` downloads the files into a local cache on first use; subsequent calls just return the cached copy.\n", + "We use a small periodic-channel snapshot from a FESOM2 simulation that ships with Parcels' tutorial data registry. As in the [quickstart](../getting_started/tutorial_quickstart.md), `parcels.tutorial.open_dataset` downloads the files into a local cache on first use; subsequent calls just return the cached copy.\n", "\n", "`uxarray` expects file paths rather than an in-memory dataset, so we trigger the downloads and then point `ux.open_mfdataset` at the cached files:" ] diff --git a/docs/user_guide/examples/tutorial_schism.ipynb b/docs/user_guide/examples/tutorial_schism.ipynb index 63c4774007..56e91b50dc 100644 --- a/docs/user_guide/examples/tutorial_schism.ipynb +++ b/docs/user_guide/examples/tutorial_schism.ipynb @@ -31,7 +31,7 @@ " end up below the local bathymetry and stop advecting them.\n", "\n", "If you have not done so already, work through the\n", - "[quickstart tutorial](../../getting_started/tutorial_quickstart.md) first to get familiar with\n", + "[quickstart tutorial](../getting_started/tutorial_quickstart.md) first to get familiar with\n", "`ParticleSet`, `Kernel`, and `ParticleFile`." ] }, @@ -66,7 +66,7 @@ "* `horizontalVelX`, `horizontalVelY`: the 3D horizontal velocity components, defined at the mesh nodes\n", " over 32 vertical layers.\n", "\n", - "As in the [quickstart](../../getting_started/tutorial_quickstart.md), `parcels.tutorial.open_dataset`\n", + "As in the [quickstart](../getting_started/tutorial_quickstart.md), `parcels.tutorial.open_dataset`\n", "downloads the files into a local cache on first use (subsequent calls return the cached copy) and opens\n", "them as `xarray` datasets:" ] diff --git a/docs/user_guide/examples/tutorial_write_in_kernel.ipynb b/docs/user_guide/examples/tutorial_write_in_kernel.ipynb index 447747d7c4..aa21f91104 100644 --- a/docs/user_guide/examples/tutorial_write_in_kernel.ipynb +++ b/docs/user_guide/examples/tutorial_write_in_kernel.ipynb @@ -19,7 +19,7 @@ "\n", "For these cases, you can use the `pfile.write()` method anywhere in a `Kernel`. You can write to the same file as the one specified in `output_file` or to a different file. \n", "\n", - "This short tutorial will show you how to use `pfile.write()` in a kernel. We will use the same dataset and particle set as in the [output tutorial ](../../getting_started/tutorial_output.ipynb)." + "This short tutorial will show you how to use `pfile.write()` in a kernel. We will use the same dataset and particle set as in the [output tutorial ](../getting_started/tutorial_output.ipynb)." ] }, { diff --git a/docs/user_guide/getting_started/explanation_concepts.md b/docs/user_guide/getting_started/explanation_concepts.md index 3533dac313..e87554615b 100644 --- a/docs/user_guide/getting_started/explanation_concepts.md +++ b/docs/user_guide/getting_started/explanation_concepts.md @@ -17,9 +17,9 @@ A Parcels simulation is generally built up from four different components: 3. [**Kernels**](#3-kernels). Kernels perform some specific operation on the particles every time step (e.g. advect the particles with the three-dimensional flow; or interpolate the temperature field to the particle location). 4. [**Execute**](#4-execute). Execute the simulation. The core method which integrates the operations defined in Kernels for a given runtime and timestep, and writes output to a ParticleFile. -We discuss each component in more detail below. The subsections titled **"Learn how to"** link to more detailed [how-to guide notebooks](../user_guide/index.md) and more detailed _explanations_ of Parcels functionality are included under **"Read more about"** subsections. The full list of classes and methods is in the [API reference](../reference/parcels/index). If you want to learn by doing, check out the [quickstart tutorial](./tutorial_quickstart.md) to start creating your first Parcels simulation. +We discuss each component in more detail below. The subsections titled **"Learn how to"** link to more detailed [how-to guide notebooks](../index.md) and more detailed _explanations_ of Parcels functionality are included under **"Read more about"** subsections. The full list of classes and methods is in the [API reference](../../reference/parcels/index). If you want to learn by doing, check out the [quickstart tutorial](./tutorial_quickstart.md) to start creating your first Parcels simulation. -```{figure} ../_static/concepts_diagram.png +```{figure} ../../_static/concepts_diagram.png :alt: Parcels concepts diagram :width: 100% @@ -59,7 +59,7 @@ Each `parcels.Field` is defined on a grid. With Parcels, we can simulate particl ```{admonition} 📖 Read more about grids :class: seealso -- [Grids explanation](../user_guide/examples/explanation_grids.md) +- [Grids explanation](../examples/explanation_grids.md) ``` ### Interpolation @@ -68,12 +68,12 @@ To find the value of a `parcels.Field` at any particle location, Parcels interpo ```{admonition} 📖 Read more about interpolation :class: seealso -- [Interpolation explanation](../user_guide/examples/explanation_interpolation.md) +- [Interpolation explanation](../examples/explanation_interpolation.md) ``` ```{admonition} 🖥️ Learn how to use Parcels interpolators :class: seealso -- [Interpolators guide](../user_guide/examples/tutorial_interpolation.ipynb) +- [Interpolators guide](../examples/tutorial_interpolation.ipynb) ``` ## 2. ParticleSet @@ -96,7 +96,7 @@ pset = parcels.ParticleSet(fieldset=fieldset, pclass=parcels.Particle, time=time ```{admonition} 🖥️ Learn more about how to create ParticleSets :class: seealso -- [Release particles at different times](../user_guide/examples/tutorial_delaystart.ipynb) +- [Release particles at different times](../examples/tutorial_delaystart.ipynb) ``` ## 3. Kernels @@ -126,7 +126,7 @@ def AdvectionEE(particles, fieldset): Basic kernels are included in Parcels to compute advection and diffusion. The standard advection kernel is `parcels.kernels.AdvectionRK2`, a [second-order Runge-Kutta integrator](https://en.wikipedia.org/wiki/Runge%E2%80%93Kutta_methods#The_Runge%E2%80%93Kutta_method) of the advection function. ```{warning} -It is advised _not_ to update the particle coordinates (`particles.time`, `particles.z`, `particles.y`, or `particles.x`) directly within a Kernel, as that can negatively interfere with the way that particle movements by different kernels are vectorially added. Use a change in the coordinates: `particles.dy`, `particles.dx` and/or `particles.dz`. Read the [kernel loop tutorial](../user_guide/examples/explanation_kernelloop.md) to understand why. +It is advised _not_ to update the particle coordinates (`particles.time`, `particles.z`, `particles.y`, or `particles.x`) directly within a Kernel, as that can negatively interfere with the way that particle movements by different kernels are vectorially added. Use a change in the coordinates: `particles.dy`, `particles.dx` and/or `particles.dz`. Read the [kernel loop tutorial](../examples/explanation_kernelloop.md) to understand why. ``` (custom-kernel)= @@ -151,20 +151,20 @@ Every Kernel must be a function with the following (and only those) arguments: ` ``` ```{warning} -We have to be careful with kernels that sample velocities on "spherical" grids (so with longitude and latitude in degrees). Parcels can automatically convert velocities from m s-1 to degrees s-1, but only when using `VectorFields`. [This guide](../user_guide/examples/tutorial_velocityconversion.ipynb) describes how to use velocities on a "spherical" grid in Parcels. +We have to be careful with kernels that sample velocities on "spherical" grids (so with longitude and latitude in degrees). Parcels can automatically convert velocities from m s-1 to degrees s-1, but only when using `VectorFields`. [This guide](../examples/tutorial_velocityconversion.ipynb) describes how to use velocities on a "spherical" grid in Parcels. ``` ```{admonition} 📖 Read more about the Kernel loop :class: seealso -- [The Kernel loop](../user_guide/examples/explanation_kernelloop.md) +- [The Kernel loop](../examples/explanation_kernelloop.md) ``` ```{admonition} 🖥️ Learn how to write Kernels :class: seealso -- [Sample fields like temperature](../user_guide/examples/tutorial_sampling.ipynb). -- [Mimic the behaviour of ARGO floats](../user_guide/examples/tutorial_Argofloats.ipynb). -- [Add diffusion to approximate subgrid-scale processes and unresolved physics](../user_guide/examples/tutorial_diffusion.ipynb). -- [Convert velocities between units in m s-1 and degrees s-1](../user_guide/examples/tutorial_velocityconversion.ipynb). +- [Sample fields like temperature](../examples/tutorial_sampling.ipynb). +- [Mimic the behaviour of ARGO floats](../examples/tutorial_Argofloats.ipynb). +- [Add diffusion to approximate subgrid-scale processes and unresolved physics](../examples/tutorial_diffusion.ipynb). +- [Convert velocities between units in m s-1 and degrees s-1](../examples/tutorial_velocityconversion.ipynb). ``` ## 4. Execute @@ -188,10 +188,10 @@ pset.execute(kernels=kernels, dt=dt, runtime=runtime) To analyse the particle data generated in the simulation, we need to define a `parcels.ParticleFile` and add it as an argument to `parcels.ParticleSet.execute()`. The output will be written in a [parquet format](https://parquet.apache.org/), which can be opened as a `polars.DataFrame`. The dataset will contain the particle data with at least `time`, `z`, `y` and `x`, for each particle at timesteps defined by the `outputdt` argument. -There are many ways to analyze particle output, and although we provide [a short tutorial to get started](./tutorial_output.ipynb), we recommend writing your own analysis code and checking out [related Lagrangian analysis projects in our community page](../community/index.md#analysis-code). +There are many ways to analyze particle output, and although we provide [a short tutorial to get started](./tutorial_output.ipynb), we recommend writing your own analysis code and checking out [related Lagrangian analysis projects in our community page](../../community/index.md#analysis-code). ```{admonition} 🖥️ Learn how to run a simulation :class: seealso -- [Choose an appropriate timestep and integrator](../user_guide/examples/tutorial_dt_integrators.ipynb) +- [Choose an appropriate timestep and integrator](../examples/tutorial_dt_integrators.ipynb) - [Work with Parcels output](./tutorial_output.ipynb) ``` diff --git a/docs/user_guide/getting_started/installation.md b/docs/user_guide/getting_started/installation.md index 110388ce17..58461fee4a 100644 --- a/docs/user_guide/getting_started/installation.md +++ b/docs/user_guide/getting_started/installation.md @@ -45,4 +45,4 @@ The next time you start a terminal and want to work with Parcels, activate the e ## Installation for developers -See the [development section in our contributing guide](../development/index.md#development) for development instructions. +See the [development section in our contributing guide](../../development/index.md#development) for development instructions. diff --git a/docs/user_guide/getting_started/tutorial_quickstart.md b/docs/user_guide/getting_started/tutorial_quickstart.md index 5918a9ba33..e6bbc35934 100644 --- a/docs/user_guide/getting_started/tutorial_quickstart.md +++ b/docs/user_guide/getting_started/tutorial_quickstart.md @@ -74,7 +74,7 @@ the virtual particles for which we will calculate the trajectories. We need to create a {py:obj}`parcels.ParticleSet` object with the particles' initial time and position. The `parcels.ParticleSet` object also needs to know about the `FieldSet` in which the particles "live". Finally, we need to specify the type of {py:obj}`parcels.ParticleClass` we want to use. The default particles have `time`, `z`, `y`, and `x`, but you can easily add -other {py:obj}`parcels.Variable`s such as size, temperature, or age to create your own particles to mimic plastic or an [ARGO float](../user_guide/examples/tutorial_Argofloats.ipynb). +other {py:obj}`parcels.Variable`s such as size, temperature, or age to create your own particles to mimic plastic or an [ARGO float](../examples/tutorial_Argofloats.ipynb). ```{code-cell} # Particle locations and initial time diff --git a/docs/v4/installation.md b/docs/v4/installation.md index aaa60ea100..9fa208f089 100644 --- a/docs/v4/installation.md +++ b/docs/v4/installation.md @@ -1,6 +1,6 @@ # 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](../development/index.md#development)! Give it a spin! +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](../../development/index.md#development)! 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). From a12d9183c1680fe8960736c091a9b8b859543880 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Wed, 8 Jul 2026 12:12:15 +0200 Subject: [PATCH 4/7] Update installation instructions --- docs/user_guide/getting_started/installation.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/user_guide/getting_started/installation.md b/docs/user_guide/getting_started/installation.md index 58461fee4a..6258dec7b5 100644 --- a/docs/user_guide/getting_started/installation.md +++ b/docs/user_guide/getting_started/installation.md @@ -14,13 +14,19 @@ The steps below are the installation instructions for Linux, macOS and Windows. **Step 2:** Start a terminal (Linux / macOS) or the Anaconda prompt (Windows). Activate the `base` environment of your Miniconda and create an environment containing Parcels, all its essential dependencies, `trajan` (a trajectory plotting dependency used in the notebooks) and the nice-to-have cartopy and jupyter packages: --> -Parcels v4 is in active development and hasn't been released. +Parcels v4 is in active development. -A pre-release version of Parcels (i.e., the latest version on `main`) can be installed via conda using the following instructions (which creates an environment `parcels-env`, activates it, installs Parcels from a custom pre-release channel that we're using, and installs some additional helper packages). +A pre-release version of Parcels (i.e., the latest version on `main`) can be installed via conda using the following instructions (which creates an environment `parcelsv4-env`, activates it, installs Parcels from a custom pre-release channel that we're using, and installs some additional helper packages). + +```{warning} +Before installing the latest version of Parcels, we *highly* recommend creating a new environment so that it doesn't affect your current environment (which you may be using for your research). + +You can find your current environment with `conda env list` and identifying the environment with 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. +``` ```bash -conda create -n parcels-env python -conda activate parcels-env +conda create -n parcelsv4-env python +conda activate parcelsv4-env conda config --add channels conda-forge conda install -c https://prefix.dev/parcels parcels conda install trajan cartopy jupyter From 4d51d962ec3c203f51a1ed72d03b2cf2f3a1326c Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Wed, 8 Jul 2026 16:54:43 +0200 Subject: [PATCH 5/7] Clean up docs --- docs/user_guide/index.md | 17 ++++++++--------- docs/v4/index.md | 3 +-- docs/v4/installation.md | 20 -------------------- 3 files changed, 9 insertions(+), 31 deletions(-) delete mode 100644 docs/v4/installation.md diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md index cd41054eea..6f2138de11 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -1,11 +1,10 @@ # User guide -The core of our user guide is a series of Jupyter notebooks which document how to implement specific Lagrangian simulations with the flexibility of **Parcels**. Before diving into these advanced _how-to_ guides (🖥️), we suggest users get started by reading the explanation (📖) of the core concepts and trying the tutorials (🎓). For a description of the specific classes and functions, check out the [API reference](../reference/parcels/index). To discover other community resources, check out our [Community](../community/index.md) page. +The core of our user guide is a series of Jupyter notebooks which document how to implement specific Lagrangian simulations with the flexibility of **Parcels**. -```{note} -The tutorials written for Parcels v3 are currently being updated for Parcels v4. Shown below are only the notebooks which have been updated. -[Feel free to post a Discussion on GitHub](https://github.com/Parcels-code/Parcels/discussions/categories/ideas) if you feel like v4 needs a specific tutorial that wasn't in v3, or [post an issue](https://github.com/Parcels-code/Parcels/issues/new?template=01_feature.md) if you feel that the notebooks below can be improved! -``` +Before diving into these advanced _how-to_ guides (🖥️), we suggest users get started by reading the explanation (📖) of the core concepts and trying the tutorials (🎓). + +For a description of the specific classes and functions, check out the [API reference](../reference/parcels/index). To discover other community resources, check out our [Community](../community/index.md) page. ## Installation @@ -16,6 +15,10 @@ The tutorials written for Parcels v3 are currently being updated for Parcels v4. getting_started/installation.md ``` +```{note} +If you have code that uses Parcels v3, you can migrate to Parcels v4 using [this migration guide](v4-migration.md) +``` + ## Getting started ```{toctree} @@ -27,10 +30,6 @@ getting_started/tutorial_output.ipynb getting_started/explanation_concepts.md ``` -```{note} -Migrate from Parcels v3 to v4 using [this migration guide](v4-migration.md) -``` - ## Set up FieldSets ```{toctree} diff --git a/docs/v4/index.md b/docs/v4/index.md index e80ec92704..e7d99ece3f 100644 --- a/docs/v4/index.md +++ b/docs/v4/index.md @@ -17,9 +17,8 @@ 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 nojit TODO -Parcels v4 Project Board +Parcels v4 Issue Tracker Parcels v4 migration guide <../user_guide/v4-migration> ``` diff --git a/docs/v4/installation.md b/docs/v4/installation.md deleted file mode 100644 index 9fa208f089..0000000000 --- a/docs/v4/installation.md +++ /dev/null @@ -1,20 +0,0 @@ -# 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](../../development/index.md#development)! 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. From 8997c7f43ccc94fe1bbbc78dcbed82007f5afa2d Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Thu, 9 Jul 2026 09:59:55 +0200 Subject: [PATCH 6/7] Removing stray print statement in unit tests --- tests/test_particleset_execute.py | 1 - 1 file changed, 1 deletion(-) diff --git a/tests/test_particleset_execute.py b/tests/test_particleset_execute.py index eb877cf749..9b347fe550 100644 --- a/tests/test_particleset_execute.py +++ b/tests/test_particleset_execute.py @@ -171,7 +171,6 @@ def test_particleset_interpolate_on_domainedge(zonal_flow_fieldset): def SampleU(particles, fieldset): # pragma: no cover particles.var = fieldset.U[particles] - print(fieldset.U.grid.lon) pset = ParticleSet(fieldset, pclass=MyParticle, x=fieldset.U.grid.lon[-1], y=fieldset.U.grid.lat[-1]) pset.execute(SampleU, runtime=np.timedelta64(1, "D"), dt=np.timedelta64(1, "D")) np.testing.assert_equal(pset[0].var, 1) From c89d27cda954a966c07f776c50ffca275c8d5671 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Thu, 9 Jul 2026 10:11:59 +0200 Subject: [PATCH 7/7] Fix info on combining models --- .../getting_started/explanation_concepts.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/user_guide/getting_started/explanation_concepts.md b/docs/user_guide/getting_started/explanation_concepts.md index 8e35f1912f..8f0f27114d 100644 --- a/docs/user_guide/getting_started/explanation_concepts.md +++ b/docs/user_guide/getting_started/explanation_concepts.md @@ -41,16 +41,13 @@ ds_fset = parcels.convert.copernicusmarine_to_sgrid(fields=fields) fieldset = parcels.FieldSet.from_sgrid_conventions(ds_fset) ``` -In some cases, we might want to combine `parcels.Field`s from different sources in the same `parcels.FieldSet`, such as ocean currents from one dataset and Stokes drift from another. This is possible in Parcels by adding each `parcels.Field` separately: +In some cases, we might want to combine fields from different sources in the same `parcels.FieldSet`, such as ocean currents from one dataset and Stokes drift from another. This is possible in Parcels by creating multiple `parcels.FieldSet` objects and combining them into a single `parcels.FieldSet`: ```python -dataset1 = xr.dataset("insert_current_data_files.nc") dataset2 = xr.dataset("insert_stokes_data_files.nc") - -Ucurrent = parcels.Field(name="Ucurrent", data=dataset1["Ucurrent"], grid=parcels.XGrid.from_dataset(dataset1), interp_method=parcels.interpolators.XLinear) -Ustokes = parcels.Field(name="Ustokes", data=dataset2["Ustokes"], grid=parcels.XGrid.from_dataset(dataset2), interp_method=parcels.interpolators.XLinear) - -fieldset = parcels.FieldSet([Ucurrent, Ustokes]) +fields2 = {"Ustokes": ds_fields["ustokes"], "Vstokes": ds_fields["vstokes"]} +ds_fset = parcels.convert.copernicusmarine_to_sgrid(fields=fields2) +fieldset += parcels.FieldSet.from_sgrid_conventions(ds_fset, vector_fields={"UVstokes": ["Ustokes", "Vstokes"]}) ``` ### Grid