arcade.api

High-level convenience API for ARCADE.

Functions

`compare`(data[, classifiers, num_qubits, ...])	Run multiple classifiers and compare results.
`describe`(classifier_name)	Return a multi-line description of a registered classifier.
`explore`(data, *[, num_qubits])	Print a human-readable data-quality summary to stdout.
`load`(path, num_qubits, *[, num_levels, format])	Load and prepare readout data for classification (data stage).

arcade.api.load(path, num_qubits, *, num_levels=2, format='auto', **kwargs)[source]

Load and prepare readout data for classification (data stage).

Prefer YAML + arcade.run() for full bake-offs. Use load() when you want an in-memory bundle for compare() or custom scripts.

Parameters:

path (str | Path) – Path to data file (HDF5, NPY, NPZ, or pickle).
num_qubits (int) – Number of qubits in the data.
num_levels (int) – Energy levels per qubit (default 2).
format (str) – File format or "auto" for detection.
**kwargs (Any) – Extra data: config fields (e.g. hdf5_keys, demodulation, multiplexed, qubit_bit_order).

Return type:

dict[str, Any]

Returns:

Prepared data dict with traces, labels, splits, and related stage outputs.

Raises:

arcade.config.ArcadeConfigError – Invalid combined config.
FileNotFoundError – path does not exist (via loader).

arcade.api.compare(data, classifiers=None, *, num_qubits=None, num_levels=2, sweep=True, hardware=True, report=False, output_dir='./output', **kwargs)[source]

Run multiple classifiers and compare results.

For production zoo runs, prefer arcade run configs/….yaml so demod, filters, and report sections stay in one file. compare() is the compact Python helper.

Parameters:

data (dict[str, Any] | str | Path) – Prepared dict from load(), or a path to a data file.
classifiers (list[str] | None) – Registry names. None defaults to ["threshold", "svm", "fnn"].
num_qubits (int | None) – Required when data is a file path.
num_levels (int) – Levels per qubit (default 2).
sweep (bool) – Enable readout-duration sweep.
hardware (bool) – Enable analytical FPGA resource estimation.
report (bool) – Generate a summary PDF/HTML report when supported.
output_dir (str) – Output directory for plots / reports.
**kwargs (Any) – Merged into the top-level config dict when data is a path (advanced; prefer a YAML file for complex recipes).

Return type:

Any

Returns:

PipelineResults when available, otherwise a plain results dict with data / classify / hardware keys.

Raises:

ValueError – File-path data without num_qubits.

arcade.api.explore(data, *, num_qubits=None)[source]

Print a human-readable data-quality summary to stdout.

Shows trace shapes, label histogram, split sizes, and whether transition detection ran. Intended for interactive debugging (also via arcade explore).

Parameters:

data (dict[str, Any] | str | Path) – Prepared dict from load(), or a path to load first.
num_qubits (int | None) – Required when data is a file path.

Raises:

ValueError – File-path data without num_qubits.

Return type:

None

arcade.api.describe(classifier_name)[source]

Return a multi-line description of a registered classifier.

Parameters:: classifier_name (str) – Registry name (e.g. "fnn", "threshold").
Return type:: str
Returns:: Text including category, FEATURE_KIND, and training / NN requirements. If the name is unknown, returns an error string listing available names (does not raise).