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 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.$

Tom Henderson 2011-11-05