Add estimate hydropower example

Author: phumthep

examples/estimate_hydropower.ipynb

@@ -0,0 +1,150 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "02a37d9a",
+   "metadata": {},
+   "source": [
+    "# Estimating Hydropower with the Reservoir Module\n",
+    "\n",
+    "This notebook shows an example of estimating daily hydropower time series given a water system. Here, we will work with a system called \"complex_river\", comprising four reservoirs: Atay, Kamchay, Kirirom1, and Kirirom2. These reservoirs are situated in a cascade. Water flow from Kamchay are diverted 25% to Kirirom1 and 75% to Kirirom2. Hydropower capacities are shown in the figure below.\n",
+    "\n",
+    "The following code imports necessary libraries and displays a diagram of the 'complex_river' water system, illustrating reservoir connections and hydropower capacities."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "67d99308",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "from IPython.display import Image, display\n",
+    "from pownet.folder_utils import get_pownet_dir\n",
+    "\n",
+    "project_root = get_pownet_dir()\n",
+    "image_path = os.path.join(project_root, \"images\", \"complex_river.png\")\n",
+    "display(Image(filename=image_path))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3e7f3d1e",
+   "metadata": {},
+   "source": [
+    "## Setup: Input/Output Folders\n",
+    "\n",
+    "First, we specify the directory containing the input data using `input_folder`. If simulation results need to be saved, we also define the `output_folder`. PowNet requires the following CSV files:\n",
+    "\n",
+    "- `reservoir_unit.csv` contains information on the characteristics of reservoirs\n",
+    "- `inflow.csv` contains the daily inflow to each reservoirs\n",
+    "- `minimum_flow.csv` contains the daily minimum flow from each reservoirs\n",
+    "- `flow_paths.csv` contains the system topology -- the water flow paths\n",
+    "\n",
+    "This code block imports the ReservoirManager and defines essential paths. It sets up the input_folder where PowNet will look for model data (e.g., CSV files for the 'complex_river' model) and an output_folder for saving simulation results. Note: If PowNet was installed via pip, or if your data resides in a different location, you may need to adjust the input_folder path accordingly."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ab379af5",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "from pownet.reservoir import ReservoirManager\n",
+    "\n",
+    "input_folder = os.path.join(project_root, \"model_library\")\n",
+    "output_folder = os.path.join(project_root, \"outputs\")\n",
+    "\n",
+    "# Define the specific model name\n",
+    "model_name = \"complex_river\"\n",
+    "input_folder = os.path.join(input_folder, model_name)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "25e9671b",
+   "metadata": {},
+   "source": [
+    "## Reservoir simulation\n",
+    "\n",
+    "The operation of downstream reservoirs is influenced by the operations of those upstream. The `ReservoirManager` class orchestrates the simulation sequence, commencing with the most upstream reservoirs and progressing downstream. The subsequent code block demonstrates loading reservoir parameters from the previously defined CSV files and executing a simulation to generate time-series data of reservoir dynamics (e.g., water levels, flow, hydropower generation).\n",
+    "\n",
+    "Here, we initialize the `ReservoirManager`, load the reservoir characteristics and system topology from CSV files located in the `input_folder`, and then run the reservoir simulation based on the loaded data and predefined operational rules."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "49059702",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "reservoir_manager = ReservoirManager()\n",
+    "reservoir_manager.load_reservoirs_from_csv(input_folder)\n",
+    "reservoir_manager.simulate()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4da626dd",
+   "metadata": {},
+   "source": [
+    "After the simulation, we retrieve the simulated daily hydropower generation time series for all reservoirs as a pandas DataFrame. We then display the first 5 days of this data, rounded to the nearest whole number, for a quick review."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ec2b2151",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "hydropower_df = reservoir_manager.get_hydropower_ts()\n",
+    "hydropower_df.round(0).head()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2b37cd6d",
+   "metadata": {},
+   "source": [
+    "Finally, to visualize the results for a specific reservoir, we access the 'atay' reservoir object from the ReservoirManager and then generate and display a plot summarizing its state variables (e.g., water level, inflow, outflow, generation) over the simulation period. Of course, we can do this for the other three reservoirs as well."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "946be6d6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "atay_reservoir = reservoir_manager.reservoirs[\"atay\"]\n",
+    "atay_reservoir.plot_state() # Include the output_folder argument if you want to save the plot"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "pownet",
+   "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.12.10"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

images/complex_river.png

@@ -0,0 +1,4 @@
+source,sink,lag_time,flow_fraction
+atay,kamchay,0,1
+kamchay,kirirom1,0,0.25
+kamchay,kirirom2,0,0.75