Sensitivity Analyst

Sensitivity Analyst is a powerful utility for exploring model response and for identifying optimal parameter sets. The Sensitivity Analyst program runs Vflo™ for a range of parameter values and generates peak discharge, volume, and time-to-peak as output for each parameter combination. The four parameters for which model sensitivity is tested include: hydraulic roughness, infiltration rate (hydraulic conductivity), initial saturation, and rainfall rate.

Three files are required: 1) a BOP file, 2) a RRP file (multiple RRPs can also be used), and 3) a configuration file that defines the parameter ranges and steps. The BOP file and RRP file may be those used for the Vflo™ model. Peak discharge, time to peak, and volume will be calculated for all watch points established within the specified BOP file. For this reason, it is important to establish all desired watch points before saving the BOP file to be used for Sensitivity Analyst. The configuration file is developed by the user to express the parameter ranges for which Vflo™ will be run. A sample configuration file is included with the software as a template for creating configuration files.

Sensitivity testing will be more efficient and meaningful if the BOP file used has already been well calibrated in Vflo™, and if choices for the initial degree of saturation and rainfall scalars may be set based on a priori information derived from other sources such as model, gauge, or satellite measurements. Even without this a priori information, however, Sensitivity Analyst is a useful exploratory tool for finding optimal parameter scalars.

Sensitivity Analyst may also be used with other calibration methods that explore parameter space by Monte Carlo or genetic search algorithms. Because the stand-alone program can be run in batch mode, automatic search algorithms can interact with the program by making changes to the configuration file in order to identify model results that best reproduce observed behavior in terms of peak discharge, timing, and volume.

One possible method for calibration of a physics-based distributed hydrologic model is the Ordered Physics-based Parameter Adjustment (OPPA) method described by Vieux and Moreda (2003). Sensitivity Analyst may be used within an OPPA framework. This involves adjusting the runoff volume first, then adjusting time-to-peak and peak discharge.

Besides rainfall input, hydraulic conductivity has the most control on runoff volume. Overland hydraulic roughness affects both the peak and arrival time of the peak. Channel hydraulics can be used to fine-tune arrival times and, to a lesser degree, the peak discharge. Selecting the most representative degree of saturation will affect model results, and should be accurately specified. As with any watershed model calibration, the goal is to find a parameter set that consistently produces accurate results for multiple events.

A Sensitivity Analyst license must be present in the Sensitivity Analyst directory in order to run Sensitivity Analyst. To order Sensitivity Analyst, contact Vieux & Associates, Inc.

Preparing required BOP and RRP files

For instruction on preparing BOP files, see Overview: Building a Vflo™ model. Be sure to establish all cells for which results are desired as watch points.

For instruction on preparing RRP files, see Overview: Precipitation.

Preparing a configuration file

A configuration file must be assembled before Sensitivity Analyst may be run. The configuration file tells Sensitivity Analyst the BOP file, RRP file, parameter values, and analysis options for which the Vflo™ model is to be tested. A configuration file template named Config.txt is provided with the software. Use any text editor to edit the configuration file so that it specifies the desired BOP, RRP and parameter ranges. A sample configuration file is shown below. A name other than the default configuration file name may be used, so long as it is specified correctly in the Sensitivity Analyst command line, as described here.

Sample Configuration File Available here

In the configuration file, parameters (located under the <Parameters tag) are established in seven groups. First, the BOP and RRP files to be used are established. Second, maximum and minimum scalar values are assigned for four parameters: 1) hydraulic roughness, 2) infiltration rate (hydraulic conductivity), 3) initial saturation, and 4) rain rate. Each parameter is assigned a numeric value or name that must be surrounded by a single quote ('). Second to last, analysis options are specified. Finally, the output file name is specified. The output file will be saved to the same directory where Sensitivity Analyst and the configuration file are saved, unless otherwise specified by entering an alternate, complete address for the output file in the configuration text.

Roughness, infiltration rate, and initial saturation parameter adjustments are only applied to overland cells, and not to channel cells. The rain rate parameter is applied to all cells. Roughness, infiltration rate, and rainfall are multiplicative factors that are applied to the existing values in the BOP file. Initial saturation values are treated explicitly, however, rather than as factors. For example, if you specify an initial saturation minimum of 0.1, a maximum of 0.9, and a step of 0.2, Sensitivity Analyst will solve with initial saturations of 10%, 30%, 50%, 70%, and 90%.

Initial degree of saturation affects model results only if all Green and Ampt infiltration parameters are contained in the BOP file. Note that if a constant rate (hydraulic conductivity) infiltration parameter is applied in the BOP file, then the initial degree of saturation scalar adjustment will have no effect.

Step-by-step instructions

1. Open the sample configuration file provided with the Sensitivity Analyst software.

A new configuration file may also be generated, provided that it follows the formatting of the sample configuration file, is located in the same file as the Sensitivity Analyst executable, and is identified by name in the Sensitivity Analyst command code, as described below.

2. Enter the BOP file for which Vflo™ will be tested.

Following the text BOP=, enter the name of the BOP file to be used. If the BOP file is not in the same directory as the Sensitivity Analyst program executable, the full path to the BOP file must be specified (e.g., C:\Vflo\Projectname\SensitivityAnalyst\yourbasin.bopx). Remember to add the .bopx (or .bop) extension for the file name. For optimal results, use a well calibrated BOP file with all desired watch points for analysis established.

3. Enter the RRP file for which Vflo™ will be tested.

Following the text RRP=, enter the name of the RRP file to be used. If the RRP file is not in the same directory as the Sensitivity Analyst program executable, the full path to the RRP file must be specified (e.g., C:\Vflo\Projectname\SensitivityAnalyst\event1.rrp). Remeber to include the .rrp extension in the file name.

4. Enter range and interval for each parameter.

Values entered for minimum and maximum should be scalar multipliers between 0.01 and 5.0, inclusive, with the exception of initial saturation values. Initial saturation values should be entered as actual minimum and maximum parameter values, not scalars, ranging between "0" and "1". Be sure to include single quotes (') around each parameter value. The values applied range from the minimum to the maximum at the step specified.

For example, multiplicative factors of 0.5, 1.25, 2, and 2.75 will be applied to the roughness parameter map values contained in the BOP file by setting these variables to:

MinRough = ‘0.5’

MaxRough = ‘2.75’

RoughStep = ‘0.75’

If the initial degree of saturation is known, then enter that value for MinSat and MaxSat (e.g., if initial saturation is known to be 50%, then enter 0.5 for MinSat and MaxSat).

The rain parameter acts as a rainfall bias adjustment. Radar rainfall is often adjusted using rain gauges to make a mean filed bias correction. If Vflo™ rainfall input has already been satisfactorily adjusted, then the rain scalar may be set to a value of 1.0. If rainfall bias correction has not occurred or requires further refinement, choose a rain factor between 0.01 and 5.0.

5. Specify channel routing method and prediction length.

Insert True beside the text Jones= to implement looped rating curves. Insert True beside the text Mod-Puls= to apply the effect of channel storage on flood wave propagation.

After Prediction=, enter the number of hours after the end of rainfall to solve Vflo™ for. Using a sufficiently long period for this variable is important for proper integration of runoff volume under the hydrograph curve and for detection of the peak discharge and time-to-peak. If too short a period is specified by the Prediction variable, then incomplete or erroneous estimates of model output and sensitivity may result, especially for volume estimates derived from the integration of the discharge hydrograph. If too long a period is specified, then computational time increases unnecessarily.

6. Specify output file name.

Following the text Output=, enter the name of the output file. If the file is not to be saved in the same directory as the Sensitivity Analyst program executable, then the full path to the file must be included. It is recommended to end the file name with the .txt extension.

7. (Optional) Make Sensitivity Analyst run faster by refining parameter ranges.

If obtaining results faster is desired, then consider narrowing the ranges for which parameters are being tested. To determine the total number of iterations for which Sensitivity Analyst is being run:

a. For each parameter, take the max minus the min value, divide by the step, then add 1.

For example, if the minimum is 0.1 and the maximum value is 0.9, the difference is 0.8. Dividing 0.8 by 0.2 and adding one yields five. Thus, the number of iterations for which Sensitivity Analyst is run is five, for that parameter.

b. Multiply the parameter iterations together to determine the total number of parameter sets run by Sensitivity Analyst.

For example, if roughness is set for five iterations, infiltration is set for four iterations, initial saturation is set for six iterations, and rainfall is set for one iteration, then the total number of iterations will be 120.

If the number of iterations is unnecessarily high, consider running a few trial solves in Vflo™ with representative scalar calibration values to judge the range of scalar values that will generate the best results.

Running Sensitivity Analyst

To generate results, run the Sensitivity Analyst batch file (*.bat), located in the same directory as the Sensitivity Analyst executable.

Step-by-step instructions

1. Check that all required files are present and properly formatted.

Ensure that the Sensitivity Analyst executable, the Sensitivity Analyst license, and the properly prepared configuration file are present in a single file.

2. Open the Sensitivity Analyst batch file.

A command line like this one will appear. The command line consists of the executable file name, the units used, and the configuration file name.    

C:\Program Files (x86)\VAI\Vflo 6.0\vflo6-sensi.exe  sensi_config.xml

3. After the executable address, enter a space, then enter the desired unit mode: either metric or english.

The address and units should be separated by a space.

4. After the units specification, enter the name of the configuration file.

The units and configuration file entries should be separated by a space. If no configuration file is specified on the command line, then the default file will be used.

5. Run the Sensitivity Analyst batch file.

Hit ENTER to run Sensitivity Analyst.

Viewing output

Once Sensitivity Analyst is finished solving, the output file will appear in the Sensitivity Analyst file. Output will resemble the data below, which shows results for a single Sensitivity Analyst iteration. In this Sensitivity Analyst run, BOP and RRP files for the Blue River Basin in Oklahoma were used. In the Blue River Basin BOP file, fourteen watch points had been established: Blue River/CS1, CS2, CS3, CS4, CS5, CS6, CS7, CS8, CS9, CS10, CS11, CS12, CS13, and CS14. These watch points are listed in order at the beginning of the output file. The full contents of the output file are as follows:

1. BOP file watch points are listed.

2. Parameters are listed in the order for which calibration values will be reported.

For this file, RainCal, Init Sat, Inf Cal, and Rough Cal are listed.

3. Output data types are listed for each watch point.

For this file, Peak(cfs), Time of Peak, and Volume(ft³) are repeated fourteen times, once for each established watch point.

4. Parameter scalars/values are listed in order.

For this file, Sensitivity Analyst was run with a rain calibration factor of 0.5, an initial saturation value of 0.1, an infiltration calibration factor of 0.5, and a roughness calibration factor of 0.8.

5. Output data is listed for each watch point, in order.

For this file, the peak, time of peak, and volume are listed for each watch point in succession. For example, the peak flow for watch point Blue River/CS1 is 1197.2006798085627 cfs; the time of peak is 1997/03/25 19:15, and the volume of the hydrograph over the solve period specified in the configuration file is 9.891943961495896 x 10⁷ ft³.