You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/getting_started/tutorial_quickstart.md
+73-28Lines changed: 73 additions & 28 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,10 +6,6 @@ kernelspec:
6
6
7
7
# Quickstart tutorial
8
8
9
-
```{note}
10
-
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
11
-
```
12
-
13
9
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](concepts_overview.md) discussing them in more detail. Let's dive in!
14
10
15
11
## Imports
@@ -22,7 +18,7 @@ import xarray as xr
22
18
import parcels
23
19
```
24
20
25
-
## Input 1: `FieldSet`
21
+
## Input flow fields: `FieldSet`
26
22
27
23
A Parcels simulation of Lagrangian trajectories of virtual particles requires two inputs; the first is a set of hydrodynamics fields in which the particles are tracked. This set of vectorfields, with `U`, `V` (and `W`) flow velocities, can be read in to a `parcels.FieldSet` object from many types of models or observations. Here we provide an example using a subset of the [Global Ocean Physics Reanalysis](https://doi.org/10.48670/moi-00021) from the Copernicus Marine Service.
The reanalysis data files contain `U`, `V`, potential temperature (`thetao`) and salinity (`so`) fields:
35
+
As we can see, the reanalysis dataset contains eastward velocity `uo`, northward velocity `vo`, potential temperature (`thetao`) and salinity (`so`) fields. To load the dataset into parcels we create a `FieldSet`, which recognizes the standard names of a velocity field:
Now that we have read in the hydrodynamic data, we need to provide our second input: the virtual particles for which we will calculate the trajectories. We need to define the initial time and position and read those into a `parcels.ParticleSet` object, which also needs to know about the `FieldSet` in which the particles "live". Finally, we need to specify the type of `parcels.Particle` we want to use. The default particles have `time`, `lon`, `lat`, and `z` to keep track of, but with Parcels you can easily build your own particles to mimic plastic or an [ARGO float](../user_guide/tutorial_Argofloats.ipynb), adding variables such as size, temperature, or age.
65
51
66
52
```{code-cell}
67
53
# Particle locations and initial time
68
54
npart = 10 # number of particles to be released
69
55
lon = np.repeat(32, npart)
70
-
lat = np.linspace(-32.5, -30.5, npart)
71
-
time = np.repeat(ds.time.values[0], npart)
72
-
z = np.repeat(ds.depth.values[0], npart)
56
+
lat = np.linspace(-32.5, -30.5, npart) # release particles in a line along a meridian
57
+
time = np.repeat(ds_in.time.values[0], npart) # at initial time of input data
58
+
z = np.repeat(ds_in.depth.values[0], npart) # at the first depth (surface)
After setting up the input data, we need to specify how to calculate the advection of the particles. These calculations, or numerical integrations, will be performed by what we call a `Kernel`, operating on each particle in the `ParticleSet`. The most common calculation is the advection of particles through the velocity field. Parcels comes with a number of standard kernels, from which we will use the Euler-forward advection kernel:
74
+
After setting up the input data, we need to specify how to calculate the advection of the particles. These calculations, or numerical integrations, will be performed by what we call a `Kernel`, operating on each particle in the `ParticleSet`. The most common calculation is the advection of particles through the velocity field. Parcels comes with a number of standard kernels, from which we will use the Euler-forward advection kernel`AdvectionEE`:
82
75
83
76
```{note}
84
-
TODO: link to list of included kernels
77
+
TODO: link to a list of included kernels
85
78
```
86
79
87
80
```{code-cell}
88
81
kernels = parcels.kernels.AdvectionEE
89
82
```
90
83
91
84
## Prepare output: `ParticleFile`
85
+
Before starting the simulation, we must define where and how frequent we want to write the output of our simulation. We can define this in a `ParticleFile` object:
The output files are in `.zarr`[format]([format](https://zarr.readthedocs.io/en/stable/).), which can be read by `xarray`. See the [Parcels output tutorial](../user_guide/examples/tutorial_output.ipynb) for more information on the zarr format. We want to choose the `outputdt` argument such they capture the smallest timescales of our interest.
92
+
97
93
## Run Simulation: `ParticleSet.execute()`
94
+
Finally, we can run the simulation by *executing* the `ParticleSet` using the specified `kernels`. Additionally, we need to specify:
95
+
- the `runtime`: for how long we want to simulate particles.
96
+
- the `dt`: the timestep with which to perform the numerical integration in the `kernels`. Depending on the numerical integration scheme, the accuracy of our simulation will depend on `dt`. Read [this notebook](https://github.com/Parcels-code/10year-anniversary-session2/blob/8931ef69577dbf00273a5ab4b7cf522667e146c5/advection_and_windage.ipynb) to learn more about numerical accuracy.
97
+
98
+
```{note}
99
+
TODO: add Michaels 10-years Parcels notebook to the user guide
100
+
```
98
101
99
102
```{code-cell}
103
+
:tags: [hide-output]
100
104
pset.execute(
101
105
kernels,
102
-
runtime=np.timedelta64(5, "h"),
106
+
runtime=np.timedelta64(1, "D"),
103
107
dt=np.timedelta64(5, "m"),
104
108
output_file=output_file,
105
109
)
106
110
```
107
111
108
112
## Read output
113
+
To start analyzing the trajectories computed by **Parcels**, we can open the `ParticleFile` using `xarray`:
109
114
110
115
```{code-cell}
111
-
data_xarray = xr.open_zarr("Output.zarr")
112
-
data_xarray
116
+
ds_out = xr.open_zarr("Output.zarr")
117
+
ds_out
113
118
```
119
+
120
+
The 10 particle trajectories are stored along the `trajectory` dimension, and each trajectory contains 25 observations (initial values + 24 hourly timesteps) along the `obs` dimension. The [Working with Parcels output tutorial](../user_guide/examples/tutorial_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!
121
+
122
+
```{code-cell}
123
+
import matplotlib.pyplot as plt
124
+
125
+
# plot positions and color particles by number of observation
That looks good! The virtual particles released in a line along the 32nd meridian (dark blue) have been advected by the flow field.
132
+
133
+
## Running a simulation backwards in time
134
+
Now that we know how to run a simulation, we can easily run another and change one of the settings. We can trace back the particles from their current to their original position by running the simulation backwards in time. To do so, we can simply make `dt` < 0.
0 commit comments