What is Cirkit? :electric_plug:

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 [^1], 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.

[^1]: Symbolic queries are especially useful when you want to combine the resulting circuit with other circuits.

Project Structure :open_file_folder:

.
├── 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. Install the latest release version via pip.

pip install libcirkit

For the latest development version, install from github after cloning this repository locally. To 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 :scroll:

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

[comment]: <> (The following bib file can be generated from the github page via the "C