Model Comparison Tool
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.
Model Comparison Use Case
The need for a model comparison tool can be illustrated by the following use case.
1. Bob acquires a copy of the current “official” version of the model file, modifies it, and saves a new model file. The modification process could be lengthy and involve many different sorts of changes, e.g., adding objects and slots, running DMIs, executing runs, interactively changing data, etc.
2. Bob provides the new model file to Susie, who would like to understand the ways in which the new model differs from the original one. A comparison tool helps Susie locate and understand the differences.
3. Having reviewed Bob’s changes, Susie might then incorporate some or all of these modifications into a new model and then save this new model as the new official version.
Note: If only some of Bob’s changes are to be incorporated into the official model, or if the official model has changed since Bob originally obtained a copy of it, then Susie cannot simply replace the current official model with the model provided by Bob. Instead Susie should compare Bob’s model with the original or updated “official” model to see what has changed and then make those same changes to the original model.
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:
• A subset of model entities are currently compared by this tool. The compared items are shown in the model selection dialog and in Table 2.2. In general, objects, accounts, slots, slot values, DMIs, scripts, MRM configurations, and RPL Sets saved within the model are compared.
• This tool doesn’t support automatic merging but allows you to copy from the selected property values panel and replace in the open model.
Accessing the Model Comparison Tool
From the RiverWare workspace, select Utilities, then Model Comparison Tool.
Selecting Models to Compare
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:
• Currently Open Model. Choose the currently opened model, including any changes made since last saving the model.
• Read Model from File. Choose a model on the file system. Use the ellipsis button to open a file chooser to select the model.
In the Series Value Comparison region, specify how series data values should be compared. The following choices are available:
• Do Not Compare Series Values: No series values are compared. The series slot Values are not shown in the results.
• Compare Value Only, Ignore Flag: Compare series values, regardless of the flag. For example, if slot 1 has 100.0 (I) in Model A, but 100 (R) in Model B, no difference will be reported.
• Compare Value and Flag Together, For All Flags: Compare series values and flags. For example, if slot 1 has 100.0 (I) in Model A, but 100 (R) in Model B, a difference will be reported.
• Compare Value and Flag Together, For the Following Flags: Compare series values and flags but only for the specified flags. For example, if slot 1 has 100.0 (I) in Model A, but 100 (R) in Model B, no difference will be reported unless the I or R flag check boxes are selected. Choose which flags to compare: Input (I), DMI Input (Z), Rule (R), or Output (O).
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.
Note: 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.
The bottom portion of the dialog shows which entities and properties in the model file will be compared. In general, objects, accounts, slots, slot values, scripts, MRM configurations, and RPL Sets embedded within the model are compared.
Note: This is a subset of entities/properties in the model file. For example the path of the two models is compared, but the run timestep is currently not compared. The list of content will be expanded in future releases.
All RPL sets saved or embedded in the model file are automatically compared including:
• Expression Slot Set
• Global Function Set (when saved in the model as described Save Location in RiverWare Policy Language (RPL))
• Initialization Rules
• Iterative MRM Ruleset
• Object Level Accounting Method Set
• Optimization Goal Set (when saved in the model as described Save Location in RiverWare Policy Language (RPL))
• Rulebased Simulation (RBS) Ruleset (when saved in the model as described Save Location in RiverWare Policy Language (RPL))
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).
Table 2.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.
Note: Not all entities of a given type will have all of the properties, e.g., not all slots have expressions.
Entity | Properties (an * indicates the Copy Property operation is supported) |
|---|---|
Model | • Path - The location of the model on the file system are compared as text. • Version - The RiverWare version from the last save. |
Simulation Object | • Description - The text description as shown on the Open Object dialog’s Description tab are compared as text. • Methods - The user-selectable methods, shown on the object’s Methods tab are compared as text. Note: The tool compares all categories and methods, whether they are visible or not (perhaps because they are specific to a certain controller or dependent on other methods/categories). They are listed alphabetically by category. |
Account | • Water Type - For each account, the Water Type is compared. • Water Owner - For each account, the Water Owner is compared. • Priority Date - For each account, the Priority Date is compared. |
Slot | • Name - compared as text • Description - For each slot, the description is compared as text. • Value(s) * - The values of slots are compared using the tolerance described below. The slot values are shown in the appropriate format based on the type of slot. For tables, periodic and scalar slots, the values are compared using the full precision in standard values on the slots. For series slots, the comparison uses the setting shown in the Series Value Comparison, described above. Note: Some slot types or values may not display exactly as shown in RiverWare dialogs. For example, values using the DateTime unit type are compared but the values shown are the numeric encoding. This will show you a difference and you can look at the slot for the actual DateTime value. • Expressions * - For expression slots, the RPL expression is compared. |
DMI Manager | DMIs are compared in a hierarchical structure. The DMI Manager is the top level item and contains: • Locked Status - Is the DMI locked? Yes/No compared as text. • Show Progress - Will the DMI Progress dialog be displayed? Yes/No compared as text. • Show Status - Will the DMI Status dialog be displayed? Yes/No compared as text. |
Control File-Executable DMI | These items correlate directly to the Control File-Executable DMI dialog. All content is compared as text and toggles are shown as Yes or No. • Name - the DMI name is compared as text • Input or Output - the DMI input/output type is compared as text. • Confirm Warnings - Does the DMI confirm warnings, compared as Yes/No. • Record Invocations - Yes or No, compared as text • Control File - The control file is compared • Executable - The executable and path are compared as text. • Allow Spaces in File Paths - Yes or No • Limit Output Range to Run Range - Yes or No • Line Ending - - Native, windows, or unix • Active User Parameters - Only the active user parameters are compared as text. |
Trace Directory DMI | These items correlate directly to the Trace Directory DMI dialog. All content is compared as text and toggles are shown as Yes or No. • Name - the DMI name is compared as text • Input or Output - the DMI input/output type is compared as text. • Confirm Warnings - Does the DMI confirm warnings, compared as Yes/No. • Record Invocations - Yes or No, compared as text • Allow Spaces in File Paths - Yes or No • Limit Output Range to Run Range - Yes or No • Line Ending - Native, windows, or unix • Top Level Directory - The file path is compared as text. • Control File - The control file (sometimes called a control file template) is compared. • Single Trace Number - The trace number used for a single run. |
Database DMI > Dataset > > Slot Selection | The properties for a Database DMI show a hierarchical structure displaying the following item: • Name - the DMI name is compared as text • Input or Output • Confirm Warning - Yes or No • Record Invocations - Yes or No • User Parameters - Compared as text Then, there is a sub item for each referenced Dataset • Name - The name of the referenced dataset. • Type - Either DSS, HDB, or Excel • Enabled - Yes or No Then, there is another sub item for each referenced Slot selection: • Selection Label - The label shown for this slot selection • Enabled - On or off • Begin Timestep • End Timestep • Slot List - The expanded list of slots for this slot selection |
Database Group | • Name - The group name is compared as text. • Comment - Comments are compared as text • Members - The names of DMIs contained in the group are compared as text. |
DMI Year Mapping Group | • Name - The group name is compared as text. • Comment - Comments are compared as text • Members - The names of DMIs contained in the group are compared as text. • Map Years - The list of map years is compared. |
DMI Parameter | • Name - The parameter name is compared as text. • Minimum Value - The minimum value is compared. • Maximum Value - The maximum value is compared. • List Items - The list of possible values is compare as text. |
DSS Dataset | These items correlate directly to the DSS Dataset dialog. All content is compared as text and toggles are shown as Yes or No. • Name • Name Map • Missing Value Preference • Missing Value Replacement • Unit Preference • Unit List • Read Table Behavior • DSS File • DSS Path • Data Type List |
Excel Dataset | These items correlate directly to the Excel Dataset dialog. All content is compared as text and toggles are shown as Yes or No. • Name • Name Map • Missing Value Preference • Missing Value Replacement • Unit Preference • Unit List • Connection Process • Workbook • Slot Mapping • Header Specification • Header Orientation • Ranges on Same Worksheet • Worksheet • Apply Header Offset • Header Offset • Apply Range Offset • Range Offset • Run Name Type • Single Run Name • Use Begin Timestep • Use Units |
HDB Dataset | These items correlate directly to the HDB Dataset dialog. All content is compared as text and toggles are shown as Yes or No. • Name • Name Map • Missing Value Preference • Missing Value Replacement • Unit Preference • Unit List • Group Slots • Database Name • Table Type • Mapping ID • Model ID • Model Run ID • Runtime Model Run ID • Ensemble ID • Runtime Ensemble ID • Ensemble Agency ID • Ensemble Trace ID • Use Water Year Table • Use Overwrite Flag • Read Validation Character |
Name Map | • Name - The name is compared • Display Order - The ordering of the name maps are compared. |
Script Manager | The Script Manager shows item shows a hierarchical list of Scripts, Scripts and Script Groups. The following general Script Manager items are compared: • Default Tab • Open on Model Load • Execute Group on Model Load • Group to Execute on Model Load |
Script Group | Each Script Group is shown with the following: • Name • Scripts |
Script | Each script has a hierarchical list showing all of the script actions and the following: • Name • Description |
Script Action | Each Script Action compares the following properties as text: • Enabled • Show in Dashboard • Display Text • Additional properties specific to the action type Note: There are many types of script actions, and each type has a different set of properties. Because these properties are numerous and varied, they are not enumerated in this table or in the Models to Compare dialog. |
MRM Configurations | These items correlate directly to the MRM Configuration dialog. All content is compared as text and toggles are shown as Yes or No. The properties for MRM Configurations show a hierarchical structure displaying the following items for each MRM Configuration: • Name • Description • Keyword / Value Descriptors • Mode • Policy Setup • Input DMIs Setup • Input DMIs Type • Rulesets - This is a list of rules shown on the Policy tab. • Input Ensembles - These are the input ensembles shown on the Ensembles tab, when configured • Output Ensembles - These are the output ensembles shown on the Ensembles tab, when configured |
MRM Output Info | For each MRM configuration, these sub items correlate directly to the Output tab of the MRM configuration dialog. All content is compared as text and toggles are shown as Yes or No. • Per Trace Output DMI • RDF: Control File • RDF: Data File • RDF: Timesteps Mode • RDF: Allow Spaces in File Paths • Excel: Generate Excel Workbooks from RDF • Excel: Delete RDF Files • Excel: Slot Name Format • Excel: Workbook Configuration • Generate Comma-Separated Values Files - Yes or no toggle, See next section. • Generate NetCDF Files - Yes or no toggle, See section below |
MRM Comma-Separated File | For each Comma-Separated Values output shown in the list, these sub items correlate directly to the Comma-Separated Values File Configuration within the MRM configuration. All content is compared as text and toggles are shown as Yes or No. • Name • File • Timestep Format • Use Object Name • Use Object Type • Use Slot Name • Use Slot Name With Unit • Use Unit • Use Timestep Size • Use Year • Use Month • Use Model Name • Use Ruleset File Name • Use Input DMI Name • Use MRM Config Name • Use MRM Descriptors • Slots - This is the list of slots to ouput to the CSV file |
MRM NetCDF File | For each NetCDF Files output shown in the list output list, these sub items correlate directly to the Net CDF File Configuration within the MRM configuration. All content is compared as text and toggles are shown as Yes or No. • Name • File • Use Ruleset File Name • Use Input DMI Name • Use MRM Config Name • Use MRM Descriptors • Use Model Name • Use Object Name • Use Object Type • Use Slot Name • Use Unit • Use Timestep Size |
MRM Run Parameters | For each MRM Configuration, these sub items correlate directly to the Run Parameter tab within the MRM configuration dialog box. All content is compared as text and toggles are shown as Yes or No. • Initial Date • Finish Date • Timesteps • Save Model File • Save After • Save In Folder • Save With Name Prefix |
MRM Input Info | For each MRM Configuration, these sub items correlate directly to the Input tab within the MRM configuration dialog box. All content is compared as text and toggles are shown as Yes or No. • Has Initialization DMI • Initialization DMI • Input DMIs • Has Ensemble Input • Index Sequential: Number of Runs • Index Sequential: Initial Offset • Index Sequential: Interval • Index Sequential: Interval Units • Index Sequential: Control File • First Trace • Number of Traces • Index Sequential / DMI Mode • Distributed Runs Enabled |
MRM Iterative Runs | For each MRM Configuration, these sub items correlate directly to the Iterative Runs tab within the MRM configuration dialog box. All content is compared as text and toggles are shown as Yes or No. • Pre-Run Rules • Post-Run Rules • Execute Pre-Run Rules • Continue After Abort • Max. Iterations |
RPL Set (for all sets that are saved within the model file) | • Name - The set names are compared as text. • Agenda Order - The agenda order (1,2,3... or ... 3,2,1) are compared as text. • Description - The set description is compared as text. • Precision - The set precision is compared as a numeric value. • Is Global? - Is this set a global functions set. • External Documentation - The external documentation toggle is compared as text. |
Utility Group (as part of a RPL set saved within the model) | • Name * - The group names are compared as text. • Description - The group description is compared as text. • Notes - The group notes are compared as text. • Is Enabled - The enabled/disabled setting is compared. • Names Color - The colors used for the group name is compared as a color value. • External Documentation - The external documentation toggle is compared as text. |
Policy Group (as part of a RPL set saved within the model) | • Name * - The group names are compared as text. • Description - The group description is compared as text. • Notes - The group notes are compared as text. • Is Enabled - The enabled/disabled setting is compared. • Names Color - The colors used for the group name is compared as a color value. • External Documentation - The external documentation toggle is compared as text. |
Report Group (as part of a RPL set saved within the model) | • Name * - The group names are compared as text. • Description - The group description is compared as text. • Notes - The group notes are compared as text. • Is Enabled - The enabled/disabled setting is compared. • Names Color - The colors used for the group name is compared as a color value. • External Documentation - The external documentation toggle is compared as text. |
Rule, Goal Method (as part of a RPL set saved within the model) | • Name * - The rule names are compared as text. • Priority - The rule priority values are compared. • Description - The rule description is compared as text. • Notes - The notes are compared as text. • Is Enabled - The enabled/disabled setting is compared as true or false. • Execution Constraint * - The execution constraints are compared as RPL items. • Pre-Execution DMI Name - The pre-execution DMI names are compared as text. • Post-Execution DMI Name - The post-execution DMI names are compared as text. • External Documentation - The external documentation toggle is compared as text. • Stop on NaN - The Stop on NaN settings are compared as true or false. • Names Color - The colors used for the rule name is compared as a color value. • Statements * - The RPL statements are compared as RPL items. |
Function (as part of a RPL set saved within the model) | • Name * - The function names are compared as text. • Description - The function description is compared as text. • Notes - The group notes are compared as text. • Is Enabled - The enabled/disabled setting is compared. • Arguments - The functions’ set of arguments are compared as text. • Return Type - The functions’ return type (NUMERIC, BOOLEAN, etc) are compared as text. • Diagnostic Units - The Display Function Diagnostics Scale/Units is compared as text. • Pre-Execution Diagnostics - The pre-execution diagnostic toggle is compared as true or false. • Post-Execution Diagnostics - The post-execution diagnostic toggle is compared as true or false. • Is Time Varying - The toggle for Time Varying is compared. • External Documentation - The external documentation toggle is compared as text. • Post-Execution Checks * - The functions’ Post-Execution Checks are compared as RPL expressions. • Names Color - The colors used for the function name is compared as a color value. • Body * - The RPL expressions are compared as RPL items. |
Report Item (as part of a RPL set embedded in the model) | • Name * - The item names are compared as text. • Item Type - The type of the item (rule, function, object, slot, etc) are compared • Item Parent - The items parent (i.e for a slot, which object is it on) are compared. • Names Color - The colors used for the item name is compared as a color value. • External Documentation - The external documentation toggle is compared as text. |
Tour of the Model Comparison Tool
The Model Comparison Tool contains the following areas, as shown in Figure 2.3 and explained by the numbered items:
1. The Models panel shows the names, sources and paths of the selected models.
2. The Search and Filter Results panel allows for searching and filtering of the results.
3. The hierarchical view of results area shows the comparison results.
4. The color coding and Status shows individual differences between the two models.
5. The Selected Property panel shows the property (if any) for the currently selected item in the comparison results view. This shows the differences are highlighted in orange.
6. When a series slot’s values are selected, a plot is also shown. Data from Model A is shown with a blue line, while model B data is shown in red. A legend above the data reinforces the color usage.
7. The Copy Property operation allows you to copy the property’s value and replace it in the opened model. It is only enabled when this operation is supported.
Figure 2.3 Screenshot of the Model Comparison Tool showing the main areas of the tool.
The following sections describe these areas and how to use the tool.
Models Panel
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.
This is useful if you make changes to Model A or B. Note: When the models are selected, the Model Comparison Tool compares the specified models. See How the Model Comparison Tool Works for details. If you make changes to one of the chosen models, it is not immediately reflected in the comparison tool. Use the Recompute Differences button 
to update the status in the tool.
to update the status in the tool. Comparison Results Panel
The Comparison Results panel shows a hierarchical view of the results of the comparison. The hierarchy is based on the structures of the two model. For example, objects contain slots as children entities. Aggregate objects have object elements as their children. Objects and slots are listed in alphabetical order within the hierarchy level.
Double-clicking an object or slot item will open the appropriate dialog to view the version of that entity, if one of the models compared was the open model.
Columns include the Name, Status and Type. The Model, Objects, and Slots show their particular icon. The Status column shows the results of the comparison. Table 2.3 lists the possible status values and their meanings.
Status | Meaning |
|---|---|
A = B | The item is identical in Models A and B. |
A ≠ B | The item is different in Models A and B. |
A | The item exists in model A but not in Model B. |
B | The item exists in Model B but not in Model A. |
A --> | The item exists here in Model A and elsewhere in Model B and/or the item has been renamed. |
<-- B | The item exists here is Model B and elsewhere in Model A and/or the item has been renamed. |
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:
Figure 2.4 Legend for Status column colors
• Yellow indicates that the item contains properties and that within the item there are differences in properties.
• A light orange shading indicates the item’s Name property has changed; that is, the item has been renamed. When an item has been renamed (not copied/pasted or moved), the item will show up twice in the list, once with the name used in model A (the status shows “A ->”) and once with the name used in model B (the status shows “<- B”).
• The darker orange color indicates that the value of the property is different.
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.
Search and Filter Tools
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 2.4 describes the search and filter buttons in the Comparison Results panel.
Button | Text | Meaning |
|---|---|---|
 | Next Match | Select the next item that matches the search criteria. |
 | Previous Match | Select the previous item that matches the search criteria |
 | Search Column | Choose in which column you wish to search. |
 | Search Content | Type in the search criteria. Use the arrow menu to select previously entered items. |
 | Ignore Case | Check the box to ignore case when searching. When unchecked, case is considered. |
 | Filter... | Open a dialog where filters can be applied. This opens the Model Comparison Tool Display Filters dialog; see Filter Settings |
 | Cancel | Remove all filters. |
 | Filter Status | Text is shown noting that there are filters applied and the number of items shown. |
Filter Settings
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:
• Show only items that differ
• Two additional filters that can be configured. Options include
– Name: Filter on the Name column to only show results containing the specified text. Choose to Ignore Case if desired.
– Type: Filter on the Type column. The drop-down menu shows the Types that are available in the results.
When a filter is applied, the status in the Search and Filters status is updated. To remove a filter, select the red X.
Figure 2.5 Model Comparison Tool Display Filters
Selected Property
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/three differences identified.)
Figure 2.6 Model Comparison Tool results with Selected Property highlighted
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.
Plots
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.
Figure 2.7 Model Comparison Results with a plot of numerical differences shown.
Copy Property
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:
Copy the value of the selected property (in Model A or B) and replace the value of that property in the open model
This operation is enabled only when the following conditions are met:
• A supported property is selected in the results tree view. Currently certain items are supported including RPL statements, RPL function bodies, slot names, and slot values. Supported items are listed in the Table 2.2 with an asterisk next to the item.
• The parent item exists in both models.
• The property’s comparison status is A≠ B.
With a property selected, there are two ways to initiate the Copy Property operation:
• Use the Copy Property button 
• Right-click context menu on the property
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 2.8 shows a sample of the dialog box after a Copy Property operation has occurred.
Figure 2.8 Screenshot showing the selected property after a replacement has occurred. Note the green text indicating the property has been replace.
How the Model Comparison Tool Works
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.
1. Loads the model file.
2. Creates a representation of the model.
3. Writes that representation to a file.
4. The original RiverWare instance then reads the file into memory.
5. It repeats the same steps for the other model, if necessary.
6. With both sets of information in memory, RiverWare can then compare the properties and values and present the results in the tool.
Note: Because of this process, comparing large models can take a long time to load the model, write a representation of the data, and then read that data back into RiverWare.
Revised: 07/17/2020