Using the RiverSMART Workspace
The RiverSMART workspace is populated with events, files, and links to create a study. These study building blocks are discussed in the following sections.
Events
RiverSMART is essentially a framework for communication between independent processes or programs, which are called events. On the software level, each event is actually an independent program called a plugin, and an event is an instance of a plugin.
To add an event to the workspace, right-click the workspace; in the shortcut menu, select Add Event and then the event you want to add.
When an event is added to the workspace, it is shown as an icon representing the event type. Following are descriptions of the available events, categorized by function.
RiverWare Event
RiverWare Displays the version of RiverWare used for the study and allows for some options. There must be exactly one RiverWare event per study.
See RiverWare Event for details.
Hydrology Events
Hydrology events allow you to create traces of hydrology data that can be moved into RiverWare through a specified RiverWare Data Management Interface (DMI) event.
Hydrology Simulator Synthesize an ensemble of hydrologic traces at an annual timestep based on observed streamflow values and a user-selected algorithm.
See Hydrology Simulator Event for details.
Spatial Disaggregation Disaggregate an annual ensemble of flow data for a site into ensembles for multiple sites.
See Spatial Disaggregation Event for details.
Temporal Disaggregation Disaggregate an annual ensemble of flow data for a site into a monthly ensemble for the site.
See Temporal Disaggregation Event for details.
RiverWare Input Events
Input events allow you to configure inputs to the model and options for generating scenarios.
Note: The combination of DMIs, models, MRM configurations, and RiverWare policies are user-selectable through the Scenario Organizer.
RiverWare DMI Specify a DMI to use in importing data into the RiverWare model. The input can be a single series, imported before the multiple runs are executed, or it can be trace-based, run as an ensemble. For example, the outputs of the Hydrology Simulator or Demand Input Tool (DIT) can be input to RiverWare through the DMI event.
See RiverWare DMI Event for details.
RiverWare DMI Sequence Specify a sequence of RiverWare DMIs, such as initial conditions, to use in importing data.
See RiverWare DMI Sequence Event for details.
RiverWare Model Specify the name and location of a RiverWare model file to use in generating scenarios.
See RiverWare Model Event for details.
RiverWare MRM Specify an MRM configuration defined in the RiverWare model to use in generating scenarios.
See RiverWare MRM Event for details.
RiverWare Policy Specify a RiverWare Policy Language (RPL) policy set, and optional global function sets, to use in generating scenarios.
See RiverWare Policy Event for details.
RiverWare Run Range Configure run ranges, and an optional R script to adjust the run ranges, to use in generating scenarios. You can configure multiple Run Range events to generate scenarios with different run ranges, such as different start dates, end dates, or timesteps.
See RiverWare Run Range Event for details.
Post-processing Events
Post-processing events allow you to configure options for processing study results.
CSV Combiner Combine comma-separated value (CSV) output data from all scenarios in a scenario set into a single CSV file.
See CSV Combiner Event for details.
or 
GPAT Graphs Execute a specified GPAT Graphs configuration file to generate statistical graphs from Microsoft Excel files that include series data for selected scenarios or scenario sets. The graphs can be written to an Excel workbook.
See GPAT Graphs Event for details.
or 
R Plugin Call user-created R programming language scripts to post-process study results for selected scenarios or scenario sets.
See R Plugin Event for details.
RDF Annualizer Aggregate data from an RDF file with a less-than-annual timestep, to produce an RDF file with an annual timestep.
See RDF Annualizer Event for details.
RDF To Excel Convert output data from an RDF file to an Excel workbook according to a user-defined workbook configuration.
See RDF To Excel Event for details.
General Event Configuration Window Fields
To open the Configuration window for an event, double-click the event icon on the RiverSMART workspace. Following is a sample Configuration window for a RiverWare DMI event.
Note: You cannot configure events and files while also generating, simulating, and post-processing scenarios. If a window for processing scenarios is open in the RiverSMART workspace, you cannot open the configuration window for an event or file.
Name
This field is common to all event Configuration windows. This entry must be unique among all events in the study. A unique name is automatically generated when an event is created, and you can replace it with a user-defined descriptive one.
This entry is displayed on the workspace as a label directly below the event icon; therefore, it should be descriptive but not too long. This entry is also used as a folder name by RiverSMART when it manages files related to the event.
Help
This menu is common to all event Configuration windows. The Help selection displays a context-sensitive Help topic to assist you in completing the configuration window.
Placeholder events
This option is available for input-type events: DMI, MRM, Policy, and Model. Sometimes, the choice of inputs in a study is not just between the type of inputs—for example, high or low demand—but between input or no input—for example, between Supplemental Flow A or no supplemental flow. For these cases, RiverSMART allows you to designate an input event as a placeholder. To do so, select Edit, then Placeholder in the DMI, MRM, Policy, or Model Configuration window.
When an event is designated as a placeholder event, all its configuration options are disabled, except the Name and Category fields for DMI events. The placeholder event is treated as any other input event in its category when scenario combinations are generated; see Generating Scenarios for details. When the scenarios are executed, however, the event does nothing. For example, a placeholder DMI event does not invoke any DMI for its category when a scenario that includes the placeholder DMI event is simulated.
Deleting events
To delete an event from the workspace, right-click the event icon on the RiverSMART workspace and select Delete Event from the shortcut menu; alternatively, select the event and press Delete.
Files
File items specify file names for outputs from events. When linked to a following event, a file item specifies an input file name for that event.
File Configuration Window Generic Fields
To add a file to the RiverSMART workspace, right-click the workspace, select Add File on the shortcut menu, and then select the file type. The following file types are available.
RiverWare Data File. ASCII file representing slot data from RiverWare, typically output to capture data from all traces of a multiple run. 
Microsoft Excel Workbook File. Excel workbook, which may be an output from the RDF To Excel event, or input or output to a GPAT Graphs event. 
CSV File. Comma Separated Values file representing slot data from RiverWare, typically output to capture data from all traces of a multiple run. 
netCDF File. Network Common Data Form file representing slot data from RiverWare, typically output to capture data from all traces of a multiple run. 
To open the Configuration window for a file, open the file icon on the RiverSMART workspace. Following is a sample Configuration window for an RDF file.
Name
This is the label that appears on the RiverSMART workspace below the file icon. This field is common to all file Configuration windows.
The default entry is the descriptive file type, such as RDF or Excel Workbook. You can override this by entering a user-defined label in the Name text box. This entry does not need to be unique.
Filename
To assign the file name, you can enter it in the text box or select it from the menu. The menu lists all files of the applicable type in the model MRM output configurations.
Note: You enter just the file name, not the full path; the full path to an instance of the file is determined by RiverSMART when it processes a scenario.
Deleting a file
To delete a file from the study, right-click the icon on the RiverSMART workspace and select Delete File from the shortcut menu; alternatively, select the file and press Delete.
Linking
You create links on the workspace to represent how information flows between events and files. The link arrow indicates the direction of the link.
In some cases, you can link an event directly to another event; but in cases where the event output is preserved as a file, you can link the event to a file item, which can then be linked to a following event. Hydrology events link directly to each other; RiverWare input events link directly to RiverWare; and post-processing events link through file items.
To create a link, right-click an event or file, select Link in the shortcut menu, and then use one of the following methods.
• The menu lists destinations that are valid for the starting item based on the valid inputs and outputs for its file type and the permitted number of input and outputs. If you select a destination from the menu, the link is automatically created between the starting item and the selected destination item.
• If you select Begin Link, a black rubber-banded line is attached to the starting item; then as you hover over other events or files, the line turns green if it is a legitimate destination, or red if it is not. To complete the link, right-click a legitimate destination and select Create Link in the shortcut menu.
To delete a link, right-click the link line and select Delete Link in the shortcut menu; alternatively, select the line and press Delete.
Adding Text
You can add text to the workspace to identify items that can be grouped together, or to add other information.
To add text, right-click the desired location on the workspace and select Add Text in the shortcut menu. Enter the desired information in the text configuration window. Line beaks will be respected. Click OK to close the Text Configuration. You can drag the text to any location on the workspace. To edit the text, double click to open the text box. To delete the text, right-click the text box and select Delete Text in the shortcut menu; alternatively, select the text and press Delete.
You can select one or more text items and use the controls in the workspace toolbar to modify their color and font size. Any new text added to the workspace uses the font size and color selected in the toolbar.
Multiple Selection
Use one of the following methods to select multiple events, files, or text items.
• Click and drag over the items.
• Ctrl+click multiple items.
When you right-click the selected items, the shortcut menu applies to all selected items.
Copy and Paste
You can copy selected events, files, and text items to the system clipboard, and then paste them anywhere in the current study. The spatial relationships among the selected items are preserved, as are any links.
To copy items to the system clipboard, right-click the selected items and select Copy from the shortcut menu. The exact wording of the Copy option varies according to the selected items.
To paste items from the system clipboard to the current study, right-click the workspace and select one of the following options from the shortcut menu.
• Here—Pastes the items at the current cursor position, which is the upper-left corner of the pasted items.
• Left of the Study—Pastes the items centered on the left border of the study.
• Right of the Study—Pastes the items centered on the right border of the study.
• Above the Study—Pastes the items centered on the top border of the study.
• Below the Study—Pastes the items centered on the bottom border of the study.
After you paste the items, they remain selected so you can adjust their placement.
You can also copy and paste items to and from external applications that support the system clipboard; for example, text editors and email clients.
File Menu
The File menu in the RiverSMART menu bar includes menu items to open and save study files. The Reopen Study menu lists the six most recently opened study files and folders.
You can select files and folders by selecting them on the menu or by entering their number. Selecting a file opens the study file, and selecting a folder opens the File Chooser in the folder.
Workspace Menu
The RiverSMART Workspace menu includes options for controlling the collection and display of diagnostic messages, validating the configurations of the events and files in the workspace, and clearing the workspace.
Diagnostic messages are displayed in the RiverSMART Diagnostics window, and they are color-coded as follows:
• Black—informational
• Gold—warning
• Red—error
The Diagnostics File and Edit menus include options to save diagnostic messages to a file, copy diagnostic messages to the system clipboard, and clear all diagnostic messages.
The Validate Study option on the Workspace menu validates the configurations of the events and files shown on the workspace. Validation varies with the event or file, but generally includes verifying that required configuration information is provided and that referenced files that should already exist are available and readable.
Validation messages are displayed in the Study Validation window, and they use the same color coding as diagnostic messages.
The Study Validation File and Edit menus provide the same options as the Diagnostics window.
The Study Validation Column menu hides or shows the Type column.
The Clear Workspace option on the Workspace menu removes all events, files, links, and text from the workspace.
Workspace Zoom
Controls on the toolbar allow you to zoom in and out of the workspace in increments of 10 percent, within the range of 10%–400%. The current zoom percent is displayed next to the controls.
Scenario Window Geometry
The size and location of the four scenario windows—confirmation, organization, simulation, and post-processing—are saved so they always open using the same size and placement on the workspace. This geometry persists across RiverSMART sessions.
To reset the window geometry to the default settings, select Workspace, then Options; alternatively, select the Options button on the RiverSMART toolbar.
In the Group area of the Options window, select Windowing, then Geometry. Under Reset the Following, select the Scenario Window Geometry check box, then select Reset.
Status Bar
The Status Bar, near the bottom of the workspace, includes the following elements.
• Study status area (blue background). For example, “Executing event RiverWare”.
• Event status area (green background). For example, “Simulating scenario C Inflow 2, E Inflow2, R Inflow1, T Vs, CRSS Policy 2”.
• Event progress bar. This displays the percent complete if the event is able to do so; otherwise, this bar functions as a busy indicator.
• Diagnostic Window. This button provides a graphical indication of whether there are warning or error messages that have not yet been viewed by users. Not yet viewed means users have not opened the RiverSMART Diagnostic window since the messages were posted. You may need to scroll the Diagnostic window to view the messages.
– Normally, this button displays a Log File icon.
– If the Diagnostic window includes warnings that have not yet been viewed, the button changes to the warning color and blinks.
– If the Diagnostic window includes errors that have not yet been viewed, the button changes to the error color and blinks.
RiverSMART Workspace
Figure 2.1 is a sample configured workspace with events, files, and links. This example study shows two sets of hydrology events, which are linked in the upper-right portion of the workspace.
Only one RiverWare event is allowed in a study. In the example, RiverWare inputs are linked to RiverWare, on the left side of the workspace, with DMIs grouped into Demands, Supplies, and Evap. RDF files coming out of RiverWare are post-processed through a series of events and files, on the right side of the workspace, to produce GPAT graphs in Excel workbooks.
Figure 2.1 Sample configured RiverSMART workspace
Approaches for Setting Up RiverWare Inputs
When you configure a study, you must consider what to configure in the RiverWare model versus what to configure as inputs in RiverSMART. This is particularly true for MRM and DMI configurations.
MRM configurations in RiverWare can specify initialization and per-trace DMIs, as well as policy. One approach is to create a RiverSMART event for a RiverWare MRM configuration that includes these components and not include the DMIs and policy as events on the RiverSMART workspace. This hides the scenario components, however, and prevents them from being displayed in RiverSMART. To view the DMIs and policies, you need to open the RiverWare model, which reduces the usefulness of RiverSMART for visualizing how inputs are combined into scenarios.
A more transparent approach is to create DMI and policy events in RiverSMART to be paired with an MRM configuration event. RiverWare substitutes the DMIs and policy configured in the RiverSMART events into the MRM configuration to create the scenarios. In this approach, the RiverSMART workspace provides a visual representation of how the scenario components are combined into scenarios.
As an example of DMI configuration trade-offs, consider the four demand DMIs in Figure 2.1. These could be Excel Database DMIs, in which the data for each demand is included on a separate worksheet in an Excel workbook.
One approach would be to set up four DMIs in RiverWare and have each DMI event in RiverSMART refer to one of the RiverWare DMIs by name. To set up the DMIs in RiverWare, you would need to repeat much of the same configuration information four separate times: you would need to repeat the Excel dataset configurations, each of which specify a different worksheet in the same Excel workbook, for each DMI; more importantly, you would need to repeat the slots into which the demand data is imported. This would involve possibly hundreds of slots, and it would be a tedious and error-prone process to keep their begin dates, end dates, and units consistent across all DMIs. Figure 2.2 shows a sample RiverWare configuration of an Excel Database DMI with slot selections.
Figure 2.2 Sample RiverWare configuration of Excel Database DMI
A better approach is to create one dataset and one DMI in RiverWare, to serve as a template for RiverSMART to use for each scenario. You can configure the Excel dataset to refer to the Excel workbook, leaving the Single Run Name (worksheet name) blank, as shown in the following figure.
The RiverWare DMI then uses this template dataset, including the slot selections shown in Figure 2.2. The four RiverSMART DMI events refer to the RiverWare DMI, but each specify a different worksheet name to be substituted into the template dataset for that particular demand, as shown in the following figure.
Using this approach, you need to maintain just one dataset and one DMI in RiverWare. RiverSMART can use these as a template and substitute the correct worksheet for each demand as configured in its DMI events. A disadvantage of this approach is that you cannot run the demand DMIs interactively from RiverWare without inserting the missing information into the template manually or through a script.
Revised: 12/06/2024