Skip to main content

TNFR: Resonant Fractal Nature Theory

DOI PyPI version Python 3.10+ License: MIT

Python Engine 0.0.4 — 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.

TNFR's constitutive premise grounds every canonical transformation in structural operators and grammar. Continuous equations and collective descriptions need a proved connection to those mechanisms. This is the paradigm's research premise; the present engine and auxiliary mathematical models are not yet a complete realization of it.

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.

The long-term physical-emergence hypothesis asks whether different persistent organizations under one complete dynamics can account for matter and its observed properties. The shared physical targets include electromagnetic, weak, strong and gravitational phenomena and quantum matter. Electromagnetism is a highlighted route; a possible double-slit comparison has its own measurement requirements. The physical assessment connects existing organization and transport results to the field, source and observation conditions still to be derived. Physical identification remains open.

The four foundational pillars are operator causality, sufficient state versus observation, persistent organizational identity, and justified research/model selection. All four have reviewed resolutions for a prepared native organization: two five-node rings joined by one supplied bridge, with evolving capacity, local recovery and transmitted response under the declared complete law. These resolutions retain that mathematical scope. Physical mapping remains blocked: the separate final readiness review is absent. The acceptance criteria govern any extension; earlier physical studies remain contextual material.

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, create an isolated environment if one is not already available:

python -m venv .venv

Activate it with .venv\Scripts\Activate.ps1 in PowerShell or source .venv/bin/activate in a POSIX shell, then install that checkout:

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 and executes a conditional relational law. It invokes no structural operators or ordered grammar; a canonical operator realization remains to be established. Formation and the comparison of different laws are separate research questions. 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
Native organization with evolving capacity Prepared joined C5 rings retain their identity, recover locally and transmit a perturbation under one complete law Joint foundation account
Acquired native organizations and response Formation/selection evidence and conditional regional response under a two-bridge dynamic-capacity law; quantitative entry of the actual sources into the response domains remains open Acquired native response
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
Controlled EPI simplification Finite error bounds for omitted memory under fixed reversible dynamics; a held-input extension preserves the maintained profile and mean drift Memory omission and profile preservation
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.

The first development priority is canonical implementation and integration of structural operators, as the mechanisms of emergence and self-organization. The current foundation question connects each missing function to sufficient state, actual actions, grammar and continued collective participation. The all-thirteen audit confirms executable coverage and corrects concrete integration defects, while identifying unresolved filtering, topology, richer-form and scale roles. Registered operators are not yet a complete canonical realization. The operator audit finds that the recent continuous contact laws have no established bridge to UM, RA or THOL. Closing this dependency takes priority over extending their results as canonical TNFR dynamics. The existing passive contact completions now have a conditional elementary acquisition theorem: a relatively open family of small preparations with no initial bridge acquires a stable common-form/common-phase organization, retains a predictive relation value and recovers after small supplied probes. The proof controls the complete changing-contact state through zero contact. It establishes neither prior constituent formation nor the older amplitude-one source's destination. The source-to-response result now gives a controlled leading law for retained contact and its tangent recovery scale. The same acquisition proof extends to finite collections of components when appropriately funded contacts connect them. These results broaden retained response geometry; acquisition of nonuniform internal patterns remains a separate question. These are conditional results for postulated auxiliary laws, not proofs of operator-driven formation. Exact detached budget/source readers are not a joint weighted executor or a uniquely selected fundamental law. The bibliographic synthesis connects this priority to stability, viability, symmetry, memory and scaling, including the selected readings and their implementation scope.

The completed two-port selection result proves eventual absence of the original periods (2,1,0) for every member of its original source family, including cut representatives. It leaves the outgoing equilibrium, periods and a common destination unidentified. This scoped exclusion does not rule out collective organization: the same contacts with the shifted-origin preparation have a separate positive capture certificate. The original law, source and frozen responses remain unchanged; completing that particular trajectory is not automatically the next research priority.

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

Structural observations are selected for the question being studied. The structural tetrad remains the shared four-channel diagnostic view. It reveals selected features; reconstructing state or predicting a response requires a sufficient observation under the chosen complete law. The SDK also retains admitted EPI, pressure, phase and capacity, with optional spatial profiles, phase-resultant evidence and explicitly oriented cycle winding.

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-product decay scale Selected fit policy, with a separately 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.

More output channels need not mean more independent structural coordinates. The observation requirements give constructive sufficiency results and counterexamples. A spatial profile can also use an explicitly supplied observation width; that width is a resolution choice, not a new fundamental TNFR parameter.

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
Assess possible physical emergence Hypothesis and scope, electromagnetic prerequisites
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. The selected raw evidence includes source archives, reviews and retained outcomes with an explicit publication manifest. User-supplied reference books remain local. The ignored bibliografia/ directory is not included in GitHub or required for installation and the routine checks. Bibliographic notes identify the consulted sources and reading limits; the published evidence is a selection, not a complete copy of local research records.

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. 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
theory/research_prerequisites.json Scoped foundation resolutions and the separate physical-readiness review; checked by scripts/check_research_prerequisites.py
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
bibliografia/ (local only) User-supplied reference books, ignored by Git and preserved separately from publishable evidence
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 scripts/check_research_prerequisites.py
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.

The ordinary prerequisite check validates the current evidence associations and permits only the foundation work admitted by the program. Before a physical study, the additional --require-physical-mapping check must pass; its failure is currently expected because the final readiness review is absent. Published source archives and consumed protocols remain evidence, not a standing instruction to rerun their producers.

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.

Metadata

Release files for tnfr 0.0.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tnfr 0.0.4
File Size Uploaded Provenance Actions
tnfr-0.0.4.tar.gz 4.0 MB Without provenance Details for tnfr-0.0.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tnfr 0.0.4
File Interpreter ABI Platform Actions
tnfr-0.0.4-py3-none-any.whl Python 3 none any Details for tnfr-0.0.4-py3-none-any.whl

Total release size: 8.7 MB

Release files / tnfr-0.0.4.tar.gz

Download URL tnfr-0.0.4.tar.gz
Size 4.0 MB
Tags Source
SHA-256 checksum
How to use checksums
4159934cf896db16a9e38c0f18cbcbedcae2f4f7636f0437268114895039605f
BLAKE2b-256 checksum
How to use checksums
7d58b6df97950684e3333751c06887ae25d0d7e9c6ca11c01f169ee5d65da6b1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / tnfr-0.0.4-py3-none-any.whl

Download URL tnfr-0.0.4-py3-none-any.whl
Size 4.7 MB
Tags Python 3
SHA-256 checksum
How to use checksums
3a73dd9a1b4a2928befef7c3dbc5deb90fd04cbcb7eed9ddf870d0a5db3f5318
BLAKE2b-256 checksum
How to use checksums
a12b78853c74841ce8241c76e6aa7e8e29a234ce530bbe443a7df5bde4d4f7b8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for tnfr 0.0.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.0.4 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page