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;