From f523a0c9fd19a85c248065d126f8ac60b07e3c17 Mon Sep 17 00:00:00 2001 From: spefk Date: Sun, 25 Jan 2026 16:07:35 +0300 Subject: [PATCH 1/4] snapshot --- README.md | 192 ++++++++++++++++--------------------------- README_DEV.md | 19 ++++- README_PYPI.md | 41 --------- pyproject.toml | 2 +- tutorial/01_intro.py | 25 ++++++ 5 files changed, 113 insertions(+), 166 deletions(-) delete mode 100644 README_PYPI.md create mode 100644 tutorial/01_intro.py diff --git a/README.md b/README.md index edd77f9..71d428d 100644 --- a/README.md +++ b/README.md @@ -1,156 +1,102 @@ # Cirbo: A New Tool for Boolean Circuit Analysis and Synthesis -## Environment setup +Cirbo is a Python library that provides methods for +Boolean circuit manipulation, analysis, and synthesis + +Usage example +```py +from cirbo.core import Circuit, Gate, gate +from cirbo.synthesis.generation.arithmetics import add_sum_n_bits + +# Create an empty circuit with 6 inputs. +ckt = Circuit.bare_circuit(input_size=6) +# Generate and connect a "gadget" subcircuit +# that computes the sum of the input bits. +b0, b1, b2 = add_sum_n_bits(ckt, ckt.inputs) +# Manually add gates that yield True only +# if at least half of the inputs are True. +ckt.add_gate(Gate('a0', gate.AND, (b0, b1))) +ckt.add_gate(Gate('a1', gate.OR, ('a0', b2))) +ckt.mark_as_output('a1') + +# Calculate general boolean function properties. +print(f"Is monotone: {ckt.is_monotone()}") +print(f"Is symmetric: {ckt.is_symmetric()}") +print(f"Is constant: {ckt.is_constant()}") + +# Draw the graph and show the image in the default viewer. +ckt.view_graph() +``` + +More examples are available in the [tutorial](https://github.com/SPbSAT/cirbo/tree/main/tutorial). -`Python 3.9` is used to cover all currently [maintained Python versions](https://devguide.python.org/versions/). +## Installation -Package was tested on `Ubuntu` and `Mac OS Ventura 13` machines. +The package is currently available on Test PyPI and will be published on PyPI after testing. -1. Update submodules `git submodule update --init --recursive` -1. Install following packages using your package manager: - - dev version of `python3.9-dev` and `python3.9-distutils` - - `build-essential` package for Ubuntu. - - `cmake` and suitable C++ compiler, e.g. `gcc` - - `graphviz` library +To install the package from Test PyPI into your virtual environment, run: - Command for Ubuntu: - ```shell - sudo apt install python3-dev python3.9-dev python3.9-distutils gcc cmake graphviz build-essential - ``` - - > Note: python3.9 is unavailable in latest versions of Ubuntu, so `deadsnakes` - > ppa may be useful: https://launchpad.net/~deadsnakes/+archive/ubuntu/ppa +```sh +python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ cirbo +``` -1. Install `poetry` ([official instruction](https://python-poetry.org/docs/)) (`cirbo` requires `poetry` version to be `>= 2.0.0`) -1. Build dist with extensions locally by running `poetry build` +Instructions on how to set up the development environment are provided in the separate [dev README](README_DEV.md). - > Note: building `ABC` extension may take long time, one can skip it - > using `(export DISABLE_ABC_CEXT=1 && poetry build && poetry install)` - > command. +## Documentation -1. Setup virtual environment by running `poetry install` -1. Execute `poetry env activate` -1. Enable virtual environment using command, which was printed by previous command. +The main library features are described in the paper "Cirbo: A New Tool for Boolean Circuit Analysis and Synthesis" ([arXiv](https://arxiv.org/abs/2412.14933), [AAAI-25](https://ojs.aaai.org/index.php/AAAI/article/view/33207)). -> Note: it may be necessary to restart an IDE after extensions -> are built and installed to refresh its index and stubs. +Currently, `cirbo` does not have web-hosted documentation, but it can be built locally using Sphinx (see the [dev README](README_DEV.md) for details). ## Package structure -Some features of a package are demonstrated in the special modules located in -the `tutorial/` directory. The same code snippets are used in the paper's listings. -This is probably a first place that should be explored after environment is set up. - -Directory `docs/` contains pre-rendered auto-api documentation of package `cirbo`. -Main classes and methods of `cirbo` can be explored it that documentation. To begin -exploration open `docs/index.html` in a browser. +Some features of the package are demonstrated in the example modules located in +the `tutorial/` directory. Similar code snippets are used in the paper's listings. +This is probably the first place to explore after environment is set up. -Main `cirbo/` directory is a Python package root. It provides following subpackages: +The `cirbo/` directory is the root of the Python package and contains the following subpackages: - `core` — provides core classes and structures: - - main boolean function abstractions: `Function` protocol to represent any - boolean function and `FunctionModel` protocol to represent any partially - defined boolean function - - structures to carry representations of a boolean function (`TruthTable`, + - core abstractions for Boolean functions: the `Function` protocol to represent any + Boolean function and the `FunctionModel` protocol to represent partially + defined Boolean functions. + - data structures for representing Boolean functions (`TruthTable`, `PyFunction` and `Circuit`) - - a `Circuit` class alongside with circuit manipulation operations. + - the `Circuit` class along with circuit manipulation operations. - `synthesis` — provides tools for circuit synthesis: - methods to synthesize new circuit either by providing model of a function (e.g. truth table with don't care values) and then formulating and solving a SAT problem of finding feasible circuit. - - methods to generate circuits describing arithmetical and logical operations - (e.g. `generate_sum_n_bits` and `generate_if_then_else`) or add such gadget to + - methods to generate circuits describing arithmetic and logical operations + (e.g. `generate_sum_n_bits` and `generate_if_then_else`) or to add such gadgets to an existing circuit. - `minimization` — provides methods to minimize circuits: - - low-effort circuit minimization algorithms (e.g. cleaning redundant gates, - merging unary operators, merging duplicates, brute forcing equivalent gates). - - high-effort circuit minimization trying to simplify small subcircuits within + - lightweight circuit minimization algorithms (e.g. cleaning redundant gates, + merging unary operators, merging duplicates, brute-force search for equivalent gates). + - heavyweight circuit minimization that tries to simplify small subcircuits within original circuit. -- `sat` — provides tools related to `SAT` solving: - - method to build a miter from two given circuits. - - method to reduce of `Circuit SAT` to `SAT` using Tseytin transformation. - - method to call `SAT` solvers using [pysat toolkit](https://github.com/pysathq/pysat). +- `sat` — provides tools related to SAT solving: + - a method to build a miter from two given circuits. + - a method to reduce of circuit satisfiability to SAT using Tseytin transformation. + - a method to call SAT solvers using [pysat toolkit](https://github.com/pysathq/pysat). - `circuits_db` — provides methods to manage (read and write) database of -(nearly) optimal small circuits. Can be useful for either search for circuit with -given (partially defined) truth table or for an optimization of existing circuit. - -> Note: most of a public methods provide docstrings, which can be useful when -> exploring `cirbo`. - -Directory `data/` contains databases of small (nearly) optimal circuits, and -an exemplar of circuit encoded in BENCH format needed for `tutorial/`. - -Directory `extensions/` contains C/C++ extensions written using `pybind11`. -Those extensions allow usage of `ABC` and `mockturtle` within python env. +(nearly) optimal small circuits. It can be useful for searching for a circuit with +a given (partially defined) truth table or for optimizing an existing circuit. -Directory `third_party/` contains all third party libraries (excluding ones -installed form `pypi`) distributed alongside current zip archive (whilts -originally those dependencies are managed using `git submodule`). Those -include: `ABC`, `mockturtle` and `pybind11`. - -Directory `tools/` contains utilities helpful for running linting checks or formatters. - -Directory `tests/` contains all tests that cover both `cirbo/` and `extensions/`. +> Note: most public methods have docstrings, which are useful when exploring `cirbo`. ## Technical info ### C/C++ extensions -`cirbo` package provides integration with external `C/C++` libraries (`mockturtle` -and `ABC`). Such extensions are written using `pybind11` and should be built before -used locally. To build dependencies run `poetry build` and to install them use -`poetry install` after. - -> Note: to build dependencies one should have all building tools available -> in the system. Currently, dependencies require `C++` compiler and `cmake` -> to be available. - -> Warning: `ABC` extension takes quite a long time (>10 min) to build. There is -> an option to avoid its building: `(export DISABLE_ABC_CEXT=1 && poetry build)` -> (parenthesis should be included). It can be helpful for fast testing because, -> but yet it may cause some `cirbo` functionality to not work property. - -### Code quality - -Code quality is sustained through both test-driven development and mandatory -linter checks. - -#### Tests - -Tests are written and executed using `pytest`. To execute unit tests run -`poetry run pytest`. Some tests have markers that disable their execution -by default due to their long execution times or extra dependencies requirements. -To execute all tests run `poetry run pytest -m 'not manual'`. - -#### Linters - -`mypy` is used for static type checking and `flake8` is used for general linting. - -`black`, `docformatter` and `usort` are used both to check if code is properly -formatted (e.g. in CI checks) and to format code locally. - -#### Tools - -All formatters can be run at once in poetry environment using following tool script: - -`python ./tools/formatter.py` - -All checks can be run at once in poetry environment using following tool script: - -`python ./tools/check.py` - -If everything is good, output is expected to be like the following: - -``` -(cirbo-py3.9) cirbo$ python ./tools/check.py -1. MYPY CHECK SUCCEED -2. FLAKE8 CHECK SUCCEED -3. PYTEST CHECK SUCCEED -4. USORT CHECK SUCCEED -5. DOCFORMATTER CHECK SUCCEED -6. BLACK CHECK SUCCEED -``` +The `cirbo` package provides integration with external C/C++ libraries (`mockturtle` and `ABC`). +These extensions are written using `pybind11` and should be built before being used locally. +To build the dependencies, run `poetry build`, and then install the package with `poetry install`. -## Development and contribution +> Note: to build the dependencies, you need the required build tools installed +> on your system. Currently, the dependencies require a C++ compiler and CMake. -More detailed developer's README can be found [nearby](README_DEV.md). +> Warning: the `ABC` extension takes quite a long time (>10 min) to build. You +> can skip building it with `(export DISABLE_ABC_CEXT=1 && poetry build)` (parentheses +> should be included). This can be helpful for faster testing, but it may cause +> some `cirbo` functionality to not work properly. diff --git a/README_DEV.md b/README_DEV.md index 3332903..6f9cb84 100644 --- a/README_DEV.md +++ b/README_DEV.md @@ -34,7 +34,6 @@ Package was tested on `Ubuntu` and `Mac OS Ventura 13` machines. > Note: it may be necessary to restart an IDE after extensions > are built and installed to refresh its index and stubs. -nstalled to refresh its index and stubs. ## Building extensions @@ -159,6 +158,24 @@ Read more about submodules in ``` 5. Add python tests to `tests/` package. +## Building documentation + +Currently, documentation can be generated using `Sphinx` in dev environment. +To do it simply navigate to `docs/` and execute `make html`. + +## Dev Directories + +Besides main source directory `cirbo/` this repo contains: + - Directory `tutorial/` with several library usage examples. + - Directory `extensions/` with C/C++ extensions written using `pybind11`. + Those extensions allow usage of `ABC` and `mockturtle` within python env. + - Directory `third_party/` with all third party libraries (excluding ones + installed form `pypi`) distributed alongside current zip archive (whilts + originally those dependencies are managed using `git submodule`). Those + include: `ABC`, `mockturtle` and `pybind11`. + - Directory `tools/` with utilities helpful for running linting checks or formatters. + - Directory `tests/` with all tests that cover both `cirbo/` and `extensions/`. + - ## CI flow GitHub Actions are used for CI. Following checks are executed automatically for diff --git a/README_PYPI.md b/README_PYPI.md deleted file mode 100644 index 531b5b3..0000000 --- a/README_PYPI.md +++ /dev/null @@ -1,41 +0,0 @@ -# Cirbo: A New Tool for Boolean Circuit Analysis and Synthesis - -Cirbo is a library for boolean circuit manipulations, providing methods to -analyse some given boolean circuits and synthetise new ones. - -More info can be found at: https://github.com/SPbSAT/cirbo - -## Package structure - -Main `cirbo/` directory is a Python package root. It provides following subpackages: - -- `core` — provides core classes and structures: - - main boolean function abstractions: `Function` protocol to represent any - boolean function and `FunctionModel` protocol to represent any partially - defined boolean function - - structures to carry representations of a boolean function (`TruthTable`, - `PyFunction` and `Circuit`) - - a `Circuit` class alongside with circuit manipulation operations. -- `synthesis` — provides tools for circuit synthesis: - - methods to synthesize new circuit either by providing model of a function - (e.g. truth table with don't care values) and then formulating and solving - a SAT problem of finding feasible circuit. - - methods to generate circuits describing arithmetical and logical operations - (e.g. `generate_sum_n_bits` and `generate_if_then_else`) or add such gadget to - an existing circuit. -- `minimization` — provides methods to minimize circuits: - - low-effort circuit minimization algorithms (e.g. cleaning redundant gates, - merging unary operators, merging duplicates, brute forcing equivalent gates). - - high-effort circuit minimization trying to simplify small subcircuits within - original circuit. -- `sat` — provides tools related to `SAT` solving: - - method to build a miter from two given circuits. - - method to reduce of `Circuit SAT` to `SAT` using Tseytin transformation. - - method to call `SAT` solvers using [pysat toolkit](https://github.com/pysathq/pysat). -- `circuits_db` — provides methods to manage (read and write) database of -(nearly) optimal small circuits. Can be useful for either search for circuit with -given (partially defined) truth table or for an optimization of existing circuit. - -> Note: most of a public methods provide docstrings, which can be useful when -> exploring `cirbo`. - diff --git a/pyproject.toml b/pyproject.toml index f079d2a..16f5de7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -20,7 +20,7 @@ authors = [ maintainers = [ {name = "Fedor Kurmazov", email = "f.kurmazov.b@gmail.com"} ] -readme = "README_PYPI.md" +readme = "README.md" license = {file = "LICENCE"} # Temporary guard against occasional publishing. classifiers = [ diff --git a/tutorial/01_intro.py b/tutorial/01_intro.py new file mode 100644 index 0000000..c69441f --- /dev/null +++ b/tutorial/01_intro.py @@ -0,0 +1,25 @@ +# Cirbo is a Python library that provides methods for +# Boolean circuit manipulations, analysis and synthesis. +# Code below demonstrates how simple Boolean circuit can +# be constructed, analyzed and drawn. +from cirbo.core import Circuit, Gate, gate +from cirbo.synthesis.generation.arithmetics import add_sum_n_bits + +# Create an empty circuit with 6 inputs. +ckt = Circuit.bare_circuit(input_size=6) +# Generate and connect a "gadget" subcircuit +# that computes the sum of the input bits. +b0, b1, b2 = add_sum_n_bits(ckt, ckt.inputs) +# Manually add gates that yield True only +# if at least half of the inputs are True. +ckt.add_gate(Gate('a0', gate.AND, (b0, b1))) +ckt.add_gate(Gate('a1', gate.OR, ('a0', b2))) +ckt.mark_as_output('a1') + +# Calculate general boolean function properties. +print(f"Is monotone: {ckt.is_monotone()}") +print(f"Is symmetric: {ckt.is_symmetric()}") +print(f"Is constant: {ckt.is_constant()}") + +# Draw graph and show image in the default viewer. +ckt.view_graph() From c9982d0aa52fb3d3bc6b45be88b2576d525d1126 Mon Sep 17 00:00:00 2001 From: spefk Date: Sun, 25 Jan 2026 16:11:02 +0300 Subject: [PATCH 2/4] fix --- README.md | 2 +- tutorial/01_intro.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 71d428d..07faaf6 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ ckt = Circuit.bare_circuit(input_size=6) # Generate and connect a "gadget" subcircuit # that computes the sum of the input bits. b0, b1, b2 = add_sum_n_bits(ckt, ckt.inputs) -# Manually add gates that yield True only +# Manually add output gate that yield True only # if at least half of the inputs are True. ckt.add_gate(Gate('a0', gate.AND, (b0, b1))) ckt.add_gate(Gate('a1', gate.OR, ('a0', b2))) diff --git a/tutorial/01_intro.py b/tutorial/01_intro.py index c69441f..34f030a 100644 --- a/tutorial/01_intro.py +++ b/tutorial/01_intro.py @@ -10,7 +10,7 @@ # Generate and connect a "gadget" subcircuit # that computes the sum of the input bits. b0, b1, b2 = add_sum_n_bits(ckt, ckt.inputs) -# Manually add gates that yield True only +# Manually add output gate that yield True only # if at least half of the inputs are True. ckt.add_gate(Gate('a0', gate.AND, (b0, b1))) ckt.add_gate(Gate('a1', gate.OR, ('a0', b2))) From e8576b2ddc0654d236db3e91e884893694f115db Mon Sep 17 00:00:00 2001 From: spefk Date: Sun, 25 Jan 2026 16:13:24 +0300 Subject: [PATCH 3/4] fix --- README.md | 16 ---------------- README_DEV.md | 33 ++++++++++++++++----------------- 2 files changed, 16 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 07faaf6..4c48dd0 100644 --- a/README.md +++ b/README.md @@ -84,19 +84,3 @@ The `cirbo/` directory is the root of the Python package and contains the follow a given (partially defined) truth table or for optimizing an existing circuit. > Note: most public methods have docstrings, which are useful when exploring `cirbo`. - -## Technical info - -### C/C++ extensions - -The `cirbo` package provides integration with external C/C++ libraries (`mockturtle` and `ABC`). -These extensions are written using `pybind11` and should be built before being used locally. -To build the dependencies, run `poetry build`, and then install the package with `poetry install`. - -> Note: to build the dependencies, you need the required build tools installed -> on your system. Currently, the dependencies require a C++ compiler and CMake. - -> Warning: the `ABC` extension takes quite a long time (>10 min) to build. You -> can skip building it with `(export DISABLE_ABC_CEXT=1 && poetry build)` (parentheses -> should be included). This can be helpful for faster testing, but it may cause -> some `cirbo` functionality to not work properly. diff --git a/README_DEV.md b/README_DEV.md index 6f9cb84..2d80be5 100644 --- a/README_DEV.md +++ b/README_DEV.md @@ -35,23 +35,22 @@ Package was tested on `Ubuntu` and `Mac OS Ventura 13` machines. > Note: it may be necessary to restart an IDE after extensions > are built and installed to refresh its index and stubs. -## Building extensions - -This package provides bridges to some external `C/C++` libraries. Extensions -are written using `pybind11` and should be built before used locally. To build -dependencies run `poetry build` and to install them after use `poetry install`. - -Note: to build dependencies one should have all building tools available -in the system. Currently, dependencies require `C++` compiler and `cmake` -to be available. - -Some extensions can be disabled using environment variables if one doesn't -need them. For example `(export DISABLE_ABC_CEXT=1 && poetry build)` (parenthesis -should be included) will build wheels without `ABC` bridge module. It can be -helpful for CI or fast testing because `ABC` compilation times are heavy. - -Tests that use `ABC` extension can be skipped by passing option `-m 'not ABC'` -to `pytest` run. +## Building C/C++ extensions + +The `cirbo` package provides integration with external C/C++ libraries (`mockturtle` and `ABC`). +These extensions are written using `pybind11` and should be built before being used locally. +To build the dependencies, run `poetry build`, and then install the package with `poetry install`. + +> Note: to build the dependencies, you need the required build tools installed +> on your system. Currently, the dependencies require a C++ compiler and CMake. + +> Warning: the `ABC` extension takes quite a long time (>10 min) to build. You +> can skip building it with `(export DISABLE_ABC_CEXT=1 && poetry build)` (parentheses +> should be included). This can be helpful for faster testing, but it may cause +> some `cirbo` functionality to not work properly. +> +> Tests that use `ABC` extension can be skipped by passing option `-m 'not ABC'` +> to `pytest` run. ## Codestyle guidelines From b6866a44996304f0ddbe605dd779babeeca08adb Mon Sep 17 00:00:00 2001 From: spefk Date: Sun, 25 Jan 2026 16:15:46 +0300 Subject: [PATCH 4/4] fix --- README_DEV.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README_DEV.md b/README_DEV.md index 2d80be5..f120d67 100644 --- a/README_DEV.md +++ b/README_DEV.md @@ -174,7 +174,7 @@ Besides main source directory `cirbo/` this repo contains: include: `ABC`, `mockturtle` and `pybind11`. - Directory `tools/` with utilities helpful for running linting checks or formatters. - Directory `tests/` with all tests that cover both `cirbo/` and `extensions/`. - - + ## CI flow GitHub Actions are used for CI. Following checks are executed automatically for