quantum-debugger 0.1.1__py3-none-any.whl

quantum_debugger/core/quantum_state.py

@@ -0,0 +1,293 @@
+"""
+Quantum state representation and operations
+"""
+
+import numpy as np
+from typing import List, Tuple, Optional
+import copy
+
+
+class QuantumState:
+    """Represents a quantum state vector"""
+    
+    def __init__(self, num_qubits: int, state_vector: Optional[np.ndarray] = None):
+        """
+        Initialize a quantum state
+        
+        Args:
+            num_qubits: Number of qubits
+            state_vector: Optional initial state vector (defaults to |0...0>)
+        """
+        self.num_qubits = num_qubits
+        self.dim = 2 ** num_qubits
+        
+        if state_vector is not None:
+            if len(state_vector) != self.dim:
+                raise ValueError(f"State vector size {len(state_vector)} doesn't match {self.dim}")
+            self.state_vector = np.array(state_vector, dtype=complex)
+            self._normalize()
+        else:
+            # Initialize to |0...0> state
+            self.state_vector = np.zeros(self.dim, dtype=complex)
+            self.state_vector[0] = 1.0
+    
+    def _normalize(self):
+        """Normalize the state vector"""
+        norm = np.linalg.norm(self.state_vector)
+        if norm > 0:
+            self.state_vector /= norm
+    
+    def copy(self):
+        """Create a deep copy of this state"""
+        return copy.deepcopy(self)
+    
+    def apply_gate(self, gate_matrix: np.ndarray, target_qubits: List[int]):
+        """
+        Apply a quantum gate to specific qubits
+        
+        Args:
+            gate_matrix: Unitary matrix of the gate
+            target_qubits: List of qubit indices to apply gate to
+        """
+        # Build full gate matrix for entire system
+        full_matrix = self._build_full_gate_matrix(gate_matrix, target_qubits)
+        
+        # Apply gate
+        self.state_vector = full_matrix @ self.state_vector
+        self._normalize()
+    
+    def _build_full_gate_matrix(self, gate_matrix: np.ndarray, target_qubits: List[int]) -> np.ndarray:
+        """Build the full gate matrix for the entire quantum system"""
+        num_gate_qubits = int(np.log2(gate_matrix.shape[0]))
+        
+        if num_gate_qubits == self.num_qubits and target_qubits == list(range(self.num_qubits)):
+            return gate_matrix
+        
+        # For single and multi-qubit gates on subset of qubits
+        return self._expand_gate_to_full_space(gate_matrix, target_qubits)
+    
+    def _expand_gate_to_full_space(self, gate_matrix: np.ndarray, target_qubits: List[int]) -> np.ndarray:
+        """
+        Expand a gate acting on subset of qubits to full Hilbert space using tensor products.
+        
+        This method builds the full gate matrix by inserting identity matrices for 
+        non-target qubits and using Kronecker products to construct the complete operator.
+        
+        Args:
+            gate_matrix: The gate matrix to expand
+            target_qubits: List of qubit indices the gate acts on
+            
+        Returns:
+            Full gate matrix for entire system
+        """
+        num_gate_qubits = len(target_qubits)
+        
+        # Build list of operators for each qubit
+        # For target qubits, we'll later insert the actual gate
+        # For non-target qubits, use identity
+        I = np.eye(2, dtype=complex)
+        
+        # Sort target qubits to understand their positions
+        target_set = set(target_qubits)
+        
+        # Build the full operator using tensor products
+        # We need to handle the gate acting on possibly non-consecutive qubits
+        
+        # Method: Iterate through all basis states and apply gate where appropriate
+        full_matrix = np.zeros((self.dim, self.dim), dtype=complex)
+        
+        for in_idx in range(self.dim):
+            for out_idx in range(self.dim):
+                # Extract individual qubit states
+                in_bits = [(in_idx >> q) & 1 for q in range(self.num_qubits)]
+                out_bits = [(out_idx >> q) & 1 for q in range(self.num_qubits)]
+                
+                # Check if non-target qubits are unchanged
+                non_target_match = all(
+                    in_bits[q] == out_bits[q] 
+                    for q in range(self.num_qubits) 
+                    if q not in target_set
+                )
+                
+                if non_target_match:
+                    # Build gate indices from target qubit states
+                    # Map physical qubit index to gate matrix index
+                    gate_in_idx = 0
+                    gate_out_idx = 0
+                    
+                    for k, qubit in enumerate(target_qubits):
+                        # Qubit k in the gate corresponds to target_qubits[k] in the system
+                        gate_in_idx |= (in_bits[qubit] << k)
+                        gate_out_idx |= (out_bits[qubit] << k)
+                    
+                    # Get the matrix element from the gate
+                    full_matrix[out_idx, in_idx] = gate_matrix[gate_out_idx, gate_in_idx]
+        
+        return full_matrix
+
+    
+    def measure(self, qubit: int) -> int:
+        """
+        Measure a qubit and collapse the state
+        
+        Args:
+            qubit: Index of qubit to measure
+            
+        Returns:
+            Measurement result (0 or 1)
+        """
+        # Calculate probabilities
+        prob_0 = self.get_measurement_probability(qubit, 0)
+        
+        # Randomly choose outcome
+        outcome = 0 if np.random.random() < prob_0 else 1
+        
+        # Collapse state
+        self._collapse_state(qubit, outcome)
+        
+        return outcome
+    
+    def measure_all(self) -> List[int]:
+        """Measure all qubits"""
+        return [self.measure(q) for q in range(self.num_qubits)]
+    
+    def get_measurement_probability(self, qubit: int, outcome: int) -> float:
+        """Get probability of measuring a specific outcome for a qubit"""
+        prob = 0.0
+        for i, amplitude in enumerate(self.state_vector):
+            if (i >> qubit) & 1 == outcome:
+                prob += abs(amplitude) ** 2
+        return prob
+    
+    def get_probabilities(self) -> np.ndarray:
+        """Get probability distribution over all basis states"""
+        return np.abs(self.state_vector) ** 2
+    
+    def _collapse_state(self, qubit: int, outcome: int):
+        """Collapse state after measurement"""
+        new_state = np.zeros_like(self.state_vector)
+        
+        for i, amplitude in enumerate(self.state_vector):
+            if (i >> qubit) & 1 == outcome:
+                new_state[i] = amplitude
+        
+        self.state_vector = new_state
+        self._normalize()
+    
+    def fidelity(self, other: 'QuantumState') -> float:
+        """
+        Calculate fidelity with another quantum state
+        
+        Args:
+            other: Another quantum state
+            
+        Returns:
+            Fidelity value between 0 and 1
+        """
+        if self.num_qubits != other.num_qubits:
+            raise ValueError("States must have same number of qubits")
+        
+        overlap = np.abs(np.vdot(self.state_vector, other.state_vector))
+        return overlap ** 2
+    
+    def entropy(self) -> float:
+        """Calculate von Neumann entropy"""
+        probabilities = self.get_probabilities()
+        # Filter out zero probabilities to avoid log(0)
+        probabilities = probabilities[probabilities > 1e-10]
+        return -np.sum(probabilities * np.log2(probabilities))
+    
+    def is_entangled(self) -> bool:
+        """
+        Check if state is entangled (simple check for 2-qubit systems)
+        
+        For 2 qubits: state is entangled if it cannot be written as tensor product
+        """
+        if self.num_qubits != 2:
+            # More complex check needed for >2 qubits
+            # For now, use entropy as heuristic
+            return self.entropy() > 0.1
+        
+        # For 2 qubits: reshape state vector to 2x2 matrix
+        # State is |ψ⟩ = α|00⟩ + β|01⟩ + γ|10⟩ + δ|11⟩
+        # Separable if can be written as (a|0⟩ + b|1⟩) ⊗ (c|0⟩ + d|1⟩)
+        # This means the 2x2 matrix has rank 1
+        
+        state_matrix = self.state_vector.reshape(2, 2)
+        
+        # Check if matrix has rank 1 (separable) or rank 2 (entangled)
+        singular_values = np.linalg.svd(state_matrix, compute_uv=False)
+        
+        # If second singular value is small, state is separable (rank 1)
+        # Use relative threshold to handle numerical precision
+        threshold = 1e-10 * max(singular_values)
+        return singular_values[1] > threshold
+
+    
+    def bloch_vector(self, qubit: int = 0) -> Tuple[float, float, float]:
+        """
+        Get Bloch sphere coordinates for a single qubit
+        
+        Args:
+            qubit: Index of qubit (for multi-qubit systems, traces out other qubits)
+            
+        Returns:
+            (x, y, z) coordinates on Bloch sphere
+        """
+        if self.num_qubits == 1:
+            rho = np.outer(self.state_vector, self.state_vector.conj())
+        else:
+            # Partial trace to get single-qubit density matrix
+            rho = self._partial_trace(qubit)
+        
+        # Pauli matrices
+        sigma_x = np.array([[0, 1], [1, 0]], dtype=complex)
+        sigma_y = np.array([[0, -1j], [1j, 0]], dtype=complex)
+        sigma_z = np.array([[1, 0], [0, -1]], dtype=complex)
+        
+        x = np.real(np.trace(rho @ sigma_x))
+        y = np.real(np.trace(rho @ sigma_y))
+        z = np.real(np.trace(rho @ sigma_z))
+        
+        return (x, y, z)
+    
+    def _partial_trace(self, keep_qubit: int) -> np.ndarray:
+        """Partial trace to get single-qubit density matrix"""
+        rho = np.zeros((2, 2), dtype=complex)
+        
+        for i in range(self.dim):
+            for j in range(self.dim):
+                i_bit = (i >> keep_qubit) & 1
+                j_bit = (j >> keep_qubit) & 1
+                
+                # Check if other qubits match
+                i_other = i & ~(1 << keep_qubit)
+                j_other = j & ~(1 << keep_qubit)
+                
+                if i_other == j_other:
+                    rho[i_bit, j_bit] += self.state_vector[i] * self.state_vector[j].conj()
+        
+        return rho
+    
+    def __repr__(self):
+        """String representation of quantum state"""
+        state_str = []
+        for i, amplitude in enumerate(self.state_vector):
+            if abs(amplitude) > 1e-10:
+                binary = format(i, f'0{self.num_qubits}b')
+                real = np.real(amplitude)
+                imag = np.imag(amplitude)
+                
+                if abs(imag) < 1e-10:
+                    coef = f"{real:.3f}"
+                elif abs(real) < 1e-10:
+                    coef = f"{imag:.3f}i"
+                else:
+                    coef = f"{real:.3f}+{imag:.3f}i"
+                
+                state_str.append(f"{coef}|{binary}>")
+        
+        return " + ".join(state_str) if state_str else "0"
+    
+    def __str__(self):
+        return self.__repr__()

quantum_debugger/debugger/__init__.py

@@ -0,0 +1,7 @@
+"""Debugger module for step-through quantum circuit execution"""
+
+from quantum_debugger.debugger.debugger import QuantumDebugger
+from quantum_debugger.debugger.breakpoints import BreakpointManager
+from quantum_debugger.debugger.inspector import StateInspector
+
+__all__ = ["QuantumDebugger", "BreakpointManager", "StateInspector"]

quantum_debugger/debugger/breakpoints.py

@@ -0,0 +1,132 @@
+"""
+Breakpoint management for quantum circuit debugging
+"""
+
+from typing import Callable, List, Optional
+from quantum_debugger.core.quantum_state import QuantumState
+
+
+class Breakpoint:
+    """Represents a breakpoint in circuit execution"""
+    
+    def __init__(self, gate_index: Optional[int] = None, 
+                 condition: Optional[Callable[[QuantumState], bool]] = None,
+                 description: str = ""):
+        """
+        Initialize a breakpoint
+        
+        Args:
+            gate_index: Index of gate to break at (None for conditional)
+            condition: Function that returns True when breakpoint should trigger
+            description: Human-readable description
+        """
+        self.gate_index = gate_index
+        self.condition = condition
+        self.description = description
+        self.enabled = True
+        self.hit_count = 0
+    
+    def should_break(self, current_gate: int, state: QuantumState) -> bool:
+        """
+        Check if breakpoint should trigger
+        
+        Args:
+            current_gate: Current gate index
+            state: Current quantum state
+            
+        Returns:
+            True if breakpoint should trigger
+        """
+        if not self.enabled:
+            return False
+        
+        # Gate-based breakpoint
+        if self.gate_index is not None and current_gate == self.gate_index:
+            self.hit_count += 1
+            return True
+        
+        # Conditional breakpoint
+        if self.condition is not None:
+            try:
+                if self.condition(state):
+                    self.hit_count += 1
+                    return True
+            except Exception:
+                pass
+        
+        return False
+    
+    def __repr__(self):
+        if self.gate_index is not None:
+            return f"Breakpoint(gate={self.gate_index}, hits={self.hit_count})"
+        return f"Breakpoint(conditional, hits={self.hit_count})"
+
+
+class BreakpointManager:
+    """Manages breakpoints for debugging"""
+    
+    def __init__(self):
+        self.breakpoints: List[Breakpoint] = []
+    
+    def add(self, gate_index: Optional[int] = None,
+            condition: Optional[Callable[[QuantumState], bool]] = None,
+            description: str = "") -> Breakpoint:
+        """
+        Add a breakpoint
+        
+        Args:
+            gate_index: Gate index to break at
+            condition: Condition function
+            description: Breakpoint description
+            
+        Returns:
+            Created breakpoint
+        """
+        bp = Breakpoint(gate_index, condition, description)
+        self.breakpoints.append(bp)
+        return bp
+    
+    def remove(self, breakpoint: Breakpoint):
+        """Remove a breakpoint"""
+        if breakpoint in self.breakpoints:
+            self.breakpoints.remove(breakpoint)
+    
+    def clear(self):
+        """Remove all breakpoints"""
+        self.breakpoints.clear()
+    
+    def check(self, gate_index: int, state: QuantumState) -> Optional[Breakpoint]:
+        """
+        Check if any breakpoint should trigger
+        
+        Args:
+            gate_index: Current gate index
+            state: Current quantum state
+            
+        Returns:
+            Triggered breakpoint or None
+        """
+        for bp in self.breakpoints:
+            if bp.should_break(gate_index, state):
+                return bp
+        return None
+    
+    def enable_all(self):
+        """Enable all breakpoints"""
+        for bp in self.breakpoints:
+            bp.enabled = True
+    
+    def disable_all(self):
+        """Disable all breakpoints"""
+        for bp in self.breakpoints:
+            bp.enabled = False
+    
+    def list_breakpoints(self) -> List[Breakpoint]:
+        """Get list of all breakpoints"""
+        return self.breakpoints.copy()
+    
+    def __len__(self):
+        return len(self.breakpoints)
+    
+    def __repr__(self):
+        return f"BreakpointManager({len(self.breakpoints)} breakpoints)"

quantum_debugger/debugger/debugger.py

@@ -0,0 +1,222 @@
+"""
+Main debugger class for step-through quantum circuit execution
+"""
+
+from typing import Optional, List, Dict
+from quantum_debugger.core.circuit import QuantumCircuit
+from quantum_debugger.core.quantum_state import QuantumState
+from quantum_debugger.debugger.breakpoints import BreakpointManager, Breakpoint
+from quantum_debugger.debugger.inspector import StateInspector
+
+
+class ExecutionState:
+    """Represents the state at a point in circuit execution"""
+    
+    def __init__(self, gate_index: int, quantum_state: QuantumState, gate_name: str = ""):
+        self.gate_index = gate_index
+        self.quantum_state = quantum_state.copy()
+        self.gate_name = gate_name
+    
+    def __repr__(self):
+        return f"ExecutionState(gate={self.gate_index}, {self.gate_name})"
+
+
+class QuantumDebugger:
+    """Interactive debugger for quantum circuits"""
+    
+    def __init__(self, circuit: QuantumCircuit, initial_state: Optional[QuantumState] = None):
+        """
+        Initialize the debugger
+        
+        Args:
+            circuit: Quantum circuit to debug
+            initial_state: Optional initial state (defaults to |0...0>)
+        """
+        self.circuit = circuit
+        self.initial_state = initial_state or QuantumState(circuit.num_qubits)
+        self.current_state = self.initial_state.copy()
+        self.current_gate_index = 0
+        self.execution_history: List[ExecutionState] = []
+        self.breakpoints = BreakpointManager()
+        self.inspector = StateInspector()
+        
+        # Store initial state in history
+        self.execution_history.append(
+            ExecutionState(0, self.current_state, "INITIAL")
+        )
+    
+    def reset(self):
+        """Reset debugger to initial state"""
+        self.current_state = self.initial_state.copy()
+        self.current_gate_index = 0
+        self.execution_history = [
+            ExecutionState(0, self.current_state, "INITIAL")
+        ]
+    
+    def step(self, steps: int = 1) -> bool:
+        """
+        Execute one or more gates
+        
+        Args:
+            steps: Number of gates to execute
+            
+        Returns:
+            True if stepped successfully, False if at end
+        """
+        for _ in range(steps):
+            if self.current_gate_index >= len(self.circuit.gates):
+                return False
+            
+            # Get current gate
+            gate = self.circuit.gates[self.current_gate_index]
+            
+            # Apply gate
+            self.current_state.apply_gate(gate.matrix, gate.qubits)
+            
+            # Update index
+            self.current_gate_index += 1
+            
+            # Save state to history
+            self.execution_history.append(
+                ExecutionState(self.current_gate_index, self.current_state, str(gate))
+            )
+            
+            # Check for breakpoints
+            bp = self.breakpoints.check(self.current_gate_index, self.current_state)
+            if bp:
+                print(f"⚠️  Breakpoint hit: {bp}")
+                return True
+        
+        return True
+    
+    def step_back(self, steps: int = 1) -> bool:
+        """
+        Step backwards in execution history
+        
+        Args:
+            steps: Number of steps to go back
+            
+        Returns:
+            True if stepped back successfully
+        """
+        target_index = max(0, self.current_gate_index - steps)
+        
+        if target_index < len(self.execution_history):
+            exec_state = self.execution_history[target_index]
+            self.current_state = exec_state.quantum_state.copy()
+            self.current_gate_index = exec_state.gate_index
+            return True
+        
+        return False
+    
+    def run_to_end(self):
+        """Execute all remaining gates"""
+        while self.step():
+            pass
+    
+    def run_until_breakpoint(self):
+        """Execute until a breakpoint is hit or circuit ends"""
+        while self.current_gate_index < len(self.circuit.gates):
+            bp = self.breakpoints.check(self.current_gate_index, self.current_state)
+            if bp:
+                print(f"⚠️  Breakpoint hit at gate {self.current_gate_index}: {bp.description}")
+                break
+            
+            if not self.step():
+                break
+    
+    def set_breakpoint(self, gate: Optional[int] = None, 
+                      condition=None, description: str = "") -> Breakpoint:
+        """
+        Set a breakpoint
+        
+        Args:
+            gate: Gate index to break at
+            condition: Conditional function
+            description: Breakpoint description
+            
+        Returns:
+            Created breakpoint
+        """
+        return self.breakpoints.add(gate, condition, description)
+    
+    def clear_breakpoints(self):
+        """Remove all breakpoints"""
+        self.breakpoints.clear()
+    
+    def inspect_state(self) -> Dict:
+        """
+        Get detailed information about current state
+        
+        Returns:
+            Dictionary with state information
+        """
+        return self.inspector.get_state_summary(self.current_state)
+    
+    def get_state(self) -> QuantumState:
+        """Get current quantum state"""
+        return self.current_state.copy()
+    
+    def visualize(self):
+        """Print visualization of current state"""
+        print(f"\n{'='*60}")
+        print(f"Gate {self.current_gate_index}/{len(self.circuit.gates)}")
+        if self.current_gate_index < len(self.circuit.gates):
+            print(f"Next gate: {self.circuit.gates[self.current_gate_index]}")
+        else:
+            print("Circuit execution complete")
+        print(f"{'='*60}")
+        
+        self.inspector.print_state_info(self.current_state)
+    
+    def get_execution_trace(self) -> List[Dict]:
+        """
+        Get full execution trace
+        
+        Returns:
+            List of execution states with information
+        """
+        trace = []
+        for exec_state in self.execution_history:
+            trace.append({
+                'gate_index': exec_state.gate_index,
+                'gate_name': exec_state.gate_name,
+                'state_summary': self.inspector.get_state_summary(exec_state.quantum_state)
+            })
+        return trace
+    
+    def compare_with_expected(self, expected_state: QuantumState) -> Dict:
+        """
+        Compare current state with expected state
+        
+        Args:
+            expected_state: Expected quantum state
+            
+        Returns:
+            Comparison metrics
+        """
+        return self.inspector.compare_states(self.current_state, expected_state)
+    
+    def print_status(self):
+        """Print current debugging status"""
+        print(f"\n{'='*60}")
+        print(f"DEBUGGER STATUS")
+        print(f"{'='*60}")
+        print(f"Circuit: {self.circuit.num_qubits} qubits, {len(self.circuit.gates)} gates")
+        print(f"Current position: Gate {self.current_gate_index}/{len(self.circuit.gates)}")
+        
+        if self.current_gate_index < len(self.circuit.gates):
+            print(f"Next gate: {self.circuit.gates[self.current_gate_index]}")
+        else:
+            print("Status: Circuit execution complete")
+        
+        print(f"\nBreakpoints: {len(self.breakpoints)}")
+        for bp in self.breakpoints.list_breakpoints():
+            status = "✓" if bp.enabled else "✗"
+            print(f"  {status} {bp}")
+        
+        print(f"\nExecution history: {len(self.execution_history)} states saved")
+        print(f"{'='*60}\n")
+    
+    def __repr__(self):
+        return f"QuantumDebugger(gate {self.current_gate_index}/{len(self.circuit.gates)})"