Metadata-Version: 2.4
Name: tnfr
Version: 0.0.3.3
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.

```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**.

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)

---

## 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
# 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().apply(G, node)
    Coherence().apply(G, node)
    Silence().apply(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 validation (56 modules)
├── physics/           # Structural fields, conservation, integrity (26 modules)
├── engines/           # Self-optimization, pattern discovery, GPU/FFT (7 modules)
├── dynamics/          # Nodal equation integration
├── riemann/           # TNFR-Riemann program (14 modules)
├── sdk/               # Simplified & Fluent API (7 modules)
│   └── simple.py      # Tetrad, conservation, grammar-aware dynamics, integrity
├── 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/              # 42 sequential tutorials (01-40 + extras)
tests/                 # 1,655 tests
theory/                # Theoretical derivations
benchmarks/            # Performance validation (14 suites)
```

---

## 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 |
| [theory/TNFR_RIEMANN_RESEARCH_NOTES.md](theory/TNFR_RIEMANN_RESEARCH_NOTES.md) | TNFR-Riemann program |
| [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 (1,655)
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 = {2025},
  version = {0.0.3.3},
  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/)
