tnfr 8.6.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

Core Documentation

Theory & Foundations

• 📘 Mathematical Foundations - Formal TNFR mathematics
• 📖 TNFR Concepts - Paradigm introduction
• 📋 GLOSSARY - Operational definitions
• 🔬 Classical Mechanics Emergence - How classical physics emerges from TNFR

Grammar System

• 🎯 Grammar Documentation Hub - Complete navigation guide
• 📐 Unified Grammar Rules - U1-U4 constraint derivations
• 🚀 Grammar Quick Reference - One-page cheat sheet
• 📊 Executive Summary - For managers and stakeholders

Implementation & API

• ⚙️ API Overview - Package architecture
• 🔧 Operator Guide - Complete operator reference
• 🛠️ ARCHITECTURE - System design

Development

• 🤝 CONTRIBUTING - Development workflow
• 🧪 TESTING - Test strategy
• 🔒 SECURITY - Security practices
• 🎓 AGENTS - Canonical invariants and guidance

---

🔬 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://fermga.github.io/TNFR-Python-Engine/
• 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