Skip to content

Commit a135b45

Browse files
reint-fischerreint-fischer
authored andcommitted
add input field figure
1 parent ce6cec9 commit a135b45

File tree

1 file changed

+18
-4
lines changed

1 file changed

+18
-4
lines changed

docs/getting_started/tutorial_quickstart.md

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ TODO: Completely rewrite examples/parcels_tutorial.ipynb to be this quickstart t
1313
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!
1414

1515
## Imports
16+
1617
Parcels depends on `xarray`, expecting inputs in the form of [`xarray.Dataset`](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html) and writing output files that can be read with xarray.
1718

1819
```{code-cell}
@@ -22,11 +23,12 @@ import parcels
2223
```
2324

2425
## Input 1: `FieldSet`
26+
2527
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.
2628

2729
```{code-cell}
2830
example_dataset_folder = parcels.download_example_dataset(
29-
"CopernicusMarine_data"
31+
"CopernicusMarine_data_for_Argo_tutorial"
3032
)
3133
3234
ds_in = xr.open_mfdataset(f"{example_dataset_folder}/*.nc", combine="by_coords")
@@ -35,20 +37,30 @@ ds_in.load() # load the dataset into memory
3537
fieldset = parcels.FieldSet.from_copernicusmarine(ds_in)
3638
```
3739

38-
The reanalysis contains `U`, `V`, potential temperature (`thetao`) and salinity (`so`):
40+
The reanalysis data files contain `U`, `V`, potential temperature (`thetao`) and salinity (`so`) fields:
3941

4042
```{code-cell}
4143
ds_in
4244
```
45+
4346
The subset contains a region of the Agulhas current along the southeastern coast of Africa:
47+
4448
```{code-cell}
4549
import matplotlib.pyplot as plt
4650
import cartopy.crs as ccrs
47-
import cartopy.feature as cfeature
48-
ds_in
51+
52+
temperature = ds_in.isel(time=0, depth=0).thetao.plot(cmap="magma",subplot_kws=dict(projection=ccrs.PlateCarree()))
53+
velocity = ds_in.isel(time=0, depth=0).plot.quiver(x="longitude", y="latitude", u="uo", v="vo")
54+
55+
temperature.axes.set_extent([30, 34, -34, -29])
56+
gl = temperature.axes.gridlines(draw_labels=True)
57+
gl.top_labels = False
58+
gl.right_labels = False
59+
temperature.axes.coastlines()
4960
```
5061

5162
## Input 2: `ParticleSet`
63+
5264
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.
5365

5466
```{code-cell}
@@ -65,11 +77,13 @@ pset = parcels.ParticleSet(
6577
```
6678

6779
## Compute: `Kernel`
80+
6881
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:
6982

7083
```{note}
7184
TODO: link to list of included kernels
7285
```
86+
7387
```{code-cell}
7488
kernels = parcels.kernels.AdvectionEE
7589
```

0 commit comments

Comments
 (0)