README.md

What is Cirkit? 🔌

cirkit is a framework for building, learning and reasoning about probabilistic machine learning models, such as circuits and tensor networks, which are tractable ( ⬆️ ) and expressive ( ➡️ ).

Main Features

• ⚡ Exact and Efficient Inference : Support for tractable operations that are automatically compiled to efficient computational graphs that run on the GPU.
• Compatible: Seamlessly integrate your circuit with deep learning models; run on any device compatible with PyTorch.
• Modular and Extensible: Support for user-defined layers and parameterizations that extend the symbolic language of cirkit.
• Templates for Common Cases : Templates for constructing circuits by mixing layers and structures with a few lines of code.

Supported Model Families and Inference

Model Family	Queries	Notebook
📈 Monotonic Circuits	mar, con, sam, exp	Region Graphs
📷 PICs Circuits	mar, con, sam, exp	PICs
🆘 SoS Circuits	mar, con, exp	SoS

Supported Queries

The supported queries are tabulated below.

Abbreviation	Query	Math	Symbolic	PyTorch
mar	marginal	$\int p(\mathbf{x}, \mathbf{z}) d\mathbf{z}$	integrate	integrate query
con	conditional	$p(\mathbf{x} \mid \mathbf{z})$	integrate and evidence	integrate query
sam	sample	$\mathbf{x} \sim p(\mathbf{x})$	-	sampling query
exp	expectation	$\mathbb{E}_{\mathbf{x} \sim p(\mathbf{x})}\left [ f(\mathbf{x}) \right ] = \int p(\mathbf{x})f(\mathbf{x}) d\mathbf{x}$	multiply and integrate	-

Symbolic vs PyTorch

Queries can be implemented either symbolically, i.e. by constructing a new circuit which implements the query ¹, or by directly applying a query to a compiled circuit in PyTorch. In the latter case, the query is evaluated using a forward pass of the existing circuit.

Project Structure 📂

.
├── cirkit              Main Code
│   ├── backend         Circuits to Numerical Operations (Currently via PyTorch backend)
│   ├── symbolic        Circuits / Layers / Operators / Compilation
│   ├── templates       APIs for easy use (e.g. region graphs, data modalities)
│   └── utils
├── docs
├── notebooks           Start here: Examples
└── tests

How to Install the Library

cirkit currently requires Python 3.10 and PyTorch 2.3 or above versions. To start developing, install the virtual environment and activate it first.

virtualenv venv           # or python -m venv venv
source venv/bin/activate

Then install the required dependencies in development mode.

pip install -U pip        # update pip
pip install -e ".[dev]"

This will install not only the core dependencies of the library itself (e.g., PyTorch) but also additional dependencies useful for development (e.g., PyTest). It also installs other development tools, such as Black, PyLint and MyPy.

Additional Requirements for Jupyter Notebooks

If you want to execute the Jupyter notebooks in the notebooks/ directory, then install the additional dependencies with:

pip install ".[notebooks]"

Documentation 📘

For more details see the Documentation here.

Development 🛠️

Build Documentation Locally

Whenever you write documentation, you can check how it would look like by building HTML pages locally. To do so, install the dependencies for building documentation:

pip install ".[docs]"

Then, run the following at the root level of the repository directory.

mkdocs serve

After waiting a few seconds, you can then navigate the rendered documentation at the link http://127.0.0.1:8000/.

Automatic Code Formatting

We try to follow a consistent formatting across the library. If you want to automatically format your code, then you should run the following script.

bash scripts/format.sh

Linting and Static Code Checks

Locate youself in the repository root. Then, run the following for executing the linters and other static code checkers.

bash scripts/check.sh [--tool linting-tool] [file ...]

Optionally,

1. Specify --tool to select the linting tool to use. If no one is given, then all of them will be run, i.e., black, isort, pydocstyle, pylint, mypy.
2. Add files to lint part of the repo. If none is specified then, all tracked directiories will be checked.

Run Unit Tests and Check the Coverage

Locate youself in the repository root. Then, rn the following script.

bash scripts/coverage.sh [--FORMAT] [pytest_arg ...]

Optionally,

1. Use a --FORMAT (e.g. --xml) flag for exporting converage to file.
2. Pass additional args to pytest (files to test etc.).

Papers 📜

If you want to learn more about the internals of cirkit, a good starting point is What is the Relationship between Tensor Factorizations and Circuits (and How Can We Exploit it)?.

Papers Implemented in Cirkit

Papers	Links within Cirkit
🆘 Subtractive Mixture Models via Squaring: Representation and Learning	SoS notebook
🆘 Sum of Squares Circuits	SoS notebook
📷 Probabilistic Integral Circuits	PICs notebook
📷 Scaling Continuous Latent Variable Models as Probabilistic Integral Circuits	PICs notebook
What is the Relationship between Tensor Factorizations and Circuits (and How Can We Exploit it)?	See Region Graphs and Folding
Random Sum-Product Networks: A Simple and Effective Approach to Probabilistic Deep Learning	See Random Binary Tree
Einsum Networks: Fast and Scalable Learning of Tractable Probabilistic Circuits	See Optimizing the Circuit Layers

Citation

If you use cirkit in your publications, please cite:

@software{The_APRIL_Lab_cirkit_2024,
author = {The APRIL Lab},
license = {GPL-3.0},
month = oct,
title = {{cirkit}},
url = {https://github.com/april-tools/cirkit},
version = {0.1},
year = {2024}
}

Footnotes

1. Symbolic queries are especially useful when you want to combine the resulting circuit with other circuits. ↩