quantum-debugger 0.1.1__tar.gz

quantum_debugger-0.1.1/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to QuantumDebugger will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.1] - 2025-12-03
+
+### Fixed
+- Fixed SWAP gate matrix for little-endian qubit ordering
+- Fixed CNOT gate matrix for little-endian qubit ordering
+- Fixed Toffoli gate matrix for little-endian qubit ordering
+- Fixed entanglement detection for Bell states
+- Rewrote multi-qubit gate expansion algorithm using tensor products
+
+### Added
+- 69 comprehensive tests (100% pass rate)
+- Test suites: quickstart, advanced, comprehensive, extreme, validation, production, edge cases
+- Numerical stability tests (100+ consecutive operations)
+- Quantum mechanics validation tests
+- Production readiness tests
+
+### Changed
+- Improved gate expansion algorithm for better accuracy
+- Enhanced test coverage to 69 tests across 7 test suites
+
+## [0.1.0] - 2025-11-30
+
+### Added
+- Initial release
+- Core quantum state representation
+- 15+ quantum gates (H, X, Y, Z, S, T, RX, RY, RZ, PHASE, CNOT, CZ, SWAP, Toffoli)
+- Step-through debugger with breakpoints
+- Circuit profiler with optimization suggestions
+- State visualization tools
+- Bloch sphere representation
+- Support for up to 15 qubits
+- Example circuits and demos
+- Comprehensive documentation

quantum_debugger-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 QuantumDebugger Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quantum_debugger-0.1.1/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include requirements.txt
+recursive-include examples *.py
+recursive-include quantum_debugger *.py

quantum_debugger-0.1.1/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: quantum-debugger
+Version: 0.1.1
+Summary: Interactive debugger and profiler for quantum circuits
+Home-page: https://github.com/yourusername/quantum-debugger
+Author: warlord9004
+Author-email: your.email@example.com
+Project-URL: Bug Reports, https://github.com/yourusername/quantum-debugger/issues
+Project-URL: Source, https://github.com/yourusername/quantum-debugger
+Project-URL: Documentation, https://quantum-debugger.readthedocs.io
+Keywords: quantum computing debugging profiling quantum-circuit visualization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: scipy>=1.7.0
+Provides-Extra: qiskit
+Requires-Dist: qiskit>=0.39.0; extra == "qiskit"
+Provides-Extra: cirq
+Requires-Dist: cirq>=1.0.0; extra == "cirq"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: flake8>=4.0.0; extra == "dev"
+Requires-Dist: sphinx>=4.5.0; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# QuantumDebugger 🔬
+
+A powerful Python library for **interactive debugging and profiling of quantum circuits** with step-through execution, state visualization, and performance analysis.
+
+## 🌟 Features
+
+### 🐛 Interactive Debugging
+- **Step-through execution**: Execute quantum circuits gate-by-gate
+- **Breakpoints**: Set breakpoints at specific gates or conditions
+- **State inspection**: Examine quantum state at any point in execution
+- **Execution history**: Track and replay circuit execution
+- **Rewind capability**: Step backwards through circuit execution
+
+### 📊 Visualization
+- **State vector plots**: Visualize quantum state amplitudes and phases
+- **Probability distributions**: See measurement probabilities
+- **Bloch sphere**: 3D visualization for single qubit states
+- **Circuit diagrams**: ASCII and graphical circuit representations
+
+### 📈 Performance Profiling
+- **Gate depth analysis**: Measure circuit depth and critical paths
+- **Complexity metrics**: Gate counts, T-count, CNOT count
+- **Performance estimation**: Predict execution time on quantum hardware
+- **Optimization suggestions**: Get recommendations for circuit improvements
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install quantum-debugger
+```
+
+### Basic Usage
+
+```python
+from quantum_debugger import QuantumCircuit, QuantumDebugger
+
+# Create a Bell state circuit
+qc = QuantumCircuit(2)
+qc.h(0)
+qc.cnot(0, 1)
+
+# Debug the circuit
+debugger = QuantumDebugger(qc)
+
+# Step through execution
+debugger.step()  # Apply H gate
+debugger.inspect_state()  # Examine current state
+debugger.visualize()  # Show state visualization
+
+debugger.step()  # Apply CNOT
+debugger.inspect_state()  # See entangled state
+```
+
+### Setting Breakpoints
+
+```python
+# Set breakpoint at gate 5
+debugger.set_breakpoint(gate=5)
+
+# Run until breakpoint
+debugger.run_until_breakpoint()
+
+# Conditional breakpoint
+debugger.set_breakpoint(condition=lambda state: state.is_entangled())
+```
+
+### Profiling
+
+```python
+from quantum_debugger import CircuitProfiler
+
+profiler = CircuitProfiler(qc)
+report = profiler.analyze()
+
+print(f"Gate depth: {report.depth}")
+print(f"Total gates: {report.gate_count}")
+print(f"CNOT count: {report.cnot_count}")
+```
+
+## 📚 Examples
+
+Check out the `examples/` directory for:
+- **Bell State Debugging**: Step-by-step entanglement creation
+- **Grover's Algorithm**: Profiling and optimization
+- **Interactive Demo**: Full feature showcase
+
+## 🛠️ Requirements
+
+- Python 3.8+
+- NumPy
+- Matplotlib
+- (Optional) Qiskit/Cirq for integration
+
+## 🤝 Contributing
+
+Contributions welcome! Please feel free to submit a Pull Request.
+
+## 📄 License
+
+MIT License - feel free to use in your quantum computing projects!
+
+## 🎯 Why QuantumDebugger?
+
+Unlike existing quantum libraries that focus on circuit creation and execution, **QuantumDebugger** is specifically designed for:
+- **Learning**: Understand how quantum algorithms work step-by-step
+- **Development**: Debug complex quantum circuits efficiently
+- **Research**: Analyze and optimize quantum algorithms
+- **Teaching**: Demonstrate quantum concepts interactively
+
+## 📖 Documentation
+
+Full documentation available at: [quantum-debugger.readthedocs.io](https://quantum-debugger.readthedocs.io)
+
+## 🌐 Links
+
+- **GitHub**: [github.com/yourusername/quantum-debugger](https://github.com/yourusername/quantum-debugger)
+- **PyPI**: [pypi.org/project/quantum-debugger](https://pypi.org/project/quantum-debugger)
+- **Issues**: [Report bugs](https://github.com/yourusername/quantum-debugger/issues)
+
+---
+
+Made with ❤️ for the quantum computing community

quantum_debugger-0.1.1/README.md

@@ -0,0 +1,124 @@
+# QuantumDebugger 🔬
+
+A powerful Python library for **interactive debugging and profiling of quantum circuits** with step-through execution, state visualization, and performance analysis.
+
+## 🌟 Features
+
+### 🐛 Interactive Debugging
+- **Step-through execution**: Execute quantum circuits gate-by-gate
+- **Breakpoints**: Set breakpoints at specific gates or conditions
+- **State inspection**: Examine quantum state at any point in execution
+- **Execution history**: Track and replay circuit execution
+- **Rewind capability**: Step backwards through circuit execution
+
+### 📊 Visualization
+- **State vector plots**: Visualize quantum state amplitudes and phases
+- **Probability distributions**: See measurement probabilities
+- **Bloch sphere**: 3D visualization for single qubit states
+- **Circuit diagrams**: ASCII and graphical circuit representations
+
+### 📈 Performance Profiling
+- **Gate depth analysis**: Measure circuit depth and critical paths
+- **Complexity metrics**: Gate counts, T-count, CNOT count
+- **Performance estimation**: Predict execution time on quantum hardware
+- **Optimization suggestions**: Get recommendations for circuit improvements
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install quantum-debugger
+```
+
+### Basic Usage
+
+```python
+from quantum_debugger import QuantumCircuit, QuantumDebugger
+
+# Create a Bell state circuit
+qc = QuantumCircuit(2)
+qc.h(0)
+qc.cnot(0, 1)
+
+# Debug the circuit
+debugger = QuantumDebugger(qc)
+
+# Step through execution
+debugger.step()  # Apply H gate
+debugger.inspect_state()  # Examine current state
+debugger.visualize()  # Show state visualization
+
+debugger.step()  # Apply CNOT
+debugger.inspect_state()  # See entangled state
+```
+
+### Setting Breakpoints
+
+```python
+# Set breakpoint at gate 5
+debugger.set_breakpoint(gate=5)
+
+# Run until breakpoint
+debugger.run_until_breakpoint()
+
+# Conditional breakpoint
+debugger.set_breakpoint(condition=lambda state: state.is_entangled())
+```
+
+### Profiling
+
+```python
+from quantum_debugger import CircuitProfiler
+
+profiler = CircuitProfiler(qc)
+report = profiler.analyze()
+
+print(f"Gate depth: {report.depth}")
+print(f"Total gates: {report.gate_count}")
+print(f"CNOT count: {report.cnot_count}")
+```
+
+## 📚 Examples
+
+Check out the `examples/` directory for:
+- **Bell State Debugging**: Step-by-step entanglement creation
+- **Grover's Algorithm**: Profiling and optimization
+- **Interactive Demo**: Full feature showcase
+
+## 🛠️ Requirements
+
+- Python 3.8+
+- NumPy
+- Matplotlib
+- (Optional) Qiskit/Cirq for integration
+
+## 🤝 Contributing
+
+Contributions welcome! Please feel free to submit a Pull Request.
+
+## 📄 License
+
+MIT License - feel free to use in your quantum computing projects!
+
+## 🎯 Why QuantumDebugger?
+
+Unlike existing quantum libraries that focus on circuit creation and execution, **QuantumDebugger** is specifically designed for:
+- **Learning**: Understand how quantum algorithms work step-by-step
+- **Development**: Debug complex quantum circuits efficiently
+- **Research**: Analyze and optimize quantum algorithms
+- **Teaching**: Demonstrate quantum concepts interactively
+
+## 📖 Documentation
+
+Full documentation available at: [quantum-debugger.readthedocs.io](https://quantum-debugger.readthedocs.io)
+
+## 🌐 Links
+
+- **GitHub**: [github.com/yourusername/quantum-debugger](https://github.com/yourusername/quantum-debugger)
+- **PyPI**: [pypi.org/project/quantum-debugger](https://pypi.org/project/quantum-debugger)
+- **Issues**: [Report bugs](https://github.com/yourusername/quantum-debugger/issues)
+
+---
+
+Made with ❤️ for the quantum computing community

quantum_debugger-0.1.1/examples/bell_state_debug.py

@@ -0,0 +1,85 @@
+"""
+Bell State Creation and Debugging Demo
+
+This example demonstrates step-by-step debugging of Bell state creation.
+"""
+
+from quantum_debugger import QuantumCircuit, QuantumDebugger
+from quantum_debugger.visualization import StateVisualizer, BlochSphere
+
+
+def main():
+    print("=" * 70)
+    print(" " * 15 + "BELL STATE DEBUGGING DEMO")
+    print("=" * 70)
+    
+    # Create a Bell state circuit
+    print("\n1️⃣  Creating Bell state circuit...")
+    qc = QuantumCircuit(2)
+    qc.h(0)        # Hadamard on qubit 0
+    qc.cnot(0, 1)  # CNOT with control=0, target=1
+    
+    print(f"   Circuit created: {qc.size()} gates, depth {qc.depth()}")
+    print(qc.draw())
+    
+    # Initialize debugger
+    print("\n2️⃣  Initializing debugger...")
+    debugger = QuantumDebugger(qc)
+    
+    # Inspect initial state
+    print("\n3️⃣  Initial state |00⟩:")
+    debugger.visualize()
+    
+    # Step 1: Apply Hadamard
+    print("\n4️⃣  Stepping through: Applying H gate to qubit 0...")
+    debugger.step()
+    debugger.visualize()
+    
+    print("\n   🔍 Analysis after Hadamard:")
+    print(f"   - Qubit 0 is in superposition")
+    prob_0, prob_1 = debugger.inspector.get_qubit_probabilities(debugger.current_state, 0)
+    print(f"   - Qubit 0 probabilities: |0⟩={prob_0:.3f}, |1⟩={prob_1:.3f}")
+    print(f"   - Qubit 1 is still |0⟩")
+    
+    # Step 2: Apply CNOT
+    print("\n5️⃣  Stepping through: Applying CNOT gate...")
+    debugger.step()
+    debugger.visualize()
+    
+    print("\n   🔍 Analysis after CNOT:")
+    state_info = debugger.inspect_state()
+    print(f"   - State is entangled: {state_info['is_entangled']}")
+    print(f"   - Entropy: {state_info['entropy']:.3f}")
+    
+    # Show measurement statistics
+    print("\n6️⃣  Measurement statistics:")
+    stats = debugger.inspector.get_measurement_stats(debugger.current_state)
+    for basis, prob in stats.items():
+        print(f"   |{basis}⟩: {prob:.4f} ({prob*100:.1f}%)")
+    
+    # Run actual measurements
+    print("\n7️⃣  Running 1000 measurements...")
+    results = qc.run(shots=1000)
+    print(f"   Measurement counts:")
+    for outcome, count in sorted(results['counts'].items()):
+        print(f"   |{outcome}⟩: {count} times ({count/10:.1f}%)")
+    
+    # Visualizations
+    print("\n8️⃣  Creating visualizations...")
+    try:
+        # Plot state probabilities
+        StateVisualizer.plot_probabilities(debugger.current_state)
+        
+        # Plot Bloch sphere for each qubit
+        BlochSphere.plot(debugger.current_state, qubit=0)
+        BlochSphere.plot(debugger.current_state, qubit=1)
+        
+    except Exception as e:
+        print(f"   Visualization requires display: {e}")
+    
+    print("\n✅ Demo complete!")
+    print("=" * 70 + "\n")
+
+
+if __name__ == "__main__":
+    main()

quantum_debugger-0.1.1/examples/grover_profiling.py

@@ -0,0 +1,136 @@
+"""
+Grover's Algorithm Profiling Demo
+
+This example demonstrates circuit profiling and optimization analysis.
+"""
+
+import numpy as np
+from quantum_debugger import QuantumCircuit, CircuitProfiler
+
+
+def create_grover_circuit(n_qubits: int = 3, target: int = 5):
+    """
+    Create a simple Grover's algorithm circuit
+    
+    Args:
+        n_qubits: Number of qubits
+        target: Target state to search for
+    """
+    qc = QuantumCircuit(n_qubits)
+    
+    # Initialize: Create superposition
+    for q in range(n_qubits):
+        qc.h(q)
+    
+    # Oracle: Mark target state
+    # (Simplified oracle using phase flip)
+    for i, bit in enumerate(format(target, f'0{n_qubits}b')):
+        if bit == '0':
+            qc.x(i)
+    
+    # Multi-controlled Z gate (simplified with Toffoli decomposition)
+    if n_qubits == 3:
+        qc.toffoli(0, 1, 2)
+    
+    for i, bit in enumerate(format(target, f'0{n_qubits}b')):
+        if bit == '0':
+            qc.x(i)
+    
+    # Diffusion operator
+    for q in range(n_qubits):
+        qc.h(q)
+    for q in range(n_qubits):
+        qc.x(q)
+    
+    if n_qubits == 3:
+        qc.toffoli(0, 1, 2)
+    
+    for q in range(n_qubits):
+        qc.x(q)
+    for q in range(n_qubits):
+        qc.h(q)
+    
+    return qc
+
+
+def main():
+    print("=" * 70)
+    print(" " * 15 + "GROVER'S ALGORITHM PROFILING DEMO")
+    print("=" * 70)
+    
+    # Create Grover circuit
+    print("\n1️⃣  Creating Grover's search circuit...")
+    target_state = 5  # Searching for |101⟩
+    qc = create_grover_circuit(n_qubits=3, target=target_state)
+    
+    print(f"   Circuit created: {qc.size()} gates, {qc.num_qubits} qubits")
+    print(f"   Searching for state: |{format(target_state, '03b')}⟩")
+    
+    # Display circuit
+    print("\n2️⃣  Circuit diagram:")
+    print(qc.draw())
+    
+    # Initialize profiler
+    print("\n3️⃣  Running profiler analysis...")
+    profiler = CircuitProfiler(qc)
+    
+    # Print comprehensive report
+    profiler.print_report()
+    
+    # Get specific metrics
+    print("\n4️⃣  Detailed metrics:")
+    metrics = profiler.metrics
+    
+    print(f"\n   Gate Distribution:")
+    total = metrics.total_gates
+    for gate_name, count in sorted(metrics.gate_counts.items(), 
+                                   key=lambda x: x[1], reverse=True):
+        percentage = (count / total) * 100
+        print(f"   - {gate_name}: {count} ({percentage:.1f}%)")
+    
+    print(f"\n   Critical Path Analysis:")
+    print(f"   - Critical path length: {len(metrics.critical_path)} gates")
+    print(f"   - Total gates: {metrics.total_gates}")
+    print(f"   - Parallelism achieved: {metrics.parallelism:.2f}x")
+    
+    # Run circuit and analyze results
+    print("\n5️⃣  Running circuit simulation...")
+    results = qc.run(shots=1000)
+    
+    print(f"\n   Measurement results (top 5):")
+    sorted_counts = sorted(results['counts'].items(), 
+                          key=lambda x: x[1], reverse=True)
+    for outcome, count in sorted_counts[:5]:
+        print(f"   |{outcome}⟩: {count} times ({count/10:.1f}%)")
+    
+    # Check if target was found
+    target_binary = format(target_state, '03b')
+    if target_binary in results['counts']:
+        target_count = results['counts'][target_binary]
+        print(f"\n   ✅ Target state |{target_binary}⟩ found {target_count} times!")
+        print(f"   Success probability: {target_count/10:.1f}%")
+    
+    # Compare different circuit sizes
+    print("\n6️⃣ Scaling analysis:")
+    print(f"\n   {'Qubits':<10} {'Gates':<10} {'Depth':<10} {'CNOT':<10} {'Exec Time (μs)':<15}")
+    print(f"   {'-'*60}")
+    
+    for n in [2, 3, 4, 5]:
+        try:
+            temp_qc = create_grover_circuit(n_qubits=n, target=1)
+            temp_profiler = CircuitProfiler(temp_qc)
+            temp_metrics = temp_profiler.metrics
+            exec_time = temp_metrics.estimate_execution_time()
+            
+            print(f"   {n:<10} {temp_metrics.total_gates:<10} "
+                  f"{temp_metrics.depth:<10} {temp_metrics.cnot_count:<10} "
+                  f"{exec_time:<15.2f}")
+        except:
+            pass
+    
+    print("\n✅ Profiling demo complete!")
+    print("=" * 70 + "\n")
+
+
+if __name__ == "__main__":
+    main()