Metadata-Version: 2.4
Name: biblioteca_qw
Version: 0.2.6
Summary: Simulacao de caminhadas quanticas discretas em grafos toroidais n-dimensionais
Author-email: Igor <igorgomesdeoliveira@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Igoro2016/biblioteca_qw
Project-URL: Repository, https://github.com/Igoro2016/biblioteca_qw
Project-URL: Bug Tracker, https://github.com/Igoro2016/biblioteca_qw/issues
Keywords: quantum walk,quantum computing,graph theory,toroidal graph,simulation,physics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.21
Requires-Dist: requests>=2.26
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.5; extra == "viz"
Provides-Extra: all
Requires-Dist: biblioteca-qw[dev,viz]; extra == "all"

# 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

```bash
pip install "biblioteca-qw[viz]"
```

### Instalação para desenvolvimento

```bash
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.

```python
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.

```python
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)
```

```python
# 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.

```python
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)
```

```python
# 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:**

```python
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⟩`.

```python
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:**

```python
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](https://github.com/typicode/json-server) via HTTP POST:

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

```python
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

```python
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)

```python
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

```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)
