# sim-d simulation replication management software

## QUICKSTART

Run the simulation server:

    $ cd simulations
    $ bin/simd.py -d

Run a simulation client:

    $ bin/simcd.py -d

Start up a simulation:

    $ bin/simcontrol.py --start sim-sample

Watch simulation progress:

    $ bin/simcontrol.py --get-clients

Look at simulation results:

    $ cat sim-sample/results.csv

## BASICS OF SIMD

A simulation "server" needs to run on what will be the central, controlling
machine. This machine has the main repository of simulations, which will be
distributed out to clients. The results will also be returned to this main
repository. It is fine for clients to run on the same machine as the server
(this is normal operation!).

Each simulation client will run one instance of ns-2 at a time. This means that
to utilise a dual-cpu machine, you may want to run two simulation clients on
that machine. Client machines only need a copy of the bin/ directory. The
simulation client program, simcd.py, will obtain up to date simulation files
from the server. If the simulation server is on a different machine to the
client, the client must be told where to connect, eg. "bin/simcd.py --server
foo.example.com".

simcontrol.py controls the simulation system. This is the user interface
program. Simulations can be started, stopped, and their progress may be
inspected with this script. The output is mostly intended to be parsed by a
nicer frontend, though it is still human-readable.

All programs above have usage staments accessible with the "--help" command-
line option, eg. "bin/simcontrol.py --help".

## SIMULATION SETUP

Simulations must be crafted in a special way for simd. simd looks in the root
simulation directory for directories with a file "sim.tcl" in them, it
considers these as simulations. Each of these simulation scenarios may have
many different simulation instaces with different parameters. This is
controlled by two more files in the simulation directory, "num_simulations" and
"get_parameters". 

The file "num_simulations" should have one integer in it specifying the number
of different sets of parameters, that is, the number of simulations that will
be performed with this simulation script. If this file has the number "5" in
it, 5 simulations would be performed with simulation IDs of 1, 2, 3, 4 and 5.
These numbers interface with the "get_parameters" script.

The "get_parameters" script should be an executable script. It takes the
simulation ID as an argument, and outputs the parameters to the simulation
required. Note that this script isn't necessary, the simulation script
"sim.tcl" could easily figure out the simulation parameters from the simulation
ID. A simple "get_parameters" script to allow for this to happen would be as
follows:

    #!/bin/sh
    echo $1

The simulation script itself will be executed with ns-2 with the output of
"get_parameters" as its arguments. This script should then output its result
on standard output as comma seperated values suitable for a CSV file. This
CSV is then reported back to the server machine and stored in a file named
"results.csv" in the simulation directory.

Note that only the files reported above are distributed to client machines
automatically!

Summary:

    bin/*   - Simulation programs
    my-sim/ - Simulations are identified by directories...
        sim.tcl         - The simulation script itself, executed with ns
        num_simulations - The number of simulations/replications run
        get_parameters  - Maps simulation id -> simulation parameters

Output from sim.tcl on stdout is reported to the server.

                                    - - - -
Software by:

    Sam Jansen
    sam@wand.net.nz
    WAND Network Research Group

  ---------------------------------------------------------------------------
   "THE BEER-WARE LICENSE" (Revision 42): <sam@wand.net.nz> wrote this file.
    As long as you retain this notice you can do whatever you want with this
   stuff. If we meet some day, and you think this stuff is worth it, you can
                     buy me a beer in return - Sam Jansen.
  ---------------------------------------------------------------------------