HBV-Lab 0.2.3__tar.gz → 1.1.0__tar.gz

{hbv_lab-0.2.3 → hbv_lab-1.1.0}/HBV_Lab/HBV_model.py

@@ -6,7 +6,7 @@ HBV-like hydrological model. It handles parameter management, data reading, mode
 execution, and output visualization.
 
 Usage:
-    from hbv_model import HBVModel
+    from HBV_Lab import HBVModel
     model = HBVModel()
     model.load_data("path/to/data.csv")
     model.set_parameters(params)
@@ -24,8 +24,6 @@ import datetime
 from types import MethodType
 from .uncertainty import uncertainty
 from .calibration import calibration
-## from calibration import calibrate_hbv_model
-##  from uncertainty import evaluate_uncertainty
 from .hbv_step import hbv_step
 from .routing import route_with_maxbas
 
@@ -71,7 +69,7 @@ class HBVModel(uncertainty, calibration):
             'lower_storage': 20.0     # Lower zone storage (mm)
         }
         
-        # Initialize time tracking
+        ## Initialize time tracking
         self.start_date = None
         self.end_date = None
         self.time_step = 'D'  # Default: daily
@@ -424,25 +422,42 @@ class HBVModel(uncertainty, calibration):
         sim_q_valid = sim_q[valid_idx]
         obs_q_valid = obs_q[valid_idx]
         
-        # Calculate Nash-Sutcliffe Efficiency (NSE)
+        # Calculate Nash-Sutcliffe Efficiency (NSE).
+        # NSE is undefined when the observations have zero variance (constant
+        # series); guard the division so we return NaN instead of raising a
+        # RuntimeWarning / producing +/-inf.
         mean_obs = np.mean(obs_q_valid)
         nse_numerator = np.sum((obs_q_valid - sim_q_valid) ** 2)
         nse_denominator = np.sum((obs_q_valid - mean_obs) ** 2)
-        nse = 1 - (nse_numerator / nse_denominator)
-        
-        # Calculate Kling-Gupta Efficiency (KGE)
+        nse = 1 - (nse_numerator / nse_denominator) if nse_denominator > 0 else np.nan
+
+        # Calculate Kling-Gupta Efficiency (KGE).
+        # This uses the modified KGE' (Kling et al., 2012) in which the
+        # variability ratio is based on the coefficient of variation
+        # (CV_sim / CV_obs) rather than the plain standard-deviation ratio.
         mean_sim = np.mean(sim_q_valid)
         std_obs = np.std(obs_q_valid)
         std_sim = np.std(sim_q_valid)
-        
-        r = np.corrcoef(obs_q_valid, sim_q_valid)[0, 1]  # Correlation coefficient
-        alpha = (std_sim/mean_sim) / (std_obs/mean_obs)  # Relative variability
-        beta = mean_sim / mean_obs  # Bias
-        
-        kge = 1 - np.sqrt((r - 1) ** 2 + (alpha - 1) ** 2 + (beta - 1) ** 2)
-        
-        # Calculate percent bias
-        pbias = 100 * (np.sum(sim_q_valid - obs_q_valid) / np.sum(obs_q_valid))
+
+        # Correlation is undefined if either series is constant.
+        if std_obs == 0 or std_sim == 0:
+            r = np.nan
+        else:
+            r = np.corrcoef(obs_q_valid, sim_q_valid)[0, 1]
+
+        if mean_obs == 0 or mean_sim == 0 or std_obs == 0:
+            # KGE components cannot be formed (division by zero); flag as NaN.
+            alpha = np.nan
+            beta = np.nan
+            kge = np.nan
+        else:
+            alpha = (std_sim / mean_sim) / (std_obs / mean_obs)  # variability ratio
+            beta = mean_sim / mean_obs                           # bias ratio
+            kge = 1 - np.sqrt((r - 1) ** 2 + (alpha - 1) ** 2 + (beta - 1) ** 2)
+
+        # Calculate percent bias (undefined if observations sum to zero).
+        sum_obs = np.sum(obs_q_valid)
+        pbias = 100 * (np.sum(sim_q_valid - obs_q_valid) / sum_obs) if sum_obs != 0 else np.nan
         
         # Calculate RMSE and MAE
         rmse = np.sqrt(np.mean((sim_q_valid - obs_q_valid) ** 2))
@@ -766,23 +781,27 @@ class HBVModel(uncertainty, calibration):
         
         return None
 
+    @staticmethod
     def load_model(model_path):
-
         """
         Load a saved HBV model from a file.
-        
+
+        Can be called either on the class or on an instance::
+
+            model = HBVModel.load_model("path/to/model")
+
         Parameters:
         -----------
         model_path : str
             Path to the saved model file.
-            
+
         Returns:
         --------
         HBVModel
             The loaded model instance.
         """
         import pickle
-        
+
         with open(model_path, 'rb') as f:
             model = pickle.load(f)
         

hbv_lab-1.1.0/HBV_Lab/__init__.py

@@ -0,0 +1,36 @@
+"""
+HBV_Lab — an intuitive, object-oriented Python implementation of a lumped
+conceptual HBV hydrological model for education and research.
+
+Typical usage::
+
+    from HBV_Lab import HBVModel
+    model = HBVModel()
+    model.load_data(data=df, ...)
+    model.run()
+    model.calibrate()
+    model.evaluate_uncertainty()
+
+The individual process routines are also importable for advanced use::
+
+    from HBV_Lab import snow_routine, soil_routine, response_routine_two_tanks
+    from HBV_Lab import hbv_step, route_with_maxbas
+"""
+
+from .HBV_model import HBVModel
+from .hbv_step import hbv_step
+from .snow import snow_routine
+from .soil import soil_routine
+from .response import response_routine_two_tanks
+from .routing import route_with_maxbas
+
+__version__ = "1.1.0"
+
+__all__ = [
+    "HBVModel",
+    "hbv_step",
+    "snow_routine",
+    "soil_routine",
+    "response_routine_two_tanks",
+    "route_with_maxbas",
+]

{hbv_lab-0.2.3 → hbv_lab-1.1.0}/HBV_Lab/calibration.py

@@ -1,17 +1,22 @@
 class calibration:
 
-    def calibrate(self, method='SLSQP', objective='NSE', iterations=100, 
+    def calibrate(self, method='Nelder-Mead', objective='NSE', iterations=100,
                             verbose=True, plot_results=True):
         """
         Calibrate an HBV model's parameters to optimize the objective function.
-        
+
         Parameters:
         -----------
         self : HBVmodel
             The HBV model instance to calibrate
-        method : str, default 'SLSQP'
+        method : str, default 'Nelder-Mead'
             Optimization method to use (see scipy.optimize.minimize).
-            Options include 'SLSQP', 'L-BFGS-B', 'Nelder-Mead', etc.
+            A gradient-free method is used by default because the HBV objective
+            surface is piecewise-constant (many min/max thresholds), which makes
+            finite-difference gradients ~0 and causes gradient-based methods such
+            as 'SLSQP' or 'L-BFGS-B' to terminate immediately without improving
+            on the starting values. Gradient-free options that respect the
+            parameter bounds include 'Nelder-Mead' and 'Powell'.
         objective : str, default 'NSE'
             Objective function to maximize. Options are:
             - 'NSE': Nash-Sutcliffe Efficiency (higher is better)
@@ -103,13 +108,13 @@ class calibration:
             self.params = param_dict
             
             
-            # Run the model
-            self.run(verbose)
-            
-            # Get simulated discharge and valid observed discharge
-            sim_q = self.results['discharge'][valid_idx]
-            obs_q_valid = obs_q[valid_idx]
-            self.calculate_performance_metrics
+            # Run the model (run() computes performance metrics internally when
+            # observed discharge is available, honouring the warmup period)
+            self.run(verbose=False)
+
+            # Ensure performance metrics reflect the current parameter set
+            self.calculate_performance_metrics(verbose=False)
+
             # Calculate objective function value
             if objective == 'NSE':
                 # Nash-Sutcliffe Efficiency (to be maximized)

{hbv_lab-0.2.3 → hbv_lab-1.1.0}/HBV_Lab/snow.py

@@ -13,8 +13,6 @@ def snow_routine(precipitation, temperature, snowpack, liquid_water, params):
             - CFR (float): Refreezing factor (-).
             - CWH (float): Water holding capacity of snowpack (-, e.g., 0.1).
             - SFCF (float): Snowfall correction factor (-).
-            - PCF (float): Precipitation correction factor——to account for bias in precipitation  (-).
-
 
     Returns:
         new_snowpack (float): Updated snowpack (mm).
@@ -27,11 +25,6 @@ def snow_routine(precipitation, temperature, snowpack, liquid_water, params):
     CFR = params['CFR']['default']
     CWH = params['CWH']['default']
     SFCF = params['SFCF']['default']
-    #PCF = params['PCF']['default']
-    
-    # Give the model a room to account for any biases in the estimation of precipitation
-
-    precipitation= precipitation 
 
     # Initialize snowfall and rainfall
     snowfall = 0.0

{hbv_lab-0.2.3 → hbv_lab-1.1.0}/HBV_Lab/soil.py

@@ -9,8 +9,7 @@ def soil_routine(runoff_from_snow, temperature, potential_et, soil_moisture, par
     Parameters:
     -----------
     runoff_from_snow : float
-        Incoming liquid wls
-        ater from snow routine (mm/day).
+        Incoming liquid water from the snow routine (mm/day).
     temperature : float
         Daily average temperature (°C). (Currently unused but kept for possible extensions).
     potential_et : float
@@ -27,12 +26,14 @@ def soil_routine(runoff_from_snow, temperature, potential_et, soil_moisture, par
     --------
     soil_moisture : float
         Updated soil moisture storage (mm).
+    out_to_response : float
+        Total water passed to the response routine (recharge + surface runoff) (mm/day).
     recharge : float
         Water recharging to the groundwater (mm/day).
-    actual_et : float
-        Actual evapotranspiration (mm/day).
     runoff : float
         Surface runoff due to soil overflow (mm/day).
+    actual_et : float
+        Actual evapotranspiration (mm/day).
     """
 
     FC = params['FC']     ['default']   # Maximum soil moisture capacity

{hbv_lab-0.2.3 → hbv_lab-1.1.0}/HBV_Lab.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: HBV_Lab
-Version: 0.2.3
+Version: 1.1.0
 Summary: An intuitive, object-oriented and user-friendly Python implementation of a lumped conceptual HBV hydrological model for educational and research purposes.
 Home-page: https://github.com/abdallaox/HBV_python_implementation
 Author: Abdalla Mohammed
@@ -20,6 +20,9 @@ Requires-Dist: pandas
 Requires-Dist: matplotlib
 Requires-Dist: scipy
 Requires-Dist: tqdm
+Requires-Dist: openpyxl
+Provides-Extra: playground
+Requires-Dist: bokeh>=2.4.0; extra == "playground"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -29,6 +32,7 @@ Dynamic: home-page
 Dynamic: keywords
 Dynamic: license
 Dynamic: license-file
+Dynamic: provides-extra
 Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
@@ -39,14 +43,29 @@ HBV is a simple conceptual hydrological model that simulates the main hydrologic
 
 I've been experimenting with the model lately and—in an endeavour to better understand the logic behind it—I decided to implement my own version—in Python, following an intuitive object-oriented programming approach.
 
-This versioin implements the snow, soil, response and routing routines—controled by 14 calibratable parameters as shown below. In addition to calibration and uncertainty analysis modules.
+This version implements the snow, soil, response and routing routines—controlled by 14 calibratable parameters as shown below—in addition to calibration and uncertainty analysis modules. See the [documentation for one step of the model.](https://lucid.app/publicSegments/view/a0edb3b6-8eba-4db5-9984-bfd23cc004ef/image.png)
+
+Conceptually the parameters belong to four routines:
+
 ```python
-parameters   = {
-                  'snow':        ['TT', 'CFMAX', 'SFCF', 'CFR', 'CWH'],
-                  'soil':        ['FC', 'LP', 'BETA'],
-                  'response':    ['K0', 'K1', 'K2', 'UZL', 'PERC']
-                  'routing' :    [ 'MAXBAS'],
-               }
+parameters = {
+    'snow':     ['TT', 'CFMAX', 'SFCF', 'CFR', 'CWH'],
+    'soil':     ['FC', 'LP', 'BETA'],
+    'response': ['K0', 'K1', 'K2', 'UZL', 'PERC'],
+    'routing':  ['MAXBAS'],
+}
+```
+
+In the model object the parameters are stored in three groups—`snow`, `soil`, and
+`response`—and the routing parameter `MAXBAS` lives inside the `response` group.
+Each parameter is a dict with `min` / `max` / `default` values, so a custom update
+passed to `set_parameters` looks like:
+
+```python
+model.set_parameters({
+    'soil':     {'FC': {'min': 50, 'max': 500, 'default': 250}},
+    'response': {'MAXBAS': {'default': 4}},
+})
 ```
 
 
@@ -55,29 +74,56 @@ This can be flexibly used for different modelling tasks, but can also be used in
 ## Get Started
 
 ### Install the Package
-```python 
-pip install HBV_Lab       or
-! pip install HBV_Lab
+From PyPI:
+```bash
+pip install HBV_Lab
+```
+Or, inside a notebook:
+```python
+!pip install HBV_Lab
+```
+To work from the source / latest version:
+```bash
+git clone https://github.com/abdallaox/HBV_python_implementation.git
+cd HBV_python_implementation
+pip install -e .
 ```
+
 ### How to Use
 It is very intuitive—you create a model like an object which has attributes (data, parameters, initial conditions, etc.) that you can assign and access. The object also performs functions (calibration, uncertainty estimation, save, load, etc.)
 ```python
+import pandas as pd
 from HBV_Lab import HBVModel
+
+# 1. Load forcing data (a DataFrame with date, precipitation, temperature,
+#    potential ET and—optionally—observed discharge columns)
+df = pd.read_excel("data/test_data_2.xlsx")
 model = HBVModel()
-model.load_data("pandas dataframe")
-model.set_parameters(params)
+model.load_data(
+    data=df,
+    date_column="Date", precip_column="P", temp_column="T",
+    pet_column="PET", obs_q_column="Q",
+    date_format="%Y%m%d", warmup_end="19811231",
+)
+
+# 2. (Optional) override default parameter ranges/values
+# model.set_parameters({'soil': {'FC': {'default': 250}}})
+
+# 3. Run, calibrate and analyse
 model.run()
-model.calibrate()
-model.evaluate_uncertainity()
+model.calibrate()              # gradient-free optimisation by default
+model.evaluate_uncertainty()   # Monte-Carlo uncertainty analysis
 model.plot_results()
-model.save_results()
-model.save_model("path")
-model.load_model("path")
+
+# 4. Persist results and the model itself
+model.save_results("results/run.csv")
+model.save_model("models/my_model")
+model = HBVModel.load_model("models/my_model")
 ```
 ### Tutorial
 Start by following a simple case study in the notebook:  [**quick_start_guide.ipynb**](https://github.com/abdallaox/HBV_python_implementation/blob/main/quick_start_guide.ipynb)
 ### Play with HBV 
-Get a feeling of how the model works and the role of the different parameters in [**HBVLAB**](https://hbv-playground.onrender.com/HBV_playground)—a playground that uses a model developed with this implementation.
+Get a feeling of how the model works and the role of the different parameters in [**HBVLAB**](https://hbvpythonimplementation-production.up.railway.app/HBV_playground)—a playground that uses a model developed with this implementation.
 ### References
 
 **[1]** Bergström, S., & Forsman, A. (1973). Development of a conceptual deterministic rainfall-runoff model. *Hydrology Research*, *4*, 147-170.

{hbv_lab-0.2.3 → hbv_lab-1.1.0}/HBV_Lab.egg-info/SOURCES.txt

@@ -14,4 +14,9 @@ HBV_Lab.egg-info/PKG-INFO
 HBV_Lab.egg-info/SOURCES.txt
 HBV_Lab.egg-info/dependency_links.txt
 HBV_Lab.egg-info/requires.txt
-HBV_Lab.egg-info/top_level.txt
+HBV_Lab.egg-info/top_level.txt
+tests/test_hbv_model.py
+tests/test_hbv_step.py
+tests/test_response.py
+tests/test_snow.py
+tests/test_soil.py

hbv_lab-1.1.0/HBV_Lab.egg-info/requires.txt

@@ -0,0 +1,9 @@
+numpy
+pandas
+matplotlib
+scipy
+tqdm
+openpyxl
+
+[playground]
+bokeh>=2.4.0

{hbv_lab-0.2.3 → hbv_lab-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: HBV_Lab
-Version: 0.2.3
+Version: 1.1.0
 Summary: An intuitive, object-oriented and user-friendly Python implementation of a lumped conceptual HBV hydrological model for educational and research purposes.
 Home-page: https://github.com/abdallaox/HBV_python_implementation
 Author: Abdalla Mohammed
@@ -20,6 +20,9 @@ Requires-Dist: pandas
 Requires-Dist: matplotlib
 Requires-Dist: scipy
 Requires-Dist: tqdm
+Requires-Dist: openpyxl
+Provides-Extra: playground
+Requires-Dist: bokeh>=2.4.0; extra == "playground"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -29,6 +32,7 @@ Dynamic: home-page
 Dynamic: keywords
 Dynamic: license
 Dynamic: license-file
+Dynamic: provides-extra
 Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
@@ -39,14 +43,29 @@ HBV is a simple conceptual hydrological model that simulates the main hydrologic
 
 I've been experimenting with the model lately and—in an endeavour to better understand the logic behind it—I decided to implement my own version—in Python, following an intuitive object-oriented programming approach.
 
-This versioin implements the snow, soil, response and routing routines—controled by 14 calibratable parameters as shown below. In addition to calibration and uncertainty analysis modules.
+This version implements the snow, soil, response and routing routines—controlled by 14 calibratable parameters as shown below—in addition to calibration and uncertainty analysis modules. See the [documentation for one step of the model.](https://lucid.app/publicSegments/view/a0edb3b6-8eba-4db5-9984-bfd23cc004ef/image.png)
+
+Conceptually the parameters belong to four routines:
+
 ```python
-parameters   = {
-                  'snow':        ['TT', 'CFMAX', 'SFCF', 'CFR', 'CWH'],
-                  'soil':        ['FC', 'LP', 'BETA'],
-                  'response':    ['K0', 'K1', 'K2', 'UZL', 'PERC']
-                  'routing' :    [ 'MAXBAS'],
-               }
+parameters = {
+    'snow':     ['TT', 'CFMAX', 'SFCF', 'CFR', 'CWH'],
+    'soil':     ['FC', 'LP', 'BETA'],
+    'response': ['K0', 'K1', 'K2', 'UZL', 'PERC'],
+    'routing':  ['MAXBAS'],
+}
+```
+
+In the model object the parameters are stored in three groups—`snow`, `soil`, and
+`response`—and the routing parameter `MAXBAS` lives inside the `response` group.
+Each parameter is a dict with `min` / `max` / `default` values, so a custom update
+passed to `set_parameters` looks like:
+
+```python
+model.set_parameters({
+    'soil':     {'FC': {'min': 50, 'max': 500, 'default': 250}},
+    'response': {'MAXBAS': {'default': 4}},
+})
 ```
 
 
@@ -55,29 +74,56 @@ This can be flexibly used for different modelling tasks, but can also be used in
 ## Get Started
 
 ### Install the Package
-```python 
-pip install HBV_Lab       or
-! pip install HBV_Lab
+From PyPI:
+```bash
+pip install HBV_Lab
+```
+Or, inside a notebook:
+```python
+!pip install HBV_Lab
+```
+To work from the source / latest version:
+```bash
+git clone https://github.com/abdallaox/HBV_python_implementation.git
+cd HBV_python_implementation
+pip install -e .
 ```
+
 ### How to Use
 It is very intuitive—you create a model like an object which has attributes (data, parameters, initial conditions, etc.) that you can assign and access. The object also performs functions (calibration, uncertainty estimation, save, load, etc.)
 ```python
+import pandas as pd
 from HBV_Lab import HBVModel
+
+# 1. Load forcing data (a DataFrame with date, precipitation, temperature,
+#    potential ET and—optionally—observed discharge columns)
+df = pd.read_excel("data/test_data_2.xlsx")
 model = HBVModel()
-model.load_data("pandas dataframe")
-model.set_parameters(params)
+model.load_data(
+    data=df,
+    date_column="Date", precip_column="P", temp_column="T",
+    pet_column="PET", obs_q_column="Q",
+    date_format="%Y%m%d", warmup_end="19811231",
+)
+
+# 2. (Optional) override default parameter ranges/values
+# model.set_parameters({'soil': {'FC': {'default': 250}}})
+
+# 3. Run, calibrate and analyse
 model.run()
-model.calibrate()
-model.evaluate_uncertainity()
+model.calibrate()              # gradient-free optimisation by default
+model.evaluate_uncertainty()   # Monte-Carlo uncertainty analysis
 model.plot_results()
-model.save_results()
-model.save_model("path")
-model.load_model("path")
+
+# 4. Persist results and the model itself
+model.save_results("results/run.csv")
+model.save_model("models/my_model")
+model = HBVModel.load_model("models/my_model")
 ```
 ### Tutorial
 Start by following a simple case study in the notebook:  [**quick_start_guide.ipynb**](https://github.com/abdallaox/HBV_python_implementation/blob/main/quick_start_guide.ipynb)
 ### Play with HBV 
-Get a feeling of how the model works and the role of the different parameters in [**HBVLAB**](https://hbv-playground.onrender.com/HBV_playground)—a playground that uses a model developed with this implementation.
+Get a feeling of how the model works and the role of the different parameters in [**HBVLAB**](https://hbvpythonimplementation-production.up.railway.app/HBV_playground)—a playground that uses a model developed with this implementation.
 ### References
 
 **[1]** Bergström, S., & Forsman, A. (1973). Development of a conceptual deterministic rainfall-runoff model. *Hydrology Research*, *4*, 147-170.

hbv_lab-1.1.0/README.md

@@ -0,0 +1,95 @@
+# HBV_Lab (Python implementation of a lumped conceptual HBV model)
+
+HBV is a simple conceptual hydrological model that simulates the main hydrological processes related to snow, soil, groundwater, and routing [[1]](https://iwaponline.com/hr/article/4/3/147/1357/DEVELOPMENT-OF-A-CONCEPTUAL-DETERMINISTIC-RAINFALL). There are many software packages and off-the-shelf products that implement different versions of it [[2]](https://www.geo.uzh.ch/en/units/h2k/Services/HBV-Model.html) [[3]](https://hess.copernicus.org/articles/17/445/2013/).
+
+I've been experimenting with the model lately and—in an endeavour to better understand the logic behind it—I decided to implement my own version—in Python, following an intuitive object-oriented programming approach.
+
+This version implements the snow, soil, response and routing routines—controlled by 14 calibratable parameters as shown below—in addition to calibration and uncertainty analysis modules. See the [documentation for one step of the model.](https://lucid.app/publicSegments/view/a0edb3b6-8eba-4db5-9984-bfd23cc004ef/image.png)
+
+Conceptually the parameters belong to four routines:
+
+```python
+parameters = {
+    'snow':     ['TT', 'CFMAX', 'SFCF', 'CFR', 'CWH'],
+    'soil':     ['FC', 'LP', 'BETA'],
+    'response': ['K0', 'K1', 'K2', 'UZL', 'PERC'],
+    'routing':  ['MAXBAS'],
+}
+```
+
+In the model object the parameters are stored in three groups—`snow`, `soil`, and
+`response`—and the routing parameter `MAXBAS` lives inside the `response` group.
+Each parameter is a dict with `min` / `max` / `default` values, so a custom update
+passed to `set_parameters` looks like:
+
+```python
+model.set_parameters({
+    'soil':     {'FC': {'min': 50, 'max': 500, 'default': 250}},
+    'response': {'MAXBAS': {'default': 4}},
+})
+```
+
+
+This can be flexibly used for different modelling tasks, but can also be used in a classroom setup—to explain hydrological concepts (processes, calibration, uncertainty analysis, etc.).
+
+## Get Started
+
+### Install the Package
+From PyPI:
+```bash
+pip install HBV_Lab
+```
+Or, inside a notebook:
+```python
+!pip install HBV_Lab
+```
+To work from the source / latest version:
+```bash
+git clone https://github.com/abdallaox/HBV_python_implementation.git
+cd HBV_python_implementation
+pip install -e .
+```
+
+### How to Use
+It is very intuitive—you create a model like an object which has attributes (data, parameters, initial conditions, etc.) that you can assign and access. The object also performs functions (calibration, uncertainty estimation, save, load, etc.)
+```python
+import pandas as pd
+from HBV_Lab import HBVModel
+
+# 1. Load forcing data (a DataFrame with date, precipitation, temperature,
+#    potential ET and—optionally—observed discharge columns)
+df = pd.read_excel("data/test_data_2.xlsx")
+model = HBVModel()
+model.load_data(
+    data=df,
+    date_column="Date", precip_column="P", temp_column="T",
+    pet_column="PET", obs_q_column="Q",
+    date_format="%Y%m%d", warmup_end="19811231",
+)
+
+# 2. (Optional) override default parameter ranges/values
+# model.set_parameters({'soil': {'FC': {'default': 250}}})
+
+# 3. Run, calibrate and analyse
+model.run()
+model.calibrate()              # gradient-free optimisation by default
+model.evaluate_uncertainty()   # Monte-Carlo uncertainty analysis
+model.plot_results()
+
+# 4. Persist results and the model itself
+model.save_results("results/run.csv")
+model.save_model("models/my_model")
+model = HBVModel.load_model("models/my_model")
+```
+### Tutorial
+Start by following a simple case study in the notebook:  [**quick_start_guide.ipynb**](https://github.com/abdallaox/HBV_python_implementation/blob/main/quick_start_guide.ipynb)
+### Play with HBV 
+Get a feeling of how the model works and the role of the different parameters in [**HBVLAB**](https://hbvpythonimplementation-production.up.railway.app/HBV_playground)—a playground that uses a model developed with this implementation.
+### References
+
+**[1]** Bergström, S., & Forsman, A. (1973). Development of a conceptual deterministic rainfall-runoff model. *Hydrology Research*, *4*, 147-170.
+
+**[2]** Seibert, J., & Vis, M. J. P. (2012). Teaching hydrological modeling with a user-friendly catchment-runoff-model software package. *Hydrology and Earth System Sciences*, *16*(9), 3315-3325. [doi:10.5194/hess-16-3315-2012](https://doi.org/10.5194/hess-16-3315-2012)
+
+**[3]** AghaKouchak, A., Nakhjiri, N., & Habib, E. (2013). An educational model for ensemble streamflow simulation and uncertainty analysis. *Hydrology and Earth System Sciences*, *17*(2), 445-452. [doi:10.5194/hess-17-445-2013](https://doi.org/10.5194/hess-17-445-2013)
+

{hbv_lab-0.2.3 → hbv_lab-1.1.0}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as f:
 
 setup(
     name='HBV_Lab',
-    version='0.2.3',
+    version='1.1.0',
     packages=find_packages(include=['HBV_Lab', 'HBV_Lab.*']),
     install_requires=[
         'numpy',
@@ -13,7 +13,12 @@ setup(
         'matplotlib',
         'scipy',
         'tqdm',
+        'openpyxl',  # required by pandas to read the .xlsx example data
     ],
+    extras_require={
+        # Optional dependencies for the interactive Bokeh playground
+        'playground': ['bokeh>=2.4.0'],
+    },
     author='Abdalla Mohammed',
     author_email='abdalla.mohammed.ox@gmail.com',
     description='An intuitive, object-oriented and user-friendly Python implementation of a lumped conceptual HBV hydrological model for educational and research purposes.',

hbv_lab-1.1.0/tests/test_hbv_model.py

@@ -0,0 +1,75 @@
+import pandas as pd
+import numpy as np
+import os
+import tempfile
+import pytest
+from HBV_Lab import HBVModel
+
+
+def make_sample_df(n_days=10):
+    dates = pd.date_range(start='2000-01-01', periods=n_days, freq='D')
+    df = pd.DataFrame({
+        'Date': dates.strftime('%Y%m%d'),
+        'Precipitation': np.ones(n_days) * 1.0,
+        'Temperature': np.ones(n_days) * 2.0,
+        'PotentialET': np.ones(n_days) * 0.5,
+        'ObservedQ': np.ones(n_days) * 0.2
+    })
+    return df
+
+
+def test_load_data_and_time_step_and_pet_expansion():
+    model = HBVModel()
+    df = make_sample_df(n_days=20)
+
+    model.load_data(data=df, date_column='Date', date_format='%Y%m%d', precip_column='Precipitation', temp_column='Temperature', pet_column='PotentialET', obs_q_column='ObservedQ')
+
+    assert model.data is not None
+    assert model.start_date is not None
+    assert model.time_step == 'D'
+
+
+def test_set_parameters_validation():
+    model = HBVModel()
+    with pytest.raises(ValueError):
+        model.set_parameters(None)
+
+    # valid update
+    custom = {'soil': {'FC': {'default': 200.0}}}
+    model.set_parameters(custom)
+    assert model.params['soil']['FC']['default'] == 200.0
+
+
+def test_set_initial_conditions_and_run(tmp_path):
+    model = HBVModel()
+    df = make_sample_df(n_days=15)
+    model.load_data(data=df, date_column='Date', date_format='%Y%m%d', precip_column='Precipitation', temp_column='Temperature', pet_column='PotentialET', obs_q_column='ObservedQ')
+
+    model.set_initial_conditions(snowpack=5.0, soil_moisture=40.0)
+    results = model.run(verbose=False)
+
+    assert results['discharge'].shape[0] == 15
+    assert np.all(results['discharge'] >= 0.0)
+
+    # Test save_results
+    out_file = tmp_path / "results_test.csv"
+    model.results = results
+    model.save_results(str(out_file))
+    assert os.path.exists(out_file)
+
+
+def test_performance_metrics_calculation():
+    model = HBVModel()
+    df = make_sample_df(n_days=12)
+    model.load_data(data=df, date_column='Date', date_format='%Y%m%d', precip_column='Precipitation', temp_column='Temperature', pet_column='PotentialET', obs_q_column='ObservedQ')
+
+    model.set_initial_conditions()
+    results = model.run(verbose=False)
+    # attach observed into results
+    results['observed_q'] = np.ones(len(results['discharge'])) * 0.2
+    model.results = results
+
+    model.calculate_performance_metrics(verbose=False)
+    assert hasattr(model, 'performance_metrics')
+    keys = {'NSE','KGE','PBIAS','RMSE','MAE'}
+    assert keys.issubset(set(model.performance_metrics.keys()))

hbv_lab-1.1.0/tests/test_hbv_step.py

@@ -0,0 +1,18 @@
+from HBV_Lab import hbv_step
+
+
+def test_hbv_step_returns_expected_keys():
+    params = {
+        'snow': {'TT': {'default': 0.0}, 'CFMAX': {'default': 2.0}, 'CFR': {'default': 0.0}, 'CWH': {'default': 0.1}, 'SFCF': {'default': 1.0}},
+        'soil': {'FC': {'default': 100.0}, 'BETA': {'default': 2.0}, 'LP': {'default': 0.5}},
+        'response': {'K0': {'default': 0.5}, 'K1': {'default': 0.2}, 'K2': {'default': 0.01}, 'UZL': {'default': 20.0}, 'PERC': {'default': 1.0}}
+    }
+
+    initial_conditions = {'snowpack': 0.0, 'liquid_water': 0.0, 'soil_moisture': 50.0, 'upper_storage': 10.0, 'lower_storage': 20.0}
+
+    new_states, fluxes = hbv_step(precipitation=5.0, temperature=5.0, potential_et=2.0, params=params, initial_conditions=initial_conditions)
+
+    # new_states contains required keys
+    assert set(new_states.keys()) == {'snowpack','liquid_water','soil_moisture','upper_storage','lower_storage'}
+    # fluxes contain discharge and flow components
+    assert 'discharge' in fluxes and 'quick_flow' in fluxes and 'baseflow' in fluxes

hbv_lab-1.1.0/tests/test_response.py

@@ -0,0 +1,23 @@
+from HBV_Lab import response_routine_two_tanks
+
+
+def test_response_basic_mass_balance():
+    params = {'K0': {'default': 0.5}, 'K1': {'default': 0.2}, 'K2': {'default': 0.01}, 'UZL': {'default': 20.0}, 'PERC': {'default': 1.0}}
+
+    upper, lower, discharge, q0, q1, q2 = response_routine_two_tanks(out_to_response=5.0, upper_storage=10.0, lower_storage=20.0, params=params)
+
+    # discharge is sum of flow components
+    assert discharge == q0 + q1 + q2
+    assert upper >= 0.0
+    assert lower >= 0.0
+
+
+def test_response_percolation_and_threshold():
+    params = {'K0': {'default': 0.5}, 'K1': {'default': 0.2}, 'K2': {'default': 0.01}, 'UZL': {'default': 0.0}, 'PERC': {'default': 100.0}}
+
+    # Large PERC means most incoming water should percolate to lower zone
+    upper, lower, discharge, q0, q1, q2 = response_routine_two_tanks(out_to_response=3.0, upper_storage=1.0, lower_storage=0.0, params=params)
+
+    # Ensure percolation did not make storages negative and produced baseflow
+    assert lower >= 0.0
+    assert q2 >= 0.0

hbv_lab-1.1.0/tests/test_snow.py

@@ -0,0 +1,38 @@
+from HBV_Lab import snow_routine
+
+
+def test_snow_accumulates_and_runs_off():
+    params = {
+        'TT': {'default': 0.0},
+        'CFMAX': {'default': 2.0},
+        'CFR': {'default': 0.0},
+        'CWH': {'default': 0.1},
+        'SFCF': {'default': 1.0}
+    }
+
+    # Cold day: precipitation becomes snowfall and increases snowpack
+    snowpack, liquid, runoff = snow_routine(precipitation=10.0, temperature=-5.0,
+                                            snowpack=0.0, liquid_water=0.0, params=params)
+
+    assert snowpack > 0.0
+    assert liquid >= 0.0
+    assert runoff == 0.0  # no holding capacity exceeded immediately
+
+
+def test_snow_melts_when_warm():
+    params = {
+        'TT': {'default': 0.0},
+        'CFMAX': {'default': 5.0},
+        'CFR': {'default': 0.0},
+        'CWH': {'default': 0.2},
+        'SFCF': {'default': 1.0}
+    }
+
+    # Warm day with existing snowpack should generate melt and liquid water
+    snowpack, liquid, runoff = snow_routine(precipitation=0.0, temperature=5.0,
+                                            snowpack=20.0, liquid_water=0.0, params=params)
+
+    assert snowpack < 20.0
+    assert liquid >= 0.0
+    # since holding capacity = CWH * snowpack after melt, liquid might be <= holding capacity
+    assert runoff >= 0.0

hbv_lab-1.1.0/tests/test_soil.py

@@ -0,0 +1,28 @@
+import pytest
+from HBV_Lab import soil_routine
+
+
+def test_soil_et_and_recharge():
+    params = {'FC': {'default': 100.0}, 'BETA': {'default': 2.0}, 'LP': {'default': 0.5}}
+
+    # With moderate soil moisture and incoming runoff, we expect some recharge and ET
+    soil_moisture, out_to_response, recharge, runoff, actual_et = soil_routine(
+        runoff_from_snow=10.0, temperature=5.0, potential_et=2.0, soil_moisture=50.0, params=params
+    )
+
+    assert soil_moisture >= 0.0
+    assert actual_et <= 2.0
+    assert recharge >= 0.0
+    assert out_to_response == pytest.approx(recharge + runoff)
+
+
+def test_soil_overflow_produces_runoff():
+    params = {'FC': {'default': 20.0}, 'BETA': {'default': 1.0}, 'LP': {'default': 0.5}}
+
+    # Large incoming water should cause soil to exceed FC and produce runoff
+    soil_moisture, out_to_response, recharge, runoff, actual_et = soil_routine(
+        runoff_from_snow=100.0, temperature=5.0, potential_et=0.0, soil_moisture=10.0, params=params
+    )
+
+    assert runoff > 0.0
+    assert soil_moisture <= params['FC']['default']

hbv_lab-0.2.3/HBV_Lab/__init__.py

@@ -1,5 +0,0 @@
-from .HBV_model import HBVModel
-from .uncertainty import uncertainty
-from .calibration import calibration
-from .hbv_step import hbv_step
-from .routing import route_with_maxbas

hbv_lab-0.2.3/HBV_Lab.egg-info/requires.txt

@@ -1,5 +0,0 @@
-numpy
-pandas
-matplotlib
-scipy
-tqdm

hbv_lab-0.2.3/README.md

@@ -1,53 +0,0 @@
-# HBV_Lab (Python implementation of a lumped conceptual HBV model)
-
-HBV is a simple conceptual hydrological model that simulates the main hydrological processes related to snow, soil, groundwater, and routing [[1]](https://iwaponline.com/hr/article/4/3/147/1357/DEVELOPMENT-OF-A-CONCEPTUAL-DETERMINISTIC-RAINFALL). There are many software packages and off-the-shelf products that implement different versions of it [[2]](https://www.geo.uzh.ch/en/units/h2k/Services/HBV-Model.html) [[3]](https://hess.copernicus.org/articles/17/445/2013/).
-
-I've been experimenting with the model lately and—in an endeavour to better understand the logic behind it—I decided to implement my own version—in Python, following an intuitive object-oriented programming approach.
-
-This versioin implements the snow, soil, response and routing routines—controled by 14 calibratable parameters as shown below. In addition to calibration and uncertainty analysis modules.
-```python
-parameters   = {
-                  'snow':        ['TT', 'CFMAX', 'SFCF', 'CFR', 'CWH'],
-                  'soil':        ['FC', 'LP', 'BETA'],
-                  'response':    ['K0', 'K1', 'K2', 'UZL', 'PERC']
-                  'routing' :    [ 'MAXBAS'],
-               }
-```
-
-
-This can be flexibly used for different modelling tasks, but can also be used in a classroom setup—to explain hydrological concepts (processes, calibration, uncertainty analysis, etc.).
-
-## Get Started
-
-### Install the Package
-```python 
-pip install HBV_Lab       or
-! pip install HBV_Lab
-```
-### How to Use
-It is very intuitive—you create a model like an object which has attributes (data, parameters, initial conditions, etc.) that you can assign and access. The object also performs functions (calibration, uncertainty estimation, save, load, etc.)
-```python
-from HBV_Lab import HBVModel
-model = HBVModel()
-model.load_data("pandas dataframe")
-model.set_parameters(params)
-model.run()
-model.calibrate()
-model.evaluate_uncertainity()
-model.plot_results()
-model.save_results()
-model.save_model("path")
-model.load_model("path")
-```
-### Tutorial
-Start by following a simple case study in the notebook:  [**quick_start_guide.ipynb**](https://github.com/abdallaox/HBV_python_implementation/blob/main/quick_start_guide.ipynb)
-### Play with HBV 
-Get a feeling of how the model works and the role of the different parameters in [**HBVLAB**](https://hbv-playground.onrender.com/HBV_playground)—a playground that uses a model developed with this implementation.
-### References
-
-**[1]** Bergström, S., & Forsman, A. (1973). Development of a conceptual deterministic rainfall-runoff model. *Hydrology Research*, *4*, 147-170.
-
-**[2]** Seibert, J., & Vis, M. J. P. (2012). Teaching hydrological modeling with a user-friendly catchment-runoff-model software package. *Hydrology and Earth System Sciences*, *16*(9), 3315-3325. [doi:10.5194/hess-16-3315-2012](https://doi.org/10.5194/hess-16-3315-2012)
-
-**[3]** AghaKouchak, A., Nakhjiri, N., & Habib, E. (2013). An educational model for ensemble streamflow simulation and uncertainty analysis. *Hydrology and Earth System Sciences*, *17*(2), 445-452. [doi:10.5194/hess-17-445-2013](https://doi.org/10.5194/hess-17-445-2013)
-