GLUE

class smartpy.montecarlo.GLUE(catchment, root_f, in_format, out_format, conditioning, parallel='seq', save_sim=False, settings_filename=None, decompression_csv=False)

GLUE is the available to condition a sample of parameter sets using a Generalized Likelihood Uncertainty Estimation (GLUE) approach (Beven and Binley (1992), Beven and Freer (2001), Beven and Binley (2014)). That is to say elicit which parameter sets in a sample are “behavioural” or not, based on some likelihood measure.

Important

A sampling must have already been performed prior to using this functionality, and the conditioned sample is then used to run the model on a different simulation period than the sampling simulation period.

Instantiation

Parameters

catchment: str

A name to identify the catchment of interest in the inputs and outputs directories.

root_f: str

The file path to the directory containing the model inputs and outputs. Note that a specific internal structure for this directory must be followed:

root_f
├── in
│   └── catchment
│       ├── catchment.rain
│       ├── catchment.peva
│       ├── catchment.flow
│       └── catchment.sttngs
└── out

in_format: str

The input file format. It can either be 'csv' or 'netcdf'. Note that in either case, a specific file format must be followed.

out_format: str

The output file format. It can either be 'csv' or 'netcdf'.

conditioning: dict

The set of conditions to use to consider a parameter set as “behavioural” gathered in a dictionary. The objective functions to choose from as likelihood measures are:

‘NSE’	Nash Sutcliffe Efficiency.
‘KGE’	Kling-Gupta Efficiency.
‘KGEc’	r component of Kling-Gupta Efficiency.
‘KGEa’	alpha component of Kling-Gupta Efficiency.
‘KGEb’	beta component of Kling-Gupta Efficiency.
‘PBias’	Percent bias.
‘RMSE’	Root mean square error.
‘GW’	Groundwater contribution to runoff. This is a specific objective function for the SMART model. This objective function acts as a filter to eliminate parameter sets who produce ratios of groundwater runoff, shallow and deep, over total runoff that are not within \(\pm\) 10% of the observed/expected value. The objective function evaluates as one when this is the case, and as zero when this is not (i.e. eliminated).

Parameter example:

conditioning={
    'GW': ['equal', (1,)],  # GW = 1
    'NSE': ['min', (0.8,)]  # NSE >= 0.8
    'PBias': ['max', (10,)],  # PBias <= 10%
}

Parameter example:

conditioning={
    'PBias': ['inside', (-10, 10)],  # -10% <= PBias <= 10%
    'KGE': ['min', (0.6,)]  # KGE >= 0.6
}

Warning

Depending on the conditions chosen, this may yield no “behavioural” parameter set.

parallel: str, optional

Whether the sampling is to performed in parallel (i.e. using MPI calls to run several simulations at the same time), or in serial (i.e. running simulations sequentially one after another). The options are:

Parallel	Description
'seq'	Run the simulations one after another.
'mpi'	Run several simulations at the same time. The number of simultaneous simulations is determined with the number of processes using mpirun -np.

If not provided, set to default value 'seq'.

save_sim: bool, optional

Whether to save the simulated discharge time series. If not provided, set to default value False (i.e. the simulated values are not recorded). Note that the sampled parameter values as well as a bundle of objective functions are always recorded in the sampling output file regardless of this argument.

settings_filename: str, optional

The name of the settings file to use to configure the SMART model. This argument is to be used when the settings file does not follow the specific file name expected by the model, i.e. {root_f}/in/{catchment}.sttngs. If not provided, set to the specific file name expected. Note that regardless of this argument, the settings file must be in the inputs folder for the given catchment (in other words, absolute paths are not supported here).

decompression_csv: bool, optional

Whether the CSV files containing the sample of parameter sets is compressed or not. If it is, this must be set to True to decompress the CSV file as a pre-processing step. If not provided, set to default vaalue False (i.e. no decompression).

Methods

run	Run the simulations for the sample of parameter sets.