Metadata-Version: 2.4
Name: relucent
Version: 1.0.0
Summary: Explore the polyhedral complexes of ReLU neural networks.
Keywords: relu,neural networks,polyhedral complex,linear regions,decision boundary,topology,betti numbers,persistent homology
Author: Blake B. Gaines
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Requires-Dist: gurobipy>=12,<14
Requires-Dist: networkx>=3.0
Requires-Dist: numpy>=2.0
Requires-Dist: plotly>=5.20
Requires-Dist: scipy>=1.13
Requires-Dist: tqdm>=4.60
Requires-Dist: pytest>=9.0.2 ; extra == 'dev'
Requires-Dist: ruff ; extra == 'dev'
Requires-Dist: basedpyright>=1.39.0 ; extra == 'dev'
Requires-Dist: sphinx>=9.0.4 ; extra == 'docs'
Requires-Dist: sphinx-rtd-theme ; extra == 'docs'
Requires-Dist: torch>=2.5.0 ; extra == 'torch'
Requires-Python: >=3.11
Project-URL: Repository, https://github.com/bl-ake/relucent
Project-URL: Documentation, https://bl-ake.github.io/relucent/
Project-URL: Changelog, https://github.com/bl-ake/relucent/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/bl-ake/relucent/issues
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: torch
Description-Content-Type: text/markdown



![Relucent](https://raw.githubusercontent.com/bl-ake/relucent/main/docs/title.svg)

<div align="center">


[![Usable](https://github.com/bl-ake/relucent/actions/workflows/python-package.yml/badge.svg)](https://github.com/bl-ake/relucent/actions/workflows/python-package.yml)
[![Latest Release](https://img.shields.io/github/v/tag/bl-ake/relucent?label=Latest%20Release)](https://github.com/bl-ake/relucent/releases)

</div>

Relucent is a Python package for computing the polyhedra of ReLU networks! Its main features include:
- Distributed calculation of the activation regions of ReLU networks via local search
- Visualization of ReLU complexes in two or three dimensions with [Plotly](https://plotly.com/python/)
- Conversion of [PyTorch](https://docs.pytorch.org/tutorials/beginner/basics/quickstart_tutorial.html) networks built from `Linear`, `ReLU`, `Conv2d`, `AvgPool2d`, `Flatten` and `Dropout` layers, checked against the network's own forward pass
- Computation of the complex's dual as a [NetworkX](https://networkx.org/documentation/stable/tutorial.html) Graph
- Topology of the complex and of decision boundaries over GF(2): Betti numbers, persistent homology, and PL Morse critical points
- Various calculations for individual activation regions, decision boundaries, and affine splines

## Environment Setup 
- Core package only (without PyTorch): `pip install relucent`
- With PyTorch support: `pip install "relucent[torch]"`
  - Note: Supports PyTorch `>=2.5.0` ([PyTorch install guide](https://pytorch.org/get-started/locally/))

### Development Check Modes

- With torch (full checks): `pip install ".[dev,torch]" && pytest`
- Without torch (optional-dependency compatibility): `pip install ".[dev]" && pytest tests/test_no_torch.py`

## Getting Started
To see if the installation has been successful, try plotting the complex of a randomly initialized network in 2 dimensions like this:

```python
import numpy as np
import torch.nn as nn
import relucent

if __name__ == "__main__":
    # Create Model
    network = nn.Sequential(
        nn.Linear(2, 10),
        nn.ReLU(),
        nn.Linear(10, 5),
        nn.ReLU(),
        nn.Linear(5, 1),
    )  ## or conveniently, relucent.mlp(widths=[2, 10, 5, 1])

    ## Initialize a Complex to track calculations
    cplx = relucent.Complex(network)

    ## Calculate the activation regions via local search
    cplx.bfs()

    ## Plotting functions return Plotly figures
    fig = cplx.plot()
    fig.show()
```

Given some input point, you could get a minimal H-representation of the polyhedral region containing it like this:
```python
input_point = np.random.random((1, 2))
p = cplx.point2poly(input_point)
print(p.halfspaces[p.shis])
```
Attributes like `p.halfspaces` (halfspaces of the form Ax + b <= 0, in format [A; b], induced by each neuron), `p.shis` (the indices of the non-redundant halfspaces), and `p.center` (the Chebyshev center) are computed lazily.

You could also check the average number of faces of all polyhedra with:
```python
sum(len(p.shis) for p in cplx) / len(cplx)
```
Or, get the adjacency graph of top-dimensional cells in the complex with:
```python
print(cplx.dual_graph())
```

You can view the full documentation for this library at https://bl-ake.github.io/relucent/. Upgrading from 0.9? See [Stability and migrating to 1.0](https://bl-ake.github.io/relucent/migrating.html).

## Obtaining a Gurobi License
`pip install relucent` installs the [Gurobi Python library](https://pypi.org/project/gurobipy/), which works for most applications without a [license](https://support.gurobi.com/hc/en-us/articles/12872879801105-How-do-I-retrieve-and-set-up-a-Gurobi-license). However, without one, Gurobi will only work with a limited feature set. This includes a limit on the number of decision variables in the models it can solve, which limits the size of the networks this code is able to analyze. There are multiple ways to install the software, but we recommend the following steps to those eligible for an academic license:
0. Create a fresh Python environment using a distribution of [Anaconda](https://mamba.readthedocs.io/en/latest/index.html).
1. Install the [Gurobi Python library](https://pypi.org/project/gurobipy/) using `conda install -c gurobi gurobi`, before installing relucent, so that pip uses this copy.
2. [Obtain a Gurobi license](https://support.gurobi.com/hc/en-us/articles/360040541251-How-do-I-obtain-a-free-academic-license) (Note: a WLS license will limit the number of concurrent sessions across multiple devices, which can result in slowdowns when using this library on different machines simultaneously.)
3. In your Conda environment, run `grbgetkey` followed by your license key
4. Install relucent and complete the remaining steps in [Getting Started](#getting-started)

## Citing this Package
If you run into any problems or have any feature requests, please create an issue on the project's [Github](https://github.com/bl-ake/relucent). If you want to credit its use in your research, please cite our [paper](https://openreview.net/forum?id=TgLW2DiRDG).

```
@inproceedings{
  gaines2026characterizing,
  title={Characterizing the Discrete Geometry of Re{LU} Networks},
  author={Blake B. Gaines and Jinbo Bi},
  booktitle={The Fourteenth International Conference on Learning Representations},
  year={2026},
  url={https://openreview.net/forum?id=TgLW2DiRDG}
}
```

## Related Software:
Please check out the amazing software created by others working in this area. Depending on your goal, some of these could be even better!
- [CanonicalPoly 2.0](https://github.com/mmasden/canonicalpoly2.0) by Marissa Masden ([Paper](https://doi.org/10.1137/24M1646996))
- [GoL Toolbox](https://github.com/cglrtrgy/GoL_Toolbox) by Turgay Caglar ([Paper](https://doi.org/10.3389/fdata.2023.1274831))
- [Neural Network Elements](https://github.com/gtri/neural-network-elements) by Andrew Tawfeek ([Paper](https://doi.org/10.48550/arXiv.2510.12700))
- [ReLU Edge Subdivision](https://github.com/arturs-berzins/relu_edge_subdivision) by Arturs Berzins ([Paper](https://proceedings.mlr.press/v202/berzins23a.html))
- [SplineCam](https://github.com/AhmedImtiazPrio/SplineCAM) by Ahmed Imtiaz Humayun ([Paper](https://doi.org/10.48550/arXiv.2302.12828))

## Bibliography
This package was made possible by the following work:
  - Brooks, R., & Masden, M. (2024). Combinatorial Regularity for Relatively Perfect Discrete Morse Gradient Vector Fields of ReLU Neural Networks. arXiv:2412.18005. https://doi.org/10.48550/arXiv.2412.18005
  - Fukuda, K. (2004, August 26). Frequently Asked Questions in Polyhedral Computation. https://people.inf.ethz.ch/~fukudak/polyfaq/
  - Grigsby, J. E., & Lindsey, K. (2022). On Transversality of Bent Hyperplane Arrangements and the Topological Expressiveness of ReLU Neural Networks. SIAM Journal on Applied Algebra and Geometry, 6(2), 216–242. https://doi.org/10.1137/20M1368902
  - Liu, Y., Caglar, T., Peterson, C., & Kirby, M. (2023). Integrating geometries of ReLU feedforward neural networks. Frontiers in Big Data, 6, 1274831. https://doi.org/10.3389/fdata.2023.1274831
  - Liu, Y., Cole, C. M., Peterson, C., & Kirby, M. (2023). ReLU Neural Networks, Polyhedral Decompositions, and Persistent Homology. TAG-ML. https://proceedings.mlr.press/v221/liu23a.html
  - Masden, M. (2025). Algorithmic Determination of the Combinatorial Structure of the Linear Regions of ReLU Neural Networks. SIAM Journal on Applied Algebra and Geometry, 9(2), 374–404. https://doi.org/10.1137/24M1646996
  - Xu, S., Vaughan, J., Chen, J., Zhang, A., & Sudjianto, A. (2022). Traversing the Local Polytopes of ReLU Neural Networks. The AAAI-22 Workshop on Adversarial Machine Learning and Beyond. https://openreview.net/forum?id=EQjwT2-Vaba
  - Zhang, X., & Wu, D. (2019, September 25). Empirical Studies on the Properties of Linear Regions in Deep Neural Networks. International Conference on Learning Representations. https://openreview.net/forum?id=SkeFl1HKwr
