Status: Active normative view Version source: package metadata
This hub owns shared API admission and execution boundaries and the generated operator-contract view. The operator registry owns operator metadata; the linked engine, observation and validation modules own their respective execution paths. A registry change alone does not revise an integrator, diagnostic or certificate contract.
| Responsibility | Contract owner | Implementation boundary |
|---|---|---|
| Common admission, solvers and named operator contracts | This document | Shared scalar/clock owners, nodal integrators and operator registry |
| Conditional relational dynamics and observations | Relational dynamics | Selected joint law, snapshot/step reports and capture/transit admission |
| Hybrid events and finite execution evidence | Operator events | Declared schedules, transactions, runtime provenance and REMESH certificate APIs |
For executable calls and examples, use the CLI and SDK guide. Mathematical definitions, hypotheses and proofs remain with the linked theory owners. A serialized declaration or diagnostic report does not bypass live preconditions or certify future stability. For calculations that consume conditional sine reports, the chained-report contract owns primitive re-admission, derived-field rebuilding and source-association limits. Public adapters delegate to those shared consumers. The relational contract index distinguishes complete-state observations, exact collective families, finite maintenance bounds and observations of saved forecasts. Sharing a storage identity or export format does not make their support, law or evidence interchangeable.
Word admission rejects unregistered operator identifiers before role checks;
operator instances retain their metadata, including Recursivity depth. Grammar
context flags use the shared Boolean parser: "false" does not grant initialized
form or diagnostic permission, and unknown Boolean strings reject. Context is
copied, leaving the caller's mapping unchanged. See the
grammar contract.
validate_sequence, parse_sequence and ValidatedSequence default to
the shared core word contracts. String validation delegates to the same
GrammarValidator checks used by typed execution, including causal debt and
prior Coherence; a different input representation cannot bypass these checks.
String words carry default operator metadata only. Use actual operator
instances when, for example, Recursivity depth matters.
The explicit context {"compatibility_profile": "legacy"} adds the historical
adjacency and THOL-terminal preferences. validate_sequence and
parse_sequence also accept that keyword directly, taking precedence over the
context value. Both profiles retain the shared core checks; neither establishes
live admission, trajectory stability or every manuscript sentence prescription.
Callers requiring those additional preferences must select legacy explicitly.
Both profiles reject violations of the shared causal checks. parse_sequence
raises on rejection; validate_sequence returns its structured outcome.
TNFR.explain_sequence(operators, context=...) reports this same word policy,
ordered English display names in operators, its selected compatibility_profile
and compact glyph notation, such as AL → IL → SHA. Lead reader-facing
explanations with the English names. It accepts registered names or simple
glyph codes, not arrow
expressions, apostrophe spellings or bracket syntax as individual tokens.
Invalid context yields valid=False with no selected profile; unknown operator
identifiers raise. The report explicitly leaves manuscript syntax, live state
and trajectory checks unassessed. Context is a declaration, not observed
initialization or trigger evidence.
GrammarValidator.validate and collect_grammar_errors consume the same
immutable outcomes from GrammarValidator.validate_checks; diagnostic text
does not decide whether a check passed. Strings use shared identifier normalization; supplied
operator objects retain their metadata, so unknown identifiers report SYNTAX
and Recursivity depth remains subject to U5. run_structural_validation uses
these errors for its word status. Omitting the sequence skips word validation;
live U3 admission and temporal U6 evidence remain separate obligations.
structural.run_sequence observes the target's actual admitted signed form
when determining initialization context; a caller flag cannot promote zero
or invalid form into permission. It records the last completed operator only
after that invocation succeeds.
Persistent grammar state. Shared require_grammar_state admits stored
glyph_history as an ordered list, tuple or deque of registered identifiers.
Strings, mappings, sets, unknown tokens and explicitly stored None reject;
one-shot iterators reject without consumption. Omit an absent history key,
or materialize a valid owned sequence before execution. Present U2 debt must
be a nonnegative integer excluding Booleans, and prior-Coherence state must
be Boolean. Invalid present state cannot fall back to a shorter trace.
The stored operator-step index likewise requires a nonnegative non-Boolean
integer; only a missing index falls back to the retained trace length.
Only absent bookkeeping is reconstructed from retained history; this cannot
recover evicted facts. Deliberate full-trace replacement uses the shared reset
helper; restoring a snapshot preserves its valid persistent context.
on_applied_glyph delegates to the shared occurrence recorder: it normalizes
glyph codes and updates the index, debt and prior IL while preserving deque
bounds or unbounded list retention. Tuple traces become unbounded lists.
This helper records a caller-supplied occurrence; it neither executes nor
authenticates an operator. Do not record an already runtime-recorded action twice.
read_grammar_state builds a fresh immutable view of canonical history codes,
debt, prior Coherence and operator index. Recording admits each retained
identifier once; it does not cache permission across mutations. History readers,
repetition scores, hysteresis and direct Mutation/Dissonance context readers
use shared admission, so equivalent supported names and codes give the same
decisions. Malformed authoritative history cannot be hidden by a diagnostic
shortcut. Graph validation retains its TNFRValueError error envelope.
Native batches pre-admit consumed grammar context and lag counters before
incrementing counters. Lag limits/counts reject Boolean, fractional or invalid
values, and the hysteresis window uses shared integer admission. Grammar's
enabled uses shared Boolean parsing. Lag resets follow the glyph actually
applied, including grammar substitution; a blocked AL proposal replaced by IL
does not reset since_AL. _choose_glyph applies the same grammar to forced
candidates but neither increments counters nor executes them. Native batches
remain sequential: a later operator failure can retain earlier completed
operations and policy bookkeeping; this is not the atomic-stage contract.
Mutation proposal screening and execution share raw authoritative-alias and
signed-form certificate admission. Explicit invalid EPI cannot be replaced by
a secondary alias or turned into missing temporal evidence. Recorded abstention
clocks must be valid represented real values.
Mutation admits raw authoritative phase and active proposal scalars before
conversion. Boolean/nonreal values, nonfinite values and nonzero values lost
to zero reject; direct graph rejection precedes adapter caching. The shared
proposal preserves the consumed pressure's signed zero after admission.
An explicit fixed shift still leaves dynamic proposal arguments unconsumed;
the independent temporal/capacity gate remains required. Valid phase wrapping
and public/direct/staged execution boundaries are unchanged.
Native batch proposals resolve supported English names, tokens and glyph codes
through the shared identifier owner before Mutation screening and lag accounting.
Emission/Reception counters and Mutation abstention records therefore agree
across those spellings, including with canonical grammar disabled. Unknown
proposals retain the selected grammar rejection/substitution policy; this is
not whole-batch prevalidation or rollback of an earlier executed prefix.
With glyph execution enabled, runtime.step runs the same batch preflight
before creating history, reserving an invocation ordinal or invoking callbacks.
It re-admits at consumption after callbacks and pressure refresh. Disabled
glyph execution does not consume lag limits or grammar policy. This covers
the supplied batch configuration/context, not arbitrary callbacks or a full-step
transaction. A late failure can retain observations and its invocation ordinal.
Soft repetition thresholds GRAMMAR.force_dnfr and force_accel and consumed
normalized scores admit original represented-real values in [0,1]; Boolean,
text, nonfinite or lost nonzero values reject. Explicit malformed fallback
operators reject. Context parameters must be mappings: optional constructor
None remains absent, whereas explicitly malformed graph-owned configurations
reject before defaults. Empty graph mappings retain the documented default
overlay. These checks preserve the supplied normalization/selection policies;
they do not infer global maxima from local input or derive a controller.
Repeat checking and its error context reuse one fresh admitted history view,
without a second permissive interpretation of the retained identifiers.
Selector pressure/acceleration ratios use shared checked division on scalar, vector and worker paths. Nonfinite quotients and nonzero quotients rounded to zero reject before threshold comparisons. Valid represented ratios remain unclipped; a zero supplied normalization maximum retains its unit-divisor convention. This rejects unrepresentable observations rather than selecting an operator from an invented zero.
The native selector runs at an outer call's left boundary. Lag counts measure
decision batches, internal integration substeps add none, and dt=0 still
allows operator events. The clock comparison
shows that additional outer decisions can change the physical endpoint at
the same final time. Numerical comparisons must retain their declared event
schedule and other per-call policies; apply_glyphs=False skips only the glyph
batch, not phase/capacity policies or all runtime bookkeeping.
Native execution consumes complete associated state: form, phase, capacity, stored and refreshed pressure, grammar and lag records, adaptation counters, prior rates, temporal observations and target-associated random-stream state. Default selection additionally uses graph-wide capacity and absolute-pressure maxima through Si and normalized pressure. Matching a component's local state or selected operator labels therefore does not establish a closed component law. Reception consumes live neighboring form; Resonance consumes the live U3-compatible subset and its associated form/phase data. Earlier target events can change a later target's branch. Integration consumes event capacities and held prepared pressure; later policies have their own observation boundaries.
The native dynamics owner derives the scoped selector, ordered-event and complete-call reductions and counterexamples. The collective calculus owns sufficient retained state, correlated enclosures and their composition requirements. The aggregate operator owner states when an actual registered operator descends to a coarse representation and when it does not. These conditional results neither create a public collective executor nor let a summary report replace the source required by a later call.
A collective prediction must retain the actual request origin, target order, live branches, state associations and relevant memory. Marginal bounds or matching means do not establish their joint realizability. A retained prefix is not a completed call; refreshed diagnostics, lag increments and invocation ordinals may survive a later failure on the sequential native path. Distinguish native rejection, observer interruption, unavailable temporal evidence and atomic-stage rollback. Ideal reductions and asymptotic theorems also retain their own arithmetic premises; they are not bitwise runtime guarantees.
The following names are not supported GRAMMAR_CANON controls or
--grammar.* CLI options: zhir_requires_oz_window,
zhir_dnfr_min, thol_min_len, thol_max_len, thol_close_dnfr, and si_high.
Remove these options from CLI invocations; arbitrary mapping extensions retain
no admission meaning. The shared U4 context and measured Mutation gate own
their actual requirements. Words supply their closure explicitly; no sense-index
threshold chooses a THOL closure. There is no one-to-one threshold replacement.
Coupling's four UM_* branch flags and OZ_NOISE_MODE use the same Boolean
parser before active-factor resolution and proposals. Transition's NAV_STRICT
and NAV_RANDOM retain their stricter Boolean-only domain across public classes,
direct glyphs and stages; strings are rejected. Disabling a branch removes only
that branch's factor requirements. It does not waive live U3 or other operator
preconditions. The operator maps and
event contracts specify the execution effects.
The existing typed tokens,
parser/compiler and
program executor own the THOL, WAIT and TARGET
program syntax used by the specialized CLI sequence route. This is separate
from complete-word validation and the atomic operator-stage route. Compilation
does not admit a child NFR, choose a branch or install a continuous law. The
source comparison
retains the wider hierarchical and prosodic proposals with their open premises.
parse_program_tokens returns owned typed bodies for explicit THOL blocks;
plain iterable grouping remains sequential. compile_sequence returns ordered
(OpTag, payload) operations. BLOCK_ENTER and BLOCK_EXIT carry immutable
BlockBoundary(path, iteration, repeat) metadata identifying nested occurrences
and zero-based body repetitions. These markers neither execute a structural
operator nor advance time. Consumers of compiled streams must retain them;
filtering only glyphs loses program scope. THOLEvaluator retains its iterator
interface as an unscoped token view, not the execution representation.
The THOL opening executes once per block invocation. Each body repetition
inherits the enclosing targets; TARGET changes are local to that repetition
and are restored at its exit. There is no automatic child-target selection.
Before any explicit TARGET, the target is the current graph population at each
glyph; TARGET(None) instead captures the population when that token executes.
Ordered explicit target collections preserve their supplied order.
Program construction follows these explicit contracts:
| Input | Contract |
|---|---|
| Omitted THOL closure | force_close=None, or block(..., close=None), adds no glyph. Supply Glyph.NUL explicitly when that action is intended. |
| Explicit closure glyph | Every supplied registered glyph is emitted after each repetition and remains subject to live admission. Its position does not make it a valid grammatical closure. |
| Nested TARGET assignment | Targets restore at each repetition exit. Put a TARGET after the block when subsequent operations require that selection. |
| WAIT/repeat count | Counts must implement the integer-index protocol, be positive and be non-Boolean. Floats, fractions and strings reject, including integer-valued ones. |
| Nested or reused group | Cyclic ancestry rejects; repeated occurrences of an ordered group remain present. Unordered sets, unknown token fields and malformed glyphs reject. |
max_materialize is a nonnegative integer or None; the default is 1000.
The finite bound covers parsed input and expanded operations, including scope
markers. play completes syntax admission and compilation before changing graph
history. Live targets, grammar and preconditions are still checked during
execution; earlier accepted operations and callback effects are not rolled back
if a later operation fails.
Requested program glyphs use the native direct-glyph path and reject blocked
requests without substitution, even when the graph's ordinary rejection policy
is fallback. That original policy is restored before the step function runs.
No future-handler context is invented across changing targets or scopes.
The supplied step_fn, or the existing native runtime by default, runs after
each actual glyph, including THOL and an explicit final glyph. WAIT requests
additional step-function calls. The default step can select more operators and
update phase/capacity: WAIT is not an event-free interval, and its count is
neither seconds nor a newly derived clock.
The bounded history["program_trace"] distinguishes supplied program requests
from subsequent step-function execution. A glyph/THOL row is appended after
successful glyph dispatch and before stepping, with selection_origin set to
supplied_program, ordered pre-dispatch targets, event_time, and
event_boundary="after_requested_glyph". A later-created node cannot become a
recorded target of that earlier dispatch. TARGET rows retain ordered node IDs;
WAIT rows describe requested step calls and make no glyph-event claim.
Rows begin with step_status="pending" and record_boundary="before_step".
They become completed/after_step on success, preserving the existing t
field as the post-step clock. Failures retain a failed/step_failed row and
the original exception; there is no rollback. Requested, started and normally
returned call counts are step_calls_requested, step_calls_started and
step_calls_completed. A returned call can still fail clock admission.
step_origin distinguishes native_runtime from supplied_step_function;
neither value enumerates operators selected internally by that function.
The initial clock and each recorded clock sample use shared finite represented
real admission. Missing _t uses the explicit zero convention. Boolean,
nonfinite or nonzero unrepresentable clocks reject. If a callback leaves an
invalid clock, its effects remain, the row retains its last admitted t, and
clock_sample_available=False marks the unavailable current sample. A rejected
glyph dispatch creates no completed-glyph row; earlier target effects can still
exist on this non-atomic route. Trace truncation and callback effects prevent
using missing rows as proof of no event or as a complete execution checkpoint.
The canonical_example program preset requests Emission → Coherence → Silence
(AL → IL → SHA). It is distinct from the SDK's registered basic_activation
word. Presets retain their declared actions and contextual admission needs;
contained_mutation and coupling_exploration request Contraction (NUL)
explicitly. Controls:
program admission and execution.
The following interfaces are not part of the current API. Use the declared replacement where one exists; no compatibility alias substitutes a different mathematical model. Source recovery belongs to the recovery index.
| Unsupported interface | Current replacement or scope boundary |
|---|---|
validate_grammar(..., collect_unified_telemetry=...) |
Remove the argument; word validation has no observed graph. Use diagnose_network(actual_graph) or physics.fields.compute_unified_telemetry(actual_graph) with explicit state. The removed option reported fields of a fixed demonstration graph, not the validated word or its execution. |
tnfr.operators.algebra.validate_identity_property, validate_idempotence, validate_commutativity_nul |
Use the actual operator event contracts and compare the same admitted transformations. The retired routines compared different words or unsupported words; they did not prove the advertised algebra. Silence attenuates capacity and is not generally idempotent. |
tnfr.dynamics.DynamicLimits, DynamicLimitsConfig, compute_dynamic_limits and tnfr.dynamics.dynamic_limits |
No replacement emergent-limit law. The unused score-based proposal mixed configured coefficients and a fabricated missing-Si baseline. Declare application bounds explicitly through the model's existing configuration and admission. |
tnfr.compat and tnfr._compat |
Import dataclass from dataclasses and TypeAlias from typing on supported Python versions. NumPy is required; optional dependencies use their actual libraries and the engine's existing dependency admission. Unused fake-library stubs are removed. |
tnfr.secure_config |
Import the same implementations from tnfr.config.security. |
evaluate_bifurcation_risk from tnfr, tnfr.math, tnfr.mathematics and tnfr.math.symbolic |
No bifurcation detector replaces it. A threshold on supplied acceleration neither proves stability nor justifies automatic operator selection. compute_second_derivative_symbolic() retains the product-rule identity; actual event admission belongs to the operator contracts. |
tnfr.operators.discover_operators, tnfr.operators.registry.discover_operators and structural_operator |
Remove the no-op discovery calls and decorator. get_operator_class() retains lazy class lookup and explicit subclass registration; TNFR.operators() owns the canonical contract inventory. Registering a class does not create a canonical operator contract. |
tnfr.operators.registry.invalidate_operator_cache and get_operator_cache_stats |
Removed unused telemetry; the invalidation function did not clear a cache. Operator class lookup and actual graph/state cache invalidation keep their separate owners. |
tnfr.math.grammar_validators, tnfr.math.optimizer and their facade exports |
Use tnfr.operators.grammar for word admission. Removed duplicate role scores and a greedy score-based word extension; neither certified dynamical stability nor an optimum. Application objectives remain supplied policies. |
tnfr.math.fields_symbolic and its facade exports |
Use tnfr.physics.fields for the implemented graph diagnostics. The removed continuum expressions were a different model, not symbolic versions of those fields. Nodal calculus in tnfr.math.symbolic remains available. |
tnfr.riemann.operator_catalog_discipline_signature and its facade exports |
Use TNFR.operators() and operator_contracts.verify_contract_consistency() for canonical inventory checks. Those checks do not prove ontological completeness; compatibility class registration remains separate. |
tnfr.operators.grammar.validate_sequence_cached, clear_validation_cache, get_validation_cache_stats and get_grammar_cache_stats |
Use validate_grammar() for operator objects, validate_sequence()/parse_sequence() for canonical names, and GrammarValidator for detailed configured checks. The retired cache wrapper did not validate live graph context; node/edge counts cannot replace live preconditions. |
Private duplicate start/end/U2 checks in grammar_patterns |
Use the shared public word validators. Their core checks delegate to GrammarValidator; explicit legacy retains only additional compatibility preferences. Private helper names are not independent admission contracts. |
tnfr.utils.clear_orjson_param_warnings (also in tnfr.utils.io) and tnfr.config.presets.legacy_preset_guidance |
Remove these no-op calls. Shared JSON admission/encoding and get_preset() retain their existing behavior; unknown presets still raise KeyError. |
Global tnfr.validation.config.ValidationConfig fields epi_range, vf_range, phase_coupling_threshold, cache_validation_results, max_validation_time_ms |
Removed unconsumed settings. Scalar domains, live U3 admission and the separate cached-validator configuration retain their own owners. Construction rejects the removed keywords; configure_validation() rejects them without committing other supplied settings. |
The basic primality utility retains
static arithmetic descriptors and a numerical predicate. Its CLI and
python -m tnfr_primality use the same basic implementation; advanced
adapters, advanced/legacy console names and the full extra are retired.
Core arithmetic pressure and residue-graph theorems retain their own premises
and implementations.
tnfr.factorization, TNFR.factorize and Network.factorize are deprecated
compatibility bridges for a separately supplied legacy tnfr_factorization
package. They do not discover or activate the
archived lab.
An absent or archived implementation raises retirement guidance; an admitted
external package emits DeprecationWarning. Historical factor-candidate,
acceptance and completeness labels are not independent arithmetic certificates.
The SDK self-optimization helpers keep generic manifest orchestration in the engine. They require the checkout scripts and an explicit graph payload; modulus-only lab reconstruction is no longer supported. Wheel-only calls without those drivers fail explicitly. These helpers propose and assess a dry run, do not dispatch operators, and return no promotable recommendations. The default operation-to-regression mapping is empty: unmapped operations remain pending, rather than inheriting an unrelated arithmetic suite's result. The runner contract owns serialization and observations.
tnfr.math.symbolic.solve_nodal_equation_constant_params constructs
EPI_0 + nu_f_val * delta_nfr_val * (t - t0) for supplied scalar expressions
held independent of its clock t. Each argument enters SymPy before
arithmetic; supplied symbols are preserved without placeholder substitution
or an integration-constant naming convention. The increment remains factored
to preserve the initial form when approximate coefficients and the time
origin have widely different scales. Approximate inputs retain their SymPy
precision; later expansion or numerical evaluation can still round values.
Zero capacity or pressure yields the initial form. These conditional symbolic
calculations do not admit a runtime state or supply a complete evolution law.
The same helper remains exported by tnfr.math, tnfr.mathematics and tnfr.
The numerical tnfr.mathematics facade derives its symbolic exports from
tnfr.math and omits them only when SymPy itself is missing. Unexpected
symbolic import failures propagate rather than appearing as unavailable helpers.
The retained check_convergence_exponential(growth_rate, time_horizon) uses
the specified unit-amplitude, unit-capacity exponential pressure law. Its
Boolean describes infinite-horizon integral convergence, which requires a
strictly negative rate. At zero rate it returns False and the finite integral
is the supplied horizon: constant pressure produces linear form growth, not
equilibrium. This is a corrected boundary, not a general U2 or stability result.
The public tnfr.validation input validators re-export the implementations in
validation/input_validation.py; no parallel validation rules are introduced.
This includes signed form/pressure, nonnegative capacity, circular phase,
node/glyph, graph-interface and operator-parameter adapters. Their configured
input scope is distinct from live operator admission: a graph-interface check
does not establish a complete nodal state, and an operator-parameter check does
not authenticate an event or certify its trajectory.
The global tnfr.validation.config.ValidationConfig, also exported as
tnfr.validation.StructuralValidationConfig, supplies invariant flags and
minimum severity consumed by structural.run_sequence. Its
enable_semantic_validation and allow_semantic_warnings fields remain accepted
compatibility settings; neither disables the shared grammar or activates an
independent heuristic gate. SequenceSemanticValidator retains its report
interface by delegating to shared word admission. The existing facade
name tnfr.validation.ValidationConfig retains its separate meaning: the
configuration of TNFRUnifiedValidationSystem, including its cache policy.
These are different consumers, not interchangeable configurations.
StructuralValidationConfig construction and configure_validation() use
shared Boolean parsing and InvariantSeverity
members or their exact string values. Updates admit all keys and values before
mutating the shared object, so an invalid batch cannot partially disable its
checks. Keys come from declared dataclass fields, not arbitrary attributes.
Direct Python attribute assignment is outside that update contract. Scalar
domains, live U3 admission and other validator configurations have separate
owners; a successful audit is not a certificate for every nodal model.
Every canonical operator has:
- a lowercase English execution token, a public display/class name, and an internal glyph;
- one primary nodal-equation channel;
- node or network scale;
- a direct-effect direction;
- a verifiable postcondition;
- independent grammar and state preconditions.
The channel classification does not replace grammar roles. For example, Mutation acts primarily on phase while also being a U2 destabilizer and U4 transformer.
Scale is the U5 fractality axis: node acts at the current fiber/level and
network denotes the multi-scale REMESH echo. It is not an execution-footprint
field. Coupling remains node-scale on this axis even though one application may
write neighbouring phases and edge support; those overlaps belong to the
separate stage contract.
The optional validate_nodal_equation helper compares supplied EPI endpoints
with one unforced Euler step holding the current capacity and pressure fixed.
THOL proposal validation reuses this same arithmetic and configuration owner.
It neither authenticates an executed interval nor converts a named operator
jump into continuous nodal flow. A boundary-clipped match can occur with no EPI
motion despite a nonzero unprojected rate. The shared default tolerance is
NODAL_EQUATION_TOLERANCE; compatibility units are EPI for clip-aware comparison
and EPI/time for rate comparison. Invalid time, coefficients or active policy
raise errors. See the parameter foundations
for numerical-policy scope and ownership.
The generic public-operator comparison runs after its event and supplies no
rollback guarantee; THOL checks its detached proposal before committing it.
Positive-duration default and extended integration resolve the same clipping
policy through dynamics.structural_clip.resolve_clip_policy. Invalid modes,
bounds or soft-knee gain reject before rate evaluation, including on frozen
rows; an invalid mode never silently selects hard clipping. Zero-duration
execution retains its no-op contract.
The detached TNFRUnifiedBackend nodal proposal uses the shared rate/Euler
arithmetic. It reports epi_step_scope="unforced_unclipped_proposal" and
stability_not_certified=True: it does not execute Gamma, clipping or history
writes. Stored-state fields must retain their scalar numeric types; Boolean
and textual values are rejected before coercion. Finite inputs with a
nonrepresentable rate or endpoint reject instead of returning a successful
infinite state. A temporal integration request has its own full integrator
contract; it is not this detached proposal.
The backend's temporal request validates the raw step, integral step count and Boolean trajectory flag before dispatch. Stored-pressure execution preflights the entire supplied clock grid, including internal subdivisions, through the integrator's own preparation and clock checks. A later inevitable clock overflow or rounded nonadvance therefore rejects before the first state write. Each step still admits live state/configuration; the preflight neither invokes sources nor makes future callbacks or state-dependent failures globally transactional.
Validated nodal scalar inputs use the shared represented-real admission: Boolean/text values and nonzero values that disappear during binary64 materialization reject. Capacity admits zero and has no arbitrary finite upper cutoff; the supplied product and returned derivatives must still be finite. The extended model reuses the same EPI derivative owner. Validation certifies these numeric domains, not the model's physical derivation; an explicitly unchecked call does not acquire that certificate.
Closed scalar configuration intervals use bounded_represented_real from
_exact_time.py to check the original admitted source against their bounds.
An exact value outside the interval cannot enter by rounding to an endpoint;
floating sources and bounds exposing exact integer ratios use those ratios
for comparison, retaining precision beyond binary64 when available.
Accepted values retain the consumer's binary64 model. This boundary applies
to selector/adaptation controls, stability fractions and active glyph factors.
It does not prohibit rounded arithmetic already declared by a numerical model.
Scalar operator inputs use the same admission before coercion, including incoming form consumed from a neighbor. Runtime Mutation-history recording also requires signed scalar EPI; a rich BEPI magnitude cannot become observed scalar motion. Every node's sample and retained history are admitted before that recording boundary writes any node's history.
Default pressure and optional EPI/capacity hooks reuse nodal capacity admission;
phase pressure admits the authoritative finite phase before trigonometric
conversion. Malformed primary aliases cannot be replaced by a valid secondary
spelling. Invalid state rejects before stored pressure is written, including
after cache reuse and on isolates. Preparation caches are not a rollback
boundary. The phase-only hook requires only its consumed phase coordinates.
Registered pressure hooks and runtime refresh share one optional-n_jobs
dispatcher. Legacy hooks without that keyword remain supported; a TypeError
inside a Python callback body propagates without replaying its side effects.
Uninspectable callables retain the traceback-based argument-binding fallback.
This dispatch boundary does not promise rollback of writes already made by the hook.
The finite forcing observer uses the runtime's own vectorization predicate to
exclude every disabled NumPy route; alternative accumulation paths are not
silently identified with its certified numerical kernel.
Default pressure mixtures and selector score weights use the same strict nonnegative represented-real normalization. Invalid coefficient types or negative values reject rather than becoming zero or a different default mix. Large finite coefficients retain a finite normalized mixture even when their raw sum overflows. An all-zero mix still selects uniform weights by explicit compatibility policy; it is not a request to disable the corresponding model.
metrics.export_metrics exports one detached snapshot of retained history;
it does not initialize or repair history on the graph. CSV and JSON admit the
same scalar values before any destination replacement. Missing samples,
clocks and glyph entries remain JSON null or empty CSV cells; an observed
zero remains zero. Sigma columns align by retained position, without borrowing
another stream's timestamp or substituting a row index. Present Boolean,
nonreal, nonfinite or unrepresentable numbers reject. This replaces the earlier
zero-filling and inferred-clock behavior; consumers must handle availability.
Each file uses the shared atomic writer, but the CSV file set is not one
transaction if a later filesystem write fails.
Network.history() shares retained-sample admission with the metric exporter.
It returns detached kuramoto_R, C_steps, phase_sync and Si_mean series.
An absent series is empty; an explicit missing sample remains None, so callers
must retain that availability when analyzing the series. Lists, tuples, deques,
other non-text sequences and one-dimensional NumPy arrays preserve stored order.
Unordered collections, one-shot iterators and multidimensional arrays reject;
readers do not consume an iterator, flatten coordinates or repair the graph.
Present samples reject Boolean, nonreal, nonfinite and underflowed values
before conversion. These series have no implied clock or formation certificate.
SDK scalar and raw-map readers raise ImportError when their field or balance
implementation is unavailable. In particular, structural_charge() and
candidate_energy() cannot report an unavailable calculation as zero.
The structured conservation() report retains its explicit availability
envelope; missing capability and an observed zero are distinct outcomes.
NuFWindow admits nonnegative integer counts, positive represented durations
and each supplied finite timestamp before conversion. Booleans, fractional
counts, malformed lone bounds and nonzero clock underflow reject. Two bounds
must describe a nonempty window consistent with its duration. The
NuFTelemetryAccumulator retains exact sums of represented durations, so
evicting a large window cannot erase smaller retained windows. Counts, clock
totals, estimates and unit conversions are admitted before a recording changes
the window buffer or graph history; unrepresentable results reject.
Configuration is validated even when an accumulator already exists. Explicit
empty graph/mapping sinks take precedence over an attached graph.
These are observed count-rate estimates under a supplied Poisson model, with
approximate normal confidence intervals. Independence and nonoverlap are
observation premises, not reducer guarantees. The estimate does not replace
the capacity in a nodal law; the configured HZ_STR_BRIDGE is a conversion
convention until independently calibrated. Empty evidence yields unavailable
estimates. Controls: count-rate telemetry.
The standard observer supplies an unstable-node count proxy, derived from the
configured pressure/rate thresholds. It is neither a count of operator events
nor a measurement of primitive capacity. A matching BEFORE_STEP/AFTER_STEP
pair requires a fresh stability observation and positive actual elapsed time;
requested dt does not replace that interval. The runtime's initial zero clock
is an explicit convention. Missing, stale or invalid stability evidence marks
the observation unavailable without adding a zero or all-node count. A second
AFTER_STEP cannot reuse the same interval. Metrics registration places its
producer before this consumer regardless of attachment order, preserving other
callbacks' relative order and existing telemetry configuration. Controls:
standard observer evidence.
The completed window publishes its existing snapshot and updates only the
current observation's metric-history entry, without a second append. An
unavailable observation preserves prior successful telemetry.
Repeated diagnostic registration is idempotent, including strict callback
registration; worker counts are resolved from live configuration when observed.
Only advanced glyph-duration diagnostics consume the configured DT, admitting
it before metric writes. That configured operation-time basis is distinct from
the standard observer's measured elapsed interval.
Global and local structural coherence share stored-alias admission, finite mean
reduction and the reciprocal diagnostic in metrics.common. The radius-local
observation includes its center; the legacy immediate-neighbor observation
excludes it and returns zero at isolates. Invalid consumed aliases reject
without becoming zero or falling through to another spelling. These are
different declared observation scopes, not different coherence laws; neither
refreshes pressure or reconstructs an observed EPI rate.
Local structural and phase observations share one center-inclusive support-ball reader: the center must exist and radius must be a nonnegative integer, excluding Booleans. Phase order reuses admitted trigonometric values and the shared Kuramoto magnitude; malformed present phases cannot be skipped to report perfect alignment. Its legacy empty-graph value of one is a convention, not evidence. A zero resultant has zero magnitude but no direction. Pairwise linear phase affinity is a configured score, distinct from structural C and live U3 admission. All-node pulse and dissonance observations share one live trigonometric capture across their weighted local rows. Sparse affinity entries are partitioned once per call, checking every index and weight before reducing rows. Entry order, duplicates and diagonal admission are retained. Each new observation detects raw phase/support edits; the public one-node reader still revalidates live state independently. No public input can supply a trusted snapshot, and the shared capture is not a persistent observation. Weights reject negative, nonfinite and nonzero-underflowing inputs before acceptance. Ordinary row summation order is unchanged; extreme finite weights use common positive rescaling to avoid overflow and subnormal-product loss in the weighted mean.
The declared-cycle winding reader
uses shared represented-real admission before circular reduction. A nonzero
phase that would materialize as zero makes the observation undefined; an
invalid authoritative alias cannot fall through to a secondary phase. Invalid
or underflowing branch_tolerance and phase_gate raise ValueError; exact
zero remains permitted. The word observer rejects invalid initial phase
before executing a step. A defined sampled winding does not certify identity
between observations or transport of a localized organization.
The shared coherence-value boundary checks the original real input in [0, 1]
before accepting its finite binary64 representation. Rounding a value above one
to one, or a nonzero value to zero, cannot make it admissible. The SDK and
configured validation reports reuse this boundary. TNFRUnifiedValidationSystem
memoizes only typed immutable inputs together with the consumed policy, and
returns detached results. Text cannot reuse a numeric result; changed bounds or
string patterns require their own evaluation. Both caching switches must be
enabled for reads and writes. Its frequency cap and phase-range warnings are
application policy, not additional constraints on the nodal identity.
TNFRValidator.validate_inputs() delegates to the existing typed input helpers
and returns admitted values for supplied form, capacity, phase, pressure, node,
glyph and graph inputs. Failures raise ValidationError or populate error
when raise_on_error=False; the aggregate validate() consumes that failure.
Its legacy config argument does not override the shared adapter's policy.
Graph-interface admission does not validate an entire trajectory or operator word.
The aggregate validator admits Boolean check flags and operator graph/target
context before dispatch; missing context cannot produce a successful skipped
operator check. Runtime validation explicitly opts into the existing mutating
clamp pass. Disabled passes are tagged skipped; reported runtime/invariant
failure respects raise_on_error. Live graph checks always run afresh: the legacy
cache switches remain compatibility arguments, since graph identity cannot
capture changing state, selected checks or arbitrary custom-validator inputs.
Returned violation records are detached while preserving node-label identity.
The ten historical invariant-check identifiers retain API compatibility; they do not replace the six canonical invariants. Scalar checks admit authoritative aliases through the shared domain owners: uniform signed-real BEPI is valid form, while complex/nonuniform form cannot be projected into admission. Nonnegative capacity includes zero even at nonzero pressure. Configured bounds, edge-phase thresholds and low-capacity/high-pressure alerts remain diagnostic policies, separate from live U3 admission or NFR existence. A false optional operator-history marker with changed form produces a warning; that marker neither forbids declared continuous flow nor identifies the change's cause. See the validator controls.
run_structural_validation() and its health summary distinguish field
availability from threshold flags. Unavailable comparisons have no passing
Boolean; empty support, undefined curvature or invalid thresholds cannot yield
low risk. Independent valid alerts remain active. Reports retain comparison
status/reasons and xi estimator provenance. These observers do not advance nodal
state; shared field and geometry owners may maintain rebuildable graph caches.
Coherence level-set certificates additionally reject a non-equilibrium input that rounds to the exact equilibrium level. Their fixed capacities use the shared represented-real boundary. Retrospective learning efficiency is absolute scalar EPI change per retained operator count, not evidence of learning quality; its initial state and count must refer to the same observation window.
OZ topology telemetry compares explicitly captured before/after heterogeneity
scores. Without a preceding observation, its delta and change flags are None.
The shared direct/stage lifecycle captures this diagnostic only when metrics
are requested; nodal validation alone does not require topology telemetry.
The native pressure operation preserves support; an asymmetric snapshot alone
does not establish an operator-induced change or mathematical symmetry breaking.
StructuralFeedbackLoop reads signed scalar form and radius-local coherence
through their shared owners. Invalid state or consumed mutable policy rejects
before operator selection. Its adaptation accepts a finite signed performance
measure, checks the represented update, then applies the existing threshold
clamp; NaN or overflow cannot become a successful clamp. Each cycle measures
one pre-action and one post-action state without initializing an unused backend.
This remains a supplied controller, not an emergent operator-selection law or
a transaction covering arbitrary later operator/callback failures.
TNFRSelfOptimizingEngine admits consumed graph scalars before binary64
conversion. Boolean/text/nonfinite values and nonzero values lost to zero
raise TNFRValueError. Invalid optional performance measurements remain
unavailable. Pressure magnitude and measured speedup, memory, charge-drift
and Si means use shared finite reductions, retaining representable means
even when a naive sum would overflow. EPI variance uses translated/scaled
dispersion and becomes None when its nonzero square cannot be represented;
that case does not trigger the low-variance policy. Exact zero remains valid.
These are numerical and policy-admission rules, not new nodal dynamics.
The manifest workflow
owns input-file admission and report handling.
Phase coordination validates every proposed phase before its first phase
write on NumPy, scalar and worker paths. Only its exact-reduction transaction
also restores graph-owned caches/history after a late failure. Capacity
adaptation applies raw represented-real admission before eligibility checks;
neither change selects a phase law or derives its configured diagnostic gates.
Missing Si or pressure makes the capacity gate unavailable: its consecutive
stability count resets and that node's capacity is retained. Missing capacity
rejects before mutation because the neighbor snapshot consumes it. Explicit
invalid values, including None, still reject; absence is not a zero-valued
measurement. The policy reads stored inputs and does not refresh them.
It is a per-invocation event, not a continuous capacity law. Preservation of
a supplied relation nu=g(x) has separate
flow and event obligations.
Coherence and equilibrium observations apply this admission before scalar or array coercion. Stored pressure/rate/capacity readers honor the first present alias: an invalid authoritative value cannot fall through to a later alias or become zero. Missing attributes retain their documented defaults. Stability tolerances must be finite nonnegative real values even on empty support; their positive cuts describe a diagnostic neighborhood, not exact equilibrium. Sense-index normalization shares these reads on Python and NumPy paths, including cache refresh. This changes invalid-input handling, not the Si law or its status as a configured diagnostic used by existing controllers.
The shared scalar setters rebuild a cold absolute-maximum cache, or one without a live witness, from the whole consumed channel. Untargeted nodes therefore remain included after a selected-node write. Rebuilds admit authoritative real capacity/pressure values and signed scalar EPI through their respective shared owners; missing values retain zero, while invalid present values reject. A tied maximum witness is an implementation choice, not structural identity. Warm incremental caches require mutations to stay within their declared setter scope; arbitrary raw writes require rebuilding. Generic setters have no failure-atomicity promise. Snapshot operator stages retain their separate graph-owned rollback contract if a rebuild fails.
Shared physics scalar and series readers also use represented-real admission:
nonzero values lost in binary64 conversion reject before a diagnostic can
interpret them as zero. Their ValueError policy and signed-zero convention
remain intact. Series return owned, writable float64 arrays; ordinary numeric
arrays and plain lists/tuples of binary16/32/64 floating scalars use equivalent
vector checks. Other source types retain scalar admission before conversion,
and invalid elements retain their indexed errors. Model-specific sign and shape
constraints still apply.
The older integrate_canonical_nodal_equation convenience API also uses the
shared derivative/Euler arithmetic but holds pressure and capacity throughout
its loop. Both accepted method names describe that same constant-slope map;
its step-change stopping criterion is not equilibrium. Its legacy missing-value
defaults (unit capacity, zero form/pressure) are initialization policies, and
it writes neither the runtime clock nor derivative history. Invalid candidate
states reject before commit. The default runtime's rk4 path, in contrast,
samples the declared Gamma forcing at the quadrature times while holding the
nodal base fixed. Shared quadrature handles exceptional floating-point ranges;
this does not establish fourth-order accuracy for arbitrary changing pressure.
The default additive-forcing integrator evaluates declared Gamma sources strictly
on positive-duration calls:
an invalid source cannot silently become the unforced model on one backend.
The live Gamma registry owns dispatch. Built-in array formulas apply only to
their unchanged registered implementations; custom or replaced entries use
the staged scalar path, once per node and quadrature sample. These callbacks
read the live graph, not hypothetical intermediate EPI states. Kuramoto-based
forcing refreshes its phase-dependent cache even when the requested time is
unchanged. The permissive public eval_gamma(..., strict=False) read retains
its explicit zero-on-error compatibility behavior; it is not solver admission.
Callback effects outside the integrator's documented write boundary are not
made transactional by source dispatch.
The opt-in extended EPI/phase/pressure integrator uses this same live source
registry once per node at each synchronous Euler substep. Its form row is
dEPI/dt=nu_f*DeltaNFR+Gamma, including at zero capacity; its independently
configured phase and pressure rows are unchanged. The scalar helper
compute_extended_nodal_system evaluates the unforced local rows and does
not itself consume a graph registry. Zero-duration calls evaluate no source.
Restoration after failure covers solver-owned outputs, not callback side
effects or diagnostic caches.
Direct and staged Emission/Silence share structural and lifecycle proposals.
Emission rejects a configured clipped result that would decrease the supplied
EPI before writing form or lifecycle metadata. For example, soft clipping of
-0.99 + 0.001 produces approximately -0.995113, outside AL's nondecrease
contract; hard clipping admits the corresponding -0.989 result. The selected
clipping law itself is unchanged. Silence validates nonnegative raw capacity
even when its attenuation factor is zero. Expansion/Contraction likewise
validate consumed raw state and any active telemetry sink before primary
writes. These preflights do not make arbitrary later callback failures atomic.
This table is generated from the registry, including its declared measurement
context. Refresh it with python scripts/check_documentation.py --write-generated;
the normal documentation gate checks exact agreement. It specifies metadata and
contracts, not a proof that every execution path satisfies a global theorem.
The separate grammar role table
is generated from the grammar registry; a role does not replace the operator's
live preconditions or measured postcondition.
| Operator | Token | Glyph | Primary channel | Scale | Context | Registered postcondition |
|---|---|---|---|---|---|---|
| Emission | emission | AL | EPI | node | network | EPI not decreased; νf, phase and ΔNFR unchanged |
| Reception | reception | EN | EPI | node | network | Immediate operator-local C(t) unchanged; ΔNFR and dEPI unchanged |
| Resonance | resonance | RA | EPI | node | identity | EPI structural identity (sign/kind) preserved |
| Silence | silence | SHA | nu_f | node | network | νf not increased; EPI, ΔNFR and phase unchanged during SHA |
| Expansion | expansion | VAL | nu_f | node | network | νf not decreased (capacity added) |
| Contraction | contraction | NUL | nu_f | node | network | νf not increased (capacity removed) |
| Coupling | coupling | UM | theta | node | network | |ΔNFR| not increased (mutual stabilization) |
| Mutation | mutation | ZHIR | theta | node | phase | θ transformed (θ → θ') |
| Coherence | coherence | IL | delta_nfr | node | network | |ΔNFR| not increased and C(t) not decreased |
| Dissonance | dissonance | OZ | delta_nfr | node | node | |ΔNFR| not decreased |
| Self-organization | self_organization | THOL | delta_nfr | node | network | parent EPI, nu_f and phase fixed; DeltaNFR follows signed acceleration; nested child creation preserves parent identity |
| Transition | transition | NAV | delta_nfr | node | state | state changed (νf, θ, or ΔNFR) |
| Recursivity | recursivity | REMESH | EPI | network | advisory | node-level advisory; network effect = EPI mixed toward temporal/multi-scale history |
The REMESH row distinguishes the advisory glyph from the separately invoked network operation apply_network_remesh. Its public planner, plan_network_remesh, returns an immutable all-node proposal. Insufficient history or empty live support is an explicit no-op; after the history guard passes, each selected temporal snapshot must be a node mapping with exactly the live support. Missing values are never replaced by current EPI.
The executor returns an immutable result that exposes raw affine and bounded values separately. Optional evidence reports the three-snapshot convex disagreement bound, weighted-mean drift and only sufficient fixed-history gain conditions. These fields do not infer stability from the operator name. The commit is atomic over graph-owned state, topology, metadata, history, caches and capturable callback state. Effects already emitted to external systems by a callback cannot be rolled back.
A direct node-level Recursivity glyph and its shared word stage are advisory-only: the stage derives one immutable advisory from its snapshot, deduplicates one graph event per telemetry step and leaves structural channels unchanged. It never triggers delayed EPI mixing implicitly.
The optional memory helper propagate_structural_identity is a separate
hybrid jump. It interpolates signed scalar form and nonnegative capacity and
uses the shortest circular phase arc, with the shared signed antipodal tie
convention. It does not solve continuous nodal flow or certify persistence.
Strength must be a finite represented real in [0,1]; zero is a no-op.
Every unique non-origin target is validated before writes, including consumed
triad coordinates, clipping policy and lineage sink. Missing coordinates and
invalid strengths no longer acquire zero/default interpretations; invalid
clipping modes reject. Materialized uniform-real BEPI is admitted in the scalar
chart; richer or serialized form payloads are not. Convex form/capacity
proposals round once from represented inputs and reject nonzero underflow.
Lineage records actual endpoints and the step ordinal, while stored pressure
and the physical clock are retained. Input preflight does not promise rollback
of arbitrary custom mapping/setter failures or the entire memory wrapper.
For exact wording and measured context, inspect
OPERATOR_CONTRACTS.
The single working definition is AGENTS.md, canonical invariants. This API reference states path-specific preconditions, effects and evidence; it does not maintain a second list or strengthen those invariants.
from tnfr.operators.definitions import Coherence, Emission, Silence
from tnfr.structural import create_nfr, run_sequence
G, node = create_nfr("seed", epi=0.1, vf=1.0, theta=0.0)
run_sequence(G, node, [Emission(), Coherence(), Silence()])The word starts with a U1 generator, contains a stabilizer, and ends with a U1 closure. State-dependent operator preconditions remain mandatory during execution. Coupling and Resonance additionally enforce U3 before mutation.
Resonance's optional strict preconditions and readiness report share admitted state and finite nonnegative policy thresholds. Invalid thresholds reject before direct or atomic-stage writes. The readiness flag covers the configured form-magnitude, capacity, pressure-magnitude and connectivity checks; it does not replace U3 or authorize execution. Its neighbor-mean phase warning retains an unavailable direction at an exactly zero represented resultant, while invalid consumed phases raise. These reads do not write graph caches.
The shared nodal integrator reads the
authoritative capacity, pressure and previous derivative aliases: invalid
provided values cannot fall through to a later alias or a zero default.
Capacity must be finite and nonnegative; pressure and retained derivatives
must be finite represented reals. Missing values retain the documented defaults.
The step, initial time and minimum step use the same raw scalar admission:
Boolean/text inputs and nonzero values lost to zero during conversion reject.
Use explicit numeric
0.0 or 1.0 when those durations are intended. Admitted zero-duration calls
remain no-ops.
Runtime consumption retains the authoritative timestep until shared
represented-real admission, including values changed by BEFORE_STEP
callbacks or pressure hooks. Earlier callback/pressure effects are not rolled
back by this check. The auxiliary-engine handoff retains the duration supplied
to the nodal integrator, rather than rereading a mutable DT afterward.
The separate mechanical symplectic steppers use the same
raw admission for signed timesteps, retaining negative reversible stages and
zero-step identity.
Every positive internal substep must advance a finite represented clock; checking only the requested final duration is insufficient under subdivision. Empty and populated graphs use the same repeated-add time convention. Projected EPI and stored rate/acceleration must be finite before commit. The scalar and optional extended paths restore solver-owned node outputs if a later substep fails; callback side effects and diagnostic caches are outside this local restoration. The event executor supplies its broader transaction. Clipping still separates the stored unconstrained rate from the realized EPI secant. These checks establish neither solver accuracy nor a physical clock. Controls: integrator numerics.
The separate rk4_coupled_step(state, rhs, *, t, dt) accepts a nonempty tuple
of complete real coordinates and a callback returning the same-size tuple of
rates. It refreshes that callback at every immutable full-state RK4 stage,
reusing the existing Euler and quadrature arithmetic. Every coordinate, rate,
time and output receives represented-real admission; the positive duration
must retain strictly ordered start, midpoint and endpoint clocks. Invalid
dimensions, nonfinite results and nonzero results lost to zero reject.
This explicit helper supplies no model, clipping, phase wrapping, graph writes,
history or accuracy certificate. The caller retains law, Gamma, clock and
observation association; callback effects are outside rollback. The ordinary
graph integrator's held-pressure semantics remain unchanged. Independent
coupled-step controls exercise its numerical
and admission boundaries.
The extended scalar flux divergence retains its unique outgoing-neighbor law
sqrt(k) * (J_i - mean(J_j)), including self-loops and excluding parallel-edge
multiplicity. It reuses shared neighbor-difference arithmetic, so finite common
offsets and mixed-sign cancellation do not create spurious overflow or
divergence. Invalid consumed inputs and unrepresentable final values reject.
This scalar contrast is not an incidence divergence or a conservation theorem.
Active built-in Gamma sources validate authoritative phase aliases before
trigonometric caching or array conversion. A vector source requires one phase
per node; a malformed primary alias cannot be hidden by a valid secondary one.
Scalar and array Gamma APIs validate the supplied clock. The unforced none
source does not consume phase, and custom registry entries retain their declared
input dependencies. The shared trigonometric cache validates current raw phase
values on every read, including when they would coerce to a cached value.
U3 phase/limit admission, Coupling coefficients and consumed known numeric glyph factors use the shared represented-real boundary. A tiny nonzero factor cannot silently select a zero-valued policy; unknown extension keys remain outside the canonical factor schema. The conservation/gauge snapshot mapper applies the same scalar admission to consumed U3 phases and U6 pressure/reference fields; nonzero underflow makes that diagnostic unavailable, not a passing zero. Direct and simultaneous Resonance reuse one capacity proposal: finite nonnegative capacity is required even when amplification is inactive. Graphless unidirectional Coupling updates only the target phase. On graph paths, UM/RA means use unique outgoing support neighbors, including zero-weight edges; parallel multiplicity and incoming arcs do not supply additional samples. These remain operator policies, distinct from weighted EPI transport. The coupled-state controls also verify support-cache invalidation after functional-link creation.
The maintained contract is Conditional relational execution. The separate sine report admission also covers exact supplied primitives, captured binary64 coordinates and derived-field reconstruction. The regional guide routes those readers by task; none is an implicit sine mode of the native relational executor.
See Exact linear observations.
See Prepared relational pattern observations.
See Supplied relational attachment observation.
See Conditional relational capture.
See Validated conditional relational transit.
See Exact cycle resultant sectors.
The maintained operator-event and finite-evidence contract owns schedules, runtime transactions, flow/stage observations, REMESH composition and the scoped certificate APIs. The headings above retain earlier incoming links; full contracts are maintained only in the linked chapters.
The testing guide owns selection and execution commands. Core operator regression entry points are:
Use the grammar verification map for U1–U6, the REMESH proof owner's direct checks for history/schedule/certificate controls, and the theory-to-implementation map for other model-specific controls. Those owners retain the detailed test obligations; this hub does not duplicate their inventories. Finite regression checks are not unrestricted stability proofs or physical validation.
The catalog is fixed at 13 canonical operators. A domain feature should compose existing operators or remain a diagnostic/morphism outside the catalog. Any proposal to alter the catalog requires a nodal-equation channel, scale, postcondition, grammar classification, tests, and an update to the canonical synthesis; adding a class or registry entry alone does not establish canonicity.
get_backend resolves an explicit name,
then TNFR_MATH_BACKEND, then
tnfr.backend_config.get_config().math_backend. The service default is auto.
Automatic selection tries GPU-capable adapters in JAX, PyTorch, NumPy order,
then repeats that order for any available adapter, including CPU adapters.
An explicit numpy request selects NumPy. A registered but unavailable named
adapter falls back to NumPy; unknown names raise LookupError.
MathematicsBackend includes is_gpu_available(), get_device_name() and
get_backend_info() alongside its array operations. Its
typing declarations retain that interface
and the canonical core.exceptions.BackendUnavailableError identity.
Backend selection supplies a numerical implementation, not an evolution law;
reproducibility records must identify the adapter actually used.
The PyTorch adapter copies read-only NumPy arrays before conversion because
tensors cannot preserve their write protection. Writable arrays retain the
existing sharing behavior when dtype/device permit; native tensor conversion
preserves identity and autograd when no conversion is needed.
The NumPy adapter delegates general matrix exponentials to the required SciPy
dependency. If SciPy is unavailable, that operation raises
BackendUnavailableError; a possibly defective eigenvector decomposition is
not substituted for the exponential. Other NumPy array operations remain
available.
register_backend validates a complete registration before changing factories,
aliases or instantiated adapters. Canonical names and aliases cannot shadow
one another, including with override=True; empty names and the reserved
selection name auto reject. A canonical override replaces its
factory and invalidates its instantiated adapter; unmentioned aliases remain.
An alias override may retarget an existing alias. A rejected proposal leaves
the registry and instance cache unchanged.
BEPIElement admits original finite real/imaginary components before array
conversion, using the shared represented-real boundary for each channel.
Boolean/text coercion and nonzero materialization loss reject, including in
ensure_bepi scalar/serialized routes. Complex and nonuniform BEPI remain
valid auxiliary elements; the shared signed-scalar reader still governs
whether an element can enter the nodal form row.
The sampling grid likewise admits original represented-real entries before
conversion: Boolean/text coordinates, complex coordinates and nonzero
materialization loss reject.
The stored BEPI arrays are owned, writable copies. Numeric-array fast paths
retain the same primitive admission and zero normalization; mutable arrays
are re-admitted by consuming calculations. The standard Banach-space element
factory delegates construction admission to BEPIElement, while customized
validation hooks retain their dispatch.
HilbertSpace represents finite coordinate vectors with a positive integer
dimension. Its floating or complex storage dtype cannot discard a nonzero
real/imaginary channel: real storage rejects nonzero imaginary coordinates,
and narrowing that overflows or erases a nonzero channel rejects. Norms use
the shared range-safe Euclidean observer. Inner products, Gram checks and
projections accumulate in complex128 and reject nonfinite outputs; ordinary
floating rounding remains, including possible underflow in products. A
supplied partial orthonormal family returns only its projection coefficients.
Composite EPI regularity trends admit finite represented-real observations,
including those computed from BEPI, and nonnegative represented tolerances.
Their threshold comparisons use the exact represented values, so an
overflowed or rounded comparison cannot turn a violation into a pass. A
reported drop must itself be representable. The plateau policy uses shared
Boolean parsing. These trends remain auxiliary regularity diagnostics, not
canonical C(t) measurements or stability certificates. The generic isometry
factory and norm-preservation checker remain explicitly unimplemented.
BanachSpaceEPI.derivative_regularity cancels a common large amplitude before
evaluating its sampled derivative-energy quotient. Its quadrature arithmetic
and result must be finite, with a positive denominator; a nonconstant field's
positive quotient lost to zero rejects. Exact constant fields retain zero.
Composite regularity uses a range-safe discrete norm and admits its strictly positive weights
before conversion; an unrepresentable composite value rejects.
evaluate_composite_epi_regularity_transform and its historical
evaluate_coherence_transform alias admit nonnegative finite policies and
both observed regularities, including results from a custom space. The
lower-bound comparison uses their exact represented values; the reported
requirement, deficit and ratio with a positive baseline must be representable.
A zero baseline followed by a value above the supplied tolerance retains
the explicit infinite-ratio convention. That ratio does not decide the
inequality or identify the auxiliary functional with canonical coherence.
Spectral state and operator readers admit original complex components before
materialization. Concrete backend tensors are checked through observations
while native calculations retain their automatic-differentiation path. A JAX
symbolic trace has no observable concrete finiteness verdict; its numeric
dtype/shape admission does not certify future values. Spectral expectations,
weighted angles and normalized mathematical evolution scale the vector before
taking its norm, so a representable normalized result is not erased by
overflow in the unscaled squared norm.
The mathematical runtime uses that same admission and normalization in
stable_unitary. Its normalized and stable_unitary reports observe the
standard Euclidean norm without squaring the unscaled amplitudes; an
unrepresentable norm rejects instead of returning infinity. Their tolerances
must be finite nonnegative represented reals. stable_unitary reports whether
the final norm is one within tolerance; with normalise=False, a preserved
non-unit input norm therefore does not pass this unit-norm check.
MathematicalDynamicsEngine and ContractiveDynamicsEngine likewise own their
admitted generators and return detached generator observations. Reconstruct
the engine to change that law; editing the original input or returned array
does not change its evolution.
Both engines admit signed finite represented-real time increments, including
when evolve requests zero steps; step counts are nonnegative integers.
Concrete native real scalar clocks retain their gradient path after admission.
Symbolic JAX clocks receive only scalar-shape and real-dtype checks, with no
concrete finiteness certificate. Exponential arguments and evolved concrete
states must be finite; a nonfinite observed density trace rejects before
normalization. Signed time permits reverse auxiliary evolution; it
does not extend a forward dissipative-semigroup theorem to negative time.
For the built-in engines, one evolve invocation reuses the exponential of
its fixed generator and time increment. State admission, normalization and
monitoring still run at each step. The propagator is local to the invocation:
zero steps compute none, and subsequent calls build it anew, including native
gradient graphs. Subclasses and replaced public step methods retain their
per-step dispatch.
The nodal runtime's optional MATH_ENGINE path forwards authoritative raw
coordinates to its projector; a rejected node is not silently omitted from
the preparation. Tolerance and generator admission precede auxiliary evolution.
Retained state uses the engine's declared backend, with explicit export for
observation adapters. These handoff checks do not promise full-step rollback.
The public mathematical phase readers apply the same raw-value admission to
scalar, list and NumPy inputs. normalize_phase returns the represented
half-open interval [0, 2*pi); a modulo result rounded to its upper endpoint
is canonicalized to zero. compute_phase_difference retains its signed
atan2(sin(delta), cos(delta)) convention and rejects unrepresentable
subtractions. These numerical readers do not replace live U3 admission.
The circular mean uses this same represented phase boundary.
The shared safe_divide and clamp_value helpers reuse raw represented-real
admission for values, bounds and fallback. Boolean, text, nonfinite and
nonzero materialization-loss inputs reject on NumPy and scalar paths before
division or clipping. A zero denominator selects the admitted fallback;
overflow or nonzero underflow of a quotient rejects instead. NumPy
broadcasting and the scalar path's one-dimensional broadcasting remain
available. The clamp/clamp01 adapters inherit this boundary, so clipping
cannot turn an invalid observation into an apparently valid bounded score.
Bounded pressure, capacity and grammar normalizations compare admitted
magnitudes before dividing, so a finite ratio above the clipping bound can
saturate without an overflowing intermediate. Nonzero interior ratios must
remain representable; zero-normalizer conventions remain with each caller.
Range and similarity helpers use exact represented differences when finite
endpoints span more than binary64 can hold. These are numerical diagnostic
policies, not stability certificates.
angle_diff_array checks selected results in the requested output dtype
before writing: narrowing that erases a nonzero difference rejects and leaves
the output unchanged, including its unselected entries.
BasicStateProjector admits signed scalar EPI, nonnegative capacity, finite
phase and a positive integer dimension before array construction or random
excitation. It requires a complex dtype and admits its null tolerance before
random draws. Boolean/text values and nonzero materialization loss reject,
including nonzero components erased when narrowing the output dtype.
The CLI math summary reads authoritative aliases under these same domains;
invalid primary state cannot fall through to a secondary alias, and legacy
phase storage is retained. This auxiliary map does not identify physical state.
The summary rebuilds its validator from current admitted operators and
thresholds; a cached verdict cannot substitute for those live premises.
The projector reuses the shared spectral-state normalization, scaling
finite amplitudes before evaluating their norm. Its null threshold must be a
finite nonnegative represented real, matching the other normalization consumers.
A representable large-amplitude vector therefore remains normalized instead
of collapsing to zero after norm overflow. Nonfinite intermediate amplitudes
reject; finite inputs alone do not promise representable output arithmetic.
ContractiveDynamicsEngine.step(..., raise_on_violation=True) propagates an
explicit monitored-norm violation and retains the measured gap. Failure to
observe that gap remains distinct from a measured violation. This auxiliary
monitor does not establish contraction in every norm: valid amplitude damping
can increase distance from the maximally mixed state.
Its public Frobenius observer and concrete centered monitoring norms use the
shared range-safe norm. Nonfinite or unrepresentable concrete observations
raise instead of becoming an unavailable gap that bypasses the monitor.
A live JAX trace still has no concrete norm observation and retains an
unavailable gap; native propagation retains its gradient path.
get_laplacian_spectrum rebuilds the consumed operator before cache lookup.
Cached diagonalizations use immutable matrix bytes in the current node order,
including the selected combinatorial weight channel; returned arrays are
detached. Changing edge weights or node iteration order cannot reuse a
different matrix's eigenbasis. heat_diffusion uses shared nonnegative
represented-time admission before evaluating the supplied spectral semigroup.
The eigensolver follows exact symmetry of the admitted real operator matrix,
not the graph container's directed flag. Reciprocal directed support can have
a symmetric operator and therefore an orthonormal eigenbasis; an asymmetric
operator retains the general right-basis solver, including for partial requests.
For nonnegative reversible graph operators, component support determines the
stationary subspace (constant vectors for combinatorial/random-walk charts,
square-root-strength vectors for the symmetric chart). Identified stationary
modes retain exact represented zero rates at long horizons. A small eigenvalue
alone is never clipped: unresolved mixing with slow modes rejects the chart.
Very weak bridges between otherwise strongly connected components can reach
this numerical resolution limit even with strictly positive finite weights.
This floating subspace check is not a validated spectral enclosure. Signed
combinatorial and asymmetric operators retain their generic numerical spectrum;
arbitrary supplied spectra receive no stationary-mode correction. Nonfinite
heat-result arithmetic rejects explicitly.
Multi-field spectral diagnostics with at most 100 nodes can reuse an
invocation-local basis validation across individual GFTs. Larger diagnostics
retain their sequential backend dispatch and field reductions. No basis-validity
cache survives the call; generic inputs and replaced transform hooks retain
their individual dispatch. The public spectral_filter still revalidates its
basis after the supplied filter callback.
physics.spectral_conservation aligns consumed snapshot maps with the graph's
node iteration order and requires matching nonempty support. Its real Parseval
diagnostics additionally require a full finite real orthonormal basis; the
general GFT's invertible right-basis domain alone is insufficient. Consumed
snapshot values use shared real admission before array conversion, including
Boolean, nonfinite and nonzero-materialization-loss rejection. Time intervals
must be finite and strictly positive; supplied policy thresholds must be finite
and nonnegative. Invalid observations, charts or unrepresentable report arithmetic
reject before classification. The explicit sector_ratio infinity convention
for a geometric denominator below its existing floor remains separate from
arithmetic failure.
The two-snapshot modal source is the GFT of delta_rho / dt + mean_divergence;
stored divergence is not multiplied by Laplacian eigenvalues again. The
mode_transport_rates classification field contains the signed divergence
spectrum itself, with the non-strict threshold boundary including zero at a
zero threshold. Band scores describe the supplied observations; neither their
ordering nor a future stability guarantee follows from an operator label.
In conservation_quality_by_band, a band without observed modes has value
None; consumers must handle that absence instead of interpreting it as the
former perfect score of 1.0.
These are scoped observations under the
spectral balance contract.
Liouvillian spectral readers require finite original real/imaginary components
and finite nonnegative represented tolerances. Invalid spectra reject before
selection or metadata mutation. Numeric-array admission returns owned complex
storage with canonical positive zeros; invalid arrays retain the scalar reader's
first failing component and exception. The compatibility validate_contractivity
flag checks only eigenvalue real parts against its tolerance; it does not
certify a Lindblad representation or contraction in an arbitrary norm. Stored
spectra retain no independently authenticated generator or clock provenance.
The slow-mode reader selects the first eigenvalue with the least negative real
part strictly below -tolerance. Its decay timescale alone does not establish
whole-state convergence, measured recovery or U6 admission.
build_lindblad_delta_nfr uses the shared original-component reader for its
Hamiltonian and collapse matrices, admitting each supplied matrix once. Its
trace-preservation check is vec(I)* L = 0, with * denoting the adjoint;
it does not require L vec(I) = 0 (unitality). Amplitude damping is an example
that preserves trace while changing the identity.
Both generator factories admit finite real scaling factors and a representable
product, plus positive integer dimensions. They reject nonfinite constructed
matrices. These are supplied auxiliary matrix multipliers; a signed multiplier
does not redefine the nonnegative nodal-capacity domain. Forward GKSL
interpretation requires a nonnegative overall generator factor and its other
model hypotheses.
The auxiliary dissipative diagnostics require representable snapshot purity,
computed actions, bounds, rates and comparison thresholds as well as finite
primitive inputs.
They reject nonfinite results before issuing bound or unitality verdicts;
nonzero collapse-norm squares lost to underflow also reject. Frobenius norms
use the shared scaled fallback when direct squaring exceeds the numeric range,
and observed balance rates use the shared signed secant reader. These checks
preserve the diagnostic availability conventions:
absent collapse or reference data retain explicit NaNs and unevaluated flags.
The trace-distance ratio remains infinite when the initial distance is at or below
its configured floor but the final distance is not; that observation fails
the contraction check and is distinct from arithmetic overflow.
Generator spectral scales, eigenspectra and residuals must also be finite
before stationarity, trace-preservation or mode classifications.
DissipativeConservationTracker.record commits its snapshot history and
diagnostic series only after snapshot admission and all diagnostics succeed.
The optimized arithmetic sieve uses Python integers for divisor sums before
evaluating the supplied floating pressure formula. FiniteField admits an
integer prime characteristic, supported positive integer extension degree and
integer modulus coefficients; a composite-characteristic ring is not admitted
as a field. These are premises of the
arithmetic models, not physical identifications.
cayley_diffusion_action preserves support-derived exact stationary Fourier
modes, including disconnected supports. Unrepresentable positive clock
products or nonfinite Fourier intermediates reject explicitly; the calculation
remains a floating evaluation of a supplied fixed circulant law.
Finite-field arithmetic normalizes integer/index elements to Python integers
before operations and requires 0 <= element < q; powers require nonnegative
integer exponents, and power-set orders are positive integers.
For built-in field arithmetic, normalized periods can reuse character values
within one invocation while preserving the original summation order. Later
calls read the current presentation anew; customized arithmetic and character
hooks retain their direct dispatch.
OptimizedTNFRPrimality applies the same strict abs(delta_nfr) < threshold
policy with and without sieve coverage. The cut must be finite, positive and
representable; the default 0.5 separates the prime zero set for its configured
weights. Larger cuts may admit composites and do not alter the exact theorem.
Returned reports and nested metrics are detached from the cache; subsequent
calls do not change previous cache_hit observations.
SpectralExpectationOperator evaluates the Hermitian quadratic form
<psi|A|psi>. For a unit-norm state, including the default
expectation(..., normalise=True) path, its exact-real value lies in the
spectral interval of A; numerical evaluation retains floating-point error.
With normalise=False, an unnormalized input instead scales that interval by
||psi||^2: A=diag(2,3) and psi=(2,0) give 8, not a value in [2,3].
Values above one are valid in either mode. This auxiliary value is never the
structural coherence C(t), never inherits a [0,1] bound, and never enters
C_steps. Payload metadata range="unbounded_real" and bounded=False
describe the family of supplied observables; they do not negate the conditional
spectral bound for a fixed Hermitian operator and normalized state.
is_positive_semidefinite requires Hermiticity as well as nonnegative
eigenvalues within its tolerance. spectral_weighted_angle uses that shared
gate; positive eigenvalues of a non-Hermitian matrix cannot admit a Hermitian
angle geometry.
The weighted-angle ratio combines binary exponents separately rather than
squaring overlaps and multiplying expectations at their original scale.
This retains finite scale-invariant angles when those intermediate products
would overflow or underflow. Consumed overlaps and positive expectations must
still be representable; this does not repair precision lost in dot products
or remove the configured absolute null threshold.
Operator factories reuse the constructor's Hermiticity and PSD gates and
admit original components before backend conversion. The spectral factory's
real projection within its imaginary-part tolerance retains the native
gradient path. Factory dimensions use the same positive-integer admission
as their SDK/CLI consumers; Boolean and floating dimensions reject.
Explicit comparison floors and thresholds use the shared represented-real
boundary, including rejection of nonzero values lost to materialization.
A comparison floor may be negative independently of the supplied PSD spectrum.
Construction owns a detached matrix and its matching spectrum. The public
matrix and eigenvalues properties, and spectrum(), return detached arrays;
editing these observations or the original input cannot change the operator
or its PSD verdict. Direct property assignment is no longer supported: create
a new operator to change the observable and recompute its spectrum together.
Construction reuses its admitted matrix snapshot for Hermiticity checks,
avoiding redundant backend transfers; native spectral arithmetic retains its
gradient path.
NodeNX, create_math_nfr, the dynamics runtime and the CLI expose the
canonical names spectral_operator, spectral_expectation_threshold and
spectral_operator_expectation. Every result payload contains value,
threshold, passed, metric_kind, range, bounded,
provenance, canonical_coherence_certified=False and
records_to_C_steps=False.
Historical coherence_operator, coherence_threshold, coherence_value,
coherence_passed and runtime history keys remain explicit compatibility
aliases. They mirror the same auxiliary spectral value and carry no C(t)
meaning. Supplying contradictory canonical and historical inputs is rejected.
The CLI accepts --math-spectral-expectation-spectrum,
--math-spectral-expectation-floor and
--math-spectral-expectation-threshold. The former
--math-coherence-* spellings remain accepted as aliases.