dense-evolution 8.2.0__tar.gz → 8.2.1__tar.gz

{dense_evolution-8.2.0 → dense_evolution-8.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dense-evolution
-Version: 8.2.0
+Version: 8.2.1
 Summary: High-performance quantum simulation toolkit -- Statevector/MPS engines with JIT compilation, noise modeling, VQE, QEC, quantum chemistry, and agent-native tooling
 Author-email: Salvatore Pennacchio <jtatopenn@libero.it>
 License: Business Source License 1.1
@@ -64,6 +64,11 @@ Provides-Extra: qmmm
 Requires-Dist: rdkit>=2023.9.1; extra == "qmmm"
 Provides-Extra: ase
 Requires-Dist: ase>=3.22.0; extra == "ase"
+Provides-Extra: rag
+Requires-Dist: scikit-learn>=1.0.0; extra == "rag"
+Requires-Dist: sentence-transformers>=2.2.0; extra == "rag"
+Provides-Extra: armor
+Requires-Dist: dense-armor>=1.1.18; extra == "armor"
 Provides-Extra: full
 Requires-Dist: cupy-cuda12x>=12.0.0; extra == "full"
 Requires-Dist: streamlit>=1.30.0; extra == "full"
@@ -80,6 +85,7 @@ Requires-Dist: httpx>=0.27; extra == "full"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-env>=1.0.0; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: mkdocs>=1.6.0; extra == "docs"
 Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
@@ -343,7 +349,7 @@ If Dense-Evolution is useful in academic work, please cite it via the metadata i
 Archived on [Zenodo](https://zenodo.org/):
 
 - **Concept DOI** (always resolves to the latest version): [10.5281/zenodo.21855643](https://doi.org/10.5281/zenodo.21855643)
-- **This release (v8.1.78)**: [10.5281/zenodo.22706039](https://doi.org/10.5281/zenodo.22706039)
+- **This release (v8.2.0)**: [10.5281/zenodo.22818319](https://doi.org/10.5281/zenodo.22818319)
 
 ---
 

{dense_evolution-8.2.0 → dense_evolution-8.2.1}/README.md

@@ -249,7 +249,7 @@ If Dense-Evolution is useful in academic work, please cite it via the metadata i
 Archived on [Zenodo](https://zenodo.org/):
 
 - **Concept DOI** (always resolves to the latest version): [10.5281/zenodo.21855643](https://doi.org/10.5281/zenodo.21855643)
-- **This release (v8.1.78)**: [10.5281/zenodo.22706039](https://doi.org/10.5281/zenodo.22706039)
+- **This release (v8.2.0)**: [10.5281/zenodo.22818319](https://doi.org/10.5281/zenodo.22818319)
 
 ---
 

{dense_evolution-8.2.0 → dense_evolution-8.2.1}/dense_evolution/__init__.py

@@ -32,6 +32,7 @@ from .mitigation.zne import (richardson_extrapolate, richardson_amplification_fa
                           bounded_exponential_extrapolate,
                           project_to_physical, uhlmann_fidelity, zne_density_matrix,
                           jsd_predictive_zne_density_matrix,
+                          coherence_predictive_zne_density_matrix,
                           richardson_extrapolate_jit, zero_noise_extrapolation_jit,
                           polynomial_extrapolate_jit, uhlmann_fidelity_jit, zne_density_matrix_jit)
 from .circuits.diagram import plot_circuit
@@ -57,7 +58,7 @@ from .physics.qec import (pauli_commutes, compute_syndrome, erasure_aware_decode
                            blind_minimum_weight_decode, decode_with_erasure_fallback,
                            counts_in_intervals_dimension, nearest_coset_decode)
 
-__version__ = "8.1.81"
+__version__ = "8.2.1"
 
 __all__ = [
     "__version__",
@@ -87,7 +88,8 @@ __all__ = [
     "zero_noise_extrapolation", "polynomial_extrapolate",
     "bounded_exponential_extrapolate",
     "project_to_physical", "uhlmann_fidelity", "zne_density_matrix",
-    "jsd_predictive_zne_density_matrix", "global_depolarizing_channel", "amplitude_damping_channel",
+    "jsd_predictive_zne_density_matrix", "coherence_predictive_zne_density_matrix",
+    "global_depolarizing_channel", "amplitude_damping_channel",
     "cosmic_ray_burst_profile", "oscillating_p_eff",
     "richardson_extrapolate_jit", "zero_noise_extrapolation_jit",
     "polynomial_extrapolate_jit", "uhlmann_fidelity_jit", "zne_density_matrix_jit",

{dense_evolution-8.2.0 → dense_evolution-8.2.1}/dense_evolution/mitigation/__init__.py

@@ -13,6 +13,7 @@ from .zne import (
     bounded_exponential_extrapolate,
     project_to_physical, uhlmann_fidelity, zne_density_matrix,
     jsd_predictive_zne_density_matrix,
+    coherence_predictive_zne_density_matrix,
     richardson_extrapolate_jit, zero_noise_extrapolation_jit,
     polynomial_extrapolate_jit, uhlmann_fidelity_jit, zne_density_matrix_jit,
 )
@@ -36,6 +37,7 @@ __all__ = [
     "bounded_exponential_extrapolate",
     "project_to_physical", "uhlmann_fidelity", "zne_density_matrix",
     "jsd_predictive_zne_density_matrix",
+    "coherence_predictive_zne_density_matrix",
     "richardson_extrapolate_jit", "zero_noise_extrapolation_jit",
     "polynomial_extrapolate_jit", "uhlmann_fidelity_jit", "zne_density_matrix_jit",
     "calculate_advanced_sigma", "calculate_phi_ab", "calculate_vettore_dinamico",

{dense_evolution-8.2.0 → dense_evolution-8.2.1}/dense_evolution/mitigation/zne.py

@@ -836,3 +836,98 @@ def _jsd_predictive_zne_density_matrix_core(rho_at_scales: jnp.ndarray, nudge_sc
     c3 = 1.0 - nudge_scale * rectified
     extrapolated = (c1 * e_l1 + c2 * e_l2 + c3 * e_l3) / (c1 + c2 + c3)
     return project_to_physical(extrapolated)
+
+
+def _coherence_l1(rho: jnp.ndarray) -> jnp.ndarray:
+    """l1-norm of coherence (Baumgratz, Cramer & Plenio, Phys. Rev. Lett.
+    113, 140401, 2014): the sum of the magnitudes of every off-diagonal
+    density-matrix entry. A standard, basis-dependent measure of how much
+    quantum coherence a state carries in the computational basis --
+    unlike `_js_divergence`, which only ever sees the diagonal
+    (populations), this is sensitive to exactly what dephasing destroys."""
+    n = rho.shape[0]
+    return jnp.sum(jnp.abs(rho) * (1.0 - jnp.eye(n, dtype=rho.dtype)))
+
+
+def coherence_predictive_zne_density_matrix(rho_at_scales, noise_factors) -> jnp.ndarray:
+    """Density-matrix ZNE with a coherence-informed coefficient nudge --
+    the same adaptive-nonlinearity mechanism as
+    `jsd_predictive_zne_density_matrix`, but signaled by the l1-norm of
+    coherence (`_coherence_l1`) instead of the Jensen-Shannon divergence
+    of the diagonal populations.
+
+    Motivation: `jsd_predictive_zne_density_matrix`'s signal is the
+    density-matrix diagonal only. Any purely dephasing-type noise
+    (phase-flip, or a coherent Z-axis over-rotation) is diagonal in the
+    computational basis -- it moves phase, never populations -- so that
+    signal is blind to it BY CONSTRUCTION, not merely weak: verified
+    directly in Dense-Evolution-Discovery's
+    scripts/jsd_zne_noise_generalization.py, the fidelity delta from the
+    classical-JSD nudge is exactly 0.0 at every tested phase-flip noise
+    strength and every tested coherent-rotation angle. A quantum-JSD
+    variant (von Neumann entropy of the full density matrix instead of
+    Shannon entropy of the diagonal) was tried there too and rejected: it
+    weakens the already-working amplitude-damping/combined-noise case
+    without fixing the coherent-error case, since a smooth deterministic
+    function of the noise-scale factor has `jsd_12~=jsd_23` regardless of
+    which divergence measures it -- the nonlinearity trigger this whole
+    family of methods relies on is structurally near-zero there no
+    matter the signal.
+
+    Validated scope, checked directly rather than assumed universal: real
+    effect on phase-flip/dephasing-dominated noise for `base_p<=0.10`;
+    NOT validated (and not claimed) for amplitude-damping-dominated noise
+    (use `jsd_predictive_zne_density_matrix` there instead) or for
+    coherent/deterministic errors (out of reach for this entire family of
+    methods, not just this signal -- see above).
+
+    Verified at 200 independent seeds on phase-flip noise (GHZ(4),
+    `base_p=0.05`, K=150 trajectories/scale) before promotion: the nudge
+    activates (rectified nonlinearity > 0) on 63/200 seeds (31.5%) --
+    among those, 63/63 improve over plain `zne_density_matrix`, mean
+    fidelity gain +0.014892, one-sample t-test against zero
+    p=1.07e-08, a 20000-resample permutation test finding no resample
+    matching or exceeding the observed effect (p<0.00005). Confirmed
+    across a noise-level sweep (100 seeds/level, GHZ(4)): significant by
+    both tests, 100% win rate among active points, at base_p in (0.03,
+    0.05, 0.08, 0.10); NOT significant at base_p=0.15 (p=0.288 t-test,
+    p=0.301 permutation) -- a real, honest upper boundary, not a
+    universal effect at any noise strength. Confirmed on a second circuit
+    family (hardware-efficient VQE-style ansatz, 2 layers) at
+    `base_p=0.05`: 69/150 active (46%, a higher activation rate than
+    GHZ), 67/69 positive, p=4.4e-06 -- the effect is not GHZ-specific.
+    When inactive, reduces EXACTLY to `zne_density_matrix` at 3
+    equally-spaced scales (verified: max deviation ~1e-8, floating-point
+    noise) -- zero risk in that regime, by construction, the same safety
+    property `jsd_predictive_zne_density_matrix` has.
+
+    Only defined for exactly 3 equally-spaced noise factors (1x, 2x, 3x),
+    same restriction and reason as `jsd_predictive_zne_density_matrix`:
+    the Lagrange coefficients (3, -3, 1) this nudges are specific to that
+    spacing."""
+    rho_at_scales = jnp.asarray(rho_at_scales, dtype=jnp.complex128)
+    noise_factors = jnp.asarray(noise_factors, dtype=jnp.float64)
+    if noise_factors.shape[0] != 3:
+        raise NotImplementedError(
+            "coherence_predictive_zne_density_matrix is only defined for exactly 3 noise "
+            "factors; call zne_density_matrix(...) directly for the plain N-point case."
+        )
+    return _coherence_predictive_zne_density_matrix_core(rho_at_scales)
+
+
+def _coherence_predictive_zne_density_matrix_core(rho_at_scales: jnp.ndarray, nudge_scale: float = 0.5) -> jnp.ndarray:
+    """`jax.jit`-traceable core of `coherence_predictive_zne_density_matrix`
+    -- `rho_at_scales` already complex128. See the public wrapper's
+    docstring for the method and its validation."""
+    c1_, c2_, c3_ = (_coherence_l1(rho_at_scales[i]) for i in range(3))
+    gap_12 = jnp.abs(c1_ - c2_)
+    gap_23 = jnp.abs(c2_ - c3_)
+    nonlinearity = (gap_23 - gap_12) / (gap_23 + gap_12 + 1e-12)
+    rectified = jnp.maximum(nonlinearity, 0.0)
+
+    e_l1, e_l2, e_l3 = rho_at_scales[0], rho_at_scales[1], rho_at_scales[2]
+    c1 = 3.0 - nudge_scale * rectified
+    c2 = -3.0 + 2.0 * nudge_scale * rectified
+    c3 = 1.0 - nudge_scale * rectified
+    extrapolated = (c1 * e_l1 + c2 * e_l2 + c3 * e_l3) / (c1 + c2 + c3)
+    return project_to_physical(extrapolated)

{dense_evolution-8.2.0 → dense_evolution-8.2.1}/dense_evolution/native_hf/scf.py

@@ -90,6 +90,7 @@ import dataclasses
 import functools
 
 import jax
+import numpy as np
 import jax.numpy as jnp
 
 from dense_evolution.config import ensure_x64
@@ -107,6 +108,7 @@ class HFResult:
     orbital_energies: jax.Array
     orbital_coefficients: jax.Array  # C, shape (n_basis, n_basis)
     density_matrix: jax.Array
+    energy_history: jax.Array  # shape (max_iterations,), NaN past n_iterations
 
 
 def nuclear_repulsion_energy(nuclear_charges: list[float], nuclear_positions: jax.Array) -> jax.Array:
@@ -231,11 +233,11 @@ def run_scf(
         return F, energy
 
     def cond_fun(state):
-        iteration, _P, _C, _orbital_energies, _energy_prev, converged, _fock_history, _error_history = state
+        iteration, _P, _C, _orbital_energies, _energy_prev, converged, _fock_history, _error_history, _energy_history = state
         return jnp.logical_and(jnp.logical_not(converged), iteration < max_iterations)
 
     def body_fun(state):
-        iteration, P, C_prev, _orbital_energies, energy_prev, _converged, fock_history, error_history = state
+        iteration, P, C_prev, _orbital_energies, energy_prev, _converged, fock_history, error_history, energy_history = state
 
         F, energy = _fock_and_energy(P)
         error = _diis_error(F, P, S, X)
@@ -262,7 +264,9 @@ def run_scf(
         P_damped = jnp.where(history_count < 2, damping * P_new + (1.0 - damping) * P, P_new)
         P_next = jnp.where(converged, P_new, P_damped)
 
-        return (iteration + 1, P_next, C, orbital_energies, energy, converged, fock_history, error_history)
+        energy_history = energy_history.at[iteration].set(energy)
+
+        return (iteration + 1, P_next, C, orbital_energies, energy, converged, fock_history, error_history, energy_history)
 
     init_state = (
         jnp.array(0),
@@ -273,8 +277,9 @@ def run_scf(
         jnp.array(False),
         jnp.zeros((diis_dim, n_basis, n_basis), dtype=H_core.dtype),
         jnp.zeros((diis_dim, n_basis, n_basis), dtype=H_core.dtype),
+        jnp.full((max_iterations,), jnp.nan, dtype=H_core.dtype),
     )
-    iteration, P, C, orbital_energies, _energy_prev, converged, _fh, _eh = jax.lax.while_loop(cond_fun, body_fun, init_state)
+    iteration, P, C, orbital_energies, _energy_prev, converged, _fh, _eh, energy_history = jax.lax.while_loop(cond_fun, body_fun, init_state)
 
     _F, electronic_energy = _fock_and_energy(P)
     e_nuc = nuclear_repulsion_energy(nuclear_charges, nuclear_positions)
@@ -288,9 +293,51 @@ def run_scf(
         orbital_energies=orbital_energies,
         orbital_coefficients=C,
         density_matrix=P,
+        energy_history=energy_history,
     )
 
 
+def _import_dense_armor_robust_filters():
+    try:
+        from dense_armor.utility.robust_filters import hampel_filter, tukey_fences
+    except ImportError as exc:
+        raise ImportError(
+            "native_hf.scf.diagnose_convergence needs Dense-Armor (pip install dense-evolution[armor])"
+        ) from exc
+    return hampel_filter, tukey_fences
+
+
+def diagnose_convergence(result: HFResult, radius: int = 5, n_sigmas: float = 3.0) -> dict:
+    """Real automatic guard on HFResult.energy_history, instead of trusting
+    the final `converged` flag in isolation: Dense-Armor's Hampel filter
+    and Tukey fences (dense_evolution.utility.robust_filters -- the sister
+    project's own anomaly detectors, Chauvenet/Tukey/Hampel/sigma-clipping,
+    validated with 0 false positives on real H2 dissociation-curve
+    chemistry) applied to the real per-iteration electronic energy trace.
+
+    Validated on a real non-converging case (a 28-heavy-atom CASMI26
+    fragment, level_shift=0.0): the broken run flags 19-24% of its 200
+    iterations as anomalous; the same fragment fixed with level_shift=0.5
+    (converges in 55 iterations) flags only ~4% -- background noise, not a
+    false-alarm storm. Needs the `armor` extra (pip install
+    dense-evolution[armor]) -- Dense-Armor is not a hard dependency of this
+    module."""
+    hampel_filter, tukey_fences = _import_dense_armor_robust_filters()
+    trace = np.asarray(result.energy_history[:result.n_iterations])
+    n = max(1, result.n_iterations)
+
+    _cleaned_h, anomalies_h = hampel_filter(trace, radius=radius, n_sigmas=n_sigmas)
+    _cleaned_t, anomalies_t = tukey_fences(trace, radius=len(trace))
+
+    return {
+        "n_iterations": result.n_iterations,
+        "n_anomalies_hampel": len(anomalies_h),
+        "n_anomalies_tukey": len(anomalies_t),
+        "anomaly_fraction_hampel": len(anomalies_h) / n,
+        "anomaly_fraction_tukey": len(anomalies_t) / n,
+    }
+
+
 @functools.partial(jax.custom_vjp, nondiff_argnums=(3,))
 def scf_electronic_energy(S: jax.Array, H_core: jax.Array, repulsion: jax.Array, n_electrons: int) -> jax.Array:
     """The RHF electronic energy (run_scf's own `electronic_energy`, not

dense_evolution-8.2.1/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-8.2.0 → dense_evolution-8.2.1}/dense_evolution.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dense-evolution
-Version: 8.2.0
+Version: 8.2.1
 Summary: High-performance quantum simulation toolkit -- Statevector/MPS engines with JIT compilation, noise modeling, VQE, QEC, quantum chemistry, and agent-native tooling
 Author-email: Salvatore Pennacchio <jtatopenn@libero.it>
 License: Business Source License 1.1
@@ -64,6 +64,11 @@ Provides-Extra: qmmm
 Requires-Dist: rdkit>=2023.9.1; extra == "qmmm"
 Provides-Extra: ase
 Requires-Dist: ase>=3.22.0; extra == "ase"
+Provides-Extra: rag
+Requires-Dist: scikit-learn>=1.0.0; extra == "rag"
+Requires-Dist: sentence-transformers>=2.2.0; extra == "rag"
+Provides-Extra: armor
+Requires-Dist: dense-armor>=1.1.18; extra == "armor"
 Provides-Extra: full
 Requires-Dist: cupy-cuda12x>=12.0.0; extra == "full"
 Requires-Dist: streamlit>=1.30.0; extra == "full"
@@ -80,6 +85,7 @@ Requires-Dist: httpx>=0.27; extra == "full"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-env>=1.0.0; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: mkdocs>=1.6.0; extra == "docs"
 Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
@@ -343,7 +349,7 @@ If Dense-Evolution is useful in academic work, please cite it via the metadata i
 Archived on [Zenodo](https://zenodo.org/):
 
 - **Concept DOI** (always resolves to the latest version): [10.5281/zenodo.21855643](https://doi.org/10.5281/zenodo.21855643)
-- **This release (v8.1.78)**: [10.5281/zenodo.22706039](https://doi.org/10.5281/zenodo.22706039)
+- **This release (v8.2.0)**: [10.5281/zenodo.22818319](https://doi.org/10.5281/zenodo.22818319)
 
 ---
 

{dense_evolution-8.2.0 → dense_evolution-8.2.1}/dense_evolution.egg-info/SOURCES.txt

@@ -109,6 +109,7 @@ dense_evolution/solvers/harrison_tb.py
 dense_evolution/solvers/vhd_tb.py
 dense_evolution/utils/__init__.py
 dense_evolution/utils/drawing.py
+dense_evolution/utils/mass_decomposition.py
 dense_evolution/utils/measurement.py
 research/local_site/__init__.py
 research/local_site/app/__init__.py
@@ -133,6 +134,7 @@ tools/dashboard/core/vqe.py
 tools/dashboard/core/wormhole.py
 tools/ia_utils/__init__.py
 tools/ia_utils/adversarial_vector_attack.py
+tools/ia_utils/rag.py
 tools/ia_utils/vector_healing.py
 tools/mcp_server/__init__.py
 tools/mcp_server/client.py

{dense_evolution-8.2.0 → dense_evolution-8.2.1}/dense_evolution.egg-info/requires.txt

@@ -5,6 +5,9 @@ scipy>=1.9.0
 jax>=0.4.0
 jaxlib>=0.4.0
 
+[armor]
+dense-armor>=1.1.18
+
 [ase]
 ase>=3.22.0
 
@@ -24,6 +27,7 @@ plotly>=5.0.0
 [dev]
 pytest>=7.0.0
 pytest-cov>=4.0.0
+pytest-env>=1.0.0
 
 [docs]
 mkdocs>=1.6.0
@@ -78,5 +82,9 @@ qiskit>=1.0.0
 [qmmm]
 rdkit>=2023.9.1
 
+[rag]
+scikit-learn>=1.0.0
+sentence-transformers>=2.2.0
+
 [stim]
 stim>=1.13.0