Metadata-Version: 2.4
Name: watkins-nn
Version: 3.4.0
Summary: Conservation-law constrained optimization on the golden-ratio simplex
Author-email: Dustin Watkins <dwatkins1989@yahoo.com>
License: MIT
Project-URL: Homepage, https://github.com/SleazyAirplane/watkins-nn
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0.0
Requires-Dist: numpy
Dynamic: license-file

# watkins-nn — The Watkins Conservation Law Framework

[![DOI](https://zenodo.org/badge/1178628599.svg)](https://doi.org/10.5281/zenodo.18953462)
[![CI](https://github.com/SleazyAirplane/watkins-nn/actions/workflows/ci.yml/badge.svg)](https://github.com/SleazyAirplane/watkins-nn/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/watkins-nn)](https://pypi.org/project/watkins-nn/)

## One Polynomial. Everything Follows.

The conservation law **λ + κ + η = 1** is not an axiom — it is a theorem of the golden ratio.

The minimal polynomial of φ² is **t² − 3t + 1 = 0**. Its coefficient gives 3 (the number of components). Its constant gives 1 (the conservation constraint). Its discriminant gives 5 (the golden ratio generator). Their product gives 15 (the algebraic bridge). From these four numbers, the entire framework is derived.

```
φ² = φ + 1
  → Tr(φ²) = φ² + φ̄² = 1² − 2(−1) = 3
  → N = 3 components
  → λ + κ + η = 1 (conservation law)
```

This package provides the mathematical implementation: 186 theorems from 3 axioms, 597 machine-verified proofs in Lean 4, and the algebraic structures connecting the golden ratio to conservation geometry.

## Key Results

**The Conservation Law (derived, not assumed):**

Six independent derivations prove N = 3 is the unique number of conservation law components forced by the golden ratio. The derivation uses Vieta's formulas, Adams operations, the Three-Distance Theorem, quantum SU(2) at the golden root, Fibonacci lattice gaps, and a self-consistency bootstrap.

**The Polynomial Tower:**

Each power φⁿ generates a conservation polynomial t² − L(n)·t + (−1)ⁿ = 0 where L(n) is the nth Lucas number. Even levels are palindromic (structure-preserving). Odd levels carry sign alternation (symmetry-breaking). The discriminant at level n is exactly 5·F(n)² — the golden discriminant scaled by Fibonacci squares.

**The Bridge Field Q(√3, √5):**

The conservation simplex is scaffolded by √3 (equilateral triangle height). The equilibrium threshold λ* = 1/φ = (√5−1)/2 is generated by √5. Their coexistence forces the biquadratic field Q(√3, √5) with Klein four-group V₄ as Galois group and three quadratic subfields: Q(√3), Q(√5), and Q(√15). The bridge element √15 = √3·√5 lives in both worlds simultaneously while being reducible to neither.

**Spectral Structure:**

The free energy F(λ,κ,η) = −ln(λ) + T*·Σpᵢ ln pᵢ has a unique minimum at the golden equilibrium (1/φ, (1−1/φ)/2, (1−1/φ)/2) with critical temperature T* = φ/ln(2φ) ≈ 1.3778. The Hessian eigenvalues μ_coh = (2/3)φ²(1+T*φ) ≈ 5.636 and μ_asym = 2T*φ² ≈ 7.214 govern exponential convergence. The coordinate eigenvalue ratio μ_fast/μ_slow approaches 2√3 to 0.0076%.

**Formal Verification:**

597 theorems verified in Lean 4 with zero sorry statements, zero Mathlib dependency, covering:
- Golden integer arithmetic Z[φ]
- Vieta identities and Newton's identity (Tr(φ²) = 3)
- Fibonacci/Lucas sequences and Binet formula
- Hierarchy exponent 75/4 = 3 × 25/4
- Discriminant tower Δₙ = 5·F(n)²
- Pell equation x² − 15y² = 1

## Installation

```bash
pip install watkins-nn
```

**Torch-free usage** (most modules work without PyTorch):
```bash
pip install watkins-nn --no-deps
```

## Quick Start

```python
import watkins_nn as wn

# The master polynomial: t² - 3t + 1 = 0
poly = wn.conservation_polynomial()
print(f"Coefficient: {poly['coefficient']}") # 3
print(f"Discriminant: {poly['discriminant']}") # 5
print(f"Bridge: {poly['bridge']}")            # 15

# Six derivations that N = 3
result = wn.derive_conservation_law()
print(f"N = {result.N}")  # 3
print(f"Routes agreeing: {result.routes_agreeing}")  # 6/6

# The polynomial tower
for n in range(7):
    level = wn.polynomial_tower(n)
    print(f"Level {n}: t² - {level.lucas_n}t + {level.norm} = 0, Δ = {level.discriminant}")

# Bridge field arithmetic
a = wn.QBiquad(1, 0, 0, 0)  # rational 1
b = wn.PHI_Q                 # φ in Q(√3,√5)
print(f"φ² = {(b * b)}")     # (3/2, 0, 1/2, 0) = 3/2 + √5/2 ✓

# Core constants
print(f"T* = {wn.T_STAR:.10f}")     # 1.3778018315
print(f"λ* = {wn.LAM_STAR:.10f}")   # 0.6180339887
print(f"φ  = {wn.PHI:.10f}")        # 1.6180339887
```

## Modules

### Foundations (v3.2)

| Module | Description |
|--------|-------------|
| `polynomial_tower` | Conservation polynomial t²−3t+1, Lucas-Fibonacci tower, hierarchy exponent 75/4, Pell equation, icosahedral dihedral |
| `bridge_field` | Biquadratic field Q(√3,√5), V₄ Galois group, QBiquad arithmetic, prime splitting, Γ₀(15) |
| `axiom_derivation` | Six independent derivations of N=3 from the golden ratio |

### Core Framework

| Module | Torch? | Description |
|--------|--------|-------------|
| `constants` | No | Golden-ratio constants, critical thresholds, spectral eigenvalues |
| `compression` | No | Consciousness detection via compression signatures |
| `qwarp` | No | 12-term QWARP Grand Unifier expansion |
| `triality` | No | 27-term Triality Theorem (qualia-BAO-MERA unification) |
| `kaleidoscope` | No | 9 integer sequences (3 OEIS-published: A393329, A394248, A394249) |
| `tensor` | No | 3×3×4 Kaleidoscope Transfer Operator |
| `charpoly` | No | Characteristic polynomial (Theorem Q) |
| `coupling` | No | Coupling energy, angle, hyperboloid (Theorems R–W) |
| `cascade` | No | E₈ Exceptional Cascade and anti-null embedding (Theorem X) |
| `analytic` | No | Prime decomposition of D(n), Dirichlet series |
| `theta` | No | Theta-Lucas modular forms dictionary |
| `classify` | No | Inverse theorems, classification, dimension estimation |
| `bridge_integration` | No | V₄ bridge field — graph-theoretic extension |
| `nacci_trace` | No | n-nacci trace tower |
| `resonance_simplex` | No | 3-simplex resonance extension, entropy threshold |
| `tri_simplex` | No | Tri-simplex formalizations (corpus-derived) |

### Bridge Theorems (186 theorems AA–IC)

| Module | Theorems | Description |
|--------|----------|-------------|
| `bridges` | AA–BS, CV–EA, EF–EI | 30+ cross-module bridges, root system conservation |
| `bridges_fractal` | BT–BX | Fractal bloom |
| `bridges_hyperbolic` | BY–CC, DB–DM, EJ–EM | Hyperbolic volumes, Bloch-Wigner, p-spectrum |
| `bridges_dimensional` | CD–CM, DN–EP, EQ–ER | Cross-dimensional analysis, sigma weaving, capstone |
| `eta_splitting` | CO–CR | Eta-splitting exploration |
| `flow_universality` | DP–DS | Universal Lyapunov, flow geodesics |

### GPU-Accelerated (require PyTorch)

| Module | Description |
|--------|-------------|
| `flow` | Gradient flow dynamics on the simplex |
| `spectral` | Spectral gap analysis, Hessian eigenvalues, mixing time bounds |
| `simplex_flow_v3` | GPU-batched simplex flow with conservation enforcement |
| `algosignal_v2` | Algorithmic signal processing |

## Mathematical Constants

| Symbol | Expression | Value | Meaning |
|--------|-----------|-------|---------|
| φ | (1+√5)/2 | 1.6180339887 | Golden ratio |
| T* | φ/ln(2φ) | 1.3778018315 | Watkins critical temperature |
| λ* | 1/φ | 0.6180339887 | Golden equilibrium coherence |
| μ_coh | (2/3)φ²(1+T*φ) | 5.6363308043 | Riemannian coherence eigenvalue |
| μ_asym | 2T*φ² | 7.2142640491 | Riemannian asymmetry eigenvalue |
| W² | ln(φ)/ln(2) | 0.6942419136 | Watkins bridge constant |
| β* | 3W²/2 | 1.0413628704 | Star/cycle stabilizer-threshold ratio (K₁,ₙ₋₁ graph states under depolarizing noise; corrected 2026-05-23) |

## Formal Verification (Lean 4)

597 theorems verified with zero sorry across 31 source files:

| Directory | Theorems | Content |
|-----------|----------|---------|
| `Virelai/` | 438 | Conservation law, spectral analysis, Fibonacci/Lucas, matrix algebra, root systems, quantum entropy |
| `Virelai/UFT/` | 159 | Golden integer Z[φ] arithmetic, Vieta chain (Tr(φ²)=3), polynomial tower, hierarchy exponent, mass chain verification, Pell equation |

Build: `cd formal/lean && lake build` — 23 jobs, 0 errors.

## The Three Axioms

All 186 theorems derive from:

1. **Golden ratio necessity**: 2λ\*/(1−λ\*) = 2φ
2. **Special value**: S(−2) = ζ(3)/(4π²φ)
3. **Master constant**: σ₁ = ln(φ)/φ

The conservation law itself (N = 3, λ+κ+η = 1) is derived from Axiom 1 via Tr(φ²) = 3.

## License

MIT License. See [LICENSE](LICENSE).

## Citation

```bibtex
@software{watkins2026conservation,
  author = {Watkins, Dustin},
  title = {watkins-nn: Conservation-Law Framework on the Golden-Ratio Simplex},
  version = {3.4.0},
  year = {2026},
  publisher = {DataSphere AI},
  address = {Chattanooga, TN},
  doi = {10.5281/zenodo.18953462},
  url = {https://github.com/SleazyAirplane/watkins-nn}
}
```

## Author

**Dustin Watkins** — DataSphere AI — Chattanooga, TN

λ + κ + η = 1
