Setup your own model

There are descriptions on how to:

1. Setup a new model starting from scratch, and
2. Setup another RAVEN example starting from the RAVEN HMETS example.

Setup a new model

Let's assume you have a model ABC and you want to identify the subset of parameters that are influential from the parameters that are non informative. The following four steps will be required to setup your own model and run the Efficient Elementary Effects using the wrapper __run_eee.sh.

1. Create a new example folder

mkdir examples/my-model-abc     # choose your model name

2. Provide information for all your model parameters
Let's assume your first parameter is x_1 that is uniformly distributed in the range U[-1,3] and your second parameter x_2 is Gaussian distributed with N[4,2]. All parameters need to be set to be non informative (last column 1 for each parameter). The default parameter value is not used in any of the methods but added for completeness.

# para   dist       lower     upper     default   informative(0)_or_noninformative(1)
#                   mean      stddev
x_1      uniform    -1.00000  3.00000   0.70000   1
x_2      Gaussian   4.00000   2.00000   4.00000   1
...

Store this in an ASCII file examples/my-model-abc/parameters.dat

3. Provide script to run model
You will need to provide a script that runs your model. You might need to call external executables, Matlab, or similar. Or you might run your model in parallel for all provided parameter sets on a high-performance cluster. The script receives all scaled parameter sets and needs to return a Pickle file containing a dictionary of model outputs. Please see to the example scripts for further details. Only scalar and one-dimensional model outputs are supported at the moment. You might call this script 2_run_model_my-model-abc.py.

Note:This script needs to be located in the codes/ subfolder.

4. Run the wrapper to perform the Efficient Elementary Effects
Run the Efficient Elementary Effects for All model outputs stored in the Pickle file ...

./__run_eee.sh -s All -x 2_run_model_my-model-abc.py examples/my-model-abc/ 

... or for a selected model output out stored in the Pickle file (out needs to be a key of the dictionary):

./__run_eee.sh -s out -x 2_run_model_my-model-abc.py examples/my-model-abc/ 

Setup another RAVEN example

1. Create a new folder
Start with creating a new example by copying the folder examples/raven-hmets/ and call it, for example, examples/raven-my-configuration/.

2. Replace RAVEN executable
You will need to replace the RAVEN executable examples/raven-my-configuration/model/Raven.exe by an executable that is compiled on your system. You can download executables from the Raven webpage. Please test if they run on your system. If not, please download the source code from the webpage and compile it using make. Then put the executable in the folder examples/raven-hmets/model/. It needs to be named Raven.exe.

3. Revise RAVEN setup files
You will need to further adjust your model setup from the example configuration of HMETS. Raven has five setup files (rvi, rvp, rvh, rvt, and rvc). They are given in examples/raven-my-configuration/model/raven_templates.py. The parameters are indicated with patterns, e.g. {par[x05]} for parameter x₅. There might be also derived parameters they have a separate pattern, e.g. {dpar[sum_x05_x06]} that is derived as the sum of x₅ and x₆. You can chose for the description, e.g. sum_x05_x06, whatever you want but you have to specify the derivation in codes/2_run_model_raven-my-configuration.py (around line 123-126).

4. Specify model parameters
You will also need to specify the parameters, their distribution type (uniform of Gaussian) and their distribution parameters. Distribution parameters are lower and upper bound for the uniform distribution and mean and standard deviation for the Gaussian distribution. The specifications need to be done in examples/raven-my-configuration/parameters.dat. Please use the same order of parameters as you in the examples/raven-my-configuration/model/raven_templates.py. For example, parameter x₅ is {par[x05]} in the template and should be the fifth parameter specified in examples/raven-my-configuration/parameters.dat. The parameter name (first column) is only used for plotting and printing but not in the patterns of the templates. Derived parameters are not specified in the parameters.dat.

5. Change model outputs
The HMETS model tracked three model outputs, i.e. NSE, discharge, and infiltration volume. If you want to change that you will need to make adjustments in codes/2_run_model_raven-my-configuration.py (around line 219-254).

6. Run analysis
Run the Efficient Elementary Effects for your RAVEN configuration using All model outputs stored in the Pickle file ...

./__run_eee.sh -s All -x 2_run_model_raven-my-configuration.py examples/raven-my-configuration/ 

... or for a selected model output Q stored in the Pickle file (Q needs to be a key of the dictionary):

./__run_eee.sh -s Q -x 2_run_model_raven-my-configuration.py examples/raven-my-configuration/