pub trait IncrementalConstraint<S, Sc>: Send + Syncwhere
Sc: Score,{
// Required methods
fn evaluate(&self, solution: &S) -> Sc;
fn match_count(&self, solution: &S) -> usize;
fn initialize(&mut self, solution: &S) -> Sc;
fn on_insert(&mut self, solution: &S, entity_index: usize) -> Sc;
fn on_retract(&mut self, solution: &S, entity_index: usize) -> Sc;
fn reset(&mut self);
fn name(&self) -> &str;
// Provided methods
fn is_hard(&self) -> bool { ... }
fn constraint_ref(&self) -> ConstraintRef { ... }
fn get_matches(&self, _solution: &S) -> Vec<DetailedConstraintMatch<Sc>> { ... }
fn weight(&self) -> Sc { ... }
}Expand description
A single constraint with incremental scoring capability.
Unlike the trait-object Constraint trait, IncrementalConstraint is
designed for monomorphized code paths where the concrete type is known.
§Incremental Protocol
The incremental methods allow delta-based score updates:
- Call
initializeonce to populate internal state - Before changing an entity’s variable: call
on_retractwith old state - After changing the variable: call
on_insertwith new state - Score delta = insert_delta - retract_delta
This avoids full re-evaluation on every move.
Required Methods§
Sourcefn evaluate(&self, solution: &S) -> Sc
fn evaluate(&self, solution: &S) -> Sc
Full evaluation of this constraint.
Iterates all entities and computes the total score impact.
Use this for initial scoring; use on_insert/on_retract for deltas.
Sourcefn match_count(&self, solution: &S) -> usize
fn match_count(&self, solution: &S) -> usize
Returns the number of matches for this constraint.
Sourcefn initialize(&mut self, solution: &S) -> Sc
fn initialize(&mut self, solution: &S) -> Sc
Initializes internal state by inserting all entities.
Must be called before using incremental methods (on_insert/on_retract).
Returns the total score from initialization.
Sourcefn on_insert(&mut self, solution: &S, entity_index: usize) -> Sc
fn on_insert(&mut self, solution: &S, entity_index: usize) -> Sc
Called when an entity is inserted or its variable changes.
Returns the score delta from this insertion.
Sourcefn on_retract(&mut self, solution: &S, entity_index: usize) -> Sc
fn on_retract(&mut self, solution: &S, entity_index: usize) -> Sc
Called when an entity is retracted or before its variable changes.
Returns the score delta (negative) from this retraction.
Provided Methods§
Sourcefn constraint_ref(&self) -> ConstraintRef
fn constraint_ref(&self) -> ConstraintRef
Returns the constraint reference (package + name).
Default implementation constructs from name().
Sourcefn get_matches(&self, _solution: &S) -> Vec<DetailedConstraintMatch<Sc>>
fn get_matches(&self, _solution: &S) -> Vec<DetailedConstraintMatch<Sc>>
Returns detailed matches with entity justifications.
The default implementation returns an empty vector. Constraints should override this to provide detailed match information including the entities involved in each constraint violation.
This enables score explanation features without requiring all constraints to implement detailed tracking.