TNFR: Resonant Fractal Nature Theory

Python Engine 0.0.3.9 — organized mathematical objects, nodal dynamics and reproducible computational research.

Summary

How can interacting parts form a recognizable pattern, keep its identity while changing, and influence other patterns? TNFR studies this question through organized mathematical objects: nodal patterns with a specified identity, retained internal state and a declared evolution law. The repository provides constructions, conditional proofs, a Python engine and numerical instruments for working with these objects. Its purpose is to investigate the scope of TNFR: which organizations its dynamics admit, what they retain when interacting, and which collective properties follow from their structure.

The network represents constituent relations and supports execution. Object studies test whether a state description retains the information needed for response, which consequences follow from a law, and which operator actions are defined on the organized target.

From nodal state to an organized object

An NFR, or fractal-resonant node, is a modeled unit at a chosen scale. A collective NFR retains the constituent and boundary information needed for its declared dynamics. Its constituents can remain distinct and internally active; equal group averages need not imply equal future responses.

The scalar engine represents the underlying nodal state through:

• Form (EPI): a signed real structural coordinate.
• Capacity (nu_f): a nonnegative factor scaling the form response.
• Phase (phi or theta): a circular coordinate.
• Support and consumed history: the connections, constituent relationships and temporal evidence required by the selected model.

The unforced nodal equation relates form to independently specified structural pressure (DeltaNFR):

$$ \frac{\partial \mathrm{EPI}}{\partial t}=\nu_f,\Delta\mathrm{NFR}. $$

Zero capacity freezes this form row, not necessarily the whole state. A complete model also declares pressure, phase, capacity, support, clock, inputs and event laws; holding a quantity fixed is a premise. The nodal identity alone does not select these laws. Parameter foundations owns their domains, units and unresolved choices.

Installation

Requires Python 3.10 or later. The examples on this page target the current checkout. From its repository root, install that source:

python -m pip install -e .
python -m tnfr --version

NumPy, SciPy and NetworkX are core dependencies. Optional tools are grouped in package metadata:

python -m pip install -e ".[test,docs]"     # tests and documentation
python -m pip install -e ".[compute-jax]"   # optional JAX backend
python -m pip install -e ".[compute-torch]" # optional Torch numerical backend

python -m pip install tnfr installs the published release, whose API can precede these checkout examples. Record the source revision and effective backend for a study. Backend availability does not imply acceleration on every execution path.

Quick start

Start with a small organized object: five nodes whose phases make one complete turn around a ring, with a small signed form contrast. Specify the native relational law, assess recovery, advance form and phase, then assess the new state.

from fractions import Fraction as Q

import networkx as nx

from tnfr.sdk import Network, RelationalExchangeModel

graph = nx.cycle_graph(5)
cycle = tuple(range(5))
for node, contrast in enumerate((1, -1, 0, 0, 0)):
    graph.nodes[node].update(EPI=Q(contrast, 1024), theta=Q(5 * node, 4), nu_f=1)
nx.set_edge_attributes(graph, 1, "weight")
graph.graph["GAMMA"] = {"type": "none"}
network = Network(graph)
model = RelationalExchangeModel(
    storage_scale=1, epi_weight=0.5, phase_weight=0.5, phase_domain="acute"
)

before = network.relational_cycle_capture(model, cycle=cycle)
step = network.step_relational(model, dt=Q(1, 1024), t=0)
after = network.relational_cycle_capture(model, cycle=cycle)
print(f"Winding: {before.cycle_winding} -> {after.cycle_winding}")
print(f"Recovery: {before.status} -> {after.status}")
print(f"Form changed: {step.before.epi != step.after.epi}")
print(f"Phase changed: {step.before.phase != step.after.phase}")
print(f"Euler storage-balance defect: {float(step.energy_step_defect):.6g}")

Output in the checked environment:

Winding: 1 -> 1
Recovery: admitted -> admitted
Form changed: True
Phase changed: True
Euler storage-balance defect: 3.18216e-11

Winding counts the net phase turns around the ordered cycle. Here it labels the object's recovery class; the full state and law remain necessary to describe its identity and evolution. Each certificate admits recovery under ideal continuous evolution from its own snapshot, with held support, positive held capacities and no forcing. The finite Euler step reports its storage-balance defect separately; two admitted endpoints are not an error bound for the intervening numerical path.

This example prepares the object. Its formation is a separate research question, as are operator events and the comparison of different laws. Time is structural time, not laboratory seconds or an operator count. The complete hello world retains the network and all reports. Continue with the example learning route and capture and memory guide.

Mathematical objects and their status

The available constructions address distinct aspects of organization. An initialized pattern, a recovered pattern and an acquired identity establish different claims:

Capability	Established scope	Mathematical owner
Native winding-pattern recovery	A prepared five-node unit ring (C5) and its ideal continuation under admitted capacity, phase and storage premises	Native recovery
Formation, retention and recovery	Prepared families under specified laws, with source, stability and uncertainty conditions	Pattern dynamics
Collective state, interaction and memory	Exact reductions or bounded descriptions that retain required constituent and boundary information	Emergent ontology
Localized motion	Finite transport of a prepared full-state identity on supplied support	Identity transport
Operator actions on organized states	Admitted actions and conditional compositions, with explicit event work, capacity and live grammar requirements	Structural operators

Combine results only when their state, law, support, capacity, clock and preparation agree. Proofs establish consequences of premises, tests check implementation, and numerical experiments describe their cases and error controls. Empirical validation requires independent measurements; mathematical storage is not identified with measured energy by its name.

Choose an execution path

Choose the interface for the intended model and action:

Task	Interface or owner	Contract
Evolve native relational form and phase	RelationalExchangeModel, Network.step_relational	Resultant-direction pressure and a joint phase law; supplied support, held capacity and admitted phase domain
Assess the normalized-sine model	Shared assessment owners and usage guide	A distinct form/phase law using neighboring sine differences; scoped observations, certificates and continuous enclosures
Run operator words	TNFR, StudySpec, run_study, tnfr network	Registered transformations, grammar, live preconditions and declared hybrid events
Read stored network state	diagnose_network	Detached diagnostics with explicit availability; stored pressure is not refreshed
Study regions, contacts and retained responses	Regional workflows	Declared regions, hypothetical support changes, preparation-specific bounds and evidence

Supplying a reference_model to a sine assessment does not make step_relational execute the sine law. A hypothetical attachment report does not add a live edge. Continuous theorems, numerical steps and validated enclosures provide different guarantees. The API contracts define admission, mutation scope, provenance and reporting.

Operators, grammar and evolution

The 13 registered operators specify transformations of NFR state and relations: Emission (AL), Reception (EN), Coherence (IL) and Silence (SHA), for example. English names lead explanations; codes abbreviate words and formulas. Grammar checks composition and execution context, while every action must satisfy its target's live preconditions. Admitting a requested action does not derive its occurrence. The collective readiness criterion states what an organization must retain to support collective actions.

For requested words, the CLI and SDK share the operator-study runner:

tnfr network --nodes 6 --topology ring --seed 42 --steps 1 --export-spec study.json --output report.json
python -m tnfr network --spec study.json --output replay-report.json
tnfr sequences basic_activation
tnfr operators emission

Use StudySpec, run_study and diagnose_network from tnfr.sdk for the Python workflow. Cycles count complete words, not seconds. The runner sets topology and execution seeds; TNFR.create(..., seed=...) sets only the topology seed. Recipes and reports are not complete checkpoints. The CLI/SDK guide owns usage and directs collective studies to their scoped instruments.

Observe state and response

The structural tetrad is a shared set of diagnostics. Like a dashboard, it reveals selected features without describing the complete internal state or predicting its future by itself. Use it alongside the object's identity criterion and response records; a diagnostic score cannot replace either.

Tetrad field	What it measures	Interpretation
Phi_s	Nonlocal aggregation of structural pressure	Pressure contributions weighted by inverse squared path distance
abs(grad phi)	Local phase separation	Mean absolute wrapped difference from neighboring phases; bounded by pi
K_phi	Circular phase curvature	Displacement relative to a neighbor phase resultant; bounded by pi where defined
xi_C	Static coherence correlation range	Coherence-product fit, with an explicitly identified spectral fallback

Field path geometry reads edge length, falling back to weight; diffusion uses weight as conductance. Undefined curvature, absent temporal evidence and unavailable estimates remain explicit. Warning thresholds are configured policies. The structural field guide owns definitions, interpretation and numerical limits.

Read the research

The TNFR research program keeps the objective, current state and priorities in a small entry document. Its linked chapters preserve each model's premises, proofs and evidence in separate canonical Markdown files. Open and preview one chapter at a time. Use the compiled research pages for chapter navigation, or python scripts/research_book.py list in a checkout. The conceptual core is the starting point for the foundations and their dependencies. The chapter workflow explains focused extraction and editing.

Need	Maintained owner
Start with the foundations	Conceptual core, dependencies and worked examples
Find a definition, proof or model	Research reading route and chapter index
Locate its implementation and tests	Theory-to-execution map
Distinguish premises, results, diagnostics and hypotheses	Glossary
Understand priorities and select a question	Selection criteria
Resume the active task	Current task and documentation prerequisites

Auxiliary Hamiltonian, graph-wave, geometric and arithmetic studies keep their own premises. The catalog identifies their scope; their presence does not make them part of the same generative model. Evaluated evidence, negative results and retirement provenance remain in the research archive.

Research scope

Developing TNFR means testing the constructions above, their limits and the additional premises needed for more complex organization. Fractality asks what a larger node must retain to inherit its constituents' dynamics and admissible actions. Grouping nodes alone does not establish that inheritance or autonomous formation across scales.

The research program owns the sole task queue. The old execution plan, strategy and portfolio are retired compatibility routes. Comparisons with independent observations require preparation, measurement, clock and uncertainty models, separate calibration and reserved evaluation, and suitable alternatives. EPI need not equal a sensor reading. The conditional results do not select a unique fundamental law.

What resonance means here

Resonance is an input/output response property of a declared model. Internal pulses, recurrence and the registered Resonance operator have separate contracts; a response peak alone proves none of them. The resonance foundation and scale connection map explain when internal motion, memory and collective response can be combined.

Repository map

Location	Responsibility
src/tnfr/	Shared dynamics, operators, observations, numerical tools, CLI and SDK; boundaries in Architecture
theory/RESEARCH_PROGRAM.md	Research objective, sole current question and technical chapters; the theory index is generated navigation
docs/	Usage and execution contracts, organized by the documentation map
tests/	Contract checks and explicitly selected research tests; selection in Testing
examples/, benchmarks/	Runnable illustrations and scoped instruments
docs/assets/, artifacts/	Published evidence and local protocols, source archives and responses; missing local evidence remains unavailable
applications/	Basic arithmetic utility and retired application scope

Contribute and verify

AGENTS.md defines contributor and agent responsibilities. Contributing and Testing own the development workflow, dependencies and test selection. Preserve unrelated changes, reuse shared implementations, and update a changed claim with its responsible contract and checks.

With the test and documentation extras installed:

python -m pytest
python scripts/check_documentation.py
python scripts/verify_internal_references.py --ci
python scripts/prepare_docs.py
python -m mkdocs build --strict

The default tests cover the routine engine and public interfaces. Select a research owner explicitly when changing its model or claim; the routine gate does not replay every retained campaign. Edit maintained documents, not generated build/docs-source/ or site/ files. Documentation catalogs supply the checked menus of the published site.

Citation and license

Cite the exact source snapshot used. CITATION.cff owns software citation metadata; the project DOI is 10.5281/zenodo.17602860. MIT licensed; see LICENSE.md.