Difference between revisions of "GSOC2012HLA"

From Nsnam
Jump to: navigation, search
Line 169: Line 169:
  
 
==Achieved Goals==
 
==Achieved Goals==
 +
 +
===A new Scheduler (chucked)===
  
 
During the first week of GSoC we worked on a RTI sheduler. This scheduler was suppose to receive messages from RTI through ns-3 federate and had map data structure. It was suppose to convert these messages received into ns-3 events. After few days we analysed the design and figured out that there could be a easier way of doing this by just modifying an implementation of src/syncronization.cc that is wall-clock-syncronizer.cc and using a real-time-simulater-impl.cc as a simulator. Thus, we changed our design a bit.
 
During the first week of GSoC we worked on a RTI sheduler. This scheduler was suppose to receive messages from RTI through ns-3 federate and had map data structure. It was suppose to convert these messages received into ns-3 events. After few days we analysed the design and figured out that there could be a easier way of doing this by just modifying an implementation of src/syncronization.cc that is wall-clock-syncronizer.cc and using a real-time-simulater-impl.cc as a simulator. Thus, we changed our design a bit.
Line 174: Line 176:
 
By the end of second week the new design was ready and we were in touch with the portico community and discussed the project. After input from them we finalised the design. We chucked the RTI scheduler module, although some part of the code was reusable.
 
By the end of second week the new design was ready and we were in touch with the portico community and discussed the project. After input from them we finalised the design. We chucked the RTI scheduler module, although some part of the code was reusable.
  
Next, we worked on getting portico up and running some example federates and creating a federation using two or more federates. Then using the poRTIco documentation we wrote some ns3Federate. ns3Federate basically has the defination for setting up a federation and enabling various features for ns-3 like time definations. It also creates objects, sets basic attributes and publish and subscribe these objects. Objects can also be registered and deleted through this. It also contains the main simulation loop with all the above mentioned events in order.
+
===ns3 client for communicating with RTI===
  
After ns3Federate we worked with ns3FedAmb (Federate Ambassador), this basically handles callbacks which the RTI (poRTIco in our case) sends them to ns-3 as and when an object is published, subscribed, deleted or any attribute is changed. A callback is also received in case of a time advance request grant. So, all in all the two classes provide an interface to communicate with the RTI and help in basic syncronization of the events with other federates by receiving time advance granted callbacks.  
+
Next, we worked on getting portico up and running some example federates and creating a federation using two or more federates. Then using the poRTIco documentation we wrote some ns3Federate. ns3Federate basically has the definition for setting up a federation and enabling various features for ns-3 like time definitions. It also creates objects, sets basic attributes and publish and subscribe these objects. Objects can also be registered and deleted through this. It also contains the main simulation loop with all the above mentioned events in order.
 +
 
 +
After ns3Federate we worked with ns3FedAmb (Federate Ambassador), this basically handles callbacks which the RTI (poRTIco in our case) sends them to ns-3 as and when an object is published, subscribed, deleted or any attribute is changed. A callback is also received in case of a time advance request grant. So, all in all the two classes provide an interface to communicate with the RTI and help in basic synchronisation of the events with other federates by receiving time advance granted callbacks.  
 +
 
 +
===Testing===
  
 
Once we were through with this, we had a lot of code but nothing to test it. So, we worked on developing another set of federate and federate ambassador, called dummy and dummyFederateAmbassador. The features of these two were similar to ns-3 but this federate also had a small simulation. It changed the attributes of the object published by ns-3, it changed the MsgType i.e. the type of message to be sent and the Msg i.e. actual text (planning to change it to data rate and delay), so when this federate was run in parallel with ns-3 federate, various functions could be easily tested, like if ns-3 is receiving callbacks when the attributes are changed? and is the changed values of the attributes reflected? After getting rid of some initial bugs everything worked fine.
 
Once we were through with this, we had a lot of code but nothing to test it. So, we worked on developing another set of federate and federate ambassador, called dummy and dummyFederateAmbassador. The features of these two were similar to ns-3 but this federate also had a small simulation. It changed the attributes of the object published by ns-3, it changed the MsgType i.e. the type of message to be sent and the Msg i.e. actual text (planning to change it to data rate and delay), so when this federate was run in parallel with ns-3 federate, various functions could be easily tested, like if ns-3 is receiving callbacks when the attributes are changed? and is the changed values of the attributes reflected? After getting rid of some initial bugs everything worked fine.
 +
 +
====Getting data from the client to ns3===
  
 
Next aim was to get these callbacks and messages into ns-3 main code (C++). So a C++ class was created, server.cc. Further, in ns3FedAmb sockets were added. A master - slave configuration was set up between ns3FedAmb and server.cc. When simulation was to be started, finished, object attributes are updated, new objects are published or time advance is granted  ns3FedAmb sends a specific string to a given port along with the accompanied message. Server.cc was a simple test program, it reads throgh a port (same as ns3FedAmb) and accordingly take decision. Like on time advance a variable RTI_CLK is incremented. Rest functions for now were only for proof of concept. We also implemented a different thread which hears from ns3FedAmb and main thread can work on something else. It is a requirement since when ns-3 will be handling events from other simulator, it will also have it's own work/events.
 
Next aim was to get these callbacks and messages into ns-3 main code (C++). So a C++ class was created, server.cc. Further, in ns3FedAmb sockets were added. A master - slave configuration was set up between ns3FedAmb and server.cc. When simulation was to be started, finished, object attributes are updated, new objects are published or time advance is granted  ns3FedAmb sends a specific string to a given port along with the accompanied message. Server.cc was a simple test program, it reads throgh a port (same as ns3FedAmb) and accordingly take decision. Like on time advance a variable RTI_CLK is incremented. Rest functions for now were only for proof of concept. We also implemented a different thread which hears from ns3FedAmb and main thread can work on something else. It is a requirement since when ns-3 will be handling events from other simulator, it will also have it's own work/events.
  
Next, we integrated this server.cc code to one of the ns-3 examples for fun (It could later help in developing the HLA API) now a ns-3 example first.cc receives messages from RTI, thus other federates. We tested this by running ns3Fedrate in one shell and parallely running dummy in another shell and first.cc in another. Object was published by ns-3 and dummy both and modified by dummy at each iteration. These changes were transffered to ns3Fedrate and subsequently first.cc and that too keeping time in mind, i.e. syncronised. A  very crude form of HLA established.
+
===Testing===
 +
 
 +
Next, we integrated this server.cc code to one of the ns-3 examples for fun (It could later help in developing the HLA API) now a ns-3 example first.cc receives messages from RTI, thus other federates. We tested this by running ns3Fedrate in one shell and parallel running dummy in another shell and first.cc in another. Object was published by ns-3 and dummy both and modified by dummy at each iteration. These changes were transferred to ns3Fedrate and subsequently first.cc and that too keeping time in mind, i.e. synchronised. A  very crude form of HLA established.
  
 
After this we started refining the server.cc and changed it to link-to-rti.cc and link-to-rti.h. The work on this is still under progress, the idea is that this could be included by hla and user can have API access to these function.  
 
After this we started refining the server.cc and changed it to link-to-rti.cc and link-to-rti.h. The work on this is still under progress, the idea is that this could be included by hla and user can have API access to these function.  
Line 188: Line 198:
 
==Future Goals==
 
==Future Goals==
  
 +
Once link-to-rti is complete we plan to work on Synchronisation and API simultaneously. Then we plan to write some examples to demonstrate the use of API and possible an API test.
 +
 +
Synchronisation as of now looks pretty straight forward, although we do have to check it. It seems that just by using the real-time-simulator-impl.cc as the default simulator for hla and changing a synchronizer.cc implementation, i.e. wall-clock-synchronizer.cc to send RTI time as real time, events could be scheduled to RTI time. Moreover, a single function GerRealTime() at presents gives real time, changing it to fetch the value of RTI_CLK might do the trick.
 +
 +
API will be designed for accessing various functions of link-to-rti and also giving the user option to create publishable objects, set and read characteristics.
 +
 +
==Known Issues/Limitations==
 +
 +
One of the known issue is that the time advance request grated by RTI are not consistent at times, we are in touch with portico community to figure out what is the problem with our implementation.
  
==Know Issues==
+
A limitation of the present model is that ns-3 acts as a sink and not a source, which we added as a future milestone. Moreover the federate at present is not sending interaction only publishing objects, another future milestone.

Revision as of 06:35, 10 July 2012

HLA interfaces for ns-3

  • Student: Mudit Raj Gupta
  • Mentors: Tommaso Pecorella
  • Code: http://code.nsnam.org/muditraajgupta/ns-3-hla/ns-3-dev/
  • Mid-Term Report:
  • Abstract: The project deals with writing a HLA compliant scheduler for NS-3 and relevant supporting classes with a HLA API to help NS-3 participate in distributed simulations with other simulators, preferably scenario simulators. HLA is an IEEE standard, facilitates interoperability among simulations and promotes reuse of simulation models. Project also deals with testing of the same by using a portico RTI.The complete proposal can be found here.
  • About me: I'm a fourth year student presently working for my M.Sc (H) in Chemistry and B.E. (H) in Electronics and Instrumentation Engineering at Birla Institute of Technology and Science - Pilani at Goa Campus. My research interest include modelling and simulation of complex systems and use and analysis of evolutionary algorithms for swarms.
  • Introduction:

HLA

HLA, which is an IEEE standard, facilitates interoperability among simulations and promotes reuse of simulation models. Using HLA, a large-scale distributed simulation can be constructed by linking together a number of distributed simulation components (or federates) into an aggregate simulation (federation). [2].

RTI

Run-time infrastructure (RTI) is a middleware that is required when implementing the High Level Architecture. RTI is the fundamental component of HLA. It provides a set of software services that are necessary to support federates to coordinate their operations and data exchange during a runtime execution. In other sense, it is the implementation of the HLA interface specification but is not itself part of specification

Federates can communicate to RTI through RTI ambassador. Request of a service from/to federate to/from any other federate is done through interactions. There are two basic ways to communicate:

  • Interchange messages between federates
  • Publication of objects that are shared between federates

poRTIco is an open-source Java implementation of the above mentioned standard and it offers libraries to implement a federate ambassador. It is an interface between the RTI and the simulator. Federates can communicate to RTI through RTI ambassador. Every time the federate schedule wants to advance in the time, it calls the methods timeAdvanceRequest of the RTI ambassador.

Approach

Design

In order to make ns-3 IEEE 1516 a new HLA compliant scheduler for ns-3 (rtiScheduler), has to be designed along with ns3FederateAmbassador.

  • 1. Ns3Federate
  • 2. LinkToRti
  • 3. Synchronising
  • 4. HLA API

There is a possibility of a two way communication between ns-3 and the other federates, but in the approach mentioned ns-3 is only used as a sink and not a source. This is so because in previous discussions with the mentor a conclusion was drawn that if ns-3 would also be used as a source, it will complicate things. The only-sink methodology can be extended to source and sink after GSoC, but adding it in the GSoC timeframe would be a bit over ambitious. Although, it will definitely be a part of post-GSoC plans.

Ns3Federate

It consists of basically two parts -

  • ns3Federate
  • ns3FedAmb

ns3Federate:

It takes care of the creating a federation (if not created else joining it), registering ns3 as a Federate and running the main simulation loop. It also deals with publishing, deleting and registering objects and interaction in the RTI.

ns3FedAmb

This segment is also responsible for creating a port and communicating with the LinkToRti code (C++) This basically handles callbacks from the RTI. These callbacks include notification when attribute of an object is changed, new object is added/registered or deleted and when a time advance request is granted. A server – client paradigm is implemented between ns3FedAmb and link-to-rti. It is implemented by using sockets.

link-to-rti

A message server is set up and appropriate sockets are used get messages from ns3FedAmb. It also acts as an entry level module to ns3 code and links ns3Federate with HLA API. It also controls time values and maintains a RTI_CLOCK.

Synchronisation

There is still a lot of debate in the synchronisation of the RTI clock with ns-3. The present approach finalised and yet to be tested looks like making a minor change in wall-clock-syncronizer.cc by changing the GetRealTime to GetRtiTime (which fetches RTI_CLOCK value) and using the real time simulator with almost no modification. Since it will wait for an event to process till real time has been reached (i.e RTI_CLOCK is the new real time). So the function process_one_event will take care of event scheduling.

HLA API

HLA API will be designed to access various features of ns-3-hla like initialise ns-3 Federate, Create Object, Add Attributes to Object, Accessing Attributes of Object.

Testing approach

  • Validation Test 1 (V1): Communication with other Federates (dummy)
  • System Integration Test 1 (S1): Message Passing between ns3Federate Ambassador and ns3 link-to-rti
  • System Integration Test 2(S2): Message Passing between RTI and ns3FederateAmbassador
  • Unit Test 1 (U1): Checking ns3Federate (Java Sockets)
  • Unit Test 2 (U2): Checking link-to-rti (C++ sockets)
  • API (API1) test is to be done with the final HLA RTI API.

Deliverables

Note: The bold text details the changes/progress from initial deliverables

  • 1.0 rtiScheduler (renamed link-to-rti)
    • 1.1 The class will be the sub class of the base class ns3::Scheduler and all virtual functions defined would be written like – Insert, PeakNext, IsEmpty, Remove, Remove. Activating a thread responsible to receive messages from the ns3FederateAmbassador and uses them appropriately. (chucked)
    • 1.2 Setting up a message server and using appropriate sockets to get messages from ns3FederateAmbassador(Done)
    • 1.3 Handling/decoding messages received (Done)
    • 1.4 Generating and Sending Time advance Request and taking proper action on the request being granted from the RTI. (Done)
  • 2.0 ns3FederateAmbassador (Ns3Federate)
    • 2.1 Define socket communication with link-to-rti (Done)
    • 2.2 Define Semantics for other federates to send message to ns-3 (Done)
    • 2.3 Define ambassador for ns3 according to poRTIco definition and adding various functions to interface with poRTIco to receive messages and send request and various other functions (Done)
    • 2.4 Integrate all the above classes and write a test code to run the ns3FederateAmbassador. (Done)
  • 3.0 HLA API
    • 3.1 Writing the Informer function and update HLA class (Done, link-to-rti has functions to make it similar to informer)
    • 3.2 Writing HLA API for the designed system
  • 4.0 Complex Network Simulation
    • 4.1 Writing a demo model which is HLA compliant (Done, created dummy federate)
    • 4.2 Writing a ns3 model which is HLA compliant and using both simultaneously
  • 0.0 If time permits/future plans (post GSoC)
    • 0.1 Adding the possibility of object publication and sharing in the existing code and integrating it. (Done, publishing objects)
    • 0.2 Addition of a functionality in which ns-3 will also be used as a source.
    • 0.3 Making more refined and complex model in which ns-3 will be a federate.

New Expected Deliverables

  • Synchronisation

Plan/Progress

  • Week 1 : May.21 -- May.27
* Read Code related to Scheduler and various implementations like Map Scheduler and List Scheduler
* Started Coding on RTI Scheduler, implemented basic functions (similar to Map Scheduler)
* Read about MessagePack Message Format.
  • Week 2 : May.28 -- Jun.03
* Changed the default scheduler from map to list and finally rti by small changes in simulator.cc
* Modified map-scheduler and wrote a basic rti-scheduler.cc and rti-scheduler.h implementing scheduler.cc it is basic skeleton for implementing thread for handling RTI request. Tried making thread in the class, some problems.
* Tested. Discussed progress with the mentor and figured out a flaw in design.
* no scheduler required, last 10 days work not so useful. 
* Finalised a new design started working fresh. 
* Completed deliverable 1.1 but soon was chucked from the final design 
   
  • Week 3 : Jun.4 -- Jun.10
* Installed portico and ran demo programs in JAVA
* Tested with multiple federates, wrote a simple dummy federate. 
* Completed deliverable 4.1
  • Week 4 : Jun.11 -- Jun.17
* Completed work on writing ns3Federate and ns3FederateAmbassador in JAVA using portico
* Added functionality to dummy by sharing object between the two federates and changing attributes
* Wrote a test for checking socket implementation 
* Completed deliverable 2.3,2.2 and 0.1
  • Week 5 : Jun.18 -- Jun.24
* Integrating the server code to one of the NS3 examples.
* Tested and debugged of the entire code. 
* Completed deliverable 2.1, 2.4
  • Week 6 : Jun.25 -- Jul.01
* Completed work on writing a C++ code for reading socket values
* Completed work on integrating the above code with link-to-rti and decoding messages
* Completed deliverable 1.2 and 1.3
  • Week 7 : Jul.02 -- Jul.08
* Migrated code repo from code.google.com to code.nsnam.org
* Time advance request handled and wrote various functions to decode the RTI messages
* Created various functions to start simulation, stop simulation and RTI_CLOCK
* Completed work on deliverables 1.4 and 4.1
  • Week 8 Jul.09 -- Jul.15: Testing and Documenting and Mid Term
  • Week 9 Jul.16 -- Jul.22: Deliverable "New Added Deliverable" : Syncronization
  • Week 10 Jul.23 -- Jul.29: Deliverable 3.2
  • Week 11 Jul.30 -- Aug.5: Deliverable 4.2
  • Week 12 Aug.06 -- Aug.12: Wrap up, clean, document and test (Prepare for Final Evaluation)
  • Week 13 Aug.13 -- Aug.19: Buffer

References

  • [1] http://www.cs.bham.ac.uk/research/projects/hlarepast/
  • [2] Distributed Repast Agent Based Simulation with HLA - R. Minson and G. K. Theodoropoulos, CONCURRENCY AND COMPUTATION: PRACTICE AND EXPERIENCE
  • [3] Large Scale Agent Based Simulation on the Grid - Dan Chena , Georgios K. Theodoropoulos, Stephen J. Turner, Wentong Cai, Robert Minson, Future Generation Computer Systems, 24 (2008), 658-51
  • [4] MobileOnRealEnvironment-GIS: a federated mobile network simulator of mobile nodes on real geographic data- Emiliano Casalicchio, Emanuele Galli and Vittorio Ottaviani Dipartimento di Informatica, Sistemi e Produzione (DISP), 2009 13th IEEE/ACM International Symposium on Distributed Simulation and Real Time Applications
  • [5] http://porticoproject.org/index.php?title=Main_Page
  • [6] http://msgpack.org/

Mid-Term Report

The detail design, weekly progress and deliverable are on the [ project wiki]. The code produced during this period can be accessed [ here]

Achieved Goals

A new Scheduler (chucked)

During the first week of GSoC we worked on a RTI sheduler. This scheduler was suppose to receive messages from RTI through ns-3 federate and had map data structure. It was suppose to convert these messages received into ns-3 events. After few days we analysed the design and figured out that there could be a easier way of doing this by just modifying an implementation of src/syncronization.cc that is wall-clock-syncronizer.cc and using a real-time-simulater-impl.cc as a simulator. Thus, we changed our design a bit.

By the end of second week the new design was ready and we were in touch with the portico community and discussed the project. After input from them we finalised the design. We chucked the RTI scheduler module, although some part of the code was reusable.

ns3 client for communicating with RTI

Next, we worked on getting portico up and running some example federates and creating a federation using two or more federates. Then using the poRTIco documentation we wrote some ns3Federate. ns3Federate basically has the definition for setting up a federation and enabling various features for ns-3 like time definitions. It also creates objects, sets basic attributes and publish and subscribe these objects. Objects can also be registered and deleted through this. It also contains the main simulation loop with all the above mentioned events in order.

After ns3Federate we worked with ns3FedAmb (Federate Ambassador), this basically handles callbacks which the RTI (poRTIco in our case) sends them to ns-3 as and when an object is published, subscribed, deleted or any attribute is changed. A callback is also received in case of a time advance request grant. So, all in all the two classes provide an interface to communicate with the RTI and help in basic synchronisation of the events with other federates by receiving time advance granted callbacks.

Testing

Once we were through with this, we had a lot of code but nothing to test it. So, we worked on developing another set of federate and federate ambassador, called dummy and dummyFederateAmbassador. The features of these two were similar to ns-3 but this federate also had a small simulation. It changed the attributes of the object published by ns-3, it changed the MsgType i.e. the type of message to be sent and the Msg i.e. actual text (planning to change it to data rate and delay), so when this federate was run in parallel with ns-3 federate, various functions could be easily tested, like if ns-3 is receiving callbacks when the attributes are changed? and is the changed values of the attributes reflected? After getting rid of some initial bugs everything worked fine.

=Getting data from the client to ns3

Next aim was to get these callbacks and messages into ns-3 main code (C++). So a C++ class was created, server.cc. Further, in ns3FedAmb sockets were added. A master - slave configuration was set up between ns3FedAmb and server.cc. When simulation was to be started, finished, object attributes are updated, new objects are published or time advance is granted ns3FedAmb sends a specific string to a given port along with the accompanied message. Server.cc was a simple test program, it reads throgh a port (same as ns3FedAmb) and accordingly take decision. Like on time advance a variable RTI_CLK is incremented. Rest functions for now were only for proof of concept. We also implemented a different thread which hears from ns3FedAmb and main thread can work on something else. It is a requirement since when ns-3 will be handling events from other simulator, it will also have it's own work/events.

Testing

Next, we integrated this server.cc code to one of the ns-3 examples for fun (It could later help in developing the HLA API) now a ns-3 example first.cc receives messages from RTI, thus other federates. We tested this by running ns3Fedrate in one shell and parallel running dummy in another shell and first.cc in another. Object was published by ns-3 and dummy both and modified by dummy at each iteration. These changes were transferred to ns3Fedrate and subsequently first.cc and that too keeping time in mind, i.e. synchronised. A very crude form of HLA established.

After this we started refining the server.cc and changed it to link-to-rti.cc and link-to-rti.h. The work on this is still under progress, the idea is that this could be included by hla and user can have API access to these function.

Future Goals

Once link-to-rti is complete we plan to work on Synchronisation and API simultaneously. Then we plan to write some examples to demonstrate the use of API and possible an API test.

Synchronisation as of now looks pretty straight forward, although we do have to check it. It seems that just by using the real-time-simulator-impl.cc as the default simulator for hla and changing a synchronizer.cc implementation, i.e. wall-clock-synchronizer.cc to send RTI time as real time, events could be scheduled to RTI time. Moreover, a single function GerRealTime() at presents gives real time, changing it to fetch the value of RTI_CLK might do the trick.

API will be designed for accessing various functions of link-to-rti and also giving the user option to create publishable objects, set and read characteristics.

Known Issues/Limitations

One of the known issue is that the time advance request grated by RTI are not consistent at times, we are in touch with portico community to figure out what is the problem with our implementation.

A limitation of the present model is that ns-3 acts as a sink and not a source, which we added as a future milestone. Moreover the federate at present is not sending interaction only publishing objects, another future milestone.