Struct BalanceConstraint 

pub struct BalanceConstraint<S, A, K, E, F, KF, Sc>
where
    Sc: Score,
{ /* private fields */ }

Zero-erasure balance constraint that penalizes uneven load distribution.

This constraint:

1. Groups entities by key (e.g., employee_id)
2. Counts how many entities belong to each group
3. Computes population standard deviation across all group counts
4. Multiplies the base score by std_dev to produce the final score

The key difference from GroupedUniConstraint is that balance computes a GLOBAL statistic, not per-group scores.

Type Parameters

• S - Solution type
• A - Entity type
• K - Group key type
• E - Extractor function for entities
• F - Filter type
• KF - Key function
• Sc - Score type

Example

use solverforge_scoring::constraint::balance::BalanceConstraint;
use solverforge_scoring::api::constraint_set::IncrementalConstraint;
use solverforge_scoring::stream::filter::TrueFilter;
use solverforge_core::{ConstraintRef, ImpactType, HardSoftDecimalScore};

#[derive(Clone)]
struct Shift { employee_id: Option<usize> }

#[derive(Clone)]
struct Solution { shifts: Vec<Shift> }

// Base score of 1000 soft per unit of std_dev
let constraint = BalanceConstraint::new(
    ConstraintRef::new("", "Balance workload"),
    ImpactType::Penalty,
    |s: &Solution| &s.shifts,
    TrueFilter,
    |shift: &Shift| shift.employee_id,
    HardSoftDecimalScore::of_soft(1),  // 1 soft per unit std_dev (scaled internally)
    false,
);

let solution = Solution {
    shifts: vec![
        Shift { employee_id: Some(0) },
        Shift { employee_id: Some(0) },
        Shift { employee_id: Some(0) },
        Shift { employee_id: Some(1) },
        Shift { employee_id: None },  // Unassigned, filtered out
    ],
};

// Employee 0: 3 shifts, Employee 1: 1 shift
// Mean = 2, Variance = ((3-2)² + (1-2)²) / 2 = 1
// StdDev = 1.0, Score = -1 soft (base_score * std_dev, negated for penalty)
let score = constraint.evaluate(&solution);
assert_eq!(score, HardSoftDecimalScore::of_soft(-1));

Implementations

impl<S, A, K, E, F, KF, Sc> BalanceConstraint<S, A, K, E, F, KF, Sc>

where S: Send + Sync + 'static, A: Clone + Send + Sync + 'static, K: Clone + Eq + Hash + Send + Sync + 'static, E: Fn(&S) -> &[A] + Send + Sync, F: UniFilter<A>, KF: Fn(&A) -> Option<K> + Send + Sync, Sc: Score + 'static,

pub fn new( constraint_ref: ConstraintRef, impact_type: ImpactType, extractor: E, filter: F, key_fn: KF, base_score: Sc, is_hard: bool, ) -> Self

Creates a new zero-erasure balance constraint.

Arguments

• constraint_ref - Identifier for this constraint
• impact_type - Whether to penalize or reward
• extractor - Function to get entity slice from solution
• filter - Filter to select which entities to consider
• key_fn - Function to extract group key (returns None to skip entity)
• base_score - Score per unit of standard deviation
• is_hard - Whether this is a hard constraint

Trait Implementations

impl<S, A, K, E, F, KF, Sc> Debug for BalanceConstraint<S, A, K, E, F, KF, Sc>

where Sc: Score,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<S, A, K, E, F, KF, Sc> IncrementalConstraint<S, Sc> for BalanceConstraint<S, A, K, E, F, KF, Sc>

where S: Send + Sync + 'static, A: Clone + Send + Sync + 'static, K: Clone + Eq + Hash + Send + Sync + 'static, E: Fn(&S) -> &[A] + Send + Sync, F: UniFilter<A>, KF: Fn(&A) -> Option<K> + Send + Sync, Sc: Score + 'static,

fn evaluate(&self, solution: &S) -> Sc

Full evaluation of this constraint.

fn match_count(&self, solution: &S) -> usize

Returns the number of matches for this constraint.

fn initialize(&mut self, solution: &S) -> Sc

Initializes internal state by inserting all entities.

fn on_insert(&mut self, solution: &S, entity_index: usize) -> Sc

Called when an entity is inserted or its variable changes.

fn on_retract(&mut self, solution: &S, entity_index: usize) -> Sc

Called when an entity is retracted or before its variable changes.

fn reset(&mut self)

Resets internal state for a new solving session.

fn name(&self) -> &str

Returns the constraint name.

fn is_hard(&self) -> bool

Returns true if this is a hard constraint.

fn constraint_ref(&self) -> ConstraintRef

Returns the constraint reference (package + name).

fn get_matches(&self, _solution: &S) -> Vec<DetailedConstraintMatch<Sc>>

Returns detailed matches with entity justifications.

fn weight(&self) -> Sc

Returns the constraint weight (score per match).