Cobble Artifact

This is the artifact for the paper "Cobble: Compiling Block Encodings for Quantum Computational Linear Algebra" by Charles Yuan. It contains the sources for the Cobble compiler, the benchmark programs and circuits used in the paper, and the evaluation package.

Contents of Artifact

This document describes:

• The claims of the paper this artifact supports
• The kick-the-tires instructions for reviewers
• How to review the artifact for functionality
• How to review the artifact for reusability
• Detailed instructions for building the artifact

The artifact contains:

• README.md: this file
• Dockerfile: the Dockerfile to build the artifact
• artifact.tgz: a pre-compiled Docker image from the Dockerfile
• cobble/: the sources for the Cobble compiler
• tex/: scripts to reproduce the tables and figures from the paper
• qasm.tar.xz: pre-generated copies of the circuits used in the evaluation
• reference_output.tar.xz: the reference outputs of the evaluation package

The remaining files are the scripts and sources constituting the evaluation package.

Claims Supported by Artifact

The artifact reproduces all of the empirical results in the paper, as depicted in Figures 12 and 13 and Tables 3 and 4 of the paper. Specifically, the artifact reproduces both these figures and tables themselves and their raw underlying data. All summary statistics of the empirical results in the main text of the paper are derived from these tables and figures or their raw data.

Kick-the-Tires Instructions

1. Install Docker on the host machine. In our testing, we used Docker Desktop version 4.62.0 on macOS 26.3. The largest test cases in the artifact require 32 GB of RAM.

2. Load the pre-compiled Docker image (x86 architecture, tested under Rosetta) and enter the image shell:

$ docker load -i artifact.tgz
$ docker run --name cobble -it cobble-artifact /bin/bash

The image shell starts at the directory /root/, inside which the artifact files can be found.

1. In /root/ in the image shell, run a fast subset of the benchmarks from the paper (takes ~1 minute):

./run_fast.sh

1. Generate the tables and figures from the paper on this subset (takes ~5 minutes):

cd /root/tex; ./build.sh

1. Check that the file artifact.pdf contains the tables and figures. To copy this file out of the Docker container, run (in the host shell):

docker cp cobble:/root/tex/artifact.pdf .

Functionality: Validating the Paper's Claims

1. Confirm that the benchmark programs from Tables 3 and 4 of the paper are present in the image.

In the image (at /root/), the benchmark programs are in the following files:

• simulation-example corresponds to cobble/examples/simulation_example.py.
• regression-example corresponds to cobble/examples/regression_example.py.
• penalized-coupler corresponds to cobble/examples/penalized_coupler.py.
• laplacian-filter corresponds to cobble/examples/laplacian_filter.py.
• ols-ridge corresponds to cobble/examples/ols_ridge.py.
• Matrix inversion corresponds to cobble/examples/matrix_inversion.py.
• Hamiltonian simulation corresponds to cobble/examples/hamiltonian_simulation.py.
• Spectral thresholding corresponds to cobble/examples/spectral_thresholding.py.

The compiled and unoptimized circuits corresponding to these programs are in the qasm/ directory. The directory qasm/opt/ contains the versions optimized by Cobble.

1. [Optional] Execute the Cobble compiler to regenerate qasm/ from the benchmark programs (takes ~1 minute):

mkdir -p /root/qasm
python3 /root/cobble/main.py --qasm all && mv *.qasm /root/qasm
python3 /root/cobble/main.py --qasm all --opt && mv *.qasm /root/qasm/opt
python3 /root/cobble/main.py 2>/root/cobble_out
python3 /root/cobble/main.py --timing >/root/timing_out 2>/root/timing_err

This step is optional as the circuits have been pre-generated in qasm/. The commands above will regenerate them from scratch, along with summary information in the file cobble_out and timing information in timing_out.

1. [Done above] Run the fast subset of the benchmarks from the paper (takes ~1 minute):

cd /root/
./run_fast.sh

The output circuits from this command will be stored in the directories whose names end in *_out. The reference outputs for this command are already provided in these directories in the initial state of the artifact. Running this command will regenerate them from scratch. This command was already executed in the kick-the-tires instructions and will produce identical results if executed again.

1. [Optional] Run all of the benchmarks from the paper (takes ~1 day):

cd /root/
./run.sh

The outputs of this command will be stored in the same directories.

This step is optional as it takes a very long time. As an alternative to running this step, the reference outputs for this command are already provided in these directories in the initial state of the artifact. The following step will automatically use the reference outputs if this step is skipped.

Note: Errors such as out-of-memory and segmentation faults from the optimizers from prior work may be reported. These errors are expected based on the results as presented in the paper.

1. [Done above] Generate the tables and figures from the paper (takes ~1 minute):

cd /root/tex; ./build.sh

after which the file artifact.pdf will contain the tables and figures. As above, to copy this file out of the Docker container, run (in the host shell):

docker cp cobble:/root/tex/artifact.pdf .

1. Compare the contents of artifact.pdf to Figures 12 and 13 and Tables 3 and 4 in the paper to see that they match.

Note: The absolute timing results and the y-axis ticks in Figure 13 may vary depending on hardware and virtualization overhead, but the relative trend should approximately match the results in the paper.

Note: Some of the optimizers from prior work, in particular Qiskit, Quartz, and wisq, can sometimes produce nondeterministic outputs. If this happens, the gate counts in Figure 12 may not match exactly with those in the paper, but should be close and the overall trends should remain the same.

The raw data for the plots can be found in the fig*.tikz files in the tex/ directory.

Reusability: Extending the Sources and Writing New Programs

The sources of the compiler and interpreter for the Cobble language included in the artifact makes it possible to write new programs and extend the functionality of the language and compiler. The file cobble/README.md describes the organization of the sources, should you wish to modify the code. Upon modifying the Python code, re-install the cobble module by:

cd /root/cobble/
pip install -e .

To compile an example program to QASM, run:

python3 /root/cobble/main.py --qasm <example>         # e.g. simulation-example, hamiltonian-simulation, or all
python3 /root/cobble/main.py --qasm <example> --opt   # emit optimized circuits

Output is written to <example>.qasm (or <example>-opt.qasm with --opt).

To build and compile your own programs: build an Expr (see syntax below), optionally call expr.optimize(), then expr.circuit() to get a Circuit, and circuit.to_qasm() for the OpenQASM string. The file standalone_example.py at the artifact root is a self-contained example program. It defines a Cobble expression in get_expr() and includes a small runner that outputs QASM directly:

python3 /root/standalone_example.py         # writes standalone_example.qasm
python3 /root/standalone_example.py --opt   # writes standalone_example-opt.qasm

You can use this file as a template for new programs: define get_expr() and copy the if __name__ == "__main__" block to compile to QASM.

The provided examples in cobble/examples/ are a convenient way to understand the syntax of Cobble. Programs are written in Python using the Cobble expression API. Main constructs include:

• Block encodings: Basic("name") — black-box block encoding (name may be a gate like "X" or "H", or start with "$" for a placeholder random u3 rotation in QASM).
• Scalars: Const(c) — scalar multiple of identity.
• Linear combinations: A + B, A - B, -A, and c * A for scalar c — build Sum expressions.
• Products and powers: A * B, A ** n — products of block encodings; repeated factors are compiled via polynomials where applicable.
• Tensor product: Expr.kron(A, B, ...) or A.kronpow(n) — tensor product of expressions.
• Adjoint: Dagger(expr) — adjoint of an expression.
• Polynomials: Poly(expr, polynomial) — polynomial of a matrix; polynomial is from cobble.polynomial.Polynomial.
• Conditionals: If(condition, then_expr, else_expr) — conditional block encoding; condition is a Condition(var, active).
• Sums/products from sequences: Sum.of(...), Prod.of(...) — build sums or products from iterables.
• Division: A / B or A / c — division (syntactic sugar, simplified away at compile time when possible).

The artifact also includes a number of scripts to help with evaluating quantum circuits and comparing circuit optimizers. To count the number of gates in a .qasm circuit, use the script count_gates.py. To run each of the individual comparisons to prior optimizers, run each of the scripts that begin with run_*.sh.

Detailed Build Instructions

To rebuild the artifact image from the sources, run

docker build --platform linux/amd64 -t cobble-artifact .

after which the artifact can be run as above:

docker run --name cobble -it cobble-artifact /bin/bash

To build the remainder of the artifact outside of the image, please see the Dockerfile for the list of dependencies and the commands to run.