solverforge_solver/stats/

phase.rs

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

use super::{AppliedMoveTelemetry, MoveTelemetry, PhaseTelemetry, SelectorTelemetry, Throughput};

const APPLIED_MOVE_TRACE_LIMIT: usize = 8;

#[path = "phase_absorb.rs"]
mod absorb;

#[derive(Debug, Clone)]
pub struct PhaseStats {
    // Index of this phase (0-based).
    pub phase_index: usize,
    // Type name of the phase.
    pub phase_type: &'static str,
    start_time: Instant,
    // Number of steps taken in this phase.
    pub step_count: u64,
    /// Number of candidate moves actually yielded by cursors in this phase.
    /// Unrequested logical neighborhood tails are not generated work.
    pub moves_generated: u64,
    // Number of moves evaluated in this phase.
    pub moves_evaluated: u64,
    /// Candidates parallel evaluation evaluated ahead of the sequential
    /// decision point in this phase and then discarded.
    pub moves_speculative: u64,
    // Number of moves accepted in this phase.
    pub moves_accepted: u64,
    // Number of moves applied in this phase.
    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,
    // Number of score calculations in this phase.
    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,
    generation_time: Duration,
    evaluation_time: Duration,
    selector_stats: Vec<SelectorTelemetry>,
    move_stats: BTreeMap<&'static str, MoveTelemetry>,
    applied_move_trace: Vec<AppliedMoveTelemetry>,
}

impl PhaseStats {
    /// Creates new phase statistics.
    pub fn new(phase_index: usize, phase_type: &'static str) -> Self {
        Self {
            phase_index,
            phase_type,
            start_time: Instant::now(),
            step_count: 0,
            moves_generated: 0,
            moves_evaluated: 0,
            moves_speculative: 0,
            moves_accepted: 0,
            moves_applied: 0,
            moves_not_doable: 0,
            moves_acceptor_rejected: 0,
            moves_forager_ignored: 0,
            moves_hard_improving: 0,
            moves_hard_neutral: 0,
            moves_hard_worse: 0,
            conflict_repair_provider_generated: 0,
            conflict_repair_duplicate_filtered: 0,
            conflict_repair_illegal_filtered: 0,
            conflict_repair_not_doable_filtered: 0,
            conflict_repair_hard_improving: 0,
            conflict_repair_exposed: 0,
            score_calculations: 0,
            construction_slots_assigned: 0,
            construction_slots_kept: 0,
            construction_slots_no_doable: 0,
            scalar_assignment_required_remaining: 0,
            generation_time: Duration::default(),
            evaluation_time: Duration::default(),
            selector_stats: Vec::new(),
            move_stats: BTreeMap::new(),
            applied_move_trace: Vec::new(),
        }
    }

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

    pub fn snapshot(&self) -> PhaseTelemetry {
        self.snapshot_with_elapsed(self.elapsed())
    }

    pub(crate) fn snapshot_with_elapsed(&self, elapsed: Duration) -> PhaseTelemetry {
        PhaseTelemetry {
            phase_index: self.phase_index,
            phase_type: self.phase_type.to_string(),
            elapsed,
            step_count: self.step_count,
            moves_generated: self.moves_generated,
            moves_evaluated: self.moves_evaluated,
            moves_speculative: self.moves_speculative,
            moves_accepted: self.moves_accepted,
            moves_applied: self.moves_applied,
            moves_score_improving: self.moves_score_improving(),
            moves_applied_improving: self.moves_applied_improving(),
            score_calculations: self.score_calculations,
            generation_time: self.generation_time,
            evaluation_time: self.evaluation_time,
        }
    }

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

    /// 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 score calculation.
    pub fn record_score_calculation(&mut self) {
        self.score_calculations += 1;
    }

    /// Records a candidate that parallel evaluation evaluated ahead of the
    /// sequential decision point and then discarded.
    pub fn record_move_speculative(&mut self) {
        self.moves_speculative += 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, count: u64) {
        self.scalar_assignment_required_remaining = count;
    }

    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 selector_telemetry(&self) -> &[SelectorTelemetry] {
        &self.selector_stats
    }

    pub fn applied_move_trace(&self) -> &[AppliedMoveTelemetry] {
        &self.applied_move_trace
    }

    pub fn move_telemetry(&self) -> Vec<MoveTelemetry> {
        self.move_stats.values().cloned().collect()
    }

    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 can_record_applied_move_trace(&self) -> bool {
        self.applied_move_trace.len() < APPLIED_MOVE_TRACE_LIMIT
    }

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

    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 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()
            })
    }
}