Metadata-Version: 2.4
Name: RamanujanFrame
Version: 0.0.3
Summary: Ramanujan Frame Expansion and Periodicity Transform
Project-URL: Homepage, https://github.com/kkt-ee/RamanujanFrame
Project-URL: Issues, https://github.com/kkt-ee/RamanujanFrame/issues
Author-email: Kishore Kumar Tarafdar <kkt.compute@outlook.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Requires-Dist: cvxpy
Requires-Dist: ecos
Requires-Dist: numpy
Description-Content-Type: text/markdown

# RamanujanFrame

[![PyPI Version](https://img.shields.io/pypi/v/RamanujanFrame?label=PyPI&color=gold)](https://pypi.org/project/RamanujanFrame/)
[![Python Versions](https://img.shields.io/pypi/pyversions/RamanujanFrame)](https://pypi.org/project/RamanujanFrame/)
[![TensorFlow](https://img.shields.io/badge/tensorflow-2.12%2B-darkorange)](https://www.tensorflow.org/)
[![CVXPY](https://img.shields.io/badge/cvxpy-1.4%2B-blue)](https://www.cvxpy.org/)
[![License](https://img.shields.io/badge/license-Apache%202.0-deepgreen.svg?style=flat)](LICENSE)

**Ramanujan Frame Expansion and Periodicity Transform (RPT)**

Ramanujan Frames are overcomplete dictionaries built from Ramanujan sums and their cyclic shifts, spanning all integer periods 1 to Q (maximum period to be detected) for discrete signals of length N. Decomposing a signal over this frame via sparse ℓ1 minimization (the Ramanujan Periodicity Transform, RPT) identifies the exact integer periods present through the subspace energies. They are particularly useful in detecting hidden periodicities in short discrete sequences that the Discrete Fourier Transform cannot resolve when the period does not divide the signal length.

## Install

**Install inside a virtual environment.**

First install TensorFlow (CPU or GPU) following the [official instructions](https://www.tensorflow.org/install/pip), then:

```bash
pip install RamanujanFrame
```

## Usage

```python
import numpy as np
from RamanujanFrame import RamanujanDict

# Build the Ramanujan dictionary
# N : signal length
# Q : search periods 1 ... Q
rd = RamanujanDict(N=64, Q=16)

# Decompose a signal
signal = np.array([1.0, 0.6, -0.2, -0.8, -0.4] * 13, dtype=np.float32)  # period-5
coeffs, energy = rd.solve_for_y_optimal(signal)

# coeffs : ndarray (Φ(Q), 1)  optimal Ramanujan coefficients y★
# energy : list of Q floats   energy per Ramanujan subspace S_q
```

A dominant peak at `energy[q-1]` identifies period `q` in the signal.
See [`examples/`](https://github.com/kkt-ee/RamanujanFrame/tree/main/examples/) for runnable demos including a DFT comparison.

---

## How it works

### Ramanujan sum

The Ramanujan sum for integer period `q` at sample `n` is

$$c_q(n) = \sum_{\substack{k=1 \\ \gcd(k,\,q)=1}}^{q} e^{\,j\frac{2\pi}{q}kn}$$

The sum runs over integers `k` coprime to `q`. `c_q(n)` is real-valued and integer-valued for all `n`.

### Ramanujan dictionary A

For each period `q = 1, ..., Q` the dictionary includes `φ(q)` columns: `c_q(n)` and its
`φ(q) − 1` cyclic shifts, where `φ` is Euler's totient function.
The full matrix `A` has shape `(N, Φ(Q))` where `Φ(Q) = Σ_{q=1}^{Q} φ(q)`.

When `Φ(Q) > N` the columns form an overcomplete frame for the N-dimensional signal space.
This is the key advantage over the Discrete Fourier Transform (DFT) basis `{W_N^k | k divides N}` which covers only the
divisors of `N` and cannot represent all integer periods.

### Sparse decomposition (RPT)

Given signal `x` of length `N`, RPT solves

$$\min_{y} \;\|Dy\|_1 \quad \text{subject to} \quad Ay = x$$

`D` is a diagonal penalty matrix with `D_{ii} = φ(P_i)`, where `P_i` is the period index of
column `i`. The ℓ1 norm promotes sparsity across Ramanujan subspaces.
Solved via [CVXPY](https://www.cvxpy.org/) with the ECOS solver.

### Subspace energy

The energy of period `q` is the squared ℓ2 norm of its coefficients in the optimal solution:

$$E_q = \sum_{i:\,P_i = q} |y^\star_i|^2$$

---

## References

[1] P. P. Vaidyanathan and S. Tenneti, "Srinivasa Ramanujan and signal-processing problems," *Philosophical Transactions of the Royal Society A*, vol. 378, no. 2163, p. 20180446, 2020.

## Citation

This software is released for broad research, educational, and engineering use. If this package helps your work, please cite the following paper:

```bibtex
@misc{tarafdar2026interpretablefrugallearningsystems,
      title={Interpretable and Frugal Learning Systems Employing Multiresolution Pyramids and Volterra Kernels},
      author={Kishore Kumar Tarafdar},
      year={2026},
      eprint={2606.15011},
      archivePrefix={arXiv},
      primaryClass={eess.SP},
      url={https://arxiv.org/abs/2606.15011},
}
```

## License

Apache 2.0 — see [LICENSE](LICENSE).
