Metadata-Version: 2.4
Name: tnfr
Version: 0.0.3.4
Summary: Resonant Fractal Nature Theory (TNFR) - Computational engine for modeling coherent patterns through resonance dynamics
Author: F. F. Martinez Gamo
License-Expression: MIT
Project-URL: Homepage, https://github.com/fermga/TNFR-Python-Engine
Project-URL: Repository, https://github.com/fermga/TNFR-Python-Engine
Project-URL: PyPI, https://pypi.org/project/tnfr/
Project-URL: Citation, https://doi.org/10.5281/zenodo.17602860
Project-URL: Zenodo, https://zenodo.org/records/17602860
Project-URL: Issues, https://github.com/fermga/TNFR-Python-Engine/issues
Project-URL: Documentation, https://fermga.github.io/TNFR-Python-Engine/
Project-URL: GPT, https://chatgpt.com/g/g-67abc78885a88191b2d67f94fd60dc97-tnfr-resonant-fractal-nature-theory
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Provides-Extra: compute-jax
Requires-Dist: jax<1.0,>=0.4; extra == "compute-jax"
Provides-Extra: compute-torch
Requires-Dist: torch<3.0,>=2.1; extra == "compute-torch"
Provides-Extra: serialization
Requires-Dist: pyyaml<7.0,>=6.0; extra == "serialization"
Requires-Dist: orjson<4,>=3; extra == "serialization"
Provides-Extra: viz-basic
Requires-Dist: matplotlib<4.0,>=3.7; extra == "viz-basic"
Requires-Dist: sympy<2.0,>=1.12; extra == "viz-basic"
Provides-Extra: numpy
Provides-Extra: jax
Requires-Dist: jax<1.0,>=0.4; extra == "jax"
Provides-Extra: torch
Requires-Dist: torch<3.0,>=2.1; extra == "torch"
Provides-Extra: yaml
Requires-Dist: pyyaml<7.0,>=6.0; extra == "yaml"
Provides-Extra: orjson
Requires-Dist: orjson<4,>=3; extra == "orjson"
Provides-Extra: viz
Requires-Dist: matplotlib<4.0,>=3.7; extra == "viz"
Provides-Extra: docs
Requires-Dist: sphinx>=7.2; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.25; extra == "docs"
Requires-Dist: myst-parser>=2.0; extra == "docs"
Requires-Dist: nbsphinx>=0.9; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.3; extra == "docs"
Requires-Dist: sphinxcontrib-mermaid>=0.9; extra == "docs"
Requires-Dist: ipykernel>=6; extra == "docs"
Requires-Dist: nbconvert>=7.16; extra == "docs"
Requires-Dist: pypandoc-binary>=1.14; extra == "docs"
Requires-Dist: mkdocs>=1.5; extra == "docs"
Requires-Dist: mkdocs-material>=9.4; extra == "docs"
Requires-Dist: mkdocs-jupyter>=0.24; extra == "docs"
Provides-Extra: test-unit
Requires-Dist: pytest<10,>=7; extra == "test-unit"
Requires-Dist: pytest-cov<8,>=4; extra == "test-unit"
Requires-Dist: pytest-timeout<3,>=2; extra == "test-unit"
Provides-Extra: test-property
Requires-Dist: hypothesis<7,>=6; extra == "test-property"
Requires-Dist: hypothesis-networkx<1.0,>=0.3; extra == "test-property"
Provides-Extra: test-performance
Requires-Dist: pytest-benchmark<6,>=4; extra == "test-performance"
Provides-Extra: test-parallel
Requires-Dist: pytest-xdist<4,>=3; extra == "test-parallel"
Provides-Extra: test-quality
Requires-Dist: pydocstyle<7,>=6; extra == "test-quality"
Requires-Dist: flake8<8,>=5; extra == "test-quality"
Requires-Dist: flake8-pyproject<2.0,>=1.2; extra == "test-quality"
Requires-Dist: vulture<3,>=2; extra == "test-quality"
Provides-Extra: test-all
Requires-Dist: pytest<10,>=7; extra == "test-all"
Requires-Dist: pytest-cov<8,>=4; extra == "test-all"
Requires-Dist: pytest-timeout<3,>=2; extra == "test-all"
Requires-Dist: hypothesis<7,>=6; extra == "test-all"
Requires-Dist: hypothesis-networkx<1.0,>=0.3; extra == "test-all"
Requires-Dist: pytest-benchmark<6,>=4; extra == "test-all"
Requires-Dist: pytest-xdist<4,>=3; extra == "test-all"
Requires-Dist: pydocstyle<7,>=6; extra == "test-all"
Requires-Dist: flake8<8,>=5; extra == "test-all"
Requires-Dist: flake8-pyproject<2.0,>=1.2; extra == "test-all"
Requires-Dist: vulture<3,>=2; extra == "test-all"
Requires-Dist: matplotlib<4.0,>=3.7; extra == "test-all"
Provides-Extra: test
Requires-Dist: pytest<10,>=7; extra == "test"
Requires-Dist: pytest-cov<8,>=4; extra == "test"
Requires-Dist: pytest-timeout<3,>=2; extra == "test"
Requires-Dist: hypothesis<7,>=6; extra == "test"
Requires-Dist: hypothesis-networkx<1.0,>=0.3; extra == "test"
Requires-Dist: pytest-benchmark<6,>=4; extra == "test"
Requires-Dist: pytest-xdist<4,>=3; extra == "test"
Requires-Dist: pydocstyle<7,>=6; extra == "test"
Requires-Dist: flake8<8,>=5; extra == "test"
Requires-Dist: flake8-pyproject<2.0,>=1.2; extra == "test"
Requires-Dist: vulture<3,>=2; extra == "test"
Requires-Dist: matplotlib<4.0,>=3.7; extra == "test"
Provides-Extra: typecheck
Requires-Dist: mypy<2.0,>=1.8; extra == "typecheck"
Requires-Dist: pyright<1.2.0,>=1.1.350; extra == "typecheck"
Requires-Dist: networkx-stubs>=0.0.1; extra == "typecheck"
Requires-Dist: types-cachetools>=6.0.0.0; extra == "typecheck"
Provides-Extra: dev-minimal
Requires-Dist: mypy<2.0,>=1.8; extra == "dev-minimal"
Requires-Dist: black<26,>=23; extra == "dev-minimal"
Requires-Dist: pytest<10,>=7; extra == "dev-minimal"
Requires-Dist: pytest-cov<8,>=4; extra == "dev-minimal"
Requires-Dist: pytest-timeout<3,>=2; extra == "dev-minimal"
Provides-Extra: dev-full
Requires-Dist: pytest<10,>=7; extra == "dev-full"
Requires-Dist: pytest-cov<8,>=4; extra == "dev-full"
Requires-Dist: pytest-timeout<3,>=2; extra == "dev-full"
Requires-Dist: hypothesis<7,>=6; extra == "dev-full"
Requires-Dist: hypothesis-networkx<1.0,>=0.3; extra == "dev-full"
Requires-Dist: pytest-benchmark<6,>=4; extra == "dev-full"
Requires-Dist: pytest-xdist<4,>=3; extra == "dev-full"
Requires-Dist: pydocstyle<7,>=6; extra == "dev-full"
Requires-Dist: flake8<8,>=5; extra == "dev-full"
Requires-Dist: flake8-pyproject<2.0,>=1.2; extra == "dev-full"
Requires-Dist: vulture<3,>=2; extra == "dev-full"
Requires-Dist: matplotlib<4.0,>=3.7; extra == "dev-full"
Requires-Dist: jax<1.0,>=0.4; extra == "dev-full"
Requires-Dist: mypy<2.0,>=1.8; extra == "dev-full"
Requires-Dist: pyright<1.2.0,>=1.1.350; extra == "dev-full"
Requires-Dist: networkx-stubs>=0.0.1; extra == "dev-full"
Requires-Dist: types-cachetools>=6.0.0.0; extra == "dev-full"
Provides-Extra: release
Requires-Dist: python-semantic-release<11,>=10.4; extra == "release"
Requires-Dist: setuptools-scm<10,>=8; extra == "release"
Requires-Dist: build<2,>=1; extra == "release"
Requires-Dist: towncrier<26,>=23; extra == "release"
Dynamic: license-file

# TNFR: Resonant Fractal Nature Theory

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17602860.svg)](https://doi.org/10.5281/zenodo.17602860)
[![PyPI version](https://badge.fury.io/py/tnfr.svg)](https://pypi.org/project/tnfr/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A mathematical framework for modeling coherent patterns in complex systems through resonance-based dynamics on networks.

A single **nodal equation** drives every node. From it, a complete **transport and geometric structure emerges** — measured by the engine, verified to machine precision, and anchored to classical, experimentally-established physics. The graph is only the substrate; the dynamics generates its own geometry.

```bash
pip install tnfr
```

---

## Core Ideas

All systems evolve via the **nodal equation**:

$$\frac{\partial \text{EPI}}{\partial t} = \nu_f \cdot \Delta\text{NFR}(t)$$

Structural changes occur exclusively through **13 canonical operators** (AL, EN, IL, OZ, UM, RA, SHA, VAL, NUL, THOL, ZHIR, NAV, REMESH) governed by **unified grammar rules U1-U6**. Each operator carries a canonical contract: it acts on exactly one channel of the nodal equation — the form EPI, the capacity νf, the phase θ, or the pressure ΔNFR — at node or network scale.

System state is characterized by four **structural fields** — the Universal Tetrahedral Correspondence:

| Constant | Field | Meaning |
|----------|-------|---------|
| φ | Φ_s | Structural potential (global stability) |
| γ | \|∇φ\| | Phase gradient (local stress) |
| π | K_φ | Phase curvature (geometric confinement) |
| e | ξ_C | Coherence length (spatial correlations) |

**Complete theory**: [AGENTS.md](AGENTS.md)

---

## From One Equation, a Geometry Emerges

TNFR is more than dynamics on a graph. The graph is only the substrate; the nodal equation **generates its own geometry**, which the engine *measures* rather than postulates. Every structure below is verified to machine precision and anchored to classical, experimentally-established phenomena:

- **Transport layer** (empirically anchored) — channel by channel, the nodal equation is a graph-Laplacian diffusion. From it emerge diffusion, synchronization (Kuramoto), random walks, effective resistance (Ohm/Kirchhoff), and standing-wave modes — all textbook phenomena.
- **Emergent symplectic substrate** (TNFR-native) — the same dynamics carries a phase space with conserved charges (Noether), a Hamiltonian equal to the energy functional, complete integrability, and a polarization structure (Stokes/Poincaré).
- **Orthogonal structure** — the dissipative (transport) and conservative (symplectic) parts are the two orthogonal Helmholtz–Hodge components of one flow.

**Honest scope**: this reorganizes known mathematics and physics inside a single framework, verified in code. It is a *characterization* of structure the nodal equation already contains — not a claim of new physics.

---

## Research Status

Two clearly-separated layers:

**Solid and verified.** The engine, the tetrad, grammar U1–U6, conservation laws, and the emergent transport + symplectic geometry are implemented, anchored to experimentally-established phenomena, and covered by 2,041 tests.

**Open research programs.** TNFR is also used to probe famous open problems. These are honest, in-progress programs that **do not claim proofs**:

| Program | Done | Open |
|---------|------|------|
| TNFR–Riemann (P1–P49) | discrete operator σ_c → 1/2; ζ↔L attack surface | Riemann Hypothesis (gap G4) — **paused at T-HP** |
| TNFR–Navier–Stokes (N1–N17) | NS-G5 closed at discrete-operator level | continuum limit / Clay (NS-G1..G4) — **open** |
| TNFR–Yang–Mills (Y1–Y5) | finite U(1) structural diagnostics | non-Abelian mass gap — **open** (Branch B) |
| TNFR–P vs NP (PNP-1) | coherence verification O(\|E\|) vs synthesis trapping | worst-case separation — **open** (Branch B) |
| TNFR–BSD (BSD-1) | rank separation via structural-pressure accumulation | rank ↔ order of vanishing — **open** (Branch B) |
| TNFR–Hodge (HC-1) | discrete Hodge = homology exactly (Eckmann) | (p,p) bigrading + algebraicity — **structurally blind** (Branch B3-leaning) |

See [AGENTS.md](AGENTS.md) and the `theory/` research notes for the full, audited status.

---

## Quick Start

```python
from tnfr.sdk import TNFR

# Create, connect, evolve
net = TNFR.create(20).ring().evolve(5)
print(net.results().summary())
# -> C=0.987, Si=0.912, N=20, E=20, rho=0.105
```

```python
# Structural Field Tetrad — four canonical fields
tetrad = net.tetrad()
print(tetrad.summary())
# -> Phi_s=0.0312, |grad_phi|=0.0841, |K_phi|=0.1523, xi_C=2.3147 (N=20)
print(tetrad.is_safe())  # canonical threshold checks
```

```python
# Conservation laws — Noether charge, Lyapunov stability
cons = net.conservation()
print(cons.summary())
# -> Q=1.2340, E=0.5678, dE/dt=-0.0012 (STABLE), quality=0.998
```

```python
# Emergent symplectic substrate — the geometry the dynamics generates
sub = net.symplectic_substrate()
print(sub.summary())
# -> dim=80, H_sub=0.0000, U=0.0000, div(X_H)=0.00e+00 (VALID)
# dim = 4N phase space; div(X_H)=0 => Liouville (volume-preserving)
```

```python
# One-shot comprehensive analysis
analysis = TNFR.analyze(net)
# Returns: coherence, tetrad, conservation, tensor_invariants,
#          emergent_fields, integrity, features
```

```python
# Grammar-aware evolution (proactive U1-U6 enforcement)
net.evolve_grammar_aware(steps=10)
```

```python
# Direct operator usage
import networkx as nx
from tnfr.operators.definitions import Emission, Coherence, Silence
from tnfr.metrics.coherence import compute_coherence

G = nx.erdos_renyi_graph(20, 0.2)
for node in G.nodes():
    Emission()(G, node)
    Coherence()(G, node)
    Silence()(G, node)

print(f"Coherence: {compute_coherence(G):.3f}")
```

---

## Installation

```bash
pip install tnfr                       # stable release
pip install -e ".[dev-minimal]"        # development
pip install -e ".[test-all]"           # full test suite
pip install -e ".[compute-jax]"        # JAX backend
pip install -e ".[compute-torch]"      # PyTorch backend
```

---

## Project Structure

```text
src/tnfr/
├── operators/         # 13 canonical operators + grammar U1–U6 (62 modules)
├── physics/           # Tetrad, conservation, emergent symplectic substrate, structural diffusion (29 modules)
├── engines/           # Self-optimization, pattern discovery, GPU/FFT (8 modules across 5 subpackages)
├── dynamics/           # Nodal equation integration
├── riemann/           # TNFR–Riemann program (61 modules, P1–P49; paused at T-HP, RH open)
├── navier_stokes/     # TNFR–Navier–Stokes program (N1–N17; NS-G5 closed at discrete level, Clay open)
├── yang_mills/        # TNFR–Yang–Mills diagnostics (Y1–Y5; Branch B, mass gap open)
├── sdk/               # Simplified & Fluent API (7 modules)
│   └── simple.py      # Tetrad, conservation, symplectic substrate, grammar-aware dynamics
├── mathematics/       # Number theory, backends
├── constants/         # Canonical constants (mpmath 35-digit precision)
├── metrics/           # Coherence, Si, phase sync, telemetry
├── validation/        # Structural health monitoring
└── factorization/     # Spectral factorization workflow

examples/              # 162 examples in 10 thematic subfolders (see examples/README.md)
tests/                 # 2,041 tests
theory/                # Theoretical derivations
benchmarks/            # 50 performance & structural-validation scripts
```

---

## Documentation

| Resource | Description |
|----------|-------------|
| [AGENTS.md](AGENTS.md) | **Primary reference** — complete TNFR theory, operators, grammar, fields |
| [theory/UNIFIED_GRAMMAR_RULES.md](theory/UNIFIED_GRAMMAR_RULES.md) | U1-U6 grammar derivations from physics |
| [theory/FUNDAMENTAL_THEORY.md](theory/FUNDAMENTAL_THEORY.md) | Universal Tetrahedral Correspondence |
| [docs/STRUCTURAL_FIELDS_TETRAD.md](docs/STRUCTURAL_FIELDS_TETRAD.md) | Field implementation specifications |
| [docs/STRUCTURAL_INTERFACE_THEORY.md](docs/STRUCTURAL_INTERFACE_THEORY.md) | Structural-interface programme: pipelines, fair benchmarks, validated results, limitations |
| [theory/TNFR_RIEMANN_RESEARCH_NOTES.md](theory/TNFR_RIEMANN_RESEARCH_NOTES.md) | TNFR-Riemann program |
| [theory/TNFR_NAVIER_STOKES_RESEARCH_NOTES.md](theory/TNFR_NAVIER_STOKES_RESEARCH_NOTES.md) | TNFR-Navier–Stokes program |
| [theory/TNFR_YANG_MILLS_RESEARCH_NOTES.md](theory/TNFR_YANG_MILLS_RESEARCH_NOTES.md) | TNFR–Yang–Mills structural gap programme (Y1–Y5; Branch B classified) |
| [theory/TNFR_P_VS_NP_RESEARCH_NOTES.md](theory/TNFR_P_VS_NP_RESEARCH_NOTES.md) | TNFR–P vs NP synthesis-vs-verification programme (PNP-1; Branch B, not a proof) |
| [theory/TNFR_BSD_RESEARCH_NOTES.md](theory/TNFR_BSD_RESEARCH_NOTES.md) | TNFR–Birch–Swinnerton-Dyer structural-pressure programme (BSD-1; Branch B, not a proof) |
| [theory/TNFR_HODGE_RESEARCH_NOTES.md](theory/TNFR_HODGE_RESEARCH_NOTES.md) | TNFR–Hodge discrete cochain programme (HC-1; Branch B3-leaning strong negative, not a proof) |
| [theory/GLOSSARY.md](theory/GLOSSARY.md) | Terminology and definitions |
| [examples/](examples/) | Sequential tutorials |
| [ARCHITECTURE.md](ARCHITECTURE.md) | System design |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Development guidelines |

---

## Testing

```bash
pytest                             # all tests (2,041 under tests/)
pytest tests/sdk/                  # SDK tests (tetrad, conservation, grammar)
pytest tests/unit/                 # unit tests
.\make.cmd smoke-tests             # smoke tests (Windows)
make smoke-tests                   # smoke tests (Unix)
```

---

## Citation

```bibtex
@software{tnfr_python_engine,
  author = {Martinez Gamo, F. F.},
  title = {TNFR-Python-Engine: Resonant Fractal Nature Theory Implementation},
  year = {2026},
  version = {0.0.3.4},
  doi = {10.5281/zenodo.17602860},
  url = {https://github.com/fermga/TNFR-Python-Engine}
}
```

---

## License

MIT — see [LICENSE.md](LICENSE.md).

## Links

[PyPI](https://pypi.org/project/tnfr/) · [Issues](https://github.com/fermga/TNFR-Python-Engine/issues) · [Discussions](https://github.com/fermga/TNFR-Python-Engine/discussions) · [Documentation](https://fermga.github.io/TNFR-Python-Engine/)
