diff --git a/.gitignore b/.gitignore index 3b1889d4b..3b4fee303 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ build/* docs/_build/* docs/_downloads +docs/jupyter_execute/* output *.log diff --git a/docs/conf.py b/docs/conf.py index 6bb23549f..6af8adef8 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -36,8 +36,7 @@ "sphinx.ext.linkcode", "sphinx.ext.mathjax", "sphinx.ext.napoleon", - "myst_parser", - "nbsphinx", + "myst_nb", "numpydoc", "sphinxcontrib.mermaid", "sphinx_design", @@ -114,7 +113,13 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ["_build", "**.ipynb_checkpoints", "user_guide/examples_v3"] +exclude_patterns = [ + "_build", + "jupyter_execute", + "**.ipynb_checkpoints", + "user_guide/examples_v3", +] +nb_execution_excludepatterns = ["jupyter_execute"] # The reST default role (used for this markup: `text`) to use for all # documents. diff --git a/docs/development/docsguide.md b/docs/development/docsguide.md index 2735c7cb7..76218ff3a 100644 --- a/docs/development/docsguide.md +++ b/docs/development/docsguide.md @@ -17,4 +17,7 @@ TODO: outline functions of the documentation based on resources ## Style guide -- Write documentation in first person plural ("we"). In our open source code, tutorials and guides can be written by any developer or user, so the documentation teaches all of us how to do something with Parcels. +- **Write out `parcels.class.method` in tutorials and how-to guides** so that we can see which classes and methods are part of Parcels. If we use `from parcels import class`, the use of `class` in a cell further along is not obviously part of `parcels`. +- [**Avoid too much Repitition In Documentation**](https://www.writethedocs.org/guide/writing/docs-principles/#arid): tutorials and how-to guides notebooks will often have repetition of the general **Parcels** steps, which is fine because we want users to see where in the simulation setup things change. We try to limit each page in the documentation to a small number of examples. +- **Import packages at the top of the section in which they are first used** to show what they are used for. +- **Write documentation in first person plural ("we").** In our open source code, tutorials and guides can be written by any developer or user, so the documentation teaches all of us how to do something with Parcels. Sometimes it can be more natural to take on the tone of a teacher, writing to a student/learner, in which case it is okay to use "you". Please refrain from using impersonal subjects such as "the user". diff --git a/docs/getting_started/tutorial_quickstart.md b/docs/getting_started/tutorial_quickstart.md index 878d4d25c..d6e1ab202 100644 --- a/docs/getting_started/tutorial_quickstart.md +++ b/docs/getting_started/tutorial_quickstart.md @@ -1,3 +1,81 @@ -# Quickstart tutorial" +--- +file_format: mystnb +kernelspec: + name: python3 +--- -TODO: Completely rewrite examples/parcels_tutorial.ipynb into the quickstart tutorial. Decide which file format and notebook testing to do so this file is checked, which is not in the "examples" folder +# Quickstart tutorial + +```{note} +TODO: Completely rewrite examples/parcels_tutorial.ipynb to be this quickstart tutorial. Decide which file format and notebook testing to do so this file is checked, which is not in the "examples" folder +``` + +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, or how they relate to each other, we have a [concepts overview](concepts_overview.md) to describe how we think about them. Let's dive in! + +## Import + +```{code-cell} +import numpy as np +import xarray as xr +import parcels +``` + +## Input: `FieldSet` + +Load the CopernicusMarine data in the Agulhas region from the example_datasets + +```{code-cell} +example_dataset_folder = parcels.download_example_dataset( + "CopernicusMarine_data_for_Argo_tutorial" +) + +ds = xr.open_mfdataset(f"{example_dataset_folder}/*.nc", combine="by_coords") +ds.load() # load the dataset into memory + +fieldset = parcels.FieldSet.from_copernicusmarine(ds) +``` + +## Input: `ParticleSet` + +```{code-cell} +# Particle locations and initial time +npart = 10 # number of particles to be released +lon = np.repeat(32, npart) +lat = np.linspace(-32.5, -30.5, npart) +time = np.repeat(ds.time.values[0], npart) +z = np.repeat(ds.depth.values[0], npart) + +pset = parcels.ParticleSet( + fieldset=fieldset, pclass=parcels.Particle, lon=lon, lat=lat, time=time, z=z +) +``` + +## Compute: `Kernel` + +```{code-cell} +kernels = parcels.kernels.AdvectionEE +``` + +## Prepare output: `ParticleFile` + +```{code-cell} +output_file = parcels.ParticleFile("Output.zarr", outputdt=np.timedelta64(1, "h")) +``` + +## Run Simulation: `ParticleSet.execute()` + +```{code-cell} +pset.execute( + kernels, + runtime=np.timedelta64(5, "h"), + dt=np.timedelta64(5, "m"), + output_file=output_file, +) +``` + +## Read output + +```{code-cell} +data_xarray = xr.open_zarr("Output.zarr") +data_xarray +``` diff --git a/docs/index.md b/docs/index.md index 8bff99346..50d366cfc 100755 --- a/docs/index.md +++ b/docs/index.md @@ -8,8 +8,6 @@ Welcome to the documentation of Parcels. **Parcels** provides a set of Python cl _Animation of virtual particles carried by ocean surface flow in the global oceans. The particles are advected with Parcels in data from the_ [NEMO Ocean Model](https://www.nemo-ocean.eu/). -**Version**: {{env.config.version}} - ```{note} You can browse the documentation for older versions by using the version switcher in the bottom right. ``` diff --git a/docs/user_guide/examples/tutorial_output.ipynb b/docs/user_guide/examples/tutorial_output.ipynb index faf5908e5..2d3607613 100644 --- a/docs/user_guide/examples/tutorial_output.ipynb +++ b/docs/user_guide/examples/tutorial_output.ipynb @@ -15,11 +15,11 @@ "source": [ "This tutorial covers the format of the trajectory output exported by Parcels. **Parcels does not include advanced analysis or plotting functionality**, which users are suggested to write themselves to suit their research goals. Here we provide some starting points to explore the parcels output files yourself.\n", "\n", - "- [**Reading the output file**](#Reading-the-output-file)\n", - "- [**Trajectory data structure**](#Trajectory-data-structure)\n", - "- [**Analysis**](#Analysis)\n", - "- [**Plotting**](#Plotting)\n", - "- [**Animations**](#Animations)\n", + "- [**Reading the output file**](#reading-the-output-file)\n", + "- [**Trajectory data structure**](#trajectory-data-structure)\n", + "- [**Analysis**](#analysis)\n", + "- [**Plotting**](#plotting)\n", + "- [**Animations**](#animations)\n", "\n", "For more advanced reading and tutorials on the analysis of Lagrangian trajectories, we recommend checking out the [Lagrangian Diagnostics Analysis Cookbook](https://lagrangian-diags.readthedocs.io/en/latest/tutorials.html) and the project in general. The [TrajAn package](https://opendrift.github.io/trajan/index.html) can be used to read and plot datasets of Lagrangian trajectories." ] @@ -373,7 +373,7 @@ "source": [ "Trajectory plots like the ones above can become very cluttered for large sets of particles. To better see patterns, it's a good idea to create an animation in time and space. To do this, matplotlib offers an [animation package](https://matplotlib.org/stable/api/animation_api.html). Here we show how to use the [**FuncAnimation**](https://matplotlib.org/3.3.2/api/_as_gen/matplotlib.animation.FuncAnimation.html#matplotlib.animation.FuncAnimation) class to animate parcels trajectory data, based on [this visualisation tutorial](https://github.com/Parcels-code/10year-anniversary-session5/blob/eaf7ac35f43c222280fa5577858be81dc346c06b/animations_tutorial.ipynb) from 10-years Parcels. \n", "\n", - "To correctly reveal the patterns in time we must remember that the `obs` dimension does not necessarily correspond to the `time` variable ([see the section of Trajectory data structure above](#Trajectory-data-structure)). In the animation of the particles, we usually want to draw the points at each consecutive moment in time, not necessarily at each moment since the start of the trajectory. To do this we must [select the correct data](#Conditional-selection) in each rendering.\n" + "To correctly reveal the patterns in time we must remember that the `obs` dimension does not necessarily correspond to the `time` variable ([see the section of Trajectory data structure above](#trajectory-data-structure)). In the animation of the particles, we usually want to draw the points at each consecutive moment in time, not necessarily at each moment since the start of the trajectory. To do this we must [select the correct data](#conditional-selection) in each rendering.\n" ] }, { diff --git a/docs/user_guide/examples/tutorial_sampling.ipynb b/docs/user_guide/examples/tutorial_sampling.ipynb index 29540ffb2..db59f866a 100644 --- a/docs/user_guide/examples/tutorial_sampling.ipynb +++ b/docs/user_guide/examples/tutorial_sampling.ipynb @@ -17,9 +17,9 @@ "\n", "In this tutorial we will go through how particles can sample `Fields`, using temperature as an example. Along the way we will get to know the parcels class `Variable` (see [here](https://parcels.readthedocs.io/en/latest/reference/particles.html#parcels.particle.Variable) for the documentation) and some of its methods. This tutorial covers several applications of a sampling setup:\n", "\n", - "- [**Basic along trajectory sampling**](#Basic-sampling)\n", - "- [**Sampling velocity fields**](#Sampling-velocity-fields)\n", - "- [**Sampling initial conditions**](#Sampling-initial-values)\n" + "- [**Basic along trajectory sampling**](#basic-sampling)\n", + "- [**Sampling velocity fields**](#sampling-velocity-fields)\n", + "- [**Sampling initial conditions**](#sampling-initial-values)\n" ] }, { @@ -27,7 +27,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Basic sampling\n", + "### Basic sampling\n", "\n", "We import both the packages that we need to set up the simulation, as well as the parcels package.\n" ] @@ -206,7 +206,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Sampling velocity fields\n" + "# Sampling velocity fields\n" ] }, { @@ -304,7 +304,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Sampling initial values\n" + "# Sampling initial values\n" ] }, { diff --git a/docs/user_guide/examples_v3/parcels_tutorial.ipynb b/docs/user_guide/examples_v3/parcels_tutorial.ipynb index 8d7256fe1..3567ce64b 100644 --- a/docs/user_guide/examples_v3/parcels_tutorial.ipynb +++ b/docs/user_guide/examples_v3/parcels_tutorial.ipynb @@ -965,7 +965,7 @@ ], "metadata": { "kernelspec": { - "display_name": "parcels", + "display_name": "test-notebooks", "language": "python", "name": "python3" }, @@ -979,7 +979,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.12.3" + "version": "3.11.0" } }, "nbformat": 4, diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md index 3c271dece..11ea2b7c2 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -9,22 +9,24 @@ The tutorials written for Parcels v3 are currently being updated for Parcels v4. ## Getting started -```{nbgallery} + + examples/tutorial_output.ipynb -``` + +````--> ## How to: ```{note} **Migrate from v3 to v4** using [this migration guide](v4-migration.md) -``` +```` -```{nbgallery} + -``` -```{nbgallery} +````--> + + -```{nbgallery} + -``` +``` --> -```{nbgallery} + -``` +``` --> -```{nbgallery} + -``` +``` --> ```{toctree} :hidden: v3 to v4 migration guide Example scripts -``` +```` diff --git a/pixi.toml b/pixi.toml index 1673dbf5a..76697cf2f 100644 --- a/pixi.toml +++ b/pixi.toml @@ -83,13 +83,12 @@ gsw = "*" [feature.docs.dependencies] numpydoc = "!=1.9.0" -nbsphinx = "*" +myst-nb = "*" ipython = "*" sphinx = "*" pandoc = "*" pydata-sphinx-theme = "*" sphinx-autobuild = "*" -myst-parser = "*" sphinxcontrib-mermaid = "*" sphinx-design = "*"