Metadata-Version: 2.4
Name: VolterraSys
Version: 0.0.1
Summary: Linear and nonlinear Volterra kernels in natural and multiresolution bases
Project-URL: Homepage, https://github.com/kkt-ee/VolterraSys
Project-URL: Issues, https://github.com/kkt-ee/VolterraSys/issues
Author-email: Kishore Kumar Tarafdar <kkt.ee.ai@gmail.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: keras
Requires-Dist: tensorflow>=2.15
Requires-Dist: tfdwt
Description-Content-Type: text/markdown

# VolterraSys: Linear and nonlinear Volterra kernels in natural and multiresolution bases

[![PyPI Version](https://img.shields.io/pypi/v/VolterraSys?label=PyPI&color=gold)](https://pypi.org/project/VolterraSys/)
[![Python Versions](https://img.shields.io/pypi/pyversions/VolterraSys)](https://pypi.org/project/VolterraSys/)
[![TensorFlow](https://img.shields.io/badge/tensorflow-required-darkorange)](https://www.tensorflow.org/)
[![License](https://img.shields.io/badge/license-Apache--2.0-deepgreen.svg?style=flat)](https://github.com/kkt-ee/VolterraSys/LICENSE)

`VolterraSys` provides TensorFlow/Keras layers for trainable linear and quadratic Volterra kernels in natural and multiresolution bases.

Copyright 2025 Kishore Kumar Tarafdar.
Licensed under the Apache License, Version 2.0. See [`LICENSE`](LICENSE).

## Capabilities

- Shift-variant 1D linear Volterra kernel: `LSVariantVolterra1D`.
- Shift-invariant linear Volterra kernels: `LSIVolterra1D`, `LSIVolterra2D`, `LSIVolterra3D`.
- Shift-invariant quadratic Volterra kernels: `QSIVolterra1D`, `QSIVolterra2D`, `QSIVolterra3D`.
- Natural-domain kernels with `wave=None`.
- Multiresolution kernels with wavelets such as `wave="haar"`.

## Limitations

- Inputs are TensorFlow tensors with channel-last layout.
- Multiresolution mode depends on `TFDWT`.
- Natural-domain computation uses `wave=None`; wavelet-domain computation uses a supported wavelet name.

## Installation

```bash
pip install VolterraSys
```

## Minimal Example

```python
import tensorflow as tf
from VolterraSys.LSIVolterra1D import LSIVolterra1D
from VolterraSys.LSIVolterra2D import LSIVolterra2D
from VolterraSys.LSIVolterra3D import LSIVolterra3D
from VolterraSys.QSIVolterra1D import QSIVolterra1D
from VolterraSys.QSIVolterra2D import QSIVolterra2D
from VolterraSys.QSIVolterra3D import QSIVolterra3D

# Natural-domain kernels
x1 = tf.random.normal([1, 32, 1])
y1 = LSIVolterra1D(filters=2, kernel_size=3, wave=None)(x1)

x2 = tf.random.normal([1, 8, 8, 1])
y2 = QSIVolterra2D(filters=2, kernel_size=2, wave=None)(x2)

x3 = tf.random.normal([1, 6, 6, 6, 1])
y3 = QSIVolterra3D(filters=2, kernel_size=2, wave=None)(x3)

print(y1.shape, y2.shape, y3.shape)
```

## Wavelet Mode

```python
layer = LSIVolterra2D(filters=1, kernel_size=4, wave="haar")
```

## 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 License 2.0. See [`LICENSE`](LICENSE).
