135 lines
4.5 KiB
Rust
135 lines
4.5 KiB
Rust
//! Solver trait hierarchy.
|
|
//!
|
|
//! All solver algorithms implement [`SolverEngine`]. Specialised traits
|
|
//! ([`SparseLaplacianSolver`], [`SublinearPageRank`]) extend it with
|
|
//! domain-specific operations.
|
|
|
|
use crate::error::SolverError;
|
|
use crate::types::{
|
|
Algorithm, ComplexityEstimate, ComputeBudget, CsrMatrix, SolverResult, SparsityProfile,
|
|
};
|
|
|
|
/// Core trait that every solver algorithm must implement.
|
|
///
|
|
/// A `SolverEngine` accepts a sparse matrix system and a compute budget,
|
|
/// returning either a [`SolverResult`] or a structured [`SolverError`].
|
|
pub trait SolverEngine: Send + Sync {
|
|
/// Solve the linear system `A x = b` (or the equivalent iterative
|
|
/// problem) subject to the given compute budget.
|
|
///
|
|
/// # Arguments
|
|
///
|
|
/// * `matrix` - the sparse coefficient matrix.
|
|
/// * `rhs` - the right-hand side vector `b`.
|
|
/// * `budget` - resource limits for this invocation.
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// Returns [`SolverError`] on non-convergence, numerical issues, budget
|
|
/// exhaustion, or invalid input.
|
|
fn solve(
|
|
&self,
|
|
matrix: &CsrMatrix<f64>,
|
|
rhs: &[f64],
|
|
budget: &ComputeBudget,
|
|
) -> Result<SolverResult, SolverError>;
|
|
|
|
/// Estimate the computational cost of solving the given system without
|
|
/// actually performing the solve.
|
|
///
|
|
/// Implementations should use the [`SparsityProfile`] to make a fast,
|
|
/// heuristic prediction.
|
|
fn estimate_complexity(&self, profile: &SparsityProfile, n: usize) -> ComplexityEstimate;
|
|
|
|
/// Return the algorithm identifier for this engine.
|
|
fn algorithm(&self) -> Algorithm;
|
|
}
|
|
|
|
/// Extended trait for solvers that operate on graph Laplacian systems.
|
|
///
|
|
/// A graph Laplacian `L = D - A` arises naturally in spectral graph theory.
|
|
/// Solvers implementing this trait can exploit Laplacian structure (e.g.
|
|
/// guaranteed positive semi-definiteness, kernel spanned by the all-ones
|
|
/// vector) for faster convergence.
|
|
pub trait SparseLaplacianSolver: SolverEngine {
|
|
/// Solve `L x = b` where `L` is a graph Laplacian.
|
|
///
|
|
/// The solver may add a small regulariser to handle the rank-deficient
|
|
/// case (connected component with zero eigenvalue).
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// Returns [`SolverError`] on failure.
|
|
fn solve_laplacian(
|
|
&self,
|
|
laplacian: &CsrMatrix<f64>,
|
|
rhs: &[f64],
|
|
budget: &ComputeBudget,
|
|
) -> Result<SolverResult, SolverError>;
|
|
|
|
/// Compute the effective resistance between two nodes.
|
|
///
|
|
/// Effective resistance `R(s, t) = (e_s - e_t)^T L^+ (e_s - e_t)` is
|
|
/// a fundamental quantity in spectral graph theory.
|
|
fn effective_resistance(
|
|
&self,
|
|
laplacian: &CsrMatrix<f64>,
|
|
source: usize,
|
|
target: usize,
|
|
budget: &ComputeBudget,
|
|
) -> Result<f64, SolverError>;
|
|
}
|
|
|
|
/// Trait for sublinear-time Personalized PageRank (PPR) algorithms.
|
|
///
|
|
/// PPR is central to nearest-neighbour search in large graphs. Algorithms
|
|
/// implementing this trait run in time proportional to the output size
|
|
/// rather than the full graph size.
|
|
pub trait SublinearPageRank: Send + Sync {
|
|
/// Compute a sparse approximate PPR vector from a single source node.
|
|
///
|
|
/// # Arguments
|
|
///
|
|
/// * `matrix` - column-stochastic transition matrix (or CSR adjacency).
|
|
/// * `source` - index of the source (seed) node.
|
|
/// * `alpha` - teleportation probability (typically 0.15).
|
|
/// * `epsilon` - approximation tolerance; controls output sparsity.
|
|
///
|
|
/// # Returns
|
|
///
|
|
/// A vector of `(node_index, ppr_value)` pairs whose values sum to
|
|
/// approximately 1.
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// Returns [`SolverError`] on invalid input or budget exhaustion.
|
|
fn ppr(
|
|
&self,
|
|
matrix: &CsrMatrix<f64>,
|
|
source: usize,
|
|
alpha: f64,
|
|
epsilon: f64,
|
|
) -> Result<Vec<(usize, f64)>, SolverError>;
|
|
|
|
/// Compute PPR from a distribution over seed nodes rather than a single
|
|
/// source.
|
|
///
|
|
/// # Arguments
|
|
///
|
|
/// * `matrix` - column-stochastic transition matrix.
|
|
/// * `seeds` - `(node_index, weight)` pairs forming the seed distribution.
|
|
/// * `alpha` - teleportation probability.
|
|
/// * `epsilon` - approximation tolerance.
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// Returns [`SolverError`] on invalid input or budget exhaustion.
|
|
fn ppr_multi_seed(
|
|
&self,
|
|
matrix: &CsrMatrix<f64>,
|
|
seeds: &[(usize, f64)],
|
|
alpha: f64,
|
|
epsilon: f64,
|
|
) -> Result<Vec<(usize, f64)>, SolverError>;
|
|
}
|