smash.forward_run#

smash.forward_run(model, cost_options=None, common_options=None, return_options=None)[source]#

Run the forward Model.

Parameters:

modelModel

Primary data structure of the hydrological model smash.

cost_optionsdict[str, Any] or None, default None

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

jobs_cmptstr or list[str, …], default ‘nse’

Type of observation objective function(s) to be computed. Should be one or a sequence of any of

'nse', 'nnse', 'kge', 'mae', 'mape', 'mse', 'rmse', 'lgrm' (classical evaluation metrics)
'Crc', 'Crchf', 'Crclf', 'Crch2r', 'Cfp2', 'Cfp10', 'Cfp50', 'Cfp90' (continuous signatures-based error metrics)
'Eff', 'Ebf', 'Erc', 'Erchf', 'Erclf', 'Erch2r', 'Elt', 'Epf' (flood event signatures-based error metrics)

>>> cost_options = {
    "jobs_cmpt": "nse",
}
>>> cost_options = {
    "jobs_cmpt": ["nse", "Epf"],
}

Hint

See the Efficiency & Error Metric and Hydrological Signature sections

wjobs_cmptstr or list[float, …], default ‘mean’

The corresponding weighting of observation objective functions in case of multi-criteria (i.e., a sequence of objective functions to compute). There are two ways to specify it:

An alias among 'mean'
A sequence of value whose size must be equal to the number of observation objective function(s) in jobs_cmpt

>>> cost_options = {
    "wjobs_cmpt": "mean",
}
>>> cost_options = {
    "wjobs_cmpt": [0.7, 0.3],
}

jobs_cmpt_tfmstr or list[str, …], default ‘keep’

Type of transformation applied to discharge in observation objective function(s). Should be one or a sequence of any of

'keep' : No transformation \(f:x \rightarrow x\)
'sqrt' : Square root transformation \(f:x \rightarrow \sqrt{x}\)
'inv' : Multiplicative inverse transformation \(f:x \rightarrow \frac{1}{x}\)

>>> cost_options = {
    "jobs_cmpt_tfm": "inv",
}
>>> cost_options = {
    "jobs_cmpt_tfm": ["keep", "inv"],
}

Note

If jobs_cmpt is a multi-criteria and only one transformation is choosen in jobs_cmpt_tfm. The transformation will be applied to each observation objective function.

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"],
}

wgaugestr or list[float, …] default ‘mean’

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

An alias among 'mean', 'lquartile' (1st quantile or lower quantile), 'median', or 'uquartile' (3rd quantile or upper quantile)
A sequence of value whose size must be equal to the number of gauges optimized in gauge

>>> cost_options = {
    "wgauge": "mean",
}
>>> cost_options = {
    "wgauge": [0.6, 0.4]",
}

event_segdict[str, float], default {‘peak_quant’: 0.995, ‘max_duration’: 240}

A dictionary of event segmentation options when calculating flood event signatures for cost computation (i.e., jobs_cmpt includes flood events signatures).

>>> cost_options = {
    event_seg = {
        "peak_quant": 0.998,
        "max_duration": 120,
    }
}

Hint

See the hydrograph_segmentation function and Hydrograph Segmentation 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.

costbool, default False

Whether to return cost value.

jobsbool, default False

Whether to return jobs (observation component of cost) value.

Returns:

modelModel: It returns an updated copy of the initial Model object.
forward_runForwardRun 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.