rustsim 0.0.1

High-performance agent-based modelling engine - top-level orchestration crate
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155

//! rustsim - high-performance agent-based modelling engine.
//!
//! This is the top-level orchestration crate that re-exports all sub-crates
//! and adds:
//!
//! - **[`compute`]** - CUDA/CPU compute routing and SoA batch stepping.
//! - **[`control_plane`]** - deterministic replay, checkpoint/restore,
//!   engine metrics, typed failures, and partition metadata.
//! - **[`device_store`]** - persistent device-side SoA storage (FlameGPU2-style).
//! - **[`ensemble`]** - parameter sweep and batch simulation runner.
//! - **[`layers`]** - layer-based execution model for multi-function steps.
//! - **[`interaction`]** - columnar spatial interaction/message indexes.
//! - **[`telemetry`]** - end-to-end pipeline from data collection to ClickHouse.
//!
//! # Quick start
//!
//! See the full working example under `examples/basic_particle.rs`:
//!
//! ```no_run
//! use rand::rngs::StdRng;
//! use rand::SeedableRng;
//! use rustsim::prelude::*;
//! use rustsim_spaces::nothing::NothingSpace;
//!
//! #[derive(Debug, Clone)]
//! struct Particle { id: AgentId, x: f64 }
//! impl Agent for Particle { fn id(&self) -> AgentId { self.id } }
//!
//! let mut store: HashMapStore<Particle> = HashMapStore::new();
//! store.insert(Particle { id: 1, x: 0.0 });
//!
//! let rng = StdRng::seed_from_u64(42);
//! let mut model: StandardModel<NothingSpace, Particle, _, (), _, Fastest> =
//!     StandardModel::new(
//!         store,
//!         NothingSpace,
//!         Fastest::new(),
//!         (),
//!         rng,
//!         None::<Box<dyn FnMut(&mut Particle, &mut StepContext<NothingSpace, Particle, (), StdRng, Fastest>)>>,
//!         None,
//!         true,
//!     );
//! model.step_n(100);
//! ```
//!
//! # Crate architecture
//!
//! | Crate | Purpose |
//! |-------|---------|
//! | `rustsim-core` | ABM engine: agents, models, stores, schedulers, stepping, messaging |
//! | `rustsim-spaces` | Space implementations: nothing, grid, continuous, graph, hybrid |
//! | `rustsim-schedulers` | Re-exports scheduler types |
//! | `rustsim-pathfinding` | Generic A\* and grid-specific pathfinding |
//! | `rustsim-io` | Arrow batch building, ClickHouse writer |
//! | `rustsim-geometry` | 2-D and 3-D geometric primitives (vectors, AABB, rays, triangles, spheres) |
//! | `rustsim-broadphase` | Spatial neighbour queries: uniform grids in 2-D and 3-D |
//! | `rustsim-modes` | Shared mode semantics (`TravelMode`, `AllowedModes`) |
//! | `rustsim-traffic` | Macroscopic traffic-flow semantics (link properties, FDs, signals, turns) |
//! | `rustsim-crowd` | Microscopic crowd locomotion (5 pedestrian models + layered 2.5-D) |
//! | `rustsim-vehicle` | Vehicle dynamics: IDM longitudinal, bicycle lateral, MOBIL lane-change |
//! | `rustsim-transit` | Transit primitives: stops, routes, schedules, boarding queues, dwell times |
//! | `rustsim-mobility` | Multi-modal glue: trips, legs, mode-transition state machine, modal Dijkstra, shared obstacle trait |
//! | `rustsim` (this crate) | Orchestration, compute routing, device storage, ensemble, telemetry |

pub mod columnar_runtime;
pub mod compute;
pub mod control_plane;
pub mod crowd_telemetry;
#[cfg(feature = "cuda")]
pub(crate) mod cuda_context;
pub mod device_store;
pub mod ensemble;
pub mod interaction;
pub mod layers;
#[cfg(feature = "rayon")]
pub mod parallel;
pub mod telemetry;

pub use rustsim_broadphase;
pub use rustsim_core;
pub use rustsim_crowd;
pub use rustsim_geometry;
pub use rustsim_io;
pub use rustsim_mobility;
pub use rustsim_modes;
pub use rustsim_pathfinding;
pub use rustsim_schedulers;
pub use rustsim_spaces;
pub use rustsim_traffic;
pub use rustsim_transit;
pub use rustsim_vehicle;

/// Convenience re-exports for common usage.
///
/// Importing `use rustsim::prelude::*` brings in all core types, spaces,
/// schedulers, pathfinding, I/O utilities, transport semantics, and compute functions.
pub mod prelude {
    #[cfg(feature = "cuda")]
    pub use crate::columnar_runtime::CudaKernelAbi;
    pub use crate::columnar_runtime::{
        ColumnarAgentBatch, ColumnarAgentBatchF64, ColumnarLifecycleCommand,
        ColumnarLifecycleCommandF64, ColumnarLifecycleReport, ColumnarPhaseBackend,
        ColumnarPhaseTiming, ColumnarRuntime, ColumnarRuntimeError, ColumnarRuntimeF64,
        ColumnarStepTiming,
    };
    #[cfg(feature = "cuda")]
    pub use crate::compute::cuda_batch_step;
    #[cfg(feature = "cuda")]
    pub use crate::compute::cuda_batch_step_pinned;
    #[cfg(feature = "rayon")]
    pub use crate::compute::par_batch_step;
    pub use crate::compute::{
        auto_batch_step, auto_device_step, cpu_batch_step, cpu_batch_step_f64, detect_backend,
        AccelStepResult, ComputeBackend,
    };
    pub use crate::control_plane::{
        CheckpointPolicy, ControlPlaneConfig, ControlledStep, EndpointPartitionExecutor,
        EngineCheckpoint, EngineControlPlane, EngineControlPlaneError, EngineMetrics,
        EnginePhaseMetric, ExternalPartitionClient, LocalThreadedPartitionExecutor,
        PartitionAssignment, PartitionCheckpoint, PartitionExecutablePhase,
        PartitionExecutionBackend, PartitionExecutionContext, PartitionExecutor,
        PartitionExecutorError, PartitionId, PartitionMode, PartitionPhaseReport, PartitionPlan,
        PartitionPlanError, PartitionTask, PartitionTaskResult, PartitionWorker, PartitionedStep,
        ReplayFingerprint, ReplayMode,
    };
    pub use crate::crowd_telemetry::{
        crowd_arrow_schema, crowd_observer, push_crowd_row, CROWD_BATCH_SIZE, CROWD_NUM_COLUMNS,
    };
    pub use crate::device_store::{
        DeviceSoaCheckpoint, DeviceSoaCheckpointF64, DeviceSoaMutationError, DeviceSoaRestoreError,
        DeviceSoaStore, DeviceSoaStoreF64, SoaColumnSchema, SoaColumnType,
    };
    pub use crate::ensemble::{Ensemble, ErrorLevel, RunPlan, RunResult};
    pub use crate::interaction::{
        DeviceNeighbor2D, DeviceSpatialCell2D, DeviceSpatialConfig2D, DeviceSpatialError,
        DeviceSpatialIndex2D,
    };
    pub use crate::layers::{LayerExecutor, LayerTiming, StepTiming};
    pub use crate::telemetry::{
        TelemetryError, TelemetryPipeline, TelemetryPipelineStats, TelemetryShutdownStats,
    };
    pub use rustsim_core::prelude::*;
    pub use rustsim_geometry::prelude::*;
    pub use rustsim_io::prelude::*;
    pub use rustsim_modes::prelude::*;
    pub use rustsim_pathfinding::prelude::*;
    pub use rustsim_spaces::prelude::*;
    pub use rustsim_traffic::prelude::*;
    // Domain-specific preludes exposing overlapping symbols (e.g.
    // `WallSegment`, `Vehicle`) are intentionally *not* glob-imported
    // here; access them via `rustsim::rustsim_crowd::prelude`,
    // `rustsim::rustsim_vehicle::prelude`, `rustsim::rustsim_transit::prelude`
    // and `rustsim::rustsim_mobility::prelude`.
}