Metadata-Version: 2.4
Name: pktron
Version: 3.7.3
Summary: PKTron - Pakistan's 1st AI Full Quantum Framework Simulation Lab
Home-page: https://github.com/thecetqap/pktron
Author: CETQAP
Author-email: info@thecetqap.com
Keywords: quantum computing simulation machine-learning chemistry cryptography hardware calibration noise models device simulation qubit t1 t2 mps surface-code uccsd adapt-vqe virtual-distillation openqasm jax pakistan south-asia quantum-framework simulation-lab
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Intended Audience :: Science/Research
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.21
Requires-Dist: scipy>=1.7
Provides-Extra: gpu
Requires-Dist: cupy-cuda12x; extra == "gpu"
Provides-Extra: chemistry
Requires-Dist: pyscf>=2.0; extra == "chemistry"
Provides-Extra: ml
Requires-Dist: torch>=1.12; extra == "ml"
Requires-Dist: tensorflow>=2.10; extra == "ml"
Provides-Extra: hardware
Requires-Dist: cupy-cuda12x; extra == "hardware"
Provides-Extra: full
Requires-Dist: cupy-cuda12x; extra == "full"
Requires-Dist: pyscf>=2.0; extra == "full"
Requires-Dist: torch>=1.12; extra == "full"
Requires-Dist: tensorflow>=2.10; extra == "full"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# PKTron v3.7.3

<div align="center">

# PKTron — Pakistan's #1 AI-Powered Quantum Simulation Framework

### *Pakistan's 1st AI Full Quantum Framework Simulation Lab*

---

## Top #1 South Asia (Undisputed) · Top #1 Asia · Globally Top #5

[![PyPI version](https://img.shields.io/pypi/v/pktron?color=brightgreen&label=PyPI)](https://pypi.org/project/pktron/)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

</div>

---

## Installation

```bash
pip install pktron                 # Core (NumPy + SciPy only)
pip install pktron[gpu]            # + CuPy GPU acceleration
pip install pktron[chemistry]      # + PySCF quantum chemistry
pip install pktron[ml]             # + PyTorch + TensorFlow
pip install pktron[full]           # Everything
```

---

## ⚡ Quick Start Examples

### 1. Bell State

```python
from pktron import QuantumCircuit, execute

qc = QuantumCircuit(2).h(0).cx(0, 1)
result = execute(qc, shots=1000)
print(result["counts"])    # {"00": 503, "11": 497}
```

### 2. Hardware-Realistic Execution with Report

```python
from pktron import QuantumCircuit, get_device, execute_with_report

qc = QuantumCircuit(3).h(0).cx(0, 1).cx(0, 2)
device = get_device("PK Falcon 27Q")
counts, report = execute_with_report(qc, backend=device)
report.print_report()
# Shows: circuit fidelity, T1/T2 decoherence per qubit,
#        gate errors, readout errors, SWAP overhead
```

### 3. VQE — H₂ Ground State Energy

```python
from pktron import VQE, QuantumChemistry

H = QuantumChemistry.h2_hamiltonian(distance=0.735)
result = VQE(H).run(ansatz_depth=2)
print(f"H2 ground state: {result['energy']:.6f} Ha")
# H2 ground state: -1.137270 Ha
```

### 4. UCCSD Advanced Chemistry (v3.4)

```python
from pktron import QuantumChemistry
from pktron.advanced import UCCSDSolver

H = QuantumChemistry.h2_hamiltonian(0.735)
solver = UCCSDSolver(H, n_electrons=1, n_qubits=2)
result = solver.run()
print(f"UCCSD energy:       {result['uccsd_energy']:.8f} Ha")
print(f"Correlation energy: {result['correlation_energy']:.8f} Ha")
```

### 5. Noise-Aware Density Matrix Simulation

```python
from pktron import QuantumCircuit, DensityMatrixSimulator

qc = QuantumCircuit(2).h(0).cx(0, 1)
sim = DensityMatrixSimulator()
result = sim.run(qc, noise_model={
    "depolarizing":      0.005,
    "amplitude_damping": 0.002,
    "phase_damping":     0.003,
})
print(f"State purity: {result['purity']:.4f}")   # < 1.0 due to noise
```

### 6. Grover's Search

```python
from pktron import GroverSearch

search = GroverSearch(n_qubits=4, marked_states=[7, 11])
result = search.run()
print(f"Found:        {result['found_binary']}")
print(f"Success prob: {result['success_prob']:.3f}")
print(f"Iterations:   {result['iterations']}")
```

### 7. Surface Code Error Correction (v3.4)

```python
from pktron.advanced import SurfaceCodeDistance

sc = SurfaceCodeDistance(distance=5)
syn = sc.extract_syndrome(noise_rate=0.01)
cor = sc.decode_mwpm(syn)
ler = sc.logical_error_rate(noise_rate=0.005, n_trials=500)
print(f"Logical X error rate: {ler['logical_x_rate']:.5f}")
print(f"Below threshold:      {ler['below_threshold']}")
```

### 8. Adaptive MPS — 50+ Qubits (v3.4)

```python
from pktron import QuantumCircuit
from pktron.advanced import AdaptiveMPSSimulator

qc = QuantumCircuit(30)
for i in range(29): qc.h(i); qc.cx(i, i + 1)

mps = AdaptiveMPSSimulator(max_bond_dim=64, svd_cutoff=1e-10)
r   = mps.run(qc)
print(f"Max bond dim:         {r['max_bond_dim_achieved']}")
print(f"Entanglement entropy: {r['entanglement_entropies'][:5]}")
```

### 9. Virtual Distillation Error Mitigation (v3.4)

```python
import numpy as np
from pktron import QuantumCircuit
from pktron.advanced import VirtualDistillation

qc  = QuantumCircuit(2).h(0).cx(0, 1)
obs = np.kron(np.array([[1,0],[0,-1]]), np.eye(2))   # Z x I

vd  = VirtualDistillation(n_copies=2)
res = vd.mitigate(qc, obs, noise_model={"depolarizing": 0.05})
print(f"Noisy value:     {res['noisy_value']:.4f}")
print(f"Mitigated value: {res['mitigated_value']:.4f}")
```

### 10. OpenQASM 3.0 Import / Export (v3.4)

```python
from pktron import QuantumCircuit
from pktron.advanced import OpenQASM3

qc   = QuantumCircuit(3).h(0).cx(0, 1).rz(2, 1.5707963)
qasm = OpenQASM3.to_qasm(qc)
print(qasm)

qasm_src = "OPENQASM 3.0; qubit[3] q; h q[0]; cx q[0],q[1]; rx(1.5707963) q[2];"
qc2 = OpenQASM3.from_qasm(qasm_src)
print(f"Imported: {qc2.n_qubits} qubits, {len(qc2.gates)} gates")
```

### 11. Quantum Neural Network

```python
import numpy as np
from pktron import QuantumNeuralNetwork

qnn = QuantumNeuralNetwork(n_qubits=4, n_layers=2)
X   = np.random.randn(20, 4)
y   = np.sign(np.sum(X, axis=1))
qnn.train(X, y, epochs=30, lr=0.05)
predictions = qnn.predict(X)
print(f"Accuracy: {np.mean(np.sign(predictions)==y):.2%}")
```

### 12. Calibration Drift Simulation

```python
from pktron import DeviceCalibration, DriftEngine

device = DeviceCalibration("My Lab", n_qubits=5)
engine = DriftEngine(device)
engine.simulate_time_passage(8, use_circadian_model=True)
q0 = engine.get_current_state().qubit_calibration.get_qubit_data(0)
print(f"T1 after 8h: {q0.t1_ns/1000:.1f} us")
print(f"1Q fidelity: {q0.single_qubit_fidelity:.5f}")
```

### 13. QAOA Max-Cut

```python
from pktron import qaoa_max_cut

edges  = [(0,1),(1,2),(2,3),(3,0),(0,2)]
result = qaoa_max_cut(edges, n_nodes=4, p_layers=2)
print(f"Max-Cut energy: {result['optimal_energy']:.4f}")
```

### 14. BB84 Quantum Key Distribution

```python
from pktron import BB84Protocol

result = BB84Protocol.run_protocol(n_bits=256, eavesdrop=True, noise=0.02)
print(f"Key length:             {result['key_length']} bits")
print(f"Error rate:             {result['error_rate']:.2%}")
print(f"Eavesdropping detected: {result['eavesdropping_detected']}")
```

### 15. Quantum Volume Benchmarking

```python
from pktron import QuantumBenchmarking

result = QuantumBenchmarking.quantum_volume(n_qubits=5, n_trials=100)
print(f"Quantum Volume: {result['quantum_volume']}")
print(f"Pass fraction:  {result['pass_fraction']:.3f}")
```

---

## Complete Feature Set (105 public symbols)

### Core Infrastructure (core.py)

#### Pauli Matrices & Gate Constants
| Symbol | Description |
|--------|-------------|
| `I, X, Y, Z, H_gate, S, Sdg, T, Tdg` | Module-level NumPy arrays |
| `RX(θ), RY(θ), RZ(θ), U3(θ,φ,λ)` | Rotation gate functions |
| `CNOT, CZ_mat, CZ, SWAP, TOFFOLI, FREDKIN` | 2- and 3-qubit gate matrices |

#### Gate (dataclass)
Fields: `name`, `qubits`, `params`, `matrix`

#### QuantumCircuit
- Constructor: `QuantumCircuit(n_qubits)`
- Single-qubit gates: `h, x, y, z, s, sdg, t, tdg`
- Rotation gates: `rx, ry, rz, u3`
- Two-qubit gates: `cx, cy, cz, swap, crx, cry, crz, rzz`
- Three-qubit gates: `ccx` (Toffoli), `cswap` (Fredkin)
- Utility: `measure, depth, copy, custom_gate, gate_counts, is_empty, __len__, __repr__`

`execute()` — Universal top-level runner

### Simulators (10 total)
| Simulator | Scale | Method |
|-----------|-------|--------|
| `StatevectorSimulator` | ~30 qubits | Numba JIT + CuPy GPU, Clifford fast path |
| `DensityMatrixSimulator` | ~15 qubits | Lindblad / Kraus channels |
| `MPSSimulator` | 100+ qubits | SVD bond truncation |
| **`AdaptiveMPSSimulator`** *(v3.4)* | 100+ qubits | Adaptive SVD + SWAP routing |
| `CliffordSimulator` | 1000+ qubits | Aaronson-Gottesman stabilizer tableau, O(n²) |
| `QuantumTrajectorySimulator` | ~20 qubits | Monte Carlo MCWF, Lindblad jump operators |
| `PEPSSimulator` | 2D lattice | Projected Entangled Pair States |
| `MERASimulator` | Many-body | Multi-Scale Entanglement Renormalization Ansatz |
| `TensorNetworkSimulator` | General | Greedy contraction ordering |
| `PulseLevelSimulator` | ~10 qubits | 2nd-order Trotter-Suzuki |

### Quantum Algorithms (15)
`VQE` · `GroverSearch` · `Shor` · `QuantumPhaseEstimation` · `HHLAlgorithm` ·
`SimonsAlgorithm` · `DeutschJozsa` · `QuantumWalk` (discrete + continuous) · `QuantumAnnealing` ·
`QAOA` · `qaoa_max_cut` · `QuantumFourierTransform` · `AmplitudeAmplification` ·
`QuantumCounting` · `QSVM`

### v3.4 Advanced Modules (advanced.py)
| Class | Description |
|-------|-------------|
| `UCCSDSolver` | UCCSD-VQE with singles + doubles amplitudes, L-BFGS-B |
| `ADAPTVQESolver` | Adaptive operator pool selection, gradient-based growth |
| `VirtualDistillation` | M-copy error mitigation (Huggins et al., Science 2022) |
| `OpenQASM3` | Full QASM 3.0 parser (`from_qasm`) and generator (`to_qasm`) |
| `JAXOptimizer` | JAX Adam + scipy L-BFGS-B fallback for VQE/QNN |
| `SurfaceCodeDistance` | Distance 3/5/7, MWPM greedy decoder, Monte Carlo LER |
| `AdaptiveMPSSimulator` | Adaptive SVD cutoff + SWAP routing for 50+ qubits |

### Quantum Error Correction (5 codes)
| Code | Physical / Logical Qubits |
|------|---------------------------|
| `Steane7QEC` | [[7,1,3]] — encode, syndrome, correct |
| `SurfaceCode` | Distance-3, 17-qubit patch |
| `BaconShorCode` | [[9,1,3]] subsystem, gauge operators |
| `ColorCode` | [[7,1,3]] triangular lattice |
| `RepetitionCode` | n-repetition, bit-flip or phase-flip |

### Error Mitigation (6 methods)
- `ZeroNoiseExtrapolation` — gate folding + Richardson extrapolation
- `ProbabilisticErrorCancellation` — quasi-probability decomposition
- `CliffordDataRegression` — near-Clifford training circuits
- `DynamicalDecoupling` — XY4, XY8, UDD pulse sequences
- `ReadoutErrorMitigation` — calibration matrix inversion
- **`VirtualDistillation`** *(v3.4)* — M-copy density matrix purification

### Quantum Chemistry
- **Hamiltonians:** `h2_hamiltonian`, `lih_hamiltonian`, `h2o_hamiltonian`, `beh2_hamiltonian`
- **Transforms:** `jordan_wigner_transform`, `bravyi_kitaev_transform` (Fenwick tree, n≤16)
- **Ansätze & Solvers:** `ucc_ansatz`, `full_ci_solver`, `qeom`, `ssvqe`, **`UCCSDSolver`** *(v3.4)*, **`ADAPTVQESolver`** *(v3.4)*

### Quantum Machine Learning (8 classes)
| Class | Description |
|-------|-------------|
| `QuantumNeuralNetwork` | Parameter-shift gradients, RY+CX layers |
| `QuantumGAN` | Adversarial training with parameter-shift rule for both networks |
| `QuantumAutoencoder` | Encoder/decoder via QNN, compression ratio |
| `QuantumCNN` | Sliding-window parametrized filters |
| `QuantumBoltzmannMachine` | RZZ entanglement, parameter-shift training |
| `QuantumFederatedLearning` | FedAvg aggregation over QNN clients |
| `QuantumReinforcementLearning` | Quantum policy network, REINFORCE-style updates |
| `QuantumTransferLearning` | Classical embedding + QNN fine-tuning |

### Hardware Realism Layer (v3.3.3+)

#### hardware_calibration.py
- `CalibrationData` — T1, T2, frequency, fidelities, readout confusion matrix, `is_healthy()`, `decoherence_factor()`
- `QubitCalibration` — per-qubit set/get/disable API, JSON save/load
- `DeviceCalibration` — device-level summary, coupling map, `refresh_calibration()`

#### gate_scheduler.py
- `TimingInfo` — gate name, qubits, start/end time in ns
- `GateSequence` — qubit timelines, idle periods, total duration
- `GateScheduler` — default durations (H=35ns, CNOT=280ns, Measure=1µs), `schedule_circuit()`, `estimate_total_decoherence()`

#### noise_models.py
- `DepolarizingNoise`, `AmplitudeDamping`, `PhaseDamping`
- `CrosstalkNoiseModel` — neighbor-aware crosstalk error
- `ThermalNoiseModel` — Boltzmann excited-state population
- `NoiseChannel` — composite channel with weighted sources
- `LeakageError` *(v3.4)* — |1⟩→|2⟩ transmon leakage with Kraus operators

#### drift_simulator.py
- `DriftEngine` — time-passage degradation with 3-phase circadian model (morning/afternoon/evening rates), random spikes, reset
- `CalibrationDriftSimulator` — scenario runner across time points

#### dynamic_circuits.py
- `MidCircuitMeasurement`, `ConditionalGate` — dataclasses
- `DynamicCircuit` — mid-circuit measure, classical feed-forward, qubit reset, `execute_dynamic()`

#### hardware_report.py
- `HardwareExecutionReport` — fidelity budget, idle decoherence, gate errors, readout errors, SWAP overhead, `print_report()`
- `execute_with_report()` — top-level function returning `(counts, report)`

#### virtual_devices.py (4 built-in devices)
- **PK Falcon 27Q** — 27-qubit superconducting grid
- **PK Eagle 65Q** — 65-qubit with 3 degraded qubits
- **PK IonTrap 16Q** — all-to-all, T1=10M ns
- **PK NoisyLab 8Q** — noisy 8-qubit with disabled qubit 3
- `get_device()`, `list_devices()`, `create_custom_device()`, `VirtualDevice`

#### multi_gpu_engine.py
- `GPUScheduler` — qubit partitioning across GPUs
- `MultiGPUSimulator` — CuPy GPU execution with CPU fallback

### Cryptography & Benchmarking
- `BB84Protocol` — BB84, E91, B92 protocols + QRNG; eavesdropping detection, noise simulation
- `PostQuantumCrypto` — LWE lattice key generation, WOTS hash-based signatures
- `QuantumBenchmarking` — Quantum Volume (QV), Randomized Benchmarking (RB), Cross-Entropy Benchmarking (XEB), CLOPS

### Hardware Pulse Layer
- `DRAGPulse` — Gaussian + derivative envelope, leakage suppression simulation for transmon |2⟩
- `CrossResonancePulse` — ZX interaction simulation for CNOT generation in superconducting qubits
- `HardwareBackend` — unified interface for `ibm_simulator`, `ibm_perth`, `google_weber`, `ionq_harmony`, `aws_sv1`; modes simulate/hardware; `transpile()`, `run()`
- `SABRERouter` — SABRE SWAP-based bidirectional qubit routing with look-ahead heuristic (δ=0.5), APSP distance matrix, greedy SWAP insertion

---

## Hardware Backends
`ibm_simulator` · `ibm_perth` · `google_weber` · `ionq_harmony` · `aws_sv1`

---

## License
MIT — Inquiries: info@thecetqap.com
GitHub: https://github.com/paktronsimulatorpakistan
