User Tools

Site Tools


Sidebar

Homepage


General

People
Publications
Contacts


Software


Projects


Datasets


Documentation

pads:lunesinst

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 MOSPAS11.
  • Gossip protocols: introduction, please see DISIO11.
  • LUNES is implemented on top of the ARTÌS/GAIA software, please see the related 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 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-2.0.4/MODELS/LUNES while in the second one it is necessary to untar the LUNES archive in the models directory (ARTÌS-2.0.4/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

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

Working directory

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.

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.

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:

  • 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:

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

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 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). Following this link it is possible to download an example of such traces. In this case, each file is the output of a single evaluation on a different graph. Each line in the 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.
pads/lunesinst.txt · Last modified: 2014/09/26 06:52 by gdangelo