Public API Reference¶

This page summarizes the import paths that are intended for examples, notebooks, scripts, and downstream use. The project keeps notebooks as thin clients over these package APIs.

Top-Level Imports¶

The qml package lazily exposes the main workflow and estimator APIs:

from qml import (
    QuantumClassifier,
    QuantumKernel,
    QuantumKernelClassifier,
    QuantumGaussianProcessRegressor,
    QuantumKernelRegressor,
    QuantumKernelPCA,
    QuantumOneClassClassifier,
    QuantumReservoirClassifier,
    QuantumReservoirFeatures,
    QuantumReservoirRegressor,
    QuantumRegressor,
    TrainableQuantumKernelRegressor,
    ansatz_parameter_count,
    benchmark_runtime_scaling,
    build_noise_model,
    cross_validate_estimator,
    embedding_parameter_count,
    estimate_circuit_depth,
    format_table,
    kernel_target_alignment,
    list_supported_optimizers,
    make_sequence_windows,
    model_selection_table,
    print_section,
    print_model_selection,
    print_table,
    qcnn_parameter_count,
    run_qcnn,
    run_quantum_autoencoder,
    run_quantum_kernel_classifier,
    run_quantum_metric_learner,
    run_trainable_quantum_kernel_classifier,
    run_trainable_quantum_kernel_regressor,
    run_vqc,
    run_vqr,
    select_best_model,
    train_test_evaluate,
)

Use top-level imports for compact examples. Use module imports when you want to make the implementation area explicit.

Workflow Functions¶

Workflow functions return dictionaries unless documented otherwise. Metric learning returns a result dataclass with attributes such as train_accuracy, test_accuracy, and loss_history.

Estimator APIs¶

Use these when data already exists outside the package:

The estimator classes expose fit, predict, score, get_params, and set_params where those operations apply. Transformers and structure-discovery models expose task-appropriate methods such as transform, fit_transform, decision_function, and score_samples.

The v0.2.12 estimator consistency pass guarantees the following at smoke scale:

• fitted array estimators record n_features_in_
• classifiers record classes_
• unfitted prediction, transform, scoring, and decision methods raise clear ValueErrors
• prediction and transform methods validate the fitted feature count
• classifier score(...) returns accuracy
• regressor score(...) returns negative mean squared error
• circuit-backed fitted estimators expose circuit_metadata_ where the estimator owns the circuit execution path
• kernel wrappers retain kernel_matrix_train_
• reservoir wrappers retain feature_matrix_train_
• trainable estimators expose learned parameters and objective traces

For the detailed matrix across estimator-style APIs, see docs/qml/estimator_consistency.md.

QuantumClassifier and QuantumRegressor are sklearn-style wrappers around the same circuit families described in the VQC and VQR theory pages. They do not introduce a separate model family; they adapt the package's variational classifier and regressor behavior to user-supplied arrays and estimator-style model-selection utilities.

Variational workflows and estimator wrappers accept batch_size for deterministic mini-batch optimizer updates. The default batch_size=None preserves full-batch training.

Circuit-backed estimators accept an optional noise_model dictionary for depolarizing, amplitude-damping, and readout-error simulation. Use qml.noise.build_noise_model(...) to validate explicit channel probabilities.

Composed estimator wrappers expose useful nested parameters through get_params(deep=True) and set_params(...). Examples include kernel__shots, kernel__embedding, kernel__noise_model, reservoir__n_layers, reservoir__shots, and reservoir__noise_model. The model-selection helpers clone estimators from shallow constructor parameters, so configured kernel and reservoir objects are preserved without passing nested keys directly to constructors.

For a compact map from public QML implementations to theory notes, tutorials, benchmarks, and generated web pages, see docs/qml/algorithm_coverage.md.

Embeddings and Ansatz Helpers¶

Workflow result dictionaries for circuit-backed package models include a circuit_metadata field with qubit count, trainable-parameter count, estimated depth, embedding/ansatz labels, and a depth_is_estimate flag.

Noise Helpers¶

Benchmark APIs¶

Benchmark results include run records, aggregate metric summaries, runtime summaries, train/test gap summaries, confidence intervals, paired deltas against the best included classical baseline, tuning metadata, environment metadata, and a convenience best_model field based on the primary test metric.

Classical Baselines¶

Classical baselines are first-class package workflows so quantum models can be compared against standard references under the same dataset settings:

Reporting Helpers¶

Notebook and CLI examples should use the shared reporting helpers instead of duplicating table-formatting code:

Versioning¶

The installed package version is exposed as:

import qml

print(qml.__version__)

During editable local development, the value comes from installed package metadata. Reinstall with pip install -e . after version changes.