Modal-Decomposition 0.2.0__tar.gz → 0.2.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. {Modal-Decomposition-0.2.0/src/Modal_Decomposition.egg-info → Modal-Decomposition-0.2.1}/PKG-INFO +41 -4
  2. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/README.md +273 -236
  3. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/pyproject.toml +1 -1
  4. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Base/Cache.py +2 -2
  5. Modal-Decomposition-0.2.1/src/Modal_Decomposition/Base/ConstDefine.py +51 -0
  6. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Base/__init__.py +6 -3
  7. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/EEMD.py +2 -2
  8. Modal-Decomposition-0.2.1/src/Modal_Decomposition/EMD.py +417 -0
  9. Modal-Decomposition-0.2.1/src/Modal_Decomposition/EWT_new.py +110 -0
  10. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/ICEEMDAN.py +4 -2
  11. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/LMD.py +47 -58
  12. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/RPSEMD.py +4 -2
  13. Modal-Decomposition-0.2.1/src/Modal_Decomposition/SSA.py +450 -0
  14. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/SVMD.py +2 -2
  15. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Utils/Check.py +48 -26
  16. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Utils/Envelope.py +33 -11
  17. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Utils/Hilbert.py +6 -10
  18. Modal-Decomposition-0.2.1/src/Modal_Decomposition/Utils/Mirror.py +144 -0
  19. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Utils/Peaks.py +1 -1
  20. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Utils/Spline.py +71 -129
  21. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Utils/_Hilbert/__init__.py +9 -8
  22. Modal-Decomposition-0.2.1/src/Modal_Decomposition/Utils/_Hilbert/_scipy_backend.py +8 -0
  23. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Utils/__init__.py +17 -0
  24. Modal-Decomposition-0.2.1/src/Modal_Decomposition/VMD_new.py +108 -0
  25. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/_SVMD_numba.py +2 -2
  26. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/__init__.py +1 -1
  27. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1/src/Modal_Decomposition.egg-info}/PKG-INFO +41 -4
  28. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition.egg-info/SOURCES.txt +4 -3
  29. Modal-Decomposition-0.2.0/tests/test_emd_new.py → Modal-Decomposition-0.2.1/tests/test_emd.py +268 -204
  30. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/tests/test_envelope.py +3 -1
  31. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/tests/test_spline.py +24 -30
  32. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/tests/test_utils.py +26 -0
  33. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Base/ConstDefine.py +0 -19
  34. Modal-Decomposition-0.2.0/src/Modal_Decomposition/EMD.py +0 -102
  35. Modal-Decomposition-0.2.0/src/Modal_Decomposition/EMD_new.py +0 -267
  36. Modal-Decomposition-0.2.0/src/Modal_Decomposition/SSA.py +0 -238
  37. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/_Hilbert/_scipy_backend.py +0 -6
  38. Modal-Decomposition-0.2.0/tests/test_path.py +0 -6
  39. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/LICENSE +0 -0
  40. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/MANIFEST.in +0 -0
  41. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/setup.cfg +0 -0
  42. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/setup.py +0 -0
  43. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Base/ClassDefine.py +0 -0
  44. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Base/ConfigDefine.py +0 -0
  45. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Base/PathDefine.py +0 -0
  46. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Base/TextDefine.py +0 -0
  47. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/CEEFD.py +0 -0
  48. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/CEEMD.py +0 -0
  49. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/CEEMDAN.py +0 -0
  50. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/EFD.py +0 -0
  51. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/EWT.py +0 -0
  52. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Error/RealizationError.py +0 -0
  53. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Error/__init__.py +0 -0
  54. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/FMD.py +0 -0
  55. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/MEMD.py +0 -0
  56. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Utils/Chunk.py +0 -0
  57. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Utils/Memory.py +0 -0
  58. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Utils/Monotonicity.py +0 -0
  59. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Utils/Seed.py +0 -0
  60. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Utils/_Hilbert/_C/_fht/am_sysdep.c +0 -0
  61. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Utils/_Hilbert/_C/_fht/am_sysdep.h +0 -0
  62. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Utils/_Hilbert/_C/_fht/math_const.h +0 -0
  63. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Utils/_Hilbert/_C/_fht/transforms.c +0 -0
  64. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Utils/_Hilbert/_C/_fht/transforms.h +0 -0
  65. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Utils/_Hilbert/_fft.py +0 -0
  66. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Utils/_Hilbert/_fht.py +0 -0
  67. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Utils/_Hilbert/_fht_native.pyx +0 -0
  68. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Utils/_Hilbert/_fir.py +0 -0
  69. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Utils/_Hilbert/_forth_order_wave.py +0 -0
  70. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Utils/_Hilbert/_kramers_kronig.py +0 -0
  71. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/Utils/_Hilbert/_wave.py +0 -0
  72. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/VMD.py +0 -0
  73. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition/_Registry.py +0 -0
  74. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition.egg-info/dependency_links.txt +0 -0
  75. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition.egg-info/requires.txt +0 -0
  76. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/src/Modal_Decomposition.egg-info/top_level.txt +0 -0
  77. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/tests/test_cache.py +0 -0
  78. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/tests/test_chunk.py +0 -0
  79. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/tests/test_contract.py +0 -0
  80. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/tests/test_facade.py +0 -0
  81. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/tests/test_fht.py +0 -0
  82. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/tests/test_fmd_lmd_refactor.py +0 -0
  83. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/tests/test_import.py +0 -0
  84. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/tests/test_montonic.py +0 -0
  85. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/tests/test_peaks.py +0 -0
  86. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/tests/test_reconstruction.py +0 -0
  87. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/tests/test_registry.py +0 -0
  88. {Modal-Decomposition-0.2.0 → Modal-Decomposition-0.2.1}/tests/test_seed.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: Modal-Decomposition
3
- Version: 0.2.0
3
+ Version: 0.2.1
4
4
  Summary: a package for modal decomposition
5
5
  Author-email: Mao_HaoChuan <2215269365@qq.com>
6
6
  License: Apache-2.0
@@ -199,18 +199,55 @@ checks and chunked utilities (`Utils.Chunk`) follow the same policy.
199
199
  src/Modal_Decomposition/
200
200
  ├── __init__.py Class / Function namespaces + global API
201
201
  ├── <METHOD>.py 1 Config dataclass + 1 Decomposer per method
202
- ├── EMD_new.py experimental native (PyEMD-free) EMD engine
202
+ ├── EMD.py native EMD engine (PyEMD-free; original EMD_new,
203
+ │ registered as the public "EMD")
203
204
  ├── _Registry.py class registry (registration at import time)
204
205
  ├── Base/ Decomposer ABC, DecompositionResult, Config,
205
206
  │ import Cache, metadata tables, size constants
206
- └── Utils/ Check / Chunk / Peaks / Spline / Envelope / Hilbert /
207
- Monotonicity / Memory / Seed (+ _Hilbert FHT backends)
207
+ └── Utils/ Check / Chunk / Peaks / Mirror / Spline / Envelope /
208
+ Hilbert / Monotonicity / Memory / Seed
209
+ (+ _Hilbert FHT backends)
208
210
  tests/ pytest suite + benchmarking harnesses (comparison/,
209
211
  ssa/, test_memory/) against PyEMD and PySDKit
210
212
  ```
211
213
 
212
214
  ## Changelog
213
215
 
216
+ ### 0.2.1
217
+
218
+ - `EMD` is now the native self-implemented sifting engine (ex-`EMD_new`,
219
+ registered as the public `EMD`; the former PyEMD wrapper was removed) —
220
+ faster than PyEMD at equal mode quality, cold start ~ms vs ~0.5 s
221
+ (`docs/EMD_vs_EMD_new_Performance_Report.md`).
222
+ - `EMD(faster=...)` two-branch stopping policy: `faster=False` (default,
223
+ quality branch) additionally requires the classic narrowband balance
224
+ `|zc - ext| <= 1` before accepting each IMF (clean signals cost nothing;
225
+ noisy / long signals trade speed for row-level purity comparable with
226
+ PyEMD); `faster=True` keeps the legacy fast branch (energy Cauchy SD
227
+ stops sifting). Full four-way comparison (MD-quality / MD-fast / PyEMD /
228
+ PySDKit) in `docs/EMD_faster_Branch_Comparison_Report.md`. Speed ratios
229
+ are always quoted same-process/same-script (median timing in the bench
230
+ scripts), never cross-day absolute timings.
231
+ - `EMD` defaults (CubicSpline envelope + `sd_thr=0.01` + `faster=False`)
232
+ chosen by the mode-level validation (`docs/EMD_Validation_and_Comparison_Report.md`)
233
+ and the mechanism/optimization analysis (`docs/EMD_Quality_Gap_and_Optimization.md`);
234
+ `spline_kind` accepts the canonical `Utils.Spline` kinds.
235
+ - Temporary memmap backing files are now cleaned up: the input-layer memmap
236
+ registry deletes its files at interpreter exit (`atexit`, handle closed
237
+ first — required on Windows), and `Utils.Chunk.exo_chunks` deletes its
238
+ files when each iteration ends; see
239
+ `docs/EMD_Large_Signal_Memory_Report.md` §5.
240
+ - Timing / quality / memory benchmarks re-run on the native engine and
241
+ reported under `docs/` (four new reports + `docs/EXPERIMENTS_INDEX.md`);
242
+ stale test files removed and legacy benchmark data archived under
243
+ `tests/comparison/results/_legacy_pyemd_wrapper/`.
244
+ - LMD defaults to the extrema (Spline) interpolation envelope; the analytic
245
+ Hilbert envelope stays as an explicit opt-in only. The Hilbert-vs-Spline
246
+ envelope concepts are separated again (`Utils.Envelope` restored as its own
247
+ module).
248
+ - New `Utils.Mirror` (endpoint mirror extension, EMD nbsym + LMD boundary
249
+ modes) shared by EMD / LMD / future consumers.
250
+
214
251
  ### 0.2.0
215
252
 
216
253
  - Unified utility layer (`Utils.Chunk` / `Peaks` / `Check` / `Cache` /
@@ -1,236 +1,273 @@
1
- # Modal-Decomposition
2
-
3
- > A unified library of modal decomposition methods — 15 classical and modern
4
- > signal-decomposition algorithms behind one consistent API.
5
-
6
- There are many methods of modal decomposition, but there is no library that
7
- covers them all with a single, coherent interface. **Modal-Decomposition**
8
- integrates the most commonly used decomposition algorithms into one package:
9
- every method shares the same class contract, the same return type, and the
10
- same validation / seeding / memory conventions, so switching between
11
- algorithms (or benchmarking them against each other) is a one-line change.
12
-
13
- ## Methods
14
-
15
- | Method | Description | Use | Reference (DOI) |
16
- |----------|--------------------------------------------------------------------------|----------------------------|-----------------|
17
- | CEEMDAN | Complete Ensemble Empirical Mode Decomposition with Adaptive Noise | `Function.CEEMDAN(S)` | [10.1109/ICASSP.2011.5947265](https://ieeexplore.ieee.org/abstract/document/5947265) |
18
- | CEEFD | Cyclic Envelop Empirical Fourier Decomposition | `Function.CEEFD(S)` | [10.3969/j.issn.1001-4551.2023.07.001](https://d.wanfangdata.com.cn/periodical/jdgc202307001) |
19
- | CEEMD | Complementary Ensemble Empirical Mode Decomposition | `Function.CEEMD(S)` | [10.1016/j.jhydrol.2020.124647](https://www.sciencedirect.com/science/article/abs/pii/S0022169420301074) |
20
- | EEMD | Ensemble Empirical Mode Decomposition | `Function.EEMD(S)` | [10.1142/S1793536909000047](https://www.semanticscholar.org/paper/Ensemble-Empirical-Mode-Decomposition%3A-a-Data-Wu-Huang/a97ee1d4a15c04160c323bd650e9cb9dff9dfced) |
21
- | EFD | Empirical Fourier Decomposition | `Function.EFD(S)` | [10.1016/j.ymssp.2021.108155](https://www.sciencedirect.com/science/article/abs/pii/S0888327021005355?via%3Dihub) |
22
- | EMD | Empirical Mode Decomposition | `Function.EMD(S)` | [10.1098/rspa.1998.0193](https://www.semanticscholar.org/paper/The-empirical-mode-decomposition-and-the-Hilbert-Huang-Shen/3842d81b0375dae8ae92734aa2a5d4aeed7a91d1) |
23
- | EWT | Empirical Wavelet Transform | `Function.EWT(S)` | [10.48550/arXiv.2304.06274](https://arxiv.org/abs/2304.06274) |
24
- | FMD | Filtered Mode Decomposition | `Function.FMD(S)` | [10.1109/TIE.2022.3156156](https://ieeexplore.ieee.org/document/9732251) |
25
- | ICEEMDAN | Improved Complete Ensemble Empirical Mode Decomposition with Adaptive Noise | `Function.ICEEMDAN(S)` | [10.1007/s10470-021-01901-3](https://link.springer.com/article/10.1007/s10470-021-01901-3#citeas) |
26
- | LMD | Local Mean Decomposition | `Function.LMD(S)` | [10.1098/rsif.2005.0058](https://royalsocietypublishing.org/doi/10.1098/rsif.2005.0058) |
27
- | MEMD | Multivariate Empirical Mode Decomposition | `Function.MEMD(S)` | [10.48550/arXiv.2206.00926](https://arxiv.org/abs/2206.00926) |
28
- | RPSEMD | Random Phase Sinusoidal Assisted Empirical Mode Decomposition | `Function.RPSEMD(S)` | [10.1109/LSP.2016.2537376](https://ieeexplore.ieee.org/document/7423702) |
29
- | SSA | Singular Spectrum Analysis | `Function.SSA(S)` | [10.1016/j.mex.2020.101015](https://www.sciencedirect.com/science/article/pii/S2215016120302351) |
30
- | SVMD | Successive Variational Mode Decomposition | `Function.SVMD(S)` | [10.1016/j.sigpro.2020.107610](https://www.sciencedirect.com/science/article/abs/pii/S0165168420301535) |
31
- | VMD | Variational Mode Decomposition | `Function.VMD(S)` | [10.1109/TSP.2013.2288675](https://ieeexplore.ieee.org/document/6655981) |
32
-
33
- ## Install
34
-
35
- ```shell
36
- pip install Modal-Decomposition
37
- ```
38
-
39
- Or install from source:
40
-
41
- ```shell
42
- git clone https://github.com/a-raining-day/Modal-Decomposition.git
43
- cd Modal-Decomposition
44
- pip install -r requirements.txt # pinned build/dev environment
45
- pip install -e . # editable install (compiles the FHT kernel)
46
- ```
47
-
48
- The published platform wheels (Windows / macOS / Linux) ship the optional
49
- Cython-compiled FHT acceleration kernel `_fht_native` (C source from the
50
- Smithsonian *am* project, see [Acknowledgement](#acknowledgement)); it is used
51
- automatically when present and the library falls back to the pure NumPy
52
- implementation otherwise, so it runs in any environment. To compile the
53
- kernel manually inside a source tree:
54
-
55
- ```shell
56
- python setup.py build_ext --inplace # repository root
57
- ```
58
-
59
- Requires **Python >= 3.10**.
60
-
61
- ### Dependencies
62
-
63
- | Package | Used by / for |
64
- |-------------|-----------------------------------------------------|
65
- | numpy | core arrays and vectorized kernels |
66
- | scipy | splines, envelope / Hilbert, filtering, peaks, FFT |
67
- | EMD-signal (PyEMD) | EMD, EEMD, CEEMDAN (and ensemble chains) |
68
- | ewtpy | EWT |
69
- | vmdpy | VMD |
70
- | psutil | available-memory reading for the memmap policy |
71
-
72
- > Please install `EMD-signal`, not `PyEMD` (the latter is an unrelated older package).
73
-
74
- Optional extras (not required at runtime): `[dev]` (pytest, black) and
75
- `[plot]` (matplotlib). `numba` may be installed to activate the optional
76
- `"numba"` backend of `Utils.Peaks` / `SVMD`; everything degrades gracefully
77
- without it.
78
-
79
- ## Quick Start
80
-
81
- ```python
82
- import numpy as np
83
- from Modal_Decomposition import Function as f
84
-
85
- fs = 1000
86
- t = np.linspace(0, 1, 1000, endpoint=False)
87
- S = np.sin(2 * np.pi * 37 * t) + 0.5 * np.sin(2 * np.pi * 180 * t)
88
-
89
- IMFs, Res, Info = f.EMD(S) # returns a DecompositionResult tuple
90
- ```
91
-
92
- ### API — two entrances
93
-
94
- All entrances live in `Modal_Decomposition/__init__.py`, exposed as two
95
- read-only namespaces plus a small set of global helpers:
96
-
97
- - **`Class`** — decomposer classes. Construct with parameters, then call
98
- `.decompose(S, T=None)` (also available as `__call__`):
99
-
100
- ```python
101
- from Modal_Decomposition import Class
102
-
103
- r = Class.VMD(alpha=3000, K=4).decompose(S)
104
- ```
105
-
106
- - **`Function`** — function facades, strictly equivalent to the class form
107
- (`Function.X(S, T=None, **params)` = `Class.X(**params).decompose(S, T)`):
108
-
109
- ```python
110
- r = f.LMD(S) # r is a DecompositionResult, not a tuple
111
- ```
112
-
113
- - **Global helpers** — `set_seed(seed)` / `get_seed()`,
114
- `set_absolute_limit(bytes)` / `set_memmap_ratio(ratio)` (see
115
- [Memory policy](#memory-policy-for-very-large-signals)).
116
-
117
- ### Return contract
118
-
119
- Every method returns a **`DecompositionResult`** (also unpackable as a
120
- 3-tuple `IMFs, Res, info`):
121
-
122
- | Field | Meaning |
123
- |----------|--------------------------------------------------------------------|
124
- | `.IMFs` | decomposed modes, shape `(K, N)` (univariate) or `(K, d, N)` (MEMD)|
125
- | `.Res` | residual, or `None` for methods without a residual concept (SSA, VMD) |
126
- | `.info` | method-specific diagnostics dict (e.g. FFT spectra, boundaries) |
127
- | `.config`| frozen dataclass snapshot of the *effective* parameters of this run |
128
-
129
- Plus helpers: `.n_imfs`, `.shape` and `.reconstruct()` (`sum(IMFs) + Res`).
130
-
131
- ```python
132
- r = f.CEEMDAN(S, trials=30, seed=0)
133
- print(r.n_imfs, r.reconstruct().shape)
134
- print(r.config) # effective parameter snapshot
135
- ```
136
-
137
- ### Random seed
138
-
139
- Methods that use randomness accept a local `seed` parameter. A process-level
140
- global seed overrides every local seed (with a `UserWarning`) — call
141
- `Modal_Decomposition.set_seed(n)` once at the start of a script to make all
142
- downstream runs reproducible.
143
-
144
- ### Time axis
145
-
146
- `T` is optional; when omitted an index axis is used. Pass a non-uniformly
147
- sampled axis when the method needs physical frequencies (e.g. `fs`-related
148
- parameters); duplicate or descending axes are validated (descending axes are
149
- reordered with a warning).
150
-
151
- ## Memory policy for very large signals
152
-
153
- Large-input support is built into the input layer
154
- (`Utils.Check_Time_and_Signal`): inputs above the policy threshold are served
155
- from disk-backed `np.memmap` working copies instead of being materialized in
156
- RAM, so a machine can process signals far larger than its physical memory.
157
-
158
- - `set_memmap_ratio(ratio)` — memmap when the projected usage reaches
159
- `ratio` (default 0.6) of the remaining available memory;
160
- - `set_absolute_limit(n_bytes)` — memmap above a fixed byte limit (default 2 GiB).
161
-
162
- The two strategies are mutually exclusive; the latest call wins. Monotonicity
163
- checks and chunked utilities (`Utils.Chunk`) follow the same policy.
164
-
165
- ## Repository layout
166
-
167
- ```
168
- src/Modal_Decomposition/
169
- ├── __init__.py Class / Function namespaces + global API
170
- ├── <METHOD>.py 1 Config dataclass + 1 Decomposer per method
171
- ├── EMD_new.py experimental native (PyEMD-free) EMD engine
172
- ├── _Registry.py class registry (registration at import time)
173
- ├── Base/ Decomposer ABC, DecompositionResult, Config,
174
- │ import Cache, metadata tables, size constants
175
- └── Utils/ Check / Chunk / Peaks / Spline / Envelope / Hilbert /
176
- Monotonicity / Memory / Seed (+ _Hilbert FHT backends)
177
- tests/ pytest suite + benchmarking harnesses (comparison/,
178
- ssa/, test_memory/) against PyEMD and PySDKit
179
- ```
180
-
181
- ## Changelog
182
-
183
- ### 0.2.0
184
-
185
- - Unified utility layer (`Utils.Chunk` / `Peaks` / `Check` / `Cache` /
186
- `Memory` / `Spline` / `Envelope`) with documented conventions and speed
187
- reports under `docs/`.
188
- - Memory-bounded processing for very large signals: policy-driven `memmap`
189
- input layer, adaptive chunking, dtype-preserving pipelines.
190
- - Optional C-accelerated FHT/Hilbert kernel (`_fht_native`, compiled wheels
191
- for Windows / macOS / Linux, cp310–cp313) with automatic pure-NumPy
192
- fallback; CI verifies native-vs-pure numerical identity.
193
- - `EMD_new`: experimental self-implemented EMD engine (prototype of the
194
- PyEMD-free roadmap).
195
- - Dependency cleanup: removed unused packages (`calorine`, `tqdm` and stale
196
- pinned entries); unified result `config` snapshots and seed handling.
197
-
198
- ## Acknowledgement
199
-
200
- The `FHT` Hilbert backend under
201
- `src/Modal_Decomposition/Utils/_Hilbert/_C/_fht/` contains **third-party C
202
- code**:
203
-
204
- - Originally written by the **Smithsonian Astrophysical Observatory**,
205
- Submillimeter Receiver Laboratory (Scott Paine), as part of the *am*
206
- atmospheric model: <https://www.cfa.harvard.edu/~spaine/am/>
207
- - Acquired from
208
- [waddafunk/Smithsonians_Discrete_Hilbert_Fourier_Hartley_Transforms](https://github.com/waddafunk/Smithsonians_Discrete_Hilbert_Fourier_Hartley_Transforms)
209
- (Jacopo Piccirillo, 13/10/2020), where the transform routines were isolated
210
- for standalone C/C++ use.
211
-
212
- Smithsonian *am* license notice:
213
-
214
- > This computer program containing an atmospheric propagation model for the
215
- > submillimeter band is a work of the United States and may be used freely,
216
- > with attribution and credit to the Smithsonian Astrophysical Observatory.
217
- > The program is intended for educational, scholarly or research purposes. In
218
- > connection with any commercial use of the program, the user should disclose
219
- > clearly and conspicuously all of the information contained in the first
220
- > sentence of this notice.
221
-
222
- **Hilbert-transform phase convention:** the SAO implementation shifts the
223
- phase by **+90°** — *not* **−90°** as in MATLAB/SciPy. To obtain the
224
- MATLAB-compatible result, multiply the component orthogonal to the input by
225
- `exp(j·π) = −1`, i.e. multiply the imaginary part of the analytic signal by
226
- −1 for a real input (`matlab_phase=True` in
227
- `Modal_Decomposition.Utils._Hilbert._fht`).
228
-
229
- ## License
230
-
231
- Apache-2.0 — see [LICENSE](LICENSE).
232
-
233
- ## URL
234
-
235
- Project homepage / repository:
236
- <https://github.com/a-raining-day/Modal-Decomposition>
1
+ # Modal-Decomposition
2
+
3
+ > A unified library of modal decomposition methods — 15 classical and modern
4
+ > signal-decomposition algorithms behind one consistent API.
5
+
6
+ There are many methods of modal decomposition, but there is no library that
7
+ covers them all with a single, coherent interface. **Modal-Decomposition**
8
+ integrates the most commonly used decomposition algorithms into one package:
9
+ every method shares the same class contract, the same return type, and the
10
+ same validation / seeding / memory conventions, so switching between
11
+ algorithms (or benchmarking them against each other) is a one-line change.
12
+
13
+ ## Methods
14
+
15
+ | Method | Description | Use | Reference (DOI) |
16
+ |----------|--------------------------------------------------------------------------|----------------------------|-----------------|
17
+ | CEEMDAN | Complete Ensemble Empirical Mode Decomposition with Adaptive Noise | `Function.CEEMDAN(S)` | [10.1109/ICASSP.2011.5947265](https://ieeexplore.ieee.org/abstract/document/5947265) |
18
+ | CEEFD | Cyclic Envelop Empirical Fourier Decomposition | `Function.CEEFD(S)` | [10.3969/j.issn.1001-4551.2023.07.001](https://d.wanfangdata.com.cn/periodical/jdgc202307001) |
19
+ | CEEMD | Complementary Ensemble Empirical Mode Decomposition | `Function.CEEMD(S)` | [10.1016/j.jhydrol.2020.124647](https://www.sciencedirect.com/science/article/abs/pii/S0022169420301074) |
20
+ | EEMD | Ensemble Empirical Mode Decomposition | `Function.EEMD(S)` | [10.1142/S1793536909000047](https://www.semanticscholar.org/paper/Ensemble-Empirical-Mode-Decomposition%3A-a-Data-Wu-Huang/a97ee1d4a15c04160c323bd650e9cb9dff9dfced) |
21
+ | EFD | Empirical Fourier Decomposition | `Function.EFD(S)` | [10.1016/j.ymssp.2021.108155](https://www.sciencedirect.com/science/article/abs/pii/S0888327021005355?via%3Dihub) |
22
+ | EMD | Empirical Mode Decomposition | `Function.EMD(S)` | [10.1098/rspa.1998.0193](https://www.semanticscholar.org/paper/The-empirical-mode-decomposition-and-the-Hilbert-Huang-Shen/3842d81b0375dae8ae92734aa2a5d4aeed7a91d1) |
23
+ | EWT | Empirical Wavelet Transform | `Function.EWT(S)` | [10.48550/arXiv.2304.06274](https://arxiv.org/abs/2304.06274) |
24
+ | FMD | Filtered Mode Decomposition | `Function.FMD(S)` | [10.1109/TIE.2022.3156156](https://ieeexplore.ieee.org/document/9732251) |
25
+ | ICEEMDAN | Improved Complete Ensemble Empirical Mode Decomposition with Adaptive Noise | `Function.ICEEMDAN(S)` | [10.1007/s10470-021-01901-3](https://link.springer.com/article/10.1007/s10470-021-01901-3#citeas) |
26
+ | LMD | Local Mean Decomposition | `Function.LMD(S)` | [10.1098/rsif.2005.0058](https://royalsocietypublishing.org/doi/10.1098/rsif.2005.0058) |
27
+ | MEMD | Multivariate Empirical Mode Decomposition | `Function.MEMD(S)` | [10.48550/arXiv.2206.00926](https://arxiv.org/abs/2206.00926) |
28
+ | RPSEMD | Random Phase Sinusoidal Assisted Empirical Mode Decomposition | `Function.RPSEMD(S)` | [10.1109/LSP.2016.2537376](https://ieeexplore.ieee.org/document/7423702) |
29
+ | SSA | Singular Spectrum Analysis | `Function.SSA(S)` | [10.1016/j.mex.2020.101015](https://www.sciencedirect.com/science/article/pii/S2215016120302351) |
30
+ | SVMD | Successive Variational Mode Decomposition | `Function.SVMD(S)` | [10.1016/j.sigpro.2020.107610](https://www.sciencedirect.com/science/article/abs/pii/S0165168420301535) |
31
+ | VMD | Variational Mode Decomposition | `Function.VMD(S)` | [10.1109/TSP.2013.2288675](https://ieeexplore.ieee.org/document/6655981) |
32
+
33
+ ## Install
34
+
35
+ ```shell
36
+ pip install Modal-Decomposition
37
+ ```
38
+
39
+ Or install from source:
40
+
41
+ ```shell
42
+ git clone https://github.com/a-raining-day/Modal-Decomposition.git
43
+ cd Modal-Decomposition
44
+ pip install -r requirements.txt # pinned build/dev environment
45
+ pip install -e . # editable install (compiles the FHT kernel)
46
+ ```
47
+
48
+ The published platform wheels (Windows / macOS / Linux) ship the optional
49
+ Cython-compiled FHT acceleration kernel `_fht_native` (C source from the
50
+ Smithsonian *am* project, see [Acknowledgement](#acknowledgement)); it is used
51
+ automatically when present and the library falls back to the pure NumPy
52
+ implementation otherwise, so it runs in any environment. To compile the
53
+ kernel manually inside a source tree:
54
+
55
+ ```shell
56
+ python setup.py build_ext --inplace # repository root
57
+ ```
58
+
59
+ Requires **Python >= 3.10**.
60
+
61
+ ### Dependencies
62
+
63
+ | Package | Used by / for |
64
+ |-------------|-----------------------------------------------------|
65
+ | numpy | core arrays and vectorized kernels |
66
+ | scipy | splines, envelope / Hilbert, filtering, peaks, FFT |
67
+ | EMD-signal (PyEMD) | EMD, EEMD, CEEMDAN (and ensemble chains) |
68
+ | ewtpy | EWT |
69
+ | vmdpy | VMD |
70
+ | psutil | available-memory reading for the memmap policy |
71
+
72
+ > Please install `EMD-signal`, not `PyEMD` (the latter is an unrelated older package).
73
+
74
+ Optional extras (not required at runtime): `[dev]` (pytest, black) and
75
+ `[plot]` (matplotlib). `numba` may be installed to activate the optional
76
+ `"numba"` backend of `Utils.Peaks` / `SVMD`; everything degrades gracefully
77
+ without it.
78
+
79
+ ## Quick Start
80
+
81
+ ```python
82
+ import numpy as np
83
+ from Modal_Decomposition import Function as f
84
+
85
+ fs = 1000
86
+ t = np.linspace(0, 1, 1000, endpoint=False)
87
+ S = np.sin(2 * np.pi * 37 * t) + 0.5 * np.sin(2 * np.pi * 180 * t)
88
+
89
+ IMFs, Res, Info = f.EMD(S) # returns a DecompositionResult tuple
90
+ ```
91
+
92
+ ### API — two entrances
93
+
94
+ All entrances live in `Modal_Decomposition/__init__.py`, exposed as two
95
+ read-only namespaces plus a small set of global helpers:
96
+
97
+ - **`Class`** — decomposer classes. Construct with parameters, then call
98
+ `.decompose(S, T=None)` (also available as `__call__`):
99
+
100
+ ```python
101
+ from Modal_Decomposition import Class
102
+
103
+ r = Class.VMD(alpha=3000, K=4).decompose(S)
104
+ ```
105
+
106
+ - **`Function`** — function facades, strictly equivalent to the class form
107
+ (`Function.X(S, T=None, **params)` = `Class.X(**params).decompose(S, T)`):
108
+
109
+ ```python
110
+ r = f.LMD(S) # r is a DecompositionResult, not a tuple
111
+ ```
112
+
113
+ - **Global helpers** — `set_seed(seed)` / `get_seed()`,
114
+ `set_absolute_limit(bytes)` / `set_memmap_ratio(ratio)` (see
115
+ [Memory policy](#memory-policy-for-very-large-signals)).
116
+
117
+ ### Return contract
118
+
119
+ Every method returns a **`DecompositionResult`** (also unpackable as a
120
+ 3-tuple `IMFs, Res, info`):
121
+
122
+ | Field | Meaning |
123
+ |----------|--------------------------------------------------------------------|
124
+ | `.IMFs` | decomposed modes, shape `(K, N)` (univariate) or `(K, d, N)` (MEMD)|
125
+ | `.Res` | residual, or `None` for methods without a residual concept (SSA, VMD) |
126
+ | `.info` | method-specific diagnostics dict (e.g. FFT spectra, boundaries) |
127
+ | `.config`| frozen dataclass snapshot of the *effective* parameters of this run |
128
+
129
+ Plus helpers: `.n_imfs`, `.shape` and `.reconstruct()` (`sum(IMFs) + Res`).
130
+
131
+ ```python
132
+ r = f.CEEMDAN(S, trials=30, seed=0)
133
+ print(r.n_imfs, r.reconstruct().shape)
134
+ print(r.config) # effective parameter snapshot
135
+ ```
136
+
137
+ ### Random seed
138
+
139
+ Methods that use randomness accept a local `seed` parameter. A process-level
140
+ global seed overrides every local seed (with a `UserWarning`) — call
141
+ `Modal_Decomposition.set_seed(n)` once at the start of a script to make all
142
+ downstream runs reproducible.
143
+
144
+ ### Time axis
145
+
146
+ `T` is optional; when omitted an index axis is used. Pass a non-uniformly
147
+ sampled axis when the method needs physical frequencies (e.g. `fs`-related
148
+ parameters); duplicate or descending axes are validated (descending axes are
149
+ reordered with a warning).
150
+
151
+ ## Memory policy for very large signals
152
+
153
+ Large-input support is built into the input layer
154
+ (`Utils.Check_Time_and_Signal`): inputs above the policy threshold are served
155
+ from disk-backed `np.memmap` working copies instead of being materialized in
156
+ RAM, so a machine can process signals far larger than its physical memory.
157
+
158
+ - `set_memmap_ratio(ratio)` — memmap when the projected usage reaches
159
+ `ratio` (default 0.6) of the remaining available memory;
160
+ - `set_absolute_limit(n_bytes)` — memmap above a fixed byte limit (default 2 GiB).
161
+
162
+ The two strategies are mutually exclusive; the latest call wins. Monotonicity
163
+ checks and chunked utilities (`Utils.Chunk`) follow the same policy.
164
+
165
+ ## Repository layout
166
+
167
+ ```
168
+ src/Modal_Decomposition/
169
+ ├── __init__.py Class / Function namespaces + global API
170
+ ├── <METHOD>.py 1 Config dataclass + 1 Decomposer per method
171
+ ├── EMD.py native EMD engine (PyEMD-free; original EMD_new,
172
+ │ registered as the public "EMD")
173
+ ├── _Registry.py class registry (registration at import time)
174
+ ├── Base/ Decomposer ABC, DecompositionResult, Config,
175
+ │ import Cache, metadata tables, size constants
176
+ └── Utils/ Check / Chunk / Peaks / Mirror / Spline / Envelope /
177
+ Hilbert / Monotonicity / Memory / Seed
178
+ (+ _Hilbert FHT backends)
179
+ tests/ pytest suite + benchmarking harnesses (comparison/,
180
+ ssa/, test_memory/) against PyEMD and PySDKit
181
+ ```
182
+
183
+ ## Changelog
184
+
185
+ ### 0.2.1
186
+
187
+ - `EMD` is now the native self-implemented sifting engine (ex-`EMD_new`,
188
+ registered as the public `EMD`; the former PyEMD wrapper was removed) —
189
+ faster than PyEMD at equal mode quality, cold start ~ms vs ~0.5 s
190
+ (`docs/EMD_vs_EMD_new_Performance_Report.md`).
191
+ - `EMD(faster=...)` two-branch stopping policy: `faster=False` (default,
192
+ quality branch) additionally requires the classic narrowband balance
193
+ `|zc - ext| <= 1` before accepting each IMF (clean signals cost nothing;
194
+ noisy / long signals trade speed for row-level purity comparable with
195
+ PyEMD); `faster=True` keeps the legacy fast branch (energy Cauchy SD
196
+ stops sifting). Full four-way comparison (MD-quality / MD-fast / PyEMD /
197
+ PySDKit) in `docs/EMD_faster_Branch_Comparison_Report.md`. Speed ratios
198
+ are always quoted same-process/same-script (median timing in the bench
199
+ scripts), never cross-day absolute timings.
200
+ - `EMD` defaults (CubicSpline envelope + `sd_thr=0.01` + `faster=False`)
201
+ chosen by the mode-level validation (`docs/EMD_Validation_and_Comparison_Report.md`)
202
+ and the mechanism/optimization analysis (`docs/EMD_Quality_Gap_and_Optimization.md`);
203
+ `spline_kind` accepts the canonical `Utils.Spline` kinds.
204
+ - Temporary memmap backing files are now cleaned up: the input-layer memmap
205
+ registry deletes its files at interpreter exit (`atexit`, handle closed
206
+ first — required on Windows), and `Utils.Chunk.exo_chunks` deletes its
207
+ files when each iteration ends; see
208
+ `docs/EMD_Large_Signal_Memory_Report.md` §5.
209
+ - Timing / quality / memory benchmarks re-run on the native engine and
210
+ reported under `docs/` (four new reports + `docs/EXPERIMENTS_INDEX.md`);
211
+ stale test files removed and legacy benchmark data archived under
212
+ `tests/comparison/results/_legacy_pyemd_wrapper/`.
213
+ - LMD defaults to the extrema (Spline) interpolation envelope; the analytic
214
+ Hilbert envelope stays as an explicit opt-in only. The Hilbert-vs-Spline
215
+ envelope concepts are separated again (`Utils.Envelope` restored as its own
216
+ module).
217
+ - New `Utils.Mirror` (endpoint mirror extension, EMD nbsym + LMD boundary
218
+ modes) shared by EMD / LMD / future consumers.
219
+
220
+ ### 0.2.0
221
+
222
+ - Unified utility layer (`Utils.Chunk` / `Peaks` / `Check` / `Cache` /
223
+ `Memory` / `Spline` / `Envelope`) with documented conventions and speed
224
+ reports under `docs/`.
225
+ - Memory-bounded processing for very large signals: policy-driven `memmap`
226
+ input layer, adaptive chunking, dtype-preserving pipelines.
227
+ - Optional C-accelerated FHT/Hilbert kernel (`_fht_native`, compiled wheels
228
+ for Windows / macOS / Linux, cp310–cp313) with automatic pure-NumPy
229
+ fallback; CI verifies native-vs-pure numerical identity.
230
+ - `EMD_new`: experimental self-implemented EMD engine (prototype of the
231
+ PyEMD-free roadmap).
232
+ - Dependency cleanup: removed unused packages (`calorine`, `tqdm` and stale
233
+ pinned entries); unified result `config` snapshots and seed handling.
234
+
235
+ ## Acknowledgement
236
+
237
+ The `FHT` Hilbert backend under
238
+ `src/Modal_Decomposition/Utils/_Hilbert/_C/_fht/` contains **third-party C
239
+ code**:
240
+
241
+ - Originally written by the **Smithsonian Astrophysical Observatory**,
242
+ Submillimeter Receiver Laboratory (Scott Paine), as part of the *am*
243
+ atmospheric model: <https://www.cfa.harvard.edu/~spaine/am/>
244
+ - Acquired from
245
+ [waddafunk/Smithsonians_Discrete_Hilbert_Fourier_Hartley_Transforms](https://github.com/waddafunk/Smithsonians_Discrete_Hilbert_Fourier_Hartley_Transforms)
246
+ (Jacopo Piccirillo, 13/10/2020), where the transform routines were isolated
247
+ for standalone C/C++ use.
248
+
249
+ Smithsonian *am* license notice:
250
+
251
+ > This computer program containing an atmospheric propagation model for the
252
+ > submillimeter band is a work of the United States and may be used freely,
253
+ > with attribution and credit to the Smithsonian Astrophysical Observatory.
254
+ > The program is intended for educational, scholarly or research purposes. In
255
+ > connection with any commercial use of the program, the user should disclose
256
+ > clearly and conspicuously all of the information contained in the first
257
+ > sentence of this notice.
258
+
259
+ **Hilbert-transform phase convention:** the SAO implementation shifts the
260
+ phase by **+90°** — *not* **−90°** as in MATLAB/SciPy. To obtain the
261
+ MATLAB-compatible result, multiply the component orthogonal to the input by
262
+ `exp(j·π) = −1`, i.e. multiply the imaginary part of the analytic signal by
263
+ −1 for a real input (`matlab_phase=True` in
264
+ `Modal_Decomposition.Utils._Hilbert._fht`).
265
+
266
+ ## License
267
+
268
+ Apache-2.0 — see [LICENSE](LICENSE).
269
+
270
+ ## URL
271
+
272
+ Project homepage / repository:
273
+ <https://github.com/a-raining-day/Modal-Decomposition>
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "Modal-Decomposition"
7
- version = "0.2.0"
7
+ version = "0.2.1"
8
8
  requires-python = ">=3.10"
9
9
 
10
10
  authors = [
@@ -32,7 +32,7 @@ import threading
32
32
  import types
33
33
  from typing import Any, Dict, List, Optional, Tuple
34
34
 
35
- __all__ = ["cache", "Cache"]
35
+ __all__ = ["Cache"]
36
36
 
37
37
 
38
38
  class cache:
@@ -47,7 +47,7 @@ class cache:
47
47
 
48
48
  Examples
49
49
  --------
50
- >>> from Modal_Decomposition.Base.Cache import cache
50
+ >>> from Modal_Decomposition.Base.Cache import Cache
51
51
  >>> import scipy.signal as ss
52
52
  >>> cache.add("scipy.signal", ss, description="signal processing submodule")
53
53
  True