quantum-debugger 0.5.0__tar.gz → 0.6.1__tar.gz

quantum_debugger-0.6.1/AUTHORS.md

@@ -0,0 +1,56 @@
+# Authors and Contributors
+
+## Primary Author
+
+**Raunak Kumar Gupta**
+- GitHub: [@Raunakg2005](https://github.com/Raunakg2005)
+- LinkedIn: [Raunak Kumar Gupta](https://www.linkedin.com/in/raunak-kumar-gupta-7b3503270/)
+- Institution: K.J. Somaiya School of Engineering
+
+## Academic Supervision
+
+**Dr. Vaibhav Prakash Vasani**
+- LinkedIn: [Dr. Vaibhav Vasani](https://www.linkedin.com/in/dr-vaibhav-vasani-phd-460a4162/)
+- Role: Project Supervisor
+- Institution: K.J. Somaiya School of Engineering
+
+## Project Information
+
+- **Project:** Quantum Machine Learning Library with AutoML
+- **Version:** 0.6.0
+- **Started:** 2025
+- **Status:** Production Ready
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+### Contributors
+
+This section will list all contributors who submit pull requests.
+
+Thank you to everyone who has contributed to making quantum-debugger better!
+
+## Citation
+
+If you use quantum-debugger in your research, please cite:
+
+```bibtex
+@software{quantum_debugger_2026,
+  title = {Quantum Debugger: Production-Grade Quantum Machine Learning Library},
+  author = {Gupta, Raunak Kumar},
+  year = {2026},
+  url = {https://github.com/Raunakg2005/quantum-debugger},
+  note = {Supervised by Dr. Vaibhav Prakash Vasani, K.J. Somaiya School of Engineering}
+}
+```
+
+## Contact
+
+- **Issues:** [GitHub Issues](https://github.com/Raunakg2005/quantum-debugger/issues)
+- **Discussions:** [GitHub Discussions](https://github.com/Raunakg2005/quantum-debugger/discussions)
+- **LinkedIn:** [Raunak Kumar Gupta](https://www.linkedin.com/in/raunak-kumar-gupta-7b3503270/)
+
+## License
+
+MIT License - See [LICENSE](LICENSE) file for details.

quantum_debugger-0.6.1/CHANGELOG.md

@@ -0,0 +1,188 @@
+# 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.6.1] - 2026-07-16
+
+Release-hardening pass focused on correctness, performance, and robustness. No
+breaking API changes.
+
+### Added
+- **GPU state-vector simulation**: `QuantumCircuit.get_statevector(use_gpu=True,
+  precision='single'|'double')` runs the entire circuit on the GPU (CuPy) — the
+  state lives on the device across all gates with a single transfer back.
+  Verified identical to CPU in double precision; measured ~6x (double) and
+  50-75x (single) vs CPU at 20-22 qubits on an RTX 5060.
+- **Automatic Windows CUDA DLL discovery** so the GPU backend works out of the
+  box with the `cupy-cuda12x` + `nvidia-*-cu12` pip wheel setup.
+
+### Fixed
+- **Import robustness**: a broken or version-incompatible optional dependency
+  (e.g. PennyLane against a mismatched JAX) no longer crashes
+  `import quantum_debugger`. Optional-integration guards now degrade gracefully
+  to `<FRAMEWORK>_AVAILABLE = False` instead of only catching `ImportError`.
+- **QNN training**: `QuantumNeuralNetwork.fit` now uses the compiled optimizer
+  (Adam / SGD) instead of a hardcoded `params -= 0.01 * gradient` that ignored
+  `compile(...)`. Training now actually converges.
+- **QNN readout**: the network output is now a proper Pauli-Z expectation
+  `<Z_0>` over the full distribution, rather than `P(|0...0>) - P(|1...1>)`
+  which discarded almost all amplitudes for >2 qubits.
+- **AutoML**: `AutoQNN` now selects models on a held-out validation split (was
+  scoring on the training data — leakage) and refits the winning configuration
+  on all data.
+- **QAOA**: the cost layer now applies genuine two-qubit ZZ interactions
+  (CNOT·RZ·CNOT) instead of single-qubit RZ rotations, so the ansatz can
+  entangle and reach the true MaxCut optima.
+- **Hybrid (PyTorch)**: fixed a shape-mismatch crash in `HybridQNN` caused by a
+  duplicated output projection, and replaced the all-zero backward pass with
+  finite-difference gradients so the quantum layer (and any preceding classical
+  layers) actually train.
+- Corrected two test bugs exposed once the suite became collectable
+  (a swapped-argument `rx` call and a sign error in a QAOA convergence check).
+- **Windows CUDA DLL discovery**: with the common `cupy-cuda12x` + `nvidia-*-cu12`
+  wheel setup, the CUDA DLLs live under `site-packages/nvidia/*/bin` and are not
+  on the Windows DLL search path, so CuPy failed to load `nvrtc`/`cublas`. The
+  backend now adds those directories to `PATH` and the DLL search list before
+  importing CuPy, so the GPU backend works out of the box (verified on an
+  RTX 5060 / sm_120).
+
+### Reworked — placeholder features are now genuinely quantum
+Several advertised features previously returned classical surrogates, random
+values, or zero gradients. They are now real implementations, each verified:
+- **Quantum fidelity kernel / QSVM**: `FidelityKernel` computes
+  `|<phi(x1)|phi(x2)>|^2` by simulating the real feature-map circuits (was a
+  classical RBF). Gram matrix verified symmetric, unit-diagonal, PSD.
+  `ProjectedKernel` is now the real reduced-density-matrix kernel.
+- **Hybrid quantum layer** (`QuantumMiddleLayer`): forward is now a real
+  encoding + variational circuit measured in Z (was `cos(x + params)`), with
+  exact parameter-shift gradients wired into the PyTorch and TensorFlow layers
+  (were all-zero gradients). Gradients verified against finite differences.
+- **Quantum GAN**: real variational generator circuit and a trainable
+  discriminator with exact BCE gradients (was a global-phase no-op generator and
+  a random discriminator). Generator demonstrably learns a target distribution.
+- **Quantum RL**: real parameterized-circuit Q-function with parameter-shift TD
+  updates (was `tanh` of a dot product). Agent learns the gridworld to optimum.
+- **Error mitigation**: genuine PEC (quasi-probability Monte Carlo that recovers
+  the ideal expectation), CDR (exact Clifford simulation + regression), Quantum
+  Natural Gradient (true Fubini-Study metric, matches analytic values), and ZNE
+  noise scaling by real unitary folding (preserves the logical unitary).
+- **GPU module**: `DistributedQNN`/`DataParallelQNN` now genuinely train via real
+  data-parallel gradient averaging (base class no longer raises
+  `NotImplementedError`); mixed-precision `train_step` uses a real gradient (was
+  random). Multi-GPU wall-clock speedup still requires GPU hardware.
+
+### Changed
+- **Core simulator performance**: `QuantumState.apply_gate` now applies gates by
+  tensor contraction (O(2**n) per gate) instead of materializing the full
+  2**n x 2**n operator (O(4**n)). Results are numerically identical (verified
+  against the previous implementation over thousands of random configurations);
+  16-qubit circuits that were previously infeasible now run in tens of ms.
+- Reconciled version metadata: `__version__` is the single source of truth and
+  `setup.py` reads it (previously `0.4.2` in the package vs `0.6.0` in setup).
+
+## [0.4.2] - 2025-12-22
+
+### Added
+- **Complete pytest migration**: All 200 legacy script-style tests converted to pytest format
+- **Hardware profiles extended**: AWS Braket, Azure Quantum provider support
+- **2025 hardware updates**: IBM Heron, Google Willow, IonQ Forte profiles
+- **Advanced backend tests**: 8 edge case and performance tests
+- **GPU backend support**: CuPy backend availability testing
+- **Enhanced test coverage**: 656 comprehensive tests (all passing ✅)
+
+### Changed
+- Migrated all legacy test files from script execution to pytest format
+- Updated test structure for better CI/CD compatibility
+- Enhanced backend validation with 6 comprehensive backend tests
+- Improved hardware profile testing (18 tests total)
+
+### Fixed
+- Test suite compatibility issues
+- Backend detection for GPU/CuPy
+- Hardware profile version tracking
+
+### Documentation
+- Updated README.md with v0.4.2 features and test count
+- Added comprehensive testing section in README
+- Created FINAL_TEST_SUMMARY.md with complete 656 test breakdown
+- Fixed all documentation links (tutorials, examples, LICENSE)
+- Updated version numbers across all files
+
+### Testing
+- **656 total tests** (all passing ✅)
+- All script-style tests converted to pytest
+- Complete test coverage documentation
+
+## [0.4.1] - 2024-12-XX
+
+### Added
+- Additional QML features and optimizations
+- Performance improvements
+
+## [0.4.0] - 2024-12-XX
+
+### Added
+- **Quantum Machine Learning Module**
+- Parameterized gates (RX, RY, RZ with trainable parameters)
+- VQE algorithm for molecular chemistry
+- QAOA for combinatorial optimization
+- Training framework with 4 optimizers (Adam, SGD, SPSA, RMSprop)
+- Gradient computation (parameter shift rule, finite differences)
+- 316 comprehensive tests
+- 3 tutorials, 4 example scripts
+
+### Changed
+- Enhanced circuit profiling
+- Improved state visualization
+
+## [0.3.0] - 2024-12-XX
+
+### Added
+- Realistic noise models (4 types)
+- Hardware profiles (IBM, Google, IonQ, Rigetti)
+- Qiskit Aer validation
+- 89 new tests
+
+## [0.2.0] - 2024-XX-XX
+
+### Added
+- Bidirectional circuit conversion with Qiskit
+- CP gate support
+- 12-qubit support
+
+## [0.1.1] - 2024-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] - 2024-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.6.1/PKG-INFO

@@ -0,0 +1,449 @@
+Metadata-Version: 2.4
+Name: quantum-debugger
+Version: 0.6.1
+Summary: Comprehensive quantum machine learning library with AutoML, GPU acceleration, advanced algorithms (QGANs, Quantum RL), transfer learning, and multi-framework support (Qiskit, PennyLane, Cirq, TensorFlow, PyTorch)
+Home-page: https://github.com/Raunakg2005/quantum-debugger
+Author: Raunak Kumar Gupta
+Author-email: raunak.gupta@somaiya.edu
+Project-URL: Bug Reports, https://github.com/Raunakg2005/quantum-debugger/issues
+Project-URL: Source, https://github.com/Raunakg2005/quantum-debugger
+Project-URL: Documentation, https://github.com/Raunakg2005/quantum-debugger#readme
+Keywords: quantum computing debugging profiling quantum-circuit visualization qml vqe qaoa machine-learning
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS.md
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: scikit-learn>=1.0.0
+Provides-Extra: qiskit
+Requires-Dist: qiskit>=1.0.0; extra == "qiskit"
+Provides-Extra: pennylane
+Requires-Dist: pennylane>=0.30.0; extra == "pennylane"
+Provides-Extra: cirq
+Requires-Dist: cirq>=1.0.0; extra == "cirq"
+Provides-Extra: tensorflow
+Requires-Dist: tensorflow>=2.10.0; extra == "tensorflow"
+Provides-Extra: pytorch
+Requires-Dist: torch>=1.13.0; extra == "pytorch"
+Provides-Extra: ibm
+Requires-Dist: qiskit-ibm-runtime>=0.15.0; extra == "ibm"
+Provides-Extra: aws
+Requires-Dist: amazon-braket-sdk>=1.50.0; extra == "aws"
+Requires-Dist: boto3>=1.28.0; extra == "aws"
+Provides-Extra: all
+Requires-Dist: qiskit>=1.0.0; extra == "all"
+Requires-Dist: pennylane>=0.30.0; extra == "all"
+Requires-Dist: cirq>=1.0.0; extra == "all"
+Requires-Dist: tensorflow>=2.10.0; extra == "all"
+Requires-Dist: torch>=1.13.0; extra == "all"
+Requires-Dist: scikit-learn>=1.0.0; extra == "all"
+Requires-Dist: qiskit-ibm-runtime>=0.15.0; extra == "all"
+Requires-Dist: amazon-braket-sdk>=1.50.0; extra == "all"
+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: mypy>=0.990; 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
+
+# Quantum Debugger
+
+**The Most Comprehensive Quantum Machine Learning Library with AutoML**
+
+[![PyPI version](https://badge.fury.io/py/quantum-debugger.svg)](https://pypi.org/project/quantum-debugger/)
+[![Tests](https://img.shields.io/badge/tests-384%20passing-brightgreen)](https://github.com/Raunakg2005/quantum-debugger/blob/main/tests/FINAL_TEST_SUMMARY.md)
+[![CI](https://github.com/Raunakg2005/quantum-debugger/workflows/Tests/badge.svg)](https://github.com/Raunakg2005/quantum-debugger/actions)
+[![Codecov](https://codecov.io/gh/Raunakg2005/quantum-debugger/branch/main/graph/badge.svg)](https://codecov.io/gh/Raunakg2005/quantum-debugger)
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://python.org)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+A powerful Python library for quantum circuit debugging, state inspection, performance analysis, and quantum machine learning. From basic circuits to QML with one-line AutoML.
+
+## What's New in v0.6.1
+
+Correctness, performance, and "make the advertised features real" release:
+- **Faster core** - gate application is now O(2ⁿ) per gate (was O(4ⁿ)); optional
+  **GPU state-vector simulation** (`get_statevector(use_gpu=True)`, up to ~50-75x
+  at 20+ qubits in single precision).
+- **Genuinely quantum QML** - the quantum kernel/QSVM, hybrid PyTorch/TF layers,
+  Quantum GAN, Quantum RL, and error mitigation (PEC, CDR, QNG, ZNE) are now real
+  circuit-based implementations with real gradients, each verified — not the
+  classical/placeholder stand-ins they were before.
+- **Robust imports** - a broken optional dependency no longer breaks
+  `import quantum_debugger`.
+
+See [CHANGELOG.md](CHANGELOG.md) for the full list.
+
+## What's New in v0.6.0
+
+**ONE-LINE QUANTUM MACHINE LEARNING**
+
+```python
+# NEW: AutoML - Quantum ML for everyone
+from quantum_debugger.qml.automl import auto_qnn
+
+model = auto_qnn(X_train, y_train)
+predictions = model.predict(X_test)
+```
+
+**No quantum expertise required.** AutoML automatically:
+- Selects optimal number of qubits
+- Chooses best ansatz architecture  
+- Tunes all hyperparameters
+- Finds best model configuration
+
+### v0.6.0 Complete Feature Set
+
+**Advanced QML (Weeks 1-3)**
+- **Hybrid Models** - TensorFlow and PyTorch quantum layers
+- **Quantum Kernels** - QSVM with multiple kernel types
+- **Transfer Learning** - PretrainedQNN, model zoo, fine-tuning
+
+**Production Tools (Weeks 4-5)**
+- **Error Mitigation** - PEC, CDR, realistic noise models
+- **Circuit Optimization** - Gate reduction, compilation, transpilation
+
+**Universal Compatibility (Week 6)**
+- **Framework Integrations** - Qiskit, PennyLane, Cirq bridges
+
+**Hardware and Performance (Weeks 7-8)**
+- **Real Quantum Computers** - IBM Quantum (FREE), AWS Braket
+- **Benchmarking** - QML vs Classical performance analysis
+
+**AutoML (Week 9)**
+- **auto_qnn()** - One-line interface for quantum ML
+- **Automatic Ansatz Selection** - Finds best circuit architecture
+- **Hyperparameter Tuning** - Grid and random search
+- **Neural Architecture Search** - Optimizes qubit and layer counts
+
+**Jupyter Notebooks (Week 10)**
+- **5 Example Notebooks** - AutoML, Transfer Learning, Hardware, Optimization, Benchmarking
+- **Google Colab Compatible** - Run in browser
+
+**Advanced Algorithms (Week 11 - NEW)**
+- **Quantum GANs** - Generative adversarial networks for quantum states
+- **Quantum RL** - Q-learning with quantum circuits
+- **SimpleEnvironment** - Test environment for RL
+
+**CI/CD Automation (Week 12 - NEW)**
+- **GitHub Actions** - Auto-testing on Python 3.9-3.12
+- **Auto-Publishing** - Automatic PyPI releases
+- **Code Quality** - Linting, formatting checks
+
+**GPU Acceleration (v0.6.1)**
+- **GPU state-vector simulation** - `circuit.get_statevector(use_gpu=True)` runs
+  the whole circuit on the GPU (CuPy). Measured on an RTX 5060 vs CPU: ~6x in
+  double precision, and 50-75x in single precision (`precision='single'`) at
+  20-22 qubits, where the CPU becomes the bottleneck.
+- **Distributed / mixed-precision training** - real data-parallel gradient
+  averaging and mixed-precision steps. (Multi-GPU wall-clock speedup requires
+  multiple physical GPUs; on one device these run correctly but sequentially.)
+- **Windows-friendly** - auto-discovers pip-installed CUDA runtime wheels
+  (`nvidia-*-cu12`) so the GPU backend works without a manual CUDA toolkit setup.
+
+See [complete documentation](https://github.com/Raunakg2005/quantum-debugger#documentation) for details.
+
+## Features
+
+### Core Debugging
+- **Step-through Debugging** - Execute circuits gate-by-gate with breakpoints
+- **State Inspection** - Analyze quantum states at any point
+- **Circuit Profiling** - Depth analysis, gate statistics, optimization suggestions  
+- **Visualization** - State vectors, Bloch spheres, and more
+- **Noise Simulation** - Realistic hardware noise models
+- **Qiskit Integration** - Import/export circuits from Qiskit
+
+### Quantum Machine Learning (v0.6.0)
+- **AutoML** - One-line interface with automatic optimization
+- **Advanced Algorithms** - Quantum GANs and Quantum Reinforcement Learning
+- **Transfer Learning** - PretrainedQNN, model zoo, fine-tuning
+- **GPU Acceleration** - Multi-GPU, mixed precision (2-3x speedup)
+- **Error Mitigation** - PEC, CDR, realistic noise models  
+- **Circuit Optimization** - Gate reduction, compilation, transpilation
+- **Framework Bridges** - Qiskit, PennyLane, Cirq compatibility
+- **Hardware Backends** - IBM Quantum (FREE), AWS Braket
+- **Benchmarking** - QML vs Classical performance analysis
+- **Hybrid Models** - TensorFlow and PyTorch quantum layers
+- **Quantum Kernels** - QSVM with multiple kernel types
+- **VQE and QAOA** - Molecular chemistry and optimization
+- **Advanced Optimizers** - 7 optimizers including QNG
+- **Ansatz Library** - 8 pre-built quantum circuit templates
+- **Example Notebooks** - 5 comprehensive Jupyter tutorials
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install quantum-debugger
+```
+
+### Basic Circuit Debugging
+
+```python
+from quantum_debugger import QuantumCircuit, QuantumDebugger
+
+# Create a Bell state
+qc = QuantumCircuit(2)
+qc.h(0)
+qc.cnot(0, 1)
+
+# Debug step-by-step
+debugger = QuantumDebugger(qc)
+debugger.step()  # Execute first gate
+print(debugger.get_current_state())
+debugger.step()  # Execute second gate
+print(debugger.get_current_state())
+```
+
+### Quantum Machine Learning with AutoML
+
+```python
+from quantum_debugger.qml.automl import auto_qnn
+import numpy as np
+
+# Load your data
+X_train = np.random.randn(100, 4)
+y_train = np.random.randint(0, 2, 100)
+
+# One line to train quantum model
+model = auto_qnn(X_train, y_train)
+
+# Make predictions
+X_test = np.random.randn(20, 4)
+predictions = model.predict(X_test)
+```
+
+### Manual QNN Configuration
+
+For more control over your quantum neural network:
+
+```python
+from quantum_debugger.qml.qnn import QuantumNeuralNetwork
+
+# Create network
+qnn = QuantumNeuralNetwork(n_qubits=4)
+qnn.compile(optimizer='adam', loss='mse')
+
+# Train
+history = qnn.fit(X_train, y_train, epochs=50, batch_size=16)
+
+# Predict
+predictions = qnn.predict(X_test)
+```
+
+## Advanced Features
+
+### Transfer Learning
+
+```python
+from quantum_debugger.qml.transfer import PretrainedQNN
+
+# Load pretrained model
+pretrained = PretrainedQNN.from_zoo('iris_classifier')
+
+# Fine-tune on your data
+pretrained.fine_tune(X_new, y_new, epochs=10, freeze_layers=2)
+
+# Save your model
+pretrained.save('models/my_qnn.pkl')
+```
+
+### Error Mitigation
+
+```python
+from quantum_debugger.qml.mitigation import PEC, CDR
+
+# Probabilistic Error Cancellation
+pec = PEC(gate_error_rates={'rx': 0.01, 'cnot': 0.02})
+mitigated_result, uncertainty = pec.apply_pec(circuit)
+
+# Clifford Data Regression
+cdr = CDR(n_clifford_circuits=50)
+training_data = cdr.generate_training_data(n_qubits=4, depth=3)
+cdr.train(training_data, noisy_executor)
+mitigated = cdr.apply_cdr(noisy_measurement)
+```
+
+### Circuit Optimization
+
+```python
+from quantum_debugger.optimization import optimize_circuit, compile_circuit
+
+# Simple optimization
+gates = [('h', 0), ('h', 0), ('x', 1)]  # H cancels itself
+optimized = optimize_circuit(gates)  # Returns: [('x', 1)]
+
+# Multi-level compilation
+compiled = compile_circuit(gates, optimization_level=3)
+```
+
+### Hardware Deployment
+
+```python
+from quantum_debugger.backends import IBMQuantumBackend
+
+# Connect to IBM Quantum (FREE tier)
+backend = IBMQuantumBackend()
+backend.connect({'token': 'YOUR_FREE_IBM_TOKEN'})
+
+# Execute on real quantum computer
+gates = [('h', 0), ('cnot', (0, 1))]
+counts = backend.execute(gates, n_shots=1024)
+```
+
+Get your free IBM Quantum token at: https://quantum.ibm.com
+
+### Framework Integration
+
+```python
+from quantum_debugger.integrations import to_qiskit, from_qiskit, to_pennylane, to_cirq
+
+# Convert to Qiskit
+qiskit_circuit = to_qiskit(gates)
+
+# Convert to PennyLane
+pennylane_qnode = to_pennylane(gates)
+
+# Convert to Cirq
+cirq_circuit = to_cirq(gates)
+```
+
+## Installation Options
+
+### Basic Installation
+
+```bash
+pip install quantum-debugger
+```
+
+### With Optional Dependencies
+
+```bash
+# All frameworks
+pip install quantum-debugger[all]
+
+# Individual frameworks
+pip install quantum-debugger[qiskit]
+pip install quantum-debugger[pennylane]
+pip install quantum-debugger[cirq]
+pip install quantum-debugger[tensorflow]
+pip install quantum-debugger[pytorch]
+
+# Hardware backends
+pip install quantum-debugger[ibm]  # FREE
+pip install quantum-debugger[aws]  # Paid service
+
+# Development tools
+pip install quantum-debugger[dev]
+```
+
+## Documentation
+
+**v0.6.0 Guides:**
+- [V0.6.0 Features](V06_FEATURES.md) - Complete feature reference
+- [Transfer Learning Guide](docs/transfer_learning_guide.md)
+- [Error Mitigation Guide](docs/error_mitigation_guide.md)
+- [Circuit Optimization Guide](docs/circuit_optimization_guide.md)
+- [Hardware Backends Guide](docs/hardware_backends_guide.md)
+
+**v0.5.0 Guides (still valid):**
+- [QNN Guide](docs/qnn_guide.md)
+- [Hybrid Models Guide](docs/hybrid_models_guide.md)
+- [VQE Guide](docs/vqe_guide.md)
+- [QAOA Guide](docs/qaoa_guide.md)
+
+## Testing
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run specific test suites
+pytest tests/qml/ -v
+pytest tests/test_optimization.py -v
+pytest tests/test_integrations.py -v
+
+# With coverage
+pytest tests/ --cov=quantum_debugger --cov-report=html
+```
+
+See [FINAL_TEST_SUMMARY.md](tests/FINAL_TEST_SUMMARY.md) for detailed test information.
+
+**Test Statistics (v0.6.1):**
+- ~980 tests passing (`pytest tests/ -m "not aws"`)
+- GPU-hardware tests require a working CUDA + CuPy install; they skip otherwise
+- A few tests are performance/timing based and may vary by machine
+
+## Contributing
+
+Contributions are welcome. Please ensure:
+1. All tests pass
+2. Code follows PEP 8 style guidelines
+3. Documentation is updated
+4. New features include tests
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file.
+
+## Citation
+
+If you use quantum-debugger in your research, please cite:
+
+```bibtex
+@software{quantum_debugger_2026,
+  title = {Quantum Debugger: Production-Grade Quantum Machine Learning Library},
+  author = {Gupta, Raunak Kumar},
+  year = {2026},
+  url = {https://github.com/Raunakg2005/quantum-debugger}
+}
+```
+
+## Acknowledgments
+
+**Author:** Raunak Kumar Gupta  
+**GitHub:** [@Raunakg2005](https://github.com/Raunakg2005)  
+**LinkedIn:** [Raunak Kumar Gupta](https://www.linkedin.com/in/raunak-kumar-gupta-7b3503270/)  
+**Supervised by:** Dr. Vaibhav Prakash Vasani  
+**Supervisor LinkedIn:** [Dr. Vaibhav Vasani](https://www.linkedin.com/in/dr-vaibhav-vasani-phd-460a4162/)  
+**Institution:** K.J. Somaiya School of Engineering
+
+## Links
+
+**PyPI:** https://pypi.org/project/quantum-debugger/  
+**GitHub:** https://github.com/Raunakg2005/quantum-debugger  
+**Issues:** https://github.com/Raunakg2005/quantum-debugger/issues  
+**Documentation:** https://github.com/Raunakg2005/quantum-debugger#readme
+
+---
+
+**Version:** 0.6.1  
+**Last Updated:** July 2026