You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit c80c99e
Browse filesBrowse the repository at this point in the historyBrowse files
TNFR AI Agent
committed
feat: unify canonical TNFR research and runtime semantics
Centralize nodal contracts, atomic network stages, scalar and phase semantics, and evidence-backed diagnostics across CPU, SDK, GPU, and integration paths.
Integrate the research programme with executable certificates, tests, examples, and canonical documentation while removing simulated performance claims and redundant implementations.
Copy file name to clipboardExpand all lines: README.md
+118Lines changed: 118 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,6 +19,12 @@ those primitives. [AGENTS.md](AGENTS.md) is the canonical synthesized reference.
19
19
Mathematical scope and counterexamples are stated explicitly in the linked
20
20
theory documents.
21
21
22
+
The graph engine's scalar EPI chart accepts a raw real value or the equivalent
23
+
uniform-real `BEPIElement` representation. Its scalar projection retains the
24
+
sign; `abs(EPI)` remains the nonnegative Banach-envelope magnitude. Genuinely
25
+
nonuniform or complex BEPI payloads keep that magnitude projection for generic
26
+
read-outs and are rejected by certificates that require one real EPI coordinate.
27
+
22
28
```bash
23
29
pip install tnfr
24
30
```
@@ -71,6 +77,11 @@ The public structural-field tetrad is `(Phi_s, |grad phi|, K_phi, xi_C)`.
71
77
|`K_phi`| Local wrapped phase curvature | Exact wrapped magnitude bound `pi`; `0.9*pi` is a warning margin |
72
78
|`xi_C`| Non-local correlation range | Spectral estimate scales as `1/sqrt(lambda_2)` under its documented hypotheses |
73
79
80
+
`Phi_s` uses explicit edge `length` for path geometry when available; otherwise
81
+
it retains `weight` as a compatibility fallback. EPI diffusion always reads
82
+
`weight` as conductance, so models with distinct geometry and transport should
83
+
declare both attributes.
84
+
74
85
For small phase spread on a consistent branch and matching weight conventions,
75
86
`K_phi` agrees with the random-walk Laplacian applied to phase. The EPI channel
76
87
of `Delta NFR` is exact graph diffusion. These statements do not make every
@@ -93,6 +104,60 @@ classifications are derived in
93
104
[`grammar_canon.py`](src/tnfr/operators/grammar_canon.py), and exposed through
94
105
[`grammar.py`](src/tnfr/operators/grammar.py).
95
106
107
+
The operator registry is the canonical semantic interface for named
108
+
transformations. Declared numerical solvers may advance EPI only through the
109
+
shared nodal-equation integrator from explicit `nu_f` and `DeltaNFR`, with
110
+
provenance or a residual; ad hoc state assignment is outside the engine
111
+
contract.
112
+
113
+
SDK words preserve operator order. Each SDK Reception or Resonance stage
114
+
reads one immutable all-target snapshot and commits its validated proposals
115
+
atomically; the GPU Resonance strategy reuses that same stage. These positions
116
+
have two-phase Jacobi semantics. Other operator stages retain operator-major
117
+
Gauss-Seidel semantics, so the guarantee does not make an entire mixed word
118
+
simultaneous. No GPU Reception strategy is currently registered.
119
+
120
+
THOL's `subepi_amplitude_alignment` is a variance-based EPI-amplitude
121
+
diagnostic, not canonical `C(t)` and not U5. A concrete U5 target is evaluated
122
+
by `assess_u5_parent_child_coherence(..., alpha=...)`; the hierarchy and
123
+
nonnegative `alpha` must be supplied explicitly.
124
+
125
+
### Mutation temporal evidence
126
+
127
+
Mutation keeps three related quantities separate:
128
+
129
+
| Read-out | Definition | Scope |
130
+
| --- | --- | --- |
131
+
|`predicted_depi_dt`| instantaneous `nu_f * DeltaNFR`| Nodal-equation prediction; its crossing is exposed by the legacy SDK alias `near_bifurcation`|
132
+
|`observed_depi_dt`| signed two-sample EPI secant | Evidence used by the strict, non-disableable ZHIR threshold gate |
133
+
|`d2epi_dt2`| three-sample change between adjacent secant rates | Structural-acceleration diagnostic; timestamped or legacy unit-step, and not the ZHIR gate |
134
+
135
+
Physical evidence uses timestamped `(time, EPI)` records with finite increasing
136
+
time and a fresh final EPI endpoint. If supplied, it is authoritative and does
137
+
not fall back when invalid or stale. Legacy `epi_history` and `_epi_history`
138
+
instead retain a unit-operator-step interpretation and are explicitly not
139
+
resolved in physical time. Direct Mutation requires a valid observed rate
140
+
strictly above `ZHIR_THRESHOLD_XI`, together with active capacity and any
141
+
configured minimum capacity.
142
+
143
+
When dynamic selection cannot support a proposed ZHIR from that evidence, it
144
+
substitutes Coherence (IL) before ordinary grammar enforcement and records the
145
+
requested and applied glyphs with the reason. The SDK whole-word runner
146
+
checks all target nodes before executing a word that contains Mutation and
147
+
rejects timestamped evidence that an earlier EPI-channel operator in the word
148
+
would make stale. `ZHIR_BIFURCATION_VF_THRESHOLD = 0.5` only controls branch
149
+
proposal; it is not the Mutation gate. `MutationTriggerCertificate` is an
150
+
immutable diagnostic, and `nodal_state()` reads the same evidence without
151
+
modifying the graph. Neither evaluates the prior-IL and recent-destabilizer
152
+
context required by U4b, and neither certifies execution readiness.
153
+
`TNFRNetwork.apply_evidence_gated_mutation()` is the high-level experiment
154
+
policy: it runs the requested ZHIR word only after the same preflight;
155
+
otherwise it executes a declared Mutation-free exploration word and records
156
+
the decision in `NetworkResults.mutation_workflows`. It never synthesizes EPI
157
+
history, and malformed evidence remains an error. Direct `apply_sequence()`
0 commit comments