rustsim-crowd 0.0.1

//! Microscopic crowd locomotion models for rustsim.
//!
//! This crate implements the five microscopic pedestrian models catalogued at
//! <https://pedestriandynamics.org/models/> in pure 2-D continuous space
//! plus a **layered 2.5-D** extension in the [`threed`] module for
//! multi-storey environments (stations, airports, stadiums, malls).
//!
//! It is called `rustsim-crowd` rather than `rustsim-pedestrian` because
//! the same physics apply equally to cyclists, evacuees, queue-formers,
//! and generic self-propelled agents.
//!
//! | Module | Model | Class | Primary references |
//! |---|---|---|---|
//! | [`social_force`] | Social Force | Force-based, 2nd order | Helbing & Molnár 1995; Helbing, Farkas & Vicsek 2000 |
//! | [`collision_free_speed`] | Collision-Free Speed | Velocity-based, 1st order | Tordeux, Chraibi & Seyfried 2016 |
//! | [`generalized_centrifugal_force`] | Generalized Centrifugal Force | Force-based, 2nd order | Chraibi, Seyfried & Schadschneider 2010 |
//! | [`optimal_steps`] | Optimal Steps | Discrete-step utility | Seitz & Köster 2012 |
//! | [`anticipation_velocity`] | Anticipation Velocity | Velocity-based, 1st order | Xu, Chraibi & Seyfried 2021 |
//! | [`threed`] | Layered 2.5-D Social Force | Per-floor 2-D physics + vertical connectors | Industry standard (JuPedSim, MassMotion, Legion) |
//!
//! # API shape
//!
//! Every 2-D model shares the same three-type contract defined by the
//! [`PedestrianModel`] trait:
//!
//! - [`Pedestrian`] — the shared per-agent state (position, velocity, radius,
//!   desired speed, destination).
//! - [`WallSegment`] — a 2-D line segment describing a static obstacle.
//! - `Params` — a model-specific parameter bundle living inside each module.
//!
//! Each model exposes:
//!
//! - a `Params` struct with stable literature/engineering defaults.
//! - explicit [`calibration`] helpers for deployments that must enforce a
//!   published speed-density envelope such as Weidmann (1993).
//! - a unit struct implementing [`PedestrianModel`] so callers can swap
//!   models behind a trait object or generic bound.
//! - a free `step(peds, walls, params, dt)` function (deprecated since
//!   `0.0.3`; O(n²) reference path retained for parity tests). Production
//!   callers use `step_scratch` (zero-alloc) or `step_with_grid`
//!   (broadphase) instead.
//!
//! ```
//! use rustsim_crowd::prelude::*;
//!
//! let mut peds = vec![Pedestrian::new(
//!     [0.0, 0.0],
//!     [0.0, 0.0],
//!     0.25,
//!     1.34,
//!     [10.0, 0.0],
//! )];
//! let walls: Vec<WallSegment> = Vec::new();
//! let params = social_force::Params::default();
//! // Production hot path: zero-alloc, broadphase-accelerated.
//! let mut scratch = Scratch::new(recommended_cell_size(
//!     social_force::neighbor_cutoff(&params),
//! ));
//! social_force::step_scratch(&mut peds, &walls, &params, 0.05, &mut scratch);
//! ```
//!
//! # Design constraints
//!
//! - Pure `f64`, SoA-friendly internals, no interior mutability.
//! - `step_scratch(peds, walls, params, dt, &mut scratch)` is the
//!   **zero-alloc hot path**: allocate one [`broadphase::Scratch`] per
//!   simulation and reuse it tick-after-tick. `step_with_grid` takes a
//!   caller-owned [`NeighborGrid`] and allocates one `Vec<[f64; 2]>`
//!   per tick; `step` is the O(n²) reference path with no broadphase.
//! - Determinism: every `step_*` variant is a deterministic function
//!   of its inputs.

#![deny(missing_docs)]

pub mod anticipation_velocity;
pub mod broadphase;
pub mod calibration;
pub mod collision_free_speed;
pub mod common;
#[cfg(feature = "cuda")]
pub mod cuda;
pub mod error;
pub mod generalized_centrifugal_force;
pub mod integration;
pub mod optimal_steps;
#[cfg(feature = "simd")]
pub mod simd;
pub mod social_force;
pub mod threed;

pub use broadphase::{recommended_cell_size, NeighborGrid, Scratch};
pub use calibration::{
    apply_weidmann_speed_cap, apply_weidmann_speed_target, density_for_area, mean_speed,
    CalibrationPoint, CalibrationReport, WeidmannCurve,
};
pub use common::{Pedestrian, PedestrianModel, WallSegment};
pub use error::CrowdError;
pub use integration::{
    pack_columns_from, step_columns_f64, step_scratch_store, step_scratch_store_observed,
    unpack_columns_into, AnticipationVelocityModel, CollisionFreeSpeedModel, CrowdAgent,
    CrowdObserver, CrowdStep, GeneralizedCentrifugalForceModel, OptimalStepsModel,
    SocialForceModel,
};
#[cfg(feature = "rayon")]
pub use integration::{step_scratch_store_observed_par, step_scratch_store_par, CrowdStepPar};
pub use threed::{LayeredObserver, LayeredScratch, Pedestrian3D, WallPolygon3D};

/// Convenience re-exports for the common consumer path.
pub mod prelude {
    pub use crate::broadphase::{recommended_cell_size, NeighborGrid, Scratch};
    pub use crate::calibration::{
        apply_weidmann_speed_cap, apply_weidmann_speed_target, density_for_area, mean_speed,
        CalibrationPoint, CalibrationReport, WeidmannCurve,
    };
    pub use crate::common::{Pedestrian, PedestrianModel, WallSegment};
    pub use crate::error::CrowdError;
    pub use crate::integration::{
        pack_columns_from, step_columns_f64, step_scratch_store, step_scratch_store_observed,
        unpack_columns_into, AnticipationVelocityModel, CollisionFreeSpeedModel, CrowdAgent,
        CrowdObserver, CrowdStep, GeneralizedCentrifugalForceModel, OptimalStepsModel,
        SocialForceModel,
    };
    #[cfg(feature = "rayon")]
    pub use crate::integration::{
        step_scratch_store_observed_par, step_scratch_store_par, CrowdStepPar,
    };
    pub use crate::threed::{
        step_layered, step_layered_scratch, step_layered_scratch_observed, LayeredObserver,
        LayeredScratch, Pedestrian3D, WallPolygon3D,
    };
    pub use crate::{
        anticipation_velocity, collision_free_speed, generalized_centrifugal_force, optimal_steps,
        social_force, threed,
    };
}