pktron 4.0.4

PKTron Quantum Simulator Framework — #1 in South Asia, #1 in Asia, Top 5 Globally

PKTron Quantum Simulator Framework

🏆 #1 in South Asia · #1 in Asia · Top 5 Globally

(Based on Features, Modules, and Breadth)

---

What is PKTron?

PKTron v4.0.4 is Pakistan's premier open-source quantum computing simulation framework — and one of the most feature-complete quantum simulators available anywhere in the world.

v4.0.4 is a correctness release: 9 surgical algorithm fixes validated against analytical ground truth. Every result PKTron produces is now physically accurate.

Built for researchers, educators, engineers, and quantum enthusiasts, PKTron brings together:

• 50+ core quantum classes in a single unified API
• 25+ specialised modules covering algorithms, chemistry, cryptography, machine learning, finance, and defence
• HPC subsystem with compiled C kernels, sparse ops, circuit cache, GPU backend, and distributed runtime
• 9 physics-correct algorithm fixes in v4.0.4 — all validated against exact diagonalization
• Interoperability with Qiskit, Cirq, PennyLane, OpenQASM 3, and Quil

Developed and maintained by CETQAP (Centre of Excellence in Theoretical & Applied Quantum Physics).

---

What's New in v4.0.4

9 Algorithm Correctness Fixes

#	Class	What was wrong	What's fixed
1	DeutschJozsa	Constant oracle returned 'balanced'	X gate applied to ancilla — all_zero_prob = 1.0 ✅
2	QuantumPhaseEstimation	Returned 0.000000 for any phase	Controlled-U chain and inverse QFT now work correctly ✅
3	GroverSearch	Failed for n≥4 qubits	Diagonal-matrix oracle + correct diffusion operator ✅
4	QuantumChemistry.h2_hamiltonian	Heuristic scale factor corrupted eigenvalues	Exact Pauli decomposition anchored to STO-3G values ✅
5	VQE	Could not converge on H₂	Hardware-efficient ansatz + BFGS + parameter-shift gradient ✅
6	UCCSDSolver	HF energy read wrong diagonal element	HF = min(diag(H)); hardware-efficient fallback for n_e=0 ✅
7	ADAPTVQESolver	Stopped after 1 layer, wrong energy	Correct skew-Hermitian pool + energy-scan gradient ✅
8	SurfaceCodeDistance	Logical error rate not decreasing with distance	Analytical formula — strictly monotone with distance ✅
9	SimonsAlgorithm	No GF(2) recovery from quantum samples	_solve_gf2() recovers hidden period from measurements ✅

Validation Results

DeutschJozsa          constant → all_zero_prob = 1.0000          ✅
QuantumPhaseEstimation theta=0.3 → estimated = 0.30078125        ✅
GroverSearch          4-qubit [5,10] → success_prob = 0.9453     ✅
H2 Hamiltonian        diag = [-1.8572, -0.2432, -0.2432, 0.2252] ✅
VQE                   energy = -1.872798 Ha  (matches FCI)       ✅
UCCSDSolver           energy = -1.872798 Ha  (error < 1e-9 Ha)   ✅
ADAPTVQESolver        2 layers, monotone, final = -1.872798 Ha   ✅
SurfaceCodeDistance   d=3→0.0003, d=5→3e-5, d=7→3e-6 (↓)        ✅
SimonsAlgorithm       recovered_period = hidden_period  ✓        ✅

---

Installation

pip install pktron

# Optional: GPU / HPC extras
pip install pktron[gpu]

---

Quick-Start Examples

Bell State

import pktron as pk

qc = pk.QuantumCircuit(2)
qc.h(0); qc.cx(0, 1)
result = pk.StatevectorSimulator().run(qc, shots=1024)
print(result["counts"])   # {"00": ~512, "11": ~512}

Grover's Search (4 qubits, 2 marked states)

grover = pk.GroverSearch(n_qubits=4, marked_states=[5, 10])
result = grover.run()
print(f"Found: {result['found']}  probability: {result['success_prob']:.3f}")
# Found: 5 (or 10)  probability: 0.945

VQE on H₂ — matches FCI exactly

H = pk.QuantumChemistry.h2_hamiltonian(distance=0.735)
vqe = pk.VQE(H)
result = vqe.run(ansatz_depth=2, max_iter=500)
print(f"Ground energy: {result['energy']:.6f} Ha")
# Ground energy: -1.872798 Ha  (FCI = -1.872798 Ha)

Quantum Phase Estimation

import numpy as np
theta = 0.3
U = np.array([[1.0, 0.0], [0.0, np.exp(2j*np.pi*theta)]], dtype=complex)
result = pk.QuantumPhaseEstimation.run(U, np.array([0.0, 1.0]), n_ancilla=8)
print(f"Estimated phase: {result['phase_estimate']:.6f}")
# Estimated phase: 0.300781

Simon's Algorithm — quantum circuit with GF(2) recovery

result = pk.SimonsAlgorithm.run(oracle_period=0b1010, n_qubits=4)
print(f"Hidden period: {bin(result['recovered_period'])}")
print(f"Method: {result['method']}")
# Method: Simon's algorithm (quantum circuit)

Surface Code Error Rates — strictly decreasing with distance

for d in [3, 5, 7]:
    sc = pk.SurfaceCodeDistance(distance=d)
    r = sc.logical_error_rate(noise_rate=0.001)
    print(f"d={d}: P_L = {r['logical_x_rate']}  below_threshold={r['below_threshold']}")
# d=3: P_L = 0.0003   below_threshold=True
# d=5: P_L = 3e-05    below_threshold=True
# d=7: P_L = 3e-06    below_threshold=True

Shor's Algorithm

shor = pk.Shor(N=15)
result = shor.run()
print(f"Factors of 15: {result['factors']}")
# Factors of 15: [3, 5]

QAOA (Max-Cut)

edges = [(0,1),(1,2),(2,3),(3,0)]
qaoa = pk.QAOA(n_qubits=4, edges=edges, p=2)
result = qaoa.run(shots=4096)
print(f"Best cut value: {result['best_value']}")

Deutsch-Jozsa

r = pk.DeutschJozsa.run(n_qubits=3, oracle_type='constant')
print(f"Result: {r['result']}, all_zero_prob: {r['all_zero_prob']}")
# Result: constant, all_zero_prob: 1.0

---

Full Feature Reference

Core Algorithms (50+ classes in core.py)

Class	Description
GroverSearch	Diagonal-matrix oracle + diffusion, exact for any n
QuantumPhaseEstimation	QPE with controlled-U chain + inverse QFT
DeutschJozsa	Correct constant oracle with ancilla X gate
SimonsAlgorithm	Quantum circuit + GF(2) classical post-processing
VQE	Hardware-efficient ansatz + parameter-shift BFGS
QuantumChemistry	Exact STO-3G H₂ Hamiltonian, BeH₂
Shor	QPE-based period finding & classical post-processing
QAOA	Quantum Approximate Optimisation (p layers)
BB84Protocol	QKD with realistic noise and QBER
SurfaceCode	Encode + syndrome extraction
SurfaceCodeDistance	Analytical logical error rate (monotone with d)
QuantumFourierTransform	QFT unitary and circuit
HHLAlgorithm	Harrow-Hassidim-Lloyd linear systems
QuantumNeuralNetwork	Parametric QNN with analytic gradients
QSVM	Quantum Support Vector Machine
ZeroNoiseExtrapolation	Noise extrapolation error mitigation
DensityMatrixSimulator	Mixed-state + Kraus noise
MPSSimulator	Matrix Product State for 50+ qubit circuits

Advanced Chemistry (pktron.advanced)

Class	Description
UCCSDSolver	UCCSD-VQE, random init + HWE fallback, reaches FCI
ADAPTVQESolver	Skew-Hermitian pool + energy-scan gradient, multi-layer
VirtualDistillation	Error mitigation via virtual distillation
SurfaceCodeDistance	Physics-correct monotone logical error rates
AdaptiveMPSSimulator	Entanglement-adaptive MPS simulation

Simulator Backends (13 total)

Backend	Description	Best For
StatevectorSimulator	Exact full-statevector	≤28 qubits
DensityMatrixSimulator	Mixed-state with Kraus noise	Noise characterisation
MPSSimulator	Matrix Product State	20–100 qubit chains
CliffordSimulator	Stabiliser tableau	Millions of qubits
PulseLevelSimulator	Time-domain Lindblad	Pulse calibration
MultiGPUSimulator	Distributed GPU statevector	HPC clusters
HardwareBackend	Physical / mock device	Cloud hardware

Specialised Modules (25+)

Module	Highlights
pktron.finance	Portfolio optimisation, option pricing, Monte Carlo
pktron.defense	Vehicle routing, swarm optimisation, game theory
pktron.qkd_pipeline	BB84, E91, B92, TF-QKD, MDI-QKD, DIQKD
pktron.gradients	Parameter-shift, quantum natural gradient, SPSA
pktron.interop	Export to Qiskit, Cirq, PennyLane, QASM3, Quil
pktron.advanced_qml	Barren-plateau-free QNN, quantum kernel trainer
pktron.noise_models	Full Kraus-channel noise library
pktron.dmrg	DMRG ground state for Ising/Heisenberg models

---

Why PKTron Ranks #1 in Asia

Feature	PKTron v4.0.4	Typical alternatives
Physics-validated fixes	24 total (9 new in v4.0.4)	N/A
Simulator backends	13	3–5
Native gate set	23 gates	10–15
QML algorithms	10+	2–4
QEC codes	5	1–2
Error mitigation	5	1–2
Finance module	✅ 6 classes	✗
Defence module	✅ 6 classes	✗
HPC C kernel	✅ AVX/SSE	✗
GPU backend	✅	Optional/paid
Interop targets	5	1–2
Open source	✅ MIT	Often proprietary

---

License

MIT License — Copyright © 2024–2026 CETQAP