API Reference¶

—

QkabrineAutoML ¶

The main class. All search, training, and inference goes through here.

from qkabrine_automl import QkabrineAutoML

Constructor Parameters ¶

Parameter	Type	Default	Description
`task`	str	`'classification'`	`'classification'` or `'regression'`
`n_qubits`	int or None	`None`	Number of qubits. Auto-inferred from features if None (max 10).
`max_layers`	int	`3`	Maximum circuit depth (layers) to try per ansatz.
`train_steps`	int	`40`	Number of gradient steps per candidate circuit.
`time_budget`	float or None	`None`	Stop the entire search after this many seconds. None = no limit.
`search_strategy`	str	`'bayesian'`	One of `'grid'`, `'random'`, `'bayesian'`, `'evolutionary'`, `'successive_halving'`.
`encodings`	tuple of str	`('angle',)`	Encodings to search. Any of `'angle'`, `'angle_yz'`, `'iqp'`, `'amplitude'`.
`init_strategies`	tuple of str	`('uniform',)`	Parameter initialisation strategies: `'uniform'`, `'small'`, `'zeros'`, `'normal'`, `'block'`.
`optimizer`	str	`'adam'`	`'adam'`, `'sgd'`, or `'momentum'`.
`include_kernels`	bool	`True`	Whether to also evaluate quantum kernel + SVM methods.
`cv_folds`	int or None	`None`	Cross-validation folds (>= 2). None = single train/val split.
`noise_model`	str or None	`None`	Simulate hardware noise: `'depolarizing'`, `'bitflip'`, `'phaseflip'`, `'amplitude_damping'`.
`noise_strength`	float	`0.01`	Noise probability per gate (only used if `noise_model` is set).
`feature_reduction`	str or None	`'pca'`	Reduce features to fit qubit count: `'pca'`, `'random_projection'`, `'select_variance'`, or None.
`use_dqfim_prescreening`	bool	`False`	Pre-screen candidates using DQFIM trainability score. Skips circuits likely to have vanishing gradients.
`monitor_barren_plateaus`	bool	`False`	Monitor gradient variance during training and stop early if a barren plateau is detected.
`random_seed`	int or None	`None`	Set for reproducible results.
`verbose`	bool	`True`	Print search progress.

—

Methods ¶

fit¶

automl.fit(X, y, val_size=0.2)

Run the architecture search and train all candidate circuits.

Parameters:

X — 2D array of shape (n_samples, n_features)
y — 1D array of labels (classification) or values (regression)
val_size — fraction of data to hold out for validation (default 0.2)

Returns: self

Raises:

ValueError — if X is not 2D, lengths mismatch, or fewer than 5 samples
SearchExhaustedError — if every candidate circuit fails during training

—

predict¶

predictions = automl.predict(X)

Predict using the best model found during search.

Parameters:

X — 2D array of shape (n_samples, n_features)

Returns: 1D array of predicted class labels (classification) or values (regression).

—

predict_proba¶

probs = automl.predict_proba(X)

Return class probabilities. Classification only.

Parameters:

X — 2D array of shape (n_samples, n_features)

Returns: 2D array of shape (n_samples, n_classes) where each row sums to 1.

Raises: ValueError if called on a regression model. NotImplementedError if the best model is a quantum kernel.

—

score¶

result = automl.score(X, y)

Compute accuracy (classification) or R² (regression) on new data.

Returns: float

—

leaderboard¶

automl.leaderboard(top_n=15)

Print a ranked table of all evaluated models. Best model is highlighted.

—

best_circuit_summary¶

automl.best_circuit_summary()

Print a gate-by-gate breakdown of the winning circuit, including gate name, target wires, and whether each gate is trainable.

—

export_qasm¶

qasm_str = automl.export_qasm()

Export the best variational circuit as an OpenQASM 2.0 string.

Returns: str

Raises: ValueError if the best model is a quantum kernel (kernels have no circuit to export).

—

export_qasm_to_file¶

automl.export_qasm_to_file(path='best_circuit.qasm')

Save the QASM export directly to a file.

—

save¶

automl.save(path='qkabrine_automl_model.pkl')

Serialise the fitted model to disk. Works for both variational and kernel models.

—

load¶

loaded = QkabrineAutoML.load(path='qkabrine_automl_model.pkl')

Load a previously saved model. Class method — call on the class, not an instance.

# Correct usage
loaded = QkabrineAutoML.load('my_model.pkl')
preds = loaded.predict(X_test)

—

Search Strategies ¶

Strategy	Description
`'bayesian'`	Default. Gaussian Process + Expected Improvement. Builds a surrogate model of performance and proposes the most promising candidates. Best sample efficiency.
`'evolutionary'`	Genetic algorithm with crossover and mutation across generations. Good for large search spaces.
`'successive_halving'`	HyperBand-inspired. Starts many candidates with low budget, eliminates the worst half each round, doubles budget for survivors. Efficient when training is expensive.
`'grid'`	Exhaustive enumeration of all combinations. Best for small search spaces.
`'random'`	Random sampling within the budget. Quick baseline.

—

Circuit Architectures (12 Ansätze)¶

Name	Description
`strongly_entangling`	High expressibility. CNOT ring with full rotations. Strong entanglement across all qubit pairs.
`hardware_efficient`	Low circuit depth. Designed to run well on real NISQ hardware with limited connectivity.
`data_reuploading`	Data re-encoding between trainable layers. Increases effective expressibility per qubit.
`simplified_two_design`	Near-Haar random coverage. Good baseline expressibility with fewer parameters.
`all_to_all`	Maximum qubit connectivity. Every qubit entangled with every other.
`cascading`	QFT-inspired multi-scale entanglement. Long-range correlations.
`criss_cross`	Butterfly-pattern gate arrangement. Spreads information across qubits efficiently.
`ring_of_cnots`	Dense parameterisation with ring CNOT connectivity.
`full_rotation`	Maximum rotation freedom with RX, RY, RZ on every qubit each layer.
`alternating_rx_ry`	Alternating RX and RY layers. Layer diversity reduces parameter correlation.
`shallow_rx`	Minimal depth. Barren-plateau resistant due to shallow structure.
`hadamard_entangling`	Superposition-first design. Hadamard initialisation before entanglement.

—

Data Encodings ¶

Encoding	Description
`'angle'`	Each feature encoded as an RX rotation angle. Simple and fast.
`'angle_yz'`	Features encoded as alternating RY and RZ rotations. More expressive than angle.
`'iqp'`	Instantaneous Quantum Polynomial encoding. Uses Hadamard + RZ + CNOT structure. Strong for kernel methods.
`'amplitude'`	Encodes all features into the amplitude vector of the quantum state. Requires 2^n amplitudes for n qubits.

—

Quantum Kernel Classes ¶

QuantumKernel ¶

Computes quantum kernel matrices using circuit fidelity: k(x_i, x_j) = |⟨ψ(x_i)|ψ(x_j)⟩|²

from qkabrine_automl import QuantumKernel

kernel = QuantumKernel(n_qubits=4, embedding='iqp', n_layers=1)
K = kernel.compute_kernel_matrix(X_train)       # train kernel matrix
K_test = kernel.compute_kernel_matrix(X_test, X_train)  # test kernel matrix

QuantumKernelClassifier ¶

Quantum kernel + classical SVM for classification.

from qkabrine_automl import QuantumKernelClassifier

model = QuantumKernelClassifier(n_qubits=4, embedding='iqp', C=1.0)
model.fit(X_train, y_train)
preds = model.predict(X_test)
acc = model.score(X_test, y_test)

QuantumKernelRegressor ¶

Quantum kernel + classical SVR for regression.

from qkabrine_automl import QuantumKernelRegressor

model = QuantumKernelRegressor(n_qubits=4, embedding='iqp', C=1.0)
model.fit(X_train, y_train)
preds = model.predict(X_test)

—

Training Dynamics ¶

DataQuantumFisherMetric ¶

Pre-screen circuits for trainability using the Data Quantum Fisher Information Matrix.

from qkabrine_automl import DataQuantumFisherMetric

dqfim = DataQuantumFisherMetric(n_qubits=4, n_samples=20, seed=42)
metrics = dqfim.predict_generalization(circuit_fn, X, n_params=12)
print(f"Trainability score: {metrics.trainability_score:.3f}")
# Score < 0.05 indicates likely barren plateau — skip this circuit

BarrenPlateauMonitor ¶

Monitor gradient variance during training. Stops early if gradients vanish.

from qkabrine_automl import BarrenPlateauMonitor

monitor = BarrenPlateauMonitor(threshold=1e-7, window=3, auto_surgery=True)
monitor.update(gradient_estimates)
if monitor.plateau_detected:
    print("Barren plateau detected — stopping early")

QuantumNaturalGradient ¶

Quantum natural gradient optimizer using the quantum geometric tensor.

from qkabrine_automl import QuantumNaturalGradient

qng = QuantumNaturalGradient(learning_rate=0.01, regularisation=1e-3)

—

Exceptions ¶

Exception	When it is raised
`QkabrineError`	Base exception for all Qkabrine errors.
`TrainingFailureError`	A single candidate circuit failed during training.
`SearchExhaustedError`	Every candidate failed — no valid model was found.
`InvalidCircuitError`	A circuit configuration is invalid.