Python Engine 0.0.4 — organized mathematical objects, structural operators and reproducible computational research.
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 to investigate which organizations TNFR dynamics admit, what they retain when interacting and which collective properties follow from their structure, without prescribing the outcome.
TNFR's constitutive premise grounds every canonical transformation in the thirteen registered structural operators and their grammar. Continuous equations and collective descriptions need a proved connection to those mechanisms. This is the paradigm's research premise: the engine and auxiliary models do not yet realize it completely, and canonical operator integration is the first development priority.
| Status | Scope |
|---|---|
| Established | Exact identities, conditional theorems and finite computational evidence for declared models: preparation, recovery, interaction, memory and operator actions on organized states |
| Foundations | Four pillars (operator causality, sufficient state versus observation, persistent organizational identity and justified model selection) 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 |
| Open | Autonomous occurrence of operator actions, a uniquely selected fundamental law, empirical validation and any physical identification |
Physical mapping remains blocked until a separate final readiness review binds the four resolutions; the acceptance criteria govern any extension. The long-term matter-emergence hypothesis asks whether persistent organizations under one complete dynamics could account for matter and its observed properties. The shared physical targets include electromagnetic, weak, strong and gravitational phenomena and quantum matter. Electromagnetism is the highlighted route; its assessment records the field, source and observation conditions still to be derived.
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, and equal group averages need not imply equal future responses. The network represents constituent relations and supports execution; graph construction alone does not establish an object's identity.
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 (
phiortheta): 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):
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, and the nodal identity alone does not select these laws. The parameter foundations own their domains, units and unresolved choices.
Requires Python 3.10 or later. Install the published release with:
python -m pip install tnfrThe examples on this page target the current checkout, which can be ahead of
the release. To work on it, create an isolated environment from the repository
root, activate it (.venv\Scripts\Activate.ps1 in PowerShell or
source .venv/bin/activate in a POSIX shell) and install the checkout:
python -m venv .venv
python -m pip install -e .
python -m tnfr --versionNumPy, SciPy and NetworkX are core dependencies. Optional groups in the package metadata add tools and backends:
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 backendRecord the source revision and effective backend for a study; backend availability does not imply acceleration on every execution path. Each GitHub release also ships a lightweight development bundle with onboarding and verified retrieval of omitted evidence.
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, while the full state and law 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 do not bound the intervening numerical path. This example executes a conditional relational law, not structural operators or grammar; formation and the comparison of different laws are separate 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 the capture and memory guide.
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 |
| Acquisition through passive contact | Small preparations without an initial bridge acquire a stable common-form/common-phase organization with a predictive relation value, under postulated auxiliary contact laws rather than operator-driven formation | Passive contact acquisition |
| 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, including Resonance and Contraction maintenance with ordered return, Coupling between organizations, Emission episodes and Mutation and Recursivity participation; occurrence remains supplied | 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.
Current research. The all-thirteen audit confirms executable coverage while leaving filtering, topology, richer-form and scale roles open, and the continuous contact audit finds no established bridge from the postulated contact laws to Coupling (UM), Resonance (RA) or Self-organization (THOL). The current question is collective maintenance with reciprocal participant actions: complete positive domains or obstructions under a fixed composition of existing operators with every member participating. Supplied operator words are interventions; autonomous occurrence remains open.
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 |
A reference_model in a sine assessment does not make step_relational
execute the sine law, and a hypothetical attachment report adds no live edge.
Continuous theorems, numerical steps and validated enclosures provide
different guarantees. The API contracts
define admission, mutation scope, provenance and reporting.
The thirteen registered operators transform NFR state and relations: Emission (AL), Reception (EN), Coherence (IL), Dissonance (OZ), Coupling (UM), Resonance (RA), Silence (SHA), Expansion (VAL), Contraction (NUL), Self-organization (THOL), Mutation (ZHIR), Transition (NAV) and Recursivity (REMESH). Grammar checks composition and execution context, and 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 emissionUse 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.
Structural observations are selected for the question being studied. The structural tetrad is the shared four-channel diagnostic view: it reveals selected features, while 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, and warning thresholds are configured
policies. More output channels need not mean more independent coordinates.
The structural field guide
and the observation requirements
own definitions, sufficiency results, counterexamples and numerical limits.
A spatial profile's observation width is a resolution choice, not a new
fundamental TNFR parameter.
The TNFR research program
keeps the objective, current state and priorities in one small entry document;
its linked chapters keep each model's premises, proofs and evidence in
separate canonical Markdown files. Browse the
compiled research pages
or run python scripts/research_book.py list in a checkout. 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 without making them part of
the same generative model. The repository keeps what serves active research.
Secondary and superseded records are retired with their evidence and remain
recoverable from the tag
pre-retirement-2026-11-06
through the recovery index.
The selected raw evidence
lists the published source archives, reviews and retained outcomes.
User-supplied reference books stay in the local, Git-ignored bibliografia/
directory; they are not needed for installation or the routine checks.
Developing TNFR means testing these constructions, 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 establishes neither that inheritance nor autonomous formation across scales. 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.
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.
| Location | Responsibility |
|---|---|
src/tnfr/ |
Shared dynamics, operators, observations, numerical tools, CLI and SDK; boundaries in Architecture |
theory/ |
The research program with the sole current question, canonical chapters and generated navigation; research_prerequisites.json holds the scoped foundation resolutions 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/ |
Evidence that retained claims consume: protocols, source archives and responses; missing local evidence remains unavailable |
| applications/ | The basic arithmetic utility and the scope of retired applications |
bibliografia/ (local only) |
User-supplied reference books, ignored by Git |
AGENTS.md defines contributor and agent rules; 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, the routine local gate is:
python scripts/check_research_prerequisites.py
python -m pytest
python scripts/check_documentation.py
python scripts/verify_internal_references.py --ciThe default tests cover the routine engine and public interfaces; select a
research owner explicitly when changing its model or claim. The documentation
workflow runs the strict site build (python scripts/prepare_docs.py, then
python -m mkdocs build --strict) on every Markdown change; run it locally
when navigation, catalogs, staging or rendering change. Edit maintained
documents, not generated build/docs-source/ or site/ files.
Local maintenance
uses python scripts/clean_repository.py --report to show what occupies a
checkout and --caches to remove regenerable caches.
The prerequisite check permits only the foundation work admitted by the
program. A physical study additionally requires
--require-physical-mapping to pass; it currently fails, as required, because
the final readiness review is absent. Published archives and consumed
protocols are evidence, not instructions to rerun their producers.
Cite the exact source snapshot used. CITATION.cff owns software citation metadata. The concept DOI 10.5281/zenodo.17602860 resolves to the latest version; each release's notes give its version DOI. MIT licensed; see LICENSE.md.