{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# The Parcels Kernel loop\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This tutorial explains how Parcels executes multiple Kernels, and what happens under the hood when you combine Kernels. \n",
    "\n",
    "This is probably not very relevant when you only use the built-in Advection kernels, but can be important when you are writing and combining your own Kernels!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Background\n",
    "\n",
    "When you run a Parcels simulation (i.e. a call to `pset.execute()`), the Kernel loop is the main part of the code that is executed. This part of the code loops through all particles and executes the Kernels that are defined for each particle.\n",
    "\n",
    "In order to make sure that the displacements of a particle in the different Kernels can be summed, all Kernels add to a _change_ in position (`particle_dlon`, `particle_dlat`, and `particle_ddepth`). This is important, because there are situations where movement kernels would otherwise not commute. Take the example of advecting particles by currents _and_ winds. If the particle would first be moved by the currents and then by the winds, the result could be different from first moving by the winds and then by the currents. Instead, by adding the changes in position, the ordering of the Kernels has no consequence on the particle displacement."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "\n",
    "__Note__ that the variables `particle_dlon`, `particle_dlat`, and `particle_ddepth` are defined by the wrapper function that Parcels generates for each Kernel. This is why you don't have to define these variables yourself when writing a Kernel. See [here](https://github.com/OceanParcels/parcels/blob/daa4b062ed8ae0b2be3d87367d6b45599d6f95db/parcels/kernel.py#L277-L294) for the implementation of the wrapper functions.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Basic implementation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Below is a structured overview of the Kernel loop is implemented. Note that this is for longitude only, but the same process is applied for latitude and depth.\n",
    "\n",
    "1. Define an extra variable `particle.lon_nextloop` for each particle, which is the longitude at the end of the Kernel loop. Inititalise it to `particle.lon`.\n",
    "\n",
    "2. Also define an extra variable `particle.time_nextloop` for each particle, which is the time at the end of the Kernel loop. Inititalise it to `particle.time`.\n",
    "\n",
    "3. Within the Kernel loop, for each particle:<br>\n",
    "\n",
    "    1. Update `particle.lon` with `particle.lon_nextloop`<br>\n",
    "\n",
    "    2. Update `particle.time` with `particle.time_nextloop`<br>\n",
    "\n",
    "    3. Set local variable `particle_dlon = 0`<br>\n",
    "\n",
    "    4. For each Kernel in the list of Kernels:\n",
    "        \n",
    "        1. Execute the Kernel\n",
    "        \n",
    "        2. Update `particle_dlon` by adding the change in longitude, if needed<br>\n",
    "\n",
    "    5. Update `particle.lon_nextloop` with `particle.lon + particle_dlon`<br>\n",
    "    \n",
    "    6. Update `particle.time_nextloop` with `particle.time + particle.dt`<br>\n",
    "\n",
    "    7. If `outputdt` is a multiple of `particle.time`, write `particle.lon` and `particle.time` to zarr output file<br>\n",
    "\n",
    "Besides having commutable Kernels, the main advantage of this implementation is that, when using Field Sampling with e.g. `particle.temp = fieldset.Temp[particle.time, particle.depth, particle.lat, particle.lon]`, the particle location stays the same throughout the entire Kernel loop. Additionally, this implementation ensures that the particle location is the same as the location of the sampled field in the output file."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example use"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Below is a simple example of some particles at the surface of the ocean. We create an idealised zonal wind flow that will \"push\" a particle that is already affected by the surface currents."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from datetime import timedelta\n",
    "\n",
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "import xarray as xr\n",
    "\n",
    "import parcels\n",
    "\n",
    "# Load the GlobCurrent data in the Agulhas region from the example_data\n",
    "example_dataset_folder = parcels.download_example_dataset(\"GlobCurrent_example_data\")\n",
    "filenames = {\n",
    "    \"U\": f\"{example_dataset_folder}/20*.nc\",\n",
    "    \"V\": f\"{example_dataset_folder}/20*.nc\",\n",
    "}\n",
    "variables = {\n",
    "    \"U\": \"eastward_eulerian_current_velocity\",\n",
    "    \"V\": \"northward_eulerian_current_velocity\",\n",
    "}\n",
    "dimensions = {\"lat\": \"lat\", \"lon\": \"lon\", \"time\": \"time\"}\n",
    "fieldset = parcels.FieldSet.from_netcdf(filenames, variables, dimensions)\n",
    "# uppermost layer in the hydrodynamic data\n",
    "fieldset.mindepth = fieldset.U.depth[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create an idealised wind field and add it to the fieldset\n",
    "xdim, ydim = (len(fieldset.U.lon), len(fieldset.U.lat))\n",
    "UWind = parcels.Field(\n",
    "    \"UWind\",\n",
    "    np.ones((ydim, xdim), dtype=np.float32) * np.sin(fieldset.U.lat)[:, None],\n",
    "    lon=fieldset.U.lon,\n",
    "    lat=fieldset.U.lat,\n",
    "    mesh=\"spherical\",\n",
    "    fieldtype=\"U\",\n",
    ")\n",
    "VWind = parcels.Field(\n",
    "    \"VWind\", np.zeros((ydim, xdim), dtype=np.float32), grid=UWind.grid, fieldtype=\"V\"\n",
    ")\n",
    "fieldset_wind = parcels.FieldSet(UWind, VWind)\n",
    "\n",
    "fieldset.add_field(fieldset_wind.U, name=\"UWind\")\n",
    "fieldset.add_field(fieldset_wind.V, name=\"VWind\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now define a wind kernel that uses a forward Euler method to apply the wind forcing. Note that we update the `particle_dlon` and `particle_dlat` variables, rather than `particle.lon` and `particle.lat` directly."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "def wind_kernel(particle, fieldset, time):\n",
    "    particle_dlon += (\n",
    "        fieldset.UWind[time, particle.depth, particle.lat, particle.lon] * particle.dt\n",
    "    )\n",
    "    particle_dlat += (\n",
    "        fieldset.VWind[time, particle.depth, particle.lat, particle.lon] * particle.dt\n",
    "    )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Run a simulation where we apply first kernels as `[AdvectionRK4, wind_kernel]`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO: Output files are stored in advection_then_wind.zarr.\n",
      "100%|██████████| 432000.0/432000.0 [00:00<00:00, 1059409.81it/s]\n"
     ]
    }
   ],
   "source": [
    "lons = 26.0 * np.ones(10)\n",
    "lats = np.linspace(-37.5, -34.5, 10)\n",
    "\n",
    "pset = parcels.ParticleSet(fieldset, pclass=parcels.JITParticle, lon=lons, lat=lats)\n",
    "output_file = pset.ParticleFile(\n",
    "    name=\"advection_then_wind.zarr\", outputdt=timedelta(hours=6)\n",
    ")\n",
    "pset.execute(\n",
    "    [parcels.AdvectionRK4, wind_kernel],\n",
    "    runtime=timedelta(days=5),\n",
    "    dt=timedelta(hours=1),\n",
    "    output_file=output_file,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And also run a simulation where we apply the kernels in the reverse order as `[wind_kernel, AdvectionRK4]`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "INFO: Output files are stored in wind_then_advection.zarr.\n",
      "100%|██████████| 432000.0/432000.0 [00:00<00:00, 1317764.47it/s]\n"
     ]
    }
   ],
   "source": [
    "pset_reverse = parcels.ParticleSet(\n",
    "    fieldset, pclass=parcels.JITParticle, lon=lons, lat=lats\n",
    ")\n",
    "output_file_reverse = pset_reverse.ParticleFile(\n",
    "    name=\"wind_then_advection.zarr\", outputdt=timedelta(hours=6)\n",
    ")\n",
    "pset_reverse.execute(\n",
    "    [wind_kernel, parcels.AdvectionRK4],\n",
    "    runtime=timedelta(days=5),\n",
    "    dt=timedelta(hours=1),\n",
    "    output_file=output_file_reverse,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, plot the trajectories to show that they are identical in the two simulations."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# Plot the resulting particle trajectories overlapped for both cases\n",
    "advection_then_wind = xr.open_zarr(\"advection_then_wind.zarr\")\n",
    "wind_then_advection = xr.open_zarr(\"wind_then_advection.zarr\")\n",
    "plt.plot(wind_then_advection.lon.T, wind_then_advection.lat.T, \"-\")\n",
    "plt.plot(advection_then_wind.lon.T, advection_then_wind.lat.T, \"--\", c=\"k\", alpha=0.7)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Caveats"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are a few important considerations to take into account when writing Kernels\n",
    "\n",
    "### 1. Avoid updating particle locations directly in Kernels\n",
    "It is better not to update `particle.lon` directly in a Kernel, as it can interfere with the loop above. Assigning a value to `particle.lon` in a Kernel will throw a warning. \n",
    "\n",
    "Instead, update the local variable `particle_dlon`.\n",
    "\n",
    "### 2. Be careful with updating particle variables that do not depend on Fields.\n",
    "While assigning the interpolated value of a `Field` to a Particle goes well in the loop above, this is not necessarily so for assigning other attributes. For example, a line like `particle.age += particle.dt` is executed directly so may result in the age being `dt` at `time = 0` in the output file. \n",
    "\n",
    "A workaround is to either initialise the age to `-dt`, or to increase the `age` only when `particle.time > 0` (using an `if` statement).\n",
    "\n",
    "\n",
    "### 3. The last time is not written to file\n",
    "Because the location at the start of the loop is written at the end of the Kernel loop, the last `particle.time` of the particle is not written to file. This is similar behaviour to e.g. `np.arange(start, stop)`, which also doesn't include the `stop` value itself. \n",
    "\n",
    "If you do want to write the last time to file, you can increase the `runtime` or `endtime` by `dt` (although this may cause a TimeExtrapolationError if your run was to the end of the available hydrodynamic data), or you can call `pfile.write_latest_locations(pset, time=pset[0].time_nextloop)`. Note that in the latter case, the particle locations (longitude, latitude and depth) will be updated, but other variables will _not_ be updated as the Kernels are not run again."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Working with Status Codes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In order to capture errors in the Kernel loop, Parcels uses a Status Code system. There are several Status Codes, listed below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Success = 0\n",
      "Evaluate = 10\n",
      "Repeat = 20\n",
      "Delete = 30\n",
      "StopExecution = 40\n",
      "StopAllExecution = 41\n",
      "Error = 50\n",
      "ErrorInterpolation = 51\n",
      "ErrorOutOfBounds = 60\n",
      "ErrorThroughSurface = 61\n",
      "ErrorTimeExtrapolation = 70\n"
     ]
    }
   ],
   "source": [
    "from parcels import StatusCode\n",
    "\n",
    "for statuscode, val in StatusCode.__dict__.items():\n",
    "    if statuscode.startswith(\"__\"):\n",
    "        continue\n",
    "    print(f\"{statuscode} = {val}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once an error is thrown (for example, a Field Interpolation error), then the `particle.state` is updated to the corresponding status code. This gives you the flexibility to write a Kernel that checks for a status code and does something with it. \n",
    "\n",
    "For example, you can write a Kernel that checks for `particle.state == StatusCode.ErrorOutOfBounds` and deletes the particle, and then append this to the Kernel list in `pset.execute()`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "def CheckOutOfBounds(particle, fieldset, time):\n",
    "    if particle.state == StatusCode.ErrorOutOfBounds:\n",
    "        particle.delete()\n",
    "\n",
    "\n",
    "def CheckError(particle, fieldset, time):\n",
    "    if particle.state >= 50:  # This captures all Errors\n",
    "        particle.delete()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But of course, you can also write code for more sophisticated behaviour than just deleting the particle. It's up to you! Note that if you don't delete the particle, you will have to update the `particle.state = StatusCode.Success` yourself. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "def Move1DegreeWest(particle, fieldset, time):\n",
    "    if particle.state == StatusCode.ErrorOutOfBounds:\n",
    "        particle_dlon -= 1.0\n",
    "        particle.state = StatusCode.Success"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or, if you want to make sure that particles don't escape through the water surface"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "def KeepInOcean(particle, fieldset, time):\n",
    "    if particle.state == StatusCode.ErrorThroughSurface:\n",
    "        particle_ddepth = 0.0\n",
    "        particle.state = StatusCode.Success"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Kernel functions such as the ones above can then be added to the list of kernels in `pset.execute()`. \n",
    "\n",
    "Note that these Kernels that control what to do with `particle.state` should typically be added at the _end_ of the Kernel list, because otherwise later Kernels may overwrite the `particle.state` or the `particle_dlon` variables."
   ]
  }
 ],
 "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.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}