Metadata-Version: 2.1
Name: begump
Version: 0.8.1
Summary: K, R, E, T — Four quantities. One framework. Everything computable.
Home-page: https://github.com/LacobusGump/gump
Author: Jim McCandless
Author-email: gump@begump.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Provides-Extra: full

# GUMP

**Four quantities. One framework. Everything computable.**

```
K = coupling strength     (how strongly things connect)
R = order parameter       (how synchronized they are)
E = energy cost           (what it costs in joules)
T = tension               (what wants to connect but hasn't)
```

Works on: chips, music, proteins, markets, compilers, memory, neural nets, primes, quantum circuits, organizations, and the body.

## Install

```bash
pip install gump
```

## Quick Start

```python
import gump

# Find what's missing in any graph
edges = [(0,1), (1,2), (2,3), (3,4)]
tensions = gump.tensions(5, edges)
# → [(dist, node_i, node_j, score), ...]

# Place anything optimally (spectral placement)
positions = gump.place(1000, edges, width=100, height=100)

# Track energy cost of computation
tracker = gump.EnergyTracker()
tracker.erase(1000000)  # 1M bits erased
print(tracker.summary())  # → {'bits_erased': 1000000, 'landauer_J': 2.87e-15}

# Detect market crashes
R_timeline = gump.detect_crash(stock_returns_list, window=30)

# Detect grokking in neural net training
grokked, epoch, jump = gump.watch_training(test_accuracies)

# Music: cost of any interval
fifth = gump.interval_cost(3, 2)    # 1.79 nats (cheap = consonant)
tritone = gump.interval_cost(45, 32) # 7.27 nats (expensive = dissonant)
```

## What It Does

### Tension Detection
Feed any graph. Get back what WANTS to connect but doesn't. 100% precision on circuit netlists. Found the circle of fifths from a consonance matrix. Found genre families from raw rhythm data.

### Spectral Placement
Place anything in 2D to minimize total wire length. 40 million nodes in 4.5 seconds. Same math that places transistors finds the optimal layout for any network.

### Energy Tracking
Every computation has a minimum energy cost (Landauer's principle). Track it. We're 35 trillion times above the limit. Understanding is 224,000× cheaper than memorization.

### Crash Detection
Monitor any correlated system. When the order parameter R drops below 1/φ = phase transition = crash imminent.

### Grok Detection
Monitor neural network training. When energy-per-correct-prediction drops off a cliff = the network just understood the pattern. Stop training. Save compute.

## The Science

Built on:
- **Laplacian eigenvectors** (spectral graph theory)
- **Kuramoto model** (coupled oscillator synchronization)
- **Landauer's principle** (thermodynamics of computation)
- **K = 1.868 = 256α** (universal coupling ceiling)

Discovered over 12 sessions on a $500 Mac Mini. Every result verified, benchmarked, and tested.

## Constants

```python
gump.K_CEILING        # 1.868 — universal coupling ceiling
gump.PHI              # 1.618... — golden ratio
gump.LANDAUER_PER_BIT # 2.87e-21 J — minimum cost per bit erasure at 300K
```

## License

MIT. Free forever. Good will is exothermic.

---

*"The body doesn't make music. The body IS music that hasn't been transposed to audible frequencies yet."*

— Jim McCandless, Dad, drummer, builder


