Skip to main content

tenferro_linalg/ad/
support.rs

1#[cfg(test)]
2use crate::extension::LinalgOp;
3
4/// AD rule support status for a linalg operation or output.
5///
6/// # Examples
7///
8/// ```rust
9/// use tenferro_linalg::{linalg_ad_support, LinalgAdOpKind, LinalgAdRuleSupport};
10///
11/// let svd = linalg_ad_support(LinalgAdOpKind::Svd);
12/// assert_eq!(svd.linearize, LinalgAdRuleSupport::SupportedViaLinearize);
13/// ```
14#[derive(Clone, Copy, Debug, PartialEq, Eq)]
15pub enum LinalgAdRuleSupport {
16    Supported,
17    SupportedViaLinearize,
18    PartiallySupported,
19    NonDifferentiable,
20    Unsupported,
21    PendingOracle,
22}
23
24/// Implementation route used for a user-visible AD mode.
25///
26/// # Examples
27///
28/// ```rust
29/// use tenferro_linalg::{linalg_ad_support, LinalgAdOpKind, LinalgAdRoute};
30///
31/// let svd = linalg_ad_support(LinalgAdOpKind::Svd);
32/// assert_eq!(svd.vjp.route, LinalgAdRoute::LinearizeThenTranspose);
33/// ```
34#[derive(Clone, Copy, Debug, PartialEq, Eq)]
35pub enum LinalgAdRoute {
36    /// No supported route exists.
37    Unsupported,
38    /// The mode is emitted directly by the operation's linearize rule.
39    Linearize,
40    /// Reverse mode is supported by linearizing the primal graph and then
41    /// transposing that linear graph.
42    LinearizeThenTranspose,
43    /// Reverse mode is supported by linearizing the primal graph and using a
44    /// custom transposed-linear rule for the emitted linear operation.
45    LinearizeThenCustomLinearTranspose,
46    /// Reverse mode is emitted by a direct operation-specific primal VJP rule.
47    CustomVjp,
48    /// A custom VJP is preferred, with the canonical linearize-then-transpose
49    /// route retained as an intentional not-applicable fallback.
50    CustomPreferredWithLinearizeFallback,
51}
52
53/// User-visible AD support for one mode.
54///
55/// # Examples
56///
57/// ```rust
58/// use tenferro_linalg::{linalg_ad_support, LinalgAdOpKind, LinalgAdRoute};
59///
60/// let solve = linalg_ad_support(LinalgAdOpKind::TriangularSolve);
61/// assert_eq!(solve.vjp.route, LinalgAdRoute::LinearizeThenCustomLinearTranspose);
62/// ```
63#[derive(Clone, Copy, Debug, PartialEq, Eq)]
64pub struct LinalgAdModeSupport {
65    /// Whether the user-visible mode is supported.
66    pub status: LinalgAdRuleSupport,
67    /// How the mode is implemented.
68    pub route: LinalgAdRoute,
69}
70
71/// Operation keys covered by the linalg AD support manifest.
72///
73/// # Examples
74///
75/// ```rust
76/// use tenferro_linalg::LinalgAdOpKind;
77///
78/// assert!(LinalgAdOpKind::Svd.as_index() < LinalgAdOpKind::COUNT);
79/// ```
80#[derive(Clone, Copy, Debug, PartialEq, Eq)]
81pub enum LinalgAdOpKind {
82    Cholesky,
83    Lu,
84    LuFactor,
85    SignDetFromLuFactor,
86    LogAbsDetFromLuFactor,
87    LuSolvePrepared,
88    FullPivLu,
89    FullPivLuSolve,
90    Svd,
91    SvdVals,
92    Qr,
93    Eigh,
94    EighVals,
95    Eig,
96    EigVals,
97    TriangularSolve,
98    SvdFull,
99    HouseholderQrFactor,
100    HouseholderQrFromFactors,
101    HouseholderQrAppend,
102    HouseholderQrR,
103    HouseholderQrQColumns,
104    HouseholderQrThinQ,
105    HouseholderQrAppendTangent,
106    HouseholderQrSplitTangent,
107    RankRevealingQr,
108}
109
110impl LinalgAdOpKind {
111    pub const COUNT: usize = 26;
112
113    /// Return the manifest index for this operation kind.
114    ///
115    /// # Examples
116    ///
117    /// ```rust
118    /// use tenferro_linalg::LinalgAdOpKind;
119    ///
120    /// assert_eq!(LinalgAdOpKind::Cholesky.as_index(), 0);
121    /// ```
122    pub const fn as_index(self) -> usize {
123        match self {
124            Self::Cholesky => 0,
125            Self::Lu => 1,
126            Self::LuFactor => 2,
127            Self::SignDetFromLuFactor => 3,
128            Self::LogAbsDetFromLuFactor => 4,
129            Self::LuSolvePrepared => 5,
130            Self::FullPivLu => 6,
131            Self::FullPivLuSolve => 7,
132            Self::Svd => 8,
133            Self::SvdVals => 9,
134            Self::Qr => 10,
135            Self::Eigh => 11,
136            Self::EighVals => 12,
137            Self::Eig => 13,
138            Self::EigVals => 14,
139            Self::TriangularSolve => 15,
140            Self::SvdFull => 16,
141            Self::HouseholderQrFactor => 17,
142            Self::HouseholderQrFromFactors => 18,
143            Self::HouseholderQrAppend => 19,
144            Self::HouseholderQrR => 20,
145            Self::HouseholderQrQColumns => 21,
146            Self::HouseholderQrThinQ => 22,
147            Self::HouseholderQrAppendTangent => 23,
148            Self::HouseholderQrSplitTangent => 24,
149            Self::RankRevealingQr => 25,
150        }
151    }
152
153    #[cfg(test)]
154    pub(crate) const fn from_linalg_op(op: LinalgOp) -> Self {
155        match op {
156            LinalgOp::Cholesky => Self::Cholesky,
157            LinalgOp::Lu => Self::Lu,
158            LinalgOp::LuFactor => Self::LuFactor,
159            LinalgOp::SignDetFromLuFactor => Self::SignDetFromLuFactor,
160            LinalgOp::LogAbsDetFromLuFactor => Self::LogAbsDetFromLuFactor,
161            LinalgOp::LuSolvePrepared { .. } => Self::LuSolvePrepared,
162            LinalgOp::FullPivLu => Self::FullPivLu,
163            LinalgOp::FullPivLuSolve { .. } => Self::FullPivLuSolve,
164            // The partial-pivot single-op solve shares the solve-family AD
165            // route (linearize + custom linear transpose) with FullPivLuSolve
166            // and is not separately exposed in the public manifest.
167            LinalgOp::Solve => Self::FullPivLuSolve,
168            // The fused solve is the AD carrier of `solve`, so it reports the
169            // same support entry as the plain solve kernel.
170            LinalgOp::LuFactorSolve => Self::FullPivLuSolve,
171            LinalgOp::Svd { .. } => Self::Svd,
172            LinalgOp::SvdFull => Self::SvdFull,
173            LinalgOp::SvdVals { .. } => Self::SvdVals,
174            LinalgOp::Qr { .. } => Self::Qr,
175            LinalgOp::RankRevealingQr { .. } => Self::RankRevealingQr,
176            LinalgOp::HouseholderQrFactor => Self::HouseholderQrFactor,
177            LinalgOp::HouseholderQrFromFactors => Self::HouseholderQrFromFactors,
178            LinalgOp::HouseholderQrAppend => Self::HouseholderQrAppend,
179            LinalgOp::HouseholderQrR { .. } => Self::HouseholderQrR,
180            LinalgOp::HouseholderQrQColumns { .. } => Self::HouseholderQrQColumns,
181            LinalgOp::HouseholderQrThinQ { .. } => Self::HouseholderQrThinQ,
182            LinalgOp::HouseholderQrAppendTangent => Self::HouseholderQrAppendTangent,
183            LinalgOp::HouseholderQrSplitTangent { .. } => Self::HouseholderQrSplitTangent,
184            LinalgOp::Eigh { .. } => Self::Eigh,
185            LinalgOp::EighVals { .. } => Self::EighVals,
186            LinalgOp::Eig { .. } => Self::Eig,
187            LinalgOp::EigVals { .. } => Self::EigVals,
188            LinalgOp::TriangularSolve { .. } => Self::TriangularSolve,
189        }
190    }
191}
192
193/// AD support status for one output of a linalg operation.
194///
195/// # Examples
196///
197/// ```rust
198/// use tenferro_linalg::{linalg_ad_support, LinalgAdOpKind, LinalgAdRuleSupport};
199///
200/// let full_piv_lu = linalg_ad_support(LinalgAdOpKind::FullPivLu);
201/// let l_output = full_piv_lu.outputs.iter().find(|output| output.name == "l").unwrap();
202/// assert_eq!(l_output.status, LinalgAdRuleSupport::SupportedViaLinearize);
203/// ```
204#[derive(Clone, Copy, Debug, PartialEq, Eq)]
205pub struct LinalgAdOutputSupport {
206    /// Output position in the linalg operation result tuple.
207    pub index: usize,
208    /// Stable output name used by tests and support dashboards.
209    pub name: &'static str,
210    /// AD support status for this specific output.
211    pub status: LinalgAdRuleSupport,
212}
213
214/// AD support manifest entry for one linalg operation.
215///
216/// # Examples
217///
218/// ```rust
219/// use tenferro_linalg::{linalg_ad_support, LinalgAdOpKind, LinalgAdRuleSupport};
220///
221/// let solve = linalg_ad_support(LinalgAdOpKind::TriangularSolve);
222/// assert_eq!(solve.vjp.route, tenferro_linalg::LinalgAdRoute::LinearizeThenCustomLinearTranspose);
223/// ```
224#[derive(Clone, Copy, Debug, PartialEq, Eq)]
225pub struct LinalgAdSupport {
226    /// Operation kind described by this manifest entry.
227    pub kind: LinalgAdOpKind,
228    /// User-visible JVP support and route.
229    pub jvp: LinalgAdModeSupport,
230    /// User-visible VJP support and route.
231    pub vjp: LinalgAdModeSupport,
232    /// Definitional linearize rule implementation status.
233    pub linearize_rule: LinalgAdRuleSupport,
234    /// Direct primal VJP rule implementation status.
235    pub custom_vjp_rule: LinalgAdRuleSupport,
236    /// Custom transposed-linear rule implementation status.
237    pub custom_linear_transpose_rule: LinalgAdRuleSupport,
238    /// Forward-mode graph emission support.
239    pub linearize: LinalgAdRuleSupport,
240    /// Transposed-linear graph emission support.
241    pub transpose: LinalgAdRuleSupport,
242    /// Per-output support status for multi-output operations.
243    pub outputs: &'static [LinalgAdOutputSupport],
244    /// Numerical or semantic caveats for this operation family.
245    pub caveats: &'static [&'static str],
246}
247
248const fn mode(status: LinalgAdRuleSupport, route: LinalgAdRoute) -> LinalgAdModeSupport {
249    LinalgAdModeSupport { status, route }
250}
251
252const fn jvp_route(status: LinalgAdRuleSupport) -> LinalgAdRoute {
253    match status {
254        LinalgAdRuleSupport::Unsupported
255        | LinalgAdRuleSupport::NonDifferentiable
256        | LinalgAdRuleSupport::PendingOracle => LinalgAdRoute::Unsupported,
257        LinalgAdRuleSupport::Supported
258        | LinalgAdRuleSupport::SupportedViaLinearize
259        | LinalgAdRuleSupport::PartiallySupported => LinalgAdRoute::Linearize,
260    }
261}
262
263const fn support_entry(
264    kind: LinalgAdOpKind,
265    linearize: LinalgAdRuleSupport,
266    transpose: LinalgAdRuleSupport,
267    vjp: LinalgAdModeSupport,
268    custom_linear_transpose_rule: LinalgAdRuleSupport,
269    outputs: &'static [LinalgAdOutputSupport],
270    caveats: &'static [&'static str],
271) -> LinalgAdSupport {
272    LinalgAdSupport {
273        kind,
274        jvp: mode(linearize, jvp_route(linearize)),
275        vjp,
276        linearize_rule: linearize,
277        custom_vjp_rule: LinalgAdRuleSupport::Unsupported,
278        custom_linear_transpose_rule,
279        linearize,
280        transpose,
281        outputs,
282        caveats,
283    }
284}
285
286const fn output(
287    index: usize,
288    name: &'static str,
289    status: LinalgAdRuleSupport,
290) -> LinalgAdOutputSupport {
291    LinalgAdOutputSupport {
292        index,
293        name,
294        status,
295    }
296}
297
298static CHOLESKY_OUTPUTS: [LinalgAdOutputSupport; 1] = [output(
299    0,
300    "factor",
301    LinalgAdRuleSupport::SupportedViaLinearize,
302)];
303static LU_OUTPUTS: [LinalgAdOutputSupport; 4] = [
304    output(0, "p", LinalgAdRuleSupport::NonDifferentiable),
305    output(1, "l", LinalgAdRuleSupport::SupportedViaLinearize),
306    output(2, "u", LinalgAdRuleSupport::SupportedViaLinearize),
307    output(3, "parity", LinalgAdRuleSupport::NonDifferentiable),
308];
309static LU_FACTOR_OUTPUTS: [LinalgAdOutputSupport; 3] = [
310    output(0, "packed_lu", LinalgAdRuleSupport::Unsupported),
311    output(1, "pivots", LinalgAdRuleSupport::NonDifferentiable),
312    output(2, "parity", LinalgAdRuleSupport::NonDifferentiable),
313];
314static SIGNDET_FROM_LU_FACTOR_OUTPUTS: [LinalgAdOutputSupport; 1] = [output(
315    0,
316    "sign",
317    LinalgAdRuleSupport::SupportedViaLinearize,
318)];
319static LOGABSDET_FROM_LU_FACTOR_OUTPUTS: [LinalgAdOutputSupport; 1] = [output(
320    0,
321    "logabsdet",
322    LinalgAdRuleSupport::SupportedViaLinearize,
323)];
324static SOLUTION_OUTPUTS: [LinalgAdOutputSupport; 1] = [output(
325    0,
326    "solution",
327    LinalgAdRuleSupport::SupportedViaLinearize,
328)];
329static FULL_PIV_LU_OUTPUTS: [LinalgAdOutputSupport; 5] = [
330    output(0, "p", LinalgAdRuleSupport::NonDifferentiable),
331    output(1, "l", LinalgAdRuleSupport::SupportedViaLinearize),
332    output(2, "u", LinalgAdRuleSupport::SupportedViaLinearize),
333    output(3, "q", LinalgAdRuleSupport::NonDifferentiable),
334    output(4, "parity", LinalgAdRuleSupport::NonDifferentiable),
335];
336static FULL_PIV_LU_SOLVE_OUTPUTS: [LinalgAdOutputSupport; 1] = [output(
337    0,
338    "solution",
339    LinalgAdRuleSupport::SupportedViaLinearize,
340)];
341static SVD_OUTPUTS: [LinalgAdOutputSupport; 3] = [
342    output(0, "u", LinalgAdRuleSupport::SupportedViaLinearize),
343    output(
344        1,
345        "singular_values",
346        LinalgAdRuleSupport::SupportedViaLinearize,
347    ),
348    output(2, "vt", LinalgAdRuleSupport::SupportedViaLinearize),
349];
350static SVD_VALS_OUTPUTS: [LinalgAdOutputSupport; 1] = [output(
351    0,
352    "singular_values",
353    LinalgAdRuleSupport::SupportedViaLinearize,
354)];
355static SVD_FULL_OUTPUTS: [LinalgAdOutputSupport; 3] = [
356    output(0, "u", LinalgAdRuleSupport::Unsupported),
357    output(1, "singular_values", LinalgAdRuleSupport::Unsupported),
358    output(2, "vt", LinalgAdRuleSupport::Unsupported),
359];
360static QR_OUTPUTS: [LinalgAdOutputSupport; 2] = [
361    output(0, "q", LinalgAdRuleSupport::SupportedViaLinearize),
362    output(1, "r", LinalgAdRuleSupport::SupportedViaLinearize),
363];
364static RANK_REVEALING_QR_OUTPUTS: [LinalgAdOutputSupport; 4] = [
365    output(0, "q", LinalgAdRuleSupport::Unsupported),
366    output(1, "r", LinalgAdRuleSupport::Unsupported),
367    output(2, "column_permutation", LinalgAdRuleSupport::Unsupported),
368    output(3, "rank", LinalgAdRuleSupport::Unsupported),
369];
370static HOUSEHOLDER_QR_STATE_OUTPUTS: [LinalgAdOutputSupport; 2] = [
371    output(0, "packed", LinalgAdRuleSupport::SupportedViaLinearize),
372    output(1, "coeff", LinalgAdRuleSupport::NonDifferentiable),
373];
374static HOUSEHOLDER_QR_VALUE_OUTPUTS: [LinalgAdOutputSupport; 1] = [output(
375    0,
376    "value",
377    LinalgAdRuleSupport::SupportedViaLinearize,
378)];
379static HOUSEHOLDER_QR_RESIDUAL_OUTPUTS: [LinalgAdOutputSupport; 1] = [output(
380    0,
381    "internal_value",
382    LinalgAdRuleSupport::Unsupported,
383)];
384static HOUSEHOLDER_QR_CAVEATS: [&str; 1] =
385    ["Rank-deficient states are outside the differentiable domain."];
386static HOUSEHOLDER_QR_Q_COLUMNS_CAVEATS: [&str; 2] = [
387    "Rank-deficient states are outside the differentiable domain.",
388    "Column ranges reaching past the thin-Q width k = min(m, n) are \
389     value-only: the complement basis is defined only up to a rotation inside \
390     the nullspace, so the rule returns a typed Unsupported instead of a \
391     derivative.",
392];
393static EIGH_OUTPUTS: [LinalgAdOutputSupport; 2] = [
394    output(0, "eigenvalues", LinalgAdRuleSupport::SupportedViaLinearize),
395    output(
396        1,
397        "eigenvectors",
398        LinalgAdRuleSupport::SupportedViaLinearize,
399    ),
400];
401static EIGH_VALS_OUTPUTS: [LinalgAdOutputSupport; 1] = [output(
402    0,
403    "eigenvalues",
404    LinalgAdRuleSupport::SupportedViaLinearize,
405)];
406static EIG_OUTPUTS: [LinalgAdOutputSupport; 2] = [
407    output(0, "eigenvalues", LinalgAdRuleSupport::SupportedViaLinearize),
408    output(1, "eigenvectors", LinalgAdRuleSupport::Unsupported),
409];
410static EIG_VALS_OUTPUTS: [LinalgAdOutputSupport; 1] = [output(
411    0,
412    "eigenvalues",
413    LinalgAdRuleSupport::SupportedViaLinearize,
414)];
415
416static DECOMPOSITION_CAVEATS: [&str; 1] = [
417    "Derivative regularization handles near-degenerate spectra but does not make exact degeneracies smoothly differentiable.",
418];
419
420/// `eigh`/`eigvalsh` only. The shared `DECOMPOSITION_CAVEATS` line above reads as
421/// a statement about eigenvector smoothness, which understates the defect: an
422/// HVP of a smooth spectral function is silently wrong at an exactly degenerate
423/// pair.
424static EIGH_CAVEATS: [&str; 3] = [
425    "Derivative regularization handles near-degenerate spectra but does not make exact degeneracies smoothly differentiable.",
426    "First derivatives of a smooth scalar spectral function `T(K) = tr t(K)` \
427     stay correct for every spectrum, including exactly degenerate ones, even \
428     though neither the eigenvectors nor a single eigenvalue are smooth \
429     functions of the matrix at an exact degeneracy.",
430    "Second and higher derivatives, such as an HVP `jvp(grad(T))` for a smooth \
431     spectral function `T(K) = tr t(K)`, report no error and no NaN but silently \
432     drop the term an exactly degenerate eigenvalue pair contributes when the \
433     tangent couples it: the pair weight is `diff / (diff^2 + eps^2)`, which is \
434     exactly 0 at `diff = 0`, and the confluent limit of the divided difference \
435     is not reachable from the rule because `eigh` never sees `t`.",
436];
437
438static LINALG_AD_SUPPORT: [LinalgAdSupport; LinalgAdOpKind::COUNT] = [
439    support_entry(
440        LinalgAdOpKind::Cholesky,
441        LinalgAdRuleSupport::SupportedViaLinearize,
442        LinalgAdRuleSupport::Unsupported,
443        mode(
444            LinalgAdRuleSupport::SupportedViaLinearize,
445            LinalgAdRoute::LinearizeThenTranspose,
446        ),
447        LinalgAdRuleSupport::Unsupported,
448        &CHOLESKY_OUTPUTS,
449        &DECOMPOSITION_CAVEATS,
450    ),
451    support_entry(
452        LinalgAdOpKind::Lu,
453        LinalgAdRuleSupport::PartiallySupported,
454        LinalgAdRuleSupport::Unsupported,
455        mode(
456            LinalgAdRuleSupport::PartiallySupported,
457            LinalgAdRoute::LinearizeThenTranspose,
458        ),
459        LinalgAdRuleSupport::Unsupported,
460        &LU_OUTPUTS,
461        &DECOMPOSITION_CAVEATS,
462    ),
463    support_entry(
464        LinalgAdOpKind::LuFactor,
465        LinalgAdRuleSupport::Unsupported,
466        LinalgAdRuleSupport::Unsupported,
467        mode(LinalgAdRuleSupport::Unsupported, LinalgAdRoute::Unsupported),
468        LinalgAdRuleSupport::Unsupported,
469        &LU_FACTOR_OUTPUTS,
470        &[],
471    ),
472    support_entry(
473        LinalgAdOpKind::SignDetFromLuFactor,
474        LinalgAdRuleSupport::SupportedViaLinearize,
475        LinalgAdRuleSupport::Unsupported,
476        mode(
477            LinalgAdRuleSupport::SupportedViaLinearize,
478            LinalgAdRoute::LinearizeThenTranspose,
479        ),
480        LinalgAdRuleSupport::Unsupported,
481        &SIGNDET_FROM_LU_FACTOR_OUTPUTS,
482        &[],
483    ),
484    support_entry(
485        LinalgAdOpKind::LogAbsDetFromLuFactor,
486        LinalgAdRuleSupport::SupportedViaLinearize,
487        LinalgAdRuleSupport::Unsupported,
488        mode(
489            LinalgAdRuleSupport::SupportedViaLinearize,
490            LinalgAdRoute::LinearizeThenTranspose,
491        ),
492        LinalgAdRuleSupport::Unsupported,
493        &LOGABSDET_FROM_LU_FACTOR_OUTPUTS,
494        &[],
495    ),
496    support_entry(
497        LinalgAdOpKind::LuSolvePrepared,
498        LinalgAdRuleSupport::SupportedViaLinearize,
499        LinalgAdRuleSupport::PartiallySupported,
500        mode(
501            LinalgAdRuleSupport::SupportedViaLinearize,
502            LinalgAdRoute::LinearizeThenCustomLinearTranspose,
503        ),
504        LinalgAdRuleSupport::PartiallySupported,
505        &SOLUTION_OUTPUTS,
506        &[],
507    ),
508    support_entry(
509        LinalgAdOpKind::FullPivLu,
510        LinalgAdRuleSupport::SupportedViaLinearize,
511        LinalgAdRuleSupport::Unsupported,
512        mode(
513            LinalgAdRuleSupport::SupportedViaLinearize,
514            LinalgAdRoute::LinearizeThenTranspose,
515        ),
516        LinalgAdRuleSupport::Unsupported,
517        &FULL_PIV_LU_OUTPUTS,
518        &DECOMPOSITION_CAVEATS,
519    ),
520    support_entry(
521        LinalgAdOpKind::FullPivLuSolve,
522        LinalgAdRuleSupport::SupportedViaLinearize,
523        LinalgAdRuleSupport::Supported,
524        mode(
525            LinalgAdRuleSupport::SupportedViaLinearize,
526            LinalgAdRoute::LinearizeThenCustomLinearTranspose,
527        ),
528        LinalgAdRuleSupport::Supported,
529        &FULL_PIV_LU_SOLVE_OUTPUTS,
530        &[],
531    ),
532    support_entry(
533        LinalgAdOpKind::Svd,
534        LinalgAdRuleSupport::SupportedViaLinearize,
535        LinalgAdRuleSupport::Unsupported,
536        mode(
537            LinalgAdRuleSupport::SupportedViaLinearize,
538            LinalgAdRoute::LinearizeThenTranspose,
539        ),
540        LinalgAdRuleSupport::Unsupported,
541        &SVD_OUTPUTS,
542        &DECOMPOSITION_CAVEATS,
543    ),
544    support_entry(
545        LinalgAdOpKind::SvdVals,
546        LinalgAdRuleSupport::SupportedViaLinearize,
547        LinalgAdRuleSupport::Unsupported,
548        mode(
549            LinalgAdRuleSupport::SupportedViaLinearize,
550            LinalgAdRoute::LinearizeThenTranspose,
551        ),
552        LinalgAdRuleSupport::Unsupported,
553        &SVD_VALS_OUTPUTS,
554        &DECOMPOSITION_CAVEATS,
555    ),
556    support_entry(
557        LinalgAdOpKind::Qr,
558        LinalgAdRuleSupport::SupportedViaLinearize,
559        LinalgAdRuleSupport::Unsupported,
560        mode(
561            LinalgAdRuleSupport::SupportedViaLinearize,
562            LinalgAdRoute::LinearizeThenTranspose,
563        ),
564        LinalgAdRuleSupport::Unsupported,
565        &QR_OUTPUTS,
566        &DECOMPOSITION_CAVEATS,
567    ),
568    support_entry(
569        LinalgAdOpKind::Eigh,
570        LinalgAdRuleSupport::SupportedViaLinearize,
571        LinalgAdRuleSupport::Unsupported,
572        mode(
573            LinalgAdRuleSupport::SupportedViaLinearize,
574            LinalgAdRoute::LinearizeThenTranspose,
575        ),
576        LinalgAdRuleSupport::Unsupported,
577        &EIGH_OUTPUTS,
578        &EIGH_CAVEATS,
579    ),
580    support_entry(
581        LinalgAdOpKind::EighVals,
582        LinalgAdRuleSupport::SupportedViaLinearize,
583        LinalgAdRuleSupport::Unsupported,
584        mode(
585            LinalgAdRuleSupport::SupportedViaLinearize,
586            LinalgAdRoute::LinearizeThenTranspose,
587        ),
588        LinalgAdRuleSupport::Unsupported,
589        &EIGH_VALS_OUTPUTS,
590        &EIGH_CAVEATS,
591    ),
592    support_entry(
593        LinalgAdOpKind::Eig,
594        LinalgAdRuleSupport::PartiallySupported,
595        LinalgAdRuleSupport::Unsupported,
596        mode(
597            LinalgAdRuleSupport::PartiallySupported,
598            LinalgAdRoute::LinearizeThenTranspose,
599        ),
600        LinalgAdRuleSupport::Unsupported,
601        &EIG_OUTPUTS,
602        &DECOMPOSITION_CAVEATS,
603    ),
604    support_entry(
605        LinalgAdOpKind::EigVals,
606        LinalgAdRuleSupport::SupportedViaLinearize,
607        LinalgAdRuleSupport::Unsupported,
608        mode(
609            LinalgAdRuleSupport::SupportedViaLinearize,
610            LinalgAdRoute::LinearizeThenTranspose,
611        ),
612        LinalgAdRuleSupport::Unsupported,
613        &EIG_VALS_OUTPUTS,
614        &DECOMPOSITION_CAVEATS,
615    ),
616    support_entry(
617        LinalgAdOpKind::TriangularSolve,
618        LinalgAdRuleSupport::SupportedViaLinearize,
619        LinalgAdRuleSupport::Supported,
620        mode(
621            LinalgAdRuleSupport::SupportedViaLinearize,
622            LinalgAdRoute::LinearizeThenCustomLinearTranspose,
623        ),
624        LinalgAdRuleSupport::Supported,
625        &SOLUTION_OUTPUTS,
626        &[],
627    ),
628    // Full-matrices SVD is a value-only route: nullspace/kernel extraction does
629    // not require derivatives, and the thin-SVD linearize rule does not extend
630    // to the square factors. AD is intentionally unsupported for every output.
631    support_entry(
632        LinalgAdOpKind::SvdFull,
633        LinalgAdRuleSupport::Unsupported,
634        LinalgAdRuleSupport::Unsupported,
635        mode(LinalgAdRuleSupport::Unsupported, LinalgAdRoute::Unsupported),
636        LinalgAdRuleSupport::Unsupported,
637        &SVD_FULL_OUTPUTS,
638        &[],
639    ),
640    support_entry(
641        LinalgAdOpKind::HouseholderQrFactor,
642        LinalgAdRuleSupport::SupportedViaLinearize,
643        LinalgAdRuleSupport::Unsupported,
644        mode(
645            LinalgAdRuleSupport::SupportedViaLinearize,
646            LinalgAdRoute::LinearizeThenTranspose,
647        ),
648        LinalgAdRuleSupport::Unsupported,
649        &HOUSEHOLDER_QR_STATE_OUTPUTS,
650        &HOUSEHOLDER_QR_CAVEATS,
651    ),
652    support_entry(
653        LinalgAdOpKind::HouseholderQrFromFactors,
654        LinalgAdRuleSupport::SupportedViaLinearize,
655        LinalgAdRuleSupport::Unsupported,
656        mode(
657            LinalgAdRuleSupport::SupportedViaLinearize,
658            LinalgAdRoute::LinearizeThenTranspose,
659        ),
660        LinalgAdRuleSupport::Unsupported,
661        &HOUSEHOLDER_QR_STATE_OUTPUTS,
662        &HOUSEHOLDER_QR_CAVEATS,
663    ),
664    support_entry(
665        LinalgAdOpKind::HouseholderQrAppend,
666        LinalgAdRuleSupport::SupportedViaLinearize,
667        LinalgAdRuleSupport::Unsupported,
668        mode(
669            LinalgAdRuleSupport::SupportedViaLinearize,
670            LinalgAdRoute::LinearizeThenTranspose,
671        ),
672        LinalgAdRuleSupport::Unsupported,
673        &HOUSEHOLDER_QR_STATE_OUTPUTS,
674        &HOUSEHOLDER_QR_CAVEATS,
675    ),
676    support_entry(
677        LinalgAdOpKind::HouseholderQrR,
678        LinalgAdRuleSupport::SupportedViaLinearize,
679        LinalgAdRuleSupport::Unsupported,
680        mode(
681            LinalgAdRuleSupport::SupportedViaLinearize,
682            LinalgAdRoute::LinearizeThenTranspose,
683        ),
684        LinalgAdRuleSupport::Unsupported,
685        &HOUSEHOLDER_QR_VALUE_OUTPUTS,
686        &HOUSEHOLDER_QR_CAVEATS,
687    ),
688    support_entry(
689        LinalgAdOpKind::HouseholderQrQColumns,
690        LinalgAdRuleSupport::SupportedViaLinearize,
691        LinalgAdRuleSupport::Unsupported,
692        mode(
693            LinalgAdRuleSupport::SupportedViaLinearize,
694            LinalgAdRoute::LinearizeThenTranspose,
695        ),
696        LinalgAdRuleSupport::Unsupported,
697        &HOUSEHOLDER_QR_VALUE_OUTPUTS,
698        &HOUSEHOLDER_QR_Q_COLUMNS_CAVEATS,
699    ),
700    support_entry(
701        LinalgAdOpKind::HouseholderQrThinQ,
702        LinalgAdRuleSupport::Unsupported,
703        LinalgAdRuleSupport::Unsupported,
704        mode(LinalgAdRuleSupport::Unsupported, LinalgAdRoute::Unsupported),
705        LinalgAdRuleSupport::Unsupported,
706        &HOUSEHOLDER_QR_RESIDUAL_OUTPUTS,
707        &["Internal fixed residual; no public differentiable surface."],
708    ),
709    support_entry(
710        LinalgAdOpKind::HouseholderQrAppendTangent,
711        LinalgAdRuleSupport::Unsupported,
712        LinalgAdRuleSupport::Supported,
713        mode(LinalgAdRuleSupport::Unsupported, LinalgAdRoute::Unsupported),
714        LinalgAdRuleSupport::Supported,
715        &HOUSEHOLDER_QR_RESIDUAL_OUTPUTS,
716        &["Internal linear append operation; no public differentiable surface."],
717    ),
718    support_entry(
719        LinalgAdOpKind::HouseholderQrSplitTangent,
720        LinalgAdRuleSupport::Unsupported,
721        LinalgAdRuleSupport::Unsupported,
722        mode(LinalgAdRuleSupport::Unsupported, LinalgAdRoute::Unsupported),
723        LinalgAdRuleSupport::Unsupported,
724        &HOUSEHOLDER_QR_RESIDUAL_OUTPUTS,
725        &["Internal transpose residual; no public differentiable surface."],
726    ),
727    support_entry(
728        LinalgAdOpKind::RankRevealingQr,
729        LinalgAdRuleSupport::Unsupported,
730        LinalgAdRuleSupport::Unsupported,
731        mode(LinalgAdRuleSupport::Unsupported, LinalgAdRoute::Unsupported),
732        LinalgAdRuleSupport::Unsupported,
733        &RANK_REVEALING_QR_OUTPUTS,
734        &["Pivot selection and numerical rank are discontinuous; all outputs are initially unsupported for AD."],
735    ),
736];
737
738/// Return the complete linalg AD support manifest.
739///
740/// # Examples
741///
742/// ```rust
743/// let manifest = tenferro_linalg::all_linalg_ad_support();
744/// assert_eq!(manifest.len(), tenferro_linalg::LinalgAdOpKind::COUNT);
745/// ```
746pub fn all_linalg_ad_support() -> &'static [LinalgAdSupport; LinalgAdOpKind::COUNT] {
747    &LINALG_AD_SUPPORT
748}
749
750/// Return the support manifest entry for one linalg operation kind.
751///
752/// # Examples
753///
754/// ```rust
755/// use tenferro_linalg::{linalg_ad_support, LinalgAdOpKind};
756///
757/// let entry = linalg_ad_support(LinalgAdOpKind::Eigh);
758/// assert_eq!(entry.kind, LinalgAdOpKind::Eigh);
759/// ```
760pub fn linalg_ad_support(kind: LinalgAdOpKind) -> &'static LinalgAdSupport {
761    &LINALG_AD_SUPPORT[kind.as_index()]
762}
763
764#[cfg(test)]
765pub(crate) fn linalg_ad_support_for_op(op: LinalgOp) -> &'static LinalgAdSupport {
766    linalg_ad_support(LinalgAdOpKind::from_linalg_op(op))
767}
768
769#[cfg(test)]
770mod tests;