Module avoidance 

Physical avoidance force primitives for pedestrian and agent dynamics.

Provides reusable, pure-function force calculations based on the Social Force Model (Helbing & Molnar 1995; Helbing, Farkas & Vicsek 2000). These primitives can be composed by any agent step function that needs collision-avoidance behavior.

Unit contract

All functions in this module (desired_force_*, social_repulsion_*, wall_repulsion_*) return accelerations in m/s², not Newtons. The Helbing-calibrated parameters (a_social, k_body, kappa_friction, a_wall, k_wall, kappa_wall) are still declared in Newton-scale units matching the literature (e.g. Helbing, Farkas & Vicsek 2000 Table 1), but are divided internally by SocialForceParams::mass (default 80 kg per Helbing 2000). This keeps the parameter dashboard literature-compatible while making all force outputs dimensionally consistent with the v += a * dt integrator used by integrate_euler_2d / integrate_euler_3d.

For mixed populations (children ≈ 30 kg, adults ≈ 80 kg, equipped responders > 100 kg) override mass on the SocialForceParams struct; the returned accelerations scale as 1/mass automatically.

Force components

Force	Description
Desired	Drives agent toward its destination at desired speed
Social repulsion	Exponential repulsion from nearby agents (psychological)
Physical contact	Body compression + sliding friction when agents overlap
Wall repulsion	Exponential repulsion from wall/obstacle segments
Wall contact	Body compression + sliding friction when agent overlaps a wall

References

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

Structs

SocialForceParams

Parameters for the Social Force Model with physical contact forces.

WallSegment

A wall segment defined by two endpoints.

WallSegment3D

A 3D wall segment defined by two endpoints.

Functions

desired_force_2d

Desired force driving an agent toward its destination in 2D.

desired_force_3d

Desired force driving an agent toward its destination in 3D.

integrate_euler_2d

Euler integration with speed clamping in 2D.

integrate_euler_3d

Euler integration with speed clamping in 3D.

social_repulsion_2d

Social repulsion + physical contact acceleration from a single neighbor in 2D.

social_repulsion_3d

Social repulsion + physical contact acceleration from a single neighbor in 3D.

wall_repulsion_2d

Wall repulsion + physical contact acceleration from a single wall segment in 2D.

wall_repulsion_3d

Wall repulsion + physical contact acceleration from a 3D wall segment.