https://github.com/ml-kuleuven/klay
Sparse Circuits on the GPU (ICLR2025)
https://github.com/ml-kuleuven/klay
arithmetic-circuits neurosymbolic neurosymbolic-ai probabilistic-circuits probabilistic-inference tractable-inference tractable-models
Last synced: 3 months ago
JSON representation
Sparse Circuits on the GPU (ICLR2025)
- Host: GitHub
- URL: https://github.com/ml-kuleuven/klay
- Owner: ML-KULeuven
- License: apache-2.0
- Created: 2024-06-20T08:19:18.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2026-03-05T15:38:56.000Z (3 months ago)
- Last Synced: 2026-03-05T16:14:51.417Z (3 months ago)
- Topics: arithmetic-circuits, neurosymbolic, neurosymbolic-ai, probabilistic-circuits, probabilistic-inference, tractable-inference, tractable-models
- Language: Python
- Homepage: https://klaycircuits.readthedocs.io/en/latest/index.html
- Size: 9.4 MB
- Stars: 21
- Watchers: 2
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Citation: CITATION.cff
Awesome Lists containing this project
README
# KLay
[](https://www.python.org/downloads/release/python-3100/)
[](https://opensource.org/licenses/Apache-2.0)
[](https://github.com/ML-KULeuven/klay/actions/workflows/main.yml)
[](https://pepy.tech/projects/klaycircuits)
__KLay is a Python library for evaluating sparse circuits on the GPU.__
To get started, install KLay using pip and check out the [documentation](https://klaycircuits.readthedocs.io/en/latest/). You can also refer to [this video](https://www.youtube.com/watch?v=ZCpDenbGoJ4) or [the paper](https://openreview.net/pdf?id=Zes7Wyif8G) for more information.
```bash
pip install klaycircuits
```
KLay features:
- GPU acceleration of circuits using Jax or PyTorch.
- Loading SDD and d-DNNF circuits compiled by [PySDD](https://github.com/ML-KULeuven/PySDD) or [D4](https://github.com/crillab/d4).
- Evaluation in various semirings (e.g. real, log, tropical).
- Propagating constants and merging duplicate nodes.
## 🧪 Tests
Run the test suite from the project root:
```bash
pytest tests/
```
Tests are split by backend. They are automatically skipped if the required backend is not installed:
- `tests/test_manual.py`, `tests/fuzzer_torch.py`, `tests/fuzzer_torch_multi.py`, `tests/fuzzer_creation.py` — require PyTorch
- `tests/fuzzer_jax.py` — requires JAX
- `tests/test_compression.py` — no backend required
## 📊 Benchmarks
Benchmarks live in the `benchmark/` directory. Run from the project root with:
```bash
python -m benchmark.benchmark_wmc --benchmark sdd --target torch -v 100 200 500
python -m benchmark.benchmark_wmc --benchmark sdd --target jax -v 100 200 500
python -m benchmark.benchmark_wmc --benchmark sdd --target pysdd -v 100 200 500
```
Key options:
| Flag | Description |
|------|-------------|
| `-b` / `--benchmark` | Circuit type: `sdd` or `d4` |
| `-t` / `--target` | Backend: `torch`, `jax`, or `pysdd` |
| `-v` / `--nb_vars` | Number of variables (one or more) |
| `-d` / `--device` | Device: `cpu`, `cuda`, `cuda:0`, etc. |
| `-s` / `--semiring` | Semiring: `log` (default) or `real` |
| `-r` / `--nb_repeats` | Number of seeds to average over (default: 1) |
Results are saved as JSON files under `results/`.
## 📃 Paper
If you use KLay in your research, consider citing [our paper](https://openreview.net/pdf?id=Zes7Wyif8G).
To replicate the exact results and figures of the paper, use [this code](https://github.com/ML-KULeuven/klay/tree/d3b81491c34603ba9271d25af7c789d3ba368ede).
```bibtex
@inproceedings{
maene2025klay,
title={{KL}ay: Accelerating Arithmetic Circuits for Neurosymbolic {AI}},
author = {Maene, Jaron and Derkinderen, Vincent and Zuidberg Dos Martires, Pedro},
booktitle={The Thirteenth International Conference on Learning Representations},
year={2025},
url={https://openreview.net/forum?id=Zes7Wyif8G}
}
```