ruvector_solver/
events.rs

1//! Event sourcing for solver operations.
2//!
3//! Every solver emits [`SolverEvent`]s to an event log, enabling full
4//! observability of the solve pipeline: what was requested, how many
5//! iterations ran, whether convergence was reached, and whether fallback
6//! algorithms were invoked.
7
8use std::time::Duration;
9
10use serde::{Deserialize, Serialize};
11
12use crate::types::{Algorithm, ComputeLane};
13
14/// Events emitted during a solver invocation.
15///
16/// Events are tagged with `#[serde(tag = "type")]` so they serialise as
17/// `{ "type": "SolveRequested", ... }` for easy ingestion into event stores.
18#[derive(Debug, Clone, Serialize, Deserialize)]
19#[serde(tag = "type")]
20pub enum SolverEvent {
21    /// A solve request was received and is about to begin.
22    SolveRequested {
23        /// Algorithm that will be attempted first.
24        algorithm: Algorithm,
25        /// Matrix dimension (number of rows).
26        matrix_rows: usize,
27        /// Number of non-zeros.
28        matrix_nnz: usize,
29        /// Compute lane.
30        lane: ComputeLane,
31    },
32
33    /// One iteration of the solver completed.
34    IterationCompleted {
35        /// Iteration number (0-indexed).
36        iteration: usize,
37        /// Current residual norm.
38        residual: f64,
39        /// Wall time elapsed since the solve began.
40        elapsed: Duration,
41    },
42
43    /// The solver converged successfully.
44    SolveConverged {
45        /// Algorithm that produced the result.
46        algorithm: Algorithm,
47        /// Total iterations executed.
48        iterations: usize,
49        /// Final residual norm.
50        residual: f64,
51        /// Total wall time.
52        wall_time: Duration,
53    },
54
55    /// The solver fell back from one algorithm to another (e.g. Neumann
56    /// series spectral radius too high, falling back to CG).
57    AlgorithmFallback {
58        /// Algorithm that failed or was deemed unsuitable.
59        from: Algorithm,
60        /// Algorithm that will be tried next.
61        to: Algorithm,
62        /// Human-readable reason for the fallback.
63        reason: String,
64    },
65
66    /// The compute budget was exhausted before convergence.
67    BudgetExhausted {
68        /// Algorithm that was running when the budget was hit.
69        algorithm: Algorithm,
70        /// Which budget limit was hit.
71        limit: BudgetLimit,
72        /// Wall time elapsed.
73        elapsed: Duration,
74    },
75}
76
77/// Which budget limit was exhausted.
78#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
79pub enum BudgetLimit {
80    /// Wall-clock time limit.
81    WallTime,
82    /// Iteration count limit.
83    Iterations,
84    /// Memory allocation limit.
85    Memory,
86}
ruvector_solver/events.rs

ruvector_solver/
events.rs
