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

tnfr/cli/arguments.py

@@ -1,6 +1,9 @@
+"""Argument parser helpers shared across TNFR CLI commands."""
+
 from __future__ import annotations
 
 import argparse
+from pathlib import Path
 from typing import Any, Iterable
 
 from ..config.presets import PREFERRED_PRESET_NAMES
@@ -9,7 +12,6 @@ from ..telemetry.verbosity import TELEMETRY_VERBOSITY_LEVELS
 from ..types import ArgSpec
 from .utils import spec
 
-
 _PRESET_HELP = "Available presets: {}.".format(
     ", ".join(PREFERRED_PRESET_NAMES),
 )
@@ -65,12 +67,13 @@ COMMON_ARG_SPECS: tuple[ArgSpec, ...] = (
     spec("--gamma-type", choices=list(GAMMA_REGISTRY.keys()), default="none"),
     spec("--gamma-beta", type=float, default=0.0),
     spec("--gamma-R0", type=float, default=0.0),
+    spec("--um-candidate-count", type=int),
+    spec("--stop-early-window", type=int),
+    spec("--stop-early-fraction", type=float),
 )
 
 
-def add_arg_specs(
-    parser: argparse._ActionsContainer, specs: Iterable[ArgSpec]
-) -> None:
+def add_arg_specs(parser: argparse._ActionsContainer, specs: Iterable[ArgSpec]) -> None:
     """Register arguments from ``specs`` on ``parser``."""
     for opt, kwargs in specs:
         parser.add_argument(opt, **kwargs)
@@ -99,9 +102,7 @@ def add_grammar_args(parser: argparse.ArgumentParser) -> None:
 def add_grammar_selector_args(parser: argparse.ArgumentParser) -> None:
     """Add grammar options and glyph selector."""
     add_grammar_args(parser)
-    parser.add_argument(
-        "--selector", choices=["basic", "param"], default="basic"
-    )
+    parser.add_argument("--selector", choices=["basic", "param"], default="basic")
 
 
 def add_history_export_args(parser: argparse.ArgumentParser) -> None:
@@ -122,16 +123,35 @@ def add_canon_toggle(parser: argparse.ArgumentParser) -> None:
 
 def _add_run_parser(sub: argparse._SubParsersAction) -> None:
     """Configure the ``run`` subcommand."""
-    from .execution import cmd_run, DEFAULT_SUMMARY_SERIES_LIMIT
+
+    from .execution import DEFAULT_SUMMARY_SERIES_LIMIT, cmd_run
 
     p_run = sub.add_parser(
         "run",
-        help=(
-            "Run a free scenario or preset and optionally export history"
-        ),
+        help=("Run a free scenario or preset and optionally export history"),
     )
     add_common_args(p_run)
     p_run.add_argument("--steps", type=int, default=100)
+    p_run.add_argument(
+        "--use-Si",
+        dest="use_Si",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Recompute the Sense Index during the run (use --no-use-Si to disable)",
+    )
+    p_run.add_argument(
+        "--apply-glyphs",
+        dest="apply_glyphs",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Apply glyphs at every step (use --no-apply-glyphs to disable)",
+    )
+    p_run.add_argument(
+        "--dnfr-n-jobs",
+        dest="dnfr_n_jobs",
+        type=int,
+        help="Override ΔNFR parallel jobs forwarded to the runtime",
+    )
     add_canon_toggle(p_run)
     add_grammar_selector_args(p_run)
     add_history_export_args(p_run)
@@ -147,6 +167,64 @@ def _add_run_parser(sub: argparse._SubParsersAction) -> None:
             " disable trimming)"
         ),
     )
+
+    math_group = p_run.add_argument_group("Mathematical dynamics")
+    math_group.add_argument(
+        "--math-engine",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help=(
+            "Enable the spectral mathematical dynamics engine to project nodes"
+            " onto Hilbert space vectors and validate norm, coherence and"
+            " structural frequency invariants"
+        ),
+    )
+    math_group.add_argument(
+        "--math-dimension",
+        type=int,
+        help="Hilbert space dimension to use when the math engine is enabled",
+    )
+    math_group.add_argument(
+        "--math-coherence-spectrum",
+        type=float,
+        nargs="+",
+        metavar="λ",
+        help=(
+            "Eigenvalues for the coherence operator (defaults to a flat"
+            " spectrum when omitted)"
+        ),
+    )
+    math_group.add_argument(
+        "--math-coherence-c-min",
+        type=float,
+        help="Explicit coherence floor C_min for the operator",
+    )
+    math_group.add_argument(
+        "--math-coherence-threshold",
+        type=float,
+        help="Coherence expectation threshold enforced during validation",
+    )
+    math_group.add_argument(
+        "--math-frequency-diagonal",
+        type=float,
+        nargs="+",
+        metavar="ν",
+        help=(
+            "Diagonal entries for the structural frequency operator"
+            " (defaults to the identity spectrum)"
+        ),
+    )
+    math_group.add_argument(
+        "--math-generator-diagonal",
+        type=float,
+        nargs="+",
+        metavar="ω",
+        help=(
+            "Diagonal ΔNFR generator used by the mathematical dynamics"
+            " engine (defaults to the null generator)"
+        ),
+    )
+
     p_run.set_defaults(func=cmd_run)
 
 
@@ -179,9 +257,7 @@ def _add_metrics_parser(sub: argparse._SubParsersAction) -> None:
     """Configure the ``metrics`` subcommand."""
     from .execution import cmd_metrics
 
-    p_met = sub.add_parser(
-        "metrics", help="Run briefly and export key metrics"
-    )
+    p_met = sub.add_parser("metrics", help="Run briefly and export key metrics")
     add_common_args(p_met)
     p_met.add_argument("--steps", type=int, default=None)
     add_canon_toggle(p_met)
@@ -197,3 +273,88 @@ def _add_metrics_parser(sub: argparse._SubParsersAction) -> None:
         ),
     )
     p_met.set_defaults(func=cmd_metrics)
+
+
+def _add_profile_parser(sub: argparse._SubParsersAction) -> None:
+    """Configure the ``profile-si`` subcommand."""
+
+    from .execution import cmd_profile_si
+
+    p_prof = sub.add_parser(
+        "profile-si",
+        help="Profile compute_Si with and without NumPy",
+    )
+    p_prof.add_argument("--nodes", type=int, default=240)
+    p_prof.add_argument("--chord-step", type=int, default=7)
+    p_prof.add_argument("--loops", type=int, default=5)
+    p_prof.add_argument("--output-dir", type=Path, default=Path("profiles"))
+    p_prof.add_argument("--format", choices=("pstats", "json"), default="pstats")
+    p_prof.add_argument("--sort", choices=("cumtime", "tottime"), default="cumtime")
+    p_prof.set_defaults(func=cmd_profile_si)
+
+
+def _add_profile_pipeline_parser(sub: argparse._SubParsersAction) -> None:
+    """Configure the ``profile-pipeline`` subcommand."""
+
+    from .execution import cmd_profile_pipeline
+
+    p_profile = sub.add_parser(
+        "profile-pipeline",
+        help="Profile the Sense Index + ΔNFR pipeline",
+    )
+    p_profile.add_argument("--nodes", type=int, default=240, help="Number of nodes")
+    p_profile.add_argument(
+        "--edge-probability",
+        type=float,
+        default=0.32,
+        help="Probability passed to the Erdos-Renyi generator",
+    )
+    p_profile.add_argument(
+        "--loops",
+        type=int,
+        default=5,
+        help="How many times to execute the pipeline inside the profiler",
+    )
+    p_profile.add_argument(
+        "--seed",
+        type=int,
+        default=42,
+        help="Random seed used when generating the graph",
+    )
+    p_profile.add_argument(
+        "--output-dir",
+        type=Path,
+        default=Path("profiles"),
+        help="Directory where profiling artefacts will be written",
+    )
+    p_profile.add_argument(
+        "--sort",
+        choices=("cumtime", "tottime"),
+        default="cumtime",
+        help="Sort order applied to profiling rows",
+    )
+    p_profile.add_argument(
+        "--si-chunk-sizes",
+        nargs="+",
+        metavar="SIZE",
+        help="Chunk sizes forwarded to G.graph['SI_CHUNK_SIZE']; use 'auto' for heuristics",
+    )
+    p_profile.add_argument(
+        "--dnfr-chunk-sizes",
+        nargs="+",
+        metavar="SIZE",
+        help="Chunk sizes forwarded to G.graph['DNFR_CHUNK_SIZE']; use 'auto' for heuristics",
+    )
+    p_profile.add_argument(
+        "--si-workers",
+        nargs="+",
+        metavar="COUNT",
+        help="Worker counts forwarded to G.graph['SI_N_JOBS']; use 'auto' for serial runs",
+    )
+    p_profile.add_argument(
+        "--dnfr-workers",
+        nargs="+",
+        metavar="COUNT",
+        help="Worker counts forwarded to G.graph['DNFR_N_JOBS']; use 'auto' for defaults",
+    )
+    p_profile.set_defaults(func=cmd_profile_pipeline)

tnfr/cli/arguments.pyi

@@ -11,23 +11,17 @@ GRAMMAR_ARG_SPECS: tuple[ArgSpec, ...]
 HISTORY_ARG_SPECS: tuple[ArgSpec, ...]
 COMMON_ARG_SPECS: tuple[ArgSpec, ...]
 
-
-def add_arg_specs(parser: argparse._ActionsContainer, specs: Iterable[ArgSpec]) -> None: ...
-
+def add_arg_specs(
+    parser: argparse._ActionsContainer, specs: Iterable[ArgSpec]
+) -> None: ...
 def _args_to_dict(args: argparse.Namespace, prefix: str) -> dict[str, Any]: ...
-
 def add_common_args(parser: argparse.ArgumentParser) -> None: ...
-
 def add_grammar_args(parser: argparse.ArgumentParser) -> None: ...
-
 def add_grammar_selector_args(parser: argparse.ArgumentParser) -> None: ...
-
 def add_history_export_args(parser: argparse.ArgumentParser) -> None: ...
-
 def add_canon_toggle(parser: argparse.ArgumentParser) -> None: ...
-
 def _add_run_parser(sub: argparse._SubParsersAction) -> None: ...
-
 def _add_sequence_parser(sub: argparse._SubParsersAction) -> None: ...
-
 def _add_metrics_parser(sub: argparse._SubParsersAction) -> None: ...
+def _add_profile_parser(sub: argparse._SubParsersAction) -> None: ...
+def _add_profile_pipeline_parser(sub: argparse._SubParsersAction) -> None: ...