Metadata-Version: 2.4
Name: torchrecurrent
Version: 0.2.0
Summary: A package for recurrent neural networks in PyTorch
Author-email: Francesco Martinuzzi <martinuzzi.francesco@gmail.com>
License: MIT
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: coverage; extra == "test"
Dynamic: license-file

<p align="center">
    <img width="400px" src="./docs/_static/logo.png"/>
</p>

<div align="center">
    <h2>TorchRecurrent</h2>
</div>

<div align="center">

[![PyPI](https://img.shields.io/pypi/v/torchrecurrent.svg)](https://pypi.org/project/torchrecurrent/)
[![codecov](https://codecov.io/gh/MartinuzziFrancesco/torchrecurrent/graph/badge.svg?token=AW36UWD1OM)](https://codecov.io/gh/MartinuzziFrancesco/torchrecurrent)
[![Build](https://github.com/MartinuzziFrancesco/torchrecurrent/actions/workflows/ci.yml/badge.svg)](https://github.com/MartinuzziFrancesco/torchrecurrent/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/Docs-gh--pages-blue?logo=github)](https://MartinuzziFrancesco.github.io/torchrecurrent/)
[![!python-versions](https://img.shields.io/pypi/pyversions/torchrecurrent)](https://www.python.org/)
[![code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![arXiv](https://img.shields.io/badge/arXiv-2510.21252-00b300.svg)](https://arxiv.org/abs/2510.21252)

</div>

**TorchRecurrent** is a PyTorch-compatible collection of recurrent neural network
cells and layers from across the research literature. It aims to provide
a unified, flexible interface that feels like native PyTorch while exposing
more customization options.

## Installation

```shell
pip install torchrecurrent
```

or on conda-forge

```shell
conda install -c conda-forge torchrecurrent
```
## Features

- 🔄 **30+ recurrent cells** (e.g. `LSTMCell`, `GRUCell`, and many specialized variants).
- 🏗️ **30+ recurrent layers** (e.g. `LSTM`, `GRU`, and counterparts for each cell).
- 🧩 **Unified API** — all cells/layers follow the PyTorch interface but add extra options
  for initialization and customization.
- 📚 **Comprehensive documentation** including API reference and a catalog of published models.

👉 Full model catalog: [torchrecurrent Models](https://martinuzzifrancesco.github.io/torchrecurrent/models.html)

## Quick Example

```python
import torch
from torchrecurrent import MGU #minimal gated unit

# sequence: (time_steps, batch, input_size)
inp = torch.randn(5, 3, 10)

# initialize a MGU with hidden_size=20
rnn = MGU(input_size=10, hidden_size=20, num_layers=3)

# forward pass
out, hidden = rnn(inp)

print(out.shape)  # (time_steps, batch, hidden_size)
```

## Citation

If you use TorchRecurrent in your work, please consider citing

```bibtex
@misc{martinuzzi2025unified,
  doi = {10.48550/ARXIV.2510.21252},
  url = {https://arxiv.org/abs/2510.21252},
  author = {Martinuzzi,  Francesco},
  keywords = {Machine Learning (cs.LG),  Software Engineering (cs.SE),  FOS: Computer and information sciences,  FOS: Computer and information sciences},
  title = {Unified Implementations of Recurrent Neural Networks in Multiple Deep Learning Frameworks},
  publisher = {arXiv},
  year = {2025},
  copyright = {Creative Commons Attribution 4.0 International}
}
```

## See also

[LuxRecurrentLayers.jl](https://github.com/MartinuzziFrancesco/LuxRecurrentLayers.jl):
Provides recurrent layers for Lux.jl in Julia.

[RecurrentLayers.jl](https://github.com/MartinuzziFrancesco/RecurrentLayers.jl):
Provides recurrent layers for Flux.jl in Julia.


[ReservoirComputing.jl](https://github.com/SciML/ReservoirComputing.jl):
Reservoir computing utilities for scientific machine learning.
Essentially gradient free trained recurrent neural networks.

## License

This project’s own code is distributed under the MIT License (see [LICENSE](LICENSE)). The primary intent of this software is academic research.

### Third-party Attributions

Some cells are re-implementations of published methods that carry their own licenses:
- **NASCell**: originally available under Apache 2.0 — see [LICENSE-Apache2.0.txt](licenses/Apache2.0.txt).

Please consult each of those licenses for your obligations when using this code in commercial or closed-source settings.


> ⚠️ **Disclaimer**: TorchRecurrent is an independent project and is not affiliated
with the PyTorch project or Meta AI. The name reflects compatibility with PyTorch,
not any official endorsement.
