Getting started

Hydrobricks is distributed through PyPi and can be installed using pip:

pip install hydrobricks

Use an older version of Python (e.g., 3.11) to ensure package compatibility.

Some code examples are provided in the python/examples directory of the repo. The tests can also be a useful resource to understand the behaviour of some functions.

Here is a minimum example:

import hydrobricks as hb
import hydrobricks.models as models

# Model structure
socont = models.Socont(soil_storage_nb=2, surface_runoff="linear_storage",
                       record_all=False)

# Parameters
parameters = socont.generate_parameters()
parameters.set_values({'A': 458, 'a_snow': 1.8, 'k_slow_1': 0.9, 'k_slow_2': 0.8,
                       'k_quick': 1, 'percol': 9.8})

# Hydro units
hydro_units = hb.HydroUnits()
hydro_units.load_from_csv(
    'path/to/elevation_bands.csv', column_elevation='elevation', column_area='area')

# Meteo data
forcing = hb.Forcing(hydro_units)
forcing.load_station_data_from_csv(
    'path/to/meteo.csv', column_time='Date', time_format='%d/%m/%Y',
    content={'precipitation': 'precip(mm/day)', 'temperature': 'temp(C)',
             'pet': 'pet_sim(mm/day)'})
ref_elevation = 1250  # Reference altitude for the meteo data
forcing.spatialize_from_station_data(
    variable='temperature', ref_elevation=ref_elevation, gradient=-0.6)
forcing.correct_station_data(variable='precipitation', correction_factor=0.75)
forcing.spatialize_from_station_data(
    variable='precipitation', ref_elevation=ref_elevation, gradient=0.05)
forcing.compute_pet(method='Hamon', use=['t', 'lat'], lat=47.3)

# Obs data
obs = hb.Observations()
obs.load_from_csv('path/to/discharge.csv', column_time='Date', time_format='%d/%m/%Y',
                  content={'discharge': 'Discharge (mm/d)'})

# Model setup
socont.setup(spatial_structure=hydro_units, output_path=str('path/to/outputs'),
             start_date='1981-01-01', end_date='2020-12-31')

# Initialize and run the model
socont.initialize_state_variables(parameters=parameters, forcing=forcing)
socont.run(parameters=parameters, forcing=forcing)

# Get outlet discharge time series
sim_ts = socont.get_outlet_discharge()

# Evaluate
obs_ts = obs.data[0]
nse = socont.eval('nse', obs_ts)
kge_2012 = socont.eval('kge_2012', obs_ts)

print(f"nse = {nse:.3f}, kge_2012 = {kge_2012:.3f}")