Metadata-Version: 2.4
Name: pktron
Version: 12.0.0
Summary: PkTron Quantum HPC, QML, SDK & Non-Equilibrium Metrics with the NEF (Noise & Error Free) Framework Simulator — Top #1 in Asia and South Asia, Top 5 Globally (Based on Features, Modules and Breadth)
Home-page: https://github.com/paktronsimulatorpakistan
Author: CETQAC
Author-email: info@thecetqap.com
License: MIT
Project-URL: Bug Tracker, https://github.com/paktronsimulatorpakistan/issues
Project-URL: Source, https://github.com/paktronsimulatorpakistan
Keywords: quantum,computing,simulation,HPC,SDK,VQE,QAOA,Grover,Shor,quantum-machine-learning,quantum-chemistry,quantum-error-correction,quantum-cryptography,QKD,quantum-finance,tensor-network,MPS,DMRG,surface-code,GPU,pktron
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
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: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20
Requires-Dist: scipy>=1.7
Provides-Extra: gpu
Requires-Dist: cupy-cuda12x>=11.0; extra == "gpu"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=0.10; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# PkTron Quantum HPC, QML, SDK, & Quantifiable Non-Equilibrium Metrics with The NEF (Noise & Error Free) Framework Simulator

### Top #1 in Asia and South Asia, Top 5 Globally (Based on Features, Modules and Breadth)

![Python](https://img.shields.io/badge/python-3.8%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![HPC](https://img.shields.io/badge/HPC-AVX--512%20%7C%20OpenMP%20%7C%20GPU-orange)
![SDK](https://img.shields.io/badge/SDK-Estimator%20%7C%20Sampler%20%7C%20Primitives-purple)
![Version](https://img.shields.io/badge/version-10.0.9-brightgreen)

**PKTron** is a full-stack quantum computing framework: a high-performance simulator, a quantum machine-learning toolkit, a hardware-aware SDK, and — new in v9.0.0 — two independent research systems: the **Non-Equilibrium (NEQ)** post-Born-rule metrics engine and the **NEF (Noise & Error Free)** five-layer mitigation framework. It ships **180+ public classes**, **60+ functions**, a compiled C statevector kernel (AVX-512/AVX2/OpenMP), optional GPU and MPI backends, and broad interoperability with Qiskit, Cirq, PennyLane, QASM3, Quil, IonQ and Braket.

Developed and maintained by **CETQAC — Centre of Excellence for Technology, Quantum and AI (Pakistan / Canada).**

```bash
pip install pktron            # core (numpy + scipy only)
pip install pktron[gpu]       # + CuPy GPU acceleration
pip install pktron[dev]       # + pytest, build, twine
```

```python
import pktron as pk

qc = pk.QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
result = pk.execute(qc, shots=1024)
print(result)            # Bell-state counts: ~50% '00', ~50% '11'
```

---

## Sample Circuits — Copy, Paste, Run

Every snippet below runs against the public `pktron` API exactly as installed from PyPI.

### 1. Bell state + measurement

```python
import pktron as pk

qc = pk.QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
counts = pk.execute(qc, shots=2048)
print(counts)
```

### 2. GHZ state (3 qubits)

```python
import pktron as pk

ghz = pk.QuantumCircuit(3)
ghz.h(0)
ghz.cx(0, 1)
ghz.cx(0, 2)
print(ghz.draw())                       # ASCII circuit diagram
sv = pk.StatevectorSimulator().run(ghz, shots=0)['statevector']
print("amplitudes:", sv)
```

### 3. VQE — ground-state energy

```python
import numpy as np, pktron as pk

H = np.array([[1, 0], [0, -1]], dtype=complex)   # single-qubit Z
res = pk.VQE(H).run(n_qubits=1)
print("ground-state energy:", res["energy"])      # → -1.0
```

### 4. Grover search

```python
import pktron as pk

grover = pk.GroverSearch(n_qubits=3, marked=[5])
res = grover.run()
print("found marked state:", res["found"])         # → 5
```

### 5. Zero-Noise Extrapolation (error mitigation)

```python
import numpy as np, pktron as pk

qc = pk.QuantumCircuit(3); qc.h(0); qc.cx(0, 1); qc.cx(0, 2)
obs = np.kron(np.array([[1, 0], [0, -1]]), np.eye(4))   # Z on qubit 0
executor = lambda c: pk.StatevectorSimulator().run(c, shots=0)
res = pk.ZeroNoiseExtrapolation().run(qc, executor, obs)
print("zero-noise value:", res["zero_noise_value"])
```

### 6. System I — Non-Equilibrium Mode (NEQ)  ★ new in v9.0.0

A post-Born-rule simulation engine. At coherence parameter `gamma = 0` it **recovers the exact Born rule**; as `gamma` grows it produces a controlled, fully quantified deviation.

```python
import pktron as pk

ghz = pk.QuantumCircuit(3); ghz.h(0); ghz.cx(0, 1); ghz.cx(1, 2)

# Born recovery at gamma = 0
born = pk.NEQSimulator(pk.CoherenceWeighter("exponential", gamma=0.0)).run(ghz)
print("delta_neq (should be ~0):", born.delta_neq)
print("is Born-equivalent:", born.is_born_equivalent())

# Quantified non-equilibrium deviation at gamma = 0.5
neq = pk.NEQSimulator(pk.CoherenceWeighter("exponential", gamma=0.5)).run(ghz)
print("P_neq:", neq.p_neq)               # normalised post-Born distribution
print("delta_neq (TVD):", neq.delta_neq)
print("KL forward / reverse:", neq.kl_forward, neq.kl_reverse)
print("Hellinger:", neq.hellinger)
print("partition Z:", neq.partition_Z)

# Sweep gamma and analyse
scan = pk.NEQSimulator().scan_gamma(ghz, [0.0, 0.25, 0.5, 1.0])
print("delta_neq vs gamma:", [round(r.delta_neq, 4) for r in scan])

# Export full metrics as JSON
print(pk.DeviationAnalyzer(neq).export("json"))
```

### 7. System II — NEF (Noise & Error Free) Framework  ★ new in v9.0.0

An orchestrated five-layer mitigation pipeline — **DD → ZNE → PEC → CDR → Symmetry Verification** — that returns a fully itemised error budget.

```python
import numpy as np, pktron as pk

qc = pk.QuantumCircuit(2); qc.h(0); qc.cx(0, 1)
observable = np.kron(np.diag([1, -1]), np.eye(2))     # Z on qubit 0

# Run the full five-layer pipeline
result = pk.NoiseNullifier().run(qc, observable)
print("raw value:       ", result.raw_value)
print("mitigated value: ", result.mitigated_value)
print("layers applied:  ", result.layers_applied)     # ['dd','zne','pec','cdr','sv']
print("error budget:    ", result.error_budget)

# Configure / disable individual layers
cfg = pk.NEFConfig(enable_pec=False, enable_sv=False, dd_sequence="xy8")
print(pk.NoiseNullifier(cfg).run(qc, observable).layers_applied)   # ['dd','zne','cdr']

# Richardson extrapolation primitive (coefficients sum to 1)
rich = pk.RichardsonExtrapolator([1, 2, 3])
print("coefficients:", rich.coefficients)              # [3, -3, 1]

# Benchmark mitigated vs raw over several trials
print(pk.NoiseNullifier().benchmark(qc, observable, n_trials=5))
```

### 8. Compose both new systems on one circuit

```python
import numpy as np, pktron as pk

qc = pk.QuantumCircuit(3); qc.h(0); qc.cx(0, 1); qc.cx(0, 2)
obs = np.kron(np.array([[1, 0], [0, -1]]), np.eye(4))

neq = pk.NEQSimulator(pk.CoherenceWeighter("exponential", gamma=1.0)).run(qc)
nef = pk.NoiseNullifier().run(qc, obs)
print("NEQ partition Z:", neq.partition_Z)
print("NEF mitigated  :", nef.mitigated_value)
```

---

## Complete Feature & Module Reference

### Version history shipped in this release
`v4.0.0 → v4.0.4 → v5.0.1 → v6.0.0 → v6.1.6 → v7.0.0 → v8.0.0 → v8.0.1 → v9.0.0 → v9.0.6 → v10.0.8 → v10.0.9`

### Core module — `pktron/core.py`

**Simulators:** `StatevectorSimulator` (Clifford fast-path, auto-MPS routing, GPU fallback), `DensityMatrixSimulator`, `MPSSimulator`, `CliffordSimulator`, `UnitarySimulator`, `ExtendedStabilizerSimulator`, `SuperOpSimulator`.

**Circuit & execution:** `QuantumCircuit` (with `draw()`, `depth()`, all gate methods), `execute()`, `Gate`.

**Algorithms:** `VQE`, `GroverSearch`, `Shor`, `QuantumPhaseEstimation`, `HHLAlgorithm`, `SimonsAlgorithm`, `DeutschJozsa`, `QuantumWalk`, `QuantumAnnealing`.

**QML:** `QuantumNeuralNetwork`, `QuantumGAN`, `QuantumAutoencoder`, `QuantumCNN`, `QuantumBoltzmannMachine`, `QuantumFederatedLearning`, `QuantumTransferLearning`.

**Error correction:** `Steane7QEC`, `SurfaceCode` (arbitrary odd d ≥ 3), `ProbabilisticErrorCancellation`.

**Error mitigation:** `ZeroNoiseExtrapolation`, `ReadoutErrorMitigation`.

**Compilation & routing:** `SABRERouter`, `DynamicalDecoupling`.

**Chemistry & physics:** `QuantumChemistry` (H2, N2, CH4, CO2, NH3, C2H4).

**Cryptography:** `BB84Protocol`, `PostQuantumCrypto`.

**Benchmarking & noise:** `QuantumBenchmarking`, `NoiseModel`, `PauliError`.

### Additional modules (29 files)

- **`matchgate_sim.py`** — `MatchgateSimulator` (Gaussian fermionic / covariance-matrix simulation, O(n³)).
- **`dmrg.py`** — `DMRGSolver` (2-site DMRG for 1D Hamiltonians with MPO).
- **`fermionic_gaussian.py`** — `FermionicGaussianSimulator` (free-fermion quadratic Hamiltonians).
- **`qkd_pipeline.py`** — `QKDPipeline` (BB84, E91, B92, TwinField, MDI, DIQKD; sifting, privacy amplification; eavesdrop strategies; fiber-loss model).
- **`barren_plateau.py`** — `BarrenPlateauAnalyzer`.
- **`noise_aware_compile.py`** — `NoiseAwareCompiler`.
- **`qsvt.py`** — `QSVT`, `QSPAngleFinder`, `BlockEncoding`, `LinearCombinationBlockEncoding`.
- **`circuit_debugger.py`** — `QuantumCircuitDebugger` (gate-by-gate step-through).
- **`advanced_qml.py`** — `BarrenPlateauFreeQNN`, `QuantumKernelTrainer`, `QuantumMAML`, `ShotFrugalOptimizer`, `EstimatorQNN`, `SamplerQNN`.
- **`advanced_mitigation.py`** — `SymmetryVerification`, `ErrorAmplification`, `PauliNoiselearner`.
- **`advanced_crypto.py`** — `QuantumSecretSharing`, `BlindQuantumComputing`, `QuantumDigitalSignature`, `QuantumMoney`.
- **`advanced_algorithms.py`** — `QuantumMetropolis`, `LCU`, `QuantumSDP`, `AdiabaticOptimizer`, `PhaseKickback`.
- **`new_algorithms.py`** — `QuantumWalkSearch`, `VQITE`, `GRAPE`, `ParallelTemperingAnnealing`, `QuantumNAS`, `QuantumErrorLearning`.
- **`interop.py`** — `InteropConverter` (import Qiskit/Cirq/PennyLane; export QASM3/Quil/IonQ/Braket).
- **`config.py`** — `PKTronConfig`. **`validation.py`** — `QuantumStateValidator`. **`profiling.py`** — `PerformanceMonitor`.
- **`hardware_calibration.py`** — `CalibrationData`, `DeviceCalibration`. **`gate_scheduler.py`** — `GateSequence`, `TimingInfo`.
- **`noise_models.py`** — `NoiseModel` (ABC), `DepolarizingNoise`, `AmplitudeDamping`, `PhaseDamping`, `KrausChannel`, `NoiseModelBuilder`.
- **`drift_simulator.py`** — `DriftEngine`. **`dynamic_circuits.py`** — `DynamicCircuit`, `MidCircuitMeasurement`, `ConditionalGate`.
- **`hardware_report.py`** — `HardwareExecutionReport`. **`virtual_devices.py`** — `VirtualDevice`.
- **`multi_gpu_engine.py`** — `GPUScheduler`, `MultiGPUSimulator`.
- **`advanced.py`** — `UCCSDSolver`, `ADAPTVQESolver`, `VirtualDistillation`, `OpenQASM3Compiler`, `JAXOptimizer`, `AdaptiveMPSSimulator`, `SurfaceCodeDistance`.

### Transpiler / pass manager
`CouplingMap`, `TranspilerPass` (ABC), `BasicDecomposition`, `NoiseAdaptiveRouting`, `GateCancellation`, `PassManager`.

### Gradients / autodiff — `pktron/gradients.py`
`ParameterShiftGradient`, `QuantumNaturalGradient`, `SPSAOptimizer`, `make_gradient()`.

### ML framework integration
`TorchLayer`, `KerasLayer`, `JAXLayer`, `QNNCircuit`, `EstimatorQNN`, `SamplerQNN`.

### Primitives / runtime layer
`Estimator`, `Sampler`, `StatevectorEstimator`, `StatevectorSampler`, `NoisyEstimator`, `Session`, `Job`, `PrimitiveResult`.

### Observables / Pauli framework — `pktron/pauli.py`
`Pauli`, `PauliList`, `SparsePauliOp`, `PauliTerm`, `PauliSum`, `pauli_basis(n)`, `commutator()`, `anti_commutator()`.

### Chemistry expansion
`Molecule`, `ElectronicStructureProblem`, `HartreeFockInitialPoint`, `ActiveSpaceTransformer`, `FreezeCoreTransformer`, `Z2Symmetries`, `ParityMapper`, `BravyiKitaev`, `kUpCCGSD`, `PUCCD`, `SUCCD`, `EvolvedOperatorAnsatz`.

### Error-correction expansion
`SurfaceCode(distance=d)`, `BlossomVDecoder`, `PyMatchingDecoder`, `FaultTolerantCircuit`, `ColorCode(distance=d)`, `HeavyHexCode`, `ThresholdEstimator`.

### Error-mitigation expansion
`fold_gates_at_random()`, `fold_gates_from_left()`, `fold_global()`, `RichardsonExtrapolation(order)`, `ExponentialExtrapolation`, `PolyExpExtrapolation`.

### Pulse level
`PulseSchedule`, `DriveChannel`, `ControlChannel`, `MeasureChannel`, `GaussianPulse`, `DRAGPulse`, `ConstantPulse`, `GaussianSquarePulse`, `PulseSimulator`.

### Benchmarking expansion
`StandardRB`, `InterleavedRB`, `MirrorRB`, `XEB`, `CLOPS`, `ProcessTomography`, `StateTomography`, `GateTomography`.

### Interoperability
`QASM2Codec`, `QASM3Parser`, `QuilExporter`, `QiskitImporter`, `CirqImporter`, `PennyLaneImporter`, `IonQExporter`, `BraketExporter`, `QPYCodec`.

### Circuit construction & visualization
`RXGate`, `RYGate`, `RZGate`, `U3Gate`, `CCXGate`, `C3XGate`, `QuantumRegister`, `ClassicalRegister`, `InstructionSet`, `CircuitInstruction`; `CircuitDrawer` with `.draw(mode='text'|'unicode'|'mpl', ...)`.

### Decomposition — `pktron/decompose.py`
`euler_zyz()`, `kak_decompose()`, `HardwareBackend` helpers.

### HPC subsystem
- **`kernels/`** — C kernel (`sv_kernels.c`): AVX-512/AVX2/OpenMP gate application, probabilities, sampling, expectation, fusion; `KernelSet`, `load_kernels()`.
- **`scheduler/`** — gate normalization, 1-qubit fusion, Clifford detection; `build_schedule()`, `OpNode`.
- **`runtime/`** — `StatevectorRuntime` (schedule → Clifford/GPU/C-kernel/NumPy fallback).
- **`sparse/`** — `SparseHamiltonian`, `ising_hamiltonian()`, `heisenberg_hamiltonian()`, `from_dense()`, `expectation_pauli()`.
- **`cache/`** — `CircuitCache` (LRU + disk, SHA-256 hash). **`gpu/`** — `GPUBackend` (CuPy). **`distributed/`** — `DistributedSimulator` (MPI). **`benchmarks/`** — full benchmarking harness.

### Finance module — `pktron/finance/core.py`
`QuantumAmplitudeEstimation`, `QuantumPortfolioOptimizer`, `QuantumOptionPricer`, `QuantumCreditRisk`, `OptionsPricing`, `PortfolioOptimizer`, `MonteCarloVaR`, `AnomalyDetection`.

### Defense module — `pktron/defense/core.py`
`QuantumVRP`, `QuantumGameTheory`, `MissionScheduler`, `SwarmOptimizer`, `TargetDetection`, `QuantumCryptanalysis`.

### v7.0.0 modules (23 features)
- **`v7_simulators.py`** — `SparseStatevectorSimulator`, `DynamicCircuitSimulator`, `LindbladSolver`.
- **`v7_algebra.py`** — `SparsePauliOp`, `AdjointDifferentiator`, `NaturalGradient`.
- **`v7_compiler.py`** — `CommutationCancellationPass`, `TemplateOptimizationPass`, `DepthOptimizationPass`, `NativeGateDecomposition`, `QubitRemappingPass`, `optimize_circuit()`, `circuit_unitary()`.
- **`v7_qasm3.py`** — `qasm3_export()`, `qasm3_parse()`.
- **`v7_tomography.py`** — `StateTomography`, `ProcessTomography`, `GateSetTomography`.
- **`v7_mitigation.py`** — `CliffordDataRegression`, `PauliTwirling`, `SymmetryVerification`.
- **`v7_benchmarking.py`** — `RandomizedBenchmarking`, `InterleavedRB`, `SimultaneousRB`, `MirrorBenchmarking`.
- **`v7_noise.py`** — `DeviceNoiseModel`, `fake_ibm_nairobi()`, `CorrelatedCrosstalk`, `thermal_relaxation_kraus()`, `depolarizing_kraus()`.
- **`v7_resources.py`** — `FaultTolerantResourceEstimator`, `TCountOptimizer`.

### v8.0.0 modules (7 features)
`compile.py` → `NoiseAdaptiveTranspiler`; `verify.py` → `CircuitVerifier`; `diff.py` → `AdjointGradient`; `noiselearn.py` → `NoiseCharacterizer`; `resource.py` → `ResourceEstimator`; corrected `finance/` and `defense/` implementations.

### v8.0.1 frontier algorithms (10) — `pktron/algorithms_v801.py`
`QuantumLatticeSieving`, `QuantumMoneyVerifier`, `QuantumCopyProtection`, `IQPSampling`, `QuantumGravityHolographic`, `NonAbelianAnyonSimulator`, `QuantumNPOracle`, `FaultTolerantMetropolisSampling`, `QuantumFullyHomomorphicEncryption`, `CVQKDMetropolitanRouter`.

### v9.0.0 new systems (2)

**System I — Non-Equilibrium Mode — `pktron/neq.py`**
`NEQSimulator` (post-Born-rule engine, exact Born recovery at γ=0), `CoherenceWeighter` (`exponential`/`gaussian`/`polynomial`/`custom` modes), `NEQResult` (`p_neq`, `delta_neq`, `kl_forward`, `kl_reverse`, `hellinger`, `partition_Z`, `is_born_equivalent()`), `DeviationAnalyzer` (`deviation`, `kl_divergence`, `hellinger`, `export`). *Verified:* Born rule recovered exactly at γ=0 (δ_neq < 1e-10); TVD monotone in γ; KL and Hellinger metrics consistent.

**System II — Noise & Error Free Framework — `pktron/nef.py`**
`NoiseNullifier` (orchestrated five-layer pipeline: DD → ZNE → PEC → CDR → SymmetryVerification), `NEFConfig`, `NEFResult` (`raw_value`, `mitigated_value`, `error_budget`, `layers_applied`, `improvement_factor()`), `RichardsonExtrapolator` (coefficients verified to sum to 1), `nef.SymmetryVerification`. *Verified:* Richardson coefficients correct; noiseless circuits return exact expectation; noise suppression demonstrated.

---

## Summary count

| Category | Count |
|---|---|
| Python modules / files | 45+ |
| Public classes | 180+ |
| Public functions | 60+ |
| C-extension functions | 14 |
| QKD protocols | 6 |
| Interop targets | 8 |
| Error-mitigation methods | 12+ |
| Error-correction codes | 6 |
| Benchmarking protocols | 8 |
| Finance algorithms | 8 |
| Defense algorithms | 6 |
| v7 features | 23 |
| v8.0.0 features | 7 |
| v8.0.1 frontier algorithms | 10 |
| v9.0.0 new systems | 2 (NEQ + NEF) |

---

---

## How PKTron Compares (Breadth & Modules)

This comparison is scoped to **feature and module breadth shipped in the framework itself** — not performance, maturity, or hardware access. Marks reflect each framework's current capabilities.

**Legend:** ✅ built-in &nbsp;·&nbsp; ◐ partial / via companion package or extension &nbsp;·&nbsp; ⬜ not available

| Capability | **PKTron** | Qiskit | Cirq | PennyLane | Qulacs | TensorCircuit | TKET | Braket |
|---|---|---|---|---|---|---|---|---|
| Simulator backends (SV/DM/MPS/stabilizer/…) | ✅ 7 types | ✅ | ◐ SV+DM | ◐ SV+DM | ◐ SV+DM | ◐ TN+SV+DM | ◐ ext | ◐ cloud |
| GPU acceleration | ✅ | ✅ | ◐ | ✅ | ✅ | ✅ | ◐ | ◐ cloud |
| MPI / distributed | ✅ | ✅ | ⬜ | ◐ | ◐ | ◐ | ⬜ | ◐ cloud |
| Compiled C/C++ kernel | ✅ AVX-512 | ✅ | ✅ qsim | ✅ Lightning | ✅ | ◐ XLA | ✅ | ◐ |
| Quantum machine learning | ✅ | ✅ | ◐ TFQ | ✅ | ◐ | ✅ | ⬜ | ◐ |
| Quantum chemistry | ✅ | ✅ Nature | ◐ OpenFermion | ✅ qchem | ◐ | ◐ | ◐ | ⬜ |
| Quantum finance | ✅ | ✅ Finance | ⬜ | ⬜ | ⬜ | ⬜ | ⬜ | ⬜ |
| Defense / mission domain modules | ✅ | ⬜ | ⬜ | ⬜ | ⬜ | ⬜ | ⬜ | ⬜ |
| Error-correction codes | ✅ 6 codes | ◐ qec | ◐ | ◐ | ⬜ | ⬜ | ⬜ | ⬜ |
| Error mitigation | ✅ 12+ | ✅ | ◐ | ✅ | ⬜ | ◐ | ◐ | ◐ |
| Transpiler / routing | ✅ | ✅ | ✅ | ✅ | ◐ | ◐ | ✅ best-in-class | ◐ |
| Pulse-level control | ✅ | ✅ | ◐ | ◐ | ⬜ | ⬜ | ⬜ | ✅ |
| Benchmarking (RB/tomography/XEB) | ✅ 8 | ✅ | ◐ | ◐ | ⬜ | ⬜ | ◐ | ⬜ |
| Interop (QASM3/Quil/IonQ/Braket/…) | ✅ 8 targets | ✅ | ◐ | ✅ plugins | ◐ | ◐ | ✅ | ✅ |
| **NEQ — post-Born non-equilibrium metrics** | ✅ | ⬜ | ⬜ | ⬜ | ⬜ | ⬜ | ⬜ | ⬜ |
| **NEF — unified 5-layer mitigation object** | ✅ | ⬜ | ⬜ | ⬜ | ⬜ | ⬜ | ⬜ | ⬜ |
| Everything in one `pip install` | ✅ | ⬜ (split) | ⬜ | ◐ core+plugins | ✅ | ✅ | ◐ | ◐ |

| Context | **PKTron** | Qiskit | Cirq | PennyLane | Qulacs | TensorCircuit | TKET | Braket |
|---|---|---|---|---|---|---|---|---|
| Execution model | Simulation-first | Sim + QPU | Sim + QPU | Sim + QPU | Sim | Sim + cloud | Compiler + QPU | Cloud QPU |
| Maturity | Emerging | Established | Established | Established | Established | Growing | Established | Established |

**Takeaway:** PKTron is the only framework here that ships finance **and** defense domain modules, six error-correction codes, an eight-protocol benchmarking suite, and the **NEQ + NEF** systems — all in a single `pip install`. Qiskit matches PKTron on many rows, but only by combining several separate packages (Aer, Nature, Finance, Experiments); and no other framework provides NEQ post-Born metrics or a unified NEF mitigation object at all. This breadth across simulators, QML, chemistry, finance, defense, error correction, mitigation, and benchmarking is the basis for PKTron's standing on **features, modules, and breadth.**

## What's new in v9.0.6

- **`PkDag` / `TranspileStage`** — a DAG circuit representation (topological
  order, predecessor/successor queries, in-place `substitute`) for writing
  custom transpiler passes without rebuilding the pipeline. Mirrors Qiskit's
  C-API `QkDag` at the *interface* level (pure-Python implementation).
- **`CouplingMap` / `Target`** — device connectivity (BFS distance, neighbours)
  plus a richer hardware target with per-gate error rates, per-qubit T1/T2 and
  readout error, and `Target.from_coupling_map(...)`.
- **`VF2Layout` / `VF2PostLayout`** — VF2-style subgraph-isomorphism layout, and
  a post-routing refinement pass that re-maps to a strictly lower expected-error
  qubit assignment using the `Target` error rates.
- **`GridsynthDecomposer`** — Rz to Clifford+T single-qubit synthesis via a
  bounded-depth Clifford+T search: **exact** for Clifford+T-multiple angles
  (e.g. pi/4 -> T, pi/2 -> S), ~0.10 worst-case operator-norm error otherwise.
  This is a documented simplified stand-in for full number-theoretic
  Ross-Selinger (deferred); every returned sequence's accuracy is verified
  against the ideal Rz.
- **`RuntimeExecutor`** — a job-submission primitive (`.status()` / `.result()`)
  that runs arbitrary user programs against a backend. Distinct from the
  existing `AsyncExecutor` thread-pool task runner.
- **`PauliNoiseLearnerV2`** — incremental noise-model refinement via `.update()`
  (EMA re-fit toward fresh calibration data without discarding the prior model).
- **`QPYCodec` / `FastQPYCodec`** — exact binary circuit serialization, plus a
  dedup-optimized variant that stores repeated gates/sub-circuits once. On
  repetitive workloads this yields a large **payload-size** reduction (measured
  by `benchmark_qpy`, e.g. ~45x smaller on the shipped benchmark); wall-clock is
  comparable, so no speedup is claimed.

*Deferred to 9.1.0:* third-party compiled (C/Rust) extension registration
against a stable C API (Qiskit v2.4-style) — not shipped in 9.0.6.

## What's new in v9.0.0

- **System I — NEQ:** a quantifiable post-Born-rule simulation engine with tunable coherence weighting and full deviation metrics (TVD, forward/reverse KL, Hellinger, partition function), with exact Born recovery at γ=0.
- **System II — NEF:** a configurable five-layer error-mitigation pipeline returning an itemised error budget, sampling overhead, and post-selection rate.
- Both systems are fully wired into the top-level namespace and validated by 20 spec assertions plus an 8-step end-to-end integration test.

## What's new in v10.0.8 — bug-fix release

Six real defects found by rebuilding and re-testing the framework end-to-end were fixed:

1. **`SurfaceCode(distance=d)`** had no constructor at all — the documented
   `SurfaceCode(distance=d)` call silently failed. Now supports `distance=3/5/7`
   and delegates `decode_mwpm()` / `logical_error_rate()` to the working MWPM
   decoder implementation.
2. **`QKDPipeline`** was documented as a top-level import (`pk.QKDPipeline`) but
   was never wired into the package namespace — fixed.
3. **Bloch vector calculation** (`QuantumCircuitDebugger`) used a broken partial
   trace that double-counted coherent cross-terms, producing traces > 1 and
   returning the wrong qubit's vector entirely. Replaced with a correct
   reduced-density-matrix computation (reshape + moveaxis), verified against
   known H and Bell states.
4. **ADAPT-VQE** (`ADAPTVQESolver`) called an internal `_gradient(...)` method
   that never existed — added.
5. **GRAPE** (`QuantumOptimalControl`) existed in the source but was never
   exported at the top level — fixed.
6. **Version strings** were inconsistent across `core.py` / `setup.py` /
   `setup.cfg` / `__init__.py` — unified.

Verification performed before release: 42/42 top-level symbols present,
100/100 shipped modules import cleanly, and 56 real per-feature checks pass
(algorithms, gradients, serialization round-trips, all error-correction codes,
the full transpiler stack, Pauli algebra, chemistry, cryptography, QKD, NEF,
NEQ, finance, and defense) — run against the actual built wheel installed
into a fresh, isolated virtual environment, not just the working directory.

**Known packaging issue in 10.0.8 (fixed in 10.0.9):** the PyPI project page
description rendered empty because the release's README.md was accidentally
left out of the packaging step — the installed package itself was unaffected.

## What's new in v10.0.9 — packaging fix

- Fixes the empty PyPI project-page description from 10.0.8 by including
  README.md correctly in the build.
- No functional/code changes beyond 10.0.8 — the same six bug fixes and the
  same 56-check verification suite apply. If you already have 10.0.8 working,
  upgrading is only necessary to get the PyPI page description; the installed
  package behaves identically.

```bash
pip install --upgrade pktron   # picks up 10.0.9
```



## What's new in v11.0.0

Six additive noise-control features, each validated by an objective
physical/mathematical property check (not just "did it run") before being
wired into the top-level `pktron` namespace. Nothing in `pktron.core` or
`pktron.noise_models` was modified — all six live in the new
`pktron/v11_noise_control.py` module.

- **Non-Markovian (memory-kernel) noise** — `MemoryKernelNoise` /
  `OUNoiseParams` simulate colored dephasing with a bath correlation time
  `tau`, reducing EXACTLY to standard Markovian dephasing at `tau -> 0` and
  showing the correct slower-decay ("motional narrowing") signature at
  finite `tau`.

  ```python
  import pktron as pk

  params = pk.OUNoiseParams(gamma=0.02, tau=25.0, dt=1.0)   # finite tau: non-Markovian
  mk = pk.MemoryKernelNoise(params, seed=1)
  print("predicted coherence decay after 12 gates:",
        mk.predicted_off_diagonal_decay(n_steps=12))

  markov = pk.MemoryKernelNoise(pk.OUNoiseParams(gamma=0.02, tau=0.0), seed=1)
  print("Markovian (tau=0) decay for comparison:",
        markov.predicted_off_diagonal_decay(n_steps=12))
  ```

- **Inverse Kraus synthesis** — `synthesize_from_curve()` solves for a
  CPTP-by-construction (Stinespring-dilation) Kraus channel that reproduces
  an arbitrary target fidelity-decay curve, instead of only the handful of
  textbook channel shapes (depolarizing, amplitude/phase damping).

  ```python
  import numpy as np, pktron as pk

  target = {d: float(np.exp(-0.06 * d)) for d in [0, 2, 4, 6, 8, 10]}
  out = pk.synthesize_from_curve(target, n_kraus=3, seed=42)
  print("CPTP:", out["valid"], "fit error:", out["fit_error"])
  print("achieved curve:", out["achieved_curve"])
  ```

- **Qutrit leakage + Leakage Reduction Unit** — `LeakageChannel` models
  trace-preserving `|1> -> |2>` leakage on a 3-level qutrit;
  `LeakageReductionUnit` pumps leaked population back toward the
  computational subspace at a configurable, realistic efficiency.

  ```python
  import numpy as np, pktron as pk

  rho = np.zeros((3, 3), dtype=complex); rho[1, 1] = 1.0   # start in |1>
  leaked = pk.LeakageChannel(leak_rate=0.3).apply(rho)
  recovered = pk.LeakageReductionUnit(pump_efficiency=0.9).apply(leaked)
  print("leaked |2> pop:", leaked[2, 2].real, "-> after LRU:", recovered[2, 2].real)
  ```

- **Graph-propagated multi-hop crosstalk** — `GraphCrosstalkModel` walks a
  real device coupling-map graph and attenuates crosstalk strength with hop
  distance, going beyond pairwise-only (nearest-neighbor) crosstalk models.

  ```python
  import pktron as pk

  coupling_map = {i: [j for j in (i - 1, i + 1) if 0 <= j <= 5] for i in range(6)}
  model = pk.GraphCrosstalkModel(coupling_map, base_strength=0.05, decay_factor=0.4)
  print("crosstalk reaching each qubit from a gate on qubit 2:", model.propagate(2))
  ```

- **Per-mechanism error-budget reporting** — `ErrorBudgetAnalyzer` breaks
  fidelity loss down by mechanism (coherent, incoherent, crosstalk, leakage,
  readout) and by gate, reporting both the standard additive estimate and
  the exact multiplicative ground truth so you can see the approximation
  error.

  ```python
  import pktron as pk

  entries = [
      pk.GateErrorEntry("H", [0], coherent=0.001, incoherent=0.002),
      pk.GateErrorEntry("CX", [0, 1], coherent=0.003, incoherent=0.005, crosstalk=0.002),
      pk.GateErrorEntry("Measure", [0], readout=0.01),
  ]
  pk.ErrorBudgetAnalyzer(entries).print_report()
  ```

- **Closed-loop adaptive dynamical-decoupling control** — `AdaptiveDDController`
  probes the dominant noise axis each idle window and selects the DD
  sequence (`none` / `cpmg` / `xy4`) with the strongest published
  filter-function suppression against it, beating both "no DD" and any
  fixed single-sequence baseline on time-varying noise.

  ```python
  import pktron as pk

  def probe(window):                      # swap for real calibration data
      return {"X": 0.05, "Y": 0.05, "Z": 0.9} if window % 2 == 0 else {"X": 0.4, "Y": 0.4, "Z": 0.2}

  ctrl = pk.AdaptiveDDController(probe)
  history = ctrl.run(n_windows=6)
  print("sequence chosen per window:", [e["chosen_sequence"].value for e in history])
  ```

All six modules can be dropped straight into pktron's existing noise
pipeline — `MemoryKernelNoise` and `synthesize_from_curve` both expose
their result as Kraus operators, so they attach to a circuit run the same
way any other custom channel does:

```python
import pktron as pk
from pktron.core import DensityMatrixSimulator

qc = pk.QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)

mk = pk.MemoryKernelNoise(pk.OUNoiseParams(gamma=0.01, tau=5.0), seed=7)
kraus = mk.as_kraus_pair(n_steps=4)
result = DensityMatrixSimulator().run(qc, noise_model={"custom_channels": [(0, kraus)]})
```

Verification performed before release: all six modules' self-tests pass
(non-Markovian/Markovian agreement within ~0.15%, CPTP residual ~1e-18,
exact trace conservation through leakage+LRU, strictly-decreasing crosstalk
with hop distance, additive-vs-exact-multiplicative error budget within
first-order tolerance, and adaptive DD beating both fixed-XY4 and no-DD),
plus the full `tests/test_v11_noise_control.py` regression suite and the
existing wheel-verification + fresh-venv smoke test, updated to assert
version `11.0.0` and cover all six new symbols.

*Deferred to a future release (disclosed honestly, not shipped in 11.0.0):*
multi-qubit correlated-error fingerprints for the Kraus synthesizer,
leakage-induced crosstalk to spectator qubits, pluggable per-mechanism
crosstalk strength functions, and wiring the adaptive DD noise probe to
live hardware calibration via `pktron.noiselearn`.

## What's New in v12.0.0

PKTron v12.0.0 adds **CPBN — Computationally Pumped Bath Noise**, a new
additive module (`pktron/cpbn.py`) implementing a stateful computational
environment for noise simulation. `pktron/core.py` and
`pktron/noise_models.py` are unmodified except for the version string;
CPBN plugs into the existing `DensityMatrixSimulator` Kraus-channel
pipeline the same way every other noise source does.

CPBN is a proposed computationally pumped bath noise architecture for
PKTron. History-dependent, non-Markovian, and correlated noise are
established ideas in the literature and are not claimed as new here. What
CPBN contributes is a specific simulator architecture: an explicit,
stateful environmental reservoir whose state (1) is pumped by gate
activity, (2) retains configurable memory, (3) relaxes over time,
(4) optionally propagates spatially between qubits, and (5) feeds back
into the noise applied to later operations — so the same target gate,
reached by a different computational history, can experience different
noise.

```
gate activity → environmental pumping → bath memory/relaxation
    → optional spatial propagation → modified future noise → next gate
```

### Explicit environmental state

```python
from pktron.noise import CPBNConfig, CPBNEnvironment

config = CPBNConfig(
    n_qubits=4,
    baseline_rate=0.002,
    pump_strength=0.8,
    memory=0.95,
    saturation=1.0,
    spatial_decay=0.25,
    dt=1.0,
    seed=42,
)
env = CPBNEnvironment(config)
env.step([0])          # gate activity pumps qubit 0's bath
env.relax(steps=5)      # idle evolution: bath relaxes toward zero
print(env.state)         # inspect current per-qubit bath state
```

### Making CPBN actually affect the simulation

`run_with_cpbn` drives PKTron's `DensityMatrixSimulator`: each gate first
evolves the state unitarily, then pumps the bath, then applies noise
channels (bit-flip / phase-flip / depolarizing) whose probabilities come
from the bath's *current* state — so computational history changes the
simulated output, not just an inspectable side-channel.

```python
from pktron import QuantumCircuit
from pktron.noise import CPBNConfig, CPBNEnvironment
from pktron.cpbn import run_with_cpbn

config = CPBNConfig(n_qubits=4, pump_strength=0.8, memory=0.95,
                     spatial_decay=0.25, seed=7)

qc = QuantumCircuit(4)
qc.x(1); qc.x(2); qc.x(3)   # computational history
qc.x(0)                      # target gate

result = run_with_cpbn(qc, config, shots=1024)
print(result["counts"])
print("final bath state:", result["cpbn_final_state"])
```

### History-order example

Both histories below apply the same multiset of gates in a different
order, then the same target gate on qubit 0 — with `memory > 0` the
resulting bath trajectories (and therefore the noise applied to the
target gate) can differ; with `memory = 0` the historical order effect
disappears, since the bath then only reflects the single most recent step.

```python
history_a = [1, 2, 3, 1, 2, 3]
history_b = [1, 3, 2, 1, 3, 2]
# identical gate counts, different order — see tests/test_cpbn.py
# for the full order-dependence / memory-ablation verification.
```

### Matched hardware investigation (context, not proof)

A matched IBM Quantum experiment was performed as an external hardware
investigation of history-order sensitivity — it is disclosed here for
context, not as validation of the CPBN simulator model:

- Backend: `ibm_marrakesh` (156 qubits), job `damnqlf8gn2s739lni30`
- 100 matched pairs, 400 circuits, 4096 shots, physical depth 6 on both arms
- History A target error: 0.04640625; History B target error: 0.046048583984375
- Mean absolute paired effect: 0.002723388671875 (bootstrap 95% CI
  [0.002314453125, 0.0031396484375])
- Wilcoxon p = 0.2046; sign-test p = 0.4168

The hardware run produced a measurable nonzero absolute paired difference,
but the directional paired tests were not statistically significant at
α = 0.05. This does **not** show that IBM hardware exhibits CPBN — it
shows only that a matched paired-difference protocol was run and what it
found. A valid comparison must use paired statistical tests (Wilcoxon,
sign test, paired bootstrap), not a permutation test built by swapping
labels on absolute paired differences, since a label swap leaves `|A-B|`
unchanged and such a test is not a valid test of anything.

### Physicality

Every probability CPBN produces is clamped to `[0, 1]` before use
(`tests/test_cpbn.py::test_noise_probability_always_in_unit_interval`).
The Kraus channels CPBN drives (`DensityMatrixSimulator.apply_bit_flip`,
`.apply_phase_flip`, `.apply_depolarizing`) are CPTP by construction; a
`pktron.cpbn.is_cptp` helper and a numerical Hermiticity/trace/PSD check
on `run_with_cpbn`'s output density matrix are included in the test
suite. CPBN does not claim every conceivable Kraus set a caller might
supply is automatically CPTP.

### Compatibility

CPBN integrates with `DensityMatrixSimulator` (the density-matrix, Kraus-
channel pathway) directly via `run_with_cpbn`. A `CPBNNoiseModel` adapter
is also provided exposing the same `.apply(state, qubit_id, n_qubits)`
interface as `pktron.noise_models.NoiseModel`, for callers who want to
drive a statevector Monte-Carlo trajectory loop instead. CPBN's bath
model does not currently target `MPSSimulator`, `CliffordSimulator`, or
stabilizer-only backends, since those are not naturally expressed in the
Kraus/density-matrix formalism CPBN currently uses.

### JSON-safety fix

The prior IBM hardware experiment's result-saving step failed because
NumPy scalar/array types (`np.bool_`, `np.int*`, `np.float*`,
`np.ndarray`) are not natively JSON-serializable. `pktron.cpbn` now
ships `to_safe_json` / `safe_json_default`, a reusable serializer that
recursively converts these into native `bool`/`int`/`float`/`list`/`dict`
before `json.dump()`; see `tests/test_cpbn.py` for coverage.

MIT License © CETQAC — Centre of Excellence for Technology, Quantum and AI (Pakistan / Canada).

```
@software{pktron2026,
  title  = {PKTron: Quantum HPC, QML, SDK & Non-Equilibrium Metrics with the NEF Framework},
  author = {CETQAC},
  year   = {2026},
  version = {12.0.0},
  url    = {https://github.com/paktronsimulatorpakistan}
}
```
