# aaditya-anand11/-optiq-flow architecture

> Architecture diagram of the GitHub repository aaditya-anand11/-optiq-flow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aaditya-anand11/-optiq-flow
- Repository: https://github.com/aaditya-anand11/-optiq-flow

## Overview

##### Project Type and Purpose
- OptiQ-Flow is a domain-specific quantum-enabled data pipeline plus an interactive dashboard. It is not a traditional “frontend/backend” web app; rather it is a scientific application with:
- Data ingestion modules (historical or synthetic market data)
- Algorithmic layers (QUBO formulation, QAOA solver with/without error mitigation, classical baseline)
- Visualization & dashboard (Streamlit, notebooks)
- Purpose: solve Markowitz portfolio optimization via QAOA on NISQ hardware, quantify error mitigation benefits, and present results interactively.

##### File Structure Analysis
- Top-level files:
- app.py: Streamlit entry point
- config.py: global settings (e.g., IBM token, hardware selection)
- notebooks/: exploratory Jupyter notebook
- requirements.txt / .github/: CI tests, linting
- src/ contains all core logic organized by responsibility:
- portfolio_data.py (data ingestion & preprocessing)
- qubo_formulation.py (QUBO/Ising mapping)
- qaoa_optimizer.py (circuit building & variational loop)
- error_mitigation.py (readout calibration, ZNE)
- classical_baseline.py (cvxpy Markowitz solver)
- visualization.py (Plotly/Matplotlib helpers)
- tests/: unit tests for QAOA logic

##### README Insights
- Tech stack spans Qiskit (quantum SDK, Aer simulator, IBM Runtime), SciPy/COBYLA, cvxpy, pandas/numpy, Plotly/Matplotlib, Streamlit.

1. Data Source
- Yahoo Finance or Synthetic Data (possibly an external API)
2. Data Processing Module
- src.portfolio_data: fetch, clean, compute returns & covariance matrices
3. QUBO/Ising Mapper
- src.qubo_formulation: portfolio_to_qubo(), qubo_to_ising()
4. Solver Layer (branch into two parallel sub-flows):
- QAOA Runner (no mitigation) – raw execution on hardware/simulator
- QAOA Runner (with mitigation) – includes readout calibration & zero-noise extrapolation
5. Classical Baseline
- src.classical_baseline: cvxpy mean-variance solution
6. Comparison & Visualization
- app.py / Streamlit UI for interactive dashboard
- notebooks/analysis.ipynb for static walkthrough
7. External Services & Config
- IBM Quantum Runtime (hardware endpoints)
- Environment (.env) for IBM token

- Data Source → Data Processing → QUBO Mapper → Solver Layer (split)
- Solver Outputs + Classical Baseline → Comparison & Visualization → Streamlit / Notebook
- config.py injects parameters into all modules
- Error Mitigation module hooks into the QAOA Runner (with mitigation branch)

c. Architectural Patterns
- Pipeline pattern: sequential data transformation steps
- Branching for A/B runs (raw vs. mitigated)
- Modular separation by concern (ETL, formulation, compute, visualization)
- Dependency injection via config.py and environment variables

d. Key Technologies & Frameworks
- Qiskit (SDK, Aer simulator, IBM Runtime)
- SciPy optimizers (COBYLA, SLSQP)
- cvxpy (classical baseline)
- pandas / NumPy (data handling)
- Plotly / Matplotlib (visualization)
- Streamlit (dashboard)
- GitHub Actions (.github/workflows/tests.yml) for CI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data Source
    DS["Yahoo Finance / Synthetic Data"]:::external

    %% Configuration
    CFG["Global Configuration"]:::external

    %% Data Processing
    PD["PortfolioData"]:::data
    click PD "https://github.com/aaditya-anand11/-optiq-flow/blob/main/src/portfolio_data.py"

    %% QUBO Mapper
    QF["QUBOFormulation"]:::data
    click QF "https://github.com/aaditya-anand11/-optiq-flow/blob/main/src/qubo_formulation.py"

    %% Solver Layer - Raw QAOA
    QR["QAOA Runner (Raw)"]:::quantum
    click QR "https://github.com/aaditya-anand11/-optiq-flow/blob/main/src/qaoa_optimizer.py"

    %% Solver Layer - Mitigated QAOA
    QM["QAOA Runner (with Mitigation)"]:::quantum
    click QM "https://github.com/aaditya-anand11/-optiq-flow/blob/main/src/error_mitigation.py"

    %% Classical Baseline
    CB["ClassicalBaseline"]:::classical
    click CB "https://github.com/aaditya-anand11/-optiq-flow/blob/main/src/classical_baseline.py"

    %% Comparison & Visualization
    VH["VisualizationHelpers"]:::classical
    click VH "https://github.com/aaditya-anand11/-optiq-flow/blob/main/src/visualization.py"
    UI["Streamlit UI"]:::ui
    click UI "https://github.com/aaditya-anand11/-optiq-flow/blob/main/app.py"
    NB["Analysis Notebook"]:::ui
    click NB "https://github.com/aaditya-anand11/-optiq-flow/blob/main/notebooks/analysis.ipynb"

    %% External Services & CI
    IBM["IBM Quantum Backend"]:::external
    UT["Unit Tests"]:::external
    click UT "https://github.com/aaditya-anand11/-optiq-flow/blob/main/tests/test_qaoa.py"
    CI["CI Workflow"]:::external
    click CI "https://github.com/aaditya-anand11/-optiq-flow/blob/main/.github/workflows/tests.yml"

    %% Flow
    DS --> PD
    CFG --> PD
    PD --> QF
    CFG --> QF
    QF --> QR
    QF --> QM
    QM --> VH
    QR --> VH
    CB --> VH
    VH --> UI
    VH --> NB

    CFG --> QR
    CFG --> QM

    IBM --> QR
    IBM --> QM

    UT --> QR
    CI --> UT

    %% Styles
    classDef data fill:#a3c4f3,stroke:#333,stroke-width:1px;
    classDef quantum fill:#d9b3ff,stroke:#333,stroke-width:1px;
    classDef classical fill:#b3ffb3,stroke:#333,stroke-width:1px;
    classDef ui fill:#ffd699,stroke:#333,stroke-width:1px;
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:1px;
```
