Skip to main content

Crate deep_causality_linear

Crate deep_causality_linear 

Source
Expand description

Linear algebra for the DeepCausality crates.

This crate owns the workspace’s matrix representations and the algorithms over them. The split against deep_causality_tensor is by arity, not density: a two-index object is a matrix and lives here; ein_sum, broadcast, kronecker, the axis reductions and the tensor-train stack take an N-index object and stay there.

§Three representations, side by side

Choosing a representation is the central decision in linear algebra, and this crate holds all three so that the choice is local rather than architectural:

representationfor
compressed sparse rowboundary and coboundary operators, discrete Laplacians
dense row-majorcovariance, metric tensors, density matrices
bit-packed 𝔽₂mod-2 elimination, homology read as a code

plus a dense vector, which the construction census found to be the larger need: 60 rank-1 constructions against 46 rank-2 across the seven consumer crates.

§Banded on the tower, not on f64

Every operation is bounded on the weakest trait from deep_causality_algebra that makes it correct, so the crate is generic over the integers as well as the floats. The determinant is a polynomial in the entries and needs no division, so it is defined over any commutative ring — bounding it on Field is what would have excluded ℤ. Gaussian elimination divides by its pivot and so leaves ℤ on the first step, and is bounded accordingly.

The crate defines no scalar trait, marker or newtype of its own.

§Position in the tier graph

This crate sits below deep_causality_tensor and must not depend on it under any feature. CausalTensor’s decompositions delegate into here, and a crate can only call into what it depends on. Given that edge, the orphan rule leaves deep_causality_tensor as the only place the access-trait impl for CausalTensor can be written.

Structs§

CsrMatrix
A matrix in compressed sparse row form.
CsrMatrixWitness
The higher-kinded witness for CsrMatrix.
DenseMatrix
A dense matrix stored row-major.
DenseMatrixWitness
The higher-kinded witness for DenseMatrix.
DenseVector
A dense vector, carrying its length.
DenseVectorWitness
The higher-kinded witness for DenseVector.
LinearError
Every way an operation in this crate can fail.
Lu
An LU factorisation with partial pivoting, kept so it can be applied more than once.
PackedGf2
A matrix over 𝔽₂ storing one bit per entry, packed into words of type W.
PackedGf2Vector
A vector over 𝔽₂, one bit per entry, packed into words of type W.
Reduced
What a row reduction learned, beyond the reduced matrix itself.
ZipDenseVectorWitness
The elementwise higher-kinded view of DenseVector.

Enums§

CgFailure
Why a conjugate-gradient solve stopped without converging.
LinearErrorEnum
The classification behind LinearError.
Truncation
How a truncated decomposition decides what to keep.

Traits§

MatrixBuild
Construction and mutation of a matrix, position by position.
MatrixView
Read access to a matrix: its shape, and its entries by value.
RowOps
The three row operations every elimination is built from.

Functions§

cg_solve
Solves Ax = b by conjugate gradient, with apply supplying A.
cg_solve_preconditioned
Solves Ax = b by Jacobi-preconditioned conjugate gradient.
cg_solve_preconditioned_from
As cg_solve_preconditioned, starting from a supplied initial guess.
cholesky
The Cholesky factor L of a Hermitian positive-definite matrix, so that A = L Lᴴ.
csr_i8_to_dense_i64
Widens an i8 sparse matrix to a dense i64 one, row-major.
csr_to_dense
Densifies a sparse matrix, materialising its structural zeros.
csr_to_packed_gf2_mod2
Packs an integer matrix by reducing every entry modulo 2.
csr_to_packed_gf2_strict
Packs an integer matrix, rejecting any entry outside {0, 1}.
dense_gf2_to_packed
Packs a dense matrix of 𝔽₂ entries.
dense_to_csr
Sparsifies a dense matrix, storing only its non-zeros.
determinant
The determinant, pivoting on magnitude.
determinant_3x3
The determinant of a 3×3, by cofactor expansion along the first row.
determinant_4x4
The determinant of a 4×4, by the six 2×2 minors of the first two rows.
determinant_exact
The determinant of an integer matrix, by fraction-free (Bareiss) elimination.
dot
The inner product Σ aᵢ·bᵢ of two equal-length slices.
dot_n
The inner product of two arrays of the same compile-time length.
double_dot_3x3
The Frobenius inner product A : B = Σᵢ Σⱼ aᵢⱼ·bᵢⱼ, for two 3×3 matrices.
eigen_hermitian
The eigendecomposition of a Hermitian matrix, as (eigenvalues, eigenvectors).
eigen_symmetric_3x3
The three eigenvalues of a real symmetric 3×3, sorted descending.
image_basis
A basis of the image, as the columns of the returned matrix.
image_basis_gf2
A basis of the image over 𝔽₂.
inverse
The inverse.
inverse_3x3
The inverse of a 3×3, as the adjugate over the determinant.
inverse_4x4
The inverse of a 4×4, as the adjugate over the determinant.
kernel_basis
A basis of the kernel, as the columns of the returned matrix.
kernel_basis_gf2
A basis of the kernel over 𝔽₂.
mat3_vec
The matrix-vector product M·v for a 3×3 and a 3-vector.
matrix_norm_frobenius
The Frobenius norm: sqrt(Σ |aᵢⱼ|²).
matrix_norm_inf
The ∞-norm: the largest row sum of moduli.
matrix_norm_l1
The 1-norm: the largest column sum of moduli.
packed_to_dense_gf2
Unpacks into a dense matrix of 𝔽₂ entries.
qr
The QR decomposition, as (Q, R).
rank
The rank, by exact elimination.
rank_exact
The rank of an integer matrix, exactly.
rank_gf2
The rank over 𝔽₂, exactly.
rank_stable
The rank, by elimination pivoting on magnitude.
rref
Reduces m to reduced row echelon form in place, pivoting on the first non-zero.
rref_stable
Reduces m to reduced row echelon form in place, pivoting on the largest modulus.
singular_values
The singular values alone, descending.
solve
Solves Ax = b for a dense square system, by LU with partial pivoting.
solve_least_squares
The least-squares solution of A x ≈ b by the normal equations, factored with Cholesky.
solve_lower
Solves a lower-triangular system by forward substitution.
solve_upper
Solves an upper-triangular system by backward substitution.
svd
The singular value decomposition, as (U, S, Vᵀ).
svd_sorted
The full decomposition, singular values real and sorted descending.
svd_truncated
The singular value decomposition truncated by a rank or a tolerance.
trace_of_square_3x3
The trace of the square, tr(A²) = Σᵢ Σⱼ aᵢⱼ·aⱼᵢ, for a 3×3.
vector_norm_inf
The ∞-norm of a vector, max |aᵢ|.
vector_norm_l1
The 1-norm of a vector, Σ |aᵢ|.
vector_norm_l2
The 2-norm of a vector, sqrt(Σ |aᵢ|²), computed in the scaled form.
vector_norm_sq
The squared 2-norm of a vector, Σ |aᵢ|².

Type Aliases§

EigenPair
The eigenvalues and eigenvectors of a Hermitian matrix.
QrFactors
The two factors of a QR decomposition.
SvdFactors
The three factors of a singular value decomposition: U, S and Vᵀ.
SvdReal
The full singular value decomposition with real singular values, sorted descending.