arcade.stages

Pipeline stage entry points (data, classify, hardware, visualization).

Functions

run_data_stage(cfg, *[, cache_dir, ...])

Run the default data stage (load, demodulate, split, transitions).

class arcade.stages.BaseClassifyStage

Bases: ABC

Train and evaluate classifiers (classify stage).

abstractmethod run(cfg, data_out)

Return type:

dict[str, Any]

Parameters:

• cfg (Any)

• data_out (dict[str, Any])

class arcade.stages.BaseDataStage

Bases: ABC

Load, demodulate, preprocess, split, and detect transitions.

abstractmethod run(cfg, *, cache_dir=None, demod_cache_path=None, classifiers_run=None)

Return type:

dict[str, Any]

Parameters:

• cfg (Any)

• cache_dir (str | Path | None)

• demod_cache_path (str | Path | None)

• classifiers_run (list[str] | None)

class arcade.stages.BaseFeatureStage

Bases: ABC

Compute filter banks / feature sets from transition results.

abstractmethod run(cfg, data_out)

Return type:

dict[str, Any]

Parameters:

• cfg (Any)

• data_out (dict[str, Any])

class arcade.stages.BaseHardwareStage

Bases: ABC

FPGA resource estimation and export.

abstractmethod run(cfg, classify_out)

Return type:

dict[str, Any]

Parameters:

• cfg (Any)

• classify_out (dict[str, Any])

class arcade.stages.BaseOptimizationStage

Bases: ABC

Post-training model optimization.

abstractmethod run(cfg, classify_out)

Return type:

dict[str, Any]

Parameters:

• cfg (Any)

• classify_out (dict[str, Any])

class arcade.stages.BaseVisualizationStage

Bases: ABC

Generate plots and summary reports.

abstractmethod run(cfg, data_out, classify_out, hardware_out)

Return type:

Path | None

Parameters:

• cfg (Any)

• data_out (dict[str, Any])

• classify_out (dict[str, Any])

• hardware_out (dict[str, Any])

class arcade.stages.DefaultClassifyStage

Bases: BaseClassifyStage

Train and evaluate classifiers from config.

Runs the feature stage for matched filters, then trains each classifier listed in cfg.classifiers.run (plus an optional custom classifier).

run(cfg, data_out)

Train/evaluate all configured classifiers.

Parameters:

• cfg (Any) – Pipeline config with data and classifiers blocks.

• data_out (dict[str, Any]) – Output of the data stage (splits, transition_result, optional post_measured).

Return type:

dict[str, Any]

Returns:

Dict with filter_set and classifiers (per-name results containing model, metrics, history, sweep, …). If splits is missing, returns empty classifier results.

run_single_classifier(clf_name, *, cfg, filter_set, splits, transition_result, feature_registry, post_measured=None)

Train and evaluate one classifier, optionally with length sweep.

Parameters:

• clf_name (str) – Registered classifier name (e.g. threshold, ngrc).

• cfg (Any) – Pipeline config (training, sweep, tuning, data knobs).

• filter_set (Any) – Matched-filter bank from the feature stage (may be None for trace-only classifiers).

• splits (Any) – Train/val/test split object from the data stage.

• transition_result (Any) – Transition detection result used for length sweeps (may be None when sweep is disabled).

• feature_registry (Any) – Module exposing get_feature_fn (usually arcade.features.kinds).

• post_measured (dict[str, ndarray] | None) – Optional post-measurement labels keyed by split name (train / val / test), used by REMF.

Return type:

dict[str, Any]

Returns:

Dict with model, metrics, history, sweep, best_params, benchmark_features, and benchmark_traces.

arcade.stages.DefaultDataStage

alias of Readout2019DataStage

class arcade.stages.DefaultFeatureStage

Bases: BaseFeatureStage

Compute MF / RMF / EMF matched filters from transition results.

run(cfg, data_out)

Build the matched-filter bank used by filter-set classifiers.

Parameters:

• cfg (Any) – Pipeline config (data.transitions, classifiers.filter_types).

• data_out (dict[str, Any]) – Data-stage dict; uses transition_result and optional spectral_labels for effective level count.

Return type:

dict[str, Any]

Returns:

Dict with filter_set, filter_types, and transition_result. filter_set is None when no transition result is available.

class arcade.stages.DefaultHardwareStage

Bases: BaseHardwareStage

FPGA resource estimation, export, and design-space exploration.

run(cfg, classify_out)

Estimate resources, optionally export HLS, and run DSE.

Parameters:

• cfg (Any) – Pipeline config (hardware block).

• classify_out (dict) – Classify-stage output (classifiers, optional optimization).

Return type:

dict[str, Any]

Returns:

Dict with reports, scalability, exports, dse, and comparisons. Empty collections when hardware is disabled.

class arcade.stages.DefaultOptimizationStage

Bases: BaseOptimizationStage

Apply pruning, distillation, NAS, and quantization.

run(cfg, classify_out)

Return type:

dict[str, Any]

Parameters:

• cfg (Any)

• classify_out (dict[str, Any])

class arcade.stages.DefaultVisualizationStage

Bases: BaseVisualizationStage

Generate plots and summary reports.

run(cfg, data_out, classify_out, hardware_out)

Write stage plots and a summary report under visualization.output_dir.

Parameters:

• cfg (Any) – Pipeline config (visualization block selects stages/format).

• data_out (dict) – Data-stage output (IQ clusters / averaged traces).

• classify_out (dict) – Classify-stage output (filters, metrics, sweeps).

• hardware_out (dict) – Hardware-stage output (resource / DSE plots).

Return type:

Path | None

Returns:

Path to the summary report, or None if no classifier results.

class arcade.stages.Readout2019DataStage

Bases: BaseDataStage

Load, split (indices first), demodulate, preprocess, detect transitions.

run(cfg, *, cache_dir=None, demod_cache_path=None, classifiers_run=None)

Load and prepare IQ traces for downstream classify / hardware stages.

Parameters:

• cfg (Any) – Pipeline config (data block drives loaders, demod, preprocessing, transitions, and split).

• cache_dir (str | Path | None) – Optional root for demod / spectral / transition caches.

• demod_cache_path (str | Path | None) – Optional explicit demod-cache file path.

• classifiers_run (list[str] | None) – Classifier names used when transitions.auto plans leakage vs filter-only detection.

Return type:

dict[str, Any]

Returns:

Data-stage dict with bundle, traces, labels, label_set, relaxation_result, transition_result, spectral_labels, splits, and flat train/val/test keys when splits are available. May include post_measured.

arcade.stages.hydrate_data_out(data_out)

Ensure flat train/val/test keys exist (e.g. after loading old pickles).

Parameters:

data_out (dict[str, Any]) – Data-stage dict that may only expose nested splits.

Return type:

dict[str, Any]

Returns:

The same dict if already flat, otherwise a shallow copy with train_traces / train_labels / … copied from splits.

arcade.stages.data_out_data_fraction(data_out, frac)

Subsample train/val/test splits; keep transition_result unchanged.

Parameters:

• data_out (dict[str, Any]) – Hydrated or nest-only data-stage dict.

• frac (float) – Fraction of each split to keep, in (0, 1].

Return type:

dict[str, Any]

Returns:

Shallow copy with subsampled traces, labels, and indices.

Raises:

ValueError – If frac is not in (0, 1].

arcade.stages.data_out_labels_placeholder(features)

Zero labels placeholder for DSE resource-only sweeps.

Parameters:

features (Any) – Feature matrix whose leading dimension sets label length.

Return type:

Any

Returns:

int64 zero vector of length len(features).

arcade.stages.resolve_cache_paths(dcfg, *, cache_dir, demod_cache_path)

Resolve demod / transition / spectral cache locations.

Parameters:

• dcfg (Any) – Data config block (demodulation, transitions).

• cache_dir (str | Path | None) – If set, all caches live under this directory (demod_traces.pkl, spectral_cache, transitions).

• demod_cache_path (str | Path | None) – Explicit demod-cache file; overrides dcfg.demodulation.cache_path when cache_dir is unset.

Return type:

dict[str, Path | None]

Returns:

Dict with keys demod, spectral, and transition (each a Path or None).

arcade.stages.transition_plan(tcfg, classifiers_run)

Decide which transition detectors to run for this pipeline.

Parameters:

• tcfg (Any) – Transitions config (enabled, auto, method, …).

• classifiers_run (list[str] | None) – Classifier names from classifiers.run. Used when tcfg.auto is true to enable leakage or filter-only detection.

Return type:

tuple[bool, bool, str]

Returns:

Tuple (run_relaxations, run_leakage, leakage_method).

arcade.stages.run_data_stage(cfg, *, cache_dir=None, demod_cache_path=None, classifiers_run=None)

Run the default data stage (load, demodulate, split, transitions).

Thin wrapper around DefaultDataStage.

Parameters:

• cfg (Any) – Pipeline config (typically ArcadeConfig).

• cache_dir (str | Path | None) – Optional root for demod / spectral / transition caches.

• demod_cache_path (str | Path | None) – Optional explicit demod-cache file path.

• classifiers_run (list[str] | None) – Classifier names used to auto-plan transition detection when transitions.auto is enabled.

Return type:

dict[str, Any]

Returns:

Data-stage dict with traces, labels, splits, and transition results.

arcade.stages.run_classify_stage(cfg, data_out)

Run the default classify stage.

Thin wrapper around DefaultClassifyStage.

Parameters:

• cfg (Any) – Pipeline config with data and classifiers blocks.

• data_out (dict) – Output of the data stage.

Return type:

dict[str, Any]

Returns:

Classify-stage dict (filter_set, classifiers).

arcade.stages.run_single_classifier(*args, **kwargs)

Train and evaluate one classifier (module-level entry point).

Backward-compatible wrapper around DefaultClassifyStage.run_single_classifier().

Parameters:

• *args (Any) – Positional args forwarded to DefaultClassifyStage.run_single_classifier().

• **kwargs (Any) – Keyword args forwarded to DefaultClassifyStage.run_single_classifier().

Return type:

dict[str, Any]

Returns:

Per-classifier result dict (model, metrics, …).

arcade.stages.run_hardware_stage(cfg, classify_out)

Run the default hardware stage.

Thin wrapper around DefaultHardwareStage.

Parameters:

• cfg (Any) – Pipeline config (hardware block).

• classify_out (dict) – Classify-stage output.

Return type:

dict[str, Any]

Returns:

Hardware-stage dict (reports, scalability, …).

arcade.stages.run_visualization_stage(cfg, data_out, classify_out, hardware_out)

Run the default visualization stage.

Thin wrapper around DefaultVisualizationStage.

Parameters:

• cfg (Any) – Pipeline config (visualization block).

• data_out (dict) – Data-stage output.

• classify_out (dict) – Classify-stage output.

• hardware_out (dict) – Hardware-stage output.

Return type:

Path | None

Returns:

Path to the summary report, or None if skipped.