Skip to main content

tenferro_linalg/
flags.rs

1//! Control enums for linear-algebra operations (the #2552 grammar).
2//!
3//! These replace control `bool` arguments. They are linalg-only; `Conj` is
4//! shared and lives in `tenferro-tensor`.
5
6/// Which side the matrix operand acts from.
7///
8/// # Examples
9///
10/// ```
11/// use tenferro_linalg::Side;
12///
13/// assert_eq!(Side::default(), Side::Left);
14/// ```
15#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Default)]
16pub enum Side {
17    /// The matrix acts from the left.
18    #[default]
19    Left,
20    /// The matrix acts from the right.
21    Right,
22}
23
24/// Which triangle of a matrix is referenced.
25///
26/// # Examples
27///
28/// ```
29/// use tenferro_linalg::Uplo;
30///
31/// assert_eq!(Uplo::default(), Uplo::Lower);
32/// ```
33#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Default)]
34pub enum Uplo {
35    /// The lower triangle.
36    #[default]
37    Lower,
38    /// The upper triangle.
39    Upper,
40}
41
42/// Transformation applied to a matrix operand.
43///
44/// `Adjoint` is the conjugate transpose; an operation that cannot honour it for
45/// complex input returns `Error::Unsupported` instead of treating it as
46/// `Transpose`.
47///
48/// # Examples
49///
50/// ```
51/// use tenferro_linalg::MatOp;
52///
53/// assert_eq!(MatOp::default(), MatOp::None);
54/// ```
55#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Default)]
56pub enum MatOp {
57    /// Use the matrix as it is.
58    #[default]
59    None,
60    /// Use the transpose.
61    Transpose,
62    /// Use the conjugate transpose.
63    Adjoint,
64}
65
66/// Whether a triangular matrix has an implicit unit diagonal.
67///
68/// # Examples
69///
70/// ```
71/// use tenferro_linalg::Diag;
72///
73/// assert_eq!(Diag::default(), Diag::NonUnit);
74/// ```
75#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Default)]
76pub enum Diag {
77    /// The diagonal is stored and used.
78    #[default]
79    NonUnit,
80    /// The diagonal is implicitly one.
81    Unit,
82}
83
84/// Whether a reduction keeps reduced axes as size-one axes.
85///
86/// # Examples
87///
88/// ```
89/// use tenferro_linalg::KeepDims;
90///
91/// assert_eq!(KeepDims::default(), KeepDims::No);
92/// ```
93#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Default)]
94pub enum KeepDims {
95    /// Drop the reduced axes.
96    #[default]
97    No,
98    /// Keep the reduced axes with size one.
99    Yes,
100}
101
102/// Whether an SVD returns the thin or the full-matrices factors.
103///
104/// # Examples
105///
106/// ```
107/// use tenferro_linalg::SvdShape;
108///
109/// assert_eq!(SvdShape::default(), SvdShape::Thin);
110/// ```
111#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Default)]
112pub enum SvdShape {
113    /// `U` is `m x k` and `Vh` is `k x n` with `k = min(m, n)`.
114    #[default]
115    Thin,
116    /// `U` is `m x m` and `Vh` is `n x n`; the trailing rows of `Vh` span the
117    /// right nullspace.
118    Full,
119}