The ARGoS Website

ARGoS
Large-scale robot simulations

Installation

To install ARGoS, you need a package from the Download page, or you need to compile the sources from GitHub.

For the time being, we tested ARGoS in Ubuntu/KUbuntu (32 and 64 bits), OpenSuse (32 and 64 bits), and MacOSX (10.6 Snow Leopard and newer). Windows is not supported.

Ubuntu and KUbuntu

Download the right package for your architecture and type at the command prompt:

$ sudo dpkg -i argos3_simulator-*.deb

The dependencies should automatically be checked. Optionally, you can install the POV-Ray package to activate the high quality visualization plug-in.

OpenSuse

Download the right package for your architecture and type at the command prompt:

$ sudo rpm -i argos3_simulator-*.rpm

The dependencies should automatically be checked. Optionally, you can install the POV-Ray package to activate the high quality visualization plug-in.

MacOSX

To be able to use ARGoS, you first need to install the latest version of XCode. This is necessary to compile the examples and your future experiments. In addition, for the examples you need to have CMake and GSL. The easiest way is to install them through Homebrew. Install Homebrew, open up a terminal and type:

$ brew install cmake
$ brew install gsl
$ brew install qt

After this, you can install the ARGoS package as any other OSX package.

If you wish to uninstall ARGoS, just type this command in a terminal window:

$ sudo /usr/share/argos3/uninstall_argos.sh

Running ARGoS for the first time

To test your ARGoS installation, you need to download the examples. You’ll find a README file that will guide through the features of ARGoS in a tutorial-like fashion.

To test ARGoS, get the examples, compile them and launch the most basic experiment available, diffusion_1.argos:

$ cd argos3-examples                      # go into example dir
$ mkdir build                             # create build dir
$ cd build                                # go into build dir
$ cmake ..                                # setup compilation
$ make                                    # compile
$ cd ..                                   # get out of build dir
$ argos3 -c experiments/diffusion_1.argos # launch experiment

A man page covering ARGoS' command line options is available:

$ man argos3

Using ARGoS: Basics

ARGoS input

To use ARGoS, you must run the command argos3. This command expects you to provide two kinds of input:

An XML configuration file, typically with extension .argos
User code compiled into one or more libraries

The configuration file contains all the information to set up the arena, the robots, the physics engines, the controllers, etc. User code includes robot controllers and, optionally, hook functions to be executed in various parts of ARGoS to interact with the running experiment.

The experiment configuration file

General structure

This is an example of the skeleton of the ARGoS configuration file:

<?xml version="1.0" ?>
<argos-configuration>
  <framework>
  ...
  </framework>
  <controllers>
  ...
  </controllers>
  <arena size="2, 2, 1">
  ...
  </arena>
  <physics_engines>
  ...
  </physics_engines>
  <media>
  ...
  </media>
  <visualization>
  ...
  </visualization>
  <loop_functions library="/path/to/libmy_loop_functions.so" label="my_loop_functions" />
</argos-configuration>

Each section sets up a specific aspect of the experiment to run:

framework [required]: Sets up internal parameters of ARGoS itself, such as the number of threads to use, the base random seed, the length of the experiment and the length of the integration step.
controllers [required]: Contains the list of user-defined controllers and their configuration.
arena [required]: Contains the list of entities to add to the arena at the beginning of the experiment and their initial positions.
physics_engines [required]: Configures the physics engines to use: which physics engines, how they are connected to each other, etc.
media [required]: Configures the media to use.
visualization [optional]: Contains the visualization set up.
loop_functions [optional]: Contains the configuration of the loop functions.

The framework section

The layout of the framework section is the following:

<framework>
  <system threads="2" method="balance_quantity" />
  <experiment length="60"
              ticks_per_second="10"
              random_seed="124" />
</framework>

The system tag accepts two attributes, both optional: threads and method.

The attribute thread instructs ARGoS on how many threads must be spawned to execute the each simulation step in parallel. If the value is set to zero, or if the attribute is not specified, no threads are spawned and everything is executed by a single thread. The system tag is optional, and when it is not set ARGoS defaults to using no threads.

The attribute method indicates the task assignment method for the threads. Currently ARGoS offers two methods: balance_quantity and balance_length. balance_quantity is the default and it divides the number tasks evenly among the threads. This assignment is precalculated before the execution of the experiment, and it is recalculated only when robots are added or removed from the experiment. This method gives best results when the swarm to simulate is homogeneous. In the second assignment method, balance_length, a thread fetches a new task from the dispatcher every time the thread is idle. This method allows for better intertwining of long and short tasks and gives best results when the swarm is heterogeneous.

The experiment tag is required and contains basic information about the experiment to run. The required length attribute refers to the length of the experiment in seconds. In the above example, the experiment is set to run for 60 seconds. If you set a value of zero the experiment has no time limit, and it ends if you close the graphical window or you set custom ending conditions in the loop functions.

The attribute ticks_per_second is also required and controls how many times per second the simulation step is executed. In the example, the simulation step is executed 10 times per second. Since in the above example the total length of the experiment is set to 60 seconds, the simulator executes 60 x 10 = 600 steps in total. The execution of a simulation step entails the execution of every controller’s CCI_Controller::Step() function. Physics engines can be configured to have a finer granularity— many physics updates can be executed between two simulation steps. You can set the granularity of the physics update in the physics_engines section.

The random_seed attribute, as the name suggests, contains the random seed. It is optional, and if not present (or explicitly set to 0) its value is taken from the internal clock time. Setting the random seed to a specific value is necessary to obtain the same results across many repetitions of the same experiment.

Optionally, ARGoS can collect information about memory and CPU usage. The profiling tag, if present, enables and configures this functionality:

<framework>
  ...
  <profiling file="profile.txt"
             format="human_readable"
             truncate_file="true" />
</framework>

The required file attribute sets the file in which profiling data is written. The required format attribute can take two values: human_readable or table. The human readable format reads as follows:

[profiled portion overall]

Wall clock time: 1.31369e+09
CPU usage: 5.43425e-08%
User time: 0.679896
System time: 0.033994
Maximum resident set size: 34644
Integral shared memory size: 0
Integral unshared data size: 0
Integral unshared stack size: 0
Page reclaims: 8861
Page faults: 3
Swaps: 0
Block input operations: 1216
Block output operations: 0
Messages sent: 0
Messages received: 0
Signals received: 0
Voluntary context switches: 39
Involuntary context switches: 77

[profiled portion start]

User time: 0
System time: 0
Maximum resident set size: 0
Integral shared memory size: 0
Integral unshared data size: 0
Integral unshared stack size: 0
Page reclaims: 0
Page faults: 0
Swaps: 0
Block input operations: 0
Block output operations: 0
Messages sent: 0
Messages received: 0
Signals received: 0
Voluntary context switches: 0
Involuntary context switches: 0

[profiled portion end]

User time: 0.679896
System time: 0.033994
Maximum resident set size: 34644
Integral shared memory size: 0
Integral unshared data size: 0
Integral unshared stack size: 0
Page reclaims: 8861
Page faults: 3
Swaps: 0
Block input operations: 1216
Block output operations: 0
Messages sent: 0
Messages received: 0
Signals received: 0
Voluntary context switches: 39
Involuntary context switches: 77

[process overall]

User time: 0.679896
System time: 0.033994
Maximum resident set size: 34644
Integral shared memory size: 0
Integral unshared data size: 0
Integral unshared stack size: 0
Page reclaims: 8864
Page faults: 3
Swaps: 0
Block input operations: 1216
Block output operations: 8
Messages sent: 0
Messages received: 0
Signals received: 0
Voluntary context switches: 39
Involuntary context switches: 77

[thread #0 overall]

CPU usage: 0%
User time: 0
System time: 0
Maximum resident set size: 34420
Integral shared memory size: 0
Integral unshared data size: 0
Integral unshared stack size: 0
Page reclaims: 8
Page faults: 1
Swaps: 0
Block input operations: 128
Block output operations: 0
Messages sent: 0
Messages received: 0
Signals received: 0
Voluntary context switches: 2
Involuntary context switches: 0

[thread #1 overall]

CPU usage: 0%
User time: 0
System time: 0
Maximum resident set size: 34460
Integral shared memory size: 0
Integral unshared data size: 0
Integral unshared stack size: 0
Page reclaims: 1
Page faults: 0
Swaps: 0
Block input operations: 0
Block output operations: 0
Messages sent: 0
Messages received: 0
Signals received: 0
Voluntary context switches: 4
Involuntary context switches: 0

[thread #2 overall]

CPU usage: 0%
User time: 0
System time: 0
Maximum resident set size: 34464
Integral shared memory size: 0
Integral unshared data size: 0
Integral unshared stack size: 0
Page reclaims: 2
Page faults: 0
Swaps: 0
Block input operations: 0
Block output operations: 0
Messages sent: 0
Messages received: 0
Signals received: 0
Voluntary context switches: 4
Involuntary context switches: 0

[thread #3 overall]

CPU usage: 0%
User time: 0
System time: 0
Maximum resident set size: 34472
Integral shared memory size: 0
Integral unshared data size: 0
Integral unshared stack size: 0
Page reclaims: 2
Page faults: 0
Swaps: 0
Block input operations: 0
Block output operations: 0
Messages sent: 0
Messages received: 0
Signals received: 0
Voluntary context switches: 3
Involuntary context switches: 0

[thread #4 overall]

CPU usage: 0%
User time: 0
System time: 0
Maximum resident set size: 34480
Integral shared memory size: 0
Integral unshared data size: 0
Integral unshared stack size: 0
Page reclaims: 2
Page faults: 0
Swaps: 0
Block input operations: 0
Block output operations: 0
Messages sent: 0
Messages received: 0
Signals received: 0
Voluntary context switches: 3
Involuntary context switches: 1

[thread #5 overall]

CPU usage: 0%
User time: 0
System time: 0
Maximum resident set size: 34488
Integral shared memory size: 0
Integral unshared data size: 0
Integral unshared stack size: 0
Page reclaims: 2
Page faults: 0
Swaps: 0
Block input operations: 0
Block output operations: 0
Messages sent: 0
Messages received: 0
Signals received: 0
Voluntary context switches: 3
Involuntary context switches: 0

[thread #6 overall]

CPU usage: 0%
User time: 0
System time: 0
Maximum resident set size: 34496
Integral shared memory size: 0
Integral unshared data size: 0
Integral unshared stack size: 0
Page reclaims: 1
Page faults: 0
Swaps: 0
Block input operations: 0
Block output operations: 0
Messages sent: 0
Messages received: 0
Signals received: 0
Voluntary context switches: 3
Involuntary context switches: 0

[thread #7 overall]

CPU usage: 0%
User time: 0
System time: 0
Maximum resident set size: 34500
Integral shared memory size: 0
Integral unshared data size: 0
Integral unshared stack size: 0
Page reclaims: 1
Page faults: 0
Swaps: 0
Block input operations: 0
Block output operations: 0
Messages sent: 0
Messages received: 0
Signals received: 0
Voluntary context switches: 4
Involuntary context switches: 0

while the table format looks like this:

ProfPortion 2.35426 137.262 2.76658 0.46493 0 0 0 0 361 0 0 0 0 0 0 0 37427 182
PortionStart 0 0 0.048992 0.013997 0 0 0 0 2210 0 0 0 0 0 0 0 0 3
PortionEnd 0 0 2.81557 0.478927 0 0 0 0 2571 0 0 0 0 0 0 0 37427 185
Overall 0 0 2.81557 0.478927 0 0 0 0 2574 0 0 0 0 0 0 0 37427 185
thread_0 0 6.07313 0.102984 0.039993 0 0 0 0 19 0 0 0 0 0 0 0 3566 0
thread_1 0 4.92644 0.085986 0.029995 0 0 0 0 11 0 0 0 0 0 0 0 1993 0
thread_2 0 7.55959 0.122981 0.054991 0 0 0 0 6 0 0 0 0 0 0 0 3488 0
thread_3 0 5.9457 0.092985 0.046992 0 0 0 0 6 0 0 0 0 0 0 0 3294 13
thread_4 0 5.81831 0.099984 0.036994 0 0 0 0 5 0 0 0 0 0 0 0 3401 82
thread_5 0 6.03065 0.100984 0.040993 0 0 0 0 5 0 0 0 0 0 0 0 3469 3
thread_6 0 6.79514 0.116982 0.042993 0 0 0 0 5 0 0 0 0 0 0 0 3681 13
thread_7 0 5.52102 0.089986 0.039993 0 0 0 0 6 0 0 0 0 0 0 0 3459 29

The table format is meant as easy-to-parse input for scripts and plotting programs.

The truncate_file attribute is optional and can be set to true or false. When it is set to true, the profiling data file is truncated at the beginning of the experiment run or everytime the simulation is reset. When it set to false, the profiling data is appended to the output file. The default value is true.

The controllers section

The controllers section contains a list of robot controllers to use in the experiment. In the following example, two controllers are defined, but the user can define as many controllers as necessary:

<controllers>
 
  <footbot_diffusion_controller id="fdc"
                                library="/path/to/libfootbot_diffusion.so">
    <actuators>
      <differential_steering implementation="default" />
      <footbot_ledsimplementation="default" />
    </actuators>
    <sensors>
      <footbot_proximity implementation="default" show_rays="true" />
    </sensors>
    <params alpha="7.5" delta="0.1" velocity="5" />
  </footbot_diffusion_controller>
 
  <another_controller ...>
    <actuators>
    ...
    </actuators>
    <sensors>
    ...
    </sensors>
    <params ... />
  </another_controller>
 
</controllers>

Each controller is identified by a user-defined tag. In the above example, the tags are footbot_diffusion_controller and another_controller. The tags are registered in the system by the user as part of the actual controller code through the macro REGISTER_CONTROLLER(controller_class_name, "controller_tag").

Each user-defined controller tag must have two attributes: id and library. The id tag identifies a specific configuration of a controller. As it will be explained later, each controller accepts a user-defined XML section called params which allows the user to specify any XML construct to configure the controller at will. The id tag distinguishes different configurations of the same controller type. The second required attribute is library. This attribute contains the full path to the compiled dynamic library that contains the user-defined robot controller code.

Each robot controller interacts with the environment through sensors and actuators. Actuators modify the state of the robot or of the environment, and sensors read such states. A required part of the definition of a controller is the list of sensors and actuators in use and their configuration. This information is contained in the tags actuators and sensors, as shown in the above example. To know which sensors and actuators are available, type:

$ argos3 -q actuators

$ argos3 -q sensors

at the command prompt. Sensors and actuators are plug-ins and multiple implementations of each device are possible. Implementations typically differ in accuracy, computational speed and completeness. To select the implementation you prefer, check the output of the above commands (i.e., the sensor list):

AVAILABLE SENSORS

 ...

 [ footbot_ceiling_camera (rot_z_only) ]
   The foot-bot ceiling camera sensor (optimized for 2D)

 [ footbot_proximity (rot_z_only) ]
   The foot-bot proximity sensor (optimized for 2D)

 [ footbot_proximity (sampled) ]
   The foot-bot proximity sensor (sampling technique)

 ...

Each list item reports the sensor name, the implementation identifier and a brief description of the plug-ins features. As shown, there are two implementations of the foot-bot proximity sensor in the list that differ in the way the readings are calculated. To use them, you can check their XML configuration tags with the following command:

$ argos3 -q footbot_proximity

What just explained for sensors, holds true also for actuators and more in general for each plug-in type available in ARGoS.

The last required section, params, contains user-defined XML tags to configure the controller. It can contain just attributes, as in the shown example, or an actual XML structure. The params section is passed as a parameter to the method CCI_Controller::Init().

The arena section

The arena section is used set up the simulated arena. You can specify which objects populate the arena and how they are distributed in the environment. In the following example, a foot-bot is placed in the middle of an arena bounded by four walls:

<arena size="2, 2, 1" center="0,0,0.5" positional_grid_size="5, 5, 1">
  <box id="wall_north" size="2,0.1,0.5" movable="false">
    <body position="0,1,0" orientation="0,0,0" />
  </box>
  <box id="wall_south" size="2,0.1,0.5" movable="false">
    <body position="0,-1,0" orientation="0,0,0" />
  </box>
  <box id="wall_east" size="0.1,2,0.5" movable="false">
    <body position="1,0,0" orientation="0,0,0" />
  </box>
  <box id="wall_west" size="0.1,2,0.5" movable="false">
    <body position="-1,0,0" orientation="0,0,0" />
  </box>
  <foot-bot id="fb_0">
    <body position="0,0,0" orientation="0,0,0" />
    <controller config="fdc"/>
  </foot-bot>
</arena>

Arena screen shot

Besides placing objects in fixed positions as in the above example, it is also possible to distribute them automatically in various ways. For instance, the following XML statement randomly distributes 10 foot-bots in the arena:

<arena ...>
  ...
  <distribute>
    <position method="uniform" min="-2,-2,0" max="2,2,0" />
    <orientation method="gaussian" mean="0,0,0" std_dev="360,0,0" />
    <entity quantity="10" max_trials="100">
      <foot-bot id="fb">
        <controller config="fdc" />
      </foot-bot>
    </entity>
  </distribute>
</arena>

The distribute tag is composed of three sections: entity, position and orientation. The entity section contains the type of entity to distribute. In the above example, foot-bots are distributed. The quantity attribute specifies how many robots must be distributed. The distribution algorithm first places a robot in the origin, then places it in the target position and checks for collisions. If a collision occurs, that position is discarded and a new one is tried. The max_trials attribute sets the maximum number of placing attemps before giving up with an error. The id specified for the entity type inside the entity section is used as prefix for the added entities. So, in the above example, the 10 foot-bots take as identifiers fb_0, fb_1, …, fb_9. The base_num attribute is optional and sets the base number used for the id of the robots to add. If not set, its default value is 0. If set to a non-zero, positive value, the footbot ids start from that value. For instance, if it is set to 50, the foot-bots take as identifiers fb_50, fb_51, …, fb_59.

The position and orientation section state how positions and orientations are generated for each entity to distribute. The method attribute can currently take one of the following four values:

uniform: This method chooses the values from a uniform distribution. The attributes min and max specify the range from which the values are drawn.
gaussian: This method chooses the values from a gaussian distribution. The mean and standard deviation of the distribution are set by the mean and std_dev attributes, respectively.
constant: This method is used to set the value to a constant. Specify the values attribute to set the values as a triplet x,y,z.
grid: This method is mainly thought to place the robots on a grid. The center attribute specifies the center of the grid; the distances attribute controls the distances on the X,Y,Z axes between the robots; and the layout attribute sets the number of robots per side on the X,Y,Z axes.

Troubleshooting

For bugs or help, leave a message on the forum.

When I run ARGoS, it freezes at start up. The log does not display anything but a line. What’s wrong?

The problem happens when you’re using threads. If a controller or the loop functions have a linking error, the threads hang, and ARGoS goes with them. To fix the problem, disable the threads in the system tag and re-launch ARGoS. Without threads, the linking problem is reported as it should. Fix it, and you’re ready to use threads again.