# Config schema

The source of truth for configuration is the Pydantic model tree in
``arcade/config.py``. Invalid YAML fails at ``arcade.config.load_config`` with
field paths and messages. Prefer validating with ``arcade validate`` before a
long run.

| Artifact | Role |
|----------|------|
| ``configs/example.yaml`` | Annotated template checked into the repository |
| ``arcade template`` | Emit a commented skeleton to standard output |
| {doc}`../how_to/compare_classifiers` | Fair bake-off pattern for your own traces |

## Top-level sections

| Key | Model | Default intent |
|-----|--------|----------------|
| ``data`` | ``DataConfig`` | Required. Path, keys, demodulation, and split |
| ``classifiers`` | ``ClassifiersConfig`` | Who runs and per-method options |
| ``tuning`` | ``TuningConfig`` | Off by default |
| ``sweep`` | ``SweepConfig`` | Duration and truncation sweep |
| ``hardware`` | ``HardwareConfig`` | Analytical FPGA estimate |
| ``visualization`` | ``VisualizationConfig`` | Plots and summary report |
| ``optimization`` | ``OptimizationConfig`` | Prune, distill, or quantize when enabled |
| ``qec`` | ``QECConfig`` | Optional logical error and FTQC curves |

## ``data`` highlights

| Field | Meaning |
|-------|---------|
| ``path`` | File path. Required. |
| ``format`` | ``auto``, ``hdf5``, ``npy``, ``npz``, or ``pickle`` |
| ``num_qubits`` | Qubit count. Required. |
| ``num_levels`` | ``2`` for qubit labels; ``3`` for leakage or qutrit labels |
| ``qubit_bit_order`` | ``lsb0`` for the zoo; ``msb0`` in some paper YAMLs. Wrong order destroys joint accuracy. |
| ``demodulation`` | Digital demodulation of ADC data: ``enabled``, ``frequencies``, ``sampling_rate``, and related fields |
| ``preprocessing`` | ``boxcar_window``, ``truncate_at``, ``normalize`` |
| ``split`` | ``mode: ratio`` or ``per_class`` with fixed counts |

## ``classifiers``

| Field | Notes |
|-------|-------|
| ``run`` | Registry names or dotted ``pkg.mod.Class`` paths. The magic value ``all`` expands to every registered name. |
| ``filter_types`` | Shared matched-filter bank. Default is ``[MF]``. |
| ``threshold_mode`` | ``per_qubit``, ``best_separation``, or ``otsu`` |
| Per-name blocks | For example ``fnn: { config_file: configs/nn_lienhard_fnn.yaml }`` |

Extra keys are allowed so each method can keep its own option dictionary.

## ``sweep``, ``hardware``, and ``visualization``

| Section | Key fields |
|---------|------------|
| ``sweep`` | ``enabled``, ``n_points``, ``lengths`` |
| ``hardware`` | ``enabled``, ``target_fpga``, ``clock_period_ns``, ``run_synthesis`` |
| ``visualization`` | ``output_dir``, ``format`` as ``pdf``, ``html``, or ``png``, plus ``summary_sections`` |

## Validate and run

```bash
arcade validate configs/example.yaml
arcade run configs/paper_all_methods_benchmark.yaml
arcade describe fnn
arcade list
```

Full model docs live under {doc}`api/index`.