dense-evolution 8.3.0__py3-none-win_amd64.whl

dashboard_core/qasm_library.py

@@ -0,0 +1,233 @@
+"""
+Real, standard OpenQASM 2.0 circuits offered as Composer presets --
+textbook examples (Bell pair, GHZ, W-state) and dense_evolution's own
+real circuit generators (QFT, random circuit), not synthetic results.
+The Composer runs every one of these through the real engine just like
+any custom circuit typed in by hand.
+"""
+
+import dense_evolution as de
+
+from ._gate_tables import (
+    _ONE_QUBIT_STATIC, _ONE_QUBIT_PARAM, _TWO_QUBIT_STATIC,
+    _TWO_QUBIT_PARAM, _THREE_QUBIT_STATIC,
+)
+
+__all__ = ['QASM_LIBRARY', 'gate_tuples_to_qasm']
+
+
+def gate_tuples_to_qasm(ops, n_qubits: int, measure: bool = True) -> str:
+    """Converts a dense_evolution gate-tuple circuit (the format
+    de.qft/de.ghz_state/de.random_circuit/... all return) into real
+    OpenQASM 2.0 text, so any of dense_evolution's own circuit generators
+    can be offered as a Composer preset without hand-transcribing gates.
+
+    Examples
+    --------
+    >>> import dense_evolution as de
+    >>> from dashboard_core.qasm_library import gate_tuples_to_qasm
+    >>> gate_tuples_to_qasm([('h', 0), ('cx', 0, 1)], n_qubits=2)
+    'OPENQASM 2.0;\\ninclude "qelib1.inc";\\nqreg q[2];\\ncreg c[2];\\nh q[0];\\ncx q[0],q[1];\\nmeasure q -> c;\\n'
+    >>> qft_ops = de.qft(3)
+    >>> print(gate_tuples_to_qasm(qft_ops, n_qubits=3))  # doctest: +NORMALIZE_WHITESPACE
+    OPENQASM 2.0;
+    include "qelib1.inc";
+    qreg q[3];
+    creg c[3];
+    h q[0];
+    cp(1.5707963267948966) q[1],q[0];
+    cp(0.7853981633974483) q[2],q[0];
+    h q[1];
+    cp(1.5707963267948966) q[2],q[1];
+    h q[2];
+    swap q[0],q[2];
+    measure q -> c;
+    """
+    lines = ['OPENQASM 2.0;', 'include "qelib1.inc";', f'qreg q[{n_qubits}];']
+    if measure:
+        lines.append(f'creg c[{n_qubits}];')
+    for op in ops:
+        name = op[0]
+        if name in _ONE_QUBIT_STATIC:
+            lines.append(f'{name} q[{op[1]}];')
+        elif name in _ONE_QUBIT_PARAM:
+            lines.append(f'{name}({op[2]}) q[{op[1]}];')
+        elif name in _TWO_QUBIT_STATIC:
+            lines.append(f'{name} q[{op[1]}],q[{op[2]}];')
+        elif name in _TWO_QUBIT_PARAM:
+            lines.append(f'{name}({op[3]}) q[{op[1]}],q[{op[2]}];')
+        elif name in _THREE_QUBIT_STATIC:
+            lines.append(f'{name} q[{op[1]}],q[{op[2]}],q[{op[3]}];')
+        else:
+            raise ValueError(f"gate_tuples_to_qasm: unrecognized gate {name!r}")
+    if measure:
+        lines.append('measure q -> c;')
+    return '\n'.join(lines) + '\n'
+
+
+QASM_LIBRARY = {
+    "Bell state (2 qubit)": (
+        'OPENQASM 2.0;\ninclude "qelib1.inc";\n'
+        'qreg q[2];\ncreg c[2];\n'
+        'h q[0];\ncx q[0],q[1];\n'
+        'measure q -> c;\n'
+    ),
+    "GHZ state (3 qubit)": gate_tuples_to_qasm(de.ghz_state(3), 3),
+    "GHZ state (4 qubit)": gate_tuples_to_qasm(de.ghz_state(4), 4),
+    "Superposition (1 qubit)": (
+        'OPENQASM 2.0;\ninclude "qelib1.inc";\n'
+        'qreg q[1];\ncreg c[1];\n'
+        'h q[0];\n'
+        'measure q -> c;\n'
+    ),
+    "W state (3 qubit)": (
+        # Standard 3-qubit W-state construction: RY splits the single
+        # excitation's amplitude, a controlled-Hadamard (decomposed into
+        # ry-cx-ry -- dense_evolution has no native CH gate) spreads it
+        # further, then two CX cascade it across all three qubits.
+        # Verified against the real engine: (|001>+|010>+|100>)/sqrt(3),
+        # each with probability 1/3.
+        'OPENQASM 2.0;\ninclude "qelib1.inc";\n'
+        'qreg q[3];\ncreg c[3];\n'
+        'ry(1.9106332362490184) q[0];\n'
+        'ry(0.7853981633974483) q[1];\n'
+        'cx q[0],q[1];\n'
+        'ry(-0.7853981633974483) q[1];\n'
+        'cx q[1],q[2];\n'
+        'cx q[0],q[1];\n'
+        'x q[0];\n'
+        'measure q -> c;\n'
+    ),
+    "Quantum Fourier Transform (3 qubit)": gate_tuples_to_qasm(de.qft(3), 3),
+    "Random circuit (3 qubit, fixed seed)": gate_tuples_to_qasm(
+        de.random_circuit(3, 8, seed=7), 3,
+    ),
+    "Entangling linear (5 qubit, chain topology)": gate_tuples_to_qasm(
+        [("h", q) for q in range(5)] + de.entangling_layer(5, pattern="linear"), 5,
+    ),
+    "Entangling ring (5 qubit, circular topology)": gate_tuples_to_qasm(
+        [("h", q) for q in range(5)] + de.entangling_layer(5, pattern="circular"), 5,
+    ),
+    "Entangling full (5 qubit, all-to-all topology)": gate_tuples_to_qasm(
+        [("h", q) for q in range(5)] + de.entangling_layer(5, pattern="full"), 5,
+    ),
+    "Entangling star (5 qubit, hub topology)": gate_tuples_to_qasm(
+        [("h", q) for q in range(5)] + de.entangling_layer(5, pattern="star"), 5,
+    ),
+    "Entangling brick (5 qubit, brickwork topology)": gate_tuples_to_qasm(
+        [("h", q) for q in range(5)] + de.entangling_layer(5, pattern="brick"), 5,
+    ),
+    "GHZ state (8 qubit)": gate_tuples_to_qasm(de.ghz_state(8), 8),
+    "Random circuit (5 qubit, fixed seed)": gate_tuples_to_qasm(
+        de.random_circuit(5, 12, seed=13), 5,
+    ),
+    "Grover search (3 qubit, target |111>)": (
+        # Real Grover's algorithm: uniform superposition, a CCZ oracle
+        # (via H-CCX-H) marking |111>, then the standard diffuser. One
+        # iteration is optimal for N=8/1 marked state. Verified against
+        # the real engine: P(|111>) = 0.78125, matching the theoretical
+        # sin^2(3*arcsin(1/sqrt(8))) amplitude exactly; all other 7
+        # states share the remaining probability uniformly.
+        'OPENQASM 2.0;\ninclude "qelib1.inc";\n'
+        'qreg q[3];\ncreg c[3];\n'
+        'h q[0];\nh q[1];\nh q[2];\nbarrier q;\n'
+        'h q[2];\nccx q[0],q[1],q[2];\nh q[2];\nbarrier q;\n'
+        'h q[0];\nh q[1];\nh q[2];\n'
+        'x q[0];\nx q[1];\nx q[2];\n'
+        'h q[2];\nccx q[0],q[1],q[2];\nh q[2];\n'
+        'x q[0];\nx q[1];\nx q[2];\n'
+        'h q[0];\nh q[1];\nh q[2];\n'
+        'barrier q;\nmeasure q -> c;\n'
+    ),
+    "Deutsch-Jozsa (balanced oracle, 2+1 qubit)": (
+        # Real Deutsch-Jozsa: oracle f(x0,x1) = x0 XOR x1 (balanced).
+        # Verified: the input register (q0,q1) never measures |00>, the
+        # correct signature of a balanced function (a constant function
+        # would collapse the input register to |00> with certainty).
+        'OPENQASM 2.0;\ninclude "qelib1.inc";\n'
+        'qreg q[3];\ncreg c[3];\n'
+        'h q[0];\nh q[1];\nx q[2];\nh q[2];\n'
+        'cx q[0],q[2];\ncx q[1],q[2];\n'
+        'h q[0];\nh q[1];\n'
+        'measure q -> c;\n'
+    ),
+    "Bernstein-Vazirani (secret string 101, 3+1 qubit)": (
+        # Real Bernstein-Vazirani: oracle f(x) = x . s with s = 101.
+        # Verified: input register (q0,q1,q2) measures |101> -- the
+        # secret string -- with certainty, in a single query.
+        'OPENQASM 2.0;\ninclude "qelib1.inc";\n'
+        'qreg q[4];\ncreg c[4];\n'
+        'h q[0];\nh q[1];\nh q[2];\nx q[3];\nh q[3];\n'
+        'cx q[0],q[3];\ncx q[2],q[3];\n'
+        'h q[0];\nh q[1];\nh q[2];\n'
+        'measure q -> c;\n'
+    ),
+    "Toffoli / CCX (T-gate decomposition, 3 qubit)": (
+        # Standard Nielsen & Chuang Toffoli-from-Clifford+T decomposition
+        # (6 CX + 7 T/Tdg + 2 H) -- verified against the engine's native
+        # ccx gate on all 8 computational-basis inputs, exact match
+        # (probability 1.0 on the correct output state) every time.
+        'OPENQASM 2.0;\ninclude "qelib1.inc";\n'
+        'qreg q[3];\ncreg c[3];\n'
+        'h q[2];\n'
+        'cx q[1],q[2];\ntdg q[2];\n'
+        'cx q[0],q[2];\nt q[2];\n'
+        'cx q[1],q[2];\ntdg q[2];\n'
+        'cx q[0],q[2];\n'
+        't q[1];\nt q[2];\nh q[2];\n'
+        'cx q[0],q[1];\nt q[0];\ntdg q[1];\n'
+        'cx q[0],q[1];\n'
+        'measure q -> c;\n'
+    ),
+    "Quantum Teleportation (deferred measurement, 3 qubit)": (
+        # Real teleportation of an arbitrary state prepared on q0 (here
+        # ry(0.9), swap in any single-qubit state to teleport a different
+        # one) onto q2, via a Bell pair on q1/q2. Uses the principle of
+        # deferred measurement (Nielsen & Chuang Sec. 4.4): Alice's
+        # classically-controlled X/Z corrections become coherent
+        # controlled gates applied before any measurement, since this
+        # engine's QASM parser doesn't execute if(c==N)-conditioned gates
+        # (see README "Interop" known limits) -- a naive textbook
+        # if(c[1]==1) x q[2]; if(c[0]==1) z q[2]; version would silently
+        # no-op here. Verified against the real engine: the reduced
+        # density matrix on q2 (partial trace over q0,q1) matches the
+        # state originally prepared on q0 with fidelity 1.0000000000,
+        # checked across 5 random states with nontrivial complex phase,
+        # not just this one example angle.
+        'OPENQASM 2.0;\ninclude "qelib1.inc";\n'
+        'qreg q[3];\ncreg c[3];\n'
+        'ry(0.9) q[0];\n'
+        'h q[1];\ncx q[1],q[2];\n'
+        'cx q[0],q[1];\nh q[0];\n'
+        'cx q[1],q[2];\ncz q[0],q[2];\n'
+        'barrier q;\nmeasure q -> c;\n'
+    ),
+    "Quantum Phase Estimation (3-qubit counting, T-gate)": (
+        # Real QPE estimating the phase of the T gate (eigenvalue
+        # e^(i*pi/4), i.e. phase = 1/8) on its |1> eigenstate, using 3
+        # counting qubits (q0,q1,q2) + 1 target (q3). 1/8 = 0.001 in
+        # binary, exactly representable in 3 bits, so a correct QPE gives
+        # one deterministic outcome rather than a spread -- the cleanest
+        # possible check. The controlled-U^(2^k) power assignment
+        # (q0->k=2, q1->k=1, q2->k=0) and the inverse-QFT gate sequence
+        # (swap first, then the H/CP cascade) were both determined
+        # empirically against this engine's specific MSB-first qubit
+        # convention -- a naive textbook assignment/ordering measured a
+        # spread-out, non-deterministic distribution here; the inverse
+        # QFT step is transcribed exactly from dense_evolution.qft(3,
+        # inverse=True), not hand re-derived. Verified: measuring q0q1q2
+        # gives |001> (=1/8) with probability 1.0000, not merely the most
+        # likely outcome.
+        'OPENQASM 2.0;\ninclude "qelib1.inc";\n'
+        'qreg q[4];\ncreg c[3];\n'
+        'x q[3];\n'
+        'h q[0];\nh q[1];\nh q[2];\n'
+        'cp(pi) q[0],q[3];\ncp(pi/2) q[1],q[3];\ncp(pi/4) q[2],q[3];\n'
+        'swap q[0],q[2];\n'
+        'h q[2];\ncp(-pi/2) q[2],q[1];\n'
+        'h q[1];\ncp(-pi/4) q[2],q[0];\ncp(-pi/2) q[1],q[0];\n'
+        'h q[0];\n'
+        'barrier q;\n'
+        'measure q[0] -> c[0];\nmeasure q[1] -> c[1];\nmeasure q[2] -> c[2];\n'
+    ),
+}

dashboard_core/qmmm.py

@@ -0,0 +1,16 @@
+"""
+Backward-compatibility re-export. The real implementation moved to
+dense_evolution.qmmm.forces (Dense-Evolution issue #283 -- qmmm now lives
+in the library, alongside real QM/MM region partitioning/embedding,
+instead of being buried inside the dashboard tool). Nothing in dashboard
+code needed to change: `from dashboard_core.qmmm import ...` still works.
+"""
+from dense_evolution.qmmm.forces import (
+    ATOMIC_MASSES_AMU, compute_hellmann_feynman_forces, md_step, run_md_trajectory,
+    MIN_NUCLEAR_DISTANCE_ANGSTROM, ACCEL_CONVERSION, _assert_no_nuclear_collision,
+)
+
+__all__ = [
+    'ATOMIC_MASSES_AMU', 'compute_hellmann_feynman_forces', 'md_step', 'run_md_trajectory',
+    'MIN_NUCLEAR_DISTANCE_ANGSTROM', 'ACCEL_CONVERSION',
+]

dashboard_core/rag_tool.py

@@ -0,0 +1,45 @@
+"""
+Thin, stateless Composer-kernel wrapper around ia_utils.rag: builds an
+ephemeral index over the caller's own documents and searches it in one
+call -- nothing persists server-side between requests, same as every
+other kernel endpoint. See docs/api/ia_utils_rag.md for the real
+provenance (promoted from quantumrag) and validated case behind this.
+Needs the `rag` extra (scikit-learn + sentence-transformers).
+"""
+from dataclasses import dataclass
+
+from ia_utils.rag import build_index, search, search_exact
+
+__all__ = ['RagSearchResult', 'run_rag_search']
+
+
+@dataclass
+class RagSearchResult:
+    results: list
+
+
+def run_rag_search(documents, query: str, top: int = 5, rerank: bool = True,
+                    exact: bool = False, regex: bool = False,
+                    max_hits: int = 10, context: int = 300) -> RagSearchResult:
+    """Build an ephemeral index over `documents` ([(text, source), ...])
+    and search it for `query` in one call, in one of two modes:
+
+    exact=False (default): hybrid semantic search -- pools candidates from
+    TF-IDF cosine similarity and a dense bi-encoder, then re-scores the
+    pool with a cross-encoder if rerank=True (Karpukhin et al. 2020 /
+    Nogueira & Cho 2019); rerank=False skips the dense pool and
+    cross-encoder, a plain TF-IDF ranking. Result dicts carry `rank`,
+    `source`, `score`, `score_type`, `cosine`, `text`.
+
+    exact=True: substring/regex search over raw chunk text instead --
+    no embedding, no reranker, no model download. Use this when semantic
+    ranking buries a short, specific, load-bearing phrase (an exact
+    clause, a fixed parameter value) under topically-similar-but-wrong
+    chunks. `query` is the literal substring (case-insensitive) unless
+    regex=True, in which case it's a real, case-sensitive regex. Result
+    dicts carry `source`, `chunk_index`, `match`, `snippet`, `start`, `end`.
+    """
+    index = build_index(documents, compute_embeddings=not exact)
+    if exact:
+        return RagSearchResult(results=search_exact(query, index, regex=regex, max_hits=max_hits, context=context))
+    return RagSearchResult(results=search(query, index, top=top, rerank=rerank))

dashboard_core/state_visuals.py

@@ -0,0 +1,288 @@
+"""
+Native statevector visualizations -- histogram, Q-sphere, per-qubit Bloch
+spheres -- pure matplotlib/numpy, no Qiskit anywhere. Replaces
+qiskit.visualization.{plot_histogram, plot_state_qsphere,
+plot_bloch_multivector}, the last three real Qiskit call sites in this
+project's dashboard (the circuit diagram itself was already native, see
+circuit_diagram.py's own docstring for why that mattered on macOS).
+Qiskit's own instability on macOS CI runners was never proven scoped to
+just QuantumCircuit -- no reason the plotting functions built on top of
+it are exempt -- so removing them entirely, not just making qiskit
+optional, is the actual fix.
+
+All inputs use Qiskit's little-endian bit convention (qubit 0 = least
+significant bit of the statevector index), matching
+dashboard_core.engine's own SimulationResult.statevector -- the same
+convention plot_state_qsphere/plot_bloch_multivector assumed.
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+from mpl_toolkits.mplot3d import Axes3D  # noqa: F401 -- registers the '3d' projection
+
+__all__ = ['native_histogram_figure', 'native_qsphere_figure', 'native_bloch_multivector_figure']
+
+_BLOCH_COLOR = "#4589ff"
+_QSPHERE_LINE_COLOR = "#8d8d8d"
+
+
+def native_histogram_figure(counts: dict, statevector=None):
+    """Bar chart of shot counts, bitstrings sorted ascending -- the same
+    information qiskit.visualization.plot_histogram showed, built from
+    nothing but the counts dict itself.
+
+    statevector (optional): when given, each bar is colored by the
+    complex phase of that basis state's amplitude (same HSV cyclic
+    colormap and convention as native_qsphere_figure's own phase
+    coloring) instead of the flat default color -- a state's phase is
+    real physical information invisible in a bare shot-count bar
+    otherwise. statevector must be in the same Qiskit little-endian
+    convention as `counts`' own bitstrings (see module docstring).
+
+    Examples
+    --------
+    >>> from dashboard_core.state_visuals import native_histogram_figure
+    >>> fig = native_histogram_figure({'00': 512, '11': 488})
+    >>> type(fig).__name__
+    'Figure'
+    """
+    states = sorted(counts.keys())
+    values = [counts[s] for s in states]
+    total = sum(values)
+
+    fig, ax = plt.subplots(figsize=(max(4, 0.5 * len(states)), 4))
+    if statevector is not None:
+        phases = np.angle([statevector[int(s, 2)] for s in states])
+        cmap = plt.get_cmap("hsv")
+        colors = cmap((phases % (2 * np.pi)) / (2 * np.pi))
+        bars = ax.bar(states, values, color=colors)
+        sm = plt.cm.ScalarMappable(cmap=cmap, norm=plt.Normalize(0, 2 * np.pi))
+        sm.set_array([])
+        cbar = fig.colorbar(sm, ax=ax, shrink=0.8, pad=0.02)
+        cbar.set_ticks([0, np.pi / 2, np.pi, 3 * np.pi / 2, 2 * np.pi])
+        cbar.set_ticklabels(["0", "π/2", "π", "3π/2", "2π"])
+        cbar.set_label("phase", fontsize=8)
+    else:
+        bars = ax.bar(states, values, color="#648fff")
+    ax.set_ylabel("Counts")
+    ax.set_ylim(0, max(values) * 1.15 if values else 1)
+    for bar, v in zip(bars, values):
+        pct = 100 * v / total if total else 0
+        ax.annotate(
+            f"{v}\n({pct:.1f}%)", xy=(bar.get_x() + bar.get_width() / 2, bar.get_height()),
+            xytext=(0, 3), textcoords="offset points", ha="center", va="bottom", fontsize=8,
+        )
+    if len(states) > 8:
+        plt.setp(ax.get_xticklabels(), rotation=60, ha="right")
+    fig.tight_layout()
+    return fig
+
+
+def _reduced_density_matrix(statevector: np.ndarray, n_qubits: int, qubit: int) -> np.ndarray:
+    """Partial trace over every qubit except `qubit`, in Qiskit's
+    little-endian convention (qubit 0 = LSB of the flat index).
+    np.reshape's default C order puts the LSB on the *last* tensor axis,
+    so qubit q lives on axis (n_qubits-1-q) -- moved to the front, then
+    the remaining axes are flattened into one "everything else" axis and
+    traced out via M @ M^dagger. Verified directly against a Bell pair:
+    each qubit's reduced state comes back exactly I/2 (maximally mixed),
+    the known analytic answer for a maximally entangled 2-qubit state.
+
+    Deliberately NOT dense_evolution.physics.entropy.partial_trace (prog.txt,
+    dashboard_core audit point 1c): that function is MSB-first (qubit 0 =
+    most significant bit, this project's own native convention everywhere
+    else), single-qubit-only here needs the opposite, Qiskit-matching
+    little-endian layout, since this feeds the Bloch-sphere/Q-sphere
+    panels that display in Qiskit's own bit order (see engine.py's
+    SimulationResult docstring: "statevector, Qiskit bit order"). Two
+    genuinely different conventions for two different consumers, not an
+    accidental reimplementation -- kept separate rather than adding a
+    bit_order flag to the core function for a dashboard-only need.
+    """
+    tensor = statevector.reshape((2,) * n_qubits)
+    axis = n_qubits - 1 - qubit
+    m = np.moveaxis(tensor, axis, 0).reshape(2, -1)
+    return m @ m.conj().T
+
+
+def _bloch_vector(rho: np.ndarray) -> np.ndarray:
+    """(bx, by, bz) from a single-qubit density matrix, via
+    rho = 0.5*(I + bx*X + by*Y + bz*Z) inverted: bx=2*Re(rho01),
+    by=-2*Im(rho01), bz=rho00-rho11."""
+    bx = 2 * np.real(rho[0, 1])
+    by = -2 * np.imag(rho[0, 1])
+    bz = np.real(rho[0, 0] - rho[1, 1])
+    return np.array([bx, by, bz])
+
+
+def _draw_bloch_sphere(ax, vector, title):
+    u, v = np.mgrid[0:2 * np.pi:24j, 0:np.pi:12j]
+    xs = np.cos(u) * np.sin(v)
+    ys = np.sin(u) * np.sin(v)
+    zs = np.cos(v)
+    ax.plot_wireframe(xs, ys, zs, color="#d0d0d0", linewidth=0.4)
+    ax.plot([-1, 1], [0, 0], [0, 0], color="#d0d0d0", linewidth=0.6)
+    ax.plot([0, 0], [-1, 1], [0, 0], color="#d0d0d0", linewidth=0.6)
+    ax.plot([0, 0], [0, 0], [-1, 1], color="#d0d0d0", linewidth=0.6)
+    ax.text(0, 0, 1.15, "|0⟩", ha="center", fontsize=8)
+    ax.text(0, 0, -1.3, "|1⟩", ha="center", fontsize=8)
+    ax.quiver(0, 0, 0, *vector, color=_BLOCH_COLOR, linewidth=2, arrow_length_ratio=0.15)
+    ax.set_title(title, fontsize=9)
+    ax.set_box_aspect([1, 1, 1])
+    ax.set_xlim(-1, 1); ax.set_ylim(-1, 1); ax.set_zlim(-1, 1)
+    ax.set_axis_off()
+
+
+def native_bloch_multivector_figure(statevector: np.ndarray):
+    """One Bloch sphere per qubit, each from that qubit's own reduced
+    density matrix (partial trace over every other qubit) -- the same
+    per-qubit view qiskit.visualization.plot_bloch_multivector showed,
+    computed directly from the real statevector, no Qiskit involved.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from dashboard_core.state_visuals import native_bloch_multivector_figure
+    >>> bell = np.array([1, 0, 0, 1]) / np.sqrt(2)
+    >>> fig = native_bloch_multivector_figure(bell)
+    >>> type(fig).__name__
+    'Figure'
+    """
+    n_qubits = int(np.log2(len(statevector)))
+    fig = plt.figure(figsize=(3 * n_qubits, 3.2))
+    for q in range(n_qubits):
+        rho = _reduced_density_matrix(statevector, n_qubits, q)
+        vector = _bloch_vector(rho)
+        ax = fig.add_subplot(1, n_qubits, q + 1, projection="3d")
+        _draw_bloch_sphere(ax, vector, f"qubit {q}")
+    fig.tight_layout()
+    return fig
+
+
+def _popcount(x: np.ndarray) -> np.ndarray:
+    """Vectorized Hamming weight (bit count) of each element -- a portable
+    SWAR bit-counting trick (numpy int/bitwise ops only), not np.bitwise_
+    count, which needs NumPy >=2.0 (this project declares numpy>=1.22.0).
+    Replaces a `bin(int(i)).count("1")` Python-level loop over indices
+    (prog.txt, dashboard_core audit point 4b) -- real cost at high qubit
+    count with many states above prob_threshold, even though the initial
+    threshold filter itself was already vectorized. Verified to match
+    the Python reference exactly on 5000 random 24-bit values before
+    replacing it."""
+    x = x.astype(np.uint64)
+    x = x - ((x >> np.uint64(1)) & np.uint64(0x5555555555555555))
+    x = (x & np.uint64(0x3333333333333333)) + ((x >> np.uint64(2)) & np.uint64(0x3333333333333333))
+    x = (x + (x >> np.uint64(4))) & np.uint64(0x0f0f0f0f0f0f0f0f)
+    return ((x * np.uint64(0x0101010101010101)) >> np.uint64(56)).astype(np.int64)
+
+
+def native_qsphere_figure(statevector: np.ndarray, prob_threshold: float = 1e-3):
+    """Q-sphere: every basis state with non-negligible probability placed
+    on a sphere by Hamming weight (latitude -- |00...0> at the north pole,
+    |11...1> at the south pole, states of equal weight sharing a ring),
+    marker size by probability, marker color by phase (cyclic colormap,
+    matching Qiskit's own convention) -- the same encoding
+    qiskit.visualization.plot_state_qsphere used, built directly from the
+    statevector's own amplitudes.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from dashboard_core.state_visuals import native_qsphere_figure
+    >>> bell = np.array([1, 0, 0, 1]) / np.sqrt(2)
+    >>> fig = native_qsphere_figure(bell)
+    >>> type(fig).__name__
+    'Figure'
+    """
+    n_qubits = int(np.log2(len(statevector)))
+    probs = np.abs(statevector) ** 2
+    phases = np.angle(statevector)
+
+    # Vectorized threshold: a Python-level loop over `range(len(statevector))`
+    # is O(2**n_qubits) pure-Python overhead regardless of how many states
+    # actually pass -- measured directly, this dominated runtime at 24
+    # qubits (dense's own practical ceiling) even though only a handful of
+    # states end up plotted. np.where does the same filtering in C.
+    indices = np.where(probs > prob_threshold)[0]
+    if len(indices) == 0:
+        # A state spread thin enough that nothing clears prob_threshold
+        # (e.g. a wide random state at high qubit count) -- show the
+        # single most probable state rather than an empty sphere, so
+        # there's always at least one real point plotted.
+        indices = np.array([int(np.argmax(probs))])
+    weights = _popcount(indices)
+
+    # phi (azimuthal position within a weight's ring) needs each point's
+    # rank among same-weight points, in index order -- np.unique's
+    # return_inverse plus a per-group running count gets that without a
+    # Python-level dict-of-lists pass.
+    order = np.argsort(weights, kind="stable")
+    sorted_idx, sorted_w = indices[order], weights[order]
+    group_sizes = np.bincount(sorted_w, minlength=n_qubits + 1)
+    # rank-within-group for each entry in sorted order: 0,1,2,... resets
+    # to 0 at each group boundary. offsets[w] is where weight-w's group
+    # starts in the sorted array (sum of every smaller group's size);
+    # subtracting it from the running global index 0..N-1 gives each
+    # point's position within its own group, e.g. weights [0,1,1,1,2,2,2,3]
+    # -> ranks [0,0,1,2,0,1,2,0] -- verified by hand before use here.
+    offsets = np.concatenate([[0], np.cumsum(group_sizes)[:-1]])
+    rank_within_group = np.arange(len(sorted_idx)) - offsets[sorted_w]
+    counts_per_point = group_sizes[sorted_w]
+
+    theta = np.pi * sorted_w / n_qubits if n_qubits > 0 else np.zeros_like(sorted_w, dtype=float)
+    phi = 2 * np.pi * rank_within_group / counts_per_point
+    xs = np.sin(theta) * np.cos(phi)
+    ys = np.sin(theta) * np.sin(phi)
+    zs = np.cos(theta)
+
+    sorted_probs = probs[sorted_idx]
+    sorted_phases = phases[sorted_idx]
+    cmap = plt.get_cmap("hsv")
+    colors = cmap((sorted_phases % (2 * np.pi)) / (2 * np.pi))
+    sizes = 80 + 1500 * sorted_probs
+
+    fig = plt.figure(figsize=(6, 6))
+    ax = fig.add_subplot(111, projection="3d")
+    u, v = np.mgrid[0:2 * np.pi:36j, 0:np.pi:18j]
+    ax.plot_wireframe(
+        np.cos(u) * np.sin(v), np.sin(u) * np.sin(v), np.cos(v),
+        color="#e0e0e0", linewidth=0.3,
+    )
+
+    # One Line3DCollection for every "stem" (instead of one ax.plot() call
+    # per point) and one ax.scatter() call for every marker (instead of
+    # one per point) -- measured directly: per-point matplotlib artist
+    # calls, not the math above, were the real cost of this function (a
+    # wide random 10-qubit state with 300+ states over prob_threshold took
+    # ~1.4s with the per-point version, regardless of whether text labels
+    # were also being drawn).
+    from mpl_toolkits.mplot3d.art3d import Line3DCollection
+    segments = [[(0, 0, 0), (x, y, z)] for x, y, z in zip(xs, ys, zs)]
+    linewidths = 1.0 + 3 * sorted_probs
+    ax.add_collection3d(Line3DCollection(segments, colors=_QSPHERE_LINE_COLOR, linewidths=linewidths))
+    ax.scatter(xs, ys, zs, s=sizes, color=colors, edgecolor="black", linewidth=0.5, zorder=5)
+
+    # Per-point text labels are unreadable past a few dozen overlapping
+    # entries anyway (a wide random state can push 300+ states over
+    # prob_threshold) -- dropped above this count, keeping the dots/
+    # lines/colors (the actual data) intact.
+    _MAX_LABELS = 32
+    if len(sorted_idx) <= _MAX_LABELS:
+        for idx, x, y, z in zip(sorted_idx, xs, ys, zs):
+            label = format(int(idx), f"0{n_qubits}b")
+            ax.text(x * 1.15, y * 1.15, z * 1.15, f"|{label}⟩", fontsize=7, ha="center")
+
+    ax.set_box_aspect([1, 1, 1])
+    ax.set_xlim(-1, 1); ax.set_ylim(-1, 1); ax.set_zlim(-1, 1)
+    ax.set_axis_off()
+    ax.set_title("Q-sphere (size = probability, color = phase)", fontsize=9)
+
+    sm = plt.cm.ScalarMappable(cmap=cmap, norm=plt.Normalize(0, 2 * np.pi))
+    sm.set_array([])
+    cbar = fig.colorbar(sm, ax=ax, shrink=0.6, pad=0.05)
+    cbar.set_ticks([0, np.pi / 2, np.pi, 3 * np.pi / 2, 2 * np.pi])
+    cbar.set_ticklabels(["0", "π/2", "π", "3π/2", "2π"])
+    cbar.set_label("phase", fontsize=8)
+
+    fig.tight_layout()
+    return fig

dashboard_core/system_limits.py

@@ -0,0 +1,60 @@
+"""
+Real, per-machine qubit limits -- detects actual available RAM instead of
+a number picked to fit whatever machine this was developed on. A modest
+8 GB dev laptop and a 128 GB workstation get genuinely different limits.
+
+Reuses dense_evolution.chunk.get_dynamic_chunk, the same real,
+already-tested RAM-based sizing function the Chunk engine itself uses
+(confirmed in feature/streamlit-dashboard's older simulation_runner.py:
+"Decided by de.Chunk's own dynamic, available-RAM-based sizing... not a
+hardcoded qubit-count constant, so it adapts to the machine it's running
+on") -- rather than a second, slightly different hand-rolled formula.
+The actual safety enforcement (rejecting a request that would genuinely
+overflow RAM) is separate: dashboard_core.engine.run_circuit_from_qasm
+calls dense_evolution.chunk.SafeMemoryGuard.check_allocation directly,
+which has no floor -- this module is only the UI's suggested/default cap.
+"""
+
+import dense_evolution as de
+
+__all__ = ['max_safe_dense_qubits']
+
+
+def max_safe_dense_qubits() -> dict:
+    """Suggested max qubit count for the Composer's Qubits field, from
+    dense_evolution.chunk.get_dynamic_chunk(complex128) -- floor 16,
+    ceiling 30 by that function's own design (a chunk always has *some*
+    minimum useful size, and 30 qubits/~17 GB is its own practical ceiling
+    for a single dense block -- raised from 27 in Dense-Evolution PR #278,
+    which was discarding real headroom on any 16GB+ GPU). MPS's
+    contract_to_statevector has a separate, RAM-independent hard ceiling
+    of 24 qubits; picking 25-30 with the MPS backend surfaces that
+    function's own real error rather than being silently blocked here.
+
+    Returns
+    -------
+    dict
+        `total_mb`/`available_mb` (this machine's real RAM, from
+        `SafeMemoryGuard.status()`), `threshold_pct` (the guard's safety
+        margin), `max_qubits_dense` (the suggested cap -- machine-dependent,
+        not a constant).
+
+    Examples
+    --------
+    >>> from dashboard_core.system_limits import max_safe_dense_qubits
+    >>> limits = max_safe_dense_qubits()
+    >>> sorted(limits.keys())
+    ['available_mb', 'max_qubits_dense', 'threshold_pct', 'total_mb']
+    >>> 16 <= limits['max_qubits_dense'] <= 30
+    True
+    """
+    guard = de.chunk.SafeMemoryGuard()
+    status = guard.status()
+    max_qubits = de.chunk.get_dynamic_chunk(de.chunk.jnp.complex128 if de.chunk.HAS_JAX else de.chunk.np.complex128)
+
+    return {
+        "total_mb": status["total_mb"],
+        "available_mb": status["available_mb"],
+        "threshold_pct": guard.threshold_pct,
+        "max_qubits_dense": max_qubits,
+    }