{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Fixed vertical positioning\n",
    "\n",
    "In some studies, it is useful to be able to fix the vertical position of particles in the water column. Examples include the simulation of buoyant particles (for example, certain types of marine plastic pollution) that sit on the ocean's surface, ocean drifters that sit a fixed depth below the ocean's surface, or larvae that reside close to the sea floor. In this notebook, we demonstrate how to fix the vertical position of particles in the water column when performing PyLag particle tracking simulations.\n",
    "\n",
    "## PyLag configuration options\n",
    "\n",
    "## Controlling a particle's vertical position\n",
    "\n",
    "In PyLag, particles have four attributes that can be used to control their vertical position:\n",
    "\n",
    "* `restore_to_fixed_depth` - If this attribute is set to `True`, the particle will be restored to a fixed depth below the ocean's surface.\n",
    "* `fixed_depth` - The depth below the ocean's surface to which the particle will be restored if `restore_to_fixed_depth` is `True`.\n",
    "* `restore_to_fixed_height` - If this attribute is set to `True`, the particle will be restored to a fixed height above the ocean's floor.\n",
    "* `fixed_height` - The height above the ocean's floor to which the particle will be restored if `restore_to_fixed_height` is `True`.\n",
    "\n",
    "The parameters are set in PyLag's run configuration file, in the section titled `SIMULATION`:\n",
    "\n",
    "```python\n",
    "\n",
    "[SIMULATION]\n",
    "\n",
    "# Keep particles at a fixed depth below the surface by restoring to a fixed depth each time step\n",
    "depth_restoring = True\n",
    "\n",
    "# The fixed depth below the surface that particles are held at if `depth_restoring' is True. A value\n",
    "# 0f 0.0 corresponds to the sea surface; a value of -1.0 to 1 m below the free surface.\n",
    "fixed_depth = 0.0\n",
    "\n",
    "# Keep particles at a fixed height above the ocean floor by restoring to a fixed height each time step\n",
    "fixed_height = False\n",
    "\n",
    "# The fixed height above the ocean floor that particles are held at if `fixed_height' is True. A value\n",
    "# of 0.0 corresponds to the ocean floor; a value of 1.0 to 1 m above the ocean floor.\n",
    "fixed_height = 0.0\n",
    "```\n",
    "\n",
    "**Note:** The options `restore_to_fixed_depth` and `restore_to_fixed_height` are mutually exclusive; PyLag will raise a runtime exception if both are set to `True`. \n",
    "\n",
    "## Surface only simulations\n",
    "\n",
    "In some situations, one may only have access surface fields. For example, those derived from satellite observations of sea surface height. Or, if doing surface only simulations with 3D velocity fields, one may wish to save on time by not reading in the full velocity field which takes time to read in and process. In these cases, there is a second option for controlling the vertical position of particles, which involves the configuration option `surface_only`. If this option is set to `True`, PyLag will only read in the surface fields from the input files, and will not read in the full 3D velocity field (if it is available). This can save a significant amount of time when reading in large velocity fields. The parameters is set in PyLag's run configuration file, in the section titled `SIMULATION`:\n",
    "\n",
    "```python\n",
    "\n",
    "[SIMULATION]\n",
    "\n",
    "# Flag for surface only transport. If set to True, PyLag will only read\n",
    "# surface fields. In this case, initial vertical positions should be\n",
    "# set to 0.0 m below the free surface. Depth and height restoring should\n",
    "# be set to False for efficiency reasons.\n",
    "surface_only = False\n",
    "\n",
    "```\n",
    "\n",
    "As specified in the comment, depth and height restoring should be set to `False` if `surface_only` is set to `True`."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.11.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}