Skip to main content

Crate tenferro_fft

Crate tenferro_fft 

Source
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:

LayerTraitReceiverSpellings
concreteFftOpsanything that implements AsViewx.fft(exec), x.fft_with(&opts, exec)
tracedTracedFftOpsTracedTensort.fft(), t.fft_with(&opts)
eager (autodiff)EagerFftOpsEagerSessionsess.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

FeatureEnables
autodiffThe eager layer (EagerFftOps) and AD rules. Adds the tenferro-ad dependency.
cudaCUDA 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§

FftExecutionCache
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, rfft and irfft.
FftPlanCache
Bounded, caller-owned typed cache for backend FFT plans and workspaces.
FftPlanSpec
Validated, backend-neutral description of one FFT request over one or more axes.
FftnOptions
Options of the N-dimensional transforms fftn, ifftn, rfftn and irfftn.

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 are Tensors 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, Complex32 or Complex64.
TracedFftOps
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.