MASPlanes

MASPlanes is a very simple UAV simulator, desgined to aid in the development and testing of UAV coordination mechanisms. The goal of the simulator is to acquire and report statistics about the time it taskes for the UAVs to service a number of requests. This time will vary depending on the strategy used by the planes, hence empirically showing which algorithm performs best on a given scenario.

A high level description of the simulator, the problem it is trying to solve and the included features can be found at

• Marc Pujol-Gonzalez, Jesus Cerquides, and Pedro Meseguer. MASPlanes: A multi-agent simulation environment to investigate decentralised coordination for teams of UAVs (demonstration). In The 13th International Conference on Autonomous Agents and Multiagent Systems, pages 1695-1696. International Foundation for Autonomous Agents and Multiagent Systems, 2014.

There is also a 5 minute MASPlanes introductory video at youtube.

Requirements

MASPlanes is developed in java 1.6, and it should run on any of the major platforms. You need the following dependencies to compile and run the project:

• Java SDK 1.6 or greater.
• Maven 2.0 or greater. Get it from your package manager or the maven download page.

All java libraries required by the simulator will be automatically downloaded when you first compile the package using maven as explained next.

Development

MASPlanes is under heavy development. Thus, there are no binary releases of the software. However, executable scripts can be generated by running the maven package target:

cd /path/to/project
mvn package

This command will create a bin folder containing script files to launch the programs, a repo folder containing the compiled program's classes and the required libs, and a target folder containing maven-related things you can safely ignore.

In the remainder of this guide we assume that you are using a UNIX-like system. If you are on windows, replace the sh bin/program part at the beggining of the execution commands by bin/program.bat.

Usage

In order to test the algorithm's behavior in a particular scenario, the said scenario must be first generated. This is, MASPlanes does not randomly generate scenarios when running. Instead, it includes a scenario generator that produces scenario descriptions. These descriptions can be saved to a file and then "solved" by MASPlanes using any of the implemented strategies. You can get started quickly by using the example problems found in the scenarios folder.

Simulator

Once you have an example problem, the simulator can "solve" it using any of the inbuilt UAV coordination algorithms. For instance, to solve the problem scenarios/short-hotspots.json, you can execute the following command:

sh bin/simulator -g scenarios/short-hotspots.json

The -g option here tells the simulator to display a GUI of the simulation (see below for more details about the GUI interface). If you remove it, the simulator will run in CLI mode, displaying just the progress of the simulation. This progress can also be disabled to run "batch" simulations by using the -q option. To see all available options, call the simulator without specifying any scenario to simulate:

sh bin/simulator
usage: planes [options] <problem>
  -d,--dump-settings     dump the default settings to standard output. This
                         can be used to prepare a settings file.
  -h,--help              show this help message.
  -o <setting=value>     override "setting" with "value".
  -q,--quiet             disable all output except for results and errors.
  -s,--settings <file>   Load settings from <file>.
  -t,--dry-run           Output only the resolved settings, but do not run
                         the simulation.

There are many parts of the simulator that can be customized for each run. These settings include from the mechanism used by the planes to coordinate betweem themselves (the algorithms we are testing!), to how the operator(s) choose to which plane to submit each task.

To simplify the execution of many runs with similar configurations, the simulator allows you to specify a settings file using the command line. That is, you can instruct the simulator to use the settings described by <file> by running it with a special parameter:

sh bin/simulator problem -s <file>

or the longer form:

sh bin/simulator problem --settings <file>

To learn about all available settings and prepare your own settings file, the simulator includes a special "dump" option. Using this option, you can dump the default settings (including their description) to a file. Later on, you just have to specify that settings file when solving the instances:

sh bin/simulator -d > custom.settings
sh bin/simulator problem --setings=custom.settings

Customizing a settings file is very useful when running batches of simulations. However, when trying things out you may want to override a setting without having to modify it in the settings file (or without having to create a settings file at all). In this situations, you can override a default setting by specifying it directly in the command line. For instance, you could change the operator's strategy by running the simulator as follows:

sh bin/simulator problem -o operator-strategy=nearest

Graphical User Interface

The simulator includes a simple GUI to visualize what is happening in the simulation while it runs. The GUI has three distinct sections, as shown in this figure:

First, there is a top bar that contains a few controls:

• The Tasks button toggles the displaying of all tasks (past, present and future) in the simulation area. This is useful to quickly see how the tasks are spatially distributed in this scenario.
• The Speed slider controls how fast to run the simulation. Setting it all the way to the left makes the simulation run at 1 tenth of a second of simulated time per second of real time. The maximum speed is capped by the maximum processing capability of your machine.
• The Time label shows the current simulation time in tenths of seconds.

Second, there is a bottom bar that displays some time-related information about tasks. The whole bar is actually a histogram displaying how many tasks are introduced at each point in time. Moreover, the histogram's bars are colored according to which crisis period introduces those tasks. For example, the leftmost (purple) peakshows that there is a crisis period at the beginning of the simulation. Additionally, it shows that tasks from this crisis are gaussian distributed along a short time period. The strong blue vertical line is not related to the tasks. Instead, it marks the current point in time.

Third, there is the simulator's main display area, that depicts the simulated world. In this area you can see the planes moving as they try to service tasks. Each plane is painted in a different color, and surrounded by a circle that represents its communication range. Likewise, the light blue circular area in the lower-center of the display represents the range of an operator, depicted here as a big strong blue dot. Tasks are repented as smaller dots, painted in the same color than the plane that currently owns them.

By default, the display shows the complete plan (sequence of requests to service) of each plane, provided that the coordination algorithm computes such plan. When the algorithm does not compute the full plan, only the next task to be serviced is shown for each plane. The plans are visualized by connecting the plane to its next request, then that request to the next one, and so on and so forth.

Additionally, you can click on any plane to focus on that plane. When a plane is focused, all other planes and their tasks are painted grey, so that your focused plane stands out of the rest. Additionally, you can no longer see the full plans of other planes. Instead, you can see the focused plane's plan as well as a trail of the last tasks it has serviced. When in focused mode, click any empty space of the display to go back to the normal mode.

Generator

At some point, you probably want to generate customized problems that represent different scenarios. With MASPlanes, you can generate such problems using the included problem generator:

cd /path/to/project
sh bin/generator problem

This command generates an example scenario using defaults for all settings, and saves it to a file named problem. You can obtain a commented copy of all the generator's settings by dumping the default generator configuration to a file:

sh bin/generator  -d > generator.settings

This will create a text file generator.settings containing all the default settings plus a small explanation of their effects. At this point, you can edit any setting in the file using a text editor. Thereafter, you can generate scenarios using these custom settings by telling the generator to employ the (modified) settings file:

sh bin/generator -s generator.settings problem

Contact

If you have any questions, problems or suggestions, please contact us at marc.iiia@la3.org.