solverforge_scoring/director/
traits.rs

1// Score director trait definition.
2
3use solverforge_core::domain::{PlanningSolution, SolutionDescriptor};
4use solverforge_core::ConstraintRef;
5
6use crate::api::constraint_set::ConstraintMetadata;
7
8/// Snapshot of the director's committed score state.
9///
10/// Construction and local-search trial evaluation use this to restore the
11/// wrapped director after speculative scoring.
12#[derive(Debug, PartialEq, Eq)]
13pub struct DirectorScoreState<Sc> {
14    pub solution_score: Option<Sc>,
15    pub committed_score: Option<Sc>,
16    pub initialized: bool,
17}
18
19/* The score director manages solution state and score calculation.
20
21It is responsible for:
22- Maintaining the working solution
23- Calculating scores (incrementally when possible)
24- Notifying about variable changes for incremental updates
25- Providing access to solution metadata via descriptors
26*/
27pub trait Director<S: PlanningSolution>: Send {
28    // Returns a reference to the working solution.
29    fn working_solution(&self) -> &S;
30
31    // Returns a mutable reference to the working solution.
32    fn working_solution_mut(&mut self) -> &mut S;
33
34    // Calculates and returns the current score.
35    fn calculate_score(&mut self) -> S::Score;
36
37    // Returns the solution descriptor for this solution type.
38    fn solution_descriptor(&self) -> &SolutionDescriptor;
39
40    // Clones the working solution.
41    fn clone_working_solution(&self) -> S;
42
43    // Called before a planning variable is changed.
44    fn before_variable_changed(&mut self, descriptor_index: usize, entity_index: usize);
45
46    // Called after a planning variable is changed.
47    fn after_variable_changed(&mut self, descriptor_index: usize, entity_index: usize);
48
49    // Returns the number of entities for a given descriptor index.
50    fn entity_count(&self, descriptor_index: usize) -> Option<usize>;
51
52    // Returns the total number of entities across all collections.
53    fn total_entity_count(&self) -> Option<usize>;
54
55    // Returns immutable scoring-constraint metadata known to this director.
56    fn constraint_metadata(&self) -> &[ConstraintMetadata];
57
58    // Returns whether a known constraint is hard.
59    fn constraint_is_hard(&self, constraint_ref: &ConstraintRef) -> Option<bool> {
60        self.constraint_metadata()
61            .iter()
62            .find(|metadata| &metadata.constraint_ref == constraint_ref)
63            .map(|metadata| metadata.is_hard)
64    }
65
66    // Returns true if this score director supports incremental scoring.
67    fn is_incremental(&self) -> bool {
68        false
69    }
70
71    // Snapshots the committed score state so speculative evaluation can roll
72    // back exactly.
73    fn snapshot_score_state(&self) -> DirectorScoreState<S::Score> {
74        let solution_score = self.working_solution().score();
75        DirectorScoreState {
76            solution_score,
77            committed_score: solution_score,
78            initialized: solution_score.is_some(),
79        }
80    }
81
82    // Restores a previously snapshotted committed score state.
83    fn restore_score_state(&mut self, state: DirectorScoreState<S::Score>) {
84        self.working_solution_mut().set_score(state.solution_score);
85    }
86
87    // Resets the score director state.
88    fn reset(&mut self) {}
89
90    /* Registers a typed undo closure.
91
92    Called by moves after applying changes to enable automatic undo.
93    The closure will be called in reverse order during `undo_changes()`.
94
95    Default implementation does nothing (for non-recording directors).
96    */
97    fn register_undo(&mut self, _undo: Box<dyn FnOnce(&mut S) + Send>) {
98        // Default: no-op - only RecordingDirector stores undo closures
99    }
100}
solverforge_scoring/director/traits.rs

solverforge_scoring/director/
traits.rs
