Metadata-Version: 2.1
Name: pktron
Version: 2.9.6
Summary: PKTron — #1 South Asia | #3 Asia | #9 Global — The First Truly AI-Native, End-to-End Quantum + ML + Simulation Platform
Author-email: PKTron Team <pktron@example.com>
License: MIT
Project-URL: Homepage, https://github.com/pktron/pktron
Project-URL: Documentation, https://pktron.readthedocs.io
Project-URL: Repository, https://github.com/pktron/pktron
Project-URL: Bug Tracker, https://github.com/pktron/pktron/issues
Keywords: quantum computing,quantum simulation,quantum circuits,quantum algorithms,quantum cryptography,qiskit,pennylane,quantum machine learning,hybrid quantum classical,quantum walk,variational quantum eigensolver,grover search,quantum fourier transform,HHL,quantum PCA,BB84,quantum hardware emulator,pakistan,quantum debugger,quantum AI,south asia
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
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
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.21.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: scipy>=1.7.0
Provides-Extra: full
Requires-Dist: pennylane>=0.38.0; extra == "full"
Requires-Dist: quimb>=1.4.0; extra == "full"
Requires-Dist: networkx>=2.8.0; extra == "full"
Requires-Dist: plotly>=5.0.0; extra == "full"
Requires-Dist: seaborn>=0.11.0; extra == "full"
Requires-Dist: qutip>=4.6.0; extra == "full"
Requires-Dist: imageio>=2.9.0; extra == "full"
Requires-Dist: ipywidgets>=7.0.0; extra == "full"
Requires-Dist: joblib>=1.2.0; extra == "full"
Provides-Extra: gpu
Requires-Dist: cupy-cuda12x>=12.0.0; extra == "gpu"
Provides-Extra: ml
Requires-Dist: torch>=2.0.0; extra == "ml"
Requires-Dist: tensorflow>=2.12.0; extra == "ml"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: sphinx>=7.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Requires-Dist: build>=0.10.0; extra == "dev"

# PKTron v2.9.6

## 🏆 The First Truly AI-Native, End-to-End Quantum + ML + Simulation Platform

### 🥇 #1 in South Asia &nbsp;|&nbsp; 🥈 #3 in Asia &nbsp;|&nbsp; 🌍 #9 Globally

---

PKTron is a **pure-Python quantum computing framework** that combines quantum circuit simulation, AI-powered circuit generation, hybrid quantum-classical machine learning, quantum cryptography, and hardware emulation into one unified platform — all with zero mandatory dependencies beyond NumPy.

---

## ⚡ Install

```bash
pip install pktron              # NumPy only — works everywhere
pip install pktron[full]        # + pennylane, plotly, quimb, seaborn
pip install pktron[gpu]         # + CuPy GPU acceleration (CUDA 12)
pip install pktron[ml]          # + PyTorch + TensorFlow quantum layers
```

**Python 3.8 / 3.9 / 3.10 / 3.11 / 3.12 — Windows · Mac · Linux · Google Colab**

---

## 🚀 Quick Start — Copy and Run

```python
from pktron import QuantumCircuit

# Bell State (Quantum Entanglement)
qc = QuantumCircuit(2)
qc.h(0)
qc.cnot(0, 1)
print(qc.measure())   # → 50% |00⟩, 50% |11⟩

# Grover Search — finds target in √N steps
from pktron import grover_search
r = grover_search(num_qubits=3, target=5)
print(f"Found: {r['outcome']}")   # → 5

# AI Circuit Generator
from pktron import generate_circuit, explain_circuit
qc = generate_circuit("create a GHZ state on 3 qubits")
print(explain_circuit(qc))

# BB84 Quantum Key Distribution
from pktron import BB84Protocol
bb84 = BB84Protocol(num_bits=200)
key  = bb84.run(eavesdrop=False)
print(f"Shared key: {key['key_length']} bits  |  QBER: {key['qber']:.1%}")

# HHL Quantum Linear Solver (Ax = b)
from pktron import hhl_solve
import numpy as np
A = np.array([[2., 1.], [1., 2.]])
b = np.array([1., 0.])
r = hhl_solve(A, b, verbose=False)
print(f"Solution: {r.x_quantum}  |  Residual: {r.residual:.2e}")

# Step-by-Step Simulator (see state after every gate)
from pktron import generate_circuit, run_step_by_step, print_steps
qc = generate_circuit("bell state")
steps = run_step_by_step(qc)
print_steps(steps)

# Quantum Debugger with Breakpoints
from pktron import QuantumDebugger
dbg = QuantumDebugger()
dbg.set_breakpoint(1)
dbg.set_breakpoint(2)
snapshots = dbg.run_debug(qc)
dbg.inspect(1)

# Hardware Emulator (IBM-like device)
from pktron import HardwareEmulator
emu = HardwareEmulator("ibm_5q")
counts = emu.run(qc, shots=1024)   # noisy like real hardware
emu.summary()

# Quantum PCA
from pktron import qpca_fit
X = np.random.randn(16, 4)
r = qpca_fit(X, n_components=2)
print(f"Projected: {r.X_projected.shape}")

# SamplerV2 + EstimatorV2 (Qiskit-compatible)
from pktron import SamplerV2, EstimatorV2
sampler = SamplerV2(shots=1024)
result  = sampler.run(qc)
print("Counts:", result.counts)

# Bernstein-Vazirani (1 query vs N classical)
from pktron import BernsteinVazirani
bv = BernsteinVazirani(secret="10110101")
r  = bv.run()
print(f"Found secret: {r.secret_found}")   # → "10110101"

# QSVM — Quantum Support Vector Machine
from pktron.hybrid_qml import QSVM
qsvm = QSVM(feature_map="zz", n_qubits=2)
qsvm.fit(X_train, y_train)
print(f"Accuracy: {qsvm.score(X_test, y_test):.1%}")

# Custom Gate Plugin
from pktron import GatePlugin, PluginManager
import numpy as np
class SqrtXGate(GatePlugin):
    name   = "SqrtX"
    matrix = 0.5 * np.array([[1+1j, 1-1j], [1-1j, 1+1j]])
    def apply(self, circuit, qubit):
        circuit._apply_single_qubit_gate(np.array(self.matrix), qubit)
pm = PluginManager()
pm.register_gate(SqrtXGate())

# Performance Profiler
from pktron.profiler import PerformanceProfiler
qc3 = QuantumCircuit(4)
for i in range(3): qc3.h(i); qc3.cnot(i, i+1)
result = PerformanceProfiler().profile(qc3)
print(result.summary())
```

---

## 📦 Complete Feature List — v2.9.6 (230 Features · 64 Modules · 15,531 Lines)

### ⚛️ Core Quantum Circuit
| Feature | Description |
|---|---|
| `QuantumCircuit` | Build and run quantum circuits of any size |
| `QC` | Short alias for QuantumCircuit |
| All 18 gates | H, X, Y, Z, S, Sdg, T, Tdg, RX, RY, RZ, CNOT, CZ, CY, SWAP, Toffoli, and functional API |
| `measure()` | Collapse and measure all qubits |
| `draw()` / `draw_circuit_text()` / `draw_circuit_mpl()` | ASCII and matplotlib circuit diagrams |
| `get_state()` | Access the full statevector |
| `gate_history` | Full ordered log of all applied gates |

### 🎛️ Parameterized Circuits
| Feature | Description |
|---|---|
| `Parameter` | Named trainable parameter (e.g. theta) |
| `ParameterVector` | Indexed list of parameters |
| `rx_param()` / `ry_param()` / `rz_param()` | Rotation gates that accept Parameter objects |
| `bind_parameters()` | Assign real values to all Parameters |
| `circuit.parameters` | View all unbound parameters |

### 🖥️ Simulators & Backends (11 Backends)
| Backend | Description |
|---|---|
| `StatevectorSimulator` | Exact full statevector simulation |
| `AerSimulator` | Configurable: statevector / density_matrix / unitary |
| `DensityMatrixSimulator` | Full density matrix (mixed states + noise) |
| `StabilizerSimulator` | Fast Clifford-only simulation |
| `TensorNetworkSimulator` | Large circuits via quimb MPS |
| `SmartMPS` | Adaptive bond dimension MPS with entropy tracking |
| `GPUStatevectorSimulator` | GPU via CuPy, auto-fallback to NumPy |
| `GPUDensityMatrixSimulator` | GPU density matrix |
| `FullGPUStatevector` | All-GPU statevector (no CPU fallback) |
| `BatchedGPUStatevector` | Run many circuits at once on GPU |
| `AutoBackend` | Auto-selects fastest backend for your circuit |
| `DecisionDiagramBackend` | Sparse decision-diagram backend |
| `execute()` | Functional API: run any circuit on any backend |

### 📊 Primitives (Qiskit-Compatible)
| Feature | Description |
|---|---|
| `SamplerV2` | Run circuit N times, return measurement counts |
| `EstimatorV2` | Measure expectation value ⟨ψ\|O\|ψ⟩ |
| `AdvancedEstimatorV2` | EstimatorV2 + SparseObservable support |
| `MitigatedEstimatorV2` | EstimatorV2 with built-in error mitigation |
| `GPUBatchedSampler` | Batch many circuits on GPU |
| `GPUBatchedEstimator` | Batch expectation values on GPU |

### 🌊 Noise Simulation (13 Error Types)
| Error Type | Description |
|---|---|
| `DepolarizingError` | Equal X/Y/Z error probability |
| `PauliError` | Custom X/Y/Z flip probabilities |
| `AmplitudeDampingError` | Energy loss — T1 relaxation |
| `PhaseDampingError` | Phase decoherence — T2 dephasing |
| `ThermalRelaxationError` | Combined T1 + T2 thermal relaxation |
| `BitFlipError` | Random X flip with probability p |
| `PhaseFlipError` | Random Z flip with probability p |
| `NoiseModel` | Attach noise to specific gates or qubits |
| `NoiseModelV2` | Improved noise model with channel attachment |
| `add_gate_error()` | Attach noise to a specific gate |
| `add_qubit_error()` | Attach noise to a specific qubit |

### 🔧 Transpiler & Optimization
| Feature | Description |
|---|---|
| `PassManager` | Run optimization passes in order |
| `CancelInversePass` | Remove H+H, X+X, CNOT+CNOT pairs |
| `UnrollToffoliPass` | Decompose Toffoli → H + T + CNOT |
| `MergeRotationsPass` | Combine RX(a)+RX(b) → RX(a+b) |
| `BasisTranslationPass` | Translate to U3 + CNOT universal basis |

### 🧮 Quantum Information
| Feature | Description |
|---|---|
| `Statevector` | State vector with norm, probabilities, Bloch |
| `DensityMatrix` | Density matrix with purity, entropy, partial trace |
| `Operator` | Quantum operator with unitarity check, eigensolver |
| `Pauli` | Single or multi-qubit Pauli (X, Y, Z, ZZ, XI…) |
| `Clifford` | Clifford group element |
| `SparseObservable` | Weighted sum of Pauli strings (memory-efficient) |
| `PauliProductMeasurement` | Measure a Pauli product |
| `state_fidelity()` | Fidelity between two quantum states |
| `partial_trace()` | Trace out subsystems |

### 🛡️ Error Mitigation
| Feature | Description |
|---|---|
| `ZeroNoiseExtrapolation` | Run at multiple noise levels, extrapolate to zero (ZNE) |
| `ProbabilisticErrorCancellation` | Quasi-probability decomposition (PEC) |
| `ReadoutErrorMitigation` | Calibration matrix inversion (REM) |

### 🏗️ Fault-Tolerant Computing
| Feature | Description |
|---|---|
| `SurfaceCode` | Rotated surface code (distance d) |
| `RepetitionCode` | 3-qubit bit-flip repetition code |
| `SteaneCode` | [[7,1,3]] Steane code |
| `LogicalQubit` | High-level logical qubit backed by surface code |

### 🧬 Core Quantum Algorithms
| Algorithm | Description |
|---|---|
| `grover_search()` | Grover's search — finds target in √N steps |
| `grover()` | Grover v2 with configurable oracle |
| `qft()` | Quantum Fourier Transform (in-place) |
| `phase_estimation()` | Quantum Phase Estimation (QPE) |
| `quantum_phase_estimation()` | QPE v2 |
| `amplitude_amplification()` | Generalized Grover |
| `vqe()` | Variational Quantum Eigensolver |
| `qaoa()` | Quantum Approximate Optimization Algorithm |
| `shor_period_finding()` | Shor's period-finding subroutine |
| `bb84_qkd()` | BB84 quantum key distribution function |

### 🔬 Advanced Quantum Algorithms
| Algorithm | Description |
|---|---|
| `hhl_solve()` | HHL — Quantum Linear System Solver (Ax=b) |
| `qpca_fit()` | Quantum PCA — principal component analysis |
| `BernsteinVazirani` | Find hidden string in ONE query |
| `SimonsAlgorithm` | Simon's algorithm — exponential speedup |
| `QuantumCounting` | Count marked items via QPE on Grover |
| `AmplitudeEstimator` | Estimate amplitude √(M/N) via QPE |
| `shor_full` | Full Shor factoring with QFT matrix |
| `hhl_full` | Extended HHL: VQLS, QCG, Kaczmarz, Q-GMRES |
| `qpca` | Incremental qPCA, Kernel PCA, Randomised SVD |
| `quantum_walk` | Discrete + continuous quantum walks on any graph |
| `qgan` | Quantum Generative Adversarial Network |

### 🔐 Quantum Cryptography
| Feature | Description |
|---|---|
| `BB84Protocol` | Full BB84 QKD simulation |
| Alice + Bob + Eve | Eavesdropping detection (QBER threshold) |
| `BB84Protocol.run()` | With/without Eve, configurable intercept rate |
| `key_to_hex()` | Convert secret key bits to hex string |
| `EavesdroppingDetector` | Analyse QBER and give confidence verdict |
| `RECTILINEAR` / `DIAGONAL` | Basis constants |

### 🖥️ Hardware Emulation
| Feature | Description |
|---|---|
| `HardwareEmulator("ibm_5q")` | IBM 5-qubit linear chain device |
| `HardwareEmulator("noisy_20q")` | Noisy 20-qubit linear chain device |
| `is_connected()` | Check qubit connectivity |
| `decoherence_prob()` | Decoherence probability for circuit depth |
| `DEVICE_PROFILES` | Built-in device specification dictionary |

### 🤖 AI Tools
| Feature | Description |
|---|---|
| `generate_circuit("bell state")` | Plain English → QuantumCircuit |
| `generate_circuit("grover search")` | Many supported prompts |
| `generate_circuit("ghz state")` | GHZ, teleportation, superposition, etc. |
| `explain_circuit()` | Human-readable gate-by-gate explanation |

### 👣 Step-by-Step Simulator
| Feature | Description |
|---|---|
| `run_step_by_step()` | Statevector snapshot after every gate |
| `print_steps()` | Text probability bar charts per step |
| `plot_steps()` | Matplotlib bar charts per step |

### 🐛 Quantum Debugger
| Feature | Description |
|---|---|
| `QuantumDebugger` | Full debugger with breakpoints |
| `set_breakpoint(n)` | Pause after gate n |
| `run_debug()` | Run with full state printout at breakpoints |
| `inspect(n)` | Re-examine any snapshot |
| `plot_snapshot(n)` | Probability + phase bar charts |
| `list_breakpoints()` | Show all active breakpoints |

### 🔌 Plugin System
| Feature | Description |
|---|---|
| `PluginManager` | Register and manage extensions |
| `GatePlugin` | Add any custom unitary gate (validates unitarity) |
| `BackendPlugin` | Add any custom simulator backend |
| `AlgorithmPlugin` | Add any custom algorithm |

### 🧠 Hybrid Quantum-Classical ML
| Feature | Description |
|---|---|
| `QuantumLayer` | PyTorch nn.Module — differentiable quantum circuit |
| `TFQuantumLayer` | TensorFlow/Keras quantum layer |
| `GradientEstimator` | Parameter-shift rule gradients |
| `QNNClassifier` | Ready-to-use quantum neural network classifier |
| `ZZFeatureMap` | ZZ-interaction quantum feature map |
| `PauliFeatureMap` | Pauli basis quantum feature map |
| `FidelityKernel` | Fidelity-based quantum kernel |
| `QSVM` | Quantum Support Vector Machine |
| `QGAN` | Quantum GAN (generator + discriminator) |
| `QuantumConvLayer` | Quantum convolutional layer |
| `VariationalQuantumClassifier` | VQC with angle encoding |
| `HybridTrainingLoop` | End-to-end training loop |

### 📐 Measurement Tools
| Feature | Description |
|---|---|
| `ClassicalRegister` | Store classical measurement bits |
| `DynamicCircuit` | Mid-circuit measurements + conditional gates |
| `measure_qubit()` | Measure one qubit, collapse state |
| `measure_all()` | Sample full statevector distribution |
| `measure_partial()` | Measure subset of qubits |
| `save_statevector()` | Snapshot statevector mid-circuit |
| `save_probabilities()` | Snapshot probabilities mid-circuit |
| `save_expectation_value()` | Snapshot ⟨Z⟩ mid-circuit |

### 🔄 Qiskit Compatibility
| Feature | Description |
|---|---|
| `to_qasm()` | Export PKTron circuit → OpenQASM 2.0 |
| `from_qasm()` | Import OpenQASM 2.0 → PKTron circuit |
| `to_qiskit()` | Convert to real Qiskit QuantumCircuit |
| `from_qiskit()` | Convert real Qiskit circuit → PKTron |

### 📈 Visualization
| Feature | Description |
|---|---|
| `draw_circuit_text()` | ASCII circuit diagram |
| `draw_circuit_mpl()` | Matplotlib circuit diagram |
| `plot_city()` | 3D city plot of density matrix |
| `plot_hinton()` | Hinton diagram |
| `plot_bloch_multi()` | Bloch spheres for all qubits |
| `EnhancedResult` | Result with built-in plotting |

### ⏱️ Performance Profiler
| Feature | Description |
|---|---|
| `PerformanceProfiler` | Time + memory usage per gate |
| `ProfileResult.summary()` | Formatted table of results |

### 📊 Benchmarks
| Feature | Description |
|---|---|
| `run_benchmarks()` | Speed benchmarks across all backends |

---

## 📊 Stats

| Metric | Value |
|---|---|
| Total exported items | 193 |
| Python classes | 92 |
| Functions | 62 |
| Submodules | 39 |
| Python files | 64 |
| Lines of code | 15,531 |
| Supported Python | 3.8 / 3.9 / 3.10 / 3.11 / 3.12 |
| License | MIT (free for all use) |

---

## 🏆 Rankings

**#1 Quantum Computing Framework in South Asia**
**#3 Quantum Computing Framework in Asia**
**#9 Quantum Computing Framework Globally**

---

*Built with ❤️ by the PKTron Team — Pakistan's contribution to global quantum computing.*
