A Simulation Toolkit for Evaluating Human-Robot Collaboration in Emergency Evacuations

This project is a Docker-based application that facilitates experimentation with the IMPACT+ agent-based evacuation simulation model. Developed with NetLogo,IMPACT+ is an extension of IMPACT, which simulates an evacuation from a transport hub and incorporates sociocultural, cognitive, and emotional factors.

The key addition of IMPACT+ is the introduction of an adaptable search and rescue (SAR) robot that is able to decide, when it finds a fallen victim, whether to ask help from a nearby zero-responder (another passenger) or from a first-responder (member of staff). The SAR robot bases its decision on the zero-responders' social identity, ie. the likelihood that they will accept to offer help. Assuming that first-responders are scarce, getting help from a zero-responder can lead to faster evacuation times.

This tool aims to make it easier for researchers to configure, run and analyse simulations with various evacuation scenarios and adaptation strategies for the SAR robot. See demonstration video showing installation and usage. Find accompanying paper here.

Video of an evacuation scenario simulation

Table of contents

• Installation
• Usage
  • Results
  • Examples
• Configuration
  • Basic
  • Scenario
  • Combinations
  • Rooms
• Strategies
  • Creating New Strategies
• Modules
• Help
• License

Installation (~10 minutes)

To use this tool, you'll need to have Docker installed on your machine.
Follow the instructions on the Get Docker | Docker Docs website to install Docker.

Usage

To start the application, ensure that you are at the parent directory and run:

./run-container.sh

NOTE: Make sure you use the chmod +x command to add execute permissions to the file and avoid the "permission denied" error.

NOTE: Make sure docker engine is running

If you downloaded the image from Docker Hub instead of building it locally, add hub after the script name. For example:

./run-container.sh hub

To only analyse the results of an experiment saved in a folder use:

./run-container.sh [hub] --analyse FOLDER

Replace FOLDER with the folder name, located in the results directory.

If you modify any part of the code you might need to rebuild the docker image before running it, run:

./build-docker-image.sh

or just run:

./build-and-run.sh

The application will set up the simulations based on the configurations provided and then begin running the simulations in parallel. A progress bar will display the status and an estimate time to complete all simulations. Depending on the number of simulations, parameter values and hardware resources available, the simulations may take significant amount of time to complete. Running 100 simulations with the default configuration on a 14-cores CPU should take less than 5 minutes to complete.

Results

The application generates a results folder in the workspace directory, to store the output of the simulations. Each experiment's results are stored in a subfolder named using a timestamp. This subfolder contains the following:

1. Data Folder: Contains CSV files with detailed results and metrics:

   • experiment_data.csv: Contains all the results and information for each simulation.
   • scenario_metrics.csv: Contains the metrics for each scenario.
   • scenario_processed_data.csv: Contains the evacuation time per scenario.
   • strategy_metrics.csv: Contains the metrics for each strategy.
   • strategy_processed_data.csv: Contains the evacuation time per strategy.

2. Img Folder: Contains various plots:

   • Violin plots for each scenario.
   • Violin plots for each strategy.
   • Robots actions plot.
   • Plots for each pair of parameter combinations against the evacuation time.

3. Video Folder: Contains any videos created during the simulations.

4. Config File: config.json contains the configurations used to create the experiment.

5. Hypothesis Test File: hypothesis_test.txt contains the results of the statistical analysis.

if you need to delete all the results folders run:

./clear-results.sh

Examples

The examples folder contains several example simulation experiments that demonstrate the capabilities of the tool.

Configuration Options

The config.json contains parameters that can be adjusted to configure the simulations.

Basic Parameters

Scenario Parameters

The scenarioParams section contains global parameters that are used for all simulations. These parameters can be overridden by specifying the same parameter in the simulationScenarios section.

    "scenarioParams": {
        "seed": 42,
        "netlogo_seed": null,
        "numOfSamples": 10,
        "numOfRobots": 1,
        "numOfPassengers": 800,
        "numOfStaff" : 10,
        "fallLength": 500,
        "fallChance": 0.05,
        "robotPersuasionFactor": 1,
        "maxNetlogoTicks": 2000,
        "roomType": 8,
        "enableVideo": 1
    },

    "simulationScenarios" : [
        {
            "name": "no-support",
            "description": "There are no SAR robots in the simulation.",
            "numOfRobots": 0,
            "enabled": true
        },
    ]

Combining Parameters

The application has the ability to use lists and ranges to create combinations of parameters. It will automatically generate all possible combinations of the provided parameters and run num_of_samples simulations for each combination.

For example, given the following configuration:

"numOfStaff": [2, 10],

"fallChance": {
    "start": 0.05,
    "end": 1,
    "step": 0.1
},
"num_of_samples": 5

The program will create combinations of numOfStaff and fallChance values, and for each combination, it will run 5 simulations.

• numOfStaff = 2 and fallChance = 0.05
• numOfStaff = 2 and fallChance = 0.15
• ...
• numOfStaff = 10 and fallChance = 0.95

For each of these combinations, the program will run the specified number of simulations (num_of_samples). For each combination pair, a plot will be generated comparing the impact on evacuation time.

Room Types

There are 8 different room types that the evacuation simulation can use. The PNGs for the rooms are located in workspace/netlogo/rooms

Strategies

The application includes basic predefined strategies for the SAR robot. Each strategy defines the robot's action when encountering a fallen victim:

• RandomStrategy.py: Randomly chooses between asking for help from a passenger or calling for staff assistance.
• HelpMatrixStrategy.py: A baseline strategy, uses the help matrix from the IMPACT+ model to predict if a zero responder will accept to offer help.
• AlwaysCallStaffStrategy.py: Always calls for a staff member to assist the victim.
• AlwaysAskHelpStrategy.py: Always asks for help from a passenger.

Each strategy is defined in a python file saved in the strategies folder and inherits from the AdaptationStrategy base class in adaptation_strategy.py file.

Creating New Strategies

To create a new strategy, follow these steps:

1. Create a New Python File: In the strategies folder, create a new Python file. The name of the file (minus the .py extension) will be the name of the strategy. For example, if you want to create a strategy named NewStrategy, create a file named NewStrategy.py in the strategies folder.

2. Import the Base Class: In your new strategy file, import the AdaptationStrategy base class from adaptation_strategy.py.

   from src.adaptation_strategy import AdaptationStrategy, Survivor

3. Define the Strategy Class: Create a new class with exactly the same name as the strategy and file name. This class should inherit from AdaptationStrategy.

   class NewStrategy(AdaptationStrategy):
   def get_robot_action(self,
                        simulation_id: str,
                        candidate_helper: Survivor,
                        victim: Survivor,
                        helper_victim_distance: float,
                        first_responder_victim_distance: float) -> str:
       # Implement the logic for the strategy here
       pass

4. Implement the get_robot_action Method: The get_robot_action method should contain the logic for how the robots will behave during the evacuation. This method will be called each time the robot encounters a fallen victim and must decide between asking for help from a nearby zero responder or a member of staff.

   def get_robot_action(self,
                    simulation_id: str,
                    candidate_helper: Survivor,
                    victim: Survivor,
                    helper_victim_distance: float,
                    first_responder_victim_distance: float) -> str:
   # Example logic for the new strategy
   if helper_victim_distance < first_responder_victim_distance:
       return self.ASK_FOR_HELP_ROBOT_ACTION
   else:
       return self.CALL_STAFF_ROBOT_ACTION

5. Using the Strategy: To use a strategy, simply specify the name of the strategy in the adaptationStrategy field of a scenario in the config.json file:

   {
   "name": "new-strategy",
   "description": "A new Strategy.",
   "adaptationStrategy": "NewStrategy",
   "enabled": true
   }

Modules

An overview of the main modules.

• simulation.py: Defines the classes and functions necessary for executing the NetLogo model simulations.
• simulation_manager.py: Manages the parallel execution of simulations in NetLogo.
• server.py: A simple flask server, used to communicate with the NetLogo simulations.
• results_analysis.py: Responsible for analysing and plotting the results of the simulation experiments.
• load_config.py: Responsible for loading and checking the JSON configuration file.
• batch_run.py: Contains methods to run a scenario using a different combination of parameters.
• adaptation_strategy.py: Contains the base class for adaptation strategies, which are used in the simulation to determine the robot's actions.

Help

Feel free to open an issue if something is not working as expected.

License Information

This project is licensed under the terms of the MIT license. Please refer to LICENSE for the full terms.

As with all Docker images, these may contain other software which may be under other licenses (such as Bash, etc. from the base distribution, along with any direct or indirect dependencies of the primary software being contained). It is the image user’s responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.