tenferro_tropical/lib.rs
1//! Tropical semiring tensor operations for the tenferro workspace.
2//!
3//! This crate extends the tenferro algebra-parameterized architecture with
4//! three tropical semirings:
5//!
6//! | Semiring | ⊕ (add) | ⊗ (mul) | Zero | One | Use case |
7//! |----------|---------|---------|------|-----|----------|
8//! | MaxPlus | max | + | −∞ | 0 | Shortest path, optimal alignment |
9//! | MinPlus | min | + | +∞ | 0 | Shortest path (Dijkstra) |
10//! | MaxMul | max | × | 0 | 1 | Viterbi, max-probability paths |
11//!
12//! # Architecture
13//!
14//! The crate provides:
15//!
16//! - **Scalar wrappers** ([`MaxPlus<T>`], [`MinPlus<T>`], [`MaxMul<T>`]):
17//! `#[repr(transparent)]` newtypes that redefine `Add`/`Mul` with tropical
18//! semantics. Satisfy the [`Scalar`](tenferro_algebra::Scalar) blanket impl.
19//!
20//! - **Algebra markers** ([`MaxPlusAlgebra`], [`MinPlusAlgebra`], [`MaxMulAlgebra`]):
21//! Zero-sized types used as the algebra parameter `A` in
22//! [`TensorPrims<A>`](tenferro_prims::TensorPrims).
23//!
24//! - **[`TensorPrims`](tenferro_prims::TensorPrims) implementations**:
25//! `impl TensorPrims<MaxPlusAlgebra> for CpuBackend` etc. Orphan rule
26//! compatible because algebra markers are defined locally.
27//!
28//! - **[`ArgmaxTracker`]**: Records winner indices during tropical forward
29//! pass for use in automatic differentiation.
30//!
31//! # Examples
32//!
33//! ## Scalar arithmetic
34//!
35//! ```ignore
36//! use tenferro_tropical::MaxPlus;
37//!
38//! let a = MaxPlus(3.0_f64);
39//! let b = MaxPlus(5.0_f64);
40//! let c = a + b; // MaxPlus(5.0) — tropical add = max
41//! let d = a * b; // MaxPlus(8.0) — tropical mul = ordinary +
42//! ```
43//!
44//! ## Algebra dispatch
45//!
46//! ```ignore
47//! use tenferro_algebra::HasAlgebra;
48//! use tenferro_tropical::{MaxPlus, MaxPlusAlgebra};
49//!
50//! // MaxPlus<f64> automatically maps to MaxPlusAlgebra
51//! fn check<T: HasAlgebra<Algebra = MaxPlusAlgebra>>() {}
52//! check::<MaxPlus<f64>>();
53//! ```
54//!
55//! ## Plan-based tropical contraction
56//!
57//! ```ignore
58//! use tenferro_prims::{CpuBackend, TensorPrims, PrimDescriptor};
59//! use tenferro_tropical::MaxPlusAlgebra;
60//!
61//! let desc = PrimDescriptor::BatchedGemm {
62//! batch_dims: vec![], m: 3, n: 5, k: 4,
63//! };
64//! // Under MaxPlusAlgebra, GEMM computes:
65//! // C[i,j] = max_k (A[i,k] + B[k,j])
66//! let plan = <CpuBackend as TensorPrims<MaxPlusAlgebra>>::plan::<f64>(
67//! &desc, &[&[3, 4], &[4, 5], &[3, 5]],
68//! ).unwrap();
69//! ```
70
71pub mod algebra;
72pub mod argmax;
73pub mod prims;
74pub mod scalar;
75
76// Re-export primary types at crate root.
77pub use algebra::{MaxMulAlgebra, MaxPlusAlgebra, MinPlusAlgebra};
78pub use argmax::ArgmaxTracker;
79pub use prims::TropicalPlan;
80pub use scalar::{MaxMul, MaxPlus, MinPlus};