\chapter{Running The Simulation}
\label{cha:running-the-simulation}

\section{User interfaces}

{\opp} simulations can be run under different user interfaces.
Currenly, two user interfaces are supported:

\begin{itemize}
  \item Tkenv: Tcl/Tk-based graphical, windowing user interface
  \item Cmdenv: command-line user interface for batch execution
\end{itemize}


You would typically test and debug your simulation under Tkenv,
then run actual simulation experiments from the command line or
shell script, using Cmdenv. Tkenv is also better suited for educational or
demonstration purposes.

Both Tkenv and Cmdenv are provided in the form of a library, and
you choose between them by linking one or the other into your
simulation executable. (Creating the executable was described in
chapter \ref{cha:building-simulation-programs}). Both user interfaces
are supported on Unix and Windows platforms.

Common functionality in Tkenv and Cmdenv has been collected and
placed into the Envir library\index{Envir}, which can be thought of as the
``common base class'' for the two user interfaces.

The user interface\index{user interface} is separated from the
simulation kernel, and the two parts interact through a well-defined
interface. This also means that, if needed, you can write your
own user interface or embed an {\opp} simulation into your application
without any change to models or the simulation library.

Configuration and input data for the simulation are described in
a configuration file usually called \fname{omnetpp.ini}.
Some entries in this file apply to Tkenv or Cmdenv only, other
settings are in effect regardless of the user interface.
Both user interfaces accept command-line arguments, too.


The following sections explain \fname{omnetpp.ini} and the common part of
the user interfaces, describe Cmdenv and Tkenv in detail, then
go on to specific problems.


\section{The configuration file: omnetpp.ini\index{omnetpp.ini}}

\subsection{An example}

For a start, let us see a simple \fname{omnetpp.ini} file which
can be used to run the Fifo1 sample simulation under Cmdenv.

\begin{verbatim}
[General]
network = fifonet1
sim-time-limit = 500000s
output-vector-file = fifo1.vec

[Cmdenv]
express-mode = yes

[Parameters]
# generate a large number of jobs of length 5..10 according to Poisson
fifonet1.gen.num_messages = 10000000
fifonet1.gen.ia_time = exponential(1)
fifonet1.gen.msg_length = intuniform(5,10)
# processing speeed of queue server
fifonet1.fifo.bits_per_sec = 10
\end{verbatim}

The file is grouped into \textit{sections} named \ttt{[General]}, \ttt{[Cmdenv]}
and \ttt{[Parameters]}, each one containing several \textit{entries}.
The \ttt{[General]} section applies to both Tkenv and Cmdenv, and the entries
in this case specify that the network named \fname{fifonet1} should be simulated and run
for 500,000 simulated seconds, and vector results should be written into the
\fname{fifo1.vec} file. The entry in the \ttt{[Cmdenv]} section tells
Cmdenv to run the simulation at full speed and print periodic updates
about the progress of the simulation. The \ttt{[Parameters]} section assigns
values to parameters that did not get a value (or got \fname{input} value)
inside the NED files.

Lines that start with ``\#'' or ``;'' are comments.

When you build the Fifo1 sample with Cmdenv and you run it by typing \fname{fifo1}
(or on Unix, \fname{./fifo1}) on the command prompt, you should see
something like this.

\begin{verbatim}
OMNeT++ Discrete Event Simulation  (C) 1992-2003 Andras Varga
See the license for distribution terms and warranty disclaimer
Setting up Cmdenv (command-line user interface)...

Preparing for Run #1...
Setting up network `fifonet1'...
Running simulation...
** Event #0        T=0.0000000  ( 0.00s)   Elapsed: 0m  0s   ev/sec=0
** Event #100000   T=25321.99 ( 7h  2m)    Elapsed: 0m  1s   ev/sec=0
** Event #200000   T=50275.694 (13h 57m)   Elapsed: 0m  3s   ev/sec=60168.5
** Event #300000   T=75217.597 (20h 53m)   Elapsed: 0m  5s   ev/sec=59808.6
** Event #400000   T=100125.76 ( 1d  3h)   Elapsed: 0m  6s   ev/sec=59772.9
** Event #500000   T=125239.67 ( 1d 10h)   Elapsed: 0m  8s   ev/sec=60168.5
...
** Event #1700000  T=424529.21 ( 4d 21h)   Elapsed: 0m 28s   ev/sec=58754.4
** Event #1800000  T=449573.47 ( 5d  4h)   Elapsed: 0m 30s   ev/sec=59066.7
** Event #1900000  T=474429.06 ( 5d 11h)   Elapsed: 0m 32s   ev/sec=59453
** Event #2000000  T=499417.66 ( 5d 18h)   Elapsed: 0m 34s   ev/sec=58719.9
<!> Simulation time limit reached -- simulation stopped.

Calling finish() at end of Run #1...
*** Module: fifonet1.sink***
Total jobs processed: 9818
Avg queueing time:    1.8523
Max queueing time:    10.5473
Standard deviation:   1.3826

End run of OMNeT++
\end{verbatim}

As Cmdenv runs the simulation, periodically it prints the sequence number
of the current event, the simulation time, the elapsed (real) time,
and the performance of the simulation (how many events are processed per
second; the first two values are 0 because there wasn't enough data
for it to calculate yet). At the end of the simulation, the \fname{finish()}
methods of the simple modules are run, and the output from them are displayed.
On my machine this run took 34 seconds. This Cmdenv output can be
customized via \fname{omnetpp.ini} entries. The output file \fname{fifo1.vec}
contains vector data recorded during simulation (here, queueing times),
and it can be processed using Plove or other tools.

\subsection{The concept of simulation runs}

{\opp} can execute several simulation runs automatically one after
another. If multiple runs\index{simulation!multiple runs} are
selected, option settings and parameter values can be given either
individually for each run, or together for all runs, depending in
which section the option or parameter appears.

\subsection{File syntax}

The ini file is a text file consisting of entries grouped into different sections.
The order of the sections doesn't matter. Also, if you have two sections
with the same name (e.g. \ttt{[General]} occurs twice in the file),
they will be merged.

Lines that start with "\#" or ";" are comments, and will be ignored during
processing.

Long lines can be broken up using the backslash notation: if the last character
of a line is "\textbackslash", it will be merged with the next line.

The size of the ini file (the number of sections and entries) is not limited.
Currently there is a 1024-character limit on the line length,
which \textit{cannot} be increased by breaking up the line using backslashes.
This limit might be lifted in future releases.

Example:

\begin{verbatim}
[General]
# this is a comment
foo="this is a single value \
for the foo parameter"

[General]  # duplicate sections are merged
bar="belongs to the same section as foo"
\end{verbatim}

\subsection{File inclusion}

{\opp} supports including an ini file in another\index{ini file!file inclusion},
via the \ttt{include} keyword. This feature allows you to partition large ini
files into logical units, fixed and varying part etc.

An example:

\begin{verbatim}
# omnetpp.ini
...
include parameters.ini
include per-run-pars.ini
...
\end{verbatim}


\subsection{Sections}

The following sections can exist:

\begin{longtable}{|p{4cm}|p{10cm}|}
\hline
\tabheadcol
\tbf{Section} & \tbf{Description}\\\hline
%%
\ttt{[General]} & Contains general settings that apply to all simulation runs
and all user interfaces. For details, see section \ref{sec:ch-run-sim:general-section}.
\\\hline
\ttt{[Run 1]}, \ttt{[Run 2]}, ...  & Contains per-run settings.
These sections may contain any entries that are accepted in other
sections.
\\\hline
%%
\ttt{[Cmdenv]} & Contains Cmdenv-specific settings.
For details, see section \ref{sec:ch-run-sim:cmdenv-section}
\\\hline
%%
\ttt{[Tkenv]} & Contains Tkenv-specific settings.
For details, see section \ref{sec:ch-run-sim:tkenv-section}
\\\hline
%%
\ttt{[Parameters]} & Contains values for module parameters that did not
get a value (or got \fname{input} value) inside the NED files.
For details, see section \ref{sec:ch-run-sim:parameter-settings}
\\\hline
%%
\ttt{[OutVectors]} & Configures recording of output vectors. You can specify
filtering by vector names and by simulation time (start/stop recording).
For details, see section \ref{sec:ch-run-sim:outvectors-section}
\\\hline
%%
\ttt{[DisplayStrings]} & Module display strings for Tkenv.
For details, see section \ref{sec:ch-run-sim:displaystrings-section}
\\\hline
%%
\end{longtable}



\subsection{The [General] section}
\label{sec:ch-run-sim:general-section}

The most important options of the \texttt{[General]} section are the
following.
\begin{itemize}
  \item{The \fpar{ini-warnings} option can be used for ``debugging'' ini
    files: if enabled, it lists which options were searched for but
    not found.}
  \item{The \fpar{network} option selects the model to be set up and run.}
  \item{The length of the simulation can be set with the
    \fpar{sim-time-limit} and the \fpar{cpu-time-limit} options (the
    usual time units such as ms, s, m, h, etc. can be used).}
  \item{The output file names can be set with the following options:
    \fpar{output-vector-file}, \fpar{output-scalar-file} and \fpar{snapshot-file}.}
\end{itemize}

The full list of supported options follows. Almost every one these options
can also be put into the \ttt{[Run \textit{n}]} sections. Per-run settings
have priority over globally set ones.


\begin{longtable}{|p{6.5cm}|p{7.5cm}|}
\hline
\tabheadcol
\tbf{Entry and default value} & \tbf{Description}\\\hline
\multicolumn{2}{|c|}{\tbf{[General]}} \\\hline
%%
\fpar{ini-warnings} = yes & Helps debugging of the ini file. If turned
on, {\opp} prints out the name of the entries it that it wanted to
read but they were not in the ini file.\\\hline
%%
\fpar{network} = & The name of the network to be simulated. \\\hline
%%
\fpar{snapshot-file} = omnetpp.sna & Name of the snapshot file. The result of
each \fname{snapshot()} call will be appended to this file. \\\hline
%%
\fpar{output-vector-file} = omnetpp.vec & Name of output vector file. \\\hline
%%
\fpar{output-scalar-file} = omnetpp.sca & Name of output scalar file. \\\hline
%%
\fpar{pause-in-sendmsg} = no & Only makes sense with step-by-step execution.
If enabled, {\opp} will split \fname{send()} calls to two steps.\\\hline
%%
\fpar{sim-time-limit} = & Duration of the simulation in simulation time.\\\hline
%%
\fpar{cpu-time-limit} = & Duration of the simulation in real time.\\\hline
%%
\fpar{random-seed} = & Random number seed for generator 0. Should be nonzero.\\\hline
%%
\mbox{\fpar{gen0-seed} = } \linebreak
\mbox{\fpar{gen1-seed} = } \linebreak
\mbox{...} & Seeds for the given random number generator. They should be
nonzero. \ttt{gen0-seed} is equivalent to \ttt{random-seed}.\\\hline
%%
\fpar{total-stack-kb} = & Specifies the total stack size (sum of all coroutine stacks)
in kilobytes. You need to increase this value if you get the
``Cannot allocate coroutine stack...'' error.\\\hline
%%
\fpar{load-libs} = & {\raggedright Name of shared libraries (.so files) to load after startup.
You can use it to load simple module code etc. Example:

\fpar{load-libs} = \ttt{../x25/x25.so ../lapb/lapb.so}}\\\hline
%%
\fpar{netif-check-freq} = & Used with parallel execution.\\\hline
%%
\mbox{\fpar{outputvectormanager-class} =} \linebreak
\cclass{cFileOutputVectorManager}
&
Part of the Envir\index{Envir} plugin mechanism: defines the name of
the output vector manager class to be used to record data from output
vectors\index{output!vector}.  The class has to implement the
\cclass{cOutputVectorManager} interface defined in \ttt{envirext.h}.\\\hline
%%
\mbox{\fpar{outputscalarmanager-class} =} \linebreak
\cclass{cFileOutputScalarManager}
&
Part of the Envir plugin mechanism: defines the name of the output
scalar manager class to be used to record data passed to
\fname{recordScalar()}. The class has to implement the
\cclass{cOutputScalarManager} interface defined in \ttt{envirext.h}.
\\\hline
%%
\mbox{\fpar{snapshotmanager-class} =} \linebreak
\cclass{cFileSnapshotManager}
&
Part of the Envir plugin mechanism: defines the name of the class to
handle streams to which \fname{snapshot()} writes its output.  The
class has to implement the \cclass{cSnapshotManager} interface defined
in \ttt{envirext.h}.\\\hline

\end{longtable}

\section{Cmdenv: the command-line interface}

The command line user interface\index{command line user interface} is
a small, portable and fast user interface that compiles and runs on
all platforms. Cmdenv\index{Cmdenv} is designed primarily for batch execution.

Cmdenv uses simply executes some or all simulation runs that are described
in the configuration file. If one run stops with an error message,
subsequent ones will still be executed. The runs to be executed can be
passed via command-line argument or in the ini file.

\subsection{Command-line switches}

A simulation program built with Cmdenv accepts the following command line
switches\index{command line switches}:

\begin{longtable}{lp{12cm}}
  \ttt{-h}
  &
  The program prints a short help message and the networks
  contained in the executable, then exits.\\

  \ttt{-f} \texttt{<}\textit{fileName\texttt{>}}
  &
  Specify the name of the configuration file.
  The default is \texttt{omnetpp.ini}\index{omnetpp.ini}.
  Multiple \ttt{-f} switches can be given; this allows you to partition your
  configuration file.  For example, one file can contain your general
  settings, another one most of the module parameters, another one the
  module parameters you change often.\\

  \ttt{-l} \texttt{<}\textit{fileName\texttt{>}}
  &
  Load a shared object\index{shared objects} (\texttt{.so} file on Unix).
  Multiple \ttt{-l} switches are accepted. Your \texttt{.so} files may contain module
  code etc. By dynamically loading all simple
  module code and compiled network description (\texttt{\_n.o} files
  on Unix) you can even eliminate the need to re-link the simulation
  program after each change in a source file.  (Shared objects can be
  created with \texttt{gcc -shared...})\\

  \ttt{-r} \texttt{<}\textit{runs\texttt{>}}
  &
  It specifies which runs should be executed (e.g. \ttt{-r 2,4,6-8}).
  This option overrides the \texttt{runs-to-execute=} option
  in the \texttt{[Cmdenv]} section of the ini file\index{ini file}
  (see later).\\
\end{longtable}

All other options are read from the configuration file.

An example of running an {\opp} executable with the -h flag:

\begin{verbatim}

% ./fddi -h

OMNeT++ Discrete Event Simulation  (C) 1992-2003 Andras Varga
See the license for distribution terms and warranty disclaimer
Setting up Cmdenv (command-line user interface)...

Command line switches:
  -h            print this help and exit.
  -f <inifile>  use the given ini file instead of omnetpp.ini.
  -r <runs>     execute the specified runs in the ini file.
                <runs> is a comma-separated list of run numbers or
                run number ranges, for example 1,2,5-10.
  -l <library>  load the specified shared library on startup.
                The library can contain modules, networks, etc.

Available networks:
  FDDI1
  NRing
  TUBw
  TUBs

Available modules:
  FDDI_MAC
  FDDI_MAC4Ring
  ...

Available channels:


End run of OMNeT++
\end{verbatim}


\subsection{Cmdenv ini file options}
\label{sec:ch-run-sim:cmdenv-section}

Cmdenv can be executed in two modes, selected by the \ttt{express-mode} ini file entry:

\begin{itemize}
    \item \tbf{Normal} (non-express) mode is for debugging: detailed information
        will be written to the standard output (event banners, module output,
        etc).
    \item \tbf{Express} mode can be used for long simulation runs: only
        periodical status update is displayed about the progress of the
        simulation.
\end{itemize}

The full list of ini file options recognized by Cmdenv:

\begin{longtable}{|p{6.5cm}|p{7.5cm}|}
\hline
\tabheadcol
\tbf{Entry and default value} & \tbf{Description}\\\hline
\multicolumn{2}{|l|}{\tbf{[Cmdenv]}}\\\hline
%%
\fpar{runs-to-execute} = & Specifies which simulation runs should be executed.
It accepts a comma-separated list of run numbers or run number ranges, e.g.
\ttt{1,3-4,7-9}. If the value is missing, Cmdenv executes all runs that have
ini file sections; if no runs are specified in the ini file, Cmdenv does one run.
The -r command line option overrides this ini file setting. \\\hline
%%
\fpar{express-mode}=yes/no (default: no) & Selects ``normal'' (debug/trace) or ``express'' mode.
\\\hline
%%
\fpar{module-messages}=yes/no (default: yes) & In normal mode only:
printing module ev<< output on/off \\\hline
%%
\fpar{event-banners}=yes/no (default: yes) & In normal mode only:
printing event banners on/off \\\hline
%%
\fpar{message-trace}=yes/no (default: no) & In normal mode only: print a line
about each message sending (by \fname{send()},\fname{scheduleAt()}, etc)
and delivery on the standard output \\\hline
%%
\fpar{autoflush}=yes/no (default: no) &  Call \fname{fflush(stdout)} after each
event banner or status update; affects both express and normal mode. Turning on
autoflush can be useful with printf-style debugging for tracking down
program crashes. \\\hline
%%
\fpar{status-frequency}=<integer> (default: 50000) & In express mode only:
print status update every n events (on today's computers, and
for a typical model, this will produce an update every few seconds,
perhaps a few times per second) \\\hline
%%
\fpar{performance-display}=yes/no (default: yes) & In express mode only:
print detailed performance information. Turning it on results in a 3-line
entry printed on each update, containing ev/sec, simsec/sec, ev/simsec,
number of messages created/still present/currently scheduled in FES.
\\\hline
%%
\fpar{extra-stack} = 16384 & Specifies the extra amount of stack
(bytes) that is reserved for each \fname{activity()}
simple module when the simulation is linked with Cmdenv. \\\hline
\end{longtable}

\subsection{Interpreting Cmdenv output}
\label{sec:ch-run-sim:interpreting-cmdenv-output}

When the simulation is running in ``express'' mode with detailed
performance display enabled, Cmdenv periodically outputs a three-line
status info about the progress of the simulation.
The output looks like this:

\begin{verbatim}
...
** Event #250000   T=123.74354 ( 2m  3s)    Elapsed: 0m 12s
     Speed:     ev/sec=19731.6   simsec/sec=9.80713   ev/simsec=2011.97
     Messages:  created: 55532   present: 6553   in FES: 8
** Event #300000   T=148.55496 ( 2m 28s)    Elapsed: 0m 15s
     Speed:     ev/sec=19584.8   simsec/sec=9.64698   ev/simsec=2030.15
     Messages:  created: 66605   present: 7815   in FES: 7
...
\end{verbatim}

The first line of the status display (beginning with \ttt{**})
contains:

\begin{itemize}
   \item{how many events have been processed so far}
   \item{the current simulation time (T), and}
   \item{the elapsed time (wall clock time) since the beginning of the simulation run.}
\end{itemize}

The second line displays info about simulation performance:

\begin{itemize}
   \item{\ttt{ev/sec} indicates \textit{performance}: how many events are processed
     in one real-time second.  On one hand it depends on your hardware
     (faster CPUs process more events per second), and on the other hand
     it depends on the complexity (amount of calculations) associated
     with processing one event. For example, protocol simulations tend to require
     more processing per event than e.g. queueing networks, thus
     the latter produce higher ev/sec values.
     In any case, this value is independent of the size (number of modules) in your model.}
   \item{\ttt{simsec/sec} shows \textit{relative speed} of the simulation, that is,
     how fast the simulation is progressing compared to real time, how many
     simulated seconds can be done in one real second. This value virtuall depends
     on everything: on the hardware, on the size of the simulation model,
     on the complexity of events, and the average simulation time between events as well.}
   \item{\ttt{ev/simsec} is the \textit{event density}: how many events are
     there per simulated second. Event density only depends on the simulation model,
     regardless of the hardware used to simulate it: in a cell-level ATM simulation
     you'll have very hight values ($10^9$), while in a bank teller simulation
     this value is probably well under 1. It also depends on the size of your
     model: if you double the number of modules in your model, you can expect
     the event density double, too.}
\end{itemize}

The third line displays the number of messages, and it is important
because it may indicate the `health' of your simulation.

\begin{itemize}
   \item{\ttt{Created}: total number of message objects created since the
     beginning of the simulation run. This does not mean that this many message
     object actually exist, because some (many) of them may have been deleted
     since then. It also does not mean that \textit{you} created all those
     messages -- the simulation kernel also creates messages for its own use
     (e.g. to implement \ttt{wait()} in an \ttt{activity()} simple module).}
   \item{\ttt{Present}: the number of message objects currently present
     in the simulation model, that is, the number of messages created (see above)
     minus the number of messages already deleted. This number includes
     the messages in the FES.}
   \item{\ttt{In FES}: the number of messages currently scheduled in the
     Future Event Set.}
\end{itemize}


The second value, the number of messages present is more useful than
perhaps one would initially think. It can indicator of the `health' of the simulation:
if it is growing steadily, then either you have a memory leak and losing
messages (which indicates a programming error), or the network you simulate is
overloaded and queues are steadily filling up (which might indicate wrong input
parameters).

Of course, if the number of messages does not increase, it does not mean
that you do \textit{not} have a memory leak (other memory leaks are also
possible). Nevertheless the value is still useful, because by far the
most common way of leaking memory in a simulation is by not deleting messages.



\section{Tkenv: the graphical user interface}

\subsubsection{Features}

Tkenv\index{Tkenv} is a portable graphical windowing user interface.
Tkenv supports interactive execution of the simulation, tracing and
debugging\index{simulation!debugging}. Tkenv is recommended in the
development stage of a simulation or for presentation and educational
purposes, since it allows one to get a detailed picture of the state
of simulation at any point of execution and to follow what happens
inside the network. The most important feaures are:
\begin{itemize}
  \item{message flow animation}
  \item{graphical display of statistics (histograms etc.) and output
    vectors during simulation execution}
  \item{separate window for each module's text output}
  \item{scheduled messages can be watched in a window as simulation
    progresses}
  \item{event-by-event, normal and fast execution}
  \item{labeled breakpoints}
  \item{inspector windows to examine and alter objects and variables
    in the model}
  \item{simulation can be restarted}
  \item{snapshots (detailed report about the model: objects, variables
    etc.)}
\end{itemize}


Tkenv makes it possible to view simulation results (output vectors
etc.) during execution. Results can be displayed as histograms and
time-series diagrams. This can speed up the process of verifying the
correct operation of the simulation program and provides a good
environment for experimenting with the model during execution.  When
used together with \fprog{gdb} or \fprog{xxgdb}, Tkenv can speed up
debugging a lot.

Tkenv is built with Tcl/Tk, and it work on all platforms where
Tcl/Tk has been ported to: Unix/X, Windows, Macintosh.
You can get more information about Tcl/Tk on the Web pages listed
in the Reference.

\subsection{Command-line switches}

A simulation program built with Tkenv accepts the following command line
switches\index{command line switches}:

\begin{longtable}{lp{12cm}}
  \ttt{-h}
  &
  The program prints a short help message and the networks
  contained in the executable, then exits.\\

  \ttt{-f }\textit{<fileName>}
  &
  Specify the name of the configuration file.
  The default is \texttt{omnetpp.ini}\index{omnetpp.ini}.
  Multiple \ttt{-f} switches can be given; this allows you to partition your
  configuration file.  For example, one file can contain your general
  settings, another one most of the module parameters, another one the
  module parameters you change often.\\

  \ttt{-l }\textit{<fileName>}
  &
  Load a shared object\index{shared objects} (\texttt{.so} file on Unix).
  Multiple \ttt{-l} switches are accepted. Your \texttt{.so} files may contain module
  code etc. By dynamically loading all simple
  module code and compiled network description (\texttt{\_n.o} files
  on Unix) you can even eliminate the need to re-link the simulation
  program after each change in a source file.  (Shared objects can be
  created with \texttt{gcc -shared...})\\
\end{longtable}

\subsection{Tkenv ini file settings}
\label{sec:ch-run-sim:tkenv-section}

Tkenv accepts several settings in the \ttt{[Tkenv]} section of the ini file.
These settings can also be set within the graphical environment too,
via menu items and dialogs.


\begin{longtable}{|p{6.5cm}|p{7.5cm}|}
\hline
\tabheadcol
\tbf{Entry and default value} & \tbf{Description}\\\hline
\multicolumn{2}{|c|}{\tbf{[Tkenv]}}\\\hline
%%
\fpar{default-run} = 1 & Specifies which run Tkenv should set up
automatically after startup. If there's no default-run= entry or the
value is 0, Tkenv will ask which run to set up. \\\hline
%%
\fpar{use-mainwindow} = yes & Enables/disables writing \textit{ev} output to the Tkenv main window. \\\hline
%%
\fpar{print-banners} = yes & Enables/disables printing banners for
each event.\\\hline
%%
\fpar{breakpoints-enabled} = yes & Specifies whether the simulation
should be stopped at each \fname{breakpoint()} call in the
simple modules. \\\hline
%%
\fpar{update-freq-fast} = 10 & Number of events executed between two
display updates when in \textit{Fast} execution mode. \\\hline
%%
\fpar{update-freq-express} = 500 & Number of events executed between
two display updates when in \textit{Express} execution mode. \\\hline
%%
\fpar{animation-delay} = 0.3s & Delay between steps when you slow-execute the simulation. \\\hline
%%
\fpar{animation-enabled} = yes & Enables/disables message flow animation. \\\hline
%%
\fpar{animation-msgnames} = yes & Enables/disables displaying message names during message flow
animation. \\\hline
%%
\fpar{animation-msgcolors} = yes & Enables/disables using different colors
for each message kind during message flow animation. \\\hline
%%
\fpar{animation-speed} = 1.0 & Specifies the speed of message flow animation. \\\hline
%%
\fpar{extra-stack} = 32768 & Specifies the extra amount of stack
(bytes) that is reserved for each \textit{\fname{activity()}}
simple module when the simulation is linked with
Tkenv. \\\hline
\end{longtable}


\subsection{Using the graphical environment}

\subsubsection{Simulation running modes in Tkenv}


Tkenv has the following modes for running the simulation :

\begin{itemize}
   \item{Step}
   \item{Run}
   \item{Fast run}
   \item{Express run}
\end{itemize}


The running modes have their corresponding buttons on Tkenv's
toolbar.


In \tbf{Step} mode, you can execute the simulation event-by-event.

In \tbf{Run} mode, the simulation runs with all tracing aids on.
Message animation is active and inspector windows are updated
after each event. Output messages are displayed in the main window
and module output windows. You can stop the simulation with the
Stop button on the toolbar. You can fully interact with the user
interface while the simulation is running: you can open inspectors
etc.

In \tbf{Fast} mode, animation is turned off. The inspectors and
the message output windows are updated after each 10 events (the
actual number can be set in Options{\textbar}Simulation options and
also in the ini file). Fast mode is several times faster than
the Run mode; the speedup can get close to 10 (or the configured
event count).

In \tbf{Express} mode, the simulation runs at about the same speed
as with Cmdenv, all tracing disabled. Module output is not recorded
in the output windows any more. You can interact with the simulation
only once in a while (1000 events is the default as I recall),
thus the run-time overhead of the user interface is minimal.
You have to explicitly push the Update inspectors button if you
want an update.

Tkenv has a status bar which is regularly updated while the simulation
is running. The gauges displayed are similar to those in Cmdenv,
described in section \ref{sec:ch-run-sim:interpreting-cmdenv-output}.


\subsubsection{Inspectors}


In Tkenv, objects can be viewed through inspectors. To start, choose
Inspect{\textbar}Network from the menu. Usage should be obvious; just
use double-clicks and popup menus that are brought up by
right-clicking. In Step, Run and Fast Run modes, inspectors are
updated automatically as the simulation progresses. To make ordinary
variables (int, double, char etc.) appear in Tkenv, use the
\fname{WATCH()} macro in the C++ code.

Tkenv inspectors also display the object pointer, and can also copy
the pointer value to the clipboard. This can be invaluable for debugging:
when the simulation is running under a debugger like gdb or the MSVC IDE,
you can paste the object pointer into the debugger and have closer look
at the data structures.


\subsubsection{Configuring Tkenv}


In case of nonstandard installation, it may be necessary to set the
\fvar{OMNETPP\_TKENV\_DIR} environment variable so that Tkenv can find
its parts written in Tcl script.

\begin{sloppypar}
The default path from where the icons are loaded can be changed with
the \fvar{OMNETPP\_BITMAP\_PATH} variable, which is a
semicolon-separated list of directories and defaults to
``\textit{omnetpp-dir}/bitmaps;.;./bitmaps''.
\end{sloppypar}

\subsubsection{Embedding Tcl code into the executable}

A significant part of Tkenv is written in Tcl, in several
\texttt{.tcl} script files. The default location of the scripts is
passed compile-time to \texttt{tkapp.cc}, and it can be overridden at
run-time by the \fvar{OMNETPP\_TKENV\_DIR} environment variable. The
existence of a separate script library can be inconvenient if you want
to carry standalone simulation executables to different machines. To
solve the problem, there is a possibility to compile the script parts
into Tkenv.

The details: the \fprog{tcl2c} program (its C source is there in the
Tkenv directory) is used to translate the \texttt{.tcl} files into C
code (\texttt{tclcode.cc}), which gets included into
\texttt{tkapp.cc}. This possibility is built into the makefiles
and can be optionally enabled.

\subsection{In Memoriam\dots }

There used to be other windowing user interfaces which have been removed
from the distribution:

\begin{itemize}
  \item \tbf{TVEnv}. A Turbo Vision-based user interface, the first
    interactive UI for {\opp}. Turbo Vision was an excellent
    character-graphical windowing environment, originally shipped with
    Borland C++ 3.1.
  \item \tbf{XEnv}. A GUI written in pure X/Motif. It was an
    experiment, written before I stumbled into Tcl/Tk and discovered
    its immense productivity in GUI building. XEnv never got too far
    because it was really very-very slow to program in Motif\dots
\end{itemize}


\section{More about omnetpp.ini}


\subsection{Module parameters in the configuration file}
\label{sec:ch-run-sim:parameter-settings}
\index{module!parameters}

Values for module parameters go into the \texttt{[Parameters]} or the
\texttt{[Run 1]}, \texttt{[Run 2]} etc. sections of the ini file. The
run-specific settings take precedence over the overall settings.
Parameters that were assigned a (non-input) value in the NED file are
not influenced by ini file settings.

Wildcards (*,?)\index{ini file!wildcards} can be used to supply values
to several model parameters at a time. Filename-style (glob) and not
regex-style pattern matching is used. Character ranges use curly
braces instead of square brackets to avoid interference with the
notation of module vectors: \{a-zA-Z\}. If a parameter name matches
several wildcards-patterns, the first matching occurrence is used.


An example ini file:

\begin{Verbatim}[commandchars=\\\{\}]
# omnetpp.ini

\tbf{[Parameters]}
token.num_stations = 3
token.num_messages = 10000

\tbf{[Run 1]}
token.stations[*].wait_time = 10ms

\tbf{[Run 2]}
token.stations[0].wait_time = 5ms
token.stations[*].wait_time = 1000ms
\end{Verbatim}


\subsection{Configuring output vectors}
\label{sec:ch-run-sim:outvectors-section}

As a simulation program is evolving, it is becoming capable of
collecting more and more statistics. The size of output vector
files\index{output!vector file} can easily reach a magnitude of
several ten or hundred megabytes, but very often, only some of the
recorded statistics are interesting to the analyst.


In {\opp}, you can control how \cclass{cOutVector} objects record data
to disk. You can turn output vectors on/off or you can assign a result
collection interval. Output vector configuration is given in the
\texttt{[OutVectors]} section of the ini file, or in the \texttt{[Run
  1]}, \texttt{[Run 2]} etc sections individually for each run. By
default, all output vectors are turned on.


Entries configuring output vectors can be like that:

\begin{Verbatim}[commandchars=\\\{\}]
\textit{module-pathname}.\textit{objectname}.enabled = yes/no
\textit{module-pathname}.\textit{objectname}.interval = \textit{start}..\textit{stop}
\textit{module-pathname}.\textit{objectname}.interval = ..\textit{stop}
\textit{module-pathname}.\textit{objectname}.interval = \textit{start}..
\end{Verbatim}

The object name is the string passed to \cclass{cOutVector} in its constructor
or with the \fname{setName()} member function.

\begin{verbatim}
cOutVector eed("End-to-End Delay",1);
\end{verbatim}

Start and stop values can be any time specification accepted
in NED and config files (e.g. \textit{10h 30m 45.2s}).


As with parameter names, wildcards are allowed in the object
names and module path names.

An example:

\begin{verbatim}
#
# omnetpp.ini
#

[OutVectors]
*.interval = 1s..60s
*.End-to-End Delay.enabled = yes
*.Router2.*.enabled = yes
*.enabled = no
\end{verbatim}


The above configuration limits collection of all output vectors
to the 1s..60s interval, and disables collection of output vectors
except all end-to-end delays and the ones in any module called Router2.

%%
%% NOTE: Module parameter logging not supported since 2.1.
%%
%
% \subsection{Module parameter logging}
%
% It is possible to log all the changes to module parameters into a text
% file\index{module!parameter logging}. This can be useful when the
% simulation contains run-time tuning of one or more module parameters
% and one wants to have the trajectory documented.
%
%
% Module parameter logging must be explicitly enabled from the
% header file if one wants to use it:
%
% begin{verbatim}
% [General]
% log-parchanges = yes
% parchange-file = token.pch
% end{verbatim}
%
%
% The format of the parameter change file is similar to the that
% of the output vector file.
%
% If a parameter is taken by reference\index{module!parameters!by reference} by
% several modules, any change to the parameter will appear in the file
% under the name of the top-level parameter, no matter which module
% actually changed it and under what name.
%


\subsection{Display strings}
\label{sec:ch-run-sim:displaystrings-section}

Display strings\index{display strings} control the modules' graphical
appearance in the Tkenv user interface. Display strings can be
assigned to modules, submodules and gates (a connection's display
string is stored in its ``from'' gate). Display strings can be
hardcoded into the NED file or specified in the configuration file.
(Hardcoded display strings take precedence over the ones given in ini
files.) Format of display string are documented in section
\ref{sec:ch-ned-lang:display-strings}).

Display strings can appear in the \texttt{[DisplayStrings]} section of
the ini file. They are expected as entries in one of the following
forms:

\begin{verbatim}
moduletype = "..."
moduletype.submodulename = "..."

moduletype.inputgatename = "..."
moduletype.submodulename.outputgatename = "..."
\end{verbatim}

As with parameter names, wildcards\index{display strings!wildcards}
are allowed in module types, submodule and gate names.


\subsection{Specifying seed values}

As is was pointed out earlier, it is of great importance that
different simulation runs and different random number sources
within one simulation run use non-overlapping sequences of random
numbers\index{random!numbers}.


In {\opp}, you have three choices:
\begin{enumerate}
  \item{Automatic seed selection.}
  \item{Specify seeds in the ini file (with the help of the seedtool
    program, see later)}
  \item{Manually set the seed from within the program.}
\end{enumerate}

If you decide for automatic seed selection\index{seed!automatic selection},
do not specify any seed value in the ini file. For the
random number generators, {\opp} will automatically select seeds that
are 1,000,000 values apart in the sequence. If you have several runs,
each run is started with a fresh set of seeds that are 1,000,000
values apart from the seeds used for previous runs. Since the
generation of new seed values is costly, {\opp} has a table of
pre-calculated seeds (256 values); if they are all used up, {\opp}
starts from the beginning of the table again.

\textbf{Warning!} Be aware that each time the simulation program
is started, {\opp} starts assigning seeds from the beginning
of the table. That is, if you execute Run 1, Run 2, Run 3 one
at a time (e.g. from a shell script, using the Cmdenv -r command-line
flag), all your runs will be executed using the \textit{same} seeds!
This behavior is almost surely not what you want, and it will be
fixed in future versions of {\opp}. Until then, it is a good
idea to stick to manually generating seeds and explicitly adding them
to the ini file.


Automatic seed selection may not be appropriate for you for several
reasons. First, you may need more than 256 seeds values; or, if you
use variance reduction techniques, you may want to use the same seeds
for several simulation runs. In this case, there is a standalone
program to generate appropriate seed values (\fprog{seedtool} will be
discussed in Section \ref{sec:ch-run-sim:choosing-good-seed}), and you
can specify the seeds explicitly in the ini file.


The following ini file explicitly initializes two of the random
number generators, and uses different seed values for each run:

\begin{verbatim}
[Run 1]
gen0-seed = 1768507984
gen1-seed = 33648008

[Run 2]
gen0-seed = 1082809519
gen1-seed = 703931312
...
\end{verbatim}


If you want the same seed values for all runs, you will write
something like this:

\begin{verbatim}
[General]
gen0-seed = 1768507984
gen1-seed = 33648008
\end{verbatim}


All other random number generators (2,3,...) will have their seeds
automatically assigned.  As a third way, you can also set the seed
values from the code of a simple module using
\fname{genk\_randseed()}, but I see no reason why you would want to do
so.


\section{Choosing good seed values: the seedtool utility}
\label{sec:ch-run-sim:choosing-good-seed}

For selecting good seeds, the \fprog{seedtool} program can be used (it
is in the utils directory). When started without command-line
arguments, the program prints out the following help:

\begin{verbatim}
seedtool - part of OMNeT++, (c) 1992-2001 Andras Varga, TU Budapest
See the license for distribution terms and warranty disclaimer.

A tool to help select good random number generator seed values.
Usage:
  seedtool i seed         - index of `seed' in cycle
  seedtool s index        - seed at index `index' in cycle
  seedtool d seed1 seed2  - distance of `seed1' and `seed2' in cycle
  seedtool g seed0 dist   - generate seed `dist' away from `seed0'
  seedtool g seed0 dist n - generate `n' seeds `dist' apart, starting
                            at `seed0'
  seedtool t              - generate hashtable
  seedtool p              - print out hashtable
\end{verbatim}


The last two options, p and t were used internally to generate
a hash table of pre-computed seeds that greatly speeds up the
tool. For practical use, the g option is the most important.
Suppose you have 4 simulation runs that need two independent
random number generators each and you want to start their seeds
at least 10,000,000 values apart. The first seed value can be
simply 1. You would type the following command:

\begin{verbatim}
C:\OMNETPP\UTILS> seedtool g 1 10000000 8
\end{verbatim}


The program outputs 8 numbers that can be used as random number
seeds:

\begin{verbatim}
1768507984
33648008
1082809519
703931312
1856610745
784675296
426676692
1100642647
\end{verbatim}


You would specify these seed values in the ini file.



\section{Repeating or iterating simulation runs}

Once your model works reliably, you'll usually want to run several
simulations. You may want to run the model with various
parameter settings, or you may want \textit{(should want?)} to
run the same model with the same parameter settings but with
different random number generator seeds, to achieve statistically
more reliable results.

Running a simulation several times by hand can easily become tedious,
and then a good solution is to write a control script that
takes care of the task automatically. Unix shell is
a natural language choice to write the control script in,
but other languages like Perl, Matlab/Octave, Tcl, Ruby might also have
justification for this purpose.

The next sections are only for Unix users. We'll use the
Unix `Bourne' shell (\ttt{sh}, \ttt{bash}) to write the control script.
If you'd prefer Matlab/Octave, the \ttt{contrib/octave/} directory
contains example scripts (contributed by Richard Lyon).


\subsection{Executing several runs}

In simple cases, you may define all simulation runs needed in the
\ttt{[Run 1]}, \ttt{[Run 2]}, etc. sections of \ttt{omnetpp.ini},
and invoke your simulation with the -r flag each time.
The -f flag lets you use a file name different from \ttt{omnetpp.ini}.

The following script executes a simulation named \ttt{wireless}
several times, with parameters for the different runs
given in the \ttt{runs.ini} file.

\begin{verbatim}
#! /bin/sh
./wireless -f runs.ini -r 1
./wireless -f runs.ini -r 2
./wireless -f runs.ini -r 3
./wireless -f runs.ini -r 4
...
./wireless -f runs.ini -r 10
\end{verbatim}

To run the above script, type it in a text file called e.g. \ttt{run},
give it \ttt{x} (executable) permission using \ttt{chmod},
then you can execute it by typing \ttt{./run}:

\begin{verbatim}
% chmod +x run
% ./run
\end{verbatim}

You can simplify the above script by using a \textit{for} loop.
In the example below, the variable \ttt{i} iterates through
the values of list given after the \ttt{in} keyword.
It is very practical, since you can leave out or add runs,
or change the order of runs by simply editing the list --
to demonstrate this, we skip run 6, and include run 15 instead.

\begin{verbatim}
#! /bin/sh
for i in 3 2 1 4 5 7 15 8 9 10; do
   ./wireless -f runs.ini -r $i
done
\end{verbatim}

If you have many runs, you can use a C-style loop:

\begin{verbatim}
#! /bin/sh
for ((i=1; $i<50; i++)); do
   ./wireless -f runs.ini -r $i
done
\end{verbatim}


\subsection{Variations over parameter values}

It may not be practical to hand-write descriptions of all runs
in an ini file, especially if there are many parameter
settings to try, or you want to try all possible
combinations of two or more parameters.
The solution might be to generate only a small fraction
of the ini file with the variable parameters, and
use it via ini file inclusion. For example, you might
write your \ttt{omnetpp.ini} like this:

\begin{verbatim}
[General]
network = Wireless

[Parameters]
Wireless.n = 10
...   # other fixed parameters
include params.ini  # include variable part
\end{verbatim}

And have the following as control script. It uses two nested loops to explore
all possible combinations of the \textit{alpha} and \textit{beta} parameters.
Note that \ttt{params.ini} is created by redirecting the \ttt{echo}
output into file, using the \ttt{>} and \ttt{>>} operators.

\begin{verbatim}
#! /bin/sh
for alpha in 1 2 5 10 20 50; do
   for beta in 0.1 0.2 0.3 0.4 0.5; do
       echo "Wireless.alpha=$alpha" > params.ini
       echo "Wireless.beta=$beta" >> params.ini
       ./wireless
   done
done
\end{verbatim}


As a heavy-weight example, here's the ``runall'' script of
Joel Sherrill's \textit{File System Simulator}. It also demonstrates
that loops can iterate over string values too, not just numbers.
(\texttt{omnetpp.ini} includes the generated \texttt{algorithms.ini}.)

Note that instead of redirecting every \ttt{echo} command to file,
they are grouped using parentheses, and redirected together.
The net effect is the same, but you can spare some typing this way.

\begin{verbatim}
#! /bin/bash
#
# This script runs multiple variations of the file system simulator.
#
all_cache_managers="NoCache FIFOCache LRUCache PriorityLRUCache..."
all_schedulers="FIFOScheduler SSTFScheduler CScanScheduler..."

for c in ${all_cache_managers}; do
  for s in ${all_schedulers}; do
  (
    echo "[Parameters]"
    echo "filesystem.generator_type = \"GenerateFromFile\""
    echo "filesystem.iolibrary_type = \"PassThroughIOLibrary\""
    echo "filesystem.syscalliface_type = \"PassThroughSysCallIface\""
    echo "filesystem.filesystem_type = \"PassThroughFileSystem\""
    echo "filesystem.cache_type = \"${c}\""
    echo "filesystem.blocktranslator_type = \"NoTranslation\""
    echo "filesystem.diskscheduler_type = \"${s}\""
    echo "filesystem.accessmanager_type = \"MutexAccessManager\""
    echo "filesystem.physicaldisk_type = \"HP97560Disk\""
  ) >algorithms.ini

  ./filesystem
  done
done
\end{verbatim}



\subsection{Variations over seed value (multiple independent runs)}

The same kind of control script can be used if you want to execute
several runs with different random seeds\index{random!seeds}.
The following code does 500 runs with independent seeds.
(\texttt{omnetpp.ini} should include \ttt{parameters.ini}.)

The seeds are 10 million numbers apart in the sequence (\ttt{seedtool}
parameter), so one run should not use more random numbers than this,
otherwise there will be overlaps in the sequences and the runs
will not be independent.

\begin{verbatim}
#! /bin/sh
seedtool g 1 10000000 500 > seeds.txt
for seed in `cat seeds.txt`; do
   (
     echo "[General]"
     echo "random-seed = ${seed}"
     echo "output-vector-file = xcube-${seed}.vec"
   ) > parameters.ini
   ./xcube
done
\end{verbatim}





\section{Akaroa support: Multiple Replications in Parallel}

\subsection{Introduction}

Typical simulations are Monte-Carlo simulations: they use
(pseudo-)random numbers to drive the simulation model.
For the simulation to produce statistically reliable results,
one has to carefully consider the following:

\begin{itemize}
  \item{When is the initial transient over, when can we start
    collecting data? We usually do not want to include the
    initial transient when the simulation is still ``warming up.''}
  \item{When can we stop the simulation? We want to wait long enough
    so that the statistics we are collecting can ``stabilize'',
    can reach the required sample size to be statistically trustable.}
\end{itemize}

Neither questions are trivial to answer. One might just suggest
to wait ``very long'' or ``long enough''. However, this is neither
simple (how do you know what is ``long enough''?) nor practical
(even with today's high speed processors simulations of modest complexity
can take hours, and one may not afford multiplying runtimes by,
say, 10, ``just to be safe.'') If you need further convincing,
please read \cite{Pawlikowsky02} and be horrified.

A possible solution is to look at the statistics while the simulation
is running, and decide at runtime when enough data have been
collected for the results to have reached the required accuracy.
One possible criterion is given by the confidence level,
more precisely, by its width relative to the mean.
But ex ante it is unknown how many observations have to be collected
to achieve this level -- it must be determined runtime.


\subsection{What is Akaroa}

Akaroa \cite{Akaroa99} addresses the above problem.
According to its authors, Akaroa (Akaroa2) is a ``fully automated
simulation tool designed for running distributed stochastic simulations
in MRIP scenario'' in a cluster computing environment.

MRIP stands for \textit{Multiple Replications in Parallel}.
In MRIP, the computers of the cluster run independent replications
of the whole simulation process (i.e. with the same parameters but
different seed for the RNGs (random number generators)),
generating statistically equivalent streams of simulation output data.
These data streams are fed to a global data analyser responsible for
analysis of the final results and for stopping the simulation
when the results reach a satisfactory accuracy.

The independent simulation processes run independently of one another
and continuously send their observations to the central analyser
and control process. This process \textit{combines} the independent data streams,
and calculates from these observations an overall estimate of the mean value
of each parameter.
Akaroa2 decides by a given confidence level and precision
whether it has enough observations or not. When it judges that is
has enough observations it halts the simulation.

If \textit{n} processors are used, the needed simulation execution time
is usually \textit{n} times smaller compared to a one-processor
simulation (the required number of observations are produced sooner).
Thus, the simulation would be sped up approximately in proportion
to the number of processors used and sometimes even more.

Akaroa was designed at the University of Canterbury in Christchurch, New Zealand
and can be used free of charge for teaching and non-profit research activities.


\subsection{Using Akaroa with {\opp}}

\subsubsection{Akaroa}

Before the simulation can be run in parallel under Akaroa, you have to
start up the system:

\begin{itemize}
  \item{Start \ttt{akmaster} running in the background on some host.}
  \item{On each host where you want to run a simulation engine,
     start \ttt{akslave} in the background.}
\end{itemize}

Each \ttt{akslave} establishes a connection with the \ttt{akmaster}.

Then you use \ttt{akrun} to start a simulation. \ttt{akrun} waits
for the simulation to complete, and writes a report of the results
to the standard output. The basic usage of the \ttt{akrun} command is:

\begin{verbatim}
akrun -n num_hosts command [argument..]
\end{verbatim}

where \textit{command} is the name of the simulation you want to start.
Parameters for Akaroa are read from the file named \ttt{Akaroa} in
the working directory. Collected data from the processes are
sent to the \ttt{akmaster} process, and when the required precision
has been reached, \ttt{akmaster} tells the simulation processes to
terminate. The results are written to the standard output.

The above description is of course not detailed enough help you
set up and successfully use Akaroa -- for that you need to read the
Akaroa manual. The purpose was rather to give you the ``flavour''
of using it.

\subsubsection{Configuring {\opp} for Akaroa}

First of all, you have to compile {\opp} with Akaroa support enabled.

The {\opp} simulation must be configured in \ttt{omnetpp.ini}
so that it passes the observations to Akaroa. The simulation model itself does
not need to be changed (except for RNGs, see later) -- it continues to write
the observations into output vectors (\cclass{cOutVector} objects,
see chapter \ref{cha:the-simulation-library}). You can place some of
the output vectors under Akaroa control.

You need to add the following to \ttt{omnetpp.ini}:

\begin{verbatim}
[General]
outputvectormanager-class="AkOutputVectorManager"
\end{verbatim}

The above line replaces the normal output vector handler
by its Akaroa-enabled version, using the Envir plugin interface.

Also, you have to specify which output vectors you want to
be under Akaroa control. By default, all output vectors are under Akaroa
control; the

\begin{verbatim}
<modulename>.<vectorname>.akaroa=false
\end{verbatim}

setting can be used to make Akaroa ignore specific vectors.
If you only want a few vectors be placed under Akaroa,
you can use the following ``trick'':

\begin{verbatim}
<modulename>.<vectorname1>.akaroa=true
<modulename>.<vectorname2>.akaroa=true
...
*.*.akaroa=false
\end{verbatim}


\subsubsection{Using shared file systems}

It is usually practical to have the same physical disk mounted (e.g. via NFS or Samba)
on all computers in the cluster. However, because all {\opp} simulation
processes run with the same settings, they would overwrite each other's
output files. Your can prevent this from happening using the
\ttt{fname-append-host} ini file entry:

\begin{verbatim}
[General]
fname-append-host=yes
\end{verbatim}

When turned on, it appends the host name to the names of the output
files (output vector, output scalar, snapshot files).


\subsubsection{Random number generation}

Another important point is that you cannot use the random number
generators provided by {\opp}, but rather you have to obtain
random numbers from Akaroa.

Unfortunately, {\opp}'s RNGs do not (yet) know anything about Akaroa.
Remember, all simulation processes are run with exactly the same
configuration -- including the same RNG seeds.
That is, if you'd use {\opp}'s own RNGs,
all simulation processes would use \textit{identical} random number streams,
thus executing \textit{exactly the same sequence of events!}
This is clearly not what you want or what Akaroa expects.

Akaroa provides the following random number functions. The underlying
RNG is a Combined Multiple Recursive pseudorandom
number generator (CMRG) with a period of approximately $2^{191}$
random numbers, and provides a unique stream of random numbers
for every simulation engine.

Future versions of {\opp} will wrap the random number functions
of Akaroa, thus requiring no modifications to simulation programs.


\begin{verbatim}
#include <akaroa/distribution.H>

real Uniform(real a, real b);
long UniformInt(long n0, long n1);
long Binomial(long n, real p);
real Exponential(real m);
real Erlang(real m, real s);
real HyperExponential(real m, real s);
real Normal(real m, real s);
real LogNormal(real m, real s);
long Geometric(real m);
real HyperGeometric(real m, real s);
long Poisson(real m);
real Weibull(real alpha, real beta);
\end{verbatim}





\section{Typical problems}

\subsection{Stack problems}

\subsubsection{``Stack violation (\textit{FooModule} stack too small?) in module \textit{bar.foo}''}
\index{stack!too small}

{\opp} detected that the module has used more stack space than it has
allocated. You should increase the stack for that module type. You can call
the \fname{stackUsage()} from \fname{finish()} to find out actually
how much stack the module used.


\subsubsection{``Error: Cannot allocate \textit{nn} bytes stack for module \textit{foo.bar''}}

The resolution depends on whether you are using {\opp} on Unix or on Windows.

\textbf{Unix.}
If you get the above message, you have to increase the total stack
size\index{stack!size} (the sum of all coroutine stacks). You can do
so in \texttt{omnetpp.ini}:

\begin{verbatim}
[General]
total-stack-kb = 2048 # 2MB
\end{verbatim}

There is no penalty if you set \fpar{total-stack-kb} too high. I
recommend to set it to a few K less than the maximum process stack
size allowed by the operating system (\fprog[ulimit]{ulimit -s}; see
next section).


\textbf{Windows.}
You need to set a \textit{low} (!) ``reserved stack size''
in the linker options, for example 64K (/stack:65536 linker flag) will do.
The ``reserved stack size'' is an attribute in the Windows exe
files' internal header. It can be set from the linker, or with
the \ttt{editbin} Microsoft utility. You can use the \ttt{opp\_stacktool}
program (which relies on another Microsoft utility called \ttt{dumpbin})
to display reserved stack size for executables.

You need a low reserved stack size because the Win32 Fiber API
which is the mechanism underlying \fname{activity()} uses
this number as coroutine stack size, and with 1MB being the default,
it is easy to run out of the 2GB possible address space (2GB/1MB=2048).

A more detailed explanation follows.
Each fiber has its own stack, by default 1MB (this is the ``reserved''
stack space -- i.e. reserved in the address space, but not the full
1MB is actually ``committed'', i.e. has physical memory assigned to it).
This means that a 2GB address space will run out after 2048 fibers,
which is way too few. (In practice, you won't even be able to create
this many fibers, because physical memory is also a limiting factor).
Therefore, the 1MB reserved stack size (RSS) must be set to a smaller
value: the coroutine stack size requested for the module, plus
extra-stack-for-envir, the sum of the two typically around 32K.
Unfortunately, the CreateFiber() Win32 API doesn't allow the RSS to be
specified. The more advanced CreateFiberEx() API which accepts RSS as
parameter is unfortunately only available from Windows XP.

The alternative is the stacksize parameter stored in the EXE header,
which can be set
via the STACKSIZE .def file parameter, via the /stack linker option,
or on an existing executable using the editbin /stack utility.
This parameter specifies a common RSS for the main program stack,
fiber and thread stacks. 64K should be enough. This is the way
simulation executable should be created: linked with the /stack:65536
option, or the /stack:65536 parameter applied using editbin later.
For example, after applying the editbin /stacksize:65536 command to
dyna.exe, I was able to successfully run the Dyna sample with 8000
Client modules on my Win2K PC with 256M RAM (that means about 12000
modules at runtime, including about 4000 dynamically created modules.)


\subsubsection{``Segmentation fault''}

On Unix, if you set the total stack size higher, you may get a
segmentation fault during network setup\index{segmentation fault} (or
during execution if you use dynamically created modules) for exceeding
the operating system limit for maximum stack size. For example, in
Linux 2.4.x, the default stack limit is 8192K (that is, 8MB). The
\fprog{ulimit} shell command can be used to modify the
resource limits, and you can raise the allowed maximum stack size
up to 64M.

\begin{verbatim}
$ ulimit -s 65500
$ ulimit -s
65500
\end{verbatim}

Further increase is only possible if you're root.
Resource limits are inherited by child processes.
The following sequence can be used under Linux to get a shell with
256M stack limit:

\begin{verbatim}
$ su root
Password:
# ulimit -s 262144
# su andras
$ ulimit -s
262144
\end{verbatim}

If you do not want to go through the above process at each login, you
can change the limit in the PAM configuration files. In Redhat Linux
(maybe other systems too), add the following line to
\ttt{/etc/pam.d/login}:

\begin{verbatim}
session    required    /lib/security/pam_limits.so
\end{verbatim}

and the following line to \ttt{/etc/security/limits.conf}:

\begin{verbatim}
*    hard    stack    65536
\end{verbatim}

\begin{sloppypar}
A more drastic solution is to recompile the kernel with a larger stack
limit. Edit \ttt{/usr/src/linux/include/linux/sched.h} and increase
\ttt{\_STK\_LIM} from \ttt{(8*1024*1024)} to \ttt{(64*1024*1024)}.
\end{sloppypar}

Finally, it you're tight with memory, you can switch to Cmdenv. Tkenv
increases the stack size of each module by about 32K\index{stack!for
  Tkenv} so that user interface code that is called from a
simple module's context can be safely executed.
Cmdenv does not need that much extra stack.


\subsubsection{Eventually...}

Once you get to the point where you have to adjust the total stack size
to get your program running,
you should probably consider transforming (some of) your \fname{activity()}
simple modules to \fname{handleMessage()}. \fname{activity()} does not
scale well for large simulations.



\subsection{Memory leaks and crashes}

The most common problems in C++ are associated with memory allocation
(usage of \ttt{new} and \ttt{delete}):

\begin{itemize}
   \item{\textit{memory leaks,} that is, forgetting to delete objects
     or memory blocks no longer used;}
   \item{\textit{crashes,} usually due to referring to an already deleted
     object or memory block, or trying to delete one for a second time;}
   \item{\textit{heap corruption} (enventually leading to crash) due to
     overrunning allocated blocks, i.e. writing past the end of an allocated
     array.}
\end{itemize}

By far the most common ways leaking memory in simulation programs
is by not deleting messages (\cclass{cMessage} objects or subclasses).
Both Tkenv and Cmdenv are able to display the number of messages
currently in the simulation,
see e.g. section \ref{sec:ch-run-sim:interpreting-cmdenv-output}.
If you find that the number of messages is steadily increasing,
you need to find where the message objects are. You can do so
by selecting \textit{Inspect|From list of all objects...} from
the Tkenv menu, and reviewing the list in the dialog that pops up.
(If the model is large, it may take a while for the dialog to appear.)

If the number of messages is stable, it's still possible
you're leaking other \cclass{cObject}-based objects. You can
also find them using Tkenv's \textit{Inspect|From list of all objects...}
function.

If you're leaking non-\cclass{cObject}-based objects or just
memory blocks (\ttt{struct}s, \ttt{int}/\ttt{double}/\ttt{struct} arrays,
etc, allocated by \ttt{new}), you cannot find them via Tkenv.
You'll probably need a specialized memory debugging tool like
the ones described below.

\subsubsection{Memory debugging tools}

If you suspect that you may have memory allocation problems
(crashes associated with double-deletion or accessing already
deleted block, or memory leaks), you can use specialized tools
to track them down.
  \footnote{Alternatively, you can go through the full code,
  review it looking for bugs. In my experience, the latter one
  has proved to be far more efficient than using any kind
  of memory debugger.}

The number one of these tools is \textit{Purify} from Rational Software.
This is a commercial tool. Not particularly cheap, but it has
very good reputation and proved its usefulness many times.

There are several open source tools you can try. The best seems
to be \textit{Valgrind} used by the KDE people.
Other good ones are \textit{NJAMD}, \textit{MemProf}, \textit{MPatrol}
and \textit{dmalloc}, while \textit{ElectricFence} seems
to be included in most Linux distributions.
Most of the above tools support tracking down memory leaks as well as
detecting double deletion, writing past the end of an allocated block, etc.


\subsubsection{Poor man's memory leak debugger}

However, if you don't have such tools, you can use the basic
heap debugging code in Cmdenv. It is disabled by default;
to turn it on, you have to uncomment the \ttt{\#defines}
in \ttt{src/envir/cmdenv/heap.cc}:

\begin{longtable}{l@{\qquad}p{10cm}}
\fmac{HEAPCHECK} & checks heap on new/delete\\
\fmac{COUNTBLOCKS} & counts blocks on heap and tells it if none left\\
\fmac{ALLOCTABLE} & remembers pointers and reports heap contents if only LASTN
blocks remained\\
\fmac{DISPLAYALL} & reports every new/delete\\
\fmac{DISPSTRAYS} & reports deleting of pointers that were not registered
by operator new or that were deleted since then\\
\fmac{BKPT} &  calls a function at a specified new/delete; you can set a
breakpoint to that function\\
\end{longtable}


If \fmac{COUNTBLOCKS} is turned on, you should see the
\texttt{[heap.cc-DEBUG:ALL BLOCKS FREED OK]} message at the end of the
simulation. If you do not see it, it means that some blocks have not
been freed up properly, that is, your simulation program is likely to
have memory leaks\index{memory leaks}.



%%
%% Following section is very obsolete, removed:
%%
%
% \section{Execution speed}
%
% If your simulation program is tested and runs OK, you'll probably want
% to run it as fast as possible. Here's a table that could help where to
% begin optimizing\index{simulation!optimizing for speed}.
%
%
% The measurements were made on one version of the FDDI model (you can
% find it in the samples directory); we simulated 10 milliseconds.  We
% used Cmdenv. The machine was a 100Mhz Intel Pentium with 32MB RAM. The
% simulation program was compiled with Borland C++ 3.1 (no particular
% optimization) and run on DOS 6.22. Disk caching was installed
% (SmartDrive read/write caching, 8MB cache).
%
% \begin{longtable}{|p{3cm}|p{2cm}|p{8cm}|}
% \hline
% %% ROW 1
% \tabheadcol
% \tbf{Settings} & \tbf{Execution time} & \tbf{Details}\\\hline
% %%
% {\raggedright all screen output on;\\
%   full heapcheck}
% &
% 7 min 50 sec
% &
% {\raggedright Setting in \texttt{omnetpp.ini}:\\
% \texttt{verbose-simulation = yes}\\
% \texttt{module-messages = yes}\\
% The \ttt{\#defines} in \ttt{envir/cmdenv/heap.cc} were all enabled. This means
% full heapcheck with each allocation, tracking of all allocated
% blocks etc.}\\\hline
% %%
% {\raggedright no screen output at all;\\
%   full heapcheck}
% &
% 5 min 50 sec
% &
% {\raggedright All screen output were \#ifdef'ed out from source; also, the \texttt{omnetpp.ini}
% contained the\\
% \texttt{verbose-simulation = no}\\
% line. The heapcheck defines were turned on.}\\\hline
% %%
% {\raggedright all screen output on;\\
%   no heapcheck}
% &
% 2 min
% &
% We turned off heapcheck (we commented out the defines in heap.cc)
% and turned back on the screen output. We used the same \texttt{omnetpp.ini}:
% setting as with first case.\\\hline
% %%
% {\raggedright screen output redirected to file;\\
%   no heapcheck}
% &
% 15.5 sec
% &
% {\raggedright Same as previous configuration, except that we run the program
% with\\
% \texttt{fddi > output.txt}} \\\hline
% %%
% {\raggedright screen output redirected to NUL;\\
%   no heapcheck}
% &
% 13 sec
% &
% {\raggedright Same as previous configuration, except that we run the program
% with\\
% \texttt{fddi > NUL}}\\\hline
% %%
% {\raggedright screen output turned off from ini file;\\
%   no heapcheck}
% &
% 7.5 sec
% &
% {\raggedright We did not only redirect but also disabled screen output. Setting
% in \texttt{omnetpp.ini}:\\
% \texttt{verbose-simulation = no}\\
% \texttt{module-messages = no}}\\\hline
% %%
% {\raggedright no screen output generation;\\
%   no heapcheck}
% &
% 4.5 sec
% &
% We \#ifdef'ed out all printouts from the simple module sources
% and also turned off any messages from \texttt{omnetpp.ini}.\\\hline
% \end{longtable}
%
%
%
% The moral is that heap checks\index{head checks} and screen output
% greatly influences speed, so once you do not need them (debugging is
% over), throw them out. You also gain a lot by putting \texttt{\#ifdef}
% lines around your debugging code. And of course, program with care.
%

%%% Local Variables:
%%% mode: latex
%%% TeX-master: "usman"
%%% End:
