# Classifiers reference

Every built-in discriminator implements
``arcade.classifiers.base.BaseClassifier`` and registers with
``register_classifier``. List them at runtime with ``arcade list``. Inspect one
name with ``arcade describe`` followed by the registry string.

The classify stage looks at each method’s ``FEATURE_KIND``, builds the matching
feature matrix once from the shared prepared traces, then calls ``fit`` and
``predict``. Choosing a method is therefore also choosing where it plugs into
the pipeline: filter scores, flattened IQ, or time-resolved sequences.

```{mermaid}
flowchart LR
  D[Data stage<br/>demod · split · cache] --> F[Feature build<br/>per FEATURE_KIND]
  F --> C[Classifier fit / predict]
  C --> H[Hardware estimate]
  C --> R[Summary report]
  C -.-> O[Optional optimization]
  O -.-> H
```

<div class="arcade-cards">
<div class="arcade-card classical">
<h4>Classical</h4>
<p>Operates on matched-filter scores. Fast baselines, easy FPGA stories, shared
<code>filter_types</code> bank.</p>
</div>
<div class="arcade-card neural">
<h4>Neural</h4>
<p>Learns from IQ traces or filter scores with PyTorch. Needs <code>torch</code> and usually
a companion <code>nn_*.yaml</code>.</p>
</div>
<div class="arcade-card hybrid">
<h4>Hybrid</h4>
<p>Expands traces into rich features, then applies a linear or tree head. Bridges
classical interpretability and learned capacity.</p>
</div>
<div class="arcade-card ensemble">
<h4>Ensemble</h4>
<p>Wraps per-qubit sub-classifiers and merges labels. Useful when qubits differ
strongly.</p>
</div>
</div>

## Support and maturity levels

| Level | Meaning |
|-------|---------|
| Reference benchmark | Included in the headline Readout 2019 comparison in ``configs/paper_all_methods_benchmark.yaml`` |
| Paper recipe | Dedicated ``configs/paper_*.yaml``; may differ slightly from the shared reference recipe |
| Experimental | Registered but not in the reference eight; use with care |
| Compatibility alias | Name retained for older configs; not the preferred paper algorithm |

## Reference eight-method benchmark

| Name | Category | Features | How it works | Pipeline fit | Paper or idea | Notes |
|------|----------|----------|--------------|--------------|---------------|-------|
| ``threshold`` | classical | filter scores | Cuts each matched-filter score at a learned or fixed level | After MF/RMF bank; no neural stack | Matched-filter plus cut | Fastest baseline |
| ``lda`` | classical | filter scores | Shared-covariance Gaussian discriminant on filter scores | Same filter matrix as threshold and QDA | Linear discriminant | Strong classical default |
| ``qda`` | classical | filter scores | Per-class full covariance on filter scores | Same filter matrix; heavier than LDA | Quadratic discriminant | More flexible, more parameters |
| ``mlp`` | classical | filter scores | scikit-learn multilayer perceptron on filter scores | Filter features only; not the Lienhard FNN path | sklearn MLP | Do not confuse with ``fnn`` |
| ``fnn`` | neural | IQ trace | Fully connected net on flattened demodulated IQ | Skips filter scores; uses ``iq_trace`` + ``nn_*.yaml`` | Lienhard-style FNN | Needs ``torch`` |
| ``herqules`` | neural | MF + RMF → NN | Filter bank first, then a network head on those scores | Filter features with HERQULES-style ``config_file`` | HERQULES-style | Call it style unless bit-exact |
| ``ngrc`` | hybrid | IQ poly + ridge | Polynomial expansion of IQ, then ridge readout | ``iq_trace`` into NG-RC feature builder | Next-gen reservoir | Prefer this name (``reservoir`` is a deprecated alias) |
| ``path_signature`` | hybrid | signature + RF | Path signature of the IQ trajectory, then random forest | ``iq_trace`` + ``iisignature`` extra | Cao et al. | Transfer caveat on Readout 2019 |

## Method detail: how each reference method moves through the pipeline

### Classical filter bank path

```{mermaid}
flowchart LR
  T[Prepared IQ traces] --> MF[Matched / relaxation filters]
  MF --> S[Filter score matrix]
  S --> TH[threshold]
  S --> LDA[lda / qda / mlp / svm …]
```

**threshold.** The oldest control-room story: build a matched filter, score each
shot, cut the score. In ARCADE it shares the frozen filter bank with every other
filter method so the cut is comparable.

**lda / qda.** Treat filter scores as a Gaussian feature space. LDA shares one
covariance across classes; QDA fits one per class. Both stay on
``FEATURE_KIND = filter_features``.

**mlp.** A scikit-learn neural net on the same filter scores. Useful as a
nonlinear classical baseline. It is not the Lienhard raw-trace ``fnn``.

### Neural and hybrid IQ paths

```{mermaid}
flowchart LR
  T[Prepared IQ traces] --> IQ[iq_trace matrix]
  IQ --> FNN[fnn]
  IQ --> NG[ngrc poly → ridge]
  IQ --> PS[path_signature → RF]
  T --> MF[Filter bank]
  MF --> HQ[herqules NN head]
```

**fnn.** Flattens demodulated IQ and trains a fully connected network from a
companion YAML. Pipeline fit: data → ``iq_trace`` features → PyTorch training →
metrics and analytical hardware.

**herqules.** Keeps the matched-filter front end, then trains a network on those
scores. Pipeline fit: data → shared filters → neural head. That is why zoo
``filter_types`` matter for HERQULES-style runs.

**ngrc.** Expands IQ into polynomial reservoir-style features and reads out with
ridge regression. Pipeline fit: data → ``iq_trace`` → NG-RC extractor → linear
head. Prefer the name ``ngrc``; ``reservoir`` is only a deprecated alias.

**path_signature.** Turns the IQ trajectory into a signature feature vector and
classifies with a random forest. Pipeline fit: data → ``iq_trace`` → signature
features → RF. Needs the ``signature`` extra.

## Paper and extended recipes

| Name | Category | Features | How it works | Pipeline fit | Paper | Notes |
|------|----------|----------|--------------|--------------|-------|-------|
| ``leakage`` | neural | MF / RMF / EMF | Multi-level heads with all-qubit filter inputs | Filter features; three-level labels | Mude et al. (DAC-3 lineage) | Prefer for 3-level / leakage recipes |
| ``multilevel`` | neural | same architecture | Shared-input multi-level network | Same feature path; architecture-focused name | DAC-3 lineage | Not leakage-specific by name |
| ``herqules_leakage`` | neural | MF + RMF + EMF + LMF | HERQULES-style head with leakage filters | Extended filter bank → NN | HERQULES leakage variant | Multi-level |
| ``hybrid`` | hybrid | filters → NN | Generic filter-bank plus network cousin of HERQULES | ``filter_features`` → NN | Generic hybrid | Explicit cousin of HERQULES-style |

## Classical extras on filter features

| Name | How it works | Pipeline fit |
|------|--------------|--------------|
| ``svm`` | Kernel SVM on filter scores | Same filter matrix as LDA |
| ``gmm`` | Per-class Gaussian mixtures on filter scores | Same filter matrix |
| ``gnb`` | Gaussian naive Bayes on filter scores | Same filter matrix; strongest independence assumption |

## Experimental and special names

| Name | Status | How it works | Pipeline fit | Notes |
|------|--------|--------------|--------------|-------|
| ``transformer`` | Experimental | Self-attention over time-resolved sequences | ``raw_trace_seq`` or related sequence kinds; needs ``torch`` and NN config | Not in the reference eight; see {doc}`../how_to/add_classifier` for a custom walkthrough |
| ``remf`` | Experimental | Relies on post-measurement labels | ``iq_trace`` with extra label contract | Not drop-in for the public zoo |
| ``per_qubit`` | Ensemble | Independent sub-classifier per qubit, then merge | Wraps another registry method per qubit | Useful when qubits are heterogeneous |
| ``reservoir`` | Deprecated alias of ``ngrc`` | Same as ``ngrc`` | Same as ``ngrc`` | Prefer ``ngrc`` |

## Feature kinds at a glance

| ``FEATURE_KIND`` | Typical methods | What the classify stage builds |
|------------------|-----------------|--------------------------------|
| ``filter_features`` | threshold, lda, qda, herqules, leakage | Matched-filter and related score matrix |
| ``iq_trace`` | fnn, ngrc, path_signature | Flattened or structured demodulated IQ |
| ``raw_trace_seq`` | transformer | Time-resolved sequences for attention models |

## Pitfalls checklist

Before claiming that a run reproduces paper X, check the paper YAML against the
zoo recipe.

<div class="arcade-pitfall">
<ul>
<li>HERQULES zoo filters are typically <code>[MF, RMF]</code>. Bit-exact paper parity needs
  the paper YAML.</li>
<li>Path-signature zoo configs may set <code>time_augmentation: true</code> while the paper
  path is two-dimensional I and Q.</li>
<li><code>mlp</code> is not <code>fnn</code>.</li>
<li><code>reservoir</code> is not a classical echo-state network; use <code>ngrc</code>.</li>
<li>Wrong <code>qubit_bit_order</code> destroys joint accuracy while per-qubit scores can
  still look fine.</li>
</ul>
</div>

See {doc}`../explanation/shared_recipe` for the full fairness rules.

## Extend

Build your own method, including a transformer-style custom class, in
{doc}`../how_to/add_classifier`. A toy nearest-mean example lives under
``examples/custom_classifier/``.