tnfr 8.5.0

Modular structural-based dynamics on networks.

TNFR Python Engine

Model reality as resonant patterns, not isolated objects

Quick Start • Key Concepts • Documentation • Examples • Contributing

---

🌟 What is TNFR?

TNFR (Resonant Fractal Nature Theory / Teoría de la Naturaleza Fractal Resonante) is a paradigm shift in modeling complex systems. Instead of viewing reality as isolated "things" that interact through cause-and-effect, TNFR models it as coherent patterns that persist through resonance.

Think of a choir: each singer maintains their unique voice while synchronizing with others to create harmony. When voices resonate, they produce stable, beautiful structures. When they clash, patterns fragment. TNFR captures this principle mathematically and makes it operational in code.

🎯 Why TNFR?

Traditional Approach	TNFR Paradigm
Objects exist independently	Patterns exist through resonance
Causality: A causes B	Coherence: A and B co-organize
Static snapshots	Dynamic reorganization
Domain-specific models	Trans-scale, trans-domain

Key Advantages:

• 🔄 Operational Fractality: Patterns scale without losing structure
• 📊 Complete Traceability: Every reorganization is observable
• 🎯 Guaranteed Reproducibility: Same conditions → same outcomes
• 🌐 Domain Neutral: Works from quantum to social systems

🚀 Use Cases

• 🧬 Biology: Cellular networks, neuronal synchronization, protein dynamics
• 🌐 Social Systems: Information spread, community formation, opinion dynamics
• 🤖 AI: Resonant symbolic systems, emergent learning
• 🔬 Network Science: Structural coherence, pattern detection
• 🏗️ Distributed Systems: Decentralized coordination, self-organization

---

⚡ Quick Start

Installation

pip install tnfr

Requires Python ≥ 3.9

Your First TNFR Network (3 Lines!)

from tnfr.sdk import TNFRNetwork

# Create, activate, and measure a network
network = TNFRNetwork("hello_world")
results = network.add_nodes(10).connect_nodes(0.3, "random").apply_sequence("basic_activation", repeat=3).measure()
print(results.summary())

🎉 That's it! You just created a resonant network.

What happened?

• add_nodes(10): Created 10 nodes that can synchronize
• connect_nodes(0.3, "random"): Connected them (30% probability)
• apply_sequence("basic_activation", repeat=3): Applied Emission → Coherence → Resonance (3x)
• measure(): Calculated coherence C(t), sense index Si, and structural metrics

🎓 Interactive Learning (5 Minutes)

from tnfr.tutorials import hello_tnfr
hello_tnfr()  # Guided tour of TNFR concepts

Domain Examples:

from tnfr.tutorials import (
    biological_example,      # Cell communication
    social_network_example,  # Social dynamics
    technology_example,      # Distributed systems
    adaptive_ai_example,     # Learning through resonance
)

📘 Structured Learning Path: See our 60-Minute Interactive Tutorial

---

💡 Key Concepts

New to TNFR? 👉 TNFR Fundamental Concepts Guide - Understand the paradigm in 10 minutes!

The Nodal Equation

At the heart of TNFR is one elegant equation:

∂EPI/∂t = νf · ΔNFR(t)

What it means:

• EPI: Primary Information Structure (the "shape" of a node)
• νf: Structural frequency (reorganization rate in Hz_str)
• ΔNFR: Internal reorganization operator (structural gradient)

Structure changes proportionally to frequency and gradient

Three Essential Elements

1. Resonant Fractal Node (NFR)

• Minimum unit of structural coherence
• Has EPI (form), νf (frequency), φ (phase)

2. Structural Operators (13 canonical)

• Emission/Reception: Initiate & capture patterns
• Coherence/Dissonance: Stabilize or destabilize
• Resonance: Propagate without losing identity
• Self-organization: Create emergent structures
• See all 13 operators →

3. Coherence Metrics

• C(t): Total network coherence [0,1]
• Si: Sense index (reorganization stability)
• ΔNFR: Evolution gradient

---

📚 Documentation

🎯 Single Source of Truth for Mathematics

Mathematical Foundations of TNFR ⭐

This is THE ONLY place where TNFR mathematics is formally defined:

• Hilbert space H_NFR and Banach space B_EPI
• Coherence operator Ĉ (spectral theory, proofs)
• Frequency operator Ĵ and reorganization operator ΔNFR
• Complete nodal equation derivation
• §3.1.1: Implementation bridge (theory → code)

🎯 Classical Mechanics Emergence

TNFR reveals how observable classical physics emerges from structural coherence dynamics:

TNFR Nodal Equation (∂EPI/∂t = νf · ΔNFR)
           ↓ 
    Low-dissonance limit (ε → 0)
           ↓
Observable Classical Mechanics

Key Emergent Phenomena:

• Mass: m = 1/νf (inverse structural frequency) — mass is structural inertia
• Force: F = -∇U(q) (coherence potential gradient) — force is stability flow
• Newton's Laws: Natural consequences of the nodal equation at low dissonance
• Action Principle: Coherence optimization over time
• Conservation Laws: Network symmetries preserve structural quantities

Documentation:

• 📘 N-Body Classical Mechanics Guide — Complete formal reference (variable mappings, conservation laws, validation protocols, code examples)
• Classical Mechanics from TNFR — Complete derivation from nodal equation
• Euler-Lagrange Correspondence — Variational formulation
• Numerical Validation — Computational verification

Practical Examples:

• examples/domain_applications/nbody_gravitational.py — Two-body orbits, three-body systems
• examples/nbody_quantitative_validation.py — Full validation suite (6 canonical experiments)
• tests/validation/test_nbody_validation.py — Automated test suite

This demonstrates classical mechanics as a natural expression of coherent structural dynamics in the observable, deterministic regime.

📖 Quick References

• GLOSSARY - Operational definitions for code use
• TNFR Concepts - Paradigm introduction
• API Overview - Package architecture
• Operator Guide - Complete operator reference
• NAV Guide - NAV (Transition) canonical sequences, anti-patterns, and troubleshooting
• THOL Configuration Reference - Comprehensive THOL parameter guide

🎨 Grammar System

TNFR uses a unified physics-based grammar to validate operator sequences. All constraints emerge inevitably from the nodal equation and TNFR invariants.

Four Canonical Constraints (U1-U4)

1. U1: STRUCTURAL INITIATION & CLOSURE

   • U1a: Start with generators when EPI=0
   • U1b: End with closure operators
   • Basis: ∂EPI/∂t undefined at EPI=0

2. U2: CONVERGENCE & BOUNDEDNESS

   • If destabilizers, then include stabilizers
   • Basis: ∫νf·ΔNFR dt must converge

3. U3: RESONANT COUPLING

   • If coupling/resonance, then verify phase
   • Basis: AGENTS.md Invariant #5

4. U4: BIFURCATION DYNAMICS

   • U4a: If triggers, then include handlers
   • U4b: If transformers, then recent destabilizer
   • Basis: Contract OZ + bifurcation theory

For complete derivations: See UNIFIED_GRAMMAR_RULES.md

For implementation: See src/tnfr/operators/grammar.py

Quick Start

from tnfr.operators.grammar import validate_grammar
from tnfr.operators.definitions import Emission, Coherence, Silence

sequence = [Emission(), Coherence(), Silence()]
is_valid = validate_grammar(sequence, epi_initial=0.0)

Migration from Old Grammar Systems

If you're using the old C1-C3 or RC1-RC4 systems:

• Old: from tnfr.operators.grammar import validate_sequence
• New: from tnfr.operators.grammar import validate_grammar

See migration guide in GRAMMAR_MIGRATION_GUIDE.md

🧪 Advanced Topics

• ARCHITECTURE.md - System design & invariants
• Backend System - NumPy/JAX/Torch backends
• TESTING.md - Test strategy & validation
• SECURITY.md - Security practices
• CONTRIBUTING.md - Development workflow

---

🔬 Examples

Hello World

# examples/hello_world.py
from tnfr.sdk import TNFRNetwork

network = TNFRNetwork("simple_demo")
results = (network
    .add_nodes(5)
    .connect_nodes(0.5, "random")
    .apply_sequence("basic_activation")
    .measure())

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

Biological Network

# examples/biological_network.py
from tnfr.sdk import TNFRNetwork

# Model cellular communication
cells = TNFRNetwork("cell_network")
results = (cells
    .add_nodes(20, epi_range=(0.8, 1.2))  # Biological variation
    .connect_nodes(0.3, "scale_free")      # Power-law connectivity
    .apply_sequence("therapeutic", repeat=5)  # Healing pattern
    .measure())

print(f"Network health: {results.coherence:.2%}")

More Examples

• Dynamic Limits - Adaptive thresholds
• Multiscale Networks - Hierarchical structures
• Regenerative Cycles - Self-sustaining patterns
• Performance Comparison - Backend benchmarks

📂 Full Collection: examples/ directory

---

🛠️ Development

Local Setup

# Clone repository
git clone https://github.com/fermga/TNFR-Python-Engine.git
cd TNFR-Python-Engine

# Install with development dependencies
pip install -e ".[dev,docs]"

# Run tests
./scripts/run_tests.sh

# Format code
./scripts/format.sh

Documentation Build

# Install docs dependencies
pip install -r docs/requirements.txt

# Build documentation
make docs

# View locally
open docs/_build/html/index.html

Configuration & Secrets

# Copy environment template
cp .env.example .env

# Edit .env with your credentials (never commit this file!)
# Load with:

from tnfr.secure_config import load_redis_config, get_cache_secret
redis_config = load_redis_config()

See SECURITY.md for best practices.

---

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Understand TNFR: Read Mathematical Foundations
2. Check Invariants: Follow AGENTS.md rules
3. Write Tests: Cover all invariants (see TESTING.md)
4. Run QA: Execute ./scripts/run_tests.sh
5. Submit PR: See CONTRIBUTING.md for guidelines

Key Principles:

• ✅ Preserve canonical invariants
• ✅ Use structural operators only
• ✅ Document with references to Mathematical Foundations
• ✅ Test spectral properties

---

📊 CLI Tools

Profiling Pipeline

tnfr profile-pipeline \
  --nodes 120 --edge-probability 0.28 --loops 3 \
  --si-chunk-sizes auto 48 --dnfr-chunk-sizes auto \
  --output-dir profiles/pipeline

Generates .pstats and JSON summaries for performance analysis.

---

📖 Learning Path

Recommended Progression:

1. Newcomers (10 min)

   • Read TNFR Concepts
   • Run hello_tnfr() tutorial

2. Beginners (30 min)

   • Try examples/hello_world.py
   • Explore domain examples (biological, social, AI)

3. Intermediate (2 hours)

   • Study Mathematical Foundations §1-3
   • Read GLOSSARY
   • Practice with Interactive Tutorial

4. Advanced (ongoing)

   • Deep dive: Mathematical Foundations (complete)
   • Architecture: ARCHITECTURE.md
   • Contribute: CONTRIBUTING.md

---

📜 License

Released under the MIT License.

Citation: When publishing research or applications based on TNFR, please cite:

• This repository: fermga/TNFR-Python-Engine
• Theoretical foundations: TNFR.pdf
• Mathematical formalization: Mathematical Foundations

---

🔗 Links

• Documentation: https://tnfr.netlify.app
• PyPI Package: https://pypi.org/project/tnfr/
• GitHub: https://github.com/fermga/TNFR-Python-Engine
• Issues: https://github.com/fermga/TNFR-Python-Engine/issues

---

Made with ❤️ for researchers, developers, and explorers of complex systems

Reality is not made of things—it's made of resonance