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

tnfr/constants/__init__.py

@@ -0,0 +1,174 @@
+"""Shared constants."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+from collections.abc import Mapping
+import copy
+from types import MappingProxyType
+
+from .core import CORE_DEFAULTS, REMESH_DEFAULTS
+from .init import INIT_DEFAULTS
+from .metric import (
+    METRIC_DEFAULTS,
+    SIGMA,
+    TRACE,
+    METRICS,
+    GRAMMAR_CANON,
+    COHERENCE,
+    DIAGNOSIS,
+)
+
+from ..immutable import _is_immutable
+
+try:  # pragma: no cover - optional dependency
+    from ..cache import ensure_node_offset_map
+except ImportError:  # noqa: BLE001 - allow any import error
+    ensure_node_offset_map = None
+
+# Secciones individuales exportadas
+DEFAULT_SECTIONS: Mapping[str, Mapping[str, Any]] = MappingProxyType(
+    {
+        "core": CORE_DEFAULTS,
+        "init": INIT_DEFAULTS,
+        "remesh": REMESH_DEFAULTS,
+        "metric": METRIC_DEFAULTS,
+    }
+)
+
+# Diccionario combinado exportado
+# Unimos los diccionarios en orden de menor a mayor prioridad para que los
+# valores de ``METRIC_DEFAULTS`` sobrescriban al resto, como hacía
+# ``ChainMap``.
+DEFAULTS: Mapping[str, Any] = MappingProxyType(
+    CORE_DEFAULTS | INIT_DEFAULTS | REMESH_DEFAULTS | METRIC_DEFAULTS
+)
+
+# -------------------------
+# Utilidades
+# -------------------------
+
+
+def inject_defaults(
+    G, defaults: Mapping[str, Any] = DEFAULTS, override: bool = False
+) -> None:
+    """Inject ``defaults`` into ``G.graph``.
+
+    ``defaults`` is usually ``DEFAULTS``, combining all sub-dictionaries.
+    If ``override`` is ``True`` existing values are overwritten. Immutable
+    values (numbers, strings, tuples, etc.) are assigned directly. Tuples are
+    inspected recursively; if any element is mutable, a ``deepcopy`` is made
+    to avoid shared state.
+    """
+    G.graph.setdefault("_tnfr_defaults_attached", False)
+    for k, v in defaults.items():
+        if override or k not in G.graph:
+            G.graph[k] = v if _is_immutable(v) else copy.deepcopy(v)
+    G.graph["_tnfr_defaults_attached"] = True
+    if ensure_node_offset_map is not None:
+        ensure_node_offset_map(G)
+
+
+def merge_overrides(G, **overrides) -> None:
+    """Apply specific changes to ``G.graph``.
+
+    Non-immutable values are deep-copied to avoid shared state with
+    :data:`DEFAULTS`.
+    """
+    for key, value in overrides.items():
+        if key not in DEFAULTS:
+            raise KeyError(f"Parámetro desconocido: '{key}'")
+        G.graph[key] = value if _is_immutable(value) else copy.deepcopy(value)
+
+
+def get_param(G, key: str):
+    """Retrieve a parameter from ``G.graph`` or fall back to defaults."""
+    if key in G.graph:
+        return G.graph[key]
+    if key not in DEFAULTS:
+        raise KeyError(f"Parámetro desconocido: '{key}'")
+    return DEFAULTS[key]
+
+
+def get_graph_param(G, key: str, cast: Callable[[Any], Any] = float):
+    """Return ``key`` from ``G.graph`` applying ``cast``.
+
+    The ``cast`` argument must be a function (e.g. ``float``, ``int``,
+    ``bool``). If the stored value is ``None`` it is returned without
+    casting.
+    """
+    val = get_param(G, key)
+    return None if val is None else cast(val)
+
+
+# Claves canónicas con nombres ASCII
+VF_KEY = "νf"
+THETA_KEY = "θ"
+
+# Mapa de aliases para atributos nodales
+ALIASES: dict[str, tuple[str, ...]] = {
+    "VF": (VF_KEY, "nu_f", "nu-f", "nu", "freq", "frequency"),
+    "THETA": (THETA_KEY, "theta", "fase", "phi", "phase"),
+    "DNFR": ("ΔNFR", "delta_nfr", "dnfr"),
+    "EPI": ("EPI", "psi", "PSI", "value"),
+    "EPI_KIND": ("EPI_kind", "epi_kind", "source_glyph"),
+    "SI": ("Si", "sense_index", "S_i", "sense", "meaning_index"),
+    "DEPI": ("dEPI_dt", "dpsi_dt", "dEPI", "velocity"),
+    "D2EPI": ("d2EPI_dt2", "d2psi_dt2", "d2EPI", "accel"),
+    "DVF": ("dνf_dt", "dvf_dt", "dnu_dt", "dvf"),
+    "D2VF": ("d2νf_dt2", "d2vf_dt2", "d2nu_dt2", "B"),
+    "DSI": ("δSi", "delta_Si", "dSi"),
+}
+
+
+def get_aliases(key: str) -> tuple[str, ...]:
+    """Return alias tuple for canonical ``key``."""
+
+    return ALIASES[key]
+
+
+VF_PRIMARY = get_aliases("VF")[0]
+THETA_PRIMARY = get_aliases("THETA")[0]
+DNFR_PRIMARY = get_aliases("DNFR")[0]
+EPI_PRIMARY = get_aliases("EPI")[0]
+EPI_KIND_PRIMARY = get_aliases("EPI_KIND")[0]
+SI_PRIMARY = get_aliases("SI")[0]
+dEPI_PRIMARY = get_aliases("DEPI")[0]
+D2EPI_PRIMARY = get_aliases("D2EPI")[0]
+dVF_PRIMARY = get_aliases("DVF")[0]
+D2VF_PRIMARY = get_aliases("D2VF")[0]
+dSI_PRIMARY = get_aliases("DSI")[0]
+
+__all__ = (
+    "CORE_DEFAULTS",
+    "INIT_DEFAULTS",
+    "REMESH_DEFAULTS",
+    "METRIC_DEFAULTS",
+    "SIGMA",
+    "TRACE",
+    "METRICS",
+    "GRAMMAR_CANON",
+    "COHERENCE",
+    "DIAGNOSIS",
+    "DEFAULTS",
+    "DEFAULT_SECTIONS",
+    "ALIASES",
+    "inject_defaults",
+    "merge_overrides",
+    "get_param",
+    "get_graph_param",
+    "get_aliases",
+    "VF_KEY",
+    "THETA_KEY",
+    "VF_PRIMARY",
+    "THETA_PRIMARY",
+    "DNFR_PRIMARY",
+    "EPI_PRIMARY",
+    "EPI_KIND_PRIMARY",
+    "SI_PRIMARY",
+    "dEPI_PRIMARY",
+    "D2EPI_PRIMARY",
+    "dVF_PRIMARY",
+    "D2VF_PRIMARY",
+    "dSI_PRIMARY",
+)

tnfr/constants/core.py

@@ -0,0 +1,159 @@
+"""Core constants."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict, field
+from typing import Any, Mapping
+from types import MappingProxyType
+
+
+SELECTOR_THRESHOLD_DEFAULTS: Mapping[str, float] = MappingProxyType(
+    {
+        "si_hi": 0.66,
+        "si_lo": 0.33,
+        "dnfr_hi": 0.50,
+        "dnfr_lo": 0.10,
+        "accel_hi": 0.50,
+        "accel_lo": 0.10,
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class CoreDefaults:
+    """Default parameters for the core engine.
+
+    The fields are exported via :data:`CORE_DEFAULTS` and may therefore appear
+    unused to static analysis tools such as Vulture.
+    """
+
+    DT: float = 1.0
+    INTEGRATOR_METHOD: str = "euler"
+    DT_MIN: float = 0.1
+    EPI_MIN: float = -1.0
+    EPI_MAX: float = 1.0
+    VF_MIN: float = 0.0
+    VF_MAX: float = 1.0
+    THETA_WRAP: bool = True
+    DNFR_WEIGHTS: dict[str, float] = field(
+        default_factory=lambda: {
+            "phase": 0.34,
+            "epi": 0.33,
+            "vf": 0.33,
+            "topo": 0.0,
+        }
+    )
+    SI_WEIGHTS: dict[str, float] = field(
+        default_factory=lambda: {"alpha": 0.34, "beta": 0.33, "gamma": 0.33}
+    )
+    PHASE_K_GLOBAL: float = 0.05
+    PHASE_K_LOCAL: float = 0.15
+    PHASE_ADAPT: dict[str, Any] = field(
+        default_factory=lambda: {
+            "enabled": True,
+            "R_hi": 0.90,
+            "R_lo": 0.60,
+            "disr_hi": 0.50,
+            "disr_lo": 0.25,
+            "kG_min": 0.01,
+            "kG_max": 0.20,
+            "kL_min": 0.05,
+            "kL_max": 0.25,
+            "up": 0.10,
+            "down": 0.07,
+        }
+    )
+    UM_COMPAT_THRESHOLD: float = 0.75
+    UM_CANDIDATE_MODE: str = "sample"
+    UM_CANDIDATE_COUNT: int = 0
+    GLYPH_HYSTERESIS_WINDOW: int = 7
+    AL_MAX_LAG: int = 5
+    EN_MAX_LAG: int = 3
+    GLYPH_SELECTOR_MARGIN: float = 0.05
+    VF_ADAPT_TAU: int = 5
+    VF_ADAPT_MU: float = 0.1
+    GLYPH_FACTORS: dict[str, float] = field(
+        default_factory=lambda: {
+            "AL_boost": 0.05,
+            "EN_mix": 0.25,
+            "IL_dnfr_factor": 0.7,
+            "OZ_dnfr_factor": 1.3,
+            "UM_theta_push": 0.25,
+            "RA_epi_diff": 0.15,
+            "SHA_vf_factor": 0.85,
+            "VAL_scale": 1.15,
+            "NUL_scale": 0.85,
+            "THOL_accel": 0.10,
+            "ZHIR_theta_shift": 1.57079632679,
+            "NAV_jitter": 0.05,
+            "NAV_eta": 0.5,
+            "REMESH_alpha": 0.5,
+        }
+    )
+    GLYPH_THRESHOLDS: dict[str, float] = field(
+        default_factory=lambda: {"hi": 0.66, "lo": 0.33, "dnfr": 1e-3}
+    )
+    NAV_RANDOM: bool = True
+    NAV_STRICT: bool = False
+    RANDOM_SEED: int = 0
+    JITTER_CACHE_SIZE: int = 256
+    OZ_NOISE_MODE: bool = False
+    OZ_SIGMA: float = 0.1
+    GRAMMAR: dict[str, Any] = field(
+        default_factory=lambda: {
+            "window": 3,
+            "avoid_repeats": ["ZHIR", "OZ", "THOL"],
+            "force_dnfr": 0.60,
+            "force_accel": 0.60,
+            "fallbacks": {"ZHIR": "NAV", "OZ": "ZHIR", "THOL": "NAV"},
+        }
+    )
+    SELECTOR_WEIGHTS: dict[str, float] = field(
+        default_factory=lambda: {"w_si": 0.5, "w_dnfr": 0.3, "w_accel": 0.2}
+    )
+    SELECTOR_THRESHOLDS: dict[str, float] = field(
+        default_factory=lambda: dict(SELECTOR_THRESHOLD_DEFAULTS)
+    )
+    GAMMA: dict[str, Any] = field(
+        default_factory=lambda: {"type": "none", "beta": 0.0, "R0": 0.0}
+    )
+    CALLBACKS_STRICT: bool = False
+    VALIDATORS_STRICT: bool = False
+    PROGRAM_TRACE_MAXLEN: int = 50
+    HISTORY_MAXLEN: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class RemeshDefaults:
+    """Default parameters for the remeshing subsystem.
+
+    As with :class:`CoreDefaults`, the fields are exported via
+    :data:`REMESH_DEFAULTS` and may look unused to static analysers.
+    """
+
+    EPS_DNFR_STABLE: float = 1e-3
+    EPS_DEPI_STABLE: float = 1e-3
+    FRACTION_STABLE_REMESH: float = 0.80
+    REMESH_COOLDOWN_VENTANA: int = 20
+    REMESH_COOLDOWN_TS: float = 0.0
+    REMESH_REQUIRE_STABILITY: bool = True
+    REMESH_STABILITY_WINDOW: int = 25
+    REMESH_MIN_PHASE_SYNC: float = 0.85
+    REMESH_MAX_GLYPH_DISR: float = 0.35
+    REMESH_MIN_SIGMA_MAG: float = 0.50
+    REMESH_MIN_KURAMOTO_R: float = 0.80
+    REMESH_MIN_SI_HI_FRAC: float = 0.50
+    REMESH_LOG_EVENTS: bool = True
+    REMESH_MODE: str = "knn"
+    REMESH_COMMUNITY_K: int = 2
+    REMESH_TAU_GLOBAL: int = 8
+    REMESH_TAU_LOCAL: int = 4
+    REMESH_ALPHA: float = 0.5
+    REMESH_ALPHA_HARD: bool = False
+
+
+_core_defaults = asdict(CoreDefaults())
+_remesh_defaults = asdict(RemeshDefaults())
+
+CORE_DEFAULTS = MappingProxyType(_core_defaults)
+REMESH_DEFAULTS = MappingProxyType(_remesh_defaults)

tnfr/constants/init.py

@@ -0,0 +1,31 @@
+"""Initialization constants."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict
+import math
+
+
+@dataclass(frozen=True, slots=True)
+class InitDefaults:
+    """Default parameters for node initialisation.
+
+    The fields are collected into :data:`INIT_DEFAULTS` and may therefore
+    appear unused to tools like Vulture.
+    """
+
+    INIT_RANDOM_PHASE: bool = True
+    INIT_THETA_MIN: float = -math.pi
+    INIT_THETA_MAX: float = math.pi
+    INIT_VF_MODE: str = "uniform"
+    INIT_VF_MIN: float | None = None
+    INIT_VF_MAX: float | None = None
+    INIT_VF_MEAN: float = 0.5
+    INIT_VF_STD: float = 0.15
+    INIT_VF_CLAMP_TO_LIMITS: bool = True
+    INIT_SI_MIN: float = 0.4
+    INIT_SI_MAX: float = 0.7
+    INIT_EPI_VALUE: float = 0.0
+
+
+INIT_DEFAULTS = asdict(InitDefaults())

tnfr/constants/metric.py

@@ -0,0 +1,110 @@
+"""Metric constants."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict, field
+from typing import Any
+from types import MappingProxyType
+
+
+@dataclass(frozen=True, slots=True)
+class MetricDefaults:
+    """Default parameters for metric computation.
+
+    The fields are gathered into :data:`METRIC_DEFAULTS` and exposed through
+    read-only views below, so they may appear unused to static analysis tools.
+    """
+
+    PHASE_HISTORY_MAXLEN: int = 50
+    STOP_EARLY: dict[str, Any] = field(
+        default_factory=lambda: {
+            "enabled": False,
+            "window": 25,
+            "fraction": 0.90,
+        }
+    )
+    SIGMA: dict[str, Any] = field(
+        default_factory=lambda: {
+            "enabled": True,
+            "weight": "Si",  # "Si" | "EPI" | "1"
+            "smooth": 0.0,  # EMA sobre el vector global (0=off)
+            "history_key": "sigma_global",
+            "per_node": False,
+        }
+    )
+    TRACE: dict[str, Any] = field(
+        default_factory=lambda: {
+            "enabled": True,
+            "capture": [
+                "gamma",
+                "grammar",
+                "selector",
+                "dnfr_weights",
+                "si_weights",
+                "callbacks",
+                "thol_open_nodes",
+                "sigma",
+                "kuramoto",
+                "glyph_counts",
+            ],
+            "history_key": "trace_meta",
+        }
+    )
+    METRICS: dict[str, Any] = field(
+        default_factory=lambda: {
+            "enabled": True,
+            "save_by_node": True,
+            "normalize_series": False,
+        }
+    )
+    GRAMMAR_CANON: dict[str, Any] = field(
+        default_factory=lambda: {
+            "enabled": True,
+            "zhir_requires_oz_window": 3,
+            "zhir_dnfr_min": 0.05,
+            "thol_min_len": 2,
+            "thol_max_len": 6,
+            "thol_close_dnfr": 0.15,
+            "si_high": 0.66,
+        }
+    )
+    COHERENCE: dict[str, Any] = field(
+        default_factory=lambda: {
+            "enabled": True,
+            "scope": "neighbors",
+            "weights": {"phase": 0.34, "epi": 0.33, "vf": 0.20, "si": 0.13},
+            "self_on_diag": True,
+            "store_mode": "sparse",
+            "threshold": 0.0,
+            "history_key": "W_sparse",
+            "Wi_history_key": "W_i",
+            "stats_history_key": "W_stats",
+        }
+    )
+    DIAGNOSIS: dict[str, Any] = field(
+        default_factory=lambda: {
+            "enabled": True,
+            "window": 16,
+            "history_key": "nodal_diag",
+            "stable": {"Rloc_hi": 0.80, "dnfr_lo": 0.20, "persist": 3},
+            "dissonance": {"Rloc_lo": 0.40, "dnfr_hi": 0.50, "persist": 3},
+            "transition": {"persist": 2},
+            "compute_symmetry": True,
+            "include_typology": False,
+            "advice": {
+                "stable": ["Coherence", "Coupling", "Resonance"],
+                "transition": ["Transition", "Resonance", "Self-organisation"],
+                "dissonant": ["Silence", "Contraction", "Mutation"],
+            },
+        }
+    )
+
+
+METRIC_DEFAULTS = asdict(MetricDefaults())
+
+SIGMA = MappingProxyType(METRIC_DEFAULTS["SIGMA"])
+TRACE = MappingProxyType(METRIC_DEFAULTS["TRACE"])
+METRICS = MappingProxyType(METRIC_DEFAULTS["METRICS"])
+GRAMMAR_CANON = MappingProxyType(METRIC_DEFAULTS["GRAMMAR_CANON"])
+COHERENCE = MappingProxyType(METRIC_DEFAULTS["COHERENCE"])
+DIAGNOSIS = MappingProxyType(METRIC_DEFAULTS["DIAGNOSIS"])

tnfr/constants_glyphs.py

@@ -0,0 +1,98 @@
+"""Default glyphs."""
+
+from __future__ import annotations
+
+import math
+from types import MappingProxyType
+from typing import Mapping
+
+from .types import Glyph
+
+# -------------------------
+# Orden canónico y clasificaciones funcionales
+# -------------------------
+
+GLYPHS_CANONICAL: tuple[str, ...] = (
+    Glyph.AL.value,  # 0
+    Glyph.EN.value,  # 1
+    Glyph.IL.value,  # 2
+    Glyph.OZ.value,  # 3
+    Glyph.UM.value,  # 4
+    Glyph.RA.value,  # 5
+    Glyph.SHA.value,  # 6
+    Glyph.VAL.value,  # 7
+    Glyph.NUL.value,  # 8
+    Glyph.THOL.value,  # 9
+    Glyph.ZHIR.value,  # 10
+    Glyph.NAV.value,  # 11
+    Glyph.REMESH.value,  # 12
+)
+
+GLYPHS_CANONICAL_SET: frozenset[str] = frozenset(GLYPHS_CANONICAL)
+
+ESTABILIZADORES = (
+    Glyph.IL.value,
+    Glyph.RA.value,
+    Glyph.UM.value,
+    Glyph.SHA.value,
+)
+
+DISRUPTIVOS = (
+    Glyph.OZ.value,
+    Glyph.ZHIR.value,
+    Glyph.NAV.value,
+    Glyph.THOL.value,
+)
+
+# Mapa general de agrupaciones glíficas para referencia cruzada.
+GLYPH_GROUPS: Mapping[str, tuple[str, ...]] = MappingProxyType(
+    {
+        "estabilizadores": ESTABILIZADORES,
+        "disruptivos": DISRUPTIVOS,
+        # Grupos auxiliares para métricas morfosintácticas
+        "ID": (Glyph.OZ.value,),
+        "CM": (Glyph.ZHIR.value, Glyph.NAV.value),
+        "NE": (Glyph.IL.value, Glyph.THOL.value),
+        "PP_num": (Glyph.SHA.value,),
+        "PP_den": (Glyph.REMESH.value,),
+    }
+)
+
+# -------------------------
+# Mapa de ángulos glíficos
+# -------------------------
+
+# Ángulos canónicos para todos los glyphs reconocidos. Se calculan a partir
+# del orden canónico y reglas de orientación para las categorías
+# "estabilizadores" y "disruptivos".
+
+
+def _build_angle_map() -> dict[str, float]:
+    """Construir el mapa de ángulos en el plano σ."""
+    step = 2 * math.pi / len(GLYPHS_CANONICAL)
+    canonical = {g: i * step for i, g in enumerate(GLYPHS_CANONICAL)}
+    angles = dict(canonical)
+
+    # Reglas específicas de orientación
+    for idx, g in enumerate(ESTABILIZADORES):
+        angles[g] = idx * math.pi / 4
+    for idx, g in enumerate(DISRUPTIVOS):
+        angles[g] = math.pi + idx * math.pi / 4
+
+    # Excepciones manuales
+    angles[Glyph.VAL.value] = canonical[Glyph.RA.value]
+    angles[Glyph.NUL.value] = canonical[Glyph.ZHIR.value]
+    angles[Glyph.AL.value] = 0.0
+    return angles
+
+
+ANGLE_MAP: Mapping[str, float] = MappingProxyType(_build_angle_map())
+
+__all__ = (
+    "GLYPHS_CANONICAL",
+    "GLYPHS_CANONICAL_SET",
+    "ESTABILIZADORES",
+    "DISRUPTIVOS",
+    "GLYPH_GROUPS",
+    "ANGLE_MAP",
+)