qharm-eigenbridge 0.0.2__tar.gz → 0.0.3__tar.gz

qharm_eigenbridge-0.0.3/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: qharm-eigenbridge
+Version: 0.0.3
+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, use_noise=false)` -> lowest `k` eigenvalues (`k` defaults to all)
+QAOA -> `run_qaoa_eigensolver(matrix, use_noise=false)` -> ground state only
+
+**Uncertainties (`uq_values` / `uq_vectors`)**
+- For every VQD/QAOA path (noiseless and noisy), at each final optimized circuit/state,
+  `uq_values[i] = sqrt(max(0, ⟨H²⟩ − ⟨H⟩²))`, where ⟨H⟩ is the reported eigenvalue and ⟨H²⟩
+  comes from the same estimator on `H @ H` at the same parameters.
+  This is the standard deviation of a single measurement of H in the prepared state
+  (intrinsic quantum / variational residual variance).
+  Exact eigenstates give σ ≈ 0; approximate ansatz states give nonzero σ even without noise.
+- `uq_vectors` uses the same layout as the returned eigenvectors (column `i` = mode `i`).
+  For each physical basis index `j`,
+  `uq_vectors[j, i] = sqrt(p_j (1 − p_j))` where `p_j = ⟨|j⟩⟨j|⟩` is evaluated with the
+  **same estimator / circuit / parameters** as the energy (FakeManila when `use_noise=true`).
+  This is the std of a single-shot computational-basis occupation measurement for component `j`.
+  Caveat: it can be > 0 even for an exact delocalized eigenstate (unlike σ_H, which is 0 for
+  exact energy eigenstates). It is **not** “distance to the classical eigenvector.”
+  Unused eigenvector columns stay 0. Reported eigenvectors still come from the ideal
+  statevector of the optimized circuit; only the UQ uses the estimator/noise path.
+- Non–power-of-2 dimensions pad to the next power of two and place
+  `penalty = max(1.0, Gershgorin row-sum bound)` on unused diagonal entries so pad
+  eigenvalues stay outside the original spectrum while avoiding the old 10× entry-scale
+  inflation of ⟨H²⟩ on small problems.
+- Noisy VQD keeps exact statevector overlaps; only the energy / projector estimator uses
+  FakeManila noise (demo). Expect worse eigenvalues, especially for higher states.
+
+Unit tests check that reported `uq_values` / filled `uq_vectors` entries are finite and
+nonnegative (filled columns not identically zero on the demo matrix), and that on the
+demo 3×3 matrix the ground-state interval `[⟨H⟩−σ, ⟨H⟩+σ]` contains the classical ground
+eigenvalue for noisy paths. They do not require noisy eigenvalues to match the classical answer.

qharm_eigenbridge-0.0.3/README.md

@@ -0,0 +1,50 @@
+<!--
+  ~ 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, use_noise=false)` -> lowest `k` eigenvalues (`k` defaults to all)
+QAOA -> `run_qaoa_eigensolver(matrix, use_noise=false)` -> ground state only
+
+**Uncertainties (`uq_values` / `uq_vectors`)**
+- For every VQD/QAOA path (noiseless and noisy), at each final optimized circuit/state,
+  `uq_values[i] = sqrt(max(0, ⟨H²⟩ − ⟨H⟩²))`, where ⟨H⟩ is the reported eigenvalue and ⟨H²⟩
+  comes from the same estimator on `H @ H` at the same parameters.
+  This is the standard deviation of a single measurement of H in the prepared state
+  (intrinsic quantum / variational residual variance).
+  Exact eigenstates give σ ≈ 0; approximate ansatz states give nonzero σ even without noise.
+- `uq_vectors` uses the same layout as the returned eigenvectors (column `i` = mode `i`).
+  For each physical basis index `j`,
+  `uq_vectors[j, i] = sqrt(p_j (1 − p_j))` where `p_j = ⟨|j⟩⟨j|⟩` is evaluated with the
+  **same estimator / circuit / parameters** as the energy (FakeManila when `use_noise=true`).
+  This is the std of a single-shot computational-basis occupation measurement for component `j`.
+  Caveat: it can be > 0 even for an exact delocalized eigenstate (unlike σ_H, which is 0 for
+  exact energy eigenstates). It is **not** “distance to the classical eigenvector.”
+  Unused eigenvector columns stay 0. Reported eigenvectors still come from the ideal
+  statevector of the optimized circuit; only the UQ uses the estimator/noise path.
+- Non–power-of-2 dimensions pad to the next power of two and place
+  `penalty = max(1.0, Gershgorin row-sum bound)` on unused diagonal entries so pad
+  eigenvalues stay outside the original spectrum while avoiding the old 10× entry-scale
+  inflation of ⟨H²⟩ on small problems.
+- Noisy VQD keeps exact statevector overlaps; only the energy / projector estimator uses
+  FakeManila noise (demo). Expect worse eigenvalues, especially for higher states.
+
+Unit tests check that reported `uq_values` / filled `uq_vectors` entries are finite and
+nonnegative (filled columns not identically zero on the demo matrix), and that on the
+demo 3×3 matrix the ground-state interval `[⟨H⟩−σ, ⟨H⟩+σ]` contains the classical ground
+eigenvalue for noisy paths. They do not require noisy eigenvalues to match the classical answer.

{qharm_eigenbridge-0.0.2 → qharm_eigenbridge-0.0.3}/python/eigenbridge/quantum_solvers.py

@@ -99,7 +99,9 @@ def _matrix_to_observable(flat_matrix, n):
     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))))
+        # Pad unused diagonal with Gershgorin bound so fake eigenvalues stay outside.
+        gershgorin = float(np.max(np.sum(np.abs(mat), axis=1)))
+        penalty = max(1.0, gershgorin)
         for i in range(n, next_pow2):
             padded_mat[i, i] = penalty
         mat = padded_mat
@@ -119,12 +121,12 @@ def _make_estimator(use_noise):
         from qiskit_ibm_runtime.fake_provider import FakeManilaV2
     except ImportError as exc:
         raise ImportError(
-            "Noisy QAOA requires qiskit-aer and qiskit-ibm-runtime. "
+            "Noisy solvers require 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)
+    noise_model = NoiseModel.from_backend(fake_backend)
     aer_simulator = AerSimulator(noise_model=noise_model)
     pass_manager = generate_preset_pass_manager(
         optimization_level=1, backend=aer_simulator
@@ -147,21 +149,36 @@ def _expect_energy(estimator, circuit, observable, parameters):
     return float(np.real(evs[0]))
 
 
-def _energy_diff_uncertainty(circuit, parameters, observable, noisy_estimator):
-    exact_energy = _expect_energy(
-        StatevectorEstimator(), circuit, observable, parameters
+def _quantum_variance_std(estimator, circuit, observable, parameters, h_mean):
+    # Quantum std of H in this state: sqrt(max(0, <H^2> - <H>^2)).
+    h2 = _expect_energy(
+        estimator, circuit, observable @ 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)
+    return float(np.sqrt(max(0.0, h2 - h_mean**2)))
+
+
+def _occupation_stds(estimator, circuit, parameters, n, next_pow2):
+    # Occupation std per component: sqrt(p (1 - p)) for basis outcome probability p.
+    stds = np.zeros(n, dtype=float)
+    for j in range(n):
+        proj = np.zeros((next_pow2, next_pow2), dtype=float)
+        proj[j, j] = 1.0
+        p_j = _expect_energy(
+            estimator, circuit, SparsePauliOp.from_operator(proj), parameters
+        )
+        p_j = min(1.0, max(0.0, p_j))
+        stds[j] = float(np.sqrt(max(0.0, p_j - p_j * p_j)))
+    return stds
 
 
-def run_vqd_eigensolver(flat_matrix, n, k=None):
+def run_vqd_eigensolver(flat_matrix, n, k=None, use_noise=False):
     """
     Takes a flat matrix of size n*n, and returns the lowest k eigenvalues
     and matching eigenvectors using VQD.
+
+    With use_noise=True, only the energy estimator is noisy (FakeManila);
+    VQD still recognizes distinct states perfectly.
+    Expect worse eigenvalues, especially for k > 1.
     """
     if k is None:
         k = n
@@ -172,9 +189,14 @@ def run_vqd_eigensolver(flat_matrix, n, k=None):
     num_qubits = int(np.log2(next_pow2))
 
     ansatz = EfficientSU2(num_qubits, reps=1, entanglement="linear")
-    optimizer = SLSQP(maxiter=1000, ftol=1e-9)
-    estimator = StatevectorEstimator()
+    estimator, pass_manager = _make_estimator(use_noise)
+    # Keep exact fidelity even under noise: overlaps stay exact; only energy
+    # is FakeManila-noisy (same demo style as QAOA).
     fidelity = _ExactStatevectorFidelity()
+    if use_noise:
+        optimizer = COBYLA(maxiter=50)
+    else:
+        optimizer = SLSQP(maxiter=1000, ftol=1e-9)
 
     # Overlap weights on the scale of the original matrix, not the padding.
     beta = 10.0 * max(
@@ -191,7 +213,18 @@ def run_vqd_eigensolver(flat_matrix, n, k=None):
                 rng.uniform(-np.pi, np.pi, ansatz.num_parameters)
             )
 
-    vqd = VQD(estimator, fidelity, ansatz, optimizer, k=k, betas=betas)
+    if use_noise:
+        vqd = VQD(
+            estimator,
+            fidelity,
+            ansatz,
+            optimizer,
+            k=k,
+            betas=betas,
+            transpiler=pass_manager,
+        )
+    else:
+        vqd = VQD(estimator, fidelity, ansatz, optimizer, k=k, betas=betas)
     vqd.initial_point = initial_points
 
     result = vqd.compute_eigenvalues(observable)
@@ -199,13 +232,38 @@ def run_vqd_eigensolver(flat_matrix, n, k=None):
     eigenvalues = [float(np.real(e)) for e in result.eigenvalues]
     eigenvectors = np.zeros((n, n), dtype=float)
     for i in range(k):
+        optimal_circuit = result.optimal_circuits[i]
+        optimal_parameters = result.optimal_points[i]
         eigenvectors[:, i] = _statevector_to_real_eigenvector(
-            result.optimal_circuits[i], result.optimal_points[i], n
+            optimal_circuit, optimal_parameters, n
         )
+
     uq_values = [0.0] * len(eigenvalues)
-    uq_vectors = [0.0] * (n * n)
+    uq_vectors = np.zeros((n, n), dtype=float)
+    for i in range(k):
+        optimal_circuit = result.optimal_circuits[i]
+        optimal_parameters = result.optimal_points[i]
+        uq_values[i] = _quantum_variance_std(
+            estimator,
+            optimal_circuit,
+            observable,
+            optimal_parameters,
+            eigenvalues[i],
+        )
+        uq_vectors[:, i] = _occupation_stds(
+            estimator,
+            optimal_circuit,
+            optimal_parameters,
+            n,
+            next_pow2,
+        )
 
-    return eigenvalues, eigenvectors.ravel().tolist(), uq_values, uq_vectors
+    return (
+        eigenvalues,
+        eigenvectors.ravel().tolist(),
+        uq_values,
+        uq_vectors.ravel().tolist(),
+    )
 
 
 def run_qaoa_eigensolver(flat_matrix, n, use_noise=False, reps=3):
@@ -213,7 +271,7 @@ 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)
+    observable, next_pow2 = _matrix_to_observable(flat_matrix, n)
     ansatz = QAOAAnsatz(observable, reps=reps)
     estimator, pass_manager = _make_estimator(use_noise)
     if use_noise:
@@ -227,44 +285,87 @@ def run_qaoa_eigensolver(flat_matrix, n, use_noise=False, reps=3):
 
     result = vqe.compute_minimum_eigenvalue(observable)
 
+    optimal_circuit = result.optimal_circuit
+    optimal_parameters = result.optimal_point
+
     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
+        optimal_circuit, optimal_parameters, 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
-        )
+    uq_vectors = np.zeros((n, n), dtype=float)
+    uq_values[0] = _quantum_variance_std(
+        estimator,
+        optimal_circuit,
+        observable,
+        optimal_parameters,
+        eigenvalues[0],
+    )
+    uq_vectors[:, 0] = _occupation_stds(
+        estimator,
+        optimal_circuit,
+        optimal_parameters,
+        n,
+        next_pow2,
+    )
 
-    return eigenvalues, eigenvectors.ravel().tolist(), uq_values, uq_vectors
+    return (
+        eigenvalues,
+        eigenvectors.ravel().tolist(),
+        uq_values,
+        uq_vectors.ravel().tolist(),
+    )
 
 
 # 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}")
+
+    print("=== VQD (noiseless) ===")
+    values, vectors, vqd_uq_v, vqd_uq_vec = run_vqd_eigensolver(test_matrix, 3)
+    print(f"Eigenvalues: {values}")
+    print(f"Eigenvectors: {vectors}")
+    print(f"uq_values: {vqd_uq_v}")
+    print(f"uq_vectors: {vqd_uq_vec}")
+
+    try:
+        print("\n=== VQD (noise) ===")
+        (
+            vqd_noisy_values,
+            vqd_noisy_vectors,
+            vqd_noisy_uq_v,
+            vqd_noisy_uq_vec,
+        ) = run_vqd_eigensolver(test_matrix, 3, use_noise=True)
+        print(f"Eigenvalues: {vqd_noisy_values}")
+        print(f"Eigenvectors: {vqd_noisy_vectors}")
+        print(f"uq_values: {vqd_noisy_uq_v}")
+        print(f"uq_vectors: {vqd_noisy_uq_vec}")
+    except ImportError as exc:
+        print(f"Skipping noisy VQD demo: {exc}")
+
+    print("\n=== QAOA (noiseless) ===")
     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}")
+    print(f"Eigenvalue: {qaoa_values}")
+    print(f"Eigenvector: {qaoa_vectors}")
+    print(f"uq_values: {qaoa_uq_v}")
+    print(f"uq_vectors: {qaoa_uq_vec}")
+
     try:
+        print("\n=== QAOA (noise) ===")
         (
             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}")
+        print(f"Eigenvalue: {qaoa_noisy_values}")
+        print(f"Eigenvector: {qaoa_noisy_vectors}")
+        print(f"uq_values: {noisy_uq_v}")
+        print(f"uq_vectors: {noisy_uq_vec}")
     except ImportError as exc:
         print(f"Skipping noisy QAOA demo: {exc}")

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

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: qharm-eigenbridge
+Version: 0.0.3
+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, use_noise=false)` -> lowest `k` eigenvalues (`k` defaults to all)
+QAOA -> `run_qaoa_eigensolver(matrix, use_noise=false)` -> ground state only
+
+**Uncertainties (`uq_values` / `uq_vectors`)**
+- For every VQD/QAOA path (noiseless and noisy), at each final optimized circuit/state,
+  `uq_values[i] = sqrt(max(0, ⟨H²⟩ − ⟨H⟩²))`, where ⟨H⟩ is the reported eigenvalue and ⟨H²⟩
+  comes from the same estimator on `H @ H` at the same parameters.
+  This is the standard deviation of a single measurement of H in the prepared state
+  (intrinsic quantum / variational residual variance).
+  Exact eigenstates give σ ≈ 0; approximate ansatz states give nonzero σ even without noise.
+- `uq_vectors` uses the same layout as the returned eigenvectors (column `i` = mode `i`).
+  For each physical basis index `j`,
+  `uq_vectors[j, i] = sqrt(p_j (1 − p_j))` where `p_j = ⟨|j⟩⟨j|⟩` is evaluated with the
+  **same estimator / circuit / parameters** as the energy (FakeManila when `use_noise=true`).
+  This is the std of a single-shot computational-basis occupation measurement for component `j`.
+  Caveat: it can be > 0 even for an exact delocalized eigenstate (unlike σ_H, which is 0 for
+  exact energy eigenstates). It is **not** “distance to the classical eigenvector.”
+  Unused eigenvector columns stay 0. Reported eigenvectors still come from the ideal
+  statevector of the optimized circuit; only the UQ uses the estimator/noise path.
+- Non–power-of-2 dimensions pad to the next power of two and place
+  `penalty = max(1.0, Gershgorin row-sum bound)` on unused diagonal entries so pad
+  eigenvalues stay outside the original spectrum while avoiding the old 10× entry-scale
+  inflation of ⟨H²⟩ on small problems.
+- Noisy VQD keeps exact statevector overlaps; only the energy / projector estimator uses
+  FakeManila noise (demo). Expect worse eigenvalues, especially for higher states.
+
+Unit tests check that reported `uq_values` / filled `uq_vectors` entries are finite and
+nonnegative (filled columns not identically zero on the demo matrix), and that on the
+demo 3×3 matrix the ground-state interval `[⟨H⟩−σ, ⟨H⟩+σ]` contains the classical ground
+eigenvalue for noisy paths. They do not require noisy eigenvalues to match the classical answer.

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

@@ -0,0 +1,8 @@
+{
+  "tag": "0.0.3",
+  "distance": 0,
+  "node": "gb816fc1c82456f18c3537b46b5fbe7c0cd08ccfd",
+  "dirty": false,
+  "branch": "main",
+  "node_date": "2026-09-25"
+}

qharm_eigenbridge-0.0.3/tests/unit_tests/test_eigensolvers.py

@@ -0,0 +1,187 @@
+# 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 _assert_finite_nonnegative(self, uq):
+        self.assertTrue(uq == uq and abs(uq) != float("inf"))
+        self.assertGreaterEqual(uq, 0.0)
+
+    def _assert_finite_positive(self, uq):
+        self._assert_finite_nonnegative(uq)
+        self.assertGreater(uq, 0.0)
+
+    def _check_uq_vectors(self, eigenvectors, uq_vectors, n=3, k_filled=None):
+        # uq_vectors: sqrt(p(1-p)) occupation stds; unused columns stay 0.
+        self.assertEqual(len(uq_vectors), len(eigenvectors))
+        self.assertEqual(len(uq_vectors), n * n)
+        for uq in uq_vectors:
+            self._assert_finite_nonnegative(uq)
+        if k_filled is None:
+            k_filled = n
+        for col in range(n):
+            col_uq = [uq_vectors[row * n + col] for row in range(n)]
+            if col < k_filled:
+                self.assertGreater(max(col_uq), 0.0)
+            else:
+                self.assertTrue(all(u == 0.0 for u in col_uq))
+
+    def _check_results(
+        self,
+        results,
+        val_places=14,
+        vec_places=14,
+        require_positive_uq=False,
+        k_filled=None,
+    ):
+        # 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)
+        # Energy UQs for returned modes: >= 0, or > 0 if require_positive_uq.
+        n_returned = sum(1 for v in self.correct_eigenvalues if v != 0.0)
+        if n_returned == 0:
+            n_returned = len(eigenvalues)
+        for i, uq in enumerate(uq_values):
+            if i < n_returned:
+                if require_positive_uq:
+                    self._assert_finite_positive(uq)
+                else:
+                    self._assert_finite_nonnegative(uq)
+            else:
+                self.assertEqual(uq, 0.0)
+        if k_filled is None:
+            k_filled = n_returned
+        self._check_uq_vectors(
+            eigenvectors, uq_vectors, n=3, k_filled=k_filled
+        )
+
+    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, k_filled=3)
+        eigenvalues, _, uq_values, _ = results
+        self.assertLessEqual(
+            eigenvalues[0] - uq_values[0], self.correct_eigenvalues[0]
+        )
+        self.assertLessEqual(
+            self.correct_eigenvalues[0], eigenvalues[0] + uq_values[0]
+        )
+
+    def test_vqd_eigensolver_noise(self):
+        # Does not require eigenvalues to match LAPACK, since Noisy VQD is a demo.
+        try:
+            (
+                eigenvalues,
+                eigenvectors,
+                uq_values,
+                uq_vectors,
+            ) = eigenbridge.run_vqd_eigensolver(
+                self.flat_matrix, n=3, use_noise=True
+            )
+        except ImportError as exc:
+            self.skipTest(f"Noisy VQD deps missing: {exc}")
+
+        self.assertEqual(len(eigenvalues), 3)
+        self.assertEqual(len(uq_values), 3)
+        for uq in uq_values:
+            self._assert_finite_positive(uq)
+        self._check_uq_vectors(eigenvectors, uq_vectors, n=3, k_filled=3)
+        # Sanity check on this demo matrix only — not a universal guarantee.
+        self.assertLessEqual(
+            eigenvalues[0] - uq_values[0], self.correct_eigenvalues[0]
+        )
+        self.assertLessEqual(
+            self.correct_eigenvalues[0], eigenvalues[0] + uq_values[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
+        )
+        # New gershgorin padding changes the QAOA cost Hamiltonian / landscape slightly
+        self._check_results(
+            results,
+            val_places=0,
+            vec_places=0,
+            require_positive_uq=True,
+            k_filled=1,
+        )
+        eigenvalues, _, uq_values, _ = results
+        self.assertLessEqual(
+            eigenvalues[0] - uq_values[0], self.correct_eigenvalues[0]
+        )
+        self.assertLessEqual(
+            self.correct_eigenvalues[0], eigenvalues[0] + uq_values[0]
+        )
+
+    def test_qaoa_eigensolver_noise(self):
+        try:
+            (
+                eigenvalues,
+                eigenvectors,
+                uq_values,
+                uq_vectors,
+            ) = eigenbridge.run_qaoa_eigensolver(
+                self.flat_matrix, n=3, use_noise=True
+            )
+        except ImportError as exc:
+            self.skipTest(f"Noisy QAOA deps missing: {exc}")
+
+        self._assert_finite_positive(uq_values[0])
+        for uq in uq_values[1:]:
+            self.assertEqual(uq, 0.0)
+        self._check_uq_vectors(eigenvectors, uq_vectors, n=3, k_filled=1)
+        # Sanity check on this demo matrix only, not a universal guarantee.
+        self.assertLessEqual(
+            eigenvalues[0] - uq_values[0], self.correct_eigenvalues[0]
+        )
+        self.assertLessEqual(
+            self.correct_eigenvalues[0], eigenvalues[0] + uq_values[0]
+        )

qharm_eigenbridge-0.0.2/PKG-INFO

@@ -1,55 +0,0 @@
-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

@@ -1,28 +0,0 @@
-<!--
-  ~ 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/PKG-INFO

@@ -1,55 +0,0 @@
-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/scm_version.json

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

qharm_eigenbridge-0.0.2/tests/unit_tests/test_eigensolvers.py

@@ -1,82 +0,0 @@
-# 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
-        )