QuantumWalkSimulation 0.1.0__py3-none-any.whl

quantumwalksimulation/__init__.py

@@ -0,0 +1,32 @@
+"""
+QuantumWalkSimulation
+======================
+Nucleo generico de Multi-self-loop Lackadaisical Quantum Walk com
+Inversao Parcial de Fase (MSLQW-PPI), parametrizado por `base`, `degree`
+e `structure` -- uma unica funcao `qw()` cobre hipercubo e grade (e
+outras estruturas no futuro), com o shift escolhido por dispatcher
+interno (hamming para hipercubo, manhattan para grade).
+
+>>> from QuantumWalkSimulation import qw
+>>> r = qw(
+...     base=2, degree=3, num_selfloop=3, t_f=100,
+...     weight_value=1/8, marked_vertices=[0],
+...     inverted_self_loops=2, structure="hypercube",
+... )
+>>> r.probs.shape
+(100, 8)
+"""
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__: str = version("QuantumWalkSimulation")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.1.0"
+
+__author__ = "Igor"
+__license__ = "MIT"
+
+from QuantumWalkSimulation.core import qw, QWResult
+
+__all__ = ["qw", "QWResult"]

quantumwalksimulation/core.py

@@ -0,0 +1,281 @@
+"""
+qw_core.py
+==========
+Nucleo generico de MSLQW-PPI (Multi-self-loop Lackadaisical Quantum Walk
+com Inversao Parcial de Fase), parametrizado por `base`, `degree` e
+`structure`, conforme especificacao de Igor.
+
+Ideia central: a moeda lackadaisical (Eq. 12-13 do artigo de Souza et al.,
+arXiv:2305.19614) e o oraculo de inversao parcial (Eq. 18-26) sao os
+MESMOS independente da estrutura do grafo -- o que muda e apenas o
+operador de deslocamento (S), que depende de como os vertices se
+conectam. Por isso a funcao `qw()` decide, a partir de `structure`, qual
+"shift provider" usar:
+
+    structure == "hypercube" -> shift por distancia de Hamming (bit flip)
+    structure == "grid"      -> shift por distancia de Manhattan
+                                 (coordenada +-1, periodico/toroidal para
+                                 manter grau uniforme em todos os vertices
+                                 -- necessario porque a moeda lackadaisical
+                                 e a MESMA em todo vertice, o que exige
+                                 grau uniforme; grade com reflexao de
+                                 borda teria grau variavel e exigiria uma
+                                 moeda por vertice, fora do escopo do
+                                 MSLQW-PPI original)
+
+A moeda, o oraculo e o loop de evolucao ficam em UM SO lugar (nao
+duplicados por estrutura); so o shift e "plugavel".
+
+Interface
+---------
+    from qw_core import qw
+
+    # Hipercubo Q_3 -> N = 2**3 = 8 vertices
+    r = qw(
+        base=2, degree=3, num_selfloop=3, t_f=100,
+        weight_value=1/8, marked_vertices=[0],
+        inverted_self_loops=2, structure="hypercube",
+    )
+
+    # Grade 4x4 -> N = 4**2 = 16 vertices (degree=4 = grau 2*n_dims)
+    r = qw(
+        base=4, degree=4, num_selfloop=3, t_f=100,
+        weight_value=1/16, marked_vertices=[0],
+        inverted_self_loops=2, structure="grid",
+    )
+
+    r.probs, r.det_times    # mesmo formato de biblioteca_qw: (t_f, N) / (t_f,)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, List, Optional, Tuple
+
+import numpy as np
+
+
+# ---------------------------------------------------------------------------
+# Resultado
+# ---------------------------------------------------------------------------
+
+@dataclass
+class QWResult:
+    probs: np.ndarray
+    det_times: np.ndarray
+    structure: str
+    N: int
+    n_dims: int
+    coin_dim: int
+
+    def __iter__(self):
+        yield self.probs
+        yield self.det_times
+
+    @property
+    def peak_step(self) -> int:
+        return int(np.argmax(self.det_times))
+
+    @property
+    def peak_detection(self) -> float:
+        return float(self.det_times.max())
+
+
+# ---------------------------------------------------------------------------
+# Shift providers -- um por structure. Cada um recebe (N, n_dims, base) e
+# devolve uma funcao vetorizada shift(state) -> state (shape (N, coin_dim)),
+# que move as `n_dims`*2 ou `n_dims` primeiras colunas (arestas normais) e
+# preserva as colunas de self-loop.
+# ---------------------------------------------------------------------------
+
+def _hamming_shift_targets(N: int, n_dims: int) -> List[np.ndarray]:
+    """Hipercubo Q_n: degree = n_dims arestas, uma por bit invertido."""
+    return [np.arange(N) ^ (1 << d) for d in range(n_dims)]
+
+
+def _manhattan_shift_targets(N: int, n_dims: int, base: int) -> List[np.ndarray]:
+    """Grade base^n_dims periodica: degree = 2*n_dims arestas (+1/-1 por
+    dimensao). Coordenadas em base mista (digitos de 0..base-1)."""
+    strides = [base ** (n_dims - 1 - i) for i in range(n_dims)]
+    vertices = np.arange(N)
+    # decompoe cada vertice em digitos na base `base`
+    coords = np.zeros((N, n_dims), dtype=np.int64)
+    tmp = vertices.copy()
+    for i in range(n_dims):
+        coords[:, i] = tmp // strides[i]
+        tmp = tmp % strides[i]
+
+    targets = []
+    for dim in range(n_dims):
+        for delta in (+1, -1):
+            nc = coords.copy()
+            nc[:, dim] = (nc[:, dim] + delta) % base  # periodico (toroidal)
+            idx = np.zeros(N, dtype=np.int64)
+            for i in range(n_dims):
+                idx += nc[:, i] * strides[i]
+            targets.append(idx)
+    return targets
+
+
+_SHIFT_PROVIDERS: dict = {
+    "hypercube": _hamming_shift_targets,
+    "grid": _manhattan_shift_targets,
+}
+
+
+# ---------------------------------------------------------------------------
+# Moeda lackadaisical (identica para as duas estruturas, Eq. 12-13)
+# ---------------------------------------------------------------------------
+
+def _lackadaisical_sc(degree: int, m: int, l: float) -> np.ndarray:
+    coin_dim = degree + m
+    l_prime = l / m if m > 0 else 0.0
+    s_c = np.empty(coin_dim, dtype=complex)
+    s_c[:degree] = 1.0
+    if m > 0:
+        s_c[degree:] = np.sqrt(l_prime)
+    s_c /= np.sqrt(degree + l)
+    return s_c
+
+
+def _build_coin(degree: int, m: int, l: float) -> np.ndarray:
+    s_c = _lackadaisical_sc(degree, m, l)
+    coin_dim = degree + m
+    return 2.0 * np.outer(s_c, s_c.conj()) - np.eye(coin_dim, dtype=complex)
+
+
+def _oracle_mask(degree: int, m: int, s: int) -> np.ndarray:
+    coin_dim = degree + m
+    mask = np.zeros(coin_dim, dtype=bool)
+    mask[:degree] = True     # arestas normais sempre invertidas
+    mask[degree:degree + s] = True  # s dos m self-loops
+    return mask
+
+
+# ---------------------------------------------------------------------------
+# qw() -- funcao fabrica generica, com o dispatcher pedido:
+#   if structure == "grid":       shift = manhattan
+#   if structure == "hypercube":  shift = hamming
+# ---------------------------------------------------------------------------
+
+def qw(
+    *,
+    base: int,
+    degree: int,
+    num_selfloop: int,
+    t_f: int,
+    weight_value: float,
+    marked_vertices: List[int],
+    inverted_self_loops: int = 1,
+    structure: str,
+) -> QWResult:
+    """Executa a MSLQW-PPI generica na estrutura indicada.
+
+    Parameters
+    ----------
+    base : int
+        "L" da estrutura. N = base ** n_dims.
+        - hypercube: base DEVE ser 2 (hipercubo binario Q_n).
+        - grid: qualquer base >= 2 (grade base x base x ... periodica).
+    degree : int
+        Grau do vertice (numero de arestas "normais" da moeda).
+        - hypercube: degree == n_dims (grau de Q_n e n).
+        - grid: degree == 2 * n_dims (grau de uma grade n-dimensional
+          periodica), portanto deve ser par.
+    num_selfloop : int
+        Numero m de self-loops por vertice (>= 0).
+    t_f : int
+        Passos de simulacao.
+    weight_value : float
+        Peso l do self-loop (Eq. 13). Ignorado se num_selfloop == 0.
+    marked_vertices : list[int]
+        Vertices marcados, indices em [0, N).
+    inverted_self_loops : int
+        s: quantos dos m self-loops tem a fase invertida no oraculo,
+        1 <= s <= num_selfloop (Eq. 18-26). Ignorado se num_selfloop == 0.
+    structure : {"hypercube", "grid"}
+        Estrutura do grafo -- decide o shift usado (dispatcher).
+
+    Returns
+    -------
+    QWResult com .probs (t_f, N), .det_times (t_f,), .peak_step, .peak_detection.
+    """
+    if structure not in _SHIFT_PROVIDERS:
+        raise ValueError(
+            f"structure={structure!r} nao suportada. "
+            f"Use uma de {list(_SHIFT_PROVIDERS)}."
+        )
+    if t_f < 1:
+        raise ValueError("t_f deve ser >= 1.")
+    if num_selfloop < 0:
+        raise ValueError("num_selfloop deve ser >= 0.")
+
+    # ---------------- dispatcher: deriva n_dims e os shift targets -------
+    if structure == "hypercube":
+        if base != 2:
+            raise ValueError("structure='hypercube' exige base=2 (Q_n binario).")
+        n_dims = degree
+        N = base ** n_dims
+        shift_targets = _hamming_shift_targets(N, n_dims)
+    else:  # "grid"
+        if degree % 2 != 0:
+            raise ValueError(
+                "structure='grid': degree deve ser par (degree = 2*n_dims)."
+            )
+        n_dims = degree // 2
+        N = base ** n_dims
+        shift_targets = _manhattan_shift_targets(N, n_dims, base)
+
+    m = num_selfloop
+    coin_dim = degree + m
+
+    if m > 0:
+        if not (1 <= inverted_self_loops <= m):
+            raise ValueError(
+                f"inverted_self_loops deve estar em [1, num_selfloop={m}]; "
+                f"recebido {inverted_self_loops}."
+            )
+        l = float(weight_value)
+        C = _build_coin(degree, m, l)
+        oracle = _oracle_mask(degree, m, inverted_self_loops)
+    else:
+        s_c = np.full(degree, 1.0 / np.sqrt(degree), dtype=complex)
+        C = 2.0 * np.outer(s_c, s_c.conj()) - np.eye(degree, dtype=complex)
+        oracle = np.ones(degree, dtype=bool)
+
+    marked_mask = np.zeros(N, dtype=bool)
+    marked_mask[marked_vertices] = True
+
+    # ---------------- estado inicial (Eq. 14-15) --------------------------
+    if m > 0:
+        s_c0 = _lackadaisical_sc(degree, m, float(weight_value))
+    else:
+        s_c0 = np.full(degree, 1.0 / np.sqrt(degree), dtype=complex)
+    state = np.tile(s_c0, (N, 1)) / np.sqrt(N)   # shape (N, coin_dim)
+
+    # ---------------- loop de evolucao (identico p/ qualquer structure) --
+    probs = np.empty((t_f, N), dtype=float)
+    det_times = np.empty(t_f, dtype=float)
+
+    for t in range(t_f):
+        # oraculo
+        state = state.copy()
+        state[np.ix_(marked_mask, oracle)] *= -1.0
+        # moeda
+        state = state @ C.T
+        # shift (plugavel: hamming ou manhattan)
+        new_state = np.empty_like(state)
+        for d, targets in enumerate(shift_targets):
+            new_state[targets, d] = state[:, d]
+        if coin_dim > degree:
+            new_state[:, degree:] = state[:, degree:]  # self-loops nao movem
+        state = new_state
+
+        vertex_probs = np.sum(np.abs(state) ** 2, axis=1)
+        probs[t] = vertex_probs
+        det_times[t] = float(np.sum(vertex_probs[marked_mask]))
+
+    return QWResult(
+        probs=probs, det_times=det_times,
+        structure=structure, N=N, n_dims=n_dims, coin_dim=coin_dim,
+    )

quantumwalksimulation-0.1.0.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: QuantumWalkSimulation
+Version: 0.1.0
+Summary: Simulacao generica de caminhadas quanticas discretas (MSLQW-PPI) por dispatcher de estrutura (hipercubo, grade, ...)
+Author-email: Igor <igorgomesdeoliveira@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Igoro2016/QuantumWalkSimulation
+Project-URL: Repository, https://github.com/Igoro2016/QuantumWalkSimulation
+Project-URL: Bug Tracker, https://github.com/Igoro2016/QuantumWalkSimulation/issues
+Keywords: quantum walk,quantum computing,hypercube,grid,lackadaisical,simulation,physics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Physics
+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
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+# QuantumWalkSimulation
+
+Simulacao generica de caminhadas quanticas discretas (MSLQW-PPI —
+Multi-self-loop Lackadaisical Quantum Walk com Inversao Parcial de Fase,
+Souza et al., arXiv:2305.19614) via uma unica funcao `qw()`, parametrizada
+por `base`, `degree` e `structure`. A moeda lackadaisical e o oraculo de
+inversao parcial sao os mesmos independente da estrutura; apenas o
+deslocamento (shift) muda, escolhido internamente por dispatcher:
+
+- `structure="hypercube"` -> shift por distancia de Hamming (bit flip)
+- `structure="grid"`      -> shift por distancia de Manhattan (grade periodica)
+
+## Instalacao
+
+```bash
+pip install QuantumWalkSimulation
+```
+
+## Uso
+
+```python
+from QuantumWalkSimulation import qw
+
+# Hipercubo Q_3 (N = 2**3 = 8 vertices)
+r = qw(
+    base=2, degree=3, num_selfloop=3, t_f=100,
+    weight_value=1/8, marked_vertices=[0],
+    inverted_self_loops=2, structure="hypercube",
+)
+
+# Grade 4x4 (N = 4**2 = 16 vertices; degree = 2*n_dims)
+r = qw(
+    base=4, degree=4, num_selfloop=3, t_f=100,
+    weight_value=1/16, marked_vertices=[0],
+    inverted_self_loops=2, structure="grid",
+)
+
+r.probs        # (t_f, N)
+r.det_times    # (t_f,)
+r.peak_detection
+r.peak_step
+```
+
+## Parametros
+
+| Parametro | Tipo | Descricao |
+|---|---|---|
+| `base` | `int` | N = base ** n_dims. Hipercubo exige base=2. |
+| `degree` | `int` | Grau do vertice. Hipercubo: degree = n_dims. Grade: degree = 2 * n_dims (par). |
+| `num_selfloop` | `int` | m self-loops por vertice. |
+| `t_f` | `int` | Passos de simulacao. |
+| `weight_value` | `float` | Peso l do self-loop. |
+| `marked_vertices` | `list[int]` | Vertices marcados. |
+| `inverted_self_loops` | `int` | s: quantos dos m self-loops tem fase invertida (1 <= s <= m). |
+| `structure` | `str` | `"hypercube"` ou `"grid"`. |
+
+## Licenca
+
+MIT

quantumwalksimulation-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+quantumwalksimulation/__init__.py,sha256=McywndM1vEmZdmRHEOK9MuGRdYc4D4T86qh93yPIIQI,945
+quantumwalksimulation/core.py,sha256=hqierKKamTQcB5pimiEWUaZDSz5uRsUBZizD4ppnFmE,10010
+quantumwalksimulation-0.1.0.dist-info/METADATA,sha256=jIIFJZplg-oPxSobpNi0tb4H0uwA6RMEarzR5wWlpCM,3237
+quantumwalksimulation-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+quantumwalksimulation-0.1.0.dist-info/top_level.txt,sha256=QZ4x03PHsIiOoKo5VpWaZdSbxy5RdQxm956c6IjzJhg,22
+quantumwalksimulation-0.1.0.dist-info/RECORD,,

quantumwalksimulation-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

quantumwalksimulation-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+quantumwalksimulation