= OverSim Usage =

== First steps with OverSim: ==

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

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

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

 * Select ''Options->Simulation Options->Animation'' and disable ''Animate method calls'' to speedup simulations

 * 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 OMNeT++ scavetool 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 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 
**.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 use ''sudo apt-get install python-matplotlib python-scipy gnuplot''. On Windows you can install the [python(x,y) light edition http://www.pythonxy.com/] which contains all needed packages.
 * View the results 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 a {{{chord_churn.plot}}} and a {{{chord_churn.dat}}}, which can be used as input to gnuplot.

== 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''