Skip to content

Architecture

This document describes the architecture and design of QPyth.

Overview

QPyth is a modular quantum computing library built on Qiskit. It provides:

  • Core Engine - Quantum circuit execution and management
  • Modules - Specialized quantum algorithms and protocols
  • Configuration - Flexible configuration system
  • CLI - Interactive command-line interface
  • Web UI - FastAPI + React web interface

Project Structure

QPyth/
├── quantumpytho/              # Main package
│   ├── __init__.py           # Package initialization
│   ├── __main__.py           # Entry point for `python -m quantumpytho`
│   ├── config.py             # Configuration management
│   ├── engine.py             # Core quantum engine
│   ├── menu.py               # CLI menu system
│   ├── data/                 # Calibration data
│   │   └── backends/         # IBM calibration CSVs
│   └── modules/              # Quantum modules
│       ├── bloch_ascii.py    # Bloch sphere visualization
│       ├── circuit_explorer.py # Circuit exploration
│       ├── decoherence_toggle.py # Decoherence control
│       ├── hardware_ibm.py   # IBM hardware integration
│       ├── noise_builder.py  # Noise model construction
│       ├── qec_shor.py       # Shor's 9-qubit code
│       ├── qec_steane.py     # Steane's 7-qubit code
│       ├── qrng_sacred.py    # Quantum RNG
│       ├── teleport_bridge.py # Quantum teleportation
│       ├── tmt_sierpinski.py # Sierpinski fractal
│       ├── vqe_core.py       # VQE core implementation
│       ├── vqe_h2_cli.py     # H2 VQE CLI
│       ├── vqe_h2_exact.py   # H2 VQE with physical energies
│       ├── vqe_molecules.py  # Molecule configurations
│       └── vqe_utils.py      # VQE utilities
├── tests/                    # Test suite
├── docs/                     # Documentation
├── web/                      # Web UI
│   ├── src/
│   │   ├── components/       # React components
│   │   ├── App.tsx           # Main app
│   │   └── index.css         # Styles
│   ├── package.json          # Node dependencies
│   └── vite.config.ts        # Vite configuration
├── notebooks/                # Jupyter notebooks
├── server.py                 # FastAPI backend
├── pyproject.toml            # Project configuration
└── README.md                 # Project README

Core Components

Configuration System

File: quantumpytho/config.py

The configuration system provides flexible runtime configuration:

class QuantumConfig:
    """Configuration for quantum execution."""

    def __init__(
        self,
        backend: str = "ibmq_qasm_simulator",
        shots: int = 1024,
        mode: ExecutionMode = ExecutionMode.SIMULATOR,
        noise_profile: str | None = None
    ):
        self.backend = backend
        self.shots = shots
        self.mode = mode
        self.noise_profile = noise_profile

Features: - Environment variable support - TOML configuration file support - Programmatic configuration - Default values

Quantum Engine

File: quantumpytho/engine.py

The core engine manages quantum circuit execution:

class QuantumEngine:
    """Core quantum engine for circuit execution."""

    def __init__(self, config: QuantumConfig | None = None):
        self.config = config or QuantumConfig()
        self._hardware_engine = None

    def run(self, circuit: QuantumCircuit, shots: int = 1024) -> dict:
        """Run quantum circuit."""
        # Route to appropriate executor
        if self.config.mode == ExecutionMode.HARDWARE:
            return self._run_on_hardware(circuit, shots)
        elif self.config.mode == ExecutionMode.NOISY_SIMULATOR:
            return self._run_with_noise(circuit, shots)
        else:
            return self._run_ideal(circuit, shots)

Features: - Multi-mode execution (simulator, noisy, hardware) - Automatic backend selection - Error handling and fallbacks - Result normalization

Module System

Directory: quantumpytho/modules/

Each module implements a specific quantum capability:

Bloch ASCII

  • Visualizes quantum states on Bloch sphere
  • ASCII art output
  • Measurement probability display

Circuit Explorer

  • Bell pair entanglement
  • Hadamard sweep
  • Circuit diagram generation

VQE Stack

  • Core VQE implementation
  • H2 molecule simulation
  • Multi-molecule support
  • Physical energy calculation

Hardware Integration

  • IBM Quantum connection
  • Noisy simulation engine
  • Noise model construction
  • Backend management

QEC Codes

  • Shor's 9-qubit code
  • Steane's 7-qubit code
  • Error injection and correction

Sacred Geometry

  • QRNG with golden ratio scaling
  • TMT Sierpinski fractal
  • Phi-based algorithms

Data Flow

CLI Execution Flow

User Input
    ↓
menu.py (CLI)
    ↓
Module Selection
    ↓
QuantumEngine
    ↓
Execution Mode
    ├─→ Ideal Simulator (Qiskit Aer)
    ├─→ Noisy Simulator (Qiskit Aer + Noise)
    └─→ Hardware (IBM Quantum)
    ↓
Results
    ↓
Display (ASCII/Charts)

Web UI Execution Flow

User Interface (React)
    ↓
HTTP Request
    ↓
FastAPI Backend (server.py)
    ↓
QuantumEngine
    ↓
Execution Mode
    ↓
Results (JSON)
    ↓
Display (React Components)

Design Patterns

Strategy Pattern

Execution modes use the strategy pattern:

class QuantumEngine:
    def run(self, circuit, shots):
        if self.config.mode == ExecutionMode.SIMULATOR:
            return self._run_ideal(circuit, shots)
        elif self.config.mode == ExecutionMode.NOISY_SIMULATOR:
            return self._run_with_noise(circuit, shots)
        elif self.config.mode == ExecutionMode.HARDWARE:
            return self._run_on_hardware(circuit, shots)

Factory Pattern

Noise model construction uses factory pattern:

def build_noise_model_from_profile(profile: NoiseProfile) -> NoiseModel:
    """Build Qiskit Aer noise model from profile."""
    noise_model = NoiseModel()

    # Add thermal relaxation errors
    # Add readout errors
    # Add gate errors

    return noise_model

Builder Pattern

Configuration uses builder pattern:

config = (QuantumConfig()
    .with_backend("ibm_brisbane")
    .with_shots(2048)
    .with_mode(ExecutionMode.NOISY_SIMULATOR)
    .with_noise_profile("ibm_brisbane"))

Dependencies

Core Dependencies

  • Qiskit - Quantum computing framework
  • Qiskit-Aer - Quantum simulator
  • NumPy - Numerical computing
  • Pandas - Data manipulation

Optional Dependencies

  • Qiskit-Algorithms - Quantum algorithms
  • Qiskit-Nature - Quantum chemistry
  • PySCF - Molecular calculations
  • Qiskit-IBM-Runtime - IBM Quantum hardware
  • FastAPI - Web framework
  • Uvicorn - ASGI server

Performance Considerations

Circuit Optimization

  • Transpilation for specific backends
  • Gate cancellation and merging
  • Qubit routing optimization

Noise Modeling

  • Cached noise models
  • Efficient error construction
  • Profile-based optimization

Memory Management

  • Lazy loading of calibration data
  • Efficient result storage
  • Streaming for large outputs

Security Considerations

IBM Quantum Tokens

  • Environment variable storage
  • No token logging
  • Secure credential handling

Web UI

  • Rate limiting
  • Input validation
  • CORS configuration

Extensibility

Adding New Modules

  1. Create module file in quantumpytho/modules/
  2. Implement module interface
  3. Add tests
  4. Update documentation
  5. Add to CLI menu (if applicable)

Adding New Molecules

  1. Add configuration in vqe_molecules.py
  2. Add reference energy
  3. Add tests
  4. Update documentation

Adding New Noise Profiles

  1. Add calibration CSV to data/backends/
  2. Update noise builder
  3. Add tests
  4. Update documentation

Testing Strategy

Unit Tests

  • Test individual functions
  • Mock external dependencies
  • Fast execution

Integration Tests

  • Test module interactions
  • Use real simulators
  • Slower execution

End-to-End Tests

  • Test complete workflows
  • CLI and web UI
  • Slowest execution

Deployment

PyPI Package

  • Built with setuptools
  • Trusted publishing with OIDC
  • Automatic releases via CI/CD

Web UI

  • Backend: FastAPI + Uvicorn
  • Frontend: React + Vite
  • Deployment: Docker or cloud hosting

Documentation

  • Built with MkDocs
  • Hosted on Vercel
  • Automatic updates via CI/CD

Future Enhancements

Planned Features

  • Additional QEC codes
  • More molecules
  • Advanced error mitigation
  • Distributed computing support
  • Real-time visualization

Architecture Improvements

  • Plugin system for modules
  • Async execution support
  • Caching layer
  • Metrics and monitoring

References

Next Steps