tnfr 6.0.0__py3-none-any.whl → 7.0.0__py3-none-any.whl

tnfr/cli/execution.py

@@ -1,47 +1,69 @@
+"""CLI execution helpers for running canonical TNFR programs."""
+
 from __future__ import annotations
 
 import argparse
-
+from collections import deque
+from collections.abc import Mapping
 from copy import deepcopy
+from importlib import import_module
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any, Optional, Sequence
 
 import networkx as nx
+import numpy as np
 
-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
-from ..dynamics import (
-    run,
-    default_glyph_selector,
-    parametric_glyph_selector,
-    validate_canon,
-)
+from ..config import apply_config
 from ..config.presets import (
     PREFERRED_PRESET_NAMES,
     get_preset,
-    legacy_preset_guidance,
 )
-from ..config import apply_config
-from ..io import read_structured_file, safe_write, StructuredFileError
+from ..alias import get_attr
+from ..constants import METRIC_DEFAULTS, VF_PRIMARY, get_aliases, get_param
+from ..dynamics import default_glyph_selector, parametric_glyph_selector, run
+from ..execution import CANONICAL_PRESET_NAME, play
+from ..flatten import parse_program_tokens
 from ..glyph_history import ensure_history
+from ..mathematics import (
+    BasicStateProjector,
+    CoherenceOperator,
+    FrequencyOperator,
+    HilbertSpace,
+    MathematicalDynamicsEngine,
+    NFRValidator,
+    make_coherence_operator,
+    make_frequency_operator,
+)
+from ..metrics import (
+    build_metrics_summary,
+    export_metrics,
+    glyph_top,
+    register_metrics_callbacks,
+)
+from ..metrics.core import _metrics_step
 from ..ontosim import prepare_network
+from ..sense import register_sigma_callback
+from ..trace import register_trace
 from ..types import ProgramTokens
-from ..utils import get_logger, json_dumps
-from ..flatten import parse_program_tokens
-
+from ..utils import (
+    StructuredFileError,
+    clamp01,
+    get_logger,
+    json_dumps,
+    read_structured_file,
+    safe_write,
+)
 from .arguments import _args_to_dict
+from .utils import _parse_cli_variants
+from ..validation import validate_canon
 
 logger = get_logger(__name__)
 
+_VF_ALIASES = get_aliases("VF")
+VF_ALIAS_KEYS: tuple[str, ...] = (VF_PRIMARY,) + tuple(
+    alias for alias in _VF_ALIASES if alias != VF_PRIMARY
+)
+
 
 # CLI summaries should remain concise by default while allowing callers to
 # inspect the full glyphogram series when needed.
@@ -59,11 +81,17 @@ def _attach_callbacks(G: "nx.Graph") -> None:
     register_sigma_callback(G)
     register_metrics_callbacks(G)
     register_trace(G)
+    history = ensure_history(G)
+    maxlen = int(get_param(G, "PROGRAM_TRACE_MAXLEN"))
+    history.setdefault("program_trace", deque(maxlen=maxlen))
+    history.setdefault("trace_meta", [])
     _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):
+    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)
@@ -71,7 +99,155 @@ def _persist_history(G: "nx.Graph", args: argparse.Namespace) -> None:
             export_metrics(G, args.export_history_base, fmt=args.export_format)
 
 
+def _to_float_array(values: Sequence[float] | None, *, name: str) -> np.ndarray | None:
+    if values is None:
+        return None
+    array = np.asarray(list(values), dtype=float)
+    if array.ndim != 1:
+        raise ValueError(f"{name} must be a one-dimensional sequence of numbers")
+    return array
+
+
+def _resolve_math_dimension(
+    args: argparse.Namespace, fallback: int
+) -> int:
+    dimension = getattr(args, "math_dimension", None)
+    candidate_lengths: list[int] = []
+    for attr in (
+        "math_coherence_spectrum",
+        "math_frequency_diagonal",
+        "math_generator_diagonal",
+    ):
+        seq = getattr(args, attr, None)
+        if seq is not None:
+            candidate_lengths.append(len(seq))
+    if dimension is None:
+        if candidate_lengths:
+            unique = set(candidate_lengths)
+            if len(unique) > 1:
+                raise ValueError(
+                    "Math engine configuration requires matching sequence lengths"
+                )
+            dimension = unique.pop()
+        else:
+            dimension = fallback
+    else:
+        for length in candidate_lengths:
+            if length != dimension:
+                raise ValueError(
+                    "Math engine sequence lengths must match the requested dimension"
+                )
+    if dimension is None or dimension <= 0:
+        raise ValueError("Hilbert space dimension must be a positive integer")
+    return int(dimension)
+
+
+def _build_math_engine_config(
+    G: "nx.Graph", args: argparse.Namespace
+) -> dict[str, Any]:
+    node_count = G.number_of_nodes() if hasattr(G, "number_of_nodes") else len(list(G.nodes))
+    fallback_dim = max(1, int(node_count) if node_count is not None else 1)
+    dimension = _resolve_math_dimension(args, fallback=fallback_dim)
+
+    coherence_spectrum = _to_float_array(
+        getattr(args, "math_coherence_spectrum", None),
+        name="--math-coherence-spectrum",
+    )
+    if coherence_spectrum is not None and coherence_spectrum.size != dimension:
+        raise ValueError("Coherence spectrum length must equal the Hilbert dimension")
+
+    frequency_diagonal = _to_float_array(
+        getattr(args, "math_frequency_diagonal", None),
+        name="--math-frequency-diagonal",
+    )
+    if frequency_diagonal is not None and frequency_diagonal.size != dimension:
+        raise ValueError("Frequency diagonal length must equal the Hilbert dimension")
+
+    generator_diagonal = _to_float_array(
+        getattr(args, "math_generator_diagonal", None),
+        name="--math-generator-diagonal",
+    )
+    if generator_diagonal is not None and generator_diagonal.size != dimension:
+        raise ValueError("Generator diagonal length must equal the Hilbert dimension")
+
+    coherence_c_min = getattr(args, "math_coherence_c_min", None)
+    if coherence_spectrum is None:
+        coherence_operator = make_coherence_operator(
+            dimension,
+            c_min=float(coherence_c_min) if coherence_c_min is not None else 0.1,
+        )
+    else:
+        if coherence_c_min is not None:
+            coherence_operator = CoherenceOperator(
+                coherence_spectrum, c_min=float(coherence_c_min)
+            )
+        else:
+            coherence_operator = CoherenceOperator(coherence_spectrum)
+        if not coherence_operator.is_positive_semidefinite():
+            raise ValueError("Coherence spectrum must be positive semidefinite")
+
+    frequency_matrix: np.ndarray
+    if frequency_diagonal is None:
+        frequency_matrix = np.eye(dimension, dtype=float)
+    else:
+        frequency_matrix = np.diag(frequency_diagonal)
+    frequency_operator = make_frequency_operator(frequency_matrix)
+
+    generator_matrix: np.ndarray
+    if generator_diagonal is None:
+        generator_matrix = np.zeros((dimension, dimension), dtype=float)
+    else:
+        generator_matrix = np.diag(generator_diagonal)
+
+    hilbert_space = HilbertSpace(dimension)
+    dynamics_engine = MathematicalDynamicsEngine(
+        generator_matrix,
+        hilbert_space=hilbert_space,
+    )
+
+    coherence_threshold = getattr(args, "math_coherence_threshold", None)
+    if coherence_threshold is None:
+        coherence_threshold = float(coherence_operator.c_min)
+    else:
+        coherence_threshold = float(coherence_threshold)
+
+    state_projector = BasicStateProjector()
+    validator = NFRValidator(
+        hilbert_space,
+        coherence_operator,
+        coherence_threshold,
+        frequency_operator=frequency_operator,
+    )
+
+    return {
+        "enabled": True,
+        "dimension": dimension,
+        "hilbert_space": hilbert_space,
+        "coherence_operator": coherence_operator,
+        "frequency_operator": frequency_operator,
+        "coherence_threshold": coherence_threshold,
+        "state_projector": state_projector,
+        "validator": validator,
+        "dynamics_engine": dynamics_engine,
+        "generator_matrix": generator_matrix,
+    }
+
+
+def _configure_math_engine(G: "nx.Graph", args: argparse.Namespace) -> None:
+    if not getattr(args, "math_engine", False):
+        G.graph.pop("MATH_ENGINE", None)
+        return
+    try:
+        config = _build_math_engine_config(G, args)
+    except ValueError as exc:
+        logger.error("Math engine configuration error: %s", exc)
+        raise SystemExit(1) from exc
+    G.graph["MATH_ENGINE"] = config
+
+
 def build_basic_graph(args: argparse.Namespace) -> "nx.Graph":
+    """Construct the base graph topology described by CLI ``args``."""
+
     n = args.nodes
     topology = getattr(args, "topology", "ring").lower()
     seed = getattr(args, "seed", None)
@@ -87,7 +263,7 @@ def build_basic_graph(args: argparse.Namespace) -> "nx.Graph":
                 fallback = 0.0
             else:
                 fallback = 3.0 / n
-            prob = min(max(fallback, 0.0), 1.0)
+            prob = clamp01(fallback)
         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)
@@ -101,8 +277,14 @@ def build_basic_graph(args: argparse.Namespace) -> "nx.Graph":
 
 
 def apply_cli_config(G: "nx.Graph", args: argparse.Namespace) -> None:
+    """Apply CLI overrides from ``args`` to graph-level configuration."""
+
     if args.config:
-        apply_config(G, Path(args.config))
+        try:
+            apply_config(G, Path(args.config))
+        except (StructuredFileError, ValueError) as exc:
+            logger.error("%s", exc)
+            raise SystemExit(1) from exc
     arg_map = {
         "dt": ("DT", float),
         "integrator": ("INTEGRATOR_METHOD", str),
@@ -114,8 +296,18 @@ def apply_cli_config(G: "nx.Graph", args: argparse.Namespace) -> None:
         if val is not None:
             G.graph[key] = conv(val)
 
+    base_gcanon: dict[str, Any]
+    existing_gcanon = G.graph.get("GRAMMAR_CANON")
+    if isinstance(existing_gcanon, Mapping):
+        base_gcanon = {
+            **METRIC_DEFAULTS["GRAMMAR_CANON"],
+            **dict(existing_gcanon),
+        }
+    else:
+        base_gcanon = dict(METRIC_DEFAULTS["GRAMMAR_CANON"])
+
     gcanon = {
-        **METRIC_DEFAULTS["GRAMMAR_CANON"],
+        **base_gcanon,
         **_args_to_dict(args, prefix="grammar_"),
     }
     if getattr(args, "grammar_canon", None) is not None:
@@ -128,9 +320,7 @@ def apply_cli_config(G: "nx.Graph", args: argparse.Namespace) -> None:
             "basic": default_glyph_selector,
             "param": parametric_glyph_selector,
         }
-        G.graph["glyph_selector"] = sel_map.get(
-            selector, default_glyph_selector
-        )
+        G.graph["glyph_selector"] = sel_map.get(selector, default_glyph_selector)
 
     if hasattr(args, "gamma_type"):
         G.graph["GAMMA"] = {
@@ -151,8 +341,29 @@ def apply_cli_config(G: "nx.Graph", args: argparse.Namespace) -> None:
         if value is not None:
             cfg["verbosity"] = value
 
+    candidate_count = getattr(args, "um_candidate_count", None)
+    if candidate_count is not None:
+        G.graph["UM_CANDIDATE_COUNT"] = int(candidate_count)
+
+    stop_window = getattr(args, "stop_early_window", None)
+    stop_fraction = getattr(args, "stop_early_fraction", None)
+    if stop_window is not None or stop_fraction is not None:
+        stop_cfg = G.graph.get("STOP_EARLY")
+        if isinstance(stop_cfg, Mapping):
+            next_cfg = {**stop_cfg}
+        else:
+            next_cfg = deepcopy(METRIC_DEFAULTS["STOP_EARLY"])
+        if stop_window is not None:
+            next_cfg["window"] = int(stop_window)
+        if stop_fraction is not None:
+            next_cfg["fraction"] = float(stop_fraction)
+        next_cfg.setdefault("enabled", True)
+        G.graph["STOP_EARLY"] = next_cfg
+
 
 def register_callbacks_and_observer(G: "nx.Graph") -> None:
+    """Attach callbacks and validators required for CLI runs."""
+
     _attach_callbacks(G)
     validate_canon(G)
 
@@ -164,6 +375,7 @@ def _build_graph_from_args(args: argparse.Namespace) -> "nx.Graph":
         G.graph["ATTACH_STD_OBSERVER"] = True
     prepare_network(G)
     register_callbacks_and_observer(G)
+    _configure_math_engine(G, args)
     return G
 
 
@@ -177,25 +389,21 @@ def _load_sequence(path: Path) -> ProgramTokens:
             message = str(StructuredFileError(path, exc))
         logger.error("%s", message)
         raise SystemExit(1) from exc
+    if isinstance(data, Mapping) and "sequence" in data:
+        data = data["sequence"]
     return parse_program_tokens(data)
 
 
 def resolve_program(
     args: argparse.Namespace, default: Optional[ProgramTokens] = None
 ) -> Optional[ProgramTokens]:
+    """Resolve preset/sequence inputs into program tokens."""
+
     if getattr(args, "preset", None):
         try:
             return get_preset(args.preset)
         except KeyError as exc:
-            guidance = legacy_preset_guidance(args.preset)
-            if guidance is not None:
-                details = guidance
-            else:
-                details = (
-                    exc.args[0]
-                    if exc.args
-                    else "Legacy preset identifier rejected."
-                )
+            details = exc.args[0] if exc.args else "Preset lookup failed."
             logger.error(
                 (
                     "Unknown preset '%s'. Available presets: %s. %s "
@@ -216,6 +424,8 @@ def run_program(
     program: Optional[ProgramTokens],
     args: argparse.Namespace,
 ) -> "nx.Graph":
+    """Execute ``program`` (or timed run) on ``G`` using CLI options."""
+
     if G is None:
         G = _build_graph_from_args(args)
 
@@ -231,6 +441,13 @@ def run_program(
             if value is not None:
                 run_kwargs[attr] = value
 
+        job_overrides: dict[str, Any] = {}
+        dnfr_jobs = getattr(args, "dnfr_n_jobs", None)
+        if dnfr_jobs is not None:
+            job_overrides["dnfr_n_jobs"] = int(dnfr_jobs)
+        if job_overrides:
+            run_kwargs["n_jobs"] = job_overrides
+
         run(G, steps=steps, **run_kwargs)
     else:
         play(G, program)
@@ -251,10 +468,118 @@ def _run_cli_program(
         code = exc.code if isinstance(exc.code, int) else 1
         return code or 1, None
 
-    result_graph = run_program(graph, program, args)
+    try:
+        result_graph = run_program(graph, program, args)
+    except SystemExit as exc:
+        code = exc.code if isinstance(exc.code, int) else 1
+        return code or 1, None
     return 0, result_graph
 
 
+def _log_math_engine_summary(G: "nx.Graph") -> None:
+    math_cfg = G.graph.get("MATH_ENGINE")
+    if not isinstance(math_cfg, Mapping) or not math_cfg.get("enabled"):
+        return
+
+    nodes = list(G.nodes)
+    if not nodes:
+        logger.info("[MATH] Math engine validation skipped: no nodes present")
+        return
+
+    hilbert_space: HilbertSpace = math_cfg["hilbert_space"]
+    coherence_operator: CoherenceOperator = math_cfg["coherence_operator"]
+    frequency_operator: FrequencyOperator | None = math_cfg.get("frequency_operator")
+    state_projector: BasicStateProjector = math_cfg.get(
+        "state_projector", BasicStateProjector()
+    )
+    validator: NFRValidator | None = math_cfg.get("validator")
+    if validator is None:
+        coherence_threshold = math_cfg.get("coherence_threshold")
+        validator = NFRValidator(
+            hilbert_space,
+            coherence_operator,
+            float(coherence_threshold) if coherence_threshold is not None else 0.0,
+            frequency_operator=frequency_operator,
+        )
+        math_cfg["validator"] = validator
+
+    enforce_frequency = bool(frequency_operator is not None)
+
+    norm_values: list[float] = []
+    normalized_flags: list[bool] = []
+    coherence_flags: list[bool] = []
+    coherence_values: list[float] = []
+    coherence_threshold: float | None = None
+    frequency_flags: list[bool] = []
+    frequency_values: list[float] = []
+    frequency_spectrum_min: float | None = None
+
+    for node_id in nodes:
+        data = G.nodes[node_id]
+        epi = float(data.get("EPI", 0.0))
+        nu_f = float(
+            get_attr(
+                data,
+                VF_ALIAS_KEYS,
+                default=float(data.get(VF_PRIMARY, 0.0)),
+            )
+        )
+        theta = float(data.get("theta", 0.0))
+        state = state_projector(epi=epi, nu_f=nu_f, theta=theta, dim=hilbert_space.dimension)
+        norm_values.append(float(hilbert_space.norm(state)))
+        outcome = validator.validate(
+            state,
+            enforce_frequency_positivity=enforce_frequency,
+        )
+        summary = outcome.summary
+        normalized_flags.append(bool(summary.get("normalized", False)))
+
+        coherence_summary = summary.get("coherence")
+        if isinstance(coherence_summary, Mapping):
+            coherence_flags.append(bool(coherence_summary.get("passed", False)))
+            coherence_values.append(float(coherence_summary.get("value", 0.0)))
+            if coherence_threshold is None and "threshold" in coherence_summary:
+                coherence_threshold = float(coherence_summary.get("threshold", 0.0))
+
+        frequency_summary = summary.get("frequency")
+        if isinstance(frequency_summary, Mapping):
+            frequency_flags.append(bool(frequency_summary.get("passed", False)))
+            frequency_values.append(float(frequency_summary.get("value", 0.0)))
+            if frequency_spectrum_min is None and "spectrum_min" in frequency_summary:
+                frequency_spectrum_min = float(frequency_summary.get("spectrum_min", 0.0))
+
+    if norm_values:
+        logger.info(
+            "[MATH] Hilbert norm preserved=%s (min=%.6f, max=%.6f)",
+            all(normalized_flags),
+            min(norm_values),
+            max(norm_values),
+        )
+
+    if coherence_values and coherence_threshold is not None:
+        logger.info(
+            "[MATH] Coherence ≥ C_min=%s (C_min=%.6f, min=%.6f)",
+            all(coherence_flags),
+            float(coherence_threshold),
+            min(coherence_values),
+        )
+
+    if frequency_values:
+        if frequency_spectrum_min is not None:
+            logger.info(
+                "[MATH] νf positivity=%s (min=%.6f, spectrum_min=%.6f)",
+                all(frequency_flags),
+                min(frequency_values),
+                frequency_spectrum_min,
+            )
+        else:
+            logger.info(
+                "[MATH] νf positivity=%s (min=%.6f)",
+                all(frequency_flags),
+                min(frequency_values),
+            )
+
+
 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"])
@@ -281,8 +606,12 @@ def _log_run_summaries(G: "nx.Graph", args: argparse.Namespace) -> None:
         if has_latency_values:
             logger.info("Average latency: %s", summary["latency_mean"])
 
+    _log_math_engine_summary(G)
+
 
 def cmd_run(args: argparse.Namespace) -> int:
+    """Execute ``tnfr run`` returning the exit status."""
+
     code, graph = _run_cli_program(args)
     if code != 0:
         return code
@@ -293,18 +622,18 @@ def cmd_run(args: argparse.Namespace) -> int:
 
 
 def cmd_sequence(args: argparse.Namespace) -> int:
+    """Execute ``tnfr sequence`` returning the exit status."""
+
     if args.preset and args.sequence_file:
-        logger.error(
-            "Cannot use --preset and --sequence-file at the same time"
-        )
+        logger.error("Cannot use --preset and --sequence-file at the same time")
         return 1
-    code, _ = _run_cli_program(
-        args, default_program=get_preset(CANONICAL_PRESET_NAME)
-    )
+    code, _ = _run_cli_program(args, default_program=get_preset(CANONICAL_PRESET_NAME))
     return code
 
 
 def cmd_metrics(args: argparse.Namespace) -> int:
+    """Execute ``tnfr metrics`` returning the exit status."""
+
     if getattr(args, "steps", None) is None:
         # Default a longer run for metrics stability
         args.steps = 200
@@ -320,3 +649,60 @@ def cmd_metrics(args: argparse.Namespace) -> int:
     else:
         logger.info("%s", json_dumps(out))
     return 0
+
+
+def cmd_profile_si(args: argparse.Namespace) -> int:
+    """Execute ``tnfr profile-si`` returning the exit status."""
+
+    try:
+        profile_module = import_module("benchmarks.compute_si_profile")
+    except ModuleNotFoundError as exc:  # pragma: no cover - optional dependency
+        logger.error("Sense Index profiling helpers unavailable: %s", exc)
+        return 1
+
+    profile_compute_si = getattr(profile_module, "profile_compute_si")
+
+    profile_compute_si(
+        node_count=int(args.nodes),
+        chord_step=int(args.chord_step),
+        loops=int(args.loops),
+        output_dir=Path(args.output_dir),
+        fmt=str(args.format),
+        sort=str(args.sort),
+    )
+    return 0
+
+
+def cmd_profile_pipeline(args: argparse.Namespace) -> int:
+    """Execute ``tnfr profile-pipeline`` returning the exit status."""
+
+    try:
+        profile_module = import_module("benchmarks.full_pipeline_profile")
+    except ModuleNotFoundError as exc:  # pragma: no cover - optional dependency
+        logger.error("Full pipeline profiling helpers unavailable: %s", exc)
+        return 1
+
+    profile_full_pipeline = getattr(profile_module, "profile_full_pipeline")
+
+    try:
+        si_chunk_sizes = _parse_cli_variants(getattr(args, "si_chunk_sizes", None))
+        dnfr_chunk_sizes = _parse_cli_variants(getattr(args, "dnfr_chunk_sizes", None))
+        si_workers = _parse_cli_variants(getattr(args, "si_workers", None))
+        dnfr_workers = _parse_cli_variants(getattr(args, "dnfr_workers", None))
+    except ValueError as exc:
+        logger.error("%s", exc)
+        return 2
+
+    profile_full_pipeline(
+        node_count=int(args.nodes),
+        edge_probability=float(args.edge_probability),
+        loops=int(args.loops),
+        seed=int(args.seed),
+        output_dir=Path(args.output_dir),
+        sort=str(args.sort),
+        si_chunk_sizes=si_chunk_sizes,
+        dnfr_chunk_sizes=dnfr_chunk_sizes,
+        si_workers=si_workers,
+        dnfr_workers=dnfr_workers,
+    )
+    return 0