Merge branch 'main' into fix/spatialslip-zeta-parentheses

Author: erikvansebille

.github/ci/recipe.yaml

@@ -46,6 +46,7 @@ requirements:
     - holoviews >= 1.22.0 # https://github.com/prefix-dev/rattler-build/issues/2326
     - pooch >=1.8.0
     - polars >=1.31.0
+    - tabulate >=0.10.0
 
 tests:
   - python:

.pre-commit-config.yaml

@@ -28,7 +28,7 @@ repos:
       - id: ruff-format
         types_or: [python, jupyter]
   - repo: https://github.com/rbubley/mirrors-prettier # Update mirror as official mirror is deprecated
-    rev: v3.9.1
+    rev: v3.9.4
     hooks:
       - id: prettier
 

docs/_static/custom.css

@@ -0,0 +1,3 @@
+.bd-article .toctree-wrapper > p.caption {
+  display: none;
+}

docs/conf.py

@@ -187,6 +187,7 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
+html_css_files = ["custom.css"]
 html_theme_options = {
     "logo": {
         "alt_text": "Parcels - Home",

docs/getting_started/index.md

@@ -12,7 +12,9 @@ _Animation of virtual particles carried by ocean surface flow in the global ocea
 You can browse the documentation for older versions by using the version switcher in the bottom right.
 ```
 
-**Useful links**: [Installation instructions](getting_started/installation.md) | [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/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)
+
+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.
 
 `````{grid} 1 2 2 2
 :gutter: 4
@@ -22,13 +24,12 @@ You can browse the documentation for older versions by using the version switche
 ````{grid-item-card} Getting started
 :shadow: md
 
-New to **Parcels**? Check out the installation guide, run the quickstart tutorial, and learn the key concepts to understand the package.
+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.
 
 +++
 
-```{button-ref} getting_started/index
+```{button-ref} user_guide/index
 :ref-type: doc
-:click-parent:
 :color: secondary
 :expand:
 
@@ -38,13 +39,12 @@ Get started!
 ````{grid-item-card} How to?
 :shadow: md
 
-Wondering how to load a `FieldSet` or write a `Kernel`? Find **tutorials** and explainers to these and other questions here:
+Wondering how to load a `FieldSet` or write a `Kernel`? Find **tutorials** and explainers to these and other questions here.
 
 +++
 
 ```{button-ref} user_guide/index
 :ref-type: doc
-:click-parent:
 :color: secondary
 :expand:
 
@@ -60,7 +60,6 @@ We encourage anyone to help improve **Parcels**: read our guidelines to get star
 
 ```{button-ref} development/index
 :ref-type: doc
-:click-parent:
 :color: secondary
 :expand:
 
@@ -76,7 +75,6 @@ Want to interact with other users and **Parcels** developers?
 
 ```{button-ref} community/index
 :ref-type: doc
-:click-parent:
 :color: secondary
 :expand:
 
@@ -95,6 +93,5 @@ User guide <user_guide/index>
 Community <community/index>
 Development <development/index>
 API reference <reference/parcels/index>
-v4 <v4/index>
 Parcels website <https://parcels-code.org/>
 ```

docs/index.md

@@ -14,13 +14,13 @@ particles.temperature = fieldset.temperature[particles]
 ````{note}
 The statement above is shorthand for
 ```python
-particles.temperature = fieldset.temperature[particles.time, particles.z, particles.y, particles.x, particles]
+particles.temperature = fieldset.temperature[particles.t, particles.z, particles.y, particles.x, particles]
 ```
 where the `particles` argument at the end provides the grid search algorithm with a first guess for the element indices to interpolate on.
 
 If you want to sample at a different location, or time, that is not necessarily close to the particles location, you can use
 ```python
-particles.temperature = fieldset.temperature[time, z, y, x]
+particles.temperature = fieldset.temperature[t, z, y, x]
 ```
 but this could be slower for curvilinear and unstructured Grids because the entire grid needs to be searched.
 ````
@@ -53,7 +53,7 @@ If we want to create a custom interpolation method, we need to look at the inter
 The `particle_positions` dictionary contains:
 
 ```
-particle_positions = {"time", time, "z", z, "y", y, "x", x}
+particle_positions = {"t", t, "z", z, "y", y, "x", x}
 ```
 
 For structured (`X`) grids, the `grid_positions` dictionary contains:
@@ -63,7 +63,7 @@ grid_positions = {
     "T": {"index": ti, "bcoord": tau},
     "Z": {"index": zi, "bcoord": zeta},
     "Y": {"index": yi, "bcoord": eta},
-    "X": {"index": xi, "bcoord", xsi},
+    "X": {"index": xi, "bcoord": xsi},
 }
 ```
 

docs/user_guide/examples/explanation_interpolation.md

@@ -62,7 +62,7 @@ ds_fields.load()  # load the dataset into memory
 # Create an idealised wind field and add it to the dataset
 tdim, ydim, xdim = (len(ds_fields.time),len(ds_fields.latitude), len(ds_fields.longitude))
 ds_fields["UWind"] = xr.DataArray(
-    data=np.ones((tdim, ydim, xdim)) * np.sin(ds_fields.latitude.values)[None, :, None],
+    data=0.5 * np.ones((tdim, ydim, xdim)) * np.sin(ds_fields.latitude.values - ds_fields.latitude.values.mean())[None, :, None],
     coords=[ds_fields.time, ds_fields.latitude, ds_fields.longitude])
 
 ds_fields["VWind"] = xr.DataArray(
@@ -88,10 +88,12 @@ fieldset = parcels.FieldSet.from_sgrid_conventions(
 Now we define a wind Kernel that uses a forward Euler method to apply the wind forcing. Note that we update the `particles.dx` and `particles.dy` variables, rather than `particles.x` and `particles.y` directly.
 
 ```{code-cell}
-def wind_kernel(particles, fieldset):
-    uwind, vwind = fieldset.Wind[particles]
-    particles.dx += uwind * particles.dt
-    particles.dy += vwind * particles.dt
+def windRK2(particles, fieldset):
+    (u1, v1) = fieldset.Wind[particles]
+    x1, y1 = (particles.x + u1 * 0.5 * particles.dt, particles.y + v1 * 0.5 * particles.dt)
+    (u2, v2) = fieldset.Wind[particles.t + 0.5 * particles.dt, particles.z, y1, x1, particles]
+    particles.dx += u2 * particles.dt
+    particles.dy += v2 * particles.dt
 ```
 
 First run a simulation where we apply Kernels as `[AdvectionRK2, wind_kernel]`
@@ -100,22 +102,22 @@ First run a simulation where we apply Kernels as `[AdvectionRK2, wind_kernel]`
 :tags: [hide-output]
 npart = 10
 z = np.repeat(ds_fields.depth[0].values, npart)
-lons = np.repeat(31, 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)
 output_file = parcels.ParticleFile(
     path="advection_then_wind.parquet", outputdt=np.timedelta64(6,'h')
 )
 pset.execute(
-    [parcels.kernels.AdvectionRK2, wind_kernel],
+    [parcels.kernels.AdvectionRK2, windRK2],
     runtime=np.timedelta64(5,'D'),
     dt=np.timedelta64(1,'h'),
     output_file=output_file,
 )
 ```
 
-Then also run a simulation where we apply the Kernels in the reverse order as `[wind_kernel, AdvectionRK2]`
+Then also run a simulation where we apply the Kernels in the reverse order as `[windRK2, AdvectionRK2]`
 
 ```{code-cell}
 :tags: [hide-output]
@@ -126,7 +128,7 @@ output_file_reverse = parcels.ParticleFile(
     path="wind_then_advection.parquet", outputdt=np.timedelta64(6,"h")
 )
 pset_reverse.execute(
-    [wind_kernel, parcels.kernels.AdvectionRK2],
+    [windRK2, parcels.kernels.AdvectionRK2],
     runtime=np.timedelta64(5,"D"),
     dt=np.timedelta64(1,"h"),
     output_file=output_file_reverse,

docs/user_guide/examples/explanation_kernelloop.md

@@ -63,7 +63,7 @@
     "\n",
     "    # Phase 3: Rising with vertical_speed until at surface\n",
     "    ptcls3.dz -= vertical_speed * ptcls3.dt\n",
-    "    ptcls3.temp = fieldset.thetao[ptcls3.time, ptcls3.z, ptcls3.y, ptcls3.x]\n",
+    "    ptcls3.temp = fieldset.thetao[ptcls3.t, ptcls3.z, ptcls3.y, ptcls3.x]\n",
     "    next_phase = ptcls3.z + ptcls3.dz <= mindepth\n",
     "    ptcls3.cycle_phase[next_phase] = 4\n",
     "    ptcls3.dz[next_phase] = mindepth - ptcls3.z[next_phase]  # avoid overshoot\n",
@@ -107,9 +107,6 @@
     "    \"CopernicusMarine_data_for_Argo_tutorial/data\"\n",
     ")\n",
     "\n",
-    "# TODO check how we can get good performance without loading full dataset in memory\n",
-    "ds_fields.load()  # load the dataset into memory\n",
-    "\n",
     "# Select fields\n",
     "fields = {\n",
     "    \"U\": ds_fields[\"uo\"],\n",
@@ -120,6 +117,7 @@
     "# Convert to SGRID-compliant dataset and create FieldSet\n",
     "ds_fset = parcels.convert.copernicusmarine_to_sgrid(fields=fields)\n",
     "fieldset = parcels.FieldSet.from_sgrid_conventions(ds_fset)\n",
+    "fieldset.to_windowed_arrays()\n",
     "\n",
     "# Define a new Particle type including extra Variables\n",
     "ArgoParticle = parcels.Particle.add_variable(\n",
@@ -183,8 +181,8 @@
     "\n",
     "fig = plt.figure(figsize=(13, 6))\n",
     "ax = plt.axes()\n",
-    "ax.plot(df[\"time\"], df[\"z\"], color=\"gray\")\n",
-    "cb = ax.scatter(df[\"time\"], df[\"z\"], c=df[\"temp\"], s=20, marker=\"o\", zorder=2)\n",
+    "ax.plot(df[\"t\"], df[\"z\"], color=\"gray\")\n",
+    "cb = ax.scatter(df[\"t\"], df[\"z\"], c=df[\"temp\"], s=20, marker=\"o\", zorder=2)\n",
     "ax.set_xlabel(\"Time [days]\")\n",
     "ax.set_ylabel(\"Depth (m)\")\n",
     "ax.invert_yaxis()\n",

docs/user_guide/examples/tutorial_Argofloats.ipynb

@@ -265,8 +265,8 @@
     "```python\n",
     "def SampleTempCroco(particles, fieldset):\n",
     "    \"\"\"Sample temperature field on a CROCO sigma grid by first converting z to sigma levels.\"\"\"\n",
-    "    sigma = convert_z_to_sigma_croco(fieldset, particles.time, particles.z, particles.y, particles.x, particles)\n",
-    "    particles.temp = fieldset.T[particles.time, sigma, particles.y, particles.x, particles]"
+    "    sigma = convert_z_to_sigma_croco(fieldset, particles.t, particles.z, particles.y, particles.x, particles)\n",
+    "    particles.temp = fieldset.T[particles.t, sigma, particles.y, particles.x, particles]"
    ]
   },
   {
@@ -278,14 +278,14 @@
     "In particular, the following algorithm is used (note that the RK4 version is slightly more complex than this Euler-Forward version, but the idea is identical). Also note that the vertical velocity is linearly interpolated here, which gives much better results than the default C-grid interpolation.\n",
     "\n",
     "```python\n",
-    "sigma = particles.z / fieldset.h[particles.time, 0, particles.y, particles.x]\n",
+    "sigma = particles.z / fieldset.h[particles.t, 0, particles.y, particles.x]\n",
     "\n",
-    "sigma_levels = convert_z_to_sigma_croco(fieldset, particles.time, particles.z, particles.y, particles.x, particles)\n",
-    "(u, v) = fieldset.UV[time, sigma_levels, particles.y, particles.x, particles]\n",
-    "w = fieldset.W[time, sigma_levels, particles.y, particles.x, particles]\n",
+    "sigma_levels = convert_z_to_sigma_croco(fieldset, particles.t, particles.z, particles.y, particles.x, particles)\n",
+    "(u, v) = fieldset.UV[particles.t, sigma_levels, particles.y, particles.x, particles]\n",
+    "w = fieldset.W[particles.t, sigma_levels, particles.y, particles.x, particles]\n",
     "\n",
     "# scaling the w with the sigma level of the particle\n",
-    "w_sigma = w * sigma / fieldset.h[particles.time, 0, particles.y, particles.x, particles]\n",
+    "w_sigma = w * sigma / fieldset.h[particles.t, 0, particles.y, particles.x, particles]\n",
     "\n",
     "x_new = particles.x + u*particles.dt\n",
     "y_new = particles.y + v*particles.dt\n",
@@ -294,7 +294,7 @@
     "sigma_new = sigma + w_sigma*particles.dt \n",
     "\n",
     "# converting back from sigma to z, at _new_ location\n",
-    "z_new = sigma_new * fieldset.h[particles.time, 0, y_new, x_new, particles]\n",
+    "z_new = sigma_new * fieldset.h[particles.t, 0, y_new, x_new, particles]\n",
     "```"
    ]
   }