solverforge_solver/stats/

solver.rs

use std::cmp::Ordering;
use std::collections::BTreeMap;
use std::time::{Duration, Instant};

use super::{
    AppliedMoveTelemetry, CandidatePullTelemetry, CandidateTraceDisposition,
    CandidateTracePhasePlan, CandidateTracePullToken, CandidateTraceRecordDecision,
    CandidateTraceTelemetry, MoveTelemetry, SelectorTelemetry, SolverTelemetry, Throughput,
};

const APPLIED_MOVE_TRACE_LIMIT: usize = 8;

#[derive(Debug, Default)]
pub struct SolverStats {
    start_time: Option<Instant>,
    pause_started_at: Option<Instant>,
    // Total steps taken across all phases.
    pub step_count: u64,
    /// Total candidate moves actually yielded by cursors across all phases.
    /// Unrequested logical neighborhood tails are not generated work.
    pub moves_generated: u64,
    // Total moves evaluated across all phases.
    pub moves_evaluated: u64,
    // Total moves accepted across all phases.
    pub moves_accepted: u64,
    // Total moves applied across all phases.
    pub moves_applied: u64,
    pub moves_not_doable: u64,
    pub moves_acceptor_rejected: u64,
    pub moves_forager_ignored: u64,
    pub moves_hard_improving: u64,
    pub moves_hard_neutral: u64,
    pub moves_hard_worse: u64,
    pub conflict_repair_provider_generated: u64,
    pub conflict_repair_duplicate_filtered: u64,
    pub conflict_repair_illegal_filtered: u64,
    pub conflict_repair_not_doable_filtered: u64,
    pub conflict_repair_hard_improving: u64,
    pub conflict_repair_exposed: u64,
    // Total score calculations performed.
    pub score_calculations: u64,
    pub construction_slots_assigned: u64,
    pub construction_slots_kept: u64,
    pub construction_slots_no_doable: u64,
    pub scalar_assignment_required_remaining: u64,
    scalar_assignment_required_remaining_by_group: BTreeMap<&'static str, u64>,
    generation_time: Duration,
    evaluation_time: Duration,
    selector_stats: Vec<SelectorTelemetry>,
    move_stats: BTreeMap<&'static str, MoveTelemetry>,
    applied_move_trace: Vec<AppliedMoveTelemetry>,
    candidate_trace: Option<CandidateTraceTelemetry>,
}

impl SolverStats {
    /// Marks the start of solving.
    pub fn start(&mut self) {
        self.start_time = Some(Instant::now());
        self.pause_started_at = None;
    }

    pub fn elapsed(&self) -> Duration {
        match (self.start_time, self.pause_started_at) {
            (Some(start), Some(paused_at)) => paused_at.duration_since(start),
            (Some(start), None) => start.elapsed(),
            _ => Duration::default(),
        }
    }

    pub fn pause(&mut self) {
        if self.start_time.is_some() && self.pause_started_at.is_none() {
            self.pause_started_at = Some(Instant::now());
        }
    }

    pub fn resume(&mut self) {
        if let (Some(start), Some(paused_at)) = (self.start_time, self.pause_started_at.take()) {
            self.start_time = Some(start + paused_at.elapsed());
        }
    }

    /// Records one or more generated candidate moves and the time spent generating them.
    pub fn record_generated_batch(&mut self, count: u64, duration: Duration) {
        self.moves_generated += count;
        self.generation_time += duration;
    }

    pub fn record_selector_generated(
        &mut self,
        selector_index: usize,
        count: u64,
        duration: Duration,
    ) {
        self.record_generated_batch(count, duration);
        let selector = self.selector_stats_entry(selector_index);
        selector.moves_generated += count;
        selector.generation_time += duration;
    }

    /// Records generation time that did not itself yield a counted move.
    pub fn record_generation_time(&mut self, duration: Duration) {
        self.generation_time += duration;
    }

    /// Records a single generated candidate move and the time spent generating it.
    pub fn record_generated_move(&mut self, duration: Duration) {
        self.record_generated_batch(1, duration);
    }

    /// Records a move evaluation and the time spent evaluating it.
    pub fn record_evaluated_move(&mut self, duration: Duration) {
        self.moves_evaluated += 1;
        self.evaluation_time += duration;
    }

    pub fn record_selector_evaluated(&mut self, selector_index: usize, duration: Duration) {
        self.record_evaluated_move(duration);
        let selector = self.selector_stats_entry(selector_index);
        selector.moves_evaluated += 1;
        selector.evaluation_time += duration;
    }

    /// Records an accepted move.
    pub fn record_move_accepted(&mut self) {
        self.moves_accepted += 1;
    }

    pub fn record_selector_accepted(&mut self, selector_index: usize) {
        self.record_move_accepted();
        self.selector_stats_entry(selector_index).moves_accepted += 1;
    }

    pub fn record_move_applied(&mut self) {
        self.moves_applied += 1;
    }

    pub fn record_selector_applied(&mut self, selector_index: usize) {
        self.record_move_applied();
        self.selector_stats_entry(selector_index).moves_applied += 1;
    }

    pub fn record_move_not_doable(&mut self) {
        self.moves_not_doable += 1;
    }

    pub fn record_selector_not_doable(&mut self, selector_index: usize) {
        self.record_move_not_doable();
        self.selector_stats_entry(selector_index).moves_not_doable += 1;
    }

    pub fn record_move_acceptor_rejected(&mut self) {
        self.moves_acceptor_rejected += 1;
    }

    pub fn record_selector_acceptor_rejected(&mut self, selector_index: usize) {
        self.record_move_acceptor_rejected();
        self.selector_stats_entry(selector_index)
            .moves_acceptor_rejected += 1;
    }

    pub fn record_moves_forager_ignored(&mut self, count: u64) {
        self.moves_forager_ignored += count;
    }

    pub fn record_move_hard_improving(&mut self) {
        self.moves_hard_improving += 1;
    }

    pub fn record_move_hard_neutral(&mut self) {
        self.moves_hard_neutral += 1;
    }

    pub fn record_move_hard_worse(&mut self) {
        self.moves_hard_worse += 1;
    }

    pub fn record_conflict_repair_provider_generated(&mut self, count: u64) {
        self.conflict_repair_provider_generated += count;
    }

    pub fn record_conflict_repair_duplicate_filtered(&mut self) {
        self.conflict_repair_duplicate_filtered += 1;
    }

    pub fn record_conflict_repair_illegal_filtered(&mut self) {
        self.conflict_repair_illegal_filtered += 1;
    }

    pub fn record_conflict_repair_not_doable_filtered(&mut self) {
        self.conflict_repair_not_doable_filtered += 1;
    }

    pub fn record_conflict_repair_hard_improving(&mut self) {
        self.conflict_repair_hard_improving += 1;
    }

    pub fn record_conflict_repair_exposed(&mut self) {
        self.conflict_repair_exposed += 1;
    }

    /// Records a step completion.
    pub fn record_step(&mut self) {
        self.step_count += 1;
    }

    /// Records a score calculation.
    pub fn record_score_calculation(&mut self) {
        self.score_calculations += 1;
    }

    pub fn record_construction_slot_assigned(&mut self) {
        self.construction_slots_assigned += 1;
    }

    pub fn record_construction_slot_kept(&mut self) {
        self.construction_slots_kept += 1;
    }

    pub fn record_construction_slot_no_doable(&mut self) {
        self.construction_slots_no_doable += 1;
    }

    pub fn record_scalar_assignment_required_remaining(
        &mut self,
        group_name: &'static str,
        count: u64,
    ) {
        self.scalar_assignment_required_remaining_by_group
            .insert(group_name, count);
        self.scalar_assignment_required_remaining = self
            .scalar_assignment_required_remaining_by_group
            .values()
            .copied()
            .sum();
    }

    pub fn generated_throughput(&self) -> Throughput {
        Throughput {
            count: self.moves_generated,
            elapsed: self.generation_time,
        }
    }

    pub fn evaluated_throughput(&self) -> Throughput {
        Throughput {
            count: self.moves_evaluated,
            elapsed: self.evaluation_time,
        }
    }

    pub fn acceptance_rate(&self) -> f64 {
        if self.moves_evaluated == 0 {
            0.0
        } else {
            self.moves_accepted as f64 / self.moves_evaluated as f64
        }
    }

    pub fn generation_time(&self) -> Duration {
        self.generation_time
    }

    pub fn evaluation_time(&self) -> Duration {
        self.evaluation_time
    }

    pub fn snapshot(&self) -> SolverTelemetry {
        self.snapshot_with_applied_move_trace(true)
    }

    pub fn snapshot_without_applied_move_trace(&self) -> SolverTelemetry {
        self.snapshot_with_applied_move_trace(false)
    }

    fn snapshot_with_applied_move_trace(
        &self,
        include_applied_move_trace: bool,
    ) -> SolverTelemetry {
        SolverTelemetry {
            elapsed: self.elapsed(),
            step_count: self.step_count,
            moves_generated: self.moves_generated,
            moves_evaluated: self.moves_evaluated,
            moves_accepted: self.moves_accepted,
            moves_applied: self.moves_applied,
            moves_score_improving: self.moves_score_improving(),
            moves_applied_improving: self.moves_applied_improving(),
            moves_not_doable: self.moves_not_doable,
            moves_acceptor_rejected: self.moves_acceptor_rejected,
            moves_forager_ignored: self.moves_forager_ignored,
            moves_hard_improving: self.moves_hard_improving,
            moves_hard_neutral: self.moves_hard_neutral,
            moves_hard_worse: self.moves_hard_worse,
            conflict_repair_provider_generated: self.conflict_repair_provider_generated,
            conflict_repair_duplicate_filtered: self.conflict_repair_duplicate_filtered,
            conflict_repair_illegal_filtered: self.conflict_repair_illegal_filtered,
            conflict_repair_not_doable_filtered: self.conflict_repair_not_doable_filtered,
            conflict_repair_hard_improving: self.conflict_repair_hard_improving,
            conflict_repair_exposed: self.conflict_repair_exposed,
            score_calculations: self.score_calculations,
            construction_slots_assigned: self.construction_slots_assigned,
            construction_slots_kept: self.construction_slots_kept,
            construction_slots_no_doable: self.construction_slots_no_doable,
            scalar_assignment_required_remaining: self.scalar_assignment_required_remaining,
            generation_time: self.generation_time,
            evaluation_time: self.evaluation_time,
            phase: None,
            selector_telemetry: self.selector_stats.clone(),
            move_telemetry: self.move_stats.values().cloned().collect(),
            applied_move_trace: if include_applied_move_trace {
                self.applied_move_trace.to_vec()
            } else {
                Vec::new()
            },
            candidate_trace: if include_applied_move_trace {
                self.candidate_trace
                    .as_ref()
                    .map(CandidateTraceTelemetry::snapshot)
            } else {
                None
            },
        }
    }

    pub fn record_move_kind_generated(&mut self, move_label: &'static str) {
        self.move_stats_entry(move_label).moves_generated += 1;
    }

    pub fn moves_score_improving(&self) -> u64 {
        self.move_stats
            .values()
            .map(|entry| entry.moves_score_improving)
            .sum()
    }

    pub fn moves_applied_improving(&self) -> u64 {
        self.move_stats
            .values()
            .map(|entry| entry.moves_applied_improving)
            .sum()
    }

    pub fn record_move_kind_evaluated(
        &mut self,
        move_label: &'static str,
        score_ordering: Ordering,
    ) {
        let entry = self.move_stats_entry(move_label);
        entry.moves_evaluated += 1;
        match score_ordering {
            Ordering::Greater => entry.moves_score_improving += 1,
            Ordering::Equal => entry.moves_score_equal += 1,
            Ordering::Less => entry.moves_score_worse += 1,
        }
    }

    pub fn record_move_kind_evaluated_unscored(&mut self, move_label: &'static str) {
        self.move_stats_entry(move_label).moves_evaluated += 1;
    }

    pub fn record_move_kind_accepted(&mut self, move_label: &'static str) {
        self.move_stats_entry(move_label).moves_accepted += 1;
    }

    pub fn record_move_kind_applied(&mut self, move_label: &'static str, score_improvement: f64) {
        let entry = self.move_stats_entry(move_label);
        entry.moves_applied += 1;
        if score_improvement > 0.0 {
            entry.moves_applied_improving += 1;
            entry.applied_score_improvement += score_improvement;
        }
    }

    pub fn record_move_kind_not_doable(&mut self, move_label: &'static str) {
        self.move_stats_entry(move_label).moves_not_doable += 1;
    }

    pub fn record_move_kind_acceptor_rejected(
        &mut self,
        move_label: &'static str,
        score_ordering: Ordering,
    ) {
        let entry = self.move_stats_entry(move_label);
        entry.moves_acceptor_rejected += 1;
        if score_ordering == Ordering::Greater {
            entry.moves_rejected_improving += 1;
        }
    }

    pub fn record_move_kind_forager_ignored(&mut self, move_label: &'static str, count: u64) {
        if count == 0 {
            return;
        }
        self.move_stats_entry(move_label).moves_forager_ignored += count;
    }

    pub fn record_applied_move_trace(&mut self, applied_move: AppliedMoveTelemetry) {
        if self.applied_move_trace.len() < APPLIED_MOVE_TRACE_LIMIT {
            self.applied_move_trace.push(applied_move);
        }
    }

    pub(crate) fn enable_candidate_trace(&mut self, candidate_trace: CandidateTraceTelemetry) {
        assert!(
            self.candidate_trace.is_none(),
            "candidate trace may be enabled only once per solve"
        );
        self.candidate_trace = Some(candidate_trace);
    }

    pub(crate) fn prepare_candidate_trace_pull(&mut self) -> CandidateTraceRecordDecision {
        match self.candidate_trace.as_mut() {
            Some(trace) => trace.prepare_pull(),
            None => CandidateTraceRecordDecision::Disabled,
        }
    }

    pub(crate) fn begin_candidate_trace_phase(&mut self) -> Option<usize> {
        self.candidate_trace
            .as_mut()
            .map(CandidateTraceTelemetry::begin_phase)
    }

    /// Finalizes the exact phase plan for an enabled candidate trace.
    ///
    /// A trace-free solve intentionally has no recorder to update. The
    /// one-way invariant itself is enforced by `CandidateTraceTelemetry` when
    /// a trace exists.
    pub(crate) fn finalize_candidate_trace_resolved_phase_plan(
        &mut self,
        resolved_phase_plan: CandidateTracePhasePlan,
    ) {
        if let Some(trace) = self.candidate_trace.as_mut() {
            trace.finalize_resolved_phase_plan(resolved_phase_plan);
        }
    }

    pub(crate) fn record_prepared_candidate_trace_pull(
        &mut self,
        pull: CandidatePullTelemetry,
    ) -> CandidateTracePullToken {
        let trace = self
            .candidate_trace
            .as_mut()
            .expect("a prepared candidate trace pull requires an enabled trace");
        trace.push_prepared(pull)
    }

    pub(crate) fn record_candidate_trace_disposition(
        &mut self,
        token: CandidateTracePullToken,
        disposition: CandidateTraceDisposition,
    ) {
        let trace = self
            .candidate_trace
            .as_mut()
            .expect("a candidate trace disposition requires an enabled trace");
        trace.record_disposition(token, disposition);
    }

    pub fn record_selector_generated_with_label(
        &mut self,
        selector_index: usize,
        selector_label: impl Into<String>,
        count: u64,
        duration: Duration,
    ) {
        self.record_generated_batch(count, duration);
        let selector = self.selector_stats_entry_with_label(selector_index, selector_label);
        selector.moves_generated += count;
        selector.generation_time += duration;
    }

    fn selector_stats_entry(&mut self, selector_index: usize) -> &mut SelectorTelemetry {
        self.selector_stats_entry_with_label(selector_index, format!("selector-{selector_index}"))
    }

    fn selector_stats_entry_with_label(
        &mut self,
        selector_index: usize,
        selector_label: impl Into<String>,
    ) -> &mut SelectorTelemetry {
        let selector_label = selector_label.into();
        if let Some(position) = self
            .selector_stats
            .iter()
            .position(|entry| entry.selector_index == selector_index)
        {
            if self.selector_stats[position]
                .selector_label
                .starts_with("selector-")
                && !selector_label.starts_with("selector-")
            {
                self.selector_stats[position].selector_label = selector_label;
            }
            return &mut self.selector_stats[position];
        }
        self.selector_stats.push(SelectorTelemetry {
            selector_index,
            selector_label,
            ..SelectorTelemetry::default()
        });
        self.selector_stats
            .last_mut()
            .expect("selector stats entry was just inserted")
    }

    fn move_stats_entry(&mut self, move_label: &'static str) -> &mut MoveTelemetry {
        self.move_stats
            .entry(move_label)
            .or_insert_with(|| MoveTelemetry {
                move_label: move_label.to_string(),
                ..MoveTelemetry::default()
            })
    }
}

/* Phase-level statistics.

Tracks metrics for a single solver phase.

# Example

```
use solverforge_solver::stats::PhaseStats;
use std::time::Duration;

let mut stats = PhaseStats::new(0, "LocalSearch");
stats.record_step();
stats.record_generated_move(Duration::from_millis(1));
stats.record_evaluated_move(Duration::from_millis(2));
stats.record_move_accepted();

assert_eq!(stats.phase_index, 0);
assert_eq!(stats.phase_type, "LocalSearch");
assert_eq!(stats.step_count, 1);
assert_eq!(stats.moves_accepted, 1);
```
*/