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; options are described below.

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

Use the swap button to switch the selection for model A with the selection for Model B.

When the Read Model File From Git Repository option is selected, the controls start out blank:

Select the Git Repository Explorer button to open the explorer.

In this dialog box, you navigate through the various components of a Git repository with the goal of selecting a file to compare. The four basic steps are: 1) select the folder containing the Git repository, 2) select the branch, 3) select the commit, and 4) select the file.The following sections describe each piece.

It will show the repository for the current model (if there is one) and a history of recently used repositories. Select the button to the right of the Path field to select the folder of the repository. Any folder within the Git repository can be selected. Once selected, the Path field will be populated with the root directory of the repository (i.e. the directory that contains the .git subdirectory).

The Branches list is populated with the names of all locally available branches in the repository. If the desired branch is not visible, then the branch may need to be pulled from the remote Git repository using standard Git tools outside of RiverWare.

Selecting a branch in the list populates the Commits list with the latest 50 commits in that branch ordered from newest to oldest. Each entry displays the commit hash, message, author, and date, though only the first 7 characters of the hash and the first line of the message are displayed in the list. The entire hash and message can be viewed in a tool tip or in a separate dialog by right clicking on a commit and selecting the View Full Commit Message option.

Only the newest 50 commits are loaded. More can be loaded with the Retrieve More Commits button.

Selecting a commit populates the Files list with the files in the commit according to the file display options:

A drop down menu provides the ability to filter by file type. There are three options:

To complete the selection, choose a file and select OK.

The information is now shown in the Models to Compare dialog box:

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.

The bottom portion of the dialog shows which entities and properties in the model file will be compared. A full list of items is described in the Reference on the Entities and Properties Compared below. In general, objects, accounts, slots, slot values, scripts, MRM configurations, 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, which has identical functionality. Access the RPL Set Comparison Tool from the workspace’s Policy and then RPL Set Comparison Tool menu. For more information, see Comparing RPL Sets in RiverWare Policy Language (RPL).

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

The comparison happens when the selection dialog is confirmed or the Refresh button is selected. Afterwards, the tool displays the results of that comparison, which might no longer apply if you have since changed the workspace or deleted the file.

Table 3.2 provides a description of each entity compared, and for each of the entities, the properties that are considered. The asterisk (*) in the Properties indicates the copy property is supported for this property. See Copy Property for more information.

The Model Comparison Tool contains the following areas, as shown in Figure 3.5 and explained by the numbered items:

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.

Recompute the differences between the two models by clicking on the green circular arrow. This is useful if you make changes to Model A or B.

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 3.6:

Green text indicates the property’s value has been replaced in the opened model with the value from the other model. See Copy Property for more information.

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.

Table 3.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; a sample is shown in Figure 3.7.

The following types of filters can be applied:

For each filter criterion, options include the following.

When a filter is applied, the status in the Search and Filters status is updated. To disable all filter, select the red X in the Model Comparison Tool.

One model comparison filter set and one RPL set comparison filter set can be saved in the model file as a “custom set”. This is useful when the same filter criteria are used frequently with a given model. These custom filter sets are accessed from the File menu:

You can also export/import filter sets as described in Export/Import Filter Sets.

Use the File and then Clear Filter Set menu to reset all filters in the Comparison Tool Display Filters dialog back to default values.

Filter sets can also be exported to and imported from separate files. This is useful when different sets of criteria are applicable in different circumstances or when a single set of criteria is useful across multiple models. Filter sets are exported and saved as an XML file.

Use the File and then Export Filter Set menu and then specify an XML file name/path to use. The current filters in the Comparison Tool Display Filters dialog are saved to the file.

Use the File and then Import Filter Set menu to import a previously exported set.

Quickly filter an item out of the results tree using the right-click context menu on the results tree. For example, in Figure 3.8, you don’t want to see any descriptions in the results, so right-click and choose Filter ‘Description’ out of results’.

This action creates a filter in one of the available filters in the Comparison Tool Display Filters:

For objects, you can quickly filter out objects of that name, all objects, or objects of that type (Reservoir, Reach, and so on)

Use the filter dialog, described in Filter Settings, to remove or edit the filter.

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 3.9, there are differences in the Methods on Muddy reservoir. Selecting the Methods row shows the differences in the Selected Properties area.

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.

To view individual differences displayed in the property panel more easily, the following buttons are shown in Figure 3.10 and the corresponding operations are described below:

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 3.11 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.

Once you’ve compared models and identified differences, sometimes you might want to “merge” the two models together. The Model Comparison Tool supports merging by allowing you to select a property item and then chose to copy the value and paste it into the value in the opened model. The operation is essentially:

This operation is enabled only when the following conditions are met:

With a property selected, there are two ways to initiate the Copy Property operation:

When you initiate the action, the value in value shown in the comparison tool is copied and then pasted into the same property in the open model. The dialog is typically opened. The value in the model comparison’s window is not changed. It always shows the result of the last comparison. But the property text is now shown in green and the header shows an exclamation point with a tool tip noting that the property was modified in the opened model. Figure 3.12 shows a sample of the dialog box after a Copy Property operation has occurred.

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.