Inference

End-to-end entry points. recommend is the main user-facing function: extract meta-features, query the recommender, return a ranked circuit list - no quantum evaluation at inference time. evaluate_recommendation optionally checks recommendations against Oracle ground truth (this does run quantum kernel evaluation).

Qmes.recommend

recommend(
    X,
    y,
    extractor,
    recommender,
    top_k=3,
    preprocess=True,
    stratify=False,
)

Recommend quantum encoding circuits for a new dataset.

The end-to-end inference entry point: extracts meta-features from (X, y), queries the pre-trained recommender, and returns a ranked list of circuits - no quantum evaluation at inference time.

Parameters:

Name	Type	Description	Default
`X`	`array-like of shape (n_samples, n_features)`	Feature matrix of the new dataset.	required
`y`	`array-like of shape (n_samples,)`	Target vector.	required
`extractor`	`BaseExtractor`	Stateless extractor matching the task type, e.g. `get_extractor('classification')`.	required
`recommender`	`PairwiseRecommender`	Pre-trained recommender, e.g. from `load_default_recommender()`. Must have the same task_type as extractor.	required
`top_k`	`int`	Number of top circuits to return.	`3`
`preprocess`	`bool`	If True, run preprocess_new_dataset (encode categoricals, impute, subsample) before extraction. Scaling is NOT done here - the extractor handles its own scaling.	`True`
`stratify`	`bool`	If True, use stratified subsampling during preprocessing. Relevant for classification tasks with imbalanced classes.	`False`

Returns:

Type	Description
`dict with keys:`	'ranking' : list[str] All 7 circuits sorted by votes (descending). 'top_k' : list[str] Top-k circuits (first top_k elements of 'ranking'). 'votes' : dict[str, int] Raw OvO vote counts per circuit. 'meta_features' : np.ndarray of shape (d,) Extracted meta-feature vector used for this recommendation.

Raises:

Type	Description
`ValueError`	If extractor.task_type != recommender.task_type, or if the extractor's feature names do not match the recommender's.

Examples:

>>> from Qmes import get_extractor, load_default_recommender, recommend
>>> rec = load_default_recommender('classification')
>>> ext = get_extractor('classification')
>>> result = recommend(X, y, extractor=ext, recommender=rec)
>>> result['top_k']
['RY', 'HERx', 'ZFM']

Qmes.preprocess_new_dataset

preprocess_new_dataset(
    X,
    y,
    max_samples=MAX_SAMPLES,
    random_state=42,
    stratify=False,
)

Preprocess a new dataset to match meta-dataset conventions.

Steps: 1. Encode categoricals → numeric 2. Impute missing values + cast to float64 3. Subsample to max_samples (random by default; stratified if stratify=True). The classification data loader stratifies by default - pass stratify=True to mirror it.

Parameters:

Name	Type	Description	Default
`X`	`(ndarray or DataFrame, shape(n_samples, n_features))`	Feature matrix of the new dataset.	required
`y`	`(ndarray or Series, shape(n_samples))`	Target vector.	required
`max_samples`	`int`	Cap on sample count after subsampling. See Qmes.config.MAX_SAMPLES.	`600`
`random_state`	`int`	Seed for the subsampling RNG.	`42`
`stratify`	`bool`	Stratify the subsample on y. Only meaningful for classification; leave False for regression (continuous target).	`False`

Returns:

Type	Description
`(X_clean, y_clean) : ndarray, ready for extractor + evaluator`

Qmes.evaluate_recommendation

evaluate_recommendation(
    datasets,
    extractor,
    recommender,
    evaluator,
    top_k=3,
    tied_threshold=TIED_THRESHOLD,
    preprocess=True,
)

Run full inference evaluation on multiple datasets.

For each dataset:

Recommend circuits (no quantum eval)
Run Oracle ground truth (quantum eval)
Compare

Parameters:

Name	Type	Description	Default
`datasets`	`dict[str, tuple[ndarray, ndarray]]`	Mapping of dataset name to (X, y). Each dataset is evaluated independently, out-of-sample - not the LOO in-sample evaluation of run_loo_evaluation.	required
`extractor`	`BaseExtractor`	Matching the task_type of recommender and evaluator.	required
`recommender`	`PairwiseRecommender`	Pre-trained recommender to evaluate.	required
`evaluator`	`BaseEvaluator`	Oracle used to compute ground-truth circuit scores.	required
`top_k`	`int`	Number of top circuits requested from the recommender.	`3`
`tied_threshold`	`float`	Absolute score delta defining the tied-best set for tied_hit / top3_tied_hit.	`TIED_THRESHOLD`
`preprocess`	`bool`	If True, run preprocess_new_dataset on each dataset before both recommendation and Oracle evaluation.	`True`

Returns:

Type Description

DataFrame, one row per dataset, columns:

dataset : dataset name rec_top1 : recommender's top-1 circuit rec_top_k : recommender's top-k circuits true_best : Oracle's best circuit (highest CV score) true_top3 : Oracle's top-3 circuits tied_hit : True if rec_top1 is within tied_threshold of best top3_tied_hit : True if any rec_top_k circuit is in the tied set regret : best_score - score of rec_top1 (lower is better) best_score : Oracle score of true_best rec_score : Oracle score of rec_top1

Raises:

Type	Description
`ValueError`	If recommender.task_type != evaluator.task_type.