===============================================
     S E M A N T I C   D I F F E R E N C E
B E T W E E N   S T P   W O R L D   M O D E L S
===============================================

This file includes the instructions for determining the semantic
difference between two STP world models, and for incorporating this
difference into another STP world model.


-= Installing the difference tool =-

The tool consists of two files, difstp.exe and difstp.bat, which
are available at the following locations:

www.cs.cmu.edu/~eugene/Radar/Tools/Diff/difstp.exe
www.cs.cmu.edu/~eugene/Radar/Tools/Diff/difstp.bat

To install the tool, copy "difstp.exe" into the "st/lib/" directory of
Space-Time Module, and "difstp.bat" into the "st/" directory. If you
later need to uninstall it, remove these files. The tool also uses the
following files, which are in the standard Space-Time installation:

db/params.txt
db/scenario.dtd
db/scenario.xsd
lib/datamodel.dll
lib/IIOPChannel.dll
lib/SpaceTimeDataModel.dll
lib/UncertainMath.dll

If you use the difference tool as a stand-alone application, without
Space-Time Module, you should copy these files from Space-Time Module.


-= Determining the semantic difference =-

The difference tool determines the "semantic difference" between two
world models, that is, the actual difference unrelated to the encoding
syntax, which may include the difference between room properties,
room availability, and event properties.

To apply the tool, open a command-prompt window, go to the "st/"
directory, and type the following command:

  difstp.bat d <stp-1> <stp-2> [r][a][e]

The letter "d" indicates that you are using the tool for finding the
difference between two STP files, <stp-1> and <stp-2> are the related
files, and the letters "r", "a", and "e" represent the options:

r: compare room properties
a: compare room availabilities
e: compare event properties

You may specify these letters in any order. If you do not specify any
letters, the system compares the room and event properties, and does
not compare the room availabilities; that is, specifying no options is
equivalent to specifying "ra".

The tool creates a list of properties whose values differ between <stp-1>
and <stp-2>; for each of these properties, it includes both the "old
value" from <stp-1> and "new value" from <stp-2>.  The output consists of
three (or fewer) separate lists: room properties, room availability, and
event properties.

The tool saves the resulting list of properties in the "st/out.xml"
file; note that, if the "st/" directory already contains this file,
then the tool overwrites it.


-= Incorporating a difference into another file =-

The difference tool allows incorporating a previously computed difference
into another STP world model, that is, using the "new values" specified in
a difference file to replace the respective values in the given world
model. Note that the replacement produre uses the "new values" from the
<stp-2> file, used in the difference computation, and that it ignores the
"old values" from <stp-1>. Also note that it replaces the property value
in ithe given world model even if the original value is different from the
"old value" in <stp-1>.

To apply this operation, open a command-prompt window, go to the "st/"
directory, and type the following command:

  difstp.bat p <stp> <diff>

The letter "p" indicates that you "project" a difference from the
<diff> file into the <stp> file. Normally, <diff> is a copy of the
"st/out.xml" file generated when determining the semantic difference.

The tool saves the resulting new STP world model in the "st/out.stp"
file; note that, if the "st/" directory already contains this file,
then the tool overwrites it.