Installing

Dependencies

  • Python 3.12+ for the example wrappers, tests, and docs

  • iverilog for HDL simulations of the examples and test flows

  • verilator and c++ for HDL simulations of larger examples (only when you want --sim verilator)

  • stim for simulating decoding of circuit level noise make installs the Python dependencies only. It does not install the HDL simulators.

For iverilog:

  • Ubuntu: sudo apt install verilog

  • macOS: brew install icarus-verilog

  • source/install: steveicarus/iverilog

For optional Verilator setup:

Quickstart

From the repository root:

make

This creates .venv, installs the default example dependencies (numpy, scipy, and stim), and checks that iverilog is present.

The default end-to-end decoder example path is:

./.venv/bin/python examples/minsum_decode/build.py
./.venv/bin/python examples/minsum_decode/run.py
./.venv/bin/python examples/minsum_decode/read.py

Optional setup paths

For larger examples with Verilator:

make verilator-ready

For cocotb tests:

make test-ready

For documentation only:

make docs-ready

Run the regression suite with:

make test

Build the docs with:

make docs

Usage entry points

The smallest supported end-to-end examples of the systolic solver are:

The supported Stim-backed decoder examples are: