{"id":26409419,"url":"https://github.com/yuxiang-gao/pysocialforce","last_synced_at":"2025-04-09T07:10:32.513Z","repository":{"id":45414398,"uuid":"269771056","full_name":"yuxiang-gao/PySocialForce","owner":"yuxiang-gao","description":"Extended Social Force Model in Python for social navigation research","archived":false,"fork":false,"pushed_at":"2022-11-21T10:49:01.000Z","size":80867,"stargazers_count":144,"open_issues_count":6,"forks_count":40,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-02T02:19:22.070Z","etag":null,"topics":["pedestrian-social-groups","py-social-force","python","social-force-model","social-navigation"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yuxiang-gao.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-06-05T20:42:31.000Z","updated_at":"2025-04-01T09:45:49.000Z","dependencies_parsed_at":"2023-01-23T03:01:04.267Z","dependency_job_id":null,"html_url":"https://github.com/yuxiang-gao/PySocialForce","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuxiang-gao%2FPySocialForce","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuxiang-gao%2FPySocialForce/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuxiang-gao%2FPySocialForce/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yuxiang-gao%2FPySocialForce/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yuxiang-gao","download_url":"https://codeload.github.com/yuxiang-gao/PySocialForce/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247994122,"owners_count":21030050,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["pedestrian-social-groups","py-social-force","python","social-force-model","social-navigation"],"created_at":"2025-03-17T19:34:13.652Z","updated_at":"2025-04-09T07:10:32.497Z","avatar_url":"https://github.com/yuxiang-gao.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PySocialForce\n\nmaster: [![Build Status](https://travis-ci.com/yuxiang-gao/PySocialForce.svg?branch=master)](https://travis-ci.com/yuxiang-gao/PySocialForce)\ndev: [![Build Status](https://travis-ci.com/yuxiang-gao/PySocialForce.svg?branch=dev)](https://travis-ci.com/yuxiang-gao/PySocialForce)\n\nA Python Implementation of the Extended Social Force Model for Pedestrian Dynamics\n\n## Table of Contents\n\n- [PySocialForce](#pysocialforce)\n  - [Table of Contents](#table-of-contents)\n  - [About The Project](#about-the-project)\n    - [Roadmap](#roadmap)\n  - [Installation](#installation)\n  - [Usage](#usage)\n  - [Configuration](#configuration)\n  - [Examples](#examples)\n    - [Ped-ped Scenarios](#ped-ped-scenarios)\n    - [Environmental obstacles](#environmental-obstacles)\n    - [Groups](#groups)\n  - [Contributing to this project](#contributing-to-this-project)\n  - [License](#license)\n  - [Acknowledgements](#acknowledgements)\n  - [References](#references)\n\n## About The Project\n\nThis project is a NumPy implementation of the **Extended Social Force Model** [[2]](#2).\nIt extends the vanilla social force model [[1]](#1) to simulate the walking behaviour of pedestrian social groups.\n\n### Roadmap\n\n- [x] Simulation of indiviual pedestrians\n- [x] Social groups simulation\n- [ ] Inter-group interactions\n- [x] Environmental obstacles\n- [ ] Better environment representation\n- [x] Easy configuration with toml file\n- [x] Visualization of indiviuals and groups\n- [ ] Visualization of forces/potentials\n\n## Installation\n\n1. Clone the PySocialForce repo\n\n    ```sh\n    git clone https://github.com/yuxiang-gao/PySocialForce.git\n    ```\n\n2. (optional) Create a python virtual environment and activate it\n3. Install the pip package\n\n    ```sh\n        # Option 1: install from PyPI\n        pip install 'pysocialforce[test,plot]'\n\n        # Option 2:  install from source\n        pip install -e '.[test,plot]'\n\n        # run linting and tests\n        pylint pysocialforce\n        pytest tests/*.py\n    ```\n\n## Usage\n\nBasic usage:\n\n```python\nimport pysocialforce as psf\n# initiate simulator\nsim = psf.Simulator(\n        initial_state, groups=groups, obstacles=obstacles\n    )\n# do 50 updates\nsim.step(n=50)\n```\n\nTo generate an animation of the simulation, use the `SceneVisualizer` context:\n\n```python\nwith psf.plot.SceneVisualizer(simulator, \"output_image\") as sv:\n    sv.animate()\n```\nFor more examples, please refer to the [examples folder](examples).\n\n## Configuration\nYou can configure the parameters by passing in a [toml](https://github.com/toml-lang/toml) file to the simulator:\n```Python\nsim = psf.Simulator(\n        initial_state, groups=groups, obstacles=obstacles, config_file=\"user_config.toml\"\n    )\n```\n\nBy default the simulator loads the configurations at [pysocialforce/utils/default.toml](pysocialforce/utils/default.toml).\nAn example of the user config and the explanation of the parameters is provided at [examples/example.toml](examples/example.toml).\nEach 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:\n```Toml\n...\n[desired_force]\nfactor = 1.0\n# The relaxation distance of the goal\ngoal_threshold = 0.2\n# How long the relaxation process would take\nrelaxation_time = 0.5\n\n[social_force]\nfactor = 5.1\n# relative importance of position vs velocity vector\nlambda_importance = 2.0\n# define speed interaction\ngamma = 0.35\nn = 2\n# define angular interaction\nn_prime = 3\n\n[obstacle_force]\nfactor = 10.0\n# the standard deviation of obstacle force\nsigma = 0.2\n# threshold to trigger this force\nthreshold = 3.0\n\n[group_coherence_force]\nfactor = 3.0\n\n[group_repulsive_force]\nfactor = 1.0\n# threshold to trigger this force\nthreshold = 0.55\n\n[group_gaze_force]\nfactor = 4.0\n# fielf of view\nfov_phi = 90.0\n```\n\n## Examples\n\n### Ped-ped Scenarios\n\n| ![crossing](images/crossing.png)          | ![narrow](images/narrow_crossing.png) |\n| ----------------------------------------- | ------------------------------------- |\n| ![opposing](image/../images/opposing.png) | ![2opposing](images/2opposing.png)    |\n\n### Environmental obstacles\n\n| ![sperator](images/separator.gif)                                                                             | ![gate](images/gate.gif)                                                                                       |\n| ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |\n| Emergent lane formation with Emergent lane formation with 30 pedestrians: ![walkway30](images/walkway_30.gif) | Emergent lane formation with Emergent lane formation with 60 pedestrians:  ![walkway60](images/walkway_60.gif) |\n\n### Groups\n\n![group crossing](images/group_crossing.gif)\n\n## Contributing to this project\nThanks for your interest in contributing! PySocialForce is a open-source project and we welcome contributions of any kind.\nIf you find a bug or have a feature request, feel free to contact us using [Github issues](https://github.com/yuxiang-gao/PySocialForce/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.\nIf 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](https://semver.org).\n\n## License\n\nDistributed under the MIT License. See `LICENSE` for more information.\n\n## Acknowledgements\n\n- This project is based on [svenkreiss](https://github.com/svenkreiss)'s implementation of the vanilla social force model.\n- The implementation of forces drew inspiration from the [pedsim_ros][pedsim_ros] package.\n\n## References\n\n\u003ca id=\"1\"\u003e[1]\u003c/a\u003e Helbing, D., \u0026 Molnár, P. (1995). Social force model for pedestrian dynamics. Physical Review E, 51(5), 4282–4286. \u003chttps://doi.org/10.1103/PhysRevE.51.4282\u003e\n\n\u003ca id=\"2\"\u003e[2]\u003c/a\u003e Moussaïd, M., Perozo, N., Garnier, S., Helbing, D., \u0026 Theraulaz, G. (2010). The walking behaviour of pedestrian social groups and its impact on crowd dynamics. PLoS ONE, 5(4), 1–7. \u003chttps://doi.org/10.1371/journal.pone.0010047\u003e\n\n[socialforce]: https://github.com/svenkreiss/socialforce\n\n[pedsim_ros]: https://github.com/srl-freiburg/pedsim_ros\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuxiang-gao%2Fpysocialforce","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyuxiang-gao%2Fpysocialforce","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyuxiang-gao%2Fpysocialforce/lists"}