Module incremental 

Event-gated incremental solve — ADR-001 roadmap item #2.

The central architectural lift in this crate. Instead of paying O(k · nnz(A)) cold-start cost per call when a downstream system delivers a sparse update to the right-hand side, callers get to warm-start the iterative solver from the previous solution and pay O(k_warm · nnz(A)) where k_warm ≪ k_cold for small deltas. On diagonally-dominant systems the inner solve over the delta has rapid spatial decay, so k_warm is often a small constant.

Why it matters in the stack

Every always-on system in the ADR’s directive — Cognitum reflex loops, RuView change detection, Ruflo’s agentic inner loops, ruvector graph repair — receives input as a stream of small deltas, not as fresh full RHS vectors. Without this entry point each tick pays full O(nnz(A)) even when 99% of b is unchanged. With it, steady-state cost falls toward the sparsity of the delta itself.

API

let solver = NeumannSolver::new(64, 1e-10);
// 2 entries of b changed:
let delta = SparseDelta::new(vec![3, 17], vec![0.5, -0.2])?;
let result = solver.solve_on_change(
    matrix as &dyn Matrix,
    &prev_solution,
    &delta,
    &SolverOptions::default(),
)?;

Complexity

The IncrementalSolver blanket impl on any SolverAlgorithm:

• Cold-start equivalent fallback: when nnz(delta) > break_even, falls back to a full solve. Configurable via IncrementalConfig::full_solve_break_even.
• Warm-start path: when delta is sparse, runs solve() with initial_guess = prev_solution. Iteration count drops in proportion to the L₂ norm of the residual b_new − A·prev_solution, which is ||A · z|| for the delta-induced correction z = A⁻¹ · delta.
• On well-conditioned DD systems with ||delta|| / ||b|| ≈ ε, this typically converges in O(log(1/ε)) warm-start iters instead of O(√κ · log(1/ε)) cold.

Structs

IncrementalConfig

Configuration for the incremental solve. Mostly: when to give up on warm-start and just do a full solve.

IncrementalSolveOp

Marker type with a Complexity impl declaring the asymptotic class of IncrementalSolver::solve_on_change. Pure documentation — the actual impl lives on the underlying solver’s Complexity impl, this just exists so MCP schema generation has a stable target.

SolveOnChangeSublinearOp

Op marker for solve_on_change_sublinear. SubLinear in n end-to-end.

SparseDelta

A sparse update to a right-hand side vector. indices[i] names the row whose value in b changed by values[i] (additive — pass the delta, not the new absolute value).

Traits

IncrementalSolver

Extension trait that adds an event-gated entry point to any SolverAlgorithm. Blanket-implemented below, so every solver in the crate gets solve_on_change for free.

Functions

solve_on_change_sublinear

SubLinear sibling of IncrementalSolver::solve_on_change. Returns Vec<(usize, Precision)> of (row_index, x_new[row]) for every row in the bounded-depth closure of delta’s support, computed without touching any row outside the closure.

solve_on_change_sublinear_auto

Magic-number-free sibling of solve_on_change_sublinear. Takes only (matrix, prev, b_new, delta, tolerance) and auto-tunes both closure_depth and max_terms from the matrix’s coherence margin via crate::coherence::optimal_neumann_terms.

solve_on_change_sublinear_auto_with_rho

Tightest-bound variant of solve_on_change_sublinear_auto: takes a caller-supplied spectral-radius rho (e.g. from crate::coherence::approximate_spectral_radius) and uses it to pick max_terms via crate::coherence::optimal_neumann_terms_with_rho instead of the loose (1 - coherence) bound.