Skip to main content

tenferro_runtime/
trace_ops.rs

1//! Typed operation surface over one [`TraceContext`](crate::TraceContext).
2//!
3//! Every standard operation and every traced constructor is written once here
4//! against a `(TraceContext, TraceValue)` pair. [`TracedTensor`] methods and the
5//! extension traits delegate to these helpers, so there is exactly one place that
6//! appends an operation and exactly one place that derives a tensor's cached
7//! metadata.
8
9use std::sync::Arc;
10
11use tenferro_ops::dim_expr::DimExpr;
12use tenferro_ops::ext_op::ExtensionOp;
13use tenferro_ops::shape_extent::ShapeExtent;
14use tenferro_ops::std_tensor_op::StdTensorOp;
15use tenferro_tensor::{DType, IntoShapeVec, Tensor, TensorScalar, TensorValue};
16
17use crate::checkpoint::RetainedValue;
18use crate::error::{Error, ErrorPhase, Result};
19use crate::program::{CoreSemanticOp, ProgramBuildError, ProgramInputSpec, ProgramValueMetadata};
20use crate::sym_dim::SymDim;
21use crate::trace::{TraceContext, TraceValue};
22use crate::traced::TracedTensor;
23
24/// Map a standard operation payload onto the closed core vocabulary.
25///
26/// # Errors
27///
28/// Returns [`Error::RuntimeState`] for the extension carrier, which must be
29/// appended through [`append_extension`] instead.
30pub(crate) fn core_op(op: &StdTensorOp) -> Result<CoreSemanticOp> {
31    CoreSemanticOp::try_from(op).map_err(|source| {
32        Error::runtime_state_source("semantic core operation", ErrorPhase::GraphBuild, source)
33    })
34}
35
36/// Append one standard operation to the context.
37pub(crate) fn append_core(
38    ctx: &TraceContext,
39    op: &StdTensorOp,
40    inputs: &[TraceValue],
41) -> Result<Box<[TraceValue]>> {
42    let core = core_op(op)?;
43    ctx.add_op(core, inputs)
44        .map_err(|source| build_error("semantic standard operation", source))
45}
46
47/// Append one extension operation to the context.
48pub(crate) fn append_extension(
49    ctx: &TraceContext,
50    op: Arc<dyn ExtensionOp>,
51    inputs: &[TraceValue],
52) -> Result<Box<[TraceValue]>> {
53    ctx.add_extension(op, inputs)
54        .map_err(|source| build_error("semantic extension operation", source))
55}
56
57/// Build a tensor for a value the context just appended.
58///
59/// `rank`/`dtype`/`hint` are the op-specific expectations; the returned cache is
60/// derived from the context metadata and cross-checked against them, so the cache
61/// can never disagree with the program.
62pub(crate) fn finish_value(
63    ctx: &TraceContext,
64    value: TraceValue,
65    rank: usize,
66    dtype: DType,
67    hint: Option<Vec<SymDim>>,
68) -> Result<TracedTensor> {
69    let metadata = ctx
70        .value_metadata(value)
71        .map_err(|source| build_error("semantic value metadata", source))?;
72    debug_assert_eq!(
73        rank,
74        metadata.shape().len(),
75        "cached rank must match the appended value"
76    );
77    debug_assert_eq!(
78        dtype,
79        metadata.dtype(),
80        "cached dtype must match the appended value"
81    );
82    let symbolic_id = next_symbolic_id();
83    let derived = metadata_sym_shape(&metadata, symbolic_id);
84    // An extent the program only bounds must not resurface as a concrete shape, and a
85    // caller-supplied hint describes the shape the caller asked for, not the precision
86    // the program proved: drop it unless every extent is exact.
87    let hint = if crate::shape_infer::extent_precision(metadata.shape().iter())
88        == crate::shape_infer::ExtentPrecision::Exact
89    {
90        hint
91    } else {
92        None
93    };
94    Ok(TracedTensor {
95        ctx: ctx.clone(),
96        value,
97        rank: metadata.shape().len(),
98        dtype: metadata.dtype(),
99        shape_hint: derived.or_else(|| restamp_hint(hint, symbolic_id)),
100        data: None,
101        symbolic_id,
102    })
103}
104
105/// Build a leaf tensor for a value the context just added as an input.
106fn finish_leaf(
107    ctx: &TraceContext,
108    value: TraceValue,
109    rank: usize,
110    dtype: DType,
111    hint: Option<Vec<SymDim>>,
112    data: Option<Arc<RetainedValue>>,
113) -> Result<TracedTensor> {
114    let mut tensor = finish_value(ctx, value, rank, dtype, hint)?;
115    tensor.data = data;
116    Ok(tensor)
117}
118
119/// Build a tensor purely from the value's context metadata.
120pub(crate) fn finish_derived(ctx: &TraceContext, value: TraceValue) -> Result<TracedTensor> {
121    let metadata = ctx
122        .value_metadata(value)
123        .map_err(|source| build_error("semantic value metadata", source))?;
124    finish_value(ctx, value, metadata.shape().len(), metadata.dtype(), None)
125}
126
127/// Build a tensor for a value the context just bound to concrete data.
128pub(crate) fn finish_bound_value(
129    ctx: &TraceContext,
130    value: TraceValue,
131    data: Arc<RetainedValue>,
132) -> Result<TracedTensor> {
133    let metadata = ctx
134        .value_metadata(value)
135        .map_err(|source| build_error("semantic value metadata", source))?;
136    let mut tensor = finish_value(ctx, value, metadata.shape().len(), metadata.dtype(), None)?;
137    tensor.data = Some(data);
138    Ok(tensor)
139}
140
141/// Allocate the symbolic identity of one traced value.
142///
143/// The identity is unique per handle rather than derived from the program value,
144/// so no two tensors — in one context or across contexts — can name the same
145/// symbolic axis by accident.
146fn next_symbolic_id() -> u64 {
147    static NEXT_SYMBOLIC_ID: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(1);
148    NEXT_SYMBOLIC_ID.fetch_add(1, std::sync::atomic::Ordering::Relaxed)
149}
150
151/// Re-express a symbolic shape in terms of the value that owns it.
152///
153/// `sym_size`/`axis_sym_dim` must hand back expressions that a *consumer* of this
154/// value can convert into its own input coordinates, so every non-constant axis
155/// names this value's axis instead of the axes of the operation that produced it.
156fn restamp_hint(hint: Option<Vec<SymDim>>, own_id: u64) -> Option<Vec<SymDim>> {
157    hint.map(|shape| {
158        shape
159            .into_iter()
160            .enumerate()
161            .map(|(axis, dim)| {
162                if dim.constant_value().is_some() {
163                    dim
164                } else {
165                    SymDim::tensor_axis(own_id, axis)
166                }
167            })
168            .collect()
169    })
170}
171
172/// Derive the symbolic shape cache of the handle `own_id` from value metadata.
173///
174/// Program metadata names program inputs by position (`DimExpr::InputDim`), and
175/// those positions are not handle ids: program input #1 and the handle whose id
176/// is 1 are unrelated. The cache therefore never carries a program coordinate.
177/// An extent that evaluates without inputs becomes a constant; every other axis
178/// names this handle's own axis. Returns `None` when an extent is not exact.
179fn metadata_sym_shape(metadata: &ProgramValueMetadata, own_id: u64) -> Option<Vec<SymDim>> {
180    metadata
181        .shape()
182        .iter()
183        .enumerate()
184        .map(|(axis, extent)| match extent {
185            ShapeExtent::Exact(expr) => Some(match expr.eval(&[]) {
186                Ok(size) => SymDim::from(size),
187                Err(_) => SymDim::tensor_axis(own_id, axis),
188            }),
189            _ => None,
190        })
191        .collect()
192}
193
194pub(crate) fn build_error(op: &'static str, source: ProgramBuildError) -> Error {
195    match source {
196        ProgramBuildError::Metadata { source } => *source,
197        other => Error::runtime_state_source(op, ErrorPhase::GraphBuild, other),
198    }
199}
200
201fn concrete_spec(
202    dtype: DType,
203    shape: &[usize],
204    identity: Option<&'static str>,
205) -> ProgramInputSpec {
206    let metadata = ProgramValueMetadata::new(dtype, shape.iter().map(|&size| DimExpr::Const(size)));
207    let spec = ProgramInputSpec::from_metadata(metadata);
208    match identity {
209        Some(identity) => spec.with_scalar_identity(identity),
210        None => spec,
211    }
212}
213
214fn concrete_hint(shape: &[usize]) -> Option<Vec<SymDim>> {
215    Some(shape.iter().map(|&size| SymDim::from(size)).collect())
216}
217
218fn symbolic_spec(dtype: DType, rank: usize, input_idx: usize) -> ProgramInputSpec {
219    ProgramInputSpec::new(
220        dtype,
221        (0..rank).map(|axis| DimExpr::InputDim { input_idx, axis }),
222    )
223}
224
225impl TraceContext {
226    /// Add a placeholder input with a fixed concrete shape.
227    ///
228    /// # Examples
229    ///
230    /// ```
231    /// use tenferro_runtime::TraceContext;
232    /// use tenferro_tensor::DType;
233    ///
234    /// let trace = TraceContext::new();
235    /// let x = trace.input_concrete_shape(DType::F64, &[2, 3])?;
236    /// assert_eq!(x.rank(), 2);
237    /// assert!(x.is_concrete_shape());
238    /// # Ok::<(), tenferro_runtime::Error>(())
239    /// ```
240    ///
241    /// # Errors
242    ///
243    /// Returns [`Error::RuntimeState`] when the trace cannot accept another input
244    /// or a binding already exists for it.
245    pub fn input_concrete_shape(&self, dtype: DType, shape: &[usize]) -> Result<TracedTensor> {
246        self.input_concrete_shape_with_identity(dtype, shape, None)
247    }
248
249    /// Add a placeholder input of concrete shape declaring an external scalar.
250    ///
251    /// # Errors
252    ///
253    /// Returns [`Error::RuntimeState`] when the trace cannot accept another input
254    /// or a binding already exists for it, and [`Error::RuntimeStateSource`]
255    /// wrapping `ProgramBuildError::ExternalScalarWithoutIdentity` when an
256    /// externally defined scalar dtype reaches the builder without the declared
257    /// identity.
258    pub fn input_concrete_shape_declaring_scalar(
259        &self,
260        dtype: DType,
261        shape: &[usize],
262        identity: &'static str,
263    ) -> Result<TracedTensor> {
264        self.input_concrete_shape_with_identity(dtype, shape, Some(identity))
265    }
266
267    fn input_concrete_shape_with_identity(
268        &self,
269        dtype: DType,
270        shape: &[usize],
271        identity: Option<&'static str>,
272    ) -> Result<TracedTensor> {
273        let spec = concrete_spec(dtype, shape, identity);
274        let value = self
275            .input(spec)
276            .map_err(|source| build_error("trace input", source))?;
277        finish_leaf(self, value, shape.len(), dtype, concrete_hint(shape), None)
278    }
279
280    /// Add a placeholder input with symbolic (rank-only) extents.
281    ///
282    /// # Examples
283    ///
284    /// ```
285    /// use tenferro_runtime::TraceContext;
286    /// use tenferro_tensor::DType;
287    ///
288    /// let trace = TraceContext::new();
289    /// let x = trace.input_symbolic_shape(DType::F64, 2)?;
290    /// assert_eq!(x.rank(), 2);
291    /// assert!(!x.is_concrete_shape());
292    /// # Ok::<(), tenferro_runtime::Error>(())
293    /// ```
294    ///
295    /// # Errors
296    ///
297    /// Returns [`Error::RuntimeState`] when the trace cannot accept another input.
298    pub fn input_symbolic_shape(&self, dtype: DType, rank: usize) -> Result<TracedTensor> {
299        let index = self.input_count();
300        let spec = symbolic_spec(dtype, rank, index);
301        let value = self
302            .input(spec)
303            .map_err(|source| build_error("trace input", source))?;
304        finish_leaf(self, value, rank, dtype, None, None)
305    }
306
307    /// Add a constant leaf holding `tensor` with its concrete shape.
308    ///
309    /// # Examples
310    ///
311    /// ```
312    /// use tenferro_runtime::{Tensor, TraceContext};
313    ///
314    /// let trace = TraceContext::new();
315    /// let x = trace.from_tensor_concrete_shape(
316    ///     Tensor::from_vec_col_major(vec![2], vec![1.0_f64, 2.0])?,
317    /// )?;
318    /// assert!(x.attached_value().is_some());
319    /// # Ok::<(), Box<dyn std::error::Error>>(())
320    /// ```
321    ///
322    /// # Errors
323    ///
324    /// Returns [`Error::Validation`] for a malformed tensor or
325    /// [`Error::RuntimeState`] when the trace cannot bind the constant.
326    pub fn from_tensor_concrete_shape(&self, tensor: Tensor) -> Result<TracedTensor> {
327        self.tensor_concrete_shape_with_identity(tensor, None)
328    }
329
330    /// Add a constant leaf of concrete shape declaring an external scalar.
331    ///
332    /// # Errors
333    ///
334    /// Returns [`Error::Validation`] for a malformed tensor, [`Error::RuntimeState`]
335    /// when the trace cannot bind the constant, and [`Error::RuntimeStateSource`]
336    /// wrapping `ProgramBuildError::ExternalScalarWithoutIdentity` when an
337    /// externally defined scalar dtype reaches the builder without the declared
338    /// identity.
339    pub fn from_tensor_concrete_shape_declaring_scalar(
340        &self,
341        tensor: Tensor,
342        identity: &'static str,
343    ) -> Result<TracedTensor> {
344        self.tensor_concrete_shape_with_identity(tensor, Some(identity))
345    }
346
347    fn tensor_concrete_shape_with_identity(
348        &self,
349        tensor: Tensor,
350        identity: Option<&'static str>,
351    ) -> Result<TracedTensor> {
352        let dtype = tensor.dtype();
353        let shape = tensor.shape().to_vec();
354        let spec = concrete_spec(dtype, &shape, identity);
355        let data = Arc::new(RetainedValue::from_tensor(tensor));
356        let value = self
357            .input_bound(spec, Arc::clone(&data))
358            .map_err(|source| build_error("trace constant", source))?;
359        finish_leaf(
360            self,
361            value,
362            shape.len(),
363            dtype,
364            concrete_hint(&shape),
365            Some(data),
366        )
367    }
368
369    /// Add a constant leaf holding `tensor` but advertising symbolic extents.
370    ///
371    /// # Errors
372    ///
373    /// Returns [`Error::RuntimeState`] when the trace cannot bind the constant.
374    pub fn from_tensor_symbolic_shape(&self, tensor: Tensor) -> Result<TracedTensor> {
375        let data = Arc::new(RetainedValue::from_tensor(tensor));
376        self.from_shared_tensor_value_symbolic_shape(data)
377    }
378
379    /// Add a constant leaf from a value, advertising symbolic extents.
380    ///
381    /// # Errors
382    ///
383    /// Returns [`Error::RuntimeState`] when the value cannot be retained or the
384    /// trace cannot bind it.
385    #[doc(hidden)]
386    pub fn from_tensor_value_symbolic_shape(&self, value: TensorValue) -> Result<TracedTensor> {
387        let data = Arc::new(RetainedValue::from_tensor_value(value)?);
388        self.from_shared_tensor_value_symbolic_shape(data)
389    }
390
391    /// Add a constant leaf from an already-retained value with symbolic extents.
392    ///
393    /// # Errors
394    ///
395    /// Returns [`Error::RuntimeState`] when the trace cannot bind the value.
396    #[doc(hidden)]
397    pub fn from_shared_tensor_value_symbolic_shape(
398        &self,
399        data: Arc<RetainedValue>,
400    ) -> Result<TracedTensor> {
401        let rank = data.shape().len();
402        let dtype = data.dtype();
403        let index = self.input_count();
404        let spec = symbolic_spec(dtype, rank, index);
405        let value = self
406            .input_bound(spec, Arc::clone(&data))
407            .map_err(|source| build_error("trace constant", source))?;
408        finish_leaf(self, value, rank, dtype, None, Some(data))
409    }
410
411    /// Add a constant leaf from compact column-major data.
412    ///
413    /// # Errors
414    ///
415    /// Returns [`Error::TensorRuntime`] with a typed validation error when the
416    /// shape and data length disagree.
417    pub fn from_vec_col_major<T: TensorScalar>(
418        &self,
419        shape: impl IntoShapeVec,
420        data: Vec<T>,
421    ) -> Result<TracedTensor> {
422        let tensor = Tensor::from_vec_col_major(shape, data)?;
423        self.from_tensor_concrete_shape(tensor)
424    }
425}