SQI (Simulador Quântico Interativo)

Comparação prática entre fatoração clássica e fatoração quântica (núcleo de Shor) com CLI, UI interativa e geração de relatórios técnicos

---

Documentação

A documentação técnica foi modularizada para facilitar onboarding, operação e manutenção.

• Índice da documentação
• Arquitetura
• Operação e Deploy
• Interface Web (Streamlit)
• Relatórios e Artefatos
• Testes
• Roadmap Técnico

---

Preview

Interface interativa disponível em simulador-quantico-ui:

• Arquivo principal: src/simulador_quantico/ui.py
• Acesso local: http://localhost:8501
• Fluxo: ajuste parâmetros (N, a, shots, n_counting), execute e compare resultados clássico vs quântico em tempo real.

---

Visão Geral

O SQI (Simulador Quântico Interativo) compara dois caminhos de fatoração:

• Clássico: divisão por tentativa com contagem de operações.
• Quântico: order-finding de Shor com saída probabilística e recuperação de fatores.

O projeto foi desenhado para estudo técnico, experimentação e geração de evidências visuais sobre comportamento algorítmico.

---

Principais Recursos

• CLI para execução reproduzível com parâmetros explícitos.
• UI em Streamlit com controles completos da simulação.
• Comparação de tempo e esforço computacional entre abordagens.
• Relatórios Markdown em múltiplos níveis (short, standard, detailed, paper).
• Geração automática de gráficos por execução.
• Saída versionada por timestamp em output/YYYY-MM-DD_HH-MM-SS.
• Execução local e em containers com Docker Compose.

---

Arquitetura

Fluxo principal:

1. cli.py recebe parâmetros e orquestra a execução.
2. core.py executa fatoração clássica, simulação quântica e cálculos de análise.
3. ui_logic.py centraliza a lógica de aplicação para a UI.
4. ui.py renderiza controles, métricas e gráficos no Streamlit.
5. Artefatos e relatório são persistidos em output/<timestamp>/.

Para detalhes: ARQUITETURA.md.

---

Performance

O projeto já coleta métricas suficientes para análise comparativa por execução:

• tempo clássico;
• tempo de construção quântica;
• tempo de simulação quântica;
• profundidade de circuito;
• distribuição de probabilidades medidas.

Não há benchmark oficial publicado no repositório até o momento.

---

Desafios Técnicos

• Balancear legibilidade didática com consistência matemática do fluxo de Shor.
• Tratar entradas inválidas de forma explícita na UI e na CLI.
• Normalizar artefatos de saída para facilitar auditoria de execuções.
• Manter separação de responsabilidades entre camada visual e camada de domínio.

---

Roadmap

Próximos passos recomendados:

• ampliar suíte de testes unitários e de integração;
• adicionar validações e mensagens orientadas a diagnóstico na UI;
• publicar benchmark versionado com metodologia reprodutível;
• evoluir documentação com guias de experimentos.

Roadmap detalhado: ROADMAP.md.

---

Stack

• Linguagem: Python 3.10+
• Computação quântica: Qiskit, Qiskit Aer
• Visualização: Matplotlib, Plotly
• Interface: Streamlit
• Dados tabulares: Pandas
• Empacotamento: setuptools (pyproject.toml)
• Containerização: Docker + Docker Compose

---

Estrutura do Projeto

.
├── src/
│   └── simulador_quantico/
│       ├── __init__.py
│       ├── __main__.py
│       ├── cli.py
│       ├── core.py
│       ├── ui.py
│       └── ui_logic.py
├── tests/
│   └── test_core.py
├── docs/
│   ├── README.md
│   ├── ARCHITECTURE.md
│   └── pt-br/
│       ├── ARQUITETURA.md
│       ├── OPERACAO.md
│       ├── INTERFACE_WEB.md
│       ├── RELATORIOS_E_ARTEFATOS.md
│       ├── TESTES.md
│       └── ROADMAP.md
├── output/
├── comparacao_fatoracao_quantica.py
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
├── requirements.txt
└── README.md

---

Como Rodar

Pré-requisitos

• Python 3.10+
• pip
• Docker 24+ e Docker Compose v2 (opcional)

Instalação local

pip install -e .

Ambiente de desenvolvimento:

pip install -e .[dev]

CLI

Execução padrão:

python -m simulador_quantico --sem-plot

Execução parametrizada:

python -m simulador_quantico --n 21 --a 2 --shots 4096 --n-counting 6 --report-mode detailed --sem-plot

Script legado:

python comparacao_fatoracao_quantica.py --sem-plot

Interface Web

simulador-quantico-ui

ou

streamlit run src/simulador_quantico/ui.py

---

Deploy

Docker build

docker build -t simulador-quantico:latest .

Docker run (CLI)

docker run --rm -u "$(id -u):$(id -g)" -v "$(pwd):/app" simulador-quantico:latest

Docker Compose

Inicialização padrão (somente UI, sem execução automática da simulação):

docker compose up --build

Somente UI:

docker compose up --build simulador-quantico-ui

Execução da simulação via serviço CLI (sob demanda):

docker compose run --rm simulador-quantico

Acesso:

• UI: http://localhost:8501

Parada dos serviços:

docker compose down

---

Licença

Este projeto é open source sob a licença MIT.

Consulte LICENSE.md para detalhes.

---

SQI (Simulador Quântico Interativo) — engenharia aplicada para aprendizado, análise e evolução incremental.