Metadata-Version: 2.4
Name: nwqlib
Version: 1.0.0.post2
Summary: Evidence-aware quantum algorithms and scientific workflows.
Author: NWQLib developers
License-Expression: BSD-2-Clause
Project-URL: Homepage, https://github.com/pnnl/NWQLib
Project-URL: Documentation, https://pnnl.github.io/NWQLib/
Project-URL: Repository, https://github.com/pnnl/NWQLib
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.5.2
Requires-Dist: scipy>=1.18.1
Requires-Dist: sympy>=1.14.0
Requires-Dist: pydantic<3,>=2.13.5
Provides-Extra: qiskit
Requires-Dist: qiskit>=2.5.2; extra == "qiskit"
Provides-Extra: aer
Requires-Dist: qiskit>=2.5.2; extra == "aer"
Requires-Dist: qiskit-aer>=0.17.2; extra == "aer"
Provides-Extra: nwqec
Requires-Dist: qiskit>=2.5.2; extra == "nwqec"
Requires-Dist: nwqec==0.1.2; extra == "nwqec"
Provides-Extra: qre
Requires-Dist: qdk[qre]==1.32.3; extra == "qre"
Provides-Extra: dev
Requires-Dist: jsonschema>=4.26.0; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Provides-Extra: qasm
Requires-Dist: qiskit>=2.5.2; extra == "qasm"
Requires-Dist: openqasm3[parser]>=1.0.1; extra == "qasm"
Requires-Dist: qiskit-qasm3-import>=0.6.0; extra == "qasm"
Provides-Extra: notebook
Requires-Dist: jupyter>=1.0; extra == "notebook"
Requires-Dist: ipykernel>=6.0; extra == "notebook"
Requires-Dist: nbclient>=0.10; extra == "notebook"
Requires-Dist: matplotlib>=3.7; extra == "notebook"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
Provides-Extra: tensor
Requires-Dist: qiskit>=2.5.2; extra == "tensor"
Provides-Extra: chemistry
Requires-Dist: qiskit>=2.5.2; extra == "chemistry"
Requires-Dist: openfermion>=1.5; extra == "chemistry"
Requires-Dist: pyscf>=2.6; extra == "chemistry"
Provides-Extra: ibm
Requires-Dist: qiskit>=2.5.2; extra == "ibm"
Requires-Dist: qiskit-ibm-runtime>=0.49.0; extra == "ibm"
Provides-Extra: ionq
Requires-Dist: qiskit>=2.5.2; extra == "ionq"
Requires-Dist: qiskit-ionq>=1.1.1; extra == "ionq"
Requires-Dist: requests>=2.34.2; extra == "ionq"
Requires-Dist: urllib3>=2.8.0; extra == "ionq"
Provides-Extra: nexus
Requires-Dist: qiskit>=2.5.2; extra == "nexus"
Requires-Dist: qnexus>=0.49.0; extra == "nexus"
Requires-Dist: pytket>=2.18.1; extra == "nexus"
Requires-Dist: pytket-qiskit>=0.78.0; extra == "nexus"
Requires-Dist: selene-core>=0.3.2; extra == "nexus"
Dynamic: license-file

# NWQLib: Northwest Quantum Library

[![PyPI](https://img.shields.io/pypi/v/nwqlib.svg)](https://pypi.org/project/nwqlib/)    [![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://pypi.org/project/nwqlib/)    [![License](https://img.shields.io/badge/license-BSD--2--Clause-blue.svg)](https://github.com/pnnl/NWQLib/blob/main/LICENSE)    [![Documentation](https://img.shields.io/badge/docs-pnnl.github.io%2FNWQLib-blue.svg)](https://pnnl.github.io/NWQLib/)    [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23074265.svg)](https://doi.org/10.5281/zenodo.23074265)

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:

```bash
python -m pip install "nwqlib[aer]"
```

The base package, `python -m pip install nwqlib`, describes the methods, accepts inputs, plans LCHS with its default settings and runs the classical methods. Building and running circuits needs the extra of the chosen backend (`aer`, `ibm`, `ionq`, `nexus`), each of which includes Qiskit. [Install and first result](https://pnnl.github.io/NWQLib/quickstart/#install) lists every extra, and [Choose a backend](https://pnnl.github.io/NWQLib/backends/) explains what each backend supports. To work on NWQLib itself, see [Set up, test and build](https://pnnl.github.io/NWQLib/development/setup/).

## First result

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

```python
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)
```

```text
[ 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](https://pnnl.github.io/NWQLib/quickstart/) 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](https://github.com/pnnl/NWQLib/tree/main/examples) 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](https://pnnl.github.io/NWQLib/examples/) points you to the notebook that matches your problem. The [mathematics page](https://pnnl.github.io/NWQLib/mathematics/) 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

| Task | Read |
| --- | --- |
| Install and get a first result | [Install and first result](https://pnnl.github.io/NWQLib/quickstart/), [examples](https://pnnl.github.io/NWQLib/examples/) |
| Learn what Problem, Method, Plan, Run and Result are | [How NWQLib works](https://pnnl.github.io/NWQLib/how_it_works/) |
| Choose a problem and output | [Choose a problem and output](https://pnnl.github.io/NWQLib/problems/) |
| Compare NWQLib with other quantum packages | [Why NWQLib](https://pnnl.github.io/NWQLib/why_nwqlib/) |
| Compare methods and inspect results | [Plan, compare and solve](https://pnnl.github.io/NWQLib/scientist/) |
| Supply operators and states | [Supply inputs](https://pnnl.github.io/NWQLib/inputs/) |
| Estimate resources and check device fit | [Estimate resources](https://pnnl.github.io/NWQLib/resources/), [Check device fit and run time](https://pnnl.github.io/NWQLib/profiles/) |
| Check a result against a reference or tolerance | [Check accuracy and verify a result](https://pnnl.github.io/NWQLib/verification/) |
| Run locally or submit to a provider | [Run on a backend](https://pnnl.github.io/NWQLib/prepared_execution/), [Choose a backend](https://pnnl.github.io/NWQLib/backends/) |
| Save results or continue an interrupted run | [Save, load and reanalyze results](https://pnnl.github.io/NWQLib/saved_evidence/), [Continue an interrupted run](https://pnnl.github.io/NWQLib/run_archives/) |
| Run your own circuit or compare your own method | [Run your own circuit](https://pnnl.github.io/NWQLib/own_circuit/), [Add a method](https://pnnl.github.io/NWQLib/algorithm_protocol/) |
| List methods or use the command line | [Use the command line](https://pnnl.github.io/NWQLib/cli/) |
| Look up a signature | [API reference](https://pnnl.github.io/NWQLib/api/) |
| Check known defects in Qiskit and other dependencies, and how NWQLib handles them | [Dependency issues](https://pnnl.github.io/NWQLib/dependency_issues/) |
| Trace code to its paper, equation and reason | [Code tour](https://pnnl.github.io/NWQLib/CODE_TOUR/#find-the-source-and-reason-for-a-line-of-code), [references](https://pnnl.github.io/NWQLib/references/) |
| Find the bound, resource formula or error budget behind a result, its proof or source, and its code | [Mathematics](https://pnnl.github.io/NWQLib/mathematics/) |
| Maintain NWQLib | [Set up, test and build](https://pnnl.github.io/NWQLib/development/setup/), [Contributing](https://github.com/pnnl/NWQLib/blob/main/CONTRIBUTING.md) |

## Algorithms

| Scientific task | Methods |
| --- | --- |
| Normalized expectation of a finite real Pauli sum | [Expectation](https://pnnl.github.io/NWQLib/algorithms/expectation/) |
| Energy estimates from moments or a chosen subspace | [Chebyshev Lanczos](https://pnnl.github.io/NWQLib/algorithms/lanczos/), [fixed and adaptive GCiM](https://pnnl.github.io/NWQLib/algorithms/gcim/) |
| Phase or energy estimation | [QPE: QCELS, RWPE, SPE and RFE](https://pnnl.github.io/NWQLib/algorithms/qpe/) |
| Time-independent linear dynamics | [LCHS](https://pnnl.github.io/NWQLib/algorithms/lchs/) |
| Linear systems | [QLS: QSVT inverse polynomial (`qsvt_inverse`, the default) and the Dalzell kernel shortcut (`shortcut_native_svp`, `shortcut_dilation`)](https://pnnl.github.io/NWQLib/algorithms/qls/) |
| Box-constrained optimization | [QHD](https://pnnl.github.io/NWQLib/algorithms/qhd/) |
| Optimization over a box with equality or inequality constraints | [QHD augmented Lagrangian](https://pnnl.github.io/NWQLib/algorithms/qhd/#constrained-problems) |

Each method reports the quantity it obtained and any accuracy conditions that remain unresolved. A projected energy, a local statistical interval or a completed simulation does not by itself establish the full requested scientific claim. [Limitations and open work](https://pnnl.github.io/NWQLib/ROADMAP/) lists current limitations. State preparation, block encoding, LCU, QSP/QSVT and evolution subroutines have their own [API reference pages](https://pnnl.github.io/NWQLib/api/).

## Backend support

| Backend | Runs where | Tested against the live service |
| --- | --- | --- |
| [Aer](https://pnnl.github.io/NWQLib/aer/) | Locally | Not applicable |
| [NWQ-Sim](https://pnnl.github.io/NWQLib/nwqsim/) | Locally, with the NWQ-Sim build described in its guide. CPU execution, and continuing a run after Python exits, were tested on macOS and Linux with that build | Not applicable |
| [Slurm](https://pnnl.github.io/NWQLib/slurm/) | NWQ-Sim on your cluster, with explicit site configuration | No. Scheduler and site-configuration handling is tested offline. Site allocation, MPI and GPU execution are not tested |
| [IBM Runtime](https://pnnl.github.io/NWQLib/ibm/) | IBM Quantum service | No. SDK calls and result handling are tested offline. Live accounts, queues and QPUs are not tested |
| [IonQ](https://pnnl.github.io/NWQLib/ionq/) | IonQ service | No. Circuit conversion and result handling are tested offline. QPUs are not tested |
| [Quantinuum Nexus](https://pnnl.github.io/NWQLib/nexus/) | Nexus H2 service | No. Conversion, remote-job handling and results are tested offline. Nexus needs a [pandas dependency exception and has no per-request timeout](https://pnnl.github.io/NWQLib/nexus/#costs-timeout-and-qualification) |

A backend runs a method only when it supports that method's circuits and readout. [Choose a backend](https://pnnl.github.io/NWQLib/backends/) gives the details.

## Citation

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

```bibtex
@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.0},
  doi     = {10.5281/zenodo.23074265},
  url     = {https://github.com/pnnl/NWQLib}
}
```

The [references page](https://pnnl.github.io/NWQLib/references/) 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; see [`LICENSE`](https://github.com/pnnl/NWQLib/blob/main/LICENSE). Information release number PNNL-SA-227989.
