solverforge_solver/manager/config.rs
1//! Configuration types for solver phases.
2//!
3//! This module contains enums for configuring different types of solver phases:
4//!
5//! - [`LocalSearchType`]: Algorithm selection for local search phases
6//! - [`ConstructionType`]: Algorithm selection for construction heuristic phases
7//! - [`PhaseConfig`]: Complete phase configuration
8
9/// Type of local search algorithm to use.
10///
11/// Different local search algorithms have different characteristics:
12///
13/// - [`HillClimbing`](Self::HillClimbing): Simple, fast, but can get stuck in local optima
14/// - [`TabuSearch`](Self::TabuSearch): Avoids revisiting recent states
15/// - [`SimulatedAnnealing`](Self::SimulatedAnnealing): Probabilistic acceptance of worse moves
16/// - [`LateAcceptance`](Self::LateAcceptance): Compares against historical scores
17///
18/// # Examples
19///
20/// ```
21/// use solverforge_solver::manager::LocalSearchType;
22///
23/// // Hill climbing - simplest approach
24/// let hill = LocalSearchType::HillClimbing;
25/// assert_eq!(hill, LocalSearchType::default());
26///
27/// // Tabu search with memory of 10 recent moves
28/// let tabu = LocalSearchType::TabuSearch { tabu_size: 10 };
29///
30/// // Simulated annealing with temperature decay
31/// let sa = LocalSearchType::SimulatedAnnealing {
32/// starting_temp: 1.0,
33/// decay_rate: 0.995,
34/// };
35///
36/// // Late acceptance comparing to 100 steps ago
37/// let late = LocalSearchType::LateAcceptance { size: 100 };
38/// ```
39#[derive(Debug, Clone, Copy, PartialEq)]
40pub enum LocalSearchType {
41 /// Hill climbing: only accept improving moves.
42 ///
43 /// This is the simplest local search strategy. It only accepts moves
44 /// that improve the score. Fast but can easily get stuck in local optima.
45 ///
46 /// # Example
47 ///
48 /// ```
49 /// use solverforge_solver::manager::LocalSearchType;
50 ///
51 /// let acceptor = LocalSearchType::HillClimbing;
52 /// ```
53 HillClimbing,
54
55 /// Tabu search: avoid recently visited states.
56 ///
57 /// Maintains a list of recently made moves and forbids reversing them.
58 /// This helps escape local optima by forcing exploration.
59 ///
60 /// # Example
61 ///
62 /// ```
63 /// use solverforge_solver::manager::LocalSearchType;
64 ///
65 /// // Keep last 7 moves in tabu list
66 /// let tabu = LocalSearchType::TabuSearch { tabu_size: 7 };
67 /// ```
68 TabuSearch {
69 /// Size of the tabu list.
70 tabu_size: usize,
71 },
72
73 /// Simulated annealing: accept worse moves with decreasing probability.
74 ///
75 /// Initially accepts worse moves with high probability, but as the
76 /// "temperature" decreases, it becomes more selective. Good for
77 /// escaping local optima early in the search.
78 ///
79 /// # Example
80 ///
81 /// ```
82 /// use solverforge_solver::manager::LocalSearchType;
83 ///
84 /// // Start with temperature 1.0, decay by 0.1% per step
85 /// let sa = LocalSearchType::SimulatedAnnealing {
86 /// starting_temp: 1.0,
87 /// decay_rate: 0.999,
88 /// };
89 /// ```
90 SimulatedAnnealing {
91 /// Initial temperature.
92 starting_temp: f64,
93 /// Temperature decay rate per step.
94 decay_rate: f64,
95 },
96
97 /// Late acceptance: compare against score from N steps ago.
98 ///
99 /// Accepts a move if the new score is better than the score from
100 /// N steps ago. Provides a balance between exploration and exploitation.
101 ///
102 /// # Example
103 ///
104 /// ```
105 /// use solverforge_solver::manager::LocalSearchType;
106 ///
107 /// // Compare against score from 400 steps ago
108 /// let late = LocalSearchType::LateAcceptance { size: 400 };
109 /// ```
110 LateAcceptance {
111 /// Number of steps to look back.
112 size: usize,
113 },
114
115 /// Value tabu search: forbid recently assigned values.
116 ///
117 /// Remembers recently assigned values and forbids reassigning them.
118 /// Different from entity tabu in that it tracks the values themselves,
119 /// not the entity-variable combinations.
120 ///
121 /// # Example
122 ///
123 /// ```
124 /// use solverforge_solver::manager::LocalSearchType;
125 ///
126 /// // Forbid last 5 assigned values
127 /// let value_tabu = LocalSearchType::ValueTabuSearch { value_tabu_size: 5 };
128 /// ```
129 ValueTabuSearch {
130 /// Number of recent values to forbid.
131 value_tabu_size: usize,
132 },
133
134 /// Move tabu search: forbid recently made moves.
135 ///
136 /// Remembers recently made moves (by hash) and forbids making the same
137 /// move again. Supports aspiration criterion: tabu moves can be accepted
138 /// if they lead to a new best solution.
139 ///
140 /// # Example
141 ///
142 /// ```
143 /// use solverforge_solver::manager::LocalSearchType;
144 ///
145 /// // Forbid last 10 moves, with aspiration enabled
146 /// let move_tabu = LocalSearchType::MoveTabuSearch {
147 /// move_tabu_size: 10,
148 /// aspiration_enabled: true,
149 /// };
150 /// ```
151 MoveTabuSearch {
152 /// Number of recent moves to forbid.
153 move_tabu_size: usize,
154 /// Whether to allow tabu moves that reach new best score.
155 aspiration_enabled: bool,
156 },
157}
158
159impl Default for LocalSearchType {
160 /// Returns [`HillClimbing`](Self::HillClimbing) as the default.
161 ///
162 /// # Example
163 ///
164 /// ```
165 /// use solverforge_solver::manager::LocalSearchType;
166 ///
167 /// let default = LocalSearchType::default();
168 /// assert_eq!(default, LocalSearchType::HillClimbing);
169 /// ```
170 fn default() -> Self {
171 LocalSearchType::HillClimbing
172 }
173}
174
175/// Type of construction heuristic to use.
176///
177/// Construction heuristics build an initial solution by assigning values
178/// to uninitialized planning variables. The type determines how values
179/// are selected:
180///
181/// - [`FirstFit`](Self::FirstFit): Fast, takes first valid value
182/// - [`BestFit`](Self::BestFit): Slower, evaluates all options to find best
183///
184/// # Examples
185///
186/// ```
187/// use solverforge_solver::manager::ConstructionType;
188///
189/// // First fit - faster but may produce lower quality initial solution
190/// let fast = ConstructionType::FirstFit;
191/// assert_eq!(fast, ConstructionType::default());
192///
193/// // Best fit - slower but produces better initial solution
194/// let best = ConstructionType::BestFit;
195/// ```
196#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
197pub enum ConstructionType {
198 /// First fit: accept first valid assignment.
199 ///
200 /// Assigns the first value that produces a feasible solution.
201 /// Fast but may not produce an optimal initial solution.
202 ///
203 /// # Example
204 ///
205 /// ```
206 /// use solverforge_solver::manager::ConstructionType;
207 ///
208 /// let construction = ConstructionType::FirstFit;
209 /// ```
210 #[default]
211 FirstFit,
212
213 /// Best fit: evaluate all options, pick best score.
214 ///
215 /// Evaluates all possible values and selects the one that produces
216 /// the best score. Slower but produces a higher quality initial solution.
217 ///
218 /// # Example
219 ///
220 /// ```
221 /// use solverforge_solver::manager::ConstructionType;
222 ///
223 /// let construction = ConstructionType::BestFit;
224 /// ```
225 BestFit,
226}
227
228/// Configuration for a phase.
229///
230/// This enum represents the configuration for different types of solver phases.
231/// Use this with the builder to configure your solving strategy.
232///
233/// # Examples
234///
235/// ```
236/// use solverforge_solver::manager::{PhaseConfig, ConstructionType, LocalSearchType};
237///
238/// // Construction phase configuration
239/// let construction = PhaseConfig::ConstructionHeuristic {
240/// construction_type: ConstructionType::BestFit,
241/// };
242///
243/// // Local search phase with step limit
244/// let local_search = PhaseConfig::LocalSearch {
245/// search_type: LocalSearchType::TabuSearch { tabu_size: 7 },
246/// step_limit: Some(1000),
247/// };
248/// ```
249#[derive(Debug, Clone)]
250pub enum PhaseConfig {
251 /// Construction heuristic phase.
252 ///
253 /// Builds an initial solution by assigning values to uninitialized
254 /// planning variables.
255 ///
256 /// # Example
257 ///
258 /// ```
259 /// use solverforge_solver::manager::{PhaseConfig, ConstructionType};
260 ///
261 /// let config = PhaseConfig::ConstructionHeuristic {
262 /// construction_type: ConstructionType::FirstFit,
263 /// };
264 /// ```
265 ConstructionHeuristic {
266 /// Type of construction.
267 construction_type: ConstructionType,
268 },
269
270 /// Local search phase.
271 ///
272 /// Improves an existing solution by exploring neighboring solutions.
273 ///
274 /// # Example
275 ///
276 /// ```
277 /// use solverforge_solver::manager::{PhaseConfig, LocalSearchType};
278 ///
279 /// let config = PhaseConfig::LocalSearch {
280 /// search_type: LocalSearchType::HillClimbing,
281 /// step_limit: Some(500),
282 /// };
283 /// ```
284 LocalSearch {
285 /// Type of local search.
286 search_type: LocalSearchType,
287 /// Optional step limit for this phase.
288 step_limit: Option<u64>,
289 },
290}