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
  • Configuration
  • Examples
    • Ped-ped Scenarios
    • Environmental obstacles
    • Groups
  • Contributing to this project
  • 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
    )
# 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()

For more examples, please refer to the examples folder.

Configuration

You can configure the parameters by passing in a toml file to the simulator:

sim = psf.Simulator(
        initial_state, groups=groups, obstacles=obstacles, config_file="user_config.toml"
    )

By default the simulator loads the configurations at pysocialforce/utils/default.toml. An example of the user config and the explanation of the parameters is provided at examples/example.toml. Each force has a parameter named factor, which is the scale factor for that force. For specific parameters for each force, refer to the comments in the example below:

...
[desired_force]
factor = 1.0
# The relaxation distance of the goal
goal_threshold = 0.2
# How long the relaxation process would take
relaxation_time = 0.5

[social_force]
factor = 5.1
# relative importance of position vs velocity vector
lambda_importance = 2.0
# define speed interaction
gamma = 0.35
n = 2
# define angular interaction
n_prime = 3

[obstacle_force]
factor = 10.0
# the standard deviation of obstacle force
sigma = 0.2
# threshold to trigger this force
threshold = 3.0

[group_coherence_force]
factor = 3.0

[group_repulsive_force]
factor = 1.0
# threshold to trigger this force
threshold = 0.55

[group_gaze_force]
factor = 4.0
# fielf of view
fov_phi = 90.0

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

Contributing to this project

Thanks for your interest in contributing! PySocialForce is a open-source project and we welcome contributions of any kind. If you find a bug or have a feature request, feel free to contact us using Github issues. If you are reporting a bug, please try to include a minimal example to recreate it. If you are requesting a feature, please also give some possible use cases to justify the request. If you want to help with development, you can work on a fork of the project and start a pull request. Please document your code and make sure that you have added the necessary tests and examples. Please also adhere to semantic versioning.

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