rustsim_core/
lib.rs

1//! Core ABM engine for rustsim.
2//!
3//! This crate provides the foundational abstractions for agent-based modelling:
4//!
5//! - **[`Agent`]** trait - the interface every agent type must implement.
6//! - **[`Model`]** trait - the abstract model interface exposing time, RNG, space, and agents.
7//! - **[`StandardModel`]** - discrete-time model with per-agent and per-model step functions.
8//! - **[`EventQueueModel`]** - continuous-time model driven by a deterministic event queue.
9//! - **[`AgentStore`]** - container trait with [`HashMapStore`] and [`VecStore`] implementations.
10//! - **[`Scheduler`]** - trait for controlling agent activation order each step.
11//! - **[`StepContext`]** - safe, borrow-checked context passed to agent step functions.
12//! - **Core semantic types** - shared identifiers and interfaces for nodes, edges, zones, levels, and connectors.
13//! - **[`SoaExtractable`]** - trait for extracting agent data into GPU-friendly SoA buffers.
14//!
15//! # Architecture
16//!
17//! The crate mirrors the design of Julia's [Agents.jl](https://github.com/JuliaDynamics/Agents.jl):
18//!
19//! 1. Define agent types implementing [`Agent`].
20//! 2. Choose a space (from `rustsim-spaces`) and a scheduler.
21//! 3. Wire up step functions and build a [`StandardModel`] or [`EventQueueModel`].
22//! 4. Call [`StandardModel::step`] / [`StandardModel::step_n`] to advance the simulation.
23//! 5. Use [`collect_step`] to gather data at each step.
24//!
25//! # Interior Mutability
26//!
27//! Agent stores use [`RefCell`]-based interior mutability so that agent step functions
28//! can read other agents while mutating the current one. This means the model types
29//! are `!Send` and `!Sync` - see the top-level `rustsim` crate for compute-routing
30//! alternatives.
31//!
32//! [`Agent`]: agent::Agent
33//! [`Model`]: model::Model
34//! [`StandardModel`]: standard::StandardModel
35//! [`StandardModel::step`]: standard::StandardModel::step
36//! [`StandardModel::step_n`]: standard::StandardModel::step_n
37//! [`EventQueueModel`]: event_queue::EventQueueModel
38//! [`AgentStore`]: store::AgentStore
39//! [`HashMapStore`]: store::HashMapStore
40//! [`VecStore`]: store::VecStore
41//! [`Scheduler`]: scheduler::Scheduler
42//! [`StepContext`]: step_context::StepContext
43//! [`SoaExtractable`]: soa::SoaExtractable
44//! [`collect_step`]: collect::collect_step
45//! [`RefCell`]: std::cell::RefCell
46
47pub mod agent;
48pub mod avoidance;
49pub mod collect;
50pub mod event_queue;
51pub mod interaction;
52pub mod messaging;
53pub mod model;
54pub mod scheduler;
55pub mod soa;
56pub mod space;
57pub mod standard;
58pub mod step_context;
59pub mod store;
60pub mod two_phase;
61pub mod types;
62
63pub mod prelude {
64    pub use crate::agent::Agent;
65    pub use crate::avoidance::{
66        desired_force_2d, desired_force_3d, integrate_euler_2d, integrate_euler_3d,
67        social_repulsion_2d, social_repulsion_3d, wall_repulsion_2d, wall_repulsion_3d,
68        SocialForceParams, WallSegment, WallSegment3D,
69    };
70    pub use crate::collect::collect_step;
71    pub use crate::event_queue::{EventContext, EventQueueModel};
72    pub use crate::interaction::{
73        add_agent, add_agent_random, all_ids, move_agent, nearby_agents, nearby_agents_except,
74        nearby_ids, nearby_ids_except, random_agent, random_id, remove_agent, InteractionError,
75        PositionedAgent, SpaceInteraction,
76    };
77    pub use crate::messaging::{
78        BruteForceMessages, MessageConfigError, MessagePhaseError, SpatialIter3D,
79        SpatialMessages2D, SpatialMessages3D,
80    };
81    pub use crate::model::Model;
82    pub use crate::scheduler::{ById, ByProperty, Fastest, PartiallyRandom, Randomly, Scheduler};
83    pub use crate::soa::{SoaExtractable, SoaExtractableF64};
84    pub use crate::space::Space;
85    pub use crate::standard::{HasAgentIds, StandardModel};
86    pub use crate::step_context::StepContext;
87    pub use crate::store::{AgentStore, HashMapStore, VecStore};
88    pub use crate::two_phase::{
89        two_phase_brute_force, two_phase_spatial_2d, two_phase_spatial_3d, TwoPhaseResult,
90    };
91    pub use crate::types::{
92        AgentId, Connective, ConnectorMetadata, ConnectorType, EdgeId, LevelId, LevelMetadata,
93        LevelRelation, Leveled, NodeId, ProcessingPointMetadata, SemanticEntity, Time, ZoneId,
94        ZoneMetadata, Zoned,
95    };
96}
rustsim_core/lib.rs

rustsim_core/
lib.rs
