master: 
A Python Implementation of the Extended Social Force Model for Pedestrian Dynamics
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.
- 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
-
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
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.
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 |
 |
|---|---|
 |
 |
 |
 |
|---|---|
Emergent lane formation with Emergent lane formation with 30 pedestrians:  |
Emergent lane formation with Emergent lane formation with 60 pedestrians:  |
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.
Distributed under the MIT License. See LICENSE for more information.
- 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.
[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