qubasic 0.1.0__py3-none-any.whl

qbasic_core/locc_commands.py

@@ -0,0 +1,221 @@
+"""QBASIC LOCC commands mixin — cmd_locc, cmd_send, cmd_share, cmd_connect, cmd_disconnect, cmd_loccinfo."""
+
+import re
+
+from qbasic_core.engine import (
+    LOCCEngine,
+    _get_ram_gb,
+    LOCC_MAX_JOINT_QUBITS, LOCC_MAX_SPLIT_QUBITS, LOCC_MAX_REGISTERS,
+    RAM_BUDGET_FRACTION,
+)
+
+
+class LOCCCommandsMixin:
+    """LOCC user-facing commands for QBasicTerminal.
+
+    Requires: TerminalProtocol — uses self.locc, self.locc_mode, self.program,
+    self.variables, self.eval_expr(), self.io.
+    """
+
+    def cmd_locc(self, rest):
+        args = rest.upper().split()
+        if not args:
+            if self.locc_mode:
+                mode = "JOINT" if self.locc.joint else "SPLIT"
+                reg_desc = '  '.join(f"{n}={s}q" for n, s in
+                                     zip(self.locc.names, self.locc.sizes))
+                self.io.writeln(f"LOCC {mode}: {reg_desc}")
+                tot, peak = self.locc.mem_gb()
+                self.io.writeln(f"  RAM per instance: {tot:.1f} GB (with overhead)")
+                if self.locc.classical:
+                    self.io.writeln(f"  Classical: {self.locc.classical}")
+            else:
+                self.io.writeln("LOCC OFF. Usage: LOCC [JOINT] <n1> <n2> [n3 ...]")
+            return
+
+        if args[0] == 'OFF':
+            self.locc = None
+            self.locc_mode = False
+            self.io.writeln("LOCC OFF — back to normal Aer mode")
+            return
+
+        if args[0] == 'STATUS':
+            if not self.locc_mode:
+                self.io.writeln("NOT IN LOCC MODE")
+                return
+            mode = "JOINT" if self.locc.joint else "SPLIT"
+            reg_desc = '  '.join(f"{n}={s}q" for n, s in
+                                 zip(self.locc.names, self.locc.sizes))
+            self.io.writeln(f"LOCC {mode}: {reg_desc}")
+            tot, peak = self.locc.mem_gb()
+            self.io.writeln(f"  RAM per instance: {tot:.1f} GB (with overhead)")
+            ram = _get_ram_gb()
+            if ram:
+                budget = ram[0] * RAM_BUDGET_FRACTION
+                max_par = int(budget / tot) if tot > 0 else 0
+                if max_par > 0:
+                    self.io.writeln(f"  Max parallel in 80% budget: ~{max_par}")
+            self.io.writeln(f"  Classical vars: {self.locc.classical if self.locc.classical else '(none)'}")
+            return
+
+        joint = False
+        nums = args
+        if args[0] == 'JOINT':
+            joint = True
+            nums = args[1:]
+        elif args[0] == 'SPLIT':
+            nums = args[1:]
+
+        # Support "2+2+2" notation: split on + if present
+        expanded = []
+        for n in nums:
+            expanded.extend(n.split('+'))
+        nums = [n for n in expanded if n]
+
+        if len(nums) < 2:
+            self.io.writeln("?USAGE: LOCC [JOINT|SPLIT] <n1> <n2> [n3 ...]")
+            return
+        if len(nums) > LOCC_MAX_REGISTERS:
+            self.io.writeln(f"?MAX {LOCC_MAX_REGISTERS} registers (A-Z)")
+            return
+
+        sizes = [int(n) for n in nums]
+        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})")
+            return
+        if not joint and max(sizes) > LOCC_MAX_SPLIT_QUBITS:
+            self.io.writeln(f"?Each register limited to {LOCC_MAX_SPLIT_QUBITS} qubits")
+            return
+
+        # Pre-check RAM before allocating
+        mode = "JOINT" if joint else "SPLIT"
+        temp_eng = LOCCEngine(sizes, joint=joint)
+        tot, peak = temp_eng.mem_gb()
+        ram = _get_ram_gb()
+        if ram and tot > ram[1]:
+            self.io.writeln(f"?BLOCKED: LOCC {mode} needs ~{tot:.1f} GB but only "
+                           f"{ram[1]:.1f} GB available. Reduce register sizes.")
+            return
+
+        self.locc = temp_eng
+        self.locc_mode = True
+        reg_desc = '  '.join(f"{n}={s}q" for n, s in
+                             zip(self.locc.names, sizes))
+        self.io.writeln(f"LOCC {mode}: {reg_desc}  ({total} total)")
+        self.io.writeln(f"  RAM per instance: {tot:.1f} GB (with overhead)")
+        if ram:
+            sys_total, avail = ram
+            budget = sys_total * RAM_BUDGET_FRACTION
+            if tot > 0:
+                max_par = int(budget / tot)
+                if max_par > 0:
+                    self.io.writeln(f"  Max parallel instances in 80% budget: ~{max_par}")
+        if not joint:
+            self.io.writeln(f"  Registers are INDEPENDENT — no cross-register entanglement")
+            self.io.writeln(f"  Use SEND/IF for classical coordination")
+        else:
+            self.io.writeln(f"  Joint statevector — use SHARE for pre-shared entanglement")
+        if peak > 30:
+            self.io.writeln(f"  WARNING: large registers. Keep SHOTS low for SEND-based protocols.")
+
+    def cmd_send(self, rest):
+        if not self.locc_mode:
+            self.io.writeln("?SEND requires LOCC mode")
+            return
+        m = re.match(r'([A-Z])\s+(\S+)\s*->\s*(\w+)', rest, re.IGNORECASE)
+        if not m:
+            self.io.writeln("?USAGE: SEND <reg> <qubit> -> <var>")
+            return
+        reg = m.group(1).upper()
+        if reg not in self.locc.names:
+            self.io.writeln(f"?UNKNOWN REGISTER: {reg} (have {', '.join(self.locc.names)})")
+            return
+        qubit = int(self.eval_expr(m.group(2)))
+        var = m.group(3)
+        n_reg = self.locc.get_size(reg)
+        if qubit < 0 or qubit >= n_reg:
+            self.io.writeln(f"?QUBIT {qubit} OUT OF RANGE for register {reg} (0-{n_reg-1})")
+            return
+        outcome = self.locc.send(reg, qubit)
+        self.variables[var] = outcome
+        self.locc.classical[var] = outcome
+        self.io.writeln(f"  {reg}[{qubit}] -> {var} = {outcome}")
+
+    def cmd_share(self, rest):
+        if not self.locc_mode:
+            self.io.writeln("?SHARE requires LOCC mode")
+            return
+        m = re.match(r'([A-Z])\s+(\d+)\s*,?\s*([A-Z])\s+(\d+)', rest, re.IGNORECASE)
+        if not m:
+            self.io.writeln("?USAGE: SHARE <reg1> <qubit> <reg2> <qubit>")
+            return
+        reg1, q1 = m.group(1).upper(), int(m.group(2))
+        reg2, q2 = m.group(3).upper(), int(m.group(4))
+        for r in (reg1, reg2):
+            if r not in self.locc.names:
+                self.io.writeln(f"?UNKNOWN REGISTER: {r}")
+                return
+        try:
+            self.locc.share(reg1, q1, reg2, q2)
+            self.io.writeln(f"  Bell pair |Phi+> created: {reg1}[{q1}] <-> {reg2}[{q2}]")
+        except RuntimeError as e:
+            self.io.writeln(f"?{e}")
+
+    def cmd_connect(self, rest: str) -> None:
+        """CONNECT "host:port" AS <reg> — attach a remote quantum register.
+
+        Stub: uses local simulation. No network transport implemented.
+
+        Creates a local register that can be used with LOCC commands.
+        The connection info is stored for future network-backed execution.
+        """
+        m = re.match(r'"?([^"]+)"?\s+AS\s+([A-Z])', rest, re.IGNORECASE)
+        if not m:
+            self.io.writeln('?USAGE: CONNECT "host:port" AS <reg>')
+            return
+        endpoint = m.group(1).strip()
+        reg = m.group(2).upper()
+        if not hasattr(self, '_connections'):
+            self._connections = {}
+        self._connections[reg] = endpoint
+        # If not in LOCC mode, auto-enter with a default local register + the remote
+        if not self.locc_mode:
+            self.cmd_locc(f'3 3')
+        self.io.writeln(f"CONNECTED {reg} -> {endpoint} (experimental stub — no real network transport)")
+        self.io.writeln("  (local simulation only)")
+
+    def cmd_disconnect(self, rest: str) -> None:
+        """DISCONNECT <reg> — detach a remote register.
+
+        Stub: uses local simulation. No network transport implemented.
+        """
+        reg = rest.strip().upper()
+        if hasattr(self, '_connections') and reg in self._connections:
+            del self._connections[reg]
+            self.io.writeln(f"DISCONNECTED {reg}")
+        else:
+            self.io.writeln(f"?{reg} NOT CONNECTED")
+
+    def cmd_loccinfo(self):
+        """Show LOCC protocol metrics after a run."""
+        if not self.locc_mode:
+            self.io.writeln("?NOT IN LOCC MODE")
+            return
+        mode = "JOINT" if self.locc.joint else "SPLIT"
+        self.io.writeln(f"\n  LOCC Protocol Metrics ({mode})")
+        reg_desc = '  '.join(f"{n}={s}q" for n, s in
+                             zip(self.locc.names, self.locc.sizes))
+        self.io.writeln(f"  Registers: {reg_desc}  ({self.locc.n_regs} parties)")
+        n_classical = len(self.locc.classical)
+        self.io.writeln(f"  Classical bits exchanged: {n_classical}")
+        if self.locc.classical:
+            for k, v in self.locc.classical.items():
+                self.io.writeln(f"    {k} = {v}")
+        n_sends = sum(1 for l in self.program.values()
+                      if re.search(r'\bSEND\b', l, re.IGNORECASE))
+        self.io.writeln(f"  SEND operations: {n_sends}")
+        self.io.writeln(f"  Communication rounds: ~{n_sends}")
+        tot, peak = self.locc.mem_gb()
+        self.io.writeln(f"  Memory: {tot:.1f} GB")
+        self.io.writeln('')

qbasic_core/locc_display.py

@@ -0,0 +1,61 @@
+"""QBASIC LOCC display mixin — state inspection and Bloch sphere for LOCC registers."""
+
+import re
+
+
+class LOCCDisplayMixin:
+    """LOCC display methods for QBasicTerminal.
+
+    Requires: TerminalProtocol — uses self.locc, self._print_statevector(),
+    self._print_bloch_single(), self.print_histogram(), self.io.
+    """
+
+    def _locc_state(self, rest=''):
+        reg = rest.strip().upper() if rest else ''
+        if self.locc.joint:
+            if not reg or reg in self.locc.names:
+                sizes = '+'.join(str(s) for s in self.locc.sizes)
+                self.io.writeln(f"\n  Joint statevector ({sizes} qubits):")
+                self._print_statevector(self.locc.sv, self.locc.n_total)
+        else:
+            show = [reg] if reg and reg in self.locc.names else self.locc.names
+            for name in show:
+                size = self.locc.get_size(name)
+                self.io.writeln(f"\n  Register {name} ({size} qubits):")
+                self._print_statevector(self.locc.svs[name], size)
+
+    def _locc_bloch(self, rest):
+        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()
+            if reg not in self.locc.names:
+                self.io.writeln(f"?UNKNOWN REGISTER: {reg}")
+                return
+            sv = self.locc.get_sv(reg)
+            n = self.locc.get_n(reg)
+            idx = self.locc._idx(reg)
+            if m.group(2):
+                q = int(m.group(2))
+                actual_q = q if not self.locc.joint else q + self.locc.offsets[idx]
+                self.io.writeln(f"  [Register {reg}, qubit {q}]")
+                self._print_bloch_single(sv, actual_q, n)
+            else:
+                n_show = self.locc.get_size(reg)
+                for q in range(min(n_show, 4)):
+                    actual_q = q if not self.locc.joint else q + self.locc.offsets[idx]
+                    self.io.writeln(f"  [Register {reg}, qubit {q}]")
+                    self._print_bloch_single(sv, actual_q, n)
+                    self.io.writeln('')
+        else:
+            self.io.writeln(f"?USAGE: BLOCH <reg> [qubit]  (registers: {', '.join(self.locc.names)})")
+
+    def _locc_display_results(self, per_reg, counts_joint):
+        """Display per-register and joint histograms."""
+        for name in self.locc.names:
+            size = self.locc.get_size(name)
+            self.io.writeln(f"\n  Register {name} ({size}q):")
+            self.print_histogram(per_reg[name])
+        if counts_joint and self.locc.n_regs <= 4:
+            jlabel = '|'.join(self.locc.names)
+            self.io.writeln(f"\n  Joint ({jlabel}):")
+            self.print_histogram(counts_joint)

qbasic_core/locc_engine.py

@@ -0,0 +1,195 @@
+"""LOCC quantum engine — multi-register simulation with classical channels."""
+
+from __future__ import annotations
+
+import numpy as np
+from qbasic_core.gates import (
+    _np_gate_matrix, _apply_gate_np, _measure_np, _sample_np,
+)
+
+# ═══════════════════════════════════════════════════════════════════════
+# LOCC-specific constants
+# ═══════════════════════════════════════════════════════════════════════
+
+LOCC_MAX_JOINT_QUBITS = 33
+LOCC_MAX_SPLIT_QUBITS = 33
+LOCC_MAX_REGISTERS = 26
+LOCC_SEND_SHOT_CAP = 100
+LOCC_SEND_QUBIT_THRESHOLD = 20
+
+
+class LOCCEngine:
+    """N-register quantum simulation with classical channels.
+
+    Supports 2-26 independent quantum registers (A through Z).
+    SPLIT mode: independent statevectors per register. Max capacity.
+    JOINT mode: one statevector, LOCC constraints enforced.
+    """
+
+    def __init__(self, sizes: list[int], joint: bool = False):
+        """Initialize LOCC engine with given register sizes."""
+        self.sizes = list(sizes)
+        self.n_regs = len(self.sizes)
+        self.names = [chr(ord('A') + i) for i in range(self.n_regs)]
+        self.joint = joint
+        self.classical = {}
+        # Precompute offsets for JOINT mode
+        self.offsets = []
+        off = 0
+        for s in self.sizes:
+            self.offsets.append(off)
+            off += s
+        self.n_total = sum(self.sizes)
+        self.reset()
+
+    # Backward-compatible properties
+    @property
+    def n_a(self):
+        return self.sizes[0] if self.sizes else 0
+
+    @property
+    def n_b(self):
+        return self.sizes[1] if len(self.sizes) > 1 else 0
+
+    def _idx(self, reg):
+        """Register name -> index."""
+        return ord(reg) - ord('A')
+
+    def reset(self) -> None:
+        """Reset all registers to |0> and clear classical state."""
+        self.classical.clear()
+        if self.joint:
+            self.sv = np.zeros(2**self.n_total, dtype=complex)
+            self.sv[0] = 1.0
+        else:
+            self.svs = {}
+            for name, size in zip(self.names, self.sizes):
+                sv = np.zeros(2**size, dtype=complex)
+                sv[0] = 1.0
+                self.svs[name] = sv
+
+    def snapshot(self) -> dict:
+        """Capture current quantum state for later restore."""
+        if self.joint:
+            return {'joint': True, 'sv': self.sv.copy(), 'classical': dict(self.classical)}
+        return {'joint': False,
+                'svs': {n: sv.copy() for n, sv in self.svs.items()},
+                'classical': dict(self.classical)}
+
+    def restore(self, snap: dict) -> None:
+        """Restore quantum state from a snapshot."""
+        self.classical = dict(snap['classical'])
+        if snap['joint']:
+            self.sv = snap['sv'].copy()
+        else:
+            self.svs = {n: sv.copy() for n, sv in snap['svs'].items()}
+
+    def _check_qubits(self, reg: str, qubits: list[int]) -> None:
+        """Validate that all qubit indices are in range for the given register."""
+        size = self.sizes[self._idx(reg)]
+        for q in qubits:
+            if q < 0 or q >= size:
+                raise ValueError(
+                    f"Qubit {q} out of range for register {reg} (size {size})"
+                )
+
+    def apply(self, reg: str, gate_name: str, params: tuple[float, ...], qubits: list[int]) -> None:
+        """Apply a gate to a specific register."""
+        self._check_qubits(reg, qubits)
+        matrix = _np_gate_matrix(gate_name, tuple(params))
+        if self.joint:
+            idx = self._idx(reg)
+            actual = [q + self.offsets[idx] for q in qubits]
+            self.sv = _apply_gate_np(self.sv, matrix, actual, self.n_total)
+        else:
+            size = self.sizes[self._idx(reg)]
+            self.svs[reg] = _apply_gate_np(self.svs[reg], matrix, qubits, size)
+
+    def share(self, reg1: str, q1: int, reg2: str, q2: int) -> None:
+        """Create Bell pair |Phi+> between reg1[q1] and reg2[q2]. JOINT only."""
+        if not self.joint:
+            raise RuntimeError("SHARE requires LOCC JOINT mode")
+        self._check_qubits(reg1, [q1])
+        self._check_qubits(reg2, [q2])
+        h = _np_gate_matrix('H', ())
+        cx = _np_gate_matrix('CX', ())
+        actual1 = q1 + self.offsets[self._idx(reg1)]
+        actual2 = q2 + self.offsets[self._idx(reg2)]
+        self.sv = _apply_gate_np(self.sv, h, [actual1], self.n_total)
+        self.sv = _apply_gate_np(self.sv, cx, [actual1, actual2], self.n_total)
+
+    def send(self, reg: str, qubit: int) -> int:
+        """Measure a qubit (Born rule) and return the classical outcome."""
+        self._check_qubits(reg, [qubit])
+        if self.joint:
+            actual = qubit + self.offsets[self._idx(reg)]
+            outcome, self.sv = _measure_np(self.sv, actual, self.n_total)
+        else:
+            size = self.sizes[self._idx(reg)]
+            outcome, self.svs[reg] = _measure_np(self.svs[reg], qubit, size)
+        return outcome
+
+    def get_sv(self, reg: str) -> np.ndarray:
+        if self.joint:
+            return self.sv
+        return self.svs[reg]
+
+    def get_n(self, reg: str) -> int:
+        if self.joint:
+            return self.n_total
+        return self.sizes[self._idx(reg)]
+
+    def get_size(self, reg: str) -> int:
+        return self.sizes[self._idx(reg)]
+
+    def sample_joint(self, shots: int) -> tuple[dict[str, dict[str, int]], dict[str, int]]:
+        """Sample and return (per_reg_counts, joint_counts)."""
+        if self.joint:
+            raw = _sample_np(self.sv, self.n_total, shots)
+            per_reg = {name: {} for name in self.names}
+            joint = {}
+            for state, count in raw.items():
+                # Split the joint bitstring into per-register segments.
+                # The joint statevector is ordered A[0..nA-1] B[0..nB-1] ...
+                # with register A occupying the most-significant qubits.
+                # The bitstring is MSB-first, so register A's bits are at
+                # the left end. We walk backward from the right to peel
+                # off each register's segment from least-significant first.
+                parts = []
+                pos = len(state)
+                for i in range(self.n_regs):
+                    size = self.sizes[i]
+                    parts.append(state[pos - size:pos])
+                    pos -= size
+                for name, part in zip(self.names, parts):
+                    per_reg[name][part] = per_reg[name].get(part, 0) + count
+                jkey = '|'.join(parts)
+                joint[jkey] = joint.get(jkey, 0) + count
+            return per_reg, joint
+        else:
+            per_reg = {}
+            for name in self.names:
+                size = self.sizes[self._idx(name)]
+                per_reg[name] = _sample_np(self.svs[name], size, shots)
+            return per_reg, {}
+
+    def apply_matrix(self, reg: str, matrix: np.ndarray, qubits: list[int]) -> None:
+        """Apply a raw unitary matrix to qubits in a register."""
+        self._check_qubits(reg, qubits)
+        if self.joint:
+            idx = self._idx(reg)
+            actual = [q + self.offsets[idx] for q in qubits]
+            self.sv = _apply_gate_np(self.sv, matrix, actual, self.n_total)
+        else:
+            size = self.sizes[self._idx(reg)]
+            self.svs[reg] = _apply_gate_np(self.svs[reg], matrix, qubits, size)
+
+    def mem_gb(self) -> tuple[float, float]:  # (total_gb, peak_gb)
+        """Return (total_gb, peak_gb) realistic memory estimates including overhead."""
+        from qbasic_core.engine import OVERHEAD_FACTOR
+        if self.joint:
+            total = (2**self.n_total) * 16 * OVERHEAD_FACTOR / 1e9
+            return total, total
+        total = sum((2**s) * 16 * OVERHEAD_FACTOR / 1e9 for s in self.sizes)
+        peak = max((2**s) * 16 * OVERHEAD_FACTOR / 1e9 for s in self.sizes)
+        return total, peak