# First zoo run

You are about to run a public bake-off: several readout discriminators, one
frozen recipe, one report. By the end of this sitting you will have plots under
``output/`` and a ranking you can open in a lab meeting.

Complete {doc}`../quickstart/index` first if the package is not yet installed or
if you have not verified ``arcade list``.

<div class="arcade-mission">
<p><strong>Mission.</strong> Install the zoo extras, link the Readout 2019 files the bundled
configs expect, launch <code>configs/paper_all_methods_benchmark.yaml</code>, then open
the summary report and name a provisional winner under the shared recipe.</p>
</div>

```{mermaid}
flowchart LR
  A[Install extras] --> B[Link paper data]
  B --> C[arcade list]
  C --> D[arcade run zoo YAML]
  D --> E[Open summary report]
```

<ul class="arcade-pipeline">
  <li><strong>Prepare</strong><span>venv, extras, data symlinks</span></li>
  <li><strong>Launch</strong><span>one YAML, many methods</span></li>
  <li><strong>Inspect</strong><span>report table + plots</span></li>
  <li class="optional"><strong>Extend</strong><span>your traces or a custom class</span></li>
</ul>

## Install the extras used by the public zoo

```bash
cd ARCADE
pip install -e ".[torch,signature]"
bash scripts/link_paper_data.sh
arcade list
```

The ``link_paper_data.sh`` script symlinks Readout 2019 HDF5 files into
``data/`` so the bundled paper configs resolve. Verify the environment with:

```bash
python -c "import arcade; print('arcade import ok')"
arcade describe threshold
```

You should see a non-empty classifier list from ``arcade list`` and a short
description for ``threshold``. Treat that as your green light before the long
run.

### Optional extras you may need later

| Extra | Command | Enables |
|-------|---------|---------|
| Core only | ``pip install -e .`` | Threshold and scikit-learn baselines without PyTorch |
| ``torch`` | ``pip install -e ".[torch]"`` | FNN, HERQULES, leakage, multilevel, transformer |
| ``signature`` | ``pip install -e ".[signature]"`` | Path-signature classifier via ``iisignature`` |
| ``hardware`` | ``pip install -e ".[hardware]"`` | HLS4ML-oriented helpers |
| ``qec`` | ``pip install -e ".[qec]"`` | Stim-based logical error and FTQC curves |
| ``dev`` | ``pip install -e ".[dev]"`` | pytest and ruff |
| ``docs`` | ``pip install -e ".[docs]"`` | Sphinx build via ``make -C doc html`` |
| ``export`` | ``pip install -e ".[export]"`` | PDF figure export with PyMuPDF |
| All | ``pip install -e ".[all]"`` | Full dependency set |

## Run the public zoo

```bash
arcade run configs/paper_all_methods_benchmark.yaml
```

While it runs, the pipeline walks data preparation, feature build, classify for
every name in ``classifiers.run``, optional hardware estimation, and report
writing. Outputs land under ``output/``. Expect per-method plots and a summary
report when visualization is enabled in that configuration.

### Same run from Python

YAML is the supported public path. ADC file paths and demodulation settings
live in the config:

```python
import arcade

arcade.run("configs/paper_all_methods_benchmark.yaml")
```

Useful companion commands while you wait or after the run finishes:

```bash
arcade list
arcade describe fnn
```

## Point ARCADE at your own traces

Once the public zoo works, swap the data path and shrink the method list for a
faster personal bake-off:

```yaml
data:
  path: /path/to/your_traces.h5
  format: hdf5
  num_qubits: 5

classifiers:
  run: [threshold, lda, qda, svm, fnn, herqules]

sweep:
  enabled: true

visualization:
  output_dir: output/my_run
```

```bash
arcade run path/to/my_config.yaml
```

Fill demodulation and split fields so they match your file contract. Keep those
fields identical for every method in the run. See
{doc}`../how_to/compare_classifiers` for a fuller bake-off recipe, and
{doc}`../how_to/add_classifier` when you want a custom method beside the zoo.

## Next

Continue with {doc}`read_the_report` to interpret Accuracy, F5Q, LUT, and
latency columns. That tutorial is where the ranking becomes a decision rather
than a pile of files.