smash.Model#

class smash.Model(setup, mesh)[source]#

Primary data structure of the hydrological model smash.

Parameters:

setupdict[str, Any]

Model initialization setup dictionary. The elements are:

snow_modulestr, default ‘zero’

Name of snow module. Should be one of:

'zero'
'ssn'

Hint

See the Snow Module section

hydrological_modulestr, default ‘gr4’

Name of hydrological module. Should be one of:

'gr4'
'gr5'
'grd'
'loieau'
'vic3l'

Hint

See the Hydrological Module section

routing_modulestr, default ‘lr’

Name of routing module. Should be one of:

'lag0'
'lr'
'kw'

Hint

See the Routing Module section

serr_mu_mappingstr, default ‘Zero’

Name of the mapping used for \(\mu\), the mean of structural errors. Should be one of:

'Zero' (\(\mu = 0\))
'Constant' (\(\mu = \mu_0\))
'Linear' (\(\mu = \mu_0 + \mu_1 \times q\))

Hint

See the Bayesian Estimation section

serr_sigma_mappingstr, default ‘Linear’

Name of the mapping used for \(\sigma\), the standard deviation of structural errors. Should be one of:

'Constant' (\(\sigma=\sigma_0\))
'Linear' (\(\sigma=\sigma_0 + \sigma_1 \times q\))
'Power' (\(\sigma=\sigma_0 + \sigma_1 \times q^{\sigma_2}\))
'Exponential' (\(\sigma=\sigma_0 + (\sigma_2-\sigma_0) \times \left( 1-\exp (-q/\sigma_1) \right)\))
'Gaussian' (\(\sigma=\sigma_0 + (\sigma_2-\sigma_0) \times \left( 1-\exp( -(q/\sigma_1)^2) \right)\))

Hint

See the Bayesian Estimation section

dtfloat, default 3600

Simulation time step in seconds.

start_timestr, datetime.date or pandas.Timestamp

Start time date.

end_timestr, datetime.date or pandas.Timestamp

End time date. end_time must be later than start_time

Note

The convention of smash is that start_time is the date used to initialize the model’s states. All the modeled state-flux variables \(\boldsymbol{U}(x,t)\) (i.e. discharge, states, internal fluxes) will be computed over the period start_time + 1dt and end_time

adjust_interceptionbool, default True: Whether or not to adjust the maximum capacity of the interception reservoir. This option is only applicable if hydrological_module is set to 'gr4' or 'gr5' and for a sub-daily simulation time step dt.
compute_mean_atmosbool, default True: Whether or not to compute mean atmospheric data for each gauge.
read_qobsbool, default False: Whether or not to read observed discharge file(s).

Hint

See the Input Data Convention section
qobs_directorystr: Path to the root directory of the observed discharge file(s). This option is mandatory if read_qobs is set to True.
read_prcpbool, default False: Whether or not to read precipitation file(s).

Hint

See the Input Data Convention section
prcp_formatstr, default ‘tif’: Precipitation file format. This option is only applicable if read_prcp is set to True.

Note

Only the tif format is currently supported. We would like to extend this to netcdf format in future version.
prcp_conversion_factorfloat, default 1: Preciptation conversion factor. The precipitation will be multiplied by the conversion factor. This option is only applicable if read_prcp is set to True.
prcp_directorystr: Path to the root directory of the precipitation file(s). This option is mandatory if read_prcp is set to True.
prcp_accessstr, default ‘’: Precipitation directory structure access. By default, files are read using a recursive search from the root directory prcp_directory. This option makes it possible to specify the directory structure and allow faster access according to start_time and end_time dates. This option is only applicable if read_prcp is set to True.
read_petbool, default False: Whether or not to read potential evapotranspiration file(s).

Hint

See the Input Data Convention section
pet_formatstr, default ‘tif’: Potential evapotranspiration file format. This option is only applicable if read_pet is set to True.

Note

Only the tif format is currently supported. We would like to extend this to netcdf format in future version.
pet_conversion_factorfloat, default 1: Potential evapotranspiration conversion factor. The potential evapotranspiration will be multiplied by the conversion factor. This option is only applicable if read_pet is set to True.
pet_directorystr: Path to the root directory of the potential evapotranspiration file(s). This option is mandatory if read_pet is set to True.
pet_accessstr, default ‘’: Potential evapotranspiration directory structure access. By default, files are read using a recursive search from the root directory pet_directory. This option makes it possible to specify the directory structure and allow faster access according to start_time and end_time dates. This option is only applicable if read_pet is set to True.
daily_interannual_petbool, default False: Whether or not to read daily interannual potential evapotranspiration. This replaces the conventional way of reading a file in time steps.
read_snowbool, default False: Whether or not to read snow file(s). This option is only applicable if snow_module is set to ssn.

Hint

See the Input Data Convention section
snow_formatstr, default ‘tif’: Snow file format. This option is only applicable if read_snow is set to True and if snow_module is set to ssn.

Note

Only the tif format is currently supported. We would like to extend this to netcdf format in future version.
snow_conversion_factorfloat, default 1: Snow conversion factor. The snow will be multiplied by the conversion factor. This option is only applicable if read_snow is set to True and if snow_module is set to ssn.
snow_directorystr: Path to the root directory of the snow file(s). This option is mandatory if read_snow is set to True and if snow_module is set to ssn.
snow_accessstr, default ‘’: Snow directory structure access. By default, files are read using a recursive search from the root directory snow_directory. This option makes it possible to specify the directory structure and allow faster access according to start_time and end_time dates. This option is only applicable if read_snow is set to True and if snow_module is set to ssn.
read_tempbool, default False: Whether or not to read temperature file(s).

Hint

See the Input Data Convention section
temp_formatstr, default ‘tif’: Temperature file format. This option is only applicable if read_temp is set to True and if snow_module is set to ssn.

Note

Only the tif format is currently supported. We would like to extend this to netcdf format in future version.
temp_directorystr: Path to the root directory of the temperature file(s). This option is mandatory if read_temp is set to True and if snow_module is set to ssn.
temp_accessstr, default ‘’: Temperature directory structure access. By default, files are read using a recursive search from the root directory temp_directory. This option makes it possible to specify the directory structure and allow faster access according to start_time and end_time dates. This option is only applicable if read_temp is set to True and if snow_module is set to ssn.
prcp_partitioningbool, default False: Whether or not to partition precipitation into liquid (precipitation) and solid (snow) parts. If precipitation and snow are read, the precipitation and snow will be summed before partitioning. This option is only applicable if snow_module is set to ssn.

Hint

See the Precipitation Partitioning section
sparse_storagebool, default False: Whether or not to store atmospheric data (i.e. precipitation, potential evapotranspiration, snow and temperature) sparsely. This option reduces the amount of memory taken up by atmospheric data. It is particularly useful when working large dataset.
read_descriptorbool, default False: Whether or not to read descriptor file(s).
descriptor_formatstr, default ‘tif’: Descriptor file format. This option is only applicable if read_descriptor is set to True.

Note

Only the tif format is currently supported. We would like to extend this to netcdf format in future version.
descriptor_directorystr: Path to the root directory of the descriptor file(s). This option is mandatory if read_descriptor is set to True.
descriptor_namelist[str]: List of descriptor name. This option is mandatory if read_descriptor is set to True.

meshdict[str, Any]

Model initialization mesh dictionary.

Note

The elements are described in the smash.factory.generate_mesh method.

See also

smash.io.save_setup: Save the Model initialization setup dictionary to YAML.
smash.io.read_setup: Read the Model initialization setup dictionary from YAML.
smash.factory.generate_mesh: Automatic Model initialization mesh dictionary generation.
smash.io.save_mesh: Save the Model initialization mesh dictionary to HDF5.
smash.io.read_mesh: Read the Model initialization mesh dictionary from HDF5.
smash.io.save_model: Save the Model object to HDF5.
smash.io.read_model: Read the Model object from HDF5.

Examples

>>> from smash.factory import load_dataset
>>> setup, mesh = load_dataset("cance")

Setup and mesh dictionaries loaded from Cance dataset

>>> setup
{
    'hydrological_module': 'gr4',
    'routing_module': 'lr',
    'dt': 3600,
    ...
    'descriptor_name': ['slope', 'dd']
}
>>> mesh.keys()
dict_keys(['active_cell', 'area', 'area_dln', ..., 'yres'])

Constructing the Model object

>>> model = smash.Model(setup, mesh)
</> Reading precipitation: 100%|█████████████████████████████| 1440/1440 [00:00<00:00, 10323.28it/s]
</> Reading daily interannual pet: 100%|███████████████████████| 366/366 [00:00<00:00, 13735.82it/s]
</> Disaggregating daily interannual pet: 100%|█████████████| 1440/1440 [00:00<00:00, 132565.08it/s]
</> Computing mean atmospheric data
</> Adjusting GR interception capacity
>>> model
Model
    atmos_data: ['mean_pet', 'mean_prcp', '...', 'sparse_prcp', 'sparse_snow']
    mesh: ['active_cell', 'area', '...', 'xres', 'ymax']
    physio_data: ['descriptor', 'l_descriptor', 'u_descriptor']
    response: ['q']
    response_data: ['q']
    rr_final_states: ['keys', 'values']
    rr_initial_states: ['keys', 'values']
    rr_parameters: ['keys', 'values']
    serr_mu_parameters: ['keys', 'values']
    serr_sigma_parameters: ['keys', 'values']
    setup: ['adjust_interception', 'compute_mean_atmos', '...', 'temp_access', 'temp_directory']
    u_response_data: ['q_stdev']

Attributes:

atmos_data: Model atmospheric data.
mesh: Model mesh.
physio_data: Model physiographic data.
response: Model response.
response_data: Model response data.
rr_final_states: Model rainfall-runoff final states.
rr_initial_states: Model rainfall-runoff initial states.
rr_parameters: Model rainfall-runoff parameters.
serr_mu_parameters: Model structural error mu parameters.
serr_sigma_parameters: Model structural error sigma parameters.
setup: Model setup.
u_response_data: Model response data uncertainties.

Methods

`bayesian_optimize`([mapping, optimizer, ...])	Model bayesian assimilation using numerical optimization algorithms.
`copy`()	Create a deep copy of Model.
`forward_run`([cost_options, common_options, ...])	Run the forward Model.
`get_rr_final_states`(key)	Get the values of a Model rainfall-runoff final state.
`get_rr_initial_states`(key)	Get the values of a Model rainfall-runoff initial state.
`get_rr_initial_states_bounds`()	Get the boundary condition for the Model rainfall-runoff initial states.
`get_rr_parameters`(key)	Get the values of a Model rainfall-runoff parameter.
`get_rr_parameters_bounds`()	Get the boundary condition for the Model rainfall-runoff parameters.
`get_serr_mu`()	Get the structural error mu value by applying the mu mapping.
`get_serr_mu_parameters`(key)	Get the values of a Model structural error mu parameter.
`get_serr_mu_parameters_bounds`()	Get the boundary condition for the Model structural error mu parameters.
`get_serr_sigma`()	Get the structural error sigma value by applying the sigma mapping.
`get_serr_sigma_parameters`(key)	Get the values of a Model structural error sigma parameter.
`get_serr_sigma_parameters_bounds`()	Get the boundary condition for the Model structural error sigma parameters.
`multiset_estimate`(multiset[, alpha, ...])	Model assimilation using Bayesian-like estimation on multiple sets of solutions.
`optimize`([mapping, optimizer, ...])	Model assimilation using numerical optimization algorithms.
`set_rr_initial_states`(key, value)	Set the values of a Model rainfall-runoff initial state.
`set_rr_parameters`(key, value)	Set the values of a Model rainfall-runoff parameter.
`set_serr_mu_parameters`(key, value)	Set the values of a Model structural error mu parameter.
`set_serr_sigma_parameters`(key, value)	Set the values of a Model structural error sigma parameter.