Skip to main content

tensor4all_core/matrixluci/
scalar.rs

1//! Scalar capability for MatrixLUCI implementations.
2
3use num_complex::{Complex32, Complex64};
4
5use crate::error::Result;
6use crate::matrix_luci::MatrixLuciFactors;
7use crate::matrixlu::RrLUOptions;
8use tensor4all_tensorbackend::{
9    explicit::Session, BackendLinalgError, BackendLinalgScalar, Matrix, MatrixSolveScalar,
10    MatrixTriangularSolveScalar,
11};
12
13mod private {
14    // The dispatch methods below route into crate-internal kernels, so an
15    // out-of-crate implementation could not produce real LUCI factors.
16    pub(super) trait Sealed {}
17}
18
19/// Scalar types supported by MatrixLUCI factorization.
20///
21/// Common arithmetic comes from [`crate::Scalar`]; this trait adds only the
22/// backend solve capabilities and MatrixLUCI dispatch used by the factorizer.
23///
24/// The trait is sealed; use `f32`, `f64`, [`Complex32`], or [`Complex64`].
25#[allow(private_bounds)]
26pub trait MatrixLuciScalar:
27    crate::Scalar
28    + BackendLinalgScalar
29    + MatrixSolveScalar
30    + MatrixTriangularSolveScalar
31    + private::Sealed
32{
33    #[doc(hidden)]
34    fn matrix_luci_factors_from_matrix(
35        a: &Matrix<Self>,
36        options: RrLUOptions,
37    ) -> Result<MatrixLuciFactors<Self>>
38    where
39        Self: Sized;
40
41    #[doc(hidden)]
42    fn matrix_luci_factors_from_blocks<F>(
43        nrows: usize,
44        ncols: usize,
45        fill_block: F,
46        options: RrLUOptions,
47    ) -> Result<MatrixLuciFactors<Self>>
48    where
49        F: Fn(&[usize], &[usize], &mut [Self]),
50        Self: Sized;
51
52    /// [`Self::matrix_luci_factors_from_blocks`] with the previous pivots of
53    /// the same candidate matrix as the rook search's starting points.
54    ///
55    /// Seeds only move where the rook walks start and carry no error guarantee,
56    /// so they cannot loosen the stop rule. Ignoring them is a valid, unseeded
57    /// factorization; the supported scalars forward them to the kernel.
58    #[doc(hidden)]
59    fn matrix_luci_factors_from_blocks_seeded<F>(
60        nrows: usize,
61        ncols: usize,
62        fill_block: F,
63        seeds: &[(usize, usize)],
64        options: RrLUOptions,
65    ) -> Result<MatrixLuciFactors<Self>>
66    where
67        F: Fn(&[usize], &[usize], &mut [Self]),
68        Self: Sized;
69
70    /// Triangular solve on an explicit session (non-unit diagonal, no transpose).
71    #[doc(hidden)]
72    fn matrix_luci_triangular_solve_in(
73        session: &mut Session<'_>,
74        a: &Matrix<Self>,
75        b: &Matrix<Self>,
76        left_side: bool,
77        lower: bool,
78    ) -> std::result::Result<Matrix<Self>, BackendLinalgError>
79    where
80        Self: Sized;
81}
82
83macro_rules! impl_matrix_luci_scalar {
84    ($($ty:ty),* $(,)?) => {
85        $(
86            impl private::Sealed for $ty {}
87
88            impl MatrixLuciScalar for $ty {
89                fn matrix_luci_factors_from_matrix(
90                    a: &Matrix<Self>,
91                    options: RrLUOptions,
92                ) -> Result<MatrixLuciFactors<Self>> {
93                    crate::matrix_luci::dense_matrix_luci_factors_from_matrix(a, options)
94                }
95
96                fn matrix_luci_factors_from_blocks<F>(
97                    nrows: usize,
98                    ncols: usize,
99                    fill_block: F,
100                    options: RrLUOptions,
101                ) -> Result<MatrixLuciFactors<Self>>
102                where
103                    F: Fn(&[usize], &[usize], &mut [Self]),
104                {
105                    crate::matrix_luci::lazy_matrix_luci_factors_from_blocks(
106                        nrows, ncols, fill_block, options,
107                    )
108                }
109
110                fn matrix_luci_factors_from_blocks_seeded<F>(
111                    nrows: usize,
112                    ncols: usize,
113                    fill_block: F,
114                    seeds: &[(usize, usize)],
115                    options: RrLUOptions,
116                ) -> Result<MatrixLuciFactors<Self>>
117                where
118                    F: Fn(&[usize], &[usize], &mut [Self]),
119                {
120                    crate::matrix_luci::lazy_matrix_luci_factors_from_blocks_seeded(
121                        nrows, ncols, fill_block, seeds, options,
122                    )
123                }
124
125                fn matrix_luci_triangular_solve_in(
126                    session: &mut Session<'_>,
127                    a: &Matrix<Self>,
128                    b: &Matrix<Self>,
129                    left_side: bool,
130                    lower: bool,
131                ) -> std::result::Result<Matrix<Self>, BackendLinalgError> {
132                    session.triangular_solve_matrix(a, b, left_side, lower, false, false)
133                }
134            }
135        )*
136    };
137}
138
139impl_matrix_luci_scalar!(f64, f32, Complex64, Complex32);
140
141#[cfg(test)]
142mod tests;