Parallel And Distributed Simulation Research Group

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== LUNES HOWTO ======

The goal of this document is to provide a basic installation and usage guide for the LUNES software.

===== Prerequisites =====

   * **GNU/Linux**: operating system usage
   * **Bash shell**: command line usage
   * **LUNES**: general structure, please see [[http://arxiv.org/abs/1105.2447|MOSPAS11]].
   * **Gossip protocols**: introduction, please see [[http://arxiv.org/abs/1102.0720|DISIO11]].
   * LUNES is implemented on top of the ARTÌS/GAIA software, please see the related [[pads:artisinst|ARTÌS & GAIA HOWTO]].

===== Assumptions =====

   * **UBUNTU Linux 12.04.1**: desktop version, fully updated
   * **ARTÌS/GAIA**: correctly installed and working.

===== Installation =====

==== Download ====

The last version of the LUNES software can be freely downloaded from the [[pads:download|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: [[pads:artisinst|ARTÌS & GAIA HOWTO]]. **In the following of this document we assume a running ARTÌS/GAIA installation.**

==== Missing libraries ====

<color #ff0000>MISSING LIBRARIES:</color> 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  |

<color #ff6600>EXAMPLE:</color>
<code>
sudo apt-get install libigraph0 libigraph0-dev
</code>

==== Working directory ====

LUNES needs <color #ff0000>A LOT OF DISK SPACE</color> 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).

<color #ff0000>NOTE:</color> 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.

===== Basic Usage =====


==== A simple example ====

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.

<color #ff6600>EXAMPLE:</color>
<code>
cd ARTIS-2.0.4/MODELS/LUNES
</code>

The LUNES simulator is provided as source code and therefore needs to be compiled before usage, a Makefile is provided.

<color #ff6600>EXAMPLE:</color>
<code>
make
</code>

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.

<color #ff6600>EXAMPLE:</color>
<code>
tar xvfz example-corpuses/random_corpus-100_vertex-200_edges-diameter_8-100_graphs.tgz -C /srv/lunes/
</code>

<color #ff6600>EXAMPLE:</color>
<code>
ln -s /srv/lunes/random_corpus-100_vertex-200_edges-diameter_8-100_graphs /srv/lunes/corpus
</code>

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.

<color #ff6600>scripts_configuration.sh: (before)</color>
<code>
[...]
#
#       Total number of runs per each configuration
#       (for statistical purposes)
NUMBERRUNS=100
#
[...]
</code>

<color #ff6600>scripts_configuration.sh: (after)</color>
<code>
[...]
#
#       Total number of runs per each configuration
#       (for statistical purposes)
NUMBERRUNS=10
#
[...]
</code>

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.

<color #ff6600>**sim-metrics-broadcast-corpus**: (before)</color>
<code>
[...]
#
# 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"
#
[...]
</code>

<color #ff6600>**sim-metrics-broadcast-corpus**: (after)</color>
<code>
[...]
#
# Dissemination probability
DISPROB="10 30 50"
#
[...]
</code>

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}).

<color #ff6600>EXAMPLE:</color>
<code>
./sim-metrics-broadcast-corpus
</code>

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:
  * **broadcast-100-lp1-migr0-prob10-mfactor1.2-load0** 
  * **broadcast-100-lp1-migr0-prob30-mfactor1.2-load0**
  * **broadcast-100-lp1-migr0-prob50-mfactor1.2-load0**
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:

<color #ff6600>**broadcast-STATS.dat**:</color>
<code>
100     63.781000                4.304000        5029901.200000  1.056000
</code>

|  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 [[http://arxiv.org/abs/1102.0720|DISIO11]].

===== Bug reports =====

Bug reports are always welcome but before reporting please check the following:

  * do you have enough free disk space for a correct execution of LUNES?
  * are you able to reproduce the bug using the "vanilla" (standard) version of LUNES?

Please report a detailed description of each bug using the e-mail address provided in the [[pads:contacts|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:

  * the command line used for running the LUNES experiment;
  * a tarball containing the whole **artis/MODELS/LUNES** directory;
  * the "corpus" that has been used in the experimental evaluation;
  * the "traces" directory in the LUNES working directory (e.g. /**srv/lunes/traces**). Please note that in the standard configuration LUNES deletes all the trace files just after the statistical evaluation. This behavior can be changed setting "NOTRACE=0" in the **scripts_configuration.sh** file (in the main LUNES directory).

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.**

===== Appendix A: trace files =====

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.       |