1use std::collections::HashSet;
10use std::sync::Arc;
11
12use tenferro_ops::input_key::TensorInputKey;
13use tenferro_ops::TensorMeta;
14use tenferro_runtime::ad_support::{ones_tensor, RetainedValue};
15use tenferro_runtime::program::{FrozenProgram, ProgramImport, ProgramValue};
16use tenferro_runtime::{
17 Error, ErrorPhase, ExecutionEngine, GraphCompiler, Result, Runtime, Tensor, TraceValue,
18 TracedTensor,
19};
20
21use crate::semantic_extension::{SemanticAdError, SemanticExtensionRuleSet};
22use crate::semantic_transform::{SemanticAdProgram, SemanticAdTransformError};
23use crate::transform_cache::AdTransformCache;
24use crate::AdContext;
25
26fn error_shape_hint(tensor: &TracedTensor) -> Vec<usize> {
27 tensor
28 .try_concrete_shape()
29 .unwrap_or_else(|| vec![0; tensor.rank()])
30}
31
32pub(crate) fn inactive_wrt_error(op: &'static str, wrt_key: impl std::fmt::Debug) -> Error {
37 Error::invalid_argument(
38 op,
39 ErrorPhase::GraphBuild,
40 "wrt",
41 format!(
42 "{op} is inactive for {wrt_key:?}; use {op}_optional to observe the inactive state"
43 ),
44 )
45}
46
47fn snapshot_error(source: tenferro_runtime::program::ProgramFinishError) -> Error {
48 Error::runtime_state_source("traced AD snapshot", ErrorPhase::GraphBuild, source)
49}
50
51fn import_error(source: tenferro_runtime::program::ProgramBuildError) -> Error {
52 Error::runtime_state_source("traced AD import", ErrorPhase::GraphBuild, source)
53}
54
55struct AdSource {
57 frozen: FrozenProgram,
58 inputs: Vec<(TensorInputKey, TraceValue)>,
60}
61
62impl AdSource {
63 fn of(output: &TracedTensor) -> Result<Self> {
64 let (frozen, inputs) = output
65 .context()
66 .ad_snapshot_with_inputs(&[output.trace_value()])
67 .map_err(snapshot_error)?;
68 Ok(Self { frozen, inputs })
69 }
70
71 fn slot_of(&self, wrt: &TracedTensor) -> Result<Option<usize>> {
73 let Some(key) = wrt.input_key() else {
74 return Ok(None);
75 };
76 Ok(self
77 .inputs
78 .iter()
79 .position(|(candidate, _)| *candidate == key))
80 }
81
82 fn input_count(&self) -> usize {
83 self.inputs.len()
84 }
85}
86
87fn leaf_input_key(tensor: &TracedTensor) -> Result<TensorInputKey> {
88 tensor.input_key().ok_or_else(|| {
89 Error::invalid_argument(
90 "traced AD",
91 ErrorPhase::GraphBuild,
92 "wrt",
93 "the differentiated tensor is not a trace input",
94 )
95 })
96}
97
98fn seed_leaf(
99 output: &TracedTensor,
100 seeded_value: TraceValue,
101 data: &Arc<RetainedValue>,
102 op: &'static str,
103) -> Result<TraceValue> {
104 let identity = output.context().value_scalar_identity(seeded_value);
107 output
108 .context()
109 .bound_input_concrete(Arc::clone(data), identity)
110 .map_err(|source| {
111 Error::invalid_argument(
112 op,
113 ErrorPhase::GraphBuild,
114 "seed",
115 format!("a seed value could not be bound into the trace: {source}"),
116 )
117 })
118}
119
120fn import_derivative(
126 output: &TracedTensor,
127 source: &AdSource,
128 derivative: &SemanticAdProgram,
129 seeds: &[(usize, TraceValue)],
130 derivative_output_indices: &[usize],
131 transform: &'static str,
132) -> Result<Vec<TracedTensor>> {
133 let frozen = derivative.frozen();
134 let derivative_inputs = frozen.program.inputs();
135 let source_input_count = source.input_count();
136 let mut input_map: Vec<(ProgramValue, ProgramValue)> =
137 Vec::with_capacity(source_input_count + seeds.len());
138 for (index, (_, live)) in source.inputs.iter().enumerate() {
139 let Some(&derivative_input) = derivative_inputs.get(index) else {
140 return Err(Error::runtime_state(
141 transform,
142 ErrorPhase::GraphBuild,
143 "the derivative program has fewer inputs than the source program",
144 ));
145 };
146 input_map.push((derivative_input, live.program_value()));
147 }
148 for (seed_input_index, seed) in seeds {
149 if *seed_input_index < source_input_count {
150 return Err(Error::runtime_state(
151 transform,
152 ErrorPhase::GraphBuild,
153 "a derivative seed input overlaps the source inputs",
154 ));
155 }
156 let Some(&derivative_input) = derivative_inputs.get(*seed_input_index) else {
157 return Err(Error::runtime_state(
158 transform,
159 ErrorPhase::GraphBuild,
160 "a derivative seed input is outside the derivative program",
161 ));
162 };
163 input_map.push((derivative_input, seed.program_value()));
164 }
165 let mut roots = Vec::with_capacity(derivative_output_indices.len());
166 for &index in derivative_output_indices {
167 let Some(&root) = frozen.program.outputs().get(index) else {
168 return Err(Error::runtime_state(
169 transform,
170 ErrorPhase::GraphBuild,
171 "a derivative output index is outside the derivative program",
172 ));
173 };
174 roots.push(root);
175 }
176 let imported = output
177 .context()
178 .import_values(ProgramImport {
179 program: frozen.program.as_ref(),
180 bindings: None,
181 roots: &roots,
182 input_map: &input_map,
183 })
184 .map_err(import_error)?;
185 imported
186 .into_iter()
187 .map(|value| {
188 output.context().derive_tensor(value).map_err(|source| {
189 Error::runtime_state_source(transform, ErrorPhase::GraphBuild, source)
190 })
191 })
192 .collect()
193}
194
195fn tensor_meta_of(tensor: &TracedTensor) -> Result<TensorMeta> {
200 let extents = match tensor.sym_shape() {
201 Some(shape) => shape.to_vec(),
202 None => (0..tensor.rank())
203 .map(|axis| tensor.axis_sym_dim(crate::shape_packing::signed_axis(axis)?))
204 .collect::<std::result::Result<_, _>>()?,
205 };
206 Ok(TensorMeta::exact(tensor.dtype(), extents))
207}
208
209fn cotangent_meta_of(
214 output: &TracedTensor,
215 source: &AdSource,
216 transform: &'static str,
217) -> Result<TensorMeta> {
218 match output.attached_value() {
219 Some(data) => Ok(TensorMeta::exact(
220 data.dtype(),
221 data.shape()
222 .iter()
223 .map(|&size| tenferro_ops::SymDim::from(size))
224 .collect(),
225 )),
226 None => source_output_metadata(output, source, transform),
227 }
228}
229
230fn source_output_metadata(
232 output: &TracedTensor,
233 source: &AdSource,
234 transform: &'static str,
235) -> Result<TensorMeta> {
236 let Some(&program_output) = source.frozen.program.outputs().first() else {
237 return Err(Error::runtime_state(
238 transform,
239 ErrorPhase::GraphBuild,
240 "the AD source program has no output",
241 ));
242 };
243 let metadata = source
244 .frozen
245 .program
246 .value_metadata(program_output)
247 .map_err(|source| Error::runtime_state_source(transform, ErrorPhase::GraphBuild, source))?;
248 program_metadata_to_tensor_meta(metadata, output, transform)
249}
250
251fn validate_seed_against_program(
252 transform: &'static str,
253 _source: &AdSource,
254 data: &Arc<RetainedValue>,
255 expected: TensorMeta,
256 input_index: usize,
257) -> Result<()> {
258 validate_seed_tensor(transform, input_index, data, &expected)
259}
260
261fn seed_meta_of(tensor: &TracedTensor) -> Result<TensorMeta> {
266 match tensor.attached_value() {
267 Some(data) => Ok(TensorMeta::exact(
268 data.dtype(),
269 data.shape()
270 .iter()
271 .map(|&size| tenferro_ops::SymDim::from(size))
272 .collect(),
273 )),
274 None => tensor_meta_of(tensor),
275 }
276}
277
278fn program_metadata_to_tensor_meta(
284 metadata: &tenferro_runtime::program::ProgramValueMetadata,
285 output: &TracedTensor,
286 transform: &'static str,
287) -> Result<TensorMeta> {
288 let mut extents = Vec::with_capacity(metadata.shape().len());
289 for (axis, extent) in metadata.shape().iter().enumerate() {
290 let tenferro_ops::shape_extent::ShapeExtent::Exact(expr) = extent else {
291 return Err(Error::invalid_argument(
292 transform,
293 ErrorPhase::GraphBuild,
294 "seed",
295 "the differentiated value has no concrete dtype and rank metadata",
296 ));
297 };
298 extents.push(match expr.eval(&[]) {
299 Ok(size) => tenferro_ops::SymDim::from(size),
300 Err(_) => output.axis_sym_dim(crate::shape_packing::signed_axis(axis)?)?,
301 });
302 }
303 Ok(TensorMeta::exact(metadata.dtype(), extents))
304}
305
306fn ad_context(
307 rules: &SemanticExtensionRuleSet,
308 cache: Option<&Arc<AdTransformCache>>,
309) -> AdContext {
310 match cache {
311 Some(cache) => AdContext::with_rules_and_transform_cache(rules.clone(), Arc::clone(cache)),
312 None => AdContext::builder()
313 .with_semantic_extension_rules(rules.clone())
314 .expect("registering semantic extension rules is infallible")
315 .build()
316 .expect("building an AD context with a rule set is infallible"),
317 }
318}
319
320fn vjp_many_impl(
321 output: &TracedTensor,
322 wrts: &[&TracedTensor],
323 cotangent: &TracedTensor,
324 rules: &SemanticExtensionRuleSet,
325 cache: Option<&Arc<AdTransformCache>>,
326 transform: &'static str,
327) -> Result<Vec<Option<TracedTensor>>> {
328 if wrts.is_empty() {
329 return Ok(Vec::new());
330 }
331 let source = AdSource::of(output)?;
332 let slots: Vec<Option<usize>> = wrts
333 .iter()
334 .map(|wrt| source.slot_of(wrt))
335 .collect::<Result<_>>()?;
336 let mut active_inputs = vec![false; source.input_count()];
337 for slot in slots.iter().flatten().copied() {
338 active_inputs[slot] = true;
339 }
340 if !active_inputs.iter().any(|active| *active) {
341 return Ok(vec![None; wrts.len()]);
342 }
343 let cotangent_data = cotangent.attached_value().cloned().ok_or_else(|| {
344 Error::invalid_argument(
345 transform,
346 ErrorPhase::GraphBuild,
347 "cotangent",
348 format!("{transform} cotangent must have concrete tensor data"),
349 )
350 })?;
351 let seed = seed_leaf(output, output.trace_value(), &cotangent_data, transform)?;
352 let active_outputs = vec![true; source.frozen.program.outputs().len()];
353 let derivative = ad_context(rules, cache)
354 .vjp_program(&source.frozen, &active_inputs, &active_outputs)
355 .map_err(semantic_transform_error(transform))?;
356 let Some(seed_input_index) = derivative
357 .derivative_input_indices()
358 .first()
359 .copied()
360 .flatten()
361 else {
362 return Ok(vec![None; wrts.len()]);
363 };
364 validate_seed_against_program(
365 transform,
366 &source,
367 &cotangent_data,
368 cotangent_meta_of(output, &source, transform)?,
369 seed_input_index,
370 )?;
371 let mut requested = Vec::with_capacity(wrts.len());
372 let mut roots = Vec::new();
373 for (index, slot) in slots.iter().enumerate() {
374 let derivative_output = slot.and_then(|slot| {
375 derivative
376 .derivative_output_indices()
377 .get(slot)
378 .copied()
379 .flatten()
380 });
381 requested.push((index, derivative_output));
382 if let Some(derivative_output) = derivative_output
383 && !roots.contains(&derivative_output)
384 {
385 roots.push(derivative_output);
386 }
387 }
388 if roots.is_empty() {
389 return Ok(vec![None; wrts.len()]);
390 }
391 let imported = import_derivative(
392 output,
393 &source,
394 &derivative,
395 &[(seed_input_index, seed)],
396 &roots,
397 transform,
398 )?;
399 let mut results = vec![None; wrts.len()];
400 for (index, derivative_output) in requested {
401 if let Some(derivative_output) = derivative_output
402 && let Some(position) = roots.iter().position(|root| *root == derivative_output)
403 {
404 results[index] = imported.get(position).cloned();
405 }
406 }
407 Ok(results)
408}
409
410fn jvp_many_impl(
411 output: &TracedTensor,
412 wrt_tangents: &[(&TracedTensor, &TracedTensor)],
413 rules: &SemanticExtensionRuleSet,
414 cache: Option<&Arc<AdTransformCache>>,
415 transform: &'static str,
416) -> Result<Option<TracedTensor>> {
417 if wrt_tangents.is_empty() {
418 return Ok(None);
419 }
420 let source = AdSource::of(output)?;
421 let mut seen = HashSet::with_capacity(wrt_tangents.len());
422 let mut active_inputs = vec![false; source.input_count()];
423 let mut tangents = Vec::with_capacity(wrt_tangents.len());
424 for (wrt, tangent) in wrt_tangents {
425 let key = leaf_input_key(wrt)?;
426 if !seen.insert(key.clone()) {
427 return Err(Error::invalid_argument(
428 transform,
429 ErrorPhase::GraphBuild,
430 "wrt_tangents",
431 "wrt_tangents contains duplicate wrt leaves",
432 ));
433 }
434 let tangent_data = tangent.attached_value().cloned().ok_or_else(|| {
435 Error::invalid_argument(
436 transform,
437 ErrorPhase::GraphBuild,
438 "tangent",
439 format!("{transform} tangent must have concrete tensor data"),
440 )
441 })?;
442 tangents.push((wrt, tangent_data));
443 }
444 for (index, (wrt, _)) in tangents.iter().enumerate() {
445 let Some(slot) = source.slot_of(wrt)? else {
446 continue;
447 };
448 active_inputs[slot] = true;
449 let _ = index;
450 }
451 if !active_inputs.iter().any(|active| *active) {
452 return Ok(None);
453 }
454 let derivative = ad_context(rules, cache)
455 .jvp_program(&source.frozen, &active_inputs)
456 .map_err(semantic_transform_error(transform))?;
457 let Some(derivative_output_index) = derivative
458 .derivative_output_indices()
459 .first()
460 .copied()
461 .flatten()
462 else {
463 return Ok(None);
464 };
465 let mut seeds = Vec::with_capacity(tangents.len());
466 for (wrt, data) in tangents {
467 let Some(slot) = source.slot_of(wrt)? else {
468 continue;
469 };
470 let Some(seed_input_index) = derivative
471 .derivative_input_indices()
472 .get(slot)
473 .copied()
474 .flatten()
475 else {
476 continue;
477 };
478 validate_seed_against_program(
479 transform,
480 &source,
481 &data,
482 seed_meta_of(wrt)?,
483 seed_input_index,
484 )?;
485 let seed = seed_leaf(output, wrt.trace_value(), &data, transform)?;
486 seeds.push((seed_input_index, seed));
487 }
488 if seeds.is_empty() {
489 return Ok(None);
490 }
491 let mut imported = import_derivative(
492 output,
493 &source,
494 &derivative,
495 &seeds,
496 &[derivative_output_index],
497 transform,
498 )?;
499 Ok(imported.pop())
500}
501
502pub(crate) fn grad_with_rules_and_cache(
503 output: &TracedTensor,
504 wrt: &TracedTensor,
505 rules: &SemanticExtensionRuleSet,
506 cache: Option<&Arc<AdTransformCache>>,
507) -> Result<TracedTensor> {
508 let key = leaf_input_key(wrt)?;
509 grad_optional_with_rules_and_cache(output, wrt, rules, cache)
510 .and_then(|gradient| gradient.ok_or_else(|| inactive_wrt_error("grad", &key)))
511}
512
513pub(crate) fn grad_optional_with_rules_and_cache(
514 output: &TracedTensor,
515 wrt: &TracedTensor,
516 rules: &SemanticExtensionRuleSet,
517 cache: Option<&Arc<AdTransformCache>>,
518) -> Result<Option<TracedTensor>> {
519 if output.rank() != 0 {
520 return Err(Error::NonScalarGrad {
521 shape: error_shape_hint(output),
522 });
523 }
524 let ones = ones_tensor(output.dtype(), vec![])?;
525 let seed = output
526 .context()
527 .from_tensor_concrete_shape(ones)
528 .map_err(|source| Error::runtime_state_source("grad", ErrorPhase::GraphBuild, source))?;
529 vjp_many_impl(output, &[wrt], &seed, rules, cache, "grad")
530 .map(|mut results| results.pop().flatten())
531}
532
533pub(crate) fn jvp_with_rules_and_cache(
534 output: &TracedTensor,
535 wrt: &TracedTensor,
536 tangent: &TracedTensor,
537 rules: &SemanticExtensionRuleSet,
538 cache: Option<&Arc<AdTransformCache>>,
539) -> Result<TracedTensor> {
540 let key = leaf_input_key(wrt)?;
541 jvp_many_impl(output, &[(wrt, tangent)], rules, cache, "jvp")
542 .and_then(|result| result.ok_or_else(|| inactive_wrt_error("jvp", &key)))
543}
544
545pub(crate) fn jvp_optional_with_rules_and_cache(
546 output: &TracedTensor,
547 wrt: &TracedTensor,
548 tangent: &TracedTensor,
549 rules: &SemanticExtensionRuleSet,
550 cache: Option<&Arc<AdTransformCache>>,
551) -> Result<Option<TracedTensor>> {
552 jvp_many_impl(output, &[(wrt, tangent)], rules, cache, "jvp")
553}
554
555pub(crate) fn jvp_many_with_rules_and_cache(
556 output: &TracedTensor,
557 wrt_tangents: &[(&TracedTensor, &TracedTensor)],
558 rules: &SemanticExtensionRuleSet,
559 cache: Option<&Arc<AdTransformCache>>,
560) -> Result<Option<TracedTensor>> {
561 jvp_many_impl(output, wrt_tangents, rules, cache, "jvp")
562}
563
564pub(crate) fn vjp_with_rules_and_cache(
565 output: &TracedTensor,
566 wrt: &TracedTensor,
567 cotangent: &TracedTensor,
568 rules: &SemanticExtensionRuleSet,
569 cache: Option<&Arc<AdTransformCache>>,
570) -> Result<TracedTensor> {
571 let key = leaf_input_key(wrt)?;
572 vjp_optional_with_rules_and_cache(output, wrt, cotangent, rules, cache)
573 .and_then(|gradient| gradient.ok_or_else(|| inactive_wrt_error("vjp", &key)))
574}
575
576pub(crate) fn vjp_optional_with_rules_and_cache(
577 output: &TracedTensor,
578 wrt: &TracedTensor,
579 cotangent: &TracedTensor,
580 rules: &SemanticExtensionRuleSet,
581 cache: Option<&Arc<AdTransformCache>>,
582) -> Result<Option<TracedTensor>> {
583 vjp_many_impl(output, &[wrt], cotangent, rules, cache, "vjp")
584 .map(|mut results| results.pop().flatten())
585}
586
587pub(crate) fn vjp_many_with_rules_and_cache(
588 output: &TracedTensor,
589 wrts: &[&TracedTensor],
590 cotangent: &TracedTensor,
591 rules: &SemanticExtensionRuleSet,
592 cache: Option<&Arc<AdTransformCache>>,
593) -> Result<Vec<Option<TracedTensor>>> {
594 vjp_many_impl(output, wrts, cotangent, rules, cache, "vjp")
595}
596
597pub trait TracedTensorAdExt {
598 fn grad(&self, wrt: &TracedTensor) -> Result<TracedTensor>;
649
650 fn grad_optional(&self, wrt: &TracedTensor) -> Result<Option<TracedTensor>>;
679
680 fn checkpoint(
719 &mut self,
720 compiler: &mut GraphCompiler,
721 runtime: &Runtime,
722 engine: &mut dyn ExecutionEngine,
723 ) -> Result<()>;
724
725 fn jvp(&self, wrt: &TracedTensor, tangent: &TracedTensor) -> Result<TracedTensor>;
772
773 fn jvp_optional(
803 &self,
804 wrt: &TracedTensor,
805 tangent: &TracedTensor,
806 ) -> Result<Option<TracedTensor>>;
807
808 fn vjp(&self, wrt: &TracedTensor, cotangent: &TracedTensor) -> Result<TracedTensor>;
860
861 fn vjp_optional(
891 &self,
892 wrt: &TracedTensor,
893 cotangent: &TracedTensor,
894 ) -> Result<Option<TracedTensor>>;
895
896 fn grad_many(&self, wrts: &[&TracedTensor]) -> Result<Vec<Option<TracedTensor>>>;
922
923 fn value_and_grad(
947 &self,
948 wrts: &[&TracedTensor],
949 ) -> Result<(TracedTensor, Vec<Option<TracedTensor>>)>;
950
951 fn jvp_many(
973 &self,
974 wrt_tangents: &[(&TracedTensor, &TracedTensor)],
975 ) -> Result<Option<TracedTensor>>;
976
977 fn vjp_many(
999 &self,
1000 wrts: &[&TracedTensor],
1001 cotangent: &TracedTensor,
1002 ) -> Result<Vec<Option<TracedTensor>>>;
1003}
1004
1005impl TracedTensorAdExt for TracedTensor {
1006 fn grad(&self, wrt: &TracedTensor) -> Result<TracedTensor> {
1007 grad_with_rules_and_cache(self, wrt, &SemanticExtensionRuleSet::default(), None)
1008 }
1009
1010 fn grad_optional(&self, wrt: &TracedTensor) -> Result<Option<TracedTensor>> {
1011 grad_optional_with_rules_and_cache(self, wrt, &SemanticExtensionRuleSet::default(), None)
1012 }
1013
1014 fn checkpoint(
1015 &mut self,
1016 compiler: &mut GraphCompiler,
1017 runtime: &Runtime,
1018 engine: &mut dyn ExecutionEngine,
1019 ) -> Result<()> {
1020 let data = if let Some(data) = self.attached_value() {
1021 Arc::clone(data)
1022 } else {
1023 let program = compiler.compile(self)?;
1024 let target = engine.target();
1025 let prepared = runtime.prepare(&program, &[], std::slice::from_ref(&target))?;
1026 let outputs = crate::eager::run_prepared_on(runtime, engine, &prepared, &[])?;
1027 Arc::new(RetainedValue::from_tensor(single_runtime_output(
1028 outputs,
1029 "TracedTensorAdExt::checkpoint",
1030 )?))
1031 };
1032 let value = self
1033 .context()
1034 .checkpoint_value(self.trace_value(), Arc::clone(&data))
1035 .map_err(|source| {
1036 Error::runtime_state_source(
1037 "TracedTensorAdExt::checkpoint",
1038 ErrorPhase::GraphBuild,
1039 source,
1040 )
1041 })?;
1042 self.rebind_bound(value, data)
1043 }
1044
1045 fn jvp(&self, wrt: &TracedTensor, tangent: &TracedTensor) -> Result<TracedTensor> {
1046 jvp_with_rules_and_cache(
1047 self,
1048 wrt,
1049 tangent,
1050 &SemanticExtensionRuleSet::default(),
1051 None,
1052 )
1053 }
1054
1055 fn jvp_optional(
1056 &self,
1057 wrt: &TracedTensor,
1058 tangent: &TracedTensor,
1059 ) -> Result<Option<TracedTensor>> {
1060 jvp_optional_with_rules_and_cache(
1061 self,
1062 wrt,
1063 tangent,
1064 &SemanticExtensionRuleSet::default(),
1065 None,
1066 )
1067 }
1068
1069 fn vjp(&self, wrt: &TracedTensor, cotangent: &TracedTensor) -> Result<TracedTensor> {
1070 vjp_with_rules_and_cache(
1071 self,
1072 wrt,
1073 cotangent,
1074 &SemanticExtensionRuleSet::default(),
1075 None,
1076 )
1077 }
1078
1079 fn vjp_optional(
1080 &self,
1081 wrt: &TracedTensor,
1082 cotangent: &TracedTensor,
1083 ) -> Result<Option<TracedTensor>> {
1084 vjp_optional_with_rules_and_cache(
1085 self,
1086 wrt,
1087 cotangent,
1088 &SemanticExtensionRuleSet::default(),
1089 None,
1090 )
1091 }
1092
1093 fn grad_many(&self, wrts: &[&TracedTensor]) -> Result<Vec<Option<TracedTensor>>> {
1094 if self.rank() != 0 {
1095 return Err(Error::NonScalarGrad {
1096 shape: error_shape_hint(self),
1097 });
1098 }
1099 let ones = ones_tensor(self.dtype(), vec![])?;
1100 let seed = self
1101 .context()
1102 .from_tensor_concrete_shape(ones)
1103 .map_err(|source| {
1104 Error::runtime_state_source("grad_many", ErrorPhase::GraphBuild, source)
1105 })?;
1106 vjp_many_impl(
1107 self,
1108 wrts,
1109 &seed,
1110 &SemanticExtensionRuleSet::default(),
1111 None,
1112 "grad_many",
1113 )
1114 }
1115
1116 fn value_and_grad(
1117 &self,
1118 wrts: &[&TracedTensor],
1119 ) -> Result<(TracedTensor, Vec<Option<TracedTensor>>)> {
1120 let gradients = self.grad_many(wrts)?;
1121 Ok((self.clone(), gradients))
1122 }
1123
1124 fn jvp_many(
1125 &self,
1126 wrt_tangents: &[(&TracedTensor, &TracedTensor)],
1127 ) -> Result<Option<TracedTensor>> {
1128 jvp_many_impl(
1129 self,
1130 wrt_tangents,
1131 &SemanticExtensionRuleSet::default(),
1132 None,
1133 "jvp_many",
1134 )
1135 }
1136
1137 fn vjp_many(
1138 &self,
1139 wrts: &[&TracedTensor],
1140 cotangent: &TracedTensor,
1141 ) -> Result<Vec<Option<TracedTensor>>> {
1142 vjp_many_with_rules_and_cache(
1143 self,
1144 wrts,
1145 cotangent,
1146 &SemanticExtensionRuleSet::default(),
1147 None,
1148 )
1149 }
1150}
1151
1152fn single_runtime_output(mut outputs: Vec<Tensor>, op: &'static str) -> Result<Tensor> {
1153 if outputs.len() != 1 {
1154 return Err(Error::Internal(format!(
1155 "{op}: expected exactly one execution output, got {}",
1156 outputs.len()
1157 )));
1158 }
1159 Ok(outputs.remove(0))
1160}
1161
1162fn semantic_transform_error(
1163 transform: &'static str,
1164) -> impl FnOnce(SemanticAdTransformError) -> Error {
1165 move |source| {
1166 semantic_transform_validation_error(transform, &source).unwrap_or_else(|| {
1167 Error::runtime_state_source(transform, ErrorPhase::GraphBuild, source)
1168 })
1169 }
1170}
1171
1172fn semantic_transform_validation_error(
1173 transform: &'static str,
1174 source: &SemanticAdTransformError,
1175) -> Option<Error> {
1176 if let SemanticAdTransformError::Extension(
1177 SemanticAdError::Unsupported { family_id, .. }
1178 | SemanticAdError::MissingRule { family_id, .. },
1179 ) = source
1180 {
1181 return Some(Error::UnsupportedAdRule {
1182 transform,
1183 op: (*family_id).to_owned(),
1184 });
1185 }
1186
1187 let SemanticAdTransformError::Extension(SemanticAdError::Rule { source, .. }) = source else {
1188 return None;
1189 };
1190 let tenferro_ops::ad::ADRuleError::InvalidInput { op, message, .. } =
1191 source.downcast_ref::<tenferro_ops::ad::ADRuleError>()?
1192 else {
1193 return None;
1194 };
1195 Some(Error::invalid_argument(
1196 transform,
1197 ErrorPhase::GraphBuild,
1198 "semantic_ad_rule",
1199 format!("{op}: {message}"),
1200 ))
1201}
1202
1203fn validate_seed_tensor(
1204 transform: &'static str,
1205 input_index: usize,
1206 tensor: &RetainedValue,
1207 expected: &TensorMeta,
1208) -> Result<()> {
1209 let actual_dtype = tensor.dtype();
1210 if actual_dtype != expected.dtype {
1211 return Err(Error::invalid_argument(
1212 transform,
1213 ErrorPhase::GraphBuild,
1214 "seed",
1215 format!(
1216 "seed input {input_index} dtype mismatch: expected {:?}, got {:?}",
1217 expected.dtype, actual_dtype
1218 ),
1219 ));
1220 }
1221 let actual_shape = tensor.shape();
1222 if actual_shape.len() != expected.rank() {
1223 return Err(Error::invalid_argument(
1224 transform,
1225 ErrorPhase::GraphBuild,
1226 "seed",
1227 format!(
1228 "seed input {input_index} rank mismatch: expected {}, got {}",
1229 expected.rank(),
1230 actual_shape.len()
1231 ),
1232 ));
1233 }
1234 if let Some(expected_shape) = expected
1235 .exact_shape()
1236 .filter(|shape| shape.iter().all(|dim| dim.constant_value().is_some()))
1237 .map(|shape| {
1238 shape
1239 .into_iter()
1240 .map(|dim| dim.constant_value().expect("filtered constant shape"))
1241 .collect::<Vec<_>>()
1242 })
1243 && expected_shape != actual_shape
1244 {
1245 return Err(Error::invalid_argument(
1246 transform,
1247 ErrorPhase::GraphBuild,
1248 "seed",
1249 format!(
1250 "seed input {input_index} shape mismatch: expected {:?}, got {:?}",
1251 expected_shape, actual_shape
1252 ),
1253 ));
1254 }
1255 Ok(())
1256}
1257
1258#[cfg(test)]
1259mod semantic_transform_error_tests {
1260 use super::*;
1261 use crate::semantic_extension::SemanticAdRuleRole;
1262
1263 #[test]
1264 fn unsupported_semantic_rule_maps_to_public_transform_error() {
1265 let source = SemanticAdTransformError::Extension(SemanticAdError::Unsupported {
1266 family_id: "tenferro-tests.unsupported.v1",
1267 role: SemanticAdRuleRole::LinearTranspose,
1268 message: "unsupported test payload".into(),
1269 });
1270
1271 let error = semantic_transform_validation_error("vjp", &source)
1272 .expect("semantic rejection must map to a public unsupported-rule error");
1273
1274 assert!(matches!(
1275 error,
1276 Error::UnsupportedAdRule { transform: "vjp", ref op }
1277 if op == "tenferro-tests.unsupported.v1"
1278 ));
1279 }
1280
1281 #[test]
1282 fn missing_semantic_rule_maps_to_public_transform_error() {
1283 let source = SemanticAdTransformError::Extension(SemanticAdError::MissingRule {
1284 family_id: "tenferro-tests.missing.v1",
1285 role: SemanticAdRuleRole::Linearize,
1286 });
1287
1288 let error = semantic_transform_validation_error("jvp", &source)
1289 .expect("missing semantic rule must map to a public unsupported-rule error");
1290
1291 assert!(matches!(
1292 error,
1293 Error::UnsupportedAdRule { transform: "jvp", ref op }
1294 if op == "tenferro-tests.missing.v1"
1295 ));
1296 }
1297}