qubasic 0.1.0__py3-none-any.whl

qbasic_core/display.py

@@ -0,0 +1,274 @@
+"""QBASIC display — histograms, statevector, Bloch sphere rendering."""
+
+import sys
+import math
+import numpy as np
+
+from qbasic_core.engine import (
+    MAX_HISTOGRAM_STATES, MAX_DISPLAY_AMPLITUDES,
+    HISTOGRAM_BAR_WIDTH, AMPLITUDE_THRESHOLD,
+    _RICH, _RichTable,
+)
+
+
+def _get_console():
+    """Get a Rich console bound to current sys.stdout (test-safe)."""
+    if _RICH:
+        from rich.console import Console
+        return Console(file=sys.stdout, highlight=False)
+    return None
+
+
+class DisplayMixin:
+    """Display and visualization methods for the QBASIC terminal.
+
+    Requires: TerminalProtocol — uses self.num_qubits, self.arrays.
+    """
+
+    def print_histogram(self, counts: dict[str, int]) -> None:
+        """Measurement histogram with optional rich-table formatting."""
+        total = sum(counts.values())
+        sorted_counts = sorted(counts.items(), key=lambda x: -x[1])
+        display = sorted_counts[:MAX_HISTOGRAM_STATES]
+
+        if _RICH:
+            self._print_histogram_rich(display, sorted_counts, total)
+        else:
+            self._print_histogram_plain(display, sorted_counts, total)
+
+    def _print_histogram_rich(self, display: list, sorted_counts: list,
+                              total: int) -> None:
+        """Rich-formatted histogram with colored bars."""
+        table = _RichTable(show_header=True, header_style="bold cyan",
+                           box=None, padding=(0, 1))
+        table.add_column("State", justify="right", style="bold")
+        table.add_column("Count", justify="right")
+        table.add_column("%", justify="right")
+        table.add_column("Distribution", min_width=HISTOGRAM_BAR_WIDTH)
+
+        max_count = max(c for _, c in display) if display else 1
+        if len(sorted_counts) > MAX_HISTOGRAM_STATES:
+            _get_console().print(
+                f"\n  [dim]Showing top {MAX_HISTOGRAM_STATES} of "
+                f"{len(sorted_counts)} outcomes:[/dim]\n")
+        else:
+            _get_console().print()
+
+        for state, count in display:
+            pct = 100 * count / total
+            bar_len = int(HISTOGRAM_BAR_WIDTH * count / max_count)
+            bar = '\u2588' * bar_len
+            color = "green" if pct > 40 else "yellow" if pct > 10 else "dim"
+            table.add_row(
+                f"|{state}\u27E9",
+                str(count),
+                f"{pct:5.1f}%",
+                f"[{color}]{bar}[/{color}]")
+
+        if len(sorted_counts) > MAX_HISTOGRAM_STATES:
+            rest_count = sum(c for _, c in sorted_counts[MAX_HISTOGRAM_STATES:])
+            table.add_row(
+                "...", str(rest_count),
+                f"{100*rest_count/total:5.1f}%", "[dim](remaining)[/dim]")
+
+        try:
+            _get_console().print(table)
+            _get_console().print()
+        except UnicodeEncodeError:
+            self._print_histogram_plain(display, sorted_counts, total)
+
+    def _print_histogram_plain(self, display: list, sorted_counts: list,
+                               total: int) -> None:
+        """Plain-text histogram (fallback when rich is not available)."""
+        if len(sorted_counts) > MAX_HISTOGRAM_STATES:
+            self.io.writeln(f"\n  Showing top {MAX_HISTOGRAM_STATES} of {len(sorted_counts)} outcomes:\n")
+        else:
+            self.io.writeln('')
+
+        max_count = max(c for _, c in display) if display else 1
+        max_label = max(len(k) for k, _ in display) if display else 1
+
+        for state, count in display:
+            pct = 100 * count / total
+            bar_len = int(HISTOGRAM_BAR_WIDTH * count / max_count)
+            bar = '\u2588' * bar_len
+            ket = f"|{state}\u27E9"
+            self.io.writeln(f"  {ket:>{max_label+3}}  {count:>6}  ({pct:5.1f}%)  {bar}")
+
+        if len(sorted_counts) > MAX_HISTOGRAM_STATES:
+            rest_count = sum(c for _, c in sorted_counts[MAX_HISTOGRAM_STATES:])
+            self.io.writeln(f"  {'...':>{max_label+3}}  {rest_count:>6}  "
+                            f"({100*rest_count/total:5.1f}%)  (remaining)")
+        self.io.writeln('')
+
+    def _print_statevector(self, sv, n_qubits=None):
+        """Print non-zero amplitudes of the statevector."""
+        sv = np.ascontiguousarray(sv).ravel()
+        n = n_qubits if n_qubits is not None else self.num_qubits
+
+        if _RICH:
+            table = _RichTable(show_header=True, header_style="bold cyan",
+                               box=None, padding=(0, 1))
+            table.add_column("State", justify="right", style="bold")
+            table.add_column("Amplitude", justify="right")
+            table.add_column("P", justify="right")
+            _get_console().print(f"\n  [bold]Statevector ({n} qubits):[/bold]")
+            count = 0
+            for i, amp in enumerate(sv):
+                if abs(amp) > AMPLITUDE_THRESHOLD:
+                    state = format(i, f'0{n}b')
+                    prob = abs(amp)**2
+                    table.add_row(
+                        f"|{state}\u27E9",
+                        f"{amp.real:+.4f}{amp.imag:+.4f}j",
+                        f"{prob:.4f}")
+                    count += 1
+                    if count >= MAX_DISPLAY_AMPLITUDES:
+                        remaining = sum(1 for a in sv[i+1:]
+                                        if abs(a) > AMPLITUDE_THRESHOLD)
+                        if remaining:
+                            table.add_row("...", "", f"+{remaining} more")
+                        break
+            try:
+                _get_console().print(table)
+                _get_console().print()
+                return
+            except UnicodeEncodeError:
+                pass  # fall through to plain-text path below
+
+        self.io.writeln(f"\n  Statevector ({n} qubits):")
+        count = 0
+        for i, amp in enumerate(sv):
+            if abs(amp) > AMPLITUDE_THRESHOLD:
+                state = format(i, f'0{n}b')
+                prob = abs(amp)**2
+                self.io.writeln(f"  |{state}\u27E9  {amp.real:+.4f}{amp.imag:+.4f}j  "
+                               f"(P={prob:.4f})")
+                count += 1
+                if count >= MAX_DISPLAY_AMPLITUDES:
+                    remaining = sum(1 for a in sv[i+1:] if abs(a) > AMPLITUDE_THRESHOLD)
+                    if remaining:
+                        self.io.writeln(f"  ... and {remaining} more non-zero amplitudes")
+                    break
+        self.io.writeln('')
+
+    def _print_sv_compact(self, sv):
+        """Compact statevector display for step mode."""
+        n = self.num_qubits
+        parts = []
+        for i, amp in enumerate(sv):
+            if abs(amp) > AMPLITUDE_THRESHOLD:
+                state = format(i, f'0{n}b')
+                if abs(amp.imag) < AMPLITUDE_THRESHOLD:
+                    parts.append(f"{amp.real:+.3f}|{state}\u27E9")
+                else:
+                    parts.append(f"({amp.real:.2f}{amp.imag:+.2f}j)|{state}\u27E9")
+                if len(parts) >= 8:
+                    parts.append("...")
+                    break
+        self.io.writeln(f"   |\u03C8\u27E9 = {' '.join(parts)}")
+
+    def _print_probs(self, sv):
+        """Print probability distribution with histogram."""
+        n = self.num_qubits
+        probs = []
+        for i, amp in enumerate(sv):
+            p = abs(amp)**2
+            if p > AMPLITUDE_THRESHOLD:
+                state = format(i, f'0{n}b')
+                probs.append((state, p))
+
+        probs.sort(key=lambda x: -x[1])
+        display = probs[:MAX_HISTOGRAM_STATES]
+
+        self.io.writeln(f"\n  Probability distribution ({len(probs)} non-zero):\n")
+        max_p = max(p for _, p in display) if display else 1
+
+        for state, p in display:
+            bar_len = int(HISTOGRAM_BAR_WIDTH * p / max_p)
+            bar = '\u2588' * bar_len
+            self.io.writeln(f"  |{state}\u27E9  {p*100:6.2f}%  {bar}")
+
+        if len(probs) > MAX_HISTOGRAM_STATES:
+            self.io.writeln(f"  ... and {len(probs)-MAX_HISTOGRAM_STATES} more states")
+        self.io.writeln('')
+
+    def _print_bloch_single(self, sv, qubit, n_qubits=None):
+        """ASCII Bloch sphere for a single qubit."""
+        x, y, z = self._bloch_vector(sv, qubit, n_qubits)
+
+        # Determine state label
+        if math.sqrt(x**2 + y**2 + z**2) < 0.01:
+            label = "maximally mixed"
+        elif z > 0.99:
+            label = "|0\u27E9 (north pole)"
+        elif z < -0.99:
+            label = "|1\u27E9 (south pole)"
+        elif abs(x - 1) < 0.01:
+            label = "|+\u27E9"
+        elif abs(x + 1) < 0.01:
+            label = "|-\u27E9"
+        elif abs(y - 1) < 0.01:
+            label = "|+i\u27E9"
+        elif abs(y + 1) < 0.01:
+            label = "|-i\u27E9"
+        else:
+            theta = math.acos(max(-1, min(1, z)))
+            phi = math.atan2(y, x)
+            label = f"\u03B8={theta:.2f} \u03C6={phi:.2f}"
+
+        # Draw ASCII Bloch sphere (XZ plane projection, 15x15)
+        R = 6
+        W = 2 * R + 1
+        grid = [[' '] * W for _ in range(W)]
+        cx, cy = R, R
+
+        # Circle
+        for angle in range(360):
+            rad = math.radians(angle)
+            gx = round(cx + R * math.cos(rad))
+            gy = round(cy + R * math.sin(rad))
+            if 0 <= gx < W and 0 <= gy < W:
+                if grid[gy][gx] == ' ':
+                    grid[gy][gx] = '\u00B7'
+
+        # Axes
+        for i in range(W):
+            if grid[cy][i] == ' ':
+                grid[cy][i] = '-'
+            if grid[i][cx] == ' ':
+                grid[i][cx] = '|'
+        grid[cy][cx] = '+'
+
+        # State point (XZ projection)
+        px = round(cx + x * (R - 1))
+        pz = round(cy - z * (R - 1))
+        if 0 <= px < W and 0 <= pz < W:
+            grid[pz][px] = '\u25CF'
+
+        # Labels on the sphere
+        self.io.writeln(f"  Qubit {qubit}  ({x:.3f}, {y:.3f}, {z:.3f})  {label}")
+        self.io.writeln(f"{'|0\u27E9':^{W+4}}")
+        for row in grid:
+            self.io.writeln(f"  {''.join(row)}")
+        self.io.writeln(f"{'|1\u27E9':^{W+4}}")
+
+    def _bloch_vector(self, sv, qubit, n_qubits=None):
+        """Compute the Bloch vector for a single qubit from the statevector."""
+        n = n_qubits if n_qubits is not None else self.num_qubits
+        sv_arr = np.array(sv).reshape([2] * n)
+
+        target_axis = n - 1 - qubit
+        tensor = np.moveaxis(sv_arr, target_axis, 0)
+        t0 = tensor[0].flatten()
+        t1 = tensor[1].flatten()
+
+        rho_00 = np.sum(np.abs(t0)**2)
+        rho_11 = np.sum(np.abs(t1)**2)
+        rho_01 = np.sum(np.conj(t0) * t1)
+
+        x = float(2 * rho_01.real)
+        y = float(-2 * rho_01.imag)
+        z = float(rho_00 - rho_11)
+
+        return x, y, z

qbasic_core/engine.py

@@ -0,0 +1,126 @@
+"""QBASIC engine — constants, gate tables, numpy simulation."""
+
+from __future__ import annotations
+
+from enum import Enum, auto
+import numpy as np
+from qbasic_core.patterns import (
+    RE_LINE_NUM, RE_DEF_SINGLE, RE_DEF_BEGIN, RE_REG_INDEX,
+    RE_AT_REG, RE_AT_REG_LINE, RE_SEND, RE_SHARE, RE_MEAS, RE_RESET,
+    RE_UNITARY, RE_DIM, RE_REDIM, RE_ERASE, RE_GET, RE_INPUT,
+    RE_CTRL, RE_INV, RE_LET_ARRAY, RE_LET_VAR, RE_PRINT,
+    RE_GOTO, RE_GOSUB, RE_FOR, RE_NEXT, RE_WHILE, RE_IF_THEN,
+    RE_GOTO_GOSUB_TARGET, RE_MEASURE_BASIS, RE_SYNDROME,
+    RE_DATA, RE_READ, RE_ON_GOTO, RE_ON_GOSUB,
+    RE_SELECT_CASE, RE_CASE, RE_DO, RE_LOOP_STMT, RE_EXIT,
+    RE_SUB, RE_END_SUB, RE_FUNCTION, RE_END_FUNCTION, RE_CALL,
+    RE_LOCAL, RE_STATIC_DECL, RE_SHARED,
+    RE_ON_ERROR, RE_RESUME, RE_ERROR_STMT, RE_ASSERT,
+    RE_SWAP, RE_POKE, RE_SYS, RE_OPEN, RE_CLOSE,
+    RE_PRINT_FILE, RE_INPUT_FILE, RE_LINE_INPUT, RE_OPTION_BASE,
+    RE_IMPORT, RE_SAVE_EXPECT, RE_SAVE_PROBS, RE_SAVE_AMPS,
+    RE_SET_STATE, RE_TYPE_BEGIN, RE_TYPE_FIELD, RE_END_TYPE, RE_DIM_TYPE,
+    RE_CHAIN, RE_MERGE, RE_DEF_FN, RE_PRINT_USING,
+    RE_COLOR, RE_LOCATE, RE_SCREEN, RE_LPRINT,
+    RE_ON_MEASURE, RE_ON_TIMER, RE_DIM_MULTI, RE_LET_STR,
+)
+
+# ═══════════════════════════════════════════════════════════════════════
+# Constants
+# ═══════════════════════════════════════════════════════════════════════
+
+# ═══════════════════════════════════════════════════════════════════════
+# Limits and defaults
+# ═══════════════════════════════════════════════════════════════════════
+
+MAX_QUBITS = 32
+DEFAULT_QUBITS = 4
+DEFAULT_SHOTS = 1024
+MAX_UNDO_STACK = 50
+MAX_LOOP_ITERATIONS = 100_000
+MAX_HISTOGRAM_STATES = 32
+MAX_DISPLAY_AMPLITUDES = 64
+MAX_BLOCH_DISPLAY = 8
+HISTOGRAM_BAR_WIDTH = 35
+AMPLITUDE_THRESHOLD = 1e-8
+MAX_INCLUDE_DEPTH = 8
+# Realistic multiplier for Qiskit Aer statevector simulation:
+#   1x  statevector itself (2^n complex128 = 2^n * 16 bytes)
+#  ~1x  transpilation intermediates and circuit representation
+#  ~1x  Aer internal copy during simulation and measurement collapse
+# Conservative estimate; actual overhead varies by method and circuit depth.
+OVERHEAD_FACTOR = 3.0
+RAM_BUDGET_FRACTION = 0.8
+
+# ═══════════════════════════════════════════════════════════════════════
+# Exec-result sentinels
+# ═══════════════════════════════════════════════════════════════════════
+# _exec_line and helpers return one of:
+#   ExecResult.ADVANCE — advance instruction pointer by one
+#   ExecResult.END     — stop execution
+#   int                — jump to that instruction-pointer index
+
+class ExecResult(Enum):
+    """Instruction execution result sentinels."""
+    ADVANCE = auto()
+    END = auto()
+
+
+# The return type of _exec_line and helpers: ADVANCE, END, or a jump target ip.
+ExecOutcome = ExecResult | int
+
+# ═══════════════════════════════════════════════════════════════════════
+# Optional rich-terminal packages
+# ═══════════════════════════════════════════════════════════════════════
+
+try:
+    from rich.console import Console as _RichConsole
+    from rich.table import Table as _RichTable
+    from rich.panel import Panel as _RichPanel
+    from rich.text import Text as _RichText
+    _RICH = True
+    _console = _RichConsole(highlight=False)
+except ImportError:
+    _RICH = False
+    _console = None
+
+
+
+def _estimate_gb(n_qubits: int) -> float:
+    """Estimate realistic memory for one n-qubit statevector including overhead."""
+    return (2 ** n_qubits) * 16 * OVERHEAD_FACTOR / 1e9
+
+
+def _get_ram_gb() -> tuple[float, float] | None:
+    """Return (total_gb, available_gb) or None if psutil is unavailable."""
+    try:
+        import psutil
+        mem = psutil.virtual_memory()
+        return mem.total / 1e9, mem.available / 1e9
+    except ImportError:
+        return None
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# Gate matrices, builders, and simulation primitives (re-exported from gates.py)
+# ═══════════════════════════════════════════════════════════════════════
+
+from qbasic_core.gates import (
+    GATE_TABLE, GATE_ALIASES, _np_gate_matrix, _apply_gate_np,
+    _measure_np, _sample_np, _sample_one_np, _GATE_BUILDERS,
+    _MAT_CX, _MAT_CY, _MAT_CH, _MAT_CCX, _MAT_CSWAP,
+    _MAT_H, _MAT_X, _MAT_Y, _MAT_Z, _MAT_S, _MAT_T,
+    _MAT_SDG, _MAT_TDG, _MAT_SX, _MAT_ID, _MAT_CZ,
+    _MAT_SWAP, _MAT_DCX, _MAT_ISWAP,
+)
+
+# ═══════════════════════════════════════════════════════════════════════
+# LOCC engine and constants (re-exported from locc_engine.py)
+# ═══════════════════════════════════════════════════════════════════════
+
+from qbasic_core.locc_engine import (
+    LOCCEngine,
+    LOCC_MAX_JOINT_QUBITS, LOCC_MAX_SPLIT_QUBITS, LOCC_MAX_REGISTERS,
+    LOCC_SEND_SHOT_CAP, LOCC_SEND_QUBIT_THRESHOLD,
+)
+

qbasic_core/engine_state.py

@@ -0,0 +1,109 @@
+"""QBASIC engine state — standalone execution state container.
+
+Extracted from QBasicTerminal to break the god-object. Engine holds all
+program state, variables, arrays, execution configuration, and caches.
+QBasicTerminal composes Engine and adds the REPL shell and command dispatch.
+
+Tests and headless callers can use Engine directly without the REPL.
+"""
+
+from __future__ import annotations
+
+import time
+from collections import OrderedDict
+from typing import Any
+
+from qbasic_core.engine import (
+    DEFAULT_QUBITS, DEFAULT_SHOTS, MAX_LOOP_ITERATIONS, MAX_UNDO_STACK,
+)
+from qbasic_core.io_protocol import StdIOPort, IOPort
+from qbasic_core.parser import parse_stmt
+
+
+class Engine:
+    """Standalone execution state container.
+
+    Holds all program state that was previously scattered across
+    QBasicTerminal's __init__ and 16 mixin _init_* methods.
+    """
+
+    def __init__(self, *, io: IOPort | None = None) -> None:
+        # Program
+        self.program: dict[int, str] = {}
+        self._parsed: dict[int, Any] = {}
+        self._undo_stack: list[dict[int, str]] = []
+
+        # Configuration
+        self.num_qubits: int = DEFAULT_QUBITS
+        self.shots: int = DEFAULT_SHOTS
+        self.sim_method: str = 'automatic'
+        self.sim_device: str = 'CPU'
+        self._noise_model: Any = None
+        self._max_iterations: int = MAX_LOOP_ITERATIONS
+        self._include_depth: int = 0
+
+        # Variables and arrays
+        self.variables: dict[str, Any] = {}
+        self.arrays: dict[str, Any] = {}
+        self._array_dims: dict[str, list[int]] = {}
+
+        # Subroutines and registers
+        self.subroutines: dict[str, Any] = {}
+        self.registers: OrderedDict[str, tuple[int, int]] = OrderedDict()
+
+        # Custom gates
+        self._custom_gates: dict[str, Any] = {}
+
+        # Execution state
+        self._gosub_stack: list[int] = []
+        self.step_mode: bool = False
+        self.last_counts: dict[str, int] | None = None
+        self.last_sv: Any = None
+        self.last_circuit: Any = None
+        self._circuit_cache_key: Any = None
+        self._circuit_cache: Any = None
+
+        # LOCC
+        self.locc: Any = None
+        self.locc_mode: bool = False
+
+        # I/O
+        self.io: IOPort = io or StdIOPort()
+
+        # Security
+        self.agent_mode: bool = False
+        self._include_stack: list[str] = []
+
+        # User-defined types
+        self._user_types: dict[str, list[tuple[str, str]]] = {}
+        self._pending_type: dict | None = None
+
+        # Timing
+        self._start_time: float = time.time()
+
+    def _get_parsed(self, line_num: int) -> Any:
+        """Get parsed Stmt for a line, lazily parsing if needed.
+
+        Re-parses if the program text has changed since the last parse.
+        """
+        raw = self.program.get(line_num, '')
+        p = self._parsed.get(line_num)
+        if p is None or p.raw != raw:
+            p = parse_stmt(raw)
+            self._parsed[line_num] = p
+        return p
+
+    def clear(self) -> None:
+        """Reset all state (equivalent to cmd_new)."""
+        self.program.clear()
+        self._parsed.clear()
+        self.subroutines.clear()
+        self.registers.clear()
+        self.variables.clear()
+        self.arrays.clear()
+        self._array_dims.clear()
+        self.last_counts = None
+        self.last_sv = None
+        self.last_circuit = None
+        self._circuit_cache_key = None
+        self._circuit_cache = None

qbasic_core/errors.py

@@ -0,0 +1,37 @@
+"""QBASIC structured error hierarchy."""
+
+from __future__ import annotations
+
+
+class QBasicError(Exception):
+    """Base for all QBASIC errors."""
+
+    def __init__(self, message: str, *, code: int = 0, line: int | None = None):
+        self.message = message
+        self.code = code
+        self.line = line
+        super().__init__(message)
+
+
+class QBasicSyntaxError(QBasicError):
+    """Parse-time or syntax error."""
+
+
+class QBasicRuntimeError(QBasicError):
+    """Execution-time error."""
+
+
+class QBasicBuildError(QBasicError):
+    """Circuit/program build error."""
+
+
+class QBasicRangeError(QBasicError):
+    """Value out of range."""
+
+
+class QBasicIOError(QBasicError):
+    """File or I/O error."""
+
+
+class QBasicUndefinedError(QBasicError):
+    """Reference to undefined name."""

qbasic_core/exec_context.py

@@ -0,0 +1,24 @@
+"""QBASIC execution context — unified mutable state for program execution."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ExecContext:
+    """Mutable execution state passed through the entire call tree."""
+
+    sorted_lines: list[int]
+    ip: int
+    run_vars: dict[str, Any]
+    loop_stack: list[dict[str, Any]] = field(default_factory=list)
+    iteration_count: int = 0
+    max_iterations: int = 100_000
+
+    # Qiskit circuit-build path (None in LOCC path)
+    qc: Any = None
+
+    # Backend abstraction (QiskitBackend or LOCCRegBackend)
+    backend: Any = None