developers.md

Chromobius Developer Documentation

Index

• Repository Layout
• Building chromobius as a standalone command line tool
  • with bazel
  • with cmake
  • with gcc
  • with clang
• Building chromobius as a python package
  • with bazel
  • with cmake
  • with cibuildwheels
  • with pip
• Running tests
  • python unit tests
  • C++ unit tests with Bazel
  • C++ unit tests with cmake
• Running performance benchmarks
  • with bazel
  • with cmake

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_pybind

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