Skip to content

Removing depth from the tutorials #2799

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
erikvansebille wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Removing depth from the tutorials #2799

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c41c7ab
Removing depth from the tutorials
erikvansebille Aug 4, 2026
63fc2e7
Using fieldset.surface context for KeepInOcean
erikvansebille Aug 4, 2026
3d39c63
Merge branch 'main' into removing-depth-from-tutorials
erikvansebille Aug 5, 2026
7a22809
Removing explicit setting of z from tutorial
erikvansebille Aug 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions docs/user_guide/examples/explanation_kernelloop.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,11 +103,10 @@ First run a simulation where we apply Kernels as `[AdvectionRK2, wind_kernel]`
```{code-cell}
:tags: [hide-output]
npart = 10
z = np.repeat(ds_fields.depth[0].values, npart)
lons = np.repeat(32.2, npart)
lats = np.linspace(-32.5, -30.5, npart)

pset = parcels.ParticleSet(fieldset, pclass=parcels.Particle, z=z, y=lats, x=lons)
pset = parcels.ParticleSet(fieldset, pclass=parcels.Particle, y=lats, x=lons)
output_file = parcels.ParticleFile(
path="advection_then_wind.parquet", outputdt=np.timedelta64(6,'h')
)
Expand All @@ -124,7 +123,7 @@ Then also run a simulation where we apply the Kernels in the reverse order as `[
```{code-cell}
:tags: [hide-output]
pset_reverse = parcels.ParticleSet(
fieldset, pclass=parcels.Particle, z=z, y=lats, x=lons
fieldset, pclass=parcels.Particle, y=lats, x=lons
)
output_file_reverse = parcels.ParticleFile(
path="wind_then_advection.parquet", outputdt=np.timedelta64(6,"h")
Expand Down
2 changes: 1 addition & 1 deletion docs/user_guide/examples/tutorial_croco_3D.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -261,7 +261,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"When using Croco data, Parcels needs to convert the particles.depth to sigma-coordinates, before doing any interpolation. This is done with the `convert_z_to_sigma_croco()` function. Interpolating onto a Field is then done like:\n",
"When using Croco data, Parcels needs to convert the particles.z to sigma-coordinates, before doing any interpolation. This is done with the `convert_z_to_sigma_croco()` function. Interpolating onto a Field is then done like:\n",
"\n",
"```python\n",
"def SampleTempCroco(particles, fieldset):\n",
Expand Down
9 changes: 3 additions & 6 deletions docs/user_guide/examples/tutorial_delaystart.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,10 +93,9 @@
"lat = np.linspace(-31.5, -30.5, npart, dtype=np.float32)\n",
"# release every particle one hour later from the initial fieldset time\n",
"time = ds_fields.time.values[0] + np.arange(0, npart) * np.timedelta64(1, \"h\")\n",
"z = np.repeat(ds_fields.depth.values[0], npart)\n",
"\n",
"pset = parcels.ParticleSet(\n",
" fieldset=fieldset, pclass=parcels.Particle, x=lon, y=lat, t=time, z=z\n",
" fieldset=fieldset, pclass=parcels.Particle, x=lon, y=lat, t=time\n",
")"
]
},
Expand Down Expand Up @@ -209,7 +208,6 @@
"lon_i = 32 * np.ones(npart)\n",
"lat_i = np.linspace(-31.5, -30.5, npart, dtype=np.float32)\n",
"time_i = np.repeat(ds_fields.time.values[0], npart)\n",
"z_i = np.repeat(ds_fields.depth.values[0], npart)\n",
"\n",
"# repeat release at frequency `repeatdt` for `nrepeat` different releases\n",
"repeatdt = np.timedelta64(6, \"h\")\n",
Expand All @@ -222,10 +220,9 @@
" + np.arange(0, nrepeat)[:, np.newaxis] * repeatdt\n",
")\n",
"print(f\"pset.time shape = {time.shape}\")\n",
"z = np.broadcast_to(z_i, (nrepeat, npart))\n",
"\n",
"pset = parcels.ParticleSet(\n",
" fieldset=fieldset, pclass=parcels.Particle, x=lon, y=lat, t=time, z=z\n",
" fieldset=fieldset, pclass=parcels.Particle, x=lon, y=lat, t=time\n",
")"
]
},
Expand Down Expand Up @@ -400,7 +397,7 @@
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"display_name": "Parcels:default (3.14.6)",
"language": "python",
"name": "python3"
},
Expand Down
2 changes: 1 addition & 1 deletion docs/user_guide/examples/tutorial_diffusion.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -554,7 +554,7 @@
"time = np.repeat(fieldset.time_interval.left, 13)\n",
"lon = [32] * len(time)\n",
"lat = [-30.1] * len(time)\n",
"z = [ds_fields.depth[0]] * len(time)\n",
"z = [0] * len(time)\n",
"pset = parcels.ParticleSet(\n",
" fieldset=fieldset,\n",
" pclass=parcels.Particle,\n",
Expand Down
7 changes: 2 additions & 5 deletions docs/user_guide/examples/tutorial_dt_integrators.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -198,8 +198,7 @@
"initial_release_lats = np.linspace(-32.5, -32, npart, dtype=np.float32)\n",
"initial_release_times = np.repeat(\n",
" ds_fields.time.values[0], npart\n",
") # release all particles at the start time of the fieldset\n",
"initial_release_zs = np.repeat(ds_fields.depth.values[0], npart)"
") # release all particles at the start time of the fieldset"
]
},
{
Expand Down Expand Up @@ -239,7 +238,6 @@
" fieldset=fieldset,\n",
" pclass=parcels.Particle,\n",
" t=initial_release_times,\n",
" z=initial_release_zs,\n",
" y=initial_release_lats,\n",
" x=initial_release_lons,\n",
" )\n",
Expand Down Expand Up @@ -580,7 +578,6 @@
" fieldset=fieldset,\n",
" pclass=parcels.Particle,\n",
" t=initial_release_times,\n",
" z=initial_release_zs,\n",
" y=initial_release_lats,\n",
" x=initial_release_lons,\n",
" )\n",
Expand Down Expand Up @@ -812,7 +809,7 @@
],
"metadata": {
"kernelspec": {
"display_name": "Parcels:docs (3.14.6)",
"display_name": "Parcels:test (3.14.6)",
"language": "python",
"name": "python3"
},
Expand Down
5 changes: 2 additions & 3 deletions docs/user_guide/examples/tutorial_manipulating_field_data.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,11 +125,10 @@
"fieldset = fieldset.to_windowed_arrays()\n",
"\n",
"npart = 10\n",
"z = np.repeat(ds_fields.depth[0].values, npart)\n",
"lons = np.repeat(32.2, npart)\n",
"lats = np.linspace(-32.5, -30.5, npart)\n",
"\n",
"pset = parcels.ParticleSet(fieldset, pclass=parcels.Particle, z=z, y=lats, x=lons)\n",
"pset = parcels.ParticleSet(fieldset, pclass=parcels.Particle, y=lats, x=lons)\n",
"output_file = parcels.ParticleFile(\n",
" path=\"summed_advection_wind.parquet\",\n",
" outputdt=np.timedelta64(6, \"h\"),\n",
Expand Down Expand Up @@ -168,7 +167,7 @@
],
"metadata": {
"kernelspec": {
"display_name": "Parcels:docs (3.14.6)",
"display_name": "Parcels:test (3.14.6)",
"language": "python",
"name": "python3"
},
Expand Down
2 changes: 1 addition & 1 deletion docs/user_guide/examples/tutorial_sampling.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@
"time = np.repeat(\n",
" ds_fields.time.values[0], npart\n",
") # release all particles at the start time of the fieldset\n",
"z = np.repeat(ds_fields.depth.values[0], npart)\n",
"z = np.repeat(0.5, npart) # upper level is at 0.5m depth\n",
"\n",
"# Plot temperature field and initial particle locations\n",
"plt.figure()\n",
Expand Down
3 changes: 2 additions & 1 deletion docs/user_guide/examples/tutorial_statuscodes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ def KeepInOcean(particles, fieldset):
through_surface = particles.state == parcels.StatusCode.ErrorThroughSurface

# move particles to surface
particles[through_surface].dz = fieldset.W.grid.depth[0] - particles[through_surface].z
particles[through_surface].dz = fieldset.surface - particles[through_surface].z

# change state from error to evaluate
particles[through_surface].state = parcels.StatusCode.Evaluate
Expand All @@ -71,6 +71,7 @@ dx, dy = 1.0 / len(ds.XG), 1.0 / len(ds.YG)
ds["W"] = ds["U"] - 0.1 # 0.1 m/s towards the surface

fieldset = parcels.FieldSet.from_sgrid_conventions(ds, mesh="flat")
fieldset.add_context("surface", 0) # surface is at z=0
```

If we advect particles with the `AdvectionRK2_3D` kernel, Parcels will raise a `FieldOutOfBoundSurfaceError`:
Expand Down
5 changes: 2 additions & 3 deletions docs/user_guide/getting_started/tutorial_output.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@
"# Load the CopernicusMarine data in the Agulhas region from the example_datasets\n",
"ds_fields = parcels.tutorial.open_dataset(\n",
" \"CopernicusMarine_data_for_Argo_tutorial/data\"\n",
")\n",
").isel(depth=0) # select the first depth level (surface)\n",
"\n",
"# Convert to SGRID-compliant dataset and create FieldSet\n",
"fields = {\"U\": ds_fields[\"uo\"], \"V\": ds_fields[\"vo\"]}\n",
Expand All @@ -78,11 +78,10 @@
"npart = 10 # number of particles to be released\n",
"lon = 32 * np.ones(npart)\n",
"lat = np.linspace(-32.5, -30.5, npart, dtype=np.float32)\n",
"z = np.repeat(ds_fields.depth.values[0], npart)\n",
"time = ds_fields.time.values[0] + np.arange(0, npart) * np.timedelta64(2, \"h\")\n",
"\n",
"pset = parcels.ParticleSet(\n",
" fieldset=fieldset, pclass=parcels.Particle, x=lon, y=lat, z=z, t=time\n",
" fieldset=fieldset, pclass=parcels.Particle, x=lon, y=lat, t=time\n",
")\n",
"\n",
"output_file = parcels.ParticleFile(\"output.parquet\", outputdt=np.timedelta64(2, \"h\"))"
Expand Down
2 changes: 1 addition & 1 deletion docs/user_guide/getting_started/tutorial_quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ npart = 10 # number of particles to be released
lat = np.linspace(-32.5, -30.5, npart)
lon = np.repeat(32, npart)
time = np.repeat(ds_fields.time.values[0], npart) # at initial time of input data
z = np.repeat(ds_fields.depth.values[0], npart) # at the first depth (surface)
z = np.repeat(0.5, npart) # at 0.5 meter depth (first level of the input data)

pset = parcels.ParticleSet(
fieldset=fieldset, pclass=parcels.Particle, t=time, z=z, y=lat, x=lon
Expand Down