Expand description
FFT extension operations for tenferro.
This crate is an out-of-tree ExtensionOp package with an explicit
FftBackend capability. tenferro_cpu::CpuEngine implements the
capability through RustFFT. With the cuda feature,
tenferro_gpu::cuda::CudaEngine executes the
supported F32/F64/C32/C64 operations through dynamically loaded cuFFT
without implicit transfers or CPU fallback. The vendor call synchronizes at
the cuFFT FFI boundary; subsequent CUDA postprocessing and explicit download
remain stream-managed. Backend choice remains explicit.
Every operation is declared once in the operation registry (#2552) and offered on three layers with the same spellings:
| Layer | Trait | Receiver | Spellings |
|---|---|---|---|
| concrete | FftOps | anything that implements AsView | x.fft(exec), x.fft_with(&opts, exec) |
| traced | TracedFftOps | TracedTensor | t.fft(), t.fft_with(&opts) |
eager (autodiff) | EagerFftOps | EagerSession | sess.fft(&x), sess.fft_with(&x, &opts) |
The operations are fft, ifft, rfft, irfft (FftOptions: n,
axis, norm) and fftn, ifftn, rfftn, irfftn (FftnOptions:
shape, axes, norm). Two exceptions keep their own shape: the
consuming eager transforms sess.fft_in_place(x, &opts) /
sess.ifft_in_place(x, &opts) (E01) and the plan-cache owner
FftExecutor (executor.fft_with(&x, &opts, exec), E02). The generated
page docs/spec/generated/api-ops.md lists layout handling, errors and
omissions per operation.
§Cargo features
| Feature | Enables |
|---|---|
autodiff | The eager layer (EagerFftOps) and AD rules. Adds the tenferro-ad dependency. |
cuda | CUDA execution through tenferro-gpu. |
For transforms without AD, use FftOps on concrete tensors; it needs no
autodiff.
§N-dimensional transforms
fftn, ifftn, rfftn and irfftn transform every axis in
FftnOptions::axes (empty selects them as NumPy does). One declared
axis is the ordinary one-axis transform: it runs the same single backend
call, so fftn over [axis] equals fft along axis.
The normalization of FftNorm is applied once to the whole transform, not
once per axis: the transform over axes with P = prod(shape over axes) is
scaled by 1 / P in the direction that Backward/Forward selects, and by
1 / sqrt(P) on both sides for Ortho. That is also the composition of the
one-axis transforms, whose per-axis factors multiply to the same single
factor.
With the cuda feature, each axis is one cufftPlanMany transform of that
one-dimensional length, run over the resident tensor; an n-dimensional
request therefore uses one cuFFT plan per axis and never transfers the
intermediate spectra. A single multi-dimensional cuFFT plan is not used yet.
§Examples
Traced: record, compile, run.
use num_complex::Complex64;
use tenferro_cpu::CpuEngine;
use tenferro_fft::TracedFftOps;
use tenferro_runtime::{ExecutionEngine, GraphCompiler, Runtime, TraceContext};
let trace = TraceContext::new();
let x = trace.from_vec_col_major(
vec![4],
vec![
Complex64::new(1.0, 0.0),
Complex64::new(2.0, 0.0),
Complex64::new(3.0, 0.0),
Complex64::new(4.0, 0.0),
],
)?;
let y = x.fft()?;
let program = GraphCompiler::new().compile(&y)?;
let mut engine = CpuEngine::serial();
let engine_id = tenferro_cpu::runtime_engine_id()?;
let mut builder = Runtime::builder();
builder.register_engine(tenferro_cpu::runtime_engine_registration(&engine)?)?;
builder.install_extension_module(tenferro_fft::extension_module::<CpuEngine>(engine_id)?)?;
let runtime = builder.build()?;
let prepared = runtime.prepare(&program, &[], &[engine.target()])?;
let out = {
let mut engines: [&mut dyn ExecutionEngine; 1] = [&mut engine];
runtime.run(&mut engines, &prepared, &[])?.pop().ok_or("no output")?
}
.into_tensor(&mut engine)?;
assert_eq!(out.shape(), &[4]);
assert_eq!(out.as_slice::<Complex64>()?[0], Complex64::new(10.0, 0.0));Concrete, with options:
use num_complex::Complex64;
use tenferro_cpu::CpuEngine;
use tenferro_fft::{FftNorm, FftOps, FftOptions};
use tenferro_tensor::Tensor;
let x = Tensor::from_vec_col_major(vec![4], vec![1.0_f64, 2.0, 3.0, 4.0])?;
let mut engine = CpuEngine::serial();
let out = x.fft(&mut engine)?;
assert_eq!(out.as_slice::<Complex64>()?[0], Complex64::new(10.0, 0.0));
let ortho = x.fft_with(&FftOptions::default().norm(FftNorm::Ortho), &mut engine)?;
assert_eq!(ortho.as_slice::<Complex64>()?[0], Complex64::new(5.0, 0.0));Modules§
- prelude
- The FFT grammar traits, options and common transform types (#2552).
Structs§
- FftExecution
Cache - Execution-cache state supplied to an
FftBackend. - FftExecutor
- Reusable concrete FFT executor with an explicitly owned backend-neutral cache.
- FftOptions
- Options of the one-axis transforms
fft,ifft,rfftandirfft. - FftPlan
Cache - Bounded, caller-owned typed cache for backend FFT plans and workspaces.
- FftPlan
Spec - Validated, backend-neutral description of one FFT request over one or more axes.
- Fftn
Options - Options of the N-dimensional transforms
fftn,ifftn,rfftnandirfftn.
Enums§
- FftNorm
- FFT normalization convention.
- FftOperation
- One-dimensional FFT operation requested from an
FftBackend.
Constants§
- DEFAULT_
FFT_ PLAN_ CACHE_ CAPACITY - Default number of typed entries retained by a caller-owned
FftPlanCache. - FFT_
EXTENSION_ FAMILY_ ID - Extension family id used by the tenferro FFT extension.
- FFT_
PLAN_ CACHE_ NAME - Runtime cache namespace used for private RustFFT plans.
Traits§
- FftBackend
- Explicit backend capability required by concrete and traced FFT execution.
- FftOps
- FFTs on anything that implements
AsView: owned and borrowed tensors, typed tensors and strided views. Results areTensors for erased inputs and typed tensors of the transform’s dtype for typed inputs. Every operation takes the options last-but-one and the engine last. - FftRepr
- How an FFT result is returned for an input representation.
- FftScalar
- A scalar an FFT accepts:
f32,f64,Complex32orComplex64. - Traced
FftOps - FFTs on traced tensors: each call records one FFT node and returns its traced result; execution happens when the graph is prepared and run.
Functions§
- extension_
module - Build this extension module for one runtime engine.
- fft_
plan_ cache_ selector - Select the private CPU RustFFT plan entries in an extension runtime cache.