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    // Calculates the current score from scratch without mutating the committed score state.
38    fn fresh_score(&self) -> Option<S::Score> {
39        None
40    }
41
42    // Returns the solution descriptor for this solution type.
43    fn solution_descriptor(&self) -> &SolutionDescriptor;
44
45    // Clones the working solution.
46    fn clone_working_solution(&self) -> S;
47
48    // Called before a planning variable is changed.
49    fn before_variable_changed(&mut self, descriptor_index: usize, entity_index: usize);
50
51    // Called after a planning variable is changed.
52    fn after_variable_changed(&mut self, descriptor_index: usize, entity_index: usize);
53
54    // Returns the number of entities for a given descriptor index.
55    fn entity_count(&self, descriptor_index: usize) -> Option<usize>;
56
57    // Returns the total number of entities across all collections.
58    fn total_entity_count(&self) -> Option<usize>;
59
60    // Returns immutable scoring-constraint metadata known to this director.
61    fn constraint_metadata(&self) -> Vec<ConstraintMetadata<'_>>;
62
63    // Returns whether a known constraint is hard.
64    fn constraint_is_hard(&self, constraint_ref: &ConstraintRef) -> Option<bool> {
65        let metadata = self.constraint_metadata();
66        metadata
67            .iter()
68            .find(|metadata| metadata.constraint_ref == constraint_ref)
69            .map(|metadata| metadata.is_hard)
70    }
71
72    // Returns true if this score director supports incremental scoring.
73    fn is_incremental(&self) -> bool {
74        false
75    }
76
77    // Snapshots the committed score state so speculative evaluation can roll
78    // back exactly.
79    fn snapshot_score_state(&self) -> DirectorScoreState<S::Score> {
80        let solution_score = self.working_solution().score();
81        DirectorScoreState {
82            solution_score,
83            committed_score: solution_score,
84            initialized: solution_score.is_some(),
85        }
86    }
87
88    // Restores a previously snapshotted committed score state.
89    fn restore_score_state(&mut self, state: DirectorScoreState<S::Score>) {
90        self.working_solution_mut().set_score(state.solution_score);
91    }
92
93    // Resets the score director state.
94    fn reset(&mut self) {}
95}
solverforge_scoring/director/traits.rs

solverforge_scoring/director/
traits.rs
