RPI Graph and Statistics Package For Ns User Manual and Tutorial
RPI Graph and Statistics Package For Ns User Manual and Tutorial
Abstract
This user manual contains an installation guide and a short tutorial for the RPI graphing
tools for ns.
1 Introduction
The RPI graph and statistics package provides a set of classes for generating commonly used plots
and gathering commonly important statistics. The graph package abstracts data collection from
rendering. Each graph object instantiates a set of data collection objects which are attached to
components in a network topology, as the simulation runs the data collection objects collect data
often outputting the data to an intermediate file. After simulation, the graph object conforms the
data to a canonical format and then sends it to a PlotDevice for rendering. By substituting plot
devices, the user can cause the same graph to be output to a window or a file using gnuplot, fig,
xgraph, xdvi, ghostview, or acroread. In Figure 1 we show a utilization graph that collects data
from a link in an ns simulation and then outputs to a gnuplot plot device. The gnuplot plot device
translates the data and commands from the utilization graph into gnuplot commands. The gnuplot
application then generates an encapsulated postscript file. Other scenarios include rendering a
graph with multiple plot devices for example to generate a postscript file while simultaneously
displaying the data in an X window using xgraph. Or multiple graphs may be output to the same
acroread plot device so that the graphs appear in a single acroread window in the given order.
2 Installation
Presumably you already have the distribution and have installed ns-2. The graph package has
been tested with ns-2.1.b5, ns-2.1b9a, and ns-2.26. There may be incompatibilities with other ns
versions. If you have not downloaded the graph package then get it from
http://www.ecse.rpi.edu/~harrisod/graph-v6.1.1.tar.gz.
In order for the statistics and graphing packages to function, you must define two environment
variables: the NS environment variable must point to the root of the ns source code tree, and
the NSVER environment variable must contain the ns version number (e.g., ns-2.1b5 has version
∗
I am now in the EECS department at UC Berkeley and can be reached at [email protected].
1
1 ByteCounter 2 Simulation
byte arrivals in last
interval
postscript gnuplot
UtilizationVersusTime application
(x,y) values, PlotDevice (x,y) values
plot title, gnuplot
Bottleneck Utilization vs Time
0.8
utilization
0.6
0.4
encapsulated
postscript = 0.2
0
0 0.5 1 1.5 2 2.5
time (seconds)
3 3.5
sample interval=0.1s
4 4.5 5
“2.1b5”). The following directions apply to ns version 2.1b5 and ns 2.1b7. Make a backup of your
ns source code tree before attempting this installation.
Before continuing make sure the following are in your search path:
• nam,
• acroread,
• ghostview,
• gnuplot,
• latex,
• pdflatex,
• xdvi,
• and xgraph.
nam is necessary to run network animations. The remaining applications are used in the process
of creating graphs. Not all of the applications are necessary to use the graph package though
some PlotDevice classes will not function. See Table 2 for the list of PlotDevice classes and the
dependencies between these classes and the applications.
1. If you have an earlier version of the graph package then remove it as follows, but only after
backing up your ns source code tree.
> cd $NS
> rm -r rpi
> rm -r tcl/rpi
2
> gunzip graph-v6.1.1.tar.gz
> tar -xf graph-v6.1.1.tar
> cd graph-v6.1.1
[...]
INCLUDES= \
-I. -Irpi \
[...]
OBJ_CC= \
[...]
rpi/byte-counter.o rpi/delay-monitor.o rpi/file-tools.o \
rpi/rate-monitor.o rpi/rpi-flowmon.o rpi/rpi-queue-monitor.o \
[...]
Here “INCLUDES= \” and “OBJ_CC= \” should already appear in your Makefile. “[...]”
refers to an omission of lines already appearing in your Makefile.
5. Rebuild ns
> cd $NS
> rm gen/*
> make depend
> make
6. Test ns
Change to the directory $NS/tcl/rpi/tests. Type
run-test-suite.sh
This will test the RPI Graphing and Statistics package. You should see the following output:
3
After the text above, the test suite calls graph test/graph-test.tcl, which generates a set of
graphs and displays them using a variety of plot devices. The suite first employs the “xdvi”
PlotDevice that uses the postscript and latex PlotDevices to create graphs and descriptive text
respectively. The “xdvi” PlotDevice then displays the generated DVI file using the “xdvi” appli-
cation.
Carefully inspect the generated plots for correctness against the plots bearing the label “Com-
parison Graph.” Because of the visual nature of the graphing tools and slight differences between
versions of the various graphing applications, we found that the only reliable way to test the Plot-
Device classes was through visual inspection. NOTE: That your output may not look exactly
the same as the provided comparison graphs. Look for differences in content rather than small
differences in presentation (e.g., ignore font differences).
4
3 Tutorial
All of these examples assume a working knowledge of ns. If you have not created ns scripts before
then consult the ns documentation and write a few test scripts before proceeding from here.
Currently the graph package provides the graphs shown in table 1.
Except for the XY class, an instance of any of these classes gathers statistics directly from an
ns simulation and renders a plot when the instance’s plot member function (i.e., TCL instproc) is
called. The XY class simply allows script writers to generate a plot from an arbitrary set of (x, y)
coordinates. The XY class represents a way for a script writer to use the PlotDevice classes as a
generic interface to a variety of output devices.
source $env(NS)/tcl/rpi/graph.tcl
The graph package contains several graphs for gathering statistics about traffic passing through
a link including queue length versus time, utilization versus time, rate versus time, and queue delay
versus time. In this example we will show how to graph utilization over given fixed intervals versus
time.
Assume we have created a topology with a known bottleneck spanning ns nodes n0 and n1. Next
we add the lines shown in figure 2 to our script. To collect statistics for our graph we instantiate
a Graph/UtilizationVersusTime object. The arguments $n0 and $n1 tell the graph object to
collect statistics for the link spanning between nodes n0 and n1. The 0.1 argument tells the graph
object that it should measure utilization over 0.1 second intervals. When the simulation finishes,
we call $util_graph display to tell the graph object to show a window containing our utilization
versus time plot generated using gnuplot. We show the complete source code for this script in
graph-v6.1.1/examples/ex1.tcl, and the generated graph in figure 3.
5
' $
[...]
proc finish {} {
global util_graph
[...]
$util_graph display
exit 0
}
[...] ;# define nodes n0 and n1 and link spanning them.
# create graph of utilization vs time for link [n0,n1].
set util_graph [new Graph/UtilizationVersusTime $n0 $n1 0.1]
& %
0.8
utilization
0.6
0.4
sample interval=0.1s
0.2
0
0 0.5 1 1.5 2 2.5 3 3.5 4 4.5 5
time (seconds)
Here we create an instance of the xdvi class and assign it to the Graph plot_device_ class
member. Whenever a graph object is instantiated it by default uses the plot device defined in the
6
When closed, display all graphs plotted with this device us-
acroread ing acroread. Uses postscript PlotDevice and the pdflatex
application.
fig Output to fig file via gnuplot.
ghostview Output eps via gnuplot then display using ghostview
gnuplot Show plot in X window using gnuplot.
gnuplot35 Show plot in X window using gnuplot 3.5 (no comments).
Output to eps file using the postscript PlotDevice and run
latex
latex to create a latex file that includes the graphs.
pdf Output to pdf file from eps using epstopdf.
postscript Output to encapsulated postscript via gnuplot.
postscript35 Output to eps via gnuplot 3.5 (no comments).
When closed, display all graphs plotted with this device using
xdvi
xdvi.
xgraph Show plot in X window using xgraph.
Graph plot_device_ class member. All of the classes can be instantiated by passing a plot device
object to their respective init instprocs. This allows you to use a different plot device for each
graph object if you so wish.
We show the relevant snippets from the ex2.tcl script in figure 4. Not shown in figure 4 we
create a topology containing a bottleneck between nodes $n0 and $n1. We then define two TCP
connections that pass through the bottleneck. The first of these two connections has the TCP
agent object $tcp0. Shown in figure 4, we create three graph objects of which the first two install
statistics gathering objects into the bottleneck link from n0 to n1. The last graph object traces
the congestion window of tcp0. When the simulation completes we output each of the graphs to
encapsulated postscript by calling each object’s display instproc. Next we close the plot device
causing the plot device to compile a latex file that references the eps files generated by each graph
object. The latex compiler outputs an dvi file which the plot device then opens using xdvi.
7
' $
[...]
Graph set plot_device_ [new xdvi]
[...]
proc finish {} {
global util_graph qlen_graph cwnd0_graph
$util_graph display
$qlen_graph display
$cwnd0_graph display
run-nam
exit 0
}
[...] ;# define a bottleneck between n0 and n1.
files. All temporary files are by default written to a temporary directory located in /tmp/expx where
x is replaced with smallest integer that has not already been used in the naming of another exp
directory in /tmp. The user can change the default directory by setting tmp_directory_ global
variable before instantiating any Graph objects. However, this is only advisable if the user is sure
that the directory used to store temporary files resides on the same machine that is executing the
script, since writing across a network will not only slow down the simulation but may adversely
affect other users sharing the network.
If the user does not set the output_filename_ data member then the output file is placed in
tmp_directory_ with a default name specific to the Graph class.
8
' $
[...]
Graph set plot_device_ [new fig]
[...]
set util_graph [new Graph/UtilizationVersusTime $n0 $n1 0.1]
$util_graph set title_ "Bottleneck Utilization vs Time"
$util_graph set output_filename_ "bneck_util_vs_time"
[...]
& %
the “display” instance procedure on the graph object. The “display” method plot using the default
PlotDevice. We have not defined a default plot device in this script. Instead we pass the graph
directly to two different plot devices.
Note that often times there is little need for more than one plot device since plot devices create
intermediate files of the desired type (e.g., xdvi creates encapsulated postscript files for each graph).
Multiple plot devices is more useful when the desired file type is not generated as an intermediate
file when displaying the graph in a window as in ex4.tcl.
' $
[...]
proc finish {} {
[...]
set xgraph_plotter [new xgraph]
set eps_plotter [new postscript]
$xgraph_plotter plot $util_graph
$eps_plotter plot $util_graph
$xgraph_plotter close
$eps_plotter close
[...]
}
[...]
set util_graph [new Graph/UtilizationVersusTime $n0 $n1 0.1]
$util_graph set title_ "Bottleneck Utilization vs Time"
$util_graph set output_filename_ "bneck_util_vs_time"
[...]
& %
9
gathering over the standard methods provided by ns.
To include the link statistics gathering functions do the following:
source $env(NS)/tcl/rpi/link-stats.tcl
To begin gathering statistics on a link spanning from nodes n0 to n1, do the following:
If you wish to gather statistics starting from some time into the simulation then simply in-
stantiate the LinkStats object at that time. If you want to gather statistics over consecutive
time intervals then you can reset the link statistics at the end of each time interval by calling
the LinkStats reset instance procedure. If you want to collect a link’s statistics for overlapping
intervals then create two LinkStats objects each at a time when you want to begin collecting statis-
tics then retrieve the statistics at the end of their respective intervals. Installing more than one
LinkStats object on a link is particularly useful when you want to record statistics for the whole
simulation as well as for the steady-state (i.e., skipping some time to eliminate initial transients).
We provide the code for this complete example in graph-v6.1.1/examples/ex4.tcl.
10
Instantiates a LinkStats object spanning between n0 and n1.
You must have previously created these two nodes and a link
spanning these nodes. More than one LinkStats object can
init n0 n1 [qmon] span between n0 and n1. By default the LinkStats object uses
an instance of the RPIQueueMonitor class to collect statistics.
You can install your own queue monitor using the optional
third argument.
reset resets all statistics to the initial state.
11
Returns the link utilization as the number of bytes
get-utilization departing the queue as the number of bytes that could
have departed the queue.
Returns the link utilization as the number of packets
that departed the bottleneck link times the average
get-packet-utilization avgpktsz packet size over the number of average sized pack-
ets that could have departed the link. The argument
specifies the average packet size.
Returns the number of byte arrivals at the tail of the
get-throughput
queue * 8 over time.
Returns the number of packet arrivals at the tail of
get-packet-arrivals
the queue.
Returns the number of byte arrivals at the tail of the
get-byte-arrivals
queue.
get-packet-drops Returns the number of packets dropped.
get-byte-drops Returns the number of bytes dropped.
Returns the number of packets that departed the
get-packet-departures
queue.
Returns the number of bytes that departed the queue.
get-byte-departures
12
3.6 Example 5: TCP statistics
The most direct way to obtain TCP statistics is to simply query the bound variables defined for
the Agent/TCP class. For example, if we define a TCP agent $tcp0 then we can do the following
without extending ns-2:
When using our TCP statistics gathering functions it is necessary to include the tcp-stats.tcl
package. This loads the definitions shown in tables 5 and 6:
source $env(NS)/tcl/rpi/tcp-stats.tcl
Then initialize various counters by calling init-stats. init-stats can also be called to simply
reset the the statistics for both our extensions and the statistics gathered by ns-2.1b5.
[...]
$tcp init-stats
[...]
At some later time, such as when finish is called, you can output tcp-statistics as follows:
4 Performance Issues
When one is running large or long simulations, there are various considerations to take into account
with respect to the tools used for gathering statistics or generating statistics. Our tools have been
defined to introduce reasonable overhead, though in some cases simulation performance constraints
may drive one to design task-specific tools. We outline some of the performance considerations in
this section.
13
Returns the number of packets transmitted containing new
get-useful-packets
data.
Returns the number of bytes transmitted containing new
data. The number of useful bytes in each useful packet
is the packet size minus the TCP and IP headers.
get-useful-bytes
The header size is determined by tcpip_base_hdr_size_
defined in $NS/tcl/lib/ns-default.tcl. In ns-2.1b5,
tcpip_base_hdr_size_ is set to 40.
Returns the rate of useful bits transmitted by the network.
Uses get-useful-bytes to determine the total number of useful
bits. Packets that have been lost but not yet detected by the
get-goodput-bps
source are counted as useful because our measure is based on
state maintained by the TCP source. In a long simulation
this should have negligible impact on the goodput measure.
get-goodput Returns goodput in bps over the bottleneck capacity.
14
Calculates mean goodput in bps across the
get-mean-goodput tcplist
passed TCP agents (i.e., connections).
Calculates variance in goodput (bps) across
get-goodput-variance tcplist
the passed TCP agents (i.e., connections).
Calculates the standard deviation in goodput
get-goodput-stddev tcplist in bps across the passed TCP agents (i.e., con-
nections).
Calculates the Coefficient of Variation
get-goodput-cov tcplist (C.O.V.) across the passed TCP agents.
C.O.V. is standard deviation over the mean.
Calculates the sum of the packets sent across
get-total-data-packets tcplist
the passed TCP agents (i.e., connections).
Calculates the sum of the packet retransmis-
get-total-retransmitted-packets tcplist sions across the passed TCP agents (i.e., con-
nections).
Calculates the sum of the retransmission time-
get-total-retransmission-timeouts tcplist outs across the passed TCP agents (i.e., con-
nections).
bytes that arrived at the head of the queue. Usually the few extra objects represents negligible
overhead. However, if the script writer has particularly tight performance constraints then the
script writer will have to write his or her own objects designed specifically to gather the desired
statistics.
15
should record the queue length at every arrival and departure of a packet. This results in partic-
ularly large generated files and slow run times, but it also allows the user to easily see transient
queuing behavior. If the user wishes to improve simulation run times or reduce the size of trace
files, the user can set sample_interval to a positive value denoting the time interval over which
the queue length is averaged. At the end of each interval, the average is output to the graph’s trace
file. Larger averaging intervals result in shorter run times at the expense of generating graphs with
smoother output (i.e., less transient behavior is revealed).
16