# Read the report

The zoo run is finished. Somewhere under ``visualization.output_dir`` sits a
summary report and a ``results.json``. This tutorial treats that report like a
case file: open it, read the headline table, check the traps, then decide what
to ship or what to rerun.

<div class="arcade-mission">
<p><strong>Mission.</strong> Open <code>summary_report.pdf</code> or HTML, explain joint accuracy versus
F5Q versus PQ min in one sentence each, and say whether the recommendation box
survives the hardware columns.</p>
</div>

```{mermaid}
flowchart TB
  OUT[output directory] --> PDF[summary_report]
  OUT --> JSON[results.json]
  PDF --> TAB[Comparison table]
  TAB --> REC[Recommendation box]
  TAB --> HW[LUT · DSP · latency]
  REC --> DEC{Ship, tune, or rerun?}
  HW --> DEC
```

## Where to look

After ``arcade run`` finishes, open the directory named by
``visualization.output_dir``. A typical layout looks like this:

```text
{visualization.output_dir}/
├── summary_report.pdf
├── results.json
├── data/
├── filters/
├── {classifier}/
├── sweep/
└── hardware/
```

<ul class="arcade-pipeline">
  <li><strong>data/</strong><span>IQ scatter, averaged traces</span></li>
  <li><strong>filters/</strong><span>MF / RMF envelopes</span></li>
  <li><strong>{method}/</strong><span>confusion, training curves</span></li>
  <li class="optional"><strong>sweep/</strong><span>speed vs fidelity</span></li>
  <li class="optional"><strong>hardware/</strong><span>resource comparison</span></li>
</ul>

Configuration knobs that change report shape include
``visualization.summary_sections``, ``visualization.report_detail``, and
``visualization.format``. Supported formats include ``pdf`` and ``html``.

## Anatomy of report detail tiers

| Tier | ``report_detail`` | Contents |
|------|-------------------|----------|
| Executive | ``summary`` and above | Comparison table with Accuracy, Infidelity, F5Q, PQ min, LUT, DSP, and Latency in nanoseconds; confusion small-multiples; speed and fidelity overlay; recommendation for highest joint accuracy |
| Detail | ``standard`` and above | Per-qubit fidelity table; per-classifier confusion and hardware blurbs |
| Appendix | ``full`` | Cross-fidelity heatmap; grouped per-qubit bars |

## How to read the comparison table

Read the table left to right as a story, not as a single scoreboard number.

**Accuracy joint** is the fraction of shots where the full multi-qubit label
matches. On five qubits this is a thirty-two class problem. It is harder than
averaging per-qubit scores. This is usually the ranking key in the
recommendation box.

**F5Q** is a geometric or product-style aggregation of per-qubit fidelities.
It is useful when joint accuracy is dominated by one weak qubit. Read it next
to PQ min.

**PQ min** is the worst single-qubit fidelity. It flags imbalance across the
device. A method can win joint accuracy while quietly harming one qubit your
algorithm cares about.

**LUT, DSP, and Latency** are analytical FPGA estimates from
``arcade.hardware``. Treat them as ranking aids, not bitstream guarantees.

**Recommendation box** highlights the highest joint accuracy under this shared
recipe. Always check the hardware columns before deciding what to ship.

<div class="arcade-checklist">
<p><strong>Quick read order.</strong> Joint accuracy → PQ min → F5Q → hardware columns →
recommendation box. If any step disagrees with the box, write down why before
you trust the ranking.</p>
</div>

## Pitfalls checks

```{warning}
A wrong ``data.qubit_bit_order`` systematically destroys joint accuracy while
per-qubit numbers can still look plausible. The zoo default is ``lsb0``. Path
signature results on Readout 2019 under the zoo recipe are transfer results.
Analytical LUT wins are not Vivado timing closure. See
{doc}`../explanation/shared_recipe` and {doc}`../explanation/metrics` before
claiming paper parity.
```

## Next

Read {doc}`../explanation/metrics` for formal column definitions,
{doc}`../explanation/hardware_limits` for FPGA caveats, and
{doc}`../reference/classifiers` for how each method earned its row. When you
are ready to add your own row, open {doc}`../how_to/add_classifier`.