The goal of this document is to provide a basic installation and usage guide for the LUNES software.
The last version of the LUNES software can be freely downloaded from the downloads page.
LUNES is provided as part of the ARTÌS/GAIA distribution or as a standalone archive. In the first case all the LUNES files are already placed in the ARTÌS-x.y.z/MODELS/LUNES while in the second one it is necessary to untar the LUNES archive in the models directory (ARTÌS-x.y.z/MODELS/).
For a complete installation and setup guide of ARTÌS/GAIA please see its specific howto: ARTÌS & GAIA HOWTO. In the following of this document we assume a running ARTÌS/GAIA installation.
MISSING LIBRARIES: the standard installation of Ubuntu 12.04.1 is missing some libraries that are needed by LUNES. The following libraries have to be installed using the command line interface (as shown in the following) or the graphical tools provided in Ubuntu.
| name | description |
|---|---|
| libigraph0 | library for creating and manipulating graphs |
| libigraph0-dev | library for creating and manipulating graphs, development files |
EXAMPLE:
sudo apt-get install libigraph0 libigraph0-dev
LUNES needs A LOT OF DISK SPACE for trace files and temporary files that are used for the performance evaluation tasks. The simulator expects to find a directory called /srv/lunes with the appropriate permissions. This directory, such as many other settings, can be changed modifying the scripts_configuration.sh configuration file (in the main LUNES directory).
NOTE: creating a new subdirectory in /srv/ requires root permissions. Furthermore, after the creation, it is needed to set the appropriate user/group permissions and permission bits. An alternative to /srv/ it could be using /tmp/ if enough disk space is available.
In this case our goal is to simulate a gossip protocol called “Conditional Broadcast” on top of some graphs (i.e. networks) with specific characteristics. Let's start moving on the LUNES directory.
EXAMPLE:
cd ARTIS-2.0.4/MODELS/LUNES
The LUNES simulator is provided as source code and therefore needs to be compiled before usage, a Makefile is provided.
EXAMPLE:
make
If the compilation is successful then the get_coverage_next, get_ids_next, graphgen, mig-agents and sima binaries have been created in the current directory.
To run LUNES it is possible to use the specific shell scripts provided to build the graphs, simulate the dissemination protocol and, finally, analyze the results. A better approach would be using the all-in-one shell scripts. For example: sim-metrics-broadcast, sim-metrics-fixedprob and sim-metrics-adaptive provide all what is needed for running a Conditional Broadcast, Fixed Probability and Adaptive gossip dissemination. For the sake of simplicity, in this example we prefer to not generate at runtime the network graphs. For this reason we will use a set of already generated graphs (called “corpus”) and therefore the specific shell scripts to use are: sim-metrics-broadcast-corpus, sim-metrics-fixedprob-corpus and sim-metrics-adaptive-corpus.
The first step is to prepare the corpus to be used in the simulation runs. In the LUNES distribution (i.e. in the example_corpuses directory) are provided some corpuses that can be used for this purpose.
EXAMPLE:
tar xvfz example-corpuses/random_corpus-100_vertex-200_edges-diameter_8-100_graphs.tgz -C /srv/lunes/
EXAMPLE:
ln -s /srv/lunes/random_corpus-100_vertex-200_edges-diameter_8-100_graphs /srv/lunes/corpus
Most of simulation parameters can be controlled using the parameters found in the scripts_configuration.sh and in the first part of the evaluation script (in this case the sim-metrics-broadcast-corpus). For example, each corpus is composed of 100 graphs but in this case, to reduce the running time, we are going to evaluate the broadcast protocol on smaller set of graphs. This can be done editing the scripts_configuration.sh and modifying the NUMBERRUNS parameter.
scripts_configuration.sh: (before)
[...] # # Total number of runs per each configuration # (for statistical purposes) NUMBERRUNS=100 # [...]
scripts_configuration.sh: (after)
[...] # # Total number of runs per each configuration # (for statistical purposes) NUMBERRUNS=10 # [...]
The sim-metrics-broadcast-corpus is intended for testing the gossip protocol in presence of a full range of dissemination probabilities. Also in this case it is possible to cut the running time reducing the number of tests to be done.
sim-metrics-broadcast-corpus: (before)
[...] # # Dissemination probability DISPROB="1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100" # [...]
sim-metrics-broadcast-corpus: (after)
[...] # # Dissemination probability DISPROB="10 30 50" # [...]
Now it is possible to start the simulation. The evaluation script will run the dissemination protocol on 10 graphs in the corpus and for each graph will test 3 different configurations (dissemination probability = {10, 30, 50}).
EXAMPLE:
./sim-metrics-broadcast-corpus
After a some amount of time in the /srv/lunes/results directory it is possible to find some aggregate results and statistics. In the standard setup LUNES is configured to delete the trace and working files that have been produced during the simulation and the results analysis. If everything is OK, in the results directory can be found 3 sub-directories:
Each directory contains the results for the adaptive broadcast gossip protocol when run with the given dissemination probability. For example, in the broadcast-100-lp1-migr0-prob50-mfactor1.2-load0 the file broadcast-STATS.dat contains the following results:
broadcast-STATS.dat:
100 63.781000 4.304000 5029901.200000 1.056000
| column | example | description |
|---|---|---|
| 1 | 100 | Number of nodes in each graph of the corpus |
| 2 | 63.781000 | Average coverage |
| 3 | 4.304000 | Average delay |
| 4 | 5029901.200000 | Average number of messages sent in each dissemination |
| 5 | 1.056000 | Overhead ratio of the dissemination |
For a better description of the metrics used in the performance evaluation please see please see DISIO11.
Bug reports are always welcome but before reporting please check the following:
Please report a detailed description of each bug using the e-mail address provided in the Contacts. The bug description is needed but not sufficient. Detailed information are required for reproducing the bug and (hopefully) fixing it. Please prepare the following data:
Please consider that all such data can be very large, the usage of the Dropbox sharing functionality is strongly encouraged.
Finally, the whole LUNES software is provided as source code. Therefore, please feel free to investigate the bugs and correct them, your patches will be very appreciated.
As described above, LUNES produces a large amount of trace files that are stored in the working directory (the default is /srv/lunes). Each line in the trace files describes the generation of a new message and/or its delivery to a node.
The file structure is very simple: STAT <operation> <one or more parameters>
In the current version there are only thee operations that are implemented: {GEN, RCV, MSG}.
| Operation | Parameter(s) | Description | Parameters |
|---|---|---|---|
| STAT GEN | parameter | A new message has been generated. | The parameter is a integer value that identifies the newly generated message. All the message identifiers are chosen at random. |
| STAT RCV | parameter1 parameter2 parameter3 [parameter4] | A new message has been received by a given node. | All the parameters are integer values. The parameter1 is the identifier of the receiver. The parameter2 is the identifier of the message that has been received. The parameter3 is the number of hops to arrive in this node. There is a parameter4 only if the message is not locally generated (i.e. it has been delivered by a neighbor). The meaning of this last parameter is the residual TTL of the delivered message. |
| STAT MSG | parameter | Total number of delivered messages. | The parameter is a integer value that identifies the total number of messages delivered in this run. |