qubasic 0.14.0__tar.gz → 0.17.0__tar.gz

{qubasic-0.14.0 → qubasic-0.17.0}/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 0.17.0 (2026-07-02)
+
+Hardening from an SMT-verifier triage (touchstone-prover over all 651
+functions: 153 proved trap-free, 3 refutations traced, none reachable from
+the language surface).
+
+### Changed
+- `_pmul` raises a clear ValueError on a non-Pauli character and `_emit_mcz` on an empty qubit list, instead of a raw KeyError/IndexError — both are internal preconditions (every caller feeds alphabet-constrained values), now self-documenting.
+- `_eval_with_vars` declares the ParameterExpression passthrough in its return annotation instead of claiming `-> float`.
+
+## 0.16.0 (2026-07-02)
+
+Research-grade error correction, per-method scale, parametric variational
+loops, molecular Hamiltonians, and two new front ends (Jupyter, web). The
+existing command surface is unchanged; everything below is additive.
+
+### Added
+- Circuit-level QEC: `LOGICAL_ERROR_RATE <code> <d> <p> CIRCUIT [shots]` runs stim-generated syndrome-extraction circuits (noisy gates, measurements, and resets over d rounds) decoded from the detector error model by pymatching MWPM — a d=21 surface patch samples ~13k shots/s. `MWPM` runs batched pymatching at code capacity for distances the lookup table cannot reach. Both need the `[qec]` extra (stim + pymatching).
+- Bivariate-bicycle qLDPC codes: `QEC BB [l m]` builds the family from cyclic-shift polynomials (6 6 gives [[72,12,6]], 12 6 the [[144,12,12]] gross code) with k verified by GF(2) ranks, and `LOGICAL_ERROR_RATE BB <p>` decodes with an internal belief-propagation + ordered-statistics (BP+OSD-0) decoder — no external dependency.
+- Logical-qubit mode: `LQUBITS <n> CODE <name> <d> [PHYS p]` runs the program on logical qubits — every op carries the code's per-op logical error channel, measurement a logical readout flip, and RUN appends the lattice-surgery report (surgery ops, syndrome rounds, physical qubits, error budget). `LQUBITS OFF` returns to physical mode.
+- Molecular Hamiltonians: `HAMILTONIAN H = MOLECULE H2 [R]` builds the exact 4-qubit Jordan-Wigner Hamiltonian from a self-contained STO-3G integrals engine (no pyscf); exact diagonalization reproduces the FCI energy -1.1373 Ha at R=0.7414, and `SAVE_EXPECT <name> -> var` now accepts a declared Hamiltonian for VQE cost functions.
+- Optimizers: `MINIMIZE ... METHOD SPSA` (two evaluations per iteration, robust to shot noise) and `METHOD GRAD` (parameter-shift gradient descent with adaptive step) join Nelder-Mead.
+- Lindblad trajectories: `LINDBLAD ... TRAJ [n]` switches to Monte Carlo wavefunction unraveling (sparse H_eff + quantum jumps), raising the open-system ceiling from 5 to 15 qubits.
+- Jupyter kernel (`qubasic --install-kernel`, then pick "QUBASIC") and a token-gated browser REPL (`qubasic --web [port]`, localhost by default).
+- A golden-script test layer (`tests/test_golden.py`): whole programs asserted end to end on physics identities (inverse round trips, teleportation fidelity, EXPORT-LOADQASM fixed point, FCI energies) and on the 0.15.0 audit regressions.
+
+### Changed
+- Qubit ceilings are per METHOD: statevector keeps the 32-qubit memory wall, stabilizer reaches 4096 (an 881-qubit GHZ runs in ~12 s), MPS/automatic 1024, extended_stabilizer 63. Switching METHOD clamps QUBITS when needed, and QUBITS/RAM report memory in method-appropriate terms instead of a misleading 2^n estimate.
+- MINIMIZE, GRADIENT, and SWEEP compile the circuit once with bound qiskit Parameters and re-bind per evaluation when the ansatz permits (reported as "parametric compile"), an order of magnitude on variational loops; non-symbolic programs fall back to the rebuild path.
+- GST characterizes 2-qubit programs (product fiducials, 16x16 Pauli Transfer Matrix) as well as 1-qubit.
+- The STATS progress spinner writes only to an interactive terminal, and SWEEP shows a transient progress bar there; piped and captured output is unchanged.
+- `PRINT`ing a quantum DATA token shows ket notation (|GHZ3>) instead of the storage form; IQPE hints when the target register has no eigenstate preparation; LOCCINFO branch statistics count every SEND across all shots instead of the bits' final values; LOADQASM points at `pip install qubasic[qasm3]` when the 3.0 importer is missing.
+
+## 0.15.0 (2026-07-02)
+
+Error-handling, calibration, and I/O fixes from a full-surface audit. The
+quantum engine is unchanged.
+
+### Fixed
+- `RESUME`, `RESUME NEXT`, and `RESUME <line>` return to the mainline after a trapped error: the executor routes per-line errors through the ON ERROR handler in-loop, so a handler runs as ordinary program code and resumes where the README says. Error trapping arms per run (a stale target from a previous RUN no longer traps early), the 200-line handler budget applies per activation, and an error raised inside a handler is fatal.
+- `$D014` (entanglement_entropy) is populated after each run with the qubit-0-vs-rest entropy in bits, matching `ENTROPY 0`; it always read 0.0.
+- `EXPORT` emits OpenQASM 2.0 when the circuit allows, so its output round-trips through `LOADQASM` without the optional `qiskit_qasm3_import` package. Dynamic circuits still export as 3.0, and the message reports the version written.
+- `SWEEP` restores the swept variable afterward instead of leaving it at the final sweep point, so a following RUN or STATS sees the program's own value.
+- A UTF-8 BOM no longer mangles the first statement: piped stdin and all program readers (script files, `LOAD`, `INCLUDE`, `IMPORT`, `LOADQASM`) decode utf-8-sig.
+
+### Changed
+- `XEB` reports the self-normalized linear fidelity (sampled numerator over the perfect-sampling denominator `2^n sum(p^2) - 1`), so 1.0 is the true ideal at any width; the raw estimator tops out at (D-1)/(D+1), 0.6 at 2 qubits.
+- `OPTIMIZE` reports a depth increase as such instead of a negative reduction.
+- The `SWEEP` chart's y-axis is fixed to [0, 1].
+- `DUMP` prints registers wider than a byte compactly (`698.6`) instead of truncating the decimal.
+- Qiskit's advisory warning about passing coupling_map/basis_gates with a backend is silenced on the device-model path, where that combination is by design.
+
 ## 0.14.0 (2026-06-19)
 
 Second audit-gap round: a complete agent contract, BASIC truth values, range

{qubasic-0.14.0 → qubasic-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qubasic
-Version: 0.14.0
+Version: 0.17.0
 Summary: Quantum BASIC Interactive Terminal
 Author-email: "Charles C. Norton" <machineelv@gmail.com>
 License-Expression: MIT
@@ -29,6 +29,14 @@ Provides-Extra: charts
 Requires-Dist: plotille>=5.0; extra == "charts"
 Provides-Extra: readline
 Requires-Dist: pyreadline3>=3.4; sys_platform == "win32" and extra == "readline"
+Provides-Extra: qasm3
+Requires-Dist: qiskit-qasm3-import>=0.4; extra == "qasm3"
+Provides-Extra: qec
+Requires-Dist: stim>=1.12; extra == "qec"
+Requires-Dist: pymatching>=2.1; extra == "qec"
+Provides-Extra: jupyter
+Requires-Dist: ipykernel>=6.0; extra == "jupyter"
+Requires-Dist: jupyter-client>=7.0; extra == "jupyter"
 Dynamic: license-file
 
 # QUBASIC
@@ -62,6 +70,10 @@ QUBASIC is a quantum computing environment built on Qiskit Aer that uses BASIC s
 pip install qubasic
 ```
 
+Optional extras: `qubasic[qec]` (stim + pymatching for circuit-level error
+correction), `qubasic[jupyter]` (notebook kernel), `qubasic[qasm3]` (OpenQASM
+3 import), `qubasic[charts]` (sweep charts).
+
 Development install:
 
 ```
@@ -79,6 +91,8 @@ qubasic script.qb             Run a script file
 qubasic --quiet script         Suppress banner, output results only
 qubasic --json script          Machine-readable JSON output
 qubasic --spec                Print a JSON contract (commands, gates, functions)
+qubasic --web [port]          Browser REPL (localhost, token-gated)
+qubasic --install-kernel      Install the Jupyter kernelspec (then pick "QUBASIC")
 qubasic --help                Show CLI help
 ```
 
@@ -206,7 +220,7 @@ RESET 0                Reset qubit to |0>
 ## Configuration
 
 ```
-QUBITS 8             Set qubit count (1-32)
+QUBITS 8             Set qubit count (ceiling is per METHOD)
 SHOTS 2048           Set measurement shots
 METHOD statevector   Set simulation method
 METHOD GPU           Set simulation device
@@ -219,6 +233,13 @@ STATUS JSON          Same, as machine-readable JSON
 
 Automatic selection: stabilizer for Clifford-only circuits, MPS for >28 qubits, statevector otherwise.
 
+Qubit ceilings are per method: the 32-qubit wall is a statevector memory
+limit only. `stabilizer` reaches 4096 qubits (polynomial tableau),
+`matrix_product_state` and `automatic` reach 1024 (MPS memory is set by
+entanglement, not width), `extended_stabilizer` 63; an 881-qubit GHZ runs in
+seconds on the stabilizer backend. Switching METHOD clamps QUBITS to the new
+ceiling when needed.
+
 ## Variables and expressions
 
 ```
@@ -472,9 +493,16 @@ ansatz, compute a cost with `SAVE_EXPECT`, then minimize it.
 20 SAVE_EXPECT Z 0 -> cost
 MINIMIZE theta -> cost              Nelder-Mead minimization (dependency-free)
 MINIMIZE a, b -> z0 + 0.5*z1 ITERS 200   Multi-parameter; cost is any post-run expression
+MINIMIZE a, b -> cost METHOD SPSA   SPSA (2 evals/iter, robust to shot noise)
+MINIMIZE a -> cost METHOD GRAD      Parameter-shift gradient descent
 GRADIENT theta -> cost             Parameter-shift gradient d(cost)/d(theta)
 ```
 
+When the ansatz permits, MINIMIZE/GRADIENT/SWEEP compile the circuit once
+with bound qiskit Parameters and only re-bind values per evaluation (reported
+as "parametric compile") — an order of magnitude on variational loops. The
+fallback for non-symbolic programs is the classic rebuild per step.
+
 ## Dynamic circuits (feedforward)
 
 In standard mode, `MEAS` is a real mid-circuit measurement and `IF` on the
@@ -516,26 +544,64 @@ SAVEPNG out.png hist     Save the histogram as a PNG (also: bloch, circuit; need
 ```
 HAMILTONIAN H = 1.0 ZZ 0 1 + 0.5 X 0    Declare a Pauli-sum Hamiltonian
 HAMILTONIAN H = ISING 1.0 0.5           Builders: ISING, HEISENBERG, HUBBARD, RYDBERG
+HAMILTONIAN H = MOLECULE H2 0.7414      H2/STO-3G (built-in integrals engine, no pyscf)
 10 EVOLVE H, 1.5, 20                     Trotterized e^{-iHt} (time, steps) in a circuit
-LINDBLAD NONE, 1.0, 200, 1.0 SM 0        Open-system master-equation evolution
+10 SAVE_EXPECT H -> e                    <H> of a declared Hamiltonian (VQE cost)
+LINDBLAD NONE, 1.0, 200, 1.0 SM 0        Open-system master-equation evolution (dense, <=5 qubits)
+LINDBLAD H, 1.0, 200, 1.0 SM 0 TRAJ 500  Monte Carlo wavefunction unraveling (<=15 qubits)
 CHANNEL AD = [[1,0],[0,0.95]] ; [[0,0.31],[0,0]]   Define a Kraus channel
 10 APPLYCHANNEL AD 0                      Apply a custom channel
 ```
 
+`MOLECULE H2 [R]` computes the exact 4-qubit Jordan-Wigner Hamiltonian from a
+self-contained STO-3G integrals engine (Gaussian s-orbital closed forms, RHF
+by symmetry). Exact diagonalization at R = 0.7414 reproduces the FCI energy
+-1.1373 Ha, and a one-parameter VQE reaches it in ~30 evaluations.
+
 ## Error correction
 
 ```
 QEC STEANE               Show a code (REP [d], STEANE, SHOR, SURFACE [d]) and its stabilizers
+QEC BB [l m]             Bivariate-bicycle qLDPC (6 6 -> [[72,12,6]], 12 6 -> [[144,12,12]])
 LOGICAL_ERROR_RATE STEANE 0.02   Monte-Carlo logical error rate (optimal lookup decoder)
-LOGICAL_ERROR_RATE SURFACE 0.02 UF   Same, with the union-find / matching decoder
+LOGICAL_ERROR_RATE SURFACE 0.02 UF       Union-find / matching decoder
+LOGICAL_ERROR_RATE SURFACE 11 0.05 MWPM  Batched pymatching MWPM (large distances)
+LOGICAL_ERROR_RATE SURFACE 21 0.001 CIRCUIT 1000000  Circuit-level noise (stim + pymatching)
+LOGICAL_ERROR_RATE BB 0.01       BB codes decode with the internal BP+OSD
 THRESHOLD REP 0.0 0.5 11         Sweep p across distances 3/5/7 (crossing at 0.5)
 DISTILL 0.02             15-to-1 magic-state distillation (output error ~35 p^3)
 LATTICE 0 1              Lattice-surgery joint Zbar-Zbar measurement of two patches
 ```
 
 Codes: repetition (any odd distance), Steane [[7,1,3]], Shor [[9,1,3]], rotated
-surface. Decoders: an optimal minimum-weight lookup table (all codes) and a
-scalable union-find / matching decoder (topological codes, via the `UF` flag).
+surface, and the bivariate-bicycle qLDPC family (parity checks built from the
+cyclic-shift polynomials, k verified by GF(2) ranks). Decoders: an optimal
+minimum-weight lookup table (all codes), a union-find / matching decoder (`UF`),
+batched pymatching MWPM (`MWPM`), and an internal belief-propagation +
+ordered-statistics decoder (BP+OSD-0) for the qLDPC codes.
+
+`CIRCUIT` switches from code capacity to full circuit-level noise: stim
+generates the noisy syndrome-extraction circuit (d rounds of gates,
+measurements, and resets, each carrying errors), pymatching decodes the
+detector error model, and millions of shots run in seconds — a d=21 surface
+patch (944 physical qubits, 9240 detectors) samples at ~13k shots/s.
+
+### Logical-qubit mode
+
+```
+LQUBITS 2 CODE SURFACE 5 PHYS 1e-3   Program on 2 LOGICAL qubits (surface, d=5)
+10 H 0                                Gates now act on logical qubits
+20 CX 0,1                             CX compiles to a lattice-surgery merge+split
+30 MEASURE
+RUN                                   Histogram of LOGICAL outcomes
+LQUBITS OFF                           Back to physical qubits
+```
+
+While active, every operation carries the code's per-op logical error channel
+(from the code-capacity rate for the chosen code, distance, and physical p),
+measurement carries a logical readout flip, and RUN appends the
+lattice-surgery report: surgery ops, syndrome rounds, physical-qubit total,
+wall time at 1 us/round, and the cumulative logical error budget.
 
 ## Benchmarking and verification
 
@@ -883,6 +949,11 @@ qubasic_core/
   display.py             Histograms, statevector, Bloch sphere rendering
   locc.py                LOCC commands, execution, display
   analysis.py            EXPECT, ENTROPY, DENSITY, BENCH, RAM
+  qec2.py                Circuit-level QEC (stim/pymatching), BB qLDPC, BP+OSD
+  logical.py             LQUBITS logical-qubit mode + lattice-surgery report
+  qchem.py               STO-3G molecular Hamiltonians (MOLECULE H2)
+  jupyter_kernel.py      Jupyter kernel (qubasic --install-kernel)
+  web_repl.py            Browser REPL (qubasic --web)
   sweep.py               Parameter sweep with plotille charts
   memory.py              PEEK/POKE/SYS/DUMP/MAP/MONITOR
   strings.py             String functions

qubasic-0.14.0/qubasic.egg-info/PKG-INFO → qubasic-0.17.0/README.md

@@ -1,36 +1,3 @@
-Metadata-Version: 2.4
-Name: qubasic
-Version: 0.14.0
-Summary: Quantum BASIC Interactive Terminal
-Author-email: "Charles C. Norton" <machineelv@gmail.com>
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/CharlesCNorton/qubasic
-Project-URL: Repository, https://github.com/CharlesCNorton/qubasic
-Project-URL: Issues, https://github.com/CharlesCNorton/qubasic/issues
-Keywords: quantum,computing,qiskit,basic,repl,simulator
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Education
-Classifier: Intended Audience :: Science/Research
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Scientific/Engineering :: Physics
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: qiskit>=1.0
-Requires-Dist: qiskit-aer>=0.13
-Requires-Dist: numpy>=1.24
-Requires-Dist: psutil>=5.9
-Requires-Dist: rich>=13.0
-Provides-Extra: charts
-Requires-Dist: plotille>=5.0; extra == "charts"
-Provides-Extra: readline
-Requires-Dist: pyreadline3>=3.4; sys_platform == "win32" and extra == "readline"
-Dynamic: license-file
-
 # QUBASIC
 
 Quantum computing in a BASIC REPL.
@@ -62,6 +29,10 @@ QUBASIC is a quantum computing environment built on Qiskit Aer that uses BASIC s
 pip install qubasic
 ```
 
+Optional extras: `qubasic[qec]` (stim + pymatching for circuit-level error
+correction), `qubasic[jupyter]` (notebook kernel), `qubasic[qasm3]` (OpenQASM
+3 import), `qubasic[charts]` (sweep charts).
+
 Development install:
 
 ```
@@ -79,6 +50,8 @@ qubasic script.qb             Run a script file
 qubasic --quiet script         Suppress banner, output results only
 qubasic --json script          Machine-readable JSON output
 qubasic --spec                Print a JSON contract (commands, gates, functions)
+qubasic --web [port]          Browser REPL (localhost, token-gated)
+qubasic --install-kernel      Install the Jupyter kernelspec (then pick "QUBASIC")
 qubasic --help                Show CLI help
 ```
 
@@ -206,7 +179,7 @@ RESET 0                Reset qubit to |0>
 ## Configuration
 
 ```
-QUBITS 8             Set qubit count (1-32)
+QUBITS 8             Set qubit count (ceiling is per METHOD)
 SHOTS 2048           Set measurement shots
 METHOD statevector   Set simulation method
 METHOD GPU           Set simulation device
@@ -219,6 +192,13 @@ STATUS JSON          Same, as machine-readable JSON
 
 Automatic selection: stabilizer for Clifford-only circuits, MPS for >28 qubits, statevector otherwise.
 
+Qubit ceilings are per method: the 32-qubit wall is a statevector memory
+limit only. `stabilizer` reaches 4096 qubits (polynomial tableau),
+`matrix_product_state` and `automatic` reach 1024 (MPS memory is set by
+entanglement, not width), `extended_stabilizer` 63; an 881-qubit GHZ runs in
+seconds on the stabilizer backend. Switching METHOD clamps QUBITS to the new
+ceiling when needed.
+
 ## Variables and expressions
 
 ```
@@ -472,9 +452,16 @@ ansatz, compute a cost with `SAVE_EXPECT`, then minimize it.
 20 SAVE_EXPECT Z 0 -> cost
 MINIMIZE theta -> cost              Nelder-Mead minimization (dependency-free)
 MINIMIZE a, b -> z0 + 0.5*z1 ITERS 200   Multi-parameter; cost is any post-run expression
+MINIMIZE a, b -> cost METHOD SPSA   SPSA (2 evals/iter, robust to shot noise)
+MINIMIZE a -> cost METHOD GRAD      Parameter-shift gradient descent
 GRADIENT theta -> cost             Parameter-shift gradient d(cost)/d(theta)
 ```
 
+When the ansatz permits, MINIMIZE/GRADIENT/SWEEP compile the circuit once
+with bound qiskit Parameters and only re-bind values per evaluation (reported
+as "parametric compile") — an order of magnitude on variational loops. The
+fallback for non-symbolic programs is the classic rebuild per step.
+
 ## Dynamic circuits (feedforward)
 
 In standard mode, `MEAS` is a real mid-circuit measurement and `IF` on the
@@ -516,26 +503,64 @@ SAVEPNG out.png hist     Save the histogram as a PNG (also: bloch, circuit; need
 ```
 HAMILTONIAN H = 1.0 ZZ 0 1 + 0.5 X 0    Declare a Pauli-sum Hamiltonian
 HAMILTONIAN H = ISING 1.0 0.5           Builders: ISING, HEISENBERG, HUBBARD, RYDBERG
+HAMILTONIAN H = MOLECULE H2 0.7414      H2/STO-3G (built-in integrals engine, no pyscf)
 10 EVOLVE H, 1.5, 20                     Trotterized e^{-iHt} (time, steps) in a circuit
-LINDBLAD NONE, 1.0, 200, 1.0 SM 0        Open-system master-equation evolution
+10 SAVE_EXPECT H -> e                    <H> of a declared Hamiltonian (VQE cost)
+LINDBLAD NONE, 1.0, 200, 1.0 SM 0        Open-system master-equation evolution (dense, <=5 qubits)
+LINDBLAD H, 1.0, 200, 1.0 SM 0 TRAJ 500  Monte Carlo wavefunction unraveling (<=15 qubits)
 CHANNEL AD = [[1,0],[0,0.95]] ; [[0,0.31],[0,0]]   Define a Kraus channel
 10 APPLYCHANNEL AD 0                      Apply a custom channel
 ```
 
+`MOLECULE H2 [R]` computes the exact 4-qubit Jordan-Wigner Hamiltonian from a
+self-contained STO-3G integrals engine (Gaussian s-orbital closed forms, RHF
+by symmetry). Exact diagonalization at R = 0.7414 reproduces the FCI energy
+-1.1373 Ha, and a one-parameter VQE reaches it in ~30 evaluations.
+
 ## Error correction
 
 ```
 QEC STEANE               Show a code (REP [d], STEANE, SHOR, SURFACE [d]) and its stabilizers
+QEC BB [l m]             Bivariate-bicycle qLDPC (6 6 -> [[72,12,6]], 12 6 -> [[144,12,12]])
 LOGICAL_ERROR_RATE STEANE 0.02   Monte-Carlo logical error rate (optimal lookup decoder)
-LOGICAL_ERROR_RATE SURFACE 0.02 UF   Same, with the union-find / matching decoder
+LOGICAL_ERROR_RATE SURFACE 0.02 UF       Union-find / matching decoder
+LOGICAL_ERROR_RATE SURFACE 11 0.05 MWPM  Batched pymatching MWPM (large distances)
+LOGICAL_ERROR_RATE SURFACE 21 0.001 CIRCUIT 1000000  Circuit-level noise (stim + pymatching)
+LOGICAL_ERROR_RATE BB 0.01       BB codes decode with the internal BP+OSD
 THRESHOLD REP 0.0 0.5 11         Sweep p across distances 3/5/7 (crossing at 0.5)
 DISTILL 0.02             15-to-1 magic-state distillation (output error ~35 p^3)
 LATTICE 0 1              Lattice-surgery joint Zbar-Zbar measurement of two patches
 ```
 
 Codes: repetition (any odd distance), Steane [[7,1,3]], Shor [[9,1,3]], rotated
-surface. Decoders: an optimal minimum-weight lookup table (all codes) and a
-scalable union-find / matching decoder (topological codes, via the `UF` flag).
+surface, and the bivariate-bicycle qLDPC family (parity checks built from the
+cyclic-shift polynomials, k verified by GF(2) ranks). Decoders: an optimal
+minimum-weight lookup table (all codes), a union-find / matching decoder (`UF`),
+batched pymatching MWPM (`MWPM`), and an internal belief-propagation +
+ordered-statistics decoder (BP+OSD-0) for the qLDPC codes.
+
+`CIRCUIT` switches from code capacity to full circuit-level noise: stim
+generates the noisy syndrome-extraction circuit (d rounds of gates,
+measurements, and resets, each carrying errors), pymatching decodes the
+detector error model, and millions of shots run in seconds — a d=21 surface
+patch (944 physical qubits, 9240 detectors) samples at ~13k shots/s.
+
+### Logical-qubit mode
+
+```
+LQUBITS 2 CODE SURFACE 5 PHYS 1e-3   Program on 2 LOGICAL qubits (surface, d=5)
+10 H 0                                Gates now act on logical qubits
+20 CX 0,1                             CX compiles to a lattice-surgery merge+split
+30 MEASURE
+RUN                                   Histogram of LOGICAL outcomes
+LQUBITS OFF                           Back to physical qubits
+```
+
+While active, every operation carries the code's per-op logical error channel
+(from the code-capacity rate for the chosen code, distance, and physical p),
+measurement carries a logical readout flip, and RUN appends the
+lattice-surgery report: surgery ops, syndrome rounds, physical-qubit total,
+wall time at 1 us/round, and the cumulative logical error budget.
 
 ## Benchmarking and verification
 
@@ -883,6 +908,11 @@ qubasic_core/
   display.py             Histograms, statevector, Bloch sphere rendering
   locc.py                LOCC commands, execution, display
   analysis.py            EXPECT, ENTROPY, DENSITY, BENCH, RAM
+  qec2.py                Circuit-level QEC (stim/pymatching), BB qLDPC, BP+OSD
+  logical.py             LQUBITS logical-qubit mode + lattice-surgery report
+  qchem.py               STO-3G molecular Hamiltonians (MOLECULE H2)
+  jupyter_kernel.py      Jupyter kernel (qubasic --install-kernel)
+  web_repl.py            Browser REPL (qubasic --web)
   sweep.py               Parameter sweep with plotille charts
   memory.py              PEEK/POKE/SYS/DUMP/MAP/MONITOR
   strings.py             String functions

{qubasic-0.14.0 → qubasic-0.17.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qubasic"
-version = "0.14.0"
+version = "0.17.0"
 description = "Quantum BASIC Interactive Terminal"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -40,6 +40,9 @@ Issues = "https://github.com/CharlesCNorton/qubasic/issues"
 [project.optional-dependencies]
 charts = ["plotille>=5.0"]
 readline = ["pyreadline3>=3.4; sys_platform == 'win32'"]
+qasm3 = ["qiskit-qasm3-import>=0.4"]
+qec = ["stim>=1.12", "pymatching>=2.1"]
+jupyter = ["ipykernel>=6.0", "jupyter-client>=7.0"]
 
 [project.scripts]
 qubasic = "qubasic_core.cli:main"

qubasic-0.14.0/README.md → qubasic-0.17.0/qubasic.egg-info/PKG-INFO

@@ -1,3 +1,44 @@
+Metadata-Version: 2.4
+Name: qubasic
+Version: 0.17.0
+Summary: Quantum BASIC Interactive Terminal
+Author-email: "Charles C. Norton" <machineelv@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/CharlesCNorton/qubasic
+Project-URL: Repository, https://github.com/CharlesCNorton/qubasic
+Project-URL: Issues, https://github.com/CharlesCNorton/qubasic/issues
+Keywords: quantum,computing,qiskit,basic,repl,simulator
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: qiskit>=1.0
+Requires-Dist: qiskit-aer>=0.13
+Requires-Dist: numpy>=1.24
+Requires-Dist: psutil>=5.9
+Requires-Dist: rich>=13.0
+Provides-Extra: charts
+Requires-Dist: plotille>=5.0; extra == "charts"
+Provides-Extra: readline
+Requires-Dist: pyreadline3>=3.4; sys_platform == "win32" and extra == "readline"
+Provides-Extra: qasm3
+Requires-Dist: qiskit-qasm3-import>=0.4; extra == "qasm3"
+Provides-Extra: qec
+Requires-Dist: stim>=1.12; extra == "qec"
+Requires-Dist: pymatching>=2.1; extra == "qec"
+Provides-Extra: jupyter
+Requires-Dist: ipykernel>=6.0; extra == "jupyter"
+Requires-Dist: jupyter-client>=7.0; extra == "jupyter"
+Dynamic: license-file
+
 # QUBASIC
 
 Quantum computing in a BASIC REPL.
@@ -29,6 +70,10 @@ QUBASIC is a quantum computing environment built on Qiskit Aer that uses BASIC s
 pip install qubasic
 ```
 
+Optional extras: `qubasic[qec]` (stim + pymatching for circuit-level error
+correction), `qubasic[jupyter]` (notebook kernel), `qubasic[qasm3]` (OpenQASM
+3 import), `qubasic[charts]` (sweep charts).
+
 Development install:
 
 ```
@@ -46,6 +91,8 @@ qubasic script.qb             Run a script file
 qubasic --quiet script         Suppress banner, output results only
 qubasic --json script          Machine-readable JSON output
 qubasic --spec                Print a JSON contract (commands, gates, functions)
+qubasic --web [port]          Browser REPL (localhost, token-gated)
+qubasic --install-kernel      Install the Jupyter kernelspec (then pick "QUBASIC")
 qubasic --help                Show CLI help
 ```
 
@@ -173,7 +220,7 @@ RESET 0                Reset qubit to |0>
 ## Configuration
 
 ```
-QUBITS 8             Set qubit count (1-32)
+QUBITS 8             Set qubit count (ceiling is per METHOD)
 SHOTS 2048           Set measurement shots
 METHOD statevector   Set simulation method
 METHOD GPU           Set simulation device
@@ -186,6 +233,13 @@ STATUS JSON          Same, as machine-readable JSON
 
 Automatic selection: stabilizer for Clifford-only circuits, MPS for >28 qubits, statevector otherwise.
 
+Qubit ceilings are per method: the 32-qubit wall is a statevector memory
+limit only. `stabilizer` reaches 4096 qubits (polynomial tableau),
+`matrix_product_state` and `automatic` reach 1024 (MPS memory is set by
+entanglement, not width), `extended_stabilizer` 63; an 881-qubit GHZ runs in
+seconds on the stabilizer backend. Switching METHOD clamps QUBITS to the new
+ceiling when needed.
+
 ## Variables and expressions
 
 ```
@@ -439,9 +493,16 @@ ansatz, compute a cost with `SAVE_EXPECT`, then minimize it.
 20 SAVE_EXPECT Z 0 -> cost
 MINIMIZE theta -> cost              Nelder-Mead minimization (dependency-free)
 MINIMIZE a, b -> z0 + 0.5*z1 ITERS 200   Multi-parameter; cost is any post-run expression
+MINIMIZE a, b -> cost METHOD SPSA   SPSA (2 evals/iter, robust to shot noise)
+MINIMIZE a -> cost METHOD GRAD      Parameter-shift gradient descent
 GRADIENT theta -> cost             Parameter-shift gradient d(cost)/d(theta)
 ```
 
+When the ansatz permits, MINIMIZE/GRADIENT/SWEEP compile the circuit once
+with bound qiskit Parameters and only re-bind values per evaluation (reported
+as "parametric compile") — an order of magnitude on variational loops. The
+fallback for non-symbolic programs is the classic rebuild per step.
+
 ## Dynamic circuits (feedforward)
 
 In standard mode, `MEAS` is a real mid-circuit measurement and `IF` on the
@@ -483,26 +544,64 @@ SAVEPNG out.png hist     Save the histogram as a PNG (also: bloch, circuit; need
 ```
 HAMILTONIAN H = 1.0 ZZ 0 1 + 0.5 X 0    Declare a Pauli-sum Hamiltonian
 HAMILTONIAN H = ISING 1.0 0.5           Builders: ISING, HEISENBERG, HUBBARD, RYDBERG
+HAMILTONIAN H = MOLECULE H2 0.7414      H2/STO-3G (built-in integrals engine, no pyscf)
 10 EVOLVE H, 1.5, 20                     Trotterized e^{-iHt} (time, steps) in a circuit
-LINDBLAD NONE, 1.0, 200, 1.0 SM 0        Open-system master-equation evolution
+10 SAVE_EXPECT H -> e                    <H> of a declared Hamiltonian (VQE cost)
+LINDBLAD NONE, 1.0, 200, 1.0 SM 0        Open-system master-equation evolution (dense, <=5 qubits)
+LINDBLAD H, 1.0, 200, 1.0 SM 0 TRAJ 500  Monte Carlo wavefunction unraveling (<=15 qubits)
 CHANNEL AD = [[1,0],[0,0.95]] ; [[0,0.31],[0,0]]   Define a Kraus channel
 10 APPLYCHANNEL AD 0                      Apply a custom channel
 ```
 
+`MOLECULE H2 [R]` computes the exact 4-qubit Jordan-Wigner Hamiltonian from a
+self-contained STO-3G integrals engine (Gaussian s-orbital closed forms, RHF
+by symmetry). Exact diagonalization at R = 0.7414 reproduces the FCI energy
+-1.1373 Ha, and a one-parameter VQE reaches it in ~30 evaluations.
+
 ## Error correction
 
 ```
 QEC STEANE               Show a code (REP [d], STEANE, SHOR, SURFACE [d]) and its stabilizers
+QEC BB [l m]             Bivariate-bicycle qLDPC (6 6 -> [[72,12,6]], 12 6 -> [[144,12,12]])
 LOGICAL_ERROR_RATE STEANE 0.02   Monte-Carlo logical error rate (optimal lookup decoder)
-LOGICAL_ERROR_RATE SURFACE 0.02 UF   Same, with the union-find / matching decoder
+LOGICAL_ERROR_RATE SURFACE 0.02 UF       Union-find / matching decoder
+LOGICAL_ERROR_RATE SURFACE 11 0.05 MWPM  Batched pymatching MWPM (large distances)
+LOGICAL_ERROR_RATE SURFACE 21 0.001 CIRCUIT 1000000  Circuit-level noise (stim + pymatching)
+LOGICAL_ERROR_RATE BB 0.01       BB codes decode with the internal BP+OSD
 THRESHOLD REP 0.0 0.5 11         Sweep p across distances 3/5/7 (crossing at 0.5)
 DISTILL 0.02             15-to-1 magic-state distillation (output error ~35 p^3)
 LATTICE 0 1              Lattice-surgery joint Zbar-Zbar measurement of two patches
 ```
 
 Codes: repetition (any odd distance), Steane [[7,1,3]], Shor [[9,1,3]], rotated
-surface. Decoders: an optimal minimum-weight lookup table (all codes) and a
-scalable union-find / matching decoder (topological codes, via the `UF` flag).
+surface, and the bivariate-bicycle qLDPC family (parity checks built from the
+cyclic-shift polynomials, k verified by GF(2) ranks). Decoders: an optimal
+minimum-weight lookup table (all codes), a union-find / matching decoder (`UF`),
+batched pymatching MWPM (`MWPM`), and an internal belief-propagation +
+ordered-statistics decoder (BP+OSD-0) for the qLDPC codes.
+
+`CIRCUIT` switches from code capacity to full circuit-level noise: stim
+generates the noisy syndrome-extraction circuit (d rounds of gates,
+measurements, and resets, each carrying errors), pymatching decodes the
+detector error model, and millions of shots run in seconds — a d=21 surface
+patch (944 physical qubits, 9240 detectors) samples at ~13k shots/s.
+
+### Logical-qubit mode
+
+```
+LQUBITS 2 CODE SURFACE 5 PHYS 1e-3   Program on 2 LOGICAL qubits (surface, d=5)
+10 H 0                                Gates now act on logical qubits
+20 CX 0,1                             CX compiles to a lattice-surgery merge+split
+30 MEASURE
+RUN                                   Histogram of LOGICAL outcomes
+LQUBITS OFF                           Back to physical qubits
+```
+
+While active, every operation carries the code's per-op logical error channel
+(from the code-capacity rate for the chosen code, distance, and physical p),
+measurement carries a logical readout flip, and RUN appends the
+lattice-surgery report: surgery ops, syndrome rounds, physical-qubit total,
+wall time at 1 us/round, and the cumulative logical error budget.
 
 ## Benchmarking and verification
 
@@ -850,6 +949,11 @@ qubasic_core/
   display.py             Histograms, statevector, Bloch sphere rendering
   locc.py                LOCC commands, execution, display
   analysis.py            EXPECT, ENTROPY, DENSITY, BENCH, RAM
+  qec2.py                Circuit-level QEC (stim/pymatching), BB qLDPC, BP+OSD
+  logical.py             LQUBITS logical-qubit mode + lattice-surgery report
+  qchem.py               STO-3G molecular Hamiltonians (MOLECULE H2)
+  jupyter_kernel.py      Jupyter kernel (qubasic --install-kernel)
+  web_repl.py            Browser REPL (qubasic --web)
   sweep.py               Parameter sweep with plotille charts
   memory.py              PEEK/POKE/SYS/DUMP/MAP/MONITOR
   strings.py             String functions

{qubasic-0.14.0 → qubasic-0.17.0}/qubasic.egg-info/SOURCES.txt

@@ -38,11 +38,13 @@ qubasic_core/file_io.py
 qubasic_core/gates.py
 qubasic_core/help_text.py
 qubasic_core/io_protocol.py
+qubasic_core/jupyter_kernel.py
 qubasic_core/locc.py
 qubasic_core/locc_commands.py
 qubasic_core/locc_display.py
 qubasic_core/locc_engine.py
 qubasic_core/locc_execution.py
+qubasic_core/logical.py
 qubasic_core/memory.py
 qubasic_core/mock_backend.py
 qubasic_core/noise_mixin.py
@@ -52,7 +54,9 @@ qubasic_core/pauliprop.py
 qubasic_core/profiler.py
 qubasic_core/program_mgmt.py
 qubasic_core/protocol.py
+qubasic_core/qchem.py
 qubasic_core/qec.py
+qubasic_core/qec2.py
 qubasic_core/qol.py
 qubasic_core/qudits.py
 qubasic_core/resources.py
@@ -64,5 +68,7 @@ qubasic_core/strings.py
 qubasic_core/subs.py
 qubasic_core/sweep.py
 qubasic_core/terminal.py
+qubasic_core/web_repl.py
 tests/test_features.py
+tests/test_golden.py
 tests/test_qubasic.py

{qubasic-0.14.0 → qubasic-0.17.0}/qubasic.egg-info/requires.txt

@@ -7,6 +7,17 @@ rich>=13.0
 [charts]
 plotille>=5.0
 
+[jupyter]
+ipykernel>=6.0
+jupyter-client>=7.0
+
+[qasm3]
+qiskit-qasm3-import>=0.4
+
+[qec]
+stim>=1.12
+pymatching>=2.1
+
 [readline]
 
 [readline:sys_platform == "win32"]

{qubasic-0.14.0 → qubasic-0.17.0}/qubasic_core/__init__.py

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