Add VQC and quantum-kernel benchmarking framework

Implement EncodingBenchmark and evaluate_encoding to compare encodings on classification tasks with variational quantum classifiers and quantum-kernel SVMs, paired stratified cross-validation, classical baselines, and statistical testing (Wilcoxon + Holm-Bonferroni + Cliff's delta), replacing the previously stubbed runner.

Author: ashutoshm1771

README.md

@@ -113,6 +113,33 @@ print(sorted(p.name for p in pareto_front()))
 # ['angle', 'basis', 'higher_order_angle', 'swap_equivariant']
 ```
 
+### Benchmark encodings on your own data
+
+Run variational-quantum-classifier and quantum-kernel comparisons with paired
+cross-validation, classical baselines, and statistical testing:
+
+```python
+from encoding_atlas import AngleEncoding, IQPEncoding
+from encoding_atlas.benchmark import EncodingBenchmark, evaluate_encoding
+
+# Compare encodings across datasets and methods
+bench = EncodingBenchmark(
+    encodings=[AngleEncoding(n_features=2), IQPEncoding(n_features=2)],
+    datasets=["moons", "circles"],
+    methods=("vqc", "kernel"),
+    n_runs=3,
+    n_folds=5,
+    baselines=("svm_rbf",),
+    seed=0,
+)
+results = bench.run()
+stats = bench.statistical_tests()   # Wilcoxon + Holm–Bonferroni + Cliff's delta
+
+# ...or evaluate a single encoding on your own (X, y)
+report = evaluate_encoding(AngleEncoding(n_features=2), X, y, method="kernel")
+print(report["mean"], report["ci_low"], report["ci_high"])
+```
+
 ## Supported Encodings
 
 | Category | Encodings |

docs/api/index.md

@@ -129,6 +129,56 @@ All encodings inherit from `BaseEncoding` and share a unified interface.
 
 ---
 
+## Benchmark Module
+
+Evaluate encodings on classification tasks with variational quantum classifiers
+and quantum-kernel SVMs, paired stratified cross-validation, classical
+baselines, and statistical comparison (Wilcoxon + Holm–Bonferroni + Cliff's
+delta).
+
+::: encoding_atlas.benchmark.EncodingBenchmark
+    options:
+      show_root_heading: true
+      members:
+        - run
+        - statistical_tests
+        - plot_comparison
+        - save_results
+
+::: encoding_atlas.benchmark.evaluate_encoding
+    options:
+      show_root_heading: true
+
+::: encoding_atlas.benchmark.VQCClassifier
+    options:
+      show_root_heading: true
+      members:
+        - fit
+        - predict
+        - score
+
+::: encoding_atlas.benchmark.QuantumKernelClassifier
+    options:
+      show_root_heading: true
+      members:
+        - fit
+        - predict
+        - score
+
+::: encoding_atlas.benchmark.compute_kernel_matrix
+    options:
+      show_root_heading: true
+
+::: encoding_atlas.benchmark.kernel_target_alignment
+    options:
+      show_root_heading: true
+
+::: encoding_atlas.benchmark.compare_encodings_corrected
+    options:
+      show_root_heading: true
+
+---
+
 ## Atlas Module
 
 The empirical benchmark results — measured circuit resources, simulability,

src/encoding_atlas/benchmark/__init__.py

@@ -1,12 +1,69 @@
-"""Benchmarking framework for encoding comparison."""
+"""Benchmarking framework for encoding comparison.
 
+Evaluate quantum encodings on classification tasks with variational quantum
+classifiers and quantum-kernel SVMs, paired stratified cross-validation,
+classical baselines, and statistical comparison.
+
+>>> from encoding_atlas import AngleEncoding
+>>> from encoding_atlas.benchmark import EncodingBenchmark
+>>> bench = EncodingBenchmark(
+...     [AngleEncoding(n_features=2)], ["moons"],
+...     methods=("kernel",), n_runs=1, n_folds=3, seed=0,
+... )
+>>> results = bench.run()  # doctest: +SKIP
+"""
+
+from encoding_atlas.benchmark.baselines import (
+    CLASSICAL_BASELINE_NAMES,
+    get_classical_baseline,
+    run_baseline_single_fold,
+)
 from encoding_atlas.benchmark.datasets import get_dataset, list_datasets
+from encoding_atlas.benchmark.kernel import (
+    QuantumKernelClassifier,
+    centered_kernel_target_alignment,
+    compute_kernel_matrix,
+    ensure_psd,
+    kernel_target_alignment,
+    run_kernel_single_fold,
+)
 from encoding_atlas.benchmark.metrics import compute_metrics
-from encoding_atlas.benchmark.runner import EncodingBenchmark
+from encoding_atlas.benchmark.runner import EncodingBenchmark, evaluate_encoding
+from encoding_atlas.benchmark.statistical import (
+    cliffs_delta,
+    compare_encodings,
+    compare_encodings_corrected,
+    holm_bonferroni,
+    wilcoxon_test,
+)
+from encoding_atlas.benchmark.vqc import VQCClassifier, run_vqc_single_fold
 
 __all__ = [
+    # Orchestration
+    "EncodingBenchmark",
+    "evaluate_encoding",
+    # Datasets & metrics
     "get_dataset",
     "list_datasets",
-    "EncodingBenchmark",
     "compute_metrics",
+    # Classifiers
+    "VQCClassifier",
+    "QuantumKernelClassifier",
+    "run_vqc_single_fold",
+    "run_kernel_single_fold",
+    # Quantum kernel utilities
+    "compute_kernel_matrix",
+    "kernel_target_alignment",
+    "centered_kernel_target_alignment",
+    "ensure_psd",
+    # Classical baselines
+    "get_classical_baseline",
+    "run_baseline_single_fold",
+    "CLASSICAL_BASELINE_NAMES",
+    # Statistics
+    "wilcoxon_test",
+    "compare_encodings",
+    "compare_encodings_corrected",
+    "cliffs_delta",
+    "holm_bonferroni",
 ]

src/encoding_atlas/benchmark/baselines.py

@@ -0,0 +1,93 @@
+"""Classical machine-learning baselines for benchmark calibration.
+
+Provides standard scikit-learn classifiers (SVM-RBF, random forest, 2-layer
+MLP) so quantum encoding results can be contextualised against classical
+reference accuracy on the same train/test splits.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+logger = logging.getLogger(__name__)
+
+# Names accepted by :func:`get_classical_baseline`.
+CLASSICAL_BASELINE_NAMES: list[str] = ["svm_rbf", "random_forest", "mlp_2layer"]
+
+
+def get_classical_baseline(name: str, seed: int) -> Any:
+    """Return a fresh scikit-learn classifier for the named baseline.
+
+    Parameters
+    ----------
+    name : {"svm_rbf", "random_forest", "mlp_2layer"}
+        Baseline identifier.
+    seed : int
+        Random seed for reproducibility.
+
+    Raises
+    ------
+    ValueError
+        If ``name`` is not a known baseline.
+    """
+    from sklearn.ensemble import RandomForestClassifier
+    from sklearn.neural_network import MLPClassifier
+    from sklearn.svm import SVC
+
+    builders = {
+        "svm_rbf": lambda: SVC(kernel="rbf", random_state=seed, probability=True),
+        "random_forest": lambda: RandomForestClassifier(
+            n_estimators=100, random_state=seed
+        ),
+        "mlp_2layer": lambda: MLPClassifier(
+            hidden_layer_sizes=(32, 16), max_iter=200, random_state=seed
+        ),
+    }
+    if name not in builders:
+        raise ValueError(
+            f"Unknown baseline: {name}. Available: {CLASSICAL_BASELINE_NAMES}"
+        )
+    return builders[name]()
+
+
+def run_baseline_single_fold(
+    name: str,
+    X_train: NDArray[np.floating[Any]],
+    X_test: NDArray[np.floating[Any]],
+    y_train: NDArray[np.intp],
+    y_test: NDArray[np.intp],
+    *,
+    seed: int = 42,
+) -> dict[str, Any]:
+    """Train and evaluate a classical baseline on one train/test split.
+
+    Returns a dict with ``test_accuracy``, ``precision``, ``recall``, ``f1``,
+    and ``status``. Failures are reported as ``status="failed"``.
+    """
+    from sklearn.metrics import f1_score, precision_score, recall_score
+
+    try:
+        clf = get_classical_baseline(name, seed=seed)
+        clf.fit(X_train, y_train)
+        y_pred = clf.predict(X_test)
+        return {
+            "test_accuracy": float(np.mean(y_pred == y_test)),
+            "precision": float(precision_score(y_test, y_pred, zero_division=0)),
+            "recall": float(recall_score(y_test, y_pred, zero_division=0)),
+            "f1": float(f1_score(y_test, y_pred, zero_division=0)),
+            "status": "success",
+        }
+    except Exception as exc:  # noqa: BLE001 - report and continue the sweep
+        logger.error("Baseline %s fold failed: %s", name, exc)
+        return {
+            "test_accuracy": 0.0,
+            "precision": 0.0,
+            "recall": 0.0,
+            "f1": 0.0,
+            "status": "failed",
+            "error": str(exc),
+        }