arcade.features

Feature extraction for ARCADE classifiers.

class arcade.features.BaseFeatureExtractor

Bases: ABC

Contract for turning IQ / ADC traces into a feature matrix.

Matched filters, NG-RC polynomials, and path signatures all implement this interface. Subclass and decorate with register_extractor().

name

Registry name (set by the decorator).

feature_kind

Short tag describing the output feature family.

Example:

@register_extractor("my_features")
class MyExtractor(BaseFeatureExtractor):
    feature_kind = "custom"

    def extract(self, traces, **kwargs):
        return np.zeros((len(traces), 10))

abstractmethod extract(traces, **kwargs)

Extract features from traces.

Parameters:

• traces (ndarray) – Input traces; shape depends on extractor type.

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

Return type:

ndarray

Returns:

Feature matrix shaped (n_shots, feature_dim).

feature_kind: str = 'generic'

fit(train_traces, train_labels, **kwargs)

Optionally fit templates / statistics on training traces.

Parameters:

• train_traces (ndarray) – Training IQ or ADC array (layout is extractor-specific).

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

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

Return type:

BaseFeatureExtractor

Returns:

self. Default implementation is a no-op.

name: str = 'base'

class arcade.features.FilterSet(num_qubits, num_levels, filters=<factory>, thresholds=<factory>, trace_length=None)

Bases: object

Container for per-qubit matched filter envelopes and thresholds.

Parameters:

• num_qubits (int)

• num_levels (int)

• filters (dict[int, dict[str, ndarray]])

• thresholds (dict[int, dict[str, float]])

• trace_length (int | None)

num_qubits

Number of qubits.

num_levels

Energy levels per qubit (2 for qubit, 3 for qutrit).

filters

Nested dict filters[qubit][filter_name] -> ndarray.

thresholds

Nested dict thresholds[qubit][filter_name] -> float.

trace_length

Number of time steps the filters were computed for.

filter_names(qubit)

List all filter names for a given qubit.

Return type:

list[str]

Parameters:

qubit (int)

get(qubit, name)

Return (envelope, threshold) for one filter.

Return type:

tuple[ndarray, float]

Parameters:

• qubit (int)

• name (str)

qubit_feature_slices()

Map each qubit to its column slice in the feature matrix.

Return type:

dict[int, slice]

property total_features: int

Total scalar features produced by apply_filters.

trace_length: int | None = None

num_qubits: int

num_levels: int

filters: dict[int, dict[str, ndarray]]

thresholds: dict[int, dict[str, float]]

class arcade.features.MatchedFilterExtractor

Bases: BaseFeatureExtractor

Matched filter feature extractor.

Computes filter templates from labelled training data, then projects new traces onto those templates to produce scalar features.

extract(traces, **kwargs)

Project traces onto stored filter templates.

Return type:

ndarray

Parameters:

• traces (ndarray)

• kwargs (Any)

feature_kind: str = 'filter_features'

fit(train_traces, train_labels, transitions=None, filter_types=('MF', 'RMF'), **kwargs)

Compute filter templates from labelled training data.

Parameters:

• train_traces (ndarray) – Training IQ traces (n, t, 2).

• train_labels (ndarray) – Integer state labels.

• transitions (Any) – Transition data (from detect_transitions) or None. If None, builds simple per-state trace dicts.

• filter_types (Sequence[str]) – Filter families to compute.

• kwargs (Any)

Return type:

MatchedFilterExtractor

name: str = 'matched_filter'

class arcade.features.NGRCFeatureExtractor(window_size=10, polynomial_degree=2, boxcar_ends=None)

Bases: BaseFeatureExtractor

NG-RC polynomial feature extractor.

Combines: apply_boxcar_masks -> window_average_iq -> expand_features.

Parameters:

• window_size (int)

• polynomial_degree (int)

• boxcar_ends (list[int] | None)

extract(traces, **kwargs)

Extract NG-RC polynomial features from traces.

Return type:

ndarray

Parameters:

• traces (ndarray)

• kwargs (Any)

feature_kind: str = 'ngrc_expansion'

name: str = 'ngrc'

class arcade.features.PathSignatureExtractor(signature_depth=5, time_augmentation=False)

Bases: BaseFeatureExtractor

Path signature feature extractor.

Combines: compute_weights -> build_weighted_path -> compute_signature_features.

Parameters:

• signature_depth (int)

• time_augmentation (bool)

extract(traces, **kwargs)

Extract path signature features from traces.

Return type:

ndarray

Parameters:

• traces (ndarray)

• kwargs (Any)

feature_kind: str = 'signature'

fit(train_traces, train_labels, **kwargs)

Compute weight function from labelled training data.

Return type:

PathSignatureExtractor

Parameters:

• train_traces (ndarray)

• train_labels (ndarray)

• kwargs (Any)

name: str = 'path_signature'

class arcade.features.RelaxationFilterExtractor

Bases: BaseFeatureExtractor

Relaxation matched filter (REMF) feature extractor.

Uses post-selection to separate true state preparations from relaxation/excitation events.

extract(traces, **kwargs)

Project traces onto stored REMF templates.

Return type:

ndarray

Parameters:

• traces (ndarray)

• kwargs (Any)

feature_kind: str = 'filter_features'

fit(train_traces, train_labels, post_measured_labels=None, **kwargs)

Compute REMF templates from post-selected training data.

Return type:

RelaxationFilterExtractor

Parameters:

• train_traces (ndarray)

• train_labels (ndarray)

• post_measured_labels (ndarray | None)

• kwargs (Any)

name: str = 'relaxation_filter'

arcade.features.get_extractor(name)

Resolve an extractor class by registry name or dotted import path.

Parameters:

name (str) – Registered key or package.module.ClassName.

Return type:

type[BaseFeatureExtractor]

Returns:

The extractor class.

Raises:

• KeyError – Unknown registry name.

• TypeError – Dotted path is not a BaseFeatureExtractor subclass.

arcade.features.list_extractors()

Return sorted names of all registered feature extractors.

Return type:

list[str]

arcade.features.register_extractor(name)

Register a BaseFeatureExtractor subclass under name.

Parameters:

name (str) – Registry key used when selecting extractors from config.

Return type:

Any

Returns:

A class decorator that stores the class in the registry.