Skip to main content

tenferro_runtime/
sym_dim.rs

1//! Symbolic dimensions of traced values.
2//!
3//! A [`SymDim`] tensor axis names a traced handle by an id that the handle hands
4//! out, through [`TracedTensor::sym_size`](crate::TracedTensor::sym_size),
5//! [`TracedTensor::axis_sym_dim`](crate::TracedTensor::axis_sym_dim) and
6//! [`TracedTensor::sym_shape`](crate::TracedTensor::sym_shape). A program's
7//! `DimExpr::InputDim` names a program input by position instead. Program input
8//! #1 and the handle whose id is 1 are different things.
9//!
10//! The runtime and `tenferro-ad` conversion paths no longer fabricate handle
11//! identity from a program position: a handle's cached extents are derived from
12//! its value metadata as constants or as that handle's own axes, extension shape
13//! inference gives each extension input a call-local id counted down from
14//! `u64::MAX`, and the `tenferro-ad` traced path asks the handle for its axis
15//! (#2443).
16//!
17//! A conversion accepts the axes of the handles it was given and rejects any
18//! other handle's axis:
19//!
20//! ```
21//! use tenferro_runtime::{DType, Error, TraceContext};
22//!
23//! let trace = TraceContext::new();
24//! let a = trace.input_symbolic_shape(DType::F64, 1)?; // program input #0
25//! let b = trace.input_symbolic_shape(DType::F64, 1)?; // program input #1
26//!
27//! // `a`'s own extent converts against `a`.
28//! assert!(a.reshape_sym(&[a.sym_size(0)?]).is_ok());
29//! // `b`'s extent does not: `reshape_sym` only knows `a`.
30//! let err = a.reshape_sym(&[b.sym_size(0)?]).unwrap_err();
31//! assert!(matches!(err, Error::SymbolicShapeConversion { .. }));
32//! # Ok::<(), tenferro_runtime::Error>(())
33//! ```
34//!
35//! The removed `dim_expr_to_sym_dim_public` helper, which turned a program
36//! coordinate into a `SymDim`, stays removed (#2443). This pins that one public
37//! path; it does not show that no other path exists (see Known limits):
38//!
39//! ```compile_fail,E0425
40//! use tenferro_ops::dim_expr::DimExpr;
41//! use tenferro_runtime::{DType, TraceContext};
42//!
43//! let trace = TraceContext::new();
44//! let a = trace.input_symbolic_shape(DType::F64, 1)?; // program input #0
45//! let _b = trace.input_symbolic_shape(DType::F64, 1)?; // program input #1
46//! // "Program input #1, axis 0" would carry the same id as a handle's axis.
47//! let b_extent = tenferro_runtime::dim_expr_to_sym_dim_public(&DimExpr::InputDim {
48//!     input_idx: 1,
49//!     axis: 0,
50//! })
51//! .unwrap();
52//! let _ = a.reshape_sym(&[b_extent]);
53//! # Ok::<(), tenferro_runtime::Error>(())
54//! ```
55//!
56//! # Known limits
57//!
58//! The guarantee above is a property of those paths, not of the type. The raw
59//! constructor `SymDim::tensor_axis(tensor_id, axis)` (defined in
60//! `tenferro-internal-ops`, `src/sym_dim.rs`) is `#[doc(hidden)]` but `pub`, and
61//! reaches every downstream crate as `tenferro_runtime::SymDim::tensor_axis`
62//! through the re-export below. It builds an axis carrying any id, including one
63//! equal to a live handle's id or to a program input position, and a conversion
64//! that knows a handle with that id accepts it. Its in-tree callers outside the
65//! runtime are `tenferro-einsum`'s extension AD, which uses ids counted down from
66//! `u64::MAX`, and `tenferro-linalg`'s semantic AD (`synthetic_input_shapes`),
67//! which uses program input positions offset by one. Keeping those ids apart from
68//! handle ids is the callers' responsibility, not the constructor's.
69
70pub use tenferro_ops::sym_dim::*;