FAQ

—

Installation

Why do I get an error when running ``pip install qkabrine-automl``?

Make sure you have Python 3.9 or later:

python --version

If you’re on an older version, upgrade Python first from python.org.

—

PennyLane fails to install — what do I do?

Try installing it separately first:

pip install pennylane
pip install qkabrine-automl

If you’re on Windows and get a build error, make sure you have the latest pip:

python -m pip install --upgrade pip
pip install qkabrine-automl

—

Running the Search

How long does a search take?

It depends on your settings. A rough guide:

• train_steps=20, max_layers=1, 4 qubits → 2–5 minutes

• train_steps=40, max_layers=3, 6 qubits → 10–30 minutes

• train_steps=100, max_layers=5, 8 qubits → 1–3 hours

To speed things up: reduce train_steps, reduce max_layers, reduce n_qubits, or set a time_budget in seconds.

automl = QkabrineAutoML(
    task='classification',
    train_steps=20,
    max_layers=2,
    time_budget=300,   # stop after 5 minutes no matter what
)

—

The search is running but accuracy is very low — what’s wrong?

A few things to check:

1. Too few training steps — try increasing train_steps to 80 or 100

2. Wrong encoding — try adding more encodings: encodings=('angle', 'iqp', 'angle_yz')

3. Data not normalised — Qkabrine normalises automatically, but check your data has no extreme outliers

4. Too few qubits — try increasing n_qubits

—

I get ``SearchExhaustedError`` — what does that mean?

It means every single candidate circuit failed during training. This usually happens when:

• Your data has only 1 class (classification requires at least 2)

• Your dataset is very small (need at least 5 samples)

• There is a conflict between your encoding and qubit count (e.g. 'amplitude' encoding requires the number of features to be a power of 2)

Try running with verbose=True to see exactly which circuits are failing and why.

—

Can I use this on a real quantum computer?

Yes. Export your best circuit to QASM and submit it to any hardware provider:

automl.export_qasm_to_file('my_circuit.qasm')

The file works with IBM Quantum, Amazon Braket, and any provider accepting OpenQASM 2.0. For IBM specifically, install the IBM backend:

pip install qkabrine-automl[ibm]

—

Data and Features

My dataset has 100 features but only 4 qubits — what happens?

Qkabrine automatically reduces your features to match the qubit count using the method set by feature_reduction. The default is PCA:

automl = QkabrineAutoML(
    n_qubits=4,
    feature_reduction='pca',   # reduces 100 features → 4 principal components
)

Other options: 'random_projection', 'select_variance', or None (which just takes the first N features — not recommended for large feature sets).

—

Does Qkabrine handle categorical features?

No — it expects numerical input only. Encode your categorical features first using scikit-learn’s LabelEncoder or OneHotEncoder before passing data to Qkabrine.

—

My labels are strings like “cat” and “dog” — is that OK?

Yes. Qkabrine’s LabelEncoder handles string labels automatically. predict() will return the original string labels back.

—

Models and Results

How do I know which model won — variational or kernel?

After fitting, check:

print(automl._best['model_type'])   # 'variational' or 'kernel'
print(automl._best['name'])         # e.g. 'hardware_efficient' or 'kernel_iqp'

Or just call automl.leaderboard() — the Type column shows var or kernel.

—

Can I save and reload my model?

Yes — save/load works for both variational and kernel models:

automl.save('my_model.pkl')

# Later, in any script:
loaded = QkabrineAutoML.load('my_model.pkl')
preds = loaded.predict(X_new)

—

``predict_proba`` is raising an error — why?

Two common reasons:

1. You’re calling it on a regression model — it’s only valid for classification

2. The best model is a quantum kernel — kernel models don’t support predict_proba

Check with:

print(automl.task)                    # must be 'classification'
print(automl._best['model_type'])     # must not be 'kernel'

—

The leaderboard shows many models with the same score — is that normal?

Yes, especially for small datasets where many circuits hit the ceiling (e.g. 100% accuracy on a simple dataset) or the floor (50% random chance). The first one listed among ties is selected as best. You can inspect all tied models in automl._results.

—

Advanced Usage

What is a barren plateau and should I worry about it?

A barren plateau is when gradients become so small that training makes no progress — the circuit’s loss landscape becomes completely flat. It’s more common with deep circuits and many qubits.

Enable monitoring to detect and skip affected circuits automatically:

automl = QkabrineAutoML(
    monitor_barren_plateaus=True,
    use_dqfim_prescreening=True,
)

—

What is DQFIM prescreening?

DQFIM (Data Quantum Fisher Information Matrix) is a technique that estimates how trainable a circuit is before spending time actually training it. Circuits with a trainability score below 0.05 are skipped.

Enable it with use_dqfim_prescreening=True. It adds a small overhead per candidate but can save significant time on deep circuits.

—

Can I search over multiple encodings at once?

Yes — pass a tuple:

automl = QkabrineAutoML(
    encodings=('angle', 'iqp', 'angle_yz'),
)

Each circuit architecture will be tested with each encoding combination, so the search space grows. Consider also setting a time_budget.

—

Getting Help

• Bug reports: github.com/ericjagwara/qkabrine/issues

• Author: ericjagwara.online

• Lab: solidelf.org