Simulation of Fairness Incentivization in Autonomous Ecosystems

This is a project with a Python application implementing traffic simulation for the Fairness Incentivization in Autonomous Ecosystems. It is testing a novel token-based monetisation approach that rewards autonomous vehicles for acts of generosity in order to create a more generous and fair ecosystem. This repository is a part of the thesis which aims to validate the solution proposed by this article.

The application uses SUMO simulation tool and its TraCI Python API. Individual simulation files are stored in a standard SUMO simulation format and the created Python application brings additional functionality like support of advanced vehicle metrics and the implementation of the Fairness system.

Dependencies

Python and the SUMO simulation tool needs to be installed to run the simulations. Instruction how to install SUMO can be found here.

Additionally, various python dependencies needs to by installed. The list of all dependencies is stored in the project's requirements.txt file.

All Python dependencies can be installed with the following command:

pip install -r requirements.txt

Project Structure

Project consists of four folders and a python script main.py serving as an starting script.

• core/ folder contains the source code of the implemented Python application.
• simulations/ folder stores all SUMO configurations and multiple Python scripts for running specific simulation. It consists of sub-folders configs/ and scripts/.
  • configs/ folder contains all simulation configuration files
  • scripts/ folder contains Python scripts for starting the simulations. All scripts in the folder contain application main function and inherits from the Simulation class which provides the simulation template. Thanks to this architecture, various different simulations can be created and launched by simply providing their name in a command line argument.
• results/ folder is used to store results of all simulation runs. The runs are grouped by name of simulation, simulation script and timestamp of the run.
• docs/ folder contains documentation of the application source code, that was generated from the documentary comments by pdoc tool. The documentation is in a form of statics HTML files so it can be accessed via web browser.

Simulation Execution

The main.py script in the project root folder is used to launch the simulation with a specified configuration and script files.

It takes name of the simulation stored in simulations/configs/ folder as mandatory launch argument.

Additionally, named parameter --script <name> can be used to select simulation script. If this parameter is not provided simulation will be launched with a default script.

The simulation can be also run in no-GUI mode with the usage of parameter --skip-ui.

The example bellow shows command for running simulation1 with fairness.py script.

python main.py simulation1 --script fairness

The next command shows how to run the same simulation without SUMO GUI.

python main.py simulation1 --script fairness --skip-ui

Custom simulation

To create a new simulation, new sub-folder in simulations/congigs/ folder with SUMO simulation files needs to be created. The simulation netfile needs to be named crossroad.net.xml and simulation configuration file crossroad.sumocfg to be correctly recognized by the application. Other file names are not important.

If simulation contains smart cars with custom logic, car IDs in simulation route file need to start with smart_car prefix. Car starting token balance can be defined by using suffix in format smart_car*_Token_Number. By default, simulation results are grouped by prefixes of vehicle flows names.

To implement custom simulation logic, new python script with main function needs to be created in the simulations/scripts/ folder. This script has to inherit from Simulation class. Script default.py can be used as a template, since it already contains empty simulation with only metrics implemented.

Static checks

To maintain a code quality and make sure, documentation can be generated from the comments, tools black and pylint were used for a static code analysis. These tools were also added to created gitlab pipeline to enforce the code quality before merging.

All static checks can be run with the use of Makefile with command:

make static-checks

Or manually with commands:

black --check .
pylint core/

Documentation can be generated with a make target docs or command:

pdoc --output-dir docs core/