qnmlab 0.1.0__tar.gz

qnmlab-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Abir Chekroun, Hamed Al-Yoorby, Mouadh Abderrahmane Assal,
+Zakaria Lourghi, and Achraf Boussahi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qnmlab-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: qnmlab
+Version: 0.1.0
+Summary: Black-hole quasinormal modes with quantum algorithms: phase readout, seedless search, hardware analysis
+Author: Hamed Al-Yoorby, Mouadh Abderrahmane Assal, Zakaria Lourghi, Achraf Boussahi
+Author-email: Abir Chekroun <a.chekroun@esi-sba.dz>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/abir-tech/qnmlab
+Project-URL: Issues, https://github.com/abir-tech/qnmlab/issues
+Keywords: quasinormal modes,black holes,quantum computing,variational quantum eigensolver,non-Hermitian,gravitational waves
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: sympy>=1.12
+Provides-Extra: hardware
+Requires-Dist: qiskit>=1.0; extra == "hardware"
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == "plot"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: matplotlib>=3.7; extra == "dev"
+Dynamic: license-file
+
+# qnmlab
+
+**Black-hole quasinormal modes with quantum algorithms.**
+
+`qnmlab` computes the ringing frequencies of black holes with variational quantum
+algorithms. You choose a black hole, a size in qubits, a representation, and a simulated
+or real quantum backend, and compare the result with trusted reference values.
+
+The two ideas behind it:
+
+- **Phase readout.** On hyperboloidal slices the modes are eigenvalues of one linear
+  operator, so a mode's frequency is two measured averages,
+  `Re ω = −⟨H₂⟩`, `Im ω = ⟨H₁⟩`. That costs about 130 times fewer shots than detecting
+  where a matrix becomes singular.
+- **Seedless search.** A thresholded scan of the complex frequency plane produces a
+  shortlist of candidates, and the phase readout verifies each one. No starting guess is
+  needed.
+
+Classical methods compute these modes faster; `qnmlab` is for studying, benchmarking and
+running the quantum formulation, not for replacing them.
+
+## Install
+
+```bash
+pip install qnmlab                 # core: numpy, scipy, sympy
+pip install "qnmlab[hardware]"     # + Qiskit, to export circuits for real devices
+```
+
+Latest development version:
+
+```bash
+pip install git+https://github.com/abir-tech/qnmlab.git
+```
+
+## Quick start
+
+```python
+import qnmlab as ql
+
+bh = ql.KazakovSolodukhin(a=0.5)          # or ql.Schwarzschild(), ql.ReissnerNordstrom(Q), ql.Hayward(l)
+ql.reference_modes(bh, ell=2, n_modes=2)  # classical ground truth
+
+# read the fundamental on a simulated noisy 3-qubit device
+r = ql.measure_mode(bh, qubits=3, noise=ql.NoiseModel.emerald_random(), shots=800)
+print(r.omega, r.meta["error_vs_reference"])
+
+# find modes with no starting guess (Schwarzschild, 4 qubits)
+res = ql.find_modes(ql.Schwarzschild(), qubits=4)
+print(res.modes)          # the fundamental and the first overtone
+```
+
+From the command line:
+
+```bash
+qnmlab modes   --model kazakov-solodukhin --parameter 0.5
+qnmlab readout --model schwarzschild --qubits 3 --noise emerald-random --shots 800
+qnmlab search  --model schwarzschild --qubits 4
+```
+
+## What you can choose
+
+| choice | options |
+|---|---|
+| black hole | `Schwarzschild()`, `KazakovSolodukhin(a)` — validated against published frequencies; `ReissnerNordstrom(Q)`, `Hayward(l)` — experimental (cross-checked against an independent method, not against published values) |
+| size | qubits; operator dimension `2**qubits` |
+| readout representation | `"hyperboloidal"` (any model), `"ultraspherical"` (banded generalised pencil, Schwarzschild) |
+| search representation | `"leaver"` (tridiagonal, Schwarzschild), `"frobenius"` (any model) |
+| search solver | `"exact"` (fast) or `"variational"` (a variational solver at every grid point) |
+| noise | `NoiseModel.ideal()`, `.emerald_random()`, `.emerald_coherent()`, or your own `NoiseModel(p2, eps, readout)` |
+
+## Real hardware
+
+```python
+op = ql.readout_operator(ql.Schwarzschild(), qubits=3)
+state = ql.prepare_state(op, lead=0.48 - 0.097j, layers=2)
+job = ql.hardware.build_job(op, state)                 # 11 circuits
+ok = ql.hardware.verify(job)                            # Qiskit export matches the simulation
+circuits = [ql.hardware.to_qiskit(c, 3) for c in job["circuits"]]
+# ... run them with your provider, collect raw counts by circuit name ...
+result = ql.hardware.analyse_counts(job, raw_counts)    # measures bit order, mitigates readout
+```
+
+`analyse_counts` measures the provider's bit order from two calibration circuits and stops
+if a qubit is stuck — both happened on real devices while this package was developed.
+
+The raw counts of the 2026 IQM Emerald run ship with the package:
+
+```python
+ql.benchmarks.reanalyse_emerald_2026()   # (0.43919 - 0.10430i), exact 0.48186 - 0.09674i
+```
+
+## Scope and honesty
+
+- The end-to-end search ran in simulation; on hardware only the readout was run, from a
+  classically prepared state.
+- The search costs about 10^13 measurement shots at 4 qubits.
+- The hardware error (~0.04) is dominated by gate noise; more qubits help only once it falls.
+
+## Citing
+
+If you use `qnmlab`, please cite the accompanying paper (see `CITATION.cff`):
+A. Chekroun, H. Al-Yoorby, M. A. Assal, Z. Lourghi, A. Boussahi,
+*Phase Readout and Seedless Search for Black-Hole Quasinormal Modes on Quantum Processors* (2026).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -m "not slow"     # ~5 minutes
+pytest                   # includes the ~40-minute end-to-end search
+```
+
+MIT licence.

qnmlab-0.1.0/README.md

@@ -0,0 +1,113 @@
+# qnmlab
+
+**Black-hole quasinormal modes with quantum algorithms.**
+
+`qnmlab` computes the ringing frequencies of black holes with variational quantum
+algorithms. You choose a black hole, a size in qubits, a representation, and a simulated
+or real quantum backend, and compare the result with trusted reference values.
+
+The two ideas behind it:
+
+- **Phase readout.** On hyperboloidal slices the modes are eigenvalues of one linear
+  operator, so a mode's frequency is two measured averages,
+  `Re ω = −⟨H₂⟩`, `Im ω = ⟨H₁⟩`. That costs about 130 times fewer shots than detecting
+  where a matrix becomes singular.
+- **Seedless search.** A thresholded scan of the complex frequency plane produces a
+  shortlist of candidates, and the phase readout verifies each one. No starting guess is
+  needed.
+
+Classical methods compute these modes faster; `qnmlab` is for studying, benchmarking and
+running the quantum formulation, not for replacing them.
+
+## Install
+
+```bash
+pip install qnmlab                 # core: numpy, scipy, sympy
+pip install "qnmlab[hardware]"     # + Qiskit, to export circuits for real devices
+```
+
+Latest development version:
+
+```bash
+pip install git+https://github.com/abir-tech/qnmlab.git
+```
+
+## Quick start
+
+```python
+import qnmlab as ql
+
+bh = ql.KazakovSolodukhin(a=0.5)          # or ql.Schwarzschild(), ql.ReissnerNordstrom(Q), ql.Hayward(l)
+ql.reference_modes(bh, ell=2, n_modes=2)  # classical ground truth
+
+# read the fundamental on a simulated noisy 3-qubit device
+r = ql.measure_mode(bh, qubits=3, noise=ql.NoiseModel.emerald_random(), shots=800)
+print(r.omega, r.meta["error_vs_reference"])
+
+# find modes with no starting guess (Schwarzschild, 4 qubits)
+res = ql.find_modes(ql.Schwarzschild(), qubits=4)
+print(res.modes)          # the fundamental and the first overtone
+```
+
+From the command line:
+
+```bash
+qnmlab modes   --model kazakov-solodukhin --parameter 0.5
+qnmlab readout --model schwarzschild --qubits 3 --noise emerald-random --shots 800
+qnmlab search  --model schwarzschild --qubits 4
+```
+
+## What you can choose
+
+| choice | options |
+|---|---|
+| black hole | `Schwarzschild()`, `KazakovSolodukhin(a)` — validated against published frequencies; `ReissnerNordstrom(Q)`, `Hayward(l)` — experimental (cross-checked against an independent method, not against published values) |
+| size | qubits; operator dimension `2**qubits` |
+| readout representation | `"hyperboloidal"` (any model), `"ultraspherical"` (banded generalised pencil, Schwarzschild) |
+| search representation | `"leaver"` (tridiagonal, Schwarzschild), `"frobenius"` (any model) |
+| search solver | `"exact"` (fast) or `"variational"` (a variational solver at every grid point) |
+| noise | `NoiseModel.ideal()`, `.emerald_random()`, `.emerald_coherent()`, or your own `NoiseModel(p2, eps, readout)` |
+
+## Real hardware
+
+```python
+op = ql.readout_operator(ql.Schwarzschild(), qubits=3)
+state = ql.prepare_state(op, lead=0.48 - 0.097j, layers=2)
+job = ql.hardware.build_job(op, state)                 # 11 circuits
+ok = ql.hardware.verify(job)                            # Qiskit export matches the simulation
+circuits = [ql.hardware.to_qiskit(c, 3) for c in job["circuits"]]
+# ... run them with your provider, collect raw counts by circuit name ...
+result = ql.hardware.analyse_counts(job, raw_counts)    # measures bit order, mitigates readout
+```
+
+`analyse_counts` measures the provider's bit order from two calibration circuits and stops
+if a qubit is stuck — both happened on real devices while this package was developed.
+
+The raw counts of the 2026 IQM Emerald run ship with the package:
+
+```python
+ql.benchmarks.reanalyse_emerald_2026()   # (0.43919 - 0.10430i), exact 0.48186 - 0.09674i
+```
+
+## Scope and honesty
+
+- The end-to-end search ran in simulation; on hardware only the readout was run, from a
+  classically prepared state.
+- The search costs about 10^13 measurement shots at 4 qubits.
+- The hardware error (~0.04) is dominated by gate noise; more qubits help only once it falls.
+
+## Citing
+
+If you use `qnmlab`, please cite the accompanying paper (see `CITATION.cff`):
+A. Chekroun, H. Al-Yoorby, M. A. Assal, Z. Lourghi, A. Boussahi,
+*Phase Readout and Seedless Search for Black-Hole Quasinormal Modes on Quantum Processors* (2026).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -m "not slow"     # ~5 minutes
+pytest                   # includes the ~40-minute end-to-end search
+```
+
+MIT licence.

qnmlab-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qnmlab"
+version = "0.1.0"
+description = "Black-hole quasinormal modes with quantum algorithms: phase readout, seedless search, hardware analysis"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Abir Chekroun", email = "a.chekroun@esi-sba.dz" },
+  { name = "Hamed Al-Yoorby" },
+  { name = "Mouadh Abderrahmane Assal" },
+  { name = "Zakaria Lourghi" },
+  { name = "Achraf Boussahi" },
+]
+requires-python = ">=3.10"
+dependencies = ["numpy>=1.24", "scipy>=1.10", "sympy>=1.12"]
+keywords = ["quasinormal modes", "black holes", "quantum computing", "variational quantum eigensolver",
+            "non-Hermitian", "gravitational waves"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Physics",
+  "Development Status :: 3 - Alpha",
+]
+
+[project.optional-dependencies]
+hardware = ["qiskit>=1.0"]
+plot = ["matplotlib>=3.7"]
+dev = ["pytest>=7", "matplotlib>=3.7"]
+
+[project.scripts]
+qnmlab = "qnmlab.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/abir-tech/qnmlab"
+Issues = "https://github.com/abir-tech/qnmlab/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"qnmlab.data" = ["*.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["slow: takes more than a minute (deselect with -m 'not slow')"]

qnmlab-0.1.0/setup.cfg

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

qnmlab-0.1.0/src/qnmlab/__init__.py

@@ -0,0 +1,23 @@
+"""
+qnmlab -- black-hole quasinormal modes with quantum algorithms.
+
+    import qnmlab as ql
+    bh = ql.KazakovSolodukhin(a=0.5)
+    ql.reference_modes(bh)                         # classical ground truth
+    op = ql.readout_operator(bh, qubits=3)         # modes are its eigenvalues
+    r = ql.measure_mode(bh, qubits=3, noise=ql.NoiseModel.emerald_random(), shots=800)
+    res = ql.find_modes(ql.Schwarzschild(), qubits=4)   # search with no starting guess
+"""
+from . import benchmarks, hardware
+from .models import BlackHole, Hayward, KazakovSolodukhin, ReissnerNordstrom, Schwarzschild, available_models
+from .operators import readout_operator, search_pencil
+from .readout import NoiseModel, measure_mode, phase_readout, prepare_state
+from .reference import reference_modes
+from .search import find_modes
+
+__version__ = "0.1.0"
+
+__all__ = ["BlackHole", "Schwarzschild", "KazakovSolodukhin", "ReissnerNordstrom", "Hayward",
+           "available_models", "reference_modes", "readout_operator", "search_pencil", "NoiseModel",
+           "prepare_state", "phase_readout", "measure_mode", "find_modes", "benchmarks", "hardware",
+           "__version__"]

qnmlab-0.1.0/src/qnmlab/_core/grouping.py

@@ -0,0 +1,177 @@
+"""
+grouping.py -- fewer measurement circuits via GENERAL-commuting (GC) grouping.
+
+The hardware run used qubit-wise-commuting (QWC) groups: 28 circuits for the 63
+Pauli strings of H1 and H2 at 3 qubits.  QWC cannot do better than 27 here,
+because every one of the 27 weight-3 strings needs its own local basis.
+
+General commutation is weaker than qubit-wise commutation, so groups can be much
+larger.  For n qubits all 4^n - 1 non-identity Paulis partition into 2^n + 1
+commuting families of 2^n - 1 (mutually unbiased bases): 9 circuits instead of
+28 at 3 qubits.  The price is a short Clifford circuit that rotates each family
+onto Z-strings, which adds two-qubit gates (found by search, minimising CX count).
+
+Measured trade-off: see the accompanying paper (noise and mitigation section).
+"""
+import heapq
+import itertools
+import math
+
+import numpy as np
+
+from .hardware_run import _cx_matrix, _embed, _mat1
+
+PAULI = {"I": np.eye(2), "X": np.array([[0, 1], [1, 0]]),
+         "Y": np.array([[0, -1j], [1j, 0]]), "Z": np.diag([1.0, -1.0])}
+
+
+def pmat(label):
+    M = np.array([[1.0 + 0j]])
+    for ch in label:
+        M = np.kron(M, PAULI[ch])
+    return M
+
+
+def symp(label):
+    """(x bits, z bits) of a Pauli label."""
+    x = tuple(int(c in "XY") for c in label)
+    z = tuple(int(c in "ZY") for c in label)
+    return x, z
+
+
+def commute(a, b):
+    xa, za = symp(a)
+    xb, zb = symp(b)
+    return (sum(i * j for i, j in zip(xa, zb)) + sum(i * j for i, j in zip(za, xb))) % 2 == 0
+
+
+def gc_partition(labels):
+    """
+    Partition Pauli labels into mutually commuting families with as few families
+    as possible.  Exact-cover search over maximal commuting sets (fine for n <= 3;
+    falls back to greedy colouring above that).
+    """
+    labels = list(labels)
+    n = len(labels[0])
+    if n <= 3:
+        alls = ["".join(t) for t in itertools.product("IXYZ", repeat=n)][1:]
+        fams = set()
+        for gens in itertools.combinations(alls, n):
+            if all(commute(a, b) for a, b in itertools.combinations(gens, 2)):
+                grp = {_mul_label(c) for c in _span(gens)} - {"I" * n, None}
+                if len(grp) == 2 ** n - 1:
+                    fams.add(frozenset(grp))
+        fams = list(fams)
+        target = set(labels)
+        best = [None]
+
+        def search(rem, chosen):
+            if best[0] is not None and len(chosen) >= len(best[0]):
+                return
+            if not rem:
+                best[0] = list(chosen)
+                return
+            p = min(rem)
+            for f in fams:
+                if p in f and not (f & set().union(*chosen) if chosen else False):
+                    search(rem - f, chosen + [f])
+        search(target, [])
+        return [sorted(set(f) & target) for f in best[0]]
+    groups = []
+    for lab in sorted(labels, key=lambda s: -sum(c != "I" for c in s)):
+        for g in groups:
+            if all(commute(lab, o) for o in g):
+                g.append(lab)
+                break
+        else:
+            groups.append([lab])
+    return groups
+
+
+def _span(gens):
+    out = []
+    for bits in itertools.product((0, 1), repeat=len(gens)):
+        out.append(tuple(g for g, b in zip(gens, bits) if b))
+    return out
+
+
+def _mul_label(factors):
+    n = len(factors[0]) if factors else 0
+    if not factors:
+        return None
+    x = [0] * n
+    z = [0] * n
+    for f in factors:
+        fx, fz = symp(f)
+        x = [a ^ b for a, b in zip(x, fx)]
+        z = [a ^ b for a, b in zip(z, fz)]
+    return "".join("I" if (a, b) == (0, 0) else "X" if (a, b) == (1, 0)
+                   else "Z" if (a, b) == (0, 1) else "Y" for a, b in zip(x, z))
+
+
+# ---------------------------------------------------------------- diagonalising Cliffords
+def _apply_sym(gate, vecs, n):
+    out = []
+    for x, z in vecs:
+        x, z = list(x), list(z)
+        if gate[0] == "h":
+            q = gate[1]; x[q], z[q] = z[q], x[q]
+        elif gate[0] == "s":
+            q = gate[1]; z[q] ^= x[q]
+        elif gate[0] == "cx":
+            c, t = gate[1], gate[2]; x[t] ^= x[c]; z[c] ^= z[t]
+        out.append((tuple(x), tuple(z)))
+    return tuple(out)
+
+
+def diagonalising_circuit(family, n):
+    """Cheapest {H, S, CX} circuit (CX cost 1, single-qubit 0.01) mapping every
+    member of a commuting family onto a Z-string."""
+    gens = [symp(l) for l in family]
+    moves = [("h", q) for q in range(n)] + [("s", q) for q in range(n)] + \
+            [("cx", c, t) for c in range(n) for t in range(n) if c != t]
+    start = tuple(gens)
+    pq = [(0.0, 0, start, ())]
+    seen = {start: 0.0}
+    k = 0
+    while pq:
+        cost, _, st, path = heapq.heappop(pq)
+        if all(not any(x) for x, _ in st):
+            return list(path)
+        if cost > 6:
+            break
+        for m in moves:
+            nst = _apply_sym(m, st, n)
+            nc = cost + (1.0 if m[0] == "cx" else 0.01)
+            if nst not in seen or nc < seen[nst] - 1e-12:
+                seen[nst] = nc
+                k += 1
+                heapq.heappush(pq, (nc, k, nst, path + (m,)))
+    raise RuntimeError("no diagonalising circuit found")
+
+
+def to_sim_gates(path):
+    """Map {h, s, cx} to the simulator's gate set (S = RZ(pi/2) up to global phase)."""
+    return [("h", g[1]) if g[0] == "h" else ("rz", g[1], math.pi / 2) if g[0] == "s"
+            else ("cx", g[1], g[2]) for g in path]
+
+
+def unitary(gates, n):
+    U = np.eye(2 ** n, dtype=complex)
+    for g in gates:
+        if g[0] == "cx":
+            G = _cx_matrix(g[1], g[2], n)
+        else:
+            G = _embed(_mat1(g[0], g[2] if len(g) > 2 else None), g[1], n)
+        U = G @ U
+    return U
+
+
+def z_image(label, U, n):
+    """U P U^dag = sign * Z-string.  Returns (sign, zlabel)."""
+    M = U @ pmat(label) @ U.conj().T
+    for zl in ("".join(t) for t in itertools.product("IZ", repeat=n)):
+        c = np.trace(pmat(zl) @ M) / 2 ** n
+        if abs(abs(c) - 1) < 1e-9:
+            return (1.0 if np.real(c) > 0 else -1.0), zl
+    raise RuntimeError(f"{label} is not diagonalised")