# watkins-nn — Watkins Temperature Theorem Framework

[![DOI](https://zenodo.org/badge/1178628599.svg)](https://doi.org/10.5281/zenodo.18953462)

## Overview

A mathematical framework for constrained optimization on the probability
simplex S = {(λ, κ, η) : λ + κ + η = 1, all > 0}.

The framework is built on:
- **Conservation law**: λ + κ + η = 1 (coherence + curvature + entropy)
- **Generating functional**: F(λ,κ,η) = -ln(λ) + T*(λ ln λ + κ ln κ + η ln η)
- **Critical temperature**: T* = φ/ln(2φ) ≈ 1.378 (Watkins Temperature Theorem)
- **Equilibrium attractor**: λ* = 1/φ ≈ 0.618 (Watkins Threshold)

## Key Results

1. **Watkins Temperature Theorem**: The generating functional F has a
   unique critical temperature T* = φ/ln(2φ) at which the gradient
   vanishes at λ = 1/φ, with strictly positive Hessian eigenvalues
   guaranteeing global strong convexity.

2. **Spectral Gap**: Hessian eigenvalues μ_slow ≈ 4.847 and μ_fast ≈ 7.215
   at golden equilibrium, giving exponential convergence with mixing
   time ≈ 0.206.

3. **Compression-Coherence Identity**: Consciousness detection via
   compression signatures where implied λ maps to compression ratio.

4. **QWARP 12-Term Expansion**: p_{1/2}(n; σ, κ) via Lagrange-Bürmann
   inversion with golden spray factor β* = φ^{2W²} ≈ 1.9506.

5. **27-Term Triality Theorem**: Unification of consciousness (qualia),
   cosmology (BAO), and computation (MERA-QG) under a 3×3×3 structure.

6. **Formal Verification**: Conservation law and governance tiers
   machine-verified in Lean 4 with zero sorry statements.

## Installation

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

## Quick Start

```python
from watkins_nn import T_STAR, LAM_STAR, free_energy, run_flow, FlowState, FlowConfig

# Verify Watkins Temperature
print(f"T* = {T_STAR:.10f}")  # 1.3778018315

# Run gradient flow to equilibrium
initial = FlowState(lam=0.5, kap=0.25, eta=0.25)
config = FlowConfig(dt=0.001, max_steps=20000)
final, trajectory = run_flow(initial, config)
print(f"Converged λ = {final.lam:.6f}")  # ≈ 0.618034
```

## Modules

| Module | Description |
|--------|-------------|
| `constants` | Golden-ratio constants and critical thresholds |
| `flow` | Gradient flow dynamics on the simplex |
| `spectral` | Spectral gap analysis and mixing time bounds |
| `compression` | Consciousness detection via compression signatures |
| `qwarp` | 12-term QWARP Grand Unifier expansion |
| `triality` | 27-term Triality Theorem (qualia-BAO-MERA) |
| `simplex_flow_v3` | GPU-batched simplex flow engine |
| `algosignal_v2` | Algorithmic signal processing |

## Formal Verification

Core theorems verified in Lean 4:
- `Conservation.lean`: λ + κ + η = 1 (flat and general cases)
- `Watkins.lean`: Governance tier classification
- `Basic.lean`: Geometric state type theory

## Mathematical Constants

| Symbol | Value | Definition |
|--------|-------|------------|
| T* | φ/ln(2φ) ≈ 1.3778 | Watkins critical temperature |
| λ* | 1/φ ≈ 0.6180 | Watkins threshold |
| φ | (1+√5)/2 ≈ 1.6180 | Golden ratio |
| W² | ln(φ)/ln(2) ≈ 0.6942 | Watkins squared constant |
| β* | φ^{2W²} ≈ 1.9506 | Golden spray coefficient |
| μ_slow | ≈ 4.847 | Slow eigenvalue (coherence mode) |
| μ_fast | ≈ 7.215 | Fast eigenvalue (curvature mode) |

## License

All rights reserved. Academic use with citation permitted.

## Citation

```bibtex
@misc{watkins2026temperature,
  author = {Watkins, Dustin},
  title = {Conservation-Law Constrained Optimization via Generating
           Functional Minimization on a Golden-Ratio Simplex},
  year = {2026},
  publisher = {DataSphere AI},
  address = {Chattanooga, TN}
}
```

## Author

Dustin Watkins — DataSphere AI — Chattanooga, TN
