HBV-Lab 0.1.0__py3-none-any.whl

HBV_Lab/__init__.py

@@ -0,0 +1 @@
+from .HBV_model import HBVModel

HBV_Lab/calibration.py

@@ -0,0 +1,243 @@
+class calibration:
+
+    def calibrate(self, method='SLSQP', 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'
+            Optimization method to use (see scipy.optimize.minimize).
+            Options include 'SLSQP', 'L-BFGS-B', 'Nelder-Mead', etc.
+        objective : str, default 'NSE'
+            Objective function to maximize. Options are:
+            - 'NSE': Nash-Sutcliffe Efficiency (higher is better)
+            - 'KGE': Kling-Gupta Efficiency (higher is better)
+            - 'RMSE': Root Mean Square Error (lower is better)
+            - 'MAE': Mean Absolute Error (lower is better)
+        iterations : int, default 100
+            Maximum number of iterations for the optimizer
+        verbose : bool, default True
+            Whether to print progress information
+        plot_results : bool, default True
+            Whether to plot the final results after calibration
+            
+        Returns:
+        --------
+        dict
+            Dictionary containing optimized parameters and performance metrics
+        """
+        import scipy.optimize as opt
+        import numpy as np
+        import time
+        import copy
+        
+        if self.data is None:
+            raise ValueError("No data loaded. Use load_data() method first.")
+            
+        # Check if observed discharge data is available
+        if (self.column_names['obs_q'] is None or 
+            self.column_names['obs_q'] not in self.data.columns):
+            raise ValueError("Observed discharge data is required for calibration.")
+        # Store the initial states to use it later for reseting the model 
+        initial_states = self.states
+        # Extract observed discharge data
+        obs_q = self.data[self.column_names['obs_q']].values
+        
+        # Get valid indices (where obs_q is not NaN)
+        valid_idx = ~np.isnan(obs_q)
+        if np.sum(valid_idx) == 0:
+            raise ValueError("No valid observed discharge values found.")
+        
+        # Initial parameter values (using default values)
+        initial_params = []
+        param_names = []
+        param_bounds = []
+        param_groups = []
+        
+        # Create flat parameter list for optimization
+        for group_name, group in self.params.items():
+            for param_name, param_info in group.items():
+                initial_params.append(param_info['default'])
+                param_names.append(f"{group_name}_{param_name}")
+                param_bounds.append((param_info['min'], param_info['max']))
+                param_groups.append(group_name)
+        
+        # Helper function to convert flat parameter array to nested dictionary
+        def create_param_dict(flat_params):
+            # Create a deep copy of current parameters structure
+            param_dict = {group: {} for group in set(param_groups)}
+            
+            # Fill in the parameter values
+            for i, (name, group) in enumerate(zip(param_names, param_groups)):
+                param_name = name.split('_', 1)[1]  # Extract parameter name
+                
+                # Initialize if not exists
+                if param_name not in param_dict[group]:
+                    param_dict[group][param_name] = {}
+                
+                # Copy min/max from original params
+                orig_group = self.params[group]
+                param_dict[group][param_name]['min'] = orig_group[param_name]['min']
+                param_dict[group][param_name]['max'] = orig_group[param_name]['max']
+                
+                # Set the default to the optimized value
+                param_dict[group][param_name]['default'] = flat_params[i]
+            
+            return param_dict
+        
+        
+        
+        # Define the objective function to minimize
+        def objective_function(params):
+            # Update parameters structure with flat parameter array
+            param_dict = create_param_dict(params)
+            
+            # Store original parameters to restore later
+            original_params = copy.deepcopy(self.params)
+            
+            # Update model parameters
+            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
+            # Calculate objective function value
+            if objective == 'NSE':
+                # Nash-Sutcliffe Efficiency (to be maximized)
+                # mean_obs = np.mean(obs_q_valid)
+                # nse_numerator = np.sum((obs_q_valid - sim_q) ** 2)
+                # nse_denominator = np.sum((obs_q_valid - mean_obs) ** 2)
+                # value = 1 - (nse_numerator / nse_denominator)
+                # # For minimization, return negative NSE
+                
+                return - self.performance_metrics['NSE']
+                
+            elif objective == 'KGE':
+                # # Kling-Gupta Efficiency (to be maximized)
+                # mean_sim = np.mean(sim_q)
+                # mean_obs = np.mean(obs_q_valid)
+                # std_sim = np.std(sim_q)
+                # std_obs = np.std(obs_q_valid)
+                
+                # r = np.corrcoef(obs_q_valid, sim_q)[0, 1]  # Correlation
+                # alpha = (std_sim/mean_sim) / (std_obs/mean_sim)  # Relative variability
+                # beta = mean_sim / mean_obs  # Bias
+                
+                # kge = 1 - np.sqrt((r - 1) ** 2 + (alpha - 1) ** 2 + (beta - 1) ** 2)
+                # For minimization, return negative KGE
+                return - self.performance_metrics['KGE']
+                
+            elif objective == 'RMSE':
+                # Root Mean Square Error (to be minimized)
+                # rmse = np.sqrt(np.mean((obs_q_valid - sim_q) ** 2))
+                return self.performance_metrics['RMSE']
+                
+            elif objective == 'MAE':
+                # Mean Absolute Error (to be minimized)
+                # mae = np.mean(np.abs(obs_q_valid - sim_q))
+                return self.performance_metrics['MAE']
+            
+            else:
+                raise ValueError(f"Unknown objective function: {objective}")
+        
+        # Callback function to track progress
+        num_iter = [0]
+        best_value = [float('inf') if objective in ['RMSE', 'MAE'] else float('-inf')]
+        start_time = time.time()
+        
+        def callback(params):
+            num_iter[0] += 1
+            current_value = objective_function(params)
+            
+            # For NSE and KGE, we're minimizing the negative value
+            if objective in ['NSE', 'KGE']:
+                display_value = -current_value
+                is_better = current_value < best_value[0]
+            else:
+                display_value = current_value
+                is_better = current_value < best_value[0]
+            
+            if is_better:
+                best_value[0] = current_value
+            
+            if verbose and num_iter[0] % max(1, iterations // 10) == 0:
+                elapsed = time.time() - start_time
+                print(f"Iteration {num_iter[0]}/{iterations}, "
+                    f"{objective}: {display_value:.4f}, "
+                    f"Time: {elapsed:.1f}s")
+        
+        if verbose:
+            print(f"Starting calibration using {method} method...")
+            print(f"Optimizing {objective} with {len(param_names)} parameters and {iterations} iterations")
+        
+        # Store original parameters to restore if needed
+        original_params = copy.deepcopy(self.params)
+        
+        try:
+            # Run optimization
+            result = opt.minimize(
+                objective_function,
+                initial_params,
+                method=method,
+                bounds=param_bounds,
+                callback=callback,
+                options={'maxiter': iterations}
+            )
+            
+            # Get optimized parameters
+            opt_params = result.x
+            
+            # Create parameter dictionary from optimized values
+            optimized_params = create_param_dict(opt_params)
+            
+            # Update model with optimized parameters
+            self.params = optimized_params
+            
+            # Run the model with optimized parameters
+            
+            self.run(verbose)
+            
+            # Calculate final performance metrics
+            self.calculate_performance_metrics(verbose)
+            
+            # Display results
+            if verbose:
+                print("\nCalibration completed!")
+                print(f"Final {objective}: {-result.fun if objective in ['NSE', 'KGE'] else result.fun:.4f}")
+                print(f"Success: {result.success}, Message: {result.message}")
+                print("\nOptimized Parameters:")
+                
+                for group_name, group in optimized_params.items():
+                    print(f"\n{group_name.upper()} parameters:")
+                    for param_name, param_info in group.items():
+                        print(f"  {param_name}: {param_info['default']:.4f} (range: {param_info['min']}-{param_info['max']})")
+                
+                print("\nPerformance Metrics:")
+                for metric, value in self.performance_metrics.items():
+                    print(f"  {metric}: {value:.4f}")
+            
+            # Plot results if requested
+            if plot_results:
+                self.plot_results(show_plots=True)
+            
+            # Return optimized parameters and performance
+            return {
+                'parameters': optimized_params,
+                'performance': self.performance_metrics,
+                'optimization_result': result
+            }
+            
+        except Exception as e:
+            # Restore original parameters on error
+            self.params = original_params
+            print(f"Calibration failed with error: {str(e)}")
+            raise

HBV_Lab/hbv_step.py

@@ -0,0 +1,74 @@
+from snow import snow_routine
+from soil import soil_routine
+from response import response_routine_two_tanks
+
+def hbv_step(precipitation, temperature, potential_et, params, initial_conditions):
+    """
+    HBV-light hydrological model (single timestep version).
+
+    Runs one timestep of the model using snow, soil, and groundwater response routines.
+
+    Args:
+        precipitation (float): Precipitation at the timestep (mm).
+        temperature (float): Air temperature at the timestep (°C).
+        potential_et (float): Potential evapotranspiration at the timestep (mm).
+        params (dict): Dictionary with parameters and their ranges:
+            - 'snow': parameters for the snow routine
+            - 'soil': parameters for the soil routine
+            - 'response': parameters for the groundwater response routine
+        initial_conditions (dict): Dictionary with initial storages:
+            - 'snowpack': initial snowpack (mm)
+            - 'liquid_water': initial liquid water in snowpack (mm)
+            - 'soil_moisture': initial soil moisture (mm)
+            - 'upper_storage': initial upper groundwater storage (mm)
+            - 'lower_storage': initial lower groundwater storage (mm)
+
+    Returns:
+        new_states (dict): Updated storages after the timestep.
+        fluxes (dict): Fluxes generated during the timestep (runoff, ET, etc.).
+    """
+
+    # Unpack initial conditions
+    snowpack = initial_conditions['snowpack']
+    liquid_water = initial_conditions['liquid_water']
+    soil_moisture = initial_conditions['soil_moisture']
+    upper_storage = initial_conditions['upper_storage']
+    lower_storage = initial_conditions['lower_storage']
+
+    # Step 1: Snow routine
+    snowpack, liquid_water, runoff_from_snow = snow_routine(
+        precipitation, temperature, snowpack, liquid_water, params['snow']
+    )
+
+    # Step 2: Soil routine
+    soil_moisture, out_to_response, recharge, runoff_soil, actual_et = soil_routine(
+        runoff_from_snow, temperature, potential_et, soil_moisture, params['soil']
+    )
+
+    # Step 3: Groundwater response routine
+    upper_storage, lower_storage, discharge, quick_flow, intermediate_flow, baseflow = response_routine_two_tanks(
+        out_to_response, upper_storage, lower_storage, params['response']
+    )
+
+    # Updated states
+    new_states = {
+        'snowpack': snowpack,
+        'liquid_water': liquid_water,
+        'soil_moisture': soil_moisture,
+        'upper_storage': upper_storage,
+        'lower_storage': lower_storage,
+    }
+
+    # Outputs/Fluxes
+    fluxes = {
+        'discharge': discharge,
+        'quick_flow': quick_flow,
+        'intermediate_flow': intermediate_flow,
+        'baseflow': baseflow,
+        'actual_et': actual_et,
+        'recharge': recharge,
+        'runoff_soil': runoff_soil,
+        'runoff_from_snow': runoff_from_snow,
+    }
+
+    return new_states, fluxes

HBV_Lab/response.py

@@ -0,0 +1,78 @@
+def response_routine_two_tanks(out_to_response, upper_storage, lower_storage, params):
+    """
+    Groundwater response routine for HBV-light model with three flow components.
+    
+    Based on the HBV structure 
+    
+    Parameters:
+    -----------
+    out_to_response : float
+        Water from soil routine (recharge + surface runoff) (mm/day).
+    upper_storage : float
+        Current storage in the upper zone reservoir (SUZ) (mm).
+    lower_storage : float
+        Current storage in the lower zone reservoir (SLZ) (mm).
+    params : dict
+        Model parameters:
+            - 'K0' : Recession coefficient for quick flow (upper zone above threshold) [day^-1].
+            - 'K1' : Recession coefficient for intermediate flow (upper zone) [day^-1].
+            - 'K2' : Recession coefficient for baseflow (lower zone) [day^-1].
+            - 'UZL' : Threshold parameter for upper zone [mm].
+            - 'PERC' : Percolation rate from upper to lower zone (mm/day).
+    
+    Returns:
+    --------
+    upper_storage : float
+        Updated upper zone storage (mm).
+    lower_storage : float
+        Updated lower zone storage (mm).
+    discharge : float
+        Total discharge (fast + intermediate + slow runoff) (mm/day).
+    quick_flow : float
+        Quick flow component from upper zone (above threshold).
+    intermediate_flow : float
+        Intermediate flow component from upper zone.
+    baseflow : float
+        Baseflow component from lower zone.
+    """
+    
+    # Extract parameters
+    K0 = params['K0'] ['default']      # Quick flow coefficient (above threshold)
+    K1 = params['K1'] ['default']     # Intermediate flow coefficient
+    K2 = params['K2'] ['default']     # Baseflow coefficient
+    UZL = params['UZL'] ['default']   # Upper zone threshold
+    PERC = params['PERC'] ['default'] # Percolation from upper to lower zone
+    
+    # --- Step 1: Add incoming water to upper zone reservoir ---
+    upper_storage += out_to_response
+    
+    # --- Step 2: Percolation from upper to lower zone ---
+    percolation = min(PERC, upper_storage)
+    upper_storage -= percolation
+    lower_storage += percolation
+    
+    # --- Step 3: Calculate runoff components ---
+    # Quick flow (Q0): only occurs if upper zone storage exceeds threshold
+    if upper_storage > UZL:
+        quick_flow = K0 * (upper_storage - UZL)
+    else:
+        quick_flow = 0.0
+    
+    # Intermediate flow (Q1): from all upper zone storage
+    intermediate_flow = K1 * upper_storage
+    
+    # Baseflow (Q2): from lower zone storage
+    baseflow = K2 * lower_storage
+    
+    # --- Step 4: Update storages after runoff ---
+    upper_storage -= (quick_flow + intermediate_flow)
+    lower_storage -= baseflow
+    
+    # --- Step 5: Total discharge ---
+    discharge = quick_flow + intermediate_flow + baseflow
+    
+    # --- Step 6: Prevent negative storages ---
+    upper_storage = max(upper_storage, 0.0)
+    lower_storage = max(lower_storage, 0.0)
+    
+    return upper_storage, lower_storage, discharge, quick_flow, intermediate_flow, baseflow

HBV_Lab/routing.py

@@ -0,0 +1,41 @@
+import numpy as np
+from scipy.ndimage import convolve1d
+
+def route_with_maxbas(runoff_series= None, maxbas=1):
+    """
+    Correct linear interpolation routing as per HBV specifications
+    - MAXBAS=1: No routing (weights = [1.0])
+    - MAXBAS=2: Weights = [0.5, 0.5]
+    - MAXBAS=3: Weights = [0.25, 0.5, 0.25]
+    - MAXBAS=4: Weights = [0.125, 0.375, 0.375, 0.125]
+    - And so on...
+    """
+    if maxbas < 1:
+        raise ValueError("MAXBAS must be ≥1")
+    
+    # Special case - no routing
+    if maxbas == 1:
+        return runoff_series.copy()
+    
+    # Create proper weights using linear interpolation
+    if maxbas % 2 == 0:  # Even MAXBAS
+        n = maxbas // 2
+        x = np.linspace(0.5, n - 0.5, n)
+        weights = np.concatenate([x, x[::-1]]) / (n)
+    else:  # Odd MAXBAS
+        n = (maxbas + 1) // 2
+        x = np.linspace(0.5, n - 1, n)
+        weights = np.concatenate([x, x[-2::-1]]) / (n - 0.5)
+    
+    weights /= weights.sum()  # Ensure exact sum=1
+    
+    # Apply convolution
+    routed = convolve1d(
+        runoff_series,
+        weights,
+        origin=-(len(weights)//2),
+        mode='constant',
+        cval=0.0
+    )
+    
+    return routed[:len(runoff_series)]

HBV_Lab/snow.py

@@ -0,0 +1,70 @@
+def snow_routine(precipitation, temperature, snowpack, liquid_water, params):
+    """
+    Snow routine: calculates snow accumulation, melt, refreezing, and release of meltwater.
+
+    Args:
+        precipitation (float): Precipitation at timestep (mm).
+        temperature (float): Air temperature at timestep (°C).
+        snowpack (float): Current snow water equivalent (mm).
+        liquid_water (float): Liquid water stored in snowpack (mm).
+        params (dict): Model parameters:
+            - TT (float): Threshold temperature (°C).
+            - CFMAX (float): Degree-day factor (mm/d/°C).
+            - 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).
+        new_liquid_water (float): Updated liquid water in snowpack (mm).
+        runoff (float): Released meltwater to soil (mm).
+    """
+    # Extract parameters
+    TT = params['TT']['default']
+    CFMAX = params['CFMAX']['default']
+    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
+    rainfall = 0.0
+    # Calculate melting or refreezing
+    melt = 0.0
+    refreeze = 0.0
+
+    # Determine if precipitation is snow or rain
+    if temperature < TT:
+
+        snowfall = precipitation * SFCF
+        snowpack += snowfall
+
+        refreeze = CFR * CFMAX * (TT - temperature)
+        refreeze = min(refreeze, liquid_water)
+        snowpack += refreeze
+        liquid_water -= refreeze
+    else:
+
+        rainfall = precipitation 
+        melt = CFMAX * (temperature - TT)
+        melt = min(melt, snowpack)  # Cannot melt more than available snow
+        snowpack -= melt
+        liquid_water += melt + rainfall
+    
+
+    # Water release from snowpack if above holding capacity
+    holding_capacity = CWH * snowpack
+    if liquid_water > holding_capacity:
+        runoff = liquid_water - holding_capacity
+        liquid_water = holding_capacity
+    else:
+        runoff = 0.0
+
+    return snowpack, liquid_water, runoff

HBV_Lab/soil.py

@@ -0,0 +1,73 @@
+def soil_routine(runoff_from_snow, temperature, potential_et, soil_moisture, params):
+    """
+    Soil moisture routine for HBV-light model.
+
+    Simulates soil moisture dynamics, actual evapotranspiration (ET), 
+    groundwater recharge, and surface runoff based on incoming water 
+    and current soil moisture conditions.
+
+    Parameters:
+    -----------
+    runoff_from_snow : float
+        Incoming liquid wls
+        ater from snow routine (mm/day).
+    temperature : float
+        Daily average temperature (°C). (Currently unused but kept for possible extensions).
+    potential_et : float
+        Potential evapotranspiration (mm/day).
+    soil_moisture : float
+        Current soil moisture storage (mm).
+    params : dict
+        Model parameters:
+            - 'FC'   : Maximum soil moisture storage (Field Capacity) [mm].
+            - 'BETA' : Shape parameter controlling recharge [-].
+            - 'LP'   : Soil moisture threshold for full evapotranspiration [-].
+
+    Returns:
+    --------
+    soil_moisture : float
+        Updated soil moisture storage (mm).
+    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).
+    """
+
+    FC = params['FC']     ['default']   # Maximum soil moisture capacity
+    BETA = params['BETA'] ['default'] # Recharge curve parameter
+    LP = params['LP']     ['default'] # Limit for potential ET to be fully achieved
+
+    # --- Step 1: Calculate actual evapotranspiration ---
+    if soil_moisture > LP * FC:
+        actual_et = potential_et  # Full potential ET when soil is wet enough
+    else:
+        actual_et = potential_et * (soil_moisture / (LP * FC))  # Reduced ET if soil is dry
+
+    # Ensure we don't evaporate more than what's available
+    actual_et = min(actual_et, soil_moisture)
+
+    # --- Step 2: Calculate groundwater recharge ---
+    if soil_moisture > 0:
+        recharge = runoff_from_snow * (soil_moisture / FC) ** BETA
+    else:
+        recharge = 0.0
+
+    # --- Step 3: Update soil moisture balance ---
+    soil_moisture = soil_moisture + runoff_from_snow - actual_et - recharge
+
+    # --- Step 4: Handle surface runoff if soil moisture exceeds FC ---
+    if soil_moisture > FC:
+        runoff = soil_moisture - FC  # Excess water becomes surface runoff
+        soil_moisture = FC           # Cap soil moisture at field capacity
+       
+    else:
+        runoff = 0.0  # No surface runoff
+
+    # --- Step 5: Prevent negative soil moisture ---
+    soil_moisture = max(soil_moisture, 0.0)
+
+    out_to_response = recharge + runoff
+
+    return soil_moisture, out_to_response, recharge, runoff, actual_et