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
| Family | Structure | Physical data | Logical unstored entries |
|---|---|---|---|
PackedLower | lower triangular | lower columns | zero above diagonal |
PackedUpper | upper triangular | upper columns | zero below diagonal |
PackedSymmetric | Aᵀ = A | lower columns | mirror, no conjugation |
PackedHermitian | Aᴴ = A | lower columns | conjugate mirror |
PackedSPD | SPD/HPD intent | lower columns | symmetric/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<_>>meansAᵀ = A; it does not conjugate.PackedHermitian<Complex<_>>meansAᴴ = Aand 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 a22For 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
. . a22For row <= column, the physical index is:
column * (column + 1) / 2 + rowTriangular 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_placemethods 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:
solve_vectoris concise and factors a temporary copy.solve_onceaccepts one or more column-major right-hand sides and uses a combined factor-and-solve driver.- A reusable
PackedCholesky,PackedSymmetricFactor, orPackedHermitianFactoramortizes factorization across repeated solves. expert_solveadds 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
PackedSPDB.
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: traditional
PackedLowerorPackedUpperstorage; - TR:
FullTriangular, ann × ncolumn-major triangular buffer; - TF/RFP:
RectangularFullPacked, a compact rectangular rearrangement.
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-staticbundles OpenBLAS. - On Windows, use
intel-mkl-staticfor 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-staticSee 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
| Feature | Effect | Provider selected? |
|---|---|---|
| default | core packed API | no |
nalgebra-interop | owned DMatrix conversion/validation | no |
openblas-static | static OpenBLAS | yes, Linux workflow |
intel-mkl-static | sequential LP64 MKL | yes, Windows workflow |
| Scalar | Triangular | Symmetric | Hermitian | SPD/HPD |
|---|---|---|---|---|
f32, f64 | yes | yes | not distinct | yes |
Complex32, Complex64 | yes | where supported | yes | HPD |
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§
- Conversion
Tolerance - Absolute and relative thresholds for validated nalgebra conversions.
- Eigen
Decomposition - Eigenvalues and optional eigenvectors of an
n x npacked matrix. - Equilibration
- Scaling information returned by LAPACK
xPPEQU. - Expert
Solve Options - Options for positive-definite expert solves.
- Expert
Solve Result - Solution and diagnostics returned by LAPACK expert drivers.
- Full
Triangular - A triangular matrix in column-major full (
TR) storage. - Hermitian
Packed Tridiagonal - Householder representation of a complex-Hermitian tridiagonal reduction.
- Inertia
- Counts of positive, negative, and zero eigenvalues of a symmetric or Hermitian matrix.
- Rectangular
Full Packed - A triangular matrix in LAPACK rectangular full packed (
TF/RFP) storage. - Selected
Eigen Decomposition - Selected eigenvalues and optional column-major eigenvectors.
- Signed
LogDet - A real determinant represented without forming its potentially overflowing or underflowing magnitude.
- Symmetric
Packed Tridiagonal - Householder representation of a real-symmetric tridiagonal reduction.
Enums§
- Apply
Side - Side on which an orthogonal or unitary reduction matrix is applied.
- Eigen
Range - 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.
- Equilibration
Mode - Controls whether the positive-definite expert driver equilibrates the system.
- Generalized
Eigenproblem - Mathematical form of a generalized symmetric/Hermitian definite eigenproblem.
- Orthogonal
Operation - 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.
- Unitary
Operation - Operation applied to a complex unitary reduction matrix.
Traits§
- Default
Conversion Tolerance - Supplies a conservative default conversion tolerance for a real scalar type.
Type Aliases§
- Rectangular
Full Packed View - Immutable borrowed RFP storage.
- Rectangular
Full Packed View Mut - Mutable borrowed RFP storage.