QPyth 0.4.0

QPyth - Qiskit-based quantum toolkit for simulation, education, and research workflows with VQE, IBM Quantum integration, realistic noisy simulation, quantum error correction, quantum teleportation, and optional web UI

QPyth

QPyth is a professionally engineered, physically rigorous quantum computing library built on Qiskit. Moving beyond ideal statevector simulations, QPyth provides canonical implementations of advanced quantum algorithms, including Variational Quantum Eigensolvers (VQE) for multi-electron molecules, robust Quantum Error Correction (QEC) protocols, and seamless IBM Quantum hardware execution. Featuring hardware-calibrated simulation with vendor-neutral backend profiles supporting IBM, IonQ, Rigetti, Quantinuum, and Pasqal, QPyth ensures every component follows standard physical implementations—delivering real simulation, authentic hardware routing, and graceful dependency handling within a full-stack environment.

---

🌟 Highlights

• Physically grounded quantum workflows — canonical implementations built on Qiskit, with textbook-aligned circuits and real simulation behavior.
• Molecular VQE — H₂ plus extended molecule support through the VQE stack, with physical and lightweight execution paths.
• IBM Quantum execution — run circuits on real IBM backends with configurable shots, backend routing, and runtime options.
• Hardware-calibrated noisy simulation — realistic noise models from vendor-neutral backend profiles (IBM, IonQ, Rigetti, Quantinuum, Pasqal) or user-imported calibration data.
• Core quantum protocols — Bloch state analysis, Bell-state exploration, teleportation, and measurement-driven circuit demos.
• Complete quantum teleportation — Full protocol with Bob's conditional X/Z corrections, tested on IBM Quantum hardware (ibm_fez, 14,448 shots).
• DNA-inspired circuit exploration — curated OpenQASM imports with normalized sequence and circuit metadata.
• Quantum error correction — Shor 9-qubit and Steane 7-qubit codes with proper syndrome measurement using ancilla qubits.
• Sacred-geometry modules — QRNG with phi-scaling and the 21-qubit TMT Sierpinski circuit.
• CLI + Web UI — interactive command-line interface plus optional FastAPI + React web UI for exploration.

---

🚀 Quickstart

Installation

# Core package (Qiskit, Qiskit-Aer, NumPy)
pip install QPyth

# With physical VQE support (requires qiskit-algorithms, qiskit-nature, pyscf)
pip install QPyth[physical]

# With IBM Quantum hardware support (requires qiskit-ibm-runtime)
pip install QPyth[hardware]

# With web UI support (requires FastAPI, uvicorn)
pip install QPyth[web]

# Development mode (all extras)
pip install -e .[dev,physical,web,hardware]

CLI Mode

# Run the interactive quantum playground
qpy

# Or directly via Python module
python -m quantumpytho

Web UI Mode

# Start the FastAPI backend
python server.py           # http://localhost:8000

# Start the React frontend (in a separate terminal)
cd web
npm install
npm run dev                # http://localhost:3000

For frontend build and dev commands, run npm inside the web/ directory because the React/Vite package.json lives in web/package.json.

---

📚 Usage Examples

1. Bloch Sphere State Projection

from quantumpytho.modules.bloch_ascii import run_bloch_ascii

# Display statevector at θ=π/3, φ=π/2
run_bloch_ascii(theta=1.047, phi=1.571)

Output:

State Vector Projection (θ=1.047000, φ=1.571000):
Statevector([ 8.66e-01+0.j, -1.02e-04+0.4999j], dims=(2,))
|0> state: [###############-----]   75.01% (768 shots)
|1> state: [#####---------------]   24.99% (256 shots)

2. QRNG with Golden-Ratio Scaling

from quantumpytho.engine import QuantumEngine
from quantumpytho.modules.qrng_sacred import qrng_phi_sequence

engine = QuantumEngine()
sequence = qrng_phi_sequence(engine, num_qubits=8, length=16)
print(f"QRNG φ-sequence: {sequence}")

3. Bell Pair Creation (Entanglement)

from quantumpytho.engine import QuantumEngine
from quantumpytho.modules.circuit_explorer import bell_pair

engine = QuantumEngine()
result = bell_pair(engine)
print(f"Bell pair counts: {result.counts}")
# Expected: {'00': ~512, '11': ~512}  (maximally entangled state |Φ⁺⟩)

4. TMT Sierpinski Fractal (21-qubit)

from quantumpytho.engine import QuantumEngine
from quantumpytho.modules.tmt_sierpinski import run_tmt_sierpinski, build_tmt_sierpinski_circuit

# Inspect the circuit
qc = build_tmt_sierpinski_circuit()
print(f"Circuit: {qc.num_qubits} qubits, depth {qc.depth()}, {qc.size()} gates")

# Execute on simulator
engine = QuantumEngine()
result = run_tmt_sierpinski(engine)
print(f"Most common outcome: {result['most_common'][0]} ({result['most_common'][1]} shots)")

5. Physical H₂ VQE

# Requires: pip install QPyth[physical]
from quantumpytho.modules.vqe_h2_exact import run_vqe_h2_physical

energies = run_vqe_h2_physical(max_iters=50)
for iteration, energy in energies[-5:]:
    print(f"Iter {iteration:3d}: E = {energy:.8f} Hartree")
# Ground state energy converges to ≈ −1.137 Hartree

6. Quantum Teleportation

from quantumpytho.modules.teleport_bridge import (
    build_teleport_circuit,
    build_complete_teleport_circuit,
    run_teleport_bridge,
    run_complete_teleport
)

# Basic teleportation (Bell measurement only)
qc = build_teleport_circuit()
print(f"Basic circuit: {qc.num_qubits} qubits, {qc.num_clbits} classical bits")

# Complete teleportation with Bob's conditional corrections
qc_complete = build_complete_teleport_circuit()
print(f"Complete circuit: {qc_complete.num_qubits} qubits, {qc_complete.num_clbits} classical bits")

# Run the complete protocol
counts = run_complete_teleport()
print(f"Measurement outcomes: {counts}")

# The complete protocol includes:
# - Alice's Bell measurement on qubits 0 and 1
# - Bob's conditional X gate (if alice[1] == 1)
# - Bob's conditional Z gate (if alice[0] == 1)
# - Final measurement on Bob's qubit (qubit 2)

7. Decoherence Toggle

from quantumpytho.modules.decoherence_toggle import DecoherenceController

ctrl = DecoherenceController()
print(ctrl.enabled)   # False
ctrl.toggle()
print(ctrl.enabled)   # True

8. IBM Quantum Hardware Execution

# Requires: pip install QPyth[hardware]
import os
os.environ['QISKIT_IBM_TOKEN'] = 'your-ibm-quantum-token'

from quantumpytho.modules.hardware_ibm import run_on_hardware
from quantumpytho.engine import QuantumEngine
from qiskit import QuantumCircuit

# Create a simple circuit
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()

# Run on IBM Quantum hardware
result = run_on_hardware(qc, backend_name='least_busy')
print(f"Job ID: {result.job_id}")
print(f"Backend: {result.backend_name}")
print(f"Counts: {result.counts}")

9. Noisy Simulation with Hardware Calibration Data

Simulate realistic quantum hardware noise using calibration data from IBM Quantum backends:

from quantumpytho.modules.noise_builder import (
    build_noise_model_from_ibm_backend,
    get_synthetic_demo_profiles,
    load_noise_model
)
from qiskit import QuantumCircuit

# Option 1: Use synthetic demo profiles for testing (no IBM account needed)
demo_profiles = get_synthetic_demo_profiles()
print(f"Demo profiles: {list(demo_profiles.keys())}")
# ['demo_5q', 'demo_7q']

noise_model = load_noise_model('demo_5q')

# Option 2: Retrieve from IBM Quantum at runtime (requires IBM account)
# Set your IBM Quantum token: os.environ['QISKIT_IBM_TOKEN'] = 'your-token'
# noise_model = build_noise_model_from_ibm_backend('ibm_brisbane')

# Create a Bell state circuit
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()

# Run with noise model
from qiskit_aer import AerSimulator
simulator = AerSimulator(noise_model=noise_model)
result = simulator.run(qc, shots=1000).result()
counts = result.get_counts()
print(f"Counts: {counts}")
# Shows realistic noise effects (not ideal 50/50 split)

Note: Backend-derived noise parameters are generated from IBM Quantum calibration properties and remain subject to IBM platform terms. Users are responsible for ensuring their use complies with IBM Quantum terms of service.

10. DNA-Inspired Circuit Import

from quantumpytho.modules.dna_circuits import get_available_dna_circuits, summarize_dna_circuit

catalog = get_available_dna_circuits()
print([item.circuit_id for item in catalog])

summary = summarize_dna_circuit("dna_helix_10bp")
print(summary.name)
print(summary.qubits, summary.parsed_gate_count)

large_summary = summarize_dna_circuit("stealth_dna_34bp")
print(large_summary.base_pairs, large_summary.qubits, large_summary.parsed_depth)

from quantumpytho.modules.dna_circuits import get_available_dna_sequences
print([record.record_id for record in get_available_dna_sequences()])

This feature imports curated OpenQASM assets and exposes them as circuit-exploration data. It does not claim biological simulation fidelity. OpenQASM 3 assets require the optional dependency qiskit_qasm3_import.

Responsible Use Notice

The DNA-related features in QPyth are provided for educational, computational, and circuit-exploration purposes only.

• They do not constitute biological modeling, clinical analysis, or validated genetic interpretation.
• They do not provide medical, diagnostic, therapeutic, or laboratory guidance.
• They are not intended for pathogen design, wet-lab experimentation, synthesis planning, or any harmful biological application.
• They should not be relied upon as evidence of biological function, safety, or real-world DNA behavior.

Any DNA-inspired or sequence-related assets in this repository are presented as computational abstractions or curated examples unless explicitly documented otherwise.

Data Provenance

Where bundled DNA or sequence-like assets are included, the repository should identify whether they are synthetic/demo-only, derived from public reference material, or transformed for educational use. Unless explicitly stated otherwise, treat such assets as illustrative and non-authoritative.

IBM Quantum Backend Data

Important: QPyth does not bundle IBM Quantum calibration data. Users must retrieve backend properties at runtime using their own IBM Quantum credentials.

• Runtime Retrieval: Use build_noise_model_from_ibm_backend(backend_name) to fetch calibration data directly from IBM Quantum.
• Synthetic Demo Profiles: Use get_synthetic_demo_profiles() for testing without IBM access.
• User Responsibility: Users are responsible for ensuring their use of IBM Quantum backend data complies with IBM Quantum terms of service.
• Attribution: Backend-derived noise parameters are generated from IBM Quantum calibration properties and remain subject to IBM platform terms.

Environment Variables:

Variable	Default	Description
QPYTH_MODE	simulator	Execution mode: simulator, noisy_simulator, or hardware
QPYTH_NOISE_PROFILE	—	Hardware profile for noisy simulation (e.g., Boston, Torino)

Web UI Integration:

The VQE web interface now supports three execution modes:

• 🧪 Ideal Simulator — Fast, noise-free simulation
• 🔊 Noisy Simulator — Realistic hardware noise from calibration data
• 🖥️ IBM Quantum Hardware — Real quantum hardware execution

Environment Variables:

Variable	Default	Description
QISKIT_IBM_TOKEN	—	IBM Quantum API token (required)
QPYTH_IBM_CHANNEL	ibm_quantum	Channel: ibm_quantum or ibm_cloud
QPYTH_IBM_BACKEND	least_busy	Backend name or least_busy for auto-selection
QPYTH_IBM_SHOTS	1024	Number of measurement shots
QPYTH_IBM_OPTIMIZATION_LEVEL	1	Transpilation optimization (0-3)
QPYTH_IBM_RESILIENCE_LEVEL	1	Error mitigation level (0-3)

---

🖥️ Interactive CLI

Run qpy (or python -m quantumpytho) to open the interactive menu:

=== QuantumPytho App ===
1) Sacred-geometry QRNG sequence
2) Circuit explorer (Bell pair)
3) Circuit explorer (Hadamard sweep)
4) TMT Sierpinski fractal (21-qubit)
5) Bloch State Vector Projection (ASCII)
6) Non-local Teleportation Bridge
7) Molecular Ground-State (VQE Sim)
8) Toggle Quantum Decoherence [OFF]
q) Quit

---

📊 Circuit Explorer

Circuit	Description
Bell Pair	Creates |Φ⁺⟩ = (|00⟩ + |11⟩)/√2 — maximally entangled
Hadamard Sweep	Applies n sequential Hadamard gates and measures
Teleportation	Three-qubit protocol from Nielsen & Chuang
TMT Sierpinski	21-qubit Sierpinski-triangle topology with φ-scaled RZ gates

---

🧪 Running Tests

# All tests
pytest tests/ --tb=short

# With coverage report
pytest --cov=quantumpytho --cov-report=html

# Skip slow tests
pytest -m "not slow"

# Verbose output
pytest -v

Coverage status:

Module	Status
bloch_ascii	✅
qrng_sacred	✅
circuit_explorer	✅
teleport_bridge	✅
tmt_sierpinski	✅
vqe_h2_cli	✅
decoherence_toggle	✅
config / engine	✅

---

🛠 Development

Code Quality

# Lint
ruff check .

# Format
ruff format .

# Lint + format check (CI-equivalent)
ruff check . && ruff format --check .

# Optional type checking
mypy quantumpytho/

Pre-commit Hooks

pre-commit install          # install once
pre-commit run              # run on staged files
pre-commit run --all-files  # run on entire repo

---

📁 Project Structure

QPyth/
├── quantumpytho/
│   ├── __init__.py              # Package version & public API
│   ├── __main__.py              # CLI entry point
│   ├── config.py                # QuantumConfig (env-driven)
│   ├── engine.py                # QuantumEngine + QuantumResult
│   ├── menu.py                  # Interactive CLI menu
│   └── modules/
│       ├── __init__.py
│       ├── bloch_ascii.py       # Bloch sphere ASCII projection
│       ├── qrng_sacred.py       # Sacred-geometry QRNG (φ-scaling)
│       ├── circuit_explorer.py  # Bell pairs, Hadamard sweeps
│       ├── vqe_h2_ascii.py      # Lightweight VQE optimizer
│       ├── vqe_h2_exact.py      # Physical H₂ VQE (Qiskit-Nature)
│       ├── vqe_h2_cli.py        # CLI wrapper for VQE
│       ├── vqe_core.py          # Core VQE implementation
│       ├── vqe_molecules.py     # Extended molecule support (LiH, HeH+, BeH₂, H₂O)
│       ├── vqe_utils.py         # VQE utility functions
│       ├── hardware_ibm.py      # IBM Quantum hardware integration
│       ├── teleport_bridge.py   # Quantum teleportation protocol
│       ├── decoherence_toggle.py# Noise model toggle controller
│       ├── qec_shor.py          # Shor's 9-qubit error correction
│       ├── qec_steane.py        # Steane's 7-qubit error correction
│       └── tmt_sierpinski.py    # 21-qubit TMT Sierpinski circuit
├── web/                         # React + Vite frontend
│   ├── src/                     # TypeScript source
│   └── README.md                # Web UI documentation
├── tests/
│   └── test_*.py                # pytest test suite
├── server.py                    # FastAPI web server entry point
├── pyproject.toml               # Project metadata & dependencies
├── CHANGELOG.md                 # Version history
├── CONTRIBUTING.md              # Contribution guidelines
├── SECURITY.md                  # Security policy
├── CODE_OF_CONDUCT.md           # Community standards
└── LICENSE                      # Apache 2.0

---

⚙️ Configuration

QuantumPytho reads its configuration from environment variables:

Variable	Default	Description
QPYTH_BACKEND	automatic	Qiskit-Aer simulation method
QPYTH_SHOTS	1024	Number of measurement shots

IBM Quantum Hardware Configuration

Variable	Default	Description
QISKIT_IBM_TOKEN	—	IBM Quantum API token (required for hardware)
QPYTH_IBM_CHANNEL	ibm_quantum	Channel: ibm_quantum or ibm_cloud
QPYTH_IBM_BACKEND	least_busy	Backend name or least_busy for auto-selection
QPYTH_IBM_SHOTS	1024	Number of measurement shots
QPYTH_IBM_OPTIMIZATION_LEVEL	1	Transpilation optimization (0-3)
QPYTH_IBM_RESILIENCE_LEVEL	1	Error mitigation level (0-3)

# Example: run with 4096 shots and statevector method
QPYTH_BACKEND=statevector QPYTH_SHOTS=4096 qpy

# Example: run on IBM Quantum hardware
export QISKIT_IBM_TOKEN="your-token-here"
pip install QPyth[hardware]
python -c "from quantumpytho.modules.hardware_ibm import run_on_hardware; ..."

---

🔬 Scientific Value: Simulate Real Hardware Without Physical Access

One of the most significant capabilities of QPyth is the ability to simulate the behavior of real quantum hardware without needing actual access to a quantum computer. This is scientifically and practically valuable for several reasons:

Why Noisy Simulation Matters

Real quantum hardware is subject to multiple sources of error:

Error Source	Physical Origin	Impact
T1 Relaxation	Energy decay from excited |1⟩ to ground |0⟩ state	Amplitude damping
T2 Dephasing	Loss of phase coherence between |0⟩ and |1⟩	Phase flip probability
Readout Error	Measurement apparatus imperfections	Bit-flip on measurement
Gate Error	Imperfect control pulses, crosstalk	Depolarizing noise
CZ Gate Error	Coupling between neighboring qubits	Two-qubit depolarization

How QPyth Replicates Hardware Fidelity

QPyth uses real IBM Quantum calibration data to build noise models that accurately reflect the performance characteristics of specific hardware backends. Each profile captures:

• Per-qubit T1/T2 coherence times (in microseconds)
• Qubit-specific readout error matrices
• Single-qubit gate error rates and durations
• Two-qubit (CZ) gate error rates for all coupled pairs

from quantumpytho.modules.noise_builder import get_backend_info

info = get_backend_info("Boston")
# Returns: {'name': 'Boston', 'num_qubits': 127,
#           'avg_t1_us': 280.4, 'avg_t2_us': 352.1,
#           'avg_readout_error': 0.0052, ...}

Scientific Applications Without Hardware Access

Use Case	Description
Algorithm benchmarking	Test VQE, QAOA, or other algorithms under realistic noise before running on real hardware
Error mitigation research	Develop and test error mitigation strategies with calibrated noise models
Threshold analysis	Determine minimum hardware requirements before requesting hardware access
Reproducible results	Share experiments with fixed noise parameters for peer review
Educational simulation	Teach quantum error effects without requiring expensive hardware queue time
CI/CD validation	Validate quantum software against hardware-realistic noise in automated pipelines

Supported Hardware Profiles (IBM Quantum)

All 10 hardware profiles are derived from real IBM Quantum calibration data:

Backend	Qubits	Avg T1 (μs)	Avg T2 (μs)	Avg Readout Error	Architecture
Boston	127	~280	~350	~0.5%	Eagle r3
Torino	133	~200	~150	~3.0%	Heron r1
Kingston	127	~280	~350	~0.5%	Eagle r3
Marrakesh	132	~250	~200	~2.0%	Heron r2
Fez	156	~300	~400	~0.5%	Flamingo r1
Strasbourg	127	~260	~280	~1.2%	Eagle r3
Brussels	127	~270	~300	~0.8%	Eagle r3
Aachen	127	~290	~320	~0.7%	Eagle r3
Miami	156	~310	~380	~0.6%	Flamingo r1
Pittsburgh	156	~295	~360	~0.55%	Flamingo r1

Comparison: Ideal vs. Noisy Simulation

from qiskit import QuantumCircuit
from quantumpytho.modules.hardware_ibm import NoisySimulatorEngine
from quantumpytho.engine import QuantumEngine

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

# Ideal simulation — perfect 50/50 split
ideal = QuantumEngine()
ideal_result = ideal.run(qc, shots=1000)
# {'00': 500, '11': 500}  (approximately)

# Noisy simulation — realistic hardware errors
noisy = NoisySimulatorEngine("Boston", shots=1000)
noisy_result = noisy.run(qc)
# {'00': 483, '11': 471, '01': 23, '10': 23}  (noise causes ~4.6% error)

The gap between ideal and noisy results quantifies the noise budget — the overhead that must be addressed by error mitigation or error correction strategies to achieve fault-tolerant computation.

---

🔬 Scientific Correctness

Principle	Implementation
No fabricated physics	Real Qiskit simulation or graceful error messages
Canonical parametrizations	Bloch sphere: |ψ⟩ = cos(θ/2)|0⟩ + e^{iφ} sin(θ/2)|1⟩
Textbook circuits	Bell pairs and teleportation match Nielsen & Chuang
Proper VQE stack	PySCF → Jordan-Wigner mapper → VQE when dependencies available
Physical units	Energies reported in Hartree; angles in radians

---

🌐 Web UI

The optional web interface provides:

• Bloch Sphere — interactive θ/φ sliders with real-time probability bars
• Circuit Explorer — Bell pairs, Hadamard sweeps, teleportation
• VQE — live energy convergence plots for multiple molecules (H₂, LiH, HeH⁺, BeH₂, H₂O)
• Hardware Toggle — switch between local simulator and IBM Quantum hardware
• QRNG — quantum random number sequences with φ-scaling

Requirements: Node.js 18+, Python 3.10+

See web/README.md for full setup instructions.

---

📖 References

1. Nielsen, M. A., & Chuang, I. L. (2010). Quantum Computation and Quantum Information. Cambridge University Press.
2. Qiskit Documentation
3. Qiskit Nature Documentation
4. Kawaihome — Bloch Sphere Definition (quantum information theory resources).

---

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md before submitting a pull request.

Areas we'd love help with:

• New quantum circuits and modules
• Web UI enhancements and visualizations
• Documentation improvements and tutorials
• Additional test coverage and edge cases
• Performance optimizations

---

📄 License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.

---

Made with quantum ❤️ by Quantum Dynamics

GitHub • PyPI • Issues