Chromobius Developer Documentation

November 20, 2025 ยท View on GitHub

Index

Repository Layout

  • src/chromobius/: C++ code implementing Chromobius and its Python package.
  • src/clorco/: Python code for generating color code and surface code circuits used to test Chromobius.
  • src/gen/: Generic utilities for making circuits; used by src/clorco/.
  • tools/: Bash scripts for generating circuits and statistics and plots presented in the paper.

Building Chromobius as a standalone command line tool

with Bazel:

bazel build :chromobius

Or, to run the tool:

bazel run :chromobius

with CMake:

cmake .
make chromobius

Then, to run the built tool:

out/chromobius

with GCC:

# This must be run from the repository root.
# This requires that you have libstim and libpymatching installed.

readarray -d '' CC_FILES_TO_BUILD < \
    <( \
      find src \
      | grep "\\.cc$" \
      | grep -v "\\.\(test\|perf\|pybind\)\\.cc$" \
    )

g++ \
    -I src \
    -std=c++20 \
    -O3 \
    -march=native \
    ${CC_FILES_TO_BUILD[@]} \
    -l stim \
    -l pymatching

with Clang:

# This must be run from the repository root.
# This requires that you have libstim and libpymatching installed.

readarray -d '' CC_FILES_TO_BUILD < \
    <( \
      find src \
      | grep "\\.cc$" \
      | grep -v "\\.\(test\|perf\|pybind\)\\.cc$" \
    )

clang \
    -I src \
    -std=c++20 \
    -O3 \
    -march=native \
    ${CC_FILES_TO_BUILD[@]} \
    -l "stdc++" \
    -l m \
    -l stim \
    -l pymatching

Then, to run the built tool:

./a.out

Building Chromobius as a Python package

with Bazel:

bazel build :chromobius_dev_wheel
pip install bazel-bin/chromobius-0.0.dev0-py3-none-any.whl

with CMake:

# Requires pybind11 and Python to be installed on your system.
cmake .
make chromobius_pybind
# output is in `out/` with a path that depends on your machine
# e.g. it might be `out/chromobius.cpython-311-x86_64-linux-gnu.so`

with cibuildwheel:

pip install cibuildwheel
# See https://cibuildwheel.readthedocs.io/en/stable/options/#build-skip for CIBW_BUILD values
CIBW_BUILD=cp311-manylinux_x86_64 cibuildwheel --platform linux
# output is in `wheelhouse/` with a path that depends on platform/target
# e.g. it might be `out/chromobius-0.0.dev0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl`

with pip:

# Must be run from the chromobius git repository root.
# Note this will build the package AND install it into your Python environment.
pip install .
# output is in `python_build_chromobius/` under a platform dependent directory and filename
# e.g. it might be `python_build_chromobius/lib.linux-x86_64-cpython-311/chromobius.cpython-311-x86_64-linux-gnu.so`

Running unit tests

Python unit tests

The Python unit tests check that the circuit generation utilities are working correctly, and that Chromobius can decode the generated circuits.

Note that these tests require the Chromobius Python package to be installed.

pip install -r requirements.txt
pytest src

C++ unit tests with Bazel

bazel test :all

C++ unit tests with CMake

# Requires googletest to be installed on your system.
cmake .
make chromobius_test
out/chromobius_test

Running performance benchmarks

with Bazel

bazel run :chromobius_perf

with CMake

cmake .
make chromobius_perf
out/chromobius_perf

Releasing a new version

New development releases are uploaded to the Chromobius project on PyPI automatically by a continuous integration workflow on GitHub. The updates are triggered when pull requests are merged into the main branch of the repository.

Stable releases are performed manually by following these steps:

  • Create an off-main-branch release commit
    • git checkout main -b SOMEBRANCHNAME
    • Search .py files and replace __version__ = 'X.Y.dev0' with __version__ = 'X.Y.0'
    • git commit -a -m "Bump to vX.Y.0"
    • git tag vX.Y.0
    • Push the tag to GitHub
    • Check the GitHub Actions tab and confirm CI is running on the tag
  • Collect Python wheels from GitHub
    • Wait for CI to finish validating and producing artifacts for the tag
    • Download all the wheels created as artifacts by the CI workflow
    • Do manual sanity checks, e.g., by installing one of the wheels and running tests
  • Bump to next dev version on main branch
    • git checkout main -b SOMEBRANCHNAME
    • Search .py files and replace __version__ = 'X.Y.dev0' with __version__ = 'X.(Y+1).dev0'
    • git commit -a -m "Start vX.(Y+1).dev"
    • Push to GitHub as a branch and merge into main using a pull request
  • Start a draft release on GitHub
    • For the title, use two-word theming of most important changes
    • In the body, list the user-visible fixes, additions, and other changes
    • Attach the wheels to the release
  • Do these irreversible and public viewable steps last!
    • Upload wheels/sdists to PyPI
    • Publish the GitHub release notes
    • Announce the release