Skip to main content

Crate matrixpacked

Crate matrixpacked 

Source
Expand description

§matrixpacked

matrixpacked provides owned and borrowed square matrices in traditional BLAS/LAPACK packed-column storage. It is for applications that already work with packed triangular, symmetric, Hermitian, or positive-definite data and want packed kernels without first expanding to a dense matrix.

Start by choosing a matrix family, understanding the physical layout, selecting an ownership form, and arranging a native provider before linking numerical code.

§Purpose and design

An order-n packed matrix stores n(n+1)/2 scalars instead of n². Methods call traditional packed BLAS/LAPACK families such as xTPMV, xPPTRF, xSPTRF, and xHPEV directly. This avoids an O(n²) dense expansion for operations that have a packed kernel and keeps the caller’s packed layout visible throughout the API.

Packed storage is not universally faster. Dense Level-3 BLAS algorithms use cache and parallel hardware more effectively, and many libraries focus their optimization effort there. Packed formats are most useful when memory, wire formats, an existing LAPACK interface, or compatibility with stored data matters more than peak throughput on large matrices.

§Matrix family map

FamilyStructurePhysical dataLogical unstored entries
PackedLowerlower triangularlower columnszero above diagonal
PackedUpperupper triangularupper columnszero below diagonal
PackedSymmetricAᵀ = Alower columnsmirror, no conjugation
PackedHermitianAᴴ = Alower columnsconjugate mirror
PackedSPDSPD/HPD intentlower columnssymmetric/Hermitian mirror

The LAPACK scalar set is f32, f64, num_complex::Complex32, and num_complex::Complex64 where the underlying routine exists. Some operations are narrower: ordinary symmetric BLAS rank updates are real, while Hermitian operations are complex.

Three distinctions are especially important:

  • PackedSymmetric<Complex<_>> means Aᵀ = A; it does not conjugate.
  • PackedHermitian<Complex<_>> means Aᴴ = A and conjugates mirrored reads.
  • PackedSPD<Complex<_>> records HPD intent. Basic constructors validate the packed length, not positive definiteness. Cholesky-backed operations perform the numerical check.

§Exact packed layout

Coordinates are zero-based. Lower packed-column storage for n = 3 is:

physical: [a00, a10, a20, a11, a21, a22]

logical:  a00   .    .
          a10  a11   .
          a20  a21  a22

For row >= column, the physical index is:

column * (2*n - column + 1) / 2 + (row - column)

Upper packed-column storage for n = 3 is:

physical: [a00, a01, a11, a02, a12, a22]

logical:  a00  a01  a02
           .   a11  a12
           .    .   a22

For row <= column, the physical index is:

column * (column + 1) / 2 + row

Triangular get returns zero for a logical structural zero. Symmetric, Hermitian, and SPD/HPD access maps either triangle to stored lower data, with conjugation for complex Hermitian behavior. Stored-only mutable access rejects structural zeros; indexing panics on invalid or unstored coordinates.

use matrixpacked::PackedLower;

let mut a = PackedLower::from_vec(
    3,
    vec![1.0_f64, 2.0, 3.0, 4.0, 5.0, 6.0],
)?;
assert_eq!(a.get(0, 2)?, 0.0);
assert_eq!(a[(2, 1)], 5.0);
a[(2, 1)] = 9.0;
assert_eq!(a.as_slice(), &[1.0, 2.0, 3.0, 4.0, 9.0, 6.0]);

§Ownership and allocation

The default storage parameter is Vec<T>, so PackedLower<T> is owned. Aliases ending in View borrow &[T]; aliases ending in ViewMut borrow &mut [T]. Views are zero-copy and numerical methods operate directly on the borrowed packed buffer when their mutability permits.

use matrixpacked::PackedSymmetric;

let mut storage = [2.0_f64, 1.0, 3.0];
{
    let mut view = PackedSymmetric::from_slice_mut(2, &mut storage)?;
    view.set(0, 1, 4.0)?;
}
assert_eq!(storage, [2.0, 4.0, 3.0]);

Method names communicate ownership:

  • borrowing methods leave inputs unchanged and copy packed storage when LAPACK must overwrite it;
  • _in_place methods overwrite caller-owned storage;
  • into_ methods consume owned storage and reuse its allocation;
  • methods returning a dense or nalgebra matrix allocate n² scalars.

Factorizations and reductions are destructive at the LAPACK level. Keep the original matrix when refinement or an original-matrix norm is needed. After a factor’s inverse_in_place, its buffer contains the inverse and is no longer a valid factorization.

§Basic operations

Construct owned data with from_vec, generate stored coordinates with from_fn, or borrow slices with from_slice and from_slice_mut. get and set provide checked logical access; as_slice exposes physical packed order.

Elementwise arithmetic operates on corresponding stored values. Binary operators panic on dimension mismatch; component_mul and component_div return PackedMatrixError instead. Matrix-vector products use packed BLAS. Triangular methods expose transpose, conjugate-transpose, and unit-diagonal choices through Transpose and Diagonal.

Real symmetric and complex Hermitian matrices support packed rank-1 and rank-2 updates. Strided variants follow BLAS increment rules. An unrestricted negative update can destroy positive definiteness, so PackedSPD requires conversion to PackedSymmetric or PackedHermitian before those updates are available.

§Linear systems

There are four solve levels:

  1. solve_vector is concise and factors a temporary copy.
  2. solve_once accepts one or more column-major right-hand sides and uses a combined factor-and-solve driver.
  3. A reusable PackedCholesky, PackedSymmetricFactor, or PackedHermitianFactor amortizes factorization across repeated solves.
  4. expert_solve adds reciprocal condition and forward/backward error estimates; SPD/HPD expert solves can request equilibration.

For nrhs right-hand sides, buffers contain consecutive length-n columns. The reusable-factor path is normally the right choice for repeated solves.

use matrixpacked::{MatrixNorm, PackedSPD};

let a = PackedSPD::from_vec(2, vec![4.0_f64, 1.0, 3.0])?;
let factor = a.cholesky()?;
let mut x = factor.solve_vector(&[6.0, 7.0])?;
let report = factor.refine_vector_in_place(&a, &[6.0, 7.0], &mut x)?;
let rcond = factor.rcond(a.matrix_norm(MatrixNorm::One)?)?;
assert_eq!(report.forward_error.len(), 1);
assert!(rcond > 0.0);

Refinement requires both the original matrix and its matching factor. It updates an approximate solution and returns one forward estimate (ferr) and one componentwise backward estimate (berr) per RHS.

§Inverse, norms, conditions, and diagnostics

Prefer solving A x = b over forming A⁻¹: it does less work, uses less storage, and is usually numerically preferable. Explicit packed inverses are available when the inverse itself is required.

MatrixNorm selects max-absolute, one, infinity, or Frobenius norms where supported. Reciprocal condition methods estimate 1 / cond(A); a value near zero indicates sensitivity or singularity. Estimators are approximate and may vary slightly by provider.

Cholesky factors expose determinant and log-determinant diagnostics. Pivoted symmetric/Hermitian factors expose SignedLogDet, Inertia, and singularity tests derived from their 1-by-1 and 2-by-2 blocks. The logarithmic form avoids overflow and underflow. Tolerance-aware inertia uses the caller’s explicit threshold and never introduces a hidden one.

§Eigenproblems and reductions

Real symmetric and complex Hermitian matrices provide:

  • basic eigenvalue/eigenvector drivers;
  • divide-and-conquer drivers, often faster for larger eigenvector problems but with more workspace;
  • selected drivers using all values, a zero-based inclusive index range, or LAPACK’s half-open value interval (lower, upper];
  • generalized symmetric/Hermitian-definite drivers with PackedSPD B.

Eigenvalues are ascending. Eigenvectors are consecutive column-major columns. A real eigenvector is defined only up to sign, a complex vector up to unit phase, and a repeated eigenspace may use any valid orthonormal basis.

GeneralizedEigenproblem selects A x = λ B x, A B x = λ x, or B A x = λ x and documents the associated normalization. Lower-level generalized reduction accepts a Cholesky factor of B. Tridiagonal reduction retains Householder reflectors, exposes the real diagonal/off-diagonal arrays, and can generate dense Q or apply reflectors to a dense column-major target.

§Format conversion and nalgebra interoperability

LAPACK format conversion distinguishes:

TP ↔ TR and TP ↔ RFP use LAPACK conversion routines. RFP stays compact but is a distinct physical layout and must be converted back before ordinary packed operations.

The optional nalgebra-interop feature adds owned nalgebra::DMatrix conversions. It provides conversions, not views: nalgebra’s rectangular stride model cannot describe variable-length packed columns. Structured expansion, tolerance validation, and nalgebra Cholesky-backed SPD/HPD validation are pure Rust. Triangular nalgebra conversion currently follows the TP ↔ TR LAPACK path and therefore needs a native provider at final link.

Extraction constructors ignore the opposite triangle. Strict try_from_dmatrix constructors validate it with:

|a - b| <= absolute + relative * max(|a|, |b|)

Strict SPD/HPD conversion validates structure and then proves positive definiteness with nalgebra Cholesky. See the nalgebra guide for the complete conversion matrix and allocation costs.

§Native BLAS/LAPACK providers

The Rust blas and lapack crates are bindings; a numerical executable must link one native implementation. matrixpacked selects no provider by default so it can coexist with an application’s existing BLAS/LAPACK choice.

  • On Linux, openblas-static bundles OpenBLAS.
  • On Windows, use intel-mkl-static for the repository’s supported bundled provider workflow. Do not assume the non-vcpkg OpenBLAS source build works on Windows.
  • Applications may arrange compatible native symbols themselves.
[dependencies]
matrixpacked = { version = "0.1", features = ["openblas-static"] }

Select only one bundled provider feature. docs.rs enables nalgebra-interop for API visibility but does not link and execute numerical routines while generating ordinary Rustdoc.

Cargo feature unification can enable both bundled providers when separate dependencies request them. The crate deliberately has no compile_error! for that combination, but linking two native implementations can produce conflicting symbols and is not supported. Applications should inspect their resolved features and arrange exactly one native provider. CI verifies that the combined feature set still resolves, without treating it as a supported linked runtime configuration.

§Testing and reproducibility

The repository separates deterministic unit/integration tests, fixed-seed nalgebra oracle properties, and an opt-in extended tier for larger and ill-conditioned problems. Linux uses OpenBLAS-linked commands; Windows uses MKL-linked commands. Property counts and seeds are reproducible with MATRIXPACKED_PROPTEST_CASES and MATRIXPACKED_PROPTEST_SEED. Extended tests also require MATRIXPACKED_EXTENDED_TESTS=1.

# Linux
cargo test --all-targets --features openblas-static

# Windows
cargo test --all-targets --features intel-mkl-static

See the testing guide for backend-qualified commands, replay instructions, runtime, and oracle limitations. The example matrix and routine status remain the detailed sources of truth.

§Errors and numerical behavior

PackedMatrixError separates layout and dimension mistakes from LAPACK argument failures and numerical failures. Common outcomes include a singular triangular diagonal or pivot block, failure of an SPD/HPD leading minor, eigensolver non-convergence, and invalid selected ranges.

Floating-point results are approximate. Compare residuals or use scale-sensitive tolerances rather than exact equality. Ill-conditioned systems can have a small residual but a sensitive solution, so inspect reciprocal condition and refinement estimates. Eigenvectors require sign/phase- and subspace-aware comparison.

§Features and support

FeatureEffectProvider selected?
defaultcore packed APIno
nalgebra-interopowned DMatrix conversion/validationno
openblas-staticstatic OpenBLASyes, Linux workflow
intel-mkl-staticsequential LP64 MKLyes, Windows workflow
ScalarTriangularSymmetricHermitianSPD/HPD
f32, f64yesyesnot distinctyes
Complex32, Complex64yeswhere supportedyesHPD

Exact routine/scalar coverage evolves. Consult PACKED_LAPACK_FUNCTIONS.md instead of inferring availability from the summary table.

§Supported Rust version

The minimum supported Rust version for matrixpacked 0.1.0 is Rust 1.89. This version covers the core crate and the optional nalgebra-interop feature.

§License

Licensed under either the Apache License, Version 2.0 or the MIT license at your option.

Re-exports§

pub use error::PackedMatrixError;
pub use hermitian::PackedHermitian;
pub use hermitian::PackedHermitianView;
pub use hermitian::PackedHermitianViewMut;
pub use lower::PackedLower;
pub use lower::PackedLowerView;
pub use lower::PackedLowerViewMut;
pub use scalar::LapackScalar;
pub use spd::PackedSPD;
pub use spd::PackedSPDView;
pub use spd::PackedSPDViewMut;
pub use symmetric::PackedSymmetric;
pub use symmetric::PackedSymmetricView;
pub use symmetric::PackedSymmetricViewMut;
pub use triangular::ConditionNorm;
pub use triangular::Diagonal;
pub use triangular::MatrixNorm;
pub use triangular::RefinementReport;
pub use triangular::Transpose;
pub use upper::PackedUpper;
pub use upper::PackedUpperView;
pub use upper::PackedUpperViewMut;
pub use factorization::PackedCholesky;
pub use factorization::PackedCholeskyViewMut;
pub use factorization::PackedHermitianFactor;
pub use factorization::PackedHermitianFactorViewMut;
pub use factorization::PackedSymmetricFactor;
pub use factorization::PackedSymmetricFactorViewMut;

Modules§

error
Error reporting for validation and packed numerical operations.
factorization
Reusable packed factorizations preserving the caller’s storage ownership.
hermitian
Complex Hermitian matrices stored by their lower packed triangle.
lower
Lower-triangular matrices in traditional packed-column storage.
scalar
Scalar capabilities shared by packed BLAS/LAPACK APIs.
spd
Symmetric/Hermitian positive-definite-intended packed matrices.
storage
Contiguous storage abstractions behind owned matrices and borrowed views.
symmetric
Transpose-symmetric matrices stored by their lower packed triangle.
triangular
Options and result types shared by packed triangular BLAS/LAPACK operations.
upper
Upper-triangular matrices in traditional packed-column storage.

Structs§

ConversionTolerance
Absolute and relative thresholds for validated nalgebra conversions.
EigenDecomposition
Eigenvalues and optional eigenvectors of an n x n packed matrix.
Equilibration
Scaling information returned by LAPACK xPPEQU.
ExpertSolveOptions
Options for positive-definite expert solves.
ExpertSolveResult
Solution and diagnostics returned by LAPACK expert drivers.
FullTriangular
A triangular matrix in column-major full (TR) storage.
HermitianPackedTridiagonal
Householder representation of a complex-Hermitian tridiagonal reduction.
Inertia
Counts of positive, negative, and zero eigenvalues of a symmetric or Hermitian matrix.
RectangularFullPacked
A triangular matrix in LAPACK rectangular full packed (TF/RFP) storage.
SelectedEigenDecomposition
Selected eigenvalues and optional column-major eigenvectors.
SignedLogDet
A real determinant represented without forming its potentially overflowing or underflowing magnitude.
SymmetricPackedTridiagonal
Householder representation of a real-symmetric tridiagonal reduction.

Enums§

ApplySide
Side on which an orthogonal or unitary reduction matrix is applied.
EigenRange
Selects eigenvalues by all values, a zero-based inclusive index range, or LAPACK’s half-open value interval (lower, upper].
Eigenvectors
Selects whether LAPACK computes eigenvectors as well as eigenvalues.
EquilibrationMode
Controls whether the positive-definite expert driver equilibrates the system.
GeneralizedEigenproblem
Mathematical form of a generalized symmetric/Hermitian definite eigenproblem.
OrthogonalOperation
Operation applied to a real orthogonal reduction matrix.
RfpTranspose
Selects the physical orientation of rectangular full packed (RFP) data.
Triangle
Selects the physically stored triangle of a triangular matrix.
UnitaryOperation
Operation applied to a complex unitary reduction matrix.

Traits§

DefaultConversionTolerance
Supplies a conservative default conversion tolerance for a real scalar type.

Type Aliases§

RectangularFullPackedView
Immutable borrowed RFP storage.
RectangularFullPackedViewMut
Mutable borrowed RFP storage.