# Enable optimization

Classifier optimization is an optional stage aimed at neural readout methods.
It can prune weights, distill a student from a teacher, search architectures,
reduce bit width via ``arcade.nn.quantization``, or tune hyperparameters with
Optuna. The canonical package is ``arcade.classifieroptimization``.
``arcade.optimization`` re-exports the same public API.

Classical baselines ignore these knobs. If your ``classifiers.run`` list
contains only threshold or scikit-learn methods, leave optimization disabled.

## See it in action

```bash
pip install -e ".[torch]"
bash scripts/link_paper_data.sh
python examples/run_optimization_demo.py
# or open examples/optimization_usecase.ipynb
```

Recipe: ``configs/example_optimization.yaml`` (small split, few NAS trials).

## Flip the switch in YAML

```yaml
optimization:
  enabled: true
  target_classifiers: [fnn, herqules]
  error_budget: 0.01
  pruning:
    enabled: true
  distillation:
    enabled: false
  quantization:
    enabled: true      # uses arcade.nn.quantization.quantize_model
  nas:
    enabled: true
    n_trials: 8
```

An empty ``target_classifiers`` list means every eligible neural method in the
run is considered. ``error_budget`` is the allowed accuracy drop relative to
the unoptimized baseline.

## What runs

When ``optimization.enabled`` is true, the pipeline calls
``run_optimization_stage`` after classify. Candidates that stay within the
error budget form a Pareto set (accuracy vs size / method).

| Knob | Implementation | Intent |
|------|----------------|--------|
| ``pruning`` | ``PruningOptimizer`` / stage helpers | Sparse weights within ``error_budget`` |
| ``distillation`` | ``DistillationOptimizer`` | Student from teacher logits |
| ``quantization`` | ``arcade.nn.quantization`` | Lower bit-width representation |
| ``nas`` | ``NASOptimizer`` / ``nn.nas`` | Architecture search |
| ``tuning`` (top-level) | ``HyperparameterTuner`` | Optuna or grid search |

## Caveats

Do not mix optimized and unoptimized networks in one ranking table without
labeling rows. Analytical hardware estimates still do not prove bitstream
timing. Full API: {doc}`../reference/classifieroptimization`.