docs/user_guide/02_forcing.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "bd2d9bd5",
   "metadata": {
    "nbsphinx": "hidden"
   },
   "outputs": [],
   "source": [
    "# Suppress distracting outputs in these examples\n",
    "# Note: this cell should be hidden with the metadata '\"nbsphinx\": \"hidden\"'\n",
    "import logging\n",
    "import warnings\n",
    "\n",
    "warnings.filterwarnings(\"ignore\", category=UserWarning)\n",
    "logger = logging.getLogger(\"esmvalcore\")\n",
    "logger.setLevel(logging.WARNING)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "4130c284",
   "metadata": {},
   "source": [
    "# Forcing data\n",
    "\n",
    "eWaterCycle can load or generate forcing data for a model using the `forcing` module. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6b7a256d",
   "metadata": {},
   "outputs": [],
   "source": [
    "import ewatercycle.forcing"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "83e418e7",
   "metadata": {},
   "source": [
    "Model specific forcing classes can be listed with"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "9624c99d",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"><span style=\"color: #000080; text-decoration-color: #000080\">ForcingSources</span><span style=\"color: #000080; text-decoration-color: #000080; font-weight: bold\">[</span>\n",
       "<span style=\"color: #008000; text-decoration-color: #008000\">    </span><span style=\"color: #008000; text-decoration-color: #008000\">\"DistributedMakkinkForcing\"</span><span style=\"color: #008000; text-decoration-color: #008000\">,</span>\n",
       "<span style=\"color: #008000; text-decoration-color: #008000\">    </span><span style=\"color: #008000; text-decoration-color: #008000\">\"DistributedUserForcing\"</span><span style=\"color: #008000; text-decoration-color: #008000\">,</span>\n",
       "<span style=\"color: #008000; text-decoration-color: #008000\">    </span><span style=\"color: #008000; text-decoration-color: #008000\">\"GenericDistributedForcing\"</span><span style=\"color: #008000; text-decoration-color: #008000\">,</span>\n",
       "<span style=\"color: #008000; text-decoration-color: #008000\">    </span><span style=\"color: #008000; text-decoration-color: #008000\">\"GenericLumpedForcing\"</span><span style=\"color: #008000; text-decoration-color: #008000\">,</span>\n",
       "<span style=\"color: #008000; text-decoration-color: #008000\">    </span><span style=\"color: #008000; text-decoration-color: #008000\">\"HypeForcing\"</span><span style=\"color: #008000; text-decoration-color: #008000\">,</span>\n",
       "<span style=\"color: #008000; text-decoration-color: #008000\">    </span><span style=\"color: #008000; text-decoration-color: #008000\">\"LisfloodForcing\"</span><span style=\"color: #008000; text-decoration-color: #008000\">,</span>\n",
       "<span style=\"color: #008000; text-decoration-color: #008000\">    </span><span style=\"color: #008000; text-decoration-color: #008000\">\"LumpedMakkinkForcing\"</span><span style=\"color: #008000; text-decoration-color: #008000\">,</span>\n",
       "<span style=\"color: #008000; text-decoration-color: #008000\">    </span><span style=\"color: #008000; text-decoration-color: #008000\">\"LumpedUserForcing\"</span><span style=\"color: #008000; text-decoration-color: #008000\">,</span>\n",
       "<span style=\"color: #008000; text-decoration-color: #008000\">    </span><span style=\"color: #008000; text-decoration-color: #008000\">\"MarrmotForcing\"</span><span style=\"color: #008000; text-decoration-color: #008000\">,</span>\n",
       "<span style=\"color: #008000; text-decoration-color: #008000\">    </span><span style=\"color: #008000; text-decoration-color: #008000\">\"PCRGlobWBForcing\"</span><span style=\"color: #008000; text-decoration-color: #008000\">,</span>\n",
       "<span style=\"color: #008000; text-decoration-color: #008000\">    </span><span style=\"color: #008000; text-decoration-color: #008000\">\"WflowForcing\"</span><span style=\"color: #008000; text-decoration-color: #008000\">,</span>\n",
       "<span style=\"color: #000080; text-decoration-color: #000080; font-weight: bold\">]</span>\n",
       "</pre>\n"
      ],
      "text/plain": [
       "\u001b[34mForcingSources\u001b[0m\u001b[1;34m[\u001b[0m\n",
       "\u001b[32m    \u001b[0m\u001b[32m\"DistributedMakkinkForcing\"\u001b[0m\u001b[32m,\u001b[0m\n",
       "\u001b[32m    \u001b[0m\u001b[32m\"DistributedUserForcing\"\u001b[0m\u001b[32m,\u001b[0m\n",
       "\u001b[32m    \u001b[0m\u001b[32m\"GenericDistributedForcing\"\u001b[0m\u001b[32m,\u001b[0m\n",
       "\u001b[32m    \u001b[0m\u001b[32m\"GenericLumpedForcing\"\u001b[0m\u001b[32m,\u001b[0m\n",
       "\u001b[32m    \u001b[0m\u001b[32m\"HypeForcing\"\u001b[0m\u001b[32m,\u001b[0m\n",
       "\u001b[32m    \u001b[0m\u001b[32m\"LisfloodForcing\"\u001b[0m\u001b[32m,\u001b[0m\n",
       "\u001b[32m    \u001b[0m\u001b[32m\"LumpedMakkinkForcing\"\u001b[0m\u001b[32m,\u001b[0m\n",
       "\u001b[32m    \u001b[0m\u001b[32m\"LumpedUserForcing\"\u001b[0m\u001b[32m,\u001b[0m\n",
       "\u001b[32m    \u001b[0m\u001b[32m\"MarrmotForcing\"\u001b[0m\u001b[32m,\u001b[0m\n",
       "\u001b[32m    \u001b[0m\u001b[32m\"PCRGlobWBForcing\"\u001b[0m\u001b[32m,\u001b[0m\n",
       "\u001b[32m    \u001b[0m\u001b[32m\"WflowForcing\"\u001b[0m\u001b[32m,\u001b[0m\n",
       "\u001b[1;34m]\u001b[0m\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "from rich import print\n",
    "\n",
    "print(ewatercycle.forcing.sources)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "702067fe",
   "metadata": {},
   "source": [
    "## Existing forcing from external source\n",
    "\n",
    "We first show how existing forcing data can be loaded with eWaterCycle. The wflow example parameter set already includes forcing data that was generated manually by the scientists at Deltares."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "63d34733",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"><span style=\"color: #800080; text-decoration-color: #800080; font-weight: bold\">WflowForcing</span><span style=\"font-weight: bold\">(</span>\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">start_time</span>=<span style=\"color: #008000; text-decoration-color: #008000\">'1991-01-01T00:00:00Z'</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">end_time</span>=<span style=\"color: #008000; text-decoration-color: #008000\">'1991-12-31T00:00:00Z'</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">directory</span>=<span style=\"color: #800080; text-decoration-color: #800080; font-weight: bold\">PosixPath</span><span style=\"font-weight: bold\">(</span><span style=\"color: #008000; text-decoration-color: #008000\">'/home/bart/ewatercycle/parameter-sets/wflow_rhine_sbm_nc'</span><span style=\"font-weight: bold\">)</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">shape</span>=<span style=\"color: #800080; text-decoration-color: #800080; font-style: italic\">None</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">filenames</span>=<span style=\"font-weight: bold\">{}</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">netcdfinput</span>=<span style=\"color: #008000; text-decoration-color: #008000\">'inmaps.nc'</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">Precipitation</span>=<span style=\"color: #008000; text-decoration-color: #008000\">'/P'</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">EvapoTranspiration</span>=<span style=\"color: #008000; text-decoration-color: #008000\">'/PET'</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">Temperature</span>=<span style=\"color: #008000; text-decoration-color: #008000\">'/TEMP'</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">Inflow</span>=<span style=\"color: #800080; text-decoration-color: #800080; font-style: italic\">None</span>\n",
       "<span style=\"font-weight: bold\">)</span>\n",
       "</pre>\n"
      ],
      "text/plain": [
       "\u001b[1;35mWflowForcing\u001b[0m\u001b[1m(\u001b[0m\n",
       "    \u001b[33mstart_time\u001b[0m=\u001b[32m'1991-01-01T00:00:00Z'\u001b[0m,\n",
       "    \u001b[33mend_time\u001b[0m=\u001b[32m'1991-12-31T00:00:00Z'\u001b[0m,\n",
       "    \u001b[33mdirectory\u001b[0m=\u001b[1;35mPosixPath\u001b[0m\u001b[1m(\u001b[0m\u001b[32m'/home/bart/ewatercycle/parameter-sets/wflow_rhine_sbm_nc'\u001b[0m\u001b[1m)\u001b[0m,\n",
       "    \u001b[33mshape\u001b[0m=\u001b[3;35mNone\u001b[0m,\n",
       "    \u001b[33mfilenames\u001b[0m=\u001b[1m{\u001b[0m\u001b[1m}\u001b[0m,\n",
       "    \u001b[33mnetcdfinput\u001b[0m=\u001b[32m'inmaps.nc'\u001b[0m,\n",
       "    \u001b[33mPrecipitation\u001b[0m=\u001b[32m'/P'\u001b[0m,\n",
       "    \u001b[33mEvapoTranspiration\u001b[0m=\u001b[32m'/PET'\u001b[0m,\n",
       "    \u001b[33mTemperature\u001b[0m=\u001b[32m'/TEMP'\u001b[0m,\n",
       "    \u001b[33mInflow\u001b[0m=\u001b[3;35mNone\u001b[0m\n",
       "\u001b[1m)\u001b[0m\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "from ewatercycle.parameter_sets import available_parameter_sets\n",
    "\n",
    "parameter_set = available_parameter_sets(target_model=\"wflow\")[\"wflow_rhine_sbm_nc\"]\n",
    "\n",
    "forcing = ewatercycle.forcing.sources[\"WflowForcing\"](\n",
    "    directory=str(parameter_set.directory),\n",
    "    start_time=\"1991-01-01T00:00:00Z\",\n",
    "    end_time=\"1991-12-31T00:00:00Z\",\n",
    "    shape=None,\n",
    "    # Additional information about the external forcing data needed for the model configuration\n",
    "    netcdfinput=\"inmaps.nc\",\n",
    "    Precipitation=\"/P\",\n",
    "    EvapoTranspiration=\"/PET\",\n",
    "    Temperature=\"/TEMP\",\n",
    ")\n",
    "print(forcing)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "01d2b977",
   "metadata": {},
   "source": [
    "As you can see, the forcing consists of a generic part which is the same for all eWaterCycle models, and a model-specific part (`forcing_info`). If you're familiar with wflow, you might recognize that the model-specific settings map directly to wflow configuration settings. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "db31b882",
   "metadata": {},
   "source": [
    "## Generating forcing data\n",
    "\n",
    "In most cases, you will not have access to tailor-made forcing data, and manually pre-processing existing datasets can be quite a pain. eWaterCycle includes a forcing generator that can do all the required steps to go from the available datasets (ERA5, ERA-Interim, etc) to whatever format the models require. This is done through [ESMValTool recipes](https://docs.esmvaltool.org/en/latest/recipes/recipe_hydrology.html).\n",
    "\n",
    "The most simple forcing available only contains NetCDF files for precipitation and air temperature. These are the \"generic\" forcing generators:\n",
    "\n",
    "* [GenericDistributedForcing](../autoapi/ewatercycle/base/forcing/index.html#ewatercycle.base.forcing.GenericDistributedForcing) for distributed models aka grid based models\n",
    "* [GenericLumpedForcing](../autoapi/ewatercycle/base/forcing/index.html#ewatercycle.base.forcing.GenericLumpedForcing) for lumped models aka point based models\n",
    "\n",
    "Usually, (potential) evaporation is required. For this eWaterCycle includes forcing computed using Makkink's equation:\n",
    "\n",
    "* [DistributedMakkinkForcing](../autoapi/ewatercycle/_forcings/makkink/index.html#ewatercycle._forcings.makkink.DistributedMakkinkForcing)\n",
    "* [LumpedMakkinkForcing](../autoapi/ewatercycle/_forcings/makkink/index.html#ewatercycle._forcings.makkink.LumpedMakkinkForcing)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "46980640",
   "metadata": {},
   "source": [
    "For example, to generate forcing for the Rhine river basin for 2001 and 2002 you can use the following code:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "d52b0a76",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "ERROR 1: PROJ: proj_create_from_database: Open of /home/bart/micromamba/envs/ewc3.11/share/proj failed\n",
      "ERROR 1: PROJ: proj_create_from_database: Open of /home/bart/micromamba/envs/ewc3.11/share/proj failed\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"><span style=\"color: #800080; text-decoration-color: #800080; font-weight: bold\">GenericDistributedForcing</span><span style=\"font-weight: bold\">(</span>\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">start_time</span>=<span style=\"color: #008000; text-decoration-color: #008000\">'2000-01-01T00:00:00Z'</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">end_time</span>=<span style=\"color: #008000; text-decoration-color: #008000\">'2001-01-01T00:00:00Z'</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">directory</span>=<span style=\"color: #800080; text-decoration-color: #800080; font-weight: bold\">PosixPath</span><span style=\"font-weight: bold\">(</span><span style=\"color: #008000; text-decoration-color: #008000\">'/home/bart/esmvaltool_output/ewcrepty2fypdu_20240312_154014/work/diagnostic/script'</span><span style=\"font-weight: bold\">)</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">shape</span>=<span style=\"color: #800080; text-decoration-color: #800080; font-weight: bold\">PosixPath</span><span style=\"font-weight: bold\">(</span><span style=\"color: #008000; text-decoration-color: #008000\">'/home/bart/git/ewatercycle/src/ewatercycle/testing/data/Rhine/Rhine.shp'</span><span style=\"font-weight: bold\">)</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">filenames</span>=<span style=\"font-weight: bold\">{</span>\n",
       "        <span style=\"color: #008000; text-decoration-color: #008000\">'pr'</span>: <span style=\"color: #008000; text-decoration-color: #008000\">'OBS6_ERA5_reanaly_1_day_pr_2000-2001.nc'</span>,\n",
       "        <span style=\"color: #008000; text-decoration-color: #008000\">'tas'</span>: <span style=\"color: #008000; text-decoration-color: #008000\">'OBS6_ERA5_reanaly_1_day_tas_2000-2001.nc'</span>\n",
       "    <span style=\"font-weight: bold\">}</span>\n",
       "<span style=\"font-weight: bold\">)</span>\n",
       "</pre>\n"
      ],
      "text/plain": [
       "\u001b[1;35mGenericDistributedForcing\u001b[0m\u001b[1m(\u001b[0m\n",
       "    \u001b[33mstart_time\u001b[0m=\u001b[32m'2000-01-01T00:00:00Z'\u001b[0m,\n",
       "    \u001b[33mend_time\u001b[0m=\u001b[32m'2001-01-01T00:00:00Z'\u001b[0m,\n",
       "    \u001b[33mdirectory\u001b[0m=\u001b[1;35mPosixPath\u001b[0m\u001b[1m(\u001b[0m\u001b[32m'/home/bart/esmvaltool_output/ewcrepty2fypdu_20240312_154014/work/diagnostic/script'\u001b[0m\u001b[1m)\u001b[0m,\n",
       "    \u001b[33mshape\u001b[0m=\u001b[1;35mPosixPath\u001b[0m\u001b[1m(\u001b[0m\u001b[32m'/home/bart/git/ewatercycle/src/ewatercycle/testing/data/Rhine/Rhine.shp'\u001b[0m\u001b[1m)\u001b[0m,\n",
       "    \u001b[33mfilenames\u001b[0m=\u001b[1m{\u001b[0m\n",
       "        \u001b[32m'pr'\u001b[0m: \u001b[32m'OBS6_ERA5_reanaly_1_day_pr_2000-2001.nc'\u001b[0m,\n",
       "        \u001b[32m'tas'\u001b[0m: \u001b[32m'OBS6_ERA5_reanaly_1_day_tas_2000-2001.nc'\u001b[0m\n",
       "    \u001b[1m}\u001b[0m\n",
       "\u001b[1m)\u001b[0m\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "from ewatercycle.testing.fixtures import rhine_shape\n",
    "\n",
    "shape = rhine_shape()\n",
    "forcing = ewatercycle.forcing.sources[\"GenericDistributedForcing\"].generate(\n",
    "    dataset=\"ERA5\",\n",
    "    start_time=\"2000-01-01T00:00:00Z\",\n",
    "    end_time=\"2001-01-01T00:00:00Z\",\n",
    "    shape=shape.absolute(),\n",
    ")\n",
    "print(forcing)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "56fc7471",
   "metadata": {},
   "source": [
    "As a second example, we can generate forcing from the EC-Earth3 climate model data.\n",
    "This can be for historical data, but also climate scenarios.\n",
    "\n",
    "This time we'll demonstrate the `LumpedMakkinkForcing`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "976a8ec4",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "ERROR 1: PROJ: proj_create_from_database: Open of /home/bart/micromamba/envs/ewc3.11/share/proj failed\n",
      "ERROR 1: PROJ: proj_create_from_database: Open of /home/bart/micromamba/envs/ewc3.11/share/proj failed\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"><span style=\"color: #800080; text-decoration-color: #800080; font-weight: bold\">LumpedMakkinkForcing</span><span style=\"font-weight: bold\">(</span>\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">start_time</span>=<span style=\"color: #008000; text-decoration-color: #008000\">'2000-01-01T00:00:00Z'</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">end_time</span>=<span style=\"color: #008000; text-decoration-color: #008000\">'2001-01-01T00:00:00Z'</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">directory</span>=<span style=\"color: #800080; text-decoration-color: #800080; font-weight: bold\">PosixPath</span><span style=\"font-weight: bold\">(</span><span style=\"color: #008000; text-decoration-color: #008000\">'/home/bart/esmvaltool_output/ewcrep3p_5ibfk_20240312_155600/work/diagnostic/script'</span><span style=\"font-weight: bold\">)</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">shape</span>=<span style=\"color: #800080; text-decoration-color: #800080; font-weight: bold\">PosixPath</span><span style=\"font-weight: bold\">(</span><span style=\"color: #008000; text-decoration-color: #008000\">'/home/bart/git/ewatercycle/src/ewatercycle/testing/data/Rhine/Rhine.shp'</span><span style=\"font-weight: bold\">)</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">filenames</span>=<span style=\"font-weight: bold\">{</span>\n",
       "        <span style=\"color: #008000; text-decoration-color: #008000\">'pr'</span>: <span style=\"color: #008000; text-decoration-color: #008000\">'CMIP6_EC-Earth3_day_historical_r6i1p1f1_pr_gr_2000-2001.nc'</span>,\n",
       "        <span style=\"color: #008000; text-decoration-color: #008000\">'tas'</span>: <span style=\"color: #008000; text-decoration-color: #008000\">'CMIP6_EC-Earth3_day_historical_r6i1p1f1_tas_gr_2000-2001.nc'</span>,\n",
       "        <span style=\"color: #008000; text-decoration-color: #008000\">'rsds'</span>: <span style=\"color: #008000; text-decoration-color: #008000\">'CMIP6_EC-Earth3_day_historical_r6i1p1f1_rsds_gr_2000-2001.nc'</span>,\n",
       "        <span style=\"color: #008000; text-decoration-color: #008000\">'evspsblpot'</span>: <span style=\"color: #008000; text-decoration-color: #008000\">'Derived_Makkink_evspsblpot.nc'</span>\n",
       "    <span style=\"font-weight: bold\">}</span>\n",
       "<span style=\"font-weight: bold\">)</span>\n",
       "</pre>\n"
      ],
      "text/plain": [
       "\u001b[1;35mLumpedMakkinkForcing\u001b[0m\u001b[1m(\u001b[0m\n",
       "    \u001b[33mstart_time\u001b[0m=\u001b[32m'2000-01-01T00:00:00Z'\u001b[0m,\n",
       "    \u001b[33mend_time\u001b[0m=\u001b[32m'2001-01-01T00:00:00Z'\u001b[0m,\n",
       "    \u001b[33mdirectory\u001b[0m=\u001b[1;35mPosixPath\u001b[0m\u001b[1m(\u001b[0m\u001b[32m'/home/bart/esmvaltool_output/ewcrep3p_5ibfk_20240312_155600/work/diagnostic/script'\u001b[0m\u001b[1m)\u001b[0m,\n",
       "    \u001b[33mshape\u001b[0m=\u001b[1;35mPosixPath\u001b[0m\u001b[1m(\u001b[0m\u001b[32m'/home/bart/git/ewatercycle/src/ewatercycle/testing/data/Rhine/Rhine.shp'\u001b[0m\u001b[1m)\u001b[0m,\n",
       "    \u001b[33mfilenames\u001b[0m=\u001b[1m{\u001b[0m\n",
       "        \u001b[32m'pr'\u001b[0m: \u001b[32m'CMIP6_EC-Earth3_day_historical_r6i1p1f1_pr_gr_2000-2001.nc'\u001b[0m,\n",
       "        \u001b[32m'tas'\u001b[0m: \u001b[32m'CMIP6_EC-Earth3_day_historical_r6i1p1f1_tas_gr_2000-2001.nc'\u001b[0m,\n",
       "        \u001b[32m'rsds'\u001b[0m: \u001b[32m'CMIP6_EC-Earth3_day_historical_r6i1p1f1_rsds_gr_2000-2001.nc'\u001b[0m,\n",
       "        \u001b[32m'evspsblpot'\u001b[0m: \u001b[32m'Derived_Makkink_evspsblpot.nc'\u001b[0m\n",
       "    \u001b[1m}\u001b[0m\n",
       "\u001b[1m)\u001b[0m\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# See https://www.climate4impact.eu/c4i-frontend/search for an overview of models,\n",
    "# experiments, and ensemble members.\n",
    "cmip_dataset = {\n",
    "    \"dataset\": \"EC-Earth3\",  # Name of the model\n",
    "    \"project\": \"CMIP6\",\n",
    "    \"grid\": \"gr\",\n",
    "    \"exp\": \"historical\",  # historical, or climate scenario\n",
    "    \"ensemble\": \"r6i1p1f1\",  # ensemble member\n",
    "}\n",
    "\n",
    "forcing = ewatercycle.forcing.sources[\"LumpedMakkinkForcing\"].generate(\n",
    "    dataset=cmip_dataset,\n",
    "    start_time=\"2000-01-01T00:00:00Z\",\n",
    "    end_time=\"2001-01-01T00:00:00Z\",\n",
    "    shape=shape.absolute(),\n",
    ")\n",
    "print(forcing)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "d01120c6",
   "metadata": {},
   "source": [
    "### Loading generated forcing\n",
    "\n",
    "Generated forcing is automatically saved to the ESMValTool output directory. A `yaml` file is stored there as well, such that you can easily reload the forcing later without having to generate it again."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "9a47804f",
   "metadata": {
    "tags": []
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"><span style=\"color: #800080; text-decoration-color: #800080; font-weight: bold\">WflowForcing</span><span style=\"font-weight: bold\">(</span>\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">start_time</span>=<span style=\"color: #008000; text-decoration-color: #008000\">'1990-01-01T00:00:00Z'</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">end_time</span>=<span style=\"color: #008000; text-decoration-color: #008000\">'1990-01-31T00:00:00Z'</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">directory</span>=<span style=\"color: #800080; text-decoration-color: #800080; font-weight: bold\">PosixPath</span><span style=\"font-weight: bold\">(</span><span style=\"color: #008000; text-decoration-color: #008000\">'/home/bart/esmvaltool_output/ewcrepofsot6jc_20240312_133128/work/diagnostic/script'</span><span style=\"font-weight: bold\">)</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">shape</span>=<span style=\"color: #800080; text-decoration-color: #800080; font-style: italic\">None</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">filenames</span>=<span style=\"font-weight: bold\">{}</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">netcdfinput</span>=<span style=\"color: #008000; text-decoration-color: #008000\">'wflow_ERA-Interim_Rhine_1990_1990.nc'</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">Precipitation</span>=<span style=\"color: #008000; text-decoration-color: #008000\">'/pr'</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">EvapoTranspiration</span>=<span style=\"color: #008000; text-decoration-color: #008000\">'/pet'</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">Temperature</span>=<span style=\"color: #008000; text-decoration-color: #008000\">'/tas'</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">Inflow</span>=<span style=\"color: #800080; text-decoration-color: #800080; font-style: italic\">None</span>\n",
       "<span style=\"font-weight: bold\">)</span>\n",
       "</pre>\n"
      ],
      "text/plain": [
       "\u001b[1;35mWflowForcing\u001b[0m\u001b[1m(\u001b[0m\n",
       "    \u001b[33mstart_time\u001b[0m=\u001b[32m'1990-01-01T00:00:00Z'\u001b[0m,\n",
       "    \u001b[33mend_time\u001b[0m=\u001b[32m'1990-01-31T00:00:00Z'\u001b[0m,\n",
       "    \u001b[33mdirectory\u001b[0m=\u001b[1;35mPosixPath\u001b[0m\u001b[1m(\u001b[0m\u001b[32m'/home/bart/esmvaltool_output/ewcrepofsot6jc_20240312_133128/work/diagnostic/script'\u001b[0m\u001b[1m)\u001b[0m,\n",
       "    \u001b[33mshape\u001b[0m=\u001b[3;35mNone\u001b[0m,\n",
       "    \u001b[33mfilenames\u001b[0m=\u001b[1m{\u001b[0m\u001b[1m}\u001b[0m,\n",
       "    \u001b[33mnetcdfinput\u001b[0m=\u001b[32m'wflow_ERA-Interim_Rhine_1990_1990.nc'\u001b[0m,\n",
       "    \u001b[33mPrecipitation\u001b[0m=\u001b[32m'/pr'\u001b[0m,\n",
       "    \u001b[33mEvapoTranspiration\u001b[0m=\u001b[32m'/pet'\u001b[0m,\n",
       "    \u001b[33mTemperature\u001b[0m=\u001b[32m'/tas'\u001b[0m,\n",
       "    \u001b[33mInflow\u001b[0m=\u001b[3;35mNone\u001b[0m\n",
       "\u001b[1m)\u001b[0m\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "reloaded_forcing = ewatercycle.forcing.sources[\"WflowForcing\"].load(\n",
    "    directory=\"/home/bart/esmvaltool_output/ewcrepofsot6jc_20240312_133128/work/diagnostic/script\"\n",
    ")\n",
    "print(reloaded_forcing)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9046f2fa",
   "metadata": {},
   "source": [
    "## User-defined forcing\n",
    "\n",
    "If you require variables that are not included in the previous examples, or need to compute a different variable for your model, you can make use of the UserForcing classes:\n",
    "\n",
    "* [DistributedUserForcing](../autoapi/ewatercycle/base/forcing/index.html#ewatercycle.base.forcing.DistributedUserForcing)\n",
    "* [LumpedUserForcing](../autoapi/ewatercycle/base/forcing/index.html#ewatercycle.base.forcing.LumpedUserForcing)\n",
    "\n",
    "For these you define the variables and a post-processing function.\n",
    "\n",
    "As an example, we can recreate Makkink forcing in the following way:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "d830d2ec",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "ERROR 1: PROJ: proj_create_from_database: Open of /home/bart/micromamba/envs/ewc3.11/share/proj failed\n",
      "ERROR 1: PROJ: proj_create_from_database: Open of /home/bart/micromamba/envs/ewc3.11/share/proj failed\n"
     ]
    }
   ],
   "source": [
    "from ewatercycle._forcings.makkink import derive_e_pot\n",
    "\n",
    "lumped_forcing = ewatercycle.forcing.sources[\"LumpedUserForcing\"].generate(\n",
    "    start_time=\"2000-01-01T00:00:00Z\",\n",
    "    end_time=\"2001-01-01T00:00:00Z\",\n",
    "    dataset=cmip_dataset,\n",
    "    shape=shape,\n",
    "    variables=(\n",
    "        \"pr\",\n",
    "        \"tas\",\n",
    "        \"rsds\",\n",
    "    ),  # required variables\n",
    "    postprocessor=derive_e_pot,  # post-processing function that adds e_pot\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6805235d",
   "metadata": {},
   "source": [
    "## Model-specific forcing\n",
    "\n",
    "For some models (e.g. lisflood) additional computations are done, as some steps require data and/or code that is not available to ESMValTool.\n",
    "Apart from some standard parameters (start time, datasets, etc.), the forcing generator sometimes requires additional model-specific options.\n",
    "\n",
    "For our wflow example case, we need to pass the DEM file to the ESMValTool recipe as well. All model-specific options are listed in their [documentation](https://ewatercycle.readthedocs.io/en/latest/plugins.html)."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "c9d6d040",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "<p>Current forcing generation dataset sources</p>\n",
    "    \n",
    "<p>eWaterCycle uses ESMValTool to generate forcing data. You can generate forcing from the `ERA5` and `ERA-Interim` datasets. There is also support for generating forcing from datasets on [ESGF](https://esgf.llnl.gov/) by supplying a [Dataset object](autoapi/ewatercycle/esmvaltool/models/index.html#ewatercycle.esmvaltool.models.Dataset) to the `ewatercycle.base.forcing.Defaultforcing.generate` method.</p>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "e0df94ca",
   "metadata": {
    "scrolled": true,
    "tags": []
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "ERROR 1: PROJ: proj_create_from_database: Open of /home/bart/micromamba/envs/ewc3.11/share/proj failed\n",
      "ERROR 1: PROJ: proj_create_from_database: Open of /home/bart/micromamba/envs/ewc3.11/share/proj failed\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<pre style=\"white-space:pre;overflow-x:auto;line-height:normal;font-family:Menlo,'DejaVu Sans Mono',consolas,'Courier New',monospace\"><span style=\"color: #800080; text-decoration-color: #800080; font-weight: bold\">WflowForcing</span><span style=\"font-weight: bold\">(</span>\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">start_time</span>=<span style=\"color: #008000; text-decoration-color: #008000\">'1990-01-01T00:00:00Z'</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">end_time</span>=<span style=\"color: #008000; text-decoration-color: #008000\">'1990-01-31T00:00:00Z'</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">directory</span>=<span style=\"color: #800080; text-decoration-color: #800080; font-weight: bold\">PosixPath</span><span style=\"font-weight: bold\">(</span><span style=\"color: #008000; text-decoration-color: #008000\">'/home/bart/esmvaltool_output/ewcrepssyninpz_20240312_155637/work/diagnostic/script'</span><span style=\"font-weight: bold\">)</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">shape</span>=<span style=\"color: #800080; text-decoration-color: #800080; font-weight: bold\">PosixPath</span><span style=\"font-weight: bold\">(</span><span style=\"color: #008000; text-decoration-color: #008000\">'/home/bart/git/ewatercycle/src/ewatercycle/testing/data/Rhine/Rhine.shp'</span><span style=\"font-weight: bold\">)</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">filenames</span>=<span style=\"font-weight: bold\">{}</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">netcdfinput</span>=<span style=\"color: #008000; text-decoration-color: #008000\">'wflow_ERA-Interim_Rhine_1990_1990.nc'</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">Precipitation</span>=<span style=\"color: #008000; text-decoration-color: #008000\">'/pr'</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">EvapoTranspiration</span>=<span style=\"color: #008000; text-decoration-color: #008000\">'/pet'</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">Temperature</span>=<span style=\"color: #008000; text-decoration-color: #008000\">'/tas'</span>,\n",
       "    <span style=\"color: #808000; text-decoration-color: #808000\">Inflow</span>=<span style=\"color: #800080; text-decoration-color: #800080; font-style: italic\">None</span>\n",
       "<span style=\"font-weight: bold\">)</span>\n",
       "</pre>\n"
      ],
      "text/plain": [
       "\u001b[1;35mWflowForcing\u001b[0m\u001b[1m(\u001b[0m\n",
       "    \u001b[33mstart_time\u001b[0m=\u001b[32m'1990-01-01T00:00:00Z'\u001b[0m,\n",
       "    \u001b[33mend_time\u001b[0m=\u001b[32m'1990-01-31T00:00:00Z'\u001b[0m,\n",
       "    \u001b[33mdirectory\u001b[0m=\u001b[1;35mPosixPath\u001b[0m\u001b[1m(\u001b[0m\u001b[32m'/home/bart/esmvaltool_output/ewcrepssyninpz_20240312_155637/work/diagnostic/script'\u001b[0m\u001b[1m)\u001b[0m,\n",
       "    \u001b[33mshape\u001b[0m=\u001b[1;35mPosixPath\u001b[0m\u001b[1m(\u001b[0m\u001b[32m'/home/bart/git/ewatercycle/src/ewatercycle/testing/data/Rhine/Rhine.shp'\u001b[0m\u001b[1m)\u001b[0m,\n",
       "    \u001b[33mfilenames\u001b[0m=\u001b[1m{\u001b[0m\u001b[1m}\u001b[0m,\n",
       "    \u001b[33mnetcdfinput\u001b[0m=\u001b[32m'wflow_ERA-Interim_Rhine_1990_1990.nc'\u001b[0m,\n",
       "    \u001b[33mPrecipitation\u001b[0m=\u001b[32m'/pr'\u001b[0m,\n",
       "    \u001b[33mEvapoTranspiration\u001b[0m=\u001b[32m'/pet'\u001b[0m,\n",
       "    \u001b[33mTemperature\u001b[0m=\u001b[32m'/tas'\u001b[0m,\n",
       "    \u001b[33mInflow\u001b[0m=\u001b[3;35mNone\u001b[0m\n",
       "\u001b[1m)\u001b[0m\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "generated_forcing = ewatercycle.forcing.sources[\"WflowForcing\"].generate(\n",
    "    dataset=\"ERA-Interim\",\n",
    "    start_time=\"1990-01-01T00:00:00Z\",\n",
    "    end_time=\"1990-01-31T00:00:00Z\",\n",
    "    shape=shape.absolute(),\n",
    "    dem_file=f\"{parameter_set.directory}/staticmaps/wflow_dem.map\",\n",
    ")\n",
    "print(generated_forcing)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8e484e94",
   "metadata": {},
   "source": [
    "To make your own forcing generator, see the [adding models](https://ewatercycle.readthedocs.io/en/latest/adding_models.html#custom-forcing) documentation."
   ]
  }
 ],
 "metadata": {
  "interpreter": {
   "hash": "4f63c3f017d58640bc2174e5f1b6c1610e3d96c1a3fe90d1d439f265cee739e3"
  },
  "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.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}