solverforge-scoring 0.25.0

Incremental constraint scoring for SolverForge
Documentation
//! Score director trait definition.

use solverforge_core::domain::{PlanningSolution, SolutionDescriptor};
use solverforge_core::ConstraintRef;

use crate::api::constraint_set::ConstraintMetadata;

/// Snapshot of the director's committed score state.
///
/// Construction and local-search trial evaluation use this to restore the
/// wrapped director after speculative scoring.
#[derive(Debug, PartialEq, Eq)]
pub struct DirectorScoreState<Sc> {
    /// The score stored on the working solution.
    pub solution_score: Option<Sc>,
    /// The director's cached committed score, `None` before initialization.
    pub committed_score: Option<Sc>,
    /// Whether incremental state was initialized.
    pub initialized: bool,
}

/// The score director manages solution state and score calculation.
///
/// It is responsible for:
/// - Maintaining the working solution
/// - Calculating scores (incrementally when possible)
/// - Notifying about variable changes for incremental updates
/// - Providing access to solution metadata via descriptors
pub trait Director<S: PlanningSolution>: Send {
    /// Returns a reference to the working solution.
    fn working_solution(&self) -> &S;

    /// Returns a mutable reference to the working solution.
    fn working_solution_mut(&mut self) -> &mut S;

    /// Calculates and returns the current score.
    fn calculate_score(&mut self) -> S::Score;

    /// Calculates the current score from scratch without mutating the committed score state.
    fn fresh_score(&self) -> Option<S::Score> {
        None
    }

    /// Turns score assertion on or off: while on, every [`Self::calculate_score`]
    /// panics when the score differs from [`Self::fresh_score`]. A director
    /// without a fresh calculation (`fresh_score` returns `None`) has nothing
    /// to compare against, so the default does nothing.
    fn set_score_assertion(&mut self, enabled: bool) {
        let _ = enabled;
    }

    /// Returns the solution descriptor for this solution type.
    fn solution_descriptor(&self) -> &SolutionDescriptor;

    /// Clones the working solution.
    fn clone_working_solution(&self) -> S;

    /// Called before a planning variable is changed.
    fn before_variable_changed(&mut self, descriptor_index: usize, entity_index: usize);

    /// Called after a planning variable is changed.
    fn after_variable_changed(&mut self, descriptor_index: usize, entity_index: usize);

    /// Returns the number of entities for a given descriptor index.
    fn entity_count(&self, descriptor_index: usize) -> Option<usize>;

    /// Returns the total number of entities across all collections.
    fn total_entity_count(&self) -> Option<usize>;

    /// Returns immutable scoring-constraint metadata known to this director.
    fn constraint_metadata(&self) -> Vec<ConstraintMetadata<'_>>;

    /// Returns whether a known constraint is hard.
    fn constraint_is_hard(&self, constraint_ref: &ConstraintRef) -> Option<bool> {
        let metadata = self.constraint_metadata();
        metadata
            .iter()
            .find(|metadata| metadata.constraint_ref == constraint_ref)
            .map(|metadata| metadata.is_hard)
    }

    /// Returns true if this score director supports incremental scoring.
    fn is_incremental(&self) -> bool {
        false
    }

    /// Snapshots the committed score state so speculative evaluation can roll
    /// back exactly.
    fn snapshot_score_state(&self) -> DirectorScoreState<S::Score> {
        let solution_score = self.working_solution().score();
        DirectorScoreState {
            solution_score,
            committed_score: solution_score,
            initialized: solution_score.is_some(),
        }
    }

    /// Restores a previously snapshotted committed score state.
    fn restore_score_state(&mut self, state: DirectorScoreState<S::Score>) {
        self.working_solution_mut().set_score(state.solution_score);
    }

    /// Discards incremental score state after the working solution was
    /// rewritten outside the variable-change protocol. The next
    /// `calculate_score` reinitializes from the rewritten solution.
    fn reset(&mut self) {}

    /// Builds an independent evaluator replica: an owned copy of the working
    /// solution with freshly initialized incremental constraint state.
    ///
    /// Returns `None` when this director cannot construct one.
    fn fork_replica(&self) -> Option<Self>
    where
        Self: Sized,
    {
        None
    }

    /// Builds an independent director of the same kind over `solution`, for
    /// solving a sub-problem such as one partition of partitioned search. Its
    /// incremental state is uninitialized until its first score calculation.
    ///
    /// Returns `None` when this director cannot construct one.
    fn fork_for_solution(&self, _solution: S) -> Option<Self>
    where
        Self: Sized,
    {
        None
    }
}