Struct VmdSelectKConfig 

#[non_exhaustive]
pub struct VmdSelectKConfig {
    pub k_range: RangeInclusive<usize>,
    pub improvement_threshold: f64,
    pub boundary_fidelity: f64,
    pub base_config: VMDConfig,
}

Configuration for vmd_select_k.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

k_range: RangeInclusive<usize>

Range of K values to sweep (inclusive). Default 1..=10.

The lower bound must be ≥ 1 and must include K = 1 to make K = start + 1 selectable: the second-derivative elbow detector needs three consecutive residual points and can only flag the middle one, so K = start itself is never returned. Including K = 1 (residual = signal energy, a known baseline) means a two-tone signal can still pick K = 2 from the first window [1, 2, 3].

improvement_threshold: f64

Second-derivative elbow threshold used by the main detector. Define Δ_K = E[K-1] − E[K] as the residual-energy drop gained by going from K-1 modes to K. The sweep returns the smallest K for which Δ_{K+1} / Δ_K < improvement_threshold — adding another mode shrinks the next drop to a small fraction of the previous one. Simple “next drop < threshold” rules don’t recover the right K here: after the true elbow, residuals keep falling by ~20–30 % per added mode (each new mode picks up a sliver of leakage / mode-split) and a fractional criterion never trips.

Default 0.01 (1 %). Lowering it makes the detector demand sharper elbows before declaring K; raising it makes it more eager. Separate from boundary_fidelity because the elbow measures diminishing returns (ratio) while the boundary check measures reconstruction fidelity (absolute).

boundary_fidelity: f64

Absolute residual threshold for the K = start boundary check. If E[start] ≤ boundary_fidelity (normalized residual energy ‖x − Σ u_k‖² / ‖x‖²), the sweep recommends K = start directly without consulting the ratio detector. This pre-check exists because the ratio detector uses windows(3) and physically cannot return start; without it, true single-mode inputs are over-decomposed.

Default 0.05 (5 %). Set this higher than improvement_threshold because the default τ = 0 (constraint-dropped) base config produces non-trivial reconstruction residuals — a clean single-tone near Nyquist (e.g. cos(2π·0.45t)) sits at ~1 % residual, and noisy or band-limited inputs go higher. Empirical positioning of the 5 % default:

• Single tone (low freq) at K=1: residual ≪ 1 % → trips ✓
• Single tone near Nyquist at K=1: residual ≈ 1 % → trips ✓
• Two-tone at K=1: residual ≈ 50 % → does not trip ✓
• Three-tone (paper §3.4) at K=2: residual ≈ 7.9 % → does not trip ✓
• Multi-tone broadband at K=2: residual ≥ 50 % → does not trip ✓

Lower it only if you want to reject anything but near-perfect single-mode fits. Raise it if your signals are noisier and you want to accept K = start more eagerly.

base_config: VMDConfig

Base VMDConfig used for each sweep point; num_modes is overridden per iteration.

Must keep VMDConfig::tau at 0.0: vmd_select_k uses reconstruction residual as the selection metric, and positive dual-ascent τ drives that residual toward zero even when K is too small.

Implementations

impl VmdSelectKConfig

pub fn with_k_range(self, range: RangeInclusive<usize>) -> Self

Override the K sweep range.

pub fn with_improvement_threshold(self, t: f64) -> Self

Override the elbow threshold.

pub fn with_boundary_fidelity(self, t: f64) -> Self

Override the boundary-fidelity threshold.

pub fn with_base_config(self, base: VMDConfig) -> Self

Override the base VMD config.

Trait Implementations

impl Clone for VmdSelectKConfig

fn clone(&self) -> VmdSelectKConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for VmdSelectKConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for VmdSelectKConfig

fn default() -> Self

Returns the “default value” for a type.