tnfr 3.0.3__py3-none-any.whl → 8.5.0__py3-none-any.whl

tnfr/utils/numeric.py

@@ -0,0 +1,114 @@
+"""Numeric helper functions and compensated summation utilities."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Iterable, Sequence
+from typing import Any
+
+__all__ = (
+    "clamp",
+    "clamp01",
+    "within_range",
+    "similarity_abs",
+    "kahan_sum_nd",
+    "angle_diff",
+    "angle_diff_array",
+)
+
+
+def clamp(x: float, a: float, b: float) -> float:
+    """Return ``x`` clamped to the ``[a, b]`` interval."""
+
+    return max(a, min(b, x))
+
+
+def clamp01(x: float) -> float:
+    """Clamp ``x`` to the ``[0,1]`` interval."""
+
+    return clamp(float(x), 0.0, 1.0)
+
+
+def within_range(val: float, lower: float, upper: float, tol: float = 1e-9) -> bool:
+    """Return ``True`` if ``val`` lies in ``[lower, upper]`` within ``tol``."""
+
+    v = float(val)
+    return lower <= v <= upper or abs(v - lower) <= tol or abs(v - upper) <= tol
+
+
+def _norm01(x: float, lo: float, hi: float) -> float:
+    """Normalize ``x`` to the unit interval given bounds."""
+
+    if hi <= lo:
+        return 0.0
+    return clamp01((float(x) - float(lo)) / (float(hi) - float(lo)))
+
+
+def similarity_abs(a: float, b: float, lo: float, hi: float) -> float:
+    """Return absolute similarity of ``a`` and ``b`` over ``[lo, hi]``."""
+
+    return 1.0 - _norm01(abs(float(a) - float(b)), 0.0, hi - lo)
+
+
+def kahan_sum_nd(values: Iterable[Sequence[float]], dims: int) -> tuple[float, ...]:
+    """Return compensated sums of ``values`` with ``dims`` components."""
+
+    if dims < 1:
+        raise ValueError("dims must be >= 1")
+    totals = [0.0] * dims
+    comps = [0.0] * dims
+    for vs in values:
+        for i in range(dims):
+            v = vs[i]
+            t = totals[i] + v
+            if abs(totals[i]) >= abs(v):
+                comps[i] += (totals[i] - t) + v
+            else:
+                comps[i] += (v - t) + totals[i]
+            totals[i] = t
+    return tuple(float(totals[i] + comps[i]) for i in range(dims))
+
+
+def angle_diff(a: float, b: float) -> float:
+    """Return the minimal difference between two angles in radians."""
+
+    return (float(a) - float(b) + math.pi) % math.tau - math.pi
+
+
+def angle_diff_array(
+    a: Sequence[float] | "np.ndarray",  # noqa: F821
+    b: Sequence[float] | "np.ndarray",  # noqa: F821
+    *,
+    np: Any,
+    out: "np.ndarray | None" = None,  # noqa: F821
+    where: "np.ndarray | None" = None,  # noqa: F821
+) -> "np.ndarray":  # noqa: F821
+    """Vectorised :func:`angle_diff` compatible with NumPy arrays."""
+
+    if np is None:
+        raise TypeError("angle_diff_array requires a NumPy module")
+
+    kwargs = {"where": where} if where is not None else {}
+    minuend = np.asarray(a, dtype=float)
+    subtrahend = np.asarray(b, dtype=float)
+    if out is None:
+        out = np.empty_like(minuend, dtype=float)
+        if where is not None:
+            out.fill(0.0)
+    else:
+        if getattr(out, "shape", None) != minuend.shape:
+            raise ValueError("out must match the broadcasted shape of inputs")
+
+    np.subtract(minuend, subtrahend, out=out, **kwargs)
+    np.add(out, math.pi, out=out, **kwargs)
+    if where is not None:
+        mask = np.asarray(where, dtype=bool)
+        if mask.shape != out.shape:
+            raise ValueError("where mask must match the broadcasted shape of inputs")
+        selected = out[mask]
+        if selected.size:
+            out[mask] = np.remainder(selected, math.tau)
+    else:
+        np.remainder(out, math.tau, out=out)
+    np.subtract(out, math.pi, out=out, **kwargs)
+    return out

tnfr/utils/numeric.pyi

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from typing import Any
+
+__all__: tuple[str, ...]
+
+def clamp(x: float, a: float, b: float) -> float: ...
+def clamp01(x: float) -> float: ...
+def within_range(val: float, lower: float, upper: float, tol: float = ...) -> bool: ...
+def similarity_abs(a: float, b: float, lo: float, hi: float) -> float: ...
+def kahan_sum_nd(values: Iterable[Sequence[float]], dims: int) -> tuple[float, ...]: ...
+def angle_diff(a: float, b: float) -> float: ...
+def angle_diff_array(
+    a: Sequence[float] | Any,
+    b: Sequence[float] | Any,
+    *,
+    np: Any,
+    out: Any | None = ...,
+    where: Any | None = ...,
+) -> Any: ...

tnfr/validation/__init__.py

@@ -0,0 +1,257 @@
+"""Unified validation interface consolidating grammar, graph and spectral checks.
+
+RECOMMENDED: Use TNFRValidator for unified validation pipeline
+==============================================================
+
+The TNFRValidator class provides a single entry point for all TNFR validation
+operations, consolidating input validation, graph validation, invariant checking,
+operator preconditions, and runtime validation into one coherent API.
+
+Example Usage::
+
+    from tnfr.validation import TNFRValidator
+
+    validator = TNFRValidator()
+
+    # Comprehensive validation in one call
+    result = validator.validate(
+        graph=G,
+        epi=0.5,
+        vf=1.0,
+        include_invariants=True,
+    )
+
+    if not result['passed']:
+        print(f"Validation failed: {result['errors']}")
+
+For detailed migration guide, see UNIFIED_VALIDATION_PIPELINE.md
+
+Legacy API
+==========
+
+This package also re-exports individual validation functions for backward
+compatibility, but these may be deprecated in future versions. New code should
+use TNFRValidator instead.
+"""
+
+from __future__ import annotations
+
+from ..compat.dataclass import dataclass
+from typing import Any, Generic, Mapping, Protocol, TypeVar, runtime_checkable
+
+SubjectT = TypeVar("SubjectT")
+
+
+@dataclass(slots=True)
+class ValidationOutcome(Generic[SubjectT]):
+    """Result emitted by all canonical TNFR validators."""
+
+    subject: SubjectT
+    """The validated subject in canonical form."""
+
+    passed: bool
+    """Whether the validation succeeded without invariant violations."""
+
+    summary: Mapping[str, Any]
+    """Structured diagnostics describing the performed checks."""
+
+    artifacts: Mapping[str, Any] | None = None
+    """Optional artefacts (e.g. clamped nodes, normalised vectors)."""
+
+
+@runtime_checkable
+class Validator(Protocol[SubjectT]):
+    """Contract implemented by runtime and spectral validators."""
+
+    def validate(
+        self, subject: SubjectT, /, **kwargs: Any
+    ) -> ValidationOutcome[SubjectT]:
+        """Validate ``subject`` returning a :class:`ValidationOutcome`."""
+
+    def report(self, outcome: "ValidationOutcome[SubjectT]") -> str:
+        """Produce a concise textual explanation for ``outcome``."""
+
+
+# NOTE: Compatibility module deprecated - grammar emerges from TNFR structural dynamics
+# Legacy exports kept for backward compatibility but will be removed in future versions
+try:
+    from .compatibility import (  # noqa: F401
+        CANON_COMPAT,
+        CANON_FALLBACK,
+        CompatibilityLevel,
+        GRADUATED_COMPATIBILITY,
+        get_compatibility_level,
+    )
+
+    _COMPAT_AVAILABLE = True
+except ImportError:
+    # Compatibility module removed - provide stubs for backward compatibility
+    _COMPAT_AVAILABLE = False
+    CANON_COMPAT = {}
+    CANON_FALLBACK = {}
+
+    class CompatibilityLevel:
+        EXCELLENT = "excellent"
+        GOOD = "good"
+        CAUTION = "caution"
+        AVOID = "avoid"
+
+    GRADUATED_COMPATIBILITY = {}
+
+    def get_compatibility_level(prev: str, next_op: str) -> str:
+        """Deprecated: Use frequency transition validation instead."""
+        import warnings
+
+        warnings.warn(
+            "get_compatibility_level is deprecated. "
+            "Grammar rules now emerge naturally from TNFR structural dynamics. "
+            "Use validate_frequency_transition from tnfr.operators.grammar instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return "good"
+
+
+from ..operators import grammar as _grammar
+from ..types import Glyph
+from .graph import GRAPH_VALIDATORS, run_validators  # noqa: F401
+from .window import validate_window  # noqa: F401
+from .runtime import (
+    GraphCanonicalValidator,
+    apply_canonical_clamps,
+    validate_canon,
+)  # noqa: F401
+from .rules import coerce_glyph, get_norm, glyph_fallback, normalized_dnfr  # noqa: F401
+from .soft_filters import (  # noqa: F401
+    acceleration_norm,
+    check_repeats,
+    maybe_force,
+    soft_grammar_filters,
+)
+from .input_validation import (  # noqa: F401
+    ValidationError,
+    validate_epi_value,
+    validate_vf_value,
+    validate_theta_value,
+    validate_dnfr_value,
+    validate_node_id,
+    validate_glyph,
+    validate_tnfr_graph,
+    validate_glyph_factors,
+    validate_operator_parameters,
+)
+from .invariants import (  # noqa: F401
+    InvariantSeverity,
+    InvariantViolation,
+    TNFRInvariant,
+    Invariant1_EPIOnlyThroughOperators,
+    Invariant2_VfInHzStr,
+    Invariant3_DNFRSemantics,
+    Invariant4_OperatorClosure,
+    Invariant5_ExplicitPhaseChecks,
+    Invariant6_NodeBirthCollapse,
+    Invariant7_OperationalFractality,
+    Invariant8_ControlledDeterminism,
+    Invariant9_StructuralMetrics,
+    Invariant10_DomainNeutrality,
+)
+from .validator import (  # noqa: F401
+    TNFRValidator,
+    TNFRValidationError,
+)
+from .sequence_validator import (  # noqa: F401
+    SequenceSemanticValidator,
+)
+from .config import (  # noqa: F401
+    ValidationConfig,
+    validation_config,
+    configure_validation,
+)
+
+_GRAMMAR_EXPORTS = tuple(getattr(_grammar, "__all__", ()))
+
+globals().update({name: getattr(_grammar, name) for name in _GRAMMAR_EXPORTS})
+
+_RUNTIME_EXPORTS = (
+    "ValidationOutcome",
+    "Validator",
+    "GraphCanonicalValidator",
+    "apply_canonical_clamps",
+    "validate_canon",
+    "GRAPH_VALIDATORS",
+    "run_validators",
+    "CANON_COMPAT",
+    "CANON_FALLBACK",
+    "validate_window",
+    "coerce_glyph",
+    "get_norm",
+    "glyph_fallback",
+    "normalized_dnfr",
+    "acceleration_norm",
+    "check_repeats",
+    "maybe_force",
+    "soft_grammar_filters",
+    "NFRValidator",
+    "ValidationError",
+    "validate_epi_value",
+    "validate_vf_value",
+    "validate_theta_value",
+    "validate_dnfr_value",
+    "validate_node_id",
+    "validate_glyph",
+    "validate_tnfr_graph",
+    "validate_glyph_factors",
+    "validate_operator_parameters",
+    "InvariantSeverity",
+    "InvariantViolation",
+    "TNFRInvariant",
+    "Invariant1_EPIOnlyThroughOperators",
+    "Invariant2_VfInHzStr",
+    "Invariant3_DNFRSemantics",
+    "Invariant4_OperatorClosure",
+    "Invariant5_ExplicitPhaseChecks",
+    "Invariant6_NodeBirthCollapse",
+    "Invariant7_OperationalFractality",
+    "Invariant8_ControlledDeterminism",
+    "Invariant9_StructuralMetrics",
+    "Invariant10_DomainNeutrality",
+    "TNFRValidator",
+    "TNFRValidationError",
+    "SequenceSemanticValidator",
+    "ValidationConfig",
+    "validation_config",
+    "configure_validation",
+)
+
+__all__ = _GRAMMAR_EXPORTS + _RUNTIME_EXPORTS
+
+_ENFORCE_CANONICAL_GRAMMAR = _grammar.enforce_canonical_grammar
+
+
+def enforce_canonical_grammar(
+    G: Any,
+    n: Any,
+    cand: Any,
+    ctx: Any | None = None,
+) -> Any:
+    """Proxy to the canonical grammar enforcement helper preserving Glyph outputs."""
+
+    result = _ENFORCE_CANONICAL_GRAMMAR(G, n, cand, ctx)
+    if isinstance(cand, Glyph) and not isinstance(result, Glyph):
+        translated = _grammar.function_name_to_glyph(result)
+        if translated is None and isinstance(result, str):
+            try:
+                translated = Glyph(result)
+            except (TypeError, ValueError):
+                translated = None
+        if translated is not None:
+            return translated
+    return result
+
+
+def __getattr__(name: str) -> Any:
+    if name == "NFRValidator":
+        from .spectral import NFRValidator as _NFRValidator
+
+        return _NFRValidator
+    raise AttributeError(name)

tnfr/validation/__init__.pyi

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Generic, Protocol, TypeVar
+
+from ..types import Glyph, TNFRGraph
+from .compatibility import (
+    CANON_COMPAT as CANON_COMPAT,
+    CANON_FALLBACK as CANON_FALLBACK,
+)
+from ..operators.grammar import (
+    GrammarContext,
+    MutationPreconditionError,
+    RepeatWindowError,
+    SequenceSyntaxError,
+    SequenceValidationResult,
+    StructuralGrammarError,
+    TholClosureError,
+    TransitionCompatibilityError,
+    apply_glyph_with_grammar,
+    enforce_canonical_grammar,
+    on_applied_glyph,
+    record_grammar_violation,
+    validate_sequence,
+)
+from .graph import GRAPH_VALIDATORS, run_validators
+from .window import validate_window
+from .rules import coerce_glyph, get_norm, glyph_fallback, normalized_dnfr
+from .soft_filters import (
+    acceleration_norm,
+    check_repeats,
+    maybe_force,
+    soft_grammar_filters,
+)
+from .runtime import GraphCanonicalValidator, apply_canonical_clamps, validate_canon
+from .spectral import NFRValidator
+
+SubjectT = TypeVar("SubjectT")
+
+class ValidationOutcome(Generic[SubjectT]):
+    subject: SubjectT
+    passed: bool
+    summary: Mapping[str, Any]
+    artifacts: Mapping[str, Any] | None
+
+class Validator(Protocol[SubjectT]):
+    def validate(
+        self, subject: SubjectT, /, **kwargs: Any
+    ) -> ValidationOutcome[SubjectT]: ...
+    def report(self, outcome: ValidationOutcome[SubjectT]) -> str: ...
+
+__all__ = (
+    "validate_sequence",
+    "GrammarContext",
+    "StructuralGrammarError",
+    "RepeatWindowError",
+    "MutationPreconditionError",
+    "TholClosureError",
+    "TransitionCompatibilityError",
+    "SequenceSyntaxError",
+    "SequenceValidationResult",
+    "apply_glyph_with_grammar",
+    "enforce_canonical_grammar",
+    "on_applied_glyph",
+    "record_grammar_violation",
+    "ValidationOutcome",
+    "Validator",
+    "GraphCanonicalValidator",
+    "apply_canonical_clamps",
+    "validate_canon",
+    "GRAPH_VALIDATORS",
+    "run_validators",
+    "CANON_COMPAT",
+    "CANON_FALLBACK",
+    "validate_window",
+    "coerce_glyph",
+    "get_norm",
+    "glyph_fallback",
+    "normalized_dnfr",
+    "acceleration_norm",
+    "check_repeats",
+    "maybe_force",
+    "soft_grammar_filters",
+    "NFRValidator",
+)