ContinuousWavelet

ferro_wave::transform::cwt

Trait ContinuousWavelet 

pub trait ContinuousWavelet: Send + Sync {
    // Required methods
    fn wavelet_function(&self, t: f64, scale: f64) -> Complex<f64>;
    fn center_frequency(&self) -> f64;
    fn bandwidth(&self) -> f64;
    fn is_complex(&self) -> bool;

    // Provided methods
    fn supports_frequency_domain(&self) -> bool { ... }
    fn wavelet_function_includes_l2_norm(&self) -> bool { ... }
    fn admissibility_constant(&self) -> f64 { ... }
    fn sst_inversion_constant(&self) -> f64 { ... }
    fn wavelet_fft(
        &self,
        _buffer: &mut [FftComplex<f64>],
        _scale: f64,
        _fft_size: usize,
    ) { ... }
    fn recommended_scales(
        &self,
        signal_length: usize,
        sampling_freq: f64,
    ) -> Vec<f64> { ... }
}
Expand description

Trait for continuous wavelets used in CWT.

Requires Send + Sync to enable parallel scale processing via Rayon.

§Implementing Custom Wavelets

For optimal performance, implement supports_frequency_domain() and wavelet_fft() if your wavelet has a known analytic Fourier transform. See Morlet for an example.

Important: When implementing wavelet_fft(), you MUST write to ALL elements of the buffer. The buffer may contain uninitialized or stale data from previous calls.

Required Methods§

fn wavelet_function(&self, t: f64, scale: f64) -> Complex<f64>

Get the wavelet function value at position t for scale a

fn center_frequency(&self) -> f64

Get the center frequency of the wavelet

fn bandwidth(&self) -> f64

Get the bandwidth parameter

fn is_complex(&self) -> bool

Check if the wavelet is complex-valued

Provided Methods§

fn supports_frequency_domain(&self) -> bool

Check if this wavelet supports direct frequency-domain computation

When true, wavelet_fft can be called instead of computing the time-domain wavelet and taking its FFT, which is significantly faster.

fn wavelet_function_includes_l2_norm(&self) -> bool

Whether wavelet_function already includes the CWT L2 amplitude factor 1/√a in its return value.

The CWT formula is (1/√a) · ψ((t − b)/a). Different wavelet implementations historically split this in different places: some include the 1/√a directly inside wavelet_function (and return (1/√a) · ψ(η)), others return the unnormalized ψ(η) and rely on the caller to apply the L2 factor. As of 2.0.0, both the direct cwt path and the cwt_fft time-domain fallback honor this flag: when false, they apply an extra 1/√scale multiplication; when true, they assume the wavelet’s return value already includes it. icwt also honors the flag identically.

The frequency-domain cwt_fft path (wavelet_fft-based, when supports_frequency_domain() == true) does not depend on this flag — wavelet_fft is expected to write the L2-normalized wavelet’s FFT directly.

Default false for backwards compatibility with the historical convention used by Morlet. As of 2.0.0, MexicanHat and all complex wavelets (ComplexMorlet, ComplexMexicanHat, ComplexPaul) override to true because their wavelet_functions include a /scale.sqrt() in the normalization constant.

fn admissibility_constant(&self) -> f64

Wavelet admissibility constant C_ψ = ∫₀^∞ |Ψ̂(ω)|²/ω dω, used by icwt to normalize the reconstruction.

For the Calderón reconstruction formula x(t) = (1/C_ψ) · Re[ Σ_a Σ_b W(a,b) · ψ_{a,b}(t) · Δa/a² ], the constant is wavelet- and parameter-specific (e.g. Morlet’s depends on ω₀, Paul’s on m).

All built-in wavelets (crate::transform::Morlet, crate::transform::MexicanHat, crate::transform::complex_wavelets::ComplexMorlet, crate::transform::complex_wavelets::ComplexPaul, crate::transform::complex_wavelets::ComplexMexicanHat) override with analytical formulas verified to recover input amplitude within ~5% on a single-tone cosine — see tests/transforms/cwt_reference.rs::test_icwt_amplitude_matches_input_for_admissible_wavelets.

Default 2π is used for custom ContinuousWavelet impls that don’t override. These produce shape-correct recons whose absolute amplitudes are off by a wavelet-dependent constant — override to enable amplitude-correct icwt.

fn sst_inversion_constant(&self) -> f64

Synchrosqueezing inversion constant R_ψ = ∫₀^∞ Ψ̂*(ω) dω / ω, used by crate::transform::sswt_extract_component to recover an EMD-like component from an SST ridge.

R_ψ ≠ C_ψ. The CWT admissibility constant C_ψ = ∫|Ψ̂|²/ω dω (used by icwt) and the SST inversion constant R_ψ = ∫Ψ̂*/ω dω are different integrals over Ψ̂(ω)/ω. They coincide only for special wavelets; for Morlet (ω₀=6) they differ by ~1.5x — see Daubechies-Lu-Wu 2011 §3.

The default returns Self::admissibility_constant so custom ContinuousWavelet impls keep working with SST, but the resulting ridge-reconstructed amplitudes will be biased by the ratio C_ψ/R_ψ. Override for amplitude-correct SST inversion.

fn wavelet_fft( &self, _buffer: &mut [FftComplex<f64>], _scale: f64, _fft_size: usize, )

Compute the wavelet directly in frequency domain (if supported)

This computes Ψ̂(ω/s) * √s for the given scale, where Ψ̂ is the Fourier transform of the mother wavelet. This avoids the expensive time-domain generation + FFT step.

§Arguments
  • buffer - Output buffer to fill with frequency-domain wavelet
  • scale - Scale parameter
  • fft_size - Size of the FFT (determines frequency resolution)

fn recommended_scales( &self, signal_length: usize, sampling_freq: f64, ) -> Vec<f64>

Get recommended scale range for a given signal length and sampling frequency

Implementors§