[lkdvos]

This replaces the per-tree loop in planartrace!, which used the fusion tree internals through ad-hoc single-pair FusionTreeBlocks, with the same precompute/execute split as the index manipulations (treetransformers.jl / indexmanipulations.jl).

Fusion trees

• planar_trace(src::Union{FusionTreePair, FusionTreeBlock}, p, q) follows the conventions of transpose/repartition: unique-fusion pairs map to dst => coeff, blocks to dst => U with a dense recoupling matrix. It repartitions all legs to the outgoing side, traces the splitting trees into the full block of remaining trees, and transposes that block.
• The traced sectors must be dual to each other; otherwise this throws. Callers filter with trace_sectors_match instead, which in the generic case avoids computing repartitions/transposes of blocks that vanish anyway.
• FusionTreeBlocks now hash their uncoupled sectors and duality flags, since the ad-hoc single-pair blocks are gone.

Precompute: TraceTransformer

• Cached via @cached treetracer(A, Vdst, Vsrc, p, q), keyed on the destination storagetype like the other transformers.
• Stores (U, inds_dst, inds_src) entries, grouped by destination block: several source blocks (one per traced sector) contribute to the same destination. Every destination subblock appears in exactly one entry, so threaded tasks never write the same subblock, and subblocks without contributions get an entry that only scales by β.

Execute: trace_transform_kernel!

• Mirrors add_transform_kernel!, including the per-task workspaces.
• A single destination subblock (always the case for unique fusion) is traced into directly, with β on the first contribution.
• Otherwise: trace each source into a buffer column (applying the output permutation while tracing), recouple with one matmul (_recouple!), and add into the destinations.

GPU kernel

• GPU tensors pack the TraceTransformer into isbits descriptors (cached per device storagetype, like the braid/transpose transformers) and trace in two stages:

  1. partial traces: one thread per (chunk, remaining entry) of every source subblock sums at most max(256, √ntraced) traced entries (one summed stride per traced pair) into a scratch buffer from allocator, so full reductions and traces with few remaining entries are still spread over many threads;
  2. recoupling: one thread per destination element sums the partials of every source, weighted by the recoupling coefficients, so the traced entries are summed once per source rather than once per destination tree.

• Other tensor types (e.g. adjoints) are converted to TensorMaps first. Tracing subblock views with cuTENSOR, as the previous implementation did for all GPU tensors, fails with CUDA error: misaligned address for data at unaligned offsets (reproduced for Float64 fℤ₂ ⊠ SU₂ data).

• _linear_index is now an explicit loop, since sum(()) (a full trace) does not compile for GPUs.

• Tested on an RTX A6000 against the CPU results for the same sectors and traces, in Float64 and ComplexF64, including adjoint sources, β = 0 with NaN-filled output, and full traces split into several chunks. test/cuda/planar.jl gains a symmetric planartrace test for every space in the spacelist and for large traces; cuda/planar and cuda/tensors pass locally.

• GPU timings for one-stage (one thread per destination element) vs. two-stage kernel, for degeneracies 40 (fℤ₂), 30 (Fibonacci), 12/10/8 (fℤ₂ ⊠ SU₂):

  	partial (3 legs left)	1 leg left	full reduction
  fℤ₂	0.28 → 0.31 ms	4.0 → 0.25 ms	4.0 → 0.19 ms
  Fibonacci	0.16 → 0.20 ms	2.8 → 0.21 ms	2.8 → 0.18 ms
  fℤ₂ ⊠ SU₂	0.042 → 0.036 ms	0.81 → 0.12 ms	0.81 → 0.12 ms

Testing

• Compared against the previous implementation for fℤ₂, Fibonacci, fℤ₂ ⊠ SU₂ and Fibonacci ⊠ fℤ₂, with partial, full and nested traces, adjoint sources, and the tree pair / block coefficients.
• tensors/planar, tensors/contractions and symmetries/doubletree pass locally; the planar trace test in doubletree.jl now uses the block method for generic fusion.
• Rough timings for a 5-leg trace (warm cache): fℤ₂ 0.39 → 0.26 ms, Fibonacci 0.32 → 0.058 ms, fℤ₂ ⊠ SU₂ 1.9 → 0.036 ms.

Not covered: JET was not run locally (it passes in CI); the GPU kernels were only tested on CUDA, not AMDGPU.

🤖 Generated with Claude Code