[](https://www.gnu.org/licenses/gpl-3.0)
[](https://www.python.org/downloads/release/python-3100/)
[](https://cirkit-docs.readthedocs.io/en/latest/?badge=latest)
[](https://codecov.io/gh/april-tools/cirkit)
# What is Cirkit? :electric_plug:
**cirkit** is a framework for building, learning and reasoning about **probabilistic machine learning** models, such as [circuits](https://arxiv.org/abs/2409.07953) and [tensor networks](https://arxiv.org/abs/1708.00006), 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](https://arxiv.org/abs/2409.07953) | mar, con, sam, exp | [Region Graphs](https://github.com/april-tools/cirkit/blob/main/notebooks/region-graphs-and-parametrisation.ipynb) |
| [📷 PICs Circuits](https://arxiv.org/abs/2406.06494) | mar, con, sam, exp | [PICs](https://github.com/april-tools/cirkit/blob/main/notebooks/learning-a-circuit-with-pic.ipynb) |
| [🆘 SoS Circuits](https://arxiv.org/abs/2408.11778) | mar, con, exp | [SoS](https://github.com/april-tools/cirkit/blob/main/notebooks/sum-of-squares-circuits.ipynb) |
## Supported Queries
The supported queries are tabulated below.
| **Abbreviation** | **Query** | **Math** | **[Symbolic](https://cirkit-docs.readthedocs.io/en/latest/api/cirkit/symbolic/functional/)** | **[PyTorch](https://cirkit-docs.readthedocs.io/en/latest/api/cirkit/backend/torch/queries/)** |
| :-------: | :---------: | --------------------------------------------- | :-------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------: |
| 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.
To start developing, install the virtual environment and activate it first.
```shell
virtualenv venv # or python -m venv venv
source venv/bin/activate
```
Then install the required dependencies in [development mode](https://setuptools.pypa.io/en/latest/userguide/development_mode.html).
```shell
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:
```shell
pip install ".[notebooks]"
```
## Documentation 📘
For more details [see the Documentation here](https://cirkit-docs.readthedocs.io/en/latest/).
## 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:
```shell
pip install ".[docs]"
```
Then, run the following at the root level of the repository directory.
```shell
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.
```shell
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.
```shell
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.
```shell
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)?](https://arxiv.org/abs/2409.07953).
## Papers Implemented in Cirkit
| **Papers** | **Links within Cirkit** |
|--------------------|------------------------|
| [🆘 Subtractive Mixture Models via Squaring: Representation and Learning](https://april-tools.github.io/publications/loconte2023subtractive) | [SoS notebook](https://github.com/april-tools/cirkit/blob/main/notebooks/sum-of-squares-circuits.ipynb) |
| [🆘 Sum of Squares Circuits](https://april-tools.github.io/publications/loconte2024sos) | [SoS notebook](https://github.com/april-tools/cirkit/blob/main/notebooks/sum-of-squares-circuits.ipynb) |
| [📷 Probabilistic Integral Circuits](https://april-tools.github.io/publications/gala2023pic) | [PICs notebook](https://github.com/april-tools/cirkit/blob/main/notebooks/learning-a-circuit-with-pic.ipynb) |
| [📷 Scaling Continuous Latent Variable Models as Probabilistic Integral Circuits](https://april-tools.github.io/publications/gala2024tenpics) | [PICs notebook](https://github.com/april-tools/cirkit/blob/main/notebooks/learning-a-circuit-with-pic.ipynb) |
| [What is the Relationship between Tensor Factorizations and Circuits (and How Can We Exploit it)?](https://april-tools.github.io/publications/loconte2024tfpc) | See [Region Graphs](https://github.com/april-tools/cirkit/blob/main/notebooks/region-graphs-and-parametrisation.ipynb) and [Folding](https://github.com/april-tools/cirkit/blob/main/notebooks/compilation-options.ipynb)|
| [Random Sum-Product Networks: A Simple and Effective Approach to Probabilistic Deep Learning](https://proceedings.mlr.press/v115/peharz20a) | See [Random Binary Tree](https://github.com/april-tools/cirkit/blob/main/notebooks/region-graphs-and-parametrisation.ipynb) |
| [Einsum Networks: Fast and Scalable Learning of Tractable Probabilistic Circuits](https://arxiv.org/abs/2004.06231) | See [Optimizing the Circuit Layers](https://github.com/april-tools/cirkit/blob/main/notebooks/compilation-options.ipynb) |
## Citation
[comment]: <> (The following bib file can be generated from the github page via the "Cite this repository" button. To update bib, simply update the CITATIONS.cff file by uploading current cff file to https://citation-file-format.github.io/ and modifying it )
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}
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "libcirkit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "probabilistic-modeling, tractable-models, probabilistic-inference, probabilistic-circuits, probabilistic-machine-learning, probabilistic-reasoning, tensor-network-decompositions, tractable-inference, tensor-net",
"author": "The APRIL Lab.",
"author_email": null,
"download_url": null,
"platform": null,
"description": "[](https://www.gnu.org/licenses/gpl-3.0)\n[](https://www.python.org/downloads/release/python-3100/)\n[](https://cirkit-docs.readthedocs.io/en/latest/?badge=latest)\n[](https://codecov.io/gh/april-tools/cirkit)\n\n\n\n\n# What is Cirkit? :electric_plug:\n\n\n**cirkit** is a framework for building, learning and reasoning about **probabilistic machine learning** models, such as [circuits](https://arxiv.org/abs/2409.07953) and [tensor networks](https://arxiv.org/abs/1708.00006), which are **tractable** ( \u2b06\ufe0f ) and **expressive** ( \u27a1\ufe0f ).\n\n\n\n\n\n# Main Features\n\n* \u26a1 **Exact and Efficient Inference** : Support for tractable operations that are automatically compiled to efficient computational graphs that run on the GPU.\n* **Compatible**: Seamlessly integrate your circuit with deep learning models; run on any device compatible with PyTorch.\n* **Modular and Extensible**: Support for user-defined layers and parameterizations that extend the symbolic language of cirkit.\n* **Templates for Common Cases** : Templates for constructing circuits by mixing layers and structures with a few lines of code.\n\n\n## Supported Model Families and Inference\n\n| **Model Family** | **Queries** | **Notebook** |\n| :-------------------------------------------------------: | ------------------ | ------------------------------------------------------------------------------------------------------------------ |\n| [\ud83d\udcc8 Monotonic Circuits](https://arxiv.org/abs/2409.07953) | mar, con, sam, exp | [Region Graphs](https://github.com/april-tools/cirkit/blob/main/notebooks/region-graphs-and-parametrisation.ipynb) |\n| [\ud83d\udcf7 PICs Circuits](https://arxiv.org/abs/2406.06494) | mar, con, sam, exp | [PICs](https://github.com/april-tools/cirkit/blob/main/notebooks/learning-a-circuit-with-pic.ipynb) |\n| [\ud83c\udd98 SoS Circuits](https://arxiv.org/abs/2408.11778) | mar, con, exp | [SoS](https://github.com/april-tools/cirkit/blob/main/notebooks/sum-of-squares-circuits.ipynb) |\n\n## Supported Queries\n\nThe supported queries are tabulated below.\n\n| **Abbreviation** | **Query** | **Math** | **[Symbolic](https://cirkit-docs.readthedocs.io/en/latest/api/cirkit/symbolic/functional/)** | **[PyTorch](https://cirkit-docs.readthedocs.io/en/latest/api/cirkit/backend/torch/queries/)** |\n| :-------: | :---------: | --------------------------------------------- | :-------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------: |\n| mar | marginal | $\\int p(\\mathbf{x}, \\mathbf{z}) d\\mathbf{z}$ | integrate | integrate query |\n| con | conditional | $p(\\mathbf{x} \\mid \\mathbf{z})$ | integrate and evidence | integrate query |\n| sam | sample | $\\mathbf{x} \\sim p(\\mathbf{x})$ | - | sampling query |\n| 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 | - |\n\n### Symbolic vs PyTorch\nQueries 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.\n\n[^1]: Symbolic queries are especially useful when you want to combine the resulting circuit with other circuits.\n\n## Project Structure :open_file_folder:\n\n```\n.\n\u251c\u2500\u2500 cirkit Main Code\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 backend Circuits to Numerical Operations (Currently via PyTorch backend)\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 symbolic Circuits / Layers / Operators / Compilation\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 templates APIs for easy use (e.g. region graphs, data modalities)\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 utils\n\u251c\u2500\u2500 docs\n\u251c\u2500\u2500 notebooks Start here: Examples\n\u2514\u2500\u2500 tests\n```\n\n## How to Install the Library\n\ncirkit currently requires Python 3.10 and PyTorch 2.3 or above versions.\nTo start developing, install the virtual environment and activate it first.\n```shell\nvirtualenv venv # or python -m venv venv\nsource venv/bin/activate\n```\nThen install the required dependencies in [development mode](https://setuptools.pypa.io/en/latest/userguide/development_mode.html).\n```shell\npip install -U pip # update pip\npip install -e \".[dev]\"\n```\nThis will install not only the core dependencies of the library itself (e.g., PyTorch) but also additional dependencies useful for development (e.g., PyTest).\nIt also installs other development tools, such as Black, PyLint and MyPy.\n\n### Additional Requirements for Jupyter Notebooks\n\nIf you want to execute the Jupyter notebooks in the ```notebooks/``` directory, then install the additional dependencies with:\n```shell\npip install \".[notebooks]\"\n```\n\n## Documentation \ud83d\udcd8\n\nFor more details [see the Documentation here](https://cirkit-docs.readthedocs.io/en/latest/).\n\n\n## Development \ud83d\udee0\ufe0f\n\n### Build Documentation Locally\n\nWhenever you write documentation, you can check how it would look like by building HTML pages locally.\nTo do so, install the dependencies for building documentation:\n\n```shell\npip install \".[docs]\"\n```\n\nThen, run the following at the root level of the repository directory.\n\n```shell\nmkdocs serve\n```\n\nAfter waiting a few seconds, you can then navigate the rendered documentation at the link http://127.0.0.1:8000/.\n\n### Automatic Code Formatting\n\nWe try to follow a consistent formatting across the library.\nIf you want to automatically format your code, then you should run the following script.\n\n```shell\nbash scripts/format.sh\n```\n\n### Linting and Static Code Checks\n\nLocate youself in the repository root.\nThen, run the following for executing the linters and other static code checkers.\n\n```shell\nbash scripts/check.sh [--tool linting-tool] [file ...]\n```\nOptionally,\n1. 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.\n2. Add files to lint part of the repo. If none is specified then, all tracked directiories will be checked. \n\n### Run Unit Tests and Check the Coverage \n\nLocate youself in the repository root.\nThen, rn the following script.\n\n```shell\nbash scripts/coverage.sh [--FORMAT] [pytest_arg ...]\n```\nOptionally,\n1. Use a `--FORMAT` (e.g. `--xml`) flag for exporting converage to file.\n2. Pass additional args to pytest (files to test etc.).\n\n\n## Papers :scroll:\n\n\nIf 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)?](https://arxiv.org/abs/2409.07953).\n\n\n## Papers Implemented in Cirkit\n\n| **Papers** | **Links within Cirkit** |\n|--------------------|------------------------|\n| [\ud83c\udd98 Subtractive Mixture Models via Squaring: Representation and Learning](https://april-tools.github.io/publications/loconte2023subtractive) | [SoS notebook](https://github.com/april-tools/cirkit/blob/main/notebooks/sum-of-squares-circuits.ipynb) |\n| [\ud83c\udd98 Sum of Squares Circuits](https://april-tools.github.io/publications/loconte2024sos) | [SoS notebook](https://github.com/april-tools/cirkit/blob/main/notebooks/sum-of-squares-circuits.ipynb) |\n| [\ud83d\udcf7 Probabilistic Integral Circuits](https://april-tools.github.io/publications/gala2023pic) | [PICs notebook](https://github.com/april-tools/cirkit/blob/main/notebooks/learning-a-circuit-with-pic.ipynb) |\n| [\ud83d\udcf7 Scaling Continuous Latent Variable Models as Probabilistic Integral Circuits](https://april-tools.github.io/publications/gala2024tenpics) | [PICs notebook](https://github.com/april-tools/cirkit/blob/main/notebooks/learning-a-circuit-with-pic.ipynb) |\n| [What is the Relationship between Tensor Factorizations and Circuits (and How Can We Exploit it)?](https://april-tools.github.io/publications/loconte2024tfpc) | See [Region Graphs](https://github.com/april-tools/cirkit/blob/main/notebooks/region-graphs-and-parametrisation.ipynb) and [Folding](https://github.com/april-tools/cirkit/blob/main/notebooks/compilation-options.ipynb)|\n| [Random Sum-Product Networks: A Simple and Effective Approach to Probabilistic Deep Learning](https://proceedings.mlr.press/v115/peharz20a) | See [Random Binary Tree](https://github.com/april-tools/cirkit/blob/main/notebooks/region-graphs-and-parametrisation.ipynb) |\n| [Einsum Networks: Fast and Scalable Learning of Tractable Probabilistic Circuits](https://arxiv.org/abs/2004.06231) | See [Optimizing the Circuit Layers](https://github.com/april-tools/cirkit/blob/main/notebooks/compilation-options.ipynb) |\n\n\n## Citation\n\n[comment]: <> (The following bib file can be generated from the github page via the \"Cite this repository\" button. To update bib, simply update the CITATIONS.cff file by uploading current cff file to https://citation-file-format.github.io/ and modifying it )\n\nIf you use cirkit in your publications, please cite:\n\n```\n@software{The_APRIL_Lab_cirkit_2024,\nauthor = {The APRIL Lab},\nlicense = {GPL-3.0},\nmonth = oct,\ntitle = {{cirkit}},\nurl = {https://github.com/april-tools/cirkit},\nversion = {0.1},\nyear = {2024}\n}\n```\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "a python framework to build, learn and reason about probabilistic circuits and tensor networks",
"version": "0.2.0",
"project_urls": {
"Bug Tracker": "https://github.com/april-tools/cirkit/issues",
"Coverage": "https://app.codecov.io/gh/april-tools/cirkit",
"Documentation": "https://cirkit-docs.readthedocs.io",
"Homepage": "https://github.com/april-tools/cirkit"
},
"split_keywords": [
"probabilistic-modeling",
" tractable-models",
" probabilistic-inference",
" probabilistic-circuits",
" probabilistic-machine-learning",
" probabilistic-reasoning",
" tensor-network-decompositions",
" tractable-inference",
" tensor-net"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8e64324c2cc6446b43b74eb1b02e69439bac596cc24dd2b438a7e1f53f345e59",
"md5": "228cefdb478f5d2b6afce7e99ff68d2d",
"sha256": "7fca801523e2d6355c5a27dada9105acb45c53a8e7fa16bd34309d4ef09a840f"
},
"downloads": -1,
"filename": "libcirkit-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "228cefdb478f5d2b6afce7e99ff68d2d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 155847,
"upload_time": "2024-12-17T18:24:42",
"upload_time_iso_8601": "2024-12-17T18:24:42.765891Z",
"url": "https://files.pythonhosted.org/packages/8e/64/324c2cc6446b43b74eb1b02e69439bac596cc24dd2b438a7e1f53f345e59/libcirkit-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-17 18:24:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "april-tools",
"github_project": "cirkit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "libcirkit"
}
JSON
