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.
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.6or greater.Maven 2.0or 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.
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.
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.
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
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.
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
If you have any questions, problems or suggestions, please contact us at [email protected].