# askery/computacao-quantica-aplicada-ao-mercado-financeiro architecture

> Architecture diagram of the GitHub repository askery/computacao-quantica-aplicada-ao-mercado-financeiro, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/askery/computacao-quantica-aplicada-ao-mercado-financeiro
- Repository: https://github.com/askery/computacao-quantica-aplicada-ao-mercado-financeiro

## Overview

##### Tipo e propósito do projeto (a partir do README e árvore de arquivos)

Este repositório não é uma aplicação “deployável” tradicional (web/app/backend), e sim um **projeto científico/educacional baseado em notebooks** para **computação clássica e quântica aplicada a finanças** (otimização de portfólio).

O objetivo é reproduzir/ilustrar resultados do artigo (link DOI no README) com duas linhas principais:

- **Abordagem clássica (Markowitz)**: construção de fronteira eficiente para vários ativos.
- **Abordagens quânticas**:
- Demonstração de **QAOA** e **VQE** usando **Qiskit** (IBM Q), no notebook “Quantum_Finance_DualQ.ipynb”.
- Implementação/estudo mais profundo de **QAOA usando myQLM**, com análise de qualidade e convergência por número de camadas, no notebook “QAOA_myQLM.ipynb”.

**Árvore de arquivos** (tudo é notebook + README):
- `Quantum_Finance_DualQ.ipynb` (clássico + QAOA/VQE com Qiskit)
- `QAOA_myQLM.ipynb` (QAOA com myQLM)
- `README.md` (contexto, links e setup do myQLM)

Isso indica uma arquitetura “pipeline de experimentos” (data → modelagem → solver → métricas/plots), e não camadas típicas de software (UI/API/DB).

##### Como desenhar o diagrama de arquitetura mais fiel para ESTE projeto

A forma mais precisa é desenhar **um diagrama de fluxo de processamento (pipeline) + um diagrama de componentes** (bibliotecas/runtimes) — ambos centrados nos notebooks como “orquestradores”.

##### Identifique os componentes principais (macro-blocos)

Para este repo, os blocos que você deve explicitar no diagrama são:

##### Ambiente de Execução
- Jupyter Notebook (local) / Google Colab (no caso do notebook Qiskit)
- Conda env Python 3.9 (principalmente para myQLM, conforme README)

##### Fontes de Dados / Inputs
- “Lista de ativos + parâmetros” (tickers, janela temporal, restrições, budget, etc.)
- (Se o notebook baixar cotações) **APIs externas de dados de mercado** (ex: Yahoo Finance, Stooq, B3 etc. — o README não nomeia, então no diagrama você pode deixar como “Market Data Provider API”)

##### Pré-processamento e Estatística
- limpeza/normalização
- cálculo de retornos, covariância, correlação
- geração de instâncias do problema (matriz de covariância, vetores de retorno)

##### Modelagem de Otimização (Finance → QUBO/Ising)
- Markowitz (clássico): objetivo risco/retorno + restrições
- Mapeamento para QUBO/Ising para rodar QAOA/VQE (quando aplicável)

##### Solvers / Engines
- **Clássico**: otimizador numérico (p.ex. quadratic programming / heurísticas). (Se não estiver explícito, represente como “Classical Optimizer”)
- **Quântico (Qiskit)**:
- QAOA
- VQE
- Backend: simulador local ou IBM Quantum (se conectado)
- **Quântico (myQLM)**:
- QAOA via myQLM stack
- Backend: simuladores do myQLM (ou QPU se existir no setup)

##### Avaliação e Visualização
- fronteira eficiente (plots)
- métricas de qualidade/convergência (energia/custo vs camadas p, gap, etc.)
- comparação entre clássico vs quântico (quando aplicável)

##### Saídas / Outputs
- gráficos (fronteira eficiente, convergência)
- pesos do portfólio / seleção de ativos
- tabelas de resultados

##### Relacionamentos e interações (o que ligar com setas)

Você quer que o diagrama deixe óbvio “quem chama quem” e “o que flui”. Para este repo:

- **Notebook** → chama **Data Source** → retorna **Séries de preços**
- **Séries de preços** → entram em **Pré-processamento** → produzem **retornos e covariância**
- **retornos/covariância + restrições** → entram em **Modelagem** → produzem:
- **Problema Markowitz** (para solver clássico)
- e/ou **QUBO/Ising** (para QAOA/VQE)
- **Modelagem** → alimenta **Solver** (clássico ou quântico)
- **Solver** → retorna **solução** (pesos/bitstring/energia)
- **Solução** → entra em **Avaliação** → gera **plots/tabelas**

Além disso, explicite dependências de runtime:
- `Quantum_Finance_DualQ.ipynb` → depende de **Qiskit** e possivelmente **IBM Quantum Backend** (opcional)
- `QAOA_myQLM.ipynb` → depende de **myQLM** (com setup recomendado no README, Python 3.9/conda)

##### Padrões/decisões arquiteturais a destacar (específicos deste repo)

- **Arquitetura “Notebook-as-Application”**: os notebooks são o “entrypoint” e concentram orquestração, experimentos, plots e resultados.
- **Separação por stack quântica**:
- Notebook 1: Qiskit (IBM)
- Notebook 2: myQLM
- **Pipeline analítico** (ETL leve → modelagem → solver → avaliação), típico de pesquisa em otimização/finanças quantitativas.
- **Comparabilidade**: mesma base de “ingredientes” (ativos, retorno, risco) aplicada a solvers diferentes (clássico vs QAOA/VQE).

##### Como “tailorar” o diagrama para este tipo de projeto (científico/otimização)

Como não há módulos/serviços em pastas `src/`, `api/`, `db/`, a melhor prática aqui é:

##### Diagrama 1 — “Visão de Sistema / Componentes”
Mostre dois caminhos paralelos a partir do mesmo “Data + Model”:

- Caminho A: **Markowitz (clássico)** → Classical Optimizer → Resultados/plots
- Caminho B: **Quantum formulation (QUBO/Ising)** → (QAOA/VQE via Qiskit) → Resultados/plots
- Caminho C: **Quantum formulation (QUBO/Ising)** → (QAOA via myQLM) → Resultados/plots

E coloque os notebooks como caixas no topo (orquestradores):
- `Quantum_Finance_DualQ.ipynb` orquestra A + parte de B (QAOA/VQE Qiskit)
- `QAOA_myQLM.ipynb` orquestra C (QAOA myQLM)

##### Diagrama 2 — “Fluxo Detalhado (Dataflow)”
Expanda as etapas internas, principalmente:
- aquisição de preços
- cálculo de covariância/retornos
- construção da função custo (Markowitz / QUBO)
- execução iterativa de QAOA (p camadas) e registro de convergência

Esse segundo diagrama é onde você captura a “fidelidade científica” (o que realmente acontece no experimento).

Inclua explicitamente:

- **Rótulos claros**:
- “Market Data Provider”
- “Returns & Covariance”
- “Markowitz Optimizer”
- “QUBO/Ising Mapping”
- “QAOA (Qiskit)” / “VQE (Qiskit)” / “QAOA (myQLM)”
- “Simulator / IBM Quantum Backend” (se aplicável)
- “Convergence analysis vs layers p”
- “Efficient Frontier Plot”

- **Setas direcionais**:
- sólidas para fluxo de dados (prices → returns → model → solver → results)
- tracejadas para dependências de runtime (notebook → qiskit/myQLM)

- **Codificação visual (cores/formas)**, por exemplo:
- Cilindro: fontes de dados (mesmo que seja API)
- Retângulos: etapas de processamento/modelagem
- Hexágonos: “solvers/engines”
- Cor 1: clássico; Cor 2: Qiskit; Cor 3: myQLM

- “Local/Colab Environment”
- “External Services” (Market Data API, IBM Quantum)
- “myQLM stack” (rodando local)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Entry / Orchestration
  %% =========================
  subgraph "Execution Environment (Local / Colab)"
    direction TB
    Jupyter["Jupyter Notebook / Google Colab"]:::env
    Conda["Conda env (Python 3.9 for myQLM)"]:::env

    N1["Notebook Orchestrator: DualQ (Markowitz + QAOA/VQE via Qiskit)"]:::notebook
    N2["Notebook Orchestrator: myQLM (QAOA + convergence vs layers p)"]:::notebook
    Docs["Project Documentation / Setup (README)"]:::docs
  end

  %% =========================
  %% External Services
  %% =========================
  subgraph "External Services"
    direction TB
    MarketAPI[("Market Data Provider API")]:::externalData
    IBMQ["IBM Quantum Backend (optional)"]:::externalSvc
  end

  %% =========================
  %% Common Data & Modeling Pipeline
  %% =========================
  subgraph "Common Experiment Pipeline (Data → Stats → Modeling)"
    direction TB
    Inputs["Assets list + parameters\n(tickers, window, constraints, budget)"]:::input
    Prices["Price time series"]:::data
    Preproc["Pre-processing\n(clean/normalize)"]:::process
    Stats["Returns & Covariance\n(correlation, Σ, μ)"]:::process

    subgraph "Optimization Modeling"
      direction TB
      MarkowitzModel["Markowitz formulation\n(risk/return + constraints)"]:::classic
      QuboMap["QUBO/Ising mapping\n(quantum formulation)"]:::quantumModel
    end
  end

  %% =========================
  %% Solvers / Engines
  %% =========================
  subgraph "Solvers / Engines"
    direction TB

    subgraph "Classical Path"
      direction TB
      ClassicalOpt{{"Classical Optimizer\n(quadratic programming / heuristics)"}}:::classicSolver
      ClassicalSol["Portfolio solution\n(weights)"]:::solution
    end

    subgraph "Quantum Path (Qiskit)"
      direction TB
      QiskitLib["Qiskit Runtime"]:::qiskit
      QAOA_Qiskit{{"QAOA (Qiskit)"}}:::qiskitSolver
      VQE_Qiskit{{"VQE (Qiskit)"}}:::qiskitSolver
      QiskitBackend["Simulator / IBM Quantum Backend"]:::qiskitBackend
      QuantumSol_Qiskit["Quantum solution\n(bitstring / weights / energy)"]:::solution
    end

    subgraph "Quantum Path (myQLM)"
      direction TB
      MyQLMStack["myQLM Stack"]:::myqlm
      QAOA_myQLM{{"QAOA (myQLM)"}}:::myqlmSolver
      MyQLMBackend["myQLM Simulator / QPU (if available)"]:::myqlmBackend
      QuantumSol_myQLM["Quantum solution\n(bitstring / weights / energy)"]:::solution
    end
  end

  %% =========================
  %% Evaluation & Outputs
  %% =========================
  subgraph "Evaluation & Outputs"
    direction TB
    Eval["Evaluation & Comparison\n(classical vs quantum)"]:::eval
    Frontier["Efficient Frontier Plot"]:::viz
    Convergence["Convergence analysis vs layers p\n(energy/cost vs p, gap)"]:::viz
    Tables["Result tables\n(weights, selected assets, metrics)"]:::output
  end

  %% =========================
  %% Dataflow Connections (solid)
  %% =========================
  N1 -->|"defines_inputs"| Inputs
  N2 -->|"defines_inputs"| Inputs

  Inputs -->|"fetch_prices"| MarketAPI
  MarketAPI -->|"prices"| Prices

  Prices -->|"clean_and_normalize"| Preproc
  Preproc -->|"compute_stats"| Stats

  Stats -->|"build_classical_problem"| MarkowitzModel
  Stats -->|"build_quantum_problem"| QuboMap

  MarkowitzModel -->|"optimize"| ClassicalOpt
  ClassicalOpt -->|"weights"| ClassicalSol

  QuboMap -->|"solve"| QAOA_Qiskit
  QuboMap -->|"solve"| VQE_Qiskit
  QuboMap -->|"solve_iterative_p_layers"| QAOA_myQLM

  QAOA_Qiskit -->|"execute"| QiskitBackend
  VQE_Qiskit -->|"execute"| QiskitBackend
  QiskitBackend -->|"measurement/energy"| QuantumSol_Qiskit

  QAOA_myQLM -->|"execute"| MyQLMBackend
  MyQLMBackend -->|"measurement/energy"| QuantumSol_myQLM

  ClassicalSol -->|"evaluate"| Eval
  QuantumSol_Qiskit -->|"evaluate"| Eval
  QuantumSol_myQLM -->|"evaluate"| Eval

  Eval -->|"plot"| Frontier
  Eval -->|"plot"| Convergence
  Eval -->|"export"| Tables

  %% Optional external backend link
  QiskitBackend -.->|"optional_remote_execution"| IBMQ

  %% =========================
  %% Runtime/Dependency Connections (dashed)
  %% =========================
  Jupyter -.->|"runs"| N1
  Jupyter -.->|"runs"| N2
  Conda -.->|"env_for_myQLM"| MyQLMStack

  N1 -.->|"depends_on"| QiskitLib
  QiskitLib -.->|"provides_algorithms"| QAOA_Qiskit
  QiskitLib -.->|"provides_algorithms"| VQE_Qiskit
  QiskitLib -.->|"selects_backend"| QiskitBackend

  N2 -.->|"depends_on"| MyQLMStack
  MyQLMStack -.->|"provides_algorithms"| QAOA_myQLM
  MyQLMStack -.->|"selects_backend"| MyQLMBackend

  Docs -.->|"guides_setup"| Conda
  Docs -.->|"explains_context"| N1
  Docs -.->|"explains_context"| N2

  %% =========================
  %% Click Events (from component mapping)
  %% =========================
  click N1 "https://github.com/askery/computacao-quantica-aplicada-ao-mercado-financeiro/blob/main/Quantum_Finance_DualQ.ipynb"
  click N2 "https://github.com/askery/computacao-quantica-aplicada-ao-mercado-financeiro/blob/main/QAOA_myQLM.ipynb"
  click Docs "https://github.com/askery/computacao-quantica-aplicada-ao-mercado-financeiro/blob/main/README.md"

  %% =========================
  %% Styles
  %% =========================
  classDef notebook fill:#E3F2FD,stroke:#1565C0,stroke-width:2px,color:#0D47A1
  classDef docs fill:#FFF3E0,stroke:#EF6C00,stroke-width:2px,color:#E65100
  classDef env fill:#ECEFF1,stroke:#455A64,stroke-width:1.5px,color:#263238

  classDef externalData fill:#FCE4EC,stroke:#C2185B,stroke-width:2px,color:#880E4F
  classDef externalSvc fill:#F3E5F5,stroke:#6A1B9A,stroke-width:2px,color:#4A148C

  classDef input fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px,color:#1B5E20
  classDef data fill:#E8F5E9,stroke:#2E7D32,stroke-width:1.5px,color:#1B5E20
  classDef process fill:#E0F7FA,stroke:#00838F,stroke-width:2px,color:#004D40

  classDef classic fill:#FFFDE7,stroke:#F9A825,stroke-width:2px,color:#7A5A00
  classDef quantumModel fill:#EDE7F6,stroke:#5E35B1,stroke-width:2px,color:#311B92

  classDef classicSolver fill:#FFF9C4,stroke:#F57F17,stroke-width:3px,color:#6D4C41
  classDef qiskit fill:#E1F5FE,stroke:#0277BD,stroke-width:2px,color:#01579B
  classDef qiskitSolver fill:#BBDEFB,stroke:#0D47A1,stroke-width:3px,color:#0D47A1
  classDef qiskitBackend fill:#B3E5FC,stroke:#0288D1,stroke-width:2px,color:#01579B

  classDef myqlm fill:#F1F8E9,stroke:#558B2F,stroke-width:2px,color:#33691E
  classDef myqlmSolver fill:#DCEDC8,stroke:#33691E,stroke-width:3px,color:#1B5E20
  classDef myqlmBackend fill:#C5E1A5,stroke:#558B2F,stroke-width:2px,color:#1B5E20

  classDef solution fill:#FAFAFA,stroke:#616161,stroke-width:1.5px,color:#212121
  classDef eval fill:#FFF8E1,stroke:#FF8F00,stroke-width:2px,color:#E65100
  classDef viz fill:#FBE9E7,stroke:#D84315,stroke-width:2px,color:#BF360C
  classDef output fill:#F5F5F5,stroke:#424242,stroke-width:2px,color:#212121
```
