{
"cells": [
{
"cell_type": "markdown",
"id": "c87cbaf6",
"metadata": {},
"source": [
"# Response functions\n",
"This notebook provides an overview of the response functions that are available in Pastas. Response functions describe the response of the dependent variable (an `oseries` like groundwater heads) to an independent variable (a `stress` like precipitation or groundwater pumping) and form a fundamental part in the approach implemented in Pastas. Depending on the problem under investigation, a response function may be required with a certain shape or with more degrees of freedom (parameters). Response functions are generally used in combination with a stress model, but in this notebook the response functions are discussed independently to provide an overview of the different response functions and what they represent."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "292ce7c3",
"metadata": {},
"outputs": [],
"source": [
"import numpy as np\n",
"import pandas as pd\n",
"import pastas as ps\n",
"import matplotlib.pyplot as plt\n",
"\n",
"ps.show_versions()"
]
},
{
"cell_type": "markdown",
"id": "819e135d",
"metadata": {},
"source": [
"## Response functions available in Pastas\n",
"The following response functions are available in Pastas:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "a1cb1927",
"metadata": {},
"outputs": [],
"source": [
"ps.rfunc.__all__"
]
},
{
"cell_type": "markdown",
"id": "ddf4372c",
"metadata": {},
"source": [
"Below we discuss the some of the most used respons functions and what they represent:"
]
},
{
"cell_type": "markdown",
"id": "16490ab3",
"metadata": {},
"source": [
"### Exponential response function\n",
"The exponential response function is the simplest response function with only two parameters: a scaling parameter $A$ and a shape parameter $a$. The response function may be used for stresses that start to have an immediate effect on the head, for example precipitation in a shallow aquifer. The step response function plateaus at $A$ (the gain is $A$). \n",
"The equation for the impulse response is:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "850d287f",
"metadata": {},
"outputs": [],
"source": [
"ps.Exponential.impulse"
]
},
{
"cell_type": "markdown",
"id": "2cee1e82",
"metadata": {},
"source": [
"### Gamma response function\n",
"The Gamma response function is slightly more complicated than the exponential response function and has one additional shape parameter $n$. When $n>1$, there is a delay in the response. When $n=1$, the Gamma response is the same as the Exponential response. When $n<1$ there is an immediate response. The response function is the most used response function in Pastas, as its shape is versatile and able to mimic many responses found in the field (it is also used in many other parts of hydrology to simulate a hydrological response). The step response plateaus at $A$ (the gain is $A$). The equation for the impulse response is:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "995242ef",
"metadata": {},
"outputs": [],
"source": [
"ps.Gamma.impulse"
]
},
{
"cell_type": "markdown",
"id": "456085a7",
"metadata": {},
"source": [
"### Hantush response function\n",
"The Hantush response function is intended for the simulation of the response of pumping wells. It is based on the classic Hantush function for pumping in a semi-confined aquifer. The response function has one scale parameter $A$ and two shape parameters $a$ and $b$. \n",
"The step response plateaus at $A$ (the gain is $A$). The equation for the impulse response is:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "e7a08f3d",
"metadata": {},
"outputs": [],
"source": [
"ps.Hantush.impulse"
]
},
{
"cell_type": "markdown",
"id": "a4dd9926",
"metadata": {},
"source": [
"### Double exponential function\n",
"The Double exponential response function is intended for the simulation in a multi-aquifer system, with an initially a quick response and after that a slower response. It consists of two exponential functions and contains four parameters: the scale parameter $A$, two shape parameters $a_1$ and $a_2$, and a parameter $\\alpha$ that distributes the response between the two exponential functions. The step response plateaus at $A$ (the gain is $A$). The Double exponential function is not applied very often in practice. The equation for the impulse response is:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "926b3266",
"metadata": {},
"outputs": [],
"source": [
"ps.DoubleExponential.impulse"
]
},
{
"cell_type": "markdown",
"id": "429e5bc2",
"metadata": {},
"source": [
"### Polder function\n",
"The Polder response function is intended for the simulation of the response to variations of surface water levels. It is based on the response of a semi-confined aquifer to a variation in the surface water boundary. The response function has one scale parameter $A$ and two shape parameters $a$ and $b$. The step response plateaus at $A\\exp(-2\\sqrt{b})$ (the gain is $A\\exp(-2\\sqrt{b})$. The equation for the impulse response is:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "dae6fed9",
"metadata": {},
"outputs": [],
"source": [
"ps.Polder.impulse"
]
},
{
"cell_type": "markdown",
"id": "ce6ff544",
"metadata": {},
"source": [
"### Four parameter function\n",
"The four parameter function is a function with four parameters that includes the Exponential, Gamma, Hantush and Polder functions as a special case. It is the most general function, but it is relatively slow to compute. This function needs further documentation."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "35fd788a",
"metadata": {},
"outputs": [],
"source": [
"ps.FourParam.impulse"
]
},
{
"cell_type": "markdown",
"id": "353490d4",
"metadata": {},
"source": [
"### Examples of response functions\n",
"A few example response functions are plotted below"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "cb87fab9",
"metadata": {},
"outputs": [],
"source": [
"# Default Settings\n",
"cutoff = 0.999\n",
"gain_scale_factor = 1\n",
"up = True\n",
"\n",
"responses = {}\n",
"exp = ps.Exponential()\n",
"responses[\"Exponential\"] = exp\n",
"\n",
"gamma = ps.Gamma()\n",
"responses[\"Gamma\"] = gamma\n",
"\n",
"hantush = ps.Hantush()\n",
"responses[\"Hantush\"] = hantush\n",
"\n",
"polder = ps.Polder()\n",
"responses[\"Polder\"] = polder\n",
"\n",
"fourp = ps.FourParam()\n",
"responses[\"FourParam\"] = fourp\n",
"\n",
"DoubleExp = ps.DoubleExponential()\n",
"responses[\"DoubleExponential\"] = DoubleExp\n",
"\n",
"parameters = pd.DataFrame()\n",
"\n",
"fig, [ax1, ax2] = plt.subplots(1, 2, sharex=True, figsize=(10, 3))\n",
"\n",
"for name, response in responses.items():\n",
" p = response.get_init_parameters(name)\n",
" parameters = pd.concat([parameters, p], axis=0)\n",
" ax1.plot(response.block(p.initial), label=name)\n",
" ax2.plot(response.step(p.initial), label=name)\n",
"\n",
"ax1.set_title(\"Block response\")\n",
"ax1.grid()\n",
"ax2.set_title(\"Step responses\")\n",
"ax2.grid()\n",
"ax1.set_xlabel(\"Time [days]\")\n",
"ax2.set_xlabel(\"Time [days]\")\n",
"ax1.legend()\n",
"plt.xlim(1e-1, 500)\n",
"plt.show()"
]
}
],
"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"
},
"vscode": {
"interpreter": {
"hash": "29475f8be425919747d373d827cb41e481e140756dd3c75aa328bf3399a0138e"
}
}
},
"nbformat": 4,
"nbformat_minor": 5
}