Skip to main content

tenferro_ops/primitive_rules/
mod.rs

1//! Shared primitive-rule contracts; no core differentiation dispatcher.
2
3#[cfg(feature = "autodiff")]
4use crate::ad::context;
5#[cfg(feature = "autodiff")]
6use crate::ext_op::ExtensionOp;
7#[cfg(feature = "autodiff")]
8use crate::std_tensor_op::StdTensorOp;
9#[cfg(feature = "autodiff")]
10use computegraph::graph::GraphBuilder;
11#[cfg(feature = "autodiff")]
12use computegraph::types::{LocalValueId, OperationRole, ValueKey, ValueRef};
13
14#[cfg(feature = "autodiff")]
15mod residual_spec;
16#[cfg(feature = "autodiff")]
17pub use residual_spec::primitive_residual_spec;
18
19#[cfg(feature = "autodiff")]
20#[derive(Clone, Copy, Debug, PartialEq, Eq)]
21pub enum ADRuleKind {
22    Jvp,
23    Transpose,
24}
25
26#[cfg(feature = "autodiff")]
27#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
28pub enum ADRuleError {
29    #[error("unsupported AD rule {rule:?} for {op}")]
30    Unsupported { op: String, rule: ADRuleKind },
31    #[error("invalid AD rule input for {op} ({rule:?}): {message}")]
32    InvalidInput {
33        op: String,
34        rule: ADRuleKind,
35        message: String,
36    },
37}
38
39#[cfg(feature = "autodiff")]
40impl ADRuleError {
41    pub fn unsupported(op: impl Into<String>, rule: ADRuleKind) -> Self {
42        Self::Unsupported {
43            op: op.into(),
44            rule,
45        }
46    }
47
48    pub fn invalid_input(
49        op: impl Into<String>,
50        rule: ADRuleKind,
51        message: impl Into<String>,
52    ) -> Self {
53        Self::InvalidInput {
54            op: op.into(),
55            rule,
56            message: message.into(),
57        }
58    }
59
60    pub const fn rule(&self) -> ADRuleKind {
61        match self {
62            Self::Unsupported { rule, .. } | Self::InvalidInput { rule, .. } => *rule,
63        }
64    }
65}
66
67#[cfg(feature = "autodiff")]
68pub type ADRuleResult<T> = std::result::Result<T, ADRuleError>;
69
70/// Per-rule declaration of which primal inputs/outputs a transpose (VJP) rule
71/// reads as full tensor residuals versus which need only shape/dtype metadata.
72///
73/// The AD engine uses this to bound residual retention: an index not declared
74/// here may only be accessed through its metadata, never as a tensor operand.
75/// Indices are counted in primal-input order (input mask) and primal-output
76/// order (output mask).
77///
78/// Individual indices ([`ResidualSpec::input`], [`ResidualSpec::with_input`],
79/// and the output counterparts) are limited to `0..64`. The all-index
80/// declarations ([`ResidualSpec::all_inputs`], [`ResidualSpec::with_all_inputs`],
81/// and the output counterparts) cover every index, including indices `>= 64`,
82/// so a variadic rule such as einsum or concatenate declares its whole arity.
83///
84/// # Examples
85///
86/// ```
87/// use tenferro_ops::ad::ResidualSpec;
88///
89/// // `add` needs no tensor residuals; `mul` keeps both operands.
90/// let add = ResidualSpec::none();
91/// let mul = ResidualSpec::input(0).with_input(1);
92/// assert!(add.is_empty());
93/// assert!(mul.declares_input(0) && mul.declares_input(1));
94/// // Unary ops that reuse the forward output (e.g. exp) declare it.
95/// let exp = ResidualSpec::output(0);
96/// assert!(exp.declares_output(0));
97/// // Variadic rules declare every operand, whatever the arity.
98/// let einsum = ResidualSpec::all_inputs();
99/// assert!(einsum.declares_input(0) && einsum.declares_input(64));
100/// ```
101#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
102pub struct ResidualSpec {
103    /// Declared input indices `0..64`, one bit per index.
104    input_mask: u64,
105    /// Declared output indices `0..64`, one bit per index.
106    output_mask: u64,
107    /// Whether every input index `>= 64` is declared.
108    input_tail: bool,
109    /// Whether every output index `>= 64` is declared.
110    output_tail: bool,
111}
112
113/// One explicitly declared index as a mask bit.
114///
115/// An index outside `0..64` cannot be stored as a single bit. Shifting by it
116/// would overflow (a panic with overflow checks, a wrapped and therefore wrong
117/// bit without them), so it is refused in every build instead.
118const fn index_bit(index: usize) -> u64 {
119    assert!(
120        index < 64,
121        "ResidualSpec declares individual indices 0..64 only; use all_inputs/all_outputs"
122    );
123    1 << index
124}
125
126impl ResidualSpec {
127    /// A mask declaring no tensor residuals (metadata-only rule).
128    pub const fn none() -> Self {
129        Self {
130            input_mask: 0,
131            output_mask: 0,
132            input_tail: false,
133            output_tail: false,
134        }
135    }
136
137    /// A mask declaring one input index as a tensor residual.
138    ///
139    /// # Panics
140    ///
141    /// Panics if `index >= 64`; declare such inputs with
142    /// [`ResidualSpec::all_inputs`].
143    pub const fn input(index: usize) -> Self {
144        Self::none().with_input(index)
145    }
146
147    /// A mask declaring one output index as a tensor residual.
148    ///
149    /// # Panics
150    ///
151    /// Panics if `index >= 64`; declare such outputs with
152    /// [`ResidualSpec::all_outputs`].
153    pub const fn output(index: usize) -> Self {
154        Self::none().with_output(index)
155    }
156
157    /// Add one input index to this mask.
158    ///
159    /// # Panics
160    ///
161    /// Panics if `index >= 64`; declare such inputs with
162    /// [`ResidualSpec::with_all_inputs`].
163    pub const fn with_input(mut self, index: usize) -> Self {
164        self.input_mask |= index_bit(index);
165        self
166    }
167
168    /// Add one output index to this mask.
169    ///
170    /// # Panics
171    ///
172    /// Panics if `index >= 64`; declare such outputs with
173    /// [`ResidualSpec::with_all_outputs`].
174    pub const fn with_output(mut self, index: usize) -> Self {
175        self.output_mask |= index_bit(index);
176        self
177    }
178
179    /// Add every input index, of any arity, to this mask.
180    pub const fn with_all_inputs(mut self) -> Self {
181        self.input_mask = u64::MAX;
182        self.input_tail = true;
183        self
184    }
185
186    /// Add every output index, of any arity, to this mask.
187    pub const fn with_all_outputs(mut self) -> Self {
188        self.output_mask = u64::MAX;
189        self.output_tail = true;
190        self
191    }
192
193    /// A mask declaring every input index, of any arity, as a tensor residual.
194    ///
195    /// Used by rules whose required operand set depends on the active-input
196    /// configuration (e.g. `mul`, concatenate, einsum), and by multi-op
197    /// families whose individual ops collectively read any operand.
198    pub const fn all_inputs() -> Self {
199        Self::none().with_all_inputs()
200    }
201
202    /// A mask declaring every output index, of any arity, as a tensor residual.
203    pub const fn all_outputs() -> Self {
204        Self::none().with_all_outputs()
205    }
206
207    /// Whether input `index` is declared as a tensor residual.
208    pub const fn declares_input(&self, index: usize) -> bool {
209        if index < 64 {
210            (self.input_mask >> index) & 1 == 1
211        } else {
212            self.input_tail
213        }
214    }
215
216    /// Whether output `index` is declared as a tensor residual.
217    pub const fn declares_output(&self, index: usize) -> bool {
218        if index < 64 {
219            (self.output_mask >> index) & 1 == 1
220        } else {
221            self.output_tail
222        }
223    }
224
225    /// Whether this mask declares no tensor residuals.
226    #[must_use]
227    pub const fn is_empty(&self) -> bool {
228        self.input_mask == 0 && self.output_mask == 0 && !self.input_tail && !self.output_tail
229    }
230}
231
232#[cfg(feature = "autodiff")]
233#[derive(Clone, Debug)]
234pub enum PrimitiveTransposeInput<Op: computegraph::GraphOperation> {
235    Residual(ValueKey<Op>),
236    Linear {
237        key: ValueKey<Op>,
238        primal: Option<ValueKey<Op>>,
239    },
240}
241
242#[cfg(feature = "autodiff")]
243impl<Op: computegraph::GraphOperation> PrimitiveTransposeInput<Op> {
244    pub fn key(&self) -> &ValueKey<Op> {
245        match self {
246            Self::Residual(key) | Self::Linear { key, .. } => key,
247        }
248    }
249}
250
251/// Builder interface used by tenferro AD rules.
252///
253/// # Examples
254///
255/// ```
256/// use computegraph::graph::GraphBuilder;
257/// use computegraph::{OperationRole, ValueRef};
258/// use tenferro_ops::ad::PrimitiveRuleBuilder;
259/// use tenferro_ops::input_key::TensorInputKey;
260/// use tenferro_ops::std_tensor_op::StdTensorOp;
261///
262/// let mut builder = GraphBuilder::<StdTensorOp>::new();
263/// let x = builder.add_input(TensorInputKey::User { id: 1 });
264/// let out = PrimitiveRuleBuilder::add_operation(
265///     &mut builder,
266///     StdTensorOp::Neg,
267///     vec![ValueRef::Local(x)],
268///     OperationRole::Primary,
269/// );
270/// assert_eq!(out.len(), 1);
271/// ```
272#[cfg(feature = "autodiff")]
273pub trait PrimitiveRuleBuilder {
274    /// Add one primitive graph operation and return local ids for its outputs.
275    fn add_operation(
276        &mut self,
277        operation: StdTensorOp,
278        inputs: Vec<ValueRef<StdTensorOp>>,
279        role: OperationRole,
280    ) -> Vec<LocalValueId>;
281}
282
283#[cfg(feature = "autodiff")]
284impl PrimitiveRuleBuilder for GraphBuilder<StdTensorOp> {
285    fn add_operation(
286        &mut self,
287        operation: StdTensorOp,
288        inputs: Vec<ValueRef<StdTensorOp>>,
289        role: OperationRole,
290    ) -> Vec<LocalValueId> {
291        GraphBuilder::add_operation(self, operation, inputs, role)
292    }
293}
294
295/// Extension-rule callback contract.
296///
297/// This vocabulary remains shared; core AD transforms are owned by `tenferro-ad`.
298#[doc(hidden)]
299#[cfg(feature = "autodiff")]
300pub trait ExtensionAdDispatcher: std::fmt::Debug + Send + Sync + 'static {
301    fn has_primal_vjp(&self, family_id: &str) -> bool;
302
303    fn linearize(
304        &self,
305        op: &dyn ExtensionOp,
306        builder: &mut dyn PrimitiveRuleBuilder,
307        primal_in: &[ValueKey<StdTensorOp>],
308        primal_out: &[ValueKey<StdTensorOp>],
309        tangent_in: &[Option<LocalValueId>],
310        ctx: &mut context::ShapeGuardContext,
311    ) -> ADRuleResult<Vec<Option<LocalValueId>>>;
312
313    fn transpose(
314        &self,
315        op: &dyn ExtensionOp,
316        builder: &mut dyn PrimitiveRuleBuilder,
317        cotangent_out: &[Option<LocalValueId>],
318        inputs: &[PrimitiveTransposeInput<StdTensorOp>],
319        mode: &OperationRole,
320        ctx: &mut context::ShapeGuardContext,
321    ) -> ADRuleResult<Vec<Option<LocalValueId>>>;
322}
323
324#[cfg(test)]
325mod tests;