Modal-Decomposition

A unified library of modal decomposition methods — 15 classical and modern signal-decomposition algorithms behind one consistent API.

There are many methods of modal decomposition, but there is no library that covers them all with a single, coherent interface. Modal-Decomposition integrates the most commonly used decomposition algorithms into one package: every method shares the same class contract, the same return type, and the same validation / seeding / memory conventions, so switching between algorithms (or benchmarking them against each other) is a one-line change.

Methods

Install

pip install Modal-Decomposition

Or install from source:

git clone https://github.com/a-raining-day/Modal-Decomposition.git
cd Modal-Decomposition
pip install -r requirements.txt      # pinned build/dev environment
pip install -e .                     # editable install (compiles the FHT kernel)

The published platform wheels (Windows / macOS / Linux) ship the optional Cython-compiled FHT acceleration kernel _fht_native (C source from the Smithsonian am project, see Acknowledgement); it is used automatically when present and the library falls back to the pure NumPy implementation otherwise, so it runs in any environment. To compile the kernel manually inside a source tree:

python setup.py build_ext --inplace   # repository root

Requires Python >= 3.10.

Dependencies

Please install EMD-signal, not PyEMD (the latter is an unrelated older package).

Optional extras (not required at runtime): [dev] (pytest, black) and [plot] (matplotlib). numba may be installed to activate the optional "numba" backend of Utils.Peaks / SVMD; everything degrades gracefully without it.

Quick Start

import numpy as np
from Modal_Decomposition import Function as f

fs = 1000
t = np.linspace(0, 1, 1000, endpoint=False)
S = np.sin(2 * np.pi * 37 * t) + 0.5 * np.sin(2 * np.pi * 180 * t)

IMFs, Res, Info = f.EMD(S)          # returns a DecompositionResult tuple

API — two entrances

All entrances live in Modal_Decomposition/__init__.py, exposed as two read-only namespaces plus a small set of global helpers:

• Class — decomposer classes. Construct with parameters, then call .decompose(S, T=None) (also available as __call__):

  from Modal_Decomposition import Class
  
  r = Class.VMD(alpha=3000, K=4).decompose(S)
  

• Function — function facades, strictly equivalent to the class form (Function.X(S, T=None, **params) = Class.X(**params).decompose(S, T)):

  r = f.LMD(S)          # r is a DecompositionResult, not a tuple
  

• Global helpers — set_seed(seed) / get_seed(), set_absolute_limit(bytes) / set_memmap_ratio(ratio) (see Memory policy).

Return contract

Every method returns a DecompositionResult (also unpackable as a 3-tuple IMFs, Res, info):

Plus helpers: .n_imfs, .shape and .reconstruct() (sum(IMFs) + Res).

r = f.CEEMDAN(S, trials=30, seed=0)
print(r.n_imfs, r.reconstruct().shape)
print(r.config)                 # effective parameter snapshot

Random seed

Methods that use randomness accept a local seed parameter. A process-level global seed overrides every local seed (with a UserWarning) — call Modal_Decomposition.set_seed(n) once at the start of a script to make all downstream runs reproducible.

Time axis

T is optional; when omitted an index axis is used. Pass a non-uniformly sampled axis when the method needs physical frequencies (e.g. fs-related parameters); duplicate or descending axes are validated (descending axes are reordered with a warning).

Memory policy for very large signals

Large-input support is built into the input layer (Utils.Check_Time_and_Signal): inputs above the policy threshold are served from disk-backed np.memmap working copies instead of being materialized in RAM, so a machine can process signals far larger than its physical memory.

• set_memmap_ratio(ratio) — memmap when the projected usage reaches ratio (default 0.6) of the remaining available memory;
• set_absolute_limit(n_bytes) — memmap above a fixed byte limit (default 2 GiB).

The two strategies are mutually exclusive; the latest call wins. Monotonicity checks and chunked utilities (Utils.Chunk) follow the same policy.

Repository layout

src/Modal_Decomposition/
├── __init__.py      Class / Function namespaces + global API
├── <METHOD>.py      1 Config dataclass + 1 Decomposer per method
├── EMD_new.py       experimental native (PyEMD-free) EMD engine
├── _Registry.py     class registry (registration at import time)
├── Base/            Decomposer ABC, DecompositionResult, Config,
│                    import Cache, metadata tables, size constants
└── Utils/           Check / Chunk / Peaks / Spline / Envelope / Hilbert /
                     Monotonicity / Memory / Seed (+ _Hilbert FHT backends)
tests/               pytest suite + benchmarking harnesses (comparison/,
                     ssa/, test_memory/) against PyEMD and PySDKit

Changelog

0.2.0

• Unified utility layer (Utils.Chunk / Peaks / Check / Cache / Memory / Spline / Envelope) with documented conventions and speed reports under docs/.
• Memory-bounded processing for very large signals: policy-driven memmap input layer, adaptive chunking, dtype-preserving pipelines.
• Optional C-accelerated FHT/Hilbert kernel (_fht_native, compiled wheels for Windows / macOS / Linux, cp310–cp313) with automatic pure-NumPy fallback; CI verifies native-vs-pure numerical identity.
• EMD_new: experimental self-implemented EMD engine (prototype of the PyEMD-free roadmap).
• Dependency cleanup: removed unused packages (calorine, tqdm and stale pinned entries); unified result config snapshots and seed handling.

Acknowledgement

The FHT Hilbert backend under src/Modal_Decomposition/Utils/_Hilbert/_C/_fht/ contains third-party C code:

• Originally written by the Smithsonian Astrophysical Observatory, Submillimeter Receiver Laboratory (Scott Paine), as part of the am atmospheric model: https://www.cfa.harvard.edu/~spaine/am/
• Acquired from waddafunk/Smithsonians_Discrete_Hilbert_Fourier_Hartley_Transforms (Jacopo Piccirillo, 13/10/2020), where the transform routines were isolated for standalone C/C++ use.

Smithsonian am license notice:

This computer program containing an atmospheric propagation model for the submillimeter band is a work of the United States and may be used freely, with attribution and credit to the Smithsonian Astrophysical Observatory. The program is intended for educational, scholarly or research purposes. In connection with any commercial use of the program, the user should disclose clearly and conspicuously all of the information contained in the first sentence of this notice.

Hilbert-transform phase convention: the SAO implementation shifts the phase by +90° — not −90° as in MATLAB/SciPy. To obtain the MATLAB-compatible result, multiply the component orthogonal to the input by exp(j·π) = −1, i.e. multiply the imaginary part of the analytic signal by −1 for a real input (matlab_phase=True in Modal_Decomposition.Utils._Hilbert._fht).

License

Apache-2.0 — see LICENSE.

URL

Project homepage / repository: https://github.com/a-raining-day/Modal-Decomposition