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
//! Simulation container for timestamp-based state queries.
//!
//! This module provides the `Simulation` container, which is the primary
//! consumer API for the behavioral-pathways library. Simulations hold
//! entities, events, and relationships with their associated timestamps,
//! enabling state queries at any point in time.
//!
//! # Usage Model
//!
//! ```ignore
//! use behaviorsim_rs::simulation::{Simulation, SimulationBuilder};
//! use behaviorsim_rs::entity::EntityBuilder;
//! use behaviorsim_rs::types::Timestamp;
//! use behaviorsim_rs::enums::Species;
//!
//! // Create a simulation with a reference date
//! let reference = Timestamp::from_ymd_hms(2024, 1, 1, 0, 0, 0);
//!
//! // Build an entity with a birth date
//! let entity = EntityBuilder::new()
//! .id("person_001")
//! .species(Species::Human)
//! .age(crate::types::Duration::years(30))
//! .birth_date(Timestamp::from_ymd_hms(1990, 6, 15, 0, 0, 0))
//! .build()
//! .unwrap();
//!
//! // Add entity with its anchor timestamp (when state was observed)
//! let anchor = Timestamp::from_ymd_hms(2024, 1, 1, 9, 0, 0);
//!
//! let mut sim = Simulation::new(reference);
//! sim.add_entity(entity, anchor);
//!
//! // Query state at any timestamp
//! let query_time = Timestamp::from_ymd_hms(2024, 6, 15, 12, 0, 0);
//! let handle = sim.entity(&EntityId::new("person_001").unwrap());
//! if let Some(h) = handle {
//! let state = h.state_at(query_time);
//! }
//! ```
//!
//! # Key Concepts
//!
//! - **Reference Date**: The simulation's reference point for time calculations
//! - **Anchor Timestamp**: When an entity's state was observed
//! - **Birth Date**: When an entity was born (for age calculations)
//! - **state_at()**: The core API for computing state at any timestamp
pub use ;
pub use ;
pub use ;