Module social_force 

Social Force Model (Helbing & Molnár 1995; Helbing, Farkas & Vicsek 2000).

Each pedestrian experiences a sum of three forces:

• a driving force pulling it toward its destination at its desired speed,
• a repulsive social force from every other pedestrian,
• a repulsive force from every static obstacle (wall segment).

The resulting acceleration is integrated with semi-implicit (symplectic) Euler: each tick first updates velocity from the current acceleration, then advances position using the new velocity (v ← v + a·dt; p ← p + v·dt). This is the classic stability fix for stiff pair interactions — it preserves energy far better than fully explicit Euler at identical dt and is the same integration scheme used by JuPedSim and PedSim for the Social Force family. Combined with the Params::max_accel cap and the dt · max_accel ≤ max_speed CFL check in Params::validate, this keeps the integrator stable at the default 30 Hz timestep even under panic-flow parameterisation. The speed is clipped to params.max_speed after the velocity update, before the position advance.

This implementation follows Eq. 1–3 of Helbing, Farkas & Vicsek (2000), “Simulating dynamical features of escape panic”, Nature 407, 487–490, with the elliptical repulsion shape from Helbing & Molnár (1995).

References

• Helbing, D., & Molnár, P. (1995). “Social force model for pedestrian dynamics”. Physical Review E, 51(5), 4282–4286.
• Helbing, D., Farkas, I., & Vicsek, T. (2000). “Simulating dynamical features of escape panic”. Nature, 407(6803), 487–490.

Structs

Params

Parameters for the Social Force model.

SocialForce

Unit marker type implementing PedestrianModel for Social Force.

Functions

cap_accel

Clamp the magnitude of an acceleration vector to cap.

driving_force

f_drive = m * (v0 * e_dest - v) / tau

neighbor_cutoff

Recommended neighbour cutoff radius for grid queries (metres).

ped_repulsion

Pairwise repulsion A * exp((r_ij - d_ij) / B) * e_ij along the line connecting q to p, where r_ij = p.radius + q.radius.

stepDeprecated

Free-function step for callers that do not need trait dispatch.

step_scratch

Zero-allocation step variant. Reuses scratch.buf and rebuilds scratch.grid against peds, then runs the same math as step_with_grid without any per-tick allocation.

step_with_grid

Grid-accelerated step variant. Semantically equivalent to step up to numerical floating-point noise for interaction pairs inside neighbor_cutoff(params); pairs outside that radius are pruned because their contribution is below 1 mN at default parameters.

wall_repulsion

Repulsion from the closest point on a wall segment.