TNFR: Resonant Fractal Nature Theory

Computational Framework for Coherent Pattern Analysis

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).

• AL (Emission) - Pattern creation from vacuum
• EN (Reception) - Information capture and integration
• IL (Coherence) - Stabilization through negative feedback
• OZ (Dissonance) - Controlled instability and exploration
• UM (Coupling) - Network formation via phase sync
• RA (Resonance) - Pattern amplification and propagation
• SHA (Silence) - Temporal pause, observation windows
• VAL (Expansion) - Structural complexity increase
• NUL (Contraction) - Dimensionality reduction
• THOL (Self-organization) - Spontaneous autopoietic structuring
• ZHIR (Mutation) - Phase transformation at threshold
• NAV (Transition) - Regime shift, state changes
• REMESH (Recursivity) - Multi-scale fractal operations

Unified Grammar (U1-U6)

Physics-derived constraints for valid operator sequences:

• U1: Structural Initiation & Closure
• U2: Convergence & Boundedness
• U3: Resonant Coupling (phase verification)
• U4: Bifurcation Dynamics
• U5: Multi-Scale Coherence
• U6: Structural Potential Confinement

Reference: UNIFIED_GRAMMAR_RULES.md for complete derivations

Structural Field Tetrad (Canonical)

Four fields characterizing system state:

• Φ_s: Structural potential (global field)
• |∇φ|: Phase gradient (local desynchronization)
• K_φ: Phase curvature (geometric confinement)
• ξ_C: Coherence length (spatial correlations)

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)

• TNFRSelfOptimizingEngine: Automatic network optimization using TNFR operators
• Physics: Based on ∂EPI/∂t = νf · ΔNFR(t) nodal equation
• Capabilities: Smart node targeting, multi-operator optimization, real-time metrics
• Usage: Direct engine or via SDK auto_optimize()

Pattern Discovery Engines (tnfr.engines.pattern_discovery)

• TNFREmergentPatternEngine: Mathematical pattern detection and emergence analysis
• UnifiedPatternDetector: Operator sequence pattern recognition
• Discoveries: Eigenmodes, spectral cascades, fractal scaling, symmetry breaking
• Applications: Research insights, system analysis, predictive modeling

Computation Engines (tnfr.engines.computation)

• GPUEngine: GPU-accelerated TNFR computations for high-performance analysis
• FFTEngine: Fast Fourier Transform processing for spectral analysis
• Performance: Parallel processing, optimized algorithms

Integration Engines (tnfr.engines.integration)

• EmergentIntegrationEngine: Multi-scale analysis and hierarchical coupling
• Capabilities: Cross-scale information flow, emergent behavior detection

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:

• C(t): Total coherence [0, 1]
• Si: Sense index (reorganization capacity)
• ΔNFR: Internal reorganization operator
• νf: Structural frequency (Hz_str)
• φ: Phase synchrony [0, 2π]

Validation & Health Monitoring

Structural validation and monitoring tools:

• run_structural_validation: Grammar validation with field thresholds
• compute_structural_health: Health assessment and recommendations
• TelemetryEmitter: Comprehensive telemetry streaming
• PerformanceRegistry: Performance monitoring

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:

• low – Grammar valid; no thresholds exceeded.
• elevated – Local stress: max |∇φ|, |K_φ| pocket, ξ_C watch.
• critical – Grammar invalid or ΔΦ_s / ξ_C critical breach.

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

• Sequence validation: <1ms for typical sequences (10-20 operators)
• Coherence computation: O(N) for N nodes
• Phase gradient: O(E) for E edges
• Memory footprint: ~50MB for 10k-node networks

Benchmarking tools: tools/performance/

Note on Python executable for local runs

• Windows: prefer ./test-env/Scripts/python.exe
• macOS/Linux: prefer ./test-env/bin/python

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:

• Development workflow and standards
• Testing requirements and procedures
• Documentation standards and formatting
• Pull request process and review criteria

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

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• PyPI: pypi.org/project/tnfr
• Documentation: fermga.github.io/TNFR-Python-Engine

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.