Metadata-Version: 2.4
Name: QPyth
Version: 0.3.7
Summary: 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
Author-email: Quantum Dynamics <quantumdynamics927@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/quantumdynamics927-dotcom/QPyth
Project-URL: Repository, https://github.com/quantumdynamics927-dotcom/QPyth
Project-URL: Issues, https://github.com/quantumdynamics927-dotcom/QPyth/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: qiskit>=1.1.0
Requires-Dist: qiskit-aer>=0.15.0
Requires-Dist: numpy>=2.0.0
Requires-Dist: pandas>=2.0.0
Provides-Extra: physical
Requires-Dist: qiskit-algorithms>=0.3.0; extra == "physical"
Requires-Dist: qiskit-nature>=0.7.0; extra == "physical"
Provides-Extra: hardware
Requires-Dist: qiskit-ibm-runtime>=0.28.0; extra == "hardware"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: pre-commit>=3.7.0; extra == "dev"
Provides-Extra: web
Requires-Dist: fastapi<1.0.0,>=0.115.0; extra == "web"
Requires-Dist: uvicorn[standard]<1.0.0,>=0.32.0; extra == "web"
Requires-Dist: slowapi>=0.1.9; extra == "web"
Dynamic: license-file

# QPyth

<div align="center">

![Quantum Computing](https://img.shields.io/badge/Quantum-Computing-blue?style=for-the-badge&logo=qc&logoColor=white)
![Python](https://img.shields.io/badge/Python-3.10%2B-3670A0?style=for-the-badge&logo=python&logoColor=ffdd54)
![License](https://img.shields.io/badge/License-Apache%202.0-007BFF?style=for-the-badge&logo=apache)
![Version](https://img.shields.io/badge/version-0.3.6-success?style=for-the-badge)

[![PyPI version](https://badge.fury.io/py/QPyth.svg)](https://badge.fury.io/py/QPyth)
[![CI/CD Pipeline](https://github.com/quantumdynamics927-dotcom/QPyth/actions/workflows/ci.yml/badge.svg)](https://github.com/quantumdynamics927-dotcom/QPyth/actions/workflows/ci.yml)

[![Codecov](https://codecov.io/gh/quantumdynamics927-dotcom/QPyth/branch/main/graph/badge.svg)](https://codecov.io/gh/quantumdynamics927-dotcom/QPyth)

</div>

> **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

```bash
# 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

```bash
# Run the interactive quantum playground
qpy

# Or directly via Python module
python -m quantumpytho
```

### Web UI Mode

```bash
# 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](D:/QPyth/web/package.json).

---

## 📚 Usage Examples

### 1. Bloch Sphere State Projection

```python
from quantumpytho.modules.bloch_ascii import run_bloch_ascii

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

**Output:**

```text
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

```python
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)

```python
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)

```python
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

```python
# 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

```python
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

```python
from quantumpytho.modules.decoherence_toggle import DecoherenceController

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

### 8. IBM Quantum Hardware Execution

```python
# 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:

```python
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

```python
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:

```text
=== 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

```bash
# 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

```bash
# Lint
ruff check .

# Format
ruff format .

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

# Optional type checking
mypy quantumpytho/
```

### Pre-commit Hooks

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

---

## 📁 Project Structure

```text
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) |

```bash
# 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

```python
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

```python
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](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](https://docs.quantum.ibm.com/)
3. [Qiskit Nature Documentation](https://qiskit-community.github.io/qiskit-nature/)
4. Kawaihome — *Bloch Sphere Definition* (quantum information theory resources).

---

## 🤝 Contributing

Contributions are welcome! Please read [CONTRIBUTING.md](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](LICENSE) file for details.

---

<p align="center">
<strong>Made with quantum ❤️ by Quantum Dynamics</strong>
</p>

<p align="center">
<a href="https://github.com/quantumdynamics927-dotcom/QPyth">GitHub</a> •
<a href="https://pypi.org/project/QPyth">PyPI</a> •
<a href="https://github.com/quantumdynamics927-dotcom/QPyth/issues">Issues</a>
</p>
