From 75c0c8044809ac41395348414be9d1a27f43ade3 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Thu, 5 Nov 2026 07:02:54 +0100 Subject: [PATCH 01/11] Move the documentation to a nested structure so that sections are collapsable --- docs/conf.py | 3 + .../examples/explanation_grids.ipynb | 2 +- .../examples/group_convert_models.md | 26 ++++ .../examples/group_example_kernels.md | 9 ++ docs/user_guide/examples/group_fieldsets.md | 10 ++ .../examples/group_interpolation.md | 10 ++ docs/user_guide/examples/group_kernels.md | 9 ++ docs/user_guide/examples/group_other.md | 8 ++ .../user_guide/examples/group_particlesets.md | 6 + docs/user_guide/examples/group_simulation.md | 7 + docs/user_guide/getting_started/index.md | 8 ++ docs/user_guide/index.md | 135 ++---------------- 12 files changed, 106 insertions(+), 127 deletions(-) create mode 100644 docs/user_guide/examples/group_convert_models.md create mode 100644 docs/user_guide/examples/group_example_kernels.md create mode 100644 docs/user_guide/examples/group_fieldsets.md create mode 100644 docs/user_guide/examples/group_interpolation.md create mode 100644 docs/user_guide/examples/group_kernels.md create mode 100644 docs/user_guide/examples/group_other.md create mode 100644 docs/user_guide/examples/group_particlesets.md create mode 100644 docs/user_guide/examples/group_simulation.md create mode 100644 docs/user_guide/getting_started/index.md diff --git a/docs/conf.py b/docs/conf.py index 0ca473096..1b54202b4 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -208,6 +208,9 @@ "announcement": "Parcels v4 has been released! 🎉 See our release blog post for more info", "header_links_before_dropdown": 8, "navbar_align": "left", + "show_nav_level": 0, + "collapse_navigation": True, + "navigation_depth": 2, } html_context = { diff --git a/docs/user_guide/examples/explanation_grids.ipynb b/docs/user_guide/examples/explanation_grids.ipynb index e0f98dc54..1fddce33d 100644 --- a/docs/user_guide/examples/explanation_grids.ipynb +++ b/docs/user_guide/examples/explanation_grids.ipynb @@ -12,7 +12,7 @@ "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](./explanation_writing_convert_functions.md), or reach out on our discussion board for help.\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](group_convert_models.md) for all the models we have `convert` functions for. If your model is not on that list, you can [create your own `convert` function](./explanation_writing_convert_functions.md), 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 {py:func}`parcels.FieldSet.describe()` refers to.\n", diff --git a/docs/user_guide/examples/group_convert_models.md b/docs/user_guide/examples/group_convert_models.md new file mode 100644 index 000000000..f29ecd5e8 --- /dev/null +++ b/docs/user_guide/examples/group_convert_models.md @@ -0,0 +1,26 @@ +# Converting model data to FieldSets + +Below is a list of tutorials that show how to convert data from ocean (🌊) and atmospheric (🍃) models to Parcels FieldSets. + +## Converting 🌊 ocean models + +```{toctree} +:caption: Converting 🌊 ocean models +:titlesonly: +tutorial_nemo.ipynb +tutorial_croco_3D.ipynb +tutorial_mitgcm.ipynb +tutorial_mom6.ipynb +tutorial_delft3d.ipynb +tutorial_fesom.ipynb +tutorial_schism.ipynb +explanation_writing_convert_functions.md +``` + +## Converting 🍃 atmospheric models + +```{toctree} +:caption: Converting 🍃 atmospheric models +:titlesonly: +tutorial_aifs.ipynb +``` diff --git a/docs/user_guide/examples/group_example_kernels.md b/docs/user_guide/examples/group_example_kernels.md new file mode 100644 index 000000000..39775cff8 --- /dev/null +++ b/docs/user_guide/examples/group_example_kernels.md @@ -0,0 +1,9 @@ +# Example Kernels + +```{toctree} +:titlesonly: +tutorial_gsw_density.ipynb +tutorial_Argofloats.ipynb +tutorial_diffusion.ipynb +tutorial_interaction.ipynb +``` diff --git a/docs/user_guide/examples/group_fieldsets.md b/docs/user_guide/examples/group_fieldsets.md new file mode 100644 index 000000000..d2de6ad21 --- /dev/null +++ b/docs/user_guide/examples/group_fieldsets.md @@ -0,0 +1,10 @@ +# Work with FieldSets + +```{toctree} +:titlesonly: +explanation_grids.ipynb +tutorial_sigma_coordinates.ipynb +tutorial_velocityconversion.ipynb +tutorial_nestedgrids.ipynb +tutorial_manipulating_field_data.ipynb +``` diff --git a/docs/user_guide/examples/group_interpolation.md b/docs/user_guide/examples/group_interpolation.md new file mode 100644 index 000000000..6084adc64 --- /dev/null +++ b/docs/user_guide/examples/group_interpolation.md @@ -0,0 +1,10 @@ +# Set interpolation methods + +```{toctree} +:titlesonly: +explanation_interpolation.md +tutorial_interpolation.ipynb +tutorial_peninsula_AvsCgrid.ipynb +tutorial_stuck_particles.ipynb +tutorial_unstuck_Agrid.ipynb +``` diff --git a/docs/user_guide/examples/group_kernels.md b/docs/user_guide/examples/group_kernels.md new file mode 100644 index 000000000..e6493509c --- /dev/null +++ b/docs/user_guide/examples/group_kernels.md @@ -0,0 +1,9 @@ +# Write Kernels + +```{toctree} +:titlesonly: +explanation_kernelloop.md +tutorial_sampling.ipynb +tutorial_statuscodes.ipynb +tutorial_write_in_kernel.ipynb +``` diff --git a/docs/user_guide/examples/group_other.md b/docs/user_guide/examples/group_other.md new file mode 100644 index 000000000..1d541cc5d --- /dev/null +++ b/docs/user_guide/examples/group_other.md @@ -0,0 +1,8 @@ +# Other + +```{toctree} +:titlesonly: +📖 v4 development <../../v4/index> +🎓 v3 to v4 migration guide <../v4-migration> +tutorial_homepage_animation.md +``` diff --git a/docs/user_guide/examples/group_particlesets.md b/docs/user_guide/examples/group_particlesets.md new file mode 100644 index 000000000..9c9e36bf1 --- /dev/null +++ b/docs/user_guide/examples/group_particlesets.md @@ -0,0 +1,6 @@ +# Create ParticleSets + +```{toctree} +:titlesonly: +tutorial_delaystart.ipynb +``` diff --git a/docs/user_guide/examples/group_simulation.md b/docs/user_guide/examples/group_simulation.md new file mode 100644 index 000000000..7791bda5d --- /dev/null +++ b/docs/user_guide/examples/group_simulation.md @@ -0,0 +1,7 @@ +# Run a simulation + +```{toctree} +:titlesonly: +explanation_performance.md +tutorial_dt_integrators.ipynb +``` diff --git a/docs/user_guide/getting_started/index.md b/docs/user_guide/getting_started/index.md new file mode 100644 index 000000000..25fe3c62a --- /dev/null +++ b/docs/user_guide/getting_started/index.md @@ -0,0 +1,8 @@ +# Getting started + +```{toctree} +:titlesonly: +tutorial_quickstart.md +tutorial_output.ipynb +explanation_concepts.md +``` diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md index 207d713c5..b77ed24e9 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -6,137 +6,20 @@ Before diving into these advanced _how-to_ guides (🖥️), we suggest users ge 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 - ```{toctree} -:caption: Installation instructions -:name: installation :titlesonly: getting_started/installation.md +getting_started/index.md +examples/group_convert_models.md +examples/group_fieldsets.md +examples/group_particlesets.md +examples/group_kernels.md +examples/group_interpolation.md +examples/group_simulation.md +examples/group_example_kernels.md +examples/group_other.md ``` ```{note} If you have code that uses Parcels v3, you can migrate to Parcels v4 using [🎓 the v3 to v4 migration guide](v4-migration.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 -``` - -## Converting model data to FieldSets - -Below is a list of tutorials that show how to convert data from ocean (🌊) and atmospheric (🍃) models to Parcels FieldSets. - -```{toctree} -:caption: Converting 🌊 ocean models -:name: converting-ocean-models -:titlesonly: -examples/tutorial_nemo.ipynb -examples/tutorial_croco_3D.ipynb -examples/tutorial_mitgcm.ipynb -examples/tutorial_mom6.ipynb -examples/tutorial_delft3d.ipynb -examples/tutorial_fesom.ipynb -examples/tutorial_schism.ipynb -examples/explanation_writing_convert_functions.md -``` - -```{toctree} -:caption: Converting 🍃 atmospheric models -:name: converting-atmospheric-models -:titlesonly: -examples/tutorial_aifs.ipynb -``` - -## Work with FieldSets - -```{toctree} -:caption: Work with FieldSets -:name: work-with-fieldsets -:titlesonly: -examples/explanation_grids.ipynb -examples/tutorial_sigma_coordinates.ipynb -examples/tutorial_velocityconversion.ipynb -examples/tutorial_nestedgrids.ipynb -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 -examples/tutorial_sampling.ipynb -examples/tutorial_statuscodes.ipynb -examples/tutorial_write_in_kernel.ipynb -``` - -## Set interpolation methods - -```{toctree} -:caption: Set interpolation methods -:name: interpolation-methods -:titlesonly: - -examples/explanation_interpolation.md -examples/tutorial_interpolation.ipynb -examples/tutorial_peninsula_AvsCgrid.ipynb -examples/tutorial_stuck_particles.ipynb -examples/tutorial_unstuck_Agrid.ipynb -``` - - - -## Run a simulation - -```{toctree} -:caption: Run a simulation -:name: run-simulation -:titlesonly: -examples/explanation_performance.md -examples/tutorial_dt_integrators.ipynb -``` - -## Example Kernels - -```{toctree} -:caption: Example Kernels -:name: example-kernels -:titlesonly: -examples/tutorial_gsw_density.ipynb -examples/tutorial_Argofloats.ipynb -examples/tutorial_diffusion.ipynb -examples/tutorial_interaction.ipynb -``` - -## Other - -```{toctree} -:caption: Other -:name: other -:titlesonly: -📖 v4 development <../v4/index> -🎓 v3 to v4 migration guide -examples/tutorial_homepage_animation.md -``` - - From 5265144532b2edb52b81926800a9c1e7768d03d2 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Thu, 5 Nov 2026 07:10:29 +0100 Subject: [PATCH 02/11] Moving all files out of examples and getting_started To flatten and simplify user_guide (#2966) --- docs/user_guide/{getting_started => }/explanation_concepts.md | 0 docs/user_guide/{examples => }/explanation_grids.ipynb | 0 docs/user_guide/{examples => }/explanation_interpolation.md | 0 docs/user_guide/{examples => }/explanation_kernelloop.md | 0 docs/user_guide/{examples => }/explanation_performance.md | 0 .../{examples => }/explanation_writing_convert_functions.md | 0 docs/user_guide/{examples => }/group_convert_models.md | 0 docs/user_guide/{examples => }/group_example_kernels.md | 0 docs/user_guide/{examples => }/group_fieldsets.md | 0 .../{getting_started/index.md => group_gettingstarted.md} | 0 docs/user_guide/{examples => }/group_interpolation.md | 0 docs/user_guide/{examples => }/group_kernels.md | 0 docs/user_guide/{examples => }/group_other.md | 0 docs/user_guide/{examples => }/group_particlesets.md | 0 docs/user_guide/{examples => }/group_simulation.md | 0 docs/user_guide/{getting_started => }/installation.md | 0 docs/user_guide/{examples => }/tutorial_Argofloats.ipynb | 0 docs/user_guide/{examples => }/tutorial_aifs.ipynb | 0 docs/user_guide/{examples => }/tutorial_croco_3D.ipynb | 0 docs/user_guide/{examples => }/tutorial_delaystart.ipynb | 0 docs/user_guide/{examples => }/tutorial_delft3d.ipynb | 0 docs/user_guide/{examples => }/tutorial_diffusion.ipynb | 0 docs/user_guide/{examples => }/tutorial_dt_integrators.ipynb | 0 docs/user_guide/{examples => }/tutorial_fesom.ipynb | 0 docs/user_guide/{examples => }/tutorial_gsw_density.ipynb | 0 docs/user_guide/{examples => }/tutorial_homepage_animation.md | 0 docs/user_guide/{examples => }/tutorial_interaction.ipynb | 0 docs/user_guide/{examples => }/tutorial_interpolation.ipynb | 0 .../{examples => }/tutorial_manipulating_field_data.ipynb | 0 docs/user_guide/{examples => }/tutorial_mitgcm.ipynb | 0 docs/user_guide/{examples => }/tutorial_mom6.ipynb | 0 docs/user_guide/{examples => }/tutorial_nemo.ipynb | 0 docs/user_guide/{examples => }/tutorial_nestedgrids.ipynb | 0 docs/user_guide/{getting_started => }/tutorial_output.ipynb | 0 docs/user_guide/{examples => }/tutorial_peninsula_AvsCgrid.ipynb | 0 docs/user_guide/{getting_started => }/tutorial_quickstart.md | 0 docs/user_guide/{examples => }/tutorial_sampling.ipynb | 0 docs/user_guide/{examples => }/tutorial_schism.ipynb | 0 docs/user_guide/{examples => }/tutorial_sigma_coordinates.ipynb | 0 docs/user_guide/{examples => }/tutorial_statuscodes.md | 0 docs/user_guide/{examples => }/tutorial_stuck_particles.ipynb | 0 docs/user_guide/{examples => }/tutorial_unstuck_Agrid.ipynb | 0 docs/user_guide/{examples => }/tutorial_velocityconversion.ipynb | 0 docs/user_guide/{examples => }/tutorial_write_in_kernel.ipynb | 0 44 files changed, 0 insertions(+), 0 deletions(-) rename docs/user_guide/{getting_started => }/explanation_concepts.md (100%) rename docs/user_guide/{examples => }/explanation_grids.ipynb (100%) rename docs/user_guide/{examples => }/explanation_interpolation.md (100%) rename docs/user_guide/{examples => }/explanation_kernelloop.md (100%) rename docs/user_guide/{examples => }/explanation_performance.md (100%) rename docs/user_guide/{examples => }/explanation_writing_convert_functions.md (100%) rename docs/user_guide/{examples => }/group_convert_models.md (100%) rename docs/user_guide/{examples => }/group_example_kernels.md (100%) rename docs/user_guide/{examples => }/group_fieldsets.md (100%) rename docs/user_guide/{getting_started/index.md => group_gettingstarted.md} (100%) rename docs/user_guide/{examples => }/group_interpolation.md (100%) rename docs/user_guide/{examples => }/group_kernels.md (100%) rename docs/user_guide/{examples => }/group_other.md (100%) rename docs/user_guide/{examples => }/group_particlesets.md (100%) rename docs/user_guide/{examples => }/group_simulation.md (100%) rename docs/user_guide/{getting_started => }/installation.md (100%) rename docs/user_guide/{examples => }/tutorial_Argofloats.ipynb (100%) rename docs/user_guide/{examples => }/tutorial_aifs.ipynb (100%) rename docs/user_guide/{examples => }/tutorial_croco_3D.ipynb (100%) rename docs/user_guide/{examples => }/tutorial_delaystart.ipynb (100%) rename docs/user_guide/{examples => }/tutorial_delft3d.ipynb (100%) rename docs/user_guide/{examples => }/tutorial_diffusion.ipynb (100%) rename docs/user_guide/{examples => }/tutorial_dt_integrators.ipynb (100%) rename docs/user_guide/{examples => }/tutorial_fesom.ipynb (100%) rename docs/user_guide/{examples => }/tutorial_gsw_density.ipynb (100%) rename docs/user_guide/{examples => }/tutorial_homepage_animation.md (100%) rename docs/user_guide/{examples => }/tutorial_interaction.ipynb (100%) rename docs/user_guide/{examples => }/tutorial_interpolation.ipynb (100%) rename docs/user_guide/{examples => }/tutorial_manipulating_field_data.ipynb (100%) rename docs/user_guide/{examples => }/tutorial_mitgcm.ipynb (100%) rename docs/user_guide/{examples => }/tutorial_mom6.ipynb (100%) rename docs/user_guide/{examples => }/tutorial_nemo.ipynb (100%) rename docs/user_guide/{examples => }/tutorial_nestedgrids.ipynb (100%) rename docs/user_guide/{getting_started => }/tutorial_output.ipynb (100%) rename docs/user_guide/{examples => }/tutorial_peninsula_AvsCgrid.ipynb (100%) rename docs/user_guide/{getting_started => }/tutorial_quickstart.md (100%) rename docs/user_guide/{examples => }/tutorial_sampling.ipynb (100%) rename docs/user_guide/{examples => }/tutorial_schism.ipynb (100%) rename docs/user_guide/{examples => }/tutorial_sigma_coordinates.ipynb (100%) rename docs/user_guide/{examples => }/tutorial_statuscodes.md (100%) rename docs/user_guide/{examples => }/tutorial_stuck_particles.ipynb (100%) rename docs/user_guide/{examples => }/tutorial_unstuck_Agrid.ipynb (100%) rename docs/user_guide/{examples => }/tutorial_velocityconversion.ipynb (100%) rename docs/user_guide/{examples => }/tutorial_write_in_kernel.ipynb (100%) diff --git a/docs/user_guide/getting_started/explanation_concepts.md b/docs/user_guide/explanation_concepts.md similarity index 100% rename from docs/user_guide/getting_started/explanation_concepts.md rename to docs/user_guide/explanation_concepts.md diff --git a/docs/user_guide/examples/explanation_grids.ipynb b/docs/user_guide/explanation_grids.ipynb similarity index 100% rename from docs/user_guide/examples/explanation_grids.ipynb rename to docs/user_guide/explanation_grids.ipynb diff --git a/docs/user_guide/examples/explanation_interpolation.md b/docs/user_guide/explanation_interpolation.md similarity index 100% rename from docs/user_guide/examples/explanation_interpolation.md rename to docs/user_guide/explanation_interpolation.md diff --git a/docs/user_guide/examples/explanation_kernelloop.md b/docs/user_guide/explanation_kernelloop.md similarity index 100% rename from docs/user_guide/examples/explanation_kernelloop.md rename to docs/user_guide/explanation_kernelloop.md diff --git a/docs/user_guide/examples/explanation_performance.md b/docs/user_guide/explanation_performance.md similarity index 100% rename from docs/user_guide/examples/explanation_performance.md rename to docs/user_guide/explanation_performance.md diff --git a/docs/user_guide/examples/explanation_writing_convert_functions.md b/docs/user_guide/explanation_writing_convert_functions.md similarity index 100% rename from docs/user_guide/examples/explanation_writing_convert_functions.md rename to docs/user_guide/explanation_writing_convert_functions.md diff --git a/docs/user_guide/examples/group_convert_models.md b/docs/user_guide/group_convert_models.md similarity index 100% rename from docs/user_guide/examples/group_convert_models.md rename to docs/user_guide/group_convert_models.md diff --git a/docs/user_guide/examples/group_example_kernels.md b/docs/user_guide/group_example_kernels.md similarity index 100% rename from docs/user_guide/examples/group_example_kernels.md rename to docs/user_guide/group_example_kernels.md diff --git a/docs/user_guide/examples/group_fieldsets.md b/docs/user_guide/group_fieldsets.md similarity index 100% rename from docs/user_guide/examples/group_fieldsets.md rename to docs/user_guide/group_fieldsets.md diff --git a/docs/user_guide/getting_started/index.md b/docs/user_guide/group_gettingstarted.md similarity index 100% rename from docs/user_guide/getting_started/index.md rename to docs/user_guide/group_gettingstarted.md diff --git a/docs/user_guide/examples/group_interpolation.md b/docs/user_guide/group_interpolation.md similarity index 100% rename from docs/user_guide/examples/group_interpolation.md rename to docs/user_guide/group_interpolation.md diff --git a/docs/user_guide/examples/group_kernels.md b/docs/user_guide/group_kernels.md similarity index 100% rename from docs/user_guide/examples/group_kernels.md rename to docs/user_guide/group_kernels.md diff --git a/docs/user_guide/examples/group_other.md b/docs/user_guide/group_other.md similarity index 100% rename from docs/user_guide/examples/group_other.md rename to docs/user_guide/group_other.md diff --git a/docs/user_guide/examples/group_particlesets.md b/docs/user_guide/group_particlesets.md similarity index 100% rename from docs/user_guide/examples/group_particlesets.md rename to docs/user_guide/group_particlesets.md diff --git a/docs/user_guide/examples/group_simulation.md b/docs/user_guide/group_simulation.md similarity index 100% rename from docs/user_guide/examples/group_simulation.md rename to docs/user_guide/group_simulation.md diff --git a/docs/user_guide/getting_started/installation.md b/docs/user_guide/installation.md similarity index 100% rename from docs/user_guide/getting_started/installation.md rename to docs/user_guide/installation.md diff --git a/docs/user_guide/examples/tutorial_Argofloats.ipynb b/docs/user_guide/tutorial_Argofloats.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_Argofloats.ipynb rename to docs/user_guide/tutorial_Argofloats.ipynb diff --git a/docs/user_guide/examples/tutorial_aifs.ipynb b/docs/user_guide/tutorial_aifs.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_aifs.ipynb rename to docs/user_guide/tutorial_aifs.ipynb diff --git a/docs/user_guide/examples/tutorial_croco_3D.ipynb b/docs/user_guide/tutorial_croco_3D.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_croco_3D.ipynb rename to docs/user_guide/tutorial_croco_3D.ipynb diff --git a/docs/user_guide/examples/tutorial_delaystart.ipynb b/docs/user_guide/tutorial_delaystart.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_delaystart.ipynb rename to docs/user_guide/tutorial_delaystart.ipynb diff --git a/docs/user_guide/examples/tutorial_delft3d.ipynb b/docs/user_guide/tutorial_delft3d.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_delft3d.ipynb rename to docs/user_guide/tutorial_delft3d.ipynb diff --git a/docs/user_guide/examples/tutorial_diffusion.ipynb b/docs/user_guide/tutorial_diffusion.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_diffusion.ipynb rename to docs/user_guide/tutorial_diffusion.ipynb diff --git a/docs/user_guide/examples/tutorial_dt_integrators.ipynb b/docs/user_guide/tutorial_dt_integrators.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_dt_integrators.ipynb rename to docs/user_guide/tutorial_dt_integrators.ipynb diff --git a/docs/user_guide/examples/tutorial_fesom.ipynb b/docs/user_guide/tutorial_fesom.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_fesom.ipynb rename to docs/user_guide/tutorial_fesom.ipynb diff --git a/docs/user_guide/examples/tutorial_gsw_density.ipynb b/docs/user_guide/tutorial_gsw_density.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_gsw_density.ipynb rename to docs/user_guide/tutorial_gsw_density.ipynb diff --git a/docs/user_guide/examples/tutorial_homepage_animation.md b/docs/user_guide/tutorial_homepage_animation.md similarity index 100% rename from docs/user_guide/examples/tutorial_homepage_animation.md rename to docs/user_guide/tutorial_homepage_animation.md diff --git a/docs/user_guide/examples/tutorial_interaction.ipynb b/docs/user_guide/tutorial_interaction.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_interaction.ipynb rename to docs/user_guide/tutorial_interaction.ipynb diff --git a/docs/user_guide/examples/tutorial_interpolation.ipynb b/docs/user_guide/tutorial_interpolation.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_interpolation.ipynb rename to docs/user_guide/tutorial_interpolation.ipynb diff --git a/docs/user_guide/examples/tutorial_manipulating_field_data.ipynb b/docs/user_guide/tutorial_manipulating_field_data.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_manipulating_field_data.ipynb rename to docs/user_guide/tutorial_manipulating_field_data.ipynb diff --git a/docs/user_guide/examples/tutorial_mitgcm.ipynb b/docs/user_guide/tutorial_mitgcm.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_mitgcm.ipynb rename to docs/user_guide/tutorial_mitgcm.ipynb diff --git a/docs/user_guide/examples/tutorial_mom6.ipynb b/docs/user_guide/tutorial_mom6.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_mom6.ipynb rename to docs/user_guide/tutorial_mom6.ipynb diff --git a/docs/user_guide/examples/tutorial_nemo.ipynb b/docs/user_guide/tutorial_nemo.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_nemo.ipynb rename to docs/user_guide/tutorial_nemo.ipynb diff --git a/docs/user_guide/examples/tutorial_nestedgrids.ipynb b/docs/user_guide/tutorial_nestedgrids.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_nestedgrids.ipynb rename to docs/user_guide/tutorial_nestedgrids.ipynb diff --git a/docs/user_guide/getting_started/tutorial_output.ipynb b/docs/user_guide/tutorial_output.ipynb similarity index 100% rename from docs/user_guide/getting_started/tutorial_output.ipynb rename to docs/user_guide/tutorial_output.ipynb diff --git a/docs/user_guide/examples/tutorial_peninsula_AvsCgrid.ipynb b/docs/user_guide/tutorial_peninsula_AvsCgrid.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_peninsula_AvsCgrid.ipynb rename to docs/user_guide/tutorial_peninsula_AvsCgrid.ipynb diff --git a/docs/user_guide/getting_started/tutorial_quickstart.md b/docs/user_guide/tutorial_quickstart.md similarity index 100% rename from docs/user_guide/getting_started/tutorial_quickstart.md rename to docs/user_guide/tutorial_quickstart.md diff --git a/docs/user_guide/examples/tutorial_sampling.ipynb b/docs/user_guide/tutorial_sampling.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_sampling.ipynb rename to docs/user_guide/tutorial_sampling.ipynb diff --git a/docs/user_guide/examples/tutorial_schism.ipynb b/docs/user_guide/tutorial_schism.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_schism.ipynb rename to docs/user_guide/tutorial_schism.ipynb diff --git a/docs/user_guide/examples/tutorial_sigma_coordinates.ipynb b/docs/user_guide/tutorial_sigma_coordinates.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_sigma_coordinates.ipynb rename to docs/user_guide/tutorial_sigma_coordinates.ipynb diff --git a/docs/user_guide/examples/tutorial_statuscodes.md b/docs/user_guide/tutorial_statuscodes.md similarity index 100% rename from docs/user_guide/examples/tutorial_statuscodes.md rename to docs/user_guide/tutorial_statuscodes.md diff --git a/docs/user_guide/examples/tutorial_stuck_particles.ipynb b/docs/user_guide/tutorial_stuck_particles.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_stuck_particles.ipynb rename to docs/user_guide/tutorial_stuck_particles.ipynb diff --git a/docs/user_guide/examples/tutorial_unstuck_Agrid.ipynb b/docs/user_guide/tutorial_unstuck_Agrid.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_unstuck_Agrid.ipynb rename to docs/user_guide/tutorial_unstuck_Agrid.ipynb diff --git a/docs/user_guide/examples/tutorial_velocityconversion.ipynb b/docs/user_guide/tutorial_velocityconversion.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_velocityconversion.ipynb rename to docs/user_guide/tutorial_velocityconversion.ipynb diff --git a/docs/user_guide/examples/tutorial_write_in_kernel.ipynb b/docs/user_guide/tutorial_write_in_kernel.ipynb similarity index 100% rename from docs/user_guide/examples/tutorial_write_in_kernel.ipynb rename to docs/user_guide/tutorial_write_in_kernel.ipynb From 1027903ac8971d5aec3cde0a25ad9a815369dda7 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Thu, 5 Nov 2026 08:03:59 +0100 Subject: [PATCH 03/11] Update links in the user_guide --- README.md | 4 +-- docs/index.md | 6 ++-- docs/user_guide/explanation_concepts.md | 32 +++++++++---------- docs/user_guide/explanation_grids.ipynb | 4 +-- .../explanation_writing_convert_functions.md | 2 +- docs/user_guide/group_other.md | 4 +-- docs/user_guide/index.md | 20 ++++++------ docs/user_guide/installation.md | 2 +- docs/user_guide/tutorial_fesom.ipynb | 4 +-- .../user_guide/tutorial_homepage_animation.md | 2 +- docs/user_guide/tutorial_mom6.ipynb | 2 +- docs/user_guide/tutorial_output.ipynb | 2 +- docs/user_guide/tutorial_quickstart.md | 6 ++-- docs/user_guide/tutorial_schism.ipynb | 8 ++--- .../user_guide/tutorial_stuck_particles.ipynb | 4 +-- .../user_guide/tutorial_write_in_kernel.ipynb | 2 +- docs/user_guide/v4-migration.md | 22 ++++++------- pixi.toml | 2 +- src/parcels/kernels/_advectiondiffusion.py | 2 +- 19 files changed, 65 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index 934ca6825..052618a19 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ ![CopernicusParticles](https://github.com/Parcels-code/Parcels/blob/main/docs/_static/homepage.gif?raw=true) -_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](https://docs.parcels-code.org/en/latest/user_guide/examples/tutorial_homepage_animation.html) for the script to create this animation yourself._ +_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](https://docs.parcels-code.org/en/latest/user_guide/tutorial_homepage_animation.html) for the script to create this animation yourself._ ### Parcels manuscript and code @@ -38,7 +38,7 @@ _Kehl, C, PD Nooteboom, MLA Kaandorp and E van Sebille (2023) Efficiently simula ### Further information -See [parcels-code.org](http://parcels-code.org/) for further information about [installing](https://docs.parcels-code.org/en/latest/user_guide/getting_started/installation.html) and [running](https://docs.parcels-code.org/en/latest/user_guide/index.html) the Parcels code, as well as extended [API reference](https://docs.parcels-code.org/en/latest/reference/parcels/index.html) of the methods and classes. +See [parcels-code.org](http://parcels-code.org/) for further information about [installing](https://docs.parcels-code.org/en/latest/user_guide/installation.html) and [running](https://docs.parcels-code.org/en/latest/user_guide/index.html) the Parcels code, as well as extended [API reference](https://docs.parcels-code.org/en/latest/reference/parcels/index.html) of the methods and classes. ### Contributors diff --git a/docs/index.md b/docs/index.md index 212d5ea67..5255bbb75 100755 --- a/docs/index.md +++ b/docs/index.md @@ -6,13 +6,13 @@ Welcome to the documentation of Parcels. **Parcels** provides a set of Python cl :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 [Copernicus Marine Service](https://marine.copernicus.eu). See [here](./user_guide/examples/tutorial_homepage_animation.md) for the script to create this animation yourself._ +_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/tutorial_homepage_animation.md) for the script to create this animation yourself._ ```{note} You are viewing the documentation for Parcels {{ version }}. 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) +**Useful links**: [Installation instructions](user_guide/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) `````{grid} 1 2 2 2 :gutter: 4 @@ -22,7 +22,7 @@ You are viewing the documentation for Parcels {{ version }}. You can browse the ````{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/installation), run the [quickstart tutorial](user_guide/tutorial_quickstart), and learn the [key concepts](user_guide/explanation_concepts) to understand the package. +++ diff --git a/docs/user_guide/explanation_concepts.md b/docs/user_guide/explanation_concepts.md index af968ab83..949ead3a9 100644 --- a/docs/user_guide/explanation_concepts.md +++ b/docs/user_guide/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](../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% @@ -60,7 +60,7 @@ The user doesn't need to manually construct or manage grids - this is done inter ```{admonition} 📖 Read more about grids :class: seealso -- [Grids explanation](../examples/explanation_grids.ipynb) +- [Grids explanation](./explanation_grids.ipynb) ``` ### Interpolation @@ -69,12 +69,12 @@ To find the value of a {py:obj}`parcels.Field` at any particle location, Parcels ```{admonition} 📖 Read more about interpolation :class: seealso -- [Interpolation explanation](../examples/explanation_interpolation.md) +- [Interpolation explanation](./explanation_interpolation.md) ``` ```{admonition} 🖥️ Learn how to use Parcels interpolators :class: seealso -- [Interpolators guide](../examples/tutorial_interpolation.ipynb) +- [Interpolators guide](./tutorial_interpolation.ipynb) ``` ## 2. ParticleSet @@ -99,8 +99,8 @@ pset = parcels.ParticleSet( ```{admonition} 🖥️ Learn more about how to create ParticleSets :class: seealso -- [Release particles at different times](../examples/tutorial_delaystart.ipynb) -- [Sampling initial Field values](../examples/tutorial_sampling.ipynb#sampling-initial-field-values) +- [Release particles at different times](./tutorial_delaystart.ipynb) +- [Sampling initial Field values](./tutorial_sampling.ipynb#sampling-initial-field-values) ``` ## 3. Kernels @@ -133,7 +133,7 @@ Note that the (optional) `@parcels.validate_kernel` decorator can be used to ens Basic kernels are included in Parcels to compute advection and diffusion. The standard advection kernel is {py:obj}`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.t`, `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. +It is advised _not_ to update the particle coordinates (`particles.t`, `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](./explanation_kernelloop.md) to understand why. ``` (custom-kernel)= @@ -158,20 +158,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](../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](./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](../examples/explanation_kernelloop.md) +- [The Kernel loop](./explanation_kernelloop.md) ``` ```{admonition} 🖥️ Learn how to write Kernels :class: seealso -- [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). +- [Sample fields like temperature](./tutorial_sampling.ipynb). +- [Mimic the behaviour of ARGO floats](./tutorial_Argofloats.ipynb). +- [Add diffusion to approximate subgrid-scale processes and unresolved physics](./tutorial_diffusion.ipynb). +- [Convert velocities between units in m s-1 and degrees s-1](./tutorial_velocityconversion.ipynb). ``` ## 4. Execute @@ -195,10 +195,10 @@ pset.execute(kernels=kernels, dt=dt, runtime=runtime) To analyse the particle data generated in the simulation, we need to define a {py:obj}`parcels.ParticleFile` and add it as an argument to {py:func}`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 `t`, `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](../examples/tutorial_dt_integrators.ipynb) +- [Choose an appropriate timestep and integrator](./tutorial_dt_integrators.ipynb) - [Work with Parcels output](./tutorial_output.ipynb) ``` diff --git a/docs/user_guide/explanation_grids.ipynb b/docs/user_guide/explanation_grids.ipynb index 1fddce33d..9371c7e12 100644 --- a/docs/user_guide/explanation_grids.ipynb +++ b/docs/user_guide/explanation_grids.ipynb @@ -21,7 +21,7 @@ "\n", "A structured grid is composed of quadrilateral elements, that are indexed using 3D indices, like $(i,j,k)$. In `xarray` terminology, these indices correspond to [`dimensions`](https://docs.xarray.dev/en/latest/user-guide/terminology.html#term-Dimension). For example, in NEMO datasets, $(x,y)$ typically define these dimensions horizontally, where the physical coordinates are $(glamf, gphif)$. \n", "\n", - "A major benefit of structured grids is that grid cell neighbours are easily found by decrementing or incrementing these dimensions. However, in Parcels we either perform a binary search in the case of 1-dimensional coordinates, or use a [hash table](../../development/unstructured_grid_search.md) in the case of 2-dimensional coordinates.\n", + "A major benefit of structured grids is that grid cell neighbours are easily found by decrementing or incrementing these dimensions. However, in Parcels we either perform a binary search in the case of 1-dimensional coordinates, or use a [hash table](../development/unstructured_grid_search.md) in the case of 2-dimensional coordinates.\n", "\n", "There are two styles of structured grids, rectilinear and curvilinear, as shown in Figure 1 below.\n", "\n", @@ -30,7 +30,7 @@ "2. Curvilinear grids allow for curved grid lines, which allow for better representation of coastlines. Poles are often on land to avoid singularities in the ocean. As the spatial positions of their nodes (their [\"coordinates\" in xarray-parlance](https://docs.xarray.dev/en/latest/user-guide/terminology.html#term-Coordinate)) are stored in separate 2D arrays, moving to an eastward neighbour is not as simple as incrementing the $i$-th dimension by 1.\n", "\n", "
\n", - " \"Grid\n", + " \"Grid\n", "
Figure 1 - Grid discretisations handled by Parcels. In the horizontal plane; (a) rectilinear, (b) curvilinear. In the vertical plane; (c) z-levels, (d) sigma-levels. Adapted from the Parcels v2.0 paper
\n", "
\n", "\n", diff --git a/docs/user_guide/explanation_writing_convert_functions.md b/docs/user_guide/explanation_writing_convert_functions.md index b18f0ab94..0afcf394c 100644 --- a/docs/user_guide/explanation_writing_convert_functions.md +++ b/docs/user_guide/explanation_writing_convert_functions.md @@ -405,4 +405,4 @@ ds["grid"] = xr.DataArray( A contribution would typically include the function in `convert.py`, a test in `tests/test_convert.py`, and a tutorial notebook in the "Converting model data to FieldSets" section of this user guide. See the -[development guide](../../development/index.md) for how to get started. +[development guide](../development/index.md) for how to get started. diff --git a/docs/user_guide/group_other.md b/docs/user_guide/group_other.md index 1d541cc5d..579b63ab9 100644 --- a/docs/user_guide/group_other.md +++ b/docs/user_guide/group_other.md @@ -2,7 +2,7 @@ ```{toctree} :titlesonly: -📖 v4 development <../../v4/index> -🎓 v3 to v4 migration guide <../v4-migration> +📖 v4 development <../v4/index> +🎓 v3 to v4 migration guide tutorial_homepage_animation.md ``` diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md index b77ed24e9..e9fad49f6 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -8,16 +8,16 @@ For a description of the specific classes and functions, check out the [API refe ```{toctree} :titlesonly: -getting_started/installation.md -getting_started/index.md -examples/group_convert_models.md -examples/group_fieldsets.md -examples/group_particlesets.md -examples/group_kernels.md -examples/group_interpolation.md -examples/group_simulation.md -examples/group_example_kernels.md -examples/group_other.md +installation.md +group_gettingstarted.md +group_convert_models.md +group_fieldsets.md +group_particlesets.md +group_kernels.md +group_interpolation.md +group_simulation.md +group_example_kernels.md +group_other.md ``` ```{note} diff --git a/docs/user_guide/installation.md b/docs/user_guide/installation.md index e020e4929..79a4fbeef 100644 --- a/docs/user_guide/installation.md +++ b/docs/user_guide/installation.md @@ -37,4 +37,4 @@ pixi shell ## Installation for developers We also use Pixi for our normal development. -To install the latest development version, see the [development section in our contributing guide](../../development/index.md#development). +To install the latest development version, see the [development section in our contributing guide](../development/index.md#development). diff --git a/docs/user_guide/tutorial_fesom.ipynb b/docs/user_guide/tutorial_fesom.ipynb index c7b2ebf44..3001b08b3 100644 --- a/docs/user_guide/tutorial_fesom.ipynb +++ b/docs/user_guide/tutorial_fesom.ipynb @@ -18,7 +18,7 @@ "3. Build a {py:obj}`parcels.FieldSet` with {py:func}`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](./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), {py:func}`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](./tutorial_quickstart.md), {py:func}`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/tutorial_homepage_animation.md b/docs/user_guide/tutorial_homepage_animation.md index ab5bfe400..846998838 100644 --- a/docs/user_guide/tutorial_homepage_animation.md +++ b/docs/user_guide/tutorial_homepage_animation.md @@ -145,4 +145,4 @@ anim.save( The resulting animation is then -![gif](../../_static/homepage.gif) +![gif](../_static/homepage.gif) diff --git a/docs/user_guide/tutorial_mom6.ipynb b/docs/user_guide/tutorial_mom6.ipynb index 12e45a1ea..e8ebb440a 100644 --- a/docs/user_guide/tutorial_mom6.ipynb +++ b/docs/user_guide/tutorial_mom6.ipynb @@ -7,7 +7,7 @@ "source": [ "# 🖥️ MOM6 tutorial\n", "\n", - "This tutorial shows how to run a surface (2D) simulation with output from the [MOM6](https://github.com/mom-ocean/MOM6) ocean model. MOM6 uses a curvilinear Arakawa C-grid: U is defined on the eastern cell faces `(yh, xq)`, V on the northern cell faces `(yq, xh)`, and the grid geometry is given by the cell corners `geolon_c`/`geolat_c` on `(yq, xq)`. Parcels has built-in functionality to deal with C-grid data, so the velocities can be used on the native grid without regridding or rotating them. See also the [NEMO tutorial](https://docs.parcels-code.org/en/latest/user_guide/examples/tutorial_nemo.html) and [MITgcm tutorial](https://docs.parcels-code.org/en/latest/user_guide/examples/tutorial_mitgcm.html) for other examples of C-grid data.\n", + "This tutorial shows how to run a surface (2D) simulation with output from the [MOM6](https://github.com/mom-ocean/MOM6) ocean model. MOM6 uses a curvilinear Arakawa C-grid: U is defined on the eastern cell faces `(yh, xq)`, V on the northern cell faces `(yq, xh)`, and the grid geometry is given by the cell corners `geolon_c`/`geolat_c` on `(yq, xq)`. Parcels has built-in functionality to deal with C-grid data, so the velocities can be used on the native grid without regridding or rotating them. See also the [NEMO tutorial](./tutorial_nemo.ipynb) and [MITgcm tutorial](./tutorial_mitgcm.ipynb) for other examples of C-grid data.\n", "\n", "```{note}\n", "The MOM6-to-SGRID converter currently only works with 2-dimensional (surface) velocity fields. If you have a dataset with 3-dimensional velocity fields, please raise an Issue on the [Parcels GitHub repository](https://github.com/Parcels-code/parcels/issues), specifying the details of your dataset and then we can provide guidance on how to handle it.\n", diff --git a/docs/user_guide/tutorial_output.ipynb b/docs/user_guide/tutorial_output.ipynb index 1905ed92d..ddc6e4059 100644 --- a/docs/user_guide/tutorial_output.ipynb +++ b/docs/user_guide/tutorial_output.ipynb @@ -45,7 +45,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "First we need to create some Parcels output to analyse. We simulate a set of particles using the setup described in the [Delay start tutorial](../examples/tutorial_delaystart.ipynb). We will also add some user defined metadata to the output file." + "First we need to create some Parcels output to analyse. We simulate a set of particles using the setup described in the [Delay start tutorial](./tutorial_delaystart.ipynb). We will also add some user defined metadata to the output file." ] }, { diff --git a/docs/user_guide/tutorial_quickstart.md b/docs/user_guide/tutorial_quickstart.md index 4155718de..7e9683e6f 100644 --- a/docs/user_guide/tutorial_quickstart.md +++ b/docs/user_guide/tutorial_quickstart.md @@ -61,7 +61,7 @@ ds_fset = parcels.convert.copernicusmarine_to_sgrid(fields=fields) fieldset = parcels.FieldSet.from_sgrid_conventions(ds_fset) ``` -Now, in order to improve performance, we can convert the {py:obj}`parcels.FieldSet` to windowed arrays. This is especially useful for large datasets with many timeslices, as it allows Parcels to load only the necessary timeslices into memory during the simulation. For more information about squeezing performance out of Parcels, see the [performance tutorial](../examples/explanation_performance.md). +Now, in order to improve performance, we can convert the {py:obj}`parcels.FieldSet` to windowed arrays. This is especially useful for large datasets with many timeslices, as it allows Parcels to load only the necessary timeslices into memory during the simulation. For more information about squeezing performance out of Parcels, see the [performance tutorial](./explanation_performance.md). ```{code-cell} # Convert the FieldSet to windowed arrays for better performance @@ -89,7 +89,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 {py:obj}`parcels.ParticleSet` object also needs to know about the {py:obj}`parcels.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 `t`, `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](../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](./tutorial_Argofloats.ipynb). ```{code-cell} # Particle locations and initial time @@ -120,7 +120,7 @@ If you also want to sample the initial value of a field, you can do so by callin pset.temperature = fieldset.thetao[pset] ``` -See the [sampling tutorial](../examples/tutorial_sampling.ipynb#sampling-initial-field-values) for more information on initial sampling of fields. +See the [sampling tutorial](./tutorial_sampling.ipynb#sampling-initial-field-values) for more information on initial sampling of fields. ## Compute: `Kernel` diff --git a/docs/user_guide/tutorial_schism.ipynb b/docs/user_guide/tutorial_schism.ipynb index a81b4cb97..589ca63fd 100644 --- a/docs/user_guide/tutorial_schism.ipynb +++ b/docs/user_guide/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](./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", - "We open them with {py:func}`parcels.tutorial.open_dataset()`, as in the [quickstart](../getting_started/tutorial_quickstart.md):" + "We open them with {py:func}`parcels.tutorial.open_dataset()`, as in the [quickstart](./tutorial_quickstart.md):" ] }, { @@ -422,7 +422,7 @@ " from the *smallest* cells and *fastest* flows that your particles will visit, not from the domain\n", " average. See [choosing a timestep and integration method](./tutorial_dt_integrators.ipynb).\n", "\n", - " ![CFL number for u and v near a SCHISM river inflow with dt = 5 minutes](../../_static/schism_inflow_cfl.png)\n", + " ![CFL number for u and v near a SCHISM river inflow with dt = 5 minutes](../_static/schism_inflow_cfl.png)\n", "\n", "* **Interpolation and no-normal-flow at boundaries.** The interpolator determines the discrete,\n", " continuous velocity field that particles actually feel, and it does not necessarily preserve the\n", @@ -433,7 +433,7 @@ " the [interpolation tutorial](./tutorial_interpolation.ipynb) and the\n", " [interpolators overview](./explanation_interpolation.md) for the available options and their properties.\n", "\n", - " ![u and v velocity in the outermost cells of a SCHISM river inflow](../../_static/schism_inflow_wall_velocity.png)\n", + " ![u and v velocity in the outermost cells of a SCHISM river inflow](../_static/schism_inflow_wall_velocity.png)\n", "\n", "* **Particles leaving the mesh.** Because of the two points above, some particles near the coast may\n", " still exit the mesh. Decide how to handle them: release particles away from the boundaries (as done\n", diff --git a/docs/user_guide/tutorial_stuck_particles.ipynb b/docs/user_guide/tutorial_stuck_particles.ipynb index 0a11ca700..3b95d4e02 100644 --- a/docs/user_guide/tutorial_stuck_particles.ipynb +++ b/docs/user_guide/tutorial_stuck_particles.ipynb @@ -623,7 +623,7 @@ "\n", "The cross-boundary component of velocity, defined at the cell faces where the boundary is defined, is set to zero at all boundaries. See the figure below. This corresponds exactly with the velocity field in a Parcels `FieldSet` shown in **figure 3**.\n", "\n", - "\n" + "\n" ] }, { @@ -633,7 +633,7 @@ "source": [ "There are different options for the along-boundary velocity in NEMO: a free-slip condition, a partial-slip condition and a no-slip condition. Since the tangential velocity is not defined at the boundary, this boundary condition is defined by a Neumann boundary condition: the normal derivative of the along-boundary velocity is specified. This derivative is schematically represented by a \"ghost\" velocity on the adjacent land node. The specified derivative is equivalent to what would result from the central difference between the along-boundary velocity at the nearest ocean cell and this \"ghost\" velocity. The type of boundary condition defines the direction and magnitude of this \"ghost\" velocity relative to the along-boundary velocity in the fluid domain. In Parcels, these \"ghost\" velocities may be used to determine how the velocity should be interpolated near the coast. By default, Parcels interpolates piecewise-constant in the direction normal to the velocity component. This means that the along-boundary velocity is the same for any distance away from the boundary and therefore equivalent to the free-slip boundary condition shown in subfigure **(a)** below.\n", "\n", - "\n" + "\n" ] }, { diff --git a/docs/user_guide/tutorial_write_in_kernel.ipynb b/docs/user_guide/tutorial_write_in_kernel.ipynb index e5eef9953..d299a3552 100644 --- a/docs/user_guide/tutorial_write_in_kernel.ipynb +++ b/docs/user_guide/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 ](./tutorial_output.ipynb)." ] }, { diff --git a/docs/user_guide/v4-migration.md b/docs/user_guide/v4-migration.md index 80048cc72..47d996bf7 100644 --- a/docs/user_guide/v4-migration.md +++ b/docs/user_guide/v4-migration.md @@ -99,7 +99,7 @@ Add the @parcels.validate_kernel decorator above your Kernel functi The Kernel loop is 'vectorized': the input of a Kernel is a collection of particles
-Replace if-statements with numpy.where statements or boolean indexing +Replace if-statements with numpy.where statements or boolean indexing
@@ -155,7 +155,7 @@ Change the argument name in your Kernel signature to particles particle.delete() is no longer valid
-Use StatusCode.Delete in combination with boolean indexing - as detailed here +Use StatusCode.Delete in combination with boolean indexing - as detailed here
@@ -171,7 +171,7 @@ Use fieldset.context or particle data to share information between kernels The InteractionKernel class is removed as normal Kernels now have access to all particles
-Particle-particle interaction can be performed within normal Kernels +Particle-particle interaction can be performed within normal Kernels
@@ -179,12 +179,12 @@ Particle-particle interaction can be -Explicitly use convert_z_to_sigma_croco in sampling kernels (such as the AdvectionRK4_3D_CROCO or SampleOMegaCroco kernels) when working with CROCO data +Explicitly use convert_z_to_sigma_croco in sampling kernels (such as the AdvectionRK4_3D_CROCO or SampleOMegaCroco kernels) when working with CROCO data
-The default advection scheme is changed from RK4 to RK2 as it is faster while the accuracy is comparable for most applications +The default advection scheme is changed from RK4 to RK2 as it is faster while the accuracy is comparable for most applications
Use pset.execute(parcels.AdvectionRK2) for advection @@ -201,7 +201,7 @@ Use pset.execute(parcels.AdvectionRK2) for advection FieldSet.from_<modelname>() is removed
-Convert the model data first to SGrid (for example with a parcels.covert_<MODEL>_to_sgrid() function) and then use FieldSet.from_sgrid_conventions(), as also described in the Quickstart tutorial +Convert the model data first to SGrid (for example with a parcels.covert_<MODEL>_to_sgrid() function) and then use FieldSet.from_sgrid_conventions(), as also described in the Quickstart tutorial
@@ -261,7 +261,7 @@ Simply pass the function(s) as a list to pset.execute() repeatdt is removed
-See the Delayed starts tutorial for how to implement repeated releases of particles +See the Delayed starts tutorial for how to implement repeated releases of particles
@@ -285,7 +285,7 @@ Update runtime and endtime to use numpy.datetime ParticleSet.from_field(), ParticleSet.from_line(), ParticleSet.from_list() are removed
-Use the ParticleSet constructor directly +Use the ParticleSet constructor directly
@@ -296,7 +296,7 @@ Use the ParticleSet con
-ParticleFiles output is in parquet format +ParticleFiles output is in parquet format
Read the output with polars.read_parquet() or (to automatically handle cftime) parcels.read_particlefile(). For compatility with old postprocessing codes, convert the new Parquet output to v3-style zarr output using parcels.particlefile_to_v3_zarr() @@ -355,7 +355,7 @@ Either write all timesteps of a variable, or none Particles are not written when they are deleted
-Call ParticleFile.write() inside a kernel to write out deleted particles +Call ParticleFile.write() inside a kernel to write out deleted particles
@@ -385,7 +385,7 @@ Use Field.eval() as before, but expect an array of floats instead o The NestedField class is removed
-See the Nested Grids tutorial for how to set up Nested Grids in v4 +See the Nested Grids tutorial for how to set up Nested Grids in v4
diff --git a/pixi.toml b/pixi.toml index a390f6e08..fb6b9d419 100644 --- a/pixi.toml +++ b/pixi.toml @@ -146,7 +146,7 @@ docs-run-notebook = { cmd = "rm -rf tmp-docs-run-notebook && mkdir tmp-docs-run- "file", ], description = "Execute a single MyST notebook (.md) or Jupyter notebook (.ipynb) outside of the docs build." } docs-linkcheck = { cmd = "make linkcheck", cwd = "docs", description = "Verify all links in documentation don't 404." } -docs-spelling = { cmd = "python tools/lint_british_english.py docs/user_guide/examples/tutorial*.ipynb docs/user_guide/examples/tutorial*.md docs/user_guide/getting_started/tutorial*.ipynb docs/user_guide/getting_started/tutorial*.md", description = "Check tutorial prose uses British English." } +docs-spelling = { cmd = "python tools/lint_british_english.py docs/user_guide/tutorial*.ipynb docs/user_guide/tutorial*.md docs/user_guide/tutorial*.ipynb docs/user_guide/tutorial*.md", description = "Check tutorial prose uses British English." } more-qaqc = { depends-on = [ "docs-spelling", ], description = "Additional QAQC tooling separate to pre-commit hooks" } diff --git a/src/parcels/kernels/_advectiondiffusion.py b/src/parcels/kernels/_advectiondiffusion.py index c6732f526..2d9c9e61e 100644 --- a/src/parcels/kernels/_advectiondiffusion.py +++ b/src/parcels/kernels/_advectiondiffusion.py @@ -1,6 +1,6 @@ """Collection of pre-built advection-diffusion kernels. -See `this tutorial <../examples/tutorial_diffusion.ipynb>`__ for a detailed explanation. +See `this tutorial <./tutorial_diffusion.ipynb>`__ for a detailed explanation. """ import numpy as np From 0186731b51a9ed6365d36fbe2c1cf8894681c9c2 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Thu, 5 Nov 2026 11:23:33 +0100 Subject: [PATCH 04/11] Separating convert into two groups --- .../group_convert_atmospheric_models.md | 6 ++++++ docs/user_guide/group_convert_models.md | 21 ++----------------- docs/user_guide/group_convert_ocean_models.md | 13 ++++++++++++ docs/user_guide/index.md | 1 + 4 files changed, 22 insertions(+), 19 deletions(-) create mode 100644 docs/user_guide/group_convert_atmospheric_models.md create mode 100644 docs/user_guide/group_convert_ocean_models.md diff --git a/docs/user_guide/group_convert_atmospheric_models.md b/docs/user_guide/group_convert_atmospheric_models.md new file mode 100644 index 000000000..144e3eedf --- /dev/null +++ b/docs/user_guide/group_convert_atmospheric_models.md @@ -0,0 +1,6 @@ +# Converting 🍃 atmospheric models + +```{toctree} +:titlesonly: +tutorial_aifs.ipynb +``` diff --git a/docs/user_guide/group_convert_models.md b/docs/user_guide/group_convert_models.md index f29ecd5e8..e56bb4a80 100644 --- a/docs/user_guide/group_convert_models.md +++ b/docs/user_guide/group_convert_models.md @@ -2,25 +2,8 @@ Below is a list of tutorials that show how to convert data from ocean (🌊) and atmospheric (🍃) models to Parcels FieldSets. -## Converting 🌊 ocean models - -```{toctree} -:caption: Converting 🌊 ocean models -:titlesonly: -tutorial_nemo.ipynb -tutorial_croco_3D.ipynb -tutorial_mitgcm.ipynb -tutorial_mom6.ipynb -tutorial_delft3d.ipynb -tutorial_fesom.ipynb -tutorial_schism.ipynb -explanation_writing_convert_functions.md -``` - -## Converting 🍃 atmospheric models - ```{toctree} -:caption: Converting 🍃 atmospheric models :titlesonly: -tutorial_aifs.ipynb +group_convert_ocean_models.md +group_convert_atmospheric_models.md ``` diff --git a/docs/user_guide/group_convert_ocean_models.md b/docs/user_guide/group_convert_ocean_models.md new file mode 100644 index 000000000..83c7ac6d0 --- /dev/null +++ b/docs/user_guide/group_convert_ocean_models.md @@ -0,0 +1,13 @@ +# Converting 🌊 ocean models + +```{toctree} +:titlesonly: +tutorial_nemo.ipynb +tutorial_croco_3D.ipynb +tutorial_mitgcm.ipynb +tutorial_mom6.ipynb +tutorial_delft3d.ipynb +tutorial_fesom.ipynb +tutorial_schism.ipynb +explanation_writing_convert_functions.md +``` diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md index e9fad49f6..ce24fa46f 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -8,6 +8,7 @@ For a description of the specific classes and functions, check out the [API refe ```{toctree} :titlesonly: +:maxdepth: 3 installation.md group_gettingstarted.md group_convert_models.md From 9a7017d5922ccabc0a1ad94e9dd6507c62a86e1b Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Thu, 5 Nov 2026 13:18:01 +0100 Subject: [PATCH 05/11] Reviewer feedback --- docs/user_guide/group_convert_concepts.md | 6 ++++++ docs/user_guide/group_convert_models.md | 1 + docs/user_guide/group_convert_ocean_models.md | 1 - docs/user_guide/{group_other.md => group_misc.md} | 2 +- docs/user_guide/index.md | 2 +- 5 files changed, 9 insertions(+), 3 deletions(-) create mode 100644 docs/user_guide/group_convert_concepts.md rename docs/user_guide/{group_other.md => group_misc.md} (89%) diff --git a/docs/user_guide/group_convert_concepts.md b/docs/user_guide/group_convert_concepts.md new file mode 100644 index 000000000..8be1a256d --- /dev/null +++ b/docs/user_guide/group_convert_concepts.md @@ -0,0 +1,6 @@ +# Converter concepts + +```{toctree} +:titlesonly: +explanation_writing_convert_functions.md +``` diff --git a/docs/user_guide/group_convert_models.md b/docs/user_guide/group_convert_models.md index e56bb4a80..1126036d6 100644 --- a/docs/user_guide/group_convert_models.md +++ b/docs/user_guide/group_convert_models.md @@ -6,4 +6,5 @@ Below is a list of tutorials that show how to convert data from ocean (🌊) and :titlesonly: group_convert_ocean_models.md group_convert_atmospheric_models.md +group_convert_concepts.md ``` diff --git a/docs/user_guide/group_convert_ocean_models.md b/docs/user_guide/group_convert_ocean_models.md index 83c7ac6d0..0e21146bf 100644 --- a/docs/user_guide/group_convert_ocean_models.md +++ b/docs/user_guide/group_convert_ocean_models.md @@ -9,5 +9,4 @@ tutorial_mom6.ipynb tutorial_delft3d.ipynb tutorial_fesom.ipynb tutorial_schism.ipynb -explanation_writing_convert_functions.md ``` diff --git a/docs/user_guide/group_other.md b/docs/user_guide/group_misc.md similarity index 89% rename from docs/user_guide/group_other.md rename to docs/user_guide/group_misc.md index 579b63ab9..acae67517 100644 --- a/docs/user_guide/group_other.md +++ b/docs/user_guide/group_misc.md @@ -1,4 +1,4 @@ -# Other +# Miscellaneous ```{toctree} :titlesonly: diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md index ce24fa46f..26dbad84c 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -18,7 +18,7 @@ group_kernels.md group_interpolation.md group_simulation.md group_example_kernels.md -group_other.md +group_misc.md ``` ```{note} From 4fe20f72ad1d86770e707f61cbe5008999638b27 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Thu, 5 Nov 2026 13:27:53 +0100 Subject: [PATCH 06/11] Add copernicusmarine tutorial --- docs/user_guide/group_convert_ocean_models.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/user_guide/group_convert_ocean_models.md b/docs/user_guide/group_convert_ocean_models.md index 0e21146bf..f99e4ce64 100644 --- a/docs/user_guide/group_convert_ocean_models.md +++ b/docs/user_guide/group_convert_ocean_models.md @@ -2,6 +2,7 @@ ```{toctree} :titlesonly: +explanation_copernicusmarine.md tutorial_nemo.ipynb tutorial_croco_3D.ipynb tutorial_mitgcm.ipynb From d0d280780f7a372ba0a1f9706d94d20b8b7f7cd2 Mon Sep 17 00:00:00 2001 From: Vecko <36369090+VeckoTheGecko@users.noreply.github.com> Date: Thu, 5 Nov 2026 15:00:08 +0100 Subject: [PATCH 07/11] Configure redirects --- docs/conf.py | 40 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index 7f0e50e5c..b1a900333 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -89,7 +89,45 @@ # Redirects for moved/deleted pages, handled by sphinxext-rediraffe. Paths are relative to # the docs folder, e.g. "user_guide/examples/tutorial_old.ipynb": "user_guide/examples/tutorial_new.ipynb" -rediraffe_redirects = {} +rediraffe_redirects = { + # Flattening user_guide/examples and user_guide/getting_started into user_guide (GH-3038) + "user_guide/examples/explanation_copernicusmarine.md": "user_guide/explanation_copernicusmarine.md", + "user_guide/examples/explanation_grids.ipynb": "user_guide/explanation_grids.ipynb", + "user_guide/examples/explanation_interpolation.md": "user_guide/explanation_interpolation.md", + "user_guide/examples/explanation_kernelloop.md": "user_guide/explanation_kernelloop.md", + "user_guide/examples/explanation_performance.md": "user_guide/explanation_performance.md", + "user_guide/examples/explanation_writing_convert_functions.md": "user_guide/explanation_writing_convert_functions.md", + "user_guide/examples/tutorial_Argofloats.ipynb": "user_guide/tutorial_Argofloats.ipynb", + "user_guide/examples/tutorial_aifs.ipynb": "user_guide/tutorial_aifs.ipynb", + "user_guide/examples/tutorial_croco_3D.ipynb": "user_guide/tutorial_croco_3D.ipynb", + "user_guide/examples/tutorial_delaystart.ipynb": "user_guide/tutorial_delaystart.ipynb", + "user_guide/examples/tutorial_delft3d.ipynb": "user_guide/tutorial_delft3d.ipynb", + "user_guide/examples/tutorial_diffusion.ipynb": "user_guide/tutorial_diffusion.ipynb", + "user_guide/examples/tutorial_dt_integrators.ipynb": "user_guide/tutorial_dt_integrators.ipynb", + "user_guide/examples/tutorial_fesom.ipynb": "user_guide/tutorial_fesom.ipynb", + "user_guide/examples/tutorial_gsw_density.ipynb": "user_guide/tutorial_gsw_density.ipynb", + "user_guide/examples/tutorial_homepage_animation.md": "user_guide/tutorial_homepage_animation.md", + "user_guide/examples/tutorial_interaction.ipynb": "user_guide/tutorial_interaction.ipynb", + "user_guide/examples/tutorial_interpolation.ipynb": "user_guide/tutorial_interpolation.ipynb", + "user_guide/examples/tutorial_manipulating_field_data.ipynb": "user_guide/tutorial_manipulating_field_data.ipynb", + "user_guide/examples/tutorial_mitgcm.ipynb": "user_guide/tutorial_mitgcm.ipynb", + "user_guide/examples/tutorial_mom6.ipynb": "user_guide/tutorial_mom6.ipynb", + "user_guide/examples/tutorial_nemo.ipynb": "user_guide/tutorial_nemo.ipynb", + "user_guide/examples/tutorial_nestedgrids.ipynb": "user_guide/tutorial_nestedgrids.ipynb", + "user_guide/examples/tutorial_peninsula_AvsCgrid.ipynb": "user_guide/tutorial_peninsula_AvsCgrid.ipynb", + "user_guide/examples/tutorial_sampling.ipynb": "user_guide/tutorial_sampling.ipynb", + "user_guide/examples/tutorial_schism.ipynb": "user_guide/tutorial_schism.ipynb", + "user_guide/examples/tutorial_sigma_coordinates.ipynb": "user_guide/tutorial_sigma_coordinates.ipynb", + "user_guide/examples/tutorial_statuscodes.md": "user_guide/tutorial_statuscodes.md", + "user_guide/examples/tutorial_stuck_particles.ipynb": "user_guide/tutorial_stuck_particles.ipynb", + "user_guide/examples/tutorial_unstuck_Agrid.ipynb": "user_guide/tutorial_unstuck_Agrid.ipynb", + "user_guide/examples/tutorial_velocityconversion.ipynb": "user_guide/tutorial_velocityconversion.ipynb", + "user_guide/examples/tutorial_write_in_kernel.ipynb": "user_guide/tutorial_write_in_kernel.ipynb", + "user_guide/getting_started/explanation_concepts.md": "user_guide/explanation_concepts.md", + "user_guide/getting_started/installation.md": "user_guide/installation.md", + "user_guide/getting_started/tutorial_output.ipynb": "user_guide/tutorial_output.ipynb", + "user_guide/getting_started/tutorial_quickstart.md": "user_guide/tutorial_quickstart.md", +} # Tell Jinja2 templates the build is running on Read the Docs if os.environ.get("READTHEDOCS", "") == "True": From aecbbf589e0a2c215ff9b05b26f33c0aeefae040 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Thu, 5 Nov 2026 21:38:13 +0100 Subject: [PATCH 08/11] Pinning xgcm to min version for padding argument --- pixi.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pixi.toml b/pixi.toml index af7873c86..4e86bba39 100644 --- a/pixi.toml +++ b/pixi.toml @@ -92,7 +92,7 @@ gsw = "*" py-triangle = "*" cmocean = "*" cartopy = "*" -xgcm = "*" +xgcm = ">=0.10.0" [feature.devtools.dependencies] pdbpp = "*" From 864cae0bc779d3a330ba8228846cc27a030d7c13 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Thu, 5 Nov 2026 21:38:28 +0100 Subject: [PATCH 09/11] Renaming all docs pages --- README.md | 4 +- docs/conf.py | 70 ++++++++--------- docs/index.md | 4 +- ...tutorial_aifs.ipynb => convert_aifs.ipynb} | 2 +- ...smarine.md => convert_copernicusmarine.md} | 4 +- ..._croco_3D.ipynb => convert_croco_3D.ipynb} | 0 ...al_delft3d.ipynb => convert_delft3d.ipynb} | 4 +- ...torial_fesom.ipynb => convert_fesom.ipynb} | 6 +- ...rial_mitgcm.ipynb => convert_mitgcm.ipynb} | 2 +- ...tutorial_mom6.ipynb => convert_mom6.ipynb} | 2 +- ...tutorial_nemo.ipynb => convert_nemo.ipynb} | 0 ...rial_schism.ipynb => convert_schism.ipynb} | 18 ++--- ...ctions.md => convert_writing_functions.md} | 2 +- ...ofloats.ipynb => example_Argofloats.ipynb} | 0 ...iffusion.ipynb => example_diffusion.ipynb} | 0 ...ensity.ipynb => example_gsw_density.ipynb} | 0 ...action.ipynb => example_interaction.ipynb} | 0 ...tion_grids.ipynb => fieldsets_grids.ipynb} | 4 +- ...> fieldsets_manipulating_field_data.ipynb} | 10 +-- ...rids.ipynb => fieldsets_nestedgrids.ipynb} | 0 ...pynb => fieldsets_sigma_coordinates.ipynb} | 0 ...ynb => fieldsets_velocityconversion.ipynb} | 0 ...nb => fieldsets_xgcm_derived_fields.ipynb} | 24 ++++-- ...concepts.md => gettingstarted_concepts.md} | 32 ++++---- ...tput.ipynb => gettingstarted_output.ipynb} | 2 +- ...kstart.md => gettingstarted_quickstart.md} | 12 +-- .../group_convert_atmospheric_models.md | 2 +- docs/user_guide/group_convert_concepts.md | 2 +- docs/user_guide/group_convert_ocean_models.md | 16 ++-- docs/user_guide/group_example_kernels.md | 8 +- docs/user_guide/group_fieldsets.md | 12 +-- docs/user_guide/group_gettingstarted.md | 6 +- docs/user_guide/group_interpolation.md | 10 +-- docs/user_guide/group_kernels.md | 8 +- docs/user_guide/group_misc.md | 2 +- docs/user_guide/group_particlesets.md | 2 +- docs/user_guide/group_simulation.md | 4 +- docs/user_guide/index.md | 78 ++++++++++--------- docs/user_guide/installation.md | 2 +- ...lation.md => interpolation_explanation.md} | 2 +- ...=> interpolation_peninsula_AvsCgrid.ipynb} | 2 +- ...nb => interpolation_stuck_particles.ipynb} | 6 +- ...ion.ipynb => interpolation_tutorial.ipynb} | 6 +- ...pynb => interpolation_unstuck_Agrid.ipynb} | 4 +- ...rnelloop.md => kernels_loopexplanation.md} | 2 +- ..._sampling.ipynb => kernels_sampling.ipynb} | 10 +-- ..._statuscodes.md => kernels_statuscodes.md} | 4 +- ...el.ipynb => kernels_write_in_kernel.ipynb} | 2 +- ...nimation.md => misc_homepage_animation.md} | 0 ...rt.ipynb => particlesets_delaystart.ipynb} | 4 +- ....ipynb => simulation_dt_integrators.ipynb} | 2 +- ...rformance.md => simulation_performance.md} | 2 +- docs/user_guide/v4-migration.md | 22 +++--- src/parcels/kernels/_advectiondiffusion.py | 2 +- 54 files changed, 220 insertions(+), 204 deletions(-) rename docs/user_guide/{tutorial_aifs.ipynb => convert_aifs.ipynb} (99%) rename docs/user_guide/{explanation_copernicusmarine.md => convert_copernicusmarine.md} (95%) rename docs/user_guide/{tutorial_croco_3D.ipynb => convert_croco_3D.ipynb} (100%) rename docs/user_guide/{tutorial_delft3d.ipynb => convert_delft3d.ipynb} (98%) rename docs/user_guide/{tutorial_fesom.ipynb => convert_fesom.ipynb} (96%) rename docs/user_guide/{tutorial_mitgcm.ipynb => convert_mitgcm.ipynb} (97%) rename docs/user_guide/{tutorial_mom6.ipynb => convert_mom6.ipynb} (97%) rename docs/user_guide/{tutorial_nemo.ipynb => convert_nemo.ipynb} (100%) rename docs/user_guide/{tutorial_schism.ipynb => convert_schism.ipynb} (96%) rename docs/user_guide/{explanation_writing_convert_functions.md => convert_writing_functions.md} (99%) rename docs/user_guide/{tutorial_Argofloats.ipynb => example_Argofloats.ipynb} (100%) rename docs/user_guide/{tutorial_diffusion.ipynb => example_diffusion.ipynb} (100%) rename docs/user_guide/{tutorial_gsw_density.ipynb => example_gsw_density.ipynb} (100%) rename docs/user_guide/{tutorial_interaction.ipynb => example_interaction.ipynb} (100%) rename docs/user_guide/{explanation_grids.ipynb => fieldsets_grids.ipynb} (98%) rename docs/user_guide/{tutorial_manipulating_field_data.ipynb => fieldsets_manipulating_field_data.ipynb} (94%) rename docs/user_guide/{tutorial_nestedgrids.ipynb => fieldsets_nestedgrids.ipynb} (100%) rename docs/user_guide/{tutorial_sigma_coordinates.ipynb => fieldsets_sigma_coordinates.ipynb} (100%) rename docs/user_guide/{tutorial_velocityconversion.ipynb => fieldsets_velocityconversion.ipynb} (100%) rename docs/user_guide/{tutorial_xgcm_derived_fields.ipynb => fieldsets_xgcm_derived_fields.ipynb} (92%) rename docs/user_guide/{explanation_concepts.md => gettingstarted_concepts.md} (89%) rename docs/user_guide/{tutorial_output.ipynb => gettingstarted_output.ipynb} (99%) rename docs/user_guide/{tutorial_quickstart.md => gettingstarted_quickstart.md} (94%) rename docs/user_guide/{explanation_interpolation.md => interpolation_explanation.md} (98%) rename docs/user_guide/{tutorial_peninsula_AvsCgrid.ipynb => interpolation_peninsula_AvsCgrid.ipynb} (98%) rename docs/user_guide/{tutorial_stuck_particles.ipynb => interpolation_stuck_particles.ipynb} (98%) rename docs/user_guide/{tutorial_interpolation.ipynb => interpolation_tutorial.ipynb} (98%) rename docs/user_guide/{tutorial_unstuck_Agrid.ipynb => interpolation_unstuck_Agrid.ipynb} (98%) rename docs/user_guide/{explanation_kernelloop.md => kernels_loopexplanation.md} (98%) rename docs/user_guide/{tutorial_sampling.ipynb => kernels_sampling.ipynb} (97%) rename docs/user_guide/{tutorial_statuscodes.md => kernels_statuscodes.md} (93%) rename docs/user_guide/{tutorial_write_in_kernel.ipynb => kernels_write_in_kernel.ipynb} (99%) rename docs/user_guide/{tutorial_homepage_animation.md => misc_homepage_animation.md} (100%) rename docs/user_guide/{tutorial_delaystart.ipynb => particlesets_delaystart.ipynb} (97%) rename docs/user_guide/{tutorial_dt_integrators.ipynb => simulation_dt_integrators.ipynb} (99%) rename docs/user_guide/{explanation_performance.md => simulation_performance.md} (97%) diff --git a/README.md b/README.md index 052618a19..0702f5c68 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ [![asv](https://img.shields.io/badge/benchmarked%20by-asv-blue.svg?style=flat)](https://github.com/Parcels-code/parcels-benchmarks) [![codecov](https://codecov.io/gh/Parcels-code/parcels/branch/main/graph/badge.svg)](https://codecov.io/gh/Parcels-code/parcels) [![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/Parcels-code/parcels/main?labpath=docs%2Fuser_guide%2Fexamples%2Ftutorial_Argofloats.ipynb) +[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/Parcels-code/parcels/main?labpath=docs%2Fuser_guide%2Fconvert_Argofloats.ipynb) [![LinkedIn](https://custom-icon-badges.demolab.com/badge/LinkedIn-0A66C2?logo=linkedin-white&logoColor=fff)](https://www.linkedin.com/company/parcelscode/) > This branch contains version 4 of Parcels. Change to `v3-support` to see v3 (which is currently in maintainence mode) or the tags to browse stable versions of Parcels. @@ -20,7 +20,7 @@ ![CopernicusParticles](https://github.com/Parcels-code/Parcels/blob/main/docs/_static/homepage.gif?raw=true) -_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](https://docs.parcels-code.org/en/latest/user_guide/tutorial_homepage_animation.html) for the script to create this animation yourself._ +_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](https://docs.parcels-code.org/en/latest/user_guide/misc_homepage_animation.html) for the script to create this animation yourself._ ### Parcels manuscript and code diff --git a/docs/conf.py b/docs/conf.py index b1a900333..dc1dcf1fc 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -91,42 +91,42 @@ # the docs folder, e.g. "user_guide/examples/tutorial_old.ipynb": "user_guide/examples/tutorial_new.ipynb" rediraffe_redirects = { # Flattening user_guide/examples and user_guide/getting_started into user_guide (GH-3038) - "user_guide/examples/explanation_copernicusmarine.md": "user_guide/explanation_copernicusmarine.md", - "user_guide/examples/explanation_grids.ipynb": "user_guide/explanation_grids.ipynb", - "user_guide/examples/explanation_interpolation.md": "user_guide/explanation_interpolation.md", - "user_guide/examples/explanation_kernelloop.md": "user_guide/explanation_kernelloop.md", - "user_guide/examples/explanation_performance.md": "user_guide/explanation_performance.md", - "user_guide/examples/explanation_writing_convert_functions.md": "user_guide/explanation_writing_convert_functions.md", - "user_guide/examples/tutorial_Argofloats.ipynb": "user_guide/tutorial_Argofloats.ipynb", - "user_guide/examples/tutorial_aifs.ipynb": "user_guide/tutorial_aifs.ipynb", - "user_guide/examples/tutorial_croco_3D.ipynb": "user_guide/tutorial_croco_3D.ipynb", - "user_guide/examples/tutorial_delaystart.ipynb": "user_guide/tutorial_delaystart.ipynb", - "user_guide/examples/tutorial_delft3d.ipynb": "user_guide/tutorial_delft3d.ipynb", - "user_guide/examples/tutorial_diffusion.ipynb": "user_guide/tutorial_diffusion.ipynb", - "user_guide/examples/tutorial_dt_integrators.ipynb": "user_guide/tutorial_dt_integrators.ipynb", - "user_guide/examples/tutorial_fesom.ipynb": "user_guide/tutorial_fesom.ipynb", - "user_guide/examples/tutorial_gsw_density.ipynb": "user_guide/tutorial_gsw_density.ipynb", - "user_guide/examples/tutorial_homepage_animation.md": "user_guide/tutorial_homepage_animation.md", - "user_guide/examples/tutorial_interaction.ipynb": "user_guide/tutorial_interaction.ipynb", - "user_guide/examples/tutorial_interpolation.ipynb": "user_guide/tutorial_interpolation.ipynb", - "user_guide/examples/tutorial_manipulating_field_data.ipynb": "user_guide/tutorial_manipulating_field_data.ipynb", - "user_guide/examples/tutorial_mitgcm.ipynb": "user_guide/tutorial_mitgcm.ipynb", - "user_guide/examples/tutorial_mom6.ipynb": "user_guide/tutorial_mom6.ipynb", - "user_guide/examples/tutorial_nemo.ipynb": "user_guide/tutorial_nemo.ipynb", - "user_guide/examples/tutorial_nestedgrids.ipynb": "user_guide/tutorial_nestedgrids.ipynb", - "user_guide/examples/tutorial_peninsula_AvsCgrid.ipynb": "user_guide/tutorial_peninsula_AvsCgrid.ipynb", - "user_guide/examples/tutorial_sampling.ipynb": "user_guide/tutorial_sampling.ipynb", - "user_guide/examples/tutorial_schism.ipynb": "user_guide/tutorial_schism.ipynb", - "user_guide/examples/tutorial_sigma_coordinates.ipynb": "user_guide/tutorial_sigma_coordinates.ipynb", - "user_guide/examples/tutorial_statuscodes.md": "user_guide/tutorial_statuscodes.md", - "user_guide/examples/tutorial_stuck_particles.ipynb": "user_guide/tutorial_stuck_particles.ipynb", - "user_guide/examples/tutorial_unstuck_Agrid.ipynb": "user_guide/tutorial_unstuck_Agrid.ipynb", - "user_guide/examples/tutorial_velocityconversion.ipynb": "user_guide/tutorial_velocityconversion.ipynb", - "user_guide/examples/tutorial_write_in_kernel.ipynb": "user_guide/tutorial_write_in_kernel.ipynb", - "user_guide/getting_started/explanation_concepts.md": "user_guide/explanation_concepts.md", + "user_guide/examples/explanation_copernicusmarine.md": "user_guide/convert_copernicusmarine.md", + "user_guide/examples/explanation_grids.ipynb": "user_guide/fieldsets_grids.ipynb", + "user_guide/examples/explanation_interpolation.md": "user_guide/interpolation_explanation.md", + "user_guide/examples/explanation_kernelloop.md": "user_guide/kernels_loopexplanation.md", + "user_guide/examples/explanation_performance.md": "user_guide/simulation_performance.md", + "user_guide/examples/explanation_writing_convert_functions.md": "user_guide/convert_writing_functions.md", + "user_guide/examples/tutorial_Argofloats.ipynb": "user_guide/example_Argofloats.ipynb", + "user_guide/examples/tutorial_aifs.ipynb": "user_guide/convert_aifs.ipynb", + "user_guide/examples/tutorial_croco_3D.ipynb": "user_guide/convert_croco_3D.ipynb", + "user_guide/examples/tutorial_delaystart.ipynb": "user_guide/particlesets_delaystart.ipynb", + "user_guide/examples/tutorial_delft3d.ipynb": "user_guide/convert_delft3d.ipynb", + "user_guide/examples/tutorial_diffusion.ipynb": "user_guide/example_diffusion.ipynb", + "user_guide/examples/tutorial_dt_integrators.ipynb": "user_guide/simulation_dt_integrators.ipynb", + "user_guide/examples/tutorial_fesom.ipynb": "user_guide/convert_fesom.ipynb", + "user_guide/examples/tutorial_gsw_density.ipynb": "user_guide/example_gsw_density.ipynb", + "user_guide/examples/tutorial_homepage_animation.md": "user_guide/misc_homepage_animation.md", + "user_guide/examples/tutorial_interaction.ipynb": "user_guide/example_interaction.ipynb", + "user_guide/examples/tutorial_interpolation.ipynb": "user_guide/interpolation_tutorial.ipynb", + "user_guide/examples/tutorial_manipulating_field_data.ipynb": "user_guide/fieldsets_manipulating_field_data.ipynb", + "user_guide/examples/tutorial_mitgcm.ipynb": "user_guide/convert_mitgcm.ipynb", + "user_guide/examples/tutorial_mom6.ipynb": "user_guide/convert_mom6.ipynb", + "user_guide/examples/tutorial_nemo.ipynb": "user_guide/convert_nemo.ipynb", + "user_guide/examples/tutorial_nestedgrids.ipynb": "user_guide/fieldsets_nestedgrids.ipynb", + "user_guide/examples/tutorial_peninsula_AvsCgrid.ipynb": "user_guide/interpolation_peninsula_AvsCgrid.ipynb", + "user_guide/examples/tutorial_sampling.ipynb": "user_guide/kernels_sampling.ipynb", + "user_guide/examples/tutorial_schism.ipynb": "user_guide/convert_schism.ipynb", + "user_guide/examples/tutorial_sigma_coordinates.ipynb": "user_guide/fieldsets_sigma_coordinates.ipynb", + "user_guide/examples/tutorial_statuscodes.md": "user_guide/kernels_statuscodes.ipynb", + "user_guide/examples/tutorial_stuck_particles.ipynb": "user_guide/interpolation_stuck_particles.ipynb", + "user_guide/examples/tutorial_unstuck_Agrid.ipynb": "user_guide/interpolation_unstuck_Agrid.ipynb", + "user_guide/examples/tutorial_velocityconversion.ipynb": "user_guide/fieldsets_velocityconversion.ipynb", + "user_guide/examples/tutorial_write_in_kernel.ipynb": "user_guide/kernels_write_in_kernel.ipynb", + "user_guide/getting_started/explanation_concepts.md": "user_guide/gettingstarted_concepts.md", "user_guide/getting_started/installation.md": "user_guide/installation.md", - "user_guide/getting_started/tutorial_output.ipynb": "user_guide/tutorial_output.ipynb", - "user_guide/getting_started/tutorial_quickstart.md": "user_guide/tutorial_quickstart.md", + "user_guide/getting_started/tutorial_output.ipynb": "user_guide/gettingstarted_output.ipynb", + "user_guide/getting_started/tutorial_quickstart.md": "user_guide/gettingstarted_quickstart.md", } # Tell Jinja2 templates the build is running on Read the Docs diff --git a/docs/index.md b/docs/index.md index 5255bbb75..49997604f 100755 --- a/docs/index.md +++ b/docs/index.md @@ -6,7 +6,7 @@ Welcome to the documentation of Parcels. **Parcels** provides a set of Python cl :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 [Copernicus Marine Service](https://marine.copernicus.eu). See [here](./user_guide/tutorial_homepage_animation.md) for the script to create this animation yourself._ +_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/misc_homepage_animation.md) for the script to create this animation yourself._ ```{note} You are viewing the documentation for Parcels {{ version }}. You can browse the documentation for older versions by using the version switcher in the bottom right. @@ -22,7 +22,7 @@ You are viewing the documentation for Parcels {{ version }}. You can browse the ````{grid-item-card} Getting started :shadow: md -New to Parcels? Check out the [installation instructions](user_guide/installation), run the [quickstart tutorial](user_guide/tutorial_quickstart), and learn the [key concepts](user_guide/explanation_concepts) to understand the package. +New to Parcels? Check out the [installation instructions](user_guide/installation), run the [quickstart tutorial](user_guide/gettingstarted_quickstart), and learn the [key concepts](user_guide/gettingstarted_concepts) to understand the package. +++ diff --git a/docs/user_guide/tutorial_aifs.ipynb b/docs/user_guide/convert_aifs.ipynb similarity index 99% rename from docs/user_guide/tutorial_aifs.ipynb rename to docs/user_guide/convert_aifs.ipynb index 704c45af6..c202d9fa2 100644 --- a/docs/user_guide/tutorial_aifs.ipynb +++ b/docs/user_guide/convert_aifs.ipynb @@ -165,7 +165,7 @@ "\n", "With the dataset prepared, we can build the {py:obj}`parcels.FieldSet` using {py:func}`parcels.FieldSet.from_sgrid_conventions()`. We pass `mesh=\"spherical\"` because the velocities are given in local (spherical) coordinates. For the interpolation of the 2D and 3D fields we choose linear interpolation, which is the method most commonly used in atmospheric Lagrangian transport models.\n", "\n", - "We also speed up the I/O by using the `ChunkCachedArray` backend - see the [squeezing performance out of Parcels](./explanation_performance.md) tutorial for more details.\n" + "We also speed up the I/O by using the `ChunkCachedArray` backend - see the [squeezing performance out of Parcels](./simulation_performance.md) tutorial for more details.\n" ] }, { diff --git a/docs/user_guide/explanation_copernicusmarine.md b/docs/user_guide/convert_copernicusmarine.md similarity index 95% rename from docs/user_guide/explanation_copernicusmarine.md rename to docs/user_guide/convert_copernicusmarine.md index dfac46d35..531d7c1e0 100644 --- a/docs/user_guide/explanation_copernicusmarine.md +++ b/docs/user_guide/convert_copernicusmarine.md @@ -73,13 +73,13 @@ ds_fields = parcels.convert.copernicusmarine_to_sgrid( fieldset = parcels.FieldSet.from_sgrid_conventions(ds_fields) ``` -Now, you will have to set the interpolation method for the UV fields to `XFreeslip`, which is more suitable for A-Grid data like the one provided by Copernicus Marine Service. This ensures that particles don't get stuck near the boundaries. See the [preventing stuck particles tutorial](./tutorial_unstuck_Agrid.ipynb) for more information. +Now, you will have to set the interpolation method for the UV fields to `XFreeslip`, which is more suitable for A-Grid data like the one provided by Copernicus Marine Service. This ensures that particles don't get stuck near the boundaries. See the [preventing stuck particles tutorial](./interpolation_unstuck_Agrid.ipynb) for more information. ``` fieldset.UV.interp_method = parcels.interpolators.XFreeslip() ``` -For [better performance](./explanation_performance.md), we should also use the `ChunkCachedArray` backend +For [better performance](./simulation_performance.md), we should also use the `ChunkCachedArray` backend ``` fieldset.to_chunk_cached_arrays() diff --git a/docs/user_guide/tutorial_croco_3D.ipynb b/docs/user_guide/convert_croco_3D.ipynb similarity index 100% rename from docs/user_guide/tutorial_croco_3D.ipynb rename to docs/user_guide/convert_croco_3D.ipynb diff --git a/docs/user_guide/tutorial_delft3d.ipynb b/docs/user_guide/convert_delft3d.ipynb similarity index 98% rename from docs/user_guide/tutorial_delft3d.ipynb rename to docs/user_guide/convert_delft3d.ipynb index 0904a51f4..34116ef24 100644 --- a/docs/user_guide/tutorial_delft3d.ipynb +++ b/docs/user_guide/convert_delft3d.ipynb @@ -241,7 +241,7 @@ "pset = parcels.ParticleSet(fieldset, x=X, y=Y)\n", "\n", "outfile = parcels.ParticleFile(\n", - " \"tutorial_delft3d_particles.parquet\", outputdt=np.timedelta64(15, \"m\"), mode=\"w\"\n", + " \"delft3d_particles.parquet\", outputdt=np.timedelta64(15, \"m\"), mode=\"w\"\n", ")\n", "\n", "pset.execute(\n", @@ -268,7 +268,7 @@ "metadata": {}, "outputs": [], "source": [ - "df = parcels.read_particlefile(\"tutorial_delft3d_particles.parquet\")\n", + "df = parcels.read_particlefile(\"delft3d_particles.parquet\")\n", "fig, ax = plt.subplots(figsize=(8, 6))\n", "ax.triplot(triang, color=\"k\", lw=0.3, alpha=0.5, label=\"Flow mesh\", zorder=2)\n", "ax.set_aspect(\"equal\")\n", diff --git a/docs/user_guide/tutorial_fesom.ipynb b/docs/user_guide/convert_fesom.ipynb similarity index 96% rename from docs/user_guide/tutorial_fesom.ipynb rename to docs/user_guide/convert_fesom.ipynb index 3001b08b3..4cba671d9 100644 --- a/docs/user_guide/tutorial_fesom.ipynb +++ b/docs/user_guide/convert_fesom.ipynb @@ -18,7 +18,7 @@ "3. Build a {py:obj}`parcels.FieldSet` with {py:func}`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](./tutorial_quickstart.md) first to get familiar with `ParticleSet`, `Kernel`, and `ParticleFile`." + "If you have not done so already, work through the [quickstart tutorial](./gettingstarted_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](./tutorial_quickstart.md), {py:func}`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](./gettingstarted_quickstart.md), {py:func}`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:" ] @@ -285,7 +285,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "The particles drift through the channel following the FESOM2 velocity field. From here, the rest of Parcels — custom kernels, sampling fields onto particles, writing your own interpolators — works identically to structured grids. See the [interpolation tutorial](./tutorial_interpolation.ipynb) for the available `Ux*` interpolators and how to write a custom one." + "The particles drift through the channel following the FESOM2 velocity field. From here, the rest of Parcels — custom kernels, sampling fields onto particles, writing your own interpolators — works identically to structured grids. See the [interpolation tutorial](./interpolation_tutorial.ipynb) for the available `Ux*` interpolators and how to write a custom one." ] } ], diff --git a/docs/user_guide/tutorial_mitgcm.ipynb b/docs/user_guide/convert_mitgcm.ipynb similarity index 97% rename from docs/user_guide/tutorial_mitgcm.ipynb rename to docs/user_guide/convert_mitgcm.ipynb index 49b0d2150..d05eef034 100644 --- a/docs/user_guide/tutorial_mitgcm.ipynb +++ b/docs/user_guide/convert_mitgcm.ipynb @@ -13,7 +13,7 @@ "id": "1", "metadata": {}, "source": [ - "This tutorial will show how to run a 3D simulation with output from the MITgcm model. The key thing about MITgcm is that its output is on a C-grid, which means that the U and V velocity components are not defined at the same location as the particle positions. Parcels has built-in functionality to deal with C-grid data. See also the [Nemo tutorial](tutorial_nemo.ipynb) for another example of C-grid data." + "This tutorial will show how to run a 3D simulation with output from the MITgcm model. The key thing about MITgcm is that its output is on a C-grid, which means that the U and V velocity components are not defined at the same location as the particle positions. Parcels has built-in functionality to deal with C-grid data. See also the [Nemo tutorial](convert_nemo.ipynb) for another example of C-grid data." ] }, { diff --git a/docs/user_guide/tutorial_mom6.ipynb b/docs/user_guide/convert_mom6.ipynb similarity index 97% rename from docs/user_guide/tutorial_mom6.ipynb rename to docs/user_guide/convert_mom6.ipynb index e8ebb440a..d67f9a64c 100644 --- a/docs/user_guide/tutorial_mom6.ipynb +++ b/docs/user_guide/convert_mom6.ipynb @@ -7,7 +7,7 @@ "source": [ "# 🖥️ MOM6 tutorial\n", "\n", - "This tutorial shows how to run a surface (2D) simulation with output from the [MOM6](https://github.com/mom-ocean/MOM6) ocean model. MOM6 uses a curvilinear Arakawa C-grid: U is defined on the eastern cell faces `(yh, xq)`, V on the northern cell faces `(yq, xh)`, and the grid geometry is given by the cell corners `geolon_c`/`geolat_c` on `(yq, xq)`. Parcels has built-in functionality to deal with C-grid data, so the velocities can be used on the native grid without regridding or rotating them. See also the [NEMO tutorial](./tutorial_nemo.ipynb) and [MITgcm tutorial](./tutorial_mitgcm.ipynb) for other examples of C-grid data.\n", + "This tutorial shows how to run a surface (2D) simulation with output from the [MOM6](https://github.com/mom-ocean/MOM6) ocean model. MOM6 uses a curvilinear Arakawa C-grid: U is defined on the eastern cell faces `(yh, xq)`, V on the northern cell faces `(yq, xh)`, and the grid geometry is given by the cell corners `geolon_c`/`geolat_c` on `(yq, xq)`. Parcels has built-in functionality to deal with C-grid data, so the velocities can be used on the native grid without regridding or rotating them. See also the [NEMO tutorial](./convert_nemo.ipynb) and [MITgcm tutorial](./convert_mitgcm.ipynb) for other examples of C-grid data.\n", "\n", "```{note}\n", "The MOM6-to-SGRID converter currently only works with 2-dimensional (surface) velocity fields. If you have a dataset with 3-dimensional velocity fields, please raise an Issue on the [Parcels GitHub repository](https://github.com/Parcels-code/parcels/issues), specifying the details of your dataset and then we can provide guidance on how to handle it.\n", diff --git a/docs/user_guide/tutorial_nemo.ipynb b/docs/user_guide/convert_nemo.ipynb similarity index 100% rename from docs/user_guide/tutorial_nemo.ipynb rename to docs/user_guide/convert_nemo.ipynb diff --git a/docs/user_guide/tutorial_schism.ipynb b/docs/user_guide/convert_schism.ipynb similarity index 96% rename from docs/user_guide/tutorial_schism.ipynb rename to docs/user_guide/convert_schism.ipynb index 589ca63fd..95fe1fc2c 100644 --- a/docs/user_guide/tutorial_schism.ipynb +++ b/docs/user_guide/convert_schism.ipynb @@ -20,7 +20,7 @@ "already follows the [UGRID](https://ugrid-conventions.github.io/ugrid-conventions/) conventions for\n", "its horizontal mesh, so `uxarray` can read it directly.\n", "\n", - "SCHISM output differs from the [FESOM tutorial](./tutorial_fesom.ipynb) in a few ways that this\n", + "SCHISM output differs from the [FESOM tutorial](./convert_fesom.ipynb) in a few ways that this\n", "tutorial highlights:\n", "\n", "1. The mesh coordinates are in a **projected coordinate system (meters)**, not longitude/latitude, so\n", @@ -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](./tutorial_quickstart.md) first to get familiar with\n", + "[quickstart tutorial](./gettingstarted_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", - "We open them with {py:func}`parcels.tutorial.open_dataset()`, as in the [quickstart](./tutorial_quickstart.md):" + "We open them with {py:func}`parcels.tutorial.open_dataset()`, as in the [quickstart](./gettingstarted_quickstart.md):" ] }, { @@ -201,7 +201,7 @@ "interpolator (barycentric in the horizontal, linear in the vertical) because the velocities are\n", "node-registered along the layer interfaces `zf`.\n", "\n", - "We convert the `FieldSet` to windowed arrays with {py:func}`parcels.FieldSet.to_windowed_arrays()` for [better performance](./explanation_performance.md) when advecting many particles." + "We convert the `FieldSet` to windowed arrays with {py:func}`parcels.FieldSet.to_windowed_arrays()` for [better performance](./simulation_performance.md) when advecting many particles." ] }, { @@ -401,7 +401,7 @@ " transport on an LSC2 grid would require Parcels to support a laterally varying vertical coordinate.\n", "* Add the vertical velocity as a `W` field and use `AdvectionRK4_3D` for three-dimensional transport\n", " (still subject to the single-column vertical approximation above).\n", - "* See the [interpolation tutorial](./tutorial_interpolation.ipynb) for the available `Ux*` interpolators." + "* See the [interpolation tutorial](./interpolation_tutorial.ipynb) for the available `Ux*` interpolators." ] }, { @@ -420,7 +420,7 @@ " $\\Delta x$ approximated by each triangle's shortest edge) is well above 1 in the narrow channel, so\n", " particles can jump across several cells, or out of the mesh entirely, in a single step. Choose `dt`\n", " from the *smallest* cells and *fastest* flows that your particles will visit, not from the domain\n", - " average. See [choosing a timestep and integration method](./tutorial_dt_integrators.ipynb).\n", + " average. See [choosing a timestep and integration method](./simulation_dt_integrators.ipynb).\n", "\n", " ![CFL number for u and v near a SCHISM river inflow with dt = 5 minutes](../_static/schism_inflow_cfl.png)\n", "\n", @@ -430,8 +430,8 @@ " the velocity in a triangle adjacent to the coastline is a blend of the node values, which need not\n", " be tangential to the wall. Zoomed in on the same inflow, the velocity in the outermost cells points\n", " through the boundary, so a particle in those cells can leave the domain even with a small `dt`. See\n", - " the [interpolation tutorial](./tutorial_interpolation.ipynb) and the\n", - " [interpolators overview](./explanation_interpolation.md) for the available options and their properties.\n", + " the [interpolation tutorial](./interpolation_tutorial.ipynb) and the\n", + " [interpolators overview](./interpolation_explanation.md) for the available options and their properties.\n", "\n", " ![u and v velocity in the outermost cells of a SCHISM river inflow](../_static/schism_inflow_wall_velocity.png)\n", "\n", @@ -439,7 +439,7 @@ " still exit the mesh. Decide how to handle them: release particles away from the boundaries (as done\n", " here with the `valid_levels` filter, whose threshold depends on your mesh), or catch the relevant\n", " status codes (e.g. add `parcels.StatusCode.ErrorGridSearching` to `OUT_OF_BOUNDS_STATES`) and stop\n", - " those particles. See [working with status codes](./tutorial_statuscodes.md)." + " those particles. See [working with status codes](./kernels_statuscodes.md)." ] } ], diff --git a/docs/user_guide/explanation_writing_convert_functions.md b/docs/user_guide/convert_writing_functions.md similarity index 99% rename from docs/user_guide/explanation_writing_convert_functions.md rename to docs/user_guide/convert_writing_functions.md index 0afcf394c..1fea9ae7d 100644 --- a/docs/user_guide/explanation_writing_convert_functions.md +++ b/docs/user_guide/convert_writing_functions.md @@ -9,7 +9,7 @@ kernelspec: Parcels reads structured-grid model data through {py:func}`parcels.FieldSet.from_sgrid_conventions`. This function does not guess how your model grid is laid out. Instead, it reads [SGRID](https://sgrid.github.io/sgrid/) metadata attached to the dataset, which provides information on which dimensions hold the cell corners, which dimensions hold the cell centres, and how -they line up. See the [Grids explanation](./explanation_grids.ipynb#nodes-edges-and-faces) for more on where data can +they line up. See the [Grids explanation](./fieldsets_grids.ipynb#nodes-edges-and-faces) for more on where data can sit on a grid cell. Most model output does not (yet) come with SGrid-compliant metadata. For that reason, Parcels ships a set of built-in `convert` functions in diff --git a/docs/user_guide/tutorial_Argofloats.ipynb b/docs/user_guide/example_Argofloats.ipynb similarity index 100% rename from docs/user_guide/tutorial_Argofloats.ipynb rename to docs/user_guide/example_Argofloats.ipynb diff --git a/docs/user_guide/tutorial_diffusion.ipynb b/docs/user_guide/example_diffusion.ipynb similarity index 100% rename from docs/user_guide/tutorial_diffusion.ipynb rename to docs/user_guide/example_diffusion.ipynb diff --git a/docs/user_guide/tutorial_gsw_density.ipynb b/docs/user_guide/example_gsw_density.ipynb similarity index 100% rename from docs/user_guide/tutorial_gsw_density.ipynb rename to docs/user_guide/example_gsw_density.ipynb diff --git a/docs/user_guide/tutorial_interaction.ipynb b/docs/user_guide/example_interaction.ipynb similarity index 100% rename from docs/user_guide/tutorial_interaction.ipynb rename to docs/user_guide/example_interaction.ipynb diff --git a/docs/user_guide/explanation_grids.ipynb b/docs/user_guide/fieldsets_grids.ipynb similarity index 98% rename from docs/user_guide/explanation_grids.ipynb rename to docs/user_guide/fieldsets_grids.ipynb index 9371c7e12..a6fa91b17 100644 --- a/docs/user_guide/explanation_grids.ipynb +++ b/docs/user_guide/fieldsets_grids.ipynb @@ -12,7 +12,7 @@ "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](group_convert_models.md) for all the models we have `convert` functions for. If your model is not on that list, you can [create your own `convert` function](./explanation_writing_convert_functions.md), or reach out on our discussion board for help.\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](group_convert_models.md) for all the models we have `convert` functions for. If your model is not on that list, you can [create your own `convert` function](./convert_writing_functions.md), 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 {py:func}`parcels.FieldSet.describe()` refers to.\n", @@ -333,7 +333,7 @@ "source": [ "### Vertical coordinates\n", "\n", - "Lastly, a short note on vertical coordinates. Parcels can handle two styles of vertical coordinates; z-levels which define fixed depth levels in physical space, and sigma-levels which define varying depth levels in physical space as a function of the water column depth. As sigma-levels are effectively \"terrain-following\", the grid cell faces may no longer be orthogonal to the domain surface. The bottom row of Figure 1 visualises these differences, and Parcels handles this all under the hood. See the [CROCO Tutorial](./tutorial_croco_3D.ipynb) for more details on the sigma-levels implementation.\n" + "Lastly, a short note on vertical coordinates. Parcels can handle two styles of vertical coordinates; z-levels which define fixed depth levels in physical space, and sigma-levels which define varying depth levels in physical space as a function of the water column depth. As sigma-levels are effectively \"terrain-following\", the grid cell faces may no longer be orthogonal to the domain surface. The bottom row of Figure 1 visualises these differences, and Parcels handles this all under the hood. See the [CROCO Tutorial](./convert_croco_3D.ipynb) for more details on the sigma-levels implementation.\n" ] } ], diff --git a/docs/user_guide/tutorial_manipulating_field_data.ipynb b/docs/user_guide/fieldsets_manipulating_field_data.ipynb similarity index 94% rename from docs/user_guide/tutorial_manipulating_field_data.ipynb rename to docs/user_guide/fieldsets_manipulating_field_data.ipynb index 6cf83a5e3..a2e756e52 100644 --- a/docs/user_guide/tutorial_manipulating_field_data.ipynb +++ b/docs/user_guide/fieldsets_manipulating_field_data.ipynb @@ -132,7 +132,7 @@ "## Summing Fields\n", "In some applications, you may want to sum multiple fields together to create a combined effect on particle movement. For example, you might want to combine ocean currents with wind-driven surface drift. This tutorial demonstrates how to sum multiple fields in Parcels and visualize the resulting particle trajectories.\n", "\n", - "We base this tutorial on the example provided in the [Parcels Kernel loop explanation](explanation_kernelloop.md). There, we combined two kernels to simulate the joint effect of currents and winds.\n", + "We base this tutorial on the example provided in the [Parcels Kernel loop explanation](kernels_loopexplanation.md). There, we combined two kernels to simulate the joint effect of currents and winds.\n", "\n", "However, we can also do that in one kernel, by combining the fields directly, using `xarray` operations.\n", "\n", @@ -201,7 +201,7 @@ "id": "15", "metadata": {}, "source": [ - "We can then run the same simulation as in the [Kernel loop explanation tutorial](explanation_kernelloop.md), but now using the combined fields. We only need the default advection kernel now, since the effects of both currents and winds are already included in the summed fields." + "We can then run the same simulation as in the [Kernel loop explanation tutorial](kernels_loopexplanation.md), but now using the combined fields. We only need the default advection kernel now, since the effects of both currents and winds are already included in the summed fields." ] }, { @@ -247,7 +247,7 @@ "id": "17", "metadata": {}, "source": [ - "We can then plot the trajectories, and confirm that they particles move the same as in the [Kernel loop explanation tutorial](explanation_kernelloop.md), where we combined the effects of currents and winds using two separate kernels." + "We can then plot the trajectories, and confirm that they particles move the same as in the [Kernel loop explanation tutorial](kernels_loopexplanation.md), where we combined the effects of currents and winds using two separate kernels." ] }, { @@ -268,7 +268,7 @@ ], "metadata": { "kernelspec": { - "display_name": "docs", + "display_name": "Parcels:default (3.14.8)", "language": "python", "name": "python3" }, @@ -282,7 +282,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.14.6" + "version": "3.14.8" }, "mystnb": { "execution_in_temp": true diff --git a/docs/user_guide/tutorial_nestedgrids.ipynb b/docs/user_guide/fieldsets_nestedgrids.ipynb similarity index 100% rename from docs/user_guide/tutorial_nestedgrids.ipynb rename to docs/user_guide/fieldsets_nestedgrids.ipynb diff --git a/docs/user_guide/tutorial_sigma_coordinates.ipynb b/docs/user_guide/fieldsets_sigma_coordinates.ipynb similarity index 100% rename from docs/user_guide/tutorial_sigma_coordinates.ipynb rename to docs/user_guide/fieldsets_sigma_coordinates.ipynb diff --git a/docs/user_guide/tutorial_velocityconversion.ipynb b/docs/user_guide/fieldsets_velocityconversion.ipynb similarity index 100% rename from docs/user_guide/tutorial_velocityconversion.ipynb rename to docs/user_guide/fieldsets_velocityconversion.ipynb diff --git a/docs/user_guide/tutorial_xgcm_derived_fields.ipynb b/docs/user_guide/fieldsets_xgcm_derived_fields.ipynb similarity index 92% rename from docs/user_guide/tutorial_xgcm_derived_fields.ipynb rename to docs/user_guide/fieldsets_xgcm_derived_fields.ipynb index b724f07a2..67c894b5f 100644 --- a/docs/user_guide/tutorial_xgcm_derived_fields.ipynb +++ b/docs/user_guide/fieldsets_xgcm_derived_fields.ipynb @@ -48,7 +48,7 @@ "source": [ "## Constructing the SGRID dataset\n", "\n", - "We use the surface velocities from an idealised, zonally re-entrant MITgcm channel simulation (see also the [MITgcm tutorial](tutorial_mitgcm.ipynb)). The grid is a Cartesian C-grid with 5 km spacing." + "We use the surface velocities from an idealised, zonally re-entrant MITgcm channel simulation (see also the [MITgcm tutorial](convert_mitgcm.ipynb)). The grid is a Cartesian C-grid with 5 km spacing." ] }, { @@ -182,7 +182,7 @@ "\\zeta = \\frac{\\delta_x (v \\, \\Delta y_C) - \\delta_y (u \\, \\Delta x_C)}{A_\\zeta},\n", "$$\n", "\n", - "where $\\delta_x$ and $\\delta_y$ are differences between neighbouring points, which is what {py:meth}`xgcm.Grid.diff` computes. Differencing `V` (on `(lat, XC)`) in X and `U` (on `(YC, lon)`) in Y both bring the result to the cell corners `(lat, lon)`." + "where $\\delta_x$ and $\\delta_y$ are differences between neighbouring points, which is what `xgcm.Grid.diff` computes. Differencing `V` (on `(lat, XC)`) in X and `U` (on `(YC, lon)`) in Y both bring the result to the cell corners `(lat, lon)`." ] }, { @@ -204,7 +204,8 @@ "id": "16", "metadata": {}, "source": [ - "Since the data is backed by Dask arrays, these computations are lazy: values are only computed when needed (see the [xgcm docs on Dask](https://xgcm.readthedocs.io/en/latest/xgcm-examples/04_eccov4/?h=dask#lazy-evaluation-and-parallelism-with-dask)).\n\n", + "Since the data is backed by Dask arrays, these computations are lazy: values are only computed when needed (see the [xgcm docs on Dask](https://xgcm.readthedocs.io/en/latest/xgcm-examples/04_eccov4/?h=dask#lazy-evaluation-and-parallelism-with-dask)).\n", + "\n", "Let's plot the vorticity at the first time step to check that it looks sensible. Since vorticity can be positive (anticlockwise) or negative (clockwise), we use a diverging colourmap centred on zero." ] }, @@ -268,7 +269,7 @@ "id": "21", "metadata": {}, "source": [ - "Following the [sampling tutorial](tutorial_sampling.ipynb), we create a particle class with a `vorticity` variable and a kernel that samples the field at the particle locations." + "Following the [sampling tutorial](kernels_sampling.ipynb), we create a particle class with a `vorticity` variable and a kernel that samples the field at the particle locations." ] }, { @@ -299,7 +300,7 @@ "id": "23", "metadata": {}, "source": [ - "We release a grid of particles at the surface at the start of the dataset and advect them for 8 days. As in the [MITgcm tutorial](tutorial_mitgcm.ipynb), particles that leave the domain are deleted. We also sample the vorticity at the initial particle locations before calling `pset.execute()`, so that the first entry in the output is not `NaN` (see the [sampling tutorial](tutorial_sampling.ipynb#sampling-initial-field-values))." + "We release a grid of particles at the surface at the start of the dataset and advect them for 8 days. As in the [MITgcm tutorial](convert_mitgcm.ipynb), particles that leave the domain are deleted. We also sample the vorticity at the initial particle locations before calling `pset.execute()`, so that the first entry in the output is not `NaN` (see the [sampling tutorial](kernels_sampling.ipynb#sampling-initial-field-values))." ] }, { @@ -388,12 +389,21 @@ ], "metadata": { "kernelspec": { - "display_name": "Parcels:docs", + "display_name": "Parcels:default (3.14.8)", "language": "python", "name": "python3" }, "language_info": { - "name": "python" + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.14.8" } }, "nbformat": 4, diff --git a/docs/user_guide/explanation_concepts.md b/docs/user_guide/gettingstarted_concepts.md similarity index 89% rename from docs/user_guide/explanation_concepts.md rename to docs/user_guide/gettingstarted_concepts.md index 949ead3a9..2cf7897b2 100644 --- a/docs/user_guide/explanation_concepts.md +++ b/docs/user_guide/gettingstarted_concepts.md @@ -17,7 +17,7 @@ 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](../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](./gettingstarted_quickstart.md) to start creating your first Parcels simulation. ```{figure} ../_static/concepts_diagram.png :alt: Parcels concepts diagram @@ -60,7 +60,7 @@ The user doesn't need to manually construct or manage grids - this is done inter ```{admonition} 📖 Read more about grids :class: seealso -- [Grids explanation](./explanation_grids.ipynb) +- [Grids explanation](./fieldsets_grids.ipynb) ``` ### Interpolation @@ -69,12 +69,12 @@ To find the value of a {py:obj}`parcels.Field` at any particle location, Parcels ```{admonition} 📖 Read more about interpolation :class: seealso -- [Interpolation explanation](./explanation_interpolation.md) +- [Interpolation explanation](./interpolation_explanation.md) ``` ```{admonition} 🖥️ Learn how to use Parcels interpolators :class: seealso -- [Interpolators guide](./tutorial_interpolation.ipynb) +- [Interpolators guide](./interpolation_tutorial.ipynb) ``` ## 2. ParticleSet @@ -99,8 +99,8 @@ pset = parcels.ParticleSet( ```{admonition} 🖥️ Learn more about how to create ParticleSets :class: seealso -- [Release particles at different times](./tutorial_delaystart.ipynb) -- [Sampling initial Field values](./tutorial_sampling.ipynb#sampling-initial-field-values) +- [Release particles at different times](./particlesets_delaystart.ipynb) +- [Sampling initial Field values](./kernels_sampling.ipynb#sampling-initial-field-values) ``` ## 3. Kernels @@ -133,7 +133,7 @@ Note that the (optional) `@parcels.validate_kernel` decorator can be used to ens Basic kernels are included in Parcels to compute advection and diffusion. The standard advection kernel is {py:obj}`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.t`, `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](./explanation_kernelloop.md) to understand why. +It is advised _not_ to update the particle coordinates (`particles.t`, `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](./kernels_loopexplanation.md) to understand why. ``` (custom-kernel)= @@ -158,20 +158,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](./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](./fieldsets_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](./explanation_kernelloop.md) +- [The Kernel loop](./kernels_loopexplanation.md) ``` ```{admonition} 🖥️ Learn how to write Kernels :class: seealso -- [Sample fields like temperature](./tutorial_sampling.ipynb). -- [Mimic the behaviour of ARGO floats](./tutorial_Argofloats.ipynb). -- [Add diffusion to approximate subgrid-scale processes and unresolved physics](./tutorial_diffusion.ipynb). -- [Convert velocities between units in m s-1 and degrees s-1](./tutorial_velocityconversion.ipynb). +- [Sample fields like temperature](./kernels_sampling.ipynb). +- [Mimic the behaviour of ARGO floats](./example_Argofloats.ipynb). +- [Add diffusion to approximate subgrid-scale processes and unresolved physics](./example_diffusion.ipynb). +- [Convert velocities between units in m s-1 and degrees s-1](./fieldsets_velocityconversion.ipynb). ``` ## 4. Execute @@ -195,10 +195,10 @@ pset.execute(kernels=kernels, dt=dt, runtime=runtime) To analyse the particle data generated in the simulation, we need to define a {py:obj}`parcels.ParticleFile` and add it as an argument to {py:func}`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 `t`, `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](./gettingstarted_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](./tutorial_dt_integrators.ipynb) -- [Work with Parcels output](./tutorial_output.ipynb) +- [Choose an appropriate timestep and integrator](./simulation_dt_integrators.ipynb) +- [Work with Parcels output](./gettingstarted_output.ipynb) ``` diff --git a/docs/user_guide/tutorial_output.ipynb b/docs/user_guide/gettingstarted_output.ipynb similarity index 99% rename from docs/user_guide/tutorial_output.ipynb rename to docs/user_guide/gettingstarted_output.ipynb index ddc6e4059..493f95e3f 100644 --- a/docs/user_guide/tutorial_output.ipynb +++ b/docs/user_guide/gettingstarted_output.ipynb @@ -45,7 +45,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "First we need to create some Parcels output to analyse. We simulate a set of particles using the setup described in the [Delay start tutorial](./tutorial_delaystart.ipynb). We will also add some user defined metadata to the output file." + "First we need to create some Parcels output to analyse. We simulate a set of particles using the setup described in the [Delay start tutorial](./particlesets_delaystart.ipynb). We will also add some user defined metadata to the output file." ] }, { diff --git a/docs/user_guide/tutorial_quickstart.md b/docs/user_guide/gettingstarted_quickstart.md similarity index 94% rename from docs/user_guide/tutorial_quickstart.md rename to docs/user_guide/gettingstarted_quickstart.md index 7e9683e6f..476338f8a 100644 --- a/docs/user_guide/tutorial_quickstart.md +++ b/docs/user_guide/gettingstarted_quickstart.md @@ -11,7 +11,7 @@ kernelspec: Welcome to the Parcels quickstart tutorial, in which we will go through all the necessary steps to run a simulation. The code in this notebook can be used as a starting point to run Parcels in your own environment. Along the way we will familiarize ourselves with some specific classes and methods. If you are ever confused about one of these and want to -read more, we have a [concepts overview](./explanation_concepts.md) discussing them in more detail. Let's dive in! +read more, we have a [concepts overview](./gettingstarted_concepts.md) discussing them in more detail. Let's dive in! ## Imports @@ -61,7 +61,7 @@ ds_fset = parcels.convert.copernicusmarine_to_sgrid(fields=fields) fieldset = parcels.FieldSet.from_sgrid_conventions(ds_fset) ``` -Now, in order to improve performance, we can convert the {py:obj}`parcels.FieldSet` to windowed arrays. This is especially useful for large datasets with many timeslices, as it allows Parcels to load only the necessary timeslices into memory during the simulation. For more information about squeezing performance out of Parcels, see the [performance tutorial](./explanation_performance.md). +Now, in order to improve performance, we can convert the {py:obj}`parcels.FieldSet` to windowed arrays. This is especially useful for large datasets with many timeslices, as it allows Parcels to load only the necessary timeslices into memory during the simulation. For more information about squeezing performance out of Parcels, see the [performance tutorial](./simulation_performance.md). ```{code-cell} # Convert the FieldSet to windowed arrays for better performance @@ -89,7 +89,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 {py:obj}`parcels.ParticleSet` object also needs to know about the {py:obj}`parcels.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 `t`, `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](./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](./example_Argofloats.ipynb). ```{code-cell} # Particle locations and initial time @@ -120,7 +120,7 @@ If you also want to sample the initial value of a field, you can do so by callin pset.temperature = fieldset.thetao[pset] ``` -See the [sampling tutorial](./tutorial_sampling.ipynb#sampling-initial-field-values) for more information on initial sampling of fields. +See the [sampling tutorial](./kernels_sampling.ipynb#sampling-initial-field-values) for more information on initial sampling of fields. ## Compute: `Kernel` @@ -143,7 +143,7 @@ output_file = parcels.ParticleFile("output-quickstart.parquet", outputdt=np.time ``` The output files are in `.parquet` [format](https://parquet.apache.org/), which can be read by [Polars](https://pola.rs/). -See the [Parcels output tutorial](./tutorial_output.ipynb) for more information on the parquet format. We want to choose +See the [Parcels output tutorial](./gettingstarted_output.ipynb) for more information on the parquet format. We want to choose the `outputdt` argument so that it captures the smallest timescales of our interest. ## Run Simulation: `ParticleSet.execute()` @@ -176,7 +176,7 @@ df ``` The file contains 250 rows: 25 observations for the 10 particle trajectories. -The [working with Parcels output tutorial](./tutorial_output.ipynb) provides more detail about the dataset and how to analyse it. +The [working with Parcels output tutorial](./gettingstarted_output.ipynb) provides more detail about the dataset and how to analyse it. Let's verify that Parcels has computed the advection of the virtual particles! diff --git a/docs/user_guide/group_convert_atmospheric_models.md b/docs/user_guide/group_convert_atmospheric_models.md index 144e3eedf..5f15752d0 100644 --- a/docs/user_guide/group_convert_atmospheric_models.md +++ b/docs/user_guide/group_convert_atmospheric_models.md @@ -2,5 +2,5 @@ ```{toctree} :titlesonly: -tutorial_aifs.ipynb +convert_aifs.ipynb ``` diff --git a/docs/user_guide/group_convert_concepts.md b/docs/user_guide/group_convert_concepts.md index 8be1a256d..b1f905c6c 100644 --- a/docs/user_guide/group_convert_concepts.md +++ b/docs/user_guide/group_convert_concepts.md @@ -2,5 +2,5 @@ ```{toctree} :titlesonly: -explanation_writing_convert_functions.md +convert_writing_functions.md ``` diff --git a/docs/user_guide/group_convert_ocean_models.md b/docs/user_guide/group_convert_ocean_models.md index f99e4ce64..e2ed4d6a2 100644 --- a/docs/user_guide/group_convert_ocean_models.md +++ b/docs/user_guide/group_convert_ocean_models.md @@ -2,12 +2,12 @@ ```{toctree} :titlesonly: -explanation_copernicusmarine.md -tutorial_nemo.ipynb -tutorial_croco_3D.ipynb -tutorial_mitgcm.ipynb -tutorial_mom6.ipynb -tutorial_delft3d.ipynb -tutorial_fesom.ipynb -tutorial_schism.ipynb +convert_copernicusmarine.md +convert_nemo.ipynb +convert_croco_3D.ipynb +convert_mitgcm.ipynb +convert_mom6.ipynb +convert_delft3d.ipynb +convert_fesom.ipynb +convert_schism.ipynb ``` diff --git a/docs/user_guide/group_example_kernels.md b/docs/user_guide/group_example_kernels.md index 39775cff8..440a04857 100644 --- a/docs/user_guide/group_example_kernels.md +++ b/docs/user_guide/group_example_kernels.md @@ -2,8 +2,8 @@ ```{toctree} :titlesonly: -tutorial_gsw_density.ipynb -tutorial_Argofloats.ipynb -tutorial_diffusion.ipynb -tutorial_interaction.ipynb +example_gsw_density.ipynb +example_Argofloats.ipynb +example_diffusion.ipynb +example_interaction.ipynb ``` diff --git a/docs/user_guide/group_fieldsets.md b/docs/user_guide/group_fieldsets.md index 389a08707..d6baeb31d 100644 --- a/docs/user_guide/group_fieldsets.md +++ b/docs/user_guide/group_fieldsets.md @@ -2,10 +2,10 @@ ```{toctree} :titlesonly: -explanation_grids.ipynb -tutorial_sigma_coordinates.ipynb -tutorial_velocityconversion.ipynb -tutorial_nestedgrids.ipynb -tutorial_manipulating_field_data.ipynb -tutorial_xgcm_derived_fields.ipynb +fieldsets_grids.ipynb +fieldsets_sigma_coordinates.ipynb +fieldsets_velocityconversion.ipynb +fieldsets_nestedgrids.ipynb +fieldsets_manipulating_field_data.ipynb +fieldsets_xgcm_derived_fields.ipynb ``` diff --git a/docs/user_guide/group_gettingstarted.md b/docs/user_guide/group_gettingstarted.md index 25fe3c62a..b26df50e8 100644 --- a/docs/user_guide/group_gettingstarted.md +++ b/docs/user_guide/group_gettingstarted.md @@ -2,7 +2,7 @@ ```{toctree} :titlesonly: -tutorial_quickstart.md -tutorial_output.ipynb -explanation_concepts.md +gettingstarted_quickstart.md +gettingstarted_output.ipynb +gettingstarted_concepts.md ``` diff --git a/docs/user_guide/group_interpolation.md b/docs/user_guide/group_interpolation.md index 6084adc64..ee17e9066 100644 --- a/docs/user_guide/group_interpolation.md +++ b/docs/user_guide/group_interpolation.md @@ -2,9 +2,9 @@ ```{toctree} :titlesonly: -explanation_interpolation.md -tutorial_interpolation.ipynb -tutorial_peninsula_AvsCgrid.ipynb -tutorial_stuck_particles.ipynb -tutorial_unstuck_Agrid.ipynb +interpolation_explanation.md +interpolation_tutorial.ipynb +interpolation_peninsula_AvsCgrid.ipynb +interpolation_stuck_particles.ipynb +interpolation_unstuck_Agrid.ipynb ``` diff --git a/docs/user_guide/group_kernels.md b/docs/user_guide/group_kernels.md index e6493509c..3e50ac6df 100644 --- a/docs/user_guide/group_kernels.md +++ b/docs/user_guide/group_kernels.md @@ -2,8 +2,8 @@ ```{toctree} :titlesonly: -explanation_kernelloop.md -tutorial_sampling.ipynb -tutorial_statuscodes.ipynb -tutorial_write_in_kernel.ipynb +kernels_loopexplanation.md +kernels_sampling.ipynb +kernels_statuscodes.ipynb +kernels_write_in_kernel.ipynb ``` diff --git a/docs/user_guide/group_misc.md b/docs/user_guide/group_misc.md index acae67517..5063ab9ab 100644 --- a/docs/user_guide/group_misc.md +++ b/docs/user_guide/group_misc.md @@ -4,5 +4,5 @@ :titlesonly: 📖 v4 development <../v4/index> 🎓 v3 to v4 migration guide -tutorial_homepage_animation.md +misc_homepage_animation.md ``` diff --git a/docs/user_guide/group_particlesets.md b/docs/user_guide/group_particlesets.md index 9c9e36bf1..a46bd6461 100644 --- a/docs/user_guide/group_particlesets.md +++ b/docs/user_guide/group_particlesets.md @@ -2,5 +2,5 @@ ```{toctree} :titlesonly: -tutorial_delaystart.ipynb +particlesets_delaystart.ipynb ``` diff --git a/docs/user_guide/group_simulation.md b/docs/user_guide/group_simulation.md index 7791bda5d..e160f9a7e 100644 --- a/docs/user_guide/group_simulation.md +++ b/docs/user_guide/group_simulation.md @@ -2,6 +2,6 @@ ```{toctree} :titlesonly: -explanation_performance.md -tutorial_dt_integrators.ipynb +simulation_performance.md +simulation_dt_integrators.ipynb ``` diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md index 1f1cc3816..ca13f578a 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -31,9 +31,9 @@ If you have code that uses Parcels v3, you can migrate to Parcels v4 using [🎓 :caption: Getting Started :name: getting-started :titlesonly: -getting_started/tutorial_quickstart.md -getting_started/tutorial_output.ipynb -getting_started/explanation_concepts.md +gettingstarted_quickstart.md +gettingstarted_output.ipynb +gettingstarted_concepts.md ``` ## Converting model data to FieldSets @@ -44,22 +44,28 @@ Below is a list of tutorials that show how to convert data from ocean (🌊) and :caption: Converting 🌊 ocean models :name: converting-ocean-models :titlesonly: -examples/explanation_copernicusmarine.md -examples/tutorial_nemo.ipynb -examples/tutorial_croco_3D.ipynb -examples/tutorial_mitgcm.ipynb -examples/tutorial_mom6.ipynb -examples/tutorial_delft3d.ipynb -examples/tutorial_fesom.ipynb -examples/tutorial_schism.ipynb -examples/explanation_writing_convert_functions.md +convert_copernicusmarine.md +convert_nemo.ipynb +convert_croco_3D.ipynb +convert_mitgcm.ipynb +convert_mom6.ipynb +convert_delft3d.ipynb +convert_fesom.ipynb +convert_schism.ipynb ``` ```{toctree} :caption: Converting 🍃 atmospheric models :name: converting-atmospheric-models :titlesonly: -examples/tutorial_aifs.ipynb +convert_aifs.ipynb +``` + +```{toctree} +:caption: Converter concepts +:name: converter-concepts +:titlesonly: +convert_writing_functions.md ``` ## Work with FieldSets @@ -68,12 +74,12 @@ examples/tutorial_aifs.ipynb :caption: Work with FieldSets :name: work-with-fieldsets :titlesonly: -examples/explanation_grids.ipynb -examples/tutorial_sigma_coordinates.ipynb -examples/tutorial_velocityconversion.ipynb -examples/tutorial_nestedgrids.ipynb -examples/tutorial_manipulating_field_data.ipynb -examples/tutorial_xgcm_derived_fields.ipynb +fieldsets_grids.ipynb +fieldsets_sigma_coordinates.ipynb +fieldsets_velocityconversion.ipynb +fieldsets_nestedgrids.ipynb +fieldsets_manipulating_field_data.ipynb +fieldsets_xgcm_derived_fields.ipynb ``` ## Create ParticleSets @@ -82,7 +88,7 @@ examples/tutorial_xgcm_derived_fields.ipynb :caption: Create ParticleSets :name: create-particlesets :titlesonly: -examples/tutorial_delaystart.ipynb +particlesets_delaystart.ipynb ``` ## Write Kernels @@ -92,10 +98,10 @@ examples/tutorial_delaystart.ipynb :name: write-kernels :titlesonly: -examples/explanation_kernelloop.md -examples/tutorial_sampling.ipynb -examples/tutorial_statuscodes.ipynb -examples/tutorial_write_in_kernel.ipynb +kernels_loopexplanation.md +kernels_sampling.ipynb +kernels_statuscodes.ipynb +kernels_write_in_kernel.ipynb ``` ## Set interpolation methods @@ -105,11 +111,11 @@ examples/tutorial_write_in_kernel.ipynb :name: interpolation-methods :titlesonly: -examples/explanation_interpolation.md -examples/tutorial_interpolation.ipynb -examples/tutorial_peninsula_AvsCgrid.ipynb -examples/tutorial_stuck_particles.ipynb -examples/tutorial_unstuck_Agrid.ipynb +interpolation_explanation.md +interpolation_tutorial.ipynb +interpolation_peninsula_AvsCgrid.ipynb +interpolation_stuck_particles.ipynb +interpolation_unstuck_Agrid.ipynb ``` @@ -120,8 +126,8 @@ examples/tutorial_unstuck_Agrid.ipynb :caption: Run a simulation :name: run-simulation :titlesonly: -examples/explanation_performance.md -examples/tutorial_dt_integrators.ipynb +simulation_performance.md +simulation_dt_integrators.ipynb ``` ## Example Kernels @@ -130,10 +136,10 @@ examples/tutorial_dt_integrators.ipynb :caption: Example Kernels :name: example-kernels :titlesonly: -examples/tutorial_gsw_density.ipynb -examples/tutorial_Argofloats.ipynb -examples/tutorial_diffusion.ipynb -examples/tutorial_interaction.ipynb +example_gsw_density.ipynb +example_Argofloats.ipynb +example_diffusion.ipynb +example_interaction.ipynb ``` ## Other @@ -144,7 +150,7 @@ examples/tutorial_interaction.ipynb :titlesonly: 📖 v4 development <../v4/index> 🎓 v3 to v4 migration guide -examples/tutorial_homepage_animation.md +misc_homepage_animation.md ``` diff --git a/docs/user_guide/installation.md b/docs/user_guide/installation.md index 79a4fbeef..31399e37e 100644 --- a/docs/user_guide/installation.md +++ b/docs/user_guide/installation.md @@ -16,7 +16,7 @@ conda create -n parcels-v4 -c conda-forge parcels cartopy jupyter conda activate parcels-v4 ``` -**Step 4:** Get started with the [quickstart tutorial](tutorial_quickstart.md), or first read about the most important [Parcels concepts](explanation_concepts.md). +**Step 4:** Get started with the [quickstart tutorial](gettingstarted_quickstart.md), or first read about the most important [Parcels concepts](gettingstarted_concepts.md). ## Installation of unreleased Parcels versions diff --git a/docs/user_guide/explanation_interpolation.md b/docs/user_guide/interpolation_explanation.md similarity index 98% rename from docs/user_guide/explanation_interpolation.md rename to docs/user_guide/interpolation_explanation.md index 51d5d5903..db472ad56 100644 --- a/docs/user_guide/explanation_interpolation.md +++ b/docs/user_guide/interpolation_explanation.md @@ -38,7 +38,7 @@ the requested value at the particles location. ## Interpolator API -The interpolators included in Parcels are designed for common interpolation schemes in Parcels simulations; see the [Using the built-in interpolators tutorial](./tutorial_interpolation.ipynb). +The interpolators included in Parcels are designed for common interpolation schemes in Parcels simulations; see the [Using the built-in interpolators tutorial](./interpolation_tutorial.ipynb). If we want to create a custom interpolation method, we need to look at the interpolator API. Each interpolator is a class that inherits from either the `ScalarInterpolator` or `VectorInterpolator` class. The `ScalarInterpolator` class is used for scalar fields, such as temperature or salinity, while the `VectorInterpolator` class is used for vector fields, such as velocity. diff --git a/docs/user_guide/tutorial_peninsula_AvsCgrid.ipynb b/docs/user_guide/interpolation_peninsula_AvsCgrid.ipynb similarity index 98% rename from docs/user_guide/tutorial_peninsula_AvsCgrid.ipynb rename to docs/user_guide/interpolation_peninsula_AvsCgrid.ipynb index 17ee45b54..42e3b30a1 100644 --- a/docs/user_guide/tutorial_peninsula_AvsCgrid.ipynb +++ b/docs/user_guide/interpolation_peninsula_AvsCgrid.ipynb @@ -11,7 +11,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "The notebook below shows how sensitive trajectories are to the combination of grid and velocity interpolation schemes. We will use the idealised Peninsula flowfield and carefully compare how trajectories on the [A-grid and C-grid](./explanation_grids.ipynb) version of this flow differ. To enhance the differences, we deliberately use a very coarse-resolution grid." + "The notebook below shows how sensitive trajectories are to the combination of grid and velocity interpolation schemes. We will use the idealised Peninsula flowfield and carefully compare how trajectories on the [A-grid and C-grid](./fieldsets_grids.ipynb) version of this flow differ. To enhance the differences, we deliberately use a very coarse-resolution grid." ] }, { diff --git a/docs/user_guide/tutorial_stuck_particles.ipynb b/docs/user_guide/interpolation_stuck_particles.ipynb similarity index 98% rename from docs/user_guide/tutorial_stuck_particles.ipynb rename to docs/user_guide/interpolation_stuck_particles.ipynb index 3b95d4e02..b7714e9b1 100644 --- a/docs/user_guide/tutorial_stuck_particles.ipynb +++ b/docs/user_guide/interpolation_stuck_particles.ipynb @@ -25,7 +25,7 @@ "\n", "**Short conclusion: Particles can get stuck on Arakawa A grids and B grids but should not get stuck on C grids.**\n", "\n", - "This tutorial first looks at how velocity fields are structured and what that means for where the ocean-land boundaries are located. Then we look at how particles may end up getting 'stuck' on these boundaries. How to make these particles become 'unstuck' again in Parcels will be discussed in [this notebook](./tutorial_unstuck_Agrid.ipynb).\n", + "This tutorial first looks at how velocity fields are structured and what that means for where the ocean-land boundaries are located. Then we look at how particles may end up getting 'stuck' on these boundaries. How to make these particles become 'unstuck' again in Parcels will be discussed in [this notebook](./interpolation_unstuck_Agrid.ipynb).\n", "\n", "- [Introduction](#introduction)\n", "- [A grid interpolated velocity fields](#a-grids)\n", @@ -43,7 +43,7 @@ "\n", "Parcels can handle several different types of velocity fields, which makes it widely applicable. This also means that the underlying code and therefore the accuracy of the calculated trajectories can differ, depending on the velocity data input. Even when Parcels runs smoothly with the velocity fields you use, it is good to realize how your velocity fields are structured and how those velocities are generated in the first place.\n", "\n", - "Horizontal velocity data may be structured on a staggered (Arakawa-C) or unstaggered grid (Arakawa-A). The implementation of these grids is covered in [this explainer](./explanation_grids.ipynb).\n", + "Horizontal velocity data may be structured on a staggered (Arakawa-C) or unstaggered grid (Arakawa-A). The implementation of these grids is covered in [this explainer](./fieldsets_grids.ipynb).\n", "\n", "The source of your velocity data will influence how accurate and physically consistent Parcels can calculate trajectories. Common sources are **numerical models and data assimilation products**, **interpolations** of those products or **discrete observations**. The staggering of variables determines how the ocean-land boundaries are defined in models and how their boundary conditions can be satisfied. The Parcels interpolation scheme differs per grid configuration and makes some underlying assumptions that determine the trajectory within a grid cell. Whether the source of your velocity data has physically consistent boundary conditions and how well these align with the assumptions made in Parcels determines how accurately the trajectories move within grid cells. This is especially important near ocean-land boundaries, where particles may end up 'stuck' on land.\n", "\n", @@ -794,7 +794,7 @@ "\n", "In many Parcels simulations other motions are added. Examples are Brownian motion from a diffusivity field and Stokes drift based on a wind field. These sources of motion will not necessarily consider the same boundaries and, unless they are also based on a C grid, they may also result in particles getting stuck on land. To show how this happens, let us add a random walk to the advection in a C grid velocity field.\n", "\n", - "This random walk can be added using a diffusion kernel, as documented in [this notebook](tutorial_diffusion.ipynb). Since the particles will move randomly through the domain, without awareness of the solid-fluid boundaries in the velocity field, we cannot define stuck particles as having moved less than a tolerance value and we will instead check whether particles find themselves on land or not. To do this, we sample the local velocities.\n" + "This random walk can be added using a diffusion kernel, as documented in [this notebook](example_diffusion.ipynb). Since the particles will move randomly through the domain, without awareness of the solid-fluid boundaries in the velocity field, we cannot define stuck particles as having moved less than a tolerance value and we will instead check whether particles find themselves on land or not. To do this, we sample the local velocities.\n" ] }, { diff --git a/docs/user_guide/tutorial_interpolation.ipynb b/docs/user_guide/interpolation_tutorial.ipynb similarity index 98% rename from docs/user_guide/tutorial_interpolation.ipynb rename to docs/user_guide/interpolation_tutorial.ipynb index f3ab9568f..6b825917c 100644 --- a/docs/user_guide/tutorial_interpolation.ipynb +++ b/docs/user_guide/interpolation_tutorial.ipynb @@ -6,7 +6,7 @@ "metadata": {}, "source": [ "# 🖥️ Using the built-in Interpolators\n", - "Parcels comes with a number of different interpolation methods for fields on structured (`X`) and unstructured (`Ux`) grids. Here, we will look at a few common {py:obj}`parcels.interpolators` for tracer fields, and how to configure them in an idealised example. For more guidance on the sampling of such fields, check out the [sampling tutorial](./tutorial_sampling)." + "Parcels comes with a number of different interpolation methods for fields on structured (`X`) and unstructured (`Ux`) grids. Here, we will look at a few common {py:obj}`parcels.interpolators` for tracer fields, and how to configure them in an idealised example. For more guidance on the sampling of such fields, check out the [sampling tutorial](./kernels_sampling)." ] }, { @@ -245,7 +245,7 @@ "source": [ "### Interpolation at boundaries\n", "In some cases, we need to implement specific boundary conditions, for example to prevent particles from \n", - "getting \"stuck\" near land. [This guide](./tutorial_unstuck_Agrid.ipynb) describes \n", + "getting \"stuck\" near land. [This guide](./interpolation_unstuck_Agrid.ipynb) describes \n", "how to implement this in Parcels using {py:obj}`parcels.interpolators.XFreeslip` and {py:obj}`parcels.interpolators.XPartialslip`." ] }, @@ -474,7 +474,7 @@ "metadata": {}, "source": [ "## Write your own interpolator\n", - "The interpolators included in Parcels are designed for common interpolation schemes in Parcels simulations. If we want to add a custom interpolation method, we can write a custom function (e.g. spline) using the [interpolator API](./explanation_interpolation.md#interpolator-api)." + "The interpolators included in Parcels are designed for common interpolation schemes in Parcels simulations. If we want to add a custom interpolation method, we can write a custom function (e.g. spline) using the [interpolator API](./interpolation_explanation.md#interpolator-api)." ] } ], diff --git a/docs/user_guide/tutorial_unstuck_Agrid.ipynb b/docs/user_guide/interpolation_unstuck_Agrid.ipynb similarity index 98% rename from docs/user_guide/tutorial_unstuck_Agrid.ipynb rename to docs/user_guide/interpolation_unstuck_Agrid.ipynb index 5d6afb3b1..9d5d4002f 100644 --- a/docs/user_guide/tutorial_unstuck_Agrid.ipynb +++ b/docs/user_guide/interpolation_unstuck_Agrid.ipynb @@ -13,7 +13,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "In [another notebook](tutorial_stuck_particles.ipynb), we have shown how particles may end up getting stuck on land, especially in A gridded velocity fields. Here we show how you can work around this problem and how large the effects of the solutions on the trajectories are.\n", + "In [another notebook](interpolation_stuck_particles.ipynb), we have shown how particles may end up getting stuck on land, especially in A gridded velocity fields. Here we show how you can work around this problem and how large the effects of the solutions on the trajectories are.\n", "\n", "Common solutions are:\n", "\n", @@ -33,7 +33,7 @@ "1. Flag particles within a specific distance to the shore\n", "2. Flag particles in any gridcell that has a shore edge\n", "\n", - "As argued in the [previous notebook](./tutorial_stuck_particles.ipynb), it is important to accurately plot the grid discretization, in order to understand the motion of particles near the boundary. The velocity fields can best be depicted using points or arrows that define the velocity at a single position. Four of these nodes then form gridcells that can be shown using tiles, for example with `matplotlib.pyplot.pcolormesh`.\n" + "As argued in the [previous notebook](./interpolation_stuck_particles.ipynb), it is important to accurately plot the grid discretization, in order to understand the motion of particles near the boundary. The velocity fields can best be depicted using points or arrows that define the velocity at a single position. Four of these nodes then form gridcells that can be shown using tiles, for example with `matplotlib.pyplot.pcolormesh`.\n" ] }, { diff --git a/docs/user_guide/explanation_kernelloop.md b/docs/user_guide/kernels_loopexplanation.md similarity index 98% rename from docs/user_guide/explanation_kernelloop.md rename to docs/user_guide/kernels_loopexplanation.md index a6a4677c2..0b5b25163 100644 --- a/docs/user_guide/explanation_kernelloop.md +++ b/docs/user_guide/kernels_loopexplanation.md @@ -47,7 +47,7 @@ Besides having commutable Kernels, the main advantage of this implementation is Below is a simple example of some particles at the surface of the ocean. We create an idealised zonal wind flow that will "push" a particle that is already affected by the surface currents. The Kernel loop ensures that these two forces act at the same time and location. ```{note} -Advecting particles by a combination of flow fields can be done with two separate kernels, as is shown below. However, it can also be done by summing the fields directly using `xarray` operations - provided the fields are defined on the same grid and have compatible dimensions. See the [manipulating field data tutorial](tutorial_manipulating_field_data.ipynb) for an example of that approach. +Advecting particles by a combination of flow fields can be done with two separate kernels, as is shown below. However, it can also be done by summing the fields directly using `xarray` operations - provided the fields are defined on the same grid and have compatible dimensions. See the [manipulating field data tutorial](fieldsets_manipulating_field_data.ipynb) for an example of that approach. ``` ```{code-cell} diff --git a/docs/user_guide/tutorial_sampling.ipynb b/docs/user_guide/kernels_sampling.ipynb similarity index 97% rename from docs/user_guide/tutorial_sampling.ipynb rename to docs/user_guide/kernels_sampling.ipynb index c0c330095..6e9460f08 100644 --- a/docs/user_guide/tutorial_sampling.ipynb +++ b/docs/user_guide/kernels_sampling.ipynb @@ -320,7 +320,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Instead, you should use the code `u, v = fieldset.UV[...]`. With this code, the sampling is consistent with the actual velocity fields used in the advection Kernels. The difference is that on a curvilinear grid, `fieldset.U[..]` returns the velocity in the `i`-direction (the columns on the grid), while `fieldset.UV[...]` returns the velocities in the longitude and latitude direction - see also the [velocity conversion tutorial](./tutorial_velocityconversion.ipynb). Furthermore, only `fieldset.UV[...]` sampling can correctly deal with boundary conditions such as `freeslip` and `partialslip` ([tutorial_unstuck_Agrid](tutorial_unstuck_Agrid.ipynb))\n" + "Instead, you should use the code `u, v = fieldset.UV[...]`. With this code, the sampling is consistent with the actual velocity fields used in the advection Kernels. The difference is that on a curvilinear grid, `fieldset.U[..]` returns the velocity in the `i`-direction (the columns on the grid), while `fieldset.UV[...]` returns the velocities in the longitude and latitude direction - see also the [velocity conversion tutorial](./fieldsets_velocityconversion.ipynb). Furthermore, only `fieldset.UV[...]` sampling can correctly deal with boundary conditions such as [`freeslip` and `partialslip` interpolation](interpolation_unstuck_Agrid.ipynb).\n" ] }, { @@ -381,7 +381,7 @@ "source": [ "
\n", "\n", - "Note that the Kernels above return the value of `U` and `V` in the units of the grid. That means that for a spherical grid, the velocities are in **degrees/s**. To convert these to **m/s**, see the [velocity conversion tutorial](./tutorial_velocityconversion.ipynb).\n", + "Note that the Kernels above return the value of `U` and `V` in the units of the grid. That means that for a spherical grid, the velocities are in **degrees/s**. To convert these to **m/s**, see the [velocity conversion tutorial](./fieldsets_velocityconversion.ipynb).\n", "
" ] } @@ -405,6 +405,9 @@ "pygments_lexer": "ipython3", "version": "3.14.6" }, + "mystnb": { + "execution_in_temp": true + }, "pycharm": { "stem_cell": { "cell_type": "raw", @@ -413,9 +416,6 @@ }, "source": [] } - }, - "mystnb": { - "execution_in_temp": true } }, "nbformat": 4, diff --git a/docs/user_guide/tutorial_statuscodes.md b/docs/user_guide/kernels_statuscodes.md similarity index 93% rename from docs/user_guide/tutorial_statuscodes.md rename to docs/user_guide/kernels_statuscodes.md index 84f85c5d2..a5aa33613 100644 --- a/docs/user_guide/tutorial_statuscodes.md +++ b/docs/user_guide/kernels_statuscodes.md @@ -6,7 +6,7 @@ kernelspec: # 🖥️ Working with Status Codes -In order to capture errors in the [Kernel loop](explanation_kernelloop.md), Parcels uses a Status Code system. There are several Status Codes, listed below. +In order to capture errors in the [Kernel loop](kernels_loopexplanation.md), Parcels uses a Status Code system. There are several Status Codes, listed below. ```{code-cell} import parcels @@ -96,5 +96,5 @@ print(f"particle z at end of run = {pset.z}") ``` ```{note} -Kernels that control what to do with `particles.state` should typically be added at the _end_ of the Kernel list, because otherwise later Kernels may overwrite the `particles.state` or the `particles.dx` variables (see [Kernel loop explanation](explanation_kernelloop.md)). +Kernels that control what to do with `particles.state` should typically be added at the _end_ of the Kernel list, because otherwise later Kernels may overwrite the `particles.state` or the `particles.dx` variables (see [Kernel loop explanation](kernels_loopexplanation.md)). ``` diff --git a/docs/user_guide/tutorial_write_in_kernel.ipynb b/docs/user_guide/kernels_write_in_kernel.ipynb similarity index 99% rename from docs/user_guide/tutorial_write_in_kernel.ipynb rename to docs/user_guide/kernels_write_in_kernel.ipynb index d299a3552..893b5a752 100644 --- a/docs/user_guide/tutorial_write_in_kernel.ipynb +++ b/docs/user_guide/kernels_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 ](./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 ](./gettingstarted_output.ipynb)." ] }, { diff --git a/docs/user_guide/tutorial_homepage_animation.md b/docs/user_guide/misc_homepage_animation.md similarity index 100% rename from docs/user_guide/tutorial_homepage_animation.md rename to docs/user_guide/misc_homepage_animation.md diff --git a/docs/user_guide/tutorial_delaystart.ipynb b/docs/user_guide/particlesets_delaystart.ipynb similarity index 97% rename from docs/user_guide/tutorial_delaystart.ipynb rename to docs/user_guide/particlesets_delaystart.ipynb index 7c4b183af..4729f6c6b 100644 --- a/docs/user_guide/tutorial_delaystart.ipynb +++ b/docs/user_guide/particlesets_delaystart.ipynb @@ -43,7 +43,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "First create a {py:obj}`parcels.FieldSet` (from the [Argo example](./tutorial_Argofloats.ipynb), in this case)" + "First create a {py:obj}`parcels.FieldSet` (from the [Argo example](./example_Argofloats.ipynb), in this case)" ] }, { @@ -363,7 +363,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "Now, for some applications, this behaviour may be undesirable; for example when particles need to be analysed at a same age (instead of at a same time). In that case, we recommend either changing `outputdt` so that it is a common divisor of all start times; or by [writing directly in the kernel](./tutorial_write_in_kernel.ipynb); or by doing multiple Parcels runs with subsets of the original `ParticleSet` (e.g., in the example above, one run with the Particles that start at `t=[0, 2]` and one with the Particle at `t=[1]`). In that case, you will get two files:\n" + "Now, for some applications, this behaviour may be undesirable; for example when particles need to be analysed at a same age (instead of at a same time). In that case, we recommend either changing `outputdt` so that it is a common divisor of all start times; or by [writing directly in the kernel](./kernels_write_in_kernel.ipynb); or by doing multiple Parcels runs with subsets of the original `ParticleSet` (e.g., in the example above, one run with the Particles that start at `t=[0, 2]` and one with the Particle at `t=[1]`). In that case, you will get two files:\n" ] }, { diff --git a/docs/user_guide/tutorial_dt_integrators.ipynb b/docs/user_guide/simulation_dt_integrators.ipynb similarity index 99% rename from docs/user_guide/tutorial_dt_integrators.ipynb rename to docs/user_guide/simulation_dt_integrators.ipynb index e352750b7..d45e3464c 100644 --- a/docs/user_guide/tutorial_dt_integrators.ipynb +++ b/docs/user_guide/simulation_dt_integrators.ipynb @@ -139,7 +139,7 @@ "source": [ "```{admonition} 🖥️ Spherical grids and unit converters\n", ":class: seealso\n", - "Our displacement occurs in units of longitude and latitde, but our velocity field is in m/s. That's why we have to convert the units of velocity from m/s to degrees/s. In Parcels, this is done automatically for `VectorFields` when using a `spherical` grid. See the [Spherical grids and velocity conversion guide](./tutorial_velocityconversion.ipynb) guide for more information.\n", + "Our displacement occurs in units of longitude and latitde, but our velocity field is in m/s. That's why we have to convert the units of velocity from m/s to degrees/s. In Parcels, this is done automatically for `VectorFields` when using a `spherical` grid. See the [Spherical grids and velocity conversion guide](./fieldsets_velocityconversion.ipynb) guide for more information.\n", "```" ] }, diff --git a/docs/user_guide/explanation_performance.md b/docs/user_guide/simulation_performance.md similarity index 97% rename from docs/user_guide/explanation_performance.md rename to docs/user_guide/simulation_performance.md index ae736ca67..3fa2a151c 100644 --- a/docs/user_guide/explanation_performance.md +++ b/docs/user_guide/simulation_performance.md @@ -82,7 +82,7 @@ fieldset.to_windowed_arrays() | | Does not work well for initial Field sampling when the particles start at different times, as Parcels will have to load all required timeslices into memory (see note below). | ```{note} - If your particles start at multiple times (e.g. [Delayed starts](./tutorial_delaystart.ipynb)), it's best to do the initial sampling with the FieldSet in Dask mode and only convert to WindowedArrays _after_ the initial sampling. + If your particles start at multiple times (e.g. [Delayed starts](./particlesets_delaystart.ipynb)), it's best to do the initial sampling with the FieldSet in Dask mode and only convert to WindowedArrays _after_ the initial sampling. ``` ## Option 4: use Dask diff --git a/docs/user_guide/v4-migration.md b/docs/user_guide/v4-migration.md index 47d996bf7..c7196ef32 100644 --- a/docs/user_guide/v4-migration.md +++ b/docs/user_guide/v4-migration.md @@ -99,7 +99,7 @@ Add the @parcels.validate_kernel decorator above your Kernel functi The Kernel loop is 'vectorized': the input of a Kernel is a collection of particles
-Replace if-statements with numpy.where statements or boolean indexing +Replace if-statements with numpy.where statements or boolean indexing
@@ -155,7 +155,7 @@ Change the argument name in your Kernel signature to particles particle.delete() is no longer valid
-Use StatusCode.Delete in combination with boolean indexing - as detailed here +Use StatusCode.Delete in combination with boolean indexing - as detailed here
@@ -171,7 +171,7 @@ Use fieldset.context or particle data to share information between kernels The InteractionKernel class is removed as normal Kernels now have access to all particles
-Particle-particle interaction can be performed within normal Kernels +Particle-particle interaction can be performed within normal Kernels
@@ -179,12 +179,12 @@ Particle-particle interaction can be perform Automatic conversion from depth to sigma grids under the hood is removed
-Explicitly use convert_z_to_sigma_croco in sampling kernels (such as the AdvectionRK4_3D_CROCO or SampleOMegaCroco kernels) when working with CROCO data +Explicitly use convert_z_to_sigma_croco in sampling kernels (such as the AdvectionRK4_3D_CROCO or SampleOMegaCroco kernels) when working with CROCO data
-The default advection scheme is changed from RK4 to RK2 as it is faster while the accuracy is comparable for most applications +The default advection scheme is changed from RK4 to RK2 as it is faster while the accuracy is comparable for most applications
Use pset.execute(parcels.AdvectionRK2) for advection @@ -201,7 +201,7 @@ Use pset.execute(parcels.AdvectionRK2) for advection FieldSet.from_<modelname>() is removed
-Convert the model data first to SGrid (for example with a parcels.covert_<MODEL>_to_sgrid() function) and then use FieldSet.from_sgrid_conventions(), as also described in the Quickstart tutorial +Convert the model data first to SGrid (for example with a parcels.covert_<MODEL>_to_sgrid() function) and then use FieldSet.from_sgrid_conventions(), as also described in the Quickstart tutorial
@@ -261,7 +261,7 @@ Simply pass the function(s) as a list to pset.execute() repeatdt is removed
-See the Delayed starts tutorial for how to implement repeated releases of particles +See the Delayed starts tutorial for how to implement repeated releases of particles
@@ -285,7 +285,7 @@ Update runtime and endtime to use numpy.datetime ParticleSet.from_field(), ParticleSet.from_line(), ParticleSet.from_list() are removed
-Use the ParticleSet constructor directly +Use the ParticleSet constructor directly
@@ -296,7 +296,7 @@ Use the ParticleSet constructor<
-ParticleFiles output is in parquet format +ParticleFiles output is in parquet format
Read the output with polars.read_parquet() or (to automatically handle cftime) parcels.read_particlefile(). For compatility with old postprocessing codes, convert the new Parquet output to v3-style zarr output using parcels.particlefile_to_v3_zarr() @@ -355,7 +355,7 @@ Either write all timesteps of a variable, or none Particles are not written when they are deleted
-Call ParticleFile.write() inside a kernel to write out deleted particles +Call ParticleFile.write() inside a kernel to write out deleted particles
@@ -385,7 +385,7 @@ Use Field.eval() as before, but expect an array of floats instead o The NestedField class is removed
-See the Nested Grids tutorial for how to set up Nested Grids in v4 +See the Nested Grids tutorial for how to set up Nested Grids in v4
diff --git a/src/parcels/kernels/_advectiondiffusion.py b/src/parcels/kernels/_advectiondiffusion.py index 2d9c9e61e..c27cb0137 100644 --- a/src/parcels/kernels/_advectiondiffusion.py +++ b/src/parcels/kernels/_advectiondiffusion.py @@ -1,6 +1,6 @@ """Collection of pre-built advection-diffusion kernels. -See `this tutorial <./tutorial_diffusion.ipynb>`__ for a detailed explanation. +See `this tutorial <./example_diffusion.ipynb>`__ for a detailed explanation. """ import numpy as np From 30941c1bdaef444052cfee64f6329a1fee7e241c Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Thu, 5 Nov 2026 22:21:36 +0100 Subject: [PATCH 10/11] cleaning up index.md --- .../group_convert_atmospheric_models.md | 2 - docs/user_guide/group_convert_concepts.md | 2 - docs/user_guide/group_convert_models.md | 10 --- docs/user_guide/group_convert_ocean_models.md | 2 - docs/user_guide/group_example_kernels.md | 2 - docs/user_guide/group_fieldsets.md | 2 - docs/user_guide/group_gettingstarted.md | 2 - docs/user_guide/group_interpolation.md | 2 - docs/user_guide/group_kernels.md | 2 - docs/user_guide/group_misc.md | 2 - docs/user_guide/group_particlesets.md | 2 - docs/user_guide/group_simulation.md | 2 - docs/user_guide/index.md | 71 +++++-------------- 13 files changed, 17 insertions(+), 86 deletions(-) delete mode 100644 docs/user_guide/group_convert_models.md diff --git a/docs/user_guide/group_convert_atmospheric_models.md b/docs/user_guide/group_convert_atmospheric_models.md index 5f15752d0..29ddb453e 100644 --- a/docs/user_guide/group_convert_atmospheric_models.md +++ b/docs/user_guide/group_convert_atmospheric_models.md @@ -1,5 +1,3 @@ -# Converting 🍃 atmospheric models - ```{toctree} :titlesonly: convert_aifs.ipynb diff --git a/docs/user_guide/group_convert_concepts.md b/docs/user_guide/group_convert_concepts.md index b1f905c6c..1ce851354 100644 --- a/docs/user_guide/group_convert_concepts.md +++ b/docs/user_guide/group_convert_concepts.md @@ -1,5 +1,3 @@ -# Converter concepts - ```{toctree} :titlesonly: convert_writing_functions.md diff --git a/docs/user_guide/group_convert_models.md b/docs/user_guide/group_convert_models.md deleted file mode 100644 index 1126036d6..000000000 --- a/docs/user_guide/group_convert_models.md +++ /dev/null @@ -1,10 +0,0 @@ -# Converting model data to FieldSets - -Below is a list of tutorials that show how to convert data from ocean (🌊) and atmospheric (🍃) models to Parcels FieldSets. - -```{toctree} -:titlesonly: -group_convert_ocean_models.md -group_convert_atmospheric_models.md -group_convert_concepts.md -``` diff --git a/docs/user_guide/group_convert_ocean_models.md b/docs/user_guide/group_convert_ocean_models.md index e2ed4d6a2..88aae5086 100644 --- a/docs/user_guide/group_convert_ocean_models.md +++ b/docs/user_guide/group_convert_ocean_models.md @@ -1,5 +1,3 @@ -# Converting 🌊 ocean models - ```{toctree} :titlesonly: convert_copernicusmarine.md diff --git a/docs/user_guide/group_example_kernels.md b/docs/user_guide/group_example_kernels.md index 440a04857..fbea2dbf5 100644 --- a/docs/user_guide/group_example_kernels.md +++ b/docs/user_guide/group_example_kernels.md @@ -1,5 +1,3 @@ -# Example Kernels - ```{toctree} :titlesonly: example_gsw_density.ipynb diff --git a/docs/user_guide/group_fieldsets.md b/docs/user_guide/group_fieldsets.md index d6baeb31d..f3c351169 100644 --- a/docs/user_guide/group_fieldsets.md +++ b/docs/user_guide/group_fieldsets.md @@ -1,5 +1,3 @@ -# Work with FieldSets - ```{toctree} :titlesonly: fieldsets_grids.ipynb diff --git a/docs/user_guide/group_gettingstarted.md b/docs/user_guide/group_gettingstarted.md index b26df50e8..f1193f934 100644 --- a/docs/user_guide/group_gettingstarted.md +++ b/docs/user_guide/group_gettingstarted.md @@ -1,5 +1,3 @@ -# Getting started - ```{toctree} :titlesonly: gettingstarted_quickstart.md diff --git a/docs/user_guide/group_interpolation.md b/docs/user_guide/group_interpolation.md index ee17e9066..a7b175e94 100644 --- a/docs/user_guide/group_interpolation.md +++ b/docs/user_guide/group_interpolation.md @@ -1,5 +1,3 @@ -# Set interpolation methods - ```{toctree} :titlesonly: interpolation_explanation.md diff --git a/docs/user_guide/group_kernels.md b/docs/user_guide/group_kernels.md index 3e50ac6df..cccff4dfb 100644 --- a/docs/user_guide/group_kernels.md +++ b/docs/user_guide/group_kernels.md @@ -1,5 +1,3 @@ -# Write Kernels - ```{toctree} :titlesonly: kernels_loopexplanation.md diff --git a/docs/user_guide/group_misc.md b/docs/user_guide/group_misc.md index 5063ab9ab..516ae1596 100644 --- a/docs/user_guide/group_misc.md +++ b/docs/user_guide/group_misc.md @@ -1,5 +1,3 @@ -# Miscellaneous - ```{toctree} :titlesonly: 📖 v4 development <../v4/index> diff --git a/docs/user_guide/group_particlesets.md b/docs/user_guide/group_particlesets.md index a46bd6461..f720d8180 100644 --- a/docs/user_guide/group_particlesets.md +++ b/docs/user_guide/group_particlesets.md @@ -1,5 +1,3 @@ -# Create ParticleSets - ```{toctree} :titlesonly: particlesets_delaystart.ipynb diff --git a/docs/user_guide/group_simulation.md b/docs/user_guide/group_simulation.md index e160f9a7e..c49ab19b2 100644 --- a/docs/user_guide/group_simulation.md +++ b/docs/user_guide/group_simulation.md @@ -1,5 +1,3 @@ -# Run a simulation - ```{toctree} :titlesonly: simulation_performance.md diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md index ca13f578a..fa0c32379 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -10,15 +10,6 @@ For a description of the specific classes and functions, check out the [API refe :titlesonly: :maxdepth: 3 installation.md -group_gettingstarted.md -group_convert_models.md -group_fieldsets.md -group_particlesets.md -group_kernels.md -group_interpolation.md -group_simulation.md -group_example_kernels.md -group_misc.md ``` ```{note} @@ -31,9 +22,7 @@ If you have code that uses Parcels v3, you can migrate to Parcels v4 using [🎓 :caption: Getting Started :name: getting-started :titlesonly: -gettingstarted_quickstart.md -gettingstarted_output.ipynb -gettingstarted_concepts.md +group_gettingstarted.md ``` ## Converting model data to FieldSets @@ -44,28 +33,21 @@ Below is a list of tutorials that show how to convert data from ocean (🌊) and :caption: Converting 🌊 ocean models :name: converting-ocean-models :titlesonly: -convert_copernicusmarine.md -convert_nemo.ipynb -convert_croco_3D.ipynb -convert_mitgcm.ipynb -convert_mom6.ipynb -convert_delft3d.ipynb -convert_fesom.ipynb -convert_schism.ipynb +group_convert_ocean_models.md ``` ```{toctree} :caption: Converting 🍃 atmospheric models :name: converting-atmospheric-models :titlesonly: -convert_aifs.ipynb +group_convert_atmospheric_models.md ``` ```{toctree} -:caption: Converter concepts -:name: converter-concepts +:caption: Converting other models +:name: converting-other-models :titlesonly: -convert_writing_functions.md +group_convert_concepts.md ``` ## Work with FieldSets @@ -74,12 +56,7 @@ convert_writing_functions.md :caption: Work with FieldSets :name: work-with-fieldsets :titlesonly: -fieldsets_grids.ipynb -fieldsets_sigma_coordinates.ipynb -fieldsets_velocityconversion.ipynb -fieldsets_nestedgrids.ipynb -fieldsets_manipulating_field_data.ipynb -fieldsets_xgcm_derived_fields.ipynb +group_fieldsets.md ``` ## Create ParticleSets @@ -88,7 +65,7 @@ fieldsets_xgcm_derived_fields.ipynb :caption: Create ParticleSets :name: create-particlesets :titlesonly: -particlesets_delaystart.ipynb +group_particlesets.md ``` ## Write Kernels @@ -97,11 +74,7 @@ particlesets_delaystart.ipynb :caption: Write Kernels :name: write-kernels :titlesonly: - -kernels_loopexplanation.md -kernels_sampling.ipynb -kernels_statuscodes.ipynb -kernels_write_in_kernel.ipynb +group_kernels.md ``` ## Set interpolation methods @@ -110,12 +83,7 @@ kernels_write_in_kernel.ipynb :caption: Set interpolation methods :name: interpolation-methods :titlesonly: - -interpolation_explanation.md -interpolation_tutorial.ipynb -interpolation_peninsula_AvsCgrid.ipynb -interpolation_stuck_particles.ipynb -interpolation_unstuck_Agrid.ipynb +group_interpolation.md ``` @@ -126,8 +94,7 @@ interpolation_unstuck_Agrid.ipynb :caption: Run a simulation :name: run-simulation :titlesonly: -simulation_performance.md -simulation_dt_integrators.ipynb +group_simulation.md ``` ## Example Kernels @@ -136,21 +103,17 @@ simulation_dt_integrators.ipynb :caption: Example Kernels :name: example-kernels :titlesonly: -example_gsw_density.ipynb -example_Argofloats.ipynb -example_diffusion.ipynb -example_interaction.ipynb +group_example_kernels.md ``` -## Other +## Miscellaneous ```{toctree} -:caption: Other -:name: other +:caption: Miscellaneous +:name: miscellaneous :titlesonly: -📖 v4 development <../v4/index> -🎓 v3 to v4 migration guide -misc_homepage_animation.md +:maxdepth: 1 +group_misc.md ``` From bc9787c2e567cd6ba78826989a03c972e8453b07 Mon Sep 17 00:00:00 2001 From: Erik van Sebille Date: Fri, 6 Nov 2026 09:03:34 +0100 Subject: [PATCH 11/11] Fixing pixi run docs-spelling --- docs/user_guide/gettingstarted_concepts.md | 2 +- pixi.toml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user_guide/gettingstarted_concepts.md b/docs/user_guide/gettingstarted_concepts.md index 2cf7897b2..3f3bc656c 100644 --- a/docs/user_guide/gettingstarted_concepts.md +++ b/docs/user_guide/gettingstarted_concepts.md @@ -195,7 +195,7 @@ pset.execute(kernels=kernels, dt=dt, runtime=runtime) To analyse the particle data generated in the simulation, we need to define a {py:obj}`parcels.ParticleFile` and add it as an argument to {py:func}`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 `t`, `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](./gettingstarted_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 analyse particle output, and although we provide [a short tutorial to get started](./gettingstarted_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 diff --git a/pixi.toml b/pixi.toml index 4e86bba39..0c0251866 100644 --- a/pixi.toml +++ b/pixi.toml @@ -146,7 +146,7 @@ docs-run-notebook = { cmd = "rm -rf tmp-docs-run-notebook && mkdir tmp-docs-run- "file", ], description = "Execute a single MyST notebook (.md) or Jupyter notebook (.ipynb) outside of the docs build." } docs-linkcheck = { cmd = "make linkcheck", cwd = "docs", description = "Verify all links in documentation don't 404." } -docs-spelling = { cmd = "python tools/lint_british_english.py docs/user_guide/tutorial*.ipynb docs/user_guide/tutorial*.md docs/user_guide/tutorial*.ipynb docs/user_guide/tutorial*.md", description = "Check tutorial prose uses British English." } +docs-spelling = { cmd = "python tools/lint_british_english.py docs/user_guide/*.ipynb docs/user_guide/*.md docs/user_guide/*.ipynb docs/user_guide/*.md", description = "Check tutorial prose uses British English." } more-qaqc = { depends-on = [ "docs-spelling", ], description = "Additional QAQC tooling separate to pre-commit hooks" }