qharm-eigenbridge 0.0.2__tar.gz

qharm_eigenbridge-0.0.2/.clang-format

@@ -0,0 +1,110 @@
+# Copyright 2026 QHARM
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+---
+Language:        Cpp
+# BasedOnStyle:  Mozilla
+AccessModifierOffset: -4
+AlignAfterOpenBracket: Align
+AlignConsecutiveAssignments: true
+AlignConsecutiveDeclarations: false
+AlignEscapedNewlines: Left
+AlignOperands:   true
+AlignTrailingComments: true
+AllowAllParametersOfDeclarationOnNextLine: true
+AllowShortBlocksOnASingleLine: true
+AllowShortCaseLabelsOnASingleLine: true
+AllowShortFunctionsOnASingleLine: All
+AllowShortIfStatementsOnASingleLine: true
+AllowShortLoopsOnASingleLine: true
+AlwaysBreakAfterDefinitionReturnType: false
+AlwaysBreakAfterReturnType: None
+AlwaysBreakBeforeMultilineStrings: false
+AlwaysBreakTemplateDeclarations: true
+BinPackArguments: true
+BinPackParameters: true
+BraceWrapping:
+  AfterClass:      false
+  AfterControlStatement: false
+  AfterEnum:       false
+  AfterFunction:   false
+  AfterNamespace:  false
+  AfterObjCDeclaration: false
+  AfterStruct:     false
+  AfterUnion:      false
+  BeforeCatch:     false
+  BeforeElse:      false
+  IndentBraces:    false
+BreakAfterJavaFieldAnnotations: false
+BreakBeforeBinaryOperators: None
+BreakBeforeBraces: Custom
+BreakBeforeInheritanceComma: false
+BreakBeforeTernaryOperators: false
+BreakConstructorInitializers: AfterColon
+BreakStringLiterals: true
+ColumnLimit:     80
+CommentPragmas:  '^ IWYU pragma:'
+CompactNamespaces: false
+ConstructorInitializerAllOnOneLineOrOnePerLine: true
+ConstructorInitializerIndentWidth: 2
+ContinuationIndentWidth: 2
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+DisableFormat:   false
+ExperimentalAutoDetectBinPacking: false
+FixNamespaceComments: true
+ForEachMacros:   [ foreach, Q_FOREACH, BOOST_FOREACH ]
+IncludeCategories:
+  - Regex:           '^"'
+    Priority:        1
+  - Regex:           '^<'
+    Priority:        2
+IncludeIsMainRegex: '(Test)$'
+IndentCaseLabels: true
+IndentWidth: 4
+IndentWrappedFunctionNames: false
+JavaScriptQuotes: Leave
+JavaScriptWrapImports: true
+KeepEmptyLinesAtTheStartOfBlocks: false
+MacroBlockBegin: ''
+MacroBlockEnd:   ''
+MaxEmptyLinesToKeep: 1
+NamespaceIndentation: None
+ObjCBlockIndentWidth: 4
+ObjCSpaceAfterProperty: true
+ObjCSpaceBeforeProtocolList: false
+PenaltyBreakBeforeFirstCallParameter: 19
+PenaltyBreakComment: 300
+PenaltyBreakFirstLessLess: 120
+PenaltyBreakString: 1000
+PenaltyExcessCharacter: 1000000
+PenaltyReturnTypeOnItsOwnLine: 200
+PointerAlignment: Left
+ReflowComments:  true
+SortIncludes:    true
+SpaceAfterCStyleCast: false
+SpaceAfterTemplateKeyword: false
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeParens: Never
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 1
+SpacesInAngles:  false
+SpacesInCStyleCastParentheses: false
+SpacesInContainerLiterals: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+Standard:        Cpp11
+TabWidth:        8
+UseTab:          Never
+...

qharm_eigenbridge-0.0.2/.github/workflows/merge.yaml

@@ -0,0 +1,25 @@
+name: Merge Workflow
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  tag-commit:
+    uses: NWChemEx/.github/.github/workflows/tag.yaml@master
+    secrets: inherit
+
+  deploy_to_pypi:
+    needs: tag-commit
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - name: Build PyPI Distribution
+        uses: NWChemEx/.github/.github/actions/build_pypi_dist@master
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

qharm_eigenbridge-0.0.2/.github/workflows/pull_request.yaml

@@ -0,0 +1,50 @@
+name: Pull Request Workflow
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  # Build and test Python bindings.
+  test_python:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - name: Install LAPACK and LAPACKE
+        run: sudo apt-get install -y liblapacke-dev
+        shell: bash
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.x"
+      - name: Build and Test
+        run: |
+          pip install .
+          cd tests/unit_tests
+          python -m unittest
+        shell: bash
+
+  test_pypi_deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Build PyPI Distribution
+        uses: NWChemEx/.github/.github/actions/build_pypi_dist@master
+
+  # Run pre-commit hooks
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Source
+        uses: actions/checkout@v5
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.x"
+      - name: Install and Run pre-commit
+        run: |
+          pip install pre-commit
+          pre-commit run --all-files
+        shell: bash

qharm_eigenbridge-0.0.2/.gitignore

@@ -0,0 +1,82 @@
+# Copyright 2026 QHARM
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# These are directories used by IDEs for storing settings
+.idea/
+.vscode/
+.cache/
+
+# These are common build directory names
+build*/
+docs/build
+docs/source/_build
+docs/doxyoutput
+docs/source/api
+*-build-*/
+_build/
+Debug/
+Release/
+
+# Project automation
+.tox/
+
+# Users commonly store their specific CMake settings in a toolchain file
+toolchain.cmake
+
+# Users often install under the root directory
+install/
+
+# Per-project virtualenvs
+*venv*/
+.conda*/
+.python-version
+
+# Python distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# These are extensions commonly used to denote temporary files
+*.tmp
+*.autosave
+*.bak
+*~
+*.py[cod]
+*.so
+*.cfg
+!.isort.cfg
+!setup.cfg
+*.orig
+*.log
+*.pot
+__pycache__/*
+.cache/*
+.*.swp
+*/.ipynb_checkpoints/*
+.DS_Store

qharm_eigenbridge-0.0.2/.licenserc.yaml

@@ -0,0 +1,26 @@
+# Copyright 2026 QHARM
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+header:
+  license:
+    spdx-id: Apache-2.0
+    copyright-owner: QHARM
+
+  paths-ignore:
+    - .github/
+    - LICENSE
+    - build/
+    - venv/
+
+  comment: never

qharm_eigenbridge-0.0.2/.pre-commit-config.yaml

@@ -0,0 +1,68 @@
+# Copyright 2026 QHARM
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: check-added-large-files
+      - id: check-ast
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-xml
+      - id: check-yaml
+      - id: debug-statements
+      - id: end-of-file-fixer
+      - id: requirements-txt-fixer
+      - id: mixed-line-ending
+        args: ["--fix=auto"]
+
+  - repo: https://github.com/psf/black
+    rev: 23.11.0
+    hooks:
+      - id: black
+        language_version: python3
+        args: ["--line-length=79"]
+
+  - repo: https://github.com/pycqa/isort
+    rev: 5.12.0
+    hooks:
+      - id: isort
+        args:
+          [
+            "--profile",
+            "black",
+            "--filter-files",
+            "--multi-line",
+            "3",
+            "--line-length",
+            "79",
+          ]
+
+  - repo: https://github.com/PyCQA/flake8
+    rev: 6.1.0
+    hooks:
+      - id: flake8
+        args: ["--max-line-length=88"]
+
+  - repo: local
+    hooks:
+      - id: license-eye
+        name: license-eye
+        additional_dependencies:
+          - github.com/apache/skywalking-eyes/cmd/license-eye@v0.4.0
+        entry: license-eye header fix --verbosity error
+        language: golang
+        pass_filenames: false

qharm_eigenbridge-0.0.2/LICENSE

@@ -0,0 +1,177 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

qharm_eigenbridge-0.0.2/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: qharm-eigenbridge
+Version: 0.0.2
+Summary: Quantum eigensolver implementation using Qiskit
+Author-email: Jonathan Waldrop <jwaldrop@ameslab.gov>, Mahir Anand <mahiranand@outlook.com>
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pybind11
+Requires-Dist: qiskit
+Requires-Dist: qiskit-algorithms
+Requires-Dist: qiskit-aer
+Requires-Dist: qiskit-ibm-runtime
+Provides-Extra: dev
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+<!--
+  ~ Copyright 2026 QHARM
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~ http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+-->
+
+# EigenBridge
+
+There are two quantum solvers. VQD can return several eigenvalues; QAOA returns only the ground state.
+
+VQD -> `run_vqd_eigensolver(matrix, k)` -> `solve_vqd` -> lowest `k` eigenvalues (`k` defaults to all)
+QAOA -> `run_qaoa_eigensolver(matrix, use_noise=false)` -> `solve_qaoa` -> ground state only
+
+**Uncertainties (`uq_values` / `uq_vectors`)**
+- Noiseless solvers (LAPACK, VQD, noiseless QAOA): `uq_* = 0`
+- Noisy QAOA (`use_noise=true`): at the final circuit, `uq_values[0] = |E_noisy − E_exact|`; Unused slots and `uq_vectors` stay 0
+
+The noisy QAOA unit test checks that `uq_values[0] = |E_noisy − E_exact|` (at the final circuit) and `|λ_noisy − λ_LAPACK|` agree within a factor of 10 (ratio < 10).

qharm_eigenbridge-0.0.2/README.md

@@ -0,0 +1,28 @@
+<!--
+  ~ Copyright 2026 QHARM
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~ http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+-->
+
+# EigenBridge
+
+There are two quantum solvers. VQD can return several eigenvalues; QAOA returns only the ground state.
+
+VQD -> `run_vqd_eigensolver(matrix, k)` -> `solve_vqd` -> lowest `k` eigenvalues (`k` defaults to all)
+QAOA -> `run_qaoa_eigensolver(matrix, use_noise=false)` -> `solve_qaoa` -> ground state only
+
+**Uncertainties (`uq_values` / `uq_vectors`)**
+- Noiseless solvers (LAPACK, VQD, noiseless QAOA): `uq_* = 0`
+- Noisy QAOA (`use_noise=true`): at the final circuit, `uq_values[0] = |E_noisy − E_exact|`; Unused slots and `uq_vectors` stay 0
+
+The noisy QAOA unit test checks that `uq_values[0] = |E_noisy − E_exact|` (at the final circuit) and `|λ_noisy − λ_LAPACK|` agree within a factor of 10 (ratio < 10).

qharm_eigenbridge-0.0.2/pyproject.toml

@@ -0,0 +1,63 @@
+# Copyright 2026 QHARM
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+[build-system]
+requires = ["setuptools>=64", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"
+
+
+[project]
+name = "qharm-eigenbridge"
+authors = [
+    { name = "Jonathan Waldrop", email = "jwaldrop@ameslab.gov" },
+    { name = "Mahir Anand", email = "mahiranand@outlook.com" },
+]
+description = "Quantum eigensolver implementation using Qiskit"
+readme = "README.md"
+requires-python = ">=3.9"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dynamic = ["version"]
+dependencies = [
+    "numpy",
+    "pybind11",
+    "qiskit",
+    "qiskit-algorithms",
+    "qiskit-aer",
+    "qiskit-ibm-runtime",
+]
+
+[project.optional-dependencies]
+dev = ["pre-commit", "pytest"]
+
+[tool.setuptools.packages.find]
+where = ["python"]
+
+[tool.setuptools_scm]
+fallback_version = "0.0.0"
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+addopts = "-ra -q -p no:warnings" # Silencing warnings b/c Qiskit
+testpaths = [
+    "tests",
+]

qharm_eigenbridge-0.0.2/python/eigenbridge/__init__.py

@@ -0,0 +1,18 @@
+# Copyright 2026 QHARM
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .quantum_solvers import (  # noqa: F401
+    run_qaoa_eigensolver,
+    run_vqd_eigensolver,
+)

qharm_eigenbridge-0.0.2/python/eigenbridge/quantum_solvers.py

@@ -0,0 +1,270 @@
+# Copyright 2026 QHARM
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import numpy as np
+from qiskit import QuantumCircuit
+from qiskit.circuit.library import EfficientSU2, QAOAAnsatz
+from qiskit.primitives import StatevectorEstimator
+from qiskit.quantum_info import SparsePauliOp, Statevector
+from qiskit_algorithms import VQD
+from qiskit_algorithms.algorithm_job import AlgorithmJob
+from qiskit_algorithms.minimum_eigensolvers import VQE
+from qiskit_algorithms.optimizers import COBYLA, SLSQP
+from qiskit_algorithms.state_fidelities import (
+    BaseStateFidelity,
+    StateFidelityResult,
+)
+
+
+class _ExactStatevectorFidelity(BaseStateFidelity):
+    def create_fidelity_circuit(self, circuit_1, circuit_2):
+        return circuit_1.copy()
+
+    def _run(
+        self,
+        circuits_1,
+        circuits_2,
+        values_1=None,
+        values_2=None,
+        *,
+        shots=None,
+    ):
+        if isinstance(circuits_1, QuantumCircuit):
+            circuits_1 = [circuits_1]
+        if isinstance(circuits_2, QuantumCircuit):
+            circuits_2 = [circuits_2]
+        values_1 = self._preprocess_values(circuits_1, values_1)
+        values_2 = self._preprocess_values(circuits_2, values_2)
+        # _preprocess_values returns a single empty row when values is None
+        if len(values_1) == 1 and len(circuits_1) > 1:
+            values_1 = list(values_1) * len(circuits_1)
+        if len(values_2) == 1 and len(circuits_2) > 1:
+            values_2 = list(values_2) * len(circuits_2)
+
+        def _call():
+            fidelities = []
+            for circuit_1, circuit_2, val_1, val_2 in zip(
+                circuits_1, circuits_2, values_1, values_2
+            ):
+                bound_1 = (
+                    circuit_1.assign_parameters(val_1) if val_1 else circuit_1
+                )
+                bound_2 = (
+                    circuit_2.assign_parameters(val_2) if val_2 else circuit_2
+                )
+                overlap = Statevector(bound_1).inner(Statevector(bound_2))
+                fidelities.append(float(np.abs(overlap) ** 2))
+            return StateFidelityResult(
+                fidelities=fidelities,
+                raw_fidelities=fidelities,
+                metadata=[{} for _ in fidelities],
+                shots=0,
+            )
+
+        return AlgorithmJob(_call)
+
+
+def _statevector_to_real_eigenvector(circuit, parameters, n):
+    # Turn the VQD circuit into a real unit vector of length n.
+    bound = circuit.assign_parameters(parameters)
+    vec = np.asarray(Statevector(bound).data[:n], dtype=complex)
+    idx = int(np.argmax(np.abs(vec)))
+    peak = vec[idx]
+    if np.abs(peak) > 0:
+        vec = vec * np.conj(peak) / np.abs(peak)
+    vec = np.real(vec)
+    if vec[idx] < 0:
+        vec = -vec
+    norm = np.linalg.norm(vec)
+    if norm > 0:
+        vec = vec / norm
+    return vec
+
+
+def _matrix_to_observable(flat_matrix, n):
+    # Reshape into an n x n NumPy array and pad to the next power of two.
+    mat = np.array(flat_matrix, dtype=float).reshape((n, n))
+    next_pow2 = 1 << (n - 1).bit_length()
+    if next_pow2 != n:
+        padded_mat = np.zeros((next_pow2, next_pow2))
+        padded_mat[:n, :n] = mat
+        penalty = 10.0 * max(1.0, float(np.max(np.abs(mat))))
+        for i in range(n, next_pow2):
+            padded_mat[i, i] = penalty
+        mat = padded_mat
+    return SparsePauliOp.from_operator(mat), next_pow2
+
+
+def _make_estimator(use_noise):
+    if not use_noise:
+        return StatevectorEstimator(), None
+    try:
+        from qiskit.transpiler.preset_passmanagers import (
+            generate_preset_pass_manager,
+        )
+        from qiskit_aer import AerSimulator
+        from qiskit_aer.noise import NoiseModel
+        from qiskit_aer.primitives import EstimatorV2 as AerEstimatorV2
+        from qiskit_ibm_runtime.fake_provider import FakeManilaV2
+    except ImportError as exc:
+        raise ImportError(
+            "Noisy QAOA requires qiskit-aer and qiskit-ibm-runtime. "
+            "Install with: pip install qiskit-aer qiskit-ibm-runtime"
+        ) from exc
+
+    fake_backend = FakeManilaV2()
+    noise_model = NoiseModel.from_backend(fake_backend, warnings=False)
+    aer_simulator = AerSimulator(noise_model=noise_model)
+    pass_manager = generate_preset_pass_manager(
+        optimization_level=1, backend=aer_simulator
+    )
+
+    estimator = AerEstimatorV2(
+        options={"backend_options": {"noise_model": noise_model}}
+    )
+    return estimator, pass_manager
+
+
+def _expect_energy(estimator, circuit, observable, parameters):
+    op = observable
+    if getattr(circuit, "layout", None) is not None:
+        op = observable.apply_layout(circuit.layout)
+    evs = np.asarray(
+        estimator.run([(circuit, op, parameters)]).result()[0].data.evs,
+        dtype=float,
+    ).reshape(-1)
+    return float(np.real(evs[0]))
+
+
+def _energy_diff_uncertainty(circuit, parameters, observable, noisy_estimator):
+    exact_energy = _expect_energy(
+        StatevectorEstimator(), circuit, observable, parameters
+    )
+    noisy_energy = _expect_energy(
+        noisy_estimator, circuit, observable, parameters
+    )
+    # Predicted noise = |E_noisy - E_exact| on the final circuit
+    return abs(noisy_energy - exact_energy)
+
+
+def run_vqd_eigensolver(flat_matrix, n, k=None):
+    """
+    Takes a flat matrix of size n*n, and returns the lowest k eigenvalues
+    and matching eigenvectors using VQD.
+    """
+    if k is None:
+        k = n
+    if k < 1 or k > n:
+        raise ValueError(f"k must satisfy 1 <= k <= n, got k={k}, n={n}")
+
+    observable, next_pow2 = _matrix_to_observable(flat_matrix, n)
+    num_qubits = int(np.log2(next_pow2))
+
+    ansatz = EfficientSU2(num_qubits, reps=1, entanglement="linear")
+    optimizer = SLSQP(maxiter=1000, ftol=1e-9)
+    estimator = StatevectorEstimator()
+    fidelity = _ExactStatevectorFidelity()
+
+    # Overlap weights on the scale of the original matrix, not the padding.
+    beta = 10.0 * max(
+        1.0, float(np.max(np.abs(np.array(flat_matrix, dtype=float))))
+    )
+    betas = np.full(k, beta)
+    rng = np.random.default_rng(0)
+    if k == 1:
+        initial_points = np.zeros(ansatz.num_parameters)
+    else:
+        initial_points = [np.zeros(ansatz.num_parameters)]
+        for _ in range(k - 1):
+            initial_points.append(
+                rng.uniform(-np.pi, np.pi, ansatz.num_parameters)
+            )
+
+    vqd = VQD(estimator, fidelity, ansatz, optimizer, k=k, betas=betas)
+    vqd.initial_point = initial_points
+
+    result = vqd.compute_eigenvalues(observable)
+
+    eigenvalues = [float(np.real(e)) for e in result.eigenvalues]
+    eigenvectors = np.zeros((n, n), dtype=float)
+    for i in range(k):
+        eigenvectors[:, i] = _statevector_to_real_eigenvector(
+            result.optimal_circuits[i], result.optimal_points[i], n
+        )
+    uq_values = [0.0] * len(eigenvalues)
+    uq_vectors = [0.0] * (n * n)
+
+    return eigenvalues, eigenvectors.ravel().tolist(), uq_values, uq_vectors
+
+
+def run_qaoa_eigensolver(flat_matrix, n, use_noise=False, reps=3):
+    """
+    Takes a flat matrix of size n*n, and returns the ground eigenvalue,
+    and matching eigenvector using QAOA.
+    """
+    observable, _ = _matrix_to_observable(flat_matrix, n)
+    ansatz = QAOAAnsatz(observable, reps=reps)
+    estimator, pass_manager = _make_estimator(use_noise)
+    if use_noise:
+        optimizer = COBYLA(maxiter=50)
+        vqe = VQE(estimator, ansatz, optimizer, transpiler=pass_manager)
+    else:
+        optimizer = SLSQP(maxiter=1000, ftol=1e-9)
+        vqe = VQE(estimator, ansatz, optimizer)
+    rng = np.random.default_rng(2)
+    vqe.initial_point = rng.uniform(0, np.pi, ansatz.num_parameters)
+
+    result = vqe.compute_minimum_eigenvalue(observable)
+
+    eigenvalues = [float(np.real(result.eigenvalue))]
+    eigenvectors = np.zeros((n, n), dtype=float)
+    eigenvectors[:, 0] = _statevector_to_real_eigenvector(
+        result.optimal_circuit, result.optimal_point, n
+    )
+
+    uq_values = [0.0] * len(eigenvalues)
+    uq_vectors = [0.0] * (n * n)
+    if use_noise:
+        uq_values[0] = _energy_diff_uncertainty(
+            result.optimal_circuit, result.optimal_point, observable, estimator
+        )
+
+    return eigenvalues, eigenvectors.ravel().tolist(), uq_values, uq_vectors
+
+
+# Quick Test
+if __name__ == "__main__":
+    # The same 3x3 matrix from the C++ test file
+    test_matrix = [3.0, 5.0, 2.0, 5.0, 1.0, 3.0, 2.0, 3.0, 2.0]
+    values, vectors = run_vqd_eigensolver(test_matrix, 3)
+    print(f"VQD Eigenvalues: {values}")
+    print(f"VQD Eigenvectors: {vectors}")
+    qaoa_values, qaoa_vectors, qaoa_uq_v, qaoa_uq_vec = run_qaoa_eigensolver(
+        test_matrix, 3
+    )
+    print(f"QAOA Eigenvalue: {qaoa_values}")
+    print(f"QAOA Eigenvector: {qaoa_vectors}")
+    print(f"QAOA uq_values: {qaoa_uq_v}")
+    try:
+        (
+            qaoa_noisy_values,
+            qaoa_noisy_vectors,
+            noisy_uq_v,
+            noisy_uq_vec,
+        ) = run_qaoa_eigensolver(test_matrix, 3, use_noise=True)
+        print(f"QAOA Eigenvalue (noise): {qaoa_noisy_values}")
+        print(f"QAOA Eigenvector (noise): {qaoa_noisy_vectors}")
+        print(f"QAOA uq_values (noise): {noisy_uq_v}")
+    except ImportError as exc:
+        print(f"Skipping noisy QAOA demo: {exc}")

qharm_eigenbridge-0.0.2/python/qharm_eigenbridge.egg-info/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: qharm-eigenbridge
+Version: 0.0.2
+Summary: Quantum eigensolver implementation using Qiskit
+Author-email: Jonathan Waldrop <jwaldrop@ameslab.gov>, Mahir Anand <mahiranand@outlook.com>
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: pybind11
+Requires-Dist: qiskit
+Requires-Dist: qiskit-algorithms
+Requires-Dist: qiskit-aer
+Requires-Dist: qiskit-ibm-runtime
+Provides-Extra: dev
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+<!--
+  ~ Copyright 2026 QHARM
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~ http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+-->
+
+# EigenBridge
+
+There are two quantum solvers. VQD can return several eigenvalues; QAOA returns only the ground state.
+
+VQD -> `run_vqd_eigensolver(matrix, k)` -> `solve_vqd` -> lowest `k` eigenvalues (`k` defaults to all)
+QAOA -> `run_qaoa_eigensolver(matrix, use_noise=false)` -> `solve_qaoa` -> ground state only
+
+**Uncertainties (`uq_values` / `uq_vectors`)**
+- Noiseless solvers (LAPACK, VQD, noiseless QAOA): `uq_* = 0`
+- Noisy QAOA (`use_noise=true`): at the final circuit, `uq_values[0] = |E_noisy − E_exact|`; Unused slots and `uq_vectors` stay 0
+
+The noisy QAOA unit test checks that `uq_values[0] = |E_noisy − E_exact|` (at the final circuit) and `|λ_noisy − λ_LAPACK|` agree within a factor of 10 (ratio < 10).

qharm_eigenbridge-0.0.2/python/qharm_eigenbridge.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+.clang-format
+.gitignore
+.licenserc.yaml
+.pre-commit-config.yaml
+LICENSE
+README.md
+pyproject.toml
+.github/workflows/merge.yaml
+.github/workflows/pull_request.yaml
+python/eigenbridge/__init__.py
+python/eigenbridge/quantum_solvers.py
+python/qharm_eigenbridge.egg-info/PKG-INFO
+python/qharm_eigenbridge.egg-info/SOURCES.txt
+python/qharm_eigenbridge.egg-info/dependency_links.txt
+python/qharm_eigenbridge.egg-info/requires.txt
+python/qharm_eigenbridge.egg-info/scm_file_list.json
+python/qharm_eigenbridge.egg-info/scm_version.json
+python/qharm_eigenbridge.egg-info/top_level.txt
+tests/unit_tests/test_eigensolvers.py

qharm_eigenbridge-0.0.2/python/qharm_eigenbridge.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

qharm_eigenbridge-0.0.2/python/qharm_eigenbridge.egg-info/requires.txt

@@ -0,0 +1,10 @@
+numpy
+pybind11
+qiskit
+qiskit-algorithms
+qiskit-aer
+qiskit-ibm-runtime
+
+[dev]
+pre-commit
+pytest

qharm_eigenbridge-0.0.2/python/qharm_eigenbridge.egg-info/scm_file_list.json

@@ -0,0 +1,16 @@
+{
+  "files": [
+    ".clang-format",
+    ".github/workflows/merge.yaml",
+    ".github/workflows/pull_request.yaml",
+    ".gitignore",
+    ".licenserc.yaml",
+    ".pre-commit-config.yaml",
+    "LICENSE",
+    "README.md",
+    "pyproject.toml",
+    "python/eigenbridge/__init__.py",
+    "python/eigenbridge/quantum_solvers.py",
+    "tests/unit_tests/test_eigensolvers.py"
+  ]
+}

qharm_eigenbridge-0.0.2/python/qharm_eigenbridge.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.0.2",
+  "distance": 0,
+  "node": "g4e9a0a279e66d7ca617ba5c9e3270f3580a2e3f0",
+  "dirty": false,
+  "branch": "main",
+  "node_date": "2026-09-01"
+}

qharm_eigenbridge-0.0.2/python/qharm_eigenbridge.egg-info/top_level.txt

@@ -0,0 +1 @@
+eigenbridge

qharm_eigenbridge-0.0.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

qharm_eigenbridge-0.0.2/tests/unit_tests/test_eigensolvers.py

@@ -0,0 +1,82 @@
+# Copyright 2026 QHARM
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import unittest
+
+import eigenbridge
+
+
+class TestEigensolvers(unittest.TestCase):
+    def setUp(self):
+        # Define a 3x3 matrix
+        self.flat_matrix = [3.0, 5.0, 2.0, 5.0, 1.0, 3.0, 2.0, 3.0, 2.0]
+        # Correct results
+        self.correct_eigenvalues = [
+            -3.3610452994996525,
+            0.5038738768058354,
+            8.8571714226938152,
+        ]
+        self.correct_eigenvectors = [
+            -0.5518254419285664,
+            -0.5057445690691208,
+            -0.6631071651682192,
+            0.7984036023978691,
+            -0.0906811731252565,
+            -0.5952550818924042,
+            -0.2409156892326610,
+            0.8579040480716453,
+            -0.4538284642723896,
+        ]
+
+    def _check_results(
+        self,
+        results,
+        val_places=14,
+        vec_places=14,
+        uq_val=1e-16,
+        uq_vec=1e-16,
+    ):
+        # Check the results
+        eigenvalues, eigenvectors, uq_values, uq_vectors = results
+        for i in zip(eigenvalues, self.correct_eigenvalues):
+            self.assertAlmostEqual(i[0], i[1], places=val_places)
+        for i in zip(eigenvectors, self.correct_eigenvectors):
+            self.assertAlmostEqual(abs(i[0]), abs(i[1]), places=vec_places)
+        for i in uq_values:
+            self.assertEqual(i, uq_val)
+        for i in uq_vectors:
+            self.assertEqual(i, uq_vec)
+
+    def test_vqd_eigensolver(self):
+        results = eigenbridge.run_vqd_eigensolver(self.flat_matrix, n=3)
+        self._check_results(
+            results, val_places=8, vec_places=4, uq_val=0.0, uq_vec=0.0
+        )
+
+    def test_qaoa_eigensolver(self):
+        # Adjust the correct eigenvalues and eigenvectors for QAOA's output
+        # The QAOA solver will not return all eigenvalues/eigenvectors, so we
+        # zero out the ones that are not expected to be returned.
+        for i in range(len(self.correct_eigenvalues)):
+            if i % 3 != 0:
+                self.correct_eigenvalues[i] = 0.0
+        for i in range(len(self.correct_eigenvectors)):
+            if i % 3 != 0:
+                self.correct_eigenvectors[i] = 0.0
+        results = eigenbridge.run_qaoa_eigensolver(
+            self.flat_matrix, n=3, use_noise=False
+        )
+        self._check_results(
+            results, val_places=8, vec_places=4, uq_val=0.0, uq_vec=0.0
+        )