Metadata-Version: 2.4
Name: fast-vmdpy
Version: 0.1.0
Summary: Low-memory Variational Mode Decomposition with optional Numba acceleration
Author: jiliangboki
License-Expression: MIT
Project-URL: Homepage, https://github.com/JiLiangBOKI/fast-vmdpy
Project-URL: Repository, https://github.com/JiLiangBOKI/fast-vmdpy
Project-URL: Issues, https://github.com/JiLiangBOKI/fast-vmdpy/issues
Keywords: VMD,signal processing,time series,Numba
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy>=1.23
Provides-Extra: accelerate
Requires-Dist: numba<0.67,>=0.59; extra == "accelerate"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: vmdpy==0.2; extra == "test"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: vmdpy==0.2; extra == "dev"
Requires-Dist: numba<0.67,>=0.59; extra == "dev"
Dynamic: license-file

# fast-vmdpy

Low-memory Variational Mode Decomposition with optional Numba acceleration.

This project follows the numerical update equations and public return format of
[`vmdpy`](https://github.com/vrcarva/vmdpy), while replacing the full ADMM
iteration-history tensor with two rolling mode buffers. It also provides a
weighted reconstruction path that combines mode spectra before a single IFFT.

> Status: pre-release. The package has not been uploaded to PyPI yet.

## Why

The reference implementation allocates mode spectra for all 500 possible ADMM
iterations. For a 250-sample signal and seven modes, the main complex history
array alone is about 28 MB per call. The rolling-buffer implementation retains
only the previous and current iterations.

In the motivating real-time EEG workload, the weighted reconstruction path
reduced mean VMD time from 110.8 ms to 14.7 ms after JIT warm-up. Performance
depends on signal length, parameters, CPU, and whether Numba is installed.

## Installation

After the first PyPI release:

```bash
pip install "fast-vmdpy[accelerate]"
```

For the low-memory NumPy implementation without Numba:

```bash
pip install fast-vmdpy
```

## Drop-in VMD API

```python
from fast_vmdpy import VMD

u, u_hat, omega = VMD(
    signal,
    alpha=2000,
    tau=0.0,
    K=3,
    DC=False,
    init=1,
    tol=1e-7,
)
```

The first seven arguments and the three return values match `vmdpy.VMD`.
Numba is selected automatically when installed. Pass `use_numba=False` to
force the NumPy path.

## Weighted reconstruction

```python
from fast_vmdpy import weighted_vmd_reconstruct

filtered = weighted_vmd_reconstruct(
    signal,
    alpha=1140.82,
    tau=0.4882,
    modes=7,
    dc=False,
    init=1,
    tol=1e-6,
    weights=[0.0, 0.2, 0.4, 0.8, 1.0, 1.0, 1.0],
)
```

Because the inverse Fourier transform is linear, the function combines the
weighted final mode spectra and performs one IFFT instead of reconstructing
every mode separately.

## Development

```bash
python -m pip install -e ".[dev]"
pytest
python benchmarks/benchmark_vmd.py
python -m build
python -m twine check dist/*
```

## Compatibility notes

- Odd-length inputs follow `vmdpy` 0.2 behavior by dropping the last sample.
- Zero-energy modes use a safe center-frequency average rather than producing
  a division-by-zero result.
- Numba compilation adds one-time startup cost; benchmark after warm-up.

## Attribution and citation

This implementation is derived from the MIT-licensed `vmdpy` implementation by
Vinícius Rezende Carvalho and Eduardo Mazoni, itself based on Dominique Zosso's
MATLAB implementation.

If you use VMD in research, cite:

> Dragomiretskiy, K. and Zosso, D. (2014). Variational Mode Decomposition.
> IEEE Transactions on Signal Processing, 62(3), 531–544.
> https://doi.org/10.1109/TSP.2013.2288675

Please also follow the citation guidance in the original `vmdpy` project.

## License

MIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
