ARCADE documentation
====================

ARCADE stands for Automated Readout Classification, Analysis, Design, and
Evaluation. It is a research software package for comparing superconducting
qubit readout discriminators under a shared experimental recipe so that
accuracy numbers, measurement duration tradeoffs, and analytical FPGA cost
estimates can be read side by side without each paper inventing its own
evaluation protocol.

A microwave resonator returns an in-phase and quadrature time series for every
shot. A discriminator maps that series to a classical label. Different research
groups publish different discriminators. Without a common dataset split,
common metrics, and a common report shape, those publications are hard to
compare. ARCADE freezes those choices in YAML configuration files, runs every
registered method through the same preparation stages, and writes a comparison
report you can take to a lab meeting.

The pipeline in order is data preparation, feature extraction, classification,
optional classifier optimization for neural methods, hardware resource
estimation, and report generation. You may also enable quantum error correction
curves that translate readout error into logical error rate and wall-clock
cycle time. Optional stages stay off until you turn them on in configuration.

How to use this manual
----------------------

Read the sections in the sidebar order if you are new. Start with Quickstart
for an overview of the package and a working install. Continue with Guides when
you have a concrete goal such as bringing your own traces or enabling
optimization. Use the API Reference when you need exact signatures, registry
names, or configuration fields. Work through Tutorials last when you want a
paced, hands-on sitting that walks from a first zoo run to reading the report
in detail.

.. toctree::
   :maxdepth: 2
   :caption: Quickstart

   quickstart/index

.. toctree::
   :maxdepth: 2
   :caption: Guides

   how_to/index
   explanation/index

.. toctree::
   :maxdepth: 2
   :caption: API Reference

   reference/index

.. toctree::
   :maxdepth: 2
   :caption: Tutorials

   tutorials/index

Quickstart
----------

The Quickstart section introduces what ARCADE is for, how the pieces fit
together, how to install the package with the extras you need, and how to
verify that the command line entry points work. It is written for a first-time
reader who has not yet decided which classifier family to study.

Guides
------

Guides are goal-oriented. The how-to pages tell you how to compare classifiers
on your own data, how to register a new discriminator, how to enable pruning
or distillation or neural architecture search, and how to turn on quantum error
correction curves. The explanation pages go deeper into readout physics,
metrics such as joint accuracy and F5Q, the shared recipe philosophy, the
limits of analytical hardware estimates, and the bridge from readout error to
fault-tolerant cycle time.

API Reference
-------------

The API Reference is look-up documentation generated from the source tree and
from curated tables for the command line interface, the YAML schema, the
classifier registry, and the classifier optimization package. Prefer this
section when you already know the task and need precise names and parameters.

Tutorials
---------

Tutorials are learning sessions. They assume you already skimmed Quickstart.
They walk through a full public zoo run and then through reading the summary
report so that Accuracy, F5Q, LUT estimates, and latency columns become
familiar before you invent your own configuration.

Indices and search
------------------

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`