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.

        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

Classical

Operates on matched-filter scores. Fast baselines, easy FPGA stories, shared filter_types bank.

Neural

Learns from IQ traces or filter scores with PyTorch. Needs torch and usually a companion nn_*.yaml.

Hybrid

Expands traces into rich features, then applies a linear or tree head. Bridges classical interpretability and learned capacity.

Ensemble

Wraps per-qubit sub-classifiers and merges labels. Useful when qubits differ strongly.

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

        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

        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 Build your own 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.

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

See Shared recipe for the full fairness rules.

Extend

Build your own method, including a transformer-style custom class, in Build your own classifier. A toy nearest-mean example lives under examples/custom_classifier/.