Lisp Educational Network Simulator (LENS)

LENS is easier to extend and develop for than other network simulators.

The decision to write a new network simulator in |LISP| was based upon a number of observations:

• Simulation environments require a core model and a means for specifying particular simulations at run time. Most simulators have the core model written in a compiled language (e.g. C++) for efficiency and have a separate embedded run time interpreter (e.g. Tcl or a domain specific language) for describing the particular simulation. |LISP| provides the full language and compiler environment at run-time so there is no need for this separation.
• Users of a simulator will want to describe their problem in a way which matches their particular domain. |LISP| is an extensible language which is especially good for writing domain specific languages.
• LISP enables introspection of all aspects of the simulated system while it is running without any additional programming. Most other simulators provide only limited introspection capabilities which have to be explicitly programmed in.
• In modern LENS the simulations are run in a separate thread to the normal Common Lisp read-eval loop so the user can probe or modify the simulation even while it is running.

The architecture of LENS is inspired by the http://www.omnetpp.org/ [OMNET++ simulator framework written in C++ however may aspects of that design become simpler when implemented in LISP.

LENS has been developed using the SBCL http://sbcl.sourceforge.net/ Common Lisp implementation. Implementation specific features are accessed through a thin compatibility layer in `core/compatibility.lisp` which is the only file that should need changed to port it to other implementations. Currently the only implementation feature used is threading so porting is a minimal task. If you do port LENS to another implementation please send me the changes to encorporate back into the main distribution.

LENS is dependant on the following additional Common Lisp libraries

• asdf: http://www.cliki.net/asdf
• Closer-MOP: http://common-lisp.net/project/closer/
• split-sequence: http://www.cliki.net/SPLIT-SEQUENCE
• trivial-gray-streams: http://www.cliki.net/trivial-gray-streams
• data-format-validation : http://www.cliki.net/CL-DATA-FORMAT-VALIDATION
• clrs : https://github.com/willijar/clrs

LENS is available from the GIT repository. You can clone and install LENS like this:

cd ~/src/
git clone https://github.com/willijar/LENS.git

1. The file lens.asd provides the asdf system definition for LENS. You should place a symbolic link to this file in a system definition directory where ASDF can find it. Similarly for
2. Load LENS with

   (asdf:operate 'asdf:load-op :lens)
   

3. Load the simulation system you want with

   (asdf:operate 'asdf:load-op :simulation-system-name)
   

   e.g. (asdf:operate 'asdf:load-op :lens.samples) for the provided example `samples` network.

4. Make the simulation package your current package

   (asdf:operate 'asdf:load-op :simulation-package-name)
   

   e.g. (in-package :lens.samples) for the provided example networks.

5. Load and run a simulation configuration from a configuration file

   (run-simulations "configuration-file.ini" :config "section-name")
   

   e.g. (run-simulations +tictoc+ :config "TicToc2") will run the sample simulation specified by section "TicToc2" in the samples configuration file (+tictoc+ is defined in the :lens.samples package to point to this file)

If you have have questions, remarks, or ideas about LENS or want to submit a bug report then please email me at mailto:J.A.R.Williams@aston.ac.uk

Simulations of networks can provide a useful educational tool both for supporting traditional modular courses and for enabling students to carry out more open ended project work. In terms of research ultralow power wireless are an interesting engineering problem as they operate under significant resource constraints and the protocols and techniques that are needed are therefore very application dependant. Simulations provide an efficient way of investigating those challenges and potential solutions. A simulation framework that can support both these tasks would enable students to carry out research work in wireless sensor networks as part of their projects.

There are many discrete time event network simulators available. Those which are most widely used (such as NS2 and it's derivatives) are popular because they have been around a long time and a very large number of network models have been written for them. The range of models available has outgrown the original framework design and this gives rise to many workarounds and the introduction of substantial unnecessary complexity. This growth of baroque complexity makes it very difficult to fully understand the details of the models or to modify or customise them. As the models continue to grow this is becoming harder and harder. While there have been attempts to re-factor some of these large simulator frameworks they have met with limited success - partly because one of the goals is to try to maintain some sort of compatibility with the legacy of complex models.

An alternative is to design a new simulator framework based on experience of the limitations of the previous designs which have led to the growth in their complexity. One such framework is OMNET++ which is a simulator framework written in C++ which addresses the design issues. The disadvantage is that it does have the wide range of network models available as the more long standing simulators.

Traditionally simulation models are typically made up of a fixed compiled component written in C or C++ for efficiency and a run time interpreted component to allow customisation without having to recompile for every model change. The run time component is either in a dynamic extension language (such as Tcl for NS2) or a custom language (NED for OMNET++). This simulation models are typically spread across at least two files in two different programming languages. Aspects which have been fixed in the compiled model cannot be changed at run time. It is not always transparent which aspects of the model should be fixed and which should be configurable at model implementation time, nor is it obvious in complex models where to find different aspects of the implementation.

From experience I have found that students take too long to have sufficiently in depth understanding of the Baroque mature simulators to write new models withing the 6 month time frame allowed for Masters projects. They are suitable for projects involving running currently available models but not if the project is to evaluate some new model. Additionally, when looking for a network simulator to carry out more complete systematic evaluation of wireless sensor networks I found that none of the already existing network simulators had implementations of all the protocols of interest. No matter which simulator I chose I would need to port across implementations of protocols.

On this basis a new simulator framework \acr{LENS} has been designed. Many aspects of the architecture are based on the excellent design of OMNET++ however it was written entirely in \gls{CL}. \gls{CL} provides a dynamic compiled environment with full introspection capabilities during run time. It is an extensible language which is especially good for domain specific customisation. There is therefore no need to use or design a separate interpreted language for the dynamic aspect. This simplifies the design - typically a single protocol will be fully described in a single file containing a class definition describing its state variables and configurable parameters as well as its implementation. Full use has been made of the [[CLOS] [Common Lisp Object System (CLOS)] to provide modularity in the design and the associated Meta Object protocol has been used to handle cross cutting concerns in the design. It was considered that the initial investment in designing the simulation framework would pay off when having to port protocols across to it and when designing new protocols.

(defclass communications(compound-module)
 ()
 (:gates
  (application :inout)
  (channel :inout))
 (:submodules
  (routing routing)
  (mac mac)
  (radio radio))
 (:connections
  (<=> application (routing application))
  (<=> (routing mac) (mac routing))
  (<=> (mac radio) (radio mac))
  (<= (radio receive) channel))
 (:metaclass compound-module-class)
 (:documentation "A Communications module"))

LENS is a discrete time event simulator. It is suitable for simulating systems which can be represented as a set of entities exchanging discrete messages over time. It supports a hierarchical design methodology where complex entities (called compound modules) are broken down into smaller networks of components etc until we get to simple modules (or just modules) which contain the specific implementation details of the system being modelled. The modules (whether simple or compound) interact by send and received messages through named gates. Connections between gates are represented using channels which may include delays and modify the messages (for example adding in message loss or errors). The system models are described and implemented using the Common Lisp (CL) programming language. Figure fig:compound shows an example of a compound communications model with the CL and the associated graphical representation. The system component types are defined as classes using CLOS - part of this definition is the set of configurable parameters for the model which will be read from a configuration file when it is being run.

Simulations are used to run a series of experiments which varying system parameters and to collect a measurements of the system performance for each experiment. LENS provides separation of the system model from the specification of the experiments being performed. It is not necessary to change the model to carry out different experiments. Experiments are described in configuration files which specify what parameters to use and what measurements are to be recorded. A single configuration file may describe many different named experiments and may also specify a series of experiments with varying parameters.

The model implementation modules are instrumented by signalling signal useful events or value changes using emit. These signals may be handled by the simulator to collect statistics and provide performance evaluation reports. They might also be used to update various views of the running simulation (for example a graphical display). No such graphical display is currently implemented.

The framework is generic and many different models may be represented using it. It is recommended that a package be created for each model which uses the :lens package (as well as :cl and :cl-user) and that all declarations for that model are made in it's package. This will prevent namespace collisions between models. Users should then be in a particular model package when running it. When reading parameters the :lens namespace is used by default so symbols which may be read from external files will need to be specified either with an explicit package name or be exported into the :lens package. Parameter names however are parsed as strings as they are addressed by their position in the model hierarchy and so the package in which they are declared is ignored.

Simulations are represented as a heirarchical network of modules interconnected using channels. Every simulation must have one top level network module which will specify submodules and their interconnections. These submodules may be compound modules which can contain further submodules or simple modules which contain implementations. All module types are declared as CLOS classes inheriting from network, compound-module and module base classes as appropriate. In addition module classes must declare a metaclass - compound-module-class for networks and compound modules and module-class for simple modules. These meta-classes allow for the declaration of parameter slots (where the value may be initialised from the configuration file), gates, submodules and connections in the class definition. When a simulation is run the network type is read from the parameter file and created. This will then create the submodules and so on until the whole network is created.

message instances in LENS are used to represent events, packets, commands, jobs, customers and other types of entities depending on the model domain. They may be sent through gates and channels between modules or may be send directly to a module. The base message class records the creation time, transmission time, arrival time and the source and destination entites. The send generic function provides the basic mechanism for a module to send a message out through one of its named gates. The gate can be an actual gate object or it's specifier.

The simulator will call handle-message with the module and message when at the message arrival time.

packet instances objects are messages used to represent network packets.

All message and packet types must override the duplicate method to provide proper duplication semantics (i.e. must explicitely copy slots from an originating packet to a duplicate one. The encapsulate and decapsulate methods are used to embed and access higher level encapsulated packets. Duplication does results in the originating and duplicate packets sharing the same encapsulated packet - however decapsulating returns a duplicate of the encapsulated packet ensuring appropriate copy semantics are maintained efficiently through this interface.

The control-info field in packets may be used to pass additional information with packets as they are passed between protocol layers - for example command information to a lower layer as the packet is passed down or additional information associated with packet reception as the packet is passed up a protocol stack.

For a simulation to be useful it must collect useful information on the model operation. Separating our the generation of the information from the collecting and reporting of it allows for the maximum flexibility and generality. The LENS this is achieved with the use of named signals which may be emitted with useful information in the model implementation code and which can then be collected and analysed by listeners attached to the various modules in the simulation.

The register-signal function is normally called as a top level form to register a particular named signal with the symbol. Adding documentation is recommended so that other implements may reuse it if they have similar semantics. Registering commonly used signals ensures that their handling will be optimised.

In the model implementation the emit method is called to broadcast a signal. This may optionally take an argument (for example a count) associated with that signal. Listeners registered to receive this signal in the broadcasting module or above it in the hierarchy will all receive the signal in via the receive-signal method. If the generation of the broadcast signal is expensive the may-have-listeners function may be called to check whether it is necessary first.

Modules call the subscribe and unsubscribe functions to register or unregister a listener object for a particular signal on a particular module. A listener may be registered to more than one signal or module and can use the source-component, signal and value arguments to differentiate the source as required).

As an example an application module might register signals for packet transmission and reception at the top level in the source file.

(register-signal
 'packet-receive
 "Emitted when application receives a packet.")

(register-signal
 'packet-send
 "Emitted when application sends a packet.")

In the relevant code implementation for transmission and reception it may call (emit application 'packet-send packet) or (emit application 'packet-receive packet) respectively to inform the relevant listeners of these events. These send the actual packet as a value. Listeners should not modify the packet but may read values from them.

This package provides the main simulation framework. It is intended that every simulation system will be defined in its own package which will use this package to import the public API. Simulations should be run from within the dynamic context of their specific simulation package so that symbolic configuration parameters will be read into the correct package.

Simulations are represented as a heirarchical network of modules interconnected using channels. Every simulation must have one top level network module which will specify submodules and their interconnections. These submodules may be compound modules which can contain further submodules or simple modules which contain implementations. All module types are declared as CLOS classes inheriting from network, compound-module and module base classes as appropriate. In addition module classes must declare a metaclass - compound-module-class for networks and compound modules and module-class for simple modules. These meta-classes allow for the declaration of parameter slots (where the value may be initialised from the configuration file), gates, submodules and connections in the class definition. When a simulation is run the network type is read from the parameter file and created. This will then create the submodules and so on until the whole network is created.