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

AUTHOR: Malik Tremain <maliktremain1@gmail.com>
DATE: 04/08/2023

*** INTRODUCTION ***

This is an extension to Carlo Pinciroli's argos3-examples repo(https://github.com/ilpincy/argos3-examples).

This repo contains an example of aggregation implamented from Schmickl T, Möslinger C, Crailsheim K 2007 Collective perception in a robot swarm. Swarm Robotics, (Springer, Berlin) pp.144–157.

The main branch will contain an faithful implamentation of the described algorithm where every robot will be initalized with a hop count equal to the maximum hop count
and there will be zones spawed in to act as targets, whereas the alternate_aggregation branch will have a slightly different version where fb0 will be initalized to have
a hop count of 0 which will not change and then fb0 will be the target. 

This repo also features some python scripts which can be used to generate xmls, run multiple "headless" instances of argos3 to generate CSV files and to then plot
the results from those CSV files. 

For any of the python scripts in this project, you should only need to change the values of the constants in order to get them to run as you would like.

The "automation.py" script can be used to generate and run experiments based on the values of some constants set within the file. All of the xml and CSV files
generated by this script will be saved into the "alt_xmls" directory. If run with the "--xml-only" argument then it will only generate the xml files without running them.
On the "alternate_aggregation" branch only, this script can accept 8 arguments to specify a few of the settings. When using this script, it is important to update
the path stored by "PATH_TO_WORKING_DIR" constant. 

The "plotting.py" script can be used to plot a graph based on the results stored in the .csv files. If run with the "--nocontext" flag it will generate the graphs without the 
text describing the current experiment's settings.

The "archiever.py" script(alternate_aggregation branch only) can be used to automate the process of varying the constants of "automation.py", running the script, plotting
the results and then compressing the final xmls, CSVs and the graph into a tar.gz file.


*** COMPILATION ***

In principle, you can compile your code however you want. In practice,
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.



*** TROUBLESHOOTING ***

When you launch one of the two 'cmake' commands, you might get an
error like 'package argos3_simulator' not found. This error has two
possible causes:

1. You haven't installed ARGoS3 system-wide. To fix this, install
   ARGoS3 through the packages or with the command 'sudo make install'
   in the ARGoS3 build directory.

2. You have installed ARGoS in a non-standard location. The standard
   locations are /usr and /usr/local. If you did not install ARGoS
   there, CMake won't be able to find the file ARGoSConfig.cmake at
   PREFIX/share/argos3/cmake. The solution in this case is to run
   
   $ cmake -DCMAKE_MODULE_PATH=/path/to/argos3/share/cmake
   
   Make sure that the folder /path/to/argos3/share/cmake contains the
   file ARGoSConfig.cmake.



*** 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:

$ argos3 -c experiments/aggregation_one.argos

To run an examperiment without visulisation, you can add a "-z" flag like so:

$ argos3 -c experiments/aggregation_one.argos -z