nwqlib 1.0.0__tar.gz

nwqlib-1.0.0/.python-version

@@ -0,0 +1 @@
+3.12.14

nwqlib-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,13 @@
+# Contributing
+
+NWQLib provides quantum algorithm workflows with explicitly selected native SDK extras. Before changing algorithm behavior, read [docs/FRAMEWORK.md](docs/FRAMEWORK.md) for the package contract, execution modes, backend capability policy, reporting standards, and testing expectations. The package root lazily exposes scientist and finite-search operations; import additional public classes and functions from their owning subpackage. Keep changes scoped to one focused capability or fix. Avoid new dependencies unless the framework requires them, and record user-facing behavior through typed records, validation results, reports, and focused tests. Before submitting changes, run the checks in [docs/MAINTENANCE.md](docs/MAINTENANCE.md). A Method that submits your own circuit and returns its counts needs a `descriptor` and two hooks, `plan` and `analyze`, shown in [docs/own_circuit.md](docs/own_circuit.md).
+
+## Environment Lock
+
+`docs/ENVIRONMENT_LOCK.txt` records the interpreter version and exact package versions used for validation. When resuming work, verify the selected interpreter, imported source location and dependency versions before using their results as evidence. Resumption does not automatically recreate or change an environment. Follow [docs/MAINTENANCE.md](docs/MAINTENANCE.md) for the selected environment and checks appropriate to an authorized dependency change.
+
+Public dataclass docstrings use an `Args:` or `Attributes:` section that names every field exactly once. Literal-valued fields list their accepted spellings. Scientific quantities state non-obvious units, normalization, and shape.
+
+Example notebooks are generated from their percent-format sources in `examples/generators/`. Edit the source, regenerate the notebook, and run the freshness check rather than maintaining two independent copies of example logic.
+
+Generated figures identify their reproducible input or are marked as illustrative. Captions state whether plotted resources describe a full algorithm circuit, an oracle, or a subroutine, and synthesis comparisons name the method, state family, seed, and approximation parameters. Mathematical quantities must satisfy their actual domains before evidence is assessed. A justified roundoff adjustment requires an explicit scale-aware policy, retention of the raw value and disclosure of the adjustment. Signed statistical estimators retain their distinct meaning; formatting must not silently turn them into bounded physical quantities. See [Mathematical Definitions Before Evidence](docs/FRAMEWORK.md#mathematical-definitions-before-evidence).

nwqlib-1.0.0/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, Battelle Memorial Institute
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

nwqlib-1.0.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include .python-version mkdocs.yml CONTRIBUTING.md
+recursive-include docs *.md *.txt *.py *.json
+recursive-include examples *.md *.py *.ipynb
+recursive-include tests *.py *.json

nwqlib-1.0.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: nwqlib
+Version: 1.0.0
+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
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23074265.svg)](https://doi.org/10.5281/zenodo.23074265)
+
+**Documentation: <https://pnnl.github.io/NWQLib/>**
+
+NWQLib applies quantum algorithms to scientific problems. A workflow connects your inputs and requested output to a selected method, execution and a report of the result, evidence and resources. Native circuit execution uses Qiskit and an explicitly selected backend.
+
+IR# PNNL-SA-227989
+
+## Start here
+
+**The [example notebooks](examples/) solve complete scientific problems from input to result, error and circuit cost, and the [examples guide](docs/examples.md) points you to the one that matches your problem. The [mathematics page](docs/mathematics.md) states the bounds, resource laws and error budgets that NWQLib uses, each with its proof or source and the code that implements it.**
+
+From a source checkout, install the package with the local Aer executor:
+
+```bash
+python -m pip install -e ".[aer]"
+```
+
+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)
+```
+
+The default returns the physical solution approximation using nine total qubits. The [quickstart](docs/quickstart.md) compares it with an independent reference and shows how to change the approximation. The base install, `python -m pip install -e .`, supports metadata, admitted inputs, default LCHS planning and supported classical methods. Other planning paths follow their Method's input/conversion requirements; native preparation and execution require the selected backend extra. Method guides describe these boundaries.
+
+The notebooks in `examples/` apply NWQLib to molecular ground-state energy, a linear system, linear dynamics and optimization, and one estimates the resources of a linear system, heat flow, two spin chains, a GCiM trial basis and a QHD optimization step at up to 100 qubits. The [examples guide](docs/examples.md) describes the work each notebook performs.
+
+## Choose a task
+
+| Task | Read |
+| --- | --- |
+| Learn the Python workflow | [Quickstart](docs/quickstart.md), [examples](docs/examples.md) |
+| Compare NWQLib with other quantum packages | [Why NWQLib](docs/why_nwqlib.md) |
+| Discover methods or use the command line | [CLI guide](docs/cli.md) |
+| Compare methods and inspect results | [Scientist workflow](docs/scientist.md) |
+| Supply operators and states | [Input access](docs/inputs.md) |
+| Estimate resources and assess a device | [Resource estimates](docs/resources.md), [device profiles](docs/profiles.md) |
+| Run locally or submit to a provider | [Prepared execution](docs/prepared_execution.md), [backends](docs/backends.md) |
+| Save results or continue a workflow | [Saved evidence](docs/saved_evidence.md), [run archives](docs/run_archives.md) |
+| Look up a signature | [API reference](docs/api/index.md) |
+| Check known defects in Qiskit and other dependencies, and how NWQLib handles them | [Dependency issues](docs/dependency_issues.md) |
+| Extend or maintain NWQLib | [Run your own circuit](docs/own_circuit.md), [Contributing](CONTRIBUTING.md), [code tour](docs/CODE_TOUR.md), [maintenance](docs/MAINTENANCE.md) |
+| Trace code to its paper, equation and reason | [Code tour](docs/CODE_TOUR.md#find-the-source-and-reason-for-a-line-of-code), [references](docs/references.md) |
+| Find the bound, resource law or error budget behind a result, its proof or source, and its code | [Mathematics](docs/mathematics.md) |
+
+## Algorithms
+
+| Scientific task | Methods |
+| --- | --- |
+| Normalized expectation of a finite real Pauli sum | [Expectation](docs/algorithms/expectation.md) |
+| Energy estimates from moments or a selected subspace | [Chebyshev Lanczos](docs/algorithms/lanczos.md), [fixed and adaptive GCiM](docs/algorithms/gcim.md) |
+| Phase or energy estimation | [QPE: QCELS, RWPE, SPE and RFE](docs/algorithms/qpe.md) |
+| Time-independent linear dynamics | [LCHS](docs/algorithms/lchs.md) |
+| Linear systems | [QLS: QSVT inverse polynomial (`qsvt_inverse`, the default) and the Dalzell kernel shortcut (`shortcut_native_svp`, `shortcut_dilation`)](docs/algorithms/qls.md) |
+| Box-constrained optimization | [QHD](docs/algorithms/qhd.md) |
+| Optimization over a box with equality or inequality constraints | [QHD augmented Lagrangian](docs/algorithms/qhd.md#constrained-problems) |
+
+Methods report the quantity actually obtained and any unresolved accuracy conditions. A projected energy, local statistical interval or completed simulation does not by itself establish the full requested scientific claim. The [roadmap](docs/ROADMAP.md) records current limitations and open work. Reusable state preparation, block encoding, LCU, QSP/QSVT and evolution primitives have their own [API references](docs/api/index.md).
+
+## Backend support
+
+Aer supports local execution. NWQ-Sim CPU execution and process-exit continuation have been exercised on macOS and Linux with the qualified build described in the [backend guide](docs/backends.md). IBM Runtime, IonQ and Nexus have offline SDK and injected-result qualification. Live provider accounts, queues and QPUs remain unqualified. Slurm and GPU/site support have their documented offline qualification boundaries.
+
+The [Nexus guide](docs/nexus.md#costs-timeout-and-qualification) documents its pandas dependency exception and missing per-request timeout. See [Slurm](docs/slurm.md) for explicit site configuration. Each method/backend/readout combination must satisfy its own capability checks.
+
+## 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.
+
+[Algorithm and subroutine references](docs/references.md).
+
+NWQLib is released under the BSD 2-Clause License; see `LICENSE`.

nwqlib-1.0.0/README.md

@@ -0,0 +1,104 @@
+# NWQLib: Northwest Quantum Library
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23074265.svg)](https://doi.org/10.5281/zenodo.23074265)
+
+**Documentation: <https://pnnl.github.io/NWQLib/>**
+
+NWQLib applies quantum algorithms to scientific problems. A workflow connects your inputs and requested output to a selected method, execution and a report of the result, evidence and resources. Native circuit execution uses Qiskit and an explicitly selected backend.
+
+IR# PNNL-SA-227989
+
+## Start here
+
+**The [example notebooks](examples/) solve complete scientific problems from input to result, error and circuit cost, and the [examples guide](docs/examples.md) points you to the one that matches your problem. The [mathematics page](docs/mathematics.md) states the bounds, resource laws and error budgets that NWQLib uses, each with its proof or source and the code that implements it.**
+
+From a source checkout, install the package with the local Aer executor:
+
+```bash
+python -m pip install -e ".[aer]"
+```
+
+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)
+```
+
+The default returns the physical solution approximation using nine total qubits. The [quickstart](docs/quickstart.md) compares it with an independent reference and shows how to change the approximation. The base install, `python -m pip install -e .`, supports metadata, admitted inputs, default LCHS planning and supported classical methods. Other planning paths follow their Method's input/conversion requirements; native preparation and execution require the selected backend extra. Method guides describe these boundaries.
+
+The notebooks in `examples/` apply NWQLib to molecular ground-state energy, a linear system, linear dynamics and optimization, and one estimates the resources of a linear system, heat flow, two spin chains, a GCiM trial basis and a QHD optimization step at up to 100 qubits. The [examples guide](docs/examples.md) describes the work each notebook performs.
+
+## Choose a task
+
+| Task | Read |
+| --- | --- |
+| Learn the Python workflow | [Quickstart](docs/quickstart.md), [examples](docs/examples.md) |
+| Compare NWQLib with other quantum packages | [Why NWQLib](docs/why_nwqlib.md) |
+| Discover methods or use the command line | [CLI guide](docs/cli.md) |
+| Compare methods and inspect results | [Scientist workflow](docs/scientist.md) |
+| Supply operators and states | [Input access](docs/inputs.md) |
+| Estimate resources and assess a device | [Resource estimates](docs/resources.md), [device profiles](docs/profiles.md) |
+| Run locally or submit to a provider | [Prepared execution](docs/prepared_execution.md), [backends](docs/backends.md) |
+| Save results or continue a workflow | [Saved evidence](docs/saved_evidence.md), [run archives](docs/run_archives.md) |
+| Look up a signature | [API reference](docs/api/index.md) |
+| Check known defects in Qiskit and other dependencies, and how NWQLib handles them | [Dependency issues](docs/dependency_issues.md) |
+| Extend or maintain NWQLib | [Run your own circuit](docs/own_circuit.md), [Contributing](CONTRIBUTING.md), [code tour](docs/CODE_TOUR.md), [maintenance](docs/MAINTENANCE.md) |
+| Trace code to its paper, equation and reason | [Code tour](docs/CODE_TOUR.md#find-the-source-and-reason-for-a-line-of-code), [references](docs/references.md) |
+| Find the bound, resource law or error budget behind a result, its proof or source, and its code | [Mathematics](docs/mathematics.md) |
+
+## Algorithms
+
+| Scientific task | Methods |
+| --- | --- |
+| Normalized expectation of a finite real Pauli sum | [Expectation](docs/algorithms/expectation.md) |
+| Energy estimates from moments or a selected subspace | [Chebyshev Lanczos](docs/algorithms/lanczos.md), [fixed and adaptive GCiM](docs/algorithms/gcim.md) |
+| Phase or energy estimation | [QPE: QCELS, RWPE, SPE and RFE](docs/algorithms/qpe.md) |
+| Time-independent linear dynamics | [LCHS](docs/algorithms/lchs.md) |
+| Linear systems | [QLS: QSVT inverse polynomial (`qsvt_inverse`, the default) and the Dalzell kernel shortcut (`shortcut_native_svp`, `shortcut_dilation`)](docs/algorithms/qls.md) |
+| Box-constrained optimization | [QHD](docs/algorithms/qhd.md) |
+| Optimization over a box with equality or inequality constraints | [QHD augmented Lagrangian](docs/algorithms/qhd.md#constrained-problems) |
+
+Methods report the quantity actually obtained and any unresolved accuracy conditions. A projected energy, local statistical interval or completed simulation does not by itself establish the full requested scientific claim. The [roadmap](docs/ROADMAP.md) records current limitations and open work. Reusable state preparation, block encoding, LCU, QSP/QSVT and evolution primitives have their own [API references](docs/api/index.md).
+
+## Backend support
+
+Aer supports local execution. NWQ-Sim CPU execution and process-exit continuation have been exercised on macOS and Linux with the qualified build described in the [backend guide](docs/backends.md). IBM Runtime, IonQ and Nexus have offline SDK and injected-result qualification. Live provider accounts, queues and QPUs remain unqualified. Slurm and GPU/site support have their documented offline qualification boundaries.
+
+The [Nexus guide](docs/nexus.md#costs-timeout-and-qualification) documents its pandas dependency exception and missing per-request timeout. See [Slurm](docs/slurm.md) for explicit site configuration. Each method/backend/readout combination must satisfy its own capability checks.
+
+## 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.
+
+[Algorithm and subroutine references](docs/references.md).
+
+NWQLib is released under the BSD 2-Clause License; see `LICENSE`.