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.
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.
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.
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
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
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.
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:
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 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
or
$ 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 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>
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:
For bugs or help, leave a message on the forum.
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.