arcade.classifieroptimization

Classifier optimization: pruning, distillation, NAS, Optuna tuning.

Quantization uses arcade.nn.quantization.quantize_model() from the optimization stage (no separate QuantizationOptimizer class).

Optional post-classify stage for neural readout methods. Enable via optimization.enabled in YAML (see OptimizationConfig).

class arcade.classifieroptimization.BaseOptimizer

Bases: ABC

Interface for model optimization (pruning, distillation, NAS, etc.).

Subclass and decorate with @register_optimizer("name").

Example:

@register_optimizer("my_opt")
class MyOptimizer(BaseOptimizer):
    def optimize(self, model, train_data, val_data=None, **kwargs):
        ...
        return OptimizationResult(model=optimized)

name: str = 'base'

abstractmethod optimize(model, train_data, val_data=None, **kwargs)

Apply optimization to a model.

Parameters:

• model (Any) – The model to optimize.

• train_data (tuple[Any, Any]) – Tuple of (features, labels) for training.

• val_data (tuple[Any, Any] | None) – Optional tuple of (features, labels) for validation.

• **kwargs (Any) – Optimizer-specific options.

Return type:

OptimizationResult

Returns:

An OptimizationResult with the optimized model and metrics.

class arcade.classifieroptimization.DistillationOptimizer(student_sizes=None, temperature=3.0, accuracy_tolerance=0.01)

Bases: BaseOptimizer

Knowledge distillation from a teacher to smaller student models.

Parameters:

• student_sizes (list[int] | None)

• temperature (float)

• accuracy_tolerance (float)

name: str = 'distillation'

optimize(model, train_data, val_data=None, **kwargs)

Apply optimization to a model.

Parameters:

• model (Any) – The model to optimize.

• train_data (tuple[Any, Any]) – Tuple of (features, labels) for training.

• val_data (tuple[Any, Any] | None) – Optional tuple of (features, labels) for validation.

• **kwargs (Any) – Optimizer-specific options.

Return type:

OptimizationResult

Returns:

An OptimizationResult with the optimized model and metrics.

class arcade.classifieroptimization.HyperparameterTuner(method='optuna', n_trials=100, metric='accuracy', search_space=None)

Bases: BaseOptimizer

Hyperparameter tuning via Optuna or grid search.

Parameters:

• method (str)

• n_trials (int)

• metric (str)

• search_space (dict[str, Any] | None)

name: str = 'tuning'

optimize(model, train_data, val_data=None, **kwargs)

Apply optimization to a model.

Parameters:

• model (Any) – The model to optimize.

• train_data (tuple[Any, Any]) – Tuple of (features, labels) for training.

• val_data (tuple[Any, Any] | None) – Optional tuple of (features, labels) for validation.

• **kwargs (Any) – Optimizer-specific options.

Return type:

OptimizationResult

Returns:

An OptimizationResult with the optimized model and metrics.

class arcade.classifieroptimization.NASOptimizer(n_trials=50, max_hidden_layers=4, min_hidden_dim=16, max_hidden_dim=256)

Bases: BaseOptimizer

Neural Architecture Search using Optuna.

Parameters:

• n_trials (int)

• max_hidden_layers (int)

• min_hidden_dim (int)

• max_hidden_dim (int)

name: str = 'nas'

optimize(model, train_data, val_data=None, **kwargs)

Apply optimization to a model.

Parameters:

• model (Any) – The model to optimize.

• train_data (tuple[Any, Any]) – Tuple of (features, labels) for training.

• val_data (tuple[Any, Any] | None) – Optional tuple of (features, labels) for validation.

• **kwargs (Any) – Optimizer-specific options.

Return type:

OptimizationResult

Returns:

An OptimizationResult with the optimized model and metrics.

class arcade.classifieroptimization.OptimizationResult(model, original_params=0, optimized_params=0, accuracy_before=0.0, accuracy_after=0.0, pareto_points=<factory>, metadata=<factory>)

Bases: object

Result returned by an optimizer’s optimize() method.

Parameters:

• model (Any)

• original_params (int)

• optimized_params (int)

• accuracy_before (float)

• accuracy_after (float)

• pareto_points (list[Any])

• metadata (dict[str, Any])

accuracy_after: float = 0.0

accuracy_before: float = 0.0

optimized_params: int = 0

original_params: int = 0

model: Any

pareto_points: list[Any]

metadata: dict[str, Any]

class arcade.classifieroptimization.PruningOptimizer(sparsity=0.5, method='magnitude', iterative=True, n_steps=10)

Bases: BaseOptimizer

Magnitude-based iterative pruning with fine-tuning.

Parameters:

• sparsity (float)

• method (str)

• iterative (bool)

• n_steps (int)

name: str = 'pruning'

optimize(model, train_data, val_data=None, **kwargs)

Apply optimization to a model.

Parameters:

• model (Any) – The model to optimize.

• train_data (tuple[Any, Any]) – Tuple of (features, labels) for training.

• val_data (tuple[Any, Any] | None) – Optional tuple of (features, labels) for validation.

• **kwargs (Any) – Optimizer-specific options.

Return type:

OptimizationResult

Returns:

An OptimizationResult with the optimized model and metrics.

arcade.classifieroptimization.get_optimizer(name)

Look up an optimizer by registry name or dotted import path.

Return type:

type[BaseOptimizer]

Parameters:

name (str)

arcade.classifieroptimization.list_optimizers()

Return the names of all registered optimizers.

Return type:

list[str]

arcade.classifieroptimization.maybe_tune(cfg, clf_name, clf_cls, train_features, train_labels, val_features, val_labels, filter_set)

Conditionally run tuning if search_space is configured (moved from stages.py).

Return type:

dict | None

Parameters:

• cfg (Any)

• clf_name (str)

• clf_cls (type)

• train_features (ndarray)

• train_labels (ndarray)

• val_features (ndarray)

• val_labels (ndarray)

• filter_set (Any)

arcade.classifieroptimization.pareto_frontier(points)

Compute accuracy-vs-parameters Pareto frontier.

Each point should have "accuracy" and "n_parameters" keys. Returns the subset of non-dominated points sorted by parameter count.

Return type:

list[dict[str, Any]]

Parameters:

points (list[dict[str, Any]])

arcade.classifieroptimization.register_optimizer(name)

Decorator to register an optimizer class by name.

Parameters:

name (str)

arcade.classifieroptimization.run_optimization_stage(cfg, data_out, classify_out)

Apply optional compression / NAS / quantization to trained models.

Return type:

dict[str, Any]

Parameters:

• cfg (Any)

• data_out (dict[str, Any])

• classify_out (dict[str, Any])

arcade.classifieroptimization.select_best(points, budget)

Pick the smallest model within an accuracy budget.

budget is the maximum allowed accuracy drop from the best candidate.

Return type:

dict[str, Any]

Parameters:

• points (list[dict[str, Any]])

• budget (float)

arcade.classifieroptimization.tune(classifier_factory, train_features, train_labels, val_features, val_labels, *, method='optuna', n_trials=50, search_space=None, metric='val_accuracy', **kwargs)

Run hyperparameter optimization for a classifier.

Parameters:

• classifier_factory (Callable[..., Any]) – Callable that accepts a dict of hyperparameters and returns a fresh classifier instance.

• train_features (ndarray) – Training features.

• train_labels (ndarray) – Training labels.

• val_features (ndarray) – Validation features.

• val_labels (ndarray) – Validation labels.

• method (str) – "optuna" or "grid".

• n_trials (int) – Number of optimization trials (Optuna only).

• search_space (dict | None) – Per-parameter search ranges. For Optuna, values can be lists (categorical) or dicts with low/high (and optional log). For grid, all values must be lists.

• metric (str) – Metric to optimize (e.g. "val_accuracy").

• **kwargs (Any) – Forwarded to the classifier’s fit() method.

Return type:

dict[str, Any]

Returns:

Dict with "best_params", "best_score", and "study" (if Optuna) or "all_results" (if grid).