biblioteca-qw 0.1.1

Simulacao de caminhadas quanticas discretas em grafos toroidais n-dimensionais

biblioteca-qw

Biblioteca Python para simulação de caminhadas quânticas discretas (DTQW) em grafos toroidais n-dimensionais, com suporte a vértices marcados (oráculo de Grover), persistência de resultados via JSON Server e exportação CSV/JSON.

---

Instalação

pip install biblioteca-qw

Com dependências de visualização

pip install "biblioteca-qw[viz]"

Instalação para desenvolvimento

git clone https://github.com/Igoro2016/biblioteca_qw.git
cd biblioteca_qw
pip install -e ".[dev]"

---

Uso rápido

from biblioteca_qw import QuantumWalkSimulation, to_csv, print_summary

# Configurar a simulação
sim = QuantumWalkSimulation(
    L=3,                     # 3 vértices por dimensão
    n=2,                     # grafo toroidal 2D (3x3 = 9 vértices)
    num_selfloop=1,          # 1 self-loop por vértice
    t_f=3500,                # 3500 passos de simulação
    weight_value=1.0,        # peso das arestas
    marked_vertices=[0, 1]  # vértices marcados (oráculo)
)

# Executar
probs, det_times = sim.run()

# Exportar resultados
to_csv(probs, det_times, "probs.csv", "det_times.csv")

# Resumo
print_summary(probs, det_times)

Com persistência REST (JSON Server)

# Instale e inicie o JSON Server
npm install -g json-server
json-server --watch db.json

sim = QuantumWalkSimulation(
    L=3, n=2, num_selfloop=1, t_f=100,
    weight_value=1.0, marked_vertices=[0],
    db_url="http://localhost:3000"   # habilita persistência REST
)
probs, det_times = sim.run()

---

Parâmetros

Parâmetro	Tipo	Descrição
L	int	Vértices por dimensão (≥ 2)
n	int	Número de dimensões (≥ 1)
num_selfloop	int	Self-loops por vértice (≥ 0)
t_f	int	Passos de simulação (≥ 1)
weight_value	float	Peso das arestas
marked_vertices	list[int]	Índices dos vértices marcados
db_url	str | None	URL do JSON Server (opcional)

---

Resultados

Array	Shape	Descrição
probs	(t_f, N)	Probabilidade por vértice em cada passo
det_times	(t_f,)	Probabilidade de detecção acumulada nos marcados

---

API

from biblioteca_qw import (
    QuantumWalkSimulation,   # simulador principal
    adjacency_matrix,        # matriz de adjacência do grafo toroidal
    degree,                  # grau dos vértices
    spectral_gap,            # gap espectral do laplaciano
    summary,                 # estatísticas dos resultados
    to_csv, to_json,         # exportação
    load_csv,                # carregamento
    print_summary,           # impressão formatada
)

---

Modelo matemático

A biblioteca implementa caminhadas quânticas discretas no espaço de Hilbert:

H = H_P ⊗ H_C

onde H_P é o espaço de posição (dim = L^n) e H_C é o espaço de moeda (dim = 2n + num_selfloop).

O operador de evolução é U = S · C_oracle, onde:

• S: operador de deslocamento condicional
• C_oracle: moeda de Grover nos vértices normais; moeda oráculo (−I) nos marcados

---

Testes

pytest tests/ -v
pytest tests/ --cov=biblioteca_qw --cov-report=term-missing

---

Licença

MIT © Igor (2025)