Struct CoherenceCache 

pub struct CoherenceCache { /* private fields */ }

Incremental coherence cache for streaming matrix-update workloads.

coherence_score is O(nnz(A)) — a full scan of the matrix. Streaming workloads (Cognitum reflex loops over a learning system, RuView agents tracking sensor-network state, anything that mutates rows over time) re-pay that cost on every event even when only a handful of rows actually changed.

This cache stores the per-row diagonal-dominance margin and the current global minimum. Initial CoherenceCache::build is the same O(nnz) one-shot cost. Each subsequent [update] only re-scans the dirty rows: O(|dirty| · avg_row_nnz). The cached [score] is an O(1) read.

Math

Per-row margin at row i: (|A[i,i]| - Σ_{j≠i}|A[i,j]|) / |A[i,i]|

Global coherence = min_i row_margin[i]. When row i’s margin changes, the global min either becomes the new value (if i was the previous min row, or the new value is lower) or stays as before (otherwise). We track the min row index so we can detect when re-computing it across all clean rows is unavoidable — happens iff the dirty update increases the previous-min row’s margin. The unavoidable case is still bounded by O(n) (just a vec scan), no matrix touches.

Complexity

• build: O(nnz(A)) — same as coherence_score.
• update: O(|dirty| · avg_row_nnz) typical case. The rare unavoidable global recompute is O(n) vec scan (no matrix touches) — still cheaper than a full coherence_score on a sparse matrix.
• score: O(1).

The “amortised SubLinear-per-event” guarantee: as long as the previous-min row stays among the dirty set or the new minimum lands among the dirty rows, the cache never has to do the global scan.

Implementations

impl CoherenceCache

pub fn build(matrix: &dyn Matrix) -> Self

Compute per-row margins for every row and cache the global minimum. One-shot O(nnz(A)) work, matches coherence_score.

pub fn update(&mut self, matrix: &dyn Matrix, dirty_rows: &[usize])

Re-scan only the listed dirty rows. O(|dirty| · row_nnz) typical case; up to O(n) vec scan if the previous-min row got dirtier and we have to find the new global minimum.

dirty_rows need not be sorted or unique; duplicates are handled idempotently. Out-of-bound indices are silently dropped (matches coherence_score’s tolerant handling).

pub fn score(&self) -> Precision

Cached global minimum margin. O(1).

pub fn min_row(&self) -> usize

Row index of the current global minimum margin.

Trait Implementations

impl Clone for CoherenceCache

fn clone(&self) -> CoherenceCache

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CoherenceCache

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

Formats the value using the given formatter.