Metadata-Version: 2.4
Name: pmtvs
Version: 1.0.6
Requires-Dist: numpy>=1.21
Requires-Dist: scipy>=1.7
Requires-Dist: pywavelets>=1.4
License-File: LICENSE
Summary: Rust-accelerated signal analysis primitives
Author: pmtvs contributors
License: PolyForm-Strict-1.0.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# pmtvs

Rust-accelerated signal analysis primitives.

**numpy in, number out.**

[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/)
[![License: PolyForm Strict](https://img.shields.io/badge/License-PolyForm%20Strict-blue.svg)](LICENSE)

## Installation

```bash
pip install pmtvs
```

## Quick Start

```python
from pmtvs import hurst_exponent
import numpy as np

signal = np.random.randn(1000)
h = hurst_exponent(signal)
print(f"Hurst exponent: {h:.3f}")
```

```python
import numpy as np
from pmtvs import (
    sample_entropy, permutation_entropy,
    hurst_exponent, dfa,
    skewness, kurtosis,
    eigendecomposition, svd_decomposition,
    granger_causality, mutual_information,
)

signal = np.random.randn(5000)

# Entropy
print(sample_entropy(signal))       # ~2.19
print(permutation_entropy(signal))  # ~2.57

# Fractal
print(hurst_exponent(signal))       # ~0.50
print(dfa(signal))                  # ~0.50

# Statistics
print(skewness(signal))             # ~0.00
print(kurtosis(signal))             # ~3.00
```

## What's Inside

232 functions in one flat import. Single wheel, no sub-packages.

| Domain | Functions | Description |
|--------|-----------|-------------|
| Entropy | 6 | Sample entropy, permutation entropy, LZ complexity |
| Fractal | 7 | Hurst exponent, DFA, rescaled range, variance growth |
| Statistics | 34 | Descriptive stats, calculus, derivatives, normalization |
| Correlation | 15 | Autocorrelation, cross-correlation, Spearman, Kendall, coherence |
| Distance | 6 | Euclidean, cosine, Manhattan, DTW, EMD |
| Embedding | 5 | Time delay embedding, FNN, Cao's method |
| Coupling | 2 | Rolling Spearman correlation |
| Dynamics | 23 | Lyapunov exponents, RQA, attractor reconstruction |
| Spectral | 17 | FFT (rustfft), PSD, Hilbert transform |
| Matrix | 22 | SVD, covariance, DMD, MI/Granger matrices |
| Topology | 11 | Persistent homology, Betti numbers |
| Network | 10 | Graph centrality, community detection |
| Information | 15 | Mutual information, KL divergence, Granger causality |
| Physics | 1 | Subspace angle |
| Tests | stat tests | Stationarity, hypothesis testing |
| Regression | 5 | Linear regression, signal arithmetic |

Full mathematical reference with LaTeX equations: [PRIMITIVES.md](PRIMITIVES.md)

## Benchmarks

Measured on Mac Mini M4 (arm64), Python 3.12. Not theoretical — timed.

| Function | Speedup | Why |
|----------|---------|-----|
| `dfa` | **267x** | Rust eliminates per-segment polyfit overhead |
| `dtw_distance` | **94x** | O(n^2) — Rust loops crush Python loops |
| `sample_entropy` | **31x** | O(n^2) template matching |
| `permutation_entropy` | **28x** | Combinatorial pattern counting |
| `hurst_exponent` | **20x** | Hybrid Rust/numpy by signal size |
| `skewness` | **7x** | Single-pass Rust vs multi-pass numpy |
| `kurtosis` | **8x** | Same |
| `autocorrelation` | **4x** | |
| `euclidean_distance` | **1.6x** | numpy BLAS — at parity |
| `rms` | **~1x** | numpy BLAS — at parity |
| `cosine_distance` | **~1x** | numpy BLAS — at parity |

**Overall: 41x mean, 326x max.**

BLAS-backed ops (rms, cosine, euclidean) delegate to numpy when numpy's LAPACK/BLAS is faster. Algorithmic functions (loops, O(n^2), combinatorial) use Rust. No ego — just speed.

Run the benchmark yourself:
```bash
python benchmarks/rust_vs_python.py
```

## Development

```bash
git clone https://github.com/pmtvs/pmtvs.git
cd pmtvs

# Install (requires Rust toolchain + maturin)
pip install maturin numpy scipy
cd packages/pmtvs && maturin develop --release

# Run tests
pytest packages/*/tests/ -v
```

## Reporting Issues

The most useful bug report includes: a minimal code example, the value pmtvs returned, and the value you expected with a source (published paper, competing library, or analytical solution).

"sample_entropy returns 2.14 but Richman-Moorman Table 2 gives 2.09 for this test vector" is a perfect bug report.

Edge cases are especially welcome — constant signals, very short signals, NaN-heavy data, extreme outliers. If you can break it, we want to know.

Issues: issues@pmtvs.dev

## Citation

```bibtex
@software{pmtvs2026,
  author    = {Rudder, Jason},
  title     = {pmtvs: Rust-Accelerated Signal Analysis Primitives},
  year      = {2026},
  publisher = {PyPI},
  url       = {https://pypi.org/project/pmtvs/}
}
```

Rudder Research © 2026

## License

PolyForm Strict 1.0.0 with Additional Terms.

- **Students & individual researchers:** Free. Cite us.
- **Funded research labs (grants > $100K):** Academic Research License required.
- **Commercial use:** Commercial License required.
- **Institutional deployment:** Institutional License required.

Contact: licensing@pmtvs.dev

See [LICENSE](LICENSE) for full terms.

