primepath 0.1.1

A geometric investigation of prime numbers — composite terrain, 3D visibility, Boltzmann entropy, and gap prediction

PrimePath

A geometric investigation of prime numbers — treating composites as terrain and primes as the path navigating it.

Not a faster primality test. A new way of seeing why primes live where they do, connecting number theory to statistical mechanics, wave physics, and 3D visibility geometry.

---

Installation

pip install primepath

Requires Python ≥ 3.9 and sympy, numpy (installed automatically).

---

Quick start

from primepath import Pipeline

p = Pipeline()

# Predict the next prime after 499 979
result = p.predict_next(499_979)
print(result)
# {'predicted': 499993, 'confidence': 0.54, 'class': 'S',
#  'gap_range': (0, 2), 'method': 'sight+ensemble',
#  'candidates': [{'n': 499993, 'sight_score': 0.06, 'gap': 14, 'is_prime': True}, ...]}

# Score the corridor clarity to a specific candidate
p.sight_score(499_979, 499_993)       # → 0.06  (clear corridor → prime)
p.sight_score(499_979, 499_991)       # → 0.44  (blocked → composite)

# Full explanation of all five signals
p.explain(499_979)
# {
#   'entropy':        3.582,
#   'boltzmann':      ('S', 0.38, {'S': 0.38, 'M': 0.34, 'L': 0.28}),
#   'detrended_mean': 0.14,
#   'gap_mean':       ('S', 0.41, {...}),
#   'pi_phase':       0.7823,
#   'sight_score_r0': 0.06,
#   'sight_class':    'S',
#   'combined':       ('S', 0.44, {...}),
# }

# Ranked candidate list (sorted by corridor clarity)
p.rank_candidates(499_979, n=5)
# [{'n': 499993, 'sight_score': 0.06, 'gap': 14, 'is_prime': True},
#  {'n': 500009, 'sight_score': 0.31, 'gap': 30, 'is_prime': True},
#  ...]

---

The five signals

Signal	Standalone accuracy	What it measures
Mod-60 wheel	3.75× speedup (filter only)	Coprime residues — eliminates 73.3%
Boltzmann entropy	35.2% (+7.2pp)	Spoke disorder — "temperature" of the sequence
Gap mean trend	34.2% (+6.5pp)	Momentum — oversold/overbought condition
3D sight score	42.4% (+14.4pp)	Corridor density in the composite solid
π-phase + 2D phase	+4–6pp	Irrational mixing, helix phase space
Five-signal ensemble	48.99%	≈ theoretical ceiling (48.94%)

All three primary signals are mutually independent (cross-correlations < 0.02).

---

Module reference

primepath.wheel — the mod-60 filter

from primepath import is_valid_spoke, candidates, wheel_info

is_valid_spoke(97)      # → True  (97 % 60 = 37 ∈ SPOKES)
is_valid_spoke(99)      # → False (99 % 60 = 39, gcd(39,60) = 3)

candidates(90, 130)     # → [91, 97, 101, 103, 107, 109, 113]
wheel_info()
# {'period': 60, 'valid_spokes': [1,7,11,...,59], 'n_valid': 16,
#  'elimination_rate': 0.7333, 'speedup_factor': 3.75}

primepath.sight — 3D visibility

from primepath import helix_pos, corridor_density, sight_score, rank_by_sight, frenet_frame

# 3D position on the helix
helix_pos(97)     # → (x, y, z) on equal-scale helix at ring=1, spoke=37

# Corridor density from 97 toward 101
corridor_density(helix_pos(97), helix_pos(101))   # → ~0.04  (clear)
corridor_density(helix_pos(97), helix_pos(99))    # → ~0.45  (blocked)

# Convenience wrapper
sight_score(97, 101)   # → 0.04

# Frenet frame: local T, N, B vectors at prime b given previous prime a
T, N, B = frenet_frame(89, 97)

# Ranked candidates
rank_by_sight(97, n_candidates=5)

primepath.boltzmann — entropy classifiers

from primepath import spoke_entropy, boltzmann_class, gap_mean_class, combined_class

# Spoke entropy of a prime window
from sympy import primerange
window = list(primerange(80, 120))
H = spoke_entropy(window)   # → 3.58...

# Predict gap class from entropy
boltzmann_class(3.572)   # → ('L', 0.38, {'S': 0.31, 'M': 0.31, 'L': 0.38})
boltzmann_class(3.586)   # → ('S', 0.37, {'S': 0.37, 'M': 0.34, 'L': 0.29})

# Gap mean (detrended, RSI-style)
gap_mean_class(-0.25)    # → ('L', 0.37, {...})  # below trend → large gap
gap_mean_class(+0.20)    # → ('S', 0.40, {...})  # above trend → small gap

# Combined
combined_class(3.575, -0.15)

primepath.terrain — composite landscape

from primepath import composite_density, valley_width, terrain_zone, terrain_map, sieve_ridges

composite_density(97)        # → 0.43  (valley)
composite_density(100)       # → 0.65  (ridge)
terrain_zone(0.43)           # → 'valley'

valley_width(97)             # → 42  (wide valley → small next gap)

# Full terrain grid around a point
cells = terrain_map(97, ring_radius=2, spoke_radius=2)
# [{'ring': 1, 'spoke': 1, 'n': 61, 'is_prime': True,
#   'density': 0.42, 'zone': 'valley'}, ...]

# Composite cells blocked by small prime 7
sieve_ridges(7, max_rings=5)

---

Honest assessment

This is a position predictor, not a primality test.

• When it predicts correctly (~49% of the time), it saves one Miller-Rabin call.
• When wrong, fall back to the standard wheel + Miller-Rabin pipeline.
• The net effect on prime generation speed is slightly negative (37 µs for the sight computation vs 1.8 µs for Miller-Rabin).

Algorithm	Speed	Memory	Error rate	Use case
Mod-60 wheel	0.05 µs	O(1)	73.3% pass-through	Pre-filter
Miller-Rabin ×4	1.8 µs	O(1)	< 10⁻²⁴	Production primality test
Our pipeline	37 µs	~50 KB	Not a primality test	Research / prediction

The value of this library is the structural understanding — the three independent signals (state, momentum, position) that explain why primes sit where they do, rather than a speed improvement over established algorithms.

---

Visualisers

Sixteen interactive HTML visualisers are available at: viewbuild.com/primepath

---

Licence

MIT — see LICENSE.

Built at ViewBuild, Tasmania, Australia.