Note

Run this notebook from the ARCADE repository root after pip install -e ".[torch,signature]" and, for paper configs, bash scripts/link_paper_data.sh.

Notebook: debugging the ARCADE pipeline

This notebook is a playbook for broken runs. It shows how to raise log levels, validate YAML early, run stages one at a time, and map common error strings to fixes. Keep it open beside a failing zoo job.

Mental model

validate YAML → data stage → classify one method → add methods → hardware → report

Do not start by re-tuning neural hyperparameters when Stage 1 label packing is wrong. Fix the earliest stage that emits a WARNING or unexpected INFO line.

[ ]:

from pathlib import Path
import logging
import traceback

from arcade._logging import configure_logging, get_logger
from arcade.config import load_config, validate_and_explain

configure_logging(logging.INFO)
log = get_logger("tutorial.debug")

CONFIG = Path("configs/example.yaml")
if not CONFIG.is_file():
    CONFIG = Path("configs/paper_all_methods_benchmark.yaml")

errors = validate_and_explain(CONFIG)
print("config valid:", not errors)
for m in errors:
    print(" ", m)

Log levels that matter

Level

When to use

WARNING

Default library quietness before configure_logging

INFO

Normal pipeline banners and per-method metrics

DEBUG

Loader internals, demod helpers, unexpected branches

 
configure_logging("DEBUG")  # string form also accepted

ARCADE formats logs as:

[LEVEL] logger.name: message

Filter on arcade.stages.data, arcade.stages.classify, arcade.stages.hardware, or arcade.stages.visualization when the full zoo scrollback is too long.

[ ]:

from arcade.stages import DefaultDataStage, DefaultClassifyStage

cfg = load_config(CONFIG)
# Minimal reproduction: one classical method, no long neural training.
cfg.classifiers.run[:] = ["threshold"]  # mutate list in place

try:
    data_out = DefaultDataStage().run(cfg)
    print("data stage OK")
except Exception as exc:
    log.error("data stage failed: %s", exc)
    traceback.print_exc()
else:
    try:
        classify_out = DefaultClassifyStage().run(cfg, data_out)
        print("classify stage OK")
        print(classify_out.get("classifiers", {}).get("threshold", {}).get("metrics"))
    except Exception as exc:
        log.error("classify stage failed: %s", exc)
        traceback.print_exc()

Symptom → stage → fix

What you see

Stage

First fix

Missing HDF5 / path errors

Data

Fix data.path; run link_paper_data.sh

Demod / frequency / sampling errors

Data

Align data.demodulation with the file

Split sizes are zero or tiny

Data

Check data.split and label coverage

FEATURE_KIND / shape mismatches

Classify

arcade describe; shrink classifiers.run

ImportError for torch / iisignature

Classify

Install matching extras

Hardware disabled or empty LUTs

Hardware

Set hardware.enabled: true

No summary report

Visualization

Confirm metrics exist; check output_dir permissions

Joint accuracy absurd, per-qubit fine

Data labels

Flip / correct qubit_bit_order

CLI helpers

arcade validate configs/my.yaml
arcade explore data/my.h5 --qubits 5
arcade list
arcade describe fnn
arcade run configs/my.yaml

Python helpers

import arcade
arcade.describe("threshold")
# arcade.explore("data/my.h5", num_qubits=5)  # when available in your install

Minimal reproduction template

Copy this pattern when filing a bug or asking for help:

  1. Exact config path and the classifiers.run list.

  2. First ERROR or traceback, not only the last line.

  3. Whether demod cache was cold or warm.

  4. Output of arcade describe for the failing method.

  5. Whether arcade validate passed.

Re-run with a single classical method before claiming a neural method is broken.