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: hardware estimation and report stage

This notebook covers analytical FPGA estimation and the visualization / report stage. You will see how hardware log lines look, where summary_report is written, and how to debug empty report directories.

Pipeline position

Data → Classify → [ Hardware ] → [ Visualization / Report ]
                 ↘ optional QEC

Hardware numbers are ranking aids. They are not place-and-route guarantees. The report stage is what turns per-method metrics into a shareable comparison.

[ ]:

from pathlib import Path
import logging

from arcade._logging import configure_logging
from arcade.config import load_config
from arcade.stages import (
    DefaultClassifyStage,
    DefaultDataStage,
    DefaultHardwareStage,
    DefaultVisualizationStage,
)

configure_logging(logging.INFO)

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

cfg = load_config(CONFIG)
cfg.classifiers.run[:] = ["threshold", "lda"]  # mutate list in place
cfg.hardware.enabled = True
cfg.visualization.output_dir = "output/tutorial_hardware_report"

print("hardware.enabled =", cfg.hardware.enabled)
print("output_dir =", cfg.visualization.output_dir)

[ ]:

data_out = DefaultDataStage().run(cfg)
classify_out = DefaultClassifyStage().run(cfg, data_out)
hardware_out = DefaultHardwareStage().run(cfg, classify_out)
print("hardware keys:", sorted(hardware_out.keys()) if isinstance(hardware_out, dict) else type(hardware_out))

viz_out = DefaultVisualizationStage().run(cfg, data_out, classify_out, hardware_out)
print("visualization result:", viz_out)

Expected log pattern

[INFO] arcade.stages.hardware: === Stage 3: Hardware ===
[INFO] arcade.stages.hardware:   threshold → LUT≈... DSP≈... latency≈... ns
[INFO] arcade.stages.classify: ...   # earlier classify lines omitted
[INFO] arcade.stages.visualization: === Stage 4: Visualization ===
[INFO] arcade.stages.visualization: Summary report: output/.../summary_report.pdf

If you see Hardware estimation disabled, hardware.enabled is false. If you see No classifier results → skipping summary report, classify returned nothing usable and you must fix Stage 2 first.

What to open after the run

output/tutorial_hardware_report/
├── summary_report.pdf   # or .html
├── results.json
├── threshold/
├── lda/
└── hardware/

Compare the report table against results.json when a PDF viewer hides a column. JSON is the ground truth for programmatic checks.

Debugging checklist

Symptom	Likely cause	What to try
No `summary_report`	Visualization disabled or no metrics	Enable visualization; confirm classify metrics exist
Empty hardware columns	`hardware.enabled: false`	Turn it on; re-run hardware stage only if your runner supports it
Synthesis warnings	`run_synthesis: true` without HLS/Vivado	Keep synthesis off unless you intend that path
Report exists but recommendation looks wrong	Reading F5Q instead of joint accuracy	Follow the Read the report tutorial order

Full pipeline shortcut

Once stage-wise debugging is done, prefer:

import arcade
arcade.run("path/to/config.yaml")

or arcade run path/to/config.yaml from the shell.

Next

For cross-stage failures, open Debugging the pipeline. For interpreting the PDF, return to the markdown tutorial Read the report.