ops: embedding/reshape/transpose/split-merge-heads fwd+bwd

Phase T5 structural ops on top of the T4 set, needed to assemble the
tiny transformer:
- embedding: gather rows by I32 ids (CUDA kernel) / scatter-add backward
  (atomic, so repeated ids accumulate). csrc/ops/model.cu + ffi.
- reshape: contiguous metadata-only view (Tensor::reshape), no kernel.
- transpose_3d01: [a,b,c]->[b,a,c] for the multi-head layout (kernel).
- autograd nodes: embedding/reshape/transpose_3d01/transpose_2d, plus
  split_heads (->Vec<Var>) / merge_heads for per-head attention.
- tape: Var::zero_grad + set_value so a hand-written GD step can update
  params and clear grads between steps.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

crates/xtrain-autodiff/src/ops.rs

@@ -146,6 +146,126 @@ pub fn softmax(x: &Var) -> Var {
     )
 }
 
+/// Token embedding gather: `out[s,:] = table[ids[s], :]`. `table`:[vocab,dim]
+/// (a learnable [`Var`]), `ids`:[seq] I32 (a constant index, not a `Var`).
+/// Backward scatter-adds the upstream grad back into the table rows.
+pub fn embedding(table: &Var, ids: &Tensor) -> Var {
+    let out = table.value().embedding(ids);
+    let vocab = table.value().shape()[0];
+    let ids = ids.clone();
+    Var::from_op(
+        out,
+        vec![table.clone()],
+        Box::new(move |dout, parents| {
+            let dtable = Tensor::embedding_backward(dout, &ids, vocab);
+            Var::push_grad(&parents[0], dtable);
+        }),
+    )
+}
+
+/// Reshape (contiguous, metadata-only). Backward reshapes the grad back to the
+/// input shape. Used for the multi-head layout swap `[seq, h*hd] <-> [seq, h, hd]`.
+pub fn reshape(x: &Var, new_shape: &[usize]) -> Var {
+    let in_shape: Vec<usize> = x.value().shape().to_vec();
+    let out = x.value().reshape(new_shape);
+    Var::from_op(
+        out,
+        vec![x.clone()],
+        Box::new(move |d, parents| {
+            Var::push_grad(&parents[0], d.reshape(&in_shape));
+        }),
+    )
+}
+
+/// 3D axis-(0,1) transpose `[a,b,c] -> [b,a,c]`. Self-inverse structure: the
+/// backward is the same transpose applied to the grad.
+pub fn transpose_3d01(x: &Var) -> Var {
+    let out = x.value().transpose_3d01();
+    Var::from_op(
+        out,
+        vec![x.clone()],
+        Box::new(|d, parents| {
+            Var::push_grad(&parents[0], d.transpose_3d01());
+        }),
+    )
+}
+
+/// 2D transpose `[r,c] -> [c,r]` as an autograd node (backward transposes the
+/// grad back). Used for `Kᵀ` in attention scores.
+pub fn transpose_2d(x: &Var) -> Var {
+    let out = x.value().transpose_2d();
+    Var::from_op(
+        out,
+        vec![x.clone()],
+        Box::new(|d, parents| {
+            Var::push_grad(&parents[0], d.transpose_2d());
+        }),
+    )
+}
+
+/// Split a `[heads, seq, head_dim]` tensor into one `[seq, head_dim]` [`Var`] per
+/// head. Each head block is contiguous in this layout, so the forward copies the
+/// head block into its own contiguous tensor; the backward scatters each head's
+/// grad back into a zero `[heads, seq, head_dim]` grad (the engine then SUMs the
+/// `heads` contributions on the shared parent — fan-out).
+pub fn split_heads(x: &Var) -> Vec<Var> {
+    let v = x.value();
+    assert_eq!(v.ndim(), 3, "split_heads requires [heads,seq,head_dim]");
+    let (heads, seq, hd) = (v.shape()[0], v.shape()[1], v.shape()[2]);
+    let dev = v.device();
+    let flat_host = v.to_device(xtrain_tensor::Device::Cpu);
+    let flat = flat_host.as_slice::<f32>();
+    (0..heads)
+        .map(|h| {
+            let base = h * seq * hd;
+            let block = Tensor::from_slice(&flat[base..base + seq * hd], &[seq, hd]).to_device(dev);
+            Var::from_op(
+                block,
+                vec![x.clone()],
+                Box::new(move |d, parents| {
+                    let mut host = vec![0.0f32; heads * seq * hd];
+                    let dvals = d.to_device(xtrain_tensor::Device::Cpu);
+                    let base = h * seq * hd;
+                    host[base..base + seq * hd].copy_from_slice(dvals.as_slice::<f32>());
+                    let g = Tensor::from_slice(&host, &[heads, seq, hd]).to_device(dev);
+                    Var::push_grad(&parents[0], g);
+                }),
+            )
+        })
+        .collect()
+}
+
+/// Inverse of [`split_heads`]: stack per-head `[seq, head_dim]` outputs into a
+/// `[heads, seq, head_dim]` tensor. Backward hands each head its own slice of the
+/// grad.
+pub fn merge_heads(heads_v: &[Var]) -> Var {
+    let heads = heads_v.len();
+    let v0 = heads_v[0].value();
+    let (seq, hd) = (v0.shape()[0], v0.shape()[1]);
+    let dev = v0.device();
+    let mut host = vec![0.0f32; heads * seq * hd];
+    for (h, hv) in heads_v.iter().enumerate() {
+        let block = hv.value().to_device(xtrain_tensor::Device::Cpu);
+        let base = h * seq * hd;
+        host[base..base + seq * hd].copy_from_slice(block.as_slice::<f32>());
+    }
+    let out = Tensor::from_slice(&host, &[heads, seq, hd]).to_device(dev);
+    Var::from_op(
+        out,
+        heads_v.to_vec(),
+        Box::new(move |d, parents| {
+            let dhost = d.to_device(xtrain_tensor::Device::Cpu);
+            let dflat = dhost.as_slice::<f32>();
+            for (h, parent) in parents.iter().enumerate() {
+                let base = h * seq * hd;
+                let g =
+                    Tensor::from_slice(&dflat[base..base + seq * hd], &[seq, hd]).to_device(dev);
+                Var::push_grad(parent, g);
+            }
+        }),
+    )
+}
+
 /// Cross-entropy mean loss over logits `x:[rows,cols]` with one I32 target per
 /// row. Returns a scalar [`Var`]. Backward: `dx = (probs - onehot)/rows`,
 /// scaled by the upstream scalar grad.

crates/xtrain-autodiff/src/tape.rs

@@ -68,6 +68,19 @@ impl Var {
         self.0.borrow().grad.clone()
     }
 
+    /// Clear the accumulated gradient. Call on every parameter between training
+    /// steps so the next `backward` accumulates from zero (grads SUM otherwise).
+    pub fn zero_grad(&self) {
+        self.0.borrow_mut().grad = None;
+    }
+
+    /// Overwrite this node's value tensor in place. Used by the optimizer to
+    /// apply a parameter update (`p ← p − lr·grad`) while keeping the leaf's
+    /// identity stable across steps.
+    pub fn set_value(&self, value: Tensor) {
+        self.0.borrow_mut().value = value;
+    }
+
     /// Pointer identity, used to dedup nodes during the topological sort.
     fn id(&self) -> *const RefCell<VarNode> {
         Rc::as_ptr(&self.0)