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 a6217ab
Browse filesBrowse the repository at this point in the historyBrowse files
TNFR AI Agent
committed
Merge audited numerical foundations and conditional formation research
Copy file name to clipboardExpand all lines: ARCHITECTURE.md
+55-2Lines changed: 55 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,6 +18,11 @@ boundary, not a measured speedup. Other state/configuration dependencies remain
18
18
part of each consumer's key or explicit invalidation contract. Graph views use
19
19
fresh computations; concurrent mutation during a read is unsupported.
20
20
21
+
The structural random-walk verifier reuses one resistance geometry within a
22
+
call for resistance and commute-time projections. The comparison still uses
23
+
the separate component-volume multiplication of materialized resistance.
24
+
There is no persistent geometry cache; a later call re-admits the graph.
25
+
21
26
LRU storage and callback handling have one implementation in
22
27
[`utils/unified_cache.py`](src/tnfr/utils/unified_cache.py). The compatibility
23
28
`InstrumentedLRUCache` and `ManagedLRUCache` names remain aliases in `utils.cache`;
@@ -61,6 +66,23 @@ graph invalidation and persistence retain their separate responsibilities.
61
66
These are implementation responsibilities. The [documentation ownership map](docs/README.md)
62
67
identifies the single maintained guide for each responsibility.
63
68
69
+
The `tnfr.physics` public namespace resolves its exports on first access.
70
+
One ordered owner map supplies `__all__`, discovery through `dir()` and lazy
71
+
dispatch; resolved names are the actual owner objects, not proxies. Importing
72
+
one field or observer therefore does not eagerly load unrelated research and
73
+
runtime certificates. Direct module imports retain their own dependencies.
74
+
The [facade controls](tests/physics/test_physics_facade_imports.py) check cold
75
+
imports, public object identity and discovery independently of timing.
76
+
The generated [typing facade](src/tnfr/physics/__init__.pyi) re-exports those
77
+
same owners for static analyzers. Its
78
+
[generator](scripts/generate_physics_stub.py) reads the runtime map without
79
+
importing the package; the [testing guide](TESTING.md#code-quality-and-documentation-checks)
80
+
owns regeneration and drift checks.
81
+
82
+
Physics imports NumPy and NetworkX as core dependencies declared in
83
+
`pyproject.toml`. Optional SciPy and acceleration paths retain their own
84
+
availability checks and fallback behavior.
85
+
64
86
## Nodal execution flow
65
87
66
88
The ordinary runtime composes the following configured operations. The diagram
@@ -203,7 +225,8 @@ lost in that conversion.
203
225
|[`physics/source_relative_form.py`](src/tnfr/physics/source_relative_form.py)| Composes the form observer with an independently supplied held rate source; `Network.source_relative_form` is the adapter. |
204
226
|[`physics/relational_observations.py`](src/tnfr/physics/relational_observations.py)| Native field, region and hypothetical support-change reports; separately, graph-independent coefficient/rate/sample-jet bounds. Sample adapters share stencils and outward error propagation. |
205
227
|[`mathematics/linear_observation.py`](src/tnfr/mathematics/linear_observation.py)| Exact row-space realization and visible/hidden memory for a supplied rational generator; scoped lower bounds distinguish conservative observation from a supplied form-loss model. `physics/epi_memory.py` retains its own diffusion admission. |
|[`mathematics/_exact_linear_algebra.py`](src/tnfr/mathematics/_exact_linear_algebra.py)| Shared exact products, powers, inverses and semidefinite tests; compatibility physics imports, fixed-map network-stage powers and p-adic tower products delegate here. The tower adapter retains its mutable list rows. Products skip exact zero factors while retaining full rational output shapes and the consumers' product-call accounting. |
229
+
|[`mathematics/krylov.py`](src/tnfr/mathematics/krylov.py)| Exact rational rank, Krylov reachability and Hankel moment calculations under their declared input/output premises. |
207
230
|[`mathematics/_phase_resultant_chamber.py`](src/tnfr/mathematics/_phase_resultant_chamber.py)| Rational trigonometric/resultant bounds, principal-argument charts and supplied-rate kinematics. Reused geometry does not transfer a law. |
208
231
|[`mathematics/_validated_taylor.py`](src/tnfr/mathematics/_validated_taylor.py)| Strict Picard tubes, Taylor remainders and initial-box propagation; the comparison kernel owns the shared 1–24-coordinate work limit. Each flow adapter retains its layout and other admission budgets. |
209
232
|[`mathematics/_validated_metric.py`](src/tnfr/mathematics/_validated_metric.py)| Reuses Picard/Taylor machinery while retaining an SPD-metric radius between steps. The caller proves its whole-tube logarithmic bound; local truncation/rounding errors enter the same norm. Coordinate projections do not replace the retained uncertainty. |
@@ -239,11 +262,34 @@ The sine layer shares four boundaries:
239
262
work and resultant kinematics. Mobility and regional/mediated readers reuse
240
263
these primitives while retaining their own complete-law identifiers.
241
264
3.`_sine_preparation.py` supplies weighted preparation and uncertainty bounds.
265
+
Its report reader re-admits original source primitives before the shared
266
+
row calculation. Fixed-source consumers can use that calculation after
267
+
admitting their law, support, capacities and exact rows, without constructing
268
+
an observation report whose derived rates they do not consume.
242
269
Forecasts share validated Taylor/metric kernels and retain environmental
243
270
coordinates, hidden initialization and original error associations.
244
271
4.`sdk/relational_reports.py` delegates reports and projects exact JSON values;
245
272
it neither installs a solver nor authenticates an evaluated response.
246
273
274
+
`relational_sine_pair.py` owns exact global pair state, cancellation
275
+
observations and finite exchange/receiver certificates. It depends directly on
276
+
shared scalar, phasor and rational-interval admission. The larger
277
+
`relational_sine_scale.py` retains replica geometry, grouping and emission.
278
+
`relational_sine_replica_pulse.py` owns prepared internal pulses, their
279
+
variations, splitting and work-response assessments, including the validated
280
+
Taylor solver dependency. The scale module re-exports the established pair
281
+
and pulse APIs for compatibility. Their defining classes/functions live in
282
+
the corresponding owners; old imports resolve to those same objects,
283
+
including SDK dispatch and older pickle class lookups. These boundaries
284
+
change neither the complete laws nor the report schemas.
285
+
286
+
`relational_sine_formation_response.py` combines the shared preparation kernel
287
+
with exact Poisson and interval bounds for its fixed positive-loss sources.
288
+
One fresh domain admission serves both source rows in a call; all public
289
+
budgets are admitted anew. It keeps its own complete-law and clock premises,
290
+
independent of the conservative pair certificates. No prepared-state or
291
+
verdict cache substitutes for source admission.
292
+
247
293
Downstream calculations re-admit the producer's primitive source and rebuild
248
294
consumed gradients, rates, work and bounds. Forecast readers also check the
249
295
source association at the actual validated time. The
@@ -321,7 +367,14 @@ or second transport law is introduced.
321
367
classifications.
322
368
-`tnfr.errors` provides contextual public exceptions.
323
369
-`tnfr.mathematics` owns numerical backends and domain-neutral mathematical
324
-
structures.
370
+
structures. Its private `_complex_arrays` reader shares original-component
371
+
admission and range-safe normalization across spectral consumers.
372
+
`_integer_admission` owns exact integer/index admission for arithmetic
373
+
modules; primality dispatch and optional SymPy selection remain with
374
+
`number_theory`.
375
+
-`tnfr.math.symbolic` owns supplied-law symbolic calculus when SymPy is
376
+
installed. Its public helpers are re-exported by `tnfr.mathematics` and
377
+
`tnfr`; those import paths share the same implementations.
0 commit comments