A scenario is a specific combination of RiverWare inputs that create a RiverWare run. The generation, simulation, and post-processing of RiverWare scenarios are controlled from the Scenarios menu in RiverSMART.

The Scenario List Organizer allows you to define scenarios from all potential combinations of inputs linked to RiverWare. To open this utility, select Scenarios, then Generate Scenarios (or Regenerate Scenarios) on the Scenarios menu.

A column is created for each RiverWare input category. In the example, the RiverWare DMIs have been assigned one of three category names in their configuration windows, so these categories show up as separate columns: Supply, Demand, and Evap.

The scenario name is automatically formed by concatenating the column names from left to right. By default, the columns are displayed in alphabetical order, but you can drag them into any order that is useful for identifying the scenarios.

You can make additional changes to scenario names by selecting Edit, then Scenario Name Configuration. The Scenario Name Configuration allows you to select the columns to include in the scenario name. It also allows you to define the separator between the components.

In this example, the same MRM Configuration and Model are used for all scenarios, so including them in the name adds no meaningful information to help differentiate among scenarios. The check boxes for these elements are therefore cleared to exclude them from the name. A comma is selected as the separator in the Components Are Separated By menu. An example scenario name is displayed at the bottom of the window.

As shown in Figure 2.3, the Scenario List Organizer indicates that 24 scenarios have been created from the combination of inputs to RiverWare. Not all of these combinations are meaningful, however—for example, VIC Evap should only be used with VIC supplies. Only 24 scenarios among the 24 should be run for this model.

To eliminate unwanted combinations, you can select the unwanted scenarios and deactivate them. To select scenarios, select Check and then one of the following options:

Once you have selected unwanted scenarios, you can deactivate them by selecting Edit, then Deactivate Checked Scenarios. When a scenario is deactivated, it is made unavailable throughout RiverSMART and is not displayed in any RiverSMART windows.

If you deactivate a scenario by mistake, you can reactivate all scenarios by selecting Edit, then Activate Inactive Scenarios. You can then select the correct ones and deactivate them.

You can also dynamically hide and show active scenarios in the current window. Hiding a scenario does not deactivate it; it simply hides the scenario in the current window and does not affect other windows.

To hide active scenarios, select the rows, then select View, then Hide Checked Scenarios. To show all active scenarios, select View, then Show Hidden Scenarios.

The status line at the bottom of the window displays the number of scenarios active, shown, hidden, and currently selected.

The Scenario List Simulator is the main interface used to simulated scenarios.

Access the window using the Scenario and then Simulate Scenarios menu.

The Scenario List Simulator has two main panels, one for showing the scenarios and their status and one for diagnostics:

The top panel displays a two-level tree view that lists the activated scenarios at the top level. Within each scenario, the activities that have been completed during simulation are listed. To open this window, select Scenarios, then Simulate Scenarios on the RiverSMART menu.

To initiate a RiverWare MRM run using the scenario inputs, select the scenario check box, and then select Scenarios, then Simulate Checked Scenarios.

MRM runs are typically set up as distributed runs. If they are not set up that way, they are automatically converted into distributed runs using the default number of processors on the machine. If you select more than one scenario in the Scenario List Simulator, each one runs sequentially until all are completed.

If you need to halt execution while scenarios are running, select Scenarios, then Stop Simulations. The current scenario is allowed to finish, and subsequent scenarios are prevented from executing before they start.

Before simulating scenarios, RiverSMART examines each RiverWare model file configured in the scenarios being simulated. If any RiverWare model file has informational diagnostics enabled and the setting enabled to warn about those diagnostics (RiverWare Model Configuration), RiverSMART posts the confirmation shown in Figure 2.4 asking how to proceed.

To simulate scenarios with the model files as they are, select Continue Simulating.

To disable diagnostics and continue, select the middle button, Simulate without Info Diagnostics. This setting is not saved in the original model file.

To cancel the simulation, select Cancel.

You can also select Don't show this dialog again during this session and RiverSMART won't open this confirmation dialog. The setting is only for the session; it isn't saved in the study.

See also RiverWare Model Configuration and the setting to enable or disable this checking on a per-model basis.

During simulation, the RiverWare Distributed MRM window is displayed. This window displays the progress of the runs as follows:

Additional information on use of iterative MRM is in Using Iterative MRM configurations.

For any type of simulation, if you need to interrupt a scenario while it is running, select Stop or Stop All.

The Scenario List Simulator window displays detailed information for each scenario simulated in a two level tree view. When a scenario tree view is expanded, the activities for a simulated scenario are displayed. An activity represents a step in the scenario simulation, such as initializing the model, executing the distributed MRM controller, or simulating traces. A green check mark indicates the activity was successful; a red check mark indicates the activity failed, and an orange check mark indicates the simulation succeeded with a warning. Selecting the simulation displays the warning. A second level shows the results of the individual Traces or Index Sequential Method (ISM) runs. We recommend expanding the activity lists for simulated scenarios and reviewing the activity details for any issues.

The following annotated screenshot shows the various status values for the activities. See the explanation after the figure.

When you select a scenario, the status line displays the current status information for that scenario, including any warning messages, if applicable. Also, the relevant diagnostics are shown in the bottom diagnostics panel.

The following actions are supported on the list view.

When you select an activity, its status is displayed in the status area and the diagnostics are shown in the diagnostics panel. This may be useful in troubleshooting issues for failed RiverWare activities. The following figure shows traces that have succeeded and the resulting diagnostics. It also shows the tool tip for the ISM run activity button.

See Diagnostics Panel for more information on diagnostics.

The following figure shows a failed run.

The red circle X indicates the MRM run failed. If you have selected in the MRM Event to Save Model Files after unsuccessful runs, double-click the RiverWare icon and it will start RiverWare and load the save model. This allows you to debug the model more directly. Right-click for all of the options.

You can manually override the Run icon status by selecting Scenarios, then Mark Checked Scenarios As Simulated or Mark Checked Scenarios As Not Simulated. For example, if a scenario simulation is successful, but the study is not saved afterward, the Run icon is gray when the study is reopened. You can correct this by manually setting the Run icon green.

The Scenario List Simulator window also provides options to deactivate or activate, and dynamically hide or show scenarios. These options function in the same manner as those on the Scenario List Organizer.

Deactivating a scenario makes it unavailable throughout RiverSMART and removes it from all RiverSMART windows. To deactivate scenarios, select the scenarios, and then select Edit, then Deactivate Checked Scenarios. To activate all inactive scenarios, select Edit, then Activate Inactive Scenarios.

Hiding a scenario does not deactivate it; it simply hides the scenario in the current window and does not affect other windows. If many scenarios have run successfully, you may want to hide them to reduce clutter on the workspace. To hide active scenarios, select the scenarios, and then select View, then Hide Checked Scenarios. To show all active scenarios, select View, then Show Hidden Scenarios.

The lower portion of the Scenario List Simulator contains the diagnostics for the selected activity. Select a row in the upper panel and see diagnostics in the lower panel. You can also double-click the button to open the diagnostics in a separate window, but the same robust searching and filtering is not supported in the separate window.

Then, search and filter as needed to find the desired diagnostics. The following sections describe the searching and filtering capabilities for the diagnostics panel. In general, the functionality is similar to the Diagnostics window in RiverWare.

There are two approaches used to find messages: Search and Filter. Search to look for a specific text string row by row. Filter to show all rows that match the text string. (You can also search on filtered results) The two approaches share the text entry field.

The Search controls include: the following:

Filtering allows you to show only those lines that match the specified text. The Filter controls include the following buttons:

The only direct indication that messages are being filtered is the Clear Filter (red “X”) button being enabled and discontinuous line numbers in the message list.

Enter your desired search/filter text pattern in the text box. This is an editable menu to support a history of recently applied patterns.

When typing in the entry field, hitting Enter is equivalent to selecting Search Forward, and pressing Shift-Enter is equivalent to selecting Search Backward.

The following options apply to both the Search and Filter functions.

A given message line matches the pattern if the line text contains the pattern. (This is different from the pattern matching the entire line of text).

The following is the definition for wildcard pattern matching (i.e. not RegEx):

Regular Expression (“RegEx”, “regex” or “regexp”) pattern syntax is an advanced, potentially complex pattern matching format developed originally with Unix-based tools. It’s not described further in this document but is widely referenced online.

RiverSMART saves all scenario simulation results to the Study Folder you have specified, using the following structure.

In addition, if configured, when a scenario simulation is run, keyword/value descriptors are created to characterize the scenario and its input events. These descriptors are written to the MRM configuration in the RiverWare distributed model as MRM descriptors. From there, they are optionally available as outputs to CSV and netCDF files from the multiple run. Descriptor keyword/value pairs are created as follows:

User-created keyword/value pairs from the RiverWare MRM event window are also included.

Scenario outputs (RDF, CSV, NetCDF, Excel, and R Script output files) can be archived as ZIP files in user-specified archive folder. Archiving is useful if you want to conserve disk space or share outputs.

To configure archiving, select Workspace, then Options from the RiverSMART menu; alternatively, select the Options button on the RiverSMART toolbar.

In the Group area of the Options window, select Archiving to configure when and how to archive successful scenarios.

When scenarios are generated, simulated, or post-processed, the scenario order is determined by the order of the RiverWare inputs, with the leftmost input changing least frequently, and the rightmost input changing most frequently.

By default, scenarios are displayed in ascending alphabetical order, as shown in the following figure.

To display scenarios in descending alphabetical order, select Descending Z-A.

To display scenarios in a custom order, select Custom, then use the Up and Down arrows to move selected scenarios up and down one row at a time.

When input events (DMI, MRM, Model, or Policy) are modified, RiverSMART provides visual indicators to identify portions of the study that are out of date. If any item in an input event configuration window is modified, other than the name, the event label turns red to indicate that scenarios in which the event is included must be regenerated.

If a new input event is added to the study, its label is also red, indicating that scenarios must be regenerated to incorporate the new event.

You can also manually indicate that an input event has been modified. This is useful when external files, such as a ruleset or data files, are modified, because RiverSMART is not aware of these changes. To indicate that an event has been modified, select Edit, then Externally Modified in the event configuration window. This has the same effect as modifying the event configuration: the event label turns red, and RiverSMART indicates that scenarios in which the event is included must be regenerated to bring the study up to date.

As an additional indication that scenarios may be out of date, in the Scenario List Simulator and Scenario List Post-Processor, any scenario that includes a modified event is displayed in red text. Scenarios not affected by changes to input events remain black.

To update all scenarios that have had input events modified, you must regenerate scenarios. On the RiverSMART menu, select Scenario, then Regenerate Scenarios.

The Scenario Confirmation opens, listing the number of scenarios to be added, removed, invalidated, or unaffected, based on modifications made to input events since the last time scenarios were generated. To expand a row and list the scenarios in that category, select the arrow next to the row.

Each category description includes the number of inactive scenarios. To display inactive scenarios, select the Show inactive scenarios check box. Inactive scenarios are shown as unavailable (dimmed).

The Scenario Confirmation includes information to assist you in making informed decisions about regenerating scenarios.

The following discussion relates to the example in Figure 2.6.

In the example, pink highlights indicate scenarios to be removed, and green highlights indicate scenarios to be added. Out-of-date scenarios, whose results will be invalidated, are highlighted to indicate the input events that caused them to be out of date.

Green Run status icons identify the scenarios that have been successfully simulated. Removing these scenarios or invalidating their results could represent a loss of significant time and effort, and the simulation status informs you of this potential loss.

You can modify some input events to add scenarios without invalidating existing ones. For example, in the DMI Sequence event, extending the sequence adds scenarios without invalidating existing scenarios; however, because of the way it generates scenarios, RiverSMART cannot recognize the distinction and therefore includes the existing scenarios with the ones whose results will be invalidated.

In this example, the “InitCond” DMI sequence event was modified to add scenarios with initial condition “Borg02”. This causes scenarios with initial condition “Borg01” to be out of date. The user removed the check from the box for the “Baseline\Borg01” scenarios to preserve their results, which eliminates the need to re-simulate those scenarios. The user checks the boxes for all “C1” scenarios because they are also out of date due to the “C1” demand being modified.

When you select OK to regenerate the scenarios, all options configured in the Scenario List Organizer are reapplied; see Generating Scenarios for details. Once scenarios are regenerated, all event labels and scenario names in the Simulator List Simulator and Scenario List Post-Processor windows return to black. Any added scenarios and scenarios that had results invalidated by the regeneration display a gray Run status icon, indicating the scenario needs to be resimulated. Unaffected scenarios continue to display the Run status they displayed before the scenarios were regenerated.

At this point, scenarios with a gray Run status icon can be resimulated and post-processed. Scenarios with a green Run icon do not need to be resimulated because their results were not affected by the changes to the input events.