Struct SparseTensor 

pub struct SparseTensor {
    pub values: NodeId,
    pub col_idx: NodeId,
    pub row_ptr: NodeId,
    pub n_rows: usize,
    pub n_cols: usize,
}

CSR-format sparse matrix at the IR level. Bundles the three CSR NodeIds with structural shape info known at graph-build time.

Modeled on jax.experimental.sparse.BCOO — a wrapper around (data, indices) arrays plus a shape tuple, with methods that expand to the right subgraph for each operation.

Fields

values: NodeId

Non-zero values in row-major CSR order. F64.

col_idx: NodeId

Column index per non-zero. I32.

row_ptr: NodeId

Start index in values / col_idx per row, length n_rows + 1. I32.

n_rows: usize

Logical row count of A.

n_cols: usize

Logical column count of A (n_rows == n_cols for square / SPD).

Implementations

impl SparseTensor

pub fn from_csr( values: NodeId, col_idx: NodeId, row_ptr: NodeId, n_rows: usize, n_cols: usize, ) -> Self

Build from existing CSR NodeIds. Caller is responsible for the layout invariants (sortedness within rows, row_ptr.len() == n_rows + 1, etc.).

pub fn mat_vec(&self, g: &mut Graph, x: NodeId) -> NodeId

y = A · x for a length-n_cols dense vector.

pub fn solve(&self, g: &mut Graph, b: NodeId) -> NodeId

x = A⁻¹ · b via direct LU.

pub fn cg_solve( &self, g: &mut Graph, b: NodeId, max_iter: u32, tol: f64, ) -> NodeId

x = A⁻¹ · b via Conjugate Gradient. SPD only. tol is the absolute residual threshold; max_iter caps iteration count.

pub fn solve_general( &self, g: &mut Graph, b: NodeId, adjoint: &SparseTensor, ) -> NodeId

x = A⁻¹ · b via direct LU for non-symmetric A. The caller supplies an explicit transpose adjoint (CSR of Aᵀ) — for square non-symmetric matrices, Aᵀ has the same nnz pattern as A after a CSR↔CSC swap. The forward solve uses only self; the VJP routes the adjoint solve through adjoint. Use this in place of solve when the assumption Aᵀ = A would be wrong.

pub fn pcg_solve( &self, g: &mut Graph, b: NodeId, max_iter: u32, tol: f64, ) -> NodeId

x = A⁻¹ · b via Jacobi-preconditioned CG. SPD only. Convergence dramatically faster than plain CG on ill- conditioned matrices where diag(A) captures most of the magnitude variation — typical for circuit MNA matrices with mixed-magnitude device parameters. The preconditioner is extracted from the CSR by the kernel; no separate input.

pub fn transpose_values( &self, g: &mut Graph, col_idx_t: NodeId, row_ptr_t: NodeId, ) -> NodeId

Permute this tensor’s values into the values vector of Aᵀ. The transposed pattern (col_idx_t, row_ptr_t) is supplied as NodeIds — typically computed once via crate::csr_transpose_pattern and embedded as Op::Constant since the pattern is fixed across Newton iterations.

pub fn cholesky_solve(&self, g: &mut Graph, b: NodeId) -> NodeId

x = A⁻¹ · b via direct sparse Cholesky for SPD A. Densifies into a dense buffer and calls LAPACK dpotrf + triangular solves. Mirror of solve (LU-based) but ½× factor cost and numerically more stable; only valid when A is SPD.

pub fn lsqr_solve( &self, g: &mut Graph, b: NodeId, max_iter: u32, tol: f64, ) -> NodeId

x = argmin ||A·x - b||₂ via LSQR (Paige-Saunders 1982). Works for any A (square / over-determined / under-determined); returns the minimum-norm solution when A is rank-deficient or under-determined. VJP not implemented in v1.

pub fn bicgstab_solve( &self, g: &mut Graph, b: NodeId, max_iter: u32, tol: f64, ) -> NodeId

x = A⁻¹ · b via BiCGSTAB for non-symmetric A. Same shape contract as CG/PCG (no explicit adjoint pattern needed — the kernel itself can solve Aᵀ·x = b via a flag, used by VJPs).

pub fn ilu_pcg_solve( &self, g: &mut Graph, b: NodeId, max_iter: u32, tol: f64, ) -> NodeId

x = A⁻¹ · b via ILU(0)-preconditioned CG. SPD A required (same contract as CG/PCG). ILU is factored on each call — for static-pattern Newton loops the cost amortizes against the faster convergence vs. Jacobi-PCG.

pub fn gmres_solve( &self, g: &mut Graph, b: NodeId, max_iter: u32, tol: f64, adjoint: &SparseTensor, ) -> NodeId

x = A⁻¹ · b via GMRES for non-symmetric A. Same transpose-triplet contract as solve_general. max_iter caps Krylov dimension; tol is the residual norm threshold.

Trait Implementations

impl Clone for SparseTensor

fn clone(&self) -> SparseTensor

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for SparseTensor

impl Debug for SparseTensor

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

Formats the value using the given formatter.