RiverWare models are saved as text files with or without compression. These files could be viewed and edited with a text editor outside of RiverWare, but their complexity and frequent format changes make direct editing difficult and dangerous. CADSWES neither recommends nor supports direct editing of model files.

Loading a new model clears any existing model on the workspace after prompting the user for verification. In the case of a blank workspace, no verification is needed.

The file chooser filters by commonly used file extensions for Model Files, as follows:

For RPL sets, the filters include the following:

In addition, the user can use asterisks (*) as wildcards in the File name to further filter. Once a file has been selected and the Open button has been selected, the cursor turns into an hourglass while the model is loading. Once the model is loaded a diagnostic window pops up with information regarding the date and time when the model was last saved, by whom the model was saved, and which version (release) of RiverWare.

If the model is configured to display background images in one or more of the Workspace views, then after the model is loaded, RiverWare reads and displays the background image files. While RiverWare is loading these images, a gray placeholder background is displayed in the appropriate views and an animated Busy icon is shown at the bottom of the Workspace. All of the usual workspace interaction is still possible while images are being loaded.

On the Workspace, selecting File, then Reopen Model gives the user previously opened models and directories. This is a quick and easy way to reopen a model. For rulesets there are options to Reopen and Reopen and Load previously viewed rulesets.

Listed in this menu are previously opened models and a list of recently accessed directories. Selecting a directory item (shown with a yellow folder icon) opens up a file chooser initialized to the specified directory. Also shown is a single user-configured default directory (for the specific type of file), based on an environment variable. This directory is shown as a green folder. If this is defined, the file chooser opened using the File, then Open menu will open to that default directory the first time within a RiverWare session. Table 2.1 lists supported environment variables.

There are three ways to save a model in RiverWare: the default Save, Save As, and Save As Baseline.

As models can be large and take up significant disk space, several options are available for minimizing the saved model size.

One option is whether or not to save the model with its calculated output values (series values with the Output or Rule flag). The model file size is greatly reduced if the output values are not saved. This is the recommended option for saving small, frequently run models. Since only the input values are required to reproduce a run, the output may be regenerated by re-running the simulation once the model has been re-loaded. But, if your model is large or takes a long time to run, you will likely want to save results, so that you can look at output values without re-running. Only Save As prompts for whether or not to save output values. The selected choice is then applied for all subsequent Saves until a new model is loaded, the RiverWare session ends, or a new Save As overrides it. The default Save behavior for a new session or model is to save output values. All series slot values with the Input flag (I, Z or i flag) and all values on non-series slots are always saved in the model file with full precision (17 digits).

Precision refers to the number of meaningful digits in a numeric value. In the Save As confirmation, if you select the option to Save Outputs in the Model File, you will also have the option to set the Precision with which to save output values. You can save outputs with 1 to 17 digits of precision. Saving with higher precision will increase model size. In the interface, select the More Information link for additional information about precision. All series slot values with the Input flag (I, Z or i flag) and all values on non-series slots are always saved in the model file with full precision (17 digits).

Although there is no required extension for RiverWare model files, the .mdl extension is often used to identify a file as a model file, and a .rls extension is used to identify a ruleset file.

Further, files that end in the .mdl extension will display the RiverWare model file icon in windows explorer. Double-selecting the icon will open the latest installed version of RiverWare and load that model.

Model files may be automatically compressed when they are saved by giving their file name a .gz extension (the gnu zip compression). When the model is re-loaded, the extension is detected, and the file is uncompressed automatically. Manually compressing and uncompressing files in WINDOWS is accomplished using any zip program such as WinZip. Manually compressed model files which do not have a .gz extension will not be recognized by RiverWare, and will produce an error upon loading. Thus, the .mdl.gz extension is often used to identify a file as a model file and a .rls.gz extension is used to identify a ruleset file when compression is desired.

In Windows, the association between RiverWare and the .gz file extension has not been made because of the general nature of the .gz extension,. You can manually associate .gz files with RiverWare so that RiverWare will automatically open when you double-click a .gz file. To do this (in XP), right-click a .gz file and select Properties. Then select the Change button and select RiverWare from the list of files.

The first time a model is saved to an existing file, a backup of the original file is made. This prevents data loss if an overwrite is unintentional or the save process fails and the model is corrupted. The backup file has the same name as the original with a .bak extension. A single backup file is made for each model. When upgrading to a newer version of RiverWare, the backup model file name will contain the previous RiverWare version number to the model file (e.g., SampleModel.6.5.mdl.gz). This ensures that there will be a model file compatible with RiverWare version 6.5 until the user explicitly removes it.

The automatic backup save utility saves a backup file in a temporary directory at a defined interval. It is strictly a backup save of the model file, and it never overwrites the model open currently.

The feature is configured from the workspace File, then Automatic Backup Save Configuration menu item, which opens the Automatic Backup Save Configuration dialog.

From the dialog, you configure the following:

In all cases, if the Automatic Backup Save is unsuccessful an error message is displayed and Automatic Backup Save is disabled (with a red highlight message in the diagnostics):

If you want to see additional messages on the automatic backup save process, turn on Workspace, then Model Load/Save diagnostic category.

RiverWare performs activities during which an Automatic Backup Save is not appropriate, for example during a simulation. If an Automatic Backup Save comes due during such an activity the Automatic Backup Save feature enters retry mode:

By default the Automatic Backup Save directory is the user's temporary directory. On recent versions of Windows this is:

It's unlikely a user will have write permission for another user's temporary directory. To facilitate sharing models, if a user loads a model file with Automatic Backup Save enabled and doesn't have write permission for the Automatic Backup Save directory, the Automatic Backup Save directory is changed to the user's temporary directory (with a green highlight diagnostic message):

Finally, because the Automatic Backup Save directory might not be obvious to all users, the configuration dialog has a Reset button, which resets the Automatic Backup Save directory to the user's temporary directory, as shown in Figure 2.1.

If the model file has been Automatic Backup Saved, the backup file can be opened by selecting the File, then Open Automatic Backup Save Model menu item. (If the model file hasn't been Automatic Backup Saved, the menu item is hidden.) This is equivalent to selecting the File, then Open Model menu item, navigating to the Automatic Backup Save directory and selecting the backup file.

If the model file name ends with either .mdl or .mdl.gz, the extension is preserved and the backup file name is <file name>.~1~.mdl or <file name>.~1~.mdl.gz. Otherwise the backup file name is <file name>.~1~. If there is not a model file loaded from a named file, the backup file name is Workspace.~1~.

When a model is loaded, a diagnostic window opens with the Model Save History. The model save history appears as a brown diagnostic message with information regarding the date and time when the model was last saved, the username of person who save the model, and the RiverWare version in which the model was last saved. The last save is part of the Model File Information and is stored with the model file when a model is saved. The model save history is automatically updated each time a model is saved.

The save history is also accessible within the Model Info dialog accessed by selecting File, then Model Info from the main RiverWare workspace. This dialog includes the Last Save, Run History and Comment.

The Last Save shows a single line, as information for only the last save operation. This text can be selected and copied to the system clipboard.

The Run History panel lists a user specified number of run history records including

You can control how many run history records to save in the Retain information for N runs field. This panel has a Clear Run History operation to clear all of the records. Because the records are saved in the model file, specifying a large number of runs to save will make the model file larger. Clearing these can recover that space.

The Run History panel allows you to right-click and Copy selected items to the system clipboard. When you paste, you can either paste in a standard formatted (i.e. HTML table) or unformatted tabular form. Figure 2.2 shows a sample of the paste results for an email program.

Enter comments about a model into the Comment section. Like the save history, this information is saved together with the model file. You can write comments or a brief description of a model.

If more than one user is working on a model, then you may want to lock the model when open to prevent others from simultaneously changing the file. To do this, use the File, then Lock Model when Open menu item and then save the model. Then a lock file is created in the same directory as the model. This lock file is also created when the model is opened.

The person who first opens the model is notified that they have locked the model file, which prevents write access by other instances of RiverWare. The lock file is in the same directory path as the model file and has the name of the model plus the .lock extension. When the model is closed, the lock file is automatically removed.

If the model is opened when a lock file already exists, the user is notified that the model file is locked by another instance of RiverWare. The time the lock file was created and the owner of the lock file is shown if that information is available from the system. Then, the model is in a state where the Save functionality is disabled. But, you can still make changes within the opened model and Save As a different name.

When developing a model, it is often desirable to compare a model to some previous version of the model to identify differences. In addition, comparison tools are essential when multiple people are developing a model or there are multiple versions of a model that are to be merged together.

The need for a model comparison tool can be illustrated by the following use case.

The Model Comparison Tool compares many entities of two models. It looks at the properties of the entities and their values. It then shows the differences and allows you to see which items have changed.

Following are the limitations of the Model Comparison Tool:

From the RiverWare workspace, select Utilities, then Model Comparison Tool.

The tool opens and shows a dialog where you specify the two models to compare.

The two models are referred to as Model A and Model B. For both models, choose one of the following:

The middle portion of the dialog shows which entities and properties in the model file will be compared. In general, objects, accounts, slots, slot values, and RPL Sets embedded within the model are compared.

All RPL sets saved or embedded in the model file are automatically compared including:

Those saved as separate files are not compared with this tool, but can be compared using the RPL Set Comparison tool.

Table 2.2 provides a description of each entity compared, and for each of the entities, the properties that are considered.

In the Series Value Comparison region, specify how series data values should be compared. The following choices are available:

If desired, specify an absolute tolerance for numeric comparisons in the Numeric Comparison Tolerance field. The value 1e-10 is used by default to avoid flagging as different those values with very small differences that occur due to machine precision.

When finished, select OK. The tool then performs the comparison and the main Model Comparison Tool is then shown.

The Model Comparison Tool contains four main areas, as shown in Figure 2.3.

The following sections describe these areas and how to use the tool.

The Models panel shows information about the models that were compared, including, for each model, the name (usually the file name), the source (i.e., whether it was the currently opened model or read from a file), and the full file system path. Use the Select Models button to choose different models and initiate another comparison. This opens the Models to Compare dialog; see “Selecting Models to Compare”.

The Type column lists the type of that row: either a Model, Simulation Object (type of object), Type of Slot, Account, DMI item, RPL item or property. The comparison tool ultimately compares Properties of the items, not the items themselves. In the Status column, the color indicates the following meaning. This is also shown in Figure 2.4:

You can search, in either direction, for specific content in any of the three columns (Name, Status, or Type). Use the drop-down menu to specify in which column to search. Type a string into the search field.

Also, the filtering: users now have more powerful mechanisms for limiting the items displayed in the comparison results tree. Previously, there was a single filter control which allowed users to limit the display to items that were not the same in both models. A new filter dialog was created which contains this checkbox as well as controls for limiting displayed items to those with a specific name, comparison status, or type.

Table 2.4 describes the search and filter buttons in the Comparison Results panel.

When displaying results for a large model, there can be many differences. Use the Filter button to set up filters to only see desired items. As shown in Figure 2.5, the following types of filters can be applied:

When a filter is applied, the status in the Search and Filters status is updated. To remove a filter, select the red X.

The Selected Property panel shows the values for the selected property where applicable. If a yellow row (Model, Object, Slot, etc.) is selected, a note is shown that “No Property Selected”. Only property values are shown in these views. When a Property row is selected, the panel shows the values for that property. Depending on which property is selected, its value will be displayed as text, a table of slot value, possibly including a plot, or as a RPL expression. For example, in Figure 2.6, there are differences in the Methods on Muddy reservoir. Selecting the Methods row shows the differences in the Selected Properties area. (This is a character by character comparison of the text, hence there are two differences identified.)

Right-click the property values and choose Copy to copy the data to the system buffer. This works for both text differences and slot values. You can paste these to an email, document, or spreadsheet.

When Values for a series slot are selected, a plot is shown within the Selected Properties panel. The plot shows the entire set of data with two lines, one for each model. Model A data is shown in blue, while Model B data is shown in red. A legend is shown above the data. Figure 2.7 illustrates.

Right-click the plot area for options to Auto-Scale, Zoom, Move, Copy Plot Image, Export Image, or Print. Draw a rectangle on the plot to zoom in.

In RiverWare, only one model can be loaded at a time. To be able to compare two models, RiverWare must create in-memory representations of the two sets of data and values to be compared. If Model A is the opened model, then RiverWare needs to read Model B and then create representations of values that can be compared. To do so, RiverWare synchronously executes the following batch RiverWare process.

A model and associated files can be grouped together and saved as a RiverWare package. These always contain a model file and can also contain ancillary files including the following:

A package is used to group the files together into one file and compress them. This functionality is often used to share a set of files with other users. For example, you can package all the files used with a model and send them to a co-worker. The co-worker opens the package to create all the files in the destination directory and then RiverWare automatically opens them.

Packages are accessed through the Workspace File menu. The Save As Package and Open Package menus on the workspace File menu allow you to work with packages.

The model is not checkable and is always included in the package. This includes the model file and any RPL sets that have been configured to be saved into the model file itself. See “Save Location” in RiverWare Policy Language (RPL) for details on embedding sets in a model.

RPL sets (Rulesets, Goalsets, and Global Functions Sets) that are open and that have been saved as files will be listed as individual options for inclusion in the package. If a set has been created, but not saved to a file, you will get a warning message that the set must be saved to be available in the list.

SCTs that are open and that have been saved as files will be listed for inclusion in the package under the SCT category. You can individually select whether or not to include each SCT from the list. If an SCT has been created, but not saved to a file, you will get a warning message that the SCT must be saved to be available in the list.

If simulation, accounting, or geospatial images are used in the model, they are available as options for inclusion in the model package.

In creating the package, all selected files will be saved to a temporary directory for packaging, as shown in Figure 2.8. When packaging is completed, these files and the temporary directory will be deleted, leaving just the specified package file.

If you have made changes to any of these items since they were last saved to files, the copies made for the package will include these changes, but the original files will not. You must save them in normal RiverWare operation to save the changes to the individual files. But, creating a package saves everything as it currently appears in the session without affecting any of the individual files on disk.

Use the Open Package option in the workspace File menu to unpacks all the files and then open those files into the RiverWare session. This menu opens the Open RiverWare Package dialog, in which you specify the package file to open and a destination directory to which the files will be unpacked.

Once the package file is chosen, a default Destination Directory is shown, which consists of a subdirectory using the name of the package. Change the directory as desired.

The Files in Package list displays the names of the files that are in the package. If files corresponding to these names already exist in the specified Destination Directory, this will be indicated with Yes in the Exists column of the list. If any of the files currently exist, the message at the bottom appears warning that the existing files will be overwritten when opening the package.

When the package is opened, files in the package will be extracted to the specified directory. The model file will be loaded, and RPL sets and SCT files will be opened. If a RPL set was loaded when the package was saved, it will be reloaded when the package is opened. The workspace images loaded with the model will now have the extracted image files as their source. Extracted files are persistent in their directory even after the RiverWare session is closed, so are just like any other set of RiverWare files. The files can be repackaged at any time into the same, or a different package file using the Save as Package functionality described above. See Figure 2.9.