arcade.config

Configuration loading and Pydantic validation.

Functions

generate_template(num_qubits[, classifiers])

Return a commented YAML config string with all sections.

load_config(source)

Load and validate an ARCADE configuration.

validate_and_explain(source)

Validate a config source and return human-readable error messages.

Classes

ArcadeConfig(**data)

Top-level ARCADE configuration, validated via Pydantic.

ClassifiersConfig(**data)

Classifier selection and per-classifier options.

DSEConfig(**data)

Design-space exploration sweep settings.

DataConfig(**data)

Full data-stage configuration.

DemodulationConfig(**data)

Digital demodulation settings.

DistillationConfig(**data)

Knowledge-distillation settings.

HDF5KeysConfig(**data)

HDF5 dataset key names.

HardwareConfig(**data)

FPGA synthesis and resource estimation settings.

NASConfig(**data)

Neural architecture search settings.

OptimizationConfig(**data)

Post-training classifier optimization (pruning / distill / NAS / quant).

PipelineConfig(**data)

Optional block pipeline overriding implicit stage wiring.

PipelineStepConfig(**data)

One composable pipeline block (Phase 2 mix-and-match).

PreprocessingConfig(**data)

Preprocessing pipeline settings.

PruningConfig(**data)

Structured / iterative pruning settings.

QECCodeConfig(**data)

Per-code stim parameters.

QECConfig(**data)

Stim-based logical error rate + FTQC timing curves (Phase 6).

QuantizationConfig(**data)

Quantization-aware training settings.

ReadoutTimingConfig(**data)

Timing model for readout_time = acquisition + transfer + inference.

SplitConfig(**data)

Train / val / test splitting (ratio-based or fixed per-class counts).

SweepConfig(**data)

Readout-duration sweep settings.

TransitionsConfig(**data)

Transition detection settings.

TuningConfig(**data)

Hyperparameter tuning settings.

VisualizationConfig(**data)

Visualization and reporting settings.

Exceptions

ArcadeConfigError

Raised when ARCADE configuration validation fails.
exception arcade.config.ArcadeConfigError[source]

Bases: ValueError

Raised when ARCADE configuration validation fails.

class arcade.config.HDF5KeysConfig(**data)[source]

Bases: BaseModel

HDF5 dataset key names.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:
traces: str
labels: str
time: str
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class arcade.config.DemodulationConfig(**data)[source]

Bases: BaseModel

Digital demodulation settings.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • enabled (bool)

  • frequencies (list[float])

  • sampling_rate (float)

  • time_bin_width (float | None)

  • skip_samples (int)

  • correct_iq_offset (bool)

  • correct_iq_amplitude (bool)

  • pre_demodulated (bool)

  • cache_path (str | None)

  • cache_force_rebuild (bool)

  • cache_auto_save (bool)

enabled: bool
frequencies: list[float]
sampling_rate: float
time_bin_width: float | None
skip_samples: int
correct_iq_offset: bool
correct_iq_amplitude: bool
pre_demodulated: bool
cache_path: str | None
cache_force_rebuild: bool
cache_auto_save: bool
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class arcade.config.PreprocessingConfig(**data)[source]

Bases: BaseModel

Preprocessing pipeline settings.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • boxcar_window (int | None)

  • truncate_at (int | None)

  • normalize (bool)

boxcar_window: int | None
truncate_at: int | None
normalize: bool
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class arcade.config.TransitionsConfig(**data)[source]

Bases: BaseModel

Transition detection settings.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • enabled (bool)

  • auto (bool)

  • method (Literal['centroid_radius', 'spectral', 'gmm'])

  • radius_scale (float)

  • n_clusters (int)

  • cache_path (str | None)

  • cache_force_rebuild (bool)

  • spectral_cache_path (str | None)

  • spectral_cache_force_rebuild (bool)

  • leakage (bool)

  • leakage_from_state (int)

  • effective_levels (int | None)

enabled: bool
auto: bool
method: Literal['centroid_radius', 'spectral', 'gmm']
radius_scale: float
n_clusters: int
cache_path: str | None
cache_force_rebuild: bool
spectral_cache_path: str | None
spectral_cache_force_rebuild: bool
leakage: bool
leakage_from_state: int
effective_levels: int | None
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class arcade.config.SplitConfig(**data)[source]

Bases: BaseModel

Train / val / test splitting (ratio-based or fixed per-class counts).

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • mode (Literal['ratio', 'per_class'])

  • train_ratio (float)

  • val_ratio (float)

  • test_ratio (float)

  • train_per_class (int | None)

  • val_per_class (int | None)

  • test_per_class (int | None)

  • stratified (bool)

  • shuffle (bool)

  • seed (int)

mode: Literal['ratio', 'per_class']
train_ratio: float
val_ratio: float
test_ratio: float
train_per_class: int | None
val_per_class: int | None
test_per_class: int | None
stratified: bool
shuffle: bool
seed: int
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class arcade.config.DataConfig(**data)[source]

Bases: BaseModel

Full data-stage configuration.

Describes how to load traces and labels, whether to demodulate ADC data, preprocessing, transition detection, and train/val/test splits. See the docs config schema and configs/example.yaml.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:
path: str
format: Literal['auto', 'hdf5', 'npy', 'npz', 'pickle']
loader: str
path_signature_dataset: str
path_signature_time_truncation: float
path_signature_label_source: Literal['expected', 'gmm', 'post_measured']
path_signature_max_per_class: int | None
hdf5_keys: HDF5KeysConfig
num_qubits: int
num_levels: int
addressing: Literal['group', 'individual']
multiplexed: bool
label_format: Literal['state_sorted', 'joint', 'per_qubit']
qubit_bit_order: Literal['lsb0', 'msb0']
demodulation: DemodulationConfig
preprocessing: PreprocessingConfig
transitions: TransitionsConfig
split: SplitConfig
custom_processor: str | None
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class arcade.config.ClassifiersConfig(**data)[source]

Bases: BaseModel

Classifier selection and per-classifier options.

run lists registry names or dotted package.module.ClassName paths. Additional keys (e.g. fnn:, herqules:) hold method-specific options and are allowed via extra="allow".

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • run (list[str])

  • custom_classifier (str | None)

  • filter_types (list[str])

  • threshold_mode (Literal['per_qubit', 'best_separation', 'otsu'])

  • threshold_percentile (float | None)

  • name_style (Literal['short', 'full'])

  • extra_data (Any)

run: list[str]
custom_classifier: str | None
filter_types: list[str]
threshold_mode: Literal['per_qubit', 'best_separation', 'otsu']
threshold_percentile: float | None
name_style: Literal['short', 'full']
model_config: ClassVar[ConfigDict] = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class arcade.config.TuningConfig(**data)[source]

Bases: BaseModel

Hyperparameter tuning settings.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:
enabled: bool
method: Literal['optuna', 'grid']
n_trials: int
metric: str
search_space: dict[str, Any]
model_config: ClassVar[ConfigDict] = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class arcade.config.ReadoutTimingConfig(**data)[source]

Bases: BaseModel

Timing model for readout_time = acquisition + transfer + inference.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:
sampling_period_ns: float
data_transfer_ns: float
inference_ns: float
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class arcade.config.SweepConfig(**data)[source]

Bases: BaseModel

Readout-duration sweep settings.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:
enabled: bool
n_points: int
lengths: list[int] | None
timing: ReadoutTimingConfig
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class arcade.config.DSEConfig(**data)[source]

Bases: BaseModel

Design-space exploration sweep settings.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:
enabled: bool
reuse_factors: list[int]
precisions: list[str]
io_types: list[str]
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class arcade.config.HardwareConfig(**data)[source]

Bases: BaseModel

FPGA synthesis and resource estimation settings.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:
enabled: bool
target_fpga: str
backend: str
clock_period_ns: float
io_type: Literal['io_parallel', 'io_stream']
reuse_factor: int
precision: str
run_synthesis: bool
run_vivado: bool
export_hls4ml: bool
export_dir: str
dse_enabled: bool
dse: DSEConfig
model_config: ClassVar[ConfigDict] = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class arcade.config.PruningConfig(**data)[source]

Bases: BaseModel

Structured / iterative pruning settings.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • enabled (bool)

  • method (Literal['iterative', 'structured'])

  • prune_fraction_per_step (float)

  • n_steps (int)

  • finetune_epochs (int)

enabled: bool
method: Literal['iterative', 'structured']
prune_fraction_per_step: float
n_steps: int
finetune_epochs: int
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class arcade.config.DistillationConfig(**data)[source]

Bases: BaseModel

Knowledge-distillation settings.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:
enabled: bool
temperature: float
student_sizes: list[int]
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class arcade.config.QuantizationConfig(**data)[source]

Bases: BaseModel

Quantization-aware training settings.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • enabled (bool)

  • precision (Literal['int8', 'int16', 'fp16'])

  • finetune_epochs (int)

enabled: bool
precision: Literal['int8', 'int16', 'fp16']
finetune_epochs: int
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class arcade.config.NASConfig(**data)[source]

Bases: BaseModel

Neural architecture search settings.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • enabled (bool)

  • network_type (Literal['fnn', 'hybrid', 'transformer'])

  • n_trials (int)

  • max_params (int | None)

  • max_hidden_layers (int)

  • min_hidden_dim (int)

  • max_hidden_dim (int)

  • hardware_aware (bool)

enabled: bool
network_type: Literal['fnn', 'hybrid', 'transformer']
n_trials: int
max_params: int | None
max_hidden_layers: int
min_hidden_dim: int
max_hidden_dim: int
hardware_aware: bool
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class arcade.config.OptimizationConfig(**data)[source]

Bases: BaseModel

Post-training classifier optimization (pruning / distill / NAS / quant).

Canonical implementation lives in arcade.classifieroptimization.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:
enabled: bool
target_classifiers: list[str]
error_budget: float
pruning: PruningConfig
distillation: DistillationConfig
quantization: QuantizationConfig
nas: NASConfig
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class arcade.config.VisualizationConfig(**data)[source]

Bases: BaseModel

Visualization and reporting settings.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • output_dir (str)

  • format (Literal['pdf', 'png', 'html'])

  • dpi (int)

  • stages (list[str])

  • show_iq_clusters (bool)

  • show_averaged_traces (bool)

  • report_detail (Literal['summary', 'standard', 'full'])

  • target_infidelity (float | None)

  • summary_sections (list[str])

output_dir: str
format: Literal['pdf', 'png', 'html']
dpi: int
stages: list[str]
show_iq_clusters: bool
show_averaged_traces: bool
report_detail: Literal['summary', 'standard', 'full']
target_infidelity: float | None
summary_sections: list[str]
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class arcade.config.PipelineStepConfig(**data)[source]

Bases: BaseModel

One composable pipeline block (Phase 2 mix-and-match).

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:
block: str
enabled: bool
model_config: ClassVar[ConfigDict] = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class arcade.config.PipelineConfig(**data)[source]

Bases: BaseModel

Optional block pipeline overriding implicit stage wiring.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

steps (list[PipelineStepConfig])

steps: list[PipelineStepConfig]
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class arcade.config.QECCodeConfig(**data)[source]

Bases: BaseModel

Per-code stim parameters.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:

  • distance (int)

  • rounds (int)

  • extra_data (Any)

distance: int
rounds: int
model_config: ClassVar[ConfigDict] = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class arcade.config.QECConfig(**data)[source]

Bases: BaseModel

Stim-based logical error rate + FTQC timing curves (Phase 6).

Use for readout-error ↔ accuracy maps, LER vs readout duration (cycle-time tradeoff), and decoder-latency vs readout time (wall-clock memory experiments) on surface / color / BB codes.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:
enabled: bool
shots: int
seed: int
codes: list[str]
experiments: list[str]
surface: QECCodeConfig
bb: QECCodeConfig
color: QECCodeConfig
walking_surface: QECCodeConfig
readout_binding: dict[str, Any]
decoders: dict[str, str]
accuracy_error_curve: bool
ler_duration_curve: bool
synthetic_duration_curve: bool
curve_points: int
curve_shots: int
control_overhead_ns: float
tau_idle_ns: float
include_decode_in_idle: bool
idle_p_floor: float
model_config: ClassVar[ConfigDict] = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class arcade.config.ArcadeConfig(**data)[source]

Bases: BaseModel

Top-level ARCADE configuration, validated via Pydantic.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:
data: DataConfig
classifiers: ClassifiersConfig
tuning: TuningConfig
sweep: SweepConfig
hardware: HardwareConfig
visualization: VisualizationConfig
optimization: OptimizationConfig
pipeline: PipelineConfig | None
qec: QECConfig
model_config: ClassVar[ConfigDict] = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

arcade.config.load_config(source)[source]

Load and validate an ARCADE configuration.

Parameters:

source (Union[str, Path, dict]) – Path to a YAML file, or an already-parsed dict.

Return type:

ArcadeConfig

Returns:

A validated ArcadeConfig instance.

Raises:
arcade.config.generate_template(num_qubits, classifiers=None)[source]

Return a commented YAML config string with all sections.

Parameters:

  • num_qubits (int) – Number of qubits for the data section.

  • classifiers (list[str] | None) – List of classifier names to include; defaults to [“threshold”].

Return type:

str

Returns:

A YAML string with comments suitable for writing to a config file.

arcade.config.validate_and_explain(source)[source]

Validate a config source and return human-readable error messages.

Parameters:

source (Union[str, Path, dict]) – A dict, file path string, or Path to a YAML config.

Return type:

list[str]

Returns:

A list of human-readable error strings. Empty list means valid.