Metadata-Version: 2.4
Name: primepath
Version: 0.1.0
Summary: A geometric investigation of prime numbers — composite terrain, 3D visibility, Boltzmann entropy, and gap prediction
Author-email: ViewBuild <hello@viewbuild.com>
License: MIT License
        
        Copyright (c) 2026 ViewBuild
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://viewbuild.com/primepath
Project-URL: Repository, https://github.com/viewbuild/primepath
Project-URL: Issues, https://github.com/viewbuild/primepath/issues
Keywords: primes,number-theory,mathematics,geometry,visualisation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
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: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sympy>=1.12
Requires-Dist: numpy>=1.24
Provides-Extra: viz
Requires-Dist: matplotlib>=3.7; extra == "viz"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

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

[![PyPI](https://img.shields.io/pypi/v/primepath)](https://pypi.org/project/primepath/)
[![Python](https://img.shields.io/pypi/pyversions/primepath)](https://pypi.org/project/primepath/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## Installation

```bash
pip install primepath
```

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

---

## Quick start

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

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

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

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

```python
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](https://viewbuild.com/primepath)**

---

## Licence

MIT — see [LICENSE](LICENSE).

Built at [ViewBuild](https://viewbuild.com), Tasmania, Australia.
