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
//! # Simulation module
//!
//! **Top-level orchestration module** – Coordinates all major components of the cellular automata traffic simulation.
//!
//! This module manages the simulation session, grid storage, vehicle and trip management, traffic lights, and the step-by-step execution of the simulation pipeline.
//! It is the main entry point for running, controlling, and inspecting the simulation state.
//!
//! ## Purpose
//!
//! - Manages the entire simulation lifecycle and state
//! - Handles vehicle generation, movement, intentions, conflicts, and traffic lights
//! - Provides API for adding trips, vehicles, cells, traffic lights, and conflict zones
//! - Collects and returns simulation state after each step
//!
//! ## Simulation pipeline
//!
//! The simulation module executes the following pipeline in [`Session::step()`](crate::simulation::session::Session::step):
//! ```text
//! 1. Generate vehicles (trips)
//! 2. Update positions
//! 3. Traffic light updates
//! 4. Prepare intentions ← intentions module
//! 5. Collect conflicts ← conflicts module
//! 6. Solve conflicts ← conflicts module
//! 7. Execute movement ← movement module
//! 8. Collect state dump
//! ```
//!
//! ## Components
//!
//! - [`grids_storage::GridsStorage`] – Stores the vehicle grid and traffic lights
//! - [`session::Session`] – Main simulation controller, manages vehicles, trips, and simulation steps
//! - [`sessions_storage::SessionsStorage`] – Optional manager for multiple sessions with TTL-based expiration (server-side use)
//! - [`states::AutomataState`] – Snapshot of the simulation state at each step
//! - [`states::VehicleState`] – State of each vehicle at a given timestamp
//! - [`states::TrafficLightGroupState`] – State of each traffic light group at a given timestamp
//! - [`session::SessionError`] – Unified error type for all simulation operations
//!
//! ## Usage
//!
//! Create a session, add trips, vehicles, cells, and traffic lights, then run the simulation step-by-step:
//! ```rust
//! use micro_traffic_sim_core::grid::road_network::GridRoads;
//! use micro_traffic_sim_core::agents::Vehicle;
//! use micro_traffic_sim_core::trips::trip::Trip;
//! use micro_traffic_sim_core::traffic_lights::lights::{TrafficLight, TrafficLightID};
//! use micro_traffic_sim_core::simulation::session::Session;
//! use micro_traffic_sim_core::simulation::grids_storage::GridsStorage;
//! use micro_traffic_sim_core::verbose::VerboseLevel;
//! use std::collections::HashMap;
//!
//! let mut grid = GridRoads::new();
//! // Populate grid with cells
//! // ...
//! let vehicles: Vec<Vehicle> = vec![/* ... vehicles ... */];
//! // Prepare vehicles or use generator
//! // ...
//! let trips: Vec<Trip> = vec![/* ... trips ... */];
//! // Prepare trips
//! // ...
//! let tls: HashMap<TrafficLightID, TrafficLight> = HashMap::new();
//! // Prepare traffic lights
//! // ...
//! let grids_storage = GridsStorage::new()
//! .with_vehicles_net(grid)
//! .with_tls(tls)
//! .build();
//! let mut session = Session::new(grids_storage, None);
//! session.set_verbose_level(VerboseLevel::Main);
//! session.add_vehicles(vehicles);
//! for trip in trips.iter() {
//! session.add_trip(trip.clone());
//! }
//! let steps = 10;
//! for step in 0..steps {
//! match session.step() {
//! Ok(automata_state) => {
//! for v in automata_state.vehicles {
//! println!(
//! "{};{};{};{};{:.5};{}",
//! step,
//! v.id,
//! v.vehicle_type,
//! v.last_speed,
//! v.last_angle,
//! v.last_cell,
//! );
//! }
//! }
//! Err(e) => {
//! eprintln!("Error during simulation step {}: {:?}", step, e);
//! }
//! };
//! }
//! ```
//!
//! ## Error handling
//!
//! All errors from grid storage, intentions, conflicts, movement, and traffic lights are unified under [`session::SessionError`] for easier debugging.
//!
//! ## Integration
//!
//! The simulation module is the main entry point for running and controlling the traffic simulation. All other modules (intentions, conflicts, movement, traffic lights, trips) are coordinated here.