Modal-Decomposition 0.1.5__tar.gz → 0.2.0__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 (108) hide show
  1. Modal-Decomposition-0.2.0/MANIFEST.in +8 -0
  2. Modal-Decomposition-0.2.0/PKG-INFO +267 -0
  3. Modal-Decomposition-0.2.0/README.md +236 -0
  4. {modal_decomposition-0.1.5 → Modal-Decomposition-0.2.0}/pyproject.toml +14 -8
  5. Modal-Decomposition-0.2.0/setup.py +71 -0
  6. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Base/Cache.py +420 -0
  7. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Base/ClassDefine.py +129 -0
  8. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Base/ConfigDefine.py +22 -0
  9. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Base/ConstDefine.py +19 -0
  10. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Base/PathDefine.py +11 -0
  11. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Base/TextDefine.py +43 -0
  12. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Base/__init__.py +21 -0
  13. Modal-Decomposition-0.2.0/src/Modal_Decomposition/CEEFD.py +161 -0
  14. Modal-Decomposition-0.2.0/src/Modal_Decomposition/CEEMD.py +149 -0
  15. Modal-Decomposition-0.2.0/src/Modal_Decomposition/CEEMDAN.py +150 -0
  16. Modal-Decomposition-0.2.0/src/Modal_Decomposition/EEMD.py +117 -0
  17. Modal-Decomposition-0.2.0/src/Modal_Decomposition/EFD.py +144 -0
  18. Modal-Decomposition-0.2.0/src/Modal_Decomposition/EMD.py +102 -0
  19. Modal-Decomposition-0.2.0/src/Modal_Decomposition/EMD_new.py +267 -0
  20. Modal-Decomposition-0.2.0/src/Modal_Decomposition/EWT.py +110 -0
  21. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Error/RealizationError.py +12 -0
  22. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Error/__init__.py +7 -0
  23. {modal_decomposition-0.1.5 → Modal-Decomposition-0.2.0}/src/Modal_Decomposition/FMD.py +418 -474
  24. Modal-Decomposition-0.2.0/src/Modal_Decomposition/ICEEMDAN.py +253 -0
  25. Modal-Decomposition-0.2.0/src/Modal_Decomposition/LMD.py +411 -0
  26. Modal-Decomposition-0.2.0/src/Modal_Decomposition/MEMD.py +285 -0
  27. Modal-Decomposition-0.2.0/src/Modal_Decomposition/RPSEMD.py +147 -0
  28. Modal-Decomposition-0.2.0/src/Modal_Decomposition/SSA.py +238 -0
  29. Modal-Decomposition-0.2.0/src/Modal_Decomposition/SVMD.py +209 -0
  30. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/Check.py +346 -0
  31. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/Chunk.py +488 -0
  32. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/Envelope.py +148 -0
  33. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/Hilbert.py +42 -0
  34. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/Memory.py +160 -0
  35. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/Monotonicity.py +407 -0
  36. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/Peaks.py +220 -0
  37. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/Seed.py +104 -0
  38. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/Spline.py +382 -0
  39. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/_Hilbert/_C/_fht/am_sysdep.c +112 -0
  40. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/_Hilbert/_C/_fht/am_sysdep.h +54 -0
  41. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/_Hilbert/_C/_fht/math_const.h +35 -0
  42. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/_Hilbert/_C/_fht/transforms.c +1406 -0
  43. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/_Hilbert/_C/_fht/transforms.h +38 -0
  44. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/_Hilbert/__init__.py +101 -0
  45. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/_Hilbert/_fht.py +191 -0
  46. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/_Hilbert/_fht_native.pyx +103 -0
  47. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/_Hilbert/_fir.py +0 -0
  48. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/_Hilbert/_forth_order_wave.py +0 -0
  49. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/_Hilbert/_kramers_kronig.py +0 -0
  50. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/_Hilbert/_scipy_backend.py +6 -0
  51. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/_Hilbert/_wave.py +0 -0
  52. Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/__init__.py +199 -0
  53. Modal-Decomposition-0.2.0/src/Modal_Decomposition/VMD.py +99 -0
  54. Modal-Decomposition-0.2.0/src/Modal_Decomposition/_Registry.py +39 -0
  55. Modal-Decomposition-0.2.0/src/Modal_Decomposition/_SVMD_numba.py +17 -0
  56. Modal-Decomposition-0.2.0/src/Modal_Decomposition/__init__.py +154 -0
  57. Modal-Decomposition-0.2.0/src/Modal_Decomposition.egg-info/PKG-INFO +267 -0
  58. Modal-Decomposition-0.2.0/src/Modal_Decomposition.egg-info/SOURCES.txt +82 -0
  59. {modal_decomposition-0.1.5 → Modal-Decomposition-0.2.0}/src/Modal_Decomposition.egg-info/requires.txt +0 -3
  60. Modal-Decomposition-0.2.0/tests/test_cache.py +494 -0
  61. Modal-Decomposition-0.2.0/tests/test_chunk.py +364 -0
  62. Modal-Decomposition-0.2.0/tests/test_contract.py +82 -0
  63. Modal-Decomposition-0.2.0/tests/test_emd_new.py +204 -0
  64. Modal-Decomposition-0.2.0/tests/test_envelope.py +109 -0
  65. Modal-Decomposition-0.2.0/tests/test_facade.py +50 -0
  66. Modal-Decomposition-0.2.0/tests/test_fht.py +23 -0
  67. Modal-Decomposition-0.2.0/tests/test_fmd_lmd_refactor.py +63 -0
  68. Modal-Decomposition-0.2.0/tests/test_import.py +9 -0
  69. Modal-Decomposition-0.2.0/tests/test_montonic.py +215 -0
  70. Modal-Decomposition-0.2.0/tests/test_path.py +6 -0
  71. Modal-Decomposition-0.2.0/tests/test_peaks.py +209 -0
  72. Modal-Decomposition-0.2.0/tests/test_reconstruction.py +41 -0
  73. Modal-Decomposition-0.2.0/tests/test_registry.py +67 -0
  74. Modal-Decomposition-0.2.0/tests/test_seed.py +92 -0
  75. Modal-Decomposition-0.2.0/tests/test_spline.py +312 -0
  76. Modal-Decomposition-0.2.0/tests/test_utils.py +564 -0
  77. modal_decomposition-0.1.5/PKG-INFO +0 -120
  78. modal_decomposition-0.1.5/README.md +0 -89
  79. modal_decomposition-0.1.5/src/Modal_Decomposition/CEEFD.py +0 -114
  80. modal_decomposition-0.1.5/src/Modal_Decomposition/CEEMD.py +0 -103
  81. modal_decomposition-0.1.5/src/Modal_Decomposition/CEEMDAN.py +0 -89
  82. modal_decomposition-0.1.5/src/Modal_Decomposition/EEMD.py +0 -58
  83. modal_decomposition-0.1.5/src/Modal_Decomposition/EFD.py +0 -120
  84. modal_decomposition-0.1.5/src/Modal_Decomposition/EMD.py +0 -54
  85. modal_decomposition-0.1.5/src/Modal_Decomposition/EWT.py +0 -62
  86. modal_decomposition-0.1.5/src/Modal_Decomposition/Error/RealizationError.py +0 -2
  87. modal_decomposition-0.1.5/src/Modal_Decomposition/ICEEMDAN.py +0 -304
  88. modal_decomposition-0.1.5/src/Modal_Decomposition/LMD.py +0 -236
  89. modal_decomposition-0.1.5/src/Modal_Decomposition/MEMD.py +0 -238
  90. modal_decomposition-0.1.5/src/Modal_Decomposition/RPSEMD.py +0 -92
  91. modal_decomposition-0.1.5/src/Modal_Decomposition/SSA.py +0 -224
  92. modal_decomposition-0.1.5/src/Modal_Decomposition/SVMD.py +0 -337
  93. modal_decomposition-0.1.5/src/Modal_Decomposition/Utils/Check.py +0 -39
  94. modal_decomposition-0.1.5/src/Modal_Decomposition/Utils/EnvironmentMemory.py +0 -20
  95. modal_decomposition-0.1.5/src/Modal_Decomposition/Utils/LazyImport.py +0 -21
  96. modal_decomposition-0.1.5/src/Modal_Decomposition/Utils/Monotonicity.py +0 -173
  97. modal_decomposition-0.1.5/src/Modal_Decomposition/Utils/NumpyNdarray_MemoryCalculator.py +0 -38
  98. modal_decomposition-0.1.5/src/Modal_Decomposition/Utils/__init__.py +0 -30
  99. modal_decomposition-0.1.5/src/Modal_Decomposition/VMD.py +0 -50
  100. modal_decomposition-0.1.5/src/Modal_Decomposition/__init__.py +0 -176
  101. modal_decomposition-0.1.5/src/Modal_Decomposition.egg-info/PKG-INFO +0 -120
  102. modal_decomposition-0.1.5/src/Modal_Decomposition.egg-info/SOURCES.txt +0 -33
  103. modal_decomposition-0.1.5/tests/test.py +0 -216
  104. {modal_decomposition-0.1.5 → Modal-Decomposition-0.2.0}/LICENSE +0 -0
  105. {modal_decomposition-0.1.5 → Modal-Decomposition-0.2.0}/setup.cfg +0 -0
  106. /modal_decomposition-0.1.5/src/Modal_Decomposition/Error/CycleError.py → /Modal-Decomposition-0.2.0/src/Modal_Decomposition/Utils/_Hilbert/_fft.py +0 -0
  107. {modal_decomposition-0.1.5 → Modal-Decomposition-0.2.0}/src/Modal_Decomposition.egg-info/dependency_links.txt +0 -0
  108. {modal_decomposition-0.1.5 → Modal-Decomposition-0.2.0}/src/Modal_Decomposition.egg-info/top_level.txt +0 -0
@@ -0,0 +1,8 @@
1
+ # Files to include in the source distribution (sdist) so that
2
+ # `pip install <sdist>` can compile the _fht_native extension on the fly.
3
+ # NOTE: keep this file pure ASCII - setuptools reads it with the locale
4
+ # encoding on some platforms (e.g. GBK on Windows).
5
+ include LICENSE
6
+ include README.md
7
+ recursive-include src/Modal_Decomposition/Utils/_Hilbert/_C *
8
+ include src/Modal_Decomposition/Utils/_Hilbert/_fht_native.pyx
@@ -0,0 +1,267 @@
1
+ Metadata-Version: 2.1
2
+ Name: Modal-Decomposition
3
+ Version: 0.2.0
4
+ Summary: a package for modal decomposition
5
+ Author-email: Mao_HaoChuan <2215269365@qq.com>
6
+ License: Apache-2.0
7
+ Project-URL: homepage, https://github.com/a-raining-day/Modal-Decomposition
8
+ Project-URL: repository, https://github.com/a-raining-day/Modal-Decomposition.git
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: Programming Language :: Python :: 3.10
11
+ Classifier: Programming Language :: Python :: 3.11
12
+ Classifier: Programming Language :: Python :: 3.12
13
+ Classifier: License :: OSI Approved :: Apache Software License
14
+ Classifier: Operating System :: Microsoft :: Windows
15
+ Classifier: Operating System :: MacOS :: MacOS X
16
+ Classifier: Operating System :: POSIX :: Linux
17
+ Requires-Python: >=3.10
18
+ Description-Content-Type: text/markdown
19
+ License-File: LICENSE
20
+ Requires-Dist: numpy
21
+ Requires-Dist: EMD-signal
22
+ Requires-Dist: ewtpy
23
+ Requires-Dist: scipy
24
+ Requires-Dist: vmdpy
25
+ Requires-Dist: psutil
26
+ Provides-Extra: dev
27
+ Requires-Dist: pytest>=7.0; extra == "dev"
28
+ Requires-Dist: black; extra == "dev"
29
+ Provides-Extra: plot
30
+ Requires-Dist: matplotlib; extra == "plot"
31
+
32
+ # Modal-Decomposition
33
+
34
+ > A unified library of modal decomposition methods — 15 classical and modern
35
+ > signal-decomposition algorithms behind one consistent API.
36
+
37
+ There are many methods of modal decomposition, but there is no library that
38
+ covers them all with a single, coherent interface. **Modal-Decomposition**
39
+ integrates the most commonly used decomposition algorithms into one package:
40
+ every method shares the same class contract, the same return type, and the
41
+ same validation / seeding / memory conventions, so switching between
42
+ algorithms (or benchmarking them against each other) is a one-line change.
43
+
44
+ ## Methods
45
+
46
+ | Method | Description | Use | Reference (DOI) |
47
+ |----------|--------------------------------------------------------------------------|----------------------------|-----------------|
48
+ | CEEMDAN | Complete Ensemble Empirical Mode Decomposition with Adaptive Noise | `Function.CEEMDAN(S)` | [10.1109/ICASSP.2011.5947265](https://ieeexplore.ieee.org/abstract/document/5947265) |
49
+ | 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) |
50
+ | CEEMD | Complementary Ensemble Empirical Mode Decomposition | `Function.CEEMD(S)` | [10.1016/j.jhydrol.2020.124647](https://www.sciencedirect.com/science/article/abs/pii/S0022169420301074) |
51
+ | 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) |
52
+ | EFD | Empirical Fourier Decomposition | `Function.EFD(S)` | [10.1016/j.ymssp.2021.108155](https://www.sciencedirect.com/science/article/abs/pii/S0888327021005355?via%3Dihub) |
53
+ | 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) |
54
+ | EWT | Empirical Wavelet Transform | `Function.EWT(S)` | [10.48550/arXiv.2304.06274](https://arxiv.org/abs/2304.06274) |
55
+ | FMD | Filtered Mode Decomposition | `Function.FMD(S)` | [10.1109/TIE.2022.3156156](https://ieeexplore.ieee.org/document/9732251) |
56
+ | 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) |
57
+ | LMD | Local Mean Decomposition | `Function.LMD(S)` | [10.1098/rsif.2005.0058](https://royalsocietypublishing.org/doi/10.1098/rsif.2005.0058) |
58
+ | MEMD | Multivariate Empirical Mode Decomposition | `Function.MEMD(S)` | [10.48550/arXiv.2206.00926](https://arxiv.org/abs/2206.00926) |
59
+ | RPSEMD | Random Phase Sinusoidal Assisted Empirical Mode Decomposition | `Function.RPSEMD(S)` | [10.1109/LSP.2016.2537376](https://ieeexplore.ieee.org/document/7423702) |
60
+ | SSA | Singular Spectrum Analysis | `Function.SSA(S)` | [10.1016/j.mex.2020.101015](https://www.sciencedirect.com/science/article/pii/S2215016120302351) |
61
+ | SVMD | Successive Variational Mode Decomposition | `Function.SVMD(S)` | [10.1016/j.sigpro.2020.107610](https://www.sciencedirect.com/science/article/abs/pii/S0165168420301535) |
62
+ | VMD | Variational Mode Decomposition | `Function.VMD(S)` | [10.1109/TSP.2013.2288675](https://ieeexplore.ieee.org/document/6655981) |
63
+
64
+ ## Install
65
+
66
+ ```shell
67
+ pip install Modal-Decomposition
68
+ ```
69
+
70
+ Or install from source:
71
+
72
+ ```shell
73
+ git clone https://github.com/a-raining-day/Modal-Decomposition.git
74
+ cd Modal-Decomposition
75
+ pip install -r requirements.txt # pinned build/dev environment
76
+ pip install -e . # editable install (compiles the FHT kernel)
77
+ ```
78
+
79
+ The published platform wheels (Windows / macOS / Linux) ship the optional
80
+ Cython-compiled FHT acceleration kernel `_fht_native` (C source from the
81
+ Smithsonian *am* project, see [Acknowledgement](#acknowledgement)); it is used
82
+ automatically when present and the library falls back to the pure NumPy
83
+ implementation otherwise, so it runs in any environment. To compile the
84
+ kernel manually inside a source tree:
85
+
86
+ ```shell
87
+ python setup.py build_ext --inplace # repository root
88
+ ```
89
+
90
+ Requires **Python >= 3.10**.
91
+
92
+ ### Dependencies
93
+
94
+ | Package | Used by / for |
95
+ |-------------|-----------------------------------------------------|
96
+ | numpy | core arrays and vectorized kernels |
97
+ | scipy | splines, envelope / Hilbert, filtering, peaks, FFT |
98
+ | EMD-signal (PyEMD) | EMD, EEMD, CEEMDAN (and ensemble chains) |
99
+ | ewtpy | EWT |
100
+ | vmdpy | VMD |
101
+ | psutil | available-memory reading for the memmap policy |
102
+
103
+ > Please install `EMD-signal`, not `PyEMD` (the latter is an unrelated older package).
104
+
105
+ Optional extras (not required at runtime): `[dev]` (pytest, black) and
106
+ `[plot]` (matplotlib). `numba` may be installed to activate the optional
107
+ `"numba"` backend of `Utils.Peaks` / `SVMD`; everything degrades gracefully
108
+ without it.
109
+
110
+ ## Quick Start
111
+
112
+ ```python
113
+ import numpy as np
114
+ from Modal_Decomposition import Function as f
115
+
116
+ fs = 1000
117
+ t = np.linspace(0, 1, 1000, endpoint=False)
118
+ S = np.sin(2 * np.pi * 37 * t) + 0.5 * np.sin(2 * np.pi * 180 * t)
119
+
120
+ IMFs, Res, Info = f.EMD(S) # returns a DecompositionResult tuple
121
+ ```
122
+
123
+ ### API — two entrances
124
+
125
+ All entrances live in `Modal_Decomposition/__init__.py`, exposed as two
126
+ read-only namespaces plus a small set of global helpers:
127
+
128
+ - **`Class`** — decomposer classes. Construct with parameters, then call
129
+ `.decompose(S, T=None)` (also available as `__call__`):
130
+
131
+ ```python
132
+ from Modal_Decomposition import Class
133
+
134
+ r = Class.VMD(alpha=3000, K=4).decompose(S)
135
+ ```
136
+
137
+ - **`Function`** — function facades, strictly equivalent to the class form
138
+ (`Function.X(S, T=None, **params)` = `Class.X(**params).decompose(S, T)`):
139
+
140
+ ```python
141
+ r = f.LMD(S) # r is a DecompositionResult, not a tuple
142
+ ```
143
+
144
+ - **Global helpers** — `set_seed(seed)` / `get_seed()`,
145
+ `set_absolute_limit(bytes)` / `set_memmap_ratio(ratio)` (see
146
+ [Memory policy](#memory-policy-for-very-large-signals)).
147
+
148
+ ### Return contract
149
+
150
+ Every method returns a **`DecompositionResult`** (also unpackable as a
151
+ 3-tuple `IMFs, Res, info`):
152
+
153
+ | Field | Meaning |
154
+ |----------|--------------------------------------------------------------------|
155
+ | `.IMFs` | decomposed modes, shape `(K, N)` (univariate) or `(K, d, N)` (MEMD)|
156
+ | `.Res` | residual, or `None` for methods without a residual concept (SSA, VMD) |
157
+ | `.info` | method-specific diagnostics dict (e.g. FFT spectra, boundaries) |
158
+ | `.config`| frozen dataclass snapshot of the *effective* parameters of this run |
159
+
160
+ Plus helpers: `.n_imfs`, `.shape` and `.reconstruct()` (`sum(IMFs) + Res`).
161
+
162
+ ```python
163
+ r = f.CEEMDAN(S, trials=30, seed=0)
164
+ print(r.n_imfs, r.reconstruct().shape)
165
+ print(r.config) # effective parameter snapshot
166
+ ```
167
+
168
+ ### Random seed
169
+
170
+ Methods that use randomness accept a local `seed` parameter. A process-level
171
+ global seed overrides every local seed (with a `UserWarning`) — call
172
+ `Modal_Decomposition.set_seed(n)` once at the start of a script to make all
173
+ downstream runs reproducible.
174
+
175
+ ### Time axis
176
+
177
+ `T` is optional; when omitted an index axis is used. Pass a non-uniformly
178
+ sampled axis when the method needs physical frequencies (e.g. `fs`-related
179
+ parameters); duplicate or descending axes are validated (descending axes are
180
+ reordered with a warning).
181
+
182
+ ## Memory policy for very large signals
183
+
184
+ Large-input support is built into the input layer
185
+ (`Utils.Check_Time_and_Signal`): inputs above the policy threshold are served
186
+ from disk-backed `np.memmap` working copies instead of being materialized in
187
+ RAM, so a machine can process signals far larger than its physical memory.
188
+
189
+ - `set_memmap_ratio(ratio)` — memmap when the projected usage reaches
190
+ `ratio` (default 0.6) of the remaining available memory;
191
+ - `set_absolute_limit(n_bytes)` — memmap above a fixed byte limit (default 2 GiB).
192
+
193
+ The two strategies are mutually exclusive; the latest call wins. Monotonicity
194
+ checks and chunked utilities (`Utils.Chunk`) follow the same policy.
195
+
196
+ ## Repository layout
197
+
198
+ ```
199
+ src/Modal_Decomposition/
200
+ ├── __init__.py Class / Function namespaces + global API
201
+ ├── <METHOD>.py 1 Config dataclass + 1 Decomposer per method
202
+ ├── EMD_new.py experimental native (PyEMD-free) EMD engine
203
+ ├── _Registry.py class registry (registration at import time)
204
+ ├── Base/ Decomposer ABC, DecompositionResult, Config,
205
+ │ import Cache, metadata tables, size constants
206
+ └── Utils/ Check / Chunk / Peaks / Spline / Envelope / Hilbert /
207
+ Monotonicity / Memory / Seed (+ _Hilbert FHT backends)
208
+ tests/ pytest suite + benchmarking harnesses (comparison/,
209
+ ssa/, test_memory/) against PyEMD and PySDKit
210
+ ```
211
+
212
+ ## Changelog
213
+
214
+ ### 0.2.0
215
+
216
+ - Unified utility layer (`Utils.Chunk` / `Peaks` / `Check` / `Cache` /
217
+ `Memory` / `Spline` / `Envelope`) with documented conventions and speed
218
+ reports under `docs/`.
219
+ - Memory-bounded processing for very large signals: policy-driven `memmap`
220
+ input layer, adaptive chunking, dtype-preserving pipelines.
221
+ - Optional C-accelerated FHT/Hilbert kernel (`_fht_native`, compiled wheels
222
+ for Windows / macOS / Linux, cp310–cp313) with automatic pure-NumPy
223
+ fallback; CI verifies native-vs-pure numerical identity.
224
+ - `EMD_new`: experimental self-implemented EMD engine (prototype of the
225
+ PyEMD-free roadmap).
226
+ - Dependency cleanup: removed unused packages (`calorine`, `tqdm` and stale
227
+ pinned entries); unified result `config` snapshots and seed handling.
228
+
229
+ ## Acknowledgement
230
+
231
+ The `FHT` Hilbert backend under
232
+ `src/Modal_Decomposition/Utils/_Hilbert/_C/_fht/` contains **third-party C
233
+ code**:
234
+
235
+ - Originally written by the **Smithsonian Astrophysical Observatory**,
236
+ Submillimeter Receiver Laboratory (Scott Paine), as part of the *am*
237
+ atmospheric model: <https://www.cfa.harvard.edu/~spaine/am/>
238
+ - Acquired from
239
+ [waddafunk/Smithsonians_Discrete_Hilbert_Fourier_Hartley_Transforms](https://github.com/waddafunk/Smithsonians_Discrete_Hilbert_Fourier_Hartley_Transforms)
240
+ (Jacopo Piccirillo, 13/10/2020), where the transform routines were isolated
241
+ for standalone C/C++ use.
242
+
243
+ Smithsonian *am* license notice:
244
+
245
+ > This computer program containing an atmospheric propagation model for the
246
+ > submillimeter band is a work of the United States and may be used freely,
247
+ > with attribution and credit to the Smithsonian Astrophysical Observatory.
248
+ > The program is intended for educational, scholarly or research purposes. In
249
+ > connection with any commercial use of the program, the user should disclose
250
+ > clearly and conspicuously all of the information contained in the first
251
+ > sentence of this notice.
252
+
253
+ **Hilbert-transform phase convention:** the SAO implementation shifts the
254
+ phase by **+90°** — *not* **−90°** as in MATLAB/SciPy. To obtain the
255
+ MATLAB-compatible result, multiply the component orthogonal to the input by
256
+ `exp(j·π) = −1`, i.e. multiply the imaginary part of the analytic signal by
257
+ −1 for a real input (`matlab_phase=True` in
258
+ `Modal_Decomposition.Utils._Hilbert._fht`).
259
+
260
+ ## License
261
+
262
+ Apache-2.0 — see [LICENSE](LICENSE).
263
+
264
+ ## URL
265
+
266
+ Project homepage / repository:
267
+ <https://github.com/a-raining-day/Modal-Decomposition>
@@ -0,0 +1,236 @@
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,11 +1,11 @@
1
1
  [build-system]
2
- requires = ["setuptools>=68.2.0", "wheel"]
2
+ requires = ["setuptools>=68.2.0", "wheel", "Cython>=3.0", "numpy>=1.21"]
3
3
  build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "Modal-Decomposition"
7
- version = "0.1.5"
8
- requires-python = ">=3.8"
7
+ version = "0.2.0"
8
+ requires-python = ">=3.10"
9
9
 
10
10
  authors = [
11
11
  {name = "Mao_HaoChuan", email = "2215269365@qq.com"},
@@ -16,17 +16,19 @@ license = {text = "Apache-2.0"}
16
16
  classifiers = [
17
17
  "Programming Language :: Python :: 3",
18
18
  "Programming Language :: Python :: 3.10",
19
+ "Programming Language :: Python :: 3.11",
20
+ "Programming Language :: Python :: 3.12",
19
21
  "License :: OSI Approved :: Apache Software License",
20
- "Operating System :: OS Independent",
22
+
23
+ "Operating System :: Microsoft :: Windows",
24
+ "Operating System :: MacOS :: MacOS X",
25
+ "Operating System :: POSIX :: Linux",
21
26
  ]
22
27
  dependencies = [
23
- "colorama",
24
28
  "numpy",
25
29
  "EMD-signal",
26
30
  "ewtpy",
27
31
  "scipy",
28
- "antropy",
29
- "tqdm",
30
32
  "vmdpy",
31
33
  "psutil"
32
34
  ]
@@ -38,4 +40,8 @@ homepage = "https://github.com/a-raining-day/Modal-Decomposition"
38
40
  repository = "https://github.com/a-raining-day/Modal-Decomposition.git"
39
41
 
40
42
  [tool.setuptools]
41
- package-dir = {"" = "src"}
43
+ package-dir = {"" = "src"}
44
+
45
+ [tool.cibuildwheel]
46
+ build = "cp310-* cp311-* cp312-* cp313-*"
47
+ skip = "*-musllinux*"
@@ -0,0 +1,71 @@
1
+ """
2
+ Modal-Decomposition 项目根构建脚本 —— Cython 加速扩展(_fht_native)的正式入口。
3
+
4
+ - PyPI / CI 构建: 由 pyproject.toml 的 build-system(setuptools + Cython + numpy)
5
+ 驱动, 本文件是扩展模块的唯一配置处;
6
+ - 本地开发(在仓库根目录运行, 编译产物直接放进源码包):
7
+ python setup.py build_ext --inplace
8
+
9
+ 说明:
10
+ - 扩展链接的 C 内核来自 Smithsonian Astrophysical Observatory "am" 项目
11
+ (见 src/Modal_Decomposition/Utils/_Hilbert/_C/_fht/ 各文件头部出处声明);
12
+ - -O3 / -ffast-math 仅适用于 GCC/Clang(Linux/macOS), Windows MSVC 用 /O2;
13
+ - NPY_TARGET_VERSION 让用 NumPy 2 头文件编译出的扩展在 NumPy>=1.19 运行时上
14
+ 依然可加载;
15
+ - cythonize 采用惰性触发: metadata/sdist 等不需要编译的阶段不依赖 Cython。
16
+ """
17
+
18
+ import sys
19
+
20
+ from setuptools import Extension, setup
21
+ from setuptools.command.build_ext import build_ext as _build_ext
22
+
23
+ _FHT_DIR = "src/Modal_Decomposition/Utils/_Hilbert"
24
+ _FHT_C_DIR = _FHT_DIR + "/_C/_fht"
25
+
26
+
27
+ def _native_extension() -> Extension:
28
+ """_fht_native: Cython 包装 SAO 的 FHT / Hilbert C 实现。
29
+
30
+ 纯 Python 版 src/Modal_Decomposition/Utils/_Hilbert/_fht.py 会自动检测该
31
+ 编译模块并优先使用; 找不到时回退到自身实现, 因此本扩展对库的功能是
32
+ 可选加速而非必需依赖。
33
+ """
34
+ compile_args = ["/O2"] if sys.platform == "win32" else ["-O3", "-ffast-math"]
35
+ return Extension(
36
+ "Modal_Decomposition.Utils._Hilbert._fht_native",
37
+ sources=[
38
+ _FHT_DIR + "/_fht_native.pyx",
39
+ _FHT_C_DIR + "/transforms.c",
40
+ _FHT_C_DIR + "/am_sysdep.c",
41
+ ],
42
+ include_dirs=[_FHT_C_DIR, _FHT_DIR],
43
+ define_macros=[
44
+ ("L1_CACHE_BYTES", "0x8000"), # am_sysdep.h: L1 = 32KB
45
+ ("NPY_TARGET_VERSION", "NPY_1_19_API_VERSION"), # 兼容 numpy>=1.19 运行时
46
+ ],
47
+ extra_compile_args=compile_args,
48
+ )
49
+
50
+
51
+ class _LazyCythonBuildExt(_build_ext):
52
+ """只有在真正编译(build_ext)时才执行 cythonize, 并注入 NumPy 头文件路径。"""
53
+
54
+ def run(self):
55
+ import numpy as np
56
+ from Cython.Build import cythonize
57
+
58
+ exts = cythonize(
59
+ self.distribution.ext_modules,
60
+ compiler_directives={"language_level": "3"},
61
+ )
62
+ for ext in exts:
63
+ ext.include_dirs.append(np.get_include())
64
+ self.distribution.ext_modules = exts
65
+ super().run()
66
+
67
+
68
+ setup(
69
+ ext_modules=[_native_extension()],
70
+ cmdclass={"build_ext": _LazyCythonBuildExt},
71
+ )