Evaluators

An evaluator (the Oracle) scores every circuit in the pool on a dataset via cross-validated quantum-kernel methods. It is used offline only - to build the meta-dataset labels and to validate recommendations. Inference never touches it.

A new Oracle implements the three-member contract of BaseEvaluator (task_type, metric_name, evaluate_circuit); the base class provides evaluate_all and build_pivot on top.

Qmes.get_evaluator

get_evaluator(task_type, **kwargs)

Return the Oracle evaluator for the given task type.

Parameters:

Name	Type	Description	Default
task_type	(classification, regression)		'classification'
**kwargs	passed to evaluator constructor (e.g. n_splits, max_features)		{}

Returns:

Type	Description
Concrete BaseEvaluator instance

Qmes.evaluators.BaseEvaluator

Bases: ABC

Evaluate all circuits on a dataset, return performance scores.

metric_name abstractmethod property

metric_name

Primary metric name, e.g. 'MCC', 'R2'.

evaluate_circuit abstractmethod

evaluate_circuit(X, y, circuit_name, **kwargs)

Evaluate one circuit on one dataset.

Returns:

Type	Description
dict with keys like 'mean_mcc', 'std_mcc', etc.

evaluate_all

evaluate_all(X, y, circuit_names=None, **kwargs)

Evaluate all circuits on one dataset.

Returns:

Type	Description
{circuit_name: {metric: value, ...}, ...}

build_pivot

build_pivot(datasets, circuit_names=None, **kwargs)

Run Oracle on all datasets × all circuits → pivot table.

Returns:

Name	Type	Description
DataFrame	index=circuit_names, columns=dataset_names,	values=primary metric score

Qmes.ClassificationEvaluator

ClassificationEvaluator(
    n_splits=3, max_features=4, random_state=42
)

Bases: BaseEvaluator

Evaluate encoding circuits for binary classification via quantum-kernel SVC.

Parameters:

Name	Type	Description	Default
n_splits	int	Number of StratifiedKFold CV folds used to estimate circuit performance.	3
max_features	int	Maximum number of PCA components (qubits) fed into the quantum kernel. Capped at 4 to match the qubit budget of the Qsun simulator; datasets with more raw features are projected down via PCA fit on the train split only.	4
random_state	int	Seed for StratifiedKFold and PCA.	42

evaluate_circuit

evaluate_circuit(X, y, circuit_name, **kwargs)

Stratified K-fold CV (default n_splits=3) with SVC(precomputed kernel).

Returns:

Type	Description
dict with keys: mean_acc, std_acc, mean_mcc, std_mcc, mean_f1, std_f1

Qmes.RegressionEvaluator

RegressionEvaluator(
    n_splits=3, max_features=4, random_state=42
)

Bases: BaseEvaluator

Evaluate encoding circuits for tabular regression via quantum-kernel KRR.

Parameters:

Name	Type	Description	Default
n_splits	int	Number of KFold CV folds used to estimate circuit performance.	3
max_features	int	Maximum number of PCA components (qubits) fed into the quantum kernel. Capped at 4 to match the qubit budget of the Qsun simulator; datasets with more raw features are projected down via PCA fit on the train split only.	4
random_state	int	Seed for StratifiedKFold and PCA.	42

evaluate_circuit

evaluate_circuit(X, y, circuit_name, **kwargs)

K-fold CV (default n_splits=3) with KernelRidge(precomputed quantum kernel).

Returns:

Type	Description
dict keys: mean_r2, std_r2, mean_rmse, std_rmse, mean_mae, std_mae

Qmes.filter_degenerate_datasets

filter_degenerate_datasets(
    pivot, min_max_score=0.1, ceiling_threshold=0.99
)

Remove no-signal and ceiling datasets from a pivot table.

Task-agnostic: operates on any (circuit x dataset) score pivot regardless of whether scores are MCC, R2, or another metric, so it lives here rather than in a concrete task's evaluator module.

Parameters:

Name	Type	Description	Default
pivot	DataFrame, index=circuits, columns=datasets		required
min_max_score	drop if max score across circuits < this		0.1
ceiling_threshold	drop if min score across circuits >= this		0.99

Returns:

Type	Description
(clean_pivot, removed_dict)