====================
==                ==
== ARGoS EXAMPLES ==
==                ==
====================

AUTHOR: Carlo Pinciroli <cpinciro@ulb.ac.be>
DATE: 1/11/2011



*** INTRODUCTION ***

In this package you'll find some basic examples to start using ARGoS.

To run an experiment with ARGoS, you need to define two things:
1. the robot controllers
2. the experiment configuration

You find example controllers in the controllers/ directory.
The experiment configuration files are located in the xml/ directory.

Currently, ARGoS supports the foot-bot (a.k.a. the marXbot), the eye-bot and
the e-puck. More robots will come in the future. All the examples, for the time
being, are implemented for the foot-bot.



*** THE EXAMPLES ***

DIFFUSION

In this example experiment, a foot-bot performs obstacle avoidance while navigating in an small
square environment.
The source files in controllers/footbot_diffusion/ contain all the basic information
about how to write a robot controller. Follow the comments and you should grasp the first steps.
The configuration files for this experiment are two: xml/diffusion_1.xml and
xml/diffusion_10.xml. The first file places a single foot-bot in the environment. In
this file all the basics about the XML configuration are covered. The second file is to see
10 robots in action. This files shows how to distribute randomly 10 robots in the environment
without having to place them manually.

SYNCHRONIZATION

This example experiment reproduces the coupled oscillators of Mirollo and Strogatz. In the beginning,
the robots flash their LEDs out of sync, but over time, seeing each other's LEDs, they synchronize.
In this example you'll see how to use the camera, and how to distribute robots in a grid.

FORAGING

This example experiment is a complete experiment. It shows how to interact with the simulation through
the loop functions and the how to draw on the OpenGL graphical visualization through the Qt user
functions. The arena is divided in two areas: a grey area that serves as nest, where the robots are
initially deployed; and a white area where food items are scattered. The task of the foot-bots is
to exit the nest, search for food items, grab them and bring them back to the nest. To simplify
control, food items are just drawn as black spots on the ground, and when a robot passes over
a food item it automatically grabs it. When a robot is transporting a food item, a cylinder is drawn
on top of it. Each robot can transport only one item per time. Once a robot has grabbed an item, it
must bring it back to the nest. The direction to/away from the nest is detectable through light sensors,
that read the position of a set of lights displaced over the nest.

EVOLUTION

This example shows how to embed ARGoS into a genetic algorithm and how to evolve a simple neural network
controller. In this example, a foot-bot is evolved to perform phototaxis. The example is
composed of a neural network controller in the controllers/ drectory, a loop function in the
loop_functions/ directory and additional code in the embedding/galib directory to wrap ARGoS.
The code is compiled only if the GALIB library is found. The library is searched for in /usr or
/usr/local. If you installed the library in a different place, use the 'ccmake' command to set the correct
path. You can download GALIB at http://lancet.mit.edu/ga/.



*** COMPILATION ***

In principle, you can compile your code however you want. In practice, we found that the help of a
build system makes your work much easier. In ARGoS, and in these examples, we use CMake. To compile
the examples, open up a shell, go to the directory where you unpacked the tar.bz2 file and type:

$ mkdir build
$ cd build

To produce debuggable code (slow), type:

$ cmake -DCMAKE_BUILD_TYPE=Debug ..

To produce fast but not debuggable code, type:

$ cmake -DCMAKE_BUILD_TYPE=Release ..

Finally, launch the compilation with the command:

$ make

If you find no error, you're ready to go to the next phase.



*** RUNNING THE EXAMPLES ***

To run an example, the configuration files have been written with the hypothesis that you run them
in the directory where you unpacked the tar.bz2, NOT in the build/ directory. Therefore, go to that
directory and type:

$ launch_argos -nc xml/diffusion_1.xml

for the example obstacle avoidance with a single robot, 

$ launch_argos -nc xml/diffusion_10.xml

for the example obstacle avoidance with 10 robots,

$ launch_argos -nc xml/synchronization.xml

for the synchronization experiment, and

$ launch_argos -nc xml/foraging.xml

for the foraging experiment.
The evolution experiment is divided in two parts. The
command

$ build/embedding/galib/argos_galib

runs the evolution process. Then, the command

$ launch_argos -nc xml/evolution-trial.xml

allows one to test a specific neural network.



*** WHAT'S NEXT? ***

More examples and a complete manual. I'm in the process of writing it, I do it a little bit every day. If
you have specific questions, you can contact me at <cpinciro@ulb.ac.be>.