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
//! # Traffic Lights Module
//!
//! Traffic signal control system for managing vehicle flow at intersections in cellular automata simulation.
//!
//! This module provides a traffic light system with signal phases, timing control,
//! and group-based management of cells that share the same traffic signal behavior.
//!
//! ## Architecture
//!
//! ### Three-layer system. Example:
//! ```text
//! TrafficLight - Layer #1 (intersection)
//! ├── TrafficLightGroup (North-South) - Layer #2 (group of cells)
//! │ ├── Signal phases: [Red, Yellow, Green] - Layer #3 (signal states)
//! │ └── Controlled cells: [1, 2, 3] - Layer #3 (cells IDs)
//! ├── TrafficLightGroup (East-West)
//! │ ├── Signal phases: [Green, Green, Red]
//! │ └── Controlled cells: [10, 11, 12]
//! └── Phase times: [10s, 3s, 15s] - Layer #1 (timing)
//! ```
//!
//! Phase times are shared across all groups in a traffic light, while each group
//! can have its own sequence of signal states. Number of phases times array must
//! match the length of signal states in each group.
//!
//! ## Components
//!
//! ### Core Structures
//! - [`lights::TrafficLight`] - Traffic light controller with timing and groups. One controller == one intersection
//! - [`groups::TrafficLightGroup`] - Group of cells sharing the same coordinated signal behavior
//! - [`signals::SignalType`] - Individual signal states (Red, Yellow, Green, etc.)
//! - [`lights::TrafficLightID`] - Unique identifier for traffic lights
//!
//! ### Builder Pattern
//! - [`lights::TrafficLightBuilder`] - API builder for traffic lights
//! - [`groups::TrafficLightGroupBuilder`] - API builder for signal groups
//!
//! ### Error Handling
//! - [`lights::TrafficLightError`] - Traffic light operation errors
//! - [`signals::SignalTypeError`] - Signal parsing and validation errors
//!
//! ## Signal Types
//!
//! Reference for signal states based on SUMO definitions:
//! https://sumo.dlr.de/docs/Simulation/Traffic_Lights.html#signal_state_definitions
//!
//!
//! | Signal | Code | Meaning |
//! |--------|------|---------|
//! | `Red` | `r` | Vehicles must stop |
//! | `Yellow` | `y` | Prepare to stop |
//! | `Green` | `g` | Vehicles may proceed |
//! | `GreenPriority` | `G` | Vehicles proceed with priority |
//! | `GreenRight` | `s` | Vehicles may proceed only right turn |
//! | `RedYellow` | `u` | Prepare for green (vehicles still stop) |
//! | `Blinking` | `o` | Vehicles must yield |
//! | `NoSignal` | `O` | Vehicles have right of way |
//! | `Undefined` | - | Uninitialized state |
//!
//! ## Usage Examples
//!
//! ### Basic four-way intersection
//!
//! ```rust
//! use micro_traffic_sim_core::traffic_lights::{
//! lights::{TrafficLight, TrafficLightID},
//! groups::TrafficLightGroup,
//! signals::SignalType
//! };
//! use micro_traffic_sim_core::geom::new_point;
//!
//! // Create signal groups for each direction
//! let north_south_group = TrafficLightGroup::new(1)
//! .with_label("North-South".to_string())
//! .with_cells_ids(vec![1, 2, 3]) // Cells for N-S traffic
//! .with_signal(vec![SignalType::Green, SignalType::Yellow, SignalType::Red])
//! .build();
//!
//! let east_west_group = TrafficLightGroup::new(2)
//! .with_label("East-West".to_string())
//! .with_cells_ids(vec![10, 11, 12]) // Cells for E-W traffic
//! .with_signal(vec![SignalType::Red, SignalType::RedYellow, SignalType::Green])
//! .build();
//!
//! // Create traffic light with timing
//! let mut intersection = TrafficLight::new(1)
//! .with_coordinates(new_point(100.0, 200.0, None))
//! .with_groups(vec![north_south_group, east_west_group])
//! .with_phases_times(vec![15, 3, 15]) // Green: 15s, Yellow: 3s, Red: 15s
//! .build();
//!
//! // Simulate traffic light operation
//! for step in 0..40 {
//! intersection.step();
//! let phase = intersection.get_active_phase();
//! let time = intersection.get_current_time();
//! println!("Step {}: Phase {}, Time {}", step, phase, time);
//! }
//! ```
//!
//! ## Timing and Phase Management
//!
//! ### Phase Cycling
//! Traffic lights automatically cycle through phases based on configured timing:
//! - **Timer increments** each simulation step
//! - **Phase changes** when timer reaches phase duration
//! - **Automatic reset** to phase 0 after completing all phases
//!
//! ### Group Synchronization
//! All groups in a traffic light share the same phase timing but can have
//! different signal states per phase, enabling complex intersection patterns.
//!
//! ## Integration
//!
//! - **Grid System**: Controls cells via [`CellID`](crate::grid::cell::CellID) references
//! - **Geometry**: Uses [`PointType`](crate::geom::PointType) for spatial positioning
//! - **Coordination**: Should be used with [`ZoneType::Coordination`](crate::grid::zones::ZoneType::Coordination) cells
//!