fbool

fbool is a Rust workspace for analysing Boolean functions, with support for entanglement-style measures, information-theoretic metrics, spectral and structural properties, certificate complexity, frontier graphs, and exact minimal-gate data for functions of up to 5 variables.

The workspace contains the publishable Rust library crate, a CLI, Python bindings built with PyO3/maturin, and experiment binaries used by the research workflow.

Workspace

fbool/                 # Publishable Rust library crate
fbool/src/metrics/     # Entanglement, entropy, fragmentation, frontier, spectral, sensitivity, influence
fbool/src/optimal5.rs  # Default Rust API for the integrated optimal5 engine
fbool/cpp/             # C++ sources from Adam P. Goucher's optimal5 engine
fbool/knuthies.dat     # Lookup data used by the optimal5 feature
fbool-cli/             # Command-line interface
fbool-py/              # Python extension module named fbool
fbool-experiments/     # Research/analysis binaries
experiments/           # Experiment assets and scripts
clique_solver/         # Standalone clique-solver code retained in the repository

The old standalone optimal5 crate has been folded into fbool as the default optimal5 feature. There is no separate workspace member for it anymore.

Rust Crate

Add the library from crates.io once published:

[dependencies]
fbool = "0.2"

The minimal-gate API backed by the integrated C++ engine is enabled by default. If you want a pure-Rust build without optimal5, disable default features and opt back into the Rust-only metric families you need:

[dependencies]
fbool = { version = "0.2", default-features = false, features = ["entanglement", "frontier"] }

For local development inside this repository:

[dependencies]
fbool = { path = "../fbool" }

Features

Basic Example

use fbool::entanglement::{Entanglement, Entropy};
use fbool::fvalue::FValue;

fn main() {
    let f = FValue::majority(4);

    println!("entanglement: {}", f.entanglement());
    println!("minmax entanglement: {}", f.minmax_entanglement());
    println!("entropy: {}", f.entropy());

    for set in f.entanglement_sets() {
        println!("{:?} | {:?} -> {}", set.set1, set.set2, set.entanglement);
    }
}

With the default optimal5 feature:

use fbool::fvalue::FValue;
use fbool::optimal5::WithMinimalGates;

fn main() {
    let f = FValue::majority(5);
    println!("minimal gates: {:?}", f.minimal_gates());
}

Function Constructors

FValue<bool> includes:

FValue<usize> includes arithmetic-valued constructors such as sum, product, max, gcd, multiply, sum_some, and constant.

Metrics

The public API exposes metrics through modules under fbool::metrics and through top-level compatibility re-exports:

Python Package

The Python package is published on PyPI as fbool and exports a module named fbool. It requires Python 3.11 or newer.

Install it with uv:

uv add fbool

Or with pip:

pip install fbool

For local development inside this repository, build the extension from fbool-py with maturin.

Python Example

from fbool import FBool

f = FBool.primality(4)

print("n vars:", f.n_vars())
print("entanglement:", f.entanglement())
print("min gates:", f.minimal_gates())
print("spectral entropy:", f.spectral_entropy())

for item in f.entanglement_sets():
    print(item.set1, item.set2, item.entanglement)

Python API Highlights

FBool supports construction from a truth table or integer encoding:

The Python bindings also expose entanglement, entropy, fragmentation, frontier, sensitivity, spectral, influence, certificate, and optimal5 metrics.

CLI

Build the CLI:

cargo build --release -p fbool-cli

Run help:

./target/release/fbool-cli --help

On Windows, the binary is target\release\fbool-cli.exe.

CLI Examples

# Entanglement of majority on 4 variables
fbool-cli entanglement majority --n-vars 4

# All bipartitions, sorted, keeping the first 10 rows
fbool-cli entanglement --sets --sorted --head 10 parity --n-vars 5

# Min-max entanglement
fbool-cli entanglement --minmax majority --n-vars 4

# Entropy sets
fbool-cli entropy --sets majority --n-vars 4

# Per-subset information
fbool-cli sub-info primality --n-vars 5

# Encode and load a function
fbool-cli encode --output-path primality_5.bin primality --n-vars 5
fbool-cli entanglement bin --path primality_5.bin

Available function subcommands include majority, parity, eq, ordered, multiply, sum, max, gcd, primality, sum-is-prime, coprimes, constant, usize-constant, raw, bin, find-zero, and meta.

Experiments

The fbool-experiments crate contains research binaries:

cargo run -p fbool-experiments --bin npn-create -- --help
cargo run -p fbool-experiments --bin compute-metrics -- --help
cargo run -p fbool-experiments --bin bayes-optimal -- --help
cargo run -p fbool-experiments --bin orthogonality -- --help

These tools are part of the repository workflow, but the publishable Rust crate is fbool.

Documentation

The MkDocs Material documentation lives in docs/ and is configured by mkdocs.yml.

uv run --with-requirements docs/requirements.txt mkdocs serve

For CI-style validation:

uv run --with-requirements docs/requirements.txt mkdocs build --strict

Building And Testing

Requirements:

• Rust stable
• A C++ compiler for default fbool builds, because optimal5 is enabled by default
• Python 3.11+ for the Python package
• uv is optional but recommended for Python development

Common commands:

cargo check -p fbool
cargo check -p fbool --no-default-features --features entanglement,frontier
cargo test --workspace
cargo clippy --all-targets --all-features
cargo package -p fbool --allow-dirty

Releases

Versioning is managed from the repository root with Commitizen via .cz.toml.

uv tool install commitizen
cz bump --changelog --yes

Publishing is driven by GitHub Actions on v* tags:

• cargo publish -p fbool publishes the Rust crate to crates.io.
• maturin builds Python wheels for Linux, Windows, and macOS ARM.
• the Python wheels are published to PyPI as fbool.

Citation

If you use this software in academic work, please cite:

@software{fbool,
  author  = {Eduardo Gonz\'{a}lez and Ricardo Maurizio Paul},
  title   = {fbool: A Rust library for Boolean function entanglement analysis},
  year    = {2025},
  url     = {https://github.com/edugzlez/fbool}
}

The associated paper citation will be added upon publication.

License

This project is licensed under the MIT License. See LICENSE.

The integrated optimal5 C++ engine is derived from Adam P. Goucher's optimal5, also used under the MIT License.

Authors

• Eduardo Gonzalez-Vaquero (edugzlez)
• Ricardo Maurizio Paul