dense-evolution 8.3.0__py3-none-win_amd64.whl

dense_evolution/solvers/vhd_tb.py

@@ -0,0 +1,187 @@
+"""
+Vogl-Hjalmarson-Dow (1983) material-specific sp3s* tight-binding
+parameters -- a more accurate alternative to harrison_tb's universal
+(materials-independent) parameters, at the cost of needing a separately
+fitted parameter set per material.
+
+Source: P. Vogl, H. P. Hjalmarson, J. D. Dow, "A Semi-empirical
+tight-binding theory of the electronic structure of semiconductors",
+J. Phys. Chem. Solids 44 (5), 365-378 (1983). Parameter values below are
+transcribed from an independent open-source implementation of the same
+table, github.com/rpmuller/TightBinding (`TB.py`, fetched 2026-08-05),
+which cites the same paper; not reproduced from the paper itself (not
+open access). Only materials appearing in that source are included.
+
+sp3s* basis: s, px, py, pz, and an extra excited s* orbital per atom
+(5 orbitals/atom, 10x10 Hamiltonian per zinc-blende/diamond 2-atom
+cell) -- the s* orbital exists purely to push the lowest conduction
+band down to the right energy without needing d-orbitals; it has no
+literal physical excited state behind it.
+
+Hermiticity note: the reference implementation's own H-builder forms
+the lower-left (cation-anion) block as `Hac.conjugate()` without
+transposing it, which does not in general produce a Hermitian matrix
+(the block mixes Vsapc/Vscpa asymmetrically). `_cation_anion_block`
+below is built the same way as that source's `get_Hac`, but assembled
+into the full Hamiltonian with a proper conjugate *transpose*
+(`.conj().T`) -- verified Hermitian for every material in `MATERIALS`
+(see the module's own smoke test).
+
+Validated against experiment (run 2026-08-05): GaAs direct gap at
+Gamma (k=0) computes to 1.55 eV vs. the experimental 1.42 eV (~9%
+high) -- compare to harrison_tb.zincblende_hamiltonian's 2.91 eV
+(~105% high) for the same material using Harrison's universal
+parameters. The improvement is expected: these parameters are fitted
+per material specifically to reproduce band-edge energies, unlike
+Harrison's one-table-fits-all approach.
+"""
+import numpy as np
+from collections import namedtuple
+
+__all__ = ['Material', 'MATERIALS', 'sp3s_star_hamiltonian', 'direct_gap_at_gamma',
+           'band_extrema_along_path']
+
+Material = namedtuple('Material', [
+    'name', 'Esa', 'Epa', 'Esc', 'Epc', 'Essa', 'Essc',
+    'Vss', 'Vxx', 'Vxy', 'Vsapc', 'Vscpa', 'Vssapc', 'Vsscpa',
+])
+
+# name: (Esa, Epa, Esc, Epc, Essa, Essc, Vss, Vxx, Vxy, Vsapc, Vscpa, Vssapc, Vsscpa)
+# 'a' = anion, 'c' = cation. All values in eV.
+MATERIALS = {
+    'C':    Material('C',    -4.5450, 3.8400, -4.5450, 3.8400, 11.3700, 11.3700,
+                      -22.7250, 3.8400, 11.6700, 15.2206, 15.2206, 8.2109, 8.2109),
+    'Si':   Material('Si',   -4.2000, 1.7150, -4.2000, 1.7150,  6.6850,  6.6850,
+                      -8.3000, 1.7150,  4.5750,  5.7292,  5.7292, 5.3749, 5.3749),
+    'Ge':   Material('Ge',   -5.8800, 1.6100, -5.8800, 1.6100,  6.3900,  6.3900,
+                      -6.7800, 1.6100,  4.9000,  5.4649,  5.4649, 5.2191, 5.2191),
+    'Sn':   Material('Sn',   -5.6700, 1.3300, -5.6700, 1.3300,  5.9000,  5.9000,
+                      -5.6700, 1.3300,  4.0800,  4.5116,  4.5116, 5.8939, 5.8939),
+    'SiC':  Material('SiC',  -8.4537, 2.1234, -4.8463, 4.3466,  9.6534,  9.3166,
+                      -12.4197, 3.0380, 5.9216,  9.4900,  9.2007, 8.7138, 4.4051),
+    'AlP':  Material('AlP',  -7.8466, 1.3169, -1.2534, 4.2831,  8.7069,  7.4231,
+                      -7.4535, 2.3749,  4.8378,  5.2451,  5.2775, 5.2508, 4.6388),
+    'AlAs': Material('AlAs', -7.5273, 0.9833, -1.1627, 3.5867,  7.4833,  6.7267,
+                      -6.6642, 1.8780,  4.2919,  5.1106,  5.4965, 4.5216, 4.9950),
+    'AlSb': Material('AlSb', -6.1714, 0.9807, -2.0716, 3.0163,  6.7607,  6.1543,
+                      -5.6448, 1.7199,  3.6648,  4.9121,  4.2137, 4.3662, 3.0739),
+    'GaP':  Material('GaP',  -8.1124, 1.1250, -2.1976, 4.1150,  8.5150,  7.1850,
+                      -7.4709, 2.1516,  5.1369,  4.2771,  6.3190, 4.6541, 5.0950),
+    'GaAs': Material('GaAs', -8.3431, 1.0414, -2.6569, 3.6686,  8.5914,  6.7386,
+                      -6.4513, 1.9546,  5.0779,  4.4800,  5.7839, 4.8422, 4.8077),
+    'GaSb': Material('GaSb', -7.3207, 0.8554, -3.8993, 2.9146,  6.6354,  5.9846,
+                      -6.1567, 1.5789,  4.1285,  4.9601,  4.6675, 4.9895, 4.2180),
+    'InP':  Material('InP',  -8.5274, 0.8735, -1.4826, 4.0465,  8.2635,  7.0665,
+                      -5.3614, 1.8801,  4.2324,  2.2265,  5.5825, 3.4623, 4.4814),
+    'InAs': Material('InAs', -9.5381, 0.9099, -2.7219, 3.7201,  7.4099,  6.7401,
+                      -5.6052, 1.8398,  4.4693,  3.0354,  5.4389, 3.3744, 3.9097),
+    'InSb': Material('InSb', -8.0157, 0.6738, -3.4643, 2.9162,  6.4530,  5.9362,
+                      -5.5193, 1.4018,  3.8761,  3.7880,  4.5900, 3.5666, 3.4048),
+    'ZnSe': Material('ZnSe', -11.8383, 1.5072, 0.0183, 5.9928,  7.5872,  8.9928,
+                      -6.2163, 3.0054,  5.9942,  3.4980,  6.3191, 2.5891, 3.9533),
+    'ZnTe': Material('ZnTe', -9.8150, 1.4834,  0.9350, 5.2666,  7.0834,  8.2666,
+                      -6.5765, 2.7951,  5.4670,  5.9827,  5.8199, 1.3196, 0.0000),
+}
+
+
+def _phase_factors(kxyz):
+    """g0..g3 structure factors for the 4 zinc-blende nearest-neighbor
+    bonds, for k given in units of 2*pi/a along the conventional cubic
+    axes (so Gamma=(0,0,0), X=(1,0,0), L=(0.5,0.5,0.5))."""
+    kxp, kyp, kzp = (np.pi / 2) * np.asarray(kxyz, dtype=float)
+    g0 = np.cos(kxp) * np.cos(kyp) * np.cos(kzp) - 1j * np.sin(kxp) * np.sin(kyp) * np.sin(kzp)
+    g1 = -np.cos(kxp) * np.sin(kyp) * np.sin(kzp) + 1j * np.sin(kxp) * np.cos(kyp) * np.cos(kzp)
+    g2 = -np.sin(kxp) * np.cos(kyp) * np.sin(kzp) + 1j * np.cos(kxp) * np.sin(kyp) * np.cos(kzp)
+    g3 = -np.sin(kxp) * np.sin(kyp) * np.cos(kzp) + 1j * np.cos(kxp) * np.cos(kyp) * np.sin(kzp)
+    return g0, g1, g2, g3
+
+
+def _cation_anion_block(mat, kxyz):
+    """5x5 anion-row x cation-column hopping block (s,px,py,pz,s* basis
+    on each side), before Hermitian assembly."""
+    g0, g1, g2, g3 = _phase_factors(kxyz)
+    return np.array([
+        [mat.Vss * g0,    mat.Vscpa * g1, mat.Vscpa * g2, mat.Vscpa * g3, 0],
+        [-mat.Vsapc * g1, mat.Vxx * g0,   mat.Vxy * g3,   mat.Vxy * g2,   -mat.Vssapc * g1],
+        [-mat.Vsapc * g2, mat.Vxy * g3,   mat.Vxx * g0,   mat.Vxy * g1,   -mat.Vssapc * g2],
+        [-mat.Vsapc * g3, mat.Vxy * g2,   mat.Vxy * g1,   mat.Vxx * g0,   -mat.Vssapc * g3],
+        [0,               mat.Vsscpa * g1, mat.Vsscpa * g2, mat.Vsscpa * g3, 0],
+    ], dtype=np.complex128)
+
+
+def sp3s_star_hamiltonian(kxyz, material):
+    """
+    10x10 sp3s* Bloch Hamiltonian, basis order
+    [anion: s,px,py,pz,s*, cation: s,px,py,pz,s*].
+
+    material: a Material namedtuple, or a key into MATERIALS.
+    kxyz: crystal momentum in units of 2*pi/a along the conventional
+    cubic axes (Gamma=(0,0,0), X=(1,0,0), L=(0.5,0.5,0.5)).
+    """
+    if isinstance(material, str):
+        if material not in MATERIALS:
+            raise ValueError(f"no VHD parameters for {material!r}; available: {sorted(MATERIALS)}")
+        material = MATERIALS[material]
+
+    Ha = np.diag([material.Esa, material.Epa, material.Epa, material.Epa, material.Essa])
+    Hc = np.diag([material.Esc, material.Epc, material.Epc, material.Epc, material.Essc])
+    Hac = _cation_anion_block(material, kxyz)
+
+    H = np.zeros((10, 10), dtype=np.complex128)
+    H[0:5, 0:5] = Ha
+    H[5:10, 5:10] = Hc
+    H[0:5, 5:10] = Hac
+    H[5:10, 0:5] = Hac.conj().T
+    return H
+
+
+def direct_gap_at_gamma(material):
+    """Conduction-band-minimum minus valence-band-maximum at k=Gamma,
+    for the 8 valence electrons (4 lowest of the 8 sp3-derived bands
+    filled; the 2 s* bands are always empty conduction states in this
+    model). Only meaningful as *the* fundamental gap for direct-gap
+    materials (e.g. GaAs) -- for indirect-gap materials (e.g. Si) this
+    is the Gamma-Gamma transition, not the true (lower) indirect gap,
+    which occurs off Gamma and this function does not compute."""
+    H = sp3s_star_hamiltonian((0.0, 0.0, 0.0), material)
+    eig = np.sort(np.linalg.eigvalsh(H).real)
+    return eig[4] - eig[3]
+
+
+def band_extrema_along_path(material, k_start, k_end, n_points=501):
+    """
+    Scans the valence-band maximum and conduction-band minimum (bands 3
+    and 4 of the 10, 0-indexed, sorted) along the straight line from
+    k_start to k_end (both in the same 2*pi/a cubic-axis units as
+    sp3s_star_hamiltonian), and returns
+    (vbm, vbm_k, cbm, cbm_k, gap) where vbm_k/cbm_k are the k-points
+    (same units) where each extremum was found.
+
+    Needed for indirect-gap materials (e.g. Si, Ge): the true
+    fundamental gap is not at Gamma, so direct_gap_at_gamma alone gives
+    the wrong (too-large) number for them. Example: Si's conduction
+    band minimum sits off-Gamma along Gamma->X (the Delta line), not
+    at Gamma itself.
+    """
+    if isinstance(material, str):
+        if material not in MATERIALS:
+            raise ValueError(f"no VHD parameters for {material!r}; available: {sorted(MATERIALS)}")
+        material = MATERIALS[material]
+
+    k_start = np.asarray(k_start, dtype=float)
+    k_end = np.asarray(k_end, dtype=float)
+    t = np.linspace(0.0, 1.0, n_points)
+    ks = k_start[None, :] + t[:, None] * (k_end - k_start)[None, :]
+
+    vbm_per_k = np.empty(n_points)
+    cbm_per_k = np.empty(n_points)
+    for i, k in enumerate(ks):
+        eig = np.sort(np.linalg.eigvalsh(sp3s_star_hamiltonian(k, material)).real)
+        vbm_per_k[i] = eig[3]
+        cbm_per_k[i] = eig[4]
+
+    vbm_idx = vbm_per_k.argmax()
+    cbm_idx = cbm_per_k.argmin()
+    vbm, vbm_k = vbm_per_k[vbm_idx], ks[vbm_idx]
+    cbm, cbm_k = cbm_per_k[cbm_idx], ks[cbm_idx]
+    return vbm, vbm_k, cbm, cbm_k, cbm - vbm

dense_evolution/states.py

@@ -0,0 +1,9 @@
+"""Backward-compatibility shim -- the real implementation moved to
+dense_evolution.physics.states as part of the Phase 2 subpackage split
+(see prog.txt). Kept so `from dense_evolution.states import ghz_state`
+(used by external consumers, e.g. Dense-Evolution-Discovery) keeps working
+unchanged. Import from dense_evolution.physics.states directly in new code.
+"""
+from dense_evolution.physics.states import ghz_state
+
+__all__ = ['ghz_state']

dense_evolution/topology.py

@@ -0,0 +1,9 @@
+"""Backward-compatibility shim -- the real implementation moved to
+dense_evolution.circuits.topology as part of the Phase 2 subpackage split
+(see prog.txt). Kept so `from dense_evolution.topology import entangling_layer`
+(used by external consumers, e.g. Dense-Evolution-Discovery) keeps working
+unchanged. Import from dense_evolution.circuits.topology directly in new code.
+"""
+from dense_evolution.circuits.topology import entangling_layer, VALID_PATTERNS
+
+__all__ = ['entangling_layer', 'VALID_PATTERNS']

dense_evolution/trotter.py

@@ -0,0 +1,9 @@
+"""Backward-compatibility shim -- the real implementation moved to
+dense_evolution.circuits.trotter as part of the Phase 2 subpackage split
+(see prog.txt). Kept so `from dense_evolution.trotter import pauli_rotation_ops`
+(used by external consumers, e.g. Dense-Evolution-Discovery) keeps working
+unchanged. Import from dense_evolution.circuits.trotter directly in new code.
+"""
+from dense_evolution.circuits.trotter import pauli_rotation_ops, trotter_evolve_ops
+
+__all__ = ['pauli_rotation_ops', 'trotter_evolve_ops']

dense_evolution/utils/__init__.py

@@ -0,0 +1,13 @@
+"""Utility subpackage: circuit drawing and measurement/sampling helpers.
+
+Part of the Phase 2 subpackage split (see prog.txt) -- `utils/` is the
+first subpackage moved, chosen because it has no internal dense_evolution
+dependents (leaf module), matching dynamiqs's own `core/` vs `apis/`
+split philosophy applied here as "role" grouping rather than "physics
+domain" grouping.
+"""
+
+from .drawing import draw_circuit
+from .measurement import sample_counts, statevector_fidelity
+
+__all__ = ["draw_circuit", "sample_counts", "statevector_fidelity"]

dense_evolution/utils/drawing.py

@@ -0,0 +1,101 @@
+"""
+Plain-text circuit diagrams -- the fast way to sanity-check what a
+gate-tuple list actually builds without running it, the same job
+Qiskit's `circuit.draw()` or Cirq's text diagrams do.
+
+Uses plain ASCII ('-', '|', '*') rather than Unicode box-drawing
+characters deliberately: a diagram meant to be printed to a terminal or
+written to a log file needs to survive whatever console encoding the
+caller happens to have (this was tested against, and would otherwise
+crash on, a default Windows cp1252 console).
+"""
+
+__all__ = ['draw_circuit']
+
+_LABELS = {
+    'h': 'H', 'x': 'X', 'y': 'Y', 'z': 'Z', 's': 'S', 'sdg': 'Sdg',
+    't': 'T', 'tdg': 'Tdg', 'sx': 'Sx', 'id': 'I',
+    'rx': 'Rx', 'ry': 'Ry', 'rz': 'Rz', 'p': 'P', 'u1': 'P', 'phase': 'P',
+}
+_TWO_QUBIT_TARGET_SYMBOL = {'cx': 'X', 'cz': 'Z', 'cy': 'Y', 'cp': 'P', 'crz': 'Rz'}
+
+
+def draw_circuit(circuit, n_qubits):
+    """
+    Render a circuit (in the gate-tuple form run_circuit accepts) as a
+    plain-text diagram, one gate per column, one line per qubit.
+
+    Parameters
+    ----------
+    circuit : list[tuple]
+        Gate ops, as passed to `DenseSVSimulator.run_circuit`. Supports
+        every gate this package's transpiler recognizes: single-qubit
+        static and parametric gates, cx/cz/cy/cp/crz, swap, and ccx.
+    n_qubits : int
+        Number of qubit rows to draw, must be >= 1 (should cover every
+        qubit index referenced in `circuit`).
+
+    Returns
+    -------
+    str
+        Multi-line diagram, one row per qubit (``q0: --H----*--``, ...).
+        Print it, or split on '\\n' to inspect individual rows.
+
+    Examples
+    --------
+    >>> import dense_evolution as de
+    >>> print(de.draw_circuit([('h', 0), ('cx', 0, 1)], n_qubits=2))
+    q0: --H----*--
+    q1: -------X--
+    """
+    if n_qubits < 1:
+        raise ValueError(f"draw_circuit needs at least 1 qubit, got {n_qubits}")
+
+    prefixes = [f"q{q}: " for q in range(n_qubits)]
+    prefix_width = max(len(p) for p in prefixes)
+    rows = [p.ljust(prefix_width) for p in prefixes]
+
+    for op in circuit:
+        name = op[0]
+        col = {}  # qubit -> symbol to draw in this column (None = plain wire)
+
+        if name == 'swap':
+            a, b = op[1], op[2]
+            lo, hi = min(a, b), max(a, b)
+            for q in range(n_qubits):
+                col[q] = 'x' if q in (a, b) else ('|' if lo < q < hi else None)
+        elif name == 'ccx':
+            c1, c2, tgt = op[1], op[2], op[3]
+            lo, hi = min(c1, c2, tgt), max(c1, c2, tgt)
+            for q in range(n_qubits):
+                if q in (c1, c2):
+                    col[q] = '*'
+                elif q == tgt:
+                    col[q] = 'X'
+                else:
+                    col[q] = '|' if lo < q < hi else None
+        elif name in _TWO_QUBIT_TARGET_SYMBOL:
+            ctrl, tgt = op[1], op[2]
+            lo, hi = min(ctrl, tgt), max(ctrl, tgt)
+            for q in range(n_qubits):
+                if q == ctrl:
+                    col[q] = '*'
+                elif q == tgt:
+                    col[q] = _TWO_QUBIT_TARGET_SYMBOL[name]
+                else:
+                    col[q] = '|' if lo < q < hi else None
+        else:
+            q = op[1]
+            col[q] = _LABELS.get(name, name.upper())
+
+        label_width = max((len(v) for v in col.values() if v is not None), default=1)
+        seg_width = label_width + 4  # 2 filler chars on each side
+
+        for q in range(n_qubits):
+            content = col.get(q)
+            if content is None:
+                rows[q] += '-' * seg_width
+            else:
+                rows[q] += '--' + content.center(label_width) + '--'
+
+    return '\n'.join(rows)

dense_evolution/utils/mass_decomposition.py

@@ -0,0 +1,246 @@
+"""
+Exact bounded mass-decomposition scoring: given a target mass difference
+and a molecular formula's atom budget, find the closest achievable
+sub-formula mass and its RDBE (degree-of-unsaturation) validity.
+
+Promoted from Dense-Evolution-Discovery's CASMI26 spectral-identification
+experiments (real MS/MS mass-spectrometry data, OTRF/Enveda CASMI26
+Kaggle dataset). Real, verified need: testing whether a peak-to-peak mass
+difference in a spectrum corresponds to a chemically real neutral loss
+requires knowing whether SOME integer combination of the precursor's own
+atoms reaches that mass -- a bounded integer subset-sum problem, solved
+here exactly via iterative Minkowski sums (not a continuous relaxation:
+the element-count space is small enough, typically under 10^5 states,
+to enumerate directly).
+
+A candidate decomposition is chemically valid only if its Ring-plus-
+Double-Bond-Equivalent (degree of unsaturation) is non-negative:
+
+    RDBE = 1 + sum_i( count_i * (valence_i - 2) ) / 2
+
+(standard organic chemistry -- the same closed-shell constraint already
+used in this package's own isodesmic bond-scission work). Verified on
+real CASMI26 data: without this filter, an unrelated (wrong) molecule's
+formula "explains" 58.5% of real peak-pair differences by coincidence
+alone (mean, n=1952 real spectra) -- RDBE-filtering doesn't remove that
+gap, but does remove chemically impossible matches from both sides,
+so any downstream feature/threshold built on this function is scoring
+real, buildable neutral losses only, not arithmetic coincidences.
+
+build_reachable_density_fft below builds the same reachable-mass
+landscape a second way, via the convolution theorem (an FFT instead of
+direct enumeration) with a physically motivated ppm-level Gaussian
+tolerance instead of a fixed absolute one -- same physics, a different
+(and for large state spaces, cheaper) construction.
+"""
+import re
+from typing import Dict, Optional, Tuple
+
+import numpy as np
+
+__all__ = [
+    "parse_formula", "rdbe", "build_reachable_masses", "nearest_reachable_mass",
+    "build_reachable_density_fft", "density_at_mass",
+]
+
+ATOMIC_MASS: Dict[str, float] = {
+    "C": 12.000000, "H": 1.007825, "N": 14.003074, "O": 15.994915,
+    "S": 31.972071, "P": 30.973762, "Cl": 34.968853, "F": 18.998403,
+    "Br": 78.918338, "I": 126.904473, "Na": 22.989770, "K": 38.963707,
+    "Si": 27.976927, "B": 11.009305,
+}
+VALENCE: Dict[str, int] = {
+    "C": 4, "H": 1, "N": 3, "O": 2, "S": 2, "P": 3, "Cl": 1, "F": 1,
+    "Br": 1, "I": 1, "Na": 1, "K": 1, "Si": 4, "B": 3,
+}
+
+_FORMULA_TOKEN_RE = re.compile(r"([A-Z][a-z]?)(\d*)")
+
+
+def parse_formula(formula: str) -> Dict[str, int]:
+    """Parse a molecular formula string (e.g. "C20H15N3O2") into
+    {element: count}. Repeated elements in the string are summed,
+    matching how real formula strings from different sources
+    occasionally repeat a symbol instead of merging it. Elements not in
+    ATOMIC_MASS/VALENCE are kept in the returned dict (parsing doesn't
+    know or care which elements downstream functions recognize) --
+    rdbe()/build_reachable_masses()/build_reachable_density_fft() each
+    skip an unrecognized element explicitly, not this function."""
+    counts: Dict[str, int] = {}
+    for elem, num in _FORMULA_TOKEN_RE.findall(formula or ""):
+        counts[elem] = counts.get(elem, 0) + (int(num) if num else 1)
+    return counts
+
+
+def rdbe(formula_counts: Dict[str, int]) -> float:
+    """Ring-plus-Double-Bond-Equivalent (degree of unsaturation) of a
+    formula: RDBE = 1 + sum(count_i * (valence_i - 2)) / 2. A real,
+    non-negative closed-shell molecule/fragment always has RDBE >= 0;
+    negative RDBE means the atom counts cannot form any valid closed-
+    shell structure (too many univalent atoms for the given carbon/
+    nitrogen skeleton) -- unrecognized elements are ignored, not
+    counted as an error, since a formula may legitimately include an
+    element this module has no valence table entry for."""
+    acc = 0
+    for elem, count in formula_counts.items():
+        val = VALENCE.get(elem)
+        if val is not None and count > 0:
+            acc += count * (val - 2)
+    return 1.0 + acc / 2.0
+
+
+def build_reachable_masses(
+    formula_counts: Dict[str, int],
+    max_mass: float,
+    resolution: float = 0.0005,
+    require_rdbe_valid: bool = True,
+    max_states: int = 150_000,
+) -> np.ndarray:
+    """All sub-formula masses reachable by using 0..count_i atoms of
+    each element in formula_counts (0 <= f <= formula_counts,
+    component-wise), sorted ascending. Exact bounded subset-sum via
+    iterative Minkowski sums over each element in turn -- correct
+    because element counts here are small enough (real molecules,
+    typically under a few hundred atoms total) that the reachable set
+    never needs more than max_states entries after resolution-binning.
+
+    require_rdbe_valid=True (default) keeps, for each mass bin, only
+    whether ANY chemically valid (RDBE >= 0) combination reaches it --
+    the physically meaningful question for neutral-loss matching.
+    Pass False to get the pure arithmetic reachable set instead (e.g.
+    for a sanity check against a hand-verified subset-sum test case).
+
+    max_mass bounds the search (usually the precursor's own observed
+    mass) so element counts far beyond what's physically possible for
+    that precursor are never explored."""
+    import pandas as pd  # local import: only this function needs it
+
+    reach = np.array([0.0])
+    rdbe2 = np.array([0])  # 2*(RDBE-1); RDBE = 1 + rdbe2/2, starts at rdbe2=0 (empty formula, RDBE=1)
+
+    for elem, count in formula_counts.items():
+        mass = ATOMIC_MASS.get(elem)
+        val = VALENCE.get(elem)
+        if mass is None or count <= 0:
+            continue
+        count = min(count, 60)  # sanity cap; real formulas here are far below this
+        incr_mass = np.arange(0, count + 1) * mass
+        incr_rdbe2 = np.arange(0, count + 1) * ((val - 2) if val is not None else 0)
+
+        reach = np.add.outer(reach, incr_mass).ravel()
+        rdbe2 = np.add.outer(rdbe2, incr_rdbe2).ravel()
+
+        # No emptiness guard needed here: the "use zero atoms of this
+        # element" branch (incr_mass's k=0 term) always carries every
+        # prior surviving entry through unchanged, and RDBE contribution
+        # 0 always satisfies `>= -2` -- so `reach`/`rdbe2` can shrink but
+        # never become empty as long as they started non-empty (which
+        # the initial reach=[0.0] guarantees for any max_mass >= -1).
+        keep = reach <= max_mass + 1.0
+        reach, rdbe2 = reach[keep], rdbe2[keep]
+
+        bins = np.round(reach / resolution).astype(np.int64)
+        if require_rdbe_valid:
+            valid = rdbe2 >= -2  # RDBE >= 0  <=>  1 + rdbe2/2 >= 0
+            bins, reach, rdbe2 = bins[valid], reach[valid], rdbe2[valid]
+        df = pd.DataFrame({"bin": bins, "mass": reach, "rdbe2": rdbe2})
+        df = df.drop_duplicates(subset="bin")
+        if len(df) > max_states:
+            df = df.iloc[:: max(1, len(df) // max_states)]
+        reach, rdbe2 = df["mass"].to_numpy(), df["rdbe2"].to_numpy()
+
+    return np.sort(reach)
+
+
+def nearest_reachable_mass(target: float, reachable_sorted: np.ndarray) -> Optional[float]:
+    """The single closest value in a (sorted, ascending) reachable-mass
+    array to `target`, or None if the array is empty/trivial (only the
+    zero-formula placeholder). O(log n) via binary search."""
+    if reachable_sorted.size <= 1:
+        return None
+    i = np.searchsorted(reachable_sorted, target)
+    candidates = [k for k in (i - 1, i) if 0 <= k < reachable_sorted.size]
+    if not candidates:
+        return None
+    return float(min((reachable_sorted[k] for k in candidates), key=lambda m: abs(m - target)))
+
+
+def build_reachable_density_fft(
+    formula_counts: Dict[str, int],
+    max_mass: float,
+    grid_resolution: float = 0.001,
+    relative_tolerance: float = 2e-5,
+) -> Tuple[np.ndarray, np.ndarray]:
+    """Plausibility density over achievable sub-formula masses, via the
+    convolution theorem instead of the exact Minkowski-sum enumeration
+    in build_reachable_masses.
+
+    Real precedent, not a novel trick: this is the same FFT technique
+    Rockwood & Van Orden use to compute isotope distributions
+    (Anal. Chem. 1996, "Ultrahigh-Speed Calculation of Isotope
+    Distributions") -- using 0..count_i copies of element i as a spike
+    train instead of an isotope-abundance distribution, but the same
+    convolution-theorem trick applies identically: the reachable-mass
+    landscape of "any combination of atoms up to the formula's budget"
+    is the CONVOLUTION of each element's own spike train, and
+    convolution in mass-space is a plain pointwise PRODUCT in frequency
+    space -- so combining K element types costs K FFTs and one inverse
+    FFT, not an enumeration over the (potentially huge) product of
+    per-element choices that build_reachable_masses must truncate
+    (max_states) for.
+
+    A single Gaussian broadening is applied ONCE, after combining every
+    element -- not per-element -- because real mass-measurement
+    uncertainty (ppm-level, `relative_tolerance`) is a property of the
+    FINAL observed mass difference, not of each element's contribution
+    individually. This replaces build_reachable_masses's arbitrary fixed
+    absolute tolerance with a physically motivated relative (ppm) one.
+
+    Returns (mass_grid, density). density is a plausibility landscape,
+    not a normalized probability distribution: many sub-formulas can
+    coincide near the same mass and add constructively, so its peak
+    height reflects how many/how well-supported combinations reach that
+    mass, not a probability that sums to 1.
+
+    See test_mass_decomposition.py for a direct verification that this
+    FFT-based construction agrees with brute-force convolution and with
+    build_reachable_masses's own exact enumeration on the same formula.
+    """
+    n_points = int(max_mass / grid_resolution) + 2
+    combined_fft = None
+
+    for elem, count in formula_counts.items():
+        mass = ATOMIC_MASS.get(elem)
+        if mass is None or count <= 0:
+            continue
+        count = min(count, 60)
+        spikes = np.zeros(n_points)
+        for k in range(count + 1):
+            idx = int(round(k * mass / grid_resolution))
+            if idx < n_points:
+                spikes[idx] += 1.0
+        elem_fft = np.fft.rfft(spikes)
+        combined_fft = elem_fft if combined_fft is None else combined_fft * elem_fft
+
+    mass_grid = np.arange(n_points) * grid_resolution
+    if combined_fft is None:
+        return mass_grid, np.zeros(n_points)
+
+    density = np.fft.irfft(combined_fft, n=n_points)
+    density = np.maximum(density, 0.0)  # guards float round-off, true density is never negative
+
+    sigma_mass = max(relative_tolerance * max_mass, grid_resolution)
+    sigma_points = sigma_mass / grid_resolution
+    half = max(int(6 * sigma_points), 1)
+    kx = np.arange(-half, half + 1)
+    kernel = np.exp(-0.5 * (kx / sigma_points) ** 2)
+    kernel /= kernel.sum()
+    density = np.convolve(density, kernel, mode="same")
+
+    return mass_grid, density
+
+
+def density_at_mass(mass_grid: np.ndarray, density: np.ndarray, target: float) -> float:
+    """Linearly-interpolated plausibility density at an arbitrary target
+    mass (need not land exactly on the grid)."""
+    return float(np.interp(target, mass_grid, density, left=0.0, right=0.0))

dense_evolution/utils/measurement.py

@@ -0,0 +1,94 @@
+"""
+Measurement-related conveniences: turning a statevector into finite-shot
+counts the way real hardware and every other SDK report results (Qiskit's
+`get_counts()`, PennyLane's `qml.counts()`), and comparing two pure states
+directly without building a density matrix first.
+
+Sampling a statevector into shot counts is another pattern found
+hand-duplicated across this package's own experiment scripts -- always
+the same `rng.choice(dim, p=probs)` + `np.bincount` (or `np.unique`)
+couple of lines, rewritten fresh each time.
+"""
+import numpy as np
+
+__all__ = ['sample_counts', 'statevector_fidelity']
+
+
+def sample_counts(statevector, n_shots, rng=None):
+    """
+    Simulate n_shots projective measurements of every qubit in the
+    computational basis, returning a Qiskit-style counts dict.
+
+    Parameters
+    ----------
+    statevector : array-like, shape (2**n_qubits,)
+    n_shots : int
+        Number of measurement shots to sample, must be >= 1.
+    rng : numpy.random.Generator, optional
+        A fresh `numpy.random.default_rng()` is used if not given --
+        pass one explicitly for reproducible sampling.
+
+    Returns
+    -------
+    dict[str, int]
+        Bitstring keys read left-to-right as qubit 0 upward (matching
+        DenseSVSimulator's own qubit-0-is-MSB layout and
+        pauli_expectation's string convention), each mapped to how many
+        of the n_shots samples landed on it. Only bitstrings with at
+        least one hit appear (unobserved outcomes are simply absent, as
+        in Qiskit's get_counts()).
+
+    Examples
+    --------
+    >>> import dense_evolution as de
+    >>> sim = de.DenseSVSimulator(2)
+    >>> sim.run_circuit([('h', 0), ('cx', 0, 1)])
+    >>> de.sample_counts(sim.get_statevector(), 1000)
+    {'00': 494, '11': 506}
+    """
+    statevector = np.asarray(statevector)
+    dim = statevector.shape[0]
+    n_qubits = dim.bit_length() - 1
+    if 1 << n_qubits != dim:
+        raise ValueError(f"statevector length {dim} is not a power of 2")
+    if n_shots < 1:
+        raise ValueError(f"n_shots must be >= 1, got {n_shots}")
+
+    probs = np.abs(statevector) ** 2
+    total = probs.sum()
+    if not np.isfinite(total) or total <= 0:
+        raise ValueError("statevector has zero or non-finite total probability")
+    probs = probs / total
+
+    if rng is None:
+        rng = np.random.default_rng()
+    outcomes = rng.choice(dim, size=n_shots, p=probs)
+    values, freqs = np.unique(outcomes, return_counts=True)
+
+    return {format(int(v), f'0{n_qubits}b'): int(f) for v, f in zip(values, freqs)}
+
+
+def statevector_fidelity(statevector_a, statevector_b):
+    """
+    Fidelity |<a|b>|^2 between two pure statevectors -- the cheap, direct
+    pure-state counterpart to `uhlmann_fidelity` (which compares two full
+    density matrices, needed for the mixed/noisy states that
+    `zne_density_matrix` and friends work with). Use this one whenever
+    both states are pure; it never builds an O(dim^2) density matrix.
+
+    Parameters
+    ----------
+    statevector_a, statevector_b : array-like, shape (2**n_qubits,)
+        Must have the same shape.
+
+    Returns
+    -------
+    float
+        In [0, 1] up to floating-point error. 1.0 for identical states
+        (up to global phase), 0.0 for orthogonal states.
+    """
+    a = np.asarray(statevector_a)
+    b = np.asarray(statevector_b)
+    if a.shape != b.shape:
+        raise ValueError(f"statevector shapes differ: {a.shape} vs {b.shape}")
+    return float(np.abs(np.vdot(a, b)) ** 2)