Introduction: Modelcomp is a comparison tool for RiverWare model files. Two model files are supplied on the command line and modelcomp compares the objects, selected methods and time series. The resulting differences between the model files is reported in the calling command window. The report is formatted with the name of the time series or the object name followed by a count of the number of differences, followed by the data from each model file. In the case of two model files with a difference on a single slot, the slot name will be output, followed by all values for that slot in each model file. Additional output options are available, using nchart.exe for Windows graphing and xmgr for Solaris graphing. Note that when using nchart.exe, a single graph may be displayed at a time. When using xmgr, the number of graphs may be specified and it defaults to 3 per page. Graphs may show a typical hydrograph for both models (the --graph option) or they may show differences (--difference), differences scaled by the maximum of the two values (--convergence) or, differences scaled by the maximum value in either slot(--scaled). Modelcomp performs some transformations automatically, comparing that the same units are used in each model, and fixing platform specific problems. Options are provided to turn off these features, so a more strict or raw comparison can be made. For comparison of optimization differences, caused by slight modifications to the model or by platform changes, there is a special option (--optonly). This option limits the comparison to the objective function values, ignoring any differences in post optimization simulation. Installation: Install Perl on your Windows system. Please install version 5.6 or greater. Versions of Perl are available from ActiveState (www.activestate.com/ActivePerl). Click on "Get ActivePerl" in upper right. Then click on the Download button for ActivePerl. Unzip the installation zip file into a temporary directory. Double click on setup.exe and follow the installation instructions. Set the System Path: Use the Control Panel -> System to add the following to your path. (You may need to be system administrator to change your path.) C:\Program Files\CADSWES\Model Compare Detailed System Path Directions: Under the Start Menu, click on Control Panel. When the Control Panel popup appears, select Performance and Maintenance followed by System. When the System popup appears, click on the Advanced tab. Click on the Environment Variables button near the bottom of the popup. In the Environment Variables popup, select the Path variable. Click the edit button and add a single semi-colon to the end of the path, followed by the path to model compare. ;C:\Program Files\CADSWES\Model Compare How to Use: Make sure the modelcomp installation directory is in your path. Start a command shell and change directories if required. Run the modelcomp utility (example here compares model1 and model2 and displays time series differences graphically): modelcomp.bat --graph model1.mdl.gz model2.mdl.gz Command Line Help: modelcomp [--graph [N]] [--difference [N]] [--convergence [N]] [--scaled [N]] [--exp0] [--ignore] [--neg0] [--tol] [--noconv] [--time] [--optonly] [--reason] [--units] [--help] The following command line options are available. Only the first letter needs to be specified. Graphing Options: For all graphing options, Modelcomp assumes that all missing or NaN values are zero for the purposes of plotting differences. This condition occurs when starting or ending dates are different between the two model files, when one time series has a different timestep, or when one time series has NaN values when the corresponding time series in the second model file does not. On solaris, [N] is used to specify the number of graphs. If [N] is not supplied, 3 graphs are displayed per page. Note, the Windows version is limited to 1 graph per page. --graph [N] Display graphical plot of slots with differences. For each timestep, the following is plotted: Value1 and Value2. --difference [N] Display graphical plot of slots with difference. A single line is shown, representing the difference between model file 1 and model file 2 values.For each timestep, the following is plotted: Value 1 - Value 2 The resulting differences can be positive or negative. --convergence [N] Display graphical plot of slots with differences scaled by the maximum value at that timestep. A single line is shown that varies between 0.0 and 1.0. This graph can help you determine the timesteps that caused a percent convergence calculation to fail thus causing the difference. For each timestep, the following is plotted: abs(Value1-Value2)/max(abs(Value1),abs(Value2)) If Value1 and Value2 are 0.0, then a 0.0 is plotted. --scaled [N] Display graphical plot of slots with differences scaled by the maximum value in either model file for this slot. A single line is shown that varies between 0.0 and 1.0. For each timestep, the following is plotted: abs(Value1-Value2)/(max absolute value in Slot1 or Slot2). Multi-Platform Options: --exp0 Do not remove leading 0s from exponents when comparing values. By default all E-notation numbers are converted to match the format: 1.234e+01 or 1.234e-01 --ignore Ignore differences in old expression slots. --neg0 Do not convert -0 to 0 when comparing values. By default all -0 values are converted to 0 before comparison. On Windows, very small negative values may be stored in the model file as -0, causing the files to be different. --tol Loosen the tolerance to allow for Solaris / Windows differences. Convergence Flags: --noconv Do not compare values using RiverWare slot convergence criteria. If this flag is selected, all convergence calculations use 1E-8 to determine convergence. Timing Flag: --time Perform a time-independent comparison. If this flag is on, all time series values are compared by numerical position from the start of the time series. Optimization Support: --optonly Compare the optimization objective values. Ignore all other differences. This option is used for model files that are different because of alternative optimal solutions. Note that this option compares objective value differences but it allows the post optimization solution to be different. Objective values that are repeated within a tolerance of 0.0001 are treated as a single value. If, after the repeated values are removed from both lines, the number of values in the line is not the same between file1 and file2, the line is different. Miscellaneous: --reason Print the reason for non-convergence as differences are found. --units Background: In the model file, RiverWare creates a list of all Scale and Unit values and uses this Scaled-Units list to index slots. E.g. "1000 Acre-feet" = 1 "1 cfs" = 2 "10 ft" = 3 When a new Scaled-Unit is used for the first time in a model, the ordering of this list may change. E.g "1 cfs" becomes index 3 because the Scaled-Unit "1 mg/L" has been inserted before "1 cfs". By default, modelcomp processes this list and compares the Scaled-Unit for each time series, reporting differences only when the actual Scaled-Unit is different not just the indexing. The --units option ignores the Scaled-Units list and reports a difference even if the indexing has changed but the underlying Scaled-Units have not. --help Display this help message.