biblioteca-qw 3.5.0

Simulacao de caminhadas quanticas discretas em grafos toroidais, grades, hipercubos e grafos arbitrarios

biblioteca-qw

Biblioteca Python para simulação de caminhadas quânticas discretas (DTQW) em múltiplas topologias de grafos: toroidal, grade, grafo arbitrário e hipercubo n-dimensional. Suporta vértices marcados com 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]"

---

Topologias disponíveis

🔁 Toroidal — QuantumWalkSimulation

Grafo toroidal n-dimensional T(L, n) com condições de contorno periódicas. Grau uniforme 2n + num_selfloop. Moeda de Grover e oráculo de Grover.

from biblioteca_qw import QuantumWalkSimulation, to_csv, print_summary

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

to_csv(probs, det_times, "probs.csv", "det_times.csv")
print_summary(probs, det_times)

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)

---

📐 Grade — GridWalkSimulation

Grade finita n-dimensional sem periodicidade. Vértices nas bordas recebem moeda de reflexão: a amplitude é refletida de volta em vez de atravessar a borda.

from biblioteca_qw import GridWalkSimulation

sim = GridWalkSimulation(
    dims=[4, 4],            # grade 4×4 → 16 vértices
    t_f=100,
    marked_vertices=[0],
)
probs, det_times = sim.run()  # probs.shape == (100, 16)

# Grade 3D
sim = GridWalkSimulation(dims=[3, 4, 5], t_f=50, marked_vertices=[0])
probs, det_times = sim.run()  # probs.shape == (50, 60)

Parâmetro	Tipo	Descrição
dims	list[int]	Tamanho de cada dimensão (cada ≥ 2)
t_f	int	Passos de simulação (≥ 1)
marked_vertices	list[int]	Índices lineares dos vértices marcados
weight_value	float	Peso das arestas (padrão: 1.0)
db_url	str | None	URL do JSON Server (opcional)

---

🕸️ Grafo arbitrário — GraphWalkSimulation

Grafo não necessariamente regular, definido por lista de arestas ou matriz de adjacência. Usa a formulação de Szegedy sobre arestas orientadas — unitariedade garantida para qualquer grafo conexo não-direcionado.

from biblioteca_qw import GraphWalkSimulation

# Por lista de arestas (ciclo C6)
sim = GraphWalkSimulation(
    N=6,
    edges=[(0,1),(1,2),(2,3),(3,4),(4,5),(5,0)],
    t_f=50,
    marked_vertices=[0],
)
probs, det_times = sim.run()  # probs.shape == (50, 6)

# Por matriz de adjacência
import numpy as np
A = np.array([
    [0, 1, 1, 0],
    [1, 0, 1, 1],
    [1, 1, 0, 1],
    [0, 1, 1, 0],
], dtype=float)

sim = GraphWalkSimulation.from_adjacency(A, t_f=50, marked_vertices=[0])
probs, det_times = sim.run()

Parâmetro	Tipo	Descrição
N	int	Número de vértices (≥ 2)
edges	list[(int,int)]	Arestas não-orientadas
t_f	int	Passos de simulação (≥ 1)
marked_vertices	list[int]	Índices dos vértices marcados
weight_value	float	Peso uniforme das arestas (padrão: 1.0)
db_url	str | None	URL do JSON Server (opcional)

Propriedades:

sim.num_edges           # número de arestas não-orientadas
sim.adjacency_matrix()  # np.ndarray (N, N)

---

🧊 Hipercubo — HypercubeWalkSimulation

Hipercubo n-dimensional Q_n: N = 2ⁿ vértices, grau uniforme n. Cada vértice é representado como inteiro (seus bits codificam as coordenadas). O operador de deslocamento usa flip de bit: S|v, d⟩ = |v XOR eₐ, d⟩.

from biblioteca_qw import HypercubeWalkSimulation

sim = HypercubeWalkSimulation(
    n=4,                     # Q_4 → 16 vértices, grau 4
    t_f=100,
    marked_vertices=[0, 15], # vértices antipodais 0000 e 1111
)
probs, det_times = sim.run()  # probs.shape == (100, 16)

Parâmetro	Tipo	Descrição
n	int	Dimensão do hipercubo (≥ 1); N = 2ⁿ
t_f	int	Passos de simulação (≥ 1)
marked_vertices	list[int]	Índices dos vértices marcados ∈ [0, 2ⁿ−1]
num_selfloop	int	Self-loops adicionais (padrão: 0)
weight_value	float	Peso das arestas (padrão: 1.0)
db_url	str | None	URL do JSON Server (opcional)

Utilitários específicos:

sim.vertex_to_binary(5)      # '0101'  — representação binária de n bits
sim.hamming_distance(0, 15)  # 4       — distância de Hamming entre vértices
sim.antipodal(0)             # 15      — vértice oposto (todos os bits invertidos)
sim.diameter                 # 4       — diâmetro do hipercubo = n

---

Resultados (todas as topologias)

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

---

Persistência de resultados

Todas as classes aceitam o parâmetro db_url para envio automático ao JSON Server via HTTP POST:

npm install -g json-server
json-server --watch db.json

sim = HypercubeWalkSimulation(
    n=3, t_f=100, marked_vertices=[0],
    db_url="http://localhost:3000"
)
probs, det_times = sim.run()  # resultados enviados automaticamente

---

API de análise e exportação

from biblioteca_qw import (
    summary,       # dict com mean/max/min detection, peak_step, etc.
    to_csv,        # salva probs e det_times em arquivos CSV
    to_json,       # salva probs e det_times em arquivos JSON
    load_csv,      # carrega resultados previamente salvos
    print_summary, # imprime resumo formatado no stdout
)

probs, det_times = sim.run()

s = summary(probs, det_times)
# {'mean_detection': ..., 'max_detection': ..., 'peak_step': ..., ...}

to_csv(probs, det_times, "probs.csv", "det_times.csv")
to_json(probs, det_times, "probs.json", "det_times.json")

probs2, det2 = load_csv("probs.csv", "det_times.csv")

print_summary(probs, det_times)
# ==================================================
#   Resumo da Simulacao - biblioteca_qw
# ==================================================
#   Passos totais     : 100
#   Vertices          : 8
#   Det. media        : 0.123456
#   Det. maxima       : 0.456789  (passo 42)

---

API de grafos (topologia toroidal)

from biblioteca_qw import (
    adjacency_matrix,  # matriz de adjacência do toroidal T(L, n)
    degree,            # grau uniforme dos vértices
    laplacian_matrix,  # laplaciano L = D - A
    spectral_gap,      # gap espectral do laplaciano
    vertex_list,       # lista de coordenadas de todos os vértices
)

A  = adjacency_matrix(L=3, n=2)        # shape (9, 9)
d  = degree(L=3, n=2, num_selfloop=1)  # 5
sg = spectral_gap(L=4, n=2)            # float
vl = vertex_list(L=3, n=2)             # [(0,0),(0,1),...,(2,2)]

---

Modelo matemático

A biblioteca implementa DTQW no espaço de Hilbert H = H_P ⊗ H_C, onde H_P é o espaço de posição e H_C o espaço de moeda.

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

Componente	Descrição
S	Operador de deslocamento condicional (específico por topologia)
C_oracle	Moeda de Grover nos vértices normais; moeda oráculo (−I) nos marcados

Topologia	Vértices N	Dim. moeda	Operador S
Toroidal T(L, n)	Lⁿ	2n + sl	deslocamento periódico
Grade n-D	∏ dims	2n	reflexão de borda
Grafo geral	|arestas orientadas|	—	swap de aresta (Szegedy)
Hipercubo Q_n	2ⁿ	n + sl	flip de bit

---

Testes

# Todos os testes (4 arquivos, ~90 casos)
pytest tests/ -v

# Com cobertura
pytest tests/ --cov=biblioteca_qw --cov-report=term-missing

# Apenas as topologias novas
pytest tests/test_topologies.py -v

---

Licença

MIT © Igor (2026)