Swash support

ci/scripts/download-all-tutorial-datasets.py

@@ -1,4 +1,4 @@
 import parcels.tutorial
 
 for name in parcels.tutorial.list_datasets():
-    parcels.tutorial.open_dataset(name)
+    parcels.tutorial.get_dataset_files(name)

docs/user_guide/examples/tutorial_fesom.ipynb

@@ -44,9 +44,9 @@
    "source": [
     "## Get the FESOM tutorial dataset\n",
     "\n",
-    "We use a small periodic-channel snapshot from a FESOM2 simulation that ships with Parcels' tutorial data registry. As in the [quickstart](../getting_started/tutorial_quickstart.md), `parcels.tutorial.open_dataset` downloads the files into a local cache on first use; subsequent calls just return the cached copy.\n",
+    "We use a small periodic-channel snapshot from a FESOM2 simulation that ships with Parcels' tutorial data registry. \n",
     "\n",
-    "`uxarray` expects file paths rather than an in-memory dataset, so we trigger the downloads and then point `ux.open_mfdataset` at the cached files:"
+    "`uxarray` expects file paths rather than an in-memory dataset, so we trigger the downloads with `parcels.tutorial.get_dataset_files()` and then point `ux.open_mfdataset` at the cached files:"
    ]
   },
   {
@@ -55,17 +55,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "for name in [\n",
-    "    \"FESOM_periodic_channel/fesom_channel\",  # grid description\n",
-    "    \"FESOM_periodic_channel/u.fesom_channel\",  # zonal velocity (face-registered)\n",
-    "    \"FESOM_periodic_channel/v.fesom_channel\",  # meridional velocity (face-registered)\n",
-    "    \"FESOM_periodic_channel/w.fesom_channel\",  # vertical velocity (node-registered)\n",
-    "]:\n",
-    "    parcels.tutorial.open_dataset(name)\n",
-    "\n",
-    "from parcels._datasets.remote import _DATA_HOME\n",
-    "\n",
-    "data_dir = Path(_DATA_HOME) / \"data\" / \"FESOM_periodic_channel\"\n",
+    "files = parcels.tutorial.get_dataset_files(\"FESOM_periodic_channel/fesom_channel\")\n",
+    "data_dir = Path(files[0]).parent\n",
     "\n",
     "grid_path = str(data_dir / \"fesom_channel.nc\")\n",
     "data_paths = [\n",
@@ -147,7 +138,7 @@
    "outputs": [],
    "source": [
     "fieldset = parcels.FieldSet.from_ugrid_conventions(ds, mesh=\"spherical\")\n",
-    "\n",
+    "fieldset = fieldset.to_windowed_arrays()\n",
     "fieldset.describe()"
    ]
   },

docs/user_guide/examples/tutorial_swash.ipynb

@@ -0,0 +1,147 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "0",
+   "metadata": {},
+   "source": [
+    "# 🖥️ SWASH tutorial"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1",
+   "metadata": {},
+   "source": [
+    "This tutorial shows how to load in native Matlab files from the SWASH model and convert them to a Parcels-compatible `FieldSet`. The tutorial also shows how to run a simple particle tracking simulation using the SWASH data."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import matplotlib.pyplot as plt\n",
+    "import numpy as np\n",
+    "\n",
+    "import parcels\n",
+    "import parcels.tutorial"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "data_file, coord_file = parcels.tutorial.get_dataset_files(\"SWASH_data/data\")\n",
+    "print(data_file, coord_file)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4",
+   "metadata": {},
+   "source": [
+    "Unlike the other tutorials, this tutorial uses the original SWASH output files in Matlab format. If you want to use your own SWASH output files, you should use the `GRD.mat` and `ALL.mat` files in the `parcels.convert.swash_to_sgrid()` function below."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ds = parcels.convert.swash_to_sgrid(data_file=data_file, coord_file=coord_file)\n",
+    "fieldset = parcels.FieldSet.from_sgrid_conventions(ds)\n",
+    "fieldset.describe()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6",
+   "metadata": {},
+   "source": [
+    "Now, we can use this `FieldSet` to run a simulation (note it's very short because the dataset provided in this tutorial is only 20 seconds long)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "npart = 10  # number of particles to be released\n",
+    "y = np.linspace(1, 16, npart)\n",
+    "x = np.repeat(15, npart)\n",
+    "\n",
+    "layerI = 0  # at which water depth, the particles are released\n",
+    "z = np.repeat(ds.depth.values[layerI], npart)\n",
+    "pset = parcels.ParticleSet(fieldset, x=x, y=y, z=z)\n",
+    "\n",
+    "output_file = parcels.ParticleFile(\n",
+    "    \"output-swash.parquet\", outputdt=np.timedelta64(5, \"s\"), mode=\"w\"\n",
+    ")\n",
+    "pset.execute(\n",
+    "    parcels.kernels.AdvectionRK2,\n",
+    "    runtime=np.timedelta64(20, \"s\"),\n",
+    "    dt=np.timedelta64(1, \"s\"),\n",
+    "    output_file=output_file,\n",
+    "    verbose_progress=False,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8",
+   "metadata": {},
+   "source": [
+    "And then plot the results of the simulation, along with the water level at a given time step. The starting positions of the particles are also shown in white."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "df = parcels.read_particlefile(\"output-swash.parquet\")\n",
+    "\n",
+    "fig, ax = plt.subplots(figsize=(8, 4))\n",
+    "waterlevel = ds.isel(time=2).watlev.plot(x=\"lon\", y=\"lat\", cmap=\"magma\", ax=ax)\n",
+    "for traj in df.partition_by(\"particle_id\"):\n",
+    "    ax.plot(traj[\"x\"][0], traj[\"y\"][0], \"wo\", markersize=5)\n",
+    "    ax.plot(traj[\"x\"], traj[\"y\"], color=\"k\")\n",
+    "ax.set_xlim([14, 16])\n",
+    "plt.show()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Parcels:docs (3.14.6)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.14.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/user_guide/index.md

@@ -40,6 +40,7 @@ examples/explanation_grids.md
 examples/tutorial_nemo.ipynb
 examples/tutorial_croco_3D.ipynb
 examples/tutorial_mitgcm.ipynb
+examples/tutorial_swash.ipynb
 examples/tutorial_fesom.ipynb
 examples/tutorial_schism.ipynb
 examples/tutorial_velocityconversion.ipynb

pixi.toml

@@ -158,6 +158,7 @@ mypy = "*"
 lxml = "*" # in CI
 types-tqdm = "*"
 pandas-stubs = "*"
+scipy-stubs = "*"
 
 [feature.typing.tasks]
 typing = { cmd = "mypy src/parcels --install-types", description = "Run static type checking with mypy." }