{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Non-linear recharge models\n",
    "*R.A. Collenteur, University of Graz*\n",
    "\n",
    "This notebook explains the use of the `RechargeModel` stress model to simulate the combined effect of precipitation and potential evaporation on the groundwater levels. For the computation of the groundwater recharge, four recharge models are currently available:\n",
    "\n",
    "- `Linear` ([Berendrecht et al., 2003](#References); [von Asmuth et al., 2008](#References))\n",
    "- `Berendrecht` ([Berendrecht et al., 2006](#References))\n",
    "- `FlexModel` ([Collenteur et al., 2021](#References))\n",
    "- `Peterson` ([Peterson & Western, 2014](#References))\n",
    "\n",
    "The first model is a simple linear function of precipitation and potential evaporation while the latter two are simulate a non-linear response of recharge to precipitation using a soil-water balance concepts. Detailed descriptions of these models can be found in articles listed in the [References](#References) at the end of this notebook.\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "    \n",
    "<b>Tip</b> \n",
    "    \n",
    "To run this notebook and the related non-linear recharge models, it is strongly recommended to install Numba (http://numba.pydata.org). This Just-In-Time (JIT) compiler compiles the computationally intensive part of the recharge calculation, making the non-linear model as fast as the Linear recharge model.\n",
    "    \n",
    "</div>\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "import pastas as ps\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "ps.show_versions(numba=True)\n",
    "ps.set_log_level(\"INFO\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Read Input data\n",
    "Input data handling is similar to other stressmodels. The only thing that is necessary to check is that the precipitation and evaporation are provided in mm/day. This is necessary because the parameters for the non-linear recharge models are defined in mm for the length unit and days for the time unit. It is possible to use other units, but this would require manually setting the initial values and parameter boundaries for the recharge models."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "head = pd.read_csv(\"data/B32C0639001.csv\",  parse_dates=['date'], \n",
    "                   index_col='date').squeeze()\n",
    "\n",
    "# Make this millimeters per day\n",
    "evap = pd.read_csv('data/evap_260.csv', index_col=0, parse_dates=[0]).squeeze()\n",
    "rain = pd.read_csv('data/rain_260.csv', index_col=0, parse_dates=[0]).squeeze()\n",
    "\n",
    "ps.plots.series(head, [evap, rain], figsize=(10,6), \n",
    "                labels=[\"Head [m]\", \"Evap [mm/d]\", \"Rain [mm/d]\"]);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Make a basic model\n",
    "The normal workflow may be used to create and calibrate the model.\n",
    "1. Create a Pastas `Model` instance\n",
    "2. Choose a recharge model. All recharge models can be accessed through the recharge subpackage (`ps.rch`).\n",
    "3. Create a `RechargeModel` object and add it to the model\n",
    "4. Solve and visualize the model\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ml = ps.Model(head)\n",
    "\n",
    "# Select a recharge model\n",
    "rch = ps.rch.FlexModel(gw_uptake=True)\n",
    "#rch = ps.rch.Berendrecht()\n",
    "#rch = ps.rch.Linear()\n",
    "#rch = ps.rch.Peterson()\n",
    "\n",
    "rm = ps.RechargeModel(rain, evap, recharge=rch, rfunc=ps.Gamma, name=\"rch\")\n",
    "ml.add_stressmodel(rm)\n",
    "\n",
    "ml.solve(noise=True, tmin=\"1990\", report=\"basic\")\n",
    "ml.plots.results(figsize=(10,6));"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Analyze the estimated recharge flux\n",
    "After the parameter estimation we can take a look at the recharge flux computed by the model. The flux is easy to obtain using the `get_stress` method of the model object, which automatically provides the optimal parameter values that were just estimated. After this, we can for example look at the yearly recharge flux estimated by the Pastas model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "nbsphinx-thumbnail"
    ]
   },
   "outputs": [],
   "source": [
    "recharge = ml.get_stress(\"rch\").resample(\"A\").sum()\n",
    "ax = recharge.plot.bar(figsize=(10,3))\n",
    "ax.set_xticklabels(recharge.index.year)\n",
    "plt.ylabel(\"Recharge [mm/year]\");"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## A few things to keep in mind:\n",
    "Below are a few things to keep in mind while using the (non-linear) recharge models.\n",
    "\n",
    "- The use of an appropriate warmup period is necessary, so make sure the precipitation and evaporation are available some time (e.g., one year) before the calibration period.\n",
    "- Make sure that the units of the precipitation fluxes are in mm/day and that the DatetimeIndex matches exactly.\n",
    "- It may be possible to fix or vary certain parameters, dependent on the problem. Obtaining better initial parameters may be possible by solving without a noise model first (`ml.solve(noise=False)`) and then solve it again using a noise model.\n",
    "- For relatively shallow groundwater levels (e.g., < 10 meters), it may be better to use the `Exponential` response function as the the non-linear models already cause a delayed response.\n",
    "\n",
    "## References\n",
    "- Berendrecht, W. L., Heemink, A. W., van Geer, F. C., and Gehrels, J. C. (2003), [Decoupling of modeling and measuring interval in groundwater time series analysis based on response characteristics](https://doi.org/10.1016/S0022-1694(03)00075-1), Journal of Hydrology, 278, 1–16.\n",
    "- Berendrecht, W. L., Heemink, A. W., van Geer, F. C., and Gehrels, J. C. (2006), [A non-linear state space approach to model groundwater fluctuations](https://www.sciencedirect.com/science/article/abs/pii/S0309170805002113), Advances in Water Resources, 29, 959–973.\n",
    "- Collenteur, R. A., Bakker, M., Klammler, G., and Birk, S. (2021), [Estimation of groundwater recharge from groundwater levels using nonlinear transfer function noise models and comparison to lysimeter data](https://doi.org/10.5194/hess-25-2931-2021), Hydrol. Earth Syst. Sci., 25, 2931–2949.\n",
    "- Peterson, T.J., and A.W. Western (2014), [Nonlinear time-series modeling of unconfined groundwater head](https://doi.org/10.1002/2013WR014800), Water Resour. Res., 50, 8330-8355.\n",
    "- Von Asmuth, J.R., Maas, K., Bakker, M. and Petersen, J. (2008), [Modeling Time Series of Ground Water Head Fluctuations Subjected to Multiple Stresses](https://doi.org/10.1111/j.1745-6584.2007.00382.x). Groundwater, 46: 30-40.\n",
    "\n",
    "## Data Sources\n",
    "In this notebook we analysed a head time series near the town of De Bilt in the Netherlands. Data is obtained from the following resources:\n",
    "- The heads (`B32C0639001.csv`) are downloaded from https://www.dinoloket.nl/ \n",
    "- The precipitation and evapotranspiration (`rain_260.csv` and `evap_260.csv`) are downloaded from https://knmi.nl"
   ]
  }
 ],
 "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.10.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}