= OverSim Usage =

== First steps with OverSim: ==

 * change into directory {{{OverSim-20101103/simulations}}}

 * start !OverSim by typing
{{{
../src/OverSim
}}}

 * choose a simulation scenario (e.g. ''Chord'')

 * press the ''Run'' button in OMNeT++'s main window

 * ... watch & enjoy ...

 * press the ''Stop'' button to pause simulation

 * end !OverSim by closing OMNeT++'s main window[[BR]]
 (press ''Yes'' to invoke {{{finish()}}}-method call in all OMNeT++ modules)

 * If you want to simulate large networks like the predefined simulation scenario ''!ChordLarge'' invoke !OverSim without GUI:
{{{
../src/OverSim -uCmdenv -cChordLarge
}}}

 * The simulation results get stored in the ''simulations/results'' directory. Use the supplied python scripts or the Eclipse IDE for postprocessing.

== Editing parameters: ==

 * Edit {{{simulations/omnetpp.ini}}} to change or define new simulation scenarios[[BR]]
 (default parameters are stored in {{{simulations/default.ini}}}, parameters are described on the
 [/chrome/site/doc/index.html OverSimAPI pages])
 * Make use of the OMNeT++ ini file syntax for easy parameter studies. This is an example for a study on Chord with different churn rates, two different stabilize intervals and 5 different seeds. Simply add this section to {{{simulations/omnetpp.ini}}}:
{{{
repeat = 5
*.underlayConfigurator.churnGeneratorTypes = "oversim.common.LifetimeChurn"
**.overlayType = "oversim.overlay.chord.ChordModules"
**.tier1Type = "oversim.applications.kbrtestapp.KBRTestAppModules"
**.targetOverlayTerminalNum = 100
**.initPhaseCreationInterval = 0.1s
**.measurementTime = 500s
**.transitionTime = 100s 
**.overlay.chord.stabilizeDelay = ${stab=5, 60}s
**.lifetimeMean = ${lifetime=1000, 2000, 10000}s
}}}
 * Run this parameter study:
{{{
../src/OverSim -cChordChurn -uCmdenv
}}}

== Use the post-processing scripts to generate plots ==
 * Install ''python'' (with ''matplotlib'', ''numpy'' and ''scipy'') and ''gnuplot''.
    * On Ubuntu:
{{{
sudo apt-get install python-matplotlib python-scipy gnuplot
}}}
    * On Windows:
      * Install the [http://www.pythonxy.com/ python(x,y) light edition], which contains all needed packages.
 * View the results with 95% confidence intervals by using the script {{{simulation/tools/plot.py}}}:
{{{
tools/plot.py -c0.95 lifetime "KBRTestApp: One-way Delivery Ratio.mean" results/ChordChurn-*.sca
}}}
 * To generate gnuplot output append {{{-o chord_churn}}} to the script parameters. This will generate {{{chord_churn.plot}}} and {{{chord_churn.dat}}} files, which can be used as input to gnuplot. Call gnuplot like this to generate a publication quality {{{chord_churn.eps}}} plot:
{{{
gnuplot chord_churn.plot
}}}
 * To plot a vector file (e.g. the routing latency) use the {{{simulations/tools/vecplot.py}}} script. The following creates a plot with 95% confidence intervals aggregating all vectors in buckets of 60 seconds:
{{{
tools/vecplot.py -b 60 -c0.95 -i"lifetime=1000\""  "KBRTestApp: One-way Latency" results/ChordChurn-*.vec
}}}

== Tips for using the Eclipse IDE ==

 * Start the IDE with ''omnetpp''

 * To start simulations from Eclipse, select ''!OverSim'' in the project explorer,[[BR]]
   click on ''Run simulations'' and select simulations/omnetpp.ini

 * To view simulation results, use the project explorer and double click[[BR]]
   on a .sca file in the ''simulations/results'' directory

 * Set the !OverSim coding style in ''Preferences'' by importing[[BR]]
   the style from ''doc/EclipseOverSimCodeStyle.xml''