Module vmd 

Variational Mode Decomposition (VMD).

VMD (Dragomiretskiy & Zosso, IEEE Trans. Signal Processing, 2014) decomposes a real-valued signal into K band-limited intrinsic modes by solving a constrained variational problem via ADMM:

min_{u_k, ω_k}  Σ_k ‖ ∂_t[ (δ(t) + j/πt) * u_k(t) ] · e^(−j·ω_k·t) ‖²₂
subject to     Σ_k u_k = x

Unlike EMD’s recursive sifting (greedy, non-orthogonal, scale-mixing-prone), VMD jointly fits K modes whose Fourier energy is concentrated around adaptively-found center frequencies ω_k. Modes are band-limited by construction, so VMD avoids EMD’s mode-mixing artifact when its K is set correctly.

When to use VMD over EMD / CEEMDAN

• When K is known a priori from domain knowledge (or you can sweep via vmd_select_k).
• When you need explicit, tunable noise robustness via α (AlphaSpec).
• When mode mixing has been a problem with EMD on your signal class.

When K is unknown and adaptive: CEEMDAN is a better default.

α and signal length

VMD’s bandwidth penalty is parameterized in normalized frequency [0, 0.5], so the paper’s default α = 2000 does not need rescaling when N changes — 1/√(2α) stays constant in normalized units. A tempting “scale α with N” rule actually makes recovery worse: the normalized bandwidth shrinks at larger N and low-frequency modes drift off the true value. We default to AlphaSpec::PaperDefault (α = 2000); use AlphaSpec::Fixed to pin any other value.

Reconstruction fidelity and τ

With the default VMDConfig::tau = 0 the equality constraint Σ_k u_k = x is dropped (the dual ascent term is skipped) and VMDResult::reconstruct is approximate — ~1e-4 relative energy on the paper’s three-tone signal. Set τ > 0 to engage dual ascent and drive Σ u_k → x toward exact equality (τ = 0.5 reaches < 1e-6 in the integration tests). Keep τ = 0 when you only need mode shapes and center frequencies; set τ > 0 when round-trip fidelity matters.

Diagnosing over-specified K

VMD’s behavior with too-large K is not “excess modes collapse to zero energy” — that is only sometimes true and depends on α, τ, and the initialization. More commonly the algorithm splits a true mode across two adjacent ω_k. VMDResult::redundancy returns per-pair metrics (center-frequency separation, energy ratio, time-domain correlation) that detect both modes of failure; threshold them per asset class rather than relying on a global energy-collapse assertion.

References

• Dragomiretskiy, K., & Zosso, D. (2014). Variational mode decomposition. IEEE Trans. Signal Processing, 62(3), 531–544. https://doi.org/10.1109/TSP.2013.2288675 — algorithm pseudocode is in §3.2; the reference signal used by vmd’s integration tests is §3.4.
• Wang, Y., Markert, R., Xiang, J., & Zheng, W. (2015). Research on variational mode decomposition and its application in detecting rub-impact fault of the rotor system. Mechanical Systems and Signal Processing, 60–61, 243–251. https://doi.org/10.1016/j.ymssp.2015.02.020 — center-frequency-separation diagnostic for over-K detection.
• Reference MATLAB implementation: https://math.montana.edu/dzosso/code/.

Structs

VMDConfig

Configuration for vmd.

VMDResult

Result of a vmd decomposition.

VmdRedundancy

Per-pair redundancy metrics for diagnosing over-specified K.

VmdSelectKConfig

Configuration for vmd_select_k.

VmdSelectKResult

Result of vmd_select_k.

Enums

AlphaSpec

Bandwidth-constraint specification for VMDConfig::alpha.

ModeInitialization

Initial placement of the center frequencies ω_k for the ADMM iteration.

Functions

vmd

Decompose signal into config.num_modes band-limited modes via VMD.

vmd_select_k

Sweep K over config.k_range and return the recommended K. Two detectors run in order: the K = start boundary check fires if E[start] ≤ [boundary_fidelity](VmdSelectKConfig::boundary_fidelity); otherwise the ratio-of-drops elbow detector fires at the smallest K ≥ start + 1 where Δ_{K+1}/Δ_K < [improvement_threshold](VmdSelectKConfig::improvement_threshold). Falls back to *k_range.end() when neither detector trips.