====== ARTÌS & GAIA HOWTO ======

The goal of this document is to provide a basic installation and usage guide for the ARTÌS/GAIA software.

===== Prerequisites =====

   * **GNU/Linux**: operating system usage
   * **Bash shell**: command line usage
   * **ARTÌS**: general structure, please see [[http://gdangelo.web.cs.unibo.it/pool/papers/gdangelo-PERF-2005.pdf|FIRB2005]].
   * **GAIA/GAIA+**: general structure, please see [[https://arxiv.org/abs/1610.01295|SIMPAT2017]].

===== Assumptions =====

   * **UBUNTU Linux 12.04.1**: desktop version, fully updated

===== Installation =====

==== Download ====

The last version of the ARTÌS/GAIA software can be freely downloaded from the [[pads:download|downloads page]]. The runtime is available in both 32 and 64 bits versions.

<color #ff6600>EXAMPLE:</color>
<code>
wget http://pads.cs.unibo.it/download/artis/ARTIS-2.0.4-i686.tar.bz2
</code>

Untar the downloaded file in the chosen directory.

<color #ff6600>EXAMPLE:</color>
<code>
tar xvfj ARTIS-2.0.4-i686.tar.bz2
</code>

==== Missing libraries ====

<color #ff0000>MISSING LIBRARIES:</color> the standard installation of Ubuntu 12.04.1 is missing some libraries that are needed by ARTÌS/GAIA. The following libraries have to be installed using the command line interface (as shown in the following) or the graphical tools provided in Ubuntu. Starting from ARTÌS+GAIA version 2.1.0 the "libgcrypt" libraries are no longer necessary.

|  name            ^  description  ^ 
^ libgcrypt11    |  cryptographic functions  |
^ libgcrypt-dev    |  cryptographic functions, development files  |
^ libglib2.0-0    |  library with useful C routines  |
^ libglib2.0-dev    |  library with useful C routines, development files  |

<color #ff6600>EXAMPLE:</color>
<code>
sudo apt-get install libgcrypt11 libgcrypt-dev libglib2.0-0 libglib2.0-dev
</code>

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


==== A simple example ====

Now we are ready for testing our ARTÌS/GAIA installation. In the main directory of the software (e.g. the ARTIS-2.0.0 directory) there is the STRUCTURE.TXT file that describes the whole software structure including EXAMPLES and MODELS. We will start from the WIRELESS example that is contained in the EXAMPLES directory. In this simple model there is a set of wireless devices moving in a toroidal 2D space. The interactions among them are based on proximity.

<color #ff6600>EXAMPLE:</color>
<code>
cd ARTIS-2.0.4/EXAMPLES/WIRELESS
</code>

All the models and examples are provided as source code and therefore need to be compiled before usage, in all cases a Makefile is provided.

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

If the compilation is successful then the **sima** and the **wireless** binaries have been created in the current directory. A couple of shell scripts are provided for running the example, in this case we will use the **run** script. Running the script with no parameters generates an error and shows the syntax to be used.

<color #ff6600>EXAMPLE:</color>
<code>
./run
       Incorrect syntax...               
USAGE: ./run #LP #SMH
</code>

The first parameter (#LP) is the number of Logical Processes used in the simulation and the second one (#SMH) is the number of objects to simulate.

<color #ff6600>EXAMPLE:</color>
<code>
./run 2 100
</code>

In this case we have run a simulation composed of 2 LPs and a total number of 100 simulated objects (i.e. 50 in each LP).

{{:pads:artis-1.jpg|}}

Both the LPs have completed the execution, the elapsed amount of time is shown in the output. The execution has produced one log file for each LP in which is reported a step-by-step evolution of simulated model. The log files are named {{:pads:0.out|}} and {{:pads:1.out|}}. Furthermore, two extra log files for runtime errors and low level diagnostic are produced: {{:pads:0.err|}} {{:pads:1.err|}}.

<color #ff6600>EXAMPLE:</color>
<code>
gedit 0.out
</code>

{{:pads:artis-2.jpg|}}

The first lines in the file (that is the logfile of the LP 0) show some configuration options of ARTÌS/GAIA. In the following is shown step-by-step the position (i.e. coordinates) of each object in the simulated area.

{{:pads:artis-3.jpg|}}

The tail of the file reports the number of simulated steps (Clock), the "Elapsed Time", the total number of "Processed events" and the "Events per second". 

Now please take some time for reading the source code of this simple example: {{:pads:wireless.c|}}. This model is based only on the APIs provided by the [[pads:artis|ARTÌS]] runtime. For an example that is based on the [[pads:gaia|GAIA]] framework please see the next section.


==== A more complex model ====

Now we can proceed with a much more complex simulated model in which are used the features offered by the [[pads:gaia|GAIA]] framework.

<color #ff6600>EXAMPLE:</color>
<code>
cd..
cd..
cd MODELS/MIGRATION-AGENTS
</code>

Also in this case it is necessary to compile the simulated model using the provided Makefile.

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

If the compilation is successful then the **sima** and the **mig-agents** binaries have been created in the current directory. As usual a shell script (i.e. **run**) can be executed to start the simulation. Running the script with no parameters generates an error and shows the syntax to be used.

<color #ff6600>EXAMPLE:</color>
<code>
./run
       Incorrect syntax...            
USAGE: ./run [#TOT_LP] [#LP] [#IA]
</code>

The first parameter (#TOT_LP) is the total number of Logical Processes used in the simulation, the second one (#LP) is the amount of LPs to be run on this computer and, finally, (#IA) is the number of objects to simulate.

<color #ff6600>EXAMPLE:</color>
<code>
./run 2 2 100
</code>

In this case we have run a simulation composed of 2 LPs (both in the local PC) and a total number of 100 simulated objects (i.e. 50 in each LP).

{{:pads:artis-4.jpg|}}

The simulation has run smoothly, as usual two log files ({{:pads:gaia-0.out|0.out}}, {{:pads:gaia-1.out|1.out}}) and two error files ({{:pads:gaia-0.err|0.err}}, {{:pads:gaia-1.err|1.err}}) have been produced.

In this case the useful information in the log file of the second LP.

<color #ff6600>EXAMPLE:</color>
<code>
gedit 1.out
</code>

{{:pads:artis-5.jpg|}}

As shown in the first lines of the log file, in this case both the ARTÌS and the GAIA layers have been initialized. The simulated objects produce a some amount of interactions and the GAIA framework implements some migrations to enhance the communication load-balancing. In this case the computational load-balancing features are turned off.

{{:pads:artis-6.jpg|}}

The source code of the simple simulation model ({{:pads:mig-agents.c|}}) shows that, in this case, the [[pads:gaia-apis|GAIA APIs]] are used. For a more detailed description of the simulation model please see the source code.