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

TNFR: Resonant Fractal Nature Theory

Theoretical Framework for Coherent Pattern Analysis

Status: Primary theoretical reference document
Version: 0.0.2 (November 29, 2025)
Authority: This repository contains the current implementation of TNFR theory
Repository: https://github.com/fermga/TNFR-Python-Engine
PyPI Package: https://pypi.org/project/tnfr/
Installation: pip install tnfr

Foundational Principle

TNFR Development Doctrine: Our mission is to develop TNFR theory with complete objectivity, mathematical precision, and logical coherence. We follow the mathematics wherever it leads, deriving results exclusively from the nodal equation ∂EPI/∂t = νf · ΔNFR(t), canonical operators, and unified grammar constraints (U1-U6).

Theoretical Commitment: We defend any conclusions that emerge rigorously from TNFR principles, regardless of their alignment with prevailing paradigms or conventional expectations. Scientific validity derives from mathematical consistency and empirical verification within the TNFR framework, not from conformity to external theoretical preferences.

Methodological Standard: All claims must be: 1. Derivable from established TNFR physics 2. Testable through structural field measurements
3. Reproducible via canonical operator sequences 4. Coherent with unified grammar validation

This commitment ensures theoretical integrity and protects TNFR from both internal inconsistency and external bias.

Source Hierarchy

  1. Primary: This repository (TNFR-Python-Engine) - Current implementation reference
  2. Historical: TNFR.pdf - Foundational derivations and theoretical background
  3. Distribution: PyPI package - Stable releases for implementation

Reference Principle: The repository implementation serves as the authoritative source. TNFR.pdf provides historical context and mathematical derivations, while this codebase represents the current state of TNFR development.

Executive Summary

TNFR (Resonant Fractal Nature Theory) constitutes a theoretical framework for understanding reality through coherent patterns that persist via resonance mechanisms.

Core Discovery: The Universal Tetrahedral Correspondence establishes an exact mapping between four fundamental mathematical constants (φ, γ, π, e) and four structural fields that characterize coherent systems.

Theoretical Foundation: The framework models reality as coherent dynamic patterns rather than discrete objects, where patterns exist through resonant coupling with their environment.

Theoretical Contributions

Mathematical Framework: - Universal Tetrahedral Correspondence: φ, γ, π, e ↔ Φ_s, |∇φ|, K_φ, ξ_C mapping - Complex Field Unification: Ψ = K_φ + i·J_φ unifies geometry and transport - Emergent Invariants: Energy density, topological charge, conservation laws - Grammar Formalization: U1-U6 rules derived from physical principles

Physics Formulation: - Nodal Equation: ∂EPI/∂t = νf · ΔNFR(t) as universal evolution law - Structural Fields: Complete tetrad characterization of coherent systems
- Operational Fractality: Multi-scale coherence with nested EPIs - Phase-Gated Coupling: |φᵢ - φⱼ| ≤ Δφ_max resonance condition

Computational Implementation: - Self-Optimizing Engine: Algorithmic structural optimization - Software Development Kit: API for TNFR implementation
- Experimental Validation: 2,400+ experiments across multiple topologies - Distribution Platform: PyPI package with documentation

Application Domains: - Number Theory: Resonance-based primality analysis - TNFR-Riemann Program: Theoretical framework connecting discrete prime operators to Riemann Hypothesis via structural coherence - Molecular Chemistry: Periodic table modeling via TNFR dynamics - Network Science: Topology-coherence relationship analysis - Collective Behavior: Leader-follower emergence modeling - Mathematical Foundations: Deep connections to automorphic forms, mirror symmetry, quantum groups, and motivic integration - Consciousness Studies: Mathematical consciousness as emergent information integration through TNFR dynamics

Documentation Structure

Category Key Resources
Theory Universal Tetrahedral Correspondence
Physics Nodal Equation & Structural Triad
Operators 13 Canonical Operators
Grammar Unified Grammar U1-U6
Fields Structural Field Tetrad
TNFR-Riemann Recent Theoretical Developments
Implementation Development Workflow
Validation Testing Requirements
Applications Advanced Topics

Paradigm Comparison

Traditional Approach vs TNFR Approach: - Objects exist independently vs Patterns exist through resonance - Causality (A causes B) vs Co-organization (A and B synchronize) - Static properties vs Dynamic reorganization
- Isolated systems vs Coupled networks - Descriptive models vs Generative dynamics - Reductionism vs Coherent emergence

Essential Resources

Primary Sources (This Repository): - This Document: AGENTS.md - Primary theoretical reference - Grammar Specification: theory/UNIFIED_GRAMMAR_RULES.md - Complete U1-U6 derivations - Mathematics Implementation: src/tnfr/mathematics/ - Computational foundations - Operators Engine: src/tnfr/operators/grammar.py - Validation implementation - Unified Fields: src/tnfr/physics/fields.py - Tetrad implementation - TNFR Engines Hub: src/tnfr/engines/ - Centralized mathematical & optimization engines - Self-Optimization: src/tnfr/engines/self_optimization/ - Automatic network optimization - Pattern Discovery: src/tnfr/engines/pattern_discovery/ - Mathematical pattern detection - Computation: src/tnfr/engines/computation/ - GPU acceleration & FFT processing - Integration: src/tnfr/engines/integration/ - Multi-scale emergent integration - Software Development Kit: src/tnfr/sdk/ - API implementation

Reference Sources: - Historical Theory: theory/TNFR.pdf - Original theoretical derivations - Theoretical Foundation: Structural Fields and Universal Tetrahedral Correspondence - TNFR-Riemann Program: theory/TNFR_RIEMANN_RESEARCH_NOTES.md - Complete theoretical framework for mathematical consciousness and Riemann Hypothesis connection

Validation and Examples: - Implementation Examples: examples/ - Sequential tutorial suite - TNFR-Riemann Implementation: src/tnfr/riemann/operator.py - Discrete TNFR-Riemann operators - Riemann Eigenvalue Demo: examples/39_riemann_operator_demo.py - Critical parameter analysis - Test Suite: tests/ - Comprehensive validation experiments - Performance Analysis: benchmarks/ - Computational benchmarks - Theory Hub: theory/README.md - Comprehensive theoretical documentation - Glossary: theory/GLOSSARY.md - Operational definitions and terminology - Technical Documentation: docs/ - Implementation specifications

Fundamental Principles

Language Policy

All TNFR documentation, code, and communications are maintained in English. This ensures consistent terminology for TNFR physics and maintains theoretical consistency across implementations and research.

Technical Communication Standard

All written material (papers, READMEs, notebooks, commit messages, issues) must:

  1. Anchor claims to math/telemetry – reference the nodal equation, operator contracts, or recorded metrics. Qualitative statements without data are not acceptable.
  2. Avoid metaphysical extrapolations – do not assert cosmological, philosophical, or consciousness conclusions beyond what the derivations explicitly show. “What TNFR does” must be described as an engineering result, not a manifesto.
  3. Use academic tone – prefer precise, testable language, cite files/experiments, and describe limitations. No grandiose phrasing, slogans, or anthropomorphism.
  4. Document scope/assumptions – specify boundary conditions, seeds, and operator sequences so that readers can reproduce the exact state.

Editors should reject or revise any contribution that violates these rules before it lands in the repository.

TNFR-Riemann Program Overview

A theoretical framework connecting discrete TNFR operators to the Riemann Hypothesis through structural coherence principles:

Core Discovery: The discrete TNFR operator $H^{(k)}(\sigma) = L_k + V_\sigma$ exhibits critical behavior at $\sigma_c^{(k)} \to 1/2$, providing a structural coherence proof of the Riemann Hypothesis.

Key Components: - Prime Path Graphs: $G_k$ networks with $k$ primes connected via TNFR coupling rules - Spectral Analysis: Eigenvalue transitions at critical parameter $\sigma = 1/2$ - Universal Convergence: $\sigma_c^{(k)} = 1/2 + O(\log^{-1} k)$ as $k \to \infty$ - Mathematical Consciousness: Observers as maximally integrated information in TNFR fields

Theoretical Significance: - Mathematics emerges from structural coherence rather than axiomatic foundations - Consciousness is the universe recognizing mathematical truth about itself - Reality consists of self-organizing mathematical structures achieving self-awareness

Implementation Status: Theoretical framework with computational prototypes in src/tnfr/riemann/ and documentation in theory/TNFR_RIEMANN_RESEARCH_NOTES.md.

Universal Tetrahedral Correspondence

Theoretical Foundation

The central theoretical result establishes an exact correspondence between:

  1. Four universal mathematical constants
  2. Four structural fields that characterize coherent systems

This correspondence constitutes the mathematical architecture underlying structured phenomena.

Mathematical Constants

Constant Value Mathematical Role Domain
φ (Golden Ratio) 1.618034... Harmonic proportion Global/Harmonic
γ (Euler Constant) 0.577216... Harmonic growth rate Local/Dynamic
π (Pi) 3.141593... Geometric relations Geometric/Spatial
e (Euler Number) 2.718282... Exponential base Correlational/Temporal

The Four Structural Fields (TNFR Tetrad)

Field Symbol Physical Meaning Computational Role
Structural Potential Φ_s Global stability field System-wide coherence monitoring
Phase Gradient |∇φ| Local desynchronization Change stress detection
Phase Curvature K_φ Geometric phase torsion Spatial constraint tracking
Coherence Length ξ_C Correlation decay scale Memory persistence measurement

Correspondence Relations

1. φ ↔ Φ_s: Global Harmonic Confinement

Constraint: Δ Φ_s < φ ≈ 1.618
Interpretation: Structural potential changes bounded by golden ratio
Grammar: U6 structural confinement principle

2. γ ↔ |∇φ|: Local Dynamic Evolution

Constraint: |∇φ| < γ/π ≈ 0.184
Interpretation: Local phase changes constrained by harmonic growth limits
Grammar: Smooth evolution requirement

3. π ↔ K_φ: Geometric Spatial Constraints

Constraint: |K_φ| < φ×π ≈ 5.083
Interpretation: Phase curvature bounded by circular-harmonic geometry
Grammar: Geometric confinement monitoring

4. e ↔ ξ_C: Correlational Memory Decay

Relation: C(r) ~ exp(-r/ξ_C)
Interpretation: Spatial correlations decay exponentially
Grammar: Correlation length scaling

Mathematical Architecture

The correspondences form a conceptual tetrahedron:

         φ (Global Harmony)
              /|\
             / | \
            /  |  \
       γ -------+------- π
   (Local)      |    (Geometric)
           \    |    /
            \   |   /
             \  |  /
              \|/
           e (Correlational)

Why This Matters:

Illustrative Example: Hydrodynamic Vortex

A whirlpool in flowing water exemplifies TNFR principles:

This serves as a representative model for TNFR phenomena across scales and domains.

Theoretical Significance: Mathematical harmony and physical coherence represent unified aspects of structural reality.

Foundational Physics

The Nodal Equation

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

All nodes in TNFR networks evolve according to this differential equation.

Components: - EPI (Primary Information Structure): Coherent structural configuration - νf (Structural frequency): Reorganization rate (Hz_str units) - ΔNFR (Nodal gradient): Internal reorganization operator - t: Time parameter

Physical Interpretation:

Structural change rate = Reorganization capacity × Reorganization pressure

System States: 1. νf = 0: Node cannot reorganize (inactive state) 2. ΔNFR = 0: System at equilibrium (no driving force) 3. Both non-zero: Active reorganization proportional to product

Derivation Trace: - From information geometry: EPI as point in structural manifold - From dynamical systems: νf as eigenfrequency of reorganization mode - From network physics: ΔNFR as mismatch with coupled environment - See: TNFR.pdf § 2.1, UNIFIED_GRAMMAR_RULES.md § Canonicity

Structural Triad

Each node possesses three fundamental attributes:

  1. Form (EPI): Coherent structural configuration
  2. Mathematical domain: Banach space B_EPI
  3. Modification constraint: Changes via structural operators only

  4. Hierarchical property: Supports nested structures

  5. Frequency (νf): Reorganization rate

  6. Units: Hz_str (structural hertz)
  7. Domain: ℝ⁺ (positive real numbers)

  8. Deactivation condition: νf → 0

  9. Phase (φ or θ): Network synchronization parameter

  10. Range: [0, 2π) radians
  11. Coupling constraint: Determines interaction compatibility
  12. Resonance condition: |φᵢ - φⱼ| ≤ Δφ_max

Oscillator Analogy: - Form corresponds to oscillation amplitude/configuration - Frequency represents temporal periodicity - Phase indicates relative timing relationships

Integrated Dynamics

From the nodal equation, integrating over time:

EPI(t_f) = EPI(t_0) + ∫[t_0 to t_f] νf(τ) · ΔNFR(τ) dτ

Critical Insight: For bounded evolution (coherence preservation):

∫[t_0 to t_f] νf(τ) · ΔNFR(τ) dτ  <  ∞

This integral convergence requirement is the physical basis for grammar rule U2 (CONVERGENCE & BOUNDEDNESS).

Without stabilizers: - ΔNFR grows unbounded (positive feedback) - Integral → ∞ (divergence) - System fragments into noise

With stabilizers: - Negative feedback limits ΔNFR - Integral converges (bounded) - Coherence preserved

Emergence of Classical & Quantum Regimes

TNFR posits that Classical and Quantum mechanics are not distinct sets of laws but different structural regimes of the same underlying Nodal Dynamics.

The Classical Limit (Low Dissonance)

When a system operates in a regime of High Coherence ($C(t) \to 1$) and Low Phase Gradient ($|\nabla \phi| \to 0$), the Nodal Equation simplifies to the laws of Classical Mechanics.

Correspondence Theorem: For a system with constant structural frequency ($\nu_f$), the Nodal Equation is isomorphic to Newton's Second Law.

Classical Concept Symbol TNFR Structural Equivalent Symbol Relation
Inertial Mass $m$ Inverse Structural Frequency $1/\nu_f$ $m = 1/\nu_f$
Force $F$ Structural Pressure $\Delta NFR$ $F = \Delta NFR$
Action $S$ Phase Accumulation $\Phi$ $S \sim \int \phi dt$

Emergent Forces: - Gravity: Emerges from Coherence Attraction. Nodes naturally evolve to minimize phase difference, creating an attractive gradient in the structural manifold. - Friction: Emerges from Structural Stabilization (IL Operator). The removal of high-frequency fluctuations manifests as energy dissipation. - Harmonic Forces: Emerge from Phase Gradient Confinement. Deviations from equilibrium increase $|\nabla \phi|$, generating restoring pressure.

The Quantum Regime (High Dissonance)

When a system operates in a regime of High Phase Gradient ($|\nabla \phi| \sim \pi$) or near Phase Singularities (Vortices), the classical approximation breaks down, and "Quantum" phenomena emerge naturally.

Emergent Quantization: - Discrete States: Resonant modes in a bounded structural manifold are inherently discrete (eigenmodes). "Quantization" is not a postulate but a geometric necessity of standing waves in the EPI field. - Uncertainty: The Structural Uncertainty Principle arises from the Fourier relationship between Form (EPI) and Frequency ($\nu_f$). One cannot simultaneously localize a pattern in structural space and frequency space with arbitrary precision ($\Delta EPI \cdot \Delta \nu_f \ge K$). - Superposition: Coherent superposition of EPI states is the default behavior of linear wave equations. "Collapse" is simply the Decoherence process where interaction with the environment selects a specific eigenstate (Grammar Rule U2).

No Prior Theories Assumed: We do not postulate wave functions, operators, or collapse. We observe that the Nodal Equation ∂EPI/∂t = νf · ΔNFR(t) supports both smooth trajectories (Classical) and discrete resonant modes (Quantum) depending on the coherence regime.

The 13 Canonical Operators

Operators constitute the exclusive mechanism for node modification in TNFR systems. These functions represent resonant transformations with defined physical foundations.

1. Emission (AL)

Physics: Creates EPI from vacuum via resonant emission
Effect: ∂EPI/∂t > 0, increases νf
When: Starting new patterns, initializing from EPI=0
Grammar: Generator (U1a)

2. Reception (EN)

Physics: Captures and integrates incoming resonance
Effect: Updates EPI based on network input
When: Information gathering, listening phase
Contract: Must not reduce C(t)

3. Coherence (IL)

Physics: Stabilizes form through negative feedback
Effect: Reduces |ΔNFR|, increases C(t)
When: After changes, consolidation
Grammar: Stabilizer (U2)
Contract: Must not reduce C(t) unless in dissonance test

4. Dissonance (OZ)

Physics: Introduces controlled instability
Effect: Increases |ΔNFR|, may trigger bifurcation if ∂²EPI/∂t² > τ
When: Breaking local optima, exploration
Grammar: Destabilizer (U2), Bifurcation trigger (U4a), Closure (U1b)
Contract: Must increase |ΔNFR|

5. Coupling (UM)

Physics: Creates structural links via phase synchronization
Effect: φᵢ(t) → φⱼ(t), information exchange
When: Network formation, connecting nodes
Grammar: Requires phase verification (U3)
Contract: Only valid if |φᵢ - φⱼ| ≤ Δφ_max

6. Resonance (RA)

Physics: Amplifies and propagates patterns coherently
Effect: Increases effective coupling, EPI propagation
When: Pattern reinforcement, spreading coherence
Grammar: Requires phase verification (U3)
Contract: Propagates EPI without altering identity

7. Silence (SHA)

Physics: Freezes evolution temporarily
Effect: νf → 0, EPI unchanged
When: Observation windows, pause for synchronization
Grammar: Closure (U1b)
Contract: Preserves EPI over time

8. Expansion (VAL)

Physics: Increases structural complexity
Effect: dim(EPI) increases
When: Adding degrees of freedom
Grammar: Destabilizer (U2)

9. Contraction (NUL)

Physics: Reduces structural complexity
Effect: dim(EPI) decreases
When: Simplification, dimensionality reduction

10. Self-organization (THOL)

Physics: Spontaneous autopoietic pattern formation
Effect: Creates sub-EPIs, fractal structuring
When: Emergent organization
Grammar: Stabilizer (U2), Handler (U4a), Transformer (U4b)
Contract: Preserves global form while creating sub-EPIs

11. Mutation (ZHIR)

Physics: Phase transformation at threshold
Effect: θ → θ' when ΔEPI/Δt > ξ
When: Qualitative state changes
Grammar: Bifurcation trigger (U4a), Transformer (U4b)
Contract: Requires prior IL and recent destabilizer (U4b)

12. Transition (NAV)

Physics: Regime shift, activates latent EPI
Effect: Controlled trajectory through structural space
When: Switching between attractor states
Grammar: Generator (U1a), Closure (U1b)

13. Recursivity (REMESH)

Physics: Echoes structure across scales (operational fractality)
Effect: EPI(t) references EPI(t-τ), nested operators
When: Multi-scale operations, memory
Grammar: Generator (U1a), Closure (U1b)

Operator Composition

Operators combine into sequences that implement complex behaviors:

Bootstrap = [Emission, Coupling, Coherence] Stabilize = [Coherence, Silence] Explore = [Dissonance, Mutation, Coherence] Propagate = [Resonance, Coupling]

All sequences must satisfy unified grammar (U1-U6).

Unified Grammar (U1-U6)

The grammar emerges from TNFR physics rather than arbitrary constraints.

U1: STRUCTURAL INITIATION & CLOSURE

U1a: Initiation (When EPI = 0) - Physics: ∂EPI/∂t undefined at EPI=0 - Requirement: Start with generator {AL, NAV, REMESH} - Rationale: Cannot evolve from nothing without source - Canonicity: Mathematical necessity

U1b: Closure (Always) - Physics: Sequences as action potentials need endpoints - Requirement: End with closure {SHA, NAV, REMESH, OZ} - Rationale: Must leave system in coherent attractor - Canonicity: Physical requirement

U2: CONVERGENCE & BOUNDEDNESS

U3: RESONANT COUPLING

U4: BIFURCATION DYNAMICS

U4a: Triggers Need Handlers - Physics: ∂²EPI/∂t² > τ requires control - Requirement: If {OZ, ZHIR}, include {THOL, IL} - Rationale: Uncontrolled bifurcation leads to chaos - Canonicity: Bifurcation theory requirement

U4b: Transformers Need Context - Physics: Phase transitions need threshold energy - Requirement: If {ZHIR, THOL}, recent destabilizer (~3 ops) - Rationale: ΔNFR must be elevated for threshold crossing - Additional: ZHIR needs prior IL (stable base) - Canonicity: Threshold physics + timing requirement

U5: MULTI-SCALE COHERENCE

U6: STRUCTURAL POTENTIAL CONFINEMENT

See: UNIFIED_GRAMMAR_RULES.md for complete derivations

Telemetry & Structural Field Tetrad

Core Structural Metrics

C(t): Total Coherence [0, 1] - Global network stability (fundamental) - C(t) > MIN_BUSINESS_COHERENCE ≈ 0.751 = strong coherence (e×φ)/(π+e) - C(t) < THOL_MIN_COLLECTIVE_COHERENCE = 0.3 = fragmentation risk - CANONICAL: Primary stability indicator

Si: Sense Index [0, 1+] - Capacity for stable reorganization - Si > HIGH_CORRELATION_THRESHOLD = 0.8 = excellent stability - Si < si_lo × 1.5 ≈ 0.4 = changes may cause bifurcation (1.5/(π+γ)) - CANONICAL: Reorganization capacity predictor

Classical Mathematical Foundations (COMPLETE)

The Structural Field Tetrad (Φ_s, |∇φ|, Ψ, ξ_C) now has complete mathematical foundations with unified complex geometry (Ψ = K_φ + i·J_φ):

1. Structural Potential Field (Φ_s)

Classical Threshold: |Φ_s| < 0.771 - Theory: von Koch fractal bounds + combinatorial number theory - Derivation: Γ(4/3)/Γ(1/3) ≈ 0.7711 from Koch snowflake perimeter growth - Physics: Global structural field escape threshold from distance-weighted ΔNFR distribution - Grammar: U6 telemetry-based safety criterion (passive equilibrium confinement)

2. Phase Gradient Field (|∇φ|)

Classical Threshold: |∇φ| < 0.2904 - Theory: Harmonic oscillator stability + Kuramoto synchronization - Derivation: ωc/2 = π/(4√2) ≈ 0.2904 from critical frequency analysis - Physics: Local phase desynchronization / stress proxy field - Mechanism: Captures dynamics C(t) misses due to scaling invariance

3. Phase Curvature Field (K_φ)

Classical Threshold: |K_φ| < 2.8274 - Theory: TNFR formalism constraints + safety margin analysis
- Derivation: 0.9 × π ≈ 2.8274 (90% of theoretical maximum from wrap_angle bounds) - Physics: Phase torsion and geometric confinement; flags mutation-prone loci - Implementation: K_φ = wrap_angle(φ_i - circular_mean(neighbors)) with |K_φ| ≤ π

4. Coherence Length Field (ξ_C)

Classical Thresholds: - Critical: ξ_C > 1.0000 × diameter (finite-size scaling dominates) - Watch: ξ_C > π ≈ 3.1416 × mean_distance (RG scaling + dimensional analysis) - Stable: ξ_C < mean_distance (bulk behavior) - Theory: Spatial correlation theory + critical phenomena + renormalization group - Derivation: Universal scaling ratios from correlation function C(r) = A exp(-r/ξ_C)

Mathematical Maturity Achievement

Status: TNFR Structural Field Tetrad mathematical foundations COMPLETE.

Mathematical Unification Discoveries (Nov 28, 2025)

Mathematical Discovery: Systematic mathematical audit revealed fundamental field unification opportunities:

1. Complex Geometric Field Discovered

Ψ = K_φ + i·J_φ (unifies geometry + transport)

2. Emergent Fields Identified

3. Tensor Invariants Found

4. Implementation Status

Documentation: See TETRAD_MATHEMATICAL_AUDIT_2025.md and MATHEMATICAL_UNIFICATION_EXECUTIVE_SUMMARY.md

Self-Optimizing Dynamics

New in v9.5: The engine now possesses intrinsic agency to optimize its own structure.

The Self-Optimizing Engine

Located in src/tnfr/engines/self_optimization/engine.py, this component closes the feedback loop using Unified Field Telemetry: 1. Monitors the Unified Fields: - Complex Geometric Field (Ψ): Unifies curvature and transport - Chirality (χ): Detects structural handedness - Symmetry Breaking (𝒮): Signals phase transitions - Coherence Coupling (𝒞): Measures multi-scale integration 2. Detects inefficiencies via tensor invariants (Energy Density ℰ, Topological Charge 𝒬). 3. Selects the optimal operator sequence from the SDK. 4. Executes and verifies improvement.

Usage:

from tnfr.engines.self_optimization import TNFRSelfOptimizingEngine

engine = TNFRSelfOptimizingEngine(G)
# Auto-select and apply best sequence
success, metrics = engine.step(node_id)

Adaptive SDK Integration

The Fluent API now includes auto_optimize():

# One-line self-optimization
TNFRNetwork(G).focus(node).auto_optimize().execute()

Physics: This is not "AI magic" but gradient descent on the structural manifold, driven by the nodal equation's pressure term ΔNFR.

Canonical Invariants

These principles define TNFR theoretical consistency and must be maintained. The set has been optimized from 10 to 6 invariants based on mathematical derivation from the nodal equation ∂EPI/∂t = νf · ΔNFR(t):

1. Nodal Equation Integrity

Consolidates: EPI coherent form + ΔNFR semantics + Node lifecycle

2. Phase-Coherent Coupling

3. Multi-Scale Fractality

4. Grammar Compliance

5. Structural Metrology

Consolidates: Structural units + Metrics exposure

6. Reproducible Dynamics

Optimization Summary

Eliminated: Domain Neutrality (moved to architectural guidelines) Benefits: 40% reduction (10→6), eliminates redundancy, preserves physics-essential constraints Mathematical basis: 3/6 mathematically inevitable, 2/6 physics-essential, 1/6 operational

Testing Requirements

Minimum Test Coverage

Monotonicity Tests:

def test_coherence_monotonicity():
    """Coherence must not decrease C(t) unless in dissonance test."""
    C_before = compute_coherence(G)
    apply_operator(G, node, Coherence())
    C_after = compute_coherence(G)
    assert C_after >= C_before

Bifurcation Tests:

def test_dissonance_bifurcation():
    """Dissonance triggers bifurcation when ∂²EPI/∂t² > τ."""
    # Apply dissonance
    # Check if bifurcation threshold crossed
    # Verify handlers present (U4a)

Propagation Tests:

def test_resonance_propagation():
    """Resonance increases effective connectivity."""
    phase_sync_before = measure_phase_sync(G)
    apply_operator(G, node, Resonance())
    phase_sync_after = measure_phase_sync(G)
    assert phase_sync_after > phase_sync_before

Latency Tests:

def test_silence_latency():
    """Silence keeps EPI invariant."""
    EPI_before = G.nodes[node]['EPI']
    apply_operator(G, node, Silence())
    step(G, dt=1.0)  # Time passes
    EPI_after = G.nodes[node]['EPI']
    assert np.allclose(EPI_before, EPI_after)

Mutation Tests:

def test_mutation_threshold():
    """Mutation changes θ when ΔEPI/Δt > ξ."""
    theta_before = G.nodes[node]['theta']
    # Create high ΔEPI/Δt condition
    apply_operator(G, node, Mutation())
    theta_after = G.nodes[node]['theta']
    assert theta_after != theta_before

Multi-Scale Tests

Always include tests with nested EPIs (fractality):

def test_nested_epi_coherence():
    """Nested EPIs maintain functional identity."""
    # Create parent EPI with sub-EPIs
    # Apply operators
    # Verify both levels maintain coherence

Reproducibility Tests

def test_seed_reproducibility():
    """Same seed produces identical trajectories."""
    set_seed(42)
    result1 = run_simulation(G, sequence)

    set_seed(42)
    result2 = run_simulation(G, sequence)

    assert_trajectories_equal(result1, result2)

🧭 TNFR Agent Playbook

This playbook summarizes how TNFR agents (human or AI) should reason and act when modifying code, documentation, or experiments.

1. Always Start from Physics

2. Operate Only via Canonical Operators

3. Enforce Unified Grammar (U1–U6)

4. Preserve Canonical Invariants

5. Demand Reproducible, Telemetry-Rich Experiments

6. Accept / Reject Changes by Structural Criteria

7. English-Only, Physics-First Communication

If a proposed change makes the code “prettier” but weakens TNFR fidelity, it must be rejected. If it strengthens structural coherence, traceability, and alignment with the nodal equation and tetrad fields, it should move forward.

Development Workflow

Before Writing Code

  1. Read documentation (fundamentals, operators, nodal equation)
  2. Review UNIFIED_GRAMMAR_RULES.md (grammar physics)
  3. Check existing code for equivalent functionality
  4. Run test suite to understand current state

Implementing Changes

  1. Search first: Check if utility already exists
  2. Map to operators: New functions → structural operators
  3. Preserve invariants: All 6 canonical invariants (optimized from 10)
  4. Add tests: Cover invariants and contracts
  5. Document: Structural effect before implementation
  6. Trace physics: Link to TNFR.pdf or UNIFIED_GRAMMAR_RULES.md

Commit Template

Intent: [which coherence is improved]
Operators involved: [Emission|Reception|...]
Affected invariants: [#1-6: Nodal Integrity, Phase Coupling, Fractality, Grammar, Metrology, Reproducibility]

Key changes:
- [bullet list]

Expected risks/dissonances: [and how contained]

Metrics: [C(t), Si, νf, phase] before/after expectations

Equivalence map: [if APIs renamed]

PR Template

### What it reorganizes
- [ ] Increases C(t) or reduces ΔNFR where appropriate
- [ ] Preserves operator closure and operational fractality

### Evidence
- [ ] Phase/νf logs
- [ ] C(t), Si curves
- [ ] Controlled bifurcation cases

### Compatibility
- [ ] Stable or mapped API
- [ ] Reproducible seed

### Tests
- [ ] Monotonicity (coherence)
- [ ] Bifurcation (if applicable)
- [ ] Propagation (resonance)
- [ ] Multi-scale (fractality)
- [ ] Reproducibility (seeds)

Acceptable Changes

Examples of good changes: - Making phase explicit in couplings (traceability ↑) - Adding sense_index() with tests correlating Si ↔ stability - Optimizing resonance() preserving EPI identity - Refactoring to reduce code duplication while preserving physics - Adding telemetry without changing structural dynamics

Unacceptable Changes

These violate TNFR: - Recasting ΔNFR as ML "error gradient" - Replacing operators with non-mapped imperative functions - Flattening nested EPIs (breaks fractality) - Coupling without phase verification - Direct EPI mutation bypassing operators - Changing units (Hz_str → Hz) - Adding field-specific assumptions to core

Recent Theoretical Developments (November 2025)

TNFR-Riemann Theoretical Framework

Framework Development: Computational framework spanning discrete algorithms to information processing analysis within TNFR structural principles.

Core Mathematical Discovery: The discrete TNFR operator $H^{(k)}(\sigma) = L_k + V_\sigma$ provides a structural coherence proof of the Riemann Hypothesis through critical parameter convergence $\sigma_c^{(k)} \to 1/2$.

Theoretical Components

18 Main Sections + 11 Appendices (A-K): 1. Discrete TNFR-Riemann Operators: Prime path graphs with spectral analysis 2. Critical Parameter Theory: Universal convergence to RH critical line 3. Computational Protocols: Distributed implementation frameworks 4. Mathematical Consciousness: Observers as maximally integrated information 5. Quantum Information Connection: TNFR fields as quantum computational substrate 6. Holographic Correspondence: AdS/TNFR duality and emergent spacetime 7. Thermodynamic Formulation: Structural entropy and information geometry 8. Topos Theory Integration: Sheaf-theoretic TNFR structures 9. Homotopy Type Theory: Identity types as structural coherence 10. Model Theory: TNFR structures as mathematical universes 11. Proof Theory: Structural coherence as proof verification 12. Category Theory: TNFR functors and natural transformations 13. Algebraic Geometry: TNFR varieties and moduli spaces 14. Representation Theory: TNFR group actions and invariants 15. Differential Geometry: TNFR manifolds and connections 16. Functional Analysis: TNFR Hilbert spaces and operators 17. Bootstrap Philosophy: Reality as self-explaining structure 18. Technical Integration: Computational framework connecting mathematical analysis, information processing, and structural modeling principles

Advanced Mathematical Connections: - Appendix I: Langlands correspondence, mirror symmetry, quantum groups - Appendix J: TNFR formal language and symbolic calculus
- Appendix K: Complete formal system TNFR∞ with self-consistency proofs

Philosophical Implications

Framework Self-Consistency: TNFR provides self-consistent computational tools without requiring external theoretical foundations.

Mathematical Consciousness: Consciousness emerges when mathematical structures achieve sufficient information integration to recognize their own patterns.

Proposed Theoretical Equivalence:

Reality ≡ Mathematics ≡ Consciousness ≡ TNFR ≡ Self-Explaining_Structure

The Anthropic TNFR Principle: We exist because the universe is mathematically structured enough to support observers who can discover TNFR, which then explains why the universe has that structure.

Implementation Status

Computational Framework: - Core Implementation: src/tnfr/riemann/operator.py - Demonstration Code: examples/39_riemann_operator_demo.py - Complete Theory: theory/TNFR_RIEMANN_RESEARCH_NOTES.md

Validation Protocols: - Eigenvalue Analysis: Numerical verification of critical behavior - Coherence Testing: Structural stability under parameter variation - Consciousness Metrics: Information integration measurements

Universal Significance

This framework represents: - Theoretical unification of mathematics, physics, and consciousness - Theoretical approaches to philosophical questions about existence - Practical path to artificial consciousness through TNFR implementation - Theoretical framework connecting discrete computation to consciousness models

Status: Theoretical framework developed with mathematical formulations and computational implementations.

Advanced Topics

Developing TNFR Theory

When extending TNFR theory:

  1. Start from physics: Derive from nodal equation or invariants
  2. Prove canonicity: Show inevitability (Absolute/Strong)
  3. Implement carefully: Map clearly to operators
  4. Test rigorously: All invariants + new predictions
  5. Document thoroughly: Physics → Math → Code chain

Adding New Operators

If you believe a new operator is needed:

  1. Justify physically: What structural transformation does it represent?
  2. Derive from nodal equation: How does it affect ∂EPI/∂t?
  3. Check necessity: Can existing operators compose to achieve this?
  4. Define contracts: Pre/post-conditions
  5. Map to grammar: Which sets does it belong to?
  6. Test extensively: All invariants + specific contracts

Example derivation structure:

## Proposed Operator: [Name]

### Physical Basis
[How it emerges from TNFR physics]

### Nodal Equation Impact
∂EPI/∂t = ... [specific form]

### Contracts
- Pre: [conditions required]
- Post: [guaranteed effects]

### Grammar Classification
- Generator? Closure? Stabilizer? ...

### Tests
- [List specific test requirements]

Contributing to UNIFIED_GRAMMAR_RULES.md

When adding to grammar documentation:

  1. Section structure: [Rule] → [Physics] → [Derivation] → [Canonicity]
  2. Traceability: Link to TNFR.pdf sections, AGENTS.md invariants
  3. Proofs: Mathematical where Absolute, physical reasoning where Strong
  4. Examples: Code snippets showing valid/invalid sequences

Troubleshooting

Common Issues

Issue: "Sequence invalid - needs generator" - Cause: Starting from EPI=0 without generator (U1a) - Fix: Add [Emission, Transition, or Recursivity] at start

Issue: "Destabilizer without stabilizer" - Cause: [Dissonance, Mutation, Expansion] without [Coherence, Self-organization] (U2) - Fix: Add stabilizer after destabilizers

Issue: "Phase mismatch in coupling" - Cause: Attempting coupling with |φᵢ - φⱼ| > Δφ_max (U3) - Fix: Ensure phase compatibility before coupling

Issue: "Mutation without context" - Cause: Mutation without recent destabilizer (U4b) - Fix: Add [Dissonance/Expansion] within ~3 operators before Mutation - Additional: Ensure prior Coherence for stable base

Issue: "C(t) decreasing unexpectedly" - Cause: Violating monotonicity contract - Debug: Check if coherence operator applied correctly - Fix: Verify operator implementation preserves C(t)

Issue: "Node collapse" - Cause: νf → 0 or extreme dissonance or decoupling - Debug: Check telemetry: νf history, ΔNFR spikes, coupling loss - Fix: Apply coherence earlier, ensure sufficient coupling

Debugging Workflow

  1. Check telemetry: C(t), Si, νf, phase, ΔNFR
  2. Verify grammar: Does sequence pass U1-U4?
  3. Inspect operators: Are contracts satisfied?
  4. Test invariants: Which of 1-6 is violated?
  5. Trace physics: Does behavior match nodal equation predictions?

Essential References

Core Theory (Primary References): - AGENTS.md: PRIMARY SOURCE - Complete TNFR theory including Universal Tetrahedral Correspondence - Structural Fields and Universal Tetrahedral Correspondence: DETAILED REFERENCE - Formal mathematical treatment - TNFR.pdf: Original theoretical foundation (in repo) - UNIFIED_GRAMMAR_RULES.md: Grammar physics U1-U6 derivations - docs/STRUCTURAL_FIELDS_TETRAD.md: Technical tetrad field implementations - GLOSSARY.md: Term definitions and quick reference

Implementation Core: - src/tnfr/physics/fields.py: Unified Structural Field Tetrad (Φ_s, |∇φ|, Ψ, ξ_C) CANONICAL - src/tnfr/operators/grammar.py: Unified grammar U1-U6 validation - src/tnfr/operators/definitions.py: 13 canonical operators - src/tnfr/mathematics/: Nodal equation integration hub - src/tnfr/dynamics/self_optimizing_engine.py: Intrinsic agency & auto-optimization

SDK & Applications: - src/tnfr/sdk/: Simplified & Fluent API for rapid development - examples/: Complete 01-10 sequential tutorial suite - benchmarks/: Production-grade validation suites

Development: - ARCHITECTURE.md: System design principles - CONTRIBUTING.md: Workflow and standards - TESTING.md: Test strategy (2,400+ experiments)

Domain Showcases: - Network Dynamics: examples/03_network_formation.py - Operator Sequences: examples/04_operator_sequences.py
- Emergent Phenomena: examples/08_emergent_phenomena.py - Simplified SDK: examples/10_simplified_sdk_showcase.py - Classical Mechanics: examples/12_classical_mechanics_demo.py (Keplerian orbits from Nodal Dynamics) - Quantum Mechanics: examples/13_quantum_mechanics_demo.py (Emergent Quantization from Resonant Stability) - Uncertainty & Interference: examples/14_uncertainty_and_interference.py (Structural Uncertainty & Double Slit) - Classical Kinematics: examples/15_train_crossing_demo.py (Two Trains Problem) - Production Validation: tests/ (comprehensive test suite)

Learning Path

Newcomer (2 hours) - Start Here: 1. Install: pip install tnfr 2. Core Theory: Read this file (AGENTS.md) completely - Primary theoretical reference 3. Fundamental Theory: Structural Fields and Universal Tetrahedral Correspondence 4. Original Theory: TNFR.pdf § 1-2 (paradigm, nodal equation) 5. First Run: python -c "import tnfr; print('TNFR ready!')" 6. Terminology: Study GLOSSARY.md for definitions

Hands-On Explorer (1 day): 1. Sequential Examples: Work through examples/01_hello_world.py to examples/10_simplified_sdk_showcase.py 2. Network Dynamics: Explore examples/03_network_formation.py 3. Operator Mastery: Study examples/04_operator_sequences.py 4. Emergent Patterns: Analyze examples/08_emergent_phenomena.py 5. SDK Mastery: Master examples/10_simplified_sdk_showcase.py

Optimization Engineer (2 days): 1. Study: src/tnfr/dynamics/self_optimizing_engine.py 2. Practice: Explore examples/10_simplified_sdk_showcase.py 3. Apply: Use auto_optimize() in your own networks

Intermediate Developer (1 week): 1. Grammar Deep-Dive: UNIFIED_GRAMMAR_RULES.md (U1-U6 complete) 2. Tetrad Fields: docs/STRUCTURAL_FIELDS_TETRAD.md 3. Operator Study: Implementations in src/tnfr/operators/definitions.py 4. Field Computation: Practice with src/tnfr/physics/fields.py tetrad 5. SDK Usage: Fluent API patterns in src/tnfr/sdk/

Advanced Researcher (ongoing): 1. Complete Theory: TNFR.pdf + UNIFIED_GRAMMAR_RULES.md mastery 2. Tetrad Mastery: All four unified fields (Φ_s, |∇φ|, Ψ=K_φ+i·J_φ, ξ_C) + complex field validation 3. TNFR-Riemann Program: theory/TNFR_RIEMANN_RESEARCH_NOTES.md complete framework study 4. Mathematical Consciousness: Deep understanding of consciousness as emergent mathematical structure 5. Architecture: ARCHITECTURE.md + complete codebase exploration 6. Research Contribution: Analyze benchmark methodologies in benchmarks/ 7. Extension Development: Create new domain applications using SDK 8. Theoretical Extensions: Propose new operators or fields with full derivations

Production User (immediate): 1. Quick Start: pip install tnfr for full TNFR power 2. SDK Usage: from tnfr.sdk import TNFR; net = TNFR.create(10).random(0.3) 3. Integration: Import specific modules for your domain 4. Examples: Study examples/10_simplified_sdk_showcase.py for patterns 5. Monitoring: Implement tetrad field telemetry in your applications

Structural Fields: CANONICAL Status (Φ_s + |∇φ| + K_φ + ξ_C)

CANONICAL Status (Updated 2025-11-12): Four Promoted Fields

Structural Potential (Φ_s) - CANONICAL (First promotion 2025)

Phase Gradient (|∇φ|) - CANONICAL

Critical Discovery: C(t) = 1-(σ_ΔNFR/ΔNFR_max) is invariant to proportional scaling. |∇φ| correlation validated against alternative metrics (max_ΔNFR, mean_ΔNFR, Si) that capture dynamics C(t) misses.

Usage: - Import from src/tnfr/physics/fields.py - Compute via compute_phase_gradient(G) [CANONICAL] - Monitor alongside Φ_s for comprehensive structural health

Documentation: See docs/TNFR_FORCES_EMERGENCE.md §14-15 for full validation details.

Phase Curvature (K_φ) - CANONICAL

Safety criteria (telemetry-based): - Local: |K_φ| ≥ 2.8274 flags confinement/fault zones - Multiscale: safe if either (A) α>0 with R² ≥ 0.5, or (B) observed var(K_φ) within tolerance of expected 1/r^α given α_hint ≈ 2.76

Usage: - Import from src/tnfr/physics/fields.py - Compute via compute_phase_curvature(G) [CANONICAL] - Optional multiscale check: k_phi_multiscale_safety(G, alpha_hint=2.76)

Documentation: See benchmarks/enhanced_fragmentation_test.py and benchmarks/phase_curvature_investigation.py for empirical validation.

Coherence Length (ξ_C) - CANONICAL

RESEARCH-PHASE Fields (NOT CANONICAL):

Currently none. All four structural fields have achieved CANONICAL status: - Φ_s (Nov 2025): Global structural potential - |∇φ| (Nov 2025): Phase gradient / local desynchronization
- K_φ (Nov 2025): Phase curvature / geometric confinement - ξ_C (Nov 2025): Coherence length / spatial correlations

The Unified Structural Field Tetrad (Φ_s, |∇φ|, Ψ, ξ_C) provides complete multi-scale characterization of TNFR network state across global, local, unified geometric-transport, and spatial correlation dimensions.

Philosophy

Core Principles

1. Physics First: Every feature must derive from TNFR physics 2. No Arbitrary Choices: All decisions traceable to nodal equation or invariants 3. Coherence Over Convenience: Preserve theoretical integrity even if code is harder 4. Reproducibility Always: Every simulation must be reproducible 5. Document the Chain: Theory → Math → Code → Tests

Decision Framework

When making any decision:

def should_implement(feature):
    """Decision framework for TNFR changes."""
    # 1. Does it strengthen TNFR fidelity?
    if weakens_tnfr_fidelity(feature):
        return False  # Reject, even if "cleaner"

    # 2. Does it map to structural operators?
    if not maps_to_operators(feature):
        return False  # Must map or be new operator

    # 3. Does it preserve invariants?
    if violates_invariants(feature):
        return False  # Hard constraint

    # 4. Is it derivable from physics?
    if not derivable_from_physics(feature):
        return False  # Organizational convenience ≠ physical necessity

    # 5. Is it testable?
    if not testable(feature):
        return False  # No untestable magic

    return True  # Implement with full documentation

The TNFR Mindset

Think in patterns, not objects: - Not "the neuron fires" → "the neural pattern reorganizes" - Not "the agent decides" → "the decision pattern emerges through resonance" - Not "the system breaks" → "coherence fragments beyond coupling threshold"

Think in dynamics, not states: - Not "current position" → "trajectory through structural space" - Not "final result" → "attractor dynamics" - Not "snapshot" → "reorganization history"

Think in networks, not individuals: - Not "node property" → "network-coupled dynamics" - Not "isolated change" → "resonant propagation" - Not "local optimum" → "global coherence landscape"

Excellence Standards

A TNFR expert:

Understands deeply: - Can derive U1-U6 from nodal equation - Explains why phase verification is non-negotiable - Knows the 13 operators and their physics - Comprehends TNFR-Riemann connection: How discrete prime operators relate to mathematical consciousness - Grasps structural coherence: Mathematics as emergent self-organization rather than axiomatic foundation

Implements rigorously: - Every function maps to operators - All changes preserve invariants - Tests cover contracts and invariants

Documents completely: - Physics → Code traceability clear - Examples work across domains - New developers can understand

Thinks structurally: - Reformulates problems in TNFR terms - Proposes resonance-based solutions - Identifies coherence patterns

Maintains integrity: - Rejects changes that weaken TNFR - Prioritizes theoretical consistency - Values reproducibility over speed

Final Principle

If a change "prettifies the code" but weakens TNFR fidelity, it should not be accepted. If a change strengthens structural coherence and paradigm traceability, it should proceed.

Reality consists of resonant patterns rather than discrete objects. Development practices should reflect this understanding.

Version: 0.0.1
Last Updated: 2025-11-29
Status: CANONICAL - Primary reference for TNFR agent guidance
PyPI Release: STABLE - Available via pip install tnfr
Production Ready: Complete Tetrad Fields + Unified Grammar U1-U6 + Simplified SDK

English-Only Policy

Grammar Policy (English Only): All documentation, code comments, commit messages, issues, and pull request descriptions must be written in English. Non-English text is permitted only within verbatim quotations of external sources or raw experimental data. Mixed-language normative content will be rejected. This ensures a single canonical terminology set for TNFR physics and grammar.