Metadata-Version: 2.4
Name: biblioteca-qw
Version: 0.1.1
Summary: Simulacao de caminhadas quanticas discretas em grafos toroidais n-dimensionais
Author-email: Igor <igor@example.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
License-File: LICENSE
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"
Dynamic: license-file

# 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 **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

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

---

## Uso rápido

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

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

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

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

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

---

## Licença

MIT © Igor (2025)
