qubasic 0.1.0__py3-none-any.whl

qbasic.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""
+QBASIC — Quantum BASIC Interactive Terminal
+
+Usage:
+    python qbasic.py              Interactive REPL
+    python qbasic.py script.qb    Run a script file
+"""
+
+import sys
+import os
+
+# Force UTF-8 output on Windows
+if sys.stdout and hasattr(sys.stdout, 'reconfigure'):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+if sys.stderr and hasattr(sys.stderr, 'reconfigure'):
+    try:
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+from qbasic_core.terminal import QBasicTerminal
+from qbasic_core.program_mgmt import ProgramMgmtMixin
+
+
+def run_script(path: str, terminal: 'QBasicTerminal') -> None:
+    """Run a .qb script file. Supports multi-line DEF blocks.
+
+    After loading all lines, auto-runs the program if it contains
+    numbered lines with a MEASURE statement.
+    """
+    with open(path, 'r') as f:
+        lines = [l.rstrip('\n\r') for l in f.readlines()]
+    ProgramMgmtMixin._load_lines_with_defs(
+        lines, lambda line: terminal.process(line, track_undo=False))
+
+    # Auto-run if the program has a MEASURE statement
+    has_measure = any(
+        terminal.program.get(ln, '').strip().upper() == 'MEASURE'
+        for ln in terminal.program
+    )
+    if terminal.program and has_measure:
+        terminal.cmd_run()
+
+
+def main():
+    import json as _json
+    os.environ.setdefault('PYTHONIOENCODING', 'utf-8')
+
+    args = sys.argv[1:]
+    quiet = '--quiet' in args or '-q' in args
+    json_mode = '--json' in args
+    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']
+
+    if any(a in ('-h', '--help') for a in args):
+        from qbasic_core import __version__
+        print(f"QBASIC {__version__} — Quantum BASIC Interactive Terminal")
+        print()
+        print("Usage:")
+        print("  qbasic                  Interactive REPL")
+        print("  qbasic script.qb        Run a script file")
+        print("  qbasic --quiet script    Suppress banner and progress")
+        print("  qbasic --json script     Output results as JSON")
+        print("  qbasic --help            Show this help")
+        print()
+        print("Type HELP inside the REPL for full command reference.")
+        sys.exit(0)
+
+    term = QBasicTerminal()
+
+    if args:
+        path = args[0]
+        if os.path.isfile(path):
+            if quiet or json_mode:
+                import io
+                buf = io.StringIO()
+                old = sys.stdout
+                sys.stdout = buf
+                try:
+                    run_script(path, term)
+                finally:
+                    sys.stdout = old
+                if json_mode:
+                    result = {
+                        'counts': term.last_counts or {},
+                        'num_qubits': term.num_qubits,
+                        'shots': term.shots,
+                    }
+                    print(_json.dumps(result, indent=2))
+                elif not quiet:
+                    print(buf.getvalue())
+            else:
+                term.print_banner()
+                run_script(path, term)
+            # Exit code: 0 if results exist, 1 if error
+            sys.exit(0 if term.last_counts is not None or not any(
+                term.program.get(ln, '').strip().upper() == 'MEASURE'
+                for ln in term.program) else 1)
+        else:
+            print(f"?FILE NOT FOUND: {path}")
+            sys.exit(1)
+    else:
+        term.repl()
+
+
+if __name__ == '__main__':
+    main()

qbasic_core/__init__.py

@@ -0,0 +1,80 @@
+"""QBASIC — Quantum BASIC Interactive Terminal (package)."""
+
+# Lightweight imports that don't pull in Qiskit/numpy
+from qbasic_core.statements import Stmt, GateStmt, RawStmt
+from qbasic_core.errors import (
+    QBasicError, QBasicSyntaxError, QBasicRuntimeError,
+    QBasicBuildError, QBasicRangeError, QBasicIOError, QBasicUndefinedError,
+)
+from qbasic_core.io_protocol import IOPort, StdIOPort
+from qbasic_core.exec_context import ExecContext
+
+__all__ = [
+    'QBasicTerminal', 'LOCCEngine', 'ExecResult', 'ExecOutcome',
+    'ExpressionMixin', 'DisplayMixin', 'DemoMixin', 'ControlFlowMixin',
+    'LOCCMixin', 'LOCCCommandsMixin', 'LOCCDisplayMixin', 'LOCCExecutionMixin',
+    'NoiseMixin', 'StateDisplayMixin', 'HELP_TEXT', 'BANNER_ART',
+    'FileIOMixin', 'AnalysisMixin', 'SweepMixin',
+    'MemoryMixin', 'StringMixin', 'ScreenMixin', 'ClassicMixin',
+    'SubroutineMixin', 'DebugMixin', 'ProgramMgmtMixin', 'ProfilerMixin',
+    'TerminalProtocol',
+    'Engine', 'ExecutorMixin',
+    'QBasicError', 'QBasicSyntaxError', 'QBasicRuntimeError',
+    'QBasicBuildError', 'QBasicRangeError', 'QBasicIOError', 'QBasicUndefinedError',
+    'IOPort', 'StdIOPort',
+    'Stmt', 'GateStmt', 'RawStmt', 'parse_stmt',
+    'ExecContext', 'Scope',
+    'QuantumBackend', 'QiskitBackend', 'LOCCRegBackend',
+    'GATE_TABLE', 'GATE_ALIASES',
+]
+
+__version__ = '0.1.0'
+
+def __getattr__(name):
+    """Lazy import heavy modules on first access."""
+    _lazy_imports = {
+        'GATE_TABLE': 'qbasic_core.engine',
+        'GATE_ALIASES': 'qbasic_core.engine',
+        'LOCCEngine': 'qbasic_core.engine',
+        'ExecResult': 'qbasic_core.engine',
+        'ExecOutcome': 'qbasic_core.engine',
+        'QBasicTerminal': 'qbasic_core.terminal',
+        'Engine': 'qbasic_core.engine_state',
+        'ExecutorMixin': 'qbasic_core.executor',
+        'ExpressionMixin': 'qbasic_core.expression',
+        'DisplayMixin': 'qbasic_core.display',
+        'LOCCMixin': 'qbasic_core.locc',
+        'LOCCCommandsMixin': 'qbasic_core.locc_commands',
+        'LOCCDisplayMixin': 'qbasic_core.locc_display',
+        'LOCCExecutionMixin': 'qbasic_core.locc_execution',
+        'ControlFlowMixin': 'qbasic_core.control_flow',
+        'DemoMixin': 'qbasic_core.demos',
+        'FileIOMixin': 'qbasic_core.file_io',
+        'AnalysisMixin': 'qbasic_core.analysis',
+        'SweepMixin': 'qbasic_core.sweep',
+        'MemoryMixin': 'qbasic_core.memory',
+        'StringMixin': 'qbasic_core.strings',
+        'ScreenMixin': 'qbasic_core.screen',
+        'ClassicMixin': 'qbasic_core.classic',
+        'SubroutineMixin': 'qbasic_core.subs',
+        'DebugMixin': 'qbasic_core.debug',
+        'ProgramMgmtMixin': 'qbasic_core.program_mgmt',
+        'ProfilerMixin': 'qbasic_core.profiler',
+        'NoiseMixin': 'qbasic_core.noise_mixin',
+        'StateDisplayMixin': 'qbasic_core.state_display',
+        'TerminalProtocol': 'qbasic_core.protocol',
+        'HELP_TEXT': 'qbasic_core.help_text',
+        'BANNER_ART': 'qbasic_core.help_text',
+        'QuantumBackend': 'qbasic_core.backend',
+        'QiskitBackend': 'qbasic_core.backend',
+        'LOCCRegBackend': 'qbasic_core.backend',
+        'Scope': 'qbasic_core.scope',
+        'parse_stmt': 'qbasic_core.parser',
+    }
+    if name in _lazy_imports:
+        import importlib
+        module = importlib.import_module(_lazy_imports[name])
+        val = getattr(module, name)
+        globals()[name] = val  # cache for next access
+        return val
+    raise AttributeError(f"module 'qbasic_core' has no attribute {name}")

qbasic_core/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running qbasic_core as a module: python -m qbasic_core."""
+
+from qbasic_core.terminal import QBasicTerminal
+
+if __name__ == '__main__':
+    QBasicTerminal().repl()

qbasic_core/analysis.py

@@ -0,0 +1,179 @@
+"""QBASIC analysis mixin — EXPECT, ENTROPY, DENSITY, BENCH, RAM."""
+
+from __future__ import annotations
+
+import time
+
+from qiskit import QuantumCircuit, transpile
+from qiskit_aer import AerSimulator
+import numpy as np
+
+from qbasic_core.engine import (
+    _estimate_gb, _get_ram_gb,
+    OVERHEAD_FACTOR, RAM_BUDGET_FRACTION,
+)
+
+
+class AnalysisMixin:
+    """Analysis and introspection commands for QBasicTerminal.
+
+    Requires: TerminalProtocol — uses self.last_sv, self.last_counts,
+    self.num_qubits, self.shots, self.sim_method, self.sim_device,
+    self.locc, self.locc_mode.
+    """
+
+    def cmd_expect(self, rest: str) -> None:
+        """EXPECT <pauli> [qubits] — compute expectation value.
+        Examples: EXPECT Z 0, EXPECT ZZ 0 1, EXPECT X 0"""
+        if self.last_sv is None:
+            self.io.writeln("?NO STATE — RUN first")
+            return
+        parts = rest.split()
+        if not parts:
+            self.io.writeln("?USAGE: EXPECT <Z|X|Y|ZZ|...> [qubits]")
+            return
+        pauli_str = parts[0].upper()
+        qubits = [int(q) for q in parts[1:]] if len(parts) > 1 else list(range(len(pauli_str)))
+
+        try:
+            from qiskit.quantum_info import Statevector, SparsePauliOp
+            sv = Statevector(np.ascontiguousarray(self.last_sv).ravel())
+            # Build Pauli string for full system
+            full_pauli = ['I'] * self.num_qubits
+            for i, p in enumerate(pauli_str):
+                if i < len(qubits):
+                    full_pauli[self.num_qubits - 1 - qubits[i]] = p
+            op = SparsePauliOp(''.join(full_pauli))
+            val = sv.expectation_value(op)
+            self.io.writeln(f"  <{pauli_str}> on qubits {qubits} = {val.real:.6f}")
+        except Exception as e:
+            self.io.writeln(f"?EXPECT ERROR: {e}")
+
+    def cmd_entropy(self, rest: str = '') -> None:
+        """ENTROPY [qubits] — entanglement entropy of specified qubits vs rest.
+        Examples: ENTROPY 0  |  ENTROPY 0 1  |  ENTROPY (defaults to qubit 0)"""
+        if self.last_sv is None:
+            self.io.writeln("?NO STATE — RUN first")
+            return
+        if rest.strip():
+            partition_a = [int(q) for q in rest.replace(',', ' ').split() if q.strip()]
+        else:
+            partition_a = [0]
+        n = self.num_qubits
+        try:
+            from qiskit.quantum_info import Statevector, entropy, partial_trace
+            sv_obj = Statevector(np.ascontiguousarray(self.last_sv).ravel())
+            keep = partition_a
+            rho_a = partial_trace(sv_obj, [q for q in range(n) if q not in keep])
+            ent = entropy(rho_a, base=2)
+            self.io.writeln(f"  Entanglement entropy S(A) = {ent:.6f} bits")
+            self.io.writeln(f"  Partition A: qubits {partition_a}")
+            self.io.writeln(f"  Partition B: qubits {[q for q in range(n) if q not in partition_a]}")
+            if ent < 0.01:
+                self.io.writeln(f"  -> Qubits are separable (product state)")
+            elif abs(ent - len(partition_a)) < 0.01:
+                self.io.writeln(f"  -> Maximally entangled")
+        except Exception as e:
+            self.io.writeln(f"?ENTROPY ERROR: {e}")
+
+    def cmd_density(self) -> None:
+        """Show density matrix (or partial trace for small systems)."""
+        if self.last_sv is None:
+            self.io.writeln("?NO STATE — RUN first")
+            return
+        sv = np.ascontiguousarray(self.last_sv).ravel()
+        rho = np.outer(sv, sv.conj())
+        n = self.num_qubits
+        dim = 2**n
+        if dim > 16:
+            self.io.writeln(f"  Density matrix: {dim}x{dim} (too large to display)")
+            self.io.writeln(f"  Purity: {np.real(np.trace(rho @ rho)):.6f}")
+            self.io.write(f"  Von Neumann entropy: ")
+            eigvals = np.linalg.eigvalsh(rho)
+            eigvals = eigvals[eigvals > 1e-15]
+            ent = -np.sum(eigvals * np.log2(eigvals))
+            self.io.writeln(f"{ent:.6f} bits")
+            return
+        self.io.writeln(f"\n  Density matrix ({dim}x{dim}):\n")
+        for i in range(dim):
+            row = []
+            for j in range(dim):
+                v = rho[i, j]
+                if abs(v.imag) < 1e-6:
+                    row.append(f"{v.real:7.3f}")
+                else:
+                    row.append(f"{v.real:+.2f}{v.imag:+.2f}j")
+            self.io.writeln(f"    {'  '.join(row)}")
+        self.io.writeln(f"\n  Purity: {np.real(np.trace(rho @ rho)):.6f}")
+        self.io.writeln('')
+
+    def cmd_bench(self) -> None:
+        """BENCH — benchmark simulation at various qubit counts."""
+        self.io.writeln("\n  Benchmark (H + CX chain + measure):")
+        try:
+            import psutil
+            has_psutil = True
+        except ImportError:
+            has_psutil = False
+        header_mem = '  mem_gb' if has_psutil else ''
+        self.io.writeln(f"  {'qubits':>8}  {'method':>20}  {'time':>8}{header_mem}")
+        for n in [4, 8, 12, 16, 20, 24, 28]:
+            qc = QuantumCircuit(n)
+            for i in range(n):
+                qc.h(i)
+            for i in range(n - 1):
+                qc.cx(i, i + 1)
+            qc.measure_all()
+            method = 'stabilizer' if n > 28 else 'automatic'
+            backend = AerSimulator(method=method)
+            t0 = time.time()
+            try:
+                result = backend.run(transpile(qc, backend), shots=100).result()
+                dt = time.time() - t0
+                mem_str = f"  {psutil.virtual_memory().used / 1e9:>7.1f}" if has_psutil else ""
+                self.io.writeln(f"  {n:>8}  {method:>20}  {dt:>7.2f}s{mem_str}")
+            except Exception as e:
+                self.io.writeln(f"  {n:>8}  {method:>20}  FAILED: {e}")
+        self.io.writeln('')
+
+    def cmd_ram(self) -> None:
+        """RAM — show memory budget, per-instance cost, and parallelism estimates."""
+        ram = _get_ram_gb()
+        if not ram:
+            self.io.writeln("?psutil not installed — RAM detection unavailable")
+            self.io.writeln("  Install: pip install psutil")
+            return
+        total, avail = ram
+        budget = total * RAM_BUDGET_FRACTION
+
+        self.io.writeln(f"\n  System RAM: {total:.1f} GB total, {avail:.1f} GB available")
+        self.io.writeln(f"  80% budget: {budget:.1f} GB\n")
+
+        if self.locc_mode and self.locc:
+            mode = "JOINT" if self.locc.joint else "SPLIT"
+            sizes_str = '+'.join(str(s) for s in self.locc.sizes)
+            est, _ = self.locc.mem_gb()
+            max_par = int(budget / est) if est > 0 else 0
+            self.io.writeln(f"  Current: LOCC {mode} {sizes_str}q")
+            self.io.writeln(f"    Per instance: {est:.2f} GB")
+            if max_par > 0:
+                self.io.writeln(f"    Parallel:     ~{max_par} instances in budget")
+        else:
+            n = self.num_qubits
+            est = _estimate_gb(n)
+            max_par = int(budget / est) if est > 0 else 0
+            self.io.writeln(f"  Current: {n} qubits")
+            self.io.writeln(f"    Per instance: {est:.2f} GB")
+            if max_par > 0:
+                self.io.writeln(f"    Parallel:     ~{max_par} instances in budget")
+
+        self.io.writeln(f"\n  Qubit scaling (per instance, with {OVERHEAD_FACTOR:.0f}x overhead):")
+        for nq in [16, 20, 24, 28, 30, 32]:
+            e = _estimate_gb(nq)
+            mp = int(budget / e) if e > 0 and budget >= e else 0
+            marker = " <--" if nq == self.num_qubits else ""
+            if mp > 0:
+                self.io.writeln(f"    {nq:>2} qubits: {e:>8.2f} GB  ->  ~{mp:>6,} parallel{marker}")
+            else:
+                self.io.writeln(f"    {nq:>2} qubits: {e:>8.2f} GB  ->  exceeds budget{marker}")
+        self.io.writeln('')

qbasic_core/backend.py

@@ -0,0 +1,76 @@
+"""QBASIC backend abstraction — Qiskit and numpy behind a common interface."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+import numpy as np
+
+
+class QuantumBackend(Protocol):
+    """Abstract quantum backend for gate application."""
+
+    def apply_gate(self, gate_name: str, params: tuple[float, ...],
+                   qubits: list[int]) -> None: ...
+    def barrier(self) -> None: ...
+    def reset(self, qubit: int) -> None: ...
+
+
+class QiskitBackend:
+    """Wraps a QuantumCircuit for the circuit-build path."""
+
+    def __init__(self, qc: Any, apply_gate_fn: Any):
+        self._qc = qc
+        self._apply_gate = apply_gate_fn
+
+    def apply_gate(self, gate_name: str, params: tuple[float, ...],
+                   qubits: list[int]) -> None:
+        self._apply_gate(self._qc, gate_name, list(params), qubits)
+
+    def barrier(self) -> None:
+        self._qc.barrier()
+
+    def reset(self, qubit: int) -> None:
+        self._qc.reset(qubit)
+
+    def measure(self, qubit: int, classical_bit: Any) -> None:
+        self._qc.measure(qubit, classical_bit)
+
+    def add_classical_register(self, name: str, size: int = 1) -> Any:
+        from qiskit.circuit import ClassicalRegister
+        cr = ClassicalRegister(size, name)
+        self._qc.add_register(cr)
+        return cr
+
+    def h(self, qubit: int) -> None:
+        self._qc.h(qubit)
+
+    def append_inverse(self, sub_qc: Any, qubits: list[int]) -> None:
+        self._qc.append(sub_qc.inverse(), qubits)
+
+    def append_controlled(self, gate: Any, qubits: list[int]) -> None:
+        self._qc.append(gate, qubits)
+
+    @property
+    def qc(self) -> Any:
+        return self._qc
+
+
+class LOCCRegBackend:
+    """Wraps a LOCCEngine register for the numpy path."""
+
+    def __init__(self, engine: Any, reg: str):
+        self._engine = engine
+        self._reg = reg
+
+    def apply_gate(self, gate_name: str, params: tuple[float, ...],
+                   qubits: list[int]) -> None:
+        self._engine.apply(self._reg, gate_name, params, qubits)
+
+    def barrier(self) -> None:
+        pass
+
+    def reset(self, qubit: int) -> None:
+        outcome = self._engine.send(self._reg, qubit)
+        if outcome == 1:
+            self._engine.apply(self._reg, 'X', (), [qubit])