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.

Reviewed Package Matrix

Release metadata and official API documentation checked on 2026-10-01. The VQE example was executed against a dense exact reference, and the two-variable Optimization/QAOA example returned the known optimum. Nature, Machine Learning, and addon workflows are illustrative and were not rerun in this refresh:

Install exact pins together in a fresh environment:

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

For chemistry:

uv pip install \
  "qiskit==2.5.2" \
  "qiskit-algorithms==0.4.0" \
  "qiskit-nature[pyscf]==0.8.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)
energy = float(result.eigenvalue.real)
# Tiny diagnostic only: dense diagonalization is exponential.
import numpy as np
exact_energy = float(np.linalg.eigvalsh(hamiltonian.to_matrix())[0])
assert abs(energy - exact_energy) < 1e-5
print(energy, exact_energy)

For hardware:

1. Use the Runtime client-side Estimator.
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_optimization.minimum_eigensolvers import QAOA
from qiskit_optimization.optimizers import COBYLA
from qiskit_optimization.utils import algorithm_globals
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},
)

algorithm_globals.random_seed = 5  # optimizer initialization is separate from sampler seed
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)

Qiskit Optimization 0.7 ships its own minimum_eigensolvers, optimizers, and utilities; use those types with MinimumEigenOptimizer instead of mixing qiskit_algorithms.QAOA results. 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.units import DistanceUnit
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",
    unit=DistanceUnit.ANGSTROM,
    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)

qiskit-nature[pyscf] installs the PySCF dependency for this driver. The separate qiskit-nature-pyscf plugin provides reverse integration and is not required by this snippet. 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.

Preserve the physical particle-number/spin sector when solving the mapped operator; unrestricted minimization over the full qubit Hilbert space can select the wrong sector. 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 documentation-checked illustrative 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.

Example installation:

uv pip install "qiskit-addon-cutting==0.10.0"
uv pip install "qiskit-addon-sqd==0.13.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?