Examples & Tutorials¶
—
Example 1 — Binary Classification¶
Classifying cancer data with a Bayesian search over angle and IQP encodings.
from sklearn.datasets import load_breast_cancer
from sklearn.model_selection import train_test_split
from qkabrine_automl import QkabrineAutoML
# Load data
X, y = load_breast_cancer(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(
X, y, test_size=0.2, random_state=42
)
# Create and fit
automl = QkabrineAutoML(
task='classification',
n_qubits=4, # use 4 qubits
max_layers=2, # try up to 2 layers per circuit
search_strategy='bayesian',
encodings=('angle', 'iqp'),
feature_reduction='pca', # reduce 30 features → 4 qubits via PCA
train_steps=50,
verbose=True,
)
automl.fit(X_train, y_train)
# Results
automl.leaderboard()
print(f"Test accuracy: {automl.score(X_test, y_test):.4f}")
# Inspect the winning circuit
automl.best_circuit_summary()
What to expect: The Bayesian search will run ~25 candidates, taking roughly 3–8 minutes depending on your machine. Typical accuracy on this dataset is 0.90–0.96.
—
Example 2 — Multi-Class Classification¶
Three-class classification on the Iris dataset using an evolutionary search.
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
from qkabrine_automl import QkabrineAutoML
X, y = load_iris(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(
X, y, test_size=0.2, random_state=42
)
automl = QkabrineAutoML(
task='classification',
n_qubits=4,
search_strategy='evolutionary',
encodings=('angle', 'angle_yz'),
max_layers=3,
train_steps=60,
)
automl.fit(X_train, y_train)
# Predict class labels
predictions = automl.predict(X_test)
print(predictions) # e.g. ['setosa', 'versicolor', 'virginica', ...]
# Soft class probabilities
probs = automl.predict_proba(X_test)
print(probs.shape) # (n_samples, 3)
Note: Multi-class uses qml.probs() with cross-entropy loss, which
trains all classes simultaneously rather than one-vs-rest.
—
Example 3 — Regression¶
Predicting house prices with a quantum regression model.
from sklearn.datasets import fetch_california_housing
from sklearn.model_selection import train_test_split
from qkabrine_automl import QkabrineAutoML
X, y = fetch_california_housing(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(
X, y, test_size=0.2, random_state=42
)
automl = QkabrineAutoML(
task='regression',
n_qubits=6,
search_strategy='bayesian',
encodings=('angle',),
feature_reduction='pca',
train_steps=40,
include_kernels=False, # skip kernel methods for regression speed
)
automl.fit(X_train, y_train)
print(f"R² score: {automl.score(X_test, y_test):.4f}")
—
Example 4 — Quantum Kernel Methods¶
Letting the search compare variational circuits against quantum kernel SVMs.
from sklearn.datasets import load_wine
from sklearn.model_selection import train_test_split
from qkabrine_automl import QkabrineAutoML
X, y = load_wine(return_X_y=True)
# Keep it binary for this example
mask = y < 2
X, y = X[mask], y[mask]
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)
automl = QkabrineAutoML(
task='classification',
n_qubits=4,
search_strategy='grid',
include_kernels=True, # compare variational + kernel methods
feature_reduction='pca',
)
automl.fit(X_train, y_train)
automl.leaderboard()
# Check which type won
print(automl._best['model_type']) # 'variational' or 'kernel'
—
Example 5 — Save, Load, and Deploy¶
Train once, save the model, load it later for predictions.
# --- Train and save ---
automl = QkabrineAutoML(task='classification', n_qubits=4)
automl.fit(X_train, y_train)
automl.save('my_quantum_model.pkl')
# --- Load later (even in a different script) ---
from qkabrine_automl import QkabrineAutoML
loaded = QkabrineAutoML.load('my_quantum_model.pkl')
predictions = loaded.predict(X_test)
print(f"Accuracy: {loaded.score(X_test, y_test):.4f}")
—
Example 6 — Export to QASM¶
Export the best circuit to OpenQASM 2.0 for use on real quantum hardware.
automl = QkabrineAutoML(task='classification', n_qubits=4)
automl.fit(X_train, y_train)
# Print QASM to screen
qasm_string = automl.export_qasm()
print(qasm_string)
# Or save to a file
automl.export_qasm_to_file('best_circuit.qasm')
The exported QASM file can be submitted to IBM Quantum, Amazon Braket, or any hardware provider that accepts OpenQASM 2.0.
—
Example 7 — Cross-Validation¶
More reliable evaluation using k-fold cross-validation.
automl = QkabrineAutoML(
task='classification',
n_qubits=4,
search_strategy='bayesian',
cv_folds=5, # 5-fold stratified cross-validation
train_steps=30,
)
automl.fit(X, y) # pass the full dataset — no manual split needed
—
Example 8 — Noise-Aware Training¶
Train with a noise model to prepare for real NISQ hardware.
automl = QkabrineAutoML(
task='classification',
n_qubits=4,
noise_model='depolarizing', # simulate gate errors
noise_strength=0.01, # 1% error rate per gate
train_steps=60, # more steps to compensate for noise
)
automl.fit(X_train, y_train)
Available noise models: 'depolarizing', 'bitflip',
'phaseflip', 'amplitude_damping'.
—
Example 9 — Barren Plateau Detection¶
Monitor for vanishing gradients and stop early if detected.
automl = QkabrineAutoML(
task='classification',
n_qubits=6,
monitor_barren_plateaus=True, # watch gradient variance
use_dqfim_prescreening=True, # skip untrainable circuits early
train_steps=80,
)
automl.fit(X_train, y_train)
When a barren plateau is detected mid-training you will see [BP@step]
printed in the progress output, and training stops early for that candidate.
—
Example 10 — Analysing Circuit Quality¶
Use the built-in expressibility and entanglement metrics.
from qkabrine_automl import (
ANSATZ_REGISTRY,
compute_expressibility,
compute_entangling_capability,
rank_ansatze,
)
# Rank all 12 ansätze by expressibility on 4 qubits
rankings = rank_ansatze(n_qubits=4, n_layers=2)
for name, expr, ent in rankings:
print(f"{name:<30} expr={expr:.4f} ent={ent:.4f}")
# Check a specific ansatz
arch = ANSATZ_REGISTRY['strongly_entangling'](n_qubits=4, n_layers=2)
expr = compute_expressibility(arch, n_qubits=4, n_samples=200)
print(f"Expressibility (KL divergence): {expr:.4f}")