dense-evolution 8.3.0__py3-none-macosx_11_0_universal2.whl

dashboard_core/__init__.py

@@ -0,0 +1,115 @@
+"""
+dashboard_core -- real compute + visualization layer for app_dashboard.py.
+
+Rebuilt from scratch on the structure of IBM Quantum Composer (circuit
+editor, statevector, probabilities, Q-sphere), wired to dense_evolution's
+actual DenseSVSimulator and to Qiskit's own real visualization functions
+-- no hand-rolled plotting, no synthetic data. The previous dashboard_core
+(VQE, molecular Hamiltonians, mitigation, AI vector-healing) lives intact
+on the feature/streamlit-dashboard and feature/ipywidgets-dash-panel
+branches and will be reintegrated selectively once this base is solid.
+"""
+
+import dense_evolution as _de
+
+
+def enable_dashboard_precision():
+    """Enables float64 precision for the dashboard (prog.txt,
+    dashboard_core audit point 2). dense_evolution no longer forces
+    jax_enable_x64 as an import-time side effect (see
+    dense_evolution/config.py) -- it's enabled lazily, only by the
+    specific call that needs complex128 (e.g. DenseSVSimulator). Some
+    paths here (MPSSimulator-only branches in engine.py, Chunk usage in
+    system_limits.py/wormhole.py) never construct a DenseSVSimulator, so
+    this dashboard -- which always wants float64 -- must set it
+    explicitly rather than relying on that now-removed side effect.
+
+    This used to run as a bare module-level `_de.set_precision(True)`
+    call here, so merely `from dashboard_core.circuit_diagram import
+    draw_native_circuit_diagram` paid the x64-enable cost even though
+    that submodule never touches precision -- exactly the import-time
+    side effect dense_evolution's own config.py was written to eliminate
+    (see its module docstring), just not yet applied one level up here.
+    Call this explicitly from the dashboard's own entry point
+    (tools/dashboard/app.py) instead."""
+    _de.set_precision(True)
+
+from .qasm_library import QASM_LIBRARY, gate_tuples_to_qasm
+from .engine import (
+    SimulationResult, run_circuit_from_qasm,
+    LargeScaleMPSResult, run_large_circuit_mps, MPS_DENSE_CONTRACTION_LIMIT,
+    run_bond_convergence_check,
+)
+from .visuals import (
+    draw_circuit_figure, histogram_figure, qsphere_figure, bloch_multivector_figure,
+    energy_landscape_figure, zne_bar_figure, qec_syndrome_map_figure,
+)
+from .graphical_builder import GATE_PALETTE, ops_to_native_tuples
+from .circuit_builder_component import mount_circuit_builder
+from .hamiltonians import (
+    MOLECULE_CATALOG, build_molecular_hamiltonian, get_compatible_molecules,
+    get_all_molecules, get_molecule_n_qubits,
+    get_molecular_hamiltonian_matrix, ground_state_energy, ground_state_energy_sparse,
+    linear_chain_geometry, ring_geometry, mix_hamiltonians,
+)
+from .mitigation import (
+    MitigationResult, run_zne_mitigation, DensityMatrixZNEResult, run_density_matrix_zne,
+    CoherenceZNEResult, run_coherence_zne_mitigation,
+)
+from .crypto_protocols import (
+    Bb84Result, run_bb84, DiQkdGhzResult, run_di_qkd_ghz, run_dicka_protocol,
+)
+from .native_hf_diagnostics import NativeHfDiagnosticsResult, run_native_hf_diagnostics
+from .mass_decomposition_tool import MassDecompositionResult, run_mass_decomposition
+from .rag_tool import RagSearchResult, run_rag_search
+from .system_limits import max_safe_dense_qubits
+from .vqe import run_vqe, scan_hardware_efficient_energy_landscape
+from .qmmm import (
+    ATOMIC_MASSES_AMU,
+    compute_hellmann_feynman_forces, md_step, run_md_trajectory,
+)
+from .wormhole import (
+    build_sparse_syk_terms, commuting_pair_count, select_good_instance,
+    run_wormhole_protocol, run_wormhole_protocol_trotter,
+)
+from .vector_healing import VectorHealingResult, run_vector_healing
+from .noise_tools import (
+    CosmicRayBurstResult, run_cosmic_ray_burst,
+    OscillatingNoiseResult, run_oscillating_noise,
+    DensityMatrixChannelResult, run_density_matrix_channel,
+)
+from .band_structure import scan_bands_along_path, band_structure_figure
+
+__all__ = [
+    'enable_dashboard_precision',
+    'QASM_LIBRARY', 'gate_tuples_to_qasm',
+    'SimulationResult', 'run_circuit_from_qasm',
+    'LargeScaleMPSResult', 'run_large_circuit_mps', 'MPS_DENSE_CONTRACTION_LIMIT',
+    'run_bond_convergence_check',
+    'draw_circuit_figure', 'histogram_figure', 'qsphere_figure', 'bloch_multivector_figure',
+    'energy_landscape_figure', 'zne_bar_figure', 'qec_syndrome_map_figure',
+    'GATE_PALETTE', 'ops_to_native_tuples',
+    'mount_circuit_builder',
+    'MOLECULE_CATALOG', 'build_molecular_hamiltonian', 'get_compatible_molecules',
+    'get_all_molecules', 'get_molecule_n_qubits',
+    'get_molecular_hamiltonian_matrix', 'ground_state_energy', 'ground_state_energy_sparse',
+    'linear_chain_geometry', 'ring_geometry', 'mix_hamiltonians',
+    'MitigationResult', 'run_zne_mitigation',
+    'DensityMatrixZNEResult', 'run_density_matrix_zne',
+    'CoherenceZNEResult', 'run_coherence_zne_mitigation',
+    'Bb84Result', 'run_bb84', 'DiQkdGhzResult', 'run_di_qkd_ghz', 'run_dicka_protocol',
+    'NativeHfDiagnosticsResult', 'run_native_hf_diagnostics',
+    'MassDecompositionResult', 'run_mass_decomposition',
+    'RagSearchResult', 'run_rag_search',
+    'max_safe_dense_qubits',
+    'run_vqe', 'scan_hardware_efficient_energy_landscape',
+    'ATOMIC_MASSES_AMU',
+    'compute_hellmann_feynman_forces', 'md_step', 'run_md_trajectory',
+    'build_sparse_syk_terms', 'commuting_pair_count', 'select_good_instance',
+    'run_wormhole_protocol', 'run_wormhole_protocol_trotter',
+    'VectorHealingResult', 'run_vector_healing',
+    'CosmicRayBurstResult', 'run_cosmic_ray_burst',
+    'OscillatingNoiseResult', 'run_oscillating_noise',
+    'DensityMatrixChannelResult', 'run_density_matrix_channel',
+    'scan_bands_along_path', 'band_structure_figure',
+]

dashboard_core/_gate_tables.py

@@ -0,0 +1,30 @@
+"""Gate-name classification, shared by qasm_library.py and
+circuit_diagram.py (prog.txt, dashboard_core audit point 2). Was: two
+independently hand-copied sets of the same 5 constants, each with a
+comment claiming to mirror a different, non-existent "canonical" source
+(dense_evolution/compiler.py's gate categories, dashboard_core/engine.py's
+dispatch tables) -- neither actually defines these as a literal data
+structure. The two copies had already drifted apart in practice:
+circuit_diagram.py's _ONE_QUBIT_PARAM was missing the 'u1'/'phase'
+aliases qasm_library.py's copy had, so a circuit using either of those
+two (both real gate names dense_evolution.circuits.gates.GATE_IDS
+recognizes, both mapped to the same gate as 'p') crashed
+draw_native_circuit_diagram with "unsupported gate for native circuit
+diagram" -- a real bug, not just a duplication risk, fixed by making
+this the one place these sets are defined.
+
+Matches dense_evolution.circuits.gates.GATE_IDS's own gate-name
+vocabulary (the actual source of truth for which names QASMParser
+accepts) -- verified directly, not assumed, before writing this down.
+"""
+
+__all__ = [
+    '_ONE_QUBIT_STATIC', '_ONE_QUBIT_PARAM', '_TWO_QUBIT_STATIC',
+    '_TWO_QUBIT_PARAM', '_THREE_QUBIT_STATIC',
+]
+
+_ONE_QUBIT_STATIC = {"h", "x", "y", "z", "s", "sdg", "t", "tdg", "sx", "id"}
+_ONE_QUBIT_PARAM = {"rx", "ry", "rz", "p", "u1", "phase"}
+_TWO_QUBIT_STATIC = {"cx", "cz", "cy", "swap"}
+_TWO_QUBIT_PARAM = {"cp", "crz"}
+_THREE_QUBIT_STATIC = {"ccx"}

dashboard_core/band_structure.py

@@ -0,0 +1,71 @@
+"""
+Real sp3s* tight-binding band structure along a k-path
+(dense_evolution.sp3s_star_hamiltonian, the same real Hamiltonian
+direct_gap_at_gamma/band_extrema_along_path already use -- all 10 bands
+here, not just the VBM/CBM pair those two track), plus an interactive
+Plotly figure with real hover tooltips (k-point and energy per band).
+
+This is the one interactive (hover/zoom) visualization in the dashboard;
+everywhere else in dashboard_core.visuals uses static matplotlib. The
+choice here is unrelated to that module's own reason for staying
+matplotlib-only (Qiskit's macOS instability, see visuals.py) -- this is
+purely about wanting real per-point hover data that a static image
+cannot provide, and needed adding plotly as a declared dependency
+(pyproject.toml's `dashboard` extra) since it was only ever an
+incidental transitive package before.
+"""
+
+import numpy as np
+import plotly.graph_objects as go
+
+import dense_evolution as de
+
+__all__ = ['scan_bands_along_path', 'band_structure_figure']
+
+
+def scan_bands_along_path(material, k_start, k_end, n_points=201):
+    """All 10 sp3s* tight-binding bands (real eigenvalues of
+    dense_evolution.sp3s_star_hamiltonian at each sampled k-point, not
+    just the single VBM/CBM pair band_extrema_along_path tracks) along
+    the straight line from k_start to k_end, both in the same 2*pi/a
+    cubic-axis units as sp3s_star_hamiltonian itself.
+
+    Returns (t, bands): t is the fractional position along the path
+    (0..1, n_points), bands is a (n_points, 10) array with band j's
+    energy at t[i] in bands[i, j] (sorted ascending at every k-point).
+    """
+    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, :]
+
+    bands = np.empty((n_points, 10))
+    for i, k in enumerate(ks):
+        bands[i] = np.sort(np.linalg.eigvalsh(de.sp3s_star_hamiltonian(k, material)).real)
+    return t, bands
+
+
+def band_structure_figure(t, bands, material_name, k_start_label='Γ', k_end_label='X'):
+    """Interactive Plotly band-structure plot: one line per band, real
+    hover tooltip per point showing the exact k-path position and
+    energy (not read off a static image). Bands 3/4 (0-indexed, the
+    valence-band maximum / conduction-band minimum pair
+    band_extrema_along_path itself tracks) are highlighted."""
+    fig = go.Figure()
+    n_bands = bands.shape[1]
+    for j in range(n_bands):
+        is_frontier = j in (3, 4)
+        fig.add_trace(go.Scatter(
+            x=t, y=bands[:, j], mode='lines',
+            name=f'banda {j}' + (' (VBM)' if j == 3 else ' (CBM)' if j == 4 else ''),
+            line=dict(width=3 if is_frontier else 1, color='#d62728' if j == 3 else '#1f77b4' if j == 4 else '#999999'),
+            hovertemplate=f'banda {j}<br>t=%{{x:.3f}}<br>E=%{{y:.4f}} eV<extra></extra>',
+        ))
+    fig.update_layout(
+        title=f'Struttura a bande sp3s* -- {material_name} ({k_start_label}→{k_end_label})',
+        xaxis_title=f'{k_start_label} → {k_end_label}',
+        yaxis_title='Energia (eV)',
+        hovermode='closest',
+        template='plotly_white',
+    )
+    return fig

dashboard_core/circuit_builder_component.py

@@ -0,0 +1,232 @@
+"""
+Graphical (drag-and-drop) circuit builder -- the fourth pillar of IBM
+Quantum Composer's layout (graphical editor + code editor + Statevector +
+Probabilities), the one missing piece the rest of dashboard_core didn't
+have yet.
+
+Built on Streamlit's own native bidirectional component API
+(st.components.v2.component -- real HTML/CSS/JS running in the browser,
+not a hand-waved "coming soon" panel). Gates are dragged from a palette
+onto a qubit x time-step grid using plain HTML5 drag-and-drop; every drop
+re-serializes the grid into an ops list and pushes it back to Python via
+setStateValue, so Streamlit always has the real current state of what's
+on the canvas.
+
+The ops list this emits is consumed by dashboard_core.graphical_builder.
+ops_to_native_tuples, which builds dense_evolution's own gate tuples
+(no Qiskit) executed by the exact same dense_evolution engine as typed
+OpenQASM -- no separate/fake execution path for graphically-built
+circuits.
+"""
+
+from .graphical_builder import GATE_PALETTE
+
+__all__ = ['mount_circuit_builder']
+
+_CSS = """
+.cb-root { display: flex; flex-direction: column; gap: 10px; font-family: monospace; }
+.cb-palette { display: flex; flex-wrap: wrap; gap: 6px; padding: 6px; border: 1px solid var(--st-border-color, #444); border-radius: 6px; }
+.cb-chip {
+  padding: 4px 10px; border-radius: 4px; cursor: grab; user-select: none;
+  background: var(--st-secondary-background-color, #262730);
+  color: var(--st-text-color, #fafafa);
+  border: 1px solid var(--st-border-color, #444);
+  font-size: 14px;
+}
+.cb-chip:active { cursor: grabbing; }
+.cb-chip[data-kind="control"] { background: #3a5; color: #fff; }
+.cb-chip[data-kind="target"] { background: #35a; color: #fff; }
+.cb-chip[data-kind="swap"] { background: #a53; color: #fff; }
+.cb-toolbar { display: flex; gap: 8px; align-items: center; }
+.cb-toolbar button {
+  padding: 4px 10px; border-radius: 4px; cursor: pointer;
+  background: var(--st-secondary-background-color, #262730);
+  color: var(--st-text-color, #fafafa);
+  border: 1px solid var(--st-border-color, #444);
+}
+.cb-grid { display: grid; gap: 2px; align-items: center; position: relative; }
+.cb-qlabel { font-size: 12px; opacity: 0.75; text-align: right; padding-right: 6px; }
+.cb-cell {
+  width: 40px; height: 32px; border: 1px solid var(--st-border-color, #444);
+  border-radius: 4px; display: flex; align-items: center; justify-content: center;
+  font-size: 13px; cursor: pointer;
+  background: var(--st-background-color, #0e1117);
+  color: var(--st-text-color, #fafafa);
+}
+.cb-cell.cb-filled { background: var(--st-secondary-background-color, #262730); font-weight: bold; }
+.cb-cell.cb-over { outline: 2px dashed #4af; }
+.cb-count { font-size: 12px; opacity: 0.75; }
+"""
+
+_HTML = """
+<div class="cb-toolbar">
+  <span class="cb-count" data-role="count">0 gates placed</span>
+  <button data-role="clear">Clear grid</button>
+</div>
+"""
+
+_JS = r"""
+export default function(component) {
+  const { data, setStateValue, parentElement } = component;
+  const nQubits = Math.max(1, data.n_qubits || 1);
+  const nCols = Math.max(1, data.n_columns || 12);
+  const palette = data.palette || [];
+
+  const grid = Array.from({ length: nQubits }, () => Array(nCols).fill(null));
+  const cellEls = Array.from({ length: nQubits }, () => Array(nCols).fill(null));
+
+  const root = document.createElement('div');
+  root.className = 'cb-root';
+
+  const paletteEl = document.createElement('div');
+  paletteEl.className = 'cb-palette';
+  palette.forEach((g) => {
+    const chip = document.createElement('div');
+    chip.className = 'cb-chip';
+    chip.draggable = true;
+    chip.textContent = g.label;
+    chip.dataset.kind = g.kind;
+    chip.title = g.kind === 'single' ? `Porta a 1 qubit: ${g.label}`
+      : g.kind === 'control' ? 'Controllo -- trascina un target nella stessa colonna'
+      : g.kind === 'target' ? `Target -- forma C${g.gate.toUpperCase()} con un controllo nella stessa colonna`
+      : 'SWAP -- trascina due marcatori nella stessa colonna';
+    chip.addEventListener('dragstart', (e) => {
+      e.dataTransfer.setData('text/plain', g.id);
+      e.dataTransfer.effectAllowed = 'copy';
+    });
+    paletteEl.appendChild(chip);
+  });
+  root.appendChild(paletteEl);
+
+  const gridEl = document.createElement('div');
+  gridEl.className = 'cb-grid';
+  gridEl.style.gridTemplateColumns = `36px repeat(${nCols}, 40px)`;
+
+  for (let r = 0; r < nQubits; r++) {
+    const label = document.createElement('div');
+    label.className = 'cb-qlabel';
+    label.textContent = `q${r}`;
+    gridEl.appendChild(label);
+    for (let c = 0; c < nCols; c++) {
+      const cell = document.createElement('div');
+      cell.className = 'cb-cell';
+      cell.addEventListener('dragover', (e) => { e.preventDefault(); cell.classList.add('cb-over'); });
+      cell.addEventListener('dragleave', () => cell.classList.remove('cb-over'));
+      cell.addEventListener('drop', (e) => {
+        e.preventDefault();
+        cell.classList.remove('cb-over');
+        const gateId = e.dataTransfer.getData('text/plain');
+        const g = palette.find((x) => x.id === gateId);
+        if (!g) return;
+        grid[r][c] = { kind: g.kind, gate: g.gate };
+        renderCell(r, c);
+        emit();
+      });
+      cell.addEventListener('click', () => {
+        if (grid[r][c]) {
+          grid[r][c] = null;
+          renderCell(r, c);
+          emit();
+        }
+      });
+      gridEl.appendChild(cell);
+      cellEls[r][c] = cell;
+    }
+  }
+  root.appendChild(gridEl);
+  parentElement.appendChild(root);
+
+  const countEl = parentElement.querySelector('[data-role="count"]');
+  parentElement.querySelector('[data-role="clear"]').addEventListener('click', () => {
+    for (let r = 0; r < nQubits; r++) {
+      for (let c = 0; c < nCols; c++) {
+        grid[r][c] = null;
+        renderCell(r, c);
+      }
+    }
+    emit();
+  });
+
+  const SYMS = { control: '●', swap: '×' };
+
+  function renderCell(r, c) {
+    const cell = cellEls[r][c];
+    const v = grid[r][c];
+    if (!v) {
+      cell.textContent = '';
+      cell.classList.remove('cb-filled');
+      return;
+    }
+    cell.classList.add('cb-filled');
+    if (v.kind === 'single') cell.textContent = v.gate.toUpperCase();
+    else if (v.kind === 'target') cell.textContent = v.gate === 'x' ? '⊕' : v.gate.toUpperCase();
+    else cell.textContent = SYMS[v.kind] || '?';
+  }
+
+  function buildOps() {
+    const ops = [];
+    for (let c = 0; c < nCols; c++) {
+      let single = null;
+      const controls = [];
+      const targets = [];
+      const swaps = [];
+      for (let r = 0; r < nQubits; r++) {
+        const v = grid[r][c];
+        if (!v) continue;
+        if (v.kind === 'single') single = { row: r, gate: v.gate };
+        else if (v.kind === 'control') controls.push(r);
+        else if (v.kind === 'target') targets.push({ row: r, gate: v.gate });
+        else if (v.kind === 'swap') swaps.push(r);
+      }
+      const isEmpty = !single && controls.length === 0 && targets.length === 0 && swaps.length === 0;
+      if (isEmpty) continue;
+      if (single && controls.length === 0 && targets.length === 0 && swaps.length === 0) {
+        ops.push({ gate: single.gate, qubits: [single.row] });
+      } else if (!single && controls.length === 1 && targets.length === 1 && swaps.length === 0) {
+        ops.push({ gate: 'c' + targets[0].gate, qubits: [controls[0], targets[0].row] });
+      } else if (!single && controls.length === 0 && targets.length === 0 && swaps.length === 2) {
+        ops.push({ gate: 'swap', qubits: swaps });
+      }
+      // Any other combination in a column (e.g. a lone control with no
+      // target yet) is an incomplete gate -- shown on the grid but not
+      // emitted as an op until it's completed.
+    }
+    return ops;
+  }
+
+  function emit() {
+    const ops = buildOps();
+    countEl.textContent = `${ops.length} gates placed`;
+    setStateValue('circuit', ops);
+  }
+
+  emit();
+}
+"""
+
+_COMPONENT_NAME = "dense_evolution_circuit_builder"
+
+
+def mount_circuit_builder(n_qubits: int, n_columns: int = 12, key: str = "circuit_builder"):
+    """Mount the drag-and-drop circuit builder and return its current ops
+    list (list[dict] with 'gate'/'qubits'), or [] if nothing is placed yet.
+
+    `key` should change whenever `n_qubits` changes (e.g. include it in the
+    caller's key) so Streamlit mounts a fresh grid instead of reusing a
+    stale one sized for a different qubit count.
+
+    Streamlit is imported here, not at module level: this component only
+    means anything inside a Streamlit app (app_dashboard.py) -- the
+    Composer kernel (local_site/app/server.py) imports dashboard_core too
+    but never calls this function, and shouldn't need streamlit installed
+    just to start.
+    """
+    import streamlit as st
+    builder = st.components.v2.component(_COMPONENT_NAME, html=_HTML, css=_CSS, js=_JS)
+    result = builder(
+        key=key,
+        data={"n_qubits": n_qubits, "n_columns": n_columns, "palette": GATE_PALETTE},
+        default={"circuit": []},
+        on_circuit_change=lambda: None,
+    )
+    return result.circuit if result.circuit is not None else []

dashboard_core/circuit_diagram.py

@@ -0,0 +1,216 @@
+"""
+Native circuit-diagram renderer -- pure matplotlib, never a Qiskit
+QuantumCircuit. Replaces qiskit's circuit.draw(output='mpl') for exactly
+the reason documented in dashboard_core/engine.py's module docstring:
+qiskit.circuit.QuantumCircuit.__init__ itself segfaults (SIGSEGV) on
+macOS CI runners, on the simplest possible call (QuantumCircuit(3) alone,
+no QASM, no methods called on it) -- see tests/integration/test_interop.py::
+TestQiskitInterop for the full reproduction story. There is no way to
+keep using Qiskit's own drawer without constructing that object, so this
+module draws directly from the same (name, *qubits[, param]) gate-tuple
+format every other dense_evolution entry point already uses.
+
+Gate vocabulary comes from dashboard_core._gate_tables (_ONE_QUBIT_STATIC /
+_ONE_QUBIT_PARAM / _TWO_QUBIT_STATIC / _TWO_QUBIT_PARAM /
+_THREE_QUBIT_STATIC), shared with qasm_library.py -- the same gate set
+QASMParser can ever hand back, so nothing here can see a name it doesn't
+recognize. Was a second, independently hand-copied set of these 5
+constants until this shared import (prog.txt, dashboard_core audit point
+2): this copy was missing the 'u1'/'phase' aliases the other one had,
+so a circuit using either of those two real gate names crashed this
+function with "unsupported gate for native circuit diagram" -- a real
+bug the duplication caused, not just a divergence risk.
+"""
+
+import matplotlib.pyplot as plt
+from matplotlib.patches import Circle, Rectangle
+
+from ._gate_tables import (
+    _ONE_QUBIT_STATIC, _ONE_QUBIT_PARAM, _TWO_QUBIT_STATIC,
+    _TWO_QUBIT_PARAM, _THREE_QUBIT_STATIC,
+)
+
+__all__ = ['draw_native_circuit_diagram']
+
+_BOX_LABEL = {
+    "h": "H", "x": "X", "y": "Y", "z": "Z", "s": "S", "sdg": "S†",
+    "t": "T", "tdg": "T†", "sx": "√X", "id": "I",
+    "rx": "RX", "ry": "RY", "rz": "RZ", "p": "P",
+    # u1/phase are the same gate as 'p' (see _gate_tables.py) -- without
+    # an entry here they'd still draw (that bug is fixed), just as the
+    # raw uppercased name ("U1"/"PHASE") instead of the same "P" label
+    # 'p' gets, inconsistent with dense_evolution/utils/drawing.py's own
+    # _LABELS, which already maps all three to "P" (prog.txt, dashboard_core
+    # audit point 5e).
+    "u1": "P", "phase": "P",
+    "cy": "Y", "cp": "P", "crz": "RZ",
+}
+
+_WIRE_COLOR = "black"
+_BOX_FACE = "#6FA8DC"
+_BOX_EDGE = "black"
+_DOT_COLOR = "black"
+_MEASURE_FACE = "#DDDDDD"
+
+
+def _op_qubits(op, name):
+    """Every op tuple is (name, *qubits, *params) -- qubit count is fixed
+    per gate name (never variadic), so this just slices the right span."""
+    if name in _ONE_QUBIT_STATIC:
+        return [op[1]]
+    if name in _ONE_QUBIT_PARAM:
+        return [op[1]]
+    if name in _TWO_QUBIT_STATIC:
+        return [op[1], op[2]]
+    if name in _TWO_QUBIT_PARAM:
+        return [op[1], op[2]]
+    if name in _THREE_QUBIT_STATIC:
+        return [op[1], op[2], op[3]]
+    raise ValueError(f"unsupported gate for native circuit diagram: {name!r}")
+
+
+def _schedule_columns(ops):
+    """Greedy left-packing, same rule every real circuit drawer uses: an
+    op goes in the first column strictly after the last column any of its
+    qubits was already used in. Returns a list of (op, column) pairs and
+    the total column count.
+
+    A multi-qubit op's vertical connector is drawn spanning every row
+    between its lowest and highest qubit index (see _draw_vertical_link
+    call sites below), not just the qubits it actually touches -- e.g.
+    cy(2, 0) draws a line through q1's row even though q1 isn't part of
+    the gate. So every qubit in that span, not just the op's own qubits,
+    must be marked used at this column too, or an unrelated single-qubit
+    gate on the skipped-over qubit can land in the same column and get
+    visually cut through by the connector line."""
+    next_free_col = {}
+    scheduled = []
+    for op in ops:
+        name = op[0]
+        qubits = _op_qubits(op, name)
+        span = range(min(qubits), max(qubits) + 1)
+        col = max((next_free_col.get(q, 0) for q in span), default=0)
+        scheduled.append((op, col))
+        for q in span:
+            next_free_col[q] = col + 1
+    n_columns = max((col for _, col in scheduled), default=-1) + 1
+    return scheduled, n_columns
+
+
+def _draw_one_qubit_box(ax, x, y, label):
+    box = Rectangle((x - 0.3, y - 0.3), 0.6, 0.6, facecolor=_BOX_FACE, edgecolor=_BOX_EDGE, zorder=3)
+    ax.add_patch(box)
+    ax.text(x, y, label, ha="center", va="center", fontsize=10, fontweight="bold", zorder=4)
+
+
+def _draw_control_dot(ax, x, y):
+    ax.add_patch(Circle((x, y), 0.08, facecolor=_DOT_COLOR, edgecolor=_DOT_COLOR, zorder=4))
+
+
+def _draw_target_plus(ax, x, y):
+    ax.add_patch(Circle((x, y), 0.28, facecolor="white", edgecolor=_DOT_COLOR, zorder=3))
+    ax.plot([x - 0.28, x + 0.28], [y, y], color=_DOT_COLOR, linewidth=1.4, zorder=4)
+    ax.plot([x, x], [y - 0.28, y + 0.28], color=_DOT_COLOR, linewidth=1.4, zorder=4)
+
+
+def _draw_swap_x(ax, x, y):
+    ax.plot([x - 0.15, x + 0.15], [y - 0.15, y + 0.15], color=_DOT_COLOR, linewidth=2, zorder=4)
+    ax.plot([x - 0.15, x + 0.15], [y + 0.15, y - 0.15], color=_DOT_COLOR, linewidth=2, zorder=4)
+
+
+def _draw_vertical_link(ax, x, y0, y1):
+    ax.plot([x, x], [y0, y1], color=_DOT_COLOR, linewidth=1.4, zorder=2)
+
+
+def _param_label(name, params):
+    base = _BOX_LABEL.get(name, name.upper())
+    if params:
+        return f"{base}({params[0]:.2f})"
+    return base
+
+
+def draw_native_circuit_diagram(ops, n_qubits: int, add_measure: bool = True):
+    """Draws a circuit diagram figure directly from dense_evolution gate
+    tuples -- no Qiskit QuantumCircuit ever constructed. Qubit 0 is drawn
+    at the top, increasing downward, matching Qiskit's own drawer
+    convention so this is a drop-in replacement for
+    dashboard_core.visuals.draw_circuit_figure's panel.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+
+    Examples
+    --------
+    >>> from dashboard_core.circuit_diagram import draw_native_circuit_diagram
+    >>> fig = draw_native_circuit_diagram([('h', 0), ('cx', 0, 1)], n_qubits=2)
+    >>> type(fig).__name__
+    'Figure'
+    >>> fig.savefig('bell_pair.png')  # doctest: +SKIP
+    """
+    scheduled, n_columns = _schedule_columns(ops)
+    n_display_columns = n_columns + (1 if add_measure else 0)
+
+    fig_width = max(3.0, 1.1 * (n_display_columns + 1))
+    fig_height = max(2.0, 0.9 * n_qubits + 0.5)
+    fig, ax = plt.subplots(figsize=(fig_width, fig_height))
+
+    def row_y(qubit):
+        return n_qubits - 1 - qubit
+
+    wire_x_end = n_display_columns + 0.7
+    for q in range(n_qubits):
+        y = row_y(q)
+        ax.plot([0, wire_x_end], [y, y], color=_WIRE_COLOR, linewidth=1.2, zorder=1)
+        ax.text(-0.35, y, f"q{q}", ha="right", va="center", fontsize=10)
+
+    for op, col in scheduled:
+        name = op[0]
+        x = col + 1.0
+        qubits = _op_qubits(op, name)
+        rows = [row_y(q) for q in qubits]
+        params = list(op[1 + len(qubits):])
+
+        if name in _ONE_QUBIT_STATIC:
+            _draw_one_qubit_box(ax, x, rows[0], _BOX_LABEL.get(name, name.upper()))
+        elif name in _ONE_QUBIT_PARAM:
+            _draw_one_qubit_box(ax, x, rows[0], _param_label(name, params))
+        elif name == "swap":
+            _draw_vertical_link(ax, x, rows[0], rows[1])
+            _draw_swap_x(ax, x, rows[0])
+            _draw_swap_x(ax, x, rows[1])
+        elif name in _TWO_QUBIT_STATIC:
+            # cx/cy/cz: qubits[0] is control, qubits[1] is target.
+            _draw_vertical_link(ax, x, rows[0], rows[1])
+            _draw_control_dot(ax, x, rows[0])
+            if name == "cx":
+                _draw_target_plus(ax, x, rows[1])
+            else:
+                _draw_one_qubit_box(ax, x, rows[1], _BOX_LABEL.get(name, name.upper()))
+        elif name in _TWO_QUBIT_PARAM:
+            _draw_vertical_link(ax, x, rows[0], rows[1])
+            _draw_control_dot(ax, x, rows[0])
+            _draw_one_qubit_box(ax, x, rows[1], _param_label(name, params))
+        elif name in _THREE_QUBIT_STATIC:
+            # ccx (Toffoli): qubits[0], qubits[1] control, qubits[2] target.
+            _draw_vertical_link(ax, x, min(rows), max(rows))
+            _draw_control_dot(ax, x, rows[0])
+            _draw_control_dot(ax, x, rows[1])
+            _draw_target_plus(ax, x, rows[2])
+        else:
+            raise ValueError(f"unsupported gate for native circuit diagram: {name!r}")
+
+    if add_measure:
+        x = n_columns + 1.0
+        for q in range(n_qubits):
+            y = row_y(q)
+            box = Rectangle((x - 0.3, y - 0.3), 0.6, 0.6, facecolor=_MEASURE_FACE, edgecolor=_BOX_EDGE, zorder=3)
+            ax.add_patch(box)
+            ax.text(x, y, "M", ha="center", va="center", fontsize=9, zorder=4)
+
+    ax.set_xlim(-1.2, wire_x_end + 0.3)
+    ax.set_ylim(-0.7, n_qubits - 0.3)
+    ax.set_aspect("equal")
+    ax.axis("off")
+    fig.tight_layout()
+    return fig