use crate::{
FullTriangular, PackedHermitian, PackedLower, PackedMatrixError, PackedSPD, PackedSymmetric,
PackedUpper, Triangle, backend::PackedFormatConversion, storage::PackedStorage,
};
use nalgebra::{ComplexField, DMatrix, Scalar, linalg::Cholesky};
use num_complex::{Complex32, Complex64};
use num_traits::{Float, Zero};
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct ConversionTolerance<R> {
pub absolute: R,
pub relative: R,
}
impl<R> ConversionTolerance<R> {
pub const fn new(absolute: R, relative: R) -> Self {
Self { absolute, relative }
}
}
pub trait DefaultConversionTolerance: Sized {
fn default_conversion_tolerance() -> ConversionTolerance<Self>;
}
macro_rules! impl_default_conversion_tolerance {
($type:ty) => {
impl DefaultConversionTolerance for $type {
fn default_conversion_tolerance() -> ConversionTolerance<Self> {
ConversionTolerance::new(0.0, 8.0 * <$type>::EPSILON)
}
}
impl Default for ConversionTolerance<$type> {
fn default() -> Self {
<$type>::default_conversion_tolerance()
}
}
};
}
impl_default_conversion_tolerance!(f32);
impl_default_conversion_tolerance!(f64);
impl<T> FullTriangular<T>
where
T: Scalar,
{
pub fn to_dmatrix(&self) -> DMatrix<T> {
DMatrix::from_vec(self.dimension(), self.dimension(), self.as_slice().to_vec())
}
pub fn into_dmatrix(self) -> DMatrix<T> {
let dimension = self.dimension();
DMatrix::from_vec(dimension, dimension, self.into_vec())
}
}
impl<T> FullTriangular<T>
where
T: Scalar + Zero,
{
pub fn try_from_dmatrix(
matrix: &DMatrix<T>,
triangle: Triangle,
) -> Result<Self, PackedMatrixError> {
let (rows, columns) = matrix.shape();
if rows != columns {
return Err(PackedMatrixError::NonSquareMatrix { rows, columns });
}
let mut data = matrix.as_slice().to_vec();
for column in 0..columns {
for row in 0..rows {
let is_structural_zero = match triangle {
Triangle::Lower => row < column,
Triangle::Upper => row > column,
};
if is_structural_zero {
data[column * rows + row] = T::zero();
}
}
}
Self::from_vec(rows, triangle, data)
}
}
impl<T> From<FullTriangular<T>> for DMatrix<T>
where
T: Scalar,
{
fn from(matrix: FullTriangular<T>) -> Self {
matrix.into_dmatrix()
}
}
macro_rules! impl_packed_to_dmatrix {
($packed:ident) => {
#[allow(private_bounds)]
impl<T, S> $packed<T, S>
where
T: PackedFormatConversion + Scalar,
S: PackedStorage<T>,
{
pub fn to_dmatrix(&self) -> Result<DMatrix<T>, PackedMatrixError> {
Ok(self.to_full_triangular()?.into_dmatrix())
}
}
};
}
impl_packed_to_dmatrix!(PackedLower);
impl_packed_to_dmatrix!(PackedUpper);
#[allow(private_bounds)]
impl<T> PackedLower<T>
where
T: PackedFormatConversion + Scalar + Zero,
{
pub fn from_lower_triangle(matrix: &DMatrix<T>) -> Result<Self, PackedMatrixError> {
let full = FullTriangular::try_from_dmatrix(matrix, Triangle::Lower)?;
Self::from_full_triangular(&full)
}
}
#[allow(private_bounds)]
impl<T> PackedUpper<T>
where
T: PackedFormatConversion + Scalar + Zero,
{
pub fn from_upper_triangle(matrix: &DMatrix<T>) -> Result<Self, PackedMatrixError> {
let full = FullTriangular::try_from_dmatrix(matrix, Triangle::Upper)?;
Self::from_full_triangular(&full)
}
}
trait StructuredScalar: Scalar + Copy + Zero {
fn conjugate(self) -> Self;
fn hermitian_diagonal(self) -> Self;
}
macro_rules! impl_real_structured_scalar {
($type:ty) => {
impl StructuredScalar for $type {
fn conjugate(self) -> Self {
self
}
fn hermitian_diagonal(self) -> Self {
self
}
}
};
}
impl_real_structured_scalar!(f32);
impl_real_structured_scalar!(f64);
macro_rules! impl_complex_structured_scalar {
($type:ty) => {
impl StructuredScalar for $type {
fn conjugate(self) -> Self {
self.conj()
}
fn hermitian_diagonal(self) -> Self {
Self::new(self.re, 0.0)
}
}
};
}
impl_complex_structured_scalar!(Complex32);
impl_complex_structured_scalar!(Complex64);
trait ValidationScalar:
StructuredScalar
+ crate::LapackScalar
+ ComplexField<RealField = <Self as crate::LapackScalar>::Real>
where
<Self as crate::LapackScalar>::Real: Float,
{
const IS_COMPLEX: bool;
}
macro_rules! impl_validation_scalar {
($type:ty, $is_complex:expr) => {
impl ValidationScalar for $type {
const IS_COMPLEX: bool = $is_complex;
}
};
}
impl_validation_scalar!(f32, false);
impl_validation_scalar!(f64, false);
impl_validation_scalar!(Complex32, true);
impl_validation_scalar!(Complex64, true);
fn validate_tolerance<R: Float>(
tolerance: ConversionTolerance<R>,
) -> Result<(), PackedMatrixError> {
for (component, value) in [
("absolute", tolerance.absolute),
("relative", tolerance.relative),
] {
if !value.is_finite() {
return Err(PackedMatrixError::InvalidTolerance {
component,
reason: "must be finite",
});
}
if value < R::zero() {
return Err(PackedMatrixError::InvalidTolerance {
component,
reason: "must be nonnegative",
});
}
}
Ok(())
}
fn approximately_equal<T: ValidationScalar>(
left: T,
right: T,
tolerance: ConversionTolerance<<T as crate::LapackScalar>::Real>,
) -> bool
where
<T as crate::LapackScalar>::Real: Float,
{
let difference = (left - right).modulus();
let left_magnitude = left.modulus();
let right_magnitude = right.modulus();
let scale = if left_magnitude > right_magnitude {
left_magnitude
} else {
right_magnitude
};
difference <= tolerance.absolute + tolerance.relative * scale
}
fn approximately_real<T: ValidationScalar>(
value: T,
tolerance: ConversionTolerance<<T as crate::LapackScalar>::Real>,
) -> bool
where
<T as crate::LapackScalar>::Real: Float,
{
let imaginary = value.imaginary().abs();
imaginary <= tolerance.absolute + tolerance.relative * value.modulus()
}
fn square_dimension<T>(matrix: &DMatrix<T>) -> Result<usize, PackedMatrixError> {
let (rows, columns) = matrix.shape();
if rows != columns {
return Err(PackedMatrixError::NonSquareMatrix { rows, columns });
}
Ok(rows)
}
fn validate_triangle<T: ValidationScalar>(
matrix: &DMatrix<T>,
triangle: Triangle,
tolerance: ConversionTolerance<<T as crate::LapackScalar>::Real>,
) -> Result<usize, PackedMatrixError>
where
<T as crate::LapackScalar>::Real: Float,
{
let dimension = square_dimension(matrix)?;
validate_tolerance(tolerance)?;
for column in 0..dimension {
for row in 0..dimension {
let is_opposite = match triangle {
Triangle::Lower => row < column,
Triangle::Upper => row > column,
};
if is_opposite && !approximately_equal(matrix[(row, column)], T::zero(), tolerance) {
return Err(PackedMatrixError::NotTriangular {
triangle: match triangle {
Triangle::Lower => "lower",
Triangle::Upper => "upper",
},
row,
column,
});
}
}
}
Ok(dimension)
}
fn pack_triangle<T: ValidationScalar>(matrix: &DMatrix<T>, triangle: Triangle) -> Vec<T>
where
<T as crate::LapackScalar>::Real: Float,
{
let dimension = matrix.nrows();
let mut packed = Vec::with_capacity(dimension * (dimension + 1) / 2);
for column in 0..dimension {
let rows = match triangle {
Triangle::Lower => column..dimension,
Triangle::Upper => 0..column + 1,
};
for row in rows {
packed.push(matrix[(row, column)]);
}
}
packed
}
fn validate_symmetric<T: ValidationScalar>(
matrix: &DMatrix<T>,
tolerance: ConversionTolerance<<T as crate::LapackScalar>::Real>,
) -> Result<usize, PackedMatrixError>
where
<T as crate::LapackScalar>::Real: Float,
{
let dimension = square_dimension(matrix)?;
validate_tolerance(tolerance)?;
for column in 0..dimension {
for row in column + 1..dimension {
if !approximately_equal(matrix[(row, column)], matrix[(column, row)], tolerance) {
return Err(PackedMatrixError::NotSymmetric { row, column });
}
}
}
Ok(dimension)
}
fn validate_hermitian<T: ValidationScalar>(
matrix: &DMatrix<T>,
tolerance: ConversionTolerance<<T as crate::LapackScalar>::Real>,
) -> Result<usize, PackedMatrixError>
where
<T as crate::LapackScalar>::Real: Float,
{
let dimension = square_dimension(matrix)?;
validate_tolerance(tolerance)?;
for index in 0..dimension {
if !approximately_real(matrix[(index, index)], tolerance) {
return Err(PackedMatrixError::NonRealHermitianDiagonal { index });
}
}
for column in 0..dimension {
for row in column + 1..dimension {
if !approximately_equal(
matrix[(row, column)],
ComplexField::conjugate(matrix[(column, row)]),
tolerance,
) {
return Err(PackedMatrixError::NotHermitian { row, column });
}
}
}
Ok(dimension)
}
#[derive(Clone, Copy)]
enum Reconstruction {
Symmetric,
Hermitian,
}
fn expand_lower_packed<T: StructuredScalar>(
dimension: usize,
packed: &[T],
reconstruction: Reconstruction,
) -> DMatrix<T> {
let mut data = vec![T::zero(); dimension * dimension];
let mut packed_index = 0;
for column in 0..dimension {
for row in column..dimension {
let value = packed[packed_index];
packed_index += 1;
if row == column {
data[column * dimension + row] = match reconstruction {
Reconstruction::Symmetric => value,
Reconstruction::Hermitian => value.hermitian_diagonal(),
};
} else {
data[column * dimension + row] = value;
data[row * dimension + column] = match reconstruction {
Reconstruction::Symmetric => value,
Reconstruction::Hermitian => value.conjugate(),
};
}
}
}
DMatrix::from_vec(dimension, dimension, data)
}
fn extract_lower<T: StructuredScalar>(
matrix: &DMatrix<T>,
canonicalize_diagonal: bool,
) -> Result<Vec<T>, PackedMatrixError> {
let (rows, columns) = matrix.shape();
if rows != columns {
return Err(PackedMatrixError::NonSquareMatrix { rows, columns });
}
let mut packed = Vec::with_capacity(rows * (rows + 1) / 2);
for column in 0..columns {
for row in column..rows {
let value = matrix[(row, column)];
packed.push(if canonicalize_diagonal && row == column {
value.hermitian_diagonal()
} else {
value
});
}
}
Ok(packed)
}
#[allow(private_bounds)]
impl<T, S> PackedSymmetric<T, S>
where
T: StructuredScalar,
S: PackedStorage<T>,
{
pub fn to_dmatrix(&self) -> DMatrix<T> {
expand_lower_packed(self.dimension(), self.as_slice(), Reconstruction::Symmetric)
}
}
#[allow(private_bounds)]
impl<T> PackedSymmetric<T>
where
T: StructuredScalar,
{
pub fn from_lower_triangle(matrix: &DMatrix<T>) -> Result<Self, PackedMatrixError> {
Self::from_vec(matrix.nrows(), extract_lower(matrix, false)?)
}
}
#[allow(private_bounds)]
impl<T, S> PackedHermitian<T, S>
where
T: StructuredScalar,
S: PackedStorage<T>,
{
pub fn to_dmatrix(&self) -> DMatrix<T> {
expand_lower_packed(self.dimension(), self.as_slice(), Reconstruction::Hermitian)
}
}
#[allow(private_bounds)]
impl<T> PackedHermitian<T>
where
T: StructuredScalar,
{
pub fn from_lower_triangle(matrix: &DMatrix<T>) -> Result<Self, PackedMatrixError> {
Self::from_vec(matrix.nrows(), extract_lower(matrix, true)?)
}
}
#[allow(private_bounds)]
impl<T, S> PackedSPD<T, S>
where
T: StructuredScalar,
S: PackedStorage<T>,
{
pub fn to_dmatrix(&self) -> DMatrix<T> {
expand_lower_packed(self.dimension(), self.as_slice(), Reconstruction::Hermitian)
}
}
#[allow(private_bounds)]
impl<T> PackedSPD<T>
where
T: StructuredScalar,
{
pub fn from_lower_triangle_unchecked_structure(
matrix: &DMatrix<T>,
) -> Result<Self, PackedMatrixError> {
Self::from_vec(matrix.nrows(), extract_lower(matrix, true)?)
}
}
#[allow(private_bounds)]
impl<T> PackedLower<T>
where
T: ValidationScalar,
<T as crate::LapackScalar>::Real: Float,
{
pub fn try_from_dmatrix(
matrix: &DMatrix<T>,
tolerance: ConversionTolerance<<T as crate::LapackScalar>::Real>,
) -> Result<Self, PackedMatrixError> {
let dimension = validate_triangle(matrix, Triangle::Lower, tolerance)?;
Self::from_vec(dimension, pack_triangle(matrix, Triangle::Lower))
}
}
#[allow(private_bounds)]
impl<T> PackedUpper<T>
where
T: ValidationScalar,
<T as crate::LapackScalar>::Real: Float,
{
pub fn try_from_dmatrix(
matrix: &DMatrix<T>,
tolerance: ConversionTolerance<<T as crate::LapackScalar>::Real>,
) -> Result<Self, PackedMatrixError> {
let dimension = validate_triangle(matrix, Triangle::Upper, tolerance)?;
Self::from_vec(dimension, pack_triangle(matrix, Triangle::Upper))
}
}
#[allow(private_bounds)]
impl<T> PackedSymmetric<T>
where
T: ValidationScalar,
<T as crate::LapackScalar>::Real: Float,
{
pub fn try_from_dmatrix(
matrix: &DMatrix<T>,
tolerance: ConversionTolerance<<T as crate::LapackScalar>::Real>,
) -> Result<Self, PackedMatrixError> {
let dimension = validate_symmetric(matrix, tolerance)?;
Self::from_vec(dimension, extract_lower(matrix, false)?)
}
}
#[allow(private_bounds)]
impl<T> PackedHermitian<T>
where
T: ValidationScalar,
<T as crate::LapackScalar>::Real: Float,
{
pub fn try_from_dmatrix(
matrix: &DMatrix<T>,
tolerance: ConversionTolerance<<T as crate::LapackScalar>::Real>,
) -> Result<Self, PackedMatrixError> {
let dimension = validate_hermitian(matrix, tolerance)?;
Self::from_vec(dimension, extract_lower(matrix, true)?)
}
}
#[allow(private_bounds)]
impl<T> PackedSPD<T>
where
T: ValidationScalar,
<T as crate::LapackScalar>::Real: Float,
{
pub fn try_from_structured_dmatrix(
matrix: &DMatrix<T>,
tolerance: ConversionTolerance<<T as crate::LapackScalar>::Real>,
) -> Result<Self, PackedMatrixError> {
let dimension = if T::IS_COMPLEX {
validate_hermitian(matrix, tolerance)?
} else {
validate_symmetric(matrix, tolerance)?
};
Self::from_vec(dimension, extract_lower(matrix, true)?)
}
pub fn try_from_dmatrix(
matrix: &DMatrix<T>,
tolerance: ConversionTolerance<<T as crate::LapackScalar>::Real>,
) -> Result<Self, PackedMatrixError> {
let packed = Self::try_from_structured_dmatrix(matrix, tolerance)?;
let Some(cholesky) = Cholesky::new(packed.to_dmatrix()) else {
return Err(PackedMatrixError::NotPositiveDefinite);
};
let factor = cholesky.unpack_dirty();
for index in 0..factor.nrows() {
let diagonal = factor[(index, index)];
if !diagonal.real().is_finite()
|| !diagonal.imaginary().is_zero()
|| diagonal.real() <= <T as crate::LapackScalar>::Real::zero()
{
return Err(PackedMatrixError::NotPositiveDefinite);
}
}
Ok(packed)
}
}