This file briefly describes how the simulations tools we used when
simulating the AX and WAMW algorithms work.  The tools are written in
the Python programming language (see http://www.python.org/), and
require Python-2.0 or higher to run.

The RON tracefile format used in many of the traces is described in:

	http://nms.lcs.mit.edu/ron/data/


wamw.py
-------
Runs the WAMW algorithm on a given network tracefile (RON format).
Also requires some additional input besides the RON tracefile:

<taskfile> - A file containing the individial task execution time in
seconds, divided by a newline for each task.

<hostfile> - A file containing the hosts in the RON tracefile which
will be used as masters in the simulation, divided by a newline for
each host.

<# of workers> - The number of workers per master.  Currently, the
number of workers is the same for all masters.

<dry run> - The number of "virtual" seconds to advance the RON trace
before starting the simulation (may be used to start the simulation at
times interesting events happen in the trace, e.g. partitions)

<pmax only> - Set to 1 if master to master communication should only
happen when pmax seconds elapse, and 0 if master to master
communication should happen at both task completion and at pmax
intervals.


ping2ron.py
-----------
Converts a set of files in the 'ping' tracefile format to the 'RON'
tracefile format.  We used this utility to convert the 'ping' files
supplied by Omar Bakr and Idit Keidar from their experiments for the
PODC'02 paper.


ping.py
-------
Given a 'ping' tracefile, generate a outage list for that trace (used
by ping2ron.py to generate outage lists during conversion to the RON
tracefile format).


sim.py
------
Traverses a RON tracefile and report the times outages occur.  Set the
NULL variable on the top of the file to the string which denotes that
a packet send/recv failed in the RON tracefile (this was 'NULL' in the
first RON traces, and '0' in the latest traces we got from David
Andersen at MIT).


gen_view.py
-----------
Generate a trace of view changes from a tracefile (RON format).

Parameters:

<RON tracefile> - a tracefile in RON format.

<output file> - the file to store the output generated. Each line
represents a new view installed. 'connect' means the communication in
the view is symmetric and transitive, and 'obsolete' means the
communication in the view is not transitive. If there is only one
group in the system, and no host crashed, we omit the name of hosts
and only write the status of the view in this file.

<hostfile> - A file containing the hosts in the tracefile which will
be used as local area networks in the simulation, divided by a newline
for each host.


analysis.py
-----------
Calculate the time of transitive views and non-transitive views. And
analyze the percentage of transitive communications.

Parameters:

<tracefile> - the trace of view changes, generated by gen_view.py.

<number of lans> - the number of LANs in the tracefile.


ax.py
-----
Runs the AX algorithm on a given network tracefile. Currently, this
algorithm only work properly when there is no host crash during the
simulation.

Parameters:

<tracefile> - The trace of view changes, generated by gen_view.py.

<hostfile> - A file containing the hosts in the tracefile which will
be used as local area networks in the simulation, divided by a newline
for each host.

<number of tasks> - The number of tasks to be executed.

<workers per lan> - The number of workers per LAN. Currently, the
number of workers is the same for all masters.

<dry run time> - The number of "virtual" seconds to advance the RON
trace before starting the simulation (may be used to start the
simulation at times interesting events happen in the trace,
e.g. partitions)

<time slice> - The time to execute one task. Currently, the size of
all tasks are the same, according to the definition of algorithm AX.

<number of lans> - the number of LANs in the tracefile.
