RiverWISE Model Developer’s Guide
RiverWISE Model Developer’s Guide
Introduction
RiverWISE (RiverWare Interactive Scenario Explorer) is a standalone application for viewing and exploring alternatives of certain specially configured models generated in the RiverWare software. RiverWISE is freely available and easy to use; it does not require the RiverWare software or training.
RiverWISE is automatically installed with RiverWare. Anyone with a RiverWare license can use RiverWISE. Also, stakeholders can obtain a separate RiverWISE license for the exploration process.
There are distinct roles with the following descriptions.
Model developer
RiverWare user who prepares and exports a RiverWare model into a RiverWISE file. This user selects which slots are visible from within RiverWISE, as inputs that can be changed and slot results that can be viewed and analyzed. This user is typically knowledgeable about RiverWare and the particular model being exported to RiverWISE. The model developer communicates with both CADSWES and the stakeholders to facilitate the stakeholder licenses. See licensing and installation instructions at the following location.
Stakeholder
User who opens a RiverWISE file, creates and runs scenarios. We call this person a stakeholder, as they might like to understand a model and explore alternatives. This user may not have any prior experience with RiverWare or the model.
This document describes the exploration process from the point of view of a model developer. See “RiverWISE Stakeholder’s Guide” for RiverWISE stakeholder information.
RiverWare Export to RiverWISE
The sharing process begins within RiverWare, where a model developer conducts a run and then exports the model and results to a special file called a WISE file (*.wise). This file contains everything RiverWISE needs to support stakeholder scenario exploration, including the following items.
• RiverWare model. The RiverWare model, including input and output values corresponding to the last run, policies, and workspace background images.
• Input slots. A list of slots whose input values may be modified by stakeholders, with bounds within which those changes should be constrained.
• Result slots. A list of series slots whose values are visible from within RiverWISE.
• Model/run description. Textual description of the model/run, providing a model background and orientation to stakeholders.
In the rest of this section, we describe in detail how to export a WISE file from RiverWare.
Preparing to Export
Before exporting a RiverWISE file, you should be clear about your goals for scenario exploration. For example, you should identify the following information.
• The stakeholders who will receive the WISE file and have an idea of their backgrounds and interests.
• The baseline run you would like to share, including the run range, policy, and input values.
• The series slots that are likely to be of interest to these stakeholders.
• The sort of alternative scenarios that are both permitted by the model and likely to be of interest to the stakeholders.
Note: RiverWISE does not support optimization or MRM runs.
Keep in mind that RiverWISE is a special-purpose tool designed to be accessible to stakeholders with little or no familiarity with RiverWare, and its interface prioritizes simplicity and clarity over the comprehensiveness and generality of RiverWare. The view of a basin provided by RiverWISE is necessarily narrower than that provided by RiverWare, and so it is important to consider which facets of your model are the most relevant to the stakeholders with whom you wish to share your results.
Once you are clear on these issues, the next step is to modify the model and policies as necessary to permit the desired scenario exploration. You may need to change the model to provide stakeholders with the desired input controls and results, as follows.
Input slots
Perhaps you would like stakeholders to be able to scale the input hydrology up or down by 5%. To do this conveniently, they should be able to specify a value in the range [-5%, +5%] and then have this change all of the series slots representing the input hydrology by that percentage. RiverWISE does not directly provide a way to change all of the values of a set of slots, but it does support editing of a scalar value with a given range. Therefore, to meet this need, you will need to add an Input Hydrology Scale Factor scalar slot to your model, and then write initialization rules that use that value to do the scaling. The Initialization rules should multiply the base hydrology (likely stored on a custom slot) by the scaling factor and set the result on the slot (likely an Inflow slot), at each timestep.
Further, input series slots must actually have values with the “I” or “Z” flag for input. See “Input Slots” for details about specifying input slots.
Result slots
You might wish to add slots that show a specific metric. For example, if you determine that the targeted stakeholders would like to see a particular quantity that is not currently represented as a series slot in you model (say cumulative flow through a particular stream gage over the course of the run), you will need to add a custom expression series slot that computes the quantity. This slot can then be included in the results available for viewing within RiverWISE.
Once you have modified the policy as necessary and provided the desired inputs, the next step is to execute the run whose results you will be exporting.
The Export to RiverWISE Dialog
Once the baseline run is complete and you are ready to export, from the RiverWare main workspace window, initiate the export by selecting the File, then Export to RiverWISE operation. This will open the Export to RiverWISE dialog.
Figure 1.1 shows the Export to RiverWISE dialog.
The remainder of this section describes the parts of this dialog.
Figure 1.1
Last Simulation Timestamp
The top of the dialog displays the date and time of the last simulation. The results from that run that will be exported to the WISE file, so it is advisable to confirm that this time corresponds to your expectations.
Caution: If you have changed the model topology, policy, or any slot values since the last simulation, then you must re-execute the simulation before exporting to RiverWISE; otherwise, the export will be internally inconsistent and conclusions drawn within RiverWISE by stakeholders using the exported WISE file are likely to be incorrect/invalid. To be safe, export should occur immediately after the simulation generating the baseline results.
Export File Specification
Next, specify the folder to save in and the user configurable part of the WISE file name. There are two parts you specify: the folder in which to save and the File Name Root. The resulting file is saved to the specified folder with a name that contains the root and the timestamp at which it is saved. Following are descriptions of these parts.
Export folder
The Folder field specifies the folder path to which the WISE file will be written when the export occurs. There are several options for providing this path, as follows:
• Type it into the text box.
• Copy it from elsewhere and paste it into the text box.
• Select the 
to the right of the text box, displaying a menu of previously selected paths, and select the desired folder from that menu.
to the right of the text box, displaying a menu of previously selected paths, and select the desired folder from that menu. • Select the More button on the far right, which will open a folder selection dialog.
File name root
The File name root is the user specified portion of the file name. Type the desired name in the field. Often you will include a model name and run descriptor; for example, “MyBasinEIS2018”.
Resulting file name
The resulting file name combines the File Name Root with the date/time at which the export occurs. A sample of this file name is shown, but the actual file name is generated at export.
By convention, WISE files use the *.wise extension; the file name has the following convention:
<File Name Root>.YYYYMMMDDHHMMSS.wise
The file name root and export timestamp together uniquely identify the exported WISE file, and in addition to being incorporated into the file name, are stored within the file. It persists when the WISE file is saved after scenario runs are added and when scenarios are exported; see “Save WISE File and Export Scenarios” in RiverWISE Stakeholder’s Guide for details.
The Model or Run Name
The model or run name is a single-line text field into which you should enter a label which describes the particular model and run results you wish to export. RiverWISE displays the model/run name as the primary identifier associated with a particular WISE file.
This field is initialized based on the current model file (workspace) name, but can be edited. This text can contain white space and it need not be unique (that is, it can be the same for multiple exports). But if it isn't unique, then it is likely to be confusing to stakeholders.
When a stakeholder opens a WISE file in RiverWISE, the Model/Run name is used as shown in Figure 1.2.
Figure 1.2
The Model or Run Description
The model or run description multi-line text field may contain a more detailed description of the RiverWare model, the conditions of the particular run that is being exported, and anything else that might be of use to stakeholders using RiverWISE. The first time the Export to RiverWISE dialog is opened, this field is initialized to the Model Info dialog’s Comment.
When a stakeholder opens a WISE file in RiverWISE, it is displayed to the left of the workspace view, as shown in Figure 1.3.
Figure 1.3
The Baseline Scenario Name
The baseline scenario name is the label which will be displayed with the scenario represented by the exported values; that is, the last run. The default value for this field is “Baseline.”
Note: Within RiverWISE, stakeholders that have opened the WISE file you have created can create, name, and delete additional scenarios, but they cannot delete or rename the baseline scenario.
Input Slots
The input slots panel specifies an ordered list of the input slots which stakeholders will be able to modify for non-baseline scenarios. Only scalar, series, and table slots are permitted in this list.
Note: Periodic Slots, Statistical Table Slots and Table Series Slots cannot be exported as input slots.
Series slots must have one or more values with the Input “I” or “Z” flag.
To add slots to this list, select the Add Slots 
button below the panel. This will open a dialog in which you can choose one or more slots to add to the existing list. If a slot that is already in the input slots list is selected when you select the Add Slots button, the new slots will be added after that slot, otherwise they will be appended to the end of the list. Use the Up and Down arrows to rearrange the slots as desired.
button below the panel. This will open a dialog in which you can choose one or more slots to add to the existing list. If a slot that is already in the input slots list is selected when you select the Add Slots button, the new slots will be added after that slot, otherwise they will be appended to the end of the list. Use the Up and Down arrows to rearrange the slots as desired. For scalar and series slots, you may provide lower and/or upper bounds for the slot by selecting the Settings button and then entering the bounds in the appropriate fields. For series slots, default lower and upper bounds are provided.
Note: Series and scalar slots must have bounds to be scaled by a percentage or offset by a fraction within RiverWISE. It is recommended that all slots have bounds.
Tip: In RiverWISE, series slot bounds are shown as horizontal lines on plots.
These bounds will be enforced both when you export the WISE file (that is, the baseline scenario cannot violate the bounds provided for an input slot) as well as within RiverWISE when stakeholders are modifying scenarios they have created.
Figure 1.4
When series slots are added to the input slots list, they are also automatically added to the result slots list, as it is assumed that stakeholders will be interested in viewing these slots.
Tip: The RiverWISE stakeholder will be able to toggle the display units for flows and volumes. Thus, make sure both flow and volume unit schemes are configured as desired.
Result Slots
The result slots panel specifies an ordered list of the series slots whose values stakeholders will be able to view in RiverWISE. Only series slots are permitted in this list as most run results ares held in series slots.
To add slots to this list, select the Add Slots 
button below the panel. This will open a dialog in which you can choose one or more slots to add to the existing list. If a slot is already selected in the input slots list when you select the Add Slots button, the new slots will be added after that slot, otherwise they will be appended to the end of the list.
button below the panel. This will open a dialog in which you can choose one or more slots to add to the existing list. If a slot is already selected in the input slots list when you select the Add Slots button, the new slots will be added after that slot, otherwise they will be appended to the end of the list.Figure 1.5
Do the Export
When the configuration is complete and you are ready to export the WISE file, select one of the export buttons, as follows.
• Export. Create the WISE file.
• Export & Open in RiverWISE. Create the WISE file and open RiverWISE as a separate process. When RiverWISE starts, it will automatically open the WISE file you have just exported.
Note: The RiverWISE file has a model and baseline scenario within it. Depending on the size, it could take significant time to write this file and open it in RiverWISE.
After Export
Once you have created a WISE file, usually you will want to open that file in RiverWISE and verify that it supports model exploration as you intend. This might lead you to change to the model, policy, or inputs, in which case you would need to re-execute before generating a new WISE file, or you might just need to adjust the export configuration before doing another export. For example, within RiverWISE you might realize that there are too many result slots for a stakeholder to easily evaluate, so choose to limit exported results. Conversely, you might decide that it would be useful for them to view additional series slots.
Note: If a stakeholder changes input values in RiverWISE in a way that causes that run to abort, while they will have access to the same error messages that RiverWare would issue, stakeholders will often not be able to effectively interpret these messages. Therefore, you might want to limit the input slots to a manageable set, provide bounds for those inputs, and then test those inputs by running within RiverWISE with a range of input modifications.
Once you are satisfied with the WISE file, you can send it to stakeholders with instructions on how to use it. To use RiverWISE, a stakeholder must perform the following steps.
1. Save the WISE file within their file system.
2. Download the RiverWISE installer from the following location.
http://riverware.org/RiverWISE/index.html
Note: The stakeholder must install the same version that was used to generate the WISE file, so you must provide them with that version number.
3. Install RiverWISE.
4. Obtain a RiverWISE license from CADSWES.
Note: If the stakeholder also has a RiverWare license, he or she does not need a separate RiverWISE license.
Once these steps have been accomplished, the stakeholder should be able to run RiverWISE, open the WISE file, then conduct their scenario exploration, including: view baseline run results, change input slot values and rerun the simulation, compare scenario results with the baseline run, export results, and save scenarios. The stakeholder could then provide you with feedback on the baseline model in the form of a new WISE file that includes additional scenarios they have created. You can then use RiverWISE to reproduce and view their scenario results.
Note: RiverWISE supports the export of a RiverWare model corresponding to the last scenario execution, providing another mechanism for the stakeholder to provide feedback.
Caution: A WISE file represents the state of a RiverWare model at the specific moment in time when the file was generated by the developer. Each scenario applies to a specific original WISE file. It is not possible to import a scenario that was created in a different original WISE file. The naming convention used on *.wise and *.sce files will help you identify which scenarios can be imported into which WISE files. That is, the name and date in the file name, must match.
The File Menu
The File menu has the following options.
Load Settings From File
The File, then Load Settings from File operation initializes the Export to RiverWISE fields from an existing WISE file. When this operation is initiated, RiverWare opens a file chooser dialog in which you can specify an existing WISE file. Once a WISE file has been specified, RiverWare extracts information from that file and uses it to initializes the fields of the dialog to their values when the selected file was exported.
Open RiverWISE
The File, then Open RiverWISE operation opens RiverWISE as a separate process. 
Interactive Scenario Exploration
Use RiverWISE to explore a model, change inputs, and run scenarios. See “Open a WISE File” in RiverWISE Stakeholder’s Guide for details.
Use Cases
This topic describes scenario exploration use cases. For each use case, the Developer and Stakeholder interacts with RiverWare and RiverWISE to accomplish their objectives.
Note: The Developer themselves can play the role of the stakeholder, using RiverWISE to provide additional non-baseline scenarios to stakeholders.
Stakeholder Views Results From a RiverWare Run
In this use case, the stakeholder would like to view some results from a RiverWare run.
1. From RiverWare, the Developer
a. Loads a model
b. Runs the model
c. Exports a WISE file
2. The Developer then provides the WISE file to a Stakeholder
3. From RiverWISE, the Stakeholder
a. Opens the WISE file provided by the Developer
b. Views the inputs and results of the baseline run
Stakeholder Provides Feedback to Developer
In this use case, the stakeholder would like to run their own scenarios and provide one or more scenarios back to the developer with feedback.
1. From RiverWare, the Developer
a. Loads a model
b. Runs the model
c. Exports a WISE file
2. The Developer then provides the WISE file to a Stakeholder
3. From RiverWISE, the Stakeholder
a. Opens the RiverWISE file provided by the Developer
b. Views the inputs and results of the baseline run
c. Creates and runs additional scenarios, compares the results for all scenarios.
d. Exports a particularly interesting scenario
4. The Stakeholder then provides the RiverWISE scenario file (*.sce) to the Developer
5. From RiverWISE, the Developer
a. Opens the WISE file
b. Imports the RiverWISE scenario file (*.sce)
c. Views the inputs and results of the baseline run and compares to the scenario run.
Stakeholder Team Collaboration
In this use case, a team of stakeholders would like to create many scenarios and then bring them together for comparison.
1. From RiverWare, the Developer
a. Loads a model
b. Runs the model
c. Exports a WISE file
2. The Developer then provides the WISE file to a team of Stakeholders
3. From RiverWISE, each Stakeholder
a. Opens the WISE file provided by the Developer
b. Views the inputs and results of the baseline run
c. Creates and runs additional scenarios, compares the results for all scenarios
d. Export one or more particularly interesting scenarios
4. The Stakeholders then provide each other with their new RiverWISE scenario files
5. From RiverWISE, each recipient of a scenario file
a. Opens the WISE file
b. Imports the RiverWISE scenario files
c. Views the inputs and results of the baseline run and the scenario run
Stakeholder Team Provides Feedback to Developer
In this use case, a team of stakeholders would like to create scenarios and then provide them back to the Developer. The Developer can review the scenarios and create a new model and WISE file for additional analysis.
1. From RiverWare, the Developer
a. Loads a model
b. Runs the model
c. Exports a WISE file
2. The Developer then provides the WISE file to a team of Stakeholders
3. From RiverWISE, each Stakeholder
a. Opens the WISE file provided by the Developer
b. Views the inputs and results of the baseline run
c. Creates and runs additional scenarios, compares the results for all scenarios
d. Export a particularly interesting scenario
4. Each Stakeholder then provides the Developer with their new RiverWISE scenario file
5. From RiverWISE, the Developer
a. Opens the WISE file
b. Imports the RiverWISE scenario files
c. Views the inputs and results of the baseline run and the scenario run
d. Exports a new RiverWare model file with the desired new scenario.
6. From RiverWare, the Developer
a. Loads the saved model
b. Runs the model
c. Exports a WISE file
7. The Developer then provides the new WISE file to another interested Stakeholder
8. From RiverWISE, the recipient of the scenario file
a. Opens the WISE file
b. Views the inputs and results of the baseline run and the scenario runs
The Developer Closely Analyzes a Stakeholder Scenario
In this use case, a stakeholder would like to create scenarios and then provide them back to the Developer. The Developer can analyze what the stakeholder has done using the full power of RiverWare. Often this is necessary for debugging an error or problem.
1. From RiverWare, the Developer
a. Loads a model
b. Runs the model
c. Exports a WISE file
2. The Developer then provides the WISE file to a Stakeholders
3. From RiverWISE, the Stakeholder
a. Opens the WISE file provided by the Developer
b. Views the inputs and results of the baseline run
c. Creates and runs additional scenarios, compares the results for all scenarios. Perhaps there is an error in the desired scenarios that prevents it from finishing.
d. Exports a RiverWare model corresponding to a scenario which they would like to analyze in depth from within RiverWare
4. The Stakeholder then provides the RiverWare model file to the Developer.
5. From RiverWare, the Developer
a. Loads the new RiverWare model file
b. Analyzes the results, possibly re-running the model with diagnostics enabled
Revised: 11/11/2019