Adding a tutorial to show gsw use in Kernels

docs/examples/tutorial_gsw_density.ipynb

@@ -0,0 +1,155 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "0",
+   "metadata": {},
+   "source": [
+    "# Using the `gsw` toolbox to compute density"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1",
+   "metadata": {},
+   "source": [
+    "This tutorial shows how to use the [`gsw` toolbox](https://teos-10.github.io/GSW-Python/) (the Gibbs SeaWater Oceanographic Toolbox of TEOS-10) within Parcels to compute density from temperature and salinity fields. The `gsw` toolbox can be installed via `conda install gsw`."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2",
+   "metadata": {},
+   "source": [
+    "First, load the necessary libraries and the data:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "import xarray as xr\n",
+    "\n",
+    "import parcels\n",
+    "\n",
+    "# Load the CopernicusMarine data in the Agulhas region from the example_datasets\n",
+    "example_dataset_folder = parcels.download_example_dataset(\n",
+    "    \"CopernicusMarine_data_for_Argo_tutorial\"\n",
+    ")\n",
+    "\n",
+    "ds = xr.open_mfdataset(f\"{example_dataset_folder}/*.nc\", combine=\"by_coords\")\n",
+    "\n",
+    "# TODO check how we can get good performance without loading full dataset in memory\n",
+    "ds.load()  # load the dataset into memory\n",
+    "\n",
+    "fieldset = parcels.FieldSet.from_copernicusmarine(ds)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4",
+   "metadata": {},
+   "source": [
+    "Now, define a custom Particle class that includes temperature, salinity, and density as variables, and create a ParticleSet with one particle at a known location:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "GSWParticle = parcels.Particle.add_variable(\n",
+    "    [\n",
+    "        parcels.Variable(\"temp\", dtype=np.float32, initial=np.nan),\n",
+    "        parcels.Variable(\"salt\", dtype=np.float32, initial=np.nan),\n",
+    "        parcels.Variable(\"density\", dtype=np.float32, initial=np.nan),\n",
+    "    ]\n",
+    ")\n",
+    "\n",
+    "# Initiate one Argo float in the Agulhas Current\n",
+    "pset = parcels.ParticleSet(\n",
+    "    fieldset=fieldset,\n",
+    "    pclass=GSWParticle,\n",
+    "    lon=[32],\n",
+    "    lat=[-31],\n",
+    "    depth=[200],\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6",
+   "metadata": {},
+   "source": [
+    "Now (as the core part of this tutorial) define a custom kernel that uses the `gsw` toolbox to compute density from temperature and salinity:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def ParcelsGSW(particles, fieldset):\n",
+    "    import gsw\n",
+    "\n",
+    "    particles.temp = fieldset.thetao[particles]\n",
+    "    particles.salt = fieldset.so[particles]\n",
+    "    pressure = gsw.p_from_z(-particles.depth, particles.lat)\n",
+    "    particles.density = gsw.density.rho(particles.salt, particles.temp, pressure)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8",
+   "metadata": {},
+   "source": [
+    "Finally, run the `ParcelsGSW` Kernel for one timestep and check (for Continuous Integration purposes) that the computed density is as expected:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "pset.execute(ParcelsGSW, runtime=np.timedelta64(1, \"s\"), dt=np.timedelta64(1, \"s\"))\n",
+    "\n",
+    "np.testing.assert_allclose(pset.density, [1026.8281], rtol=1e-5)\n",
+    "\n",
+    "print(\n",
+    "    f\"Temperature: {pset.temp[0]:.2f}, Salinity: {pset.salt[0]:.2f}, Density: {pset.density[0]:.2f}\"\n",
+    ")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "parcels",
+   "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.13.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

pixi.toml

@@ -64,6 +64,7 @@ tests-notebooks = "pytest --nbval-lax -k 'argo' docs/examples"
 jupyter = "*"
 trajan = "*"
 matplotlib-base = ">=2.0.2"
+gsw = "*"
 
 [feature.docs.dependencies]
 numpydoc = "!=1.9.0"

src/parcels/_tutorial.py

@@ -47,6 +47,7 @@
     ],
     "CopernicusMarine_data_for_Argo_tutorial": [
         "cmems_mod_glo_phy-cur_anfc_0.083deg_P1D-m_uo-vo_31.00E-33.00E_33.00S-30.00S_0.49-2225.08m_2024-01-01-2024-02-01.nc",
+        "cmems_mod_glo_phy-so_anfc_0.083deg_P1D-m_so_31.00E-33.00E_33.00S-30.00S_0.49-2225.08m_2024-01-01-2024-02-01.nc",
         "cmems_mod_glo_phy-thetao_anfc_0.083deg_P1D-m_thetao_31.00E-33.00E_33.00S-30.00S_0.49-2225.08m_2024-01-01-2024-02-01.nc",
     ],
     "DecayingMovingEddy_data": [