Models
The following model structures are currently implemented:
Common options
All models accept the following options at instantiation:
solver: numerical solver to use; choices areheun_explicit(default),runge_kutta, andeuler_explicit.record_all(defaultFalse): whenTrue, all fluxes and state variables are recorded at every time step. This slows computation and produces large output files. Enable only for diagnostic analysis, not during calibration.land_cover_types: list of land cover types (e.g.,['ground', 'glacier']). See the section on the spatial structure.land_cover_names: list of land cover names. Each entry must correspond to a type inland_cover_types. Names distinguish similar types, for example bare-ice and debris-covered glaciers. See the section on the spatial structure.
Example:
socont = models.Socont(solver="heun_explicit", record_all=False)
GSM-Socont
GSM-Socont is a conceptual glacio-hydrological model described in Schaefli et al. [2005].
Spatial structure: semi-lumped (elevation bands)
Time step: daily
Specific options
soil_storage_nb:1or2. Number of soil reservoirs; the second represents the baseflow component (not in the original model).surface_runoff:socont_runoff(the original non-linear quick reservoir) orlinear_storage(a classic linear storage).snow_melt_process: melt model to use; see melt models. Default:"melt:degree_day".
Parameters
Precipitation (snow/rain transition)
prec_t_start(optional, °C, default: 0, [-2, 2])Temperature below which precipitation is 100% snow. The rain/snow transition is linear between
prec_t_startandprec_t_end.Full name:
snow_rain_transition:transition_start.
prec_t_end(optional, °C, default: 2, [0, 4])Temperature above which precipitation is 100% liquid.
Full name:
snow_rain_transition:transition_end.
Snow (melt:degree_day)
a_snow(mm/d/°C, no default, [1, 12])Degree-day snow melt factor. \(a_\mathrm{snow}\) in Schaefli et al. [2005].
Full name:
snowpack:degree_day_factor.
melt_t_snow(optional, °C, default: 0, [0, 5])Temperature above which snow starts to melt.
Full name:
snowpack:melting_temperature.
Glacier (melt:degree_day)
a_ice(single type),a_ice_<name>,a_ice_<i>(mm/d/°C, no default, [5, 20])Degree-day ice melt factor. \(a_\mathrm{ice}\) in Schaefli et al. [2005].
<name>is the land cover name (e.g.,glacier_debris);<i>is the index of similar land covers (e.g.,a_ice_glacier_debris,a_ice_1).Full name:
<name>:degree_day_factor.
melt_t_ice(optional, °C, default: 0, [0, 5])Temperature above which ice starts to melt.
Full name:
<name>:melting_temperature.
Glacier area lumped reservoir
k_snow(1/d, no default, [0.05, 0.25])Response factor for the lumped reservoir receiving rain and snowmelt water from the glacier area. Similar to \(k_\mathrm{snow}\) in Schaefli et al. [2005], but in different units.
Full name:
glacier_area_rain_snowmelt_storage:response_factor.
k_ice(1/d, no default, [0.05, 1])Response factor for the lumped reservoir receiving ice melt water. Similar to \(k_\mathrm{ice}\) in Schaefli et al. [2005], but in different units.
Full name:
glacier_area_icemelt_storage:response_factor.
Quick runoff (non-linear version)
beta(m^(4/3)/s, no default, [100, 30000])Runoff coefficient (to calibrate).
Full name:
surface_runoff:runoff_coefficient.
Quick runoff (linear version)
k_quick(1/d, no default, [0.05, 1])Response factor for the quick reservoir.
Full name:
surface_runoff:response_factor.
Slow reservoir
A(mm, no default, [10, 3000])Maximum storage capacity of the slow reservoir.
Full name:
slow_reservoir:capacity.
k_slow,k_slow_1(1/d, no default, [0.001, 1])Response factor for the slow reservoir. Same as \(k\) in Schaefli et al. [2005], but in different units.
Full name:
slow_reservoir:response_factor.
Baseflow (optional)
percol(mm/d, no default, [0, 10])Percolation rate from the first slow reservoir to the baseflow reservoir.
Full name:
slow_reservoir:percolation_rate.
k_slow_2(1/d, no default, [0.001, 1])Response factor for the baseflow reservoir.
Full name:
slow_reservoir_2:response_factor.
For the melt:degree_day_aspect and melt:temperature_index options, see
Snow / Glacier melt parameters under Shared processes.
Pre-defined parameter constraints:
Glacier
a_snow < a_ice
Slow reservoir
k_slow_1 < k_quickk_slow_2 < k_quickk_slow_2 < k_slow_1
GR4J
GR4J (Génie Rural à 4 paramètres Journalier) is a parsimonious daily rainfall-runoff model described in Perrin et al. [2003]. It is well suited for non-glacierized or weakly glacierized catchments. Snow can optionally be accounted for using either the CemaNeige model or a simple degree-day approach.
Spatial structure: lumped
Time step: daily
Specific options
snow_melt_process: snow model to use. Options:None(default): no snow accounting."melt:cemaneige": CemaNeige thermal-state model (recommended for catchments with significant seasonal snow). See processes page."melt:degree_day": simple degree-day model.
snow_redistribution: optional snow redistribution process (e.g.,'transport:snow_slide'). See the snow redistribution section.
Parameters
Production store
X1(mm, default: 350, [100, 1200])Maximum capacity of the production store.
Full name:
production_store:capacity.
Groundwater exchange
X2(mm/d, default: 0, [-10, 5])Groundwater exchange coefficient. Negative values indicate a net loss (deep percolation); positive values indicate recharge from outside the catchment.
Full name:
uh_input:exchange_factor.
Routing store
X3(mm, default: 90, [1, 500])Maximum capacity of the routing store.
Full name:
uh_input:routing_capacity.
Unit hydrograph
X4(d, default: 1.7, [0.5, 4])Time base of the unit hydrograph. Must be > 0.5 d.
Full name:
uh_input:uh_base_time.
For CemaNeige parameters (melt:cemaneige), see
Snow / Glacier melt parameters under Shared processes.
When snow_melt_process='melt:degree_day', only a_snow (alias Kf)
and Tmelt are added.
Usage examples
Minimal run without snow:
import hydrobricks as hb
import hydrobricks.models as models
gr4j = models.GR4J()
parameters = gr4j.generate_parameters()
parameters.set_values({'X1': 350, 'X2': 0, 'X3': 90, 'X4': 1.7})
hydro_units = hb.HydroUnits()
hydro_units.load_from_csv(
'path/to/hydro_units.csv',
column_elevation='elevation',
column_area='area'
)
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)', 'pet': 'pet(mm/day)'}
)
forcing.spatialize_from_station_data(
variable='precipitation',
ref_elevation=1250,
gradient=0.05
)
forcing.spatialize_from_station_data(variable='pet')
gr4j.setup(
spatial_structure=hydro_units,
output_path='path/to/outputs',
start_date='1981-01-01',
end_date='2020-12-31'
)
gr4j.run(parameters=parameters, forcing=forcing)