NWQLib: Northwest Quantum Library

NWQLib applies quantum algorithms to scientific problems. You state the problem and choose a method, and NWQLib plans the construction, runs it on the backend you choose and returns the result with its resource counts and what is known about its error. Circuits are built with Qiskit.

Documentation: https://pnnl.github.io/NWQLib/

Installation

NWQLib requires Python 3.12 or later. Install the package with the local Aer simulator:

python -m pip install "nwqlib[aer]"

The base package depends on NumPy 2.5.2 or later, SciPy 1.18.1 or later, SymPy 1.14.0 or later and Pydantic 2.13.5 or later, below 3. The extras aer, qiskit, ibm, ionq, nexus, chemistry, tensor, qasm and nwqec require Qiskit 2.5.2 or later. The validated CI environment in docs/ENVIRONMENT_LOCK.txt uses Python 3.12.14, Qiskit 2.5.2 and Qiskit Aer 0.17.2.

The base package, python -m pip install nwqlib, describes the methods, accepts numerical inputs, plans LCHS with its default settings and supports classical evaluation with execution="classical" for LCHS, QLS, QCELS, SPE, RFE, RWPE, QHD, Expectation, Lanczos, FixedGCIM and ADAPT within their supported numerical-input and method-option domains. Classical evaluation that expands a circuit-defined initial or trial state also requires Qiskit. Building circuits needs the qiskit extra, and running them needs the extra of the chosen backend (aer, ibm, ionq, nexus), each of which includes Qiskit. For example, python -m pip install "nwqlib[aer,notebook,chemistry]" adds the example notebooks and the molecular Hamiltonian builder, and python -m pip install "nwqlib[ibm]" adds IBM Runtime. Install and first result lists every extra, and Choose a backend explains what each backend supports. To work on NWQLib itself, see Set up, test and build.

First result

To solve du/dt = -A u with a small physical input:

from nwqlib import LinearDynamics, solve
from nwqlib.algorithms import LCHS

problem = LinearDynamics(
    A=[[0.4, 0.15], [0.05, 0.25]],
    initial_state=[1.0, 0.0],
    time=0.1,
)
result = solve(problem, method=LCHS())
print(result.solution)

[ 0.96006038-1.54102084e-12j -0.00513885+3.61167323e-13j]

The default returns an approximation of the physical solution using nine qubits in total. Install and first result compares it with an independent reference and shows how to change the approximation. Each method accepts its own input forms and conversions, which its algorithm guide describes.

The example notebooks solve complete scientific problems from input to result, error and circuit cost: molecular ground-state energy, a linear system, linear dynamics and optimization. One more notebook estimates the resources of a linear system, heat flow, two spin chains and a GCiM trial basis at 80 to 100 system qubits, where the largest circuit, LCHS for heat flow, has 109 qubits in total. It also estimates one QHD step on a three-variable grid of 32 points per variable, which takes 96 qubits in the one-hot encoding. The examples guide points you to the notebook that matches your problem. The mathematics page states the bounds, resource formulas and error budgets that NWQLib uses, each with its proof or source and the code that implements it.

Choose a task

Each method's tests are in tests/, in files named after the method, such as tests/test_lchs_*.py and tests/test_qls_*.py. The examples guide lists the notebook of each method.

Algorithms

Each method reports the quantity it obtained and any accuracy conditions that remain unresolved. Each method is checked on small cases against independent references, and Limitations and open work lists what has been checked for each method and its current limitations. The resource-estimation notebook runs no circuit. A projected energy, a local statistical interval or a completed simulation does not by itself establish the full requested scientific claim. State preparation, block encoding, LCU, QSP/QSVT and evolution subroutines have their own API reference pages.

Backend support

A backend runs a method only when it supports that method's circuits and readout. Choose a backend gives the details.

Citation

If you use NWQLib in your work, please cite it through its Zenodo record, which resolves to the latest version:

@software{nwqlib,
  author  = {Zheng, Muqing and Liu, Chenxu and Song, Zhixin and Wu, Zeguan and Li, Xiangyu and Li, Mingze and Bauman, Nicholas P. and Stein, Samuel A. and M{\"u}lmenst{\"a}dt, Johannes and Chen, Yousu and Wiebe, Nathan and Li, Ang and Kowalski, Karol},
  title   = {NWQLib},
  year    = {2026},
  version = {1.0.2},
  doi     = {10.5281/zenodo.23074265},
  url     = {https://github.com/pnnl/NWQLib}
}

The references page lists the papers behind each algorithm and subroutine, with the equations NWQLib implements.

Authors and Developers

For questions, bug reports or collaboration, contact Muqing Zheng (muqing.zheng@pnnl.gov).

Affiliations are those at the time of contribution.

• Muqing Zheng, Pacific Northwest National Laboratory
• Chenxu Liu, Pacific Northwest National Laboratory
• Zhixin Song, Pacific Northwest National Laboratory and Georgia Institute of Technology
• Zeguan Wu, Pacific Northwest National Laboratory and University of Pittsburgh
• Xiangyu Li, Pacific Northwest National Laboratory
• Mingze Li, Pacific Northwest National Laboratory
• Nicholas P. Bauman, Pacific Northwest National Laboratory
• Samuel A. Stein, Pacific Northwest National Laboratory
• Johannes Mülmenstädt, Pacific Northwest National Laboratory
• Yousu Chen, Pacific Northwest National Laboratory
• Nathan Wiebe, Pacific Northwest National Laboratory and University of Toronto
• Ang Li, Pacific Northwest National Laboratory and University of Washington
• Karol Kowalski, Pacific Northwest National Laboratory

Acknowledgements

This work was supported by Pacific Northwest National Laboratory's Quantum Algorithms and Architecture for Domain Science (QuAADS) Laboratory Directed Research and Development (LDRD) Initiative. This material is based upon work supported by the U.S. Department of Energy, Office of Science, National Quantum Information Science Research Centers, Quantum Science Center (QSC). The Pacific Northwest National Laboratory is operated by Battelle for the U.S. Department of Energy under Contract DE-AC05-76RL01830.

NWQLib is released under the BSD 2-Clause License, given in LICENSE. Information release number PNNL-SA-227989.