smash.bayesian_optimize#

smash.bayesian_optimize(model, mapping='uniform', optimizer=None, optimize_options=None, cost_options=None, common_options=None, return_options=None)[source]#

Model bayesian assimilation using numerical optimization algorithms.

Parameters:

modelModel

Primary data structure of the hydrological model smash.

mappingstr, default ‘uniform’

Type of mapping. Should be one of

'uniform'
'distributed'
'multi-linear'
'multi-polynomial'

Hint

See the Mapping section

optimizerstr or None, default None

Name of optimizer. Should be one of

'sbs' ('uniform' mapping only)
'lbfgsb' ('uniform', 'distributed', 'multi-linear' or 'multi-polynomial' mapping only)

Note

If not given, a default optimizer will be set depending on the optimization mapping:

mapping = 'uniform'; optimizer = 'sbs'
mapping = 'distributed', 'multi-linear', or 'multi-polynomial'; optimizer = 'lbfgsb'

Hint

See the Optimization Algorithm section

optimize_optionsdict[str, Any] or None, default None

Dictionary containing optimization options for fine-tuning the optimization process. See default_bayesian_optimize_options to retrieve the default optimize options based on the mapping and optimizer.

parametersstr, list[str, …] or None, default None

Name of parameters to optimize. Should be one or a sequence of any key of:

>>> optimize_options = {
    "parameters": "cp",
}
>>> optimize_options = {
    "parameters": ["cp", "ct", "kexc", "llr"],
}

Note

If not given, all parameters in Model.rr_parameters, Model.serr_mu_parameters and Model.serr_sigma_parameters will be optimized.

boundsdict[str, tuple[float, float]] or None, default None

Bounds on optimized parameters. A dictionary where the keys represent parameter names, and the values are pairs of (min, max) values (i.e., a list or tuple) with min lower than max. The keys must be included in parameters.

>>> optimize_options = {
    "bounds": {
        "cp": (1, 2000),
        "ct": (1, 1000),
        "kexc": (-10, 5)
        "llr": (1, 1000)
    },
}

Note

If not given, default bounds will be applied to each parameter. See Model.get_rr_parameters_bounds, Model.get_rr_initial_states_bounds, Model.get_serr_mu_parameters_bounds and Model.get_serr_sigma_parameters_bounds

control_tfmstr or None, default None

Transformation method applied to the control vector. Only used with 'sbs' or 'lbfgsb' optimizer. Should be one of:

'keep'
'normalize'
'sbs' ('sbs' optimizer only)

Note

If not given, a default control vector transformation will be set depending on the optimizer:

optimizer = 'sbs'; control_tfm = 'sbs'
optimizer = 'lbfgsb'; control_tfm = 'normalize'

descriptordict[str, list[str, …]] or None, default None

Descriptors linked to optimized parameters. A dictionary where the keys represent parameter names, and the values are list of descriptor names. The keys must be included in parameters.

>>> optimize_options = {
    "descriptor": {
        "cp": ["slope", "dd"],
        "ct": ["slope"],
        "kexc": ["slope", "dd"],
        "llr": ["dd"],
    },
}

Note

If not given, all descriptors will be used for each parameter. This option is only be used when mapping is 'multi-linear' or 'multi-polynomial'. In case of 'ann', all descriptors will be used.

termination_critdict[str, Any] or None, default None

Termination criteria. The elements are:

'maxiter': The maximum number of iterations. Only used when optimizer is 'sbs' or 'lbfgsb'.
'factr': An additional termination criterion based on cost values. Only used when optimizer is 'lbfgsb'.
'pgtol': An additional termination criterion based on the projected gradient of the cost function. Only used when optimizer is 'lbfgsb'.
'epochs': The number of training epochs for the neural network. Only used when mapping is 'ann'.
'early_stopping': A positive number to stop training when the loss function does not decrease below the current optimal value for early_stopping consecutive epochs. When set to zero, early stopping is disabled, and the training continues for the full number of epochs. Only used when mapping is 'ann'.

>>> optimize_options = {
    "termination_crit": {
        "maxiter": 10,
        "factr": 1e6,
    },
}
>>> optimize_options = {
    "termination_crit": {
        "epochs": 200,
    },
}

Note

If not given, default values are set to each elements.

cost_optionsdict[str, Any] or None, default None

Dictionary containing computation cost options for simulated and observed responses. The elements are:

end_warmupstr, pandas.Timestamp or None, default None

The end of the warm-up period, which must be between the start time and the end time defined in Model.setup.

>>> cost_options = {
    "end_warmup": "1997-12-21",
}
>>> cost_options = {
    "end_warmup": pd.Timestamp("19971221"),
}

Note

If not given, it is set to be equal to the Model.setup start time.

gaugestr or list[str, …], default ‘dws’

Type of gauge to be computed. There are two ways to specify it:

An alias among 'all' (all gauge codes) or 'dws' (most downstream gauge code(s))
A gauge code or any sequence of gauge codes. The gauge code(s) given must belong to the gauge codes defined in the Model.mesh

>>> cost_options = {
    "gauge": "dws",
}
>>> cost_options = {
    "gauge": "V3524010",
}
>>> cost_options = {
    "gauge": ["V3524010", "V3515010"],
}

control_priordict[str, list[str, list[float]]] or None, default None

Prior applied to the control vector. A dictionary containing the type of prior to link to control vector. The keys are any control parameter name (i.e. 'cp0', 'cp1-1', 'cp-slope-a', etc.), see bayesian_optimize_control_info to retrieve control parameters names. The values are list of length 2 containing distribution information (i.e. distribution name and parameters). Below, the set of available distributions and the associated number of parameters:

'FlatPrior', [] (0)
'Uniform', [lower_bound, higher_bound] (2)
'Gaussian', [mean, standard_deviation] (2)
'Exponential', [threshold, scale] (2)
'LogNormal', [mean_log, standard_deviation_log] (2)
'Triangle', [peak, lower_bound, higher_bound] (3)

>>> cost_options = {
    control_prior: {
        "cp0": ["Gaussian", [200, 100]],
        "kexc0": ["Gaussian", [0, 5]],
    }
}

Note

If not given, 'FlatPrior' is applied to each control vector parameter (i.e. equivalent to no prior).

Hint

See a more detailed explanation on the available distributions in Bayesian Estimation section.

common_optionsdict[str, Any] or None, default None

Dictionary containing common options with two elements:

ncpuint, default 1: Number of CPU(s) to perform a parallel computation.

Warning

Parallel computation is not supported on Windows.
verbosebool, default False: Whether to display information about the running method.

return_optionsdict[str, Any] or None, default None

Dictionary containing return options to save intermediate variables. The elements are:

time_stepstr, pandas.Timestamp, pandas.DatetimeIndex or list[str, …], default ‘all’

Returned time steps. There are five ways to specify it:

An alias among 'all' (return all time steps).
A date as string which respect pandas.Timestamp format
A pandas.Timestamp.
A pandas.DatetimeIndex.
A sequence of dates as strings.

>>> return_options = {
    "time_step": "all",
}
>>> return_options = {
    "time_step": "1997-12-21",
}
>>> return_options = {
    "time_step": pd.Timestamp("19971221"),
}
>>> return_options = {
    "time_step": pd.date_range(
        start="1997-12-21",
        end="1998-12-21",
        freq="1D"
    ),
}
>>> return_options = {
    "time_step": ["1998-05-23", "1998-05-24", "1998-05-25"],
}

Note

It only applies to the following variables: 'rr_states' and 'q_domain'

rr_statesbool, default False

Whether to return rainfall-runoff states for specific time steps.

q_domainbool, default False

Whether to return simulated discharge on the whole domain for specific time steps.

iter_costbool, default False

Whether to return cost iteration values.

iter_projgbool, default False

Whether to return infinity norm of the projected gardient iteration values.

control_vectorbool, default False

Whether to return control vector at end of optimization. In case of optimization with 'ann' mapping, the control vector is represented in Net.layers instead.

costbool, default False

Whether to return cost value.

log_lkhbool, default False

Whether to return log likelihood component value.

log_priorbool, default False

Whether to return log prior component value.

log_hbool, default False

Whether to return log h component value.

serr_mubool, default False

Whether to return mu, the mean of structural errors. It can also be returned directly from the Model object using the Model.get_serr_mu method.

serr_sigmabool, default False

Whether to return sigma, the standard deviation of structural errors. It can also be returned directly from the Model object using the Model.get_serr_sigma method.

Returns:

modelModel: It returns an updated copy of the initial Model object.
bayesian_optimizeBayesianOptimize or None, default None: It returns an object containing the intermediate variables defined in return_options. If no intermediate variables are defined, it returns None.