SCHISM tutorial update

docs/user_guide/examples/tutorial_schism.ipynb

@@ -404,6 +404,44 @@
     "  (still subject to the single-column vertical approximation above).\n",
     "* See the [interpolation tutorial](./tutorial_interpolation.ipynb) for the available `Ux*` interpolators."
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "18",
+   "metadata": {},
+   "source": [
+    "## Adapting this tutorial to your own SCHISM setup\n",
+    "\n",
+    "The settings in this tutorial, including release region, `dt`, and interpolator, were chosen for this particular demonstration. When applying the tutorial to a different SCHISM grid or domain, revisit the following:\n",
+    "\n",
+    "* **Timestep and the CFL number.** Unstructured meshes are often strongly refined near coastlines,\n",
+    "  river inflows and outflows, exactly where currents are fastest. The local CFL number\n",
+    "  $|u|\\,\\Delta t / \\Delta x$ can therefore vary by orders of magnitude across the mesh. The example\n",
+    "  below is from a river inflow on a finer Lake Ontario mesh: with `dt = 5 min`, the CFL number (with\n",
+    "  $\\Delta x$ approximated by each triangle's shortest edge) is well above 1 in the narrow channel, so\n",
+    "  particles can jump across several cells, or out of the mesh entirely, in a single step. Choose `dt`\n",
+    "  from the *smallest* cells and *fastest* flows that your particles will visit, not from the domain\n",
+    "  average. See [choosing a timestep and integration method](./tutorial_dt_integrators.ipynb).\n",
+    "\n",
+    "  ![CFL number for u and v near a SCHISM river inflow with dt = 5 minutes](../../_static/schism_inflow_cfl.png)\n",
+    "\n",
+    "* **Interpolation and no-normal-flow at boundaries.** The interpolator determines the discrete,\n",
+    "  continuous velocity field that particles actually feel, and it does not necessarily preserve the\n",
+    "  model's boundary conditions. With node-based barycentric interpolation (`UxLinearNodeLinearZF`),\n",
+    "  the velocity in a triangle adjacent to the coastline is a blend of the node values, which need not\n",
+    "  be tangential to the wall. Zoomed in on the same inflow, the velocity in the outermost cells points\n",
+    "  through the boundary, so a particle in those cells can leave the domain even with a small `dt`. See\n",
+    "  the [interpolation tutorial](./tutorial_interpolation.ipynb) and the\n",
+    "  [interpolators overview](./explanation_interpolation.md) for the available options and their properties.\n",
+    "\n",
+    "  ![u and v velocity in the outermost cells of a SCHISM river inflow](../../_static/schism_inflow_wall_velocity.png)\n",
+    "\n",
+    "* **Particles leaving the mesh.** Because of the two points above, some particles near the coast may\n",
+    "  still exit the mesh. Decide how to handle them: release particles away from the boundaries (as done\n",
+    "  here with the `valid_levels` filter, whose threshold depends on your mesh), or catch the relevant\n",
+    "  status codes (e.g. add `parcels.StatusCode.ErrorGridSearching` to `OUT_OF_BOUNDS_STATES`) and stop\n",
+    "  those particles. See [working with status codes](./tutorial_statuscodes.md)."
+   ]
   }
  ],
  "metadata": {