Adding tutorial

Author: erikvansebille

docs/user_guide/examples/tutorial_mitgcm.ipynb

@@ -0,0 +1,133 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "0",
+   "metadata": {},
+   "source": [
+    "# 🖥️ MITgcm tutorial"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1",
+   "metadata": {},
+   "source": [
+    "This tutorial will show how to run a 3D simulation with output from the MITgcm model."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import matplotlib.pyplot as plt\n",
+    "import numpy as np\n",
+    "import xarray as xr\n",
+    "\n",
+    "import parcels\n",
+    "\n",
+    "data_folder = parcels.download_example_dataset(\"MITgcm_example_data\")\n",
+    "ds_fields = xr.open_dataset(data_folder / \"mitgcm_UV_surface_zonally_reentrant.nc\")\n",
+    "\n",
+    "# TODO fix cftime conversion in Parcels itself\n",
+    "t = ds_fields[\"time\"].values\n",
+    "secs = np.array([(ti - t[0]).total_seconds() for ti in t])\n",
+    "td_ns = np.rint(secs * 1e9).astype(\"int64\").astype(\"timedelta64[ns]\")\n",
+    "ds_fields = ds_fields.assign_coords(time=td_ns)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "coords = ds_fields[[\"XG\", \"YG\", \"Zl\", \"time\"]]\n",
+    "ds_fset = parcels.convert.mitgcm_to_sgrid(\n",
+    "    fields={\"U\": ds_fields.UVEL, \"V\": ds_fields.VVEL}, coords=coords\n",
+    ")\n",
+    "fieldset = parcels.FieldSet.from_sgrid_conventions(ds_fset)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4",
+   "metadata": {
+    "tags": [
+     "hide-output"
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "perc = np.arange(5, 100, 10)\n",
+    "lon_vals = np.percentile(fieldset.UV.grid.lon, perc)\n",
+    "lat_vals = np.percentile(fieldset.UV.grid.lat, perc)\n",
+    "\n",
+    "X, Y = np.meshgrid(\n",
+    "    lon_vals,\n",
+    "    lat_vals,\n",
+    ")\n",
+    "Z = np.zeros_like(X)\n",
+    "\n",
+    "\n",
+    "def DeleteParticle(particles, fieldset):\n",
+    "    any_error = particles.state >= 50\n",
+    "    particles[any_error].state = parcels.StatusCode.Delete\n",
+    "\n",
+    "\n",
+    "pset = parcels.ParticleSet(fieldset=fieldset, lon=X, lat=Y, z=Z)\n",
+    "\n",
+    "outputfile = parcels.ParticleFile(\n",
+    "    store=\"mitgcm_particles.zarr\",\n",
+    "    outputdt=np.timedelta64(5000, \"s\"),\n",
+    ")\n",
+    "\n",
+    "pset.execute(\n",
+    "    [parcels.kernels.AdvectionRK2, DeleteParticle],\n",
+    "    runtime=np.timedelta64(10, \"D\"),\n",
+    "    dt=np.timedelta64(1, \"h\"),\n",
+    "    output_file=outputfile,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ds = xr.open_zarr(\"mitgcm_particles.zarr\")\n",
+    "\n",
+    "plt.plot(ds.lon.T, ds.lat.T, \".-\")\n",
+    "plt.show()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "docs",
+   "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.2"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/user_guide/index.md

@@ -27,6 +27,7 @@ The tutorials written for Parcels v3 are currently being updated for Parcels v4.
 examples/explanation_grids.md
 examples/tutorial_nemo_curvilinear.ipynb
 examples/tutorial_nemo_3D.ipynb
+examples/tutorial_mitgcm.ipynb
 examples/tutorial_velocityconversion.ipynb
 examples/tutorial_nestedgrids.ipynb
 examples/tutorial_summingfields.ipynb