Skip to main content

coeus_ops/fuse/
expr_node.rs

1use crate::fuse::op_tags::{BinaryOpTag, UnaryOpTag};
2use crate::CpuBackend;
3use coeus_core::{BackendError, ComputeBackend, CpuAddressableStorage, Scalar, Shape};
4use coeus_tensor::broadcast::broadcast_shapes;
5use coeus_tensor::Tensor;
6use std::collections::HashMap;
7
8/// A node in the fused expression DAG.
9///
10/// Implementors describe how to collect input tensors and emit an accelerator
11/// shader fragment. CPU scalar evaluation is isolated in [`CpuExprNode`].
12pub trait ExprNode<T: Scalar, B: ComputeBackend>: Send + Sync {
13    /// Collect all input tensors borrowed by this node.
14    fn collect_inputs<'expression>(&'expression self, list: &mut Vec<&'expression Tensor<T, B>>);
15    /// Emit a WGSL expression string referencing the inputs by index.
16    fn to_shader_expr(&self, input_map: &HashMap<*const Tensor<T, B>, usize>) -> String;
17
18    /// Returns the output shape of this node, or `None` for scalar nodes.
19    ///
20    /// # Errors
21    ///
22    /// Returns [`BackendError`] when child shapes cannot be broadcast.
23    fn shape(&self) -> Result<Option<Shape>, BackendError>;
24
25    /// Returns `true` if this node is contiguous and matches `out_shape`.
26    fn is_contiguous_and_same_shape(&self, out_shape: &[usize]) -> bool;
27}
28
29/// CPU-addressable scalar evaluation for a fused expression node.
30///
31/// This capability is implemented only when every tensor leaf uses storage
32/// directly readable by a [`CpuBackend`]. Accelerator expressions retain the
33/// device-neutral [`ExprNode`] contract without acquiring a host fallback.
34pub trait CpuExprNode<T: Scalar, B: CpuBackend>: ExprNode<T, B> {
35    /// Evaluate the node at the specified coordinates.
36    ///
37    /// # Safety
38    /// The caller must ensure that the coordinates are within bounds for the
39    /// expression shape and that the underlying input tensors remain valid.
40    unsafe fn eval_cpu(&self, coords: &[usize]) -> T;
41
42    /// Evaluate the node at a flat index for contiguous tensors.
43    ///
44    /// # Safety
45    /// The caller must ensure that the index is within flat offset bounds.
46    unsafe fn eval_cpu_flat(&self, idx: usize) -> T;
47}
48
49/// A borrowed tensor leaf in the fused expression DAG.
50pub struct TensorRef<'tensor, T: Scalar, B: ComputeBackend>(&'tensor Tensor<T, B>);
51
52impl<T: Scalar, B: ComputeBackend> Clone for TensorRef<'_, T, B> {
53    #[inline(always)]
54    fn clone(&self) -> Self {
55        *self
56    }
57}
58
59impl<T: Scalar, B: ComputeBackend> Copy for TensorRef<'_, T, B> {}
60
61impl<T: Scalar, B: ComputeBackend> ExprNode<T, B> for TensorRef<'_, T, B> {
62    fn collect_inputs<'expression>(&'expression self, list: &mut Vec<&'expression Tensor<T, B>>) {
63        if !list.iter().any(|tensor| std::ptr::eq(*tensor, self.0)) {
64            list.push(self.0);
65        }
66    }
67
68    fn to_shader_expr(&self, input_map: &HashMap<*const Tensor<T, B>, usize>) -> String {
69        let ptr = std::ptr::from_ref(self.0);
70        let idx = input_map.get(&ptr).expect("Input tensor not found in map");
71        format!("val_{}", idx)
72    }
73
74    fn shape(&self) -> Result<Option<Shape>, BackendError> {
75        Ok(Some(self.0.shape_cloned()))
76    }
77
78    fn is_contiguous_and_same_shape(&self, out_shape: &[usize]) -> bool {
79        let layout = self.0.layout();
80        layout.is_contiguous() && layout.shape() == out_shape
81    }
82}
83
84impl<T, B> CpuExprNode<T, B> for TensorRef<'_, T, B>
85where
86    T: Scalar,
87    B: CpuBackend,
88    B::DeviceBuffer<T>: CpuAddressableStorage<T>,
89{
90    unsafe fn eval_cpu(&self, coords: &[usize]) -> T {
91        let tensor = self.0;
92        let layout = tensor.layout();
93        let shape = layout.shape();
94        let strides = layout.strides();
95        let ndim = layout.ndim();
96        let out_ndim = coords.len();
97
98        let mut off = layout.offset();
99        let diff = out_ndim.saturating_sub(ndim);
100        for (d, &coord) in coords.iter().enumerate().skip(diff) {
101            let ad = d - diff;
102            if shape[ad] > 1 {
103                off += coord * strides[ad];
104            }
105        }
106        tensor.storage().as_slice()[off]
107    }
108
109    unsafe fn eval_cpu_flat(&self, idx: usize) -> T {
110        let tensor = self.0;
111        let off = tensor.layout().offset() + idx;
112        tensor.storage().as_slice()[off]
113    }
114}
115
116#[derive(Clone, Copy)]
117/// A scalar constant leaf node in the fused expression DAG.
118pub struct ScalarVal<T: Scalar>(pub T);
119
120impl<T: Scalar, B: ComputeBackend> ExprNode<T, B> for ScalarVal<T> {
121    fn collect_inputs<'expression>(&'expression self, _list: &mut Vec<&'expression Tensor<T, B>>) {}
122
123    fn to_shader_expr(&self, _input_map: &HashMap<*const Tensor<T, B>, usize>) -> String {
124        let val = <T as coeus_core::NumericElement>::to_f64(self.0);
125        if val.is_infinite() {
126            if val.is_sign_positive() {
127                "3.40282347e+38".to_string()
128            } else {
129                "-3.40282347e+38".to_string()
130            }
131        } else if val.is_nan() {
132            "0.0".to_string()
133        } else {
134            let s = format!("{:?}", val);
135            if s.contains('.') || s.contains('e') {
136                s
137            } else {
138                format!("{}.0", s)
139            }
140        }
141    }
142
143    fn shape(&self) -> Result<Option<Shape>, BackendError> {
144        Ok(None)
145    }
146
147    fn is_contiguous_and_same_shape(&self, _out_shape: &[usize]) -> bool {
148        true
149    }
150}
151
152impl<T: Scalar, B: CpuBackend> CpuExprNode<T, B> for ScalarVal<T> {
153    unsafe fn eval_cpu(&self, _coords: &[usize]) -> T {
154        self.0
155    }
156
157    unsafe fn eval_cpu_flat(&self, _idx: usize) -> T {
158        self.0
159    }
160}
161
162#[derive(Clone, Copy)]
163/// A unary operation node in the fused expression DAG.
164pub struct UnaryExpr<Op, Child> {
165    /// The operation tag.
166    pub op: Op,
167    /// The child sub-expression.
168    pub child: Child,
169}
170
171impl<Op: UnaryOpTag<T> + Send, Child: ExprNode<T, B>, T: Scalar, B: ComputeBackend> ExprNode<T, B>
172    for UnaryExpr<Op, Child>
173{
174    fn collect_inputs<'expression>(&'expression self, list: &mut Vec<&'expression Tensor<T, B>>) {
175        self.child.collect_inputs(list);
176    }
177
178    fn to_shader_expr(&self, input_map: &HashMap<*const Tensor<T, B>, usize>) -> String {
179        let child_str = self.child.to_shader_expr(input_map);
180        Op::wgsl_expr(&child_str)
181    }
182
183    fn shape(&self) -> Result<Option<Shape>, BackendError> {
184        self.child.shape()
185    }
186
187    fn is_contiguous_and_same_shape(&self, out_shape: &[usize]) -> bool {
188        self.child.is_contiguous_and_same_shape(out_shape)
189    }
190}
191
192impl<Op: UnaryOpTag<T> + Send, Child: CpuExprNode<T, B>, T: Scalar, B: CpuBackend> CpuExprNode<T, B>
193    for UnaryExpr<Op, Child>
194{
195    unsafe fn eval_cpu(&self, coords: &[usize]) -> T {
196        let val = self.child.eval_cpu(coords);
197        Op::apply(val)
198    }
199
200    unsafe fn eval_cpu_flat(&self, idx: usize) -> T {
201        let val = self.child.eval_cpu_flat(idx);
202        Op::apply(val)
203    }
204}
205
206#[derive(Clone, Copy)]
207/// A binary operation node in the fused expression DAG.
208pub struct BinaryExpr<Op: BinaryOpTag, Left, Right> {
209    /// The operation tag.
210    pub op: Op,
211    /// The left-hand sub-expression.
212    pub left: Left,
213    /// The right-hand sub-expression.
214    pub right: Right,
215}
216
217impl<
218        Op: BinaryOpTag + Send,
219        Left: ExprNode<T, B>,
220        Right: ExprNode<T, B>,
221        T: Scalar,
222        B: ComputeBackend,
223    > ExprNode<T, B> for BinaryExpr<Op, Left, Right>
224{
225    fn collect_inputs<'expression>(&'expression self, list: &mut Vec<&'expression Tensor<T, B>>) {
226        self.left.collect_inputs(list);
227        self.right.collect_inputs(list);
228    }
229
230    fn to_shader_expr(&self, input_map: &HashMap<*const Tensor<T, B>, usize>) -> String {
231        let left_str = self.left.to_shader_expr(input_map);
232        let right_str = self.right.to_shader_expr(input_map);
233        format!("(({}) {} ({}))", left_str, Op::WGSL_SYMBOL, right_str)
234    }
235
236    fn shape(&self) -> Result<Option<Shape>, BackendError> {
237        let left_shape = self.left.shape()?;
238        let right_shape = self.right.shape()?;
239        match (left_shape, right_shape) {
240            (Some(l), Some(r)) => {
241                let out = broadcast_shapes(&l, &r).ok_or_else(|| {
242                    BackendError::IncompatibleBroadcast {
243                        operation: "fused expression",
244                        from: l.to_vec(),
245                        to: r.to_vec(),
246                    }
247                })?;
248                Ok(Some(out))
249            }
250            (Some(l), None) => Ok(Some(l)),
251            (None, Some(r)) => Ok(Some(r)),
252            (None, None) => Ok(None),
253        }
254    }
255
256    fn is_contiguous_and_same_shape(&self, out_shape: &[usize]) -> bool {
257        self.left.is_contiguous_and_same_shape(out_shape)
258            && self.right.is_contiguous_and_same_shape(out_shape)
259    }
260}
261
262impl<
263        Op: BinaryOpTag + Send,
264        Left: CpuExprNode<T, B>,
265        Right: CpuExprNode<T, B>,
266        T: Scalar,
267        B: CpuBackend,
268    > CpuExprNode<T, B> for BinaryExpr<Op, Left, Right>
269{
270    unsafe fn eval_cpu(&self, coords: &[usize]) -> T {
271        let left_val = self.left.eval_cpu(coords);
272        let right_val = self.right.eval_cpu(coords);
273        Op::apply(left_val, right_val)
274    }
275
276    unsafe fn eval_cpu_flat(&self, idx: usize) -> T {
277        let left_val = self.left.eval_cpu_flat(idx);
278        let right_val = self.right.eval_cpu_flat(idx);
279        Op::apply(left_val, right_val)
280    }
281}
282
283#[derive(Clone, Copy)]
284/// A wrapper around an expression node, providing operator overloading and builder methods.
285pub struct Expr<E>(pub E);
286
287impl<E: ExprNode<T, B>, T: Scalar, B: ComputeBackend> ExprNode<T, B> for Expr<E> {
288    #[inline(always)]
289    fn collect_inputs<'expression>(&'expression self, list: &mut Vec<&'expression Tensor<T, B>>) {
290        self.0.collect_inputs(list);
291    }
292
293    #[inline(always)]
294    fn to_shader_expr(&self, input_map: &HashMap<*const Tensor<T, B>, usize>) -> String {
295        self.0.to_shader_expr(input_map)
296    }
297
298    #[inline(always)]
299    fn shape(&self) -> Result<Option<Shape>, BackendError> {
300        self.0.shape()
301    }
302
303    #[inline(always)]
304    fn is_contiguous_and_same_shape(&self, out_shape: &[usize]) -> bool {
305        self.0.is_contiguous_and_same_shape(out_shape)
306    }
307}
308
309impl<E: CpuExprNode<T, B>, T: Scalar, B: CpuBackend> CpuExprNode<T, B> for Expr<E> {
310    #[inline(always)]
311    unsafe fn eval_cpu(&self, coords: &[usize]) -> T {
312        self.0.eval_cpu(coords)
313    }
314
315    #[inline(always)]
316    unsafe fn eval_cpu_flat(&self, idx: usize) -> T {
317        self.0.eval_cpu_flat(idx)
318    }
319}
320
321/// Extension trait that converts a [`Tensor`] into a fused expression leaf.
322pub trait TensorExprExt<T: Scalar, B: ComputeBackend> {
323    /// Create a fused expression leaf referencing this tensor.
324    fn expr(&self) -> Expr<TensorRef<'_, T, B>>;
325}
326
327impl<T: Scalar, B: ComputeBackend> TensorExprExt<T, B> for Tensor<T, B> {
328    #[inline(always)]
329    fn expr(&self) -> Expr<TensorRef<'_, T, B>> {
330        Expr(TensorRef(self))
331    }
332}
333
334/// Create a fused expression scalar constant.
335#[inline(always)]
336pub fn scalar<T: Scalar, B: ComputeBackend>(val: T) -> Expr<ScalarVal<T>> {
337    Expr(ScalarVal(val))
338}