biblioteca-qw 3.2

No project description provided

<<<<<<< HEAD

Biblioteca de Caminhadas Quânticas em Grafos Toroidais

Esta biblioteca permite configurar e executar simulações de caminhadas quânticas em grafos toroidais, com armazenamento de resultados em JSON Server (db.json).

Instalação

1. Clone o repositório.
2. Instale as dependências:

   pip install -r requirements.txt
   

3. Instale o JSON Server (Node.js):

   npm install -g json-server
   

4. Inicie o JSON Server:

   json-server --watch db.json
   

Uso

from biblioteca.simulation import QuantumWalkSimulation
import numpy as np

# Parâmetros da simulação
sim = QuantumWalkSimulation(
    L=3,
    n=2,
    num_selfloop=1,
    t_f=3500,  # 3500 passos
    weight_value=1.0,
    marked_vertices=[0, 1]
=======
# biblioteca-qw

[![PyPI version](https://img.shields.io/pypi/v/biblioteca-qw.svg)](https://pypi.org/project/biblioteca-qw/)
[![Python](https://img.shields.io/pypi/pyversions/biblioteca-qw.svg)](https://pypi.org/project/biblioteca-qw/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Tests](https://github.com/Igoro2016/biblioteca_qw/actions/workflows/ci.yml/badge.svg)](https://github.com/Igoro2016/biblioteca_qw/actions)

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

```bash
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
>>>>>>> a51f098 (Commit inicial: versão 3.0.0)
)

probs, det_times = sim.run()

<<<<<<< HEAD
# Salvar resultados em CSV
np.savetxt('probs.csv', probs, delimiter=',')
np.savetxt('det_times.csv', det_times, delimiter=',')

Parâmetros

• L: dimensão da grade
• n: número de dimensões
• num_selfloop: self-loops por vértice
• t_f: passos de simulação
• weight_value: peso das arestas
• marked_vertices: lista de vértices marcados

Resultados

Os resultados são armazenados em arrays NumPy e enviados ao db.json via JSON Server.

Além disso, dois arquivos CSV são gerados para facilitar a análise:

• probs.csv: contém, em cada linha, as probabilidades de encontrar a partícula em cada vértice do grafo para cada passo da simulação.
• det_times.csv: contém, em cada linha, o tempo de detecção (em que passo a partícula foi detectada) para cada simulação.

Testes

---

|---|---|---|---|

biblioteca-qw

Biblioteca Python para simulação de caminhadas quânticas discretas (DTQW) | Toroidal T(L, n) | Lⁿ | 2n + sl | deslocamento periódico | 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]"
| 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

```bash
# 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 (2025)

a51f098 (Commit inicial: versão 3.0.0)