[Ns-developers] Cooperative ns-3 simulation with third party software

[Alexander Pelov]

Hello everyone,

We are very glad that our proposition caused a lively discussion full  
with ideas and new propositions. Thank you!

We gathered together with Sebastien Vincent and talked over the points  
that were brought up. Here is a modified variant of our proposition,  
which we hope addresses the major concerns that our previous  
submission raised.

------------------------------------------------------------------------
Cooperative network simulation with third party software


1. Motivation

There may exist several reasons that would lead to the necessity of  
interfacing an external application with the network simulator. Here  
are several examples of orthogonal criteria that would require this:

(The application = the third party application willing to use the  
network simulator):
a) The application already exists
b) The application should be compatible with other network simulators
c) The application should be written in another programming language
d) The application should run on a unsupported by the network  
simulator platform
e) Resource sharing or performing distributed simulations
f) For the fun of it

Any of these requirements leads to the necessity of accessing the  
functionality of the network simulator from the external application.  
For the moment, there is no universally accepted method of doing so,  
which is the point of our proposition.


2. Use cases

The typical application needs to be able to:
a) Set up the scenario
b) Change the scenario during the course of the simulation (e.g. add a  
node, change the position of a node, drop a link)
c) Send/receive packets to/from the simulated network
d) Obtain the simulation results

Ideally, all these actions should be accessible for the remote party.


3. Proposition

A) For a native Python third party application that does not aim at  
compatibility with other network simulators, RPyC (http://rpyc.wikidot.com 
) is the way to do it. It allows all ns-3 functionality to be accessed.

B) For non-Python applications, or applications willing to use cross- 
simulator mechanisms, a list of fixed, core functions is provided,  
that can be accessed via an RPC protocol (initially JSON-RPC, but more  
implementations could be added in the future). The architecture is the  
following:

[External application] -- (RPC) -->  [RPC Layer -> Core function ->  
ns-3 functions]

Where [ ] denotes program boundaries, and -> simple function calls.
All parameters and return values are simple types, that is string,  
number, dictionary (hash table), array, true, false and null (for a  
detailed type description see http://json.org/).
All functions should be called by using positional parameters only.

The benefits from choosing such architecture are the following;
a) It is easy to add new RPC implementations
b) Ns-3 remains unchanged as the "core functions" are going to be  
implemented as additional functions. Thus, ns-3 development process  
will not be hindered.
c) It would be easy to implement the core functions in other network  
simulators, which would allow the external applications to use them  
interchangeably.
d) The core functions may still be used directly from within the  
network simulator, thus providing useful helper functions for the  
developers (even though this should not be the native way of doing  
things)


4. Core functions

The core functions are arranged in packages. A package may contain  
functions or other packages.
Naming : a function or package name can contain only the symbols [a-z,  
A-Z, 0-9, _, -]. The dot (.) is used as package and function name  
separator. The names should be given in lower_case_with_underscores.

4.1) Packages

Here, we are giving the function descriptions per package (full name  
given, along with parameters and return values). All functions return  
the execution status (success/error) and corresponding error  
description and error code.


4.2) List of functions
# Start list of functions
*******************
"system"
There are several system functions that belong to the "system"  
package, which is the only package that is guaranteed to exist.

system.describe() : array of dictionaries - returns all registered  
functions and their descriptions
system.describe_package(package:string) : array of dictionaries -  
returns all available subpackage of the given package. If the  
parameter is null, returns all available package.
system.describe_functions(package:string) : array of dictionaries -  
returns all available functions, part of the given package. If the  
parameter is null, returns the same output as system.describe()
system.package_version(package:string) : string - returns the version  
of the given package name, in major:minor format.

"system.simulator"
System package giving some additional information on the network  
simulator.
system.simulator.get_short_name() : string - returns the short name of  
the simulator, which should be unique for each simulator (e.g. "ns-3",  
"ns-3").
system.simulator.get_full_name() : string - returns the full name of  
the simulator (e.g. including build number).
system.simulator.get_time_units() : number - returns the number of  
time units per second, as used natively by the simulator (e.g. 1000,  
if the min. time is a millisecond).
system.simulator.get_version() : string - returns the simulator version.


"mobility"
The mobility package holds all functions related to mobility.
"mobility.node"
Node mobility.

mobility.node.get_position(n:number) : array of three numbers  
(corresponding to x, y and z) - the current position of the node with  
ID=n.
mobility.node.set_position(n:number, x:number, y:number, z:number) -  
sets the position of node with ID=n.
mobility.node.get_direction(n:number) : array of three numbers  
(corresponding to x, y and z) - the current movement direction of the  
node with ID=n.
mobility.node.set_direction(n:number, x:number, y:number, z:number) -  
sets the direction of node with ID=n.
mobility.node.get_acceleration(n:number) : number - get the current  
acceleration of the node with ID=n in the direction of its movement.
mobility.node.set_acceleration(n:number, a:number) - set the  
acceleration of the node with ID=n.


"data"
The data package is responsible for sending/receiving data from/to the  
network simulator.
"data.ip.udp"
For UDP over IP networks.

data.ip.udp.addresses(n:number, i:number) : array of strings - returns  
the list of IP addresses assigned to the i-th interface of the node  
with ID=n. If i is null, return all addresses.
data.ip.udp.send(n:number, packet:string, src:string, dst:string,  
p:number) - send packet from the IP address src of node n, to IP  
address dst/port p. If src is null - send from any IP address capable  
of reaching the destination.
data.ip.udp.receive(n:number, a:string) : array of dictionaries -  
returns the next waiting packet in the list for node n and address a.  
If there is no such packet, returns null. If a is null, return the  
next packet for any of the addresses of the node.
data.ip.udp.start_listening(n:number, a:array of strings, p:number) -  
the external application registers itself as willing to be called when  
a new UDP packet is received by node n on one of its addresses a. If a  
is null, the external application is informed about packets arriving  
on all addresses.
data.ip.udp.stop_listening(n:number, a:array of strings, p:number) -  
the external application stops listening on the given addresses a/port  
p for the node n.


"scenario"
The package responsible for building the scenario/topology of the  
simulation.
"scenario.file"
Scenario file functions.

scenario.file.get_supported_types() : array of strings - return the  
list of supported scenario files.
scenario.file.upload(c:string, t:string) - upload the given scenario  
file to the simulator and execute it. The type t is simulator  
dependent, and may include "python", "tcl", "cpp", etc.


"result"
The package responsible for obtaining the result of the simulation.
"result.file"
Result file functions.

result.file.file_count() : number - return the number of files  
resulting from the execution of this simulation.
result.file.get_file(n:number) : string - return the contents of the n- 
th result file
result.file.get_file_name(n:number) : string - return the name of the  
n-th result file


"exec"
Allows the execution of specific command during the simulation  
execution.
"exec.script"
Allows the execution of a script line during the simulation execution.

exec.script.simple(t:string, l:string) - execute the script line l.  
The scripting language is specified by t, e.g. "python" or "tcl". No  
value is returned.
exec.script.get_available_languages() : array of strings - return the  
names of the scripting languages available for script execution.


"sync"
Synchronize the external application with the network simulator's  
events.

sync.run() : string - start the network simulator loop. The function  
does not return until the simulation ends, or the external application  
has to be awaken. The latter case may occur if the external  
application requested to be called in a given moment, or if the  
network simulator has to inform it about an event (e.g. a packet has  
been received at a given node).
sync.callback_after(t:number) - wake the external application after t  
milliseconds.
sync.callback_at(t:number) - wake the external application when the  
simulation time becomes equal to t (in milliseconds).
sync.stop_simulation_at(t:number) - stop the simulation at time t  
(milliseconds).
sync.stop_simulation_after(t:number) - stop the simulation after t  
milliseconds.
sync.get_current_time() : number - return the current simulation time  
in milliseconds.
*******************
# End list of functions



5. Conclusion

Here, we have tried to summarize what are the motivations and what are  
the goals we want to achieve with our proposition. We are aware that  
this is far from the perfect solution, but we think that it might be a  
useful one. It is true, that for the moment it is aimed primarily at  
mobility scenarios and IP networks, but this would allow for the  
easier addition of new core functions in the long term. We must point  
out that we already have a functioning version of most of these  
functions, and the solution can be completed very soon.


As always, all comments and remarks are highly solicited.

Best Regards,
Alexander Pelov