python v0.7

Qiskit-nature

Quantum chemistry and natural science algorithms for Qiskit

Quick install

pip install qiskit-nature

Background and History

Qiskit Nature emerged from the reorganization of Qiskit’s application libraries that took place between 2021 and 2022. Its functionality was originally part of Qiskit Aqua (the “algorithms” pillar of the original Qiskit ecosystem), which bundled quantum chemistry, optimization, finance, and machine learning algorithms into a single monolithic package. As Aqua grew unwieldy, IBM split it into focused domain libraries: Qiskit Nature for chemistry and physics, Qiskit Optimization for combinatorial problems, Qiskit Finance for financial applications, and Qiskit Machine Learning for QML.

Qiskit Nature was developed by IBM Quantum’s applications research team, with Max Rossmannek, Steve Wood, and other contributors leading the effort to extract and refine the chemistry functionality from Aqua into a standalone library. The first dedicated release of Qiskit Nature appeared in 2021, with a redesigned API that was cleaner and more modular than the Aqua-era interface. A major breaking change came with Qiskit Nature 0.5 (released in 2022), which introduced a new problem and solver architecture based on second-quantized operators and mapper classes.

The library addresses a core challenge in quantum computational chemistry: translating molecular electronic structure problems into qubit Hamiltonians that quantum algorithms can solve. It integrates with classical chemistry packages, primarily PySCF, to generate molecular integrals and then provides the fermion-to-qubit mapping machinery (Jordan-Wigner, Parity, Bravyi-Kitaev) and variational ansatz circuits (UCC, UCCSD) needed for algorithms like VQE. The ActiveSpaceTransformer reduces the orbital space to a computationally tractable subset, which is essential for all but the smallest molecules.

As of 2025, Qiskit Nature is maintained by the Qiskit community (under the qiskit-community GitHub organization) rather than IBM’s core Qiskit team. Development activity has slowed compared to the core Qiskit SDK, and the library’s long-term maintenance status is tied to community contributions. It remains functional and is used in educational settings and research for benchmarking small molecular systems on quantum simulators and hardware. Competing tools in the same space include OpenFermion (which predates Qiskit Nature and focuses on the chemistry side) and PennyLane’s quantum chemistry module.

Qiskit Nature bridges classical computational chemistry and quantum hardware by framing molecular problems in terms Qiskit circuits can solve. The library’s core abstraction is the ElectronicStructureProblem, which takes a molecular geometry and basis set, invokes a classical driver (PySCF is the most commonly used), and returns a second-quantized Hamiltonian. The ActiveSpaceTransformer reduces the full orbital space to a computationally tractable active space, which is essential for molecules with more than a few electrons.

The second-quantized Hamiltonian is converted to a qubit operator using mappers such as JordanWignerMapper, ParityMapper, or BravyiKitaevMapper. From there, GroundStateEigensolver orchestrates the full pipeline: it pairs a quantum solver (typically VQE with a UCC or UCCSD ansatz) with the mapped Hamiltonian to estimate the ground-state molecular energy. Excited-state solvers and dipole moment calculations are also supported.

Qiskit Nature is designed to work within Qiskit’s broader algorithm ecosystem. VQE runs can be handed off to any Qiskit-compatible backend or simulator, and the library’s PySCF integration handles integral generation automatically when PySCF is installed. This makes it straightforward to benchmark small molecules on simulators before moving to hardware, covering use cases from hydrogen (H2) up to small organic molecules.

Key Imports

# Problem definition
from qiskit_nature.second_q.problems import ElectronicStructureProblem

# Classical chemistry drivers
from qiskit_nature.second_q.drivers import PySCFDriver

# Transformers for active space reduction
from qiskit_nature.second_q.transformers import ActiveSpaceTransformer

# Fermion-to-qubit mappers
from qiskit_nature.second_q.mappers import JordanWignerMapper, ParityMapper, BravyiKitaevMapper

# Solvers
from qiskit_nature.second_q.algorithms import GroundStateEigensolver, ExcitedStatesEigensolver

# VQE factory for ground state estimation
from qiskit_nature.second_q.algorithms import VQEUCCFactory

# Ansatz circuits
from qiskit_nature.second_q.circuit.library import UCCSD, UCC, HartreeFock

# Qiskit algorithm primitives used alongside Nature
from qiskit_algorithms import VQE, NumPyEigensolver, NumPyMinimumEigensolver
from qiskit_algorithms.optimizers import COBYLA, L_BFGS_B, SLSQP
from qiskit.primitives import Estimator

Core Classes

  • PySCFDriver - Generates molecular integrals from a geometry string and basis set by calling PySCF under the hood. This is the primary entry point for defining a molecule.
  • ElectronicStructureProblem - Wraps the driver output into a problem object that holds the second-quantized Hamiltonian and any transformers. Acts as the bridge between the classical chemistry side and the quantum solver side.
  • ActiveSpaceTransformer - Reduces the full orbital space to a smaller active space (specified by number of electrons and orbitals). Essential for keeping qubit counts tractable on real hardware.
  • JordanWignerMapper / ParityMapper / BravyiKitaevMapper - Convert the fermionic Hamiltonian to a qubit operator. Jordan-Wigner is the simplest and most common; Parity can exploit symmetries to reduce qubit count by two; Bravyi-Kitaev offers better asymptotic locality.
  • GroundStateEigensolver - Orchestrates the full pipeline: takes a mapper and a solver, applies the mapper to the problem Hamiltonian, runs the solver, and returns the ground state energy and auxiliary properties.
  • ExcitedStatesEigensolver - Same orchestration pattern as GroundStateEigensolver but targets multiple excited states.
  • VQEUCCFactory - Factory class that constructs a VQE instance pre-configured with a UCC-family ansatz and a Hartree-Fock initial state. Simplifies the common VQE workflow.
  • UCCSD / UCC - Unitary Coupled Cluster ansatz circuits. UCCSD includes single and double excitations; UCC allows custom specification of excitation types.
  • HartreeFock - Prepares the Hartree-Fock reference state as a quantum circuit, used as the initial state for UCC ansatze.

Common Patterns

H2 ground state energy (VQE)

This example computes the ground state energy of molecular hydrogen at equilibrium bond length using VQE with a UCCSD ansatz.

from qiskit_nature.second_q.drivers import PySCFDriver
from qiskit_nature.second_q.mappers import JordanWignerMapper
from qiskit_nature.second_q.algorithms import GroundStateEigensolver, VQEUCCFactory
from qiskit_algorithms import VQE
from qiskit_algorithms.optimizers import SLSQP
from qiskit.primitives import Estimator

# Define the H2 molecule at 0.735 angstrom bond length
driver = PySCFDriver(atom="H 0 0 0; H 0 0 0.735", basis="sto-3g")

# Build the electronic structure problem from the driver
problem = driver.run()

# Choose a fermion-to-qubit mapping
mapper = JordanWignerMapper()

# Create a VQE solver with UCCSD ansatz via the factory
vqe_factory = VQEUCCFactory(Estimator(), SLSQP(), "UCCSD")

# Wrap the solver in the ground state eigensolver pipeline
ground_state_solver = GroundStateEigensolver(mapper, vqe_factory)

# Run the full pipeline: map Hamiltonian, build ansatz, optimize
result = ground_state_solver.solve(problem)

print(f"Ground state energy: {result.total_energies[0]:.6f} Hartree")
print(f"Nuclear repulsion energy: {result.nuclear_repulsion_energy:.6f} Hartree")

Active space reduction

For molecules larger than H2, the full orbital space produces too many qubits. The ActiveSpaceTransformer selects a subset of orbitals and electrons.

from qiskit_nature.second_q.drivers import PySCFDriver
from qiskit_nature.second_q.transformers import ActiveSpaceTransformer
from qiskit_nature.second_q.mappers import JordanWignerMapper
from qiskit_nature.second_q.algorithms import GroundStateEigensolver, VQEUCCFactory
from qiskit_algorithms.optimizers import COBYLA
from qiskit.primitives import Estimator

# Define lithium hydride
driver = PySCFDriver(atom="Li 0 0 0; H 0 0 1.6", basis="sto-3g")

# Run the driver to get the full problem
full_problem = driver.run()

# Reduce to 2 electrons in 2 spatial orbitals (4 spin-orbitals, so 4 qubits)
transformer = ActiveSpaceTransformer(num_electrons=2, num_spatial_orbitals=2)

# Apply the transformer to the problem
reduced_problem = transformer.transform(full_problem)

# Solve the reduced problem with VQE
mapper = JordanWignerMapper()
vqe_factory = VQEUCCFactory(Estimator(), COBYLA(maxiter=500), "UCCSD")
solver = GroundStateEigensolver(mapper, vqe_factory)
result = solver.solve(reduced_problem)

print(f"Ground state energy (active space): {result.total_energies[0]:.6f} Hartree")

Excited states

Use NumPyEigensolver to compute multiple eigenvalues of the mapped Hamiltonian, giving both ground and excited state energies exactly (on a simulator).

from qiskit_nature.second_q.drivers import PySCFDriver
from qiskit_nature.second_q.mappers import JordanWignerMapper
from qiskit_nature.second_q.algorithms import ExcitedStatesEigensolver
from qiskit_algorithms import NumPyEigensolver

# Set up the H2 problem
driver = PySCFDriver(atom="H 0 0 0; H 0 0 0.735", basis="sto-3g")
problem = driver.run()

mapper = JordanWignerMapper()

# NumPyEigensolver computes k eigenvalues exactly (classical diagonalization)
numpy_solver = NumPyEigensolver(k=3)

# Wrap in the excited states pipeline
excited_state_solver = ExcitedStatesEigensolver(mapper, numpy_solver)
result = excited_state_solver.solve(problem)

for i, energy in enumerate(result.total_energies):
    print(f"State {i}: {energy:.6f} Hartree")

Custom ansatz

Build a UCC ansatz with only double excitations, or specify a custom list of excitation types.

from qiskit_nature.second_q.drivers import PySCFDriver
from qiskit_nature.second_q.mappers import JordanWignerMapper
from qiskit_nature.second_q.circuit.library import UCC, HartreeFock
from qiskit_algorithms import VQE
from qiskit_algorithms.optimizers import L_BFGS_B
from qiskit.primitives import Estimator

driver = PySCFDriver(atom="H 0 0 0; H 0 0 0.735", basis="sto-3g")
problem = driver.run()

mapper = JordanWignerMapper()

num_spatial_orbitals = problem.num_spatial_orbitals
num_particles = problem.num_particles

# Build the Hartree-Fock initial state
initial_state = HartreeFock(num_spatial_orbitals, num_particles, mapper)

# Build a UCC ansatz with only double excitations
ansatz = UCC(
    num_spatial_orbitals=num_spatial_orbitals,
    num_particles=num_particles,
    excitations="d",  # "s" for singles, "d" for doubles, "sd" for both
    qubit_mapper=mapper,
    initial_state=initial_state,
)

# Map the Hamiltonian to qubit operators
hamiltonian = mapper.map(problem.hamiltonian.second_q_op())

# Run VQE with the custom ansatz
vqe = VQE(Estimator(), ansatz, L_BFGS_B())
vqe_result = vqe.compute_minimum_eigenvalue(hamiltonian)

# Add nuclear repulsion energy back in
total_energy = vqe_result.eigenvalue.real + problem.nuclear_repulsion_energy
print(f"Ground state energy (doubles only): {total_energy:.6f} Hartree")

Comparison with Similar Tools

OpenFermion + Cirq is the closest alternative. OpenFermion predates Qiskit Nature and provides a mature fermion-to-qubit mapping layer, while Cirq handles the circuit execution. OpenFermion has stronger community adoption in academic research and supports more mapping schemes out of the box. Choose OpenFermion if you are targeting Google hardware or prefer a more modular, framework-agnostic approach to the chemistry layer.

PennyLane’s quantum chemistry module (qml.qchem) integrates tightly with PennyLane’s autodiff framework, making it a natural choice if you want gradient-based VQE optimization with automatic differentiation through the quantum circuit. It supports PySCF and Psi4 backends. Choose PennyLane if differentiability and hardware-agnostic execution are priorities.

Standalone PySCF is the right tool when you only need classical computational chemistry. PySCF handles Hartree-Fock, DFT, CCSD, CASSCF, and many other methods far more efficiently than any quantum approach for molecules that fit in its classical solvers. Use Qiskit Nature only when you specifically need to study the quantum algorithmic side, for benchmarking, or for molecules where classical methods struggle (strongly correlated systems at scale, once hardware catches up).

Learning Resources