tenferro_ops/primitive_rules/
mod.rs1#[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#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
102pub struct ResidualSpec {
103 input_mask: u64,
105 output_mask: u64,
107 input_tail: bool,
109 output_tail: bool,
111}
112
113const 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 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 pub const fn input(index: usize) -> Self {
144 Self::none().with_input(index)
145 }
146
147 pub const fn output(index: usize) -> Self {
154 Self::none().with_output(index)
155 }
156
157 pub const fn with_input(mut self, index: usize) -> Self {
164 self.input_mask |= index_bit(index);
165 self
166 }
167
168 pub const fn with_output(mut self, index: usize) -> Self {
175 self.output_mask |= index_bit(index);
176 self
177 }
178
179 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 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 pub const fn all_inputs() -> Self {
199 Self::none().with_all_inputs()
200 }
201
202 pub const fn all_outputs() -> Self {
204 Self::none().with_all_outputs()
205 }
206
207 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 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 #[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#[cfg(feature = "autodiff")]
273pub trait PrimitiveRuleBuilder {
274 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#[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;