32.1 The user level API

The user level interface to network dynamics is a collection of instance procedures in the class Simulator, and one procedure to trace and log the dynamics activity. Reflecting a rather poor choice of names, these procedures are rtmodel, rtmodel-delete, and rtmodel-at. There is one other procedure, rtmodel-configure, that is used internally by the class Simulator to configure the rtmodels just prior to simulation start. We describe this method laterSectionsec:nd-internal-arch.

--

The instance procedure []rtmodel../ns-2/dynamics.tclSimulator::rtmodel defines a model to be applied to the nodes and links in the topology. Some examples of this command as it would be used in a simulation script are:

        $ns rtmodel Exponential {0.8 1.0 1.0} $n1
        $ns rtmodel Trace dynamics.trc  $n2 $n3
        $ns rtmodel Deterministic {20.0 20.0} $node(1) $node(5)

The procedure requires at least three arguments:

• The first two arguments define the model that will be used, and the parameters to configure the model.

  The currently implemented models in ns are Exponential (On/Off), Deterministic (On/Off), Trace (driven), or Manual (one-shot) models.

• The number, format, and interpretation of the configuration parameters is specific to the particular model.
  1. The exponential on/off model takes four parameters: [start time], up interval, down interval, [finish time]. start time defaults to $0.5s.$ from the start of the simulation, finish time defaults to the end of the simulation. up interval and down interval specify the mean of the exponential distribution defining the time that the node or link will be up and down respectively. The default up and down interval values are $10s.$ and $1s.$ respectively. Any of these values can be specified as ``$-$'' to default to the original value.

     The following are example specifications of parameters to this model:

           0.8 1.0 1.0       # start at \(0.8s.\), up/down = \(1.0s.\), finish is default;
           5.0 0.5           # start is default, up/down = \(5.0s, 0.5s.\), finish is default;
           - 0.7             # start, up interval are default, down = \(0.7s.\), finish is default;
           - - - 10          # start, up, down are default, finish at \(10s.\);
     

  2. The deterministic on/off model is similar to the exponential model above, and takes four parameters: [start time], up interval, down interval, [finish time]. start time defaults to the start of the simulation, finish time defaults to the end of the simulation. Only the interpretation of the up and down interval is different; up interval and down interval specify the exact duration that the node or link will be up and down respectively. The default values for these parameters are: start time is $0.5s.$ from start of simulation, up interval is $2.0s.$, down interval is $1.0s.$, and finish time is the duration of the simulation.
  3. The trace driven model takes one parameter: the name of the trace file. The format of the input trace file is identical to that output by the dynamics trace modules, , v time link-operation node1 node2. Lines that do not correspond to the node or link specified are ignored.

             v 0.8123 link-up 3 5
             v 3.5124 link-down 3 5
     

  4. The manual one-shot model takes two parameters: the operation to be performed, and the time that it is to be performed.

• The rest of the arguments to the []rtmodel procedure define the node or link that the model will be applied to. If only one node is specified, it is assumed that the node will fail. This is modeled by making the links incident on the node fail. If two nodes are specified, then the command assumes that the two are adjacent to each other, and the model is applied to the link incident on the two nodes. If more than two nodes are specified, only the first is considered, the subsequent arguments are ignored.

• instance variable, traceAllFile_ is set.

The command returns the handle to the model that was created in this call.

Internally, []rtmodel stores the list of route models created in the class Simulator instance variable, rtModel_.

--

The instance procedure []rtmodel-delete../ns-2/dynamics.tclSimulator::rtmodel-delete takes the handle of a route model as argument, removes it from the rtModel_ list, and deletes the route model.

--

The instance procedure []rtmodel-at../ns-2/dynamics.tclSimulator::rtmodel-at is a special interface to the Manual model of network dynamics.

The command takes the time, operation, and node or link as arguments, and applies the operation to the node or link at the specified time. Example uses of this command are:

        $ns rtmodel-at 3.5 up $n0
        $ns rtmodel-at 3.9 up $n(3) $n(5)
        $ns rtmodel-at 40  down  $n4

Finally, the instance procedure []trace-dynamics of the class rtModel enables tracing of the dynamics effected by this model. It is used as:

        set fh [open "dyn.tr" w]
        $rtmodel1 trace-dynamics $fh
        $rtmodel2 trace-dynamics $fh
        $rtmodel1 trace-dynamics stdout

In this example, $rtmodel1 writes out trace entries to both dyn.tr and stdout; $rtmodel2 only writes out trace entries to dyn.tr. A typical sequence of trace entries written out by either model might be:

        v 0.8123 link-up 3 5
        v 0.8123 link-up 5 3
        v 3.5124 link-down 3 5
        v 3.5124 link-down 5 3

These lines above indicate that Link 3, 5 failed at $0.8123s.$, and recovered at time $3.5124s.$