pyqrack-cpu 2.4.0__tar.gz → 2.5.1__tar.gz

{pyqrack_cpu-2.4.0 → pyqrack_cpu-2.5.1}/MANIFEST.in

@@ -1,4 +1,3 @@
 include pyqrack/qrack_system/qrack_lib/*
 include pyqrack/qrack_system/qrack_cl_precompile/*
-include pyqrack/scripts/*
 include Makefile

{pyqrack_cpu-2.4.0/pyqrack_cpu.egg-info → pyqrack_cpu-2.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyqrack-cpu
-Version: 2.4.0
+Version: 2.5.1
 Summary: pyqrack - Pure Python vm6502q/qrack Wrapper
 Home-page: https://github.com/vm6502q/pyqrack
 Author: Daniel Strano

{pyqrack_cpu-2.4.0 → pyqrack_cpu-2.5.1}/pyqrack/qrack_ace_backend.py

@@ -230,7 +230,6 @@ class QrackAceBackend:
         is_host_pointer=(True if os.environ.get("PYQRACK_HOST_POINTER_DEFAULT_ON") else False),
         is_near_clifford_tableau_writer=False,
         noise=0,
-        bseq_ancillae=True,
         to_clone=None,
     ):
         if to_clone:
@@ -238,7 +237,6 @@ class QrackAceBackend:
             long_range_columns = to_clone.long_range_columns
             long_range_rows = to_clone.long_range_rows
             is_transpose = to_clone.is_transpose
-            bseq_ancillae = to_clone.bseq_ancillae
         if qubit_count < 0:
             qubit_count = 0
         if long_range_columns < 0:
@@ -248,7 +246,6 @@ class QrackAceBackend:
         self.long_range_columns = long_range_columns
         self.long_range_rows = long_range_rows
         self.is_transpose = is_transpose
-        self.bseq_ancillae = bseq_ancillae
 
         fppow = 5
         if "QRACK_FPPOW" in os.environ:
@@ -298,7 +295,6 @@ class QrackAceBackend:
 
         self._qubits = []
         self._lhv = {}
-        self._ancilla = {}
         sim_counts = [0] * sim_count
         sim_id = 0
         tot_qubits = 0
@@ -315,19 +311,6 @@ class QrackAceBackend:
                     qubit.append((boundary_sim_id, boundary_count))
                     boundary_count += 1
 
-                    if self.bseq_ancillae:
-                        # Reserve a second boundary-sim qubit as the BSEQ
-                        # correction ancilla, right alongside slot2.
-                        # Starts at |0> and is prepped fresh into |+>
-                        # (via H) transiently around each readout, then
-                        # acts as the CONTROL on a 4-parameter mcu gate
-                        # targeting slot2 -- see
-                        # _apply_bseq_correction/_reverse_bseq_correction.
-                        # Entirely skipped, allocating nothing extra, when
-                        # bseq_ancillae=False.
-                        self._ancilla[tot_qubits] = (boundary_sim_id, boundary_count)
-                        boundary_count += 1
-
                     self._lhv[tot_qubits] = LHVQubit(
                         to_clone=(to_clone._lhv[tot_qubits] if to_clone else None)
                     )
@@ -570,7 +553,6 @@ class QrackAceBackend:
     def _get_bloch_angles(self, hq):
         sim = self.sim[hq[0]].clone()
         q = hq[1]
-        sim.separate([q])
 
         # Z axis
         z = 1 - 2 * sim.prob(q)
@@ -590,7 +572,17 @@ class QrackAceBackend:
         inclination = math.atan2(math.sqrt(x**2 + y**2), z)
         azimuth = math.atan2(y, x)
 
-        return azimuth, inclination
+        # Separability measure, per QUnit::TrySeparate: a genuinely
+        # separable (pure, unentangled) single qubit has Bloch vector
+        # length exactly 1 ("on-shell" -- on the surface of the Bloch
+        # sphere); a qubit reduced from a larger entangled state has
+        # length < 1 ("off-shell interior"). one_minus_r = 1 - |r| is
+        # near 0 for a genuinely separable qubit, and grows toward 1 the
+        # more entangled (mixed, as seen by this one qubit's reduced
+        # density matrix) it actually is.
+        one_minus_r = 1.0 - math.sqrt(x**2 + y**2 + z**2)
+
+        return azimuth, inclination, one_minus_r
 
     def _rotate_to_bloch(self, hq, delta_azimuth, delta_inclination):
         sim = self.sim[hq[0]]
@@ -632,159 +624,6 @@ class QrackAceBackend:
 
         sim.mtrx([m00, m01, m10, m11])
 
-    # Trainable BSEQ correction, in two layers:
-    #
-    # 1. A plain, uncontrolled single-qubit U(theta, phi, lambda) gate
-    #    (QrackSimulator.u), applied directly to the boundary qubit
-    #    (slot2). U then U-adjoint, with nothing else happening to slot2
-    #    in between except a probability read, is mathematically forced
-    #    to be the identity on slot2's actual evolution (U_dag @ U = I),
-    #    while the intermediate readout genuinely depends on whatever
-    #    slot2's value was beforehand whenever U doesn't commute with
-    #    the Z basis. This layer needs no ancilla and is always
-    #    available whenever its 3 angles are set.
-    #
-    # 2. Optionally (when bseq_ancillae=True at construction, the
-    #    default, and an ancilla was therefore allocated for this
-    #    site), a second layer: the ancilla is prepped fresh into |+>
-    #    (via H), then acts as CONTROL on a 4-parameter mcu gate
-    #    targeting slot2. This layer runs AFTER the u gate in the
-    #    forward ("compute") direction, and is undone FIRST, in the
-    #    opposite order, during reversal ("uncompute"): mcu-adjoint,
-    #    then H, then u-adjoint last.
-    #
-    # PyQrack's mcu follows the same convention as Qiskit's U/CU gates.
-    # Per Qiskit's own documentation, UGate.inverse() gives
-    # U(th,ph,la)^dagger = U(-th,-la,-ph) (theta negated, phi/lambda
-    # swapped-and-negated) -- and this was directly, repeatedly
-    # verified against the real PyQrack simulator (matching to better
-    # than 1e-6 on the full state vector, across multiple random seeds)
-    # for the 3-parameter u as well as the 4-parameter mcu (with gamma
-    # simply negated alongside the same swap). Note that Qiskit's
-    # separately-documented CUGate.inverse() page states a *different*
-    # formula (straight negation of all 4 parameters, no swap) -- that
-    # formula was tested directly against PyQrack's mcu and does NOT
-    # match; the swap formula is the one actually verified to work here.
-    #
-    # All 7 angles (3 for u, 4 for mcu) are trainable; fit them
-    # empirically against the measured BSEQ S statistic (or the
-    # simpler Bell-pair objective) via the companion
-    # optimize_bseq_correction.py script, which sets them directly on
-    # this class. Default to None: each layer is inactive (a
-    # guaranteed no-op) until its own angles are explicitly set, and
-    # the mcu layer additionally requires bseq_ancillae=True at
-    # construction (and therefore an ancilla actually allocated for
-    # the site in question).
-    _BSEQ_THETA = None
-    _BSEQ_PHI = None
-    _BSEQ_LAMBDA = None
-    _BSEQ_MCU_THETA = None
-    _BSEQ_MCU_PHI = None
-    _BSEQ_MCU_LAMBDA = None
-    _BSEQ_MCU_GAMMA = None
-
-    @staticmethod
-    def _bseq_u_active():
-        return (
-            QrackAceBackend._BSEQ_THETA is not None
-            and QrackAceBackend._BSEQ_PHI is not None
-            and QrackAceBackend._BSEQ_LAMBDA is not None
-        )
-
-    @staticmethod
-    def _bseq_mcu_active():
-        return (
-            QrackAceBackend._BSEQ_MCU_THETA is not None
-            and QrackAceBackend._BSEQ_MCU_PHI is not None
-            and QrackAceBackend._BSEQ_MCU_LAMBDA is not None
-            and QrackAceBackend._BSEQ_MCU_GAMMA is not None
-        )
-
-    @staticmethod
-    def _bseq_active():
-        return QrackAceBackend._bseq_u_active() or QrackAceBackend._bseq_mcu_active()
-
-    def _apply_bseq_correction(self, lq):
-        """Apply the trained BSEQ correction for one readout (the u
-        layer, then optionally the ancilla+mcu layer), to be reversed
-        afterward by _reverse_bseq_correction in the opposite order.
-        Returns a small state dict if anything was applied (so the
-        caller can pass it straight to the reversal without
-        re-deriving it), or None if nothing is active or applicable to
-        this qubit.
-
-        Fires every time this boundary qubit's state is about to be
-        read out (prob()/_correct()/m()/force_m() all funnel through
-        here, so this covers every simulator-API readout for the
-        qubit).
-        """
-        u_active = QrackAceBackend._bseq_u_active()
-        mcu_active = QrackAceBackend._bseq_mcu_active() and lq in self._ancilla
-        if not (u_active or mcu_active):
-            return None
-        hq = self._unpack(lq)
-        if len(hq) < 3:
-            return None
-        slot2_sim, slot2_idx = hq[2]
-
-        if u_active:
-            self.sim[slot2_sim].u(
-                slot2_idx,
-                QrackAceBackend._BSEQ_THETA,
-                QrackAceBackend._BSEQ_PHI,
-                QrackAceBackend._BSEQ_LAMBDA,
-            )
-
-        anc = None
-        if mcu_active:
-            anc_sim, anc_idx = self._ancilla[lq]
-            if anc_sim == slot2_sim:
-                anc = (anc_sim, anc_idx)
-                sim = self.sim[anc_sim]
-                sim.h(anc_idx)
-                sim.mcu(
-                    [anc_idx],
-                    slot2_idx,
-                    QrackAceBackend._BSEQ_MCU_THETA,
-                    QrackAceBackend._BSEQ_MCU_PHI,
-                    QrackAceBackend._BSEQ_MCU_LAMBDA,
-                    QrackAceBackend._BSEQ_MCU_GAMMA,
-                )
-
-        return {"slot2": hq[2], "ancilla": anc, "u_active": u_active}
-
-    def _reverse_bseq_correction(self, lq, state):
-        """Undo exactly what _apply_bseq_correction did, in the
-        opposite order: mcu-adjoint and H first (if the ancilla layer
-        ran), then u-adjoint last. Must be called once for every call
-        to _apply_bseq_correction that returned non-None, after the
-        caller is done reading whatever probabilities it needed,
-        passing the same state dict back.
-        """
-        slot2_sim, slot2_idx = state["slot2"]
-        anc = state["ancilla"]
-
-        if anc is not None:
-            anc_sim, anc_idx = anc
-            sim = self.sim[anc_sim]
-            sim.mcu(
-                [anc_idx],
-                slot2_idx,
-                -QrackAceBackend._BSEQ_MCU_THETA,
-                -QrackAceBackend._BSEQ_MCU_LAMBDA,
-                -QrackAceBackend._BSEQ_MCU_PHI,
-                -QrackAceBackend._BSEQ_MCU_GAMMA,
-            )
-            sim.h(anc_idx)
-
-        if state["u_active"]:
-            self.sim[slot2_sim].u(
-                slot2_idx,
-                -QrackAceBackend._BSEQ_THETA,
-                -QrackAceBackend._BSEQ_LAMBDA,
-                -QrackAceBackend._BSEQ_PHI,
-            )
-
     def _correct(self, lq, phase=False, skip_rotation=False):
         hq = self._unpack(lq)
 
@@ -793,8 +632,6 @@ class QrackAceBackend:
 
         qb, _ = QrackAceBackend._get_qb_lhv_indices(hq)
 
-        bseq_state = self._apply_bseq_correction(lq)
-
         if phase:
             for q in qb:
                 b = hq[q]
@@ -803,53 +640,84 @@ class QrackAceBackend:
                 self._lhv[lq].h()
 
         if len(hq) == 5:
-            # RMS
-            p = [
-                self.sim[hq[0][0]].prob(hq[0][1]),
-                self.sim[hq[1][0]].prob(hq[1][1]),
-                self.sim[hq[2][0]].prob(hq[2][1]),
-                self.sim[hq[3][0]].prob(hq[3][1]),
-                self.sim[hq[4][0]].prob(hq[4][1]),
-            ]
-            # Balancing suggestion from Elara (the custom OpenAI GPT)
-            prms = math.sqrt((p[0] ** 2 + p[1] ** 2 + 3 * (p[2] ** 2) + p[3] ** 2 + p[4] ** 2) / 7)
-            qrms = math.sqrt(
-                (
-                    (1 - p[0]) ** 2
-                    + (1 - p[1]) ** 2
-                    + 3 * ((1 - p[2]) ** 2)
-                    + (1 - p[3]) ** 2
-                    + (1 - p[4]) ** 2
+            p0 = self.sim[hq[0][0]].prob(hq[0][1])
+            p1 = self.sim[hq[1][0]].prob(hq[1][1])
+            p2 = self.sim[hq[2][0]].prob(hq[2][1])
+            p3 = self.sim[hq[3][0]].prob(hq[3][1])
+            p4 = self.sim[hq[4][0]].prob(hq[4][1])
+            lhv = self._lhv.get(lq)
+
+            # The 4 "end-cap" replicas (home patch + the 3 patch-partner
+            # shadow replicas), by analogy with the 3-replica case's
+            # slot1/slot2: vote first via their own RMS pool, UNLESS they
+            # are in a genuine 2-vs-2 tie, in which case the crossbar
+            # replica (hq[2], already weighted specially in the prior
+            # flat-pool code) breaks the tie; the LHV is consulted only
+            # as a last-resort fallback if the crossbar itself is
+            # ambiguous. This is a direct structural analogy to the
+            # validated 3-replica cascade, not independently re-derived
+            # for this topology -- carried only as far as that cheap
+            # analogy supports, per explicit guidance.
+            end_caps = [p0, p1, p3, p4]
+            high_count = sum(1 for x in end_caps if x >= 0.5)
+            end_caps_tied = high_count == 2
+
+            if not end_caps_tied:
+                prms = math.sqrt(sum(x**2 for x in end_caps) / 4)
+                qrms = math.sqrt(sum((1 - x) ** 2 for x in end_caps) / 4)
+                eff_prob = (prms + (1 - qrms)) / 2
+                result = (
+                    (random.random() < 0.5)
+                    if abs(eff_prob - 0.5) <= self._epsilon
+                    else (eff_prob >= 0.5)
                 )
-                / 7
-            )
-            eff_prob = (prms + (1 - qrms)) / 2
-            result = (
-                (random.random() < 0.5)
-                if abs(eff_prob - 0.5) <= self._epsilon
-                else (eff_prob >= 0.5)
-            )
-            syndrome = (
-                [1 - p[0], 1 - p[1], 1 - p[2], 1 - p[3], 1 - p[4]]
-                if result
-                else [p[0], p[1], p[2], p[3], p[4]]
-            )
+            elif abs(p2 - 0.5) > self._epsilon:
+                result = p2 >= 0.5
+            elif lhv is not None:
+                p_lhv = lhv.prob()
+                result = (
+                    (random.random() < 0.5)
+                    if abs(p_lhv - 0.5) <= self._epsilon
+                    else (p_lhv >= 0.5)
+                )
+            else:
+                result = random.random() < 0.5
+
+            p = [p0, p1, p2, p3, p4]
+            syndrome = [1 - x for x in p] if result else list(p)
             for q in range(5):
                 if syndrome[q] > (0.5 + self._epsilon):
                     self.sim[hq[q][0]].x(hq[q][1])
 
             if not skip_rotation:
-                a, i = [0, 0, 0, 0, 0], [0, 0, 0, 0, 0]
-                a[0], i[0] = self._get_bloch_angles(hq[0])
-                a[1], i[1] = self._get_bloch_angles(hq[1])
-                a[2], i[2] = self._get_bloch_angles(hq[2])
-                a[3], i[3] = self._get_bloch_angles(hq[3])
-                a[4], i[4] = self._get_bloch_angles(hq[4])
-
-                a_target = sum(a) / 5
-                i_target = sum(i) / 5
-                for x in range(5):
-                    self._rotate_to_bloch(hq[x], a_target - a[x], i_target - i[x])
+                a, i, w = [0, 0, 0, 0, 0], [0, 0, 0, 0, 0], [0, 0, 0, 0, 0]
+                a[0], i[0], r0 = self._get_bloch_angles(hq[0])
+                a[1], i[1], r1 = self._get_bloch_angles(hq[1])
+                a[2], i[2], r2 = self._get_bloch_angles(hq[2])
+                a[3], i[3], r3 = self._get_bloch_angles(hq[3])
+                a[4], i[4], r4 = self._get_bloch_angles(hq[4])
+                w = [1 - r0, 1 - r1, 1 - r2, 1 - r3, 1 - r4]
+
+                w_total = sum(w)
+                if w_total > self._epsilon:
+                    a_target = sum(wx * ax for wx, ax in zip(w, a)) / w_total
+                    i_target = sum(wx * ix for wx, ix in zip(w, i)) / w_total
+                    # hq[0] is excluded from the rotation itself, by the
+                    # same reasoning as the 3-replica case above: it's
+                    # allocated identically (unconditionally, first, in
+                    # the qubit's home-patch simulator) before any
+                    # boundary/crossbar extension logic runs, so it's the
+                    # replica most likely to carry real, same-simulator
+                    # coherent entanglement worth protecting from the
+                    # decoherence a physical rotation would cost it.
+                    # Indices 1-4 are all crossbar-extension slots with
+                    # no comparable real entanglement to lose.
+                    for x in range(1, 5):
+                        self._rotate_to_bloch(hq[x], a_target - a[x], i_target - i[x])
+                # If every replica reads as maximally mixed (w_total ~ 0),
+                # there is no well-defined direction to rotate toward at
+                # all -- skip the rotation rather than rotate toward an
+                # arbitrary/undefined target derived from noise.
 
         else:
             lhv = self._lhv.get(lq)
@@ -891,7 +759,27 @@ class QrackAceBackend:
                 p2 = self.sim[hq[2][0]].prob(hq[2][1])
                 p_lhv = lhv.prob()
 
-                if (p1 >= 0.5) == (p2 >= 0.5):
+                end_caps_agree = (p1 >= 0.5) == (p2 >= 0.5)
+                slot0_disagrees_with_end_caps = (
+                    end_caps_agree
+                    and (abs(p0 - 0.5) > self._epsilon)
+                    and ((p0 >= 0.5) != (p1 >= 0.5))
+                )
+                if slot0_disagrees_with_end_caps:
+                    # The end-caps agreeing is not, by itself, reliable
+                    # corroboration: it can equally well mean both are
+                    # stale (e.g. an interior qubit they were shadow-
+                    # coupled to has since been measured for real, and
+                    # only slot0 -- which shares a simulator with that
+                    # interior qubit -- has actually been updated to
+                    # reflect it). When slot0 has a real, non-ambiguous
+                    # opinion that contradicts the agreeing pair, that
+                    # contradiction is itself the signal that the pair's
+                    # agreement is stale, not corroborating -- so trust
+                    # slot0 directly, overriding the agreement-trusts-
+                    # itself default below.
+                    result = p0 >= 0.5
+                elif end_caps_agree:
                     prms = math.sqrt((p1**2 + p2**2) / 2)
                     qrms = math.sqrt(((1 - p1) ** 2 + (1 - p2) ** 2) / 2)
                     eff_prob = (prms + (1 - qrms)) / 2
@@ -924,16 +812,32 @@ class QrackAceBackend:
                 # _cpauli_lhv, preserving the property that makes it usable
                 # as a non-collapsing tie-breaker of last resort.
 
-            if not skip_rotation:
-                a, i = [0, 0, 0], [0, 0, 0]
-                a[0], i[0] = self._get_bloch_angles(hq[0])
-                a[1], i[1] = self._get_bloch_angles(hq[1])
-                a[2], i[2] = self._get_bloch_angles(hq[2])
-
-                a_target = sum(a) / 3
-                i_target = sum(i) / 3
-                for x in range(3):
-                    self._rotate_to_bloch(hq[x], a_target - a[x], i_target - i[x])
+            if (not skip_rotation) and (not end_caps_agree):
+                a, i, w = [0, 0, 0], [0, 0, 0], [0, 0, 0]
+                a[0], i[0], r0 = self._get_bloch_angles(hq[0])
+                a[1], i[1], r1 = self._get_bloch_angles(hq[1])
+                a[2], i[2], r2 = self._get_bloch_angles(hq[2])
+                w = [1 - r0, 1 - r1, 1 - r2]
+
+                w_total = sum(w)
+                if w_total > self._epsilon:
+                    a_target = sum(wx * ax for wx, ax in zip(w, a)) / w_total
+                    i_target = sum(wx * ix for wx, ix in zip(w, i)) / w_total
+                    # slot0 (hq[0]) is excluded from the rotation itself:
+                    # it commonly shares a real simulator with another
+                    # logical qubit it's still genuinely, coherently
+                    # entangled with (e.g. an interior control qubit),
+                    # and physically rotating it -- even toward a
+                    # well-intentioned averaged target -- is a real
+                    # decoherence event on that relationship. slot0's
+                    # Bloch angles still inform the target above (so
+                    # slot1/slot2 reconcile toward a value that accounts
+                    # for what slot0 currently shows), but only slot1 and
+                    # slot2 (the lossy shadow replicas, which have no
+                    # comparable real entanglement to lose) are actually
+                    # rotated.
+                    for x in range(1, 3):
+                        self._rotate_to_bloch(hq[x], a_target - a[x], i_target - i[x])
 
         if phase:
             for q in qb:
@@ -942,9 +846,6 @@ class QrackAceBackend:
             if lq in self._lhv:
                 self._lhv[lq].h()
 
-        if bseq_state is not None:
-            self._reverse_bseq_correction(lq, bseq_state)
-
     def apply_magnetic_bias(self, q, b):
         if b == 0:
             return
@@ -952,7 +853,7 @@ class QrackAceBackend:
         for x in q:
             hq = self._unpack(x)
             for h in hq:
-                a, i = self._get_bloch_angles(h)
+                a, i, _ = self._get_bloch_angles(h)
                 self._rotate_to_bloch(
                     h,
                     math.atan(math.tan(a) * b) - a,
@@ -1304,8 +1205,6 @@ class QrackAceBackend:
             b = hq[0]
             return self.sim[b[0]].prob(b[1])
 
-        bseq_state = self._apply_bseq_correction(lq)
-
         self._correct(lq)
         if len(hq) == 5:
             # RMS
@@ -1356,9 +1255,6 @@ class QrackAceBackend:
                 prms = math.sqrt((p[0] ** 2 + p[1] ** 2 + p[2] ** 2) / 3)
                 qrms = math.sqrt(((1 - p[0]) ** 2 + (1 - p[1]) ** 2 + (1 - p[2]) ** 2) / 3)
 
-        if bseq_state is not None:
-            self._reverse_bseq_correction(lq, bseq_state)
-
         return (prms + (1 - qrms)) / 2
 
     def m(self, lq):

{pyqrack_cpu-2.4.0 → pyqrack_cpu-2.5.1/pyqrack_cpu.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyqrack-cpu
-Version: 2.4.0
+Version: 2.5.1
 Summary: pyqrack - Pure Python vm6502q/qrack Wrapper
 Home-page: https://github.com/vm6502q/pyqrack
 Author: Daniel Strano

{pyqrack_cpu-2.4.0 → pyqrack_cpu-2.5.1}/pyqrack_cpu.egg-info/SOURCES.txt

@@ -17,7 +17,6 @@ pyqrack/qrack_stabilizer.py
 pyqrack/quimb_circuit_type.py
 pyqrack/qrack_system/__init__.py
 pyqrack/qrack_system/qrack_system.py
-pyqrack/scripts/optimize_bseq_correction.py
 pyqrack/stats/__init__.py
 pyqrack/stats/load_quantized_data.py
 pyqrack/stats/quantize_by_range.py

{pyqrack_cpu-2.4.0 → pyqrack_cpu-2.5.1}/setup.py

@@ -7,7 +7,7 @@ from setuptools import setup
 from setuptools.command.build_py import build_py
 
 
-VERSION = "2.4.0"
+VERSION = "2.5.1"
 
 # Read long description from README.
 README_PATH = os.path.join(os.path.abspath(os.path.dirname(__file__)), 'README.md')

pyqrack_cpu-2.4.0/pyqrack/scripts/optimize_bseq_correction.py

@@ -1,443 +0,0 @@
-# Empirical optimizer for QrackAceBackend's BSEQ (Bell/CHSH) correction
-# gate(s).
-#
-# The correction has two layers:
-#
-# 1. A plain, uncontrolled U(theta, phi, lambda) gate (QrackSimulator.u)
-#    applied directly to the boundary qubit. Always available; needs
-#    no ancilla. U then U-adjoint, with nothing else happening to the
-#    qubit in between except a probability read, is mathematically
-#    guaranteed to leave the qubit's actual evolution unaffected
-#    (U_dag @ U = I), while the intermediate readout genuinely depends
-#    on the qubit's value beforehand whenever U doesn't commute with
-#    the Z basis.
-#
-# 2. Optionally (when ancillae=True, the default, both here and at
-#    QrackAceBackend construction), a second layer applied AFTER the u
-#    gate: the boundary qubit's ancilla is prepped fresh into |+>, then
-#    acts as CONTROL on a 4-parameter mcu(theta,phi,lambda,gamma) gate
-#    targeting the boundary qubit. Reversed in the opposite order
-#    (mcu-adjoint, then u-adjoint) when uncomputing.
-#
-# Both layers ONLY wrap prob()'s own readout computation: _correct()'s
-# classical cascade (which permanently decides the boundary qubit's
-# committed bit for the rest of circuit evolution) runs completely
-# unaffected, exactly as it did before this correction existed. The
-# net effect: the correction can only ever change what a given
-# prob()/m()/force_m() call reports, and never anything a subsequent
-# gate in the circuit will actually see -- i.e. it is idempotent with
-# respect to circuit evolution, applying only to observable output.
-#
-# PyQrack's mcu follows the same convention as Qiskit's U/CU gates. Per
-# Qiskit's own documentation, UGate.inverse() gives U(th,ph,la)^dagger
-# = U(-th,-la,-ph) (theta negated, phi/lambda swapped-and-negated) --
-# directly verified against the real PyQrack simulator (matching to
-# better than 1e-6 on the full state vector) for both the 3-parameter u
-# and the 4-parameter mcu (gamma simply negated alongside the same
-# swap). Note Qiskit's separately-documented CUGate.inverse() page
-# states a different formula (straight negation, no swap) -- tested
-# directly against PyQrack's mcu, that formula does NOT match; the
-# swap formula is the one verified to actually work here.
-#
-# With ancillae=True (default), all 7 angles (3 for u, 4 for mcu) are
-# fit together. With ancillae=False, only the 3 u angles are fit (and
-# QrackAceBackend should be constructed with bseq_ancillae=False too,
-# so no ancilla qubits are allocated at all). They default to None
-# (each layer inactive, a guaranteed no-op) until set here, fit by
-# direct, gradient-free search against the empirically measured CHSH S
-# statistic (or its 4 components individually), averaged over repeated
-# Bell-pair trials to average down the substantial per-construction
-# measurement variance inherent to this architecture (each circuit
-# construction makes its own one-time classical collapse choice early
-# in the elision pipeline; averaging over MANY independent
-# constructions is what makes the mean S a meaningful, optimizable
-# target -- a single fixed gate cannot reduce per-shot variance, since
-# that variance is set by an earlier, already-classical decision the
-# gate cannot retroactively undo).
-#
-# Usage:
-#   python3 optimize_bseq_correction.py [--iterations N] [--time-budget SECONDS] [--no-ancillae]
-#
-# Writes the found angles directly into pyqrack's installed
-# qrack_ace_backend.py, so every subsequently-constructed
-# QrackAceBackend in the running process (and, if you choose to
-# persist the file, future processes) uses the fitted correction
-# automatically -- no separate model file, no extra inference
-# dependency, and no torch/JIT artifact needed: the correction is at
-# most 7 floats, and baking them in as class attributes is already the
-# most efficient possible packaging.
-
-import argparse
-import math
-import random
-import statistics
-import time
-
-from pyqrack import QrackAceBackend, Pauli
-import pyqrack.qrack_ace_backend as _ace_mod
-
-PI = math.pi
-
-# Standard CHSH angle set.
-THETA_A, THETA_AP = 0.0, PI / 2
-THETA_B, THETA_BP = PI / 4, -PI / 4
-
-
-def _apply_measurement_basis(sim, q, theta):
-    sim.r(Pauli.PauliY, theta, q)
-
-
-def _measure_expectation(sim, shots):
-    results = sim.measure_shots([0, 1], shots)
-    total = 0
-    for res in results:
-        a = (res >> 0) & 1
-        b = (res >> 1) & 1
-        total += 1 if a == b else -1
-    return total / shots
-
-
-def _expectation(theta1, theta2, shots, width=16, long_range_columns=1, ancillae=True):
-    """One fresh Bell-pair construction, measured at a given basis-angle
-    pair. This is exactly the bseq.py pattern: h(0), cx(0,1), then a
-    PauliY rotation on each half before measuring."""
-    s = QrackAceBackend(width, long_range_columns=long_range_columns, bseq_ancillae=ancillae)
-    s.h(0)
-    s.mcx([0], 1)
-    _apply_measurement_basis(s, 0, theta1)
-    _apply_measurement_basis(s, 1, theta2)
-    return _measure_expectation(s, shots)
-
-
-def compute_chsh_components(shots, **kwargs):
-    """Return the 4 CHSH correlator terms (E(a,b), E(a,b'), E(a',b), E(a',b'))."""
-    return (
-        _expectation(THETA_A, THETA_B, shots, **kwargs),
-        _expectation(THETA_A, THETA_BP, shots, **kwargs),
-        _expectation(THETA_AP, THETA_B, shots, **kwargs),
-        _expectation(THETA_AP, THETA_BP, shots, **kwargs),
-    )
-
-
-def compute_S(shots, **kwargs):
-    e_ab, e_abp, e_apb, e_apbp = compute_chsh_components(shots, **kwargs)
-    return e_ab + e_abp + e_apb - e_apbp
-
-
-def compute_bell_pair_stats(
-    n_constructions, shots, width=3, long_range_columns=1, ancillae=True, control=0
-):
-    """Simpler, plain Bell-pair statistic (matching bell_state.py): for
-    each of n_constructions independent constructions, put qubit
-    `control` into superposition and CNOT from it onto the other qubit
-    (control=0: h(0); cx(0,1), matching bell_state.py exactly;
-    control=1: h(1); cx(1,0), the mirrored direction -- qubit 1 is the
-    boundary qubit in this 3-qubit, long_range_columns=1 topology, so
-    these two directions exercise genuinely different code paths, not
-    just relabeled qubits). Samples shots measurements and tracks the
-    0/1 (agreement-side) balance and overall correlation. Returns
-    (mean_correlation, mean_balance, stdev_balance).
-    """
-    target = 1 - control
-    total_correlated = 0
-    balance_vals = []
-    for _ in range(n_constructions):
-        s = QrackAceBackend(width, long_range_columns=long_range_columns, bseq_ancillae=ancillae)
-        s.h(control)
-        s.cx(control, target)
-        results = s.measure_shots([0, 1], shots)
-        zero = sum(1 for r in results if r == 0)
-        three = sum(1 for r in results if r == 3)
-        correlated = zero + three
-        total_correlated += correlated
-        if correlated:
-            balance_vals.append(zero / correlated)
-    mean_corr = total_correlated / (n_constructions * shots)
-    mean_bal = statistics.mean(balance_vals) if balance_vals else 0.5
-    stdev_bal = statistics.stdev(balance_vals) if len(balance_vals) > 1 else 0.0
-    return mean_corr, mean_bal, stdev_bal
-
-
-def bell_pair_score(params, n_constructions=200, shots=24, ancillae=True, **kwargs):
-    """A single scalar reward for the Bell-pair objective: reward high
-    correlation, balance centered at 0.5, and low variance in that
-    balance across constructions. Weighted simply; adjust to taste.
-    params is a 3-tuple (u angles only) when ancillae=False, or a
-    7-tuple (u angles + mcu angles) when ancillae=True."""
-    set_correction(params, ancillae=ancillae)
-    mean_corr, mean_bal, stdev_bal = compute_bell_pair_stats(
-        n_constructions, shots, ancillae=ancillae, **kwargs
-    )
-    return mean_corr - abs(mean_bal - 0.5) - 0.5 * stdev_bal
-
-
-def bell_correlation_score(params, n_constructions=200, shots=24, ancillae=True, **kwargs):
-    """A simpler reward: just the mean Bell-pair correlation itself
-    (matching bell_state.py's printed "Correlation:" metric exactly --
-    correlated/shots, averaged over many independent constructions),
-    with no balance-centering or variance penalty. Note: unlike
-    bell_pair_score, this has no guard against the optimizer finding a
-    correction that pushes correlation up by forcing deterministic
-    agreement between the two qubits rather than by improving genuine
-    entanglement fidelity -- it is the more direct, but less
-    constrained, objective."""
-    set_correction(params, ancillae=ancillae)
-    mean_corr, _, _ = compute_bell_pair_stats(n_constructions, shots, ancillae=ancillae, **kwargs)
-    return mean_corr
-
-
-def bell_correlation_symmetric_score(
-    params, n_constructions=200, shots=24, ancillae=True, **kwargs
-):
-    """Like bell_correlation_score, but fit simultaneously, with equal
-    weight, against BOTH CNOT directions: control=0 (h(0); cx(0,1),
-    the original bell_state.py case) and control=1 (h(1); cx(1,0), the
-    mirrored case). Returns the unweighted average of the two
-    directions' mean correlations, so a correction that helps one
-    direction while hurting the other equally is NOT rewarded --
-    direct testing showed the correction trained on control=0 alone
-    actively hurts control=1 (correlation dropping to ~0.17, well
-    below the ~0.5 chance baseline), confirming the two directions
-    exercise genuinely different code paths (qubit 1 is the boundary
-    qubit in this topology) and need to be fit together, not assumed
-    symmetric."""
-    set_correction(params, ancillae=ancillae)
-    mean_corr_0, _, _ = compute_bell_pair_stats(
-        n_constructions, shots, ancillae=ancillae, control=0, **kwargs
-    )
-    mean_corr_1, _, _ = compute_bell_pair_stats(
-        n_constructions, shots, ancillae=ancillae, control=1, **kwargs
-    )
-    return (mean_corr_0 + mean_corr_1) / 2
-
-
-def set_correction(params, ancillae=True):
-    """params is a 3-tuple (theta, phi, lambda) for the u layer alone
-    when ancillae=False, or a 7-tuple (theta, phi, lambda, mcu_theta,
-    mcu_phi, mcu_lambda, mcu_gamma) when ancillae=True."""
-    theta, phi, lam = params[0], params[1], params[2]
-    _ace_mod.QrackAceBackend._BSEQ_THETA = theta
-    _ace_mod.QrackAceBackend._BSEQ_PHI = phi
-    _ace_mod.QrackAceBackend._BSEQ_LAMBDA = lam
-    if ancillae:
-        mcu_theta, mcu_phi, mcu_lam, mcu_gam = params[3], params[4], params[5], params[6]
-        _ace_mod.QrackAceBackend._BSEQ_MCU_THETA = mcu_theta
-        _ace_mod.QrackAceBackend._BSEQ_MCU_PHI = mcu_phi
-        _ace_mod.QrackAceBackend._BSEQ_MCU_LAMBDA = mcu_lam
-        _ace_mod.QrackAceBackend._BSEQ_MCU_GAMMA = mcu_gam
-    else:
-        _ace_mod.QrackAceBackend._BSEQ_MCU_THETA = None
-        _ace_mod.QrackAceBackend._BSEQ_MCU_PHI = None
-        _ace_mod.QrackAceBackend._BSEQ_MCU_LAMBDA = None
-        _ace_mod.QrackAceBackend._BSEQ_MCU_GAMMA = None
-
-
-def mean_reward(params, n_repeats, shots, ancillae=True, **kwargs):
-    """The actual optimization target: mean S across many independent
-    Bell-pair constructions ("an RCS data set for Bell-pair
-    perturbations"), not a single noisy reading."""
-    set_correction(params, ancillae=ancillae)
-    vals = [compute_S(shots, ancillae=ancillae, **kwargs) for _ in range(n_repeats)]
-    return statistics.mean(vals)
-
-
-def optimize(
-    n_repeats=4,
-    shots=64,
-    time_budget=200.0,
-    max_iterations=None,
-    seed=None,
-    initial_step=PI / 4,
-    step_decay=0.8,
-    decay_every=10,
-    target="correlation_symmetric",
-    ancillae=True,
-):
-    """Gradient-free random-walk search over the correction angles,
-    maximizing the chosen reward. Measurement sampling is not
-    differentiable, so this uses repeated empirical evaluation rather
-    than backprop -- appropriate given the actual cost here is at most
-    7 scalars, not a network.
-
-    ancillae: True (default) fits all 7 parameters (3 for the u layer,
-        4 for the ancilla+mcu layer) and constructs QrackAceBackend
-        with bseq_ancillae=True. False fits only the 3 u-layer
-        parameters and constructs with bseq_ancillae=False (no ancilla
-        qubits allocated at all).
-
-    target: "correlation_symmetric" (default) maximizes mean Bell-pair
-        correlation, fit simultaneously with EQUAL weight against both
-        CNOT directions (control=0, the original bell_state.py case,
-        and control=1, the mirrored case h(1); cx(1,0)) -- a correction
-        that helps one direction while hurting the other is not
-        rewarded. Direct testing showed these two directions are NOT
-        symmetric in this architecture (qubit 1 is the boundary qubit
-        in the 3-qubit, long_range_columns=1 topology): a correction
-        fit only on control=0 actively harmed control=1 (correlation
-        dropping to ~0.17, below the ~0.5 chance baseline). "correlation"
-        optimizes only the original control=0 direction. "bell_pair"
-        optimizes a composite of correlation, balance-centering, and
-        low variance (control=0 only). "S" optimizes the CHSH S
-        statistic directly. In direct testing, "S" did not show a
-        consistent improvement.
-    """
-    if seed is not None:
-        random.seed(seed)
-
-    if target == "S":
-        reward_fn = lambda p: mean_reward(p, n_repeats, shots, ancillae=ancillae)
-        label = "mean_S"
-    elif target == "bell_pair":
-        reward_fn = lambda p: bell_pair_score(
-            p, n_constructions=n_repeats * 32, shots=shots, ancillae=ancillae
-        )
-        label = "bell_pair_score"
-    elif target == "correlation":
-        reward_fn = lambda p: bell_correlation_score(
-            p, n_constructions=n_repeats * 32, shots=shots, ancillae=ancillae
-        )
-        label = "mean_correlation"
-    elif target == "correlation_symmetric":
-        reward_fn = lambda p: bell_correlation_symmetric_score(
-            p, n_constructions=n_repeats * 32, shots=shots, ancillae=ancillae
-        )
-        label = "mean_correlation_symmetric"
-    else:
-        raise ValueError(
-            f"unknown target: {target!r} (expected 'S', 'bell_pair', "
-            "'correlation', or 'correlation_symmetric')"
-        )
-
-    n_params = 7 if ancillae else 3
-    best_params = tuple(0.0 for _ in range(n_params))
-    best_score = reward_fn(best_params)
-    print(f"start: {label}={best_score:.4f}")
-
-    t_start = time.time()
-    step = initial_step
-    iteration = 0
-    while True:
-        if max_iterations is not None and iteration >= max_iterations:
-            break
-        if time_budget is not None and (time.time() - t_start) >= time_budget:
-            break
-
-        candidate = tuple(p + random.uniform(-step, step) for p in best_params)
-        score = reward_fn(candidate)
-        if score > best_score:
-            best_score = score
-            best_params = candidate
-            print(
-                f"iter {iteration}: improved -> "
-                f"params={[round(p, 4) for p in candidate]} {label}={score:.4f}"
-            )
-
-        iteration += 1
-        if iteration % decay_every == 0:
-            step *= step_decay
-
-    print()
-    print(f"FINAL params: {[round(p, 6) for p in best_params]}")
-    print(f"FINAL {label}: {best_score:.4f}")
-    if target == "S":
-        print(f"  (classical bound: 2.0, Tsirelson: {2*math.sqrt(2):.4f})")
-    print(f"total iterations: {iteration}")
-    return best_params, best_score
-
-
-def write_params_to_backend_file(params):
-    """Patch the installed pyqrack/qrack_ace_backend.py in place, so the
-    fitted correction persists for future processes too, without
-    requiring a separate model-loading step at import time. params is
-    a 3-tuple (u only) or a 7-tuple (u + mcu)."""
-    import os
-    import re
-
-    path = os.path.join(os.path.dirname(_ace_mod.__file__), "qrack_ace_backend.py")
-    with open(path, "r") as f:
-        src = f.read()
-
-    theta, phi, lam = params[0], params[1], params[2]
-    src = re.sub(r"_BSEQ_THETA\s*=\s*(None|[-0-9.eE]+)", f"_BSEQ_THETA = {theta!r}", src)
-    src = re.sub(r"_BSEQ_PHI\s*=\s*(None|[-0-9.eE]+)", f"_BSEQ_PHI = {phi!r}", src)
-    src = re.sub(r"_BSEQ_LAMBDA\s*=\s*(None|[-0-9.eE]+)", f"_BSEQ_LAMBDA = {lam!r}", src)
-
-    if len(params) >= 7:
-        mcu_theta, mcu_phi, mcu_lam, mcu_gam = params[3], params[4], params[5], params[6]
-        src = re.sub(
-            r"_BSEQ_MCU_THETA\s*=\s*(None|[-0-9.eE]+)",
-            f"_BSEQ_MCU_THETA = {mcu_theta!r}",
-            src,
-        )
-        src = re.sub(
-            r"_BSEQ_MCU_PHI\s*=\s*(None|[-0-9.eE]+)", f"_BSEQ_MCU_PHI = {mcu_phi!r}", src
-        )
-        src = re.sub(
-            r"_BSEQ_MCU_LAMBDA\s*=\s*(None|[-0-9.eE]+)",
-            f"_BSEQ_MCU_LAMBDA = {mcu_lam!r}",
-            src,
-        )
-        src = re.sub(
-            r"_BSEQ_MCU_GAMMA\s*=\s*(None|[-0-9.eE]+)",
-            f"_BSEQ_MCU_GAMMA = {mcu_gam!r}",
-            src,
-        )
-
-    with open(path, "w") as f:
-        f.write(src)
-    print(f"Wrote fitted angles into {path}")
-
-
-def main():
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("--iterations", type=int, default=None)
-    parser.add_argument("--time-budget", type=float, default=200.0)
-    parser.add_argument("--repeats", type=int, default=4)
-    parser.add_argument("--shots", type=int, default=64)
-    parser.add_argument("--seed", type=int, default=None)
-    parser.add_argument(
-        "--target",
-        choices=["S", "bell_pair", "correlation", "correlation_symmetric"],
-        default="correlation_symmetric",
-        help="Optimization objective: 'correlation_symmetric' (default) "
-        "maximizes mean Bell-pair correlation, fit with equal weight "
-        "against both CNOT directions (control=0 and control=1, which "
-        "are NOT symmetric in this architecture); 'correlation' fits "
-        "only the original control=0 direction; 'bell_pair' optimizes "
-        "a composite of correlation, balance-centering, and low "
-        "variance (control=0 only); 'S' optimizes the CHSH S "
-        "statistic directly.",
-    )
-    parser.add_argument(
-        "--no-ancillae",
-        dest="ancillae",
-        action="store_false",
-        default=True,
-        help="Fit only the 3-parameter u layer (no ancilla qubits "
-        "allocated at all, QrackAceBackend constructed with "
-        "bseq_ancillae=False). Default: fit all 7 parameters (u layer "
-        "+ ancilla/mcu layer), with bseq_ancillae=True.",
-    )
-    parser.add_argument(
-        "--persist",
-        action="store_true",
-        help="Write the fitted angles into the installed backend file.",
-    )
-    args = parser.parse_args()
-
-    params, score = optimize(
-        n_repeats=args.repeats,
-        shots=args.shots,
-        time_budget=args.time_budget,
-        max_iterations=args.iterations,
-        seed=args.seed,
-        target=args.target,
-        ancillae=args.ancillae,
-    )
-
-    if args.persist:
-        write_params_to_backend_file(params)
-
-
-if __name__ == "__main__":
-    main()