ECMM Files

+----------------------+
|       README         |
+----------------------+

== Introduction ==

This project enables the introduction of community-based mobility models
into the OMNET++ simulation environment. These models provide many desired
characteristics, such as socially influenced mobility decisions and are
quite realistic. One specific model, namely the Enhanced Community-based
mobility model, is very suitable for opportunistic routing research
comparing to the others, because of its advanced properties. These
include a pause period, conformance to the existing social ties and
the ability to produce periodical epochs during the simulation. This 
is therefore, the main mobility model provided by this project.

Up to now, OMNET++ and the INET and INETMANET frameworks do not include
an opportunistic routing protocol implementation. Additionally, they lack
socially-aware mobility model support, thus making the simulation environment
not suitable for opportunistic and delay-tolerant research, especially
for Mobile Social Network. The main goal of this effort is therefore,
the introduction of one of the necessary tools for this kind of research,
namely the mobility model. In order though to keep the mobility model
implementation provided more generic, the code given does not implement
the model straight to OMNET++. On the contrary, the mobility model is
implemented into a simple C/C++ program which generates an XML output
file, containing the movement trajectories of the nodes involved. The
format of this file is suitable for ns-2 simulations. What the OMNET++
modules provided achieve, is the translation between the ns-2 traces
to OMNET++ directions.

More information on the ECMM model can be found on the relevant paper
published by the University of Essex:

http://link.springer.com/article/10.1007/s12652-012-0118-y?null


== Installation ==

Before trying to install ECMM, you first have to have OMNET++ simulation 
environment and INETMANET-2.0 framework already up and running in your
system. For more information on that you can check:

for OMNET++        ---  http://www.omnetpp.org/documentation
for INETMANET-2.0  ---  https://github.com/aarizaq/inetmanet-2.0

After you have completed all the above steps, you can use download the 
compressed ECMM. In order to import the simulator into OMNET++ 
you just have to follow a simple procedure. First you go to File->Import 
and choose General->Archive File. After that you just press Next and 
that it. You have made it! The only thing left it to build the download 
project. To do this, you need to go to Run->RunConfiguration... and 
create a new configuration by double clicking on the OMNET++ Simulation 
element on the left side list. Change the name of the configuration 
that you will see and choose the following as your working directory:

/ECMM/simulations 

Afterwards, choose the General option in the "Config name" drop down 
menu and press run. That should do the job.


== Basic Modules ==

DTApp: It is actually quite similar to the UDPBasicBurst Application module.
Sends UDP packets to the given IP address at the given interval. It is 
compatible with both IPv4 and IPv6. Their only difference it that the DTApp 
has a bit more advanced duplicate message detection mechanism and it is
able to compute a percentage outcome of the delivered packages. This
percentage does not indicate anything on its own, but by averaging all the
metrics from all the modules, the actual delivery percentage can be extracted. 

CommunityMov: This module extends the BasicMobility interface provided by  
inetmanet in order to implement a mobility model that is able to read from 
the mobility traces from an XML file of a specific format. It basically
reads these traces, locates the future targets and makes the modules
to move towards them at straight line trajectories. The XML format
is based on the ns-2 simulator, used by Mirco Musolesi for his Comminity-based
 mobility model implementation. This file containing the traces should be
pre-generated and available before the simulation takes place, usually
by the SocMovGen module.

socMovGen: The socMovGen module calls the appropriate C++ program in order to
the XML file needed by the CommunityMov module. There are generate three
options for this tracefile generation. This first one is to use the Enhanced
Community-based Mobility Model (ECMM). However, for comparison purposes,
the CMM and HCMM options are also provided. Although these models
do not use all the arguments provided, they are fully functional,
by discarding them. The main functionality of this module therefore, 
is just to gather the required arguments and to pass them to
the selected model's tracefile generation program. 


== Community-Based Models ==

In community-based mobility models, such as CMM, nodes are assigned to 
distinctive social groups called communities. Although a node could be 
thought to simultaneously belong to multiple communities, in most cases for 
simplification, only one community is assigned to each node. These communities 
are then mapped to specific geographical areas on a map. In both CMM and HCMM, 
the simulation area is considered to be a rectangle where distinct areas are 
defined by the squares of a grid, called cells. On the other hand, the 
relationships between the nodes are modelled by weighted social links in the 
range [0,1].

The most important contribution of CMM is the method social ties are generated,
a method also followed by HCMM. Initially, nodes are assigned to a specified 
number of communities in a round-robin-like manner. Inside these communities, 
social links are created between all the nodes, while random weights are 
assigned to them, larger or equal to a specific threshold mth. This threshold 
denotes the minimum strength of the strong social relationships and hence how 
strongly friends are connected. Moreover, weak social ties are also assigned 
between all nodes not linked during this initial social network generation 
process with values in the range [0,m_th]. Consequently m_th controls not only
the strength of social relationships between friends but also between 
strangers.
 
Afterwards, each strong link, connecting two nodes belonging to the same 
community, is rewired to a node of another community with a certain probability 
pr. As a result, an inter-connected social network is constructed, comprising 
from multiple distinctive communities. This Small World community generation 
model was first introduced by Watts and it is known as the Caveman Model. 
In CMM however, especially in cases of high p_r, the initial communities might
not represent the resulting community structure at all, as there is the 
possibility that nodes will be completely disconnected from their initial 
groups. Therefore, a community detection algorithm is also provided, namely the 
Girvan-Newman method for weighted graphs. This whole procedure, typical for the 
community-based mobility models, is also present in ECMM.

The social links mentioned previously determine the mobility choices of the 
nodes. More specifically, each cell of the map exerts an attraction towards 
every node, which depends on the sum of the attractions of all the nodes 
temporarily residing in its area.

Up to this point, the same process is followed by both CMM and HCMM. However, 
in HCMM the social attractivity to a node from each cell remains the same 
throughout the trace generation procedure. It only depends on the attraction 
of the nodes initially residing into each cell. This feature was introduced 
because it was noticed that in CMM, "if several nodes had social relationships 
outside their community, there would be more nodes going outside the starting 
cell". By introducing this feature, the authors attempted to avert this 
worst-case scenario, as well as to capture the effect of physical location 
attraction on users. One more positive outcome of this adjustment was the 
simplification of the model's mathematical tractability. However, regardless 
of its interesting properties, HCMM fails to maintain the most important 
feature for every social mobility model, which is the dynamic mobility decision 
mechanism, based on the current social environment. Thus, it ends up being a 
simple random choice scheme between various locations, with no existing 
influence from the social ties.

After establishing the communities and the attraction between the nodes, 
the following node movement process is the same for both CMM and HCMM. 
Each node chooses probabilistically a cell to move into, where the choice 
likelihood depends on the total attraction of the cell. After a cell is chosen, 
a point inside it is randomly selected as the specific target of the node. 
Afterwards, the node moves towards the direction of its target with a specific 
speed. When the target has been reached, the same decision process takes place 
for the selection of a new target.

== ECMM & iGraph == 

In order to enable a more advanced research into social communities and their
generated traces, the igraph library has been introduced into the enMovGen
program. This allows the generation of traces of much larger communities in
much less time. This is the case because during the Girvan-Newman algorithm,
the used community detection algorithm implementation is much slower than the
one in igraph. However, the igraph library is initially deactivated. If the
user prefers to use this option, all that needs to be done is the introduction
of the igraph library into OMNET++ in the ECMM project. Afterwards, just 
uncomment the proper lines in the enMovGen source code and comment the call
of the original Girvan-Newman call functions. Comment in the code should also
provide a helpful guidance. Compilation should be successful. 


== Simulation Parameters ==

The main parameters than control the simulation can be viewed and 
accessed from the omnetpp.ini file. The most important ones are 
the following:

**.host*.mobilityType: Should be set to "CommunityMov".
**.socMovGen.mobType: three mobility models are supported, the CMM, the HCMM 
					  and the ECMM.
**.socMovGen.totalSimulationTime: sets the total simulation time.
**.socMovGen.reconfigurationInterval: sets the reconfiguration interval.
**.socMovGen.numberOfEpochs: sets the number of the epochs.
**.socMovGen.minHostSpeed: sets lower bound of the speed of the hosts.
**.socMovGen.maxHostSpeed: sets upper bound of the speed of the hosts.
**.socMovGen.connectionThreshold: sets the connection threshold, for 
                                  which a friendship is regarded.
**.socMovGen.numberOfRows: sets the number of rows of the simulation ground
**.socMovGen.numberOfColumns: sets the number of columns of the simulation 
                              ground.
**.socMovGen.radius: sets the transmission range (in m) --  not so important
**.socMovGen.rewiringProb: sets the rewiring probability during the model 
                           initialization.
**.socMovGen.numberOfGroups: sets the initial number of groups for the Caveman 
                             model.
**.socMovGen.randSeed: sets the seed of the Random Number Generator.
**.socMovGen.numberOfTravellers: sets the number of travellers.
**.socMovGen.travellerSpeed: sets the speed of the travellers.
**.socMovGen.girvanNewmanOn: sets the Girvan-Newman algorithm on/off.
**.socMovGen.deterministicOn: sets the deterministic selection of the nodes 
                              on/off. If true the selection is deterministic, 
                              if false is probabilistic.
**.socMovGen.generateXML: generates XML.
**.socMovGen.readAdjacency: indicates whether an input adjacency file will be
                            used.
**.socMovGen.outputAdjacency: sets the output adjacency file generation on/off.
**.socMovGen.pauseTime: sets the maximum pause time duration.
**.socMovGen.inputFile: sets the the name of the input adjacency file.
**.socMovGen.colocationTracesOn: sets the colocation traces on/off.
**.socMovGen.communitiesTracesOn: sets the communities traces on/off.


== Notes ==

Tested only for omnetpp-4.6 with inetmanet-2.2.

For any comments email me at nvasta@essex.ac.uk

Nikolaos Vastardis