Metadata-Version: 2.4
Name: biblioteca_qw
Version: 3.2
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"

<<<<<<< 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:
   ```bash
   pip install -r requirements.txt
   ```
3. Instale o JSON Server (Node.js):
   ```bash
   npm install -g json-server
   ```
4. Inicie o JSON Server:
   ```bash
   json-server --watch db.json
   ```

## Uso

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

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

[![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)**
| 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

```bash
pip install biblioteca-qw
```

### Com dependências de visualização

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