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

tnfr/cli/execution.py

@@ -0,0 +1,288 @@
+from __future__ import annotations
+
+import argparse
+
+from pathlib import Path
+from typing import Any, Optional
+
+import networkx as nx  # type: ignore[import-untyped]
+
+from ..constants import METRIC_DEFAULTS
+from ..sense import register_sigma_callback
+from ..metrics import (
+    register_metrics_callbacks,
+    glyph_top,
+    export_metrics,
+    build_metrics_summary,
+)
+from ..metrics.core import _metrics_step
+from ..trace import register_trace
+from ..execution import CANONICAL_PRESET_NAME, play, seq
+from ..dynamics import (
+    run,
+    default_glyph_selector,
+    parametric_glyph_selector,
+    validate_canon,
+)
+from ..presets import get_preset
+from ..config import apply_config
+from ..io import read_structured_file, safe_write, StructuredFileError
+from ..glyph_history import ensure_history
+from ..ontosim import preparar_red
+from ..logging_utils import get_logger
+from ..types import Glyph
+from ..json_utils import json_dumps
+from ..flatten import parse_program_tokens
+
+from .arguments import _args_to_dict
+
+logger = get_logger(__name__)
+
+
+# CLI summaries should remain concise by default while allowing callers to
+# inspect the full glyphogram series when needed.
+DEFAULT_SUMMARY_SERIES_LIMIT = 10
+
+
+def _save_json(path: str, data: Any) -> None:
+    payload = json_dumps(data, ensure_ascii=False, indent=2, default=list)
+    safe_write(path, lambda f: f.write(payload))
+
+
+def _attach_callbacks(G: "nx.Graph") -> None:
+    register_sigma_callback(G)
+    register_metrics_callbacks(G)
+    register_trace(G)
+    _metrics_step(G, ctx=None)
+
+
+def _persist_history(G: "nx.Graph", args: argparse.Namespace) -> None:
+    if getattr(args, "save_history", None) or getattr(args, "export_history_base", None):
+        history = ensure_history(G)
+        if getattr(args, "save_history", None):
+            _save_json(args.save_history, history)
+        if getattr(args, "export_history_base", None):
+            export_metrics(G, args.export_history_base, fmt=args.export_format)
+
+
+def build_basic_graph(args: argparse.Namespace) -> "nx.Graph":
+    n = args.nodes
+    topology = getattr(args, "topology", "ring").lower()
+    seed = getattr(args, "seed", None)
+    if topology == "ring":
+        G = nx.cycle_graph(n)
+    elif topology == "complete":
+        G = nx.complete_graph(n)
+    elif topology == "erdos":
+        if getattr(args, "p", None) is not None:
+            prob = float(args.p)
+        else:
+            if n <= 0:
+                fallback = 0.0
+            else:
+                fallback = 3.0 / n
+            prob = min(max(fallback, 0.0), 1.0)
+        if not 0.0 <= prob <= 1.0:
+            raise ValueError(f"p must be between 0 and 1; received {prob}")
+        G = nx.gnp_random_graph(n, prob, seed=seed)
+    else:
+        raise ValueError(
+            f"Invalid topology '{topology}'. Accepted options are: ring, complete, erdos"
+        )
+    if seed is not None:
+        G.graph["RANDOM_SEED"] = int(seed)
+    return G
+
+
+def apply_cli_config(G: "nx.Graph", args: argparse.Namespace) -> None:
+    if args.config:
+        apply_config(G, Path(args.config))
+    arg_map = {
+        "dt": ("DT", float),
+        "integrator": ("INTEGRATOR_METHOD", str),
+        "remesh_mode": ("REMESH_MODE", str),
+        "glyph_hysteresis_window": ("GLYPH_HYSTERESIS_WINDOW", int),
+    }
+    for attr, (key, conv) in arg_map.items():
+        val = getattr(args, attr, None)
+        if val is not None:
+            G.graph[key] = conv(val)
+
+    gcanon = {
+        **METRIC_DEFAULTS["GRAMMAR_CANON"],
+        **_args_to_dict(args, prefix="grammar_"),
+    }
+    if getattr(args, "grammar_canon", None) is not None:
+        gcanon["enabled"] = bool(args.grammar_canon)
+    G.graph["GRAMMAR_CANON"] = gcanon
+
+    selector = getattr(args, "selector", None)
+    if selector is not None:
+        sel_map = {
+            "basic": default_glyph_selector,
+            "param": parametric_glyph_selector,
+        }
+        G.graph["glyph_selector"] = sel_map.get(
+            selector, default_glyph_selector
+        )
+
+    if hasattr(args, "gamma_type"):
+        G.graph["GAMMA"] = {
+            "type": args.gamma_type,
+            "beta": args.gamma_beta,
+            "R0": args.gamma_R0,
+        }
+
+
+def register_callbacks_and_observer(G: "nx.Graph") -> None:
+    _attach_callbacks(G)
+    validate_canon(G)
+
+
+def _build_graph_from_args(args: argparse.Namespace) -> "nx.Graph":
+    G = build_basic_graph(args)
+    apply_cli_config(G, args)
+    if getattr(args, "observer", False):
+        G.graph["ATTACH_STD_OBSERVER"] = True
+    preparar_red(G)
+    register_callbacks_and_observer(G)
+    return G
+
+
+def _load_sequence(path: Path) -> list[Any]:
+    try:
+        data = read_structured_file(path)
+    except (StructuredFileError, OSError) as exc:
+        if isinstance(exc, StructuredFileError):
+            message = str(exc)
+        else:
+            message = str(StructuredFileError(path, exc))
+        logger.error("%s", message)
+        raise SystemExit(1) from exc
+    return parse_program_tokens(data)
+
+
+def resolve_program(
+    args: argparse.Namespace, default: Optional[Any] = None
+) -> Optional[Any]:
+    if getattr(args, "preset", None):
+        try:
+            return get_preset(args.preset)
+        except KeyError as exc:
+            logger.error(
+                "Preset desconocido '%s'. Usa --sequence-file para cargar secuencias personalizadas",
+                args.preset,
+            )
+            raise SystemExit(1) from exc
+    if getattr(args, "sequence_file", None):
+        return _load_sequence(Path(args.sequence_file))
+    return default
+
+
+def run_program(
+    G: Optional["nx.Graph"], program: Optional[Any], args: argparse.Namespace
+) -> "nx.Graph":
+    if G is None:
+        G = _build_graph_from_args(args)
+
+    if program is None:
+        steps = getattr(args, "steps", 100)
+        steps = 100 if steps is None else int(steps)
+        if steps < 0:
+            steps = 0
+
+        run_kwargs: dict[str, Any] = {}
+        for attr in ("dt", "use_Si", "apply_glyphs"):
+            value = getattr(args, attr, None)
+            if value is not None:
+                run_kwargs[attr] = value
+
+        run(G, steps=steps, **run_kwargs)
+    else:
+        play(G, program)
+
+    _persist_history(G, args)
+    return G
+
+
+def _run_cli_program(
+    args: argparse.Namespace,
+    *,
+    default_program: Optional[Any] = None,
+    graph: Optional["nx.Graph"] = None,
+) -> tuple[int, Optional["nx.Graph"]]:
+    try:
+        program = resolve_program(args, default=default_program)
+    except SystemExit as exc:
+        code = exc.code if isinstance(exc.code, int) else 1
+        return code or 1, None
+
+    result_graph = run_program(graph, program, args)
+    return 0, result_graph
+
+
+def _log_run_summaries(G: "nx.Graph", args: argparse.Namespace) -> None:
+    cfg_coh = G.graph.get("COHERENCE", METRIC_DEFAULTS["COHERENCE"])
+    cfg_diag = G.graph.get("DIAGNOSIS", METRIC_DEFAULTS["DIAGNOSIS"])
+    hist = ensure_history(G)
+
+    if cfg_coh.get("enabled", True):
+        Wstats = hist.get(cfg_coh.get("stats_history_key", "W_stats"), [])
+        if Wstats:
+            logger.info("[COHERENCE] último paso: %s", Wstats[-1])
+
+    if cfg_diag.get("enabled", True):
+        last_diag = hist.get(cfg_diag.get("history_key", "nodal_diag"), [])
+        if last_diag:
+            sample = list(last_diag[-1].values())[:3]
+            logger.info("[DIAGNOSIS] ejemplo: %s", sample)
+
+    if args.summary:
+        summary_limit = getattr(args, "summary_limit", DEFAULT_SUMMARY_SERIES_LIMIT)
+        summary, has_latency_values = build_metrics_summary(
+            G, series_limit=summary_limit
+        )
+        logger.info("Tg global: %s", summary["Tg_global"])
+        logger.info("Top operadores por Tg: %s", glyph_top(G, k=5))
+        if has_latency_values:
+            logger.info("Latencia media: %s", summary["latency_mean"])
+
+
+def cmd_run(args: argparse.Namespace) -> int:
+    code, graph = _run_cli_program(args)
+    if code != 0:
+        return code
+
+    if graph is not None:
+        _log_run_summaries(graph, args)
+    return 0
+
+
+def cmd_sequence(args: argparse.Namespace) -> int:
+    if args.preset and args.sequence_file:
+        logger.error(
+            "No se puede usar --preset y --sequence-file al mismo tiempo"
+        )
+        return 1
+    code, _ = _run_cli_program(
+        args, default_program=get_preset(CANONICAL_PRESET_NAME)
+    )
+    return code
+
+
+def cmd_metrics(args: argparse.Namespace) -> int:
+    if getattr(args, "steps", None) is None:
+        # Default a longer run for metrics stability
+        args.steps = 200
+
+    code, graph = _run_cli_program(args)
+    if code != 0 or graph is None:
+        return code
+
+    summary_limit = getattr(args, "summary_limit", None)
+    out, _ = build_metrics_summary(graph, series_limit=summary_limit)
+    if args.save:
+        _save_json(args.save, out)
+    else:
+        logger.info("%s", json_dumps(out))
+    return 0

tnfr/cli/utils.py

@@ -0,0 +1,36 @@
+"""Utilities for CLI modules."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def spec(opt: str, /, **kwargs: Any) -> tuple[str, dict[str, Any]]:
+    """Create an argument specification pair.
+
+    Parameters
+    ----------
+    opt:
+        Option string to register, e.g. ``"--foo"``.
+    **kwargs:
+        Keyword arguments forwarded to
+        :meth:`argparse.ArgumentParser.add_argument`.
+
+    Returns
+    -------
+    tuple[str, dict[str, Any]]
+        A pair suitable for collecting into argument specification sequences.
+        If ``dest`` is not provided it is
+        derived from ``opt`` by stripping leading dashes and replacing dots and
+        hyphens with underscores. ``default`` defaults to ``None`` so missing
+        options can be filtered easily.
+    """
+
+    kwargs = dict(kwargs)
+    kwargs.setdefault(
+        "dest", opt.lstrip("-").replace("-", "_").replace(".", "_")
+    )
+    kwargs.setdefault("default", None)
+    return opt, kwargs
+
+

tnfr/collections_utils.py

@@ -0,0 +1,300 @@
+"""Utilities for working with generic collections and weight mappings."""
+
+from __future__ import annotations
+
+import logging
+from collections import deque
+from collections.abc import Collection, Iterable, Mapping, Sequence
+from itertools import islice
+from typing import Any, Callable, Iterator, TypeVar, cast
+
+from .logging_utils import get_logger
+from .logging_utils import warn_once as _warn_once_factory
+from .value_utils import convert_value
+from .helpers.numeric import kahan_sum_nd
+
+T = TypeVar("T")
+
+logger = get_logger(__name__)
+
+STRING_TYPES = (str, bytes, bytearray)
+
+NEGATIVE_WEIGHTS_MSG = "Negative weights detected: %s"
+
+_NEGATIVE_WARN_ONCE_MAXSIZE = 1024
+
+
+def negative_weights_warn_once(
+    *, maxsize: int = _NEGATIVE_WARN_ONCE_MAXSIZE
+) -> Callable[[Mapping[str, float]], None]:
+    """Return a ``WarnOnce`` callable for negative weight warnings.
+
+    The returned callable may be reused across multiple
+    :func:`normalize_weights` invocations to suppress duplicate warnings for
+    the same keys.
+    """
+
+    return _warn_once_factory(logger, NEGATIVE_WEIGHTS_MSG, maxsize=maxsize)
+
+
+def _log_negative_weights(negatives: Mapping[str, float]) -> None:
+    """Log negative weight warnings without deduplicating keys."""
+
+    logger.warning(NEGATIVE_WEIGHTS_MSG, negatives)
+
+
+def _resolve_negative_warn_handler(
+    warn_once: bool | Callable[[Mapping[str, float]], None]
+) -> Callable[[Mapping[str, float]], None]:
+    """Return a callable that logs negative weight warnings."""
+
+    if callable(warn_once):
+        return warn_once
+    if warn_once:
+        return negative_weights_warn_once()
+    return _log_negative_weights
+
+
+def is_non_string_sequence(obj: Any) -> bool:
+    """Return ``True`` if ``obj`` is an ``Iterable`` but not string-like or a mapping."""
+    return isinstance(obj, Iterable) and not isinstance(obj, (*STRING_TYPES, Mapping))
+
+
+def flatten_structure(
+    obj: Any,
+    *,
+    expand: Callable[[Any], Iterable[Any] | None] | None = None,
+) -> Iterator[Any]:
+    """Yield leaf items from ``obj``.
+
+    The order of yielded items follows the order of the input iterable when it
+    is defined. For unordered iterables like :class:`set` the resulting order is
+    arbitrary. Mappings are treated as atomic items and not expanded.
+
+    Parameters
+    ----------
+    obj:
+        Object that may contain nested iterables.
+    expand:
+        Optional callable returning a replacement iterable for ``item``. When
+        it returns ``None`` the ``item`` is processed normally.
+    """
+
+    stack = deque([obj])
+    seen: set[int] = set()
+    while stack:
+        item = stack.pop()
+        item_id = id(item)
+        if item_id in seen:
+            continue
+        if expand is not None:
+            replacement = expand(item)
+            if replacement is not None:
+                seen.add(item_id)
+                stack.extendleft(replacement)
+                continue
+        if is_non_string_sequence(item):
+            seen.add(item_id)
+            stack.extendleft(item)
+        else:
+            yield item
+
+
+__all__ = (
+    "MAX_MATERIALIZE_DEFAULT",
+    "normalize_materialize_limit",
+    "is_non_string_sequence",
+    "flatten_structure",
+    "STRING_TYPES",
+    "ensure_collection",
+    "normalize_weights",
+    "negative_weights_warn_once",
+    "normalize_counter",
+    "mix_groups",
+)
+
+MAX_MATERIALIZE_DEFAULT: int = 1000
+"""Default materialization limit used by :func:`ensure_collection`.
+
+This guard prevents accidentally consuming huge or infinite iterables when a
+limit is not explicitly provided. Pass ``max_materialize=None`` to disable the
+limit.
+"""
+
+
+def normalize_materialize_limit(max_materialize: int | None) -> int | None:
+    """Normalize and validate ``max_materialize`` returning a usable limit."""
+    if max_materialize is None:
+        return None
+    limit = int(max_materialize)
+    if limit < 0:
+        raise ValueError("'max_materialize' must be non-negative")
+    return limit
+
+
+def ensure_collection(
+    it: Iterable[T],
+    *,
+    max_materialize: int | None = MAX_MATERIALIZE_DEFAULT,
+    error_msg: str | None = None,
+) -> Collection[T]:
+    """Return ``it`` as a :class:`Collection`, materializing when needed.
+
+    Checks are executed in the following order:
+
+    1. Existing collections are returned directly. String-like inputs
+       (``str``, ``bytes`` and ``bytearray``) are wrapped as a single item
+       tuple.
+    2. The object must be an :class:`Iterable`; otherwise ``TypeError`` is
+       raised.
+    3. Remaining iterables are materialized up to ``max_materialize`` items.
+       ``None`` disables the limit. ``error_msg`` customizes the
+       :class:`ValueError` raised when the iterable yields more items than
+       allowed. The input is consumed at most once and no extra items beyond the
+       limit are stored in memory.
+    """
+
+    # Step 1: early-return for collections and raw strings/bytes
+    if isinstance(it, Collection):
+        if isinstance(it, STRING_TYPES):
+            return (cast(T, it),)
+        else:
+            return it
+
+    # Step 2: ensure the input is iterable
+    if not isinstance(it, Iterable):
+        raise TypeError(f"{it!r} is not iterable")
+
+    # Step 3: validate limit and materialize items once
+    limit = normalize_materialize_limit(max_materialize)
+    if limit is None:
+        return tuple(it)
+    if limit == 0:
+        return ()
+
+    items = tuple(islice(it, limit + 1))
+    if len(items) > limit:
+        examples = ", ".join(repr(x) for x in items[:3])
+        msg = error_msg or (
+            f"Iterable produced {len(items)} items, exceeds limit {limit}; first items: [{examples}]"
+        )
+        raise ValueError(msg)
+    return items
+
+
+def _convert_and_validate_weights(
+    dict_like: Mapping[str, Any],
+    keys: Iterable[str] | Sequence[str],
+    default: float,
+    *,
+    error_on_conversion: bool,
+    error_on_negative: bool,
+    warn_once: bool | Callable[[Mapping[str, float]], None],
+) -> tuple[dict[str, float], list[str], float]:
+    """Return converted weights, deduplicated keys and the accumulated total."""
+
+    keys_list = list(dict.fromkeys(keys))
+    default_float = float(default)
+
+    def convert(k: str) -> float:
+        ok, val = convert_value(
+            dict_like.get(k, default_float),
+            float,
+            strict=error_on_conversion,
+            key=k,
+            log_level=logging.WARNING,
+        )
+        return cast(float, val) if ok else default_float
+
+    weights = {k: convert(k) for k in keys_list}
+    negatives = {k: w for k, w in weights.items() if w < 0}
+    total = kahan_sum_nd(((w,) for w in weights.values()), dims=1)[0]
+
+    if negatives:
+        if error_on_negative:
+            raise ValueError(NEGATIVE_WEIGHTS_MSG % negatives)
+        warn_negative = _resolve_negative_warn_handler(warn_once)
+        warn_negative(negatives)
+        for key, weight in negatives.items():
+            weights[key] = 0.0
+            total -= weight
+
+    return weights, keys_list, total
+
+
+def normalize_weights(
+    dict_like: Mapping[str, Any],
+    keys: Iterable[str] | Sequence[str],
+    default: float = 0.0,
+    *,
+    error_on_negative: bool = False,
+    warn_once: bool | Callable[[Mapping[str, float]], None] = True,
+    error_on_conversion: bool = False,
+) -> dict[str, float]:
+    """Normalize ``keys`` in mapping ``dict_like`` so their sum is 1.
+
+    ``keys`` may be any iterable of strings and is materialized once while
+    collapsing repeated entries preserving their first occurrence.
+
+    Negative weights are handled according to ``error_on_negative``. When
+    ``True`` a :class:`ValueError` is raised. Otherwise negatives are logged,
+    replaced with ``0`` and the remaining weights are renormalized. If all
+    weights are non-positive a uniform distribution is returned.
+
+    Conversion errors are controlled separately by ``error_on_conversion``. When
+    ``True`` any :class:`TypeError` or :class:`ValueError` while converting a
+    value to ``float`` is propagated. Otherwise the error is logged and the
+    ``default`` value is used.
+
+    ``warn_once`` accepts either a boolean or a callable. ``False`` logs all
+    negative weights using :func:`logging.Logger.warning`. ``True`` (the
+    default) creates a fresh :class:`~tnfr.logging_utils.WarnOnce` instance for
+    the call, emitting a single warning containing all negative keys. To reuse
+    deduplication state across calls, pass a callable such as
+    :func:`negative_weights_warn_once`.
+    """
+    weights, keys_list, total = _convert_and_validate_weights(
+        dict_like,
+        keys,
+        default,
+        error_on_conversion=error_on_conversion,
+        error_on_negative=error_on_negative,
+        warn_once=warn_once,
+    )
+    if not keys_list:
+        return {}
+    if total <= 0:
+        uniform = 1.0 / len(keys_list)
+        return {k: uniform for k in keys_list}
+    return {k: w / total for k, w in weights.items()}
+
+
+def normalize_counter(
+    counts: Mapping[str, float | int],
+) -> tuple[dict[str, float], float]:
+    """Normalize a ``Counter`` returning proportions and total."""
+    total = kahan_sum_nd(((c,) for c in counts.values()), dims=1)[0]
+    if total <= 0:
+        return {}, 0
+    dist = {k: v / total for k, v in counts.items() if v}
+    return dist, total
+
+
+def mix_groups(
+    dist: Mapping[str, float],
+    groups: Mapping[str, Iterable[str]],
+    *,
+    prefix: str = "_",
+) -> dict[str, float]:
+    """Aggregate values of ``dist`` according to ``groups``."""
+    out: dict[str, float] = dict(dist)
+    out.update(
+        {
+            f"{prefix}{label}": kahan_sum_nd(
+                ((dist.get(k, 0.0),) for k in keys),
+                dims=1,
+            )[0]
+            for label, keys in groups.items()
+        }
+    )
+    return out

tnfr/config.py

@@ -1,41 +1,32 @@
-"""Carga e inyección de configuraciones externas.
-
-Permite definir parámetros en JSON o YAML y aplicarlos sobre ``G.graph``
-reutilizando :func:`tnfr.constants.inject_defaults`.
-"""
+"""Configuration utilities."""
 
 from __future__ import annotations
-from typing import Any, Dict
-import json
-
-try:  # pragma: no cover - dependencia opcional
-    import yaml  # type: ignore
-except Exception:  # pragma: no cover
-    yaml = None
+from typing import Any, TYPE_CHECKING
+from collections.abc import Mapping
+from pathlib import Path
+from .io import read_structured_file
 
 from .constants import inject_defaults
 
+if TYPE_CHECKING:  # pragma: no cover - only for type checkers
+    import networkx as nx  # type: ignore[import-untyped]
+
+__all__ = ("load_config", "apply_config")
+
 
-def load_config(path: str) -> Dict[str, Any]:
-    """Lee un archivo JSON/YAML y devuelve un ``dict`` con los parámetros."""
-    with open(path, "r", encoding="utf-8") as f:
-        text = f.read()
-    if path.endswith((".yaml", ".yml")):
-        if not yaml:  # pragma: no cover - fallo en entorno sin pyyaml
-            raise RuntimeError("pyyaml no está instalado")
-        data = yaml.safe_load(text)
-    else:
-        data = json.loads(text)
-    if not isinstance(data, dict):
-        raise ValueError("El archivo de configuración debe contener un objeto")
+def load_config(path: str | Path) -> Mapping[str, Any]:
+    """Read a JSON/YAML file and return a mapping with parameters."""
+    path_obj = path if isinstance(path, Path) else Path(path)
+    data = read_structured_file(path_obj)
+    if not isinstance(data, Mapping):
+        raise ValueError("Configuration file must contain an object")
     return data
 
 
-def apply_config(G, path: str) -> None:
-    """Inyecta parámetros desde ``path`` sobre ``G.graph``.
+def apply_config(G: nx.Graph, path: str | Path) -> None:
+    """Inject parameters from ``path`` into ``G.graph``.
 
-    Se reutiliza :func:`inject_defaults` para mantener la semántica de los
-    *defaults* canónicos.
+    Reuses :func:`inject_defaults` to keep canonical default semantics.
     """
     cfg = load_config(path)
     inject_defaults(G, cfg, override=True)