1. What is ARGoS?

ARGoS is a physics-based simulator designed to simulate large-scale robot swarms. Benchmark results show that ARGoS can perform physics-accurate simulation involving thousands of robots in a fraction of real time. ARGoS' main features are:

  • Multi-threaded and deeply modular architecture, more flexible than any simulator with equivalent features;

  • The possibility to run multiple physics engines at the same time;

  • The possibility to divide the physical space in region, and assign different regions to different physics engines.

Starting from version 3, ARGoS is released under the terms of the MIT license.

2. Downloading ARGoS

You can download a binary package of ARGoS from http://bohr.ulb.ac.be/~pincy/argos/download.php. Alternatively, you can download the development sources through git:

$ git clone https://github.com/ilpincy/argos3.git argos3

3. Compiling ARGoS

3.1. Requirements

If you downloaded the sources of ARGoS and want to compile its code, you need:

  • A UNIX system (Linux or MacOSX; Microsoft Windows is not supported)

  • g++ >= 4.3 (on Linux)

  • clang >= 3.1 (on MacOSX)

  • cmake >= 2.6

If you want to compile the simulator, you need:

  • gsl >= 1.15

  • FreeImage >= 3.15

The OpenGL-based graphical visualization is compiled only if the following libraries are found:

  • Qt >= 4.6

  • freeglut >= 2.6.0

  • libxi-dev (on Ubuntu and other Debian-based systems)

  • libxmu-dev (on Ubuntu and other Debian-based systems)

If you want to create the Lua wrapper you need:

  • lua == 5.1

If you want to create the documentation you need:

  • To create the API:

    • Doxygen >= 1.7.3

    • Graphviz/dot >= 2.28

  • To create the HTML version of this README:

    • asciidoc >= 8.6.2

3.1.1. Debian

On Debian, you can install all of the necessary requirements with the following command:

$ sudo apt-get install libgsl0-dev libfreeimage-dev libqt4-dev \
  freeglut3-dev libxi-dev libxmu-dev liblua5.1-dev doxygen \
  graphviz-dev asciidoc

3.1.2. OpenSuse

On openSUSE 12.3, you can install all of the necessary requirements with the following commands:

$ sudo zypper ar -n openSUSE-12.3-Graphics \
  http://download.opensuse.org/repositories/graphics/openSUSE_12.3/ \
  graphics
$ sudo zypper refresh
$ sudo zypper install git cmake gcc gcc-c++ gsl-devel freeimage-devel \
  doxygen graphviz asciidoc lua51-devel libqt4-devel freeglut-devel \
  rpmbuild

3.1.3. Mac OSX

On Mac, you can install all of the necessary requirements using HomeBrew. On the command line, type the following command:

$ brew install pkg-config cmake gsl libpng freeimage lua qt \
  docbook asciidoc graphviz doxygen

3.2. Compiling the code

The compilation of ARGoS is configured through CMake.

3.2.1. Fast compilation instructions

Compiling the ARGoS simulator
$ cd argos3
$ mkdir build_simulator
$ cd build_simulator
$ cmake ../src
$ make
Compiling ARGoS for a robot
$ cd argos3
$ mkdir build_myrobot
$ cd build_myrobot
$ cmake -DARGOS_BUILD_FOR=myrobot ../src
$ make
Compiling the documentation
$ cd argos3
$ cd build_simulator # or 'cd build_myrobot'
$ make doc
ARGoS sources under Eclipse

To use Eclipse with the ARGoS sources, you must have the CDT installed. Optionally, you can also install CMakeEd to modify the CMakeLists.txt files comfortably within Eclipse.

To configure the ARGoS sources for Eclipse, it is better to avoid compiling the code in a separate build directory (for more details, see here). Thus, execute CMake as follows:

$ cd argos3
$ cmake -G "Eclipse CDT4 - Unix Makefiles" src/

Now open Eclipse. Click on File → Import…, select Existing project into workspace, and click on Next. Set the base argos3 directory as the root directory in the dialog that appears. Click on Next and you’re ready to go.

3.2.2. Advanced compilation configuration

The compilation of ARGoS can be configured through a set of CMake options:

Variable Type Meaning [default value]

CMAKE_BUILD_TYPE

STRING

Build type (Debug, Release, etc.) [empty]

CMAKE_INSTALL_PREFIX

STRING

Install prefix (/usr, /usr/local, etc.) [/usr/local]

ARGOS_BUILD_FOR

STRING

Target of compilation (simulator or robot name) [simulator]

ARGOS_BUILD_NATIVE

BOOLEAN

Whether to use platform-specific instructions [OFF]

ARGOS_THREADSAFE_LOG

BOOLEAN

Use or not the thread-safe version of LOG/LOGERR. [ON]

ARGOS_DYNAMIC_LOADING

BOOLEAN

Compile (and use) dynamic loading facilities [ON]

ARGOS_USE_DOUBLE

BOOLEAN

Use double (ON) or float (OFF) [ON]

ARGOS_DOCUMENTATION

BOOLEAN

Create documentation (API, manpage, etc.) [ON]

You can pass the wanted values from the command line. For instance, if you wanted to set explictly all the default values, you would write:

$ cd argos3/build_simulator
$ cmake -DCMAKE_BUILD_TYPE=Debug \
        -DCMAKE_INSTALL_PREFIX=/usr/local \
        -DARGOS_BUILD_FOR=simulator \
        -DARGOS_BUILD_NATIVE=OFF \
        -DARGOS_THREADSAFE_LOG=ON \
        -DARGOS_DYNAMIC_LOADING=ON \
        -DARGOS_USE_DOUBLE=ON \
        -DARGOS_DOCUMENTATION=ON \
        ../src
Important
 When ARGOS_BUILD_FOR is set to simulator, ARGOS_THREADSAFE_LOG and ARGOS_DYNAMIC_LOADING must be ON.
Tip
 For production environments, it is recommended to compile ARGoS with CMAKE_BUILD_TYPE set to Release. If you want to debug ARGoS, it is recommended to set CMAKE_BUILD_TYPE to Debug. The other standard settings (empty and RelWithDebInfo) are supported but should be avoided.
Tip
 If you want to squeeze maximum performance from ARGoS, along with compiling with CMAKE_BUILD_TYPE set to Release, you can also set ARGOS_BUILD_NATIVE to ON. This setting instructs the compiler to use the compiler flags -march=native and -mtune=native. The code will run faster because you use the entire instruction set of your processor, but the generated binaries won’t be portable to computers with different processors.

4. Using the ARGoS simulator from the source tree

Important
 You can’t install ARGoS system-wide and run the source version at the same time. If you intend to run ARGoS from the sources, you must uninstall it from the system.

4.1. Running the ARGoS simulator

If you don’t want to install ARGoS on your system, you can run it from the sources tree. In the directory build_simulator/ you’ll find a bash script called setup_env.sh. Executing this script, you configure the current environment to run ARGoS:

$ cd argos3
$ cd build_simulator
$ . setup_env.sh     # or 'source setup_env.sh'
$ cd core
$ ./argos3 -q all    # this shows all the plugins recognized by ARGoS

If you execute ARGoS with the graphical visualization, you’ll notice that icons and textures are missing. This is normal, as ARGoS by default looks for them in the default install location. To fix this, you need to edit the file $HOME/.config/Iridia-ULB/ARGoS.conf as follows:

[MainWindow]
#
# other stuff
#
icon_dir=/path/to/argos3/src/plugins/simulator/visualizations/qt-opengl/icons/
texture_dir=/path/to/argos3/src/plugins/simulator/visualizations/qt-opengl/textures/
#
# more stuff
#

4.2. Debugging the ARGoS simulator

You can debug the ARGoS code using gdb. Since the code in scattered across multiple directories, you need a .gdbinit file. Luckily for you, this file is created automatically when you compile ARGoS. To use it, you just need to remember to run the ARGoS simulator from the build_simulator/core/ directory:

$ cd argos3/build_simulator/core
$ gdb ./argos3

5. Installing ARGoS from the compiled binaries

To install ARGoS after having compiled the sources, it is enough to write:

$ cd argos3
$ cd build_simulator # or 'cd build_myrobot'
$ make doc           # documentation is required!
$ sudo make install

Alternatively, one can create a package. To build all the packages supported by your system, run these commands:

$ cd argos3
$ git tag -a X.Y.Z-release # give the package a unique version
                           # the format must be as shown
                           # X       = version major
                           # Y       = version minor
                           # Z       = version patch
                           # release = a textual label
$ cd build_simulator       # or 'cd build_myrobot'
$ cmake .                  # let CMake read the newly set tag
$ make doc                 # documentation is required!
$ make                     # compile the code
$ sudo make package        # make the package

This typically creates a self-extracting .tar.gz archive, a .tar.bz2 archive, a .zip archive, and a platform-specific archive (.deb, .rpm, or a MacOSX package). You can determine which packages to create by setting the variables CPACK_BINARY_DEB, CPACK_BINARY_RPM, CPACK_BINARY_STGZ, CPACK_BINARY_TBZ2, CPACK_BINARY_TGZ, CPACK_BINARY_TZ.

Important
 the creation of source packages through the command make package_source is not supported.

An easier option is to install ARGoS from a package distributed at http://bohr.ulb.ac.be/~pincy/argos/download.php.