Add estimate hydropower example

Author: phumthep

examples/estimate_hydropower.ipynb

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

images/complex_river.png

@@ -0,0 +1,5 @@
+name,runoff_coeff,basin_area,max_storage,min_level,max_level,max_head,min_day,max_day,max_release,max_generation,turbine_factor
+kirirom1,0.48,99000000,30000000,500,534,373.5,150,310,1728000,12,0.9
+kirirom2,0.48,105000000,30000000,500,540,271,150,310,3456000,18,0.9
+kamchay,0.62,710000000,432000000,500,610,122,180,298,14126400,194,0.9
+atay,0.75,1157000000,443800000,510,545,216,158,311,10800000,240,0.9

model_library/complex_river/flow_path.csv

@@ -0,0 +1,7 @@
+"""This is the core module."""
+
+from .reservoir import ReservoirParams
+
+__all__ = [
+    "ReservoirParams",
+]

model_library/complex_river/inflow.csv

@@ -0,0 +1,76 @@
+import dataclasses
+import pandas as pd
+
+
+@dataclasses.dataclass()
+class ReservoirParams:
+    """
+    Data class to hold static parameters and initial timeseries data for a reservoir.
+
+    Attributes:
+        name (str): The unique name of the reservoir.
+        min_day (int): The day of the year when the target level is typically at its minimum.
+        max_day (int): The day of the year when the target level is typically at its maximum.
+        min_level (float): The minimum operational water level (meters).
+        max_level (float): The maximum operational water level (meters).
+        max_head (float): The maximum hydraulic head difference available for generation (meters).
+        max_storage (float): The maximum storage capacity of the reservoir (m³).
+        max_release (float): The maximum allowable daily release rate (m³/day).
+        max_generation (float): The maximum power generation capacity (MW).
+        turbine_factor (float): The efficiency factor of the turbine(s).
+        inflow_ts (pd.Series): Timeseries of daily natural inflow into the reservoir (m³/day),
+                            indexed from 1 to sim_horizon.
+        minflow_ts (pd.Series): Minimum environmental flow (m³/day), indexed from 1 to sim_horizon.
+        upstream_units (list[str]): List of upstream reservoir names that feed into this reservoir.
+        downstream_flow_fracs (dict[str, float]): Dictionary mapping downstream reservoir names to their
+                                                respective flow fractions (0-1).
+    """
+
+    name: str
+    min_day: int
+    max_day: int
+    min_level: float
+    max_level: float
+    max_head: float
+    max_storage: float
+    max_release: float
+    max_generation: float
+    turbine_factor: float
+    inflow_ts: pd.Series
+    minflow_ts: pd.Series
+    upstream_units: list[str]
+    downstream_flow_fracs: dict[str, float]
+
+    def __post_init__(self):
+        """Perform basic validation after initialization."""
+        # Flow fractions of downstream units should sum to 1
+        if self.downstream_flow_fracs:
+            if not 0.999 <= sum(self.downstream_flow_fracs.values()) <= 1.001:
+                raise ValueError(
+                    f"Downstream units for {self.name} do not sum to 1: "
+                    f"{self.downstream_flow_fracs}"
+                )
+
+        # Check that inflow and minflow timeseries are indexed correctly
+        if not self.inflow_ts.index.equals(self.minflow_ts.index):
+            raise ValueError(
+                f"Inflows and minflows for {self.name} are not indexed the same: "
+                f"{self.inflow_ts.index} vs {self.minflow_ts.index}"
+            )
+
+        # Indexing starts at 1
+        if self.inflow_ts.index[0] != 1:
+            raise ValueError(
+                f"Inflows for {self.name} do not start at 1: {self.inflow_ts.index[0]}"
+            )
+        if self.minflow_ts.index[0] != 1:
+            raise ValueError(
+                f"Minflows for {self.name} do not start at 1: {self.minflow_ts.index[0]}"
+            )
+
+        # Inflow must be greater than minflow for all days
+        if not all(self.inflow_ts >= self.minflow_ts):
+            raise ValueError(
+                f"Inflows for {self.name} are less than minflows on some days: "
+                f"{(self.inflow_ts < self.minflow_ts).sum()} days"
+            )

model_library/complex_river/minimum_flow.csv

@@ -1,5 +1,4 @@
-""" This is the reservoir module.
-"""
+"""This is the reservoir module."""
 
 from .reservoir import Reservoir
 from .basin import Basin
@@ -8,3 +7,4 @@
     solve_release_from_target_storage,
     solve_release_from_dispatch,
 )
+from .manager import ReservoirManager

model_library/complex_river/reservoir_unit.csv

@@ -1,26 +1,21 @@
-""" basin.py: Basin class
-"""
+"""basin.py: Basin class"""
 
 import os
 
 import pandas as pd
 
-from pownet.folder_utils import get_reservoir_file
 from .reservoir import Reservoir
 
 
 class Basin:
     def __init__(
         self,
-        model_name: str,
         basin_name: str,
         sim_horizon: int = 365,
     ) -> None:
         """
         A class to manage reservoirs in a basin.
         """
-
-        self.model_name: str = model_name
         self.basin_name: str = basin_name
         self.sim_horizon: int = sim_horizon