tenferro_ad/lib.rs
1//! Automatic differentiation APIs for tenferro.
2//!
3//! This crate is the explicit opt-in boundary for traced and eager automatic
4//! differentiation. Primal graph construction and execution live in
5//! `tenferro-runtime`; tensor storage lives in `tenferro-tensor`, and CPU
6//! execution lives in `tenferro-cpu`.
7//!
8//! Use [`EagerRuntime`] and [`EagerTensor`] for PyTorch-style immediate
9//! execution where tracked variables accumulate gradients after `EagerSession::backward`.
10//! Use [`TracedTensorAdExt`] or [`AdContext`] for JAX-style graph transforms
11//! such as `grad`, `vjp`, and `jvp` on [`tenferro_runtime::TracedTensor`]
12//! values. `AdContext` is the explicit place to add extension AD rule sets for
13//! operation-family crates such as `tenferro-linalg`.
14//!
15//! User-facing guides live at
16//! <https://tensor4all.org/tenferro-rs/guides/autodiff.html> and
17//! <https://tensor4all.org/tenferro-rs/guides/choosing-an-api.html>.
18//!
19//! # Examples
20//!
21//! ```rust
22//! use tenferro_ad::AdContext;
23//! use tenferro_runtime::{TraceContext, TracedTensor};
24//!
25//! let ad = AdContext::builder().build().unwrap();
26//! let trace = TraceContext::new();
27//! let x = trace.from_vec_col_major(vec![], vec![3.0_f64]).unwrap();
28//! let loss = (&x * &x).unwrap();
29//! let dx = ad.grad(&loss, &x).unwrap();
30//! assert_eq!(dx.rank(), 0);
31//! ```
32//!
33//! # Errors
34//!
35//! [`Error`] (the runtime error type, re-exported here) has public
36//! constructors for the failures downstream code reports itself:
37//! [`Error::invalid_argument`], [`Error::unsupported`],
38//! [`Error::dtype_mismatch`], [`Error::validation`], [`Error::runtime_state`],
39//! and [`Error::extension`] for a typed source error. Each takes the operation
40//! name and an [`ErrorPhase`]. A `tenferro_tensor::Error` converts with
41//! `From`, so `?` works on tensor-level results inside functions returning
42//! [`Result`]. Match on [`Error::kind`] rather than on variant shapes.
43//!
44//! ```rust
45//! use tenferro_ad::{Error, ErrorPhase};
46//!
47//! fn check_rank(rank: usize) -> tenferro_ad::Result<()> {
48//! if rank != 2 {
49//! return Err(Error::invalid_argument(
50//! "my_crate::attention",
51//! ErrorPhase::Execution,
52//! "query",
53//! format!("expected a rank-2 query, got rank {rank}"),
54//! ));
55//! }
56//! Ok(())
57//! }
58//!
59//! let error = check_rank(3).unwrap_err();
60//! assert_eq!(
61//! error.kind(),
62//! tenferro_tensor::ErrorKind::Validation(tenferro_tensor::ValidationKind::InvalidArgument)
63//! );
64//! let unsupported = Error::unsupported("my_crate::op", ErrorPhase::Execution, "no GPU path yet");
65//! assert_eq!(unsupported.kind(), tenferro_tensor::ErrorKind::Unsupported);
66//! let tensor_error: Error = tenferro_tensor::Error::invalid_argument("op", "arg", "bad").into();
67//! assert!(matches!(tensor_error.kind(), tenferro_tensor::ErrorKind::Validation(_)));
68//! ```
69
70mod api;
71mod context;
72mod eager;
73mod eager_backend;
74pub(crate) mod eager_exec;
75pub(crate) mod eager_ops;
76pub mod extension;
77pub mod prelude;
78// semantic_compat removed in Unification 7.
79pub mod semantic_extension;
80pub mod semantic_transform;
81mod shape_packing;
82pub mod traced;
83mod transform_cache;
84
85pub use context::{AdContext, AdContextBuilder, AdContextCacheStats};
86pub use eager::{
87 EagerNoGradGuard, EagerRuntime, EagerRuntimeCacheStats, EagerSession, EagerTensor,
88 EagerTraceCaptureGuard, GradientValue, Gradients, IntoValueError, ValueGuard,
89};
90pub use shape_packing::EagerSliceBuilder;
91pub(crate) use tenferro_runtime::scalar_semantics;
92pub use transform_cache::AdTransformCacheLimits;
93pub(crate) mod shape_infer {
94 pub use tenferro_runtime::extension::{
95 promote_dtype, promote_dtype_for_binary_op, promote_dtypes,
96 };
97}
98pub use tenferro_runtime::{
99 CompareDir, DType, DotGeneralConfig, GatherConfig, PadConfig, ScatterConfig, SliceConfig,
100 Tensor,
101};
102pub use traced::TracedTensorAdExt;
103
104pub use tenferro_runtime::{ContextId, Error, ErrorPhase, Result};
105
106pub mod error {
107 pub use tenferro_runtime::{ContextId, Error, ErrorPhase, Result};
108}
109
110pub(crate) mod metadata {}