arcade.classifiers

ARCADE classifiers.

class arcade.classifiers.BaseClassifier

Bases: ABC

Contract every ARCADE discriminator must satisfy.

Class attributes control how the pipeline builds features and trains:

• FEATURE_KIND — which feature matrix the classify stage builds (filter_features, iq_trace, …).

• CATEGORY — classical · neural · hybrid · ensemble.

• REQUIRES_NN_CONFIG — if true, YAML must supply config_file / NN dict.

• CLASSIFICATION_MODE — joint vs per-qubit decoding hints for metrics.

Subclass, set those attributes, implement fit() / predict(), and decorate with register_classifier().

Example:

@register_classifier("my_clf")
class MyClassifier(BaseClassifier):
    CATEGORY = "classical"
    FEATURE_KIND = "filter_features"

    def fit(self, train_features, train_labels, **kwargs):
        ...
        return self

    def predict(self, features):
        ...
        return labels

CATEGORY: Literal['classical', 'neural', 'hybrid', 'ensemble'] = 'classical'

CLASSIFICATION_MODE: str = 'joint'

DESCRIPTION: str = ''

FEATURE_KIND: str = 'filter_features'

REQUIRES_NN_CONFIG: bool = False

REQUIRES_TRAINING: bool = True

SUPPORTED_FEATURE_KINDS: tuple[str, ...] | None = None

TUNABLE: dict[str, Any] | bool = {}

USES_IQ_TRACES: bool = False

abstractmethod fit(train_features, train_labels, val_features=None, val_labels=None, **kwargs)

Train or fit the classifier on the prepared feature matrix.

Parameters:

• train_features (ndarray) – Array shaped (n_train, feature_dim) (or method-specific).

• train_labels (ndarray) – Integer labels aligned with train_features.

• val_features (ndarray | None) – Optional validation features for early stopping / model selection.

• val_labels (ndarray | None) – Optional validation labels.

• **kwargs (Any) – Method-specific options (epochs, device, …).

Return type:

BaseClassifier

Returns:

self, for method chaining.

classmethod from_config(config)

Construct an instance from a YAML / dict section for this classifier.

Parameters:

config (dict[str, Any]) – Merged options from the global classifiers block and any per-name subsection (plus pipeline-injected keys such as filter_set for some methods).

Return type:

BaseClassifier

Returns:

A ready-to-fit() instance.

Raises:

NotImplementedError – If the subclass does not override this method.

name: str = 'base'

abstractmethod predict(features)

Return predicted integer labels for each row of features.

Parameters:

features (ndarray) – Feature matrix with the same layout used in fit().

Return type:

ndarray

Returns:

1-D integer array of length n_shots.

predict_proba(features)

Return class probabilities, or None if unsupported.

Parameters:

features (ndarray) – Same layout as predict().

Return type:

ndarray | None

Returns:

Array shaped (n_shots, n_classes), or None.

supports_feature_kind(kind)

Return True if this classifier can consume the given feature kind.

Return type:

bool

Parameters:

kind (str)

validate_feature_kind(kind)

Raise ValueError if kind is not supported by this classifier.

Return type:

None

Parameters:

kind (str)

arcade.classifiers.ensure_classifiers_registered()

Import built-in classifier packages so the registry is populated.

Return type:

None

arcade.classifiers.get_classifier(name)

Resolve a classifier class by registry name or dotted import path.

Parameters:

name (str) – Either a registered key ("lda") or "package.module.ClassName" (last segment is the class).

Return type:

type[BaseClassifier]

Returns:

The classifier class (not an instance). Call BaseClassifier.from_config() to construct.

Raises:

• KeyError – Unknown registry name (includes close-match hints).

• TypeError – Dotted path did not resolve to a BaseClassifier subclass.

arcade.classifiers.iq_trace_classifier_names()

Return names of classifiers that consume IQ / raw traces (not MF scores).

Return type:

frozenset[str]

arcade.classifiers.list_classifiers()

Return sorted registry names of all built-in classifiers.

Triggers ensure_classifiers_registered() so the list is complete even before any classifier module was imported.

Return type:

list[str]

arcade.classifiers.list_classifiers_with_descriptions()

Return (name, category, description) for every registered classifier.

Return type:

list[tuple[str, str, str]]

arcade.classifiers.register_classifier(name)

Register a BaseClassifier subclass under name.

The name is what appears in classifiers.run in YAML.

Parameters:

name (str) – Short registry key (e.g. "fnn", "my_clf").

Return type:

Any

Returns:

A class decorator that stores the class in the registry.

Example:

@register_classifier("my_clf")
class MyClassifier(BaseClassifier):
    FEATURE_KIND = "filter_features"

    def fit(self, train_features, train_labels, **kwargs):
        return self

    def predict(self, features):
        ...

arcade.classifiers.seq_trace_classifier_names()

Return names of classifiers that consume sequential trace tensors.

Return type:

frozenset[str]