Module fft 

FftActor — wraps [cudarc::cufft::CudaFft] with an LRU cache of plans keyed by shape + transform kind + dtype + batch.

cuFFT’s plan creation can take milliseconds; the cache amortizes that across many transforms of the same shape.

Phase 1 surface

Phase 1 of the cuFFT slice expands the actor from the F2 sketch (1D R2C/C2R/C2C f32 + 2D R2C f32) to:

• full 1D / 2D / 3D transform ranks,
• f32 (R2C / C2R / C2C) and f64 (D2Z / Z2D / Z2Z),
• a true cufftPlanMany-style batched plan builder (FftPlanMany) — arbitrary (rank, dims, in_embed, in_stride, in_dist, out_embed, out_stride, out_dist, batch),
• an optional callback hook (FftCallbackKind) plumbed through cufftXtSetCallback (defined in crate::sys::cufft). PTX/cubin provisioning of the device-side callback is deferred to the caller; this layer just stores/forwards the function pointer.

Message API: Option C hybrid

Per Phase 0.2 the canonical typed API runs through [FftMsg::Exec(Box<dyn FftDispatch>)]. Each typed FftRequest<T> carries the dtype-aware GpuRef<T> payload and erases at the enum boundary, so FftActor::Msg stays a single non-generic enum (one mailbox per actor) while the public surface is dtype-typed.

The legacy F2 variants (Forward1dR2C, Inverse1dC2R, Exec1dC2C, Forward2dR2C) are kept under #[deprecated] aliases so existing examples / external callers compile.

Inverse normalization: cuFFT does NOT normalize inverse transforms by 1/N — caller’s responsibility (typically folded into a downstream kernel).

Structs

FftActor

FftPlan

Opaque handle to a cuFFT plan (already materialized through the LRU cache). Callers obtain one via FftActor::ensure_plan or by caching the PlanKey returned from FftPlanMany::key.

FftPlanMany

Builder for advanced batched plans. Mirrors cufftPlanMany’s argument list: arbitrary rank (1, 2, or 3), per-dim sizes, optional in/out embed dims with strides and per-batch distances.

FftRequest

Typed cuFFT request — the canonical Phase-1 entry point.

PlanKey

Plan-cache key. Captures everything cuFFT cares about for both the simple cufftPlan{1,2,3}d constructors and the advanced cufftPlanMany builder. dims[i] == 0 for i >= rank (unused dimensions are zeroed for hashability).

Enums

FftCallbackKind

Optional callback hook attached to a plan. cuFFT’s load callback is invoked while reading inputs; the store callback is invoked while writing outputs. The kind field tells cuFFT which signal the device-resident callback expects.

FftDirection

Direction of a complex transform. Mirrors cudarc’s [cudarc::cufft::FftDirection] but lives in our module so callers can use atomr_accel_cuda::FftDirection.

FftKind

Transform kind. Covers the six cuFFT type codes the v0.19 cudarc safe surface exposes.

FftMsg