Skip to content

algorithms.md

Latest commit

 

History

History
311 lines (236 loc) · 9.66 KB

algorithms.md

File metadata and controls

311 lines (236 loc) · 9.66 KB
Raw

Algorithms, Addons, and Application Packages

The core qiskit distribution provides circuits, operators, primitives, synthesis, transpilation, and quantum-information tools. High-level algorithms and domain applications live in separate packages.

Verified Package Matrix

Checked on 2026-07-23:

Package Version Primary role
qiskit-algorithms 0.4.0 VQE, QAOA, Grover, phase estimation, eigensolvers, optimizers
qiskit-nature 0.8.0 Electronic structure, second quantization, mappers
qiskit-nature-pyscf 0.4.0 PySCF electronic-structure driver integration
qiskit-machine-learning 0.9.0 Kernels, QNNs, classifiers/regressors, Torch connector
qiskit-optimization 0.7.0 Quadratic programs, converters, quantum optimization wrappers
qiskit-addon-cutting 0.10.0 Circuit and operator cutting
qiskit-addon-sqd 0.12.1 Sample-based quantum diagonalization
qiskit-addon-obp 0.3.0 Operator backpropagation
qiskit-addon-mpf 0.3.0 Multi-product formulas
qiskit-addon-aqc-tensor 0.3.1 Approximate quantum compilation with tensor networks

Install exact pins together in a fresh environment:

uv pip install \
  "qiskit==2.5.0" \
  "qiskit-algorithms==0.4.0" \
  "qiskit-optimization==0.7.0"

For chemistry:

uv pip install \
  "qiskit==2.5.0" \
  "qiskit-algorithms==0.4.0" \
  "qiskit-nature==0.8.0" \
  "qiskit-nature-pyscf==0.4.0"

Resolve application packages together; their Qiskit compatibility windows can differ.

Decide Between Manual and Library Implementations

Use a manual circuit when:

  • teaching or inspecting a small algorithm,
  • testing a new circuit construction,
  • controlling every primitive PUB and compilation step,
  • avoiding an application package dependency.

Use an application package when:

  • it provides tested problem transformations,
  • the result object and domain post-processing are valuable,
  • the implementation accepts current V2 primitives,
  • its release supports the installed Qiskit version.

Do not copy a pre-1.0 algorithm tutorial without checking constructors and primitive requirements.

VQE with Qiskit Algorithms 0.4

This verified local example uses the V2 StatevectorEstimator:

from qiskit.circuit.library import efficient_su2
from qiskit.primitives import StatevectorEstimator
from qiskit.quantum_info import SparsePauliOp
from qiskit_algorithms import VQE
from qiskit_algorithms.optimizers import SLSQP

hamiltonian = SparsePauliOp.from_list(
    [
        ("ZI", 1.0),
        ("IZ", 1.0),
        ("XX", 0.2),
    ]
)
ansatz = efficient_su2(
    num_qubits=2,
    reps=1,
    entanglement="linear",
)

vqe = VQE(
    estimator=StatevectorEstimator(),
    ansatz=ansatz,
    optimizer=SLSQP(maxiter=100),
    initial_point=[0.0] * ansatz.num_parameters,
)
result = vqe.compute_minimum_eigenvalue(hamiltonian)
print(float(result.eigenvalue.real))

For hardware:

  1. Use a Runtime EstimatorV2.
  2. Provide a transpiler adapter or manage the parameterized ISA circuit explicitly.
  3. Bound optimizer iterations and requested precision.
  4. Store each job ID and convergence record.

Do not transpile a newly bound circuit from scratch in every cost-function call.

QAOA and Qiskit Optimization

Model a binary problem with QuadraticProgram:

from qiskit.primitives import StatevectorSampler
from qiskit_algorithms import QAOA
from qiskit_algorithms.optimizers import COBYLA
from qiskit_optimization import QuadraticProgram
from qiskit_optimization.algorithms import MinimumEigenOptimizer

problem = QuadraticProgram("binary_demo")
problem.binary_var("x")
problem.binary_var("y")
problem.maximize(
    linear={"x": 1, "y": 1},
    quadratic={("x", "y"): -2},
)

qaoa = QAOA(
    sampler=StatevectorSampler(seed=5),
    optimizer=COBYLA(maxiter=100),
    reps=1,
)
solver = MinimumEigenOptimizer(qaoa)
result = solver.solve(problem)

print(result.x, result.fval, result.status)

Use optimizer objects such as COBYLA(...), not old string-valued optimizer arguments.

Before claiming a quantum result:

  • compare with a classical solver for small instances,
  • verify variable-to-bitstring ordering,
  • report feasibility and objective value,
  • separate optimizer stochasticity from quantum sampling,
  • quantify total circuit evaluations and shot cost.

Grover and Phase Estimation

Qiskit Algorithms 0.4 constructors accept V2 Sampler implementations:

from qiskit.primitives import StatevectorSampler
from qiskit_algorithms import Grover, PhaseEstimation

sampler = StatevectorSampler(seed=5)
grover = Grover(sampler=sampler)
phase_estimation = PhaseEstimation(
    num_evaluation_qubits=4,
    sampler=sampler,
)

The old quantum_instance= argument is not current.

Use QFTGate in custom phase-estimation circuits:

from qiskit import QuantumCircuit
from qiskit.circuit.library import QFTGate

inverse_qft = QFTGate(4).inverse()
circuit = QuantumCircuit(4)
circuit.append(inverse_qft, range(4))

The QFT blueprint class is deprecated and scheduled for removal in Qiskit 3.0.

Qiskit Nature

Qiskit Nature converts domain problems into second-quantized operators and qubit operators.

from qiskit_nature.second_q.drivers import PySCFDriver
from qiskit_nature.second_q.mappers import JordanWignerMapper

driver = PySCFDriver(
    atom="H 0 0 0; H 0 0 0.735",
    basis="sto3g",
    charge=0,
    spin=0,
)
problem = driver.run()

fermionic_hamiltonian = problem.hamiltonian.second_q_op()
mapper = JordanWignerMapper()
qubit_hamiltonian = mapper.map(fermionic_hamiltonian)

print(problem.num_spatial_orbitals)
print(problem.num_particles)
print(qubit_hamiltonian.num_qubits)

The PySCF calculation is classical preprocessing. Record:

  • geometry and units,
  • basis set,
  • charge and spin,
  • active-space or freeze-core choices,
  • mapper and symmetry reductions,
  • nuclear repulsion energy,
  • package versions.

Do not add the nuclear repulsion term twice. Prefer Qiskit Nature's result interpreters for complete energy reporting.

QubitConverter is obsolete; use mapper classes directly.

Qiskit Machine Learning 0.9

Qiskit Machine Learning includes quantum kernels, quantum neural networks, trainable models, and PyTorch integration.

This verified kernel example uses APIs moved into the Machine Learning package:

import numpy as np
from qiskit.circuit.library import zz_feature_map
from qiskit.primitives import StatevectorSampler
from qiskit_machine_learning.kernels import FidelityQuantumKernel
from qiskit_machine_learning.state_fidelities import ComputeUncompute

feature_map = zz_feature_map(
    feature_dimension=2,
    reps=1,
    entanglement="full",
)
sampler = StatevectorSampler(seed=5)
fidelity = ComputeUncompute(sampler=sampler)
kernel = FidelityQuantumKernel(
    fidelity=fidelity,
    feature_map=feature_map,
)

x = np.array([[0.1, 0.2], [0.3, 0.4]])
kernel_matrix = kernel.evaluate(x)

Since Qiskit Machine Learning 0.8, relevant gradients, optimizers, state fidelities, and utilities moved from qiskit_algorithms into qiskit_machine_learning. Check its migration guide before adapting old imports.

For evaluation:

  • use a held-out test set,
  • compare against matched classical kernels/models,
  • avoid generating labels randomly in demonstration code presented as evidence,
  • account for kernel-matrix (O(n^2)) evaluations,
  • separate simulation results from hardware results.

Qiskit Addons

Addons are modular algorithm-building components aligned with stages of the Qiskit workflow.

Addon Typical stage Use
Circuit cutting Optimize / execute / reconstruct Split large circuits or observables and reconstruct estimates
Operator backpropagation (OBP) Optimize Move selected circuit operations into observables
Multi-product formulas (MPF) Map / optimize Approximate time evolution using formula combinations
AQC-Tensor Map / optimize Approximate target circuits with tensor-network-assisted compilation
Sample-based quantum diagonalization (SQD) Analyze Combine QPU samples with classical subspace diagonalization

Example installation:

uv pip install "qiskit-addon-cutting==0.10.0"
uv pip install "qiskit-addon-sqd==0.12.1"
uv pip install "qiskit-addon-obp==0.3.0"
uv pip install "qiskit-addon-mpf==0.3.0"
uv pip install "qiskit-addon-aqc-tensor==0.3.1"

Each addon has independent release notes and assumptions. Read its tutorial and validate against a classically tractable instance.

Direct Quantum-Information Tools

Many tasks do not need a high-level algorithm package:

from qiskit.quantum_info import DensityMatrix, Operator, Statevector

state = Statevector.from_instruction(circuit)
operator = Operator(circuit)
density_matrix = DensityMatrix(state)

Use qiskit.quantum_info for:

  • ideal state/operator analysis,
  • fidelity and distance metrics,
  • partial traces and entropies,
  • Pauli and Clifford algebra,
  • channel representations,
  • small-system validation.

Dense state and operator memory grows exponentially; check dimensions before constructing them.

Algorithm Review Checklist

  1. Is the cited speedup asymptotic, heuristic, or empirically demonstrated?
  2. Does state preparation or readout dominate the claimed advantage?
  3. Is the instance classically verifiable at the tested size?
  4. Are package and primitive versions compatible?
  5. Does the implementation use V2 primitives?
  6. Is the parameterized circuit compiled once for the selected target?
  7. Are observable layouts and bit order handled correctly?
  8. Are optimizer evaluations, precision, shots, mitigation, and total QPU usage reported?
  9. Is every result labeled as ideal simulation, noisy simulation, or hardware?
  10. Are classical baselines and uncertainty included?