torchrecurrent 0.1.11
A package for recurrent neural networks in PyTorch
License: MIT
Requires Python: >=3.9

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

</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
```

Coming soon to conda-forge as well!

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


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