qbiocode.learning.compute_qensemble module#

Quantum Ensemble Learning Module#

This module implements quantum ensemble learning algorithms using controlled swap operations and quantum superposition to create ensembles of training data arrangements. The ensemble leverages quantum superposition to evaluate multiple training set configurations simultaneously.

Supports two ensemble construction methods: - Fixed swap patterns: Deterministic controlled-SWAP operations - Random unitaries: Haar-random unitary transformations

References

  • Macaluso et al., “A variational algorithm for quantum ensemble learning” IET Quantum Communication (2023)

  • Rhrissorrakrai et al., “Quantum Ensembling Methods for Healthcare and Life Science” Briefings in Bioinformatics (2026) https://doi.org/10.1093/bib/bbag280

Summary#

Functions:

build_cosine_classifier

Build quantum cosine similarity classifier circuit.

build_ensemble_circuit

Build quantum ensemble classifier circuit.

compute_qensemble

Compute quantum ensemble classifier predictions.

Reference#

build_cosine_classifier(train, test, label_train)[source]#

Build quantum cosine similarity classifier circuit.

Implements a quantum cosine similarity classifier using controlled swap operations and Hadamard gates to measure similarity between training and test data points.

Parameters:

  • train (np.ndarray) – Training data point as normalized vector (length must be power of 2)

  • test (np.ndarray) – Test data point as normalized vector

  • label_train (np.ndarray) – Training label as normalized probability vector [p0, p1]

Returns:

Quantum circuit implementing the cosine classifier

Return type:

QuantumCircuit

Notes

The circuit computes P(0) = 1/2 + 1/2 * |<train|test>|^2

build_ensemble_circuit(X_data, Y_data, x_test, n_swap=1, d=2, mode='balanced', ensemble_method='swap', barriers=False)[source]#

Build quantum ensemble classifier circuit.

Creates a quantum ensemble learning circuit using either fixed swap operations or random unitary transformations.

Parameters:

  • X_data (np.ndarray, shape (n_samples, n_features)) – Training data points (normalized, n_features must be power of 2)

  • Y_data (np.ndarray, shape (n_samples, 2)) – Training labels as one-hot encoded vectors

  • x_test (List[complex]) – Test data point to classify (normalized)

  • n_swap (int, optional) – Number of swap/unitary operations per control qubit (default: 1)

  • d (int, optional) – Number of control qubits, creates 2^d ensemble members (default: 2)

  • mode (str, optional) – Sampling strategy: “balanced”, “unbalanced”, or “pair_sample” (default: “balanced”)

  • ensemble_method ({"swap", "random_unitary"}, optional) – Method for ensemble construction: - “swap”: Fixed controlled-SWAP operations (faster, deterministic) - “random_unitary”: Haar-random unitaries (more general, slower) (default: “swap”)

  • barriers (bool, optional) – Add barrier gates for visualization (default: False)

Returns:

Quantum circuit implementing the ensemble classifier

Return type:

QuantumCircuit

Notes

Total qubits: d + 2*n_samples*log2(n_features) + n_samples + 1 (+ 1 for random_unitary)

compute_qensemble(X_train, X_test, y_train, y_test, args, model='QEnsemble', data_key='', n_train=4, n_swap=1, d=2, mode='balanced', ensemble_method='swap', n_shots=8192, seed=123, device='CPU', verbose=False)[source]#

Compute quantum ensemble classifier predictions.

This function implements a quantum ensemble learning algorithm using either fixed swap operations or random unitary transformations to create superpositions of different training data arrangements.

Parameters:

  • X_train (np.ndarray) – Training feature set

  • X_test (np.ndarray) – Testing feature set

  • y_train (np.ndarray) – Training labels

  • y_test (np.ndarray) – Testing labels

  • args (dict) – Dictionary containing arguments for backend and settings

  • model (str, optional) – Model type (default: ‘QEnsemble’)

  • data_key (str, optional) – Key for the dataset (default: ‘’)

  • n_train (int, optional) – Number of training samples to use (must be even, default: 4)

  • n_swap (int, optional) – Number of swap/unitary operations per control qubit (default: 1)

  • d (int, optional) – Number of control qubits, creates 2^d ensemble members (default: 2)

  • mode (str, optional) – Sampling strategy: “balanced”, “unbalanced”, or “pair_sample” (default: “balanced”)

  • ensemble_method ({"swap", "random_unitary"}, optional) – Method for ensemble construction: - “swap”: Fixed controlled-SWAP operations (faster, deterministic) - “random_unitary”: Haar-random unitaries (more general, slower) (default: “swap”)

  • n_shots (int, optional) – Number of measurement shots (default: 8192)

  • seed (int, optional) – Random seed for reproducibility (default: 123)

  • device (str, optional) – Device type: ‘CPU’ or ‘GPU’ (default: ‘CPU’)

  • verbose (bool, optional) – Print additional information (default: False)

Returns:

Dictionary containing evaluation results including accuracy, runtime, model parameters, and other relevant metrics

Return type:

dict

Examples

>>> from qbiocode.learning import compute_qensemble
>>> # Fixed swap ensemble (standard)
>>> results = compute_qensemble(X_train, X_test, y_train, y_test, args,
...                             n_train=4, d=2, ensemble_method="swap")
>>> # Random unitary ensemble (advanced)
>>> results = compute_qensemble(X_train, X_test, y_train, y_test, args,
...                             n_train=4, d=2, ensemble_method="random_unitary")