Skip to main content

tenferro_linalg/cpu/
tlinalg_error.rs

1//! Translation of a provider failure into tenferro's error vocabulary.
2//!
3//! The extracted provider (`tlinalg`) owns its own error enum; the interface tenferro requires
4//! lives here, so the mapping does too. The mapping is one-to-one on kind, role and typed source,
5//! because callers downcast the source and classify by kind.
6
7/// Rebuild tenferro's error from a `tlinalg` (faer route) failure.
8///
9/// This is the translation tenferro's own linalg entries apply to every `tlinalg` failure. A
10/// caller that runs `tlinalg` factorizations itself, for example on the bundle
11/// `tenferro_cpu::CpuEngine::with_exec` lends, calls it to report
12/// exactly the error tenferro would have reported for the same failure. The types are those of the
13/// `tlinalg` build this crate links, so a caller names them through a `tlinalg` dependency of the
14/// same semver-compatible version.
15///
16/// # Contract
17///
18/// The mapping is total and never panics. It is decided in two steps:
19///
20/// 1. **Operation name.** Every error it builds names `op.as_str()` from the `op` argument. The
21///    `op` field stored inside `error` is not consulted, so when the two disagree the argument
22///    wins. The only place the inner `op` survives is the typed source of
23///    `InsufficientWorkspace`, which is the provider error itself.
24/// 2. **Variant.** One `match` on the `tlinalg::Error` variant. The arms are disjoint, so their
25///    order does not change the result; the catch-all arm is last and fires only for a variant no
26///    arm names.
27///
28/// | `tlinalg::Error` | tenferro error | [`ErrorKind`](tenferro_tensor::ErrorKind) | Downcastable source |
29/// | --- | --- | --- | --- |
30/// | `NonConvergence` | `Extension` (linalg family) | `NumericalFailure` | [`Error::NonConvergence`](crate::Error::NonConvergence) `{ op }` |
31/// | `NonFinite { role }` | `Extension` (linalg family) | `NumericalFailure` | [`Error::NonFinite`](crate::Error::NonFinite) `{ op, role: role.as_str() }` |
32/// | `Singular` | `Extension` (linalg family) | `NumericalFailure` | [`Error::Singular`](crate::Error::Singular) `{ op }` |
33/// | `InvalidArgument { role, detail }` | `Validation` | `Validation(InvalidArgument)` | `ValidationError::InvalidArgument { argument: role, message: detail }` |
34/// | `InvalidWorkspace { library, routine, detail }` | `BackendSource` | `BackendFailure` | crate-private; `library`, `routine` and `detail` are in the message |
35/// | `Inconsistent { detail }` | `Internal("{op}: {detail}")` | `Internal` | none |
36/// | `InsufficientWorkspace` | `RuntimeStateSource` | `RuntimeState` | the `tlinalg::Error` itself, `op`, `needed` and `have` included |
37/// | any other variant | `Internal("{op}: unmapped linalg provider error {error:?}")` | `Internal` | none |
38///
39/// The last row is the case that cannot be represented. `tlinalg::Error` is
40/// `#[non_exhaustive]`, so a later `tlinalg` may add a variant this crate does not know. The
41/// mapping does not guess a kind for it: it returns the generic `Internal` variant with the
42/// provider error's `Debug` text, so the failure stays visible and is never misclassified as a
43/// numerical or caller error. Against the `tlinalg` this crate links, every variant has its own
44/// row and the last row is unreachable.
45///
46/// # Examples
47///
48/// ```rust
49/// use std::error::Error as _;
50/// use tenferro_tensor::ErrorKind;
51///
52/// let error = tenferro_linalg::error::map_error(
53///     tlinalg::Op::Svd,
54///     tlinalg::Error::NonConvergence { op: tlinalg::Op::Svd },
55/// );
56/// assert_eq!(error.kind(), ErrorKind::NumericalFailure);
57/// assert!(matches!(
58///     error.source().and_then(|source| source.downcast_ref()),
59///     Some(tenferro_linalg::Error::NonConvergence { op: "svd" })
60/// ));
61/// ```
62pub fn map_error(op: tlinalg::Op, error: tlinalg::Error) -> tenferro_tensor::Error {
63    use tlinalg::Error as ProviderError;
64    let op_str = op.as_str();
65    match error {
66        ProviderError::NonConvergence { .. } => {
67            crate::error::into_tensor_error(op_str, crate::Error::NonConvergence { op: op_str })
68        }
69        ProviderError::NonFinite { role, .. } => crate::error::into_tensor_error(
70            op_str,
71            crate::Error::NonFinite {
72                op: op_str,
73                role: role.as_str(),
74            },
75        ),
76        ProviderError::Singular { .. } => {
77            crate::error::into_tensor_error(op_str, crate::Error::Singular { op: op_str })
78        }
79        ProviderError::InvalidArgument { role, detail, .. } => {
80            tenferro_tensor::Error::invalid_argument(op_str, role, detail)
81        }
82        ProviderError::InvalidWorkspace {
83            library,
84            routine,
85            detail,
86            ..
87        } => crate::error::invalid_workspace(op_str, library, routine, detail),
88        ProviderError::Inconsistent { detail, .. } => {
89            tenferro_tensor::Error::Internal(format!("{op_str}: {detail}"))
90        }
91        // The host sizes every call with the matching `*_workspace` query at the
92        // same `Exec`, so a short region is a broken host contract rather than a
93        // caller error. Keep the provider error as the typed source: it names the
94        // bytes the resolved route wanted against the bytes it was given.
95        ProviderError::InsufficientWorkspace { .. } => {
96            tenferro_tensor::Error::runtime_state_source(op_str, error)
97        }
98        // The provider enum is non-exhaustive so a new variant is not a breaking
99        // change for the crate that reports it. The host cannot reproduce a payload
100        // it does not know, so it fails loudly instead of guessing a kind and
101        // silently misclassifying the failure.
102        other => tenferro_tensor::Error::Internal(format!(
103            "{op_str}: unmapped linalg provider error {other:?}"
104        )),
105    }
106}
107
108#[cfg(test)]
109#[path = "tlinalg_error/tests.rs"]
110mod tests;