PySocialForce

master: dev:

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

PySocialForce

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

Clone the PySocialForce repo

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

(optional) Create a python virtual environment and activate it

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

yuxiang-gao/PySocialForce