MulticsCompare - Simulation Input Comparison Utility

Overview

MulticsCompare is a C++ command line utility designed to compare simulation input definitions between two Multics simulation result files (e.g. simulation_results.txt).

The primary objective of this utility is to identify and report only meaningful differences between two simulation configurations. This makes it especially useful for:

  • Regression testing

  • Debugging inconsistent simulation behavior

  • Verifying reproducibility of simulation runs

  • Tracking configuration changes across projects or versions

Identical entries are intentionally omitted from the output to keep the results focused and easy to interpret.

What This Utility Compares

The comparison is divided into two categories:

  1. fileDict entries

  2. Simulation variables

fileDict Comparison

The fileDict section defines external file dependencies used by the simulation, such as geometry files or lookup tables.

A fileDict entry is reported as different if:

  • The same file name exists in both simulation files but points to different directories

  • The file exists in only one of the two simulation results

The comparison is performed bidirectionally, ensuring that files missing from either simulation are detected.

Simulation Variable Comparison

Simulation variables are defined outside the fileDict block and follow the general format:

variable_name   unit   value

A variable is reported as different if:

  • The variable exists in both files but has a different value

  • The variable exists in both files but has a different unit

  • The variable exists in only one of the two simulation results

Supported value types include:

  • Scalars

  • Vectors

  • Matrices

For vector and matrix values (enclosed in [ ... ]), the utility performs an element-wise comparison.

Comparison Rules Summary

Differences are reported in the following cases:

Case

Description

File path mismatch

Same file name, different directory

Missing file

File exists in only one simulation

Variable value change

Same variable name, different value

Variable unit change

Same variable name, different unit

Missing variable

Variable exists in only one simulation

Output Description

Output File

All comparison results are written to:

comparison_results.txt

Output Contents

The output file includes:

  • Multics version information for both simulation files

  • A warning if the Multics versions differ

  • A detailed fileDict comparison section

  • A detailed simulation variable comparison section

  • Clear labeling of File1 and File2 values

  • Explicit messages for missing files or variables

Usage

Command Line Syntax

./MulticsCompare <simulation_file_1> <simulation_file_2>

Example

./MulticsCompare simulation_results1.txt simulation_results2.txt

This command compares:

  • simulation_results1.txt (File1)

  • simulation_results2.txt (File2)

and writes the comparison report to:

comparison_results.txt

Build and Run Instructions

Step 1: Navigate to the test directory

cd test

Step 2: Generate build files using CMake

cmake ..

Step 3: Compile the executable

make

Step 4: Run the comparison

./MulticsCompare filename1 filename2

—

How the Code Works

File Reading

  • Each input file is read line by line into a std::vector<std::string>

  • Comment lines starting with # are ignored

  • Parsing is based on the first token of each line

Internal Logic

  • fileRead() loads file contents into memory

  • search() locates variables or keywords by matching the first token

  • Comparisons are performed using string-based matching (no numerical tolerance)

Processing Flow

  1. Read both simulation result files

  2. Extract and compare Multics version information

  3. Compare fileDict entries (two-pass comparison)

  4. Compare simulation variables (scalar and vector/matrix)

  5. Write formatted results to comparison_results.txt