Metadata-Version: 2.4
Name: ConvIIR
Version: 0.0.1
Summary: Separable D-dimensional IIR filters for Deep Convolutional Graphs
Project-URL: Homepage, https://github.com/kkt-ee/ConvIIR
Project-URL: Issues, https://github.com/kkt-ee/ConvIIR/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: numpy
Requires-Dist: tensorflow>=2.15
Description-Content-Type: text/markdown

# ConvIIR: Separable IIR Layers for Deep Convolutional Networks

[![PyPI Version](https://img.shields.io/pypi/v/ConvIIR?label=PyPI&color=gold)](https://pypi.org/project/ConvIIR/)
[![Python Versions](https://img.shields.io/pypi/pyversions/ConvIIR)](https://pypi.org/project/ConvIIR/)
[![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)](LICENSE)

`ConvIIR` provides TensorFlow/Keras separable IIR convolution layers for 2D and 3D inputs.

Copyright 2025 Kishore Kumar Tarafdar.
Acknowledgement: 2D layer development support with credit to Ayush Raisoni.
Licensed under the Apache License, Version 2.0. See [`LICENSE`](LICENSE).

## Capabilities

- Stable direct-form I separable IIR convolution: `IIRConv2DStable`, `IIRConv3DStable`.
- Direct-form II separable IIR convolution: `IIRConv2DDFII`, `IIRConv3DDFII`.
- Keras-compatible layers for channel-last 2D and 3D tensors.
- Optional UNet-style 2D network blocks built from ConvIIR layers.

## Limitations

- The core public API is the DF-I and DF-II 2D/3D IIR convolution layers.
- Experimental Wave+ViT helpers are not documented as public API in this package.
- Inputs are expected to use TensorFlow/Keras channel-last layout.

## Installation

```bash
pip install ConvIIR
```

## Minimal Example

```python
import tensorflow as tf
from ConvIIR.SeparableIIRDFI2D import IIRConv2DStable
from ConvIIR.SeparableIIRDFI3D import IIRConv3DStable

x2 = tf.random.normal([1, 32, 32, 1])
y2 = IIRConv2DStable(filters=4, kernel_size=(3, 3), ar_order=2, ma_order=2)(x2)

x3 = tf.random.normal([1, 16, 16, 16, 1])
y3 = IIRConv3DStable(filters=2, kernel_size=(3, 3, 3), ar_order=2, ma_order=2)(x3)

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

## Module Imports

```python
from ConvIIR.SeparableIIRDFI2D import IIRConv2DStable
from ConvIIR.SeparableIIRDFI3D import IIRConv3DStable
from ConvIIR.SeparableIIRDFII2D import IIRConv2DDFII
from ConvIIR.SeparableIIRDFII3D import IIRConv3DDFII
```

## 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).
