Workflow

SCRIMMAGE ships with a number of tools to help you simulate, playback, and analyze simulation results. The following is a description of SCRIMMAGE’s tools and how they may be used in a typical workflow:

Note

If scrimmage is not installed on your system, please navigate to Installation. If you don’t know if scrimmage is installed, enter the following command into a terminal:

$ scrimmage

If you receive the message, scrimmage: command not found, you will have to install scrimmage.

• scrimmage : The main work horse of scrimmage. Simulates scrimmage missions. Example usage:

  $ scrimmage ~/scrimmage/scrimmage/missions/straight.xml
  

• scrimmage-playback : Used to replay scrimmage simulations from saved Protocol Buffer binary files. Every time a simulation is executed, a time-stamped directory is created in the log_dir location (defined in the mission file. This is ~/.scrimmage/logs by default). The time-stamped directory contains a .bin file, which contains the trajectories of all entities, a log.txt file, which contains the number that was used to seed scrimmage’s random number generator, and a mission.xml file, which contains an exact copy of the mission used to run the simulation. Usage:

  $ scrimmage-playback ~/.scrimmage/logs/2016-11-01_14-53-27
  

• ./scripts/plot_3d_fr.py : Used to plot the recorded trajectories of the entities. The resulting plot can be difficult to visualize if the simulation contained a large number of aircraft. This plot is typically used for reports and testing low-level controllers. Example usage:

  $ cd /path/to/scrimmage/scripts
  $ ./plot_3d_fr.py ~/swarm-log/2017-07-20_15-37-25/frames.bin
  $ ./plot_3d_fr.py ~/swarm-log/2017-07-20_15-37-25/frames.bin --2d  # 2D mode
  

• aggregate-runs : The aggregate-runs tool can be executed on a directory containing many runs in order to calculate the number of wins for each team. The aggregate-runs program creates text files at ~/.scrimmage/logs/aggregate/wins that specify the scenarios in which each team won. Example usage:

  $ aggregate-runs -d ~/.scrimmage/logs
  

• filter-runsReads the generated text files and allows for easy playback

  of each type of scenario:

  $ filter-runs ~/.scrimmage/logs
  

  Running filter-runs will print output similar to the following:

  ====================================================
  Choose an outcome number:
  ----------------------------------------------------
  Number             Name            Win Count
  ----------------------------------------------------
  [0]                draw            1
  [1]                team_1          7
  [2]                team_2          3
  >>
  

  To view the simulation runs where team_1 was the winner, type the number 1, hit enter, and follow the remaing prompts to step through the playback of each simulation.

• scrimmage-plugin : Display information about a plugin. This program can help you debug the location of SCRIMMAGE plugins. Provide this program with a plugin name. For example:

  $ scrimmage-plugin Straight
  

  will produce something like the following:

  ==========================================
  Plugin found.
  Name: Straight
  File: /home/myuser/scrimmage/scrimmage/include/scrimmage/plugins/autonomy/Straight/Straight.xml
  Library: Straight_plugin
  -------------------------
  Params: XML_DIR=/home/myuser/scrimmage/scrimmage/include/scrimmage/plugins/autonomy/Straight/
  library=Straight_plugin
  save_camera_images=false
  show_camera_images=true
  speed=21