• Overview  
• Features  
• Quick Start
• Theoretical Background  
• Input & Output Formats  
• Real-World Applications  
• Ethical Considerations  
• Roadmap  
• Troubleshooting
• Acknowledgments  
• Contributing  
• License

This project delivers a scalable, realistic, and lightning-fast framework for simulating building evacuations using JuPedSim.
It combines parallel agent distribution, Numba-accelerated computations, and efficient geometry handling for advanced crowd analysis.

Designed for:

• Researchers studying pedestrian dynamics
• Safety engineers optimizing evacuation plans
• Urban planners improving public space layouts

🚀 High Performance – Parallel simulation with ThreadPoolExecutor
🔥 Numba Acceleration – JIT speed-ups for heavy math
🗺 Flexible Geometry – Import .wkt or XML building layouts
📊 Detailed Analytics – Density heatmaps, bottleneck detection, evacuation times
🎯 Customizable Agents – Adjustable speeds, behaviors, and spawn zones
📈 Visual Outputs – Real-time plots & post-simulation analysis

git clone https://github.com/Kandil2001/Jupedsim-Evacuation-Analysis.git
cd Jupedsim-Evacuation-Analysis
pip install -r requirements.txt

jupyter notebook "Ped1 - Copy.ipynb"

from jupedsim import Simulation
sim = Simulation(geometry="HC.wkt", agents=200)
sim.run()
sim.plot_heatmap()

Pedestrians are modeled as particles influenced by attractive forces (towards exits) and repulsive forces (from obstacles and others). This model is a cornerstone of microscopic pedestrian dynamics simulations. For a detailed description of the model, refer to the resources at https://pedestriandynamics.org/models/.

When many agents attempt to pass through a narrow exit, congestion forms, reducing flow efficiency.

Heatmaps visualize crowd density and movement intensity to identify congestion hotspots.

• Microscopic: Simulates each pedestrian individually (detailed interactions).  
• Macroscopic: Treats crowds as continuous flows (good for large-scale analysis).  

JuPedSim primarily uses WKT geometry definitions for simulation.

Tested on: Intel i7-11800H, 16GB RAM, Python 3.10

🏟 Event planning – Stadium crowd dispersal
🏢 Architecture – Optimizing exit placements
🚉 Transport hubs – Reducing congestion
🏙 Urban design – Public space flow analysis

• Privacy: Real-world data must be anonymized
• Inclusivity: Account for individuals with varied mobility needs
• Transparency: Document assumptions and limitations of the model

• Parallel agent simulation
• Heatmap visualizations
• Adaptive route choice AI

Q: Simulation runs slowly
A: Ensure Numba is enabled, use Python ≥3.9, and reduce visualization frequency.

Q: How do I change exits?
A: Edit the .wkt file to define new exit polygons.

Q: Output file is empty
A: Check that spawn zones and exits are correctly defined in geometry.

This project was developed as a practical assignment for the Pedestrian Dynamics course at the Bergische Universität Wuppertal. We extend our gratitude to:

• Mohcine Chraibi for supervision and guidance. His personal page is available at https://www.chraibi.de/.
• The JuPedSim development team for providing the powerful simulation framework. More information is available on the official website: https://www.jupedsim.org/stable/.
• The Python community for the essential tools and libraries (Numba, Matplotlib, etc.) that made high-performance analysis possible.

We welcome contributions of all kinds — bug fixes, performance improvements, documentation updates, and new features.

Please read our CONTRIBUTING.md for detailed contribution guidelines, coding standards, and workflow instructions before submitting a pull request.

MIT License – see LICENSE for details.