tnfr 4.5.0__py3-none-any.whl → 4.5.2__py3-none-any.whl

tnfr/grammar.py

@@ -1,155 +1,344 @@
+"""Grammar rules."""
+
 from __future__ import annotations
-from typing import Dict, Any, Set
+from dataclasses import dataclass
+from typing import Any, Iterable, Optional, Callable
 
-from .constants import (
-    DEFAULTS,
-    ALIAS_SI, ALIAS_DNFR, ALIAS_EPI,
-)
-from .helpers import _get_attr, clamp01, reciente_glifo
-from collections import deque
+from .constants import DEFAULTS, get_aliases, get_param
+from .alias import get_attr
+from .helpers.numeric import clamp01
+from .glyph_history import recent_glyph
+from .types import Glyph
+from .operators import apply_glyph  # avoid repeated import inside functions
+from .metrics.common import normalize_dnfr
+
+ALIAS_SI = get_aliases("SI")
+ALIAS_D2EPI = get_aliases("D2EPI")
+
+
+@dataclass
+class GrammarContext:
+    """Shared context for grammar helpers.
+
+    Collects graph-level settings to reduce positional parameters across
+    helper functions.
+    """
+
+    G: Any
+    cfg_soft: dict[str, Any]
+    cfg_canon: dict[str, Any]
+    norms: dict[str, Any]
 
-# Glifos nominales (para evitar typos)
-AL = "A’L"; EN = "E’N"; IL = "I’L"; OZ = "O’Z"; UM = "U’M"; RA = "R’A"; SHA = "SH’A"; VAL = "VA’L"; NUL = "NU’L"; THOL = "T’HOL"; ZHIR = "Z’HIR"; NAV = "NA’V"; REMESH = "RE’MESH"
+    @classmethod
+    def from_graph(cls, G: Any) -> "GrammarContext":
+        """Create a :class:`GrammarContext` for ``G``."""
+        return cls(
+            G=G,
+            cfg_soft=G.graph.get("GRAMMAR", DEFAULTS.get("GRAMMAR", {})),
+            cfg_canon=G.graph.get(
+                "GRAMMAR_CANON", DEFAULTS.get("GRAMMAR_CANON", {})
+            ),
+            norms=G.graph.get("_sel_norms") or {},
+        )
+
+
+__all__ = (
+    "CANON_COMPAT",
+    "CANON_FALLBACK",
+    "enforce_canonical_grammar",
+    "on_applied_glyph",
+    "apply_glyph_with_grammar",
+    "GrammarContext",
+)
 
 # -------------------------
-# Estado de gramática por nodo
+# Per-node grammar state
 # -------------------------
 
-def _gram_state(nd: Dict[str, Any]) -> Dict[str, Any]:
-    """Crea/retorna el estado de gramática nodal.
-    Campos:
+
+def _gram_state(nd: dict[str, Any]) -> dict[str, Any]:
+    """Create or return the node grammar state.
+
+    Fields:
       - thol_open (bool)
       - thol_len (int)
     """
-    st = nd.setdefault("_GRAM", {"thol_open": False, "thol_len": 0})
-    st.setdefault("thol_open", False)
-    st.setdefault("thol_len", 0)
-    return st
+    return nd.setdefault("_GRAM", {"thol_open": False, "thol_len": 0})
+
 
 # -------------------------
-# Compatibilidades canónicas (siguiente permitido)
+# Canonical compatibilities (allowed next glyphs)
 # -------------------------
-CANON_COMPAT: Dict[str, Set[str]] = {
+CANON_COMPAT: dict[Glyph, set[Glyph]] = {
     # Inicio / apertura
-    AL:   {EN, RA, NAV, VAL, UM},
-    EN:   {IL, UM, RA, NAV},
+    Glyph.AL: {Glyph.EN, Glyph.RA, Glyph.NAV, Glyph.VAL, Glyph.UM},
+    Glyph.EN: {Glyph.IL, Glyph.UM, Glyph.RA, Glyph.NAV},
     # Estabilización / difusión / acople
-    IL:   {RA, VAL, UM, SHA},
-    UM:   {RA, IL, VAL, NAV},
-    RA:   {IL, VAL, UM, NAV},
-    VAL:  {UM, RA, IL, NAV},
+    Glyph.IL: {Glyph.RA, Glyph.VAL, Glyph.UM, Glyph.SHA},
+    Glyph.UM: {Glyph.RA, Glyph.IL, Glyph.VAL, Glyph.NAV},
+    Glyph.RA: {Glyph.IL, Glyph.VAL, Glyph.UM, Glyph.NAV},
+    Glyph.VAL: {Glyph.UM, Glyph.RA, Glyph.IL, Glyph.NAV},
     # Disonancia → transición → mutación
-    OZ:   {ZHIR, NAV},
-    ZHIR: {IL, NAV},
-    NAV:  {OZ, ZHIR, RA, IL, UM},
+    Glyph.OZ: {Glyph.ZHIR, Glyph.NAV},
+    Glyph.ZHIR: {Glyph.IL, Glyph.NAV},
+    Glyph.NAV: {Glyph.OZ, Glyph.ZHIR, Glyph.RA, Glyph.IL, Glyph.UM},
     # Cierres / latencias
-    SHA:  {AL, EN},
-    NUL:  {AL, IL},
+    Glyph.SHA: {Glyph.AL, Glyph.EN},
+    Glyph.NUL: {Glyph.AL, Glyph.IL},
     # Bloques autoorganizativos
-    THOL: {OZ, ZHIR, NAV, RA, IL, UM, SHA, NUL},
+    Glyph.THOL: {
+        Glyph.OZ,
+        Glyph.ZHIR,
+        Glyph.NAV,
+        Glyph.RA,
+        Glyph.IL,
+        Glyph.UM,
+        Glyph.SHA,
+        Glyph.NUL,
+    },
 }
 
-# Fallbacks canónicos si una transición no está permitida
-CANON_FALLBACK: Dict[str, str] = {
-    AL: EN, EN: IL, IL: RA, UM: RA, RA: IL, VAL: RA, OZ: ZHIR, ZHIR: IL, NAV: RA, SHA: AL, NUL: AL, THOL: NAV,
+# Canonical fallbacks when a transition is not allowed
+CANON_FALLBACK: dict[Glyph, Glyph] = {
+    Glyph.AL: Glyph.EN,
+    Glyph.EN: Glyph.IL,
+    Glyph.IL: Glyph.RA,
+    Glyph.NAV: Glyph.RA,
+    Glyph.NUL: Glyph.AL,
+    Glyph.OZ: Glyph.ZHIR,
+    Glyph.RA: Glyph.IL,
+    Glyph.SHA: Glyph.AL,
+    Glyph.THOL: Glyph.NAV,
+    Glyph.UM: Glyph.RA,
+    Glyph.VAL: Glyph.RA,
+    Glyph.ZHIR: Glyph.IL,
 }
 
-# -------------------------
-# Cierres T’HOL y precondiciones Z’HIR
-# -------------------------
 
-def _dnfr_norm(G, nd) -> float:
-    # Normalizador robusto: usa historial de |ΔNFR| máx guardado por dynamics (si existe)
-    norms = G.graph.get("_sel_norms") or {}
-    dmax = float(norms.get("dnfr_max", 1.0)) or 1.0
-    return clamp01(abs(_get_attr(nd, ALIAS_DNFR, 0.0)) / dmax)
+def _coerce_glyph(val: Any) -> Glyph | Any:
+    """Return ``val`` as ``Glyph`` when possible."""
+    try:
+        return Glyph(val)
+    except (ValueError, TypeError):
+        return val
+
 
+def _glyph_fallback(cand_key: str, fallbacks: dict[str, Any]) -> Glyph | str:
+    """Determine fallback glyph for ``cand_key`` and return converted value."""
+    glyph_key = _coerce_glyph(cand_key)
+    canon_fb = (
+        CANON_FALLBACK.get(glyph_key, cand_key)
+        if isinstance(glyph_key, Glyph)
+        else cand_key
+    )
+    fb = fallbacks.get(cand_key, canon_fb)
+    return _coerce_glyph(fb)
 
-def _si(G, nd) -> float:
-    return clamp01(_get_attr(nd, ALIAS_SI, 0.5))
 
 # -------------------------
-# Núcleo: forzar gramática sobre un candidato
+# THOL closures and ZHIR preconditions
 # -------------------------
 
-def enforce_canonical_grammar(G, n, cand: str) -> str:
-    """Valida/ajusta el glifo candidato según la gramática canónica.
 
-    Reglas clave:
-      - Compatibilidades de transición glífica (recorrido TNFR).
-      - O’Z→Z’HIR: la mutación requiere disonancia reciente o |ΔNFR| alto.
-      - T’HOL[...]: obliga cierre con SH’A o NU’L cuando el campo se estabiliza
-        o se alcanza el largo del bloque; mantiene estado por nodo.
+def get_norm(ctx: GrammarContext, key: str) -> float:
+    """Retrieve a global normalisation value from ``ctx.norms``."""
+    return float(ctx.norms.get(key, 1.0)) or 1.0
 
-    Devuelve el glifo efectivo a aplicar.
-    """
-    nd = G.nodes[n]
-    st = _gram_state(nd)
-    cfg = G.graph.get("GRAMMAR_CANON", DEFAULTS.get("GRAMMAR_CANON", {}))
 
-    # 0) Si vienen glifos fuera del alfabeto, no tocamos
-    if cand not in CANON_COMPAT:
+def _norm_attr(ctx: GrammarContext, nd, attr_alias: str, norm_key: str) -> float:
+    """Normalise ``attr_alias`` using the global maximum ``norm_key``."""
+
+    max_val = get_norm(ctx, norm_key)
+    return clamp01(abs(get_attr(nd, attr_alias, 0.0)) / max_val)
+
+
+def _si(nd) -> float:
+    return clamp01(get_attr(nd, ALIAS_SI, 0.5))
+
+
+def _accel_norm(ctx: GrammarContext, nd) -> float:
+    """Normalise acceleration using the global maximum."""
+    return _norm_attr(ctx, nd, ALIAS_D2EPI, "accel_max")
+
+
+def _check_repeats(ctx: GrammarContext, n, cand: Glyph | str) -> Glyph | str:
+    """Avoid recent repetitions according to ``ctx.cfg_soft``."""
+    nd = ctx.G.nodes[n]
+    cfg = ctx.cfg_soft
+    gwin = int(cfg.get("window", 0))
+    avoid = set(cfg.get("avoid_repeats", []))
+    fallbacks = cfg.get("fallbacks", {})
+    cand_key = cand.value if isinstance(cand, Glyph) else str(cand)
+    if gwin > 0 and cand_key in avoid and recent_glyph(nd, cand_key, gwin):
+        return _glyph_fallback(cand_key, fallbacks)
+    return cand
+
+
+def _maybe_force(
+    ctx: GrammarContext,
+    n,
+    cand: Glyph | str,
+    original: Glyph | str,
+    accessor: Callable[[GrammarContext, dict[str, Any]], float],
+    key: str,
+) -> Glyph | str:
+    """Restore ``original`` if ``accessor`` exceeds ``key`` threshold."""
+    if cand == original:
         return cand
+    force_th = float(ctx.cfg_soft.get(key, 0.60))
+    if accessor(ctx, ctx.G.nodes[n]) >= force_th:
+        return original
+    return cand
 
-    # 1) Precondición O’Z→Z’HIR: mutación requiere disonancia reciente o campo fuerte
-    if cand == ZHIR:
+
+def _check_oz_to_zhir(ctx: GrammarContext, n, cand: Glyph | str) -> Glyph | str:
+    nd = ctx.G.nodes[n]
+    cand_glyph = _coerce_glyph(cand)
+    if cand_glyph == Glyph.ZHIR:
+        cfg = ctx.cfg_canon
         win = int(cfg.get("zhir_requires_oz_window", 3))
         dn_min = float(cfg.get("zhir_dnfr_min", 0.05))
-        if not reciente_glifo(nd, OZ, win) and _dnfr_norm(G, nd) < dn_min:
-            cand = OZ  # forzamos paso por O’Z
+        dnfr_max = get_norm(ctx, "dnfr_max")
+        if (
+            not recent_glyph(nd, Glyph.OZ, win)
+            and normalize_dnfr(nd, dnfr_max) < dn_min
+        ):
+            return Glyph.OZ
+    return cand
 
-    # 2) Si estamos dentro de T’HOL, control de cierre obligado
+
+def _check_thol_closure(
+    ctx: GrammarContext, n, cand: Glyph | str, st: dict[str, Any]
+) -> Glyph | str:
+    nd = ctx.G.nodes[n]
     if st.get("thol_open", False):
-        st["thol_len"] = int(st.get("thol_len", 0))
-        st["thol_len"] += 1
+        st["thol_len"] = int(st.get("thol_len", 0)) + 1
+        cfg = ctx.cfg_canon
         minlen = int(cfg.get("thol_min_len", 2))
         maxlen = int(cfg.get("thol_max_len", 6))
         close_dn = float(cfg.get("thol_close_dnfr", 0.15))
-        if st["thol_len"] >= maxlen or (st["thol_len"] >= minlen and _dnfr_norm(G, nd) <= close_dn):
-            cand = NUL if _si(G, nd) >= float(cfg.get("si_high", 0.66)) else SHA
-
-    # 3) Compatibilidades: si el anterior restringe el siguiente
-    prev = None
-    hist = nd.get("hist_glifos")
-    if hist:
-        try:
-            prev = list(hist)[-1]
-        except Exception:
-            prev = None
-    if prev in CANON_COMPAT and cand not in CANON_COMPAT[prev]:
-        cand = CANON_FALLBACK.get(prev, cand)
+        dnfr_max = get_norm(ctx, "dnfr_max")
+        if st["thol_len"] >= maxlen or (
+            st["thol_len"] >= minlen
+            and normalize_dnfr(nd, dnfr_max) <= close_dn
+        ):
+            return (
+                Glyph.NUL
+                if _si(nd) >= float(cfg.get("si_high", 0.66))
+                else Glyph.SHA
+            )
+    return cand
+
 
+def _check_compatibility(ctx: GrammarContext, n, cand: Glyph | str) -> Glyph | str:
+    nd = ctx.G.nodes[n]
+    hist = nd.get("glyph_history")
+    prev = hist[-1] if hist else None
+    prev_glyph = _coerce_glyph(prev)
+    cand_glyph = _coerce_glyph(cand)
+    if isinstance(prev_glyph, Glyph):
+        allowed = CANON_COMPAT.get(prev_glyph)
+        if allowed is None:
+            return cand
+        if isinstance(cand_glyph, Glyph):
+            if cand_glyph not in allowed:
+                return CANON_FALLBACK.get(prev_glyph, cand_glyph)
+        else:
+            return CANON_FALLBACK.get(prev_glyph, cand)
     return cand
 
+
+# -------------------------
+# Core: enforce grammar on a candidate
+# -------------------------
+
+
+def enforce_canonical_grammar(
+    G, n, cand: Glyph | str, ctx: Optional[GrammarContext] = None
+) -> Glyph | str:
+    """Validate and adjust a candidate glyph according to canonical grammar.
+
+    Key rules:
+      - Repeat window with forces based on |ΔNFR| and acceleration.
+      - Transition compatibilities (TNFR path).
+      - OZ→ZHIR: mutation requires recent dissonance or high |ΔNFR|.
+      - THOL[...]: forces closure with SHA or NUL when the field stabilises
+        or block length is reached; maintains per-node state.
+
+    Returns the effective glyph to apply.
+    """
+    if ctx is None:
+        ctx = GrammarContext.from_graph(G)
+
+    nd = ctx.G.nodes[n]
+    st = _gram_state(nd)
+
+    raw_cand = cand
+    cand = _coerce_glyph(cand)
+    input_was_str = isinstance(raw_cand, str)
+
+    # 0) If glyphs outside the alphabet arrive, leave untouched
+    if not isinstance(cand, Glyph) or cand not in CANON_COMPAT:
+        return raw_cand if input_was_str else cand
+
+    original = cand
+    cand = _check_repeats(ctx, n, cand)
+
+    dnfr_accessor = lambda ctx, nd: normalize_dnfr(nd, get_norm(ctx, "dnfr_max"))
+    cand = _maybe_force(ctx, n, cand, original, dnfr_accessor, "force_dnfr")
+    cand = _maybe_force(ctx, n, cand, original, _accel_norm, "force_accel")
+    cand = _check_oz_to_zhir(ctx, n, cand)
+    cand = _check_thol_closure(ctx, n, cand, st)
+    cand = _check_compatibility(ctx, n, cand)
+
+    coerced_final = _coerce_glyph(cand)
+    if input_was_str:
+        if isinstance(coerced_final, Glyph):
+            return coerced_final.value
+        return str(cand)
+    return coerced_final if isinstance(coerced_final, Glyph) else cand
+
+
 # -------------------------
-# Post-selección: actualizar estado de gramática
+# Post-selection: update grammar state
 # -------------------------
 
-def on_applied_glifo(G, n, applied: str) -> None:
+
+def on_applied_glyph(G, n, applied: str) -> None:
     nd = G.nodes[n]
     st = _gram_state(nd)
-    if applied == THOL:
+    if applied == Glyph.THOL:
         st["thol_open"] = True
         st["thol_len"] = 0
-    elif applied in (SHA, NUL):
+    elif applied in (Glyph.SHA, Glyph.NUL):
         st["thol_open"] = False
         st["thol_len"] = 0
-    else:
-        pass
+
 
 # -------------------------
-# Integración con dynamics.step: helper de selección+aplicación
+# Direct application with canonical grammar
 # -------------------------
 
-def select_and_apply_with_grammar(G, n, selector, window: int) -> None:
-    """Aplica gramática canónica sobre la propuesta del selector.
 
-    El selector puede incluir una gramática **suave** (pre–filtro) como
-    `parametric_glyph_selector`; la presente función garantiza que la
-    gramática canónica tenga precedencia final.
+def apply_glyph_with_grammar(
+    G,
+    nodes: Optional[Iterable[Any]],
+    glyph: Glyph | str,
+    window: Optional[int] = None,
+) -> None:
+    """Apply ``glyph`` to ``nodes`` enforcing the canonical grammar.
+
+    ``nodes`` may be a ``NodeView`` or any iterable. The iterable is consumed
+    directly to avoid unnecessary materialisation; callers must materialise if
+    they need indexing.
     """
-    from .operators import aplicar_glifo
-    cand = selector(G, n)
-    cand = enforce_canonical_grammar(G, n, cand)
-    aplicar_glifo(G, n, cand, window=window)
-    on_applied_glifo(G, n, cand)
+    if window is None:
+        window = get_param(G, "GLYPH_HYSTERESIS_WINDOW")
+
+    g_str = glyph.value if isinstance(glyph, Glyph) else str(glyph)
+    iter_nodes = G.nodes() if nodes is None else nodes
+    ctx = GrammarContext.from_graph(G)
+    for n in iter_nodes:
+        g_eff = enforce_canonical_grammar(G, n, g_str, ctx)
+        apply_glyph(G, n, g_eff, window=window)
+        on_applied_glyph(G, n, g_eff)

tnfr/graph_utils.py

@@ -0,0 +1,84 @@
+"""Utilities for graph-level bookkeeping.
+
+This module centralises helpers that operate on the metadata stored inside
+graph objects.  Besides flagging ΔNFR preparation caches it also exposes
+lightweight adapters to obtain the canonical ``graph`` mapping and to read
+validated configuration dictionaries.
+"""
+
+from __future__ import annotations
+
+import warnings
+from types import MappingProxyType
+from typing import Any, Mapping
+
+__all__ = (
+    "get_graph",
+    "get_graph_mapping",
+    "mark_dnfr_prep_dirty",
+    "supports_add_edge",
+)
+
+
+def get_graph(obj: Any) -> Any:
+    """Return ``obj.graph`` when present or ``obj`` otherwise."""
+    return getattr(obj, "graph", obj)
+
+
+def get_graph_mapping(
+    G: Any, key: str, warn_msg: str
+) -> Mapping[str, Any] | None:
+    """Return an immutable view of ``G``'s stored mapping for ``key``.
+
+    The helper normalises access to ``G.graph[key]`` by returning
+    ``None`` when the key is missing or holds a non-mapping value.  When a
+    mapping is found it is wrapped in :class:`types.MappingProxyType` to guard
+    against accidental mutation.  ``warn_msg`` is emitted via
+    :func:`warnings.warn` when the stored value is not a mapping.
+    """
+    graph = get_graph(G)
+    getter = getattr(graph, "get", None)
+    if getter is None:
+        return None
+
+    data = getter(key)
+    if data is None:
+        return None
+    if not isinstance(data, Mapping):
+        warnings.warn(warn_msg, UserWarning, stacklevel=2)
+        return None
+    return MappingProxyType(data)
+
+
+def mark_dnfr_prep_dirty(G: Any) -> None:
+    """Flag ΔNFR preparation data as stale.
+
+    Parameters
+    ----------
+    G : Any
+        Graph-like object whose ``graph`` attribute will receive the
+        ``"_dnfr_prep_dirty"`` flag.
+
+    Returns
+    -------
+    None
+        This function mutates ``G`` in place.
+    """
+    graph = get_graph(G)
+    graph["_dnfr_prep_dirty"] = True
+
+
+def supports_add_edge(graph: Any) -> bool:
+    """Return ``True`` if ``graph`` exposes an ``add_edge`` method.
+
+    Parameters
+    ----------
+    graph : Any
+        Object representing a graph.
+
+    Returns
+    -------
+    bool
+        ``True`` when ``graph`` implements ``add_edge``; ``False`` otherwise.
+    """
+    return hasattr(graph, "add_edge")

tnfr/helpers/__init__.py

@@ -0,0 +1,71 @@
+"""Curated high-level helpers exposed by :mod:`tnfr.helpers`.
+
+The module is intentionally small and surfaces utilities that are stable for
+external use, covering data preparation, glyph history management, and graph
+cache invalidation.
+"""
+
+from __future__ import annotations
+
+from ..cache import (
+    EdgeCacheManager,
+    cached_node_list,
+    cached_nodes_and_A,
+    edge_version_cache,
+    edge_version_update,
+    ensure_node_index_map,
+    ensure_node_offset_map,
+    increment_edge_version,
+    node_set_checksum,
+    stable_json,
+)
+from ..graph_utils import get_graph, get_graph_mapping, mark_dnfr_prep_dirty
+from .numeric import (
+    angle_diff,
+    clamp,
+    clamp01,
+    kahan_sum_nd,
+)
+
+
+def __getattr__(name: str):
+    if name in _GLYPH_HISTORY_EXPORTS:
+        from .. import glyph_history as _glyph_history
+
+        value = getattr(_glyph_history, name)
+        globals()[name] = value
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+__all__ = (
+    "EdgeCacheManager",
+    "angle_diff",
+    "cached_node_list",
+    "cached_nodes_and_A",
+    "clamp",
+    "clamp01",
+    "edge_version_cache",
+    "edge_version_update",
+    "ensure_node_index_map",
+    "ensure_node_offset_map",
+    "get_graph",
+    "get_graph_mapping",
+    "increment_edge_version",
+    "kahan_sum_nd",
+    "mark_dnfr_prep_dirty",
+    "node_set_checksum",
+    "stable_json",
+    "count_glyphs",
+    "ensure_history",
+    "last_glyph",
+    "push_glyph",
+    "recent_glyph",
+)
+
+_GLYPH_HISTORY_EXPORTS = (
+    "count_glyphs",
+    "ensure_history",
+    "last_glyph",
+    "push_glyph",
+    "recent_glyph",
+)

tnfr/helpers/numeric.py

@@ -0,0 +1,87 @@
+"""Numeric helper functions and compensated summation utilities."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+import math
+
+__all__ = (
+    "clamp",
+    "clamp01",
+    "within_range",
+    "similarity_abs",
+    "kahan_sum_nd",
+    "angle_diff",
+)
+
+
+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``.
+
+    The comparison uses absolute differences instead of :func:`math.isclose`.
+    """
+
+    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.
+
+    ``lo`` and ``hi`` delimit the original value range. When ``hi`` is not
+    greater than ``lo`` the function returns ``0.0`` to avoid division by
+    zero. The result is clamped to ``[0,1]``.
+    """
+
+    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]``.
+
+    It computes ``1`` minus the normalized absolute difference between
+    ``a`` and ``b``. Values are scaled using :func:`_norm01` so the result
+    falls within ``[0,1]``.
+    """
+
+    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.
+
+    Each component of the tuples in ``values`` is summed independently using the
+    Kahan–Babuška (Neumaier) algorithm to reduce floating point error.
+    """
+    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