README.md

TNFR Test Suite

This document describes the TNFR test suite. Only π (phase wrap) and ξ_C ∝ 1/√λ₂ are genuine structural scales; every other parameter is derived from the nodal dynamics or is a free operational parameter. Tests validate the nodal equation, structural fields, grammar U1-U6, and the 13 operators.

Test Organization

mathematical_purity/ - TIER 1: canonical-constants consistency (notational)
core_physics/ - TIER 2: Nodal equation, structural fields, and fundamental physics
grammar_operators/ - TIER 3: Unified grammar U1-U6 and 13 canonical operators
integration/ - TIER 4: End-to-end pure TNFR engine workflows
validation/ - TIER 5: Performance and regression with canonical constants
archive/pre_purification/ - Archived tests from before mathematical purity achievement

Backend selection

Pass --math-backend=<name> to pytest (or set TNFR_TEST_MATH_BACKEND) to exercise the suite under a specific numerical adapter. The flag sets TNFR_MATH_BACKEND before modules import and clears cached backend instances, ensuring that optional dependencies such as JAX or PyTorch are only used when explicitly requested.

bash

PYTHONPATH=src pytest tests/mathematics --math-backend=torch

When the requested backend is unavailable, pytest will skip the backend-specific tests while the remainder of the suite continues to run under NumPy.

Debugging and diagnostic tests

test_logging_module.py – verifies that the root logger is configured once and sets a default level.
test_logging_threadsafe.py – ensures thread-safe initialization of the logging system across concurrent calls.
test_warn_failure_emit.py – checks warning and logging behavior for failed module imports.
test_trace.py – confirms that trace utilities register callbacks and capture metadata.
test_diagnosis_state.py – validates mapping of coherence metrics into diagnostic states.

Tests that previously covered warning cache pruning and warn-once limits were removed to reduce maintenance overhead.

Performance regression tests

performance/ – covers the NumPy-accelerated ΔNFR pipeline, alias caches, and trigonometric metrics to guard against performance regressions. The tests are marked slow and are excluded by default via the addopts setting in pyproject.toml.
bash
```
pytest -m slow tests/performance
```
The suite requires NumPy for the vectorized branches; pytest will skip the affected checks automatically when the dependency is missing.

Benchmark helpers remain available behind the benchmarks marker. To run them explicitly use:

bash

pytest benchmarks --benchmark-only

This command complements the default --benchmark-skip flag defined in pyproject.toml.

README.md

TNFR Test Suite

Test Organization

mathematical_purity/ - TIER 1: canonical-constants consistency (notational)
core_physics/ - TIER 2: Nodal equation, structural fields, and fundamental physics
grammar_operators/ - TIER 3: Unified grammar U1-U6 and 13 canonical operators
integration/ - TIER 4: End-to-end pure TNFR engine workflows
validation/ - TIER 5: Performance and regression with canonical constants
archive/pre_purification/ - Archived tests from before mathematical purity achievement

Backend selection

bash

PYTHONPATH=src pytest tests/mathematics --math-backend=torch

When the requested backend is unavailable, pytest will skip the backend-specific tests while the remainder of the suite continues to run under NumPy.

Debugging and diagnostic tests

test_logging_module.py – verifies that the root logger is configured once and sets a default level.
test_logging_threadsafe.py – ensures thread-safe initialization of the logging system across concurrent calls.
test_warn_failure_emit.py – checks warning and logging behavior for failed module imports.
test_trace.py – confirms that trace utilities register callbacks and capture metadata.
test_diagnosis_state.py – validates mapping of coherence metrics into diagnostic states.

Tests that previously covered warning cache pruning and warn-once limits were removed to reduce maintenance overhead.

Performance regression tests

performance/ – covers the NumPy-accelerated ΔNFR pipeline, alias caches, and trigonometric metrics to guard against performance regressions. The tests are marked slow and are excluded by default via the addopts setting in pyproject.toml.
bash
```
pytest -m slow tests/performance
```
The suite requires NumPy for the vectorized branches; pytest will skip the affected checks automatically when the dependency is missing.

Benchmark helpers remain available behind the benchmarks marker. To run them explicitly use:

bash

pytest benchmarks --benchmark-only

This command complements the default --benchmark-skip flag defined in pyproject.toml.