[srivarra]

NOT READY FOR REVIEW, JUST EXPERIMENTING HERE.

Summary

This adds an opt-in reusable 3D phase reconstruction operator for large GPU-resident volumes. Create waveorder.reconstruction.PhaseReconstruction once, then call operator(volume, out=buffer) for repeated reconstructions. Existing model, xarray, and CLI interfaces remain unchanged.

The original path allocates large transfer-function arrays and rebuilds the inverse filter for each solve. The new path builds a compact inverse filter in 32-plane Z slabs and 4096-frequency batches, reducing intermediate allocations while keeping one global Fourier-domain reconstruction. Fixed Python-scalar settings reuse the filter across calls. The Torch path supports autograd and rebuilds preparation for tensor-valued parameters. The optional native CUDA path is Linux-only inference. It shares Torch optical preparation, then uses fused kernels with reusable cuFFT plans and workspace.

Changes

• waveorder/reconstruction/_phase.py defines the public API, parameter lifetime, out= handling, and Torch or native dispatch.
• waveorder/reconstruction/_torch.py and waveorder/optics.py implement bounded preparation, compact inverse filtering, and real FFT reconstruction.
• waveorder/reconstruction/_cuda.py, waveorder/csrc/reconstruction.cpp, and waveorder/csrc/reconstruction.cu provide the optional loader, cuFFT plans, fused kernels, and reusable workspace.
• tests/test_reconstruction.py covers the operator and numerical behavior. docs/guide/reconstruction-guide.md documents usage. pyproject.toml and uv.lock add the optional native build dependency.

Benchmarks

Compared with the original implementation, these are arithmetic means over per-size comparisons for the two matching ZYX volumes of shape $2372 \times 46 \times 256$ and $2372 \times 93 \times 512$, on an NVIDIA H100 80GB. Inputs were GPU-resident, with disk I/O and transfers excluded.

Method	Scope	Speedup	Peak allocation reduction
Optimized Torch	Setup + reconstruction	1.98x	91.6%
Native CUDA	Setup + reconstruction	1.83x	93.2%
Optimized Torch	Setup reused	2.46x	52.8%
Native CUDA	Setup reused	2.56x	70.9%

Both optimized paths passed all-voxel original-reference checks on the two matching sizes. Larger optimized cases remain reference-unverified because the original method ran out of vram. The gains include preparation, caching, and execution changes.

Performance comparison

Full scaling results

---

This is very much WIP, and I haven't quite figured out how I want these 2 paths glued into WaveOrder. and how we can reuse components to create accelerated versions of all the major reconstruction workflows.