
\chapter{Nam}
\label{chap:nam}


\section{Introduction}

Nam is a Tcl/TK based animation tool for viewing network simulation traces and real world packet tracedata. The design theory behind nam was to create an animator that is able to read large animation data sets and be extensible enough so that it could be used indifferent network visualization situations.  Under this constraint nam was designed to read simple animation event commands from a large trace file.  In order to handle large animtion data sets a minimum amount of information is kept in memory.  Event commands are kept in the file and reread from the file whenever necessary.

The first step to use nam is to produce the trace file. The trace file contains topology information, e.g., nodes, links, as well as packet traces. The detailed format is described in the section \ref{sec:namtraceformat}. Usually, the trace file is generated by ns. During an ns simulation, user can produce topology configurations, layout information, and packet traces using tracing events in ns.  However any application can generate a nam trace file.

When the trace file is generated, it is ready to be animated by nam. Upon startup, nam will read the tracefile, create topology, pop up a window, do layout if necessary, and then pause at time 0. Through its user interface, nam provides control over many aspects of animation. These functionalities will be described in detail in the USER INTERFACE section.

There are bugs in nam however each successive has become much more stable than the previous one.  Please  mail ns-users@isi.edu if you encounter any bugs, or have suggestions for addiotional desired functionality.

\section{Nam Command Line Options}
\label{sec:namcommandlineoptions}
\begin{program}
nam [ -g <geometry> ] [ -t <graphInput> ] [ -i <interval> ] [ -j <startup time> ] 
    [ -k <intial socket port number> ] [ -N <application name> ] [ -c <cache size> ] 
    [ -f <configuration file> ] [ -r initial animation rate ]
    [ -a ] [ -p ] [ -S ]
    [ <tracefile(s)> ]
\end{program}

\textbf{Command Line Options}

\begin{tabular}{ll}
-g & Specify geometry of the window upon startup. \\

-t & Instruct nam to use tkgraph, and specify input file nam for tkgraph. \\

-i & [Information  for  this  option  may  not  be  accurate]  Specify rate (real)  milliseconds  as  the  screenupdate rate. The default rate is 50ms (i.e., 20 frames per second). Note that the X server may not be able to keep up with this rate, in which case the animation will run as fast as the X server allowsit to (at 100\% cpu utilization). \\
-N & Specify the application name of this nam instance. This application name may later be used in peer synchronization. \\
-c & The  maximum  size  of  the  cache  used  to  store  'active' objects when doing animating in reverse. \\
-f & Name of the initialization files to be loaded during startup. In this file, user can define functions which will be called in the trace file. An example for this is the 'link-up' and 'link-down' events of dynamic links in ns. (Refer to \$ns rtmodel for detail, and tcl/ex/simple-dyn.tcl in your ns direc-tory for example). Example initialization files can be found at ex/sample.nam.tcl and ex/dynamicnam.conf. \\
-a & Create a separate instance of nam. \\
-p & Print out nam trace file format. \\
-S & Enable synchronous X behavior so it is easier for graphics debugging. For UNIX system running X only. \\
<tracefile> & is the name of the file containing the trace data to be animated.  If <tracefile> cannot be read, nam will try to open <tracefile>.nam. \\
\end{tabular}


\section{User Interface}
\label{sec:userinterface}

Starting up nam will first create the nam console window.  You can have multiple animations running under the same nam instance.  At the top of all nam windows is a menu bar.  For the nam console there are 'File' and 'Help' menus.  Under the 'File' there is a 'New' command for creating a ns topology using the nam editor (under construction) , an 'Open' command which allows you to open existing tracefiles, a 'WinList' command that popup a window will the names of all currently opened tracefiles, and a 'Quit' command which exits nam. The 'Help' menu contains a very limited popup help screen and a command to show version and copyright information. 

Once a tracefile has been loaded into nam (either by using the 'Open' menu command or by specifying the tracefile on the command line) an animation window will appear.  It has a 'Save layout' command which will save the current network layout to a file and a 'Print' command which will print the current network layout.

The 'Views' menu has 4 buttons:
\begin{itemize}
\item New view button: Creates a new view of the same animation. User can scroll and zoom on the newview. All views will be animated synchronously.
\item  Show monitors checkbox: If checked, will show a pane at the lower half of window, where moni-tors will be displayed.
\item  Show autolayout checkbox: If checked, will show a pane at the lower half of window, which con-tains input boxes and a button for automatic layout adjustments. This box will not be enabled when using link orientain layouts.
\item Show annotation checkbox: If checked, will show a listbox at the lower half of window, which will be used to list annotations in the ascending order of time.
\end{itemize}

Below the  menu  bar, there  is  a control  bar containing  6  buttons,  a  label,  and  a  small  scrollbar(scale). They can be clicked in any order. We will explain them from left to right.

\begin{itemize}
\item Button 1 (<<) - Rewind. When clicked, animation time will go back at the rate of 25  times the current screen update rate.
\item  Button 2 (<) - Backward play. When clicked, animation will be played backward with time decreasing.
\item Button 3 (square) - Stop. When clicked, animation will pause.
\item Button 4 (>)  - Forward play. When clicked, animation will be played forward with time increasing.
\item Button 5 (>>) - Fast  Forward.  When  clicked,  animation  time  will  go  forward  at  the  rate  of  25  times  the  current screen update rate.
\item Button 6 (Chevron logo) - Close current animation window.
\end{itemize}

Time label - Show the current animation time (i.e., simulation time as in the trace file). 
Rate Slider - Controls the screen update rate (animation granularity). The current rate is displayed in the label above the slider.


Below the first control bar, there is Main Display, which contains a tool bar and a main view pane with two panning scroll bars. All new views created by menu command  'Views/New view' will have these three components. The  tool bar contains two zoom buttons. The  button with an up arrow zooms in, the button with a down arrrow zooms out. The two scroll bars are used to pan the main animation view. 

Clicking the left button on any of the objects in the main view pane will pop up a information window. For packet and agent objects, there is a 'monitor' button in the popup window. Clicking that  button  will  bring  out  the  monitor  pane (if  it  is  not already there),  and add a monitor to the object.  For link objects, there will be a 'Graph' button. Clicking on that button will bring up another popup window, where users can select between drawing a bandwidth  utilization graph or drawing a link loss graph of one simplex edge of the duplex link.

Below the user interface objects we have discussed  so  far, there  may  or  may  not  be  a Monitor  pane, depending  on whether the checkbox 'Views/Show monitors' is set. (The default is unset). All monitors will be shown in this pane. A monitor looks like a big button in the pane. Currently only packets and agents may have monitors.

 A packet monitor shows the size, id, and sent time. When the packet reaches its destination, the monitor will still be there, but will say that the packet is invisible. An agent monitor shows the name of the agent, and if there are any variable traces associated with this agent, they will be shown there as well.
 
Below the monitor pane (or in its place if the monitor pane isn't there), there is a Time Slider. It looks likea scaled ruler, with a tag 'TIME' which can be dragged along the ruler. It is used to set the current animation time.  As you drag the 'TIME' tag, current animation time will be displayed in the time label in the control bar above. The left edge of the slider represents the earliest event time in the trace file and the right edge represents the last event time. Clicking left button on the ruler (not on the tag) has the same effect as Rewind or Fast Forward, depending on the clicking position.

The Automatic Layout Pane may be visible or hidden. If visible, it is below the time slider. It has three inputboxes and one relayout button. The labeled input boxes let user adjust two automatic layout constants, and the number of iterations during next layout. When user press ENTER in any of the input boxes, or click the'relayout' button, that number of iterations will be performed. Refer to the AUTOMATIC LAYOUT section for details of usage.

 The bottom component of the nam window is a Annotation Listbox, where annotations are displayed. Anannotation is a (time, string) pair, which describes a event occuring at that time. Refer to ns(1) for functions to generate annotations. Double-clicking on an annotation in the listbox will bring nam to the time when that annotation is recorded. When the pointer is within the listbox,  clicking the right button will stop the animation and bring up a popup menu with 3 options: Add, Delete, Info. 'Add' will bring up a dialog box with a text input to add a new annotation entry which has the current animation time. The user can type an annotation string in the dialog box. `Delete' will delete the annotation entry pointed by the pointer. `Info' will bring out a pane which shows both the annotation time and the annotation string.

\section{Keyboard Commands}
\label{sec:keyboardcommands}
Most of the buttons have keyboard equivalents. Note they only function when the mouse cursor is inside the nam window.

\begin{itemize}
\item <return> - Typing a <return> will pause nam if it's not already paused. If nam is paused, <return> will step the animation one simulated clock tick. (If your keyboard autorepeats, holding down <return> is a goodway to slow-step through the animation.)
\item 'p' or 'P' - Pause but not step if paused.
\item 'c' or 'C' - Continue after a pause.
\item 'b' or 'B' - Decrease animation time for one screen update interval.
\item 'r' or 'R' - Rewind.
\item 'f' or 'F' - Fast Forward.
\item 'n' or 'N' - Jump to time of next event in the tracefile.
\item 'x' or 'X' - Undo the last rate change.
\item 'u' or 'U' - Undo the last time slider drag.
\item '>' or `.' Increase the granularity (speed up) by 5\%.
\item '<' or ',' Decrease the granularity (slow down) by 5\%.
\item <space bar> -  Toggle the pause state of nam. 
\item 'q', 'Q' or <control-c> - Quit.
\end{itemize}

\section{Generating External Animations from Nam}
\label{sec:exteranlanimations}

Nam animations can be saved and converted to animated gifs or MPEG movies.

To save the frames of your movie, first start nam with your trace and set it up where you want it to start and adjust other parameters (step rate, size, etc.) Select 'Record Animation' from the File menu to start saving frames.  Each animation step will be saved in a X-window dump file called ``nam\%d.xwd'' where \%d is the frame number. These files can then be assembled into animated GIFs or MPEGs with the appropriate post-processing tools.

The following shell script (sh, not csh) converts these files into an animated gif:
\begin{program}
    for i in *.xwd; do
    	xwdtoppm <$i |
    	ppmtogif -interlace -transparent'#e5e5e5' >`basename $i .xwd`.gif;
    done
    gifmerge -l0 -2 -229,229,229 *.gif >movie.gif
\end{program}

Please note that the programs xwdtoppm, ppmtogif, and gifmerge are \emph{not} part of ns.
You can get the first two from
\url{http://download.sourceforge.net/netpbm/}
and gifmerge from
\url{http://www.the-labs.com/GIFMerge/}.


\section{Network Layout}
\label{sec:networklayout}

In nam, a topology is specified by alternating node objects with edge objects. But to display the topology in a comprehensible way, a layout mechanism is needed. Currently nam provides three layout methods. First, user may specify layout by the link's orientation. A link orientation is the angle between the edge and a horizontal line, in the interval [0, 2$\pi$]. During layout, nam will honor the given link orientation. Generally, it will first choose a reference node, then place other nodes using link orientations and link length.  The link length is determined by link delay and connecting node sizes. This works well for small and manually generated topologies.

Second, when dealing with randomly generated topologies, we may want to do layout automatically. An automatic graph layout algorithm has been adapted and implemented. The basic idea of the algorithm is to model the graph as balls (nodes) connected by springs (links). Balls will repulse each other, while springs pull them together. This system will (hopefully) converge after some number of iterations. In practice, after a small number of iterations (tens or hundreds), most small to medium sized graphs will converge to a visually comprehensible structure. Larger graphs may take a combination of automatic layout and hand placement to achieve an acceptable layout. 

There are 3 parameters to tune the automatic layout process: 
Ca  Attractive force constant, which controls springs's force between balls.
Cr  Repulsive force constant, which controls the repulsive force between balls.
Number of iterations How many times to run the autolayout procedure.

For small topologies with tens of nodes, using the default parameters (perhaps with 20 to 30 more iterations) will suffice to produce a nice layout. But for larger topology, careful parameter tuning is necessary. Following is a empirical method to layout a 100 node random transit stub topologygenerated  by  Georgia  Tech's ITM  internet  topology  modeler. First,  set Ca  and  Cr  to  0.2,  do about 30 iterations, then set Cr to 1.0, Ca to about 0.01, then do about 10 iterations, then set Ca to 0.5, Cr to 1.0, do about 6 iterations.

Third, there is a x,y coordinate style layout.  This was developed for use in displaying a wireless topologies in which permanent links don't exist.  Using this style, nodes events are given x and y coordinate values indicating where those nodes should be placed in a cartesian world.



\section{Animation Objects}

Nam does animation using the following building blocks which are defined below:

\begin{description}
\item[Node]
Nodes are created from 'n' trace event in trace file. It represents a source, host, or router. Nam will skip over any duplicate definitions for the same node. A node may have three shapes, (circle, square, and hexagon), but once created it cannot change its shape. Nodes can change its color during animation.

\item[Link]
Links are created between nodes to form a network topology. Internally nam links are consist of 2 simplex links. The trace event 'l' creates two simplex links and does other necessary setup. Therefore, for a users perspective all links are duplex links.  Links can change color during the animation.

\item[Queue]
Queues need to be constructed in nam between two nodes. A nam queue is associated to only one edge of a duplex link. Queues are visualized as stacked packets.  Packets are stacked along a line, the angle between the line and the horizontal line can be specified in the queue trace event.

\item[Packet]
Packets are visualized as a block with an arrow. The direction of the arrow shows the flow direction of the packet. Queued packets are shown as little squares. A packet may be dropped from a queue or a link. Dropped packets are shown as falling rotating squares, and disappear at the end of the screen.  Unfortunately, due to nam's design dropped packets are not visible during backward animation.

\item[Agent]
Agents are used to separate protocol states from nodes. They are always associated with nodes. An agent has a name, which is a unique identifier of the agent. It is shown as a square with its name inside, and is drawn next to its associated node.
\end{description}
