TNFR Python Engine TNFR: Resonant Fractal Nature Theory
Version 0.0.2 · DOI 10.5281/zenodo.17764207 · Updated 2025-11-30 Source README.md

TNFR: Resonant Fractal Nature Theory

Computational Framework for Coherent Pattern Analysis

DOI PyPI version Python 3.10+ License: MIT

TNFR (Resonant Fractal Nature Theory) provides a mathematical framework for modeling coherent patterns in complex systems through resonance-based dynamics.

Version: 0.0.2 (November 29, 2025)
Theoretical Foundation: Universal Tetrahedral Correspondence (φ↔Φ_s, γ↔|∇φ|, π↔K_φ, e↔ξ_C)
Installation: pip install tnfr

Getting Started

Getting Started

Installation: pip install tnfr

Essential Concepts: - Nodal Equation: ∂EPI/∂t = νf · ΔNFR(t) - fundamental evolution law - Canonical Operators: 13 structural operators for system modification - Unified Grammar: U1-U6 constraint rules derived from theoretical physics - Structural Fields: Tetrahedral field system (Φ_s, |∇φ|, K_φ, ξ_C)

First Steps: 1. Install package: pip install tnfr 2. Read theoretical foundation: AGENTS.md 3. Run basic example: python examples/01_hello_world.py 4. Study terminology: theory/GLOSSARY.md

Learning Path

Beginner (2 hours): 1. Install TNFR: pip install tnfr 2. Read AGENTS.md - complete theoretical foundation 3. Run python examples/01_hello_world.py

Intermediate (1 week): 1. Study theory/UNIFIED_GRAMMAR_RULES.md - physics derivations 2. Work through examples/ sequential tutorials (01-10) 3. Explore src/tnfr/physics/fields.py - field implementations

Advanced (ongoing): 1. TNFR-Riemann Program: theory/TNFR_RIEMANN_RESEARCH_NOTES.md - Complete framework connecting discrete operators to Riemann Hypothesis 2. Technical derivations: theory/TUTORIAL_FROM_NODAL_EQUATION_TO_COSMOS.md 3. Contribute following CONTRIBUTING.md

What is TNFR?

Resonant Fractal Nature Theory provides a mathematical framework for modeling coherent patterns in complex systems. The theory establishes correspondence between four universal mathematical constants (φ, γ, π, e) and four structural fields that characterize system dynamics.

Core Principle: Systems are modeled as coherent patterns maintained through resonant coupling rather than as discrete objects with independent properties.

Theoretical Foundation: AGENTS.md - Complete theory reference
Mathematical Details: Structural Fields and Universal Tetrahedral Correspondence
Theory Hub: theory/README.md - Comprehensive theoretical documentation
Implementation: This repository provides computational tools for TNFR analysis

Theoretical Approach: - Pattern analysis over discrete objects - Resonant coupling over causal relationships - Dynamic processes over static properties - Network coherence over isolated systems

Key Features

The 13 Canonical Structural Operators

TNFR provides a complete set of 13 operators for modeling structural dynamics. All system evolution occurs through these operators according to unified grammar rules (U1-U6).

Unified Grammar (U1-U6)

Physics-derived constraints for valid operator sequences:

Reference: UNIFIED_GRAMMAR_RULES.md for complete derivations

Structural Field Tetrad (Canonical)

Four fields characterizing system state:

Implementation: tnfr.physics.fields
Documentation: docs/STRUCTURAL_FIELDS_TETRAD.md

TNFR Engines Hub

Centralized mathematical and optimization engines for advanced TNFR applications:

Self-Optimization Engine (tnfr.engines.self_optimization)

Pattern Discovery Engines (tnfr.engines.pattern_discovery)

Computation Engines (tnfr.engines.computation)

Integration Engines (tnfr.engines.integration)

Quick Usage:

# Via SDK (recommended)
from tnfr.sdk import TNFR
net = TNFR.create(50).random(0.3).auto_optimize()

# Direct engine access
from tnfr.engines.self_optimization import TNFRSelfOptimizingEngine
engine = TNFRSelfOptimizingEngine(network)
success, metrics = engine.step(node_id)

Documentation: src/tnfr/engines/README.md

Core Metrics

Structural system telemetry:

Validation & Health Monitoring

Structural validation and monitoring tools:

Usage:

from tnfr.validation.aggregator import run_structural_validation
from tnfr.validation.health import compute_structural_health
from tnfr.performance.guardrails import PerformanceRegistry

perf = PerformanceRegistry()
report = run_structural_validation(
  G,
  sequence=["AL","UM","IL","SHA"],
  perf_registry=perf,
)
health = compute_structural_health(report)
print(report.risk_level, health.recommendations)
print(perf.summary())

Telemetry:

from tnfr.metrics.telemetry import TelemetryEmitter

with TelemetryEmitter("results/run.telemetry.jsonl", human_mirror=True) as em:
  for step, op in enumerate(["AL","UM","IL","SHA"]):
    em.record(G, step=step, operator=op, extra={"sequence_id": "demo"})

Risk levels:

CLI health report:

python scripts/structural_health_report.py --graph random:50:0.15 --sequence AL,UM,IL,SHA

All instrumentation preserves TNFR physics (no state mutation).

Installation

From PyPI (Stable)

pip install tnfr

From Source (Development)

git clone https://github.com/fermga/TNFR-Python-Engine.git
cd TNFR-Python-Engine
pip install -e ".[dev-minimal]"

Dependency Profiles

# Core functionality only
pip install .

# Development tools (linting, formatting, type checking)
pip install -e ".[dev-minimal]"

# Full test suite
pip install -e ".[test-all]"

# Documentation building
pip install -e ".[docs]"

# Visualization support
pip install -e ".[viz-basic]"

# Alternative backends
pip install -e ".[compute-jax]"   # JAX backend
pip install -e ".[compute-torch]"  # PyTorch backend

Quick Start

Basic Usage

from tnfr.sdk import TNFRNetwork

# Create and configure network
network = TNFRNetwork("example")
network.add_nodes(10).connect_nodes(0.3, "random")
results = network.apply_sequence("basic_activation", repeat=3).measure()

print(f"Coherence: {results.coherence:.3f}")

Using Operators Directly

import networkx as nx
from tnfr.operators.definitions import Emission, Coherence, Resonance
from tnfr.operators.grammar import validate_sequence
from tnfr.metrics.coherence import compute_coherence

# Create network
G = nx.erdos_renyi_graph(20, 0.2)

# Apply operator sequence
sequence = ["AL", "IL", "RA", "SHA"]
result = validate_sequence(sequence)

if result.valid:
    for node in G.nodes():
        Emission().apply(G, node)
        Coherence().apply(G, node)
        Resonance().apply(G, node)

    # Measure
    C_t = compute_coherence(G)
    print(f"Network coherence: {C_t:.3f}")

Domain Applications

# Therapeutic patterns (crisis, trauma, healing)
python examples/domain_applications/therapeutic_patterns.py

# Educational patterns (learning, mastery, breakthrough)
python examples/domain_applications/educational_patterns.py

# Biological systems (metabolism, evolution)
python examples/domain_applications/biological_patterns.py

Documentation

Complete Documentation: fermga.github.io/TNFR-Python-Engine

Primary References

Theoretical Foundation: - AGENTS.md - Primary theoretical reference and development guide - theory/UNIFIED_GRAMMAR_RULES.md - Grammar constraint derivations (U1-U6) - Structural Fields and Universal Tetrahedral Correspondence - Mathematical foundations

Implementation Guide: - ARCHITECTURE.md - System architecture and design - docs/STRUCTURAL_FIELDS_TETRAD.md - Field implementation specifications - theory/GLOSSARY.md - Technical definitions and terminology

Development Resources: - CONTRIBUTING.md - Development workflow and standards - examples/ - Sequential tutorials and usage examples - TESTING.md - Testing framework and requirements

Repository Structure

TNFR-Python-Engine/
├── src/tnfr/              # Core TNFR implementation
│   ├── operators/         # Canonical operator system (immutable registry)
│   │   ├── definitions.py        # Facade (backward compatibility)
│   │   ├── definitions_base.py   # Operator base class (no dynamic metaclass)
│   │   ├── emission.py           # AL operator
│   │   ├── coherence.py          # IL operator
│   │   └── ... (13 operators)    # Individual operator modules (canonical)
│   ├── operators/grammar/ # Unified grammar constraints (Phase 1)
│   │   ├── grammar.py            # Facade (unified validation)
│   │   ├── u1_initiation_closure.py
│   │   ├── u2_convergence_boundedness.py
│   │   └── ... (8 constraint modules)
│   ├── metrics/           # Modular metrics system (Phase 1)
│   │   ├── metrics.py            # Facade (backward compatibility)
│   │   ├── coherence.py          # C(t) computation
│   │   ├── sense_index.py        # Si measurement
│   │   ├── phase_sync.py         # Phase synchronization
│   │   └── telemetry.py          # Execution tracing
│   ├── physics/           # Canonical fields (Φ_s, |∇φ|, K_φ, ξ_C)
│   ├── dynamics/          # Nodal equation integration
│   ├── sdk/               # High-level API
│   └── tutorials/         # Educational modules
├── tests/                 # Comprehensive test suite (975/976 passing)
├── examples/              # Domain applications
├── docs/                  # Documentation source
├── notebooks/             # Jupyter notebooks
├── benchmarks/            # Performance testing
└── scripts/               # Maintenance utilities

Testing

# Run all tests
pytest

# Fast smoke tests (examples + telemetry)
make smoke-tests          # Unix/Linux
.\make.cmd smoke-tests    # Windows

# Specific test suites
pytest tests/unit/mathematics/         # Math tests
pytest tests/examples/                 # Example validation
pytest tests/integration/              # Integration tests

Repository Maintenance

# Clean generated artifacts
make clean                # Unix/Linux
.\make.cmd clean          # Windows

# Check repository health
python scripts/repo_health_check.py

# Verify documentation references
python scripts/verify_internal_references.py

# Security audit
pip-audit

See REPO_OPTIMIZATION_PLAN.md for cleanup routines and targeted test bundles.

Performance Characteristics

Benchmarking tools: tools/performance/

Note on Python executable for local runs

Using the workspace virtual environment avoids mismatches with system Pythons that may lack the latest telemetry aliases or configuration.

Parse precision_modes drift (benchmark_results.json)

After running ./test-env/Scripts/python.exe run_benchmark.py (Windows) or ./test-env/bin/python run_benchmark.py (macOS/Linux), parse numeric drift for the precision_modes track:

import json

with open("benchmark_results.json", "r", encoding="utf-8") as f:
  data = json.load(f)

drift_entries = data.get("precision_modes", {}).get("drift", [])
for entry in drift_entries:
  size = entry.get("size")
  phi_s = entry.get("phi_s_max_abs")
  grad = entry.get("grad_max_abs")
  curv = entry.get("curv_max_abs")
  xi_c = entry.get("xi_c_abs")
  print(
    f"N={size:>4}  ΔΦ_s_max={phi_s:.3e}  |∇φ|_max={grad:.3e}  "
    f"K_φ_max={curv:.3e}  ξ_C_abs={xi_c if xi_c is not None else 'nan'}"
  )

This reports the maximum absolute difference between standard and high precision modes for the canonical fields per graph size.

PowerShell one-liners (Windows)

# Largest ΔΦ_s drift row
Get-Content .\benchmark_results.json | ConvertFrom-Json |
  Select-Object -ExpandProperty precision_modes |
  Select-Object -ExpandProperty drift |
  Sort-Object -Property phi_s_max_abs -Descending |
  Select-Object -First 1

# Largest |∇φ| drift row
Get-Content .\benchmark_results.json | ConvertFrom-Json |
  Select-Object -ExpandProperty precision_modes |
  Select-Object -ExpandProperty drift |
  Sort-Object -Property grad_max_abs -Descending |
  Select-Object -First 1

# Largest K_φ drift row
Get-Content .\benchmark_results.json | ConvertFrom-Json |
  Select-Object -ExpandProperty precision_modes |
  Select-Object -ExpandProperty drift |
  Sort-Object -Property curv_max_abs -Descending |
  Select-Object -First 1

# Largest ξ_C drift row (skip NaNs)
Get-Content .\benchmark_results.json | ConvertFrom-Json |
  Select-Object -ExpandProperty precision_modes |
  Select-Object -ExpandProperty drift |
  Where-Object { $_.xi_c_abs -ne $null -and -not [double]::IsNaN([double]$_.xi_c_abs) } |
  Sort-Object -Property xi_c_abs -Descending |
  Select-Object -First 1

Contributing

See CONTRIBUTING.md for development guidelines:

Theoretical Development: Follow theoretical integrity guidelines in AGENTS.md.

Technical References: - docs/STRUCTURAL_FIELDS_TETRAD.md - Field implementation specifications - TESTING.md - Testing framework requirements

Citation

To cite this software:

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

See CITATION.cff for machine-readable citation metadata.

License

This project is licensed under the MIT License - see LICENSE.md for details.

Support & Community

Theoretical Foundation

TNFR implements pattern-based modeling principles: - Pattern coherence over discrete objects - Resonant coupling over causal relationships - Dynamic processes over static properties - Network structures over isolated entities

Implementation follows theoretical foundations in AGENTS.md with adherence to canonical invariants and unified grammar constraints.