topological-coherence 0.3.1

Toroidal topology primitives for LLM coherence research — Tonnetz geometry, spectral gap, attention masks, Karmonic spectral filter (v7: inference-time bias null, training-time valid)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

"""
Tonnetz topology on a 2D torus.

Mirrors the Rust `Tonnetz<N>` implementation:
- L1 (Manhattan) distance with wraparound
- Spectral gap of the torus Laplacian
- Vectorized distance matrix for attention integration

Pure numpy — no torch dependency for core geometry.
"""

import math
import numpy as np
from typing import Tuple


class Tonnetz:
    """Tonnetz topology on an N x N torus.

    The Tonnetz is a toroidal lattice originally from music theory
    (Euler, 1739). We use it as a constructive existence proof of a
    low-genus manifold with constant spectral gap.

    Args:
        grid_size: Side length N of the N x N torus (default 12).
    """

    def __init__(self, grid_size: int = 12):
        self.grid_size = grid_size

    @property
    def total_positions(self) -> int:
        """Total number of positions on the torus (N^2)."""
        return self.grid_size * self.grid_size

    def coordinates(self, index: int) -> Tuple[int, int]:
        """Convert linear index to 2D torus coordinates (row, col)."""
        n = self.grid_size
        return (index % n, (index // n) % n)

    def to_index(self, row: int, col: int) -> int:
        """Convert 2D torus coordinates to linear index."""
        n = self.grid_size
        return (row % n) + (col % n) * n

    def distance(self, i: int, j: int) -> int:
        """L1 toroidal distance between two linear indices.

        d_T(i, j) = min(|x_i - x_j|, N - |x_i - x_j|) + min(|y_i - y_j|, N - |y_i - y_j|)
        """
        n = self.grid_size
        xi, yi = self.coordinates(i)
        xj, yj = self.coordinates(j)
        dx = abs(xi - xj)
        dy = abs(yi - yj)
        return min(dx, n - dx) + min(dy, n - dy)

    def distance_coords(self, a: Tuple[int, int], b: Tuple[int, int]) -> int:
        """L1 toroidal distance between two coordinate pairs."""
        n = self.grid_size
        dx = abs(a[0] - b[0])
        dy = abs(a[1] - b[1])
        return min(dx, n - dx) + min(dy, n - dy)

    def spectral_gap(self) -> float:
        """First non-trivial eigenvalue of the torus Laplacian.

        For a 2D torus T^2_N:
            lambda_1 = 2 - 2*cos(2*pi/N) = Theta(1) for fixed N

        This constant spectral gap bounds drift decay.
        """
        return 2.0 - 2.0 * math.cos(2.0 * math.pi / self.grid_size)

    def decay_rate(self, t: float) -> float:
        """Spectral gap decay for non-resonant modes: e^(-lambda_1 * t)."""
        return math.exp(-self.spectral_gap() * t)


def distance_matrix(n_tokens: int, grid_size: int = 12) -> np.ndarray:
    """Vectorized toroidal distance matrix.

    Computes the full n_tokens x n_tokens L1 distance matrix on an
    N x N torus. O(n^2) but fully vectorized with numpy.

    Args:
        n_tokens: Number of tokens (rows/cols of output matrix).
        grid_size: Side length N of the torus.

    Returns:
        np.ndarray of shape (n_tokens, n_tokens) with integer distances.
    """
    idx = np.arange(n_tokens)
    x = idx % grid_size
    y = (idx // grid_size) % grid_size

    # Pairwise absolute differences
    dx = np.abs(x[:, None] - x[None, :])
    dy = np.abs(y[:, None] - y[None, :])

    # Wraparound
    dx = np.minimum(dx, grid_size - dx)
    dy = np.minimum(dy, grid_size - dy)

    return dx + dy