PySocialForce

master: dev:

A Python Implementation of the Extended Social Force Model for Pedestrian Dynamics

Table of Contents

• PySocialForce
  • Table of Contents
  • About The Project
    • Roadmap
  • Installation
  • Usage
  • Examples
    • Ped-ped Scenarios
    • Environmental obstacles
    • Groups
  • License
  • Acknowledgements
  • References

About The Project

This project is a NumPy implementation of the Extended Social Force Model [2]. It extends the vanilla social force model [1] to simulate the walking behaviour of pedestrian social groups.

Roadmap

• Simulation of indiviual pedestrians
• Social groups simulation
• Inter-group interactions
• Environmental obstacles
• Better environment representation
• Easy configuration with toml file
• Visualization of indiviuals and groups
• Visualization of forces/potentials

Installation

1. Clone the PySocialForce repo

   git clone https://github.com/yuxiang-gao/PySocialForce.git

2. (optional) Create a python virtual environment and activate it

3. Install the pip package

       # Option 1: install from PyPI
       pip install 'pysocialforce[test,plot]'
   
       # Option 2:  install from source
       pip install -e '.[test,plot]'
   
       # run linting and tests
       pylint pysocialforce
       pytest tests/*.py

Usage

Basic usage:

import pysocialforce as psf
# initiate simulator
sim = psf.Simulator(
        initial_state, groups=groups, obstacles=obstacles, config_file="config.toml"
    )
# do 50 updates
sim.step(n=50)

To generate an animation of the simulation, use the SceneVisualizer context:

with psf.plot.SceneVisualizer(simulator, "output_image") as sv:
    sv.animate()

You can configure the parameters by passing in a toml file. Default configurations are located in the default.toml file in root directory.

For more examples, please refer to the examples folder.

Examples

Ped-ped Scenarios

Environmental obstacles

Emergent lane formation with Emergent lane formation with 30 pedestrians:	Emergent lane formation with Emergent lane formation with 60 pedestrians:

Groups

License

Distributed under the MIT License. See LICENSE for more information.

Acknowledgements

• This project is based on svenkreiss's implementation of the vanilla social force model.
• The implementation of forces drew inspiration from the pedsim_ros package.

References

[1] Helbing, D., & Molnár, P. (1995). Social force model for pedestrian dynamics. Physical Review E, 51(5), 4282–4286. https://doi.org/10.1103/PhysRevE.51.4282

[2] Moussaïd, M., Perozo, N., Garnier, S., Helbing, D., & Theraulaz, G. (2010). The walking behaviour of pedestrian social groups and its impact on crowd dynamics. PLoS ONE, 5(4), 1–7. https://doi.org/10.1371/journal.pone.0010047