qubasic 0.4.0__tar.gz → 0.5.0__tar.gz

{qubasic-0.4.0 → qubasic-0.5.0}/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 0.5.0 (2026-03-30)
+
+- **Colorized histograms**: bars colored green/yellow/dim by probability in terminal
+- **Animated STEP mode**: press A during STEP for auto-advance with configurable delay
+- **"Did you mean?"**: typo suggestions for misspelled commands (BLASCH -> BLOCH)
+- **Status bar prompt**: REPL prompt shows qubit count, LOCC, noise status
+- **DRAW command**: braille-character Bloch sphere rendering
+- **Color-coded LIST**: gates in cyan, flow in yellow, comments dim (THEME controls)
+- **Gate throughput**: RUN summary shows gates/s and circuit complexity (T-count, CNOT count)
+- **COMPARE command**: run circuit with two methods and diff output distributions
+- **HEATMAP command**: qubit-qubit entanglement entropy grid
+- **Startup tip of the day**: random tip shown at REPL launch
+- **ANIMATE command**: animated parameter sweep with in-place terminal updates
+- **QUIZ mode**: interactive quantum computing quiz with multiple choice
+- **Tab completion for file paths**: SAVE/LOAD/INCLUDE complete .qb filenames
+- **DIFF command**: diff current program against another BANK slot
+- **PLOT command**: ASCII scatter plot of P(top state) vs swept variable
+- **UNDO preview**: shows what lines will change before applying
+- **THEME command**: switch color schemes (default, retro, none)
+- **F1/F2/F3 demo shortcuts**: load Bell, GHZ, Grover demos via function keys
+- **Quantum spinner**: |0>, |+>, |1>, |-> cycling during STATS and LOCC progress
+- **EXPLAIN command**: describe each program line in plain English
+- **LOCC progress spinner**: quantum-themed progress during SEND-based LOCC runs
+- **CLIP command**: copy last results to system clipboard
+- **Sound on completion**: terminal bell for runs exceeding 2 seconds
+- New QoLMixin with 24 quality-of-life features
+
+## 0.4.1 (2026-03-30)
+
+- **Fix SEED dispatch**: moved from no-arg to with-arg dispatch table so `SEED 42` works from the REPL
+- **Fix GPU probe**: `cmd_method` GPU probe used undefined `_pqc` variable; now uses `_pqc_m`
+- **Fix LOCC non-numeric args**: `LOCC 4 banana` no longer crashes with unguarded ValueError
+- **Coverage threshold**: raised CI coverage floor from 60% to 75%
+- **Property-based tests**: 4 new hypothesis tests (arithmetic identity, parser fuzzing, process fuzzing, FOR loop count)
+- **CLI integration tests**: 8 new tests covering dispatch, SEED, LOCC error handling, METHOD probe, --seed flag, --help
+- **Parser imports**: import regexes from patterns.py directly instead of double-indirection through engine.py
+- **Expression simplification**: `_replace_dollar_outside_strings` reduced from two passes to one
+- **Jump table**: pre-compute WHILE/WEND and DO/LOOP ip mappings in `_scan_subs`; `_find_matching_wend` and `_find_matching_loop` use O(1) lookup when available
+- **Scope cleanup**: removed dual-write hack in `Scope.__setitem__`; writes go to `_runtime` only, `_persistent` is read-through fallback
+- **STATS output**: redirect stdout during stats runs to suppress rich console output in non-TTY mode
+- **Copyright year**: LICENSE updated from 2025 to 2026
+- **CLI --seed flag**: `qubasic --seed N script.qb` sets deterministic seed before execution
+- **Type annotations**: added return type annotations to 14 unannotated mixin methods across locc_commands, locc_display, locc_execution, demos
+
 ## 0.4.0 (2026-03-29)
 
 - **Noise correctness**: transpile with optimization_level=0 when noisy so gates survive for noise attachment

{qubasic-0.4.0 → qubasic-0.5.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Charles C. Norton
+Copyright (c) 2026 Charles C. Norton
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{qubasic-0.4.0/qubasic.egg-info → qubasic-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qubasic
-Version: 0.4.0
+Version: 0.5.0
 Summary: Quantum BASIC Interactive Terminal
 Author-email: "Charles C. Norton" <machineelv@gmail.com>
 License-Expression: MIT

{qubasic-0.4.0 → qubasic-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qubasic"
-version = "0.4.0"
+version = "0.5.0"
 description = "Quantum BASIC Interactive Terminal"
 readme = "README.md"
 requires-python = ">=3.10"

{qubasic-0.4.0 → qubasic-0.5.0/qubasic.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qubasic
-Version: 0.4.0
+Version: 0.5.0
 Summary: Quantum BASIC Interactive Terminal
 Author-email: "Charles C. Norton" <machineelv@gmail.com>
 License-Expression: MIT

{qubasic-0.4.0 → qubasic-0.5.0}/qubasic.egg-info/SOURCES.txt

@@ -46,6 +46,7 @@ qubasic_core/patterns.py
 qubasic_core/profiler.py
 qubasic_core/program_mgmt.py
 qubasic_core/protocol.py
+qubasic_core/qol.py
 qubasic_core/scope.py
 qubasic_core/screen.py
 qubasic_core/state_display.py

{qubasic-0.4.0 → qubasic-0.5.0}/qubasic.py

@@ -53,10 +53,22 @@ def main():
     args = sys.argv[1:]
     quiet = '--quiet' in args or '-q' in args
     json_mode = '--json' in args
+    seed_val = None
     if quiet:
         args = [a for a in args if a not in ('--quiet', '-q')]
     if json_mode:
         args = [a for a in args if a != '--json']
+    # Parse --seed N
+    filtered = []
+    i = 0
+    while i < len(args):
+        if args[i] == '--seed' and i + 1 < len(args):
+            seed_val = int(args[i + 1])
+            i += 2
+        else:
+            filtered.append(args[i])
+            i += 1
+    args = filtered
 
     if any(a in ('-h', '--help') for a in args):
         from qubasic_core import __version__
@@ -67,12 +79,17 @@ def main():
         print("  qubasic script.qb        Run a script file")
         print("  qubasic --quiet script    Suppress banner and progress")
         print("  qubasic --json script     Output results as JSON")
+        print("  qubasic --seed N script   Set random seed for reproducibility")
         print("  qubasic --help            Show this help")
         print()
         print("Type HELP inside the REPL for full command reference.")
         sys.exit(0)
 
     term = QBasicTerminal()
+    if seed_val is not None:
+        import numpy as _np
+        term._seed = seed_val
+        _np.random.seed(seed_val)
 
     if args:
         path = args[0]

{qubasic-0.4.0 → qubasic-0.5.0}/qubasic_core/__init__.py

@@ -28,7 +28,7 @@ __all__ = [
     'GATE_TABLE', 'GATE_ALIASES',
 ]
 
-__version__ = '0.4.0'
+__version__ = '0.5.0'
 
 def __getattr__(name):
     """Lazy import heavy modules on first access."""

{qubasic-0.4.0 → qubasic-0.5.0}/qubasic_core/classic.py

@@ -217,6 +217,9 @@ class ClassicMixin:
     # ── DO / LOOP ─────────────────────────────────────────────────────
 
     def _find_matching_loop(self, sorted_lines: list[int], ip: int) -> int:
+        jt = getattr(self, '_jump_table', None)
+        if jt and ip in jt:
+            return jt[ip]
         depth = 1
         scan = ip + 1
         while scan < len(sorted_lines):

{qubasic-0.4.0 → qubasic-0.5.0}/qubasic_core/control_flow.py

@@ -166,10 +166,12 @@ class ControlFlowMixin:
     def _find_matching_wend(self, sorted_lines: list[int], ip: int) -> int:
         """Find the ip after the WEND matching the WHILE at ip.
 
-        Scans forward with proper nesting depth tracking. Returns the ip
-        index past the matching WEND. Raises with the WHILE line number
-        for clear diagnostics.
+        Uses pre-computed jump table when available (O(1)), falls back
+        to linear scan with nesting depth tracking.
         """
+        jt = getattr(self, '_jump_table', None)
+        if jt and ip in jt:
+            return jt[ip] + 1
         depth = 1
         scan = ip + 1
         while scan < len(sorted_lines):

{qubasic-0.4.0 → qubasic-0.5.0}/qubasic_core/demos.py

@@ -8,7 +8,7 @@ class DemoMixin:
     self.shots, self.cmd_new(), self.cmd_run(), self.cmd_list(), self.cmd_locc().
     """
 
-    def cmd_demo(self, name):
+    def cmd_demo(self, name: str) -> None:
         demos = {
             'BELL':        self._demo_bell,
             'GHZ':         self._demo_ghz,

{qubasic-0.4.0 → qubasic-0.5.0}/qubasic_core/display.py

@@ -88,11 +88,21 @@ class DisplayMixin:
         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
 
+        _theme = getattr(self, '_theme', {})
         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"
+            # Colorize bar by probability
+            if _theme and sys.stdout.isatty():
+                rst = _theme.get('reset', '')
+                if pct > 40:
+                    bar = f"{_theme.get('bar_hi', '')}{bar}{rst}"
+                elif pct > 10:
+                    bar = f"{_theme.get('bar_mid', '')}{bar}{rst}"
+                else:
+                    bar = f"{_theme.get('bar_lo', '')}{bar}{rst}"
             self.io.writeln(f"  {ket:>{max_label+3}}  {count:>6}  ({pct:5.1f}%)  {bar}")
 
         if len(sorted_counts) > MAX_HISTOGRAM_STATES:

{qubasic-0.4.0 → qubasic-0.5.0}/qubasic_core/expression.py

@@ -12,44 +12,28 @@ from typing import Any
 
 
 def _replace_dollar_outside_strings(expr_str: str) -> str:
-    """Apply $->_S_ replacement only outside quoted string literals."""
-    result: list[str] = []
+    """Apply $->_S_ replacement only outside quoted string literals.
+
+    Single pass: splits on quote boundaries, substitutes only in
+    unquoted segments.
+    """
+    parts: list[str] = []
     i = 0
     n = len(expr_str)
     while i < n:
         ch = expr_str[i]
         if ch in ('"', "'"):
-            # Copy the entire quoted region verbatim
             quote = ch
             j = i + 1
             while j < n and expr_str[j] != quote:
                 j += 1
-            # Include closing quote (or end of string if missing)
-            result.append(expr_str[i:j + 1])
-            i = j + 1
-        else:
-            result.append(ch)
-            i += 1
-    text = ''.join(result)
-    # Now apply the substitution only to non-quoted segments
-    parts: list[str] = []
-    i = 0
-    n = len(text)
-    while i < n:
-        ch = text[i]
-        if ch in ('"', "'"):
-            quote = ch
-            j = i + 1
-            while j < n and text[j] != quote:
-                j += 1
-            parts.append(text[i:j + 1])
+            parts.append(expr_str[i:j + 1])
             i = j + 1
         else:
-            # Accumulate non-quoted text
             j = i
-            while j < n and text[j] not in ('"', "'"):
+            while j < n and expr_str[j] not in ('"', "'"):
                 j += 1
-            segment = text[i:j]
+            segment = expr_str[i:j]
             parts.append(re.sub(r'(\w+)\$', r'\1_S_', segment))
             i = j
     return ''.join(parts)

{qubasic-0.4.0 → qubasic-0.5.0}/qubasic_core/locc_commands.py

@@ -24,7 +24,7 @@ class LOCCCommandsMixin:
         """
         return getattr(self, '_noise_depol_p', 0.0)
 
-    def cmd_locc(self, rest):
+    def cmd_locc(self, rest: str) -> None:
         args = rest.upper().split()
         if not args:
             if self.locc_mode:
@@ -86,7 +86,11 @@ class LOCCCommandsMixin:
             self.io.writeln(f"?MAX {LOCC_MAX_REGISTERS} registers (A-Z)")
             return
 
-        sizes = [int(n) for n in nums]
+        try:
+            sizes = [int(n) for n in nums]
+        except ValueError:
+            self.io.writeln("?LOCC register sizes must be integers")
+            return
         total = sum(sizes)
         if joint and total > LOCC_MAX_JOINT_QUBITS:
             self.io.writeln(f"?JOINT mode limited to {LOCC_MAX_JOINT_QUBITS} total qubits (requested {total})")
@@ -130,7 +134,7 @@ class LOCCCommandsMixin:
             self.io.writeln(f"  WARNING: non-depolarizing noise model active but not supported "
                            f"in LOCC numpy path. Only NOISE depolarizing propagates to LOCC.")
 
-    def cmd_send(self, rest):
+    def cmd_send(self, rest: str) -> None:
         if not self.locc_mode:
             self.io.writeln("?SEND requires LOCC mode")
             return
@@ -153,7 +157,7 @@ class LOCCCommandsMixin:
         self.locc.classical[var] = outcome
         self.io.writeln(f"  {reg}[{qubit}] -> {var} = {outcome}")
 
-    def cmd_share(self, rest):
+    def cmd_share(self, rest: str) -> None:
         if not self.locc_mode:
             self.io.writeln("?SHARE requires LOCC mode")
             return
@@ -173,7 +177,7 @@ class LOCCCommandsMixin:
         except RuntimeError as e:
             self.io.writeln(f"?{e}")
 
-    def cmd_loccinfo(self):
+    def cmd_loccinfo(self) -> None:
         """Show LOCC protocol metrics after a run."""
         if not self.locc_mode:
             self.io.writeln("?NOT IN LOCC MODE")

{qubasic-0.4.0 → qubasic-0.5.0}/qubasic_core/locc_display.py

@@ -10,7 +10,7 @@ class LOCCDisplayMixin:
     self._print_bloch_single(), self.print_histogram(), self.io.
     """
 
-    def _locc_state(self, rest=''):
+    def _locc_state(self, rest: str = '') -> None:
         reg = rest.strip().upper() if rest else ''
         if self.locc.joint:
             if not reg or reg in self.locc.names:
@@ -24,7 +24,7 @@ class LOCCDisplayMixin:
                 self.io.writeln(f"\n  Register {name} ({size} qubits):")
                 self._print_statevector(self.locc.svs[name], size)
 
-    def _locc_bloch(self, rest):
+    def _locc_bloch(self, rest: str) -> None:
         m = re.match(r'([A-Z])\s*(\d*)', rest.strip(), re.IGNORECASE) if rest.strip() else None
         if m and m.group(1):
             reg = m.group(1).upper()
@@ -49,7 +49,7 @@ class LOCCDisplayMixin:
         else:
             self.io.writeln(f"?USAGE: BLOCH <reg> [qubit]  (registers: {', '.join(self.locc.names)})")
 
-    def _locc_display_results(self, per_reg, counts_joint):
+    def _locc_display_results(self, per_reg: dict, counts_joint: dict) -> None:
         """Display per-register and joint histograms."""
         for name in self.locc.names:
             size = self.locc.get_size(name)

{qubasic-0.4.0 → qubasic-0.5.0}/qubasic_core/locc_execution.py

@@ -27,7 +27,7 @@ class LOCCExecutionMixin:
     self.last_counts, self.io.
     """
 
-    def _locc_run(self):
+    def _locc_run(self) -> None:
         """Execute program in LOCC mode (N registers)."""
         sorted_lines = sorted(self.program.keys())
         if not sorted_lines:
@@ -44,7 +44,7 @@ class LOCCExecutionMixin:
         # Sync last_sv from LOCC engine so EXPECT/DENSITY/BLOCH work
         self.last_sv = self._active_sv
 
-    def _locc_run_with_send(self, sorted_lines, has_measure):
+    def _locc_run_with_send(self, sorted_lines: list[int], has_measure: bool) -> None:
         """LOCC execution with SEND — prefix/suffix split optimization.
 
         Executes the deterministic prefix (before first SEND) once,
@@ -134,7 +134,9 @@ class LOCCExecutionMixin:
                 counts_joint[jkey] = counts_joint.get(jkey, 0) + 1
             if shots > 50 and (shot + 1) % progress_interval == 0:
                 pct = 100 * (shot + 1) // shots
-                _prog = f"  {pct}% ({shot+1}/{shots} shots)..."
+                from qubasic_core.qol import quantum_spin
+                spin = quantum_spin(shot)
+                _prog = f"  {spin} {pct}% ({shot+1}/{shots} shots)..."
                 if hasattr(self.io, 'write') and sys.stdout.isatty():
                     self.io.write(_prog + '\r')
                 # Non-terminal: skip progress to avoid \r noise
@@ -148,7 +150,7 @@ class LOCCExecutionMixin:
             self._locc_display_results(per_reg, counts_joint)
             self.last_counts = counts_joint
 
-    def _locc_run_vectorized(self, sorted_lines, has_measure):
+    def _locc_run_vectorized(self, sorted_lines: list[int], has_measure: bool) -> None:
         """LOCC execution without SEND — single execution, vectorized sampling.
 
         When noise is active, re-executes per shot so that Monte Carlo noise
@@ -314,7 +316,7 @@ class LOCCExecutionMixin:
 
         raise ValueError(f"LOCC mode requires @A/@B prefix, SEND, SHARE, or IF: {stmt}")
 
-    def _locc_try_special(self, reg, stmt, run_vars):
+    def _locc_try_special(self, reg: str, stmt: str, run_vars: dict) -> bool:
         """Handle MEAS/RESET/MEASURE_X/Y/Z/SYNDROME in LOCC mode."""
         from qubasic_core.parser import parse_stmt
         from qubasic_core.statements import MeasStmt, ResetStmt, MeasureBasisStmt, SyndromeStmt
@@ -373,7 +375,7 @@ class LOCCExecutionMixin:
 
         return False
 
-    def _locc_apply_gate(self, reg, gate_stmt):
+    def _locc_apply_gate(self, reg: str, gate_stmt: str) -> None:
         """Parse and apply a gate to a LOCC register via numpy.
 
         Uses LOCCRegBackend for standard gates. CTRL and INV modifiers

{qubasic-0.4.0 → qubasic-0.5.0}/qubasic_core/parser.py

@@ -4,8 +4,8 @@ from __future__ import annotations
 
 import re
 
-from qubasic_core.engine import (
-    GATE_TABLE, GATE_ALIASES,
+from qubasic_core.gates import GATE_TABLE, GATE_ALIASES
+from qubasic_core.patterns import (
     RE_LET_ARRAY, RE_LET_VAR, RE_PRINT,
     RE_GOTO, RE_GOSUB, RE_FOR, RE_NEXT, RE_WHILE, RE_IF_THEN,
     RE_MEAS, RE_RESET, RE_SEND, RE_SHARE, RE_AT_REG_LINE, RE_AT_REG,

{qubasic-0.4.0 → qubasic-0.5.0}/qubasic_core/profiler.py

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 import math
+import os
+import sys
 import time
 from typing import Any
 
@@ -111,10 +113,14 @@ class ProfilerMixin:
         self.io.writeln(f"\nRunning {n} trials...")
         for trial in range(n):
             old_io = self.io
+            old_stdout = sys.stdout
             self.io = _NullIOPort()
+            sys.stdout = open(os.devnull, 'w')
             try:
                 self.cmd_run()
             finally:
+                sys.stdout.close()
+                sys.stdout = old_stdout
                 self.io = old_io
             if self.last_counts:
                 if len(self._stats_runs) >= MAX_STATS_RUNS:
@@ -122,7 +128,9 @@ class ProfilerMixin:
                     break
                 self._stats_runs.append(dict(self.last_counts))
             if n > 10 and (trial + 1) % (n // 10) == 0:
-                self.io.write(f"  {100 * (trial + 1) // n}%..." + '\r')
+                from qubasic_core.qol import quantum_spin
+                spin = quantum_spin(trial)
+                self.io.write(f"  {spin} {100 * (trial + 1) // n}%..." + '\r')
         if n > 10:
             self.io.write(" " * 30 + '\r')
         self.io.writeln(f"Collected {len(self._stats_runs)} runs ({n} trials)")