Metadata-Version: 2.4
Name: watkins-nn
Version: 3.0.2
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 — Watkins Temperature Theorem 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/)

## 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 ≈ 5.934 and μ_fast ≈ 20.556
   at golden equilibrium (v0.7.1 corrected), giving exponential convergence
   with mixing time ≈ 0.169.

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. **Kaleidoscope Integer Sequences**: 9 integer sequences arising from
   quantum stabilizer weight-enumerators, 3 published on OEIS
   (A393329, A394248, A394249).

7. **Formal Verification**: Conservation law and core theorems
   machine-verified in [Lean 4](https://github.com/SleazyAirplane/WatkinsTheorem)
   with zero sorry statements (2153 jobs).

## Installation

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

**Torch-free usage** (constants, compression, qwarp, kaleidoscope, triality, tensor):
```bash
pip install watkins-nn --no-deps
```
```python
from watkins_nn import T_STAR, LAM_STAR, PHI  # works without torch
```

## 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 | Torch? | Description |
|--------|--------|-------------|
| `constants` | No | Golden-ratio constants and critical thresholds |
| `compression` | No | Consciousness detection via compression signatures |
| `qwarp` | No | 12-term QWARP Grand Unifier expansion |
| `triality` | No | 27-term Triality Theorem (qualia-BAO-MERA) |
| `kaleidoscope` | No | 9 integer sequences (3 OEIS-published) |
| `tensor` | No | 3×3×2 Kaleidoscope Transfer Operator |
| `flow` | Yes | Gradient flow dynamics on the simplex |
| `spectral` | Yes | Spectral gap analysis and mixing time bounds |
| `simplex_flow_v3` | Yes | GPU-batched simplex flow engine |
| `algosignal_v2` | Yes | Algorithmic signal processing |

## 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 bridge constant |
| β* | φ^{2W²} ≈ 1.9506 | Golden spray coefficient |
| μ_slow | ≈ 5.934 | Slow eigenvalue (v0.7.1 corrected) |
| μ_fast | ≈ 20.556 | Fast eigenvalue (v0.7.1 corrected) |

## Formal Verification

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

## License

MIT License. See [LICENSE](LICENSE).

## 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},
  doi = {10.5281/zenodo.18953462}
}
```

## Author

Dustin Watkins — DataSphere AI — Chattanooga, TN
