quantumflow-sdk 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

quantumflow/core/quantum_compressor.py

@@ -8,11 +8,16 @@ Key Results:
 - Compression ratio: 2.1×
 - Token reduction: 53.3%
 - Memory: O(log n) vs O(n) classical
+
+Enhanced with Gray-code measurement protocol from arXiv:2601.00247:
+- Measurement settings reduced from O(N) to 2n+1
+- Efficient amplitude and phase extraction
+- Logarithmic qubit encoding preserved
 """
 
 import math
 from dataclasses import dataclass, field
-from typing import Optional
+from typing import Optional, Literal
 import numpy as np
 from qiskit import QuantumCircuit
 
@@ -81,6 +86,313 @@ class CompressedResult:
         return reconstructed
 
 
+def generate_gray_code(n_bits: int) -> list[int]:
+    """
+    Generate Gray code sequence for n bits.
+
+    Gray code ensures adjacent codewords differ by exactly one bit,
+    enabling efficient phase extraction with minimal measurements.
+
+    Based on arXiv:2601.00247 Section IV.B
+
+    Args:
+        n_bits: Number of bits in the Gray code
+
+    Returns:
+        List of integers in Gray code order
+    """
+    if n_bits == 0:
+        return [0]
+
+    gray_sequence = []
+    for i in range(2 ** n_bits):
+        # Gray code: i XOR (i >> 1)
+        gray_sequence.append(i ^ (i >> 1))
+    return gray_sequence
+
+
+def gray_code_to_binary(gray: int) -> int:
+    """Convert Gray code to binary."""
+    binary = gray
+    mask = gray >> 1
+    while mask:
+        binary ^= mask
+        mask >>= 1
+    return binary
+
+
+def binary_to_gray(binary: int) -> int:
+    """Convert binary to Gray code."""
+    return binary ^ (binary >> 1)
+
+
+@dataclass
+class GrayCodeMeasurementResult:
+    """
+    Result from Gray-code optimized measurement.
+
+    Based on arXiv:2601.00247 - reduces measurement settings
+    from O(N) to 2n+1 where n = log₂(N).
+    """
+
+    amplitudes: np.ndarray
+    phases: np.ndarray
+    n_qubits: int
+    n_measurement_settings: int
+    measurement_type: str  # 'z', 'xx', 'xy'
+
+    @property
+    def complex_amplitudes(self) -> np.ndarray:
+        """Get full complex amplitudes α_j = |α_j|e^(iθ_j)."""
+        return self.amplitudes * np.exp(1j * self.phases)
+
+    @property
+    def probabilities(self) -> np.ndarray:
+        """Get measurement probabilities |α_j|²."""
+        return np.abs(self.amplitudes) ** 2
+
+
+class GrayCodeMeasurement:
+    """
+    Gray-code optimized measurement protocol.
+
+    Implements efficient amplitude and phase extraction from
+    arXiv:2601.00247 Section IV.B.
+
+    Key insight: By arranging codewords along a cyclic Gray code path,
+    each measurement operator couples exactly one pair of basis states,
+    enabling unique phase reconstruction.
+
+    Measurement Protocol:
+    1. M_Z: One Z-basis measurement → amplitudes |α_j|
+    2. M_XX: n X-basis measurements → cos(θ_{j+1} - θ_j)
+    3. M_XY: n XY-basis measurements → sin(θ_{j+1} - θ_j)
+
+    Total: 2n+1 measurement settings (vs O(N) standard)
+
+    Example:
+        >>> gm = GrayCodeMeasurement(n_qubits=4)
+        >>> result = gm.extract_amplitudes_and_phases(execution_result)
+        >>> print(f"Used {result.n_measurement_settings} measurement settings")
+    """
+
+    def __init__(self, n_qubits: int):
+        """
+        Initialize Gray-code measurement protocol.
+
+        Args:
+            n_qubits: Number of qubits in the system
+        """
+        self.n_qubits = n_qubits
+        self.n_states = 2 ** n_qubits
+        self.gray_sequence = generate_gray_code(n_qubits)
+
+    def get_measurement_settings_count(self) -> int:
+        """
+        Get total number of measurement settings needed.
+
+        Returns 2n+1 where n is number of qubits.
+        """
+        return 2 * self.n_qubits + 1
+
+    def extract_amplitudes(self, z_counts: dict[str, int], total_shots: int) -> np.ndarray:
+        """
+        Extract amplitudes from Z-basis measurement.
+
+        |α_j| = sqrt((1 - <Z_j>) / 2)
+
+        Args:
+            z_counts: Measurement counts from Z-basis
+            total_shots: Total number of shots
+
+        Returns:
+            Array of amplitude magnitudes
+        """
+        amplitudes = np.zeros(self.n_states)
+
+        for bitstring, count in z_counts.items():
+            # Convert bitstring to state index (Gray code order)
+            state_idx = int(bitstring, 2)
+            prob = count / total_shots
+            amplitudes[state_idx] = np.sqrt(prob)
+
+        # Normalize
+        norm = np.linalg.norm(amplitudes)
+        if norm > 0:
+            amplitudes /= norm
+
+        return amplitudes
+
+    def extract_phase_differences(
+        self,
+        xx_correlators: np.ndarray,
+        xy_correlators: np.ndarray,
+        amplitudes: np.ndarray,
+    ) -> np.ndarray:
+        """
+        Extract relative phases using Gray-code path.
+
+        θ_{j+1} - θ_j = arctan(<X_j Y_{j+1}> / <X_j X_{j+1}>)
+
+        Based on Eq. (13) and (22) from arXiv:2601.00247.
+
+        Args:
+            xx_correlators: <X_j X_{j+1}> for neighboring pairs
+            xy_correlators: <X_j Y_{j+1}> for neighboring pairs
+            amplitudes: Previously extracted amplitudes
+
+        Returns:
+            Array of phases (relative to first state)
+        """
+        phases = np.zeros(self.n_states)
+
+        # Walk along Gray code path to accumulate phases
+        for i in range(len(self.gray_sequence) - 1):
+            j = self.gray_sequence[i]
+            k = self.gray_sequence[i + 1]
+
+            # Get amplitude product
+            amp_product = amplitudes[j] * amplitudes[k]
+
+            if amp_product > 1e-10:  # Avoid division by zero
+                # Normalize correlators
+                cos_diff = xx_correlators[i] / (2 * amp_product)
+                sin_diff = xy_correlators[i] / (2 * amp_product)
+
+                # Clamp to valid range
+                cos_diff = np.clip(cos_diff, -1, 1)
+                sin_diff = np.clip(sin_diff, -1, 1)
+
+                # Phase difference
+                phase_diff = np.arctan2(sin_diff, cos_diff)
+            else:
+                phase_diff = 0.0
+
+            # Accumulate phase along path
+            phases[k] = phases[j] + phase_diff
+
+        return phases
+
+    def build_xx_measurement_circuits(
+        self,
+        base_circuit: QuantumCircuit,
+    ) -> list[QuantumCircuit]:
+        """
+        Build circuits for XX correlator measurements.
+
+        For each neighboring pair in Gray code, measure in X basis
+        on qubits that differ, Z basis on qubits that match.
+
+        Args:
+            base_circuit: The state preparation circuit
+
+        Returns:
+            List of measurement circuits
+        """
+        circuits = []
+
+        for i in range(self.n_qubits):
+            qc = base_circuit.copy()
+            qc.name = f"xx_measure_bit{i}"
+
+            # Apply H to qubit i (measure in X basis)
+            qc.h(i)
+            qc.measure_all()
+            circuits.append(qc)
+
+        return circuits
+
+    def build_xy_measurement_circuits(
+        self,
+        base_circuit: QuantumCircuit,
+    ) -> list[QuantumCircuit]:
+        """
+        Build circuits for XY correlator measurements.
+
+        Alternating X and Y basis for phase extraction.
+
+        Args:
+            base_circuit: The state preparation circuit
+
+        Returns:
+            List of measurement circuits
+        """
+        circuits = []
+
+        for i in range(self.n_qubits):
+            qc = base_circuit.copy()
+            qc.name = f"xy_measure_bit{i}"
+
+            # Apply H to qubit i (X basis)
+            qc.h(i)
+
+            # Apply S†H to qubit (i+1) mod n (Y basis)
+            next_qubit = (i + 1) % self.n_qubits
+            qc.sdg(next_qubit)
+            qc.h(next_qubit)
+
+            qc.measure_all()
+            circuits.append(qc)
+
+        return circuits
+
+    def full_reconstruction(
+        self,
+        z_result: dict[str, int],
+        xx_results: list[dict[str, int]],
+        xy_results: list[dict[str, int]],
+        total_shots: int,
+    ) -> GrayCodeMeasurementResult:
+        """
+        Perform full amplitude and phase reconstruction.
+
+        Args:
+            z_result: Z-basis measurement counts
+            xx_results: List of XX measurement counts
+            xy_results: List of XY measurement counts
+            total_shots: Shots per measurement
+
+        Returns:
+            GrayCodeMeasurementResult with amplitudes and phases
+        """
+        # Step 1: Extract amplitudes from Z measurement
+        amplitudes = self.extract_amplitudes(z_result, total_shots)
+
+        # Step 2: Compute XX correlators
+        xx_correlators = np.zeros(self.n_qubits)
+        for i, counts in enumerate(xx_results):
+            correlator = 0.0
+            for bitstring, count in counts.items():
+                # Parity of bits i and (i+1)
+                bits = [int(b) for b in bitstring]
+                parity = (-1) ** (bits[i] + bits[(i + 1) % self.n_qubits])
+                correlator += parity * count / total_shots
+            xx_correlators[i] = correlator
+
+        # Step 3: Compute XY correlators
+        xy_correlators = np.zeros(self.n_qubits)
+        for i, counts in enumerate(xy_results):
+            correlator = 0.0
+            for bitstring, count in counts.items():
+                bits = [int(b) for b in bitstring]
+                parity = (-1) ** (bits[i] + bits[(i + 1) % self.n_qubits])
+                correlator += parity * count / total_shots
+            xy_correlators[i] = correlator
+
+        # Step 4: Extract phases
+        phases = self.extract_phase_differences(
+            xx_correlators, xy_correlators, amplitudes
+        )
+
+        return GrayCodeMeasurementResult(
+            amplitudes=amplitudes,
+            phases=phases,
+            n_qubits=self.n_qubits,
+            n_measurement_settings=2 * self.n_qubits + 1,
+            measurement_type="full_reconstruction",
+        )
+
+
 class QuantumCompressor:
     """
     Quantum token compression using amplitude encoding.
@@ -288,6 +600,72 @@ class QuantumCompressor:
 
         return float(fidelity)
 
+    def compress_with_gray_code(
+        self,
+        tokens: list[int],
+        n_qubits: Optional[int] = None,
+        compression_level: float = 1.0,
+        shots: int = 1024,
+    ) -> tuple[CompressedResult, GrayCodeMeasurementResult]:
+        """
+        Compress tokens and extract using Gray-code measurement protocol.
+
+        This method uses the efficient measurement protocol from
+        arXiv:2601.00247 which requires only 2n+1 measurement settings
+        instead of O(N) for full state tomography.
+
+        Args:
+            tokens: List of integer tokens to compress
+            n_qubits: Number of qubits (auto-calculated if None)
+            compression_level: 0.0-1.0, higher = more compression
+            shots: Measurement shots per setting
+
+        Returns:
+            Tuple of (CompressedResult, GrayCodeMeasurementResult)
+
+        Example:
+            >>> compressor = QuantumCompressor(backend="simulator")
+            >>> result, gray_result = compressor.compress_with_gray_code([100, 200, 150, 175])
+            >>> print(f"Measurement settings used: {gray_result.n_measurement_settings}")
+            >>> print(f"Reconstructed amplitudes: {gray_result.amplitudes}")
+        """
+        # First compress normally
+        result = self.compress(tokens, n_qubits, compression_level)
+
+        # Initialize Gray-code measurement
+        gray_measure = GrayCodeMeasurement(result.n_qubits)
+
+        # Execute Z-basis measurement
+        z_circuit = result.compressed_circuit.copy()
+        z_circuit.measure_all()
+        z_result = self.backend.execute(z_circuit, shots=shots)
+
+        # Execute XX measurements
+        xx_circuits = gray_measure.build_xx_measurement_circuits(result.compressed_circuit)
+        xx_results = [
+            self.backend.execute(qc, shots=shots).counts
+            for qc in xx_circuits
+        ]
+
+        # Execute XY measurements
+        xy_circuits = gray_measure.build_xy_measurement_circuits(result.compressed_circuit)
+        xy_results = [
+            self.backend.execute(qc, shots=shots).counts
+            for qc in xy_circuits
+        ]
+
+        # Full reconstruction
+        gray_result = gray_measure.full_reconstruction(
+            z_result.counts, xx_results, xy_results, shots
+        )
+
+        # Update result with execution info
+        result.execution_result = z_result
+        result.metadata["gray_code_measurement"] = True
+        result.metadata["measurement_settings"] = gray_result.n_measurement_settings
+
+        return result, gray_result
+
 
 def compress_tokens(
     tokens: list[int],