\chapter{Overview}
\label{cha:overview}


\section{Modeling concepts}

{\opp} provides efficient tools for the user to describe the
structure of the actual system. Some of the main features are:
\begin{itemize}
\item{hierarchically nested modules}
\item{modules are instances of module types}
\item{modules communicate with messages through channels}
\item{flexible module parameters}
\item{topology description language}
\end{itemize}

\subsection{Hierarchical modules}


An {\opp} model consists of hierarchically nested
modules\index{module!hierarchy} which communicate with messages.
{\opp} models are often referred to as \textit{networks}. The top
level module is the \textit{system module}.  The system module
contains \textit{submodules}, which can also contain submodules
themselves (Fig. \ref{fig:ch-overview:modules}). The depth of module
nesting is not limited; this allows the user to reflect the logical
structure of the actual system in the model structure.

\begin{figure}[htbp]
\begin{center}
\includegraphics[width=3.772in, height=1.292in]{figures/usmanFig2}
\caption{Simple and compound modules}
\label{fig:ch-overview:modules}
\end{center}
\end{figure}


Modules that contain submodules are termed \textit{compound
  modules}\index{module!compound}, as opposed \textit{simple
  modules}\index{module!simple} which are at the lowest level of the
module hierarchy. Simple modules contain the algorithms in the model.
The user implements the simple modules in C++, using the {\opp}
simulation class library.


\subsection{Module types}
\index{module!types}

Both simple and compound modules are instances of \textit{module
  types}. While describing the model, the user defines module types;
instances of these module types serve as components for more complex
module types. Finally, the user creates the system module as an
instance of a previously defined module type; all modules of the
network are instantiated as submodules and sub-submodules of the
system module.


When a module type is used as a building block, there is no
distinction whether it is a simple or a compound module. This allows
the user to split a simple module into several
simple modules embedded into a compound\index{module!compound} module,
or vica versa, aggregate the functionality of a compound module into a
single simple module, without affecting existing users of the module
type.


Module types can be stored in files separately from the place
of their actual usage. This means that the user can group existing
module types and create \textit{component libraries}\index{module!libraries}. This feature
will be discussed later, in Chapter \ref{cha:running-the-simulation}.



\subsection{Messages, gates, links}

Modules communicate by exchanging
\textit{messages}\index{message!exchanging}. In an actual simulation,
messages can represent frames or packets in a computer network, jobs
or customers in a queuing network or other types of mobile entities.
Messages can contain arbitrarily complex data structures. Simple
modules can send messages either directly to their destination or
along a predefined path, through gates and connections.


The ``local simulation time'' of a module advances when the module
receives a message. The message can arrive from another module
or from the same module (\textit{self-messages} are used to implement
timers).


\textit{Gates}\index{gate} are the input and output interfaces of
modules; messages are sent out through output gates and arrive through
input gates.

Each \textit{connection}\index{connection} (also called
\textit{link}\index{link}) is created within a single level of the
module hierarchy: within a compound module, one can connect the
corresponding gates of two submodules, or a gate of one submodule and
a gate of the compound module (Fig.
\ref{fig:ch-overview:connections}).

\begin{figure}[htbp]
\begin{center}
\includegraphics[width=5.061in, height=1.121in]{figures/usmanFig3}
\caption{Connections}
\label{fig:ch-overview:connections}
\end{center}
\end{figure}

Due to the hierarchical structure of the model, messages typically
travel through a series of connections, to start and arrive in simple
modules. Such series of connections that go from simple module to
simple module are called \textit{routes}.  Compound modules act as
`cardboard boxes' in the model, transparently relaying messages
between their inside and their outside world.


\subsection{Modeling of packet transmissions}

Connections can be assigned three parameters which facilitate
the modeling of communication networks, but can be useful for
other models too: \textit{propagation delay}, \textit{bit error rate}
and \textit{data rate}, all three being optional. One can specify
link parameters individually for each connection, or define link types
and use them throughout the whole model.

Propagation delay is the amount of time the arrival of
the message is delayed by when it travels through the channel.

Bit error rate speficifies the probability that a bit is incorrectly
transmitted, and allows for simple noisy channel modelling.

Data rate is specified in bits/second, and it is used for calculating
transmission time of a packet.

When data rates are in use, the sending of the message in the model
corresponds to the transmission of the first bit, and
the arrival of the message corresponds to the reception
of the last bit. This model is not always applicable,
for example protocols like Token Ring and FDDI do not wait
for the frame to arrive in its entirety, but rather start repeating
its first bits soon after they arrive -- in other words,
frames ``flow through'' the stations, being delayed only a few bits.
If you want to model such networks, the data rate modeling feature
of {\opp} cannot be used.



\subsection{Parameters}
\index{module!parameters}
\index{parameters|see{module parameters}}

Modules can have parameters. Parameters are used for three purposes:
\begin{enumerate}
  \item{to parameterize module topology}
  \item{to customize simple module behaviour}
  \item{for module communication, as shared variables}
\end{enumerate}

Parameters can take string, numeric or pointer values; numeric
values include expressions using other parameters and calling
C functions, random variables from different distributions, and
values input interactively by the user.


Numeric-valued parameters can be used to construct topologies in a
flexible way. Within a compound module, parameters can define the
number of submodules, number of gates, and the way the internal
connections are made.


Compound modules can pass parameters or expressions of parameters
to their submodules. Parameter passing can be done by value or
by reference.

During simulation execution, if a module changes the value of
a parameter taken by reference, the changed value propagates
to other modules. This effect can be used to tune the model or
as a second means of module communication.


\subsection{Topology description method}
\index{topology!description}
The user defines the structure of the model in NED language descriptions
(Network Description).The NED language will be discussed in detail
in Chapter \ref{cha:the-ned-language}.


\section{Programming the algorithms}

The simple\index{module!simple} modules of a model contain the algorithms as C++ functions.
The full flexibility and power of the programming language can
be used, supported by the {\opp} simulation class library.


{\opp} supports a process-style\index{module!process-style} description method for describing
activities. During simulation execution, simple\index{module!simple} module functions
appear to run in parallel, because they are implemented as coroutines\index{module!coroutine}
(also termed lightweight processes). Coroutines were chosen because
they allow an intuitive description of the algorithm and they
can also serve as a good basis for implementing other description
methods like state-transition diagrams\index{state-transition diagram|see{finite state machine}} or Petri nets\index{petri nets}.

{\opp} has a consistent object-oriented design. One can freely
use OOP concepts (inheritance, polymorphism etc) to extend the
functionality of the simulator.

Elements of the simulation (messages, modules, queues etc.) are
represented as objects. These classes are part of the simulation
class library:
\begin{itemize}
\item{modules, gates, connections etc.}
\item{parameters}
\item{messages}
\item{container classes (e.g. queue, array)}
\item{data collection classes}
\item{statistic and distribution estimation classes (histograms, $P^{2}$
algorithm for calculating quantiles etc.)}
\item{transient detection and result accuracy detection classes}
\end{itemize}

The objects are designed so that they can efficiently work together,
creating a powerful framework for simulation programming.


\subsection{Creating simple modules}
\index{module!simple!creation}

Each simple\index{module!simple} module type is implemented with a C++ class. Simple
module classes are derived from a simple module base class, by
redefining the virtual function that contains the algorithm.
The user can add other member functions to the class to split
up a complex algorithm; he can also add data members to the class.

It is also possible to derive new simple\index{module!simple} module classes from
existing ones. For example, if one wants to experiment with retransmission
timeout schemes in a transport protocol, he can implement the
protocol in one class, create a virtual function for the retransmission
algorithm and then derive a family of classes that implement
concrete schemes. This concept is further supported by the fact
that in the network description, actual module types can be parameters.


\subsection{Object mechanisms}

The use of smart container classes allows the user to build
\textit{aggregate data structures}\index{aggregate data structures}.
For example, one can add any number of objects to a message object as
parameters. Since the added objects can contain further objects,
complex data structures can be built.

There is an efficient \textit{ownership}\index{ownership} mechanism
built in. The user can specify an owner for each object; then, the
owner object will have the responsibility of destroying that object.
Most of the time, the ownership mechanism works transparently;
ownership only needs to be explicitly managed when the user wants to
do something non-typical.


The \textit{foreach}\index{forEach mechanism} mechanism allows one to
enumerate the objects inside a container object in a uniform way and
do some operation on them. This feature which makes it possible to
handle many objects together. (The \textit{foreach} feature is extensively used
by the user interfaces with debugging capability and the snapshot
mechanism; see later.)


\subsection{Derive new classes}

It most cases, the functionality offered by the {\opp} classes
is enough for the user. But if it is needed, one can derive new
classes from the existing ones or create entirely new classes.
For flexibility, several member functions are declared virtual.
When the user creates new classes, certain rules need to be kept
so that the object can fully work together with other objects.


\subsection{Self-describing objects to ease debugging}
\index{debugging}

The class library is designed so that objects can give textual
information about themselves. This makes it possible to peek
into a running simulation program: through an appropriate user
interface, one can examine (and modify) the internal data structures
of a running simulation. This feature helps the user to get some
insight what is happening inside the model and get hands-on experience.


A unique feature called \textit{snapshot}\index{snapshot} allows the
user to dump the contents of the simulation model or a part of it into
a text file. The file will contain textual reports about every object;
this can be of invaluable help at times of debugging. Ordinary
variables can also be made to appear in the snapshot file. Snapshot
creations can be scheduled from within the simulation program or done
from the user interface.



\section{Using {\opp}}


\subsection{Building and running simulations}
\index{simulation!building}
\index{simulation!running}

This section gives some idea how to work with {\opp} in practice:
issues like model files, compiling and running simulations are
discussed.

An {\opp} model consists of the following parts:
\begin{itemize}
  \item{NED language topology description(s)\index{ned!files} which
    describe the module structure with parameters, gates etc. They are
    files with .ned suffix. NED files can be written with any text
    editor or using the GNED graphical editor\index{ned!graphical interface}.}
  \item{ Simple modules sources. They are C++ files, with \texttt{.h}/\texttt{.cc} suffix.}
\end{itemize}

The simulation system provides the following components:
\begin{itemize}
  \item{Simulation kernel\index{simulation!kernel}. This contains the
    code that manages the simulation and the simulation class library.
    It is written in C++, compiled and put together to form a library
    (a file with .a or .lib extension)}
  \item{User interfaces\index{simulation!user interface}.
    \index{user interface|see{simulation interface}} {\opp} user interfaces
    are used with simulation execution, to facilitate debugging,
    demonstration, or batch execution of simulations. There are
    several user interfaces, written in C++, compiled and put together
    into libraries (\texttt{.a} or \texttt{.lib} files).}
\end{itemize}


Simulation programs are built from the above components. First, the
NED files\index{ned!files} are compiled into C++ source code, using
the NEDC\index{ned!compiler} compiler which is part of {\opp}. Then
all C++ sources are compiled and linked with the simulation kernel and
a user interface to form a simulation executable.


\subsubsection{Running the simulation and analyzing the results}

The simulation executable is a standalone program,
thus it can be run on other machines without {\opp} or the model files
being present. When the program is started, it reads in a configuration
file\index{simulation!configuration file} (usually called
\texttt{omnetpp.ini}\index{omnetpp.ini}); it contains settings that
control how the simulation is run, values for model parameters, etc.
The configuration file can also prescribe several simulation runs; in
the simplest case, they will be executed by the simulation program one
after another.

The output of the simulation is written into data files: output vector
files\index{output!vector file}, output scalar files
\index{output!scalar file}, and possibly the user's own output files.
{\opp} provides a GUI tool named Plove to view and plot the contents
of output vector files. But it is not expected that someone will
process the result files using {\opp} alone: output files are text
files in a format which (maybe after some preprocessing using
\fprog{sed}, \fprog{awk} or \fprog{perl}) can be read into math
packages like Matlab or its free equivalent Octave, or imported into
spreadsheets like Excel. All these external programs have rich
functionality for statistical analysis and visualization, and {\opp}
does not try to duplicate their efforts. This manual briefly describes
some data plotting programs and how to use them with {\opp}.


\subsubsection{User interfaces}
\index{simulation!user interface}

The primary purpose of user interfaces is to make the inside
of the model visible to the user, to start/stop simulation execution,
and possibly allow the user intervene by changing variables/objects
inside the model. This is very important in the development/debugging
phase of the simulation project. Just as important, a hands-on
experience allows the user to get a `feel' about the model's
behaviour. A nice graphical user interface can also be used to
demonstrate how the model works internally.


The same simulation model can be executed with different user
interfaces, without any change in the model files themselves.
The user would test and debug the simulation with a powerful
graphical user interface, and finally run it with a simple and
fast user interface that supports batch execution.


\subsubsection{Component libraries}
\index{module!libraries}

Module types can be stored in files separately from the place
of their actual usage. This means that the user can group existing
module types and create component libraries.


\subsubsection{Universal standalone simulation programs}


A simulation executable can store several independent models
that use the same set of simple modules. The user can specify
in the configuration file which model he/she wants to run. This
allows one to build one large executable that contains several
simulation models, and distribute it as a standalone simulation
tool. The flexibility of the topology description language also
supports this approach.


\subsection{What is what in the directories}

To help you navigate among files in the {\opp} distribution,
here's a list what you can find in the different directories.

The \texttt{omnetpp} directory contains the following subdirectories.

The simulation system itself:

\begin{Verbatim}[commandchars=\\\{\}]
  \tbf{omnetpp/}         {\opp} root directory
    \tbf{bin/}           {\opp} executables (GNED, nedc, etc.)
    \tbf{include/}       header files for simulation models
    \tbf{lib/}           library files
    \tbf{bitmaps/}       icons that can be used in network graphics
    \tbf{doc/}           manual (PDF), readme, license, etc.
      \tbf{html/}        manual in HTML
       \tbf{api/}        API reference in HTML
       \tbf{nedxml-api/} API reference for the NEDXML library
    \tbf{src/}           {\opp} sources
      \tbf{nedc/}        NED compiler\index{ned!compiler}
      \tbf{sim/}         simulation kernel
        \tbf{std/}       files for non-distributed execution
        \tbf{pvm/}       files for distributed execution over PVM
        \tbf{mpi/}       files for distributed execution using MPI
      \tbf{envir/}       common code for user interfaces
      \tbf{cmdenv/}      command-line user interface
      \tbf{tkenv/}       Tcl/Tk-based user interface
      \tbf{gned/}        graphical NED editor\index{ned!graphical interface}
      \tbf{plove/}       output vector analyzer and plotting tool
      \tbf{nedxml/}      NEDXML library (experimental)
      \tbf{utils/}       makefile-autocreator etc
    \tbf{test/}          regression test suite
      \tbf{distrib/}     regression test suite for built-in distributions
\end{Verbatim}

There is a tutorial, contributed by Nick van Foreest

\begin{Verbatim}[commandchars=\\\{\}]
    \tbf{tutorial/}    the tutorial document
      \tbf{queues/}    sample simulation that supports the tutorial
      \tbf{doc\_src/}   the Latex sources for the tutorial doc
\end{Verbatim}

Sample simulations are within the \texttt{samples} directory. Each of the
sample directories contain a network description (.ned file) and
corresponding simple module code (\texttt{.h}, \texttt{.cc} files).
Makefiles are included.

\begin{Verbatim}[commandchars=\\\{\}]
    \tbf{samples/}     directories for sample simulations
      \tbf{nim/}       a simple two-player game
      \tbf{hcube/}     hypercube network with deflection routing
      \tbf{token/}     simple model of a Token Ring LAN
      \tbf{fddi/}      an accurate FDDI MAC simulation
      \tbf{hist/}      demo of the histogram classes
      \tbf{dyna/}      model of a client-server network
      \tbf{dyna2/}     a version of dyna, using message subclassing
      \tbf{fifo1/}     single-server queue
      \tbf{fifo2/}     another version of fifo, with handleMessage() and FSM
      \tbf{topo/}      NED demo, shows how to create various topologies
      \tbf{demo/}      several sim. models in a single executable
\end{Verbatim}


The \texttt{contrib} directory contains material from the {\opp} community.

\begin{Verbatim}[commandchars=\\\{\}]
    \tbf{contrib/}     directory for contributed material
      \tbf{octave/}    Octave scripts for result processing
      \tbf{emacs/}     NED syntax highlight for Emacs
\end{Verbatim}

You may also find additional directories like \texttt{msvc/}, which contain
integration components for Microsoft Visual C++, etc.


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