Quickstart

After the first public release, install the Python runner with the QEC extra to get real NumPy, Stim, and PyMatching execution. Until that release is completed, use the source-install fallback in the canonical SDK quickstart.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "ketqat[qec]"

The installed runner ships example manifests. This runs a real surface-code memory experiment with MWPM decoding via PyMatching:

ketqat examples list
ketqat run surface-code-memory --output run.json

The run prints what it found:

surface-code-mwpm-baseline  [COMPLETED]
  suite       surface-code-memory-mwpm 0.1.0
  domain      QEC
  points      1
  d=3, p=0.001  logical error rate < 0.0369935 (upper bound, 95% confidence)
      No logical failures in 100 shots. This bounds the rate; it does not show it is zero.
  backend     stim-pymatching
  hash        369a635373fab00c...
  written to  run.json

Read the logical error rate line carefully. This run observed no logical failures, which does not mean the error rate is zero — it means the rate is small enough that 100 shots could not resolve it. All the run established is an upper bound, and quoting it as zero would be a claim the data does not support. Raise shots in the manifest to tighten the bound.

run.json holds the full metric points, the confidence interval, and a canonical reproducibility hash computed from the manifest, environment, and results.

First local success does not require a KetQat account or token. To edit the manifest before running, copy the packaged example and run the local file:

ketqat examples copy surface-code-memory --output surface-code-memory.yaml
ketqat run surface-code-memory.yaml --output run.json

If the QEC extra is missing, the runner exits without writing a successful result and tells you to install ketqat[qec]. There is no synthetic QEC fallback.

Publishing is optional. Sign in with GitHub, then create a token in Settings. Tokens are shown once and stored hashed.

curl -X POST https://ketqat.com/api/runs/import \
  -H "Authorization: Bearer kq_..." \
  -H "content-type: application/json" \
  -d @run.json

The server independently recalculates the reproducibility hash and rejects the import if it doesn't match your submitted result -- so a published run can't silently drift from what you actually ran. Byte-for-byte repeated imports return the existing run instead of creating duplicates. Add {"result": ..., "visibility": "PRIVATE"} as the body instead to publish privately first.

Your run now appears on your dashboard, at its own /runs/<slug> page with a downloadable reproducibility bundle, and -- if it's against a standard QEC suite -- on the decoder leaderboard, compared only against other runs on the exact same benchmark suite and version.