Hyperoptimized Quantum Lego Contraction Schedules

aqora / Hyperoptimized Quantum Lego Contraction Schedules

Public

About dataset version

This dataset aggregates contraction-schedule results for Quantum LEGO (QL) layouts used to compute weight enumerator polynomials (WEPs) of stabilizer codes. It accompanies the paper Hyper-optimized Quantum LEGO Contraction Schedules (2025), which introduces the Sparse Stabilizer Tensor (SST) cost function and benchmarks hyper-optimized schedules (via cotengra) across QL layouts such as MSP and Tanner.

The dataset combines the authors’ MSP/Tanner layout runs; see the paper’s Sec. III.4 and VI for layout details.

Quick start

# Install: pip install polars aqora-cli pyarrow fsspec
import polars as pl
from aqora_cli.pyarrow import dataset
df = pl.scan_pyarrow_dataset(
    dataset("aqora/hyperoptimized-quantum-lego-contraction-schedules", "v1.0.0")
)
# Peek schema without reading all data:
print(df.collect_schema())  # shows column names/types
# Example 1 — compare average ops by cost function for MSP layouts
res1 = (
    df.filter(pl.col("representation") == "MSP")
      .group_by("cost_fn")
      .agg(pl.col("operations").mean().alias("avg_ops"))
      .sort("avg_ops")
      .collect()
)
print(res1)
# Example 2 — scaling: max intermediate tensor by distance
res2 = (
    df.group_by("distance")
      .agg(pl.col("max tensor size").max().alias("max_intermediate"))
      .sort("distance")
      .collect()
)
print(res2)
# Example 3 — when does QL beat brute force?
res3 = (
    df.filter(pl.col("operations_w_bruteforce").is_not_null())
      .with_columns((pl.col("operations") < pl.col("operations_w_bruteforce"))
                    .alias("ql_beats_bruteforce"))
      .group_by("representation")
      .agg(pl.col("ql_beats_bruteforce").mean().alias("share_better"))
      .sort("share_better", descending=True)
      .collect()
)
print(res3)

Schema

All columns are preserved as in the source CSVs.

Column	Type	Description
`cost_fn`	String	Cost function used when searching schedules (e.g., SST vs default/dense).
`representation`	String	QL layout / graph representation (e.g., MSP, Tanner, surface, concatenated; values depend on source).
`num_run_x`	Integer	Run/repeat counter (first pass or phase) as exported by authors’ scripts.
`distance`	Integer	Code distance or layout parameter where applicable.
`num_qubits`	Integer	Number of physical qubits in the instance.
`contraction_time`	Float	Wall-clock or measured time for the recorded contraction run (seconds, as logged).
`contraction cost`	Float	Reported contraction cost metric for the selected path (definition follows cost_fn; see Notes).
`contraction width`	Float	Reported path width / max intermediate size metric for the schedule (per source export).
`operations`	Float	Estimated floating-point operations for the contraction (per cotengra export).
`avg intermediate tensor`	Float	Average intermediate tensor size during contraction (source export).
`max tensor size`	Float	Maximum intermediate tensor size during contraction (source export).
`wep`	String	WEP target label for the instance (e.g., scalar vs tensor WEP variants; see paper background).
`score_cotengra`	Float	cotengra’s internal objective/score for the chosen path.
`brute_force`	Float	Baseline metric exported by the authors for brute-force computation.
`num_run_y`	Float	Secondary run/repeat counter (second pass or phase).
`brute_force_operations`	Float	Estimated operations for brute-force evaluation (if provided).
`operations_w_bruteforce`	Float	Combined/alternative operations estimate including brute-force baseline (if provided).

Notes on cost functions

The paper shows that intermediate tensors in stabilizer-WEP QL networks are often highly sparse, making dense-assumption cost functions unreliable. The SST cost, derived from parity-check matrix ranks, correlates tightly with true cost and improves schedule selection. Expect contraction cost to reflect the chosen cost_fn semantics.

Caveats

score_cotengra, contraction cost, and operations are model-/tool-dependent estimates; interpret comparatively, not as absolute FLOPs guarantees.
Sparse vs dense assumptions matter; see the paper’s discussion of SST vs default cost.

How to cite

If you use this dataset, please cite: Balint Pato, June Vanlerberghe, Kenneth R. Brown (2025). Hyper-optimized Quantum LEGO Contraction Schedules. arXiv:2510.08210.