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', 'gr4_mlp', 'gr4_ri', 'gr4_ode', 'gr4_ode_mlp'

  • 'gr5', 'gr5_mlp', 'gr5_ri'

  • 'gr6', 'gr6_mlp'

  • 'grc', 'grc_mlp'

  • 'grd', 'grd_mlp'

  • 'loieau', 'loieau_mlp'

  • '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

hidden_neuronint or list[int], default 16

Number of neurons in hidden layer(s) of the parameterization neural network used to correct internal fluxes, if used (depending on hydrological_module). If it is a list, the maximum length is 2, which means the neural network can have up to 2 hidden layers.

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 available for any hydrological_module having the \(c_i\) parameter (i.e., 'gr4', 'gr5', 'gr6', etc.) 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 Format Description 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 Format Description 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 Format Description 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 Format Description 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 Format Description 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.

read_imperviousnessbool, default False

Whether or not to read descriptor file(s).

imperviousness_formatstr, default ‘tif’

This option is only applicable if read_imperviousness is set to True.

Note

Only the tif format is currently supported.

imperviousness_directorystr

Path to the imperviousness file. This option is mandatory if read_imperviousness is set to True.

meshdict[str, Any]

Model initialization mesh dictionary.

Note

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

Attributes:
atmos_data

Model atmospheric data.

mesh

Model mesh.

nn_parameters

The weight and bias of the parameterization neural network.

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

adjust_interception([active_cell_only])

Adjust the interception reservoir capacity.

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_nn_parameters_bias()

Get the bias of the parameterization neural network.

get_nn_parameters_weight()

Get the weight of the parameterization neural network.

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_control_bayesian_optimize(control_vector)

Retrieve the Model parameters/states from the bayesian optimization control vector.

set_control_optimize(control_vector[, ...])

Retrieve the Model parameters/states from the optimization control vector.

set_nn_parameters_bias([value, initializer, ...])

Set the values of the bias in the parameterization neural network.

set_nn_parameters_weight([value, ...])

Set the values of the weight in the parameterization neural network.

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.

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']
On this page

This Page