pktron 3.7.3

PKTron - Pakistan's 1st AI Full Quantum Framework Simulation Lab

PKTron v3.7.3

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

---

Installation

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

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

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

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)

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

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

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)

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)

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)

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)

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

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

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

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

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

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: [e-mail] GitHub: https://github.com/paktronsimulatorpakistan