\chapter{Analyzing Simulation Results}
\label{cha:analyzing-simulation-results}


\section{Output vectors}

Output vectors are time series data: values with timestamps.
You can use output vectors to record end-to-end delays or
round trip times of packets, queue lengths, queueing times,
link utilization, the number of dopped packets, etc. --
anything that's useful to get a full picture of what happened
in the model during the simulation run.

Output vectors are recorded from simple modules, by \cclass{cOutVector} objects
(see section \ref{sec:ch-sim-lib:cOutVector}). Since output vectors usually
record a large amount of data, in \ttt{omnetpp.ini} you can disable vectors
or specify a simulation time interval for recording
(see section \ref{sec:ch-run-sim:outvectors-section}).

All \cclass{cOutVector} objects write to the same, common file.
The following sections describe the format of the file, and
how you can process them.


\section{Plotting output vectors with Plove}

\subsection{Plove features}

Typically, you'll get output vector files as a result of a simulation.
Data written to \cclass{cOutVector} objects from
simple modules go to output vector
files\index{output!vector file}. Normally, you use Plove to look
into output vector files and plot vectors in it.

Plove\index{Plove} is a handy tool for plotting {\opp} output vectors.
It uses Gnuplot\index{Gnuplot} to do the actual work. You can specify
the drawing style (lines, dots etc) for each vector as well as set the
most frequent drawing options like axis bounds, scaling, titles and
labels etc. You can save the gnuplot graphs to files (postscript,
latex, pbm etc) with a click. Plove can also generate standalone shell
scripts that plot output vectors in much the same way Plove does
itself. These scripts can be used for batch processing or to debug
filters (see later). Plove does not take away any of gnuplot's
flexibility -- you can embed your own gnuplot commands to customize
the output.


Filtering the results\index{filtering results} before plotting is
possible. Filters can do averaging, truncation of extreme values,
smoothing, they can do density estimation\index{density estimation} by
calculating histograms\index{histogram} etc. Some filters are built
in, and you can easily create new filters or modify the existing ones.
Filters can be incorporated in one of three ways: as \fprog{awk} expressions,
as \fprog{awk} programs and as external filter programs. Filters can be
parameterized. Multiple filters for the same vector is not currently
supported; also, you cannot currently feed several vectors into a
single filter.

Plove does not create temporary files, so you don't need to worry
about disk space: if the output vector is there, Plove can plot
it for you. Moreover, it can also work with gzipped vector files
without extracting them -- just make sure you have zcat.


Plove never modifies the output vector files themselves.

On startup, Plove automatically reads the \texttt{.ploverc} file in
your home directory. The file contains general gnuplot settings, the
filter configuration etc. (that is, the stuff from the Options menu).




\subsection{Usage}

First, you load an output vector file (\texttt{.vec}) into the left
pane.  You can also load gzipped vector files (\texttt{.vec.gz})
without having to decompress them. You can copy vectors from the left
pane to the right pane by clicking the right arrow icon in the middle.
The large PLOT button will plot the \textit{selected} vectors in the
right pane. Selection works as in Windows: dragging and shift+left
click selects a range, and ctrl+left click selects/deselects
individual items. To adjust drawing style, change vector title or add
filter, push the Options... button. This works for several selected
vectors too. Plove accepts nc/mc-like keystrokes: F3, F4, F5, F6, F8,
grey '+' and grey '*'.


The left pane works as a general storage for vectors you're working
with. You can load several vector files, delete vectors you don't
want to deal with, rename them etc. All this will not affect
the vector files on disk. In the right pane, you can duplicate
vectors if you want to filter the vector and also keep the original.
If you set the right options for a vector but temporarily do
not want it to hang around in the right pane, you can put it
back into the left pane for storage.





\subsection{Writing filters}

Filters get an output vector on their standard input (as plain
text, with the timestamp being the second and the value being
the third field on each line), do some processing to it and write
the result to the standard output.


Filters can be incorporated in one of three ways: as \fprog{awk}
expressions, as \fprog{awk} programs or as external programs. An `awk
expression' filter means assembling and launching a command like this:

\begin{Verbatim}[commandchars=\\\{\}]
cat foobar.vec | awk '\{$3 = \textit{<expression>}; print\}' | ...
\end{Verbatim}
%%$

An \fprog{awk} program filter means running the following command:

\begin{Verbatim}[commandchars=\\\{\}]
cat foobar.vec | awk '\{\textit{<program>}\}' | ...
\end{Verbatim}

The third type of filters is used like this:

\begin{Verbatim}[commandchars=\\\{\}]
cat foobar.vec | \textit{<program> <parameters>} | ...
\end{Verbatim}

Before the filter pipeline is launched, the following substitutions
are performed on the \fprog{awk} scripts:

\begin{itemize}
  \item \tbf{t} gets substituted to \$2, which is the simulation time
  (the second column in the output vector file)
  \item \tbf{x} gets substituted to \$3, the actual value (the third column)
\end{itemize}

The parameters of the form \ttt{\$(paramname)} are also replaced with
their actual value.

For example, if you want to add 1 to all values, you can use the \fprog{awk}
expression filter \ttt{x+1}. It will turn into the following awk script:

\begin{verbatim}
awk '{$3 = $3+1}; print'
\end{verbatim}


When you want to shift the vector by a used-defined DT time,
you can create the following \fprog{awk} program filter:

\begin{verbatim}
{t += $(DT); print}
\end{verbatim}

To plot the mean on \textit{(0,t)}, you'd write

\begin{verbatim}
{sum+=x; x=sum/++n; print}
\end{verbatim}

Do not forget the print statement, or your filter will not output
anything and the gnuplot graph will be empty.

Filters are automatically saved into and loaded from the \ttt{~/.ploverc}
file.

%%
%% TBD add example scripts
%%




\section{Format of output vector files}

An output vector file\index{output!vector file} contains several
series of data produced during simulation. The file is textual, it
looks like this:

\begin{Verbatim}[commandchars=\\\{\}]
\textbf{mysim.vec:}
vector 1   "subnet[4].term[12]"  "response time"  1
1  12.895  2355.66666666
1  14.126  4577.66664666
vector 2   "subnet[4].srvr"  "queue length"  1
2  16.960  2.00000000000.63663666
1  23.086  2355.66666666
2  24.026  8.00000000000.44766536
\end{Verbatim}


There are label lines (beginning with vector) and data lines.

A vector line introduces a new vector. Its columns are: vector ID,
module of creation, name of \cclass{cOutVector} object, multiplicity
of data (single numbers or pairs will be written).

Lines beginning with numbers are data lines. The columns: vector
ID, current simulation time, and one or two double values.





\section{Working without Plove}

\subsection{Extracting vectors from the file}

You can use the Unix \fprog{grep} tool to extract a particular vector
from the file. As the first step, you must find out the ID of the
vector. You can find the appropriate vector line with a text editor or
you can use \fprog{grep} for this purpose:

\begin{verbatim}
% grep "queue length" vector.vec
\end{verbatim}

Or, you can get the list of all vectors in the file by typing:

\begin{verbatim}
% grep ^vector vector.vec
\end{verbatim}

This will output the appropriate vector line:

\begin{verbatim}
vector 6  "subnet[4].srvr"  "queue length"  1
\end{verbatim}

Pick the vector ID, which is 6 in this case, and grep the file
for the vector's data lines:

\begin{verbatim}
grep ^6 vector.vec > vector6.vec
\end{verbatim}


Now, \texttt{vector6.vec} contains the appropriate vector. The only
potential problem is that the vector ID is there at the beginning of
each line and this may be hard to explain to some programs that you
use for post-processing and/or visualization. This problem is
eliminated by the {\opp} \fprog{splitvec} utility (written in
\fprog{awk}), to be discussed in the next section.




\subsection{Using splitvec}

The \fprog{splitvec} script (part of {\opp}) breaks the vector file
into several files which contain one vector each:

\begin{verbatim}
% splitvec mysim.vec
\end{verbatim}


creates several files: mysim1.vec, mysim2.vec etc.

\begin{Verbatim}[commandchars=\\\{\}]
\textbf{mysim1.vec:}
# vector 1  "subnet[4].term[12]"  "response time"  1
12.895  2355.66666666
14.126  4577.66664666
23.086  2355.66666666

\textbf{mysim2.vec:}
# vector 2  "subnet[4].srvr"  "queue length"  1
16.960  2.00000000000.63663666
24.026  8.00000000000.44766536
\end{Verbatim}


As you can see, the vector ID is gone.

The files can be further processed with math packages, or read
by analysis or spreadsheet programs which provide numerous ways
to display data as diagrams, do calculations on them etc. One
could use for example Gnuplot, Matlab, Excel, etc.





\subsection{Visualization under Unix}

Two programs are in common use: Gnuplot and Xmgr. Both are free
and both have their good and bad sides; we'll briefly discuss
them. There are innumerable tutorials and documentation about
them on the Web; some of them you will find among the References.


Both programs can eat files produced by \fprog{splitvec}. Both
programs can produce output in various forms: on screen, in Postscript
format, printer files, Latex output etc. For DTP purposes, Postscript
seems to be the most appropriate. On Windows, the easiest way is to
copy the picture to the clipboard from the Gnuplot window's system
menu.


Gnuplot has an interactive command interface. To get the vectors in
\texttt{mysim1.vec} and \texttt{mysim4.vec} plotted in the same graph,
you can type:

\begin{verbatim}
plot "mysim1.vec" with lines, "mysim4.vec" with lines
\end{verbatim}

To adjust the $y$ range, you would type:

\begin{verbatim}
set yrange [0:1.2]
replot
\end{verbatim}


There are several commands to adjust ranges, plotting style, labels,
scaling etc. Gnuplot\index{Gnuplot} can also plot 3D graphs. Gnuplot
is also available for Windows and other platforms. Gnuplot also
has a simple graphical interactive user interface called PlotMTV.
However, we recommend that you use {\opp}'s Plove tool, described in
an earlier section.


Xmgr\index{Xmgr} is an X/Motif based program, with a menu-driven
graphical interface. You load the appropriate file by selecting in a
dialog box. The icon bar and menu commands can be used to customize
the graph. Some say that Xmgr can produce nicer output that Gnuplot
and it is easier to use. Xmgr cannot do 3D and only runs on Unixes
with X and Motif installed. Xmgr also has a batch interface so you can
use it from scripts too.



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