{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "923e021ac3dc9de2",
   "metadata": {},
   "source": [
    "(_quick_overview)=\n",
    "# Quick overview"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "98e92fe7c85b670a",
   "metadata": {},
   "source": "``rameau`` is a Python interface to run lumped or semi-distributed model simulating river flows and/or groundwater levels in a single watershed or a cluster of watersheds."
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "178874e49aee687b",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-05-24T09:08:49.854012Z",
     "start_time": "2024-05-24T09:08:49.304565Z"
    }
   },
   "outputs": [],
   "source": [
    "import rameau as rm"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9bfead10075d03bb",
   "metadata": {},
   "source": [
    "It follows an object-oriented philosophy. The core object is a `Model` \n",
    "that can be used for simulation, optimisation, and forecast runs.\n",
    "\n",
    "To instantiate a `Model`, the simplest approach is to rely on a TOML \n",
    "configuration file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "725dbf40657b0084",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-05-24T09:08:50.240223Z",
     "start_time": "2024-05-24T09:08:49.855289Z"
    }
   },
   "outputs": [],
   "source": [
    "model = rm.Model.from_toml('model.toml')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c041f61f642f94b2",
   "metadata": {},
   "source": [
    "## Simulation"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f14383f1759ae543",
   "metadata": {},
   "source": [
    "The `Model` can then directly be used to start a simulation run. It will \n",
    "use the parameters contained in the TOML file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "50e3bae471c45912",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-05-24T09:08:50.270168Z",
     "start_time": "2024-05-24T09:08:50.241060Z"
    }
   },
   "outputs": [],
   "source": [
    "sim = model.run_simulation()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d4731a7a485275",
   "metadata": {},
   "source": [
    "This will return a `Simulation` object from which outputs can be retrieved \n",
    "as dataframes. The output variables can be *riverflow* and/or *watertable*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d4cb5e62b408a1ca",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-05-24T09:08:50.299252Z",
     "start_time": "2024-05-24T09:08:50.271221Z"
    }
   },
   "outputs": [],
   "source": [
    "sim.get_output(\"riverflow\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d4a3bfb7fd5b4533",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-05-24T09:08:50.320184Z",
     "start_time": "2024-05-24T09:08:50.300986Z"
    }
   },
   "outputs": [],
   "source": [
    "sim.get_output(\"watertable\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fe74b192aa5a2580",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-05-24T09:08:50.722146Z",
     "start_time": "2024-05-24T09:08:50.321275Z"
    }
   },
   "outputs": [],
   "source": [
    "ax = sim.get_output(\"riverflow\").plot(ylabel='streamflow [m$^3$.s$^{-1}$]')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d147724d22892b84",
   "metadata": {},
   "source": [
    "These dataframes can be used to quickly plot the timeseries."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a764213258908498",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-05-24T09:08:50.940442Z",
     "start_time": "2024-05-24T09:08:50.723274Z"
    }
   },
   "outputs": [],
   "source": [
    "ax = sim.get_output(\"watertable\").plot(ylabel='piezometric level [m]')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "748ec8fa5dd55165",
   "metadata": {},
   "source": [
    "## Parameter estimation"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b55f27a244db2988",
   "metadata": {},
   "source": [
    "The `Model` can also be used to perform an optimisation run to determine the \n",
    "optimal parameter values that best fit the observed data. It will use \n",
    "the parameter values available in the TOML file as a starting point, and\n",
    "optimise the parameters identified as to be optimised in the TOML file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "74d1e279ab20d805",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-05-24T09:08:51.146100Z",
     "start_time": "2024-05-24T09:08:50.941319Z"
    }
   },
   "outputs": [],
   "source": [
    "opt = model.run_optimization()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3275ebaefdb7dc0f",
   "metadata": {},
   "source": [
    "This will return an `OptiSimulation` object. Again, the outputs can be retrieved from it as dataframes. And so do the observations directly from the `Model` instance (either *riverobs* or *groundwaterobs*).\n",
    "They can be gathered into a single dataframe and plotted against one another."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6c290b0e6f3ba543",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2024-05-24T09:08:51.362068Z",
     "start_time": "2024-05-24T09:08:51.147031Z"
    }
   },
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "\n",
    "df =  pd.concat(\n",
    "    [\n",
    "        opt.get_output(\"riverflow\"), \n",
    "        model.get_input('riverobs')\n",
    "    ], \n",
    "    axis=1\n",
    ")\n",
    "\n",
    "df.columns = ['optimisation', 'observations']\n",
    "ax = df.plot(ylabel='streamflow [m$^3$.s$^{-1}$]')"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "3.10.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}