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

tnfr/config/defaults_core.py

@@ -0,0 +1,212 @@
+"""Core constants."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, field
+from types import MappingProxyType
+from typing import Any, Mapping
+
+from ..compat.dataclass import dataclass
+
+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 = 10.0
+    THETA_WRAP: bool = True
+    CLIP_MODE: str = "hard"
+    CLIP_SOFT_K: float = 3.0
+    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
+    HZ_STR_BRIDGE: float = 1.0
+    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,
+            "UM_vf_sync": 0.10,
+            "UM_dnfr_reduction": 0.15,
+            "RA_epi_diff": 0.15,
+            "RA_vf_amplification": 0.05,
+            "RA_phase_coupling": 0.10,  # Canonical phase alignment strengthening
+            "SHA_vf_factor": 0.85,
+            # Conservative scaling (1.05) prevents EPI overflow near boundaries
+            # while maintaining meaningful expansion capacity. Critical threshold:
+            # EPI × 1.05 = 1.0 when EPI ≈ 0.952 (vs previous threshold ≈ 0.870).
+            # This preserves structural identity at boundary (EPI_MAX as identity frontier).
+            "VAL_scale": 1.05,
+            "NUL_scale": 0.85,
+            # NUL canonical ΔNFR densification factor: implements structural pressure
+            # concentration due to volume reduction. When V' = V × 0.85, density increases
+            # by ~1.176× geometrically. Canonical value 1.35 accounts for nonlinear
+            # structural effects at smaller scales, per TNFR theory.
+            "NUL_densification_factor": 1.35,
+            "THOL_accel": 0.10,
+            # ZHIR now uses canonical transformation by default (θ → θ' based on ΔNFR)
+            # To use fixed shift, explicitly set ZHIR_theta_shift in graph
+            "ZHIR_theta_shift_factor": 0.3,  # Canonical transformation magnitude
+            "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
+    NODAL_EQUATION_CLIP_AWARE: bool = True
+    NODAL_EQUATION_TOLERANCE: float = 1e-9
+    # THOL (Self-organization) vibrational metabolism parameters
+    THOL_METABOLIC_ENABLED: bool = True
+    THOL_METABOLIC_GRADIENT_WEIGHT: float = 0.15
+    THOL_METABOLIC_COMPLEXITY_WEIGHT: float = 0.10
+    THOL_BIFURCATION_THRESHOLD: float = 0.1
+
+    # THOL network propagation and cascade parameters
+    THOL_PROPAGATION_ENABLED: bool = True
+    THOL_MIN_COUPLING_FOR_PROPAGATION: float = 0.5
+    THOL_PROPAGATION_ATTENUATION: float = 0.7
+    THOL_CASCADE_MIN_NODES: int = 3
+
+    # THOL precondition thresholds
+    THOL_MIN_EPI: float = 0.2  # Minimum EPI for bifurcation
+    THOL_MIN_VF: float = 0.1  # Minimum structural frequency for reorganization
+    THOL_MIN_DEGREE: int = 1  # Minimum network connectivity
+    THOL_MIN_HISTORY_LENGTH: int = 3  # Minimum EPI history for acceleration computation
+    THOL_ALLOW_ISOLATED: bool = False  # Require network context by default
+    THOL_MIN_COLLECTIVE_COHERENCE: float = 0.3  # Minimum collective coherence for sub-EPI ensemble
+
+    # VAL (Expansion) precondition thresholds
+    VAL_MAX_VF: float = 10.0  # Maximum structural frequency threshold
+    VAL_MIN_DNFR: float = 1e-6  # Minimum positive ΔNFR for coherent expansion (very low to minimize breaking changes)
+    VAL_MIN_EPI: float = 0.2  # Minimum EPI for coherent expansion base
+    VAL_CHECK_NETWORK_CAPACITY: bool = False  # Optional network capacity validation
+    VAL_MAX_NETWORK_SIZE: int = 1000  # Maximum network size if capacity checking enabled
+
+    # VAL (Expansion) metric thresholds (Issue #2724)
+    VAL_BIFURCATION_THRESHOLD: float = 0.3  # Threshold for |∂²EPI/∂t²| bifurcation detection
+    VAL_MIN_COHERENCE: float = 0.5  # Minimum local coherence for healthy expansion
+    VAL_FRACTAL_RATIO_MIN: float = 0.5  # Minimum vf_growth/epi_growth ratio for fractality
+    VAL_FRACTAL_RATIO_MAX: float = 2.0  # Maximum vf_growth/epi_growth ratio for fractality
+
+
+@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_WINDOW: 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/config/defaults_init.py

@@ -0,0 +1,33 @@
+"""Initialization constants."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import asdict
+
+from ..compat.dataclass import dataclass
+
+
+@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/config/defaults_metric.py

@@ -0,0 +1,104 @@
+"""Metric constants."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, field
+from types import MappingProxyType
+from typing import Any
+
+from ..compat.dataclass import dataclass
+
+
+@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 over the global vector (0=off)
+            "history_key": "sigma_global",
+            "per_node": False,
+        }
+    )
+    TRACE: dict[str, Any] = field(
+        default_factory=lambda: {
+            "enabled": True,
+            "verbosity": "debug",
+            "history_key": "trace_meta",
+        }
+    )
+    METRICS: dict[str, Any] = field(
+        default_factory=lambda: {
+            "enabled": True,
+            "save_by_node": True,
+            "normalize_series": False,
+            "n_jobs": 1,
+            "verbosity": "debug",
+        }
+    )
+    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,
+            "n_jobs": 1,
+            "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/config/feature_flags.py

@@ -0,0 +1,81 @@
+"""Math feature flag configuration helpers."""
+
+from __future__ import annotations
+
+import os
+from contextlib import contextmanager
+from dataclasses import dataclass, replace
+from typing import Iterator
+
+__all__ = ("MathFeatureFlags", "get_flags", "context_flags")
+
+
+@dataclass(frozen=True)
+class MathFeatureFlags:
+    """Toggle optional mathematical behaviours in the engine."""
+
+    enable_math_validation: bool = False
+    enable_math_dynamics: bool = False
+    log_performance: bool = False
+    math_backend: str = "numpy"
+
+
+_TRUE_VALUES = {"1", "true", "on", "yes", "y", "t"}
+_FALSE_VALUES = {"0", "false", "off", "no", "n", "f"}
+
+_BASE_FLAGS: MathFeatureFlags | None = None
+_FLAGS_STACK: list[MathFeatureFlags] = []
+
+
+def _parse_env_flag(name: str, default: bool) -> bool:
+    value = os.getenv(name)
+    if value is None:
+        return default
+    lowered = value.strip().lower()
+    if lowered in _TRUE_VALUES:
+        return True
+    if lowered in _FALSE_VALUES:
+        return False
+    return default
+
+
+def _load_base_flags() -> MathFeatureFlags:
+    global _BASE_FLAGS
+    if _BASE_FLAGS is None:
+        backend = os.getenv("TNFR_MATH_BACKEND")
+        backend_choice = backend.strip() if backend else "numpy"
+        _BASE_FLAGS = MathFeatureFlags(
+            enable_math_validation=_parse_env_flag(
+                "TNFR_ENABLE_MATH_VALIDATION", False
+            ),
+            enable_math_dynamics=_parse_env_flag("TNFR_ENABLE_MATH_DYNAMICS", False),
+            log_performance=_parse_env_flag("TNFR_LOG_PERF", False),
+            math_backend=backend_choice or "numpy",
+        )
+    return _BASE_FLAGS
+
+
+def get_flags() -> MathFeatureFlags:
+    """Return the currently active feature flags."""
+
+    if _FLAGS_STACK:
+        return _FLAGS_STACK[-1]
+    return _load_base_flags()
+
+
+@contextmanager
+def context_flags(**overrides: bool) -> Iterator[MathFeatureFlags]:
+    """Temporarily override math feature flags."""
+
+    invalid = set(overrides) - set(MathFeatureFlags.__annotations__)
+    if invalid:
+        invalid_names = ", ".join(sorted(invalid))
+        raise TypeError(f"Unknown flag overrides: {invalid_names}")
+
+    previous = get_flags()
+    next_flags = replace(previous, **overrides)
+    _FLAGS_STACK.append(next_flags)
+    try:
+        yield next_flags
+    finally:
+        _FLAGS_STACK.pop()

tnfr/config/feature_flags.pyi

@@ -0,0 +1,16 @@
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Iterator
+
+__all__ = ["MathFeatureFlags", "get_flags", "context_flags"]
+
+@dataclass(frozen=True)
+class MathFeatureFlags:
+    enable_math_validation: bool = ...
+    enable_math_dynamics: bool = ...
+    log_performance: bool = ...
+    math_backend: str = ...
+
+def get_flags() -> MathFeatureFlags: ...
+@contextmanager
+def context_flags(**overrides: bool) -> Iterator[MathFeatureFlags]: ...

tnfr/config/glyph_constants.py

@@ -0,0 +1,31 @@
+"""Shared alias constants for TNFR attributes."""
+
+from __future__ import annotations
+
+from . import get_aliases
+
+ALIAS_VF = get_aliases("VF")
+ALIAS_THETA = get_aliases("THETA")
+ALIAS_DNFR = get_aliases("DNFR")
+ALIAS_EPI = get_aliases("EPI")
+ALIAS_EPI_KIND = get_aliases("EPI_KIND")
+ALIAS_SI = get_aliases("SI")
+ALIAS_DEPI = get_aliases("DEPI")
+ALIAS_D2EPI = get_aliases("D2EPI")
+ALIAS_DVF = get_aliases("DVF")
+ALIAS_D2VF = get_aliases("D2VF")
+ALIAS_DSI = get_aliases("DSI")
+
+__all__ = [
+    "ALIAS_VF",
+    "ALIAS_THETA",
+    "ALIAS_DNFR",
+    "ALIAS_EPI",
+    "ALIAS_EPI_KIND",
+    "ALIAS_SI",
+    "ALIAS_DEPI",
+    "ALIAS_D2EPI",
+    "ALIAS_DVF",
+    "ALIAS_D2VF",
+    "ALIAS_DSI",
+]

tnfr/config/init.py

@@ -0,0 +1,77 @@
+"""Core configuration helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from ..utils import read_structured_file
+
+if TYPE_CHECKING:  # pragma: no cover - only for type checkers
+    import networkx as nx
+
+__all__ = ("load_config", "apply_config")
+
+
+def load_config(
+    path: str | Path,
+    *,
+    base_dir: str | Path | None = None,
+) -> Mapping[str, Any]:
+    """Read a JSON/YAML file and return a mapping with parameters.
+
+    Parameters
+    ----------
+    path : str | Path
+        Path to the configuration file.
+    base_dir : str | Path | None, optional
+        Base directory to restrict config file access. If provided, the
+        resolved path must stay within this directory (prevents path traversal).
+
+    Returns
+    -------
+    Mapping[str, Any]
+        Configuration parameters as a mapping.
+
+    Raises
+    ------
+    ValueError
+        If the configuration file is invalid or contains unsafe patterns.
+    PathTraversalError
+        If path traversal is detected when base_dir is provided.
+    StructuredFileError
+        If the file cannot be read or parsed.
+    """
+    path_obj = path if isinstance(path, Path) else Path(path)
+    data = read_structured_file(path_obj, base_dir=base_dir)
+    if not isinstance(data, Mapping):
+        raise ValueError("Configuration file must contain an object")
+    return data
+
+
+def apply_config(
+    G: "nx.Graph",
+    path: str | Path,
+    *,
+    base_dir: str | Path | None = None,
+) -> None:
+    """Inject parameters from ``path`` into ``G.graph``.
+
+    Uses inject_defaults from this module to keep canonical default
+    semantics.
+
+    Parameters
+    ----------
+    G : nx.Graph
+        The graph to configure.
+    path : str | Path
+        Path to the configuration file.
+    base_dir : str | Path | None, optional
+        Base directory to restrict config file access.
+    """
+    # Import inject_defaults locally to avoid circular import
+    from . import inject_defaults
+
+    cfg = load_config(path, base_dir=base_dir)
+    inject_defaults(G, cfg, override=True)

tnfr/config/init.pyi

@@ -0,0 +1,8 @@
+from typing import Any
+
+__all__: Any
+
+def __getattr__(name: str) -> Any: ...
+
+apply_config: Any
+load_config: Any