# PlaFoSim - A simple and scalable simulator for platoon formation
[](CHANGELOG.md)
[](https://pypi.org/project/plafosim/)
[](https://pypi.org/project/plafosim/)
[](LICENSE)
[](http://dx.doi.org/10.1109/VNC52810.2021.9644678)
<img align="right" width="100" height="100" src="docs/logo.png" alt="PlaFoSim's logo">
"Platoon Formation Simulator", or "PlaFoSim" for short, is an open source simulator for platoon formation, aiming for simplicity, flexibility, and scalability.
PlaFoSim aims to facilitate and accelerate the research of platoon maneuvers and formation for individually driven vehicles.
While the main focus of the simulator is on the assignment process, simulation of advertisements and maneuvers is implemented in a more abstract way.
PlaFoSim has been published at [IEEE VNC 2021](https://www.tkn.tu-berlin.de/bib/heinovski2021scalable/):
> Julian Heinovski, Dominik S. Buse and Falko Dressler, "Scalable Simulation of Platoon Formation Maneuvers with PlaFoSim," Proceedings of 13th IEEE Vehicular Networking Conference (VNC 2021), Poster Session, Virtual Conference, November 2021, pp. 137–138.
**NOTE**: This project is under active development.
---
## Installation
- Install Python (>=3.7,<=3.9)
- Install PlaFoSim from [pypi](https://pypi.org/project/plafosim/):
```pip install plafosim```
**NOTE**: The project is developed and tested only on Linux.
## Running a Simulation
**NOTE**: Since PlaFoSim is a command-line interface (CLI) application, running PlaFoSim requires using a shell.
### Quickstart
Run PlaFoSim with:
```plafosim```
You can use PlaFoSim's help to get a list of available parameters:
```plafosim -h, --help```
Or, run a simulation with the default configuration (`-d`):
```plafosim -d```
### Live GUI
You can visualize the simulation via a simple live GUI based on [sumo-gui](https://sumo.dlr.de/docs/sumo-gui.html), using the argument `gui`:
```plafosim --gui```
*A screenshot of PlaFoSim's live GUI showing 2 platoons and various individual vehicles. Copyright © 2021 IEEE.*
More options for the live GUI can be found within the ``GUI properties`` section of the help.
**NOTE**: This requires installation of [SUMO](https://sumo.dlr.de/) (>=1.6.0) and declaration of the `SUMO_HOME` variable (see [documentation](https://sumo.dlr.de/docs/Installing/Linux_Build.html#definition_of_sumo_home)).
### Advanced Simulation Control
You can use a variety of different parameters to customize the scenario and the simulation itself.
E.g., use the parameter `vehicles` to configure the number of vehicles in the simulation:
```plafosim --vehicles 1000```
The available parameters are grouped into different categories:
```
- road network properties
- vehicle properties
- trip properties
- communication properties
- platoon properties
- formation properties
- infrastructure properties
- simulation properties
- GUI properties
- result recording properties
```
You can find a list of available parameters for each category in the help:
```plafosim -h, --help```
#### Examples
```
# Configure a 100km freeway with ramps at every 10km
plafosim --road-length 100 --ramp-interval 10
# Configure random (normally distributed) desired driving speed of 130km/h
plafosim --random-desired-speed true --desired-speed 36
# Configure random trips for 500 vehicles
plafosim --vehicles 500 --random-depart-position true --random-arrival-position true --depart-desired true
# Pre fill the freeway with 1000 vehicles
plafosim --vehicles 1000 --pre-fill true
# Configure 50% of the vehicles with Advanced Cruise Control (ACC) and a headway time of 1.5s
plafosim --penetration 0.5 --acc-headway-time 1.5
# Enable a simple, distributed platoon formation algorithm [1] in order to form platoons every 30s
plafosim --formation-algorithm SpeedPosition --formation-strategy distributed --execution-interval 30
```
### Faster Simulation
You can speed up the simulation performance by enabling Python's optimization ```PYTHONOPTIMIZE```, e.g., in order to disable assertions:
```PYTHONOPTIMIZE=1 plafosim```
See the Python [documention](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONOPTIMIZE) for more details.
## Re-Playing a Simulation
The simulation can write a trace file including the mobility details of every simulated vehicle (default `results_vehicle_traces.csv`).
You can replay the simulation in the GUI (see above) based on the trace file by using the corresponding binary:
```plafosim-replay results_vehicle_traces.csv```
To see all options of this script, run:
```plafosim-replay -h, --help```
**NOTE**: This requires installation of SUMO (>=1.6.0) and declaration of the `SUMO_HOME` variable.
## Recording of Screenshots and Video from a Simulation
PlaFoSim offers functionality to automatically record a screenshot of the GUI in every simulation step with
```plafosim --gui --screenshot-file screenshot```
These screenshots can be used to create a video by using an integrated script based on [ffmpeg](https://ffmpeg.org/):
```plafosim-img2video 'screenshot_*.png' video.mp4```
**NOTE**: This requires installation of ffmpeg.
## Documentation
Documentation is available via this README and via the [official documentation](https://plafosim.readthedocs.io/).
## Extending PlaFoSim
You can extend and customize PlaFoSim flexibly by modifying its source code.
For this, you first need ot install it from source.
### Installing from Source
- Install [poetry](https://python-poetry.org/):
```pip install poetry```
- Clone this repository:
```git clone https://github.com/heinovski/plafosim.git```
- Navigate to newly created directory of the cloned repository in the command-line
- Install PlaFoSim from source in editable mode:
```poetry install```
- Run PlaFoSim in the virtual environment:
```poetry run plafosim```
You can also activate the virtual enviroment first with ```poetry shell``` and run the commands as usual (see above).
### Adding a new Formation Algorithm
In order to add a new formation algorithm, you need to follow these steps:
- Create a new sub-class of `FormationAlgorithm` (see `formation_algorithm.py`) within the sub-directory `algorithms`.
You can use the `Dummy` algorithm (see `algorithms/dummy.py`) as an example.
- Add specific arguments for your algorithm to the argument parser group within the new sub-class if necessary.
You should now be able to use your new algorithm with
```
plafosim --formation-algorithm dummy_algorithm_name
```
## Contributing to the Project
In order to contribute, please follow these steps:
- Install PlaFoSim from source (see [Extending PlaFoSim](.#extending-plafosim))
- Make desired changes and adjust the documentation if required
- Run the tests located in `tests` as well as the validation scripts located in `scripts` (see `.drone.yml` for details)
- Submit a Pull Request (PR)
### Documenting
When making changes to the code, make sure to add or adjust corresponding documentation in form of python docstrings.
Those should use the Numpy docstring format for Sphinx and follow the [style guide](https://numpydoc.readthedocs.io/en/latest/format.html) by numpydoc to ensure consistency and compatibility.
See also the [style guide](https://pandas.pydata.org/docs/development/contributing_docstring.html) by pandas.
You can build the documentation using Sphinx `make -C docs`.
### Testing
When adding methods and functions, make sure to add corresponding unit tests for `py.test`.
The tests are located under `tests` and can be executed with `./scripts/run-pytest.sh`.
This will also generate a test coverage report.
### Validation
To validate the behavior of PlaFoSim, it is compared to SUMO 1.6.0 by means of simulation results (e.g., vehicle traces).
The corresponding scripts are located under `scripts` and executed withn CI/CD pipelines.
You can have a look at `.drone.yml` for details regarding the execution.
### Profiling
You can profile the runtime of PlaFoSim's code by using [cProfile](https://docs.python.org/3/library/profile.html#module-cProfile):
```poetry run python -m cProfile -o profile.out -m plafosim.cli.plafosim```
You can visualize the results of the profiling run by using [SnakeViz](https://jiffyclub.github.io/snakeviz/):
```snakeviz profile.out```
## Contributors & Citing
PlaFoSim was originally designed and built by [Julian Heinovski](https://github.com/heinovski/) with the help of [Dominik S. Buse](https://github.com/dbuse/).
It is currently maintained by [Julian Heinovski](https://github.com/heinovski/).
The list of all authors can be found [here](AUTHORS.md).
If you are working with `PlaFoSim`, we would appreciate a citation of [our paper](https://www.tkn.tu-berlin.de/bib/heinovski2021scalable/):
> Julian Heinovski, Dominik S. Buse and Falko Dressler, "Scalable Simulation of Platoon Formation Maneuvers with PlaFoSim," Proceedings of 13th IEEE Vehicular Networking Conference (VNC 2021), Poster Session, Virtual Conference, November 2021, pp. 137–138.
```bibtex
@inproceedings{heinovski2021scalable,
author = {Heinovski, Julian and Buse, Dominik S. and Dressler, Falko},
doi = {10.1109/VNC52810.2021.9644678},
title = {{Scalable Simulation of Platoon Formation Maneuvers with PlaFoSim}},
pages = {137--138},
publisher = {IEEE},
issn = {2157-9865},
isbn = {978-1-66544-450-7},
address = {Virtual Conference},
booktitle = {13th IEEE Vehicular Networking Conference (VNC 2021), Poster Session},
month = {11},
year = {2021},
}
```
## License
PlaFoSim is licensed under the terms of the GNU General Public License 3.0 or later.
```
# Copyright (c) 2020-2024 Julian Heinovski <heinovski@ccs-labs.org>
#
# SPDX-License-Identifier: GPL-3.0-or-later
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <https://www.gnu.org/licenses/>.
```
Raw data
{
"_id": null,
"home_page": "https://www.plafosim.de",
"name": "plafosim",
"maintainer": "Julian Heinovski",
"docs_url": null,
"requires_python": ">=3.7,<3.10",
"maintainer_email": "heinovski@ccs-labs.org",
"keywords": "Algorithm,Engineering,Experiment,Platoon,Platoon Formation,Platooning,Platoon Maneuver,Research,Science,Simulation,Simulator",
"author": "Julian Heinovski",
"author_email": "heinovski@ccs-labs.org",
"download_url": "https://files.pythonhosted.org/packages/e7/ff/e4644a569288d83e1b3c8d47cc55101b9b053efe177eb440130f998f5589/plafosim-0.17.3.tar.gz",
"platform": null,
"description": "# PlaFoSim - A simple and scalable simulator for platoon formation\n[](CHANGELOG.md)\n[](https://pypi.org/project/plafosim/)\n[](https://pypi.org/project/plafosim/)\n[](LICENSE)\n[](http://dx.doi.org/10.1109/VNC52810.2021.9644678)\n\n<img align=\"right\" width=\"100\" height=\"100\" src=\"docs/logo.png\" alt=\"PlaFoSim's logo\">\n\"Platoon Formation Simulator\", or \"PlaFoSim\" for short, is an open source simulator for platoon formation, aiming for simplicity, flexibility, and scalability.\nPlaFoSim aims to facilitate and accelerate the research of platoon maneuvers and formation for individually driven vehicles.\nWhile the main focus of the simulator is on the assignment process, simulation of advertisements and maneuvers is implemented in a more abstract way.\n\nPlaFoSim has been published at [IEEE VNC 2021](https://www.tkn.tu-berlin.de/bib/heinovski2021scalable/):\n\n> Julian Heinovski, Dominik S. Buse and Falko Dressler, \"Scalable Simulation of Platoon Formation Maneuvers with PlaFoSim,\" Proceedings of 13th IEEE Vehicular Networking Conference (VNC 2021), Poster Session, Virtual Conference, November 2021, pp. 137\u2013138.\n\n**NOTE**: This project is under active development.\n\n---\n\n## Installation\n\n- Install Python (>=3.7,<=3.9)\n- Install PlaFoSim from [pypi](https://pypi.org/project/plafosim/):\n```pip install plafosim```\n\n**NOTE**: The project is developed and tested only on Linux.\n\n## Running a Simulation\n\n**NOTE**: Since PlaFoSim is a command-line interface (CLI) application, running PlaFoSim requires using a shell.\n\n### Quickstart\n\nRun PlaFoSim with:\n\n```plafosim```\n\nYou can use PlaFoSim's help to get a list of available parameters:\n\n```plafosim -h, --help```\n\nOr, run a simulation with the default configuration (`-d`):\n\n```plafosim -d```\n\n### Live GUI\n\nYou can visualize the simulation via a simple live GUI based on [sumo-gui](https://sumo.dlr.de/docs/sumo-gui.html), using the argument `gui`:\n\n```plafosim --gui```\n\n\n*A screenshot of PlaFoSim's live GUI showing 2 platoons and various individual vehicles. Copyright \u00a9 2021 IEEE.*\n\nMore options for the live GUI can be found within the ``GUI properties`` section of the help.\n\n**NOTE**: This requires installation of [SUMO](https://sumo.dlr.de/) (>=1.6.0) and declaration of the `SUMO_HOME` variable (see [documentation](https://sumo.dlr.de/docs/Installing/Linux_Build.html#definition_of_sumo_home)).\n\n### Advanced Simulation Control\n\nYou can use a variety of different parameters to customize the scenario and the simulation itself.\nE.g., use the parameter `vehicles` to configure the number of vehicles in the simulation:\n\n```plafosim --vehicles 1000```\n\nThe available parameters are grouped into different categories:\n\n```\n- road network properties\n- vehicle properties\n- trip properties\n- communication properties\n- platoon properties\n- formation properties\n- infrastructure properties\n- simulation properties\n- GUI properties\n- result recording properties\n```\n\nYou can find a list of available parameters for each category in the help:\n\n```plafosim -h, --help```\n\n#### Examples\n\n```\n# Configure a 100km freeway with ramps at every 10km\nplafosim --road-length 100 --ramp-interval 10\n\n# Configure random (normally distributed) desired driving speed of 130km/h\nplafosim --random-desired-speed true --desired-speed 36\n\n# Configure random trips for 500 vehicles\nplafosim --vehicles 500 --random-depart-position true --random-arrival-position true --depart-desired true\n\n# Pre fill the freeway with 1000 vehicles\nplafosim --vehicles 1000 --pre-fill true\n\n# Configure 50% of the vehicles with Advanced Cruise Control (ACC) and a headway time of 1.5s\nplafosim --penetration 0.5 --acc-headway-time 1.5\n\n# Enable a simple, distributed platoon formation algorithm [1] in order to form platoons every 30s\nplafosim --formation-algorithm SpeedPosition --formation-strategy distributed --execution-interval 30\n```\n\n### Faster Simulation\n\nYou can speed up the simulation performance by enabling Python's optimization ```PYTHONOPTIMIZE```, e.g., in order to disable assertions:\n\n```PYTHONOPTIMIZE=1 plafosim```\n\nSee the Python [documention](https://docs.python.org/3/using/cmdline.html#envvar-PYTHONOPTIMIZE) for more details.\n\n## Re-Playing a Simulation\n\nThe simulation can write a trace file including the mobility details of every simulated vehicle (default `results_vehicle_traces.csv`).\nYou can replay the simulation in the GUI (see above) based on the trace file by using the corresponding binary:\n\n```plafosim-replay results_vehicle_traces.csv```\n\nTo see all options of this script, run:\n\n```plafosim-replay -h, --help```\n\n**NOTE**: This requires installation of SUMO (>=1.6.0) and declaration of the `SUMO_HOME` variable.\n\n## Recording of Screenshots and Video from a Simulation\n\nPlaFoSim offers functionality to automatically record a screenshot of the GUI in every simulation step with\n\n```plafosim --gui --screenshot-file screenshot```\n\nThese screenshots can be used to create a video by using an integrated script based on [ffmpeg](https://ffmpeg.org/):\n\n```plafosim-img2video 'screenshot_*.png' video.mp4```\n\n**NOTE**: This requires installation of ffmpeg.\n\n## Documentation\n\nDocumentation is available via this README and via the [official documentation](https://plafosim.readthedocs.io/).\n\n## Extending PlaFoSim\n\nYou can extend and customize PlaFoSim flexibly by modifying its source code.\nFor this, you first need ot install it from source.\n\n### Installing from Source\n\n- Install [poetry](https://python-poetry.org/):\n```pip install poetry```\n- Clone this repository:\n```git clone https://github.com/heinovski/plafosim.git```\n- Navigate to newly created directory of the cloned repository in the command-line\n- Install PlaFoSim from source in editable mode:\n```poetry install```\n- Run PlaFoSim in the virtual environment:\n```poetry run plafosim```\nYou can also activate the virtual enviroment first with ```poetry shell``` and run the commands as usual (see above).\n\n### Adding a new Formation Algorithm\n\nIn order to add a new formation algorithm, you need to follow these steps:\n- Create a new sub-class of `FormationAlgorithm` (see `formation_algorithm.py`) within the sub-directory `algorithms`.\nYou can use the `Dummy` algorithm (see `algorithms/dummy.py`) as an example.\n- Add specific arguments for your algorithm to the argument parser group within the new sub-class if necessary.\n\nYou should now be able to use your new algorithm with\n```\nplafosim --formation-algorithm dummy_algorithm_name\n```\n\n## Contributing to the Project\n\nIn order to contribute, please follow these steps:\n- Install PlaFoSim from source (see [Extending PlaFoSim](.#extending-plafosim))\n- Make desired changes and adjust the documentation if required\n- Run the tests located in `tests` as well as the validation scripts located in `scripts` (see `.drone.yml` for details)\n- Submit a Pull Request (PR)\n\n### Documenting\n\nWhen making changes to the code, make sure to add or adjust corresponding documentation in form of python docstrings.\nThose should use the Numpy docstring format for Sphinx and follow the [style guide](https://numpydoc.readthedocs.io/en/latest/format.html) by numpydoc to ensure consistency and compatibility.\nSee also the [style guide](https://pandas.pydata.org/docs/development/contributing_docstring.html) by pandas.\nYou can build the documentation using Sphinx `make -C docs`.\n\n### Testing\n\nWhen adding methods and functions, make sure to add corresponding unit tests for `py.test`.\nThe tests are located under `tests` and can be executed with `./scripts/run-pytest.sh`.\nThis will also generate a test coverage report.\n\n### Validation\n\nTo validate the behavior of PlaFoSim, it is compared to SUMO 1.6.0 by means of simulation results (e.g., vehicle traces).\nThe corresponding scripts are located under `scripts` and executed withn CI/CD pipelines.\nYou can have a look at `.drone.yml` for details regarding the execution.\n\n### Profiling\n\nYou can profile the runtime of PlaFoSim's code by using [cProfile](https://docs.python.org/3/library/profile.html#module-cProfile):\n\n```poetry run python -m cProfile -o profile.out -m plafosim.cli.plafosim```\n\nYou can visualize the results of the profiling run by using [SnakeViz](https://jiffyclub.github.io/snakeviz/):\n\n```snakeviz profile.out```\n\n## Contributors & Citing\n\nPlaFoSim was originally designed and built by [Julian Heinovski](https://github.com/heinovski/) with the help of [Dominik S. Buse](https://github.com/dbuse/).\nIt is currently maintained by [Julian Heinovski](https://github.com/heinovski/).\nThe list of all authors can be found [here](AUTHORS.md).\n\nIf you are working with `PlaFoSim`, we would appreciate a citation of [our paper](https://www.tkn.tu-berlin.de/bib/heinovski2021scalable/):\n\n> Julian Heinovski, Dominik S. Buse and Falko Dressler, \"Scalable Simulation of Platoon Formation Maneuvers with PlaFoSim,\" Proceedings of 13th IEEE Vehicular Networking Conference (VNC 2021), Poster Session, Virtual Conference, November 2021, pp. 137\u2013138.\n\n```bibtex\n@inproceedings{heinovski2021scalable,\n author = {Heinovski, Julian and Buse, Dominik S. and Dressler, Falko},\n doi = {10.1109/VNC52810.2021.9644678},\n title = {{Scalable Simulation of Platoon Formation Maneuvers with PlaFoSim}},\n pages = {137--138},\n publisher = {IEEE},\n issn = {2157-9865},\n isbn = {978-1-66544-450-7},\n address = {Virtual Conference},\n booktitle = {13th IEEE Vehicular Networking Conference (VNC 2021), Poster Session},\n month = {11},\n year = {2021},\n}\n```\n\n## License\n\nPlaFoSim is licensed under the terms of the GNU General Public License 3.0 or later.\n\n```\n# Copyright (c) 2020-2024 Julian Heinovski <heinovski@ccs-labs.org>\n#\n# SPDX-License-Identifier: GPL-3.0-or-later\n#\n# This program is free software: you can redistribute it and/or modify\n# it under the terms of the GNU General Public License as published by\n# the Free Software Foundation, either version 3 of the License, or\n# any later version.\n#\n# This program is distributed in the hope that it will be useful,\n# but WITHOUT ANY WARRANTY; without even the implied warranty of\n# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n# GNU General Public License for more details.\n#\n# You should have received a copy of the GNU General Public License\n# along with this program. If not, see <https://www.gnu.org/licenses/>.\n```\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "A simple and scalable simulator for platoon formation.",
"version": "0.17.3",
"project_urls": {
"Changelog": "https://github.com/heinovski/plafosim/blob/master/CHANGELOG.md",
"Documentation": "https://plafosim.readthedocs.io/",
"Homepage": "https://www.plafosim.de",
"Repository": "https://github.com/heinovski/plafosim"
},
"split_keywords": [
"algorithm",
"engineering",
"experiment",
"platoon",
"platoon formation",
"platooning",
"platoon maneuver",
"research",
"science",
"simulation",
"simulator"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d599c15cff4c88922cb9ec60c4350797c69a43bb8c5ee7341d11191357c44138",
"md5": "ae50e1117c01f8f05bf0dc413897754d",
"sha256": "bec0ddcb02b0580a96d0b2718d4642807f432b0754ae1ee49495b942f7078ba5"
},
"downloads": -1,
"filename": "plafosim-0.17.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ae50e1117c01f8f05bf0dc413897754d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<3.10",
"size": 122518,
"upload_time": "2024-01-11T09:32:10",
"upload_time_iso_8601": "2024-01-11T09:32:10.853562Z",
"url": "https://files.pythonhosted.org/packages/d5/99/c15cff4c88922cb9ec60c4350797c69a43bb8c5ee7341d11191357c44138/plafosim-0.17.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e7ffe4644a569288d83e1b3c8d47cc55101b9b053efe177eb440130f998f5589",
"md5": "89d02d3cd52b8bbcd2553ca0b7377805",
"sha256": "8cf9af80ff1e630084c8aaf5b86a48271bb0741b2840eda6fd8f00d85bc15e3b"
},
"downloads": -1,
"filename": "plafosim-0.17.3.tar.gz",
"has_sig": false,
"md5_digest": "89d02d3cd52b8bbcd2553ca0b7377805",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<3.10",
"size": 95438,
"upload_time": "2024-01-11T09:32:13",
"upload_time_iso_8601": "2024-01-11T09:32:13.402563Z",
"url": "https://files.pythonhosted.org/packages/e7/ff/e4644a569288d83e1b3c8d47cc55101b9b053efe177eb440130f998f5589/plafosim-0.17.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-11 09:32:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "heinovski",
"github_project": "plafosim",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "plafosim"
}
JSON
