HMath.Fourier¶
Module index · Numerical conventions
Description
CPU reference Fourier transforms. Forward exponent is negative; inverse exponent is positive and divided by N. ND data are contiguous row-major with the last axis fastest. Plans are immutable, reusable and cache N roots; no global cache or thread-local state is retained. Scalar transforms accept 1..65536 samples (direct quadratic transforms at most 4096).
DCT/DST I--IV use orthonormal matrices, so inverse means transpose. Definitions follow https://fftw.org/fftw3_doc/What-FFTW-Really-Computes.html with explicit endpoint weights added for orthogonality. Algorithms are reference CPU paths, not hardware FFTW bindings.
On this page¶
| API | Purpose |
|---|---|
| Direction | Transform exponent convention; Inverse additionally divides by sample count. |
| Forward | Declaration and type contract below. |
| Inverse | Declaration and type contract below. |
| FFTAlgorithm | Explicit reference factorization, or Automatic mixed-radix with Bluestein for larger prime factors. |
| Automatic | Declaration and type contract below. |
| Direct | Declaration and type contract below. |
| Radix2 | Declaration and type contract below. |
| Radix4 | Declaration and type contract below. |
| MixedRadix | Declaration and type contract below. |
| SplitRadix | Declaration and type contract below. |
| Bluestein | Declaration and type contract below. |
| Rader | Declaration and type contract below. |
| FFTPlan | Opaque immutable plan with cached unit-circle roots and a fixed input length. |
| planFFT | Create a reusable plan after checking length, prime or radix requirements. |
| executeFFT | Apply a plan to exactly its declared number of finite complex samples; reject nonfinite intermediate results. |
| fft | Automatic forward/inverse FFT and bounded direct forward DFT, respectively. |
| ifft | Automatic forward/inverse FFT and bounded direct forward DFT, respectively. |
| dft | Automatic forward/inverse FFT and bounded direct forward DFT, respectively. |
| fftND | Transform all axes. |
| fftBatch | Apply one immutable plan independently to each batch; any inconsistent row length fails. |
| realFFT | Full complex spectrum; the real-spectrum inverse checks Hermitian symmetry. |
| inverseRealFFT | Inverse of a full real spectrum; require conjugate symmetry within the supplied absolute tolerance. |
| fftInPlace | The caller exclusively owns a valid, aligned, writable buffer of exactly N Complex Double elements for the duration of this call. |
| frequencies | Signed DFT frequency bins in cycles per coordinate unit, given sample count and positive sample spacing. |
| fftShift | Rotate zero frequency to/from the center; these operations are exact inverses for odd and even lengths. |
| ifftShift | Rotate zero frequency to/from the center; these operations are exact inverses for odd and even lengths. |
| TransformType | Orthonormal cosine/sine basis type I, II, III or IV. |
| TypeI | Declaration and type contract below. |
| TypeII | Declaration and type contract below. |
| TypeIII | Declaration and type contract below. |
| TypeIV | Declaration and type contract below. |
| dct | Apply an orthonormal cosine/sine basis or its transpose; type-I cosine needs at least two samples. |
| idct | Apply an orthonormal cosine/sine basis or its transpose; type-I cosine needs at least two samples. |
| dst | Apply an orthonormal cosine/sine basis or its transpose; type-I cosine needs at least two samples. |
| idst | Apply an orthonormal cosine/sine basis or its transpose; type-I cosine needs at least two samples. |
| hartley | Unnormalized real Hartley transform, Re(DFT)-Im(DFT); applying twice multiplies by N. |
| STFT | Frames include zero padding on both sides by one full window, so windows with zero endpoints reconstruct boundary samples. |
| stft | Windowed analysis with an explicit hop in samples, padded endpoint frames, and a 1048576-coefficient storage budget. |
| stftFrames | Read the full complex spectra in increasing frame-start order. |
| istft | Overlap-add inverse with squared-window normalization; reject every uncovered original sample. |
| magnitudeSpectrum | Elementwise complex magnitude, principal phase in radians, and squared magnitude; no PSD normalization. |
| phaseSpectrum | Elementwise complex magnitude, principal phase in radians, and squared magnitude; no PSD normalization. |
| powerSpectrum | Elementwise complex magnitude, principal phase in radians, and squared magnitude; no PSD normalization. |
| periodogram | Two-sided PSD in amplitude-squared/Hz: squared FFT magnitude divided by sample rate and window squared energy. |
| welch | Average full-window two-sided periodograms at the supplied hop; discard the incomplete final frame. |
| crossSpectrum | Two-sided conjugate(X)*Y cross PSD using the same sample-rate/window-energy normalization as periodogram. |
| spectrogram | Squared-magnitude STFT frames, retaining the explicit padding/frame order of stft. |
| cepstrum | Real cepstrum from inverse FFT of log(max(floor,abs(FFT(x)))); floor must be positive. |
| analyticSignal | Real signal plus imaginary Hilbert transform, formed by doubling positive-frequency bins and retaining DC/Nyquist. |
| hilbert | Imaginary part of the analytic signal; periodic finite-record boundary convention. |
| chirpZ | Direct bounded Z-transform along z_k=a*w^(-k); nonzero a,w required. |
| goertzel | One arbitrary-frequency DFT value from a second-order real resonator; omega is radians/sample. |
| fftConvolve | Full zero-padded complex linear convolution; padded transform length is limited to 65536. |
| fftCorrelate | Correlation lags -(length b-1)..length a-1, conjugating b. |
Documentation
Direction
Transform exponent convention; Inverse additionally divides by sample count.
Instances
FFTAlgorithm
data FFTAlgorithm Source #
Explicit reference factorization, or Automatic mixed-radix with Bluestein for larger prime factors.
Constructors
| Automatic | |
| Direct | |
| Radix2 | |
| Radix4 | |
| MixedRadix | |
| SplitRadix | |
| Bluestein | |
| Rader |
Instances
| Show FFTAlgorithm Source # | |
Defined in HMath.Fourier Methods showsPrec :: Int -> FFTAlgorithm -> ShowS # show :: FFTAlgorithm -> String # showList :: [FFTAlgorithm] -> ShowS # | |
| Eq FFTAlgorithm Source # | |
Defined in HMath.Fourier | |
FFTPlan
Opaque immutable plan with cached unit-circle roots and a fixed input length.
planFFT
planFFT :: Direction -> FFTAlgorithm -> Int -> Either MathError FFTPlan Source #
Create a reusable plan after checking length, prime or radix requirements. No input data or external buffers are retained.
executeFFT
executeFFT :: FFTPlan -> [Complex Double] -> Either MathError [Complex Double] Source #
Apply a plan to exactly its declared number of finite complex samples; reject nonfinite intermediate results.
fft
fft :: [Complex Double] -> Either MathError [Complex Double] Source #
Automatic forward/inverse FFT and bounded direct forward DFT, respectively.
ifft
ifft :: [Complex Double] -> Either MathError [Complex Double] Source #
Automatic forward/inverse FFT and bounded direct forward DFT, respectively.
dft
dft :: [Complex Double] -> Either MathError [Complex Double] Source #
Automatic forward/inverse FFT and bounded direct forward DFT, respectively.
fftND
fftND :: Direction -> [Int] -> [Complex Double] -> Either MathError [Complex Double] Source #
Transform all axes. Product budget is 65536; last axis varies fastest.
fftBatch
fftBatch :: FFTPlan -> [[Complex Double]] -> Either MathError [[Complex Double]] Source #
Apply one immutable plan independently to each batch; any inconsistent row length fails.
realFFT
realFFT :: [Double] -> Either MathError [Complex Double] Source #
Full complex spectrum; the real-spectrum inverse checks Hermitian symmetry.
inverseRealFFT
inverseRealFFT :: Double -> [Complex Double] -> Either MathError [Double] Source #
Inverse of a full real spectrum; require conjugate symmetry within the supplied absolute tolerance.
fftInPlace
fftInPlace :: FFTPlan -> Ptr (Complex Double) -> Int -> IO (Either MathError ()) Source #
The caller exclusively owns a valid, aligned, writable buffer of exactly N Complex Double elements for the duration of this call. No pointers escape; the entire input is copied and checked before a successful write-back.
frequencies
frequencies :: Int -> Double -> Either MathError [Double] Source #
Signed DFT frequency bins in cycles per coordinate unit, given sample count and positive sample spacing.
fftShift
fftShift :: [a] -> [a] Source #
Rotate zero frequency to/from the center; these operations are exact inverses for odd and even lengths.
ifftShift
ifftShift :: [a] -> [a] Source #
Rotate zero frequency to/from the center; these operations are exact inverses for odd and even lengths.
TransformType
data TransformType Source #
Orthonormal cosine/sine basis type I, II, III or IV.
Instances
| Show TransformType Source # | |
Defined in HMath.Fourier Methods showsPrec :: Int -> TransformType -> ShowS # show :: TransformType -> String # showList :: [TransformType] -> ShowS # | |
| Eq TransformType Source # | |
Defined in HMath.Fourier Methods (==) :: TransformType -> TransformType -> Bool # (/=) :: TransformType -> TransformType -> Bool # | |
dct
dct :: TransformType -> [Double] -> Either MathError [Double] Source #
Apply an orthonormal cosine/sine basis or its transpose; type-I cosine needs at least two samples.
idct
idct :: TransformType -> [Double] -> Either MathError [Double] Source #
Apply an orthonormal cosine/sine basis or its transpose; type-I cosine needs at least two samples.
dst
dst :: TransformType -> [Double] -> Either MathError [Double] Source #
Apply an orthonormal cosine/sine basis or its transpose; type-I cosine needs at least two samples.
idst
idst :: TransformType -> [Double] -> Either MathError [Double] Source #
Apply an orthonormal cosine/sine basis or its transpose; type-I cosine needs at least two samples.
hartley
hartley :: [Double] -> Either MathError [Double] Source #
Unnormalized real Hartley transform, Re(DFT)-Im(DFT); applying twice multiplies by N.
STFT
Frames include zero padding on both sides by one full window, so windows with zero endpoints reconstruct boundary samples. Inverse divides by summed window squares and rejects uncovered samples. No implicit amplitude scaling.
stft
stft :: [Double] -> Int -> [Double] -> Either MathError STFT Source #
Windowed analysis with an explicit hop in samples, padded endpoint frames, and a 1048576-coefficient storage budget.
stftFrames
stftFrames :: STFT -> [[Complex Double]] Source #
Read the full complex spectra in increasing frame-start order.
istft
istft :: STFT -> Either MathError [Double] Source #
Overlap-add inverse with squared-window normalization; reject every uncovered original sample.
magnitudeSpectrum
magnitudeSpectrum :: [Complex Double] -> [Double] Source #
Elementwise complex magnitude, principal phase in radians, and squared magnitude; no PSD normalization.
phaseSpectrum
phaseSpectrum :: [Complex Double] -> [Double] Source #
Elementwise complex magnitude, principal phase in radians, and squared magnitude; no PSD normalization.
powerSpectrum
powerSpectrum :: [Complex Double] -> [Double] Source #
Elementwise complex magnitude, principal phase in radians, and squared magnitude; no PSD normalization.
periodogram
periodogram :: Double -> [Double] -> [Double] -> Either MathError [Double] Source #
Two-sided PSD in amplitude-squared/Hz: squared FFT magnitude divided by sample rate and window squared energy.
welch
welch :: Double -> [Double] -> Int -> [Double] -> Either MathError [Double] Source #
Average full-window two-sided periodograms at the supplied hop; discard the incomplete final frame.
crossSpectrum
crossSpectrum :: Double -> [Double] -> [Double] -> [Double] -> Either MathError [Complex Double] Source #
Two-sided conjugate(X)*Y cross PSD using the same sample-rate/window-energy normalization as periodogram.
spectrogram
spectrogram :: [Double] -> Int -> [Double] -> Either MathError [[Double]] Source #
Squared-magnitude STFT frames, retaining the explicit padding/frame order of stft.
cepstrum
cepstrum :: Double -> [Double] -> Either MathError [Double] Source #
Real cepstrum from inverse FFT of log(max(floor,abs(FFT(x)))); floor must be positive.
analyticSignal
analyticSignal :: [Double] -> Either MathError [Complex Double] Source #
Real signal plus imaginary Hilbert transform, formed by doubling positive-frequency bins and retaining DC/Nyquist.
hilbert
hilbert :: [Double] -> Either MathError [Double] Source #
Imaginary part of the analytic signal; periodic finite-record boundary convention.
chirpZ
chirpZ :: Int -> Complex Double -> Complex Double -> [Complex Double] -> Either MathError [Complex Double] Source #
Direct bounded Z-transform along z_k=a*w^(-k); nonzero a,w required.
goertzel
goertzel :: Double -> [Double] -> Either MathError (Complex Double) Source #
One arbitrary-frequency DFT value from a second-order real resonator; omega is radians/sample.