CrowdControl

Real-time PDE-based crowd simulation • Harmonic navigation fields • Autonomous mitigation • Interactive visualization

This project combines a real-time spatial simulation engine, live risk telemetry, and a polished frontend to turn crowd-flow theory into something you can see, tune, and explore.

Why this matters

Crowd safety is one of those problems that looks simple until it is not.

A building entrance, a stadium tunnel, a transit platform, a festival gate, or a public plaza can appear fine on paper and still become dangerous when:

• entry flow exceeds exit capacity
• local density rises faster than people can redistribute
• bottlenecks create compression and stagnation
• intervention timing is too late to matter

This simulator is useful because it gives you a visual and quantitative way to explore those failure modes before they happen.

It is valuable for:

• event and venue planning
• emergency evacuation design review
• crowd flow research and teaching
• testing how gates, walls, and route changes alter risk
• experimenting with mitigation policy in a safe, visual sandbox

What this project is

CrowdControl is a browser-based simulation sandbox for studying crowd movement in 2D layouts.

The repo includes:

• a numerical crowd-flow engine built in TypeScript
• a reactive frontend for live visualization
• scenario presets like bottlenecks and stadium-style layouts
• density, speed, and risk analytics
• mitigation logic that can place structural interventions dynamically

In short: this is a compact research prototype for visualizing crowd behavior under pressure.

What it looks like

The interface is designed to feel more like a live control room than a static demo:

• density heatmaps and risk overlays
• animated movement through the grid
• live telemetry for peak density, mean risk, and high-risk area percentage
• scenario editing with walls, entries, exits, and custom layouts
• optional prevention mode that detects hazards and responds with interventions

If the goal is to make crowd theory feel tangible, this project leans into that.

---

Architecture at a glance

The simulation is split into a few clean layers:

1. Scenario + layout setup

   • gates, entries, exits, walls, obstruction patterns

2. Direction field generation

   • a harmonic potential field is solved to create smooth navigation directions

3. Density evolution

   • advection, diffusion, pressure-driven compression, and entry/exit behavior are integrated over time

4. Risk scoring

   • local density, distance to exit, mobility impairment, and pressure contribute to a composite risk field

5. Mitigation control

   • hazardous zones trigger interventions that steer or meter flow rather than only blocking blindly

6. Visualization + telemetry

   • the frontend renders the field while tracking the rise and fall of congestion and unsafe areas

---

The math underneath the hood

This project is not just a particle toy model. It is a grid-based hydrodynamic crowd model with a navigation field and a risk functional.

1. Navigation field: harmonic potential

A smooth flow direction is generated by solving a discrete Laplace equation over the map.

∇²φ = 0

The exit cells act as sinks, and the resulting scalar potential field is turned into a normalized gradient vector field:

v = -∇φ

That gives each cell a physically consistent direction of travel while respecting walls and mitigation structures.

2. Density evolution: advection-diffusion with pressure

The crowd density field is updated with a finite-volume style upwind scheme:

∂ρ/∂t = -∇·(ρv) + D∇²ρ + compression(ρ)

Where:

• $\rho$ is local crowd density
• $v$ is the local velocity field
• $D$ is diffusivity
• the compression term captures pressure accumulation as density approaches critical levels

The code also implements a mobility reduction effect such that as density rises, the actual local speed drops through a nonlinear mobility factor.

3. Risk function

The system computes a scalar risk value at every active cell using a penalized composite functional:

R = α(ρ/ρmax) + δ(1/(d + ε)) + γ(1/(|v| + ε)) + ηΨ(ρ) - cohesion

Where:

• $\rho$ = local density
• $\rho_{max}$ = packing limit
• $d$ = distance to nearest exit
• $|v|$ = local speed magnitude
• $\Psi(\rho)$ = nonlinear pressure contribution once density exceeds a critical threshold
• cohesion = a local social/collective factor that partially offsets the risk score

This means risk rises when people are crowded, slow, trapped near constrictions, and under pressure from neighboring congestion.

You can check out the paper at https://doi.org/10.5281/zenodo.20362060

4. Mitigation logic

The mitigation system does not simply seal the map. It detects dangerous local states using:

• density
• throughput imbalance / flux
• stagnation
• local pressure

Then it chooses interventions that reshape flow paths and meter movement instead of brute-force blocking.

---

Tech stack

Core

• TypeScript
• React 19
• Vite
• Tailwind CSS
• Framer Motion
• GSAP
• Zustand

Simulation

• custom finite-volume crowd dynamics engine
• grid-based analytical flow field solver
• live hazard analytics and risk scoring
• browser-rendered heatmaps and overlays

Visualization

• canvas-based simulation rendering
• animated telemetry charts
• interactive control panel for parameters and scenario editing

---

Features

• interactive scenario presets
• custom map editing with walls, entries, exits, and erasing
• live density and risk heatmaps
• real-time telemetry panels
• prevention mode with automatic mitigation responses
• results export tooling and analytics scripts

This is the kind of project that feels impressive in a demo because it blends numerical simulation with a strong visual narrative.

---

Run locally

npm install
npm run dev

Then open the local Vite URL shown in the terminal.

Useful scripts

npm run build
npm run test
npm run generate:results

The generate:results script is useful if you want to regenerate the output analytics artifacts in the results/ folder.

---

Why this is a strong demo project

This repository is especially compelling because it sits at the intersection of:

• interactive simulation
• applied mathematical modeling
• visual analytics
• emergency safety thinking
• real-time control systems

That combination makes it attractive not just as a coding project, but as a polished concept that can be shown to researchers, planners, educators, or anyone interested in crowd safety.

It is the kind of project that instantly communicates value when someone sees the map, the heat, the risk spike, and the mitigation response happening live.

---

Future directions

There are several interesting extensions that would make this even more powerful:

• 3D visualizations for multi-level buildings and venues
• more validated evacuation benchmark scenarios
• policy search for optimal gate placement and flow control
• calibration against real-world event data
• reinforcement-learning style mitigation tuning

---

License

This project is currently provided as a research and exploration codebase. If you plan to reuse or adapt it, please review the repository license and keep attribution where appropriate.

---

Bottom line

CrowdControl is a compact, visually compelling crowd-flow simulator that turns dense mathematical ideas into something you can feel, inspect, and experiment with.

It is useful because it helps answer one simple but important question:

When a space becomes unsafe, where does the danger come from, and what changes can stop it from escalating?

---

Build and Maintained by Kalepu Yashvardhan , feel free to reach out :)