Metadata-Version: 2.4
Name: QPyth
Version: 0.3.5
Summary: QPyth - Qiskit-based quantum toolkit for simulation, education, and research workflows with VQE, IBM Quantum integration, realistic noisy simulation, quantum error correction, 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.5-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 a proprietary offline noise simulation engine powered by historical IBM device calibration data, 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** — offline noise models derived from IBM calibration profiles for more realistic testing.
- **Core quantum protocols** — Bloch state analysis, Bell-state exploration, teleportation, and measurement-driven circuit demos.
- **DNA-inspired circuit exploration** — curated OpenQASM imports with normalized sequence and circuit metadata.
- **Quantum error correction** — built-in Shor 9-qubit and Steane 7-qubit code implementations.
- **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 run_teleport_bridge

run_teleport_bridge()
# Shows Alice's Bell measurement outcomes and Bob's corrected state
```

### 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.hardware_ibm import NoisySimulatorEngine
from quantumpytho.modules.noise_builder import get_backend_profile_names, get_backend_info
from qiskit import QuantumCircuit

# List available hardware profiles
profiles = get_backend_profile_names()
print(f"Available profiles: {profiles}")
# ['Aachen', 'Boston', 'Brussels', 'Fez', 'Kingston', 'Marrakesh', 'Miami', 'Pittsburgh', 'Strasbourg', 'Torino']

# Get backend info
info = get_backend_info('Boston')
print(f"Boston: {info['num_qubits']} qubits, avg T1: {info['avg_t1_us']} μs")

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

# Run with realistic hardware noise
engine = NoisySimulatorEngine('Boston', shots=1000)
result = engine.run(qc)
print(f"Counts: {result.counts}")

# Shows realistic noise effects (not ideal 50/50 split)
```

### 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.

**Available Hardware Profiles:**

| Backend | Qubits | Avg T1 (μs) | Avg T2 (μs) | Avg Readout Error |
| ------- | ------ | ----------- | ----------- | ----------------- |
| Boston | 127 | ~280 | ~350 | ~0.5% |
| Torino | 133 | ~200 | ~150 | ~3% |
| Kingston | 127 | ~280 | ~350 | ~0.5% |
| Marrakesh | 132 | ~250 | ~200 | ~2% |
| Fez | 156 | ~300 | ~400 | ~0.5% |
| ... | ... | ... | ... | ... |

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