thundergraph-model 1.0.0__py3-none-any.whl

tg_model/__init__.py

@@ -0,0 +1,46 @@
+"""ThunderGraph Model — executable systems modeling in Python.
+
+This package re-exports the **primary authoring surface** (elements, definition
+context, refs, and roll-up helpers). For configure-time and run-time APIs
+(:class:`~tg_model.execution.configured_model.ConfiguredModel`, graph compile,
+evaluation), import :mod:`tg_model.execution` explicitly.
+
+Notes
+-----
+Types are **compiled** once per class (cached). :func:`~tg_model.execution.configured_model.instantiate`
+builds a frozen topology; :class:`~tg_model.execution.run_context.RunContext` holds
+per-run values. See the user documentation plan in ``docs/user_docs/``.
+"""
+
+from tg_model.model.declarations.values import rollup
+from tg_model.model.definition_context import (
+    ModelDefinitionContext,
+    ModelDefinitionError,
+    parameter_ref,
+    requirement_ref,
+)
+from tg_model.model.elements import Element, Part, Requirement, System
+from tg_model.model.refs import (
+    AttributeRef,
+    PartRef,
+    PortRef,
+    Ref,
+    RequirementRef,
+)
+
+__all__ = [
+    "AttributeRef",
+    "Element",
+    "ModelDefinitionContext",
+    "ModelDefinitionError",
+    "Part",
+    "PartRef",
+    "PortRef",
+    "Ref",
+    "Requirement",
+    "RequirementRef",
+    "System",
+    "parameter_ref",
+    "requirement_ref",
+    "rollup",
+]

tg_model/analysis/__init__.py

@@ -0,0 +1,38 @@
+"""Multi-run orchestration: sweeps, variant comparison, value-graph propagation (Phase 5).
+
+``impact`` / :func:`dependency_impact` report **dependency reachability on the value graph**
+only — not program-wide “engineering impact” (see :mod:`tg_model.analysis.impact`).
+"""
+
+from tg_model.analysis.compare_variants import (
+    CapturedSlotOutput,
+    CompareVariantsValidationError,
+    VariantComparisonRow,
+    VariantScenario,
+    compare_variants,
+    compare_variants_async,
+)
+from tg_model.analysis.impact import (
+    ImpactReport,
+    dependency_impact,
+    value_graph_propagation,
+)
+from tg_model.analysis.sweep import SweepRecord, sweep, sweep_async
+
+impact = dependency_impact
+
+__all__ = [
+    "CapturedSlotOutput",
+    "CompareVariantsValidationError",
+    "ImpactReport",
+    "SweepRecord",
+    "VariantComparisonRow",
+    "VariantScenario",
+    "compare_variants",
+    "compare_variants_async",
+    "dependency_impact",
+    "impact",
+    "sweep",
+    "sweep_async",
+    "value_graph_propagation",
+]

tg_model/analysis/_coherence.py

@@ -0,0 +1,91 @@
+"""Shared checks: configured model, compiled graph, and ValueSlot handles must align."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, Sequence
+from typing import Any
+
+from tg_model.execution.configured_model import ConfiguredModel
+from tg_model.execution.dependency_graph import DependencyGraph
+from tg_model.execution.value_slots import ValueSlot
+
+
+def assert_slots_align_with_graph(
+    configured_model: ConfiguredModel,
+    graph: DependencyGraph,
+    slots: Iterable[ValueSlot],
+    *,
+    context: str,
+) -> None:
+    """Verify slots belong to ``configured_model`` and appear as ``val:<path>`` nodes in ``graph``.
+
+    Parameters
+    ----------
+    configured_model : ConfiguredModel
+        Topology built from the same root as ``graph``.
+    graph : DependencyGraph
+        Output of :func:`~tg_model.execution.graph_compiler.compile_graph` for that model.
+    slots : iterable of ValueSlot
+        Handles to verify (parameters, prune targets, …).
+    context : str
+        Label for error messages (e.g. ``\"sweep\"``).
+
+    Raises
+    ------
+    ValueError
+        On registry mismatch, path mismatch, or missing graph node.
+    """
+    for s in slots:
+        if s.stable_id not in configured_model.id_registry:
+            raise ValueError(
+                f"{context}: slot {s.path_string!r} (stable_id={s.stable_id!r}) "
+                f"is not registered on the given configured_model."
+            )
+        reg = configured_model.id_registry[s.stable_id]
+        if not isinstance(reg, ValueSlot):
+            raise ValueError(f"{context}: id_registry[{s.stable_id!r}] is not a ValueSlot (got {type(reg).__name__}).")
+        if reg.path_string != s.path_string:
+            raise ValueError(
+                f"{context}: slot path mismatch for stable_id {s.stable_id!r}: "
+                f"handle has {s.path_string!r}, model has {reg.path_string!r}."
+            )
+        vid = f"val:{s.path_string}"
+        if vid not in graph.nodes:
+            raise ValueError(
+                f"{context}: no graph node {vid!r} for slot {s.path_string!r}. "
+                "Pass the DependencyGraph from compile_graph(same configured_model)."
+            )
+
+
+def plan_sweep_axes(
+    parameter_values: Mapping[ValueSlot, Sequence[Any]],
+) -> tuple[list[ValueSlot], list[Sequence[Any]]]:
+    """Sort sweep axes by ``stable_id`` and validate each axis is non-empty.
+
+    Parameters
+    ----------
+    parameter_values
+        Map each parameter slot to its value sequence.
+
+    Returns
+    -------
+    slots_sorted : list[ValueSlot]
+        Keys sorted by ``stable_id``.
+    combo_lists : list[Sequence[Any]]
+        Parallel list of value sequences (same order as ``slots_sorted``).
+
+    Raises
+    ------
+    ValueError
+        If any slot maps to an empty sequence.
+    """
+    if not parameter_values:
+        return [], []
+    slots_sorted = sorted(parameter_values.keys(), key=lambda s: s.stable_id)
+    combo_lists: list[Sequence[Any]] = []
+    for slot in slots_sorted:
+        seq = parameter_values[slot]
+        if not seq:
+            raise ValueError(f"Empty value sequence for slot '{slot.path_string}'")
+        combo_lists.append(seq)
+    return slots_sorted, combo_lists

tg_model/analysis/compare_variants.py

@@ -0,0 +1,197 @@
+"""Cross-variant evaluation: same workflow, isolated runs, aligned outputs (Phase 5).
+
+Each scenario compiles its own graph from its :class:`ConfiguredModel` — structure
+may differ per variant. There is no shared :class:`tg_model.execution.run_context.RunContext`.
+
+By default, :func:`validate_graph` runs (with ``configured_model``) before each
+evaluation so ill-posed variants fail with :class:`CompareVariantsValidationError`
+instead of obscure runtime errors.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, TypeAlias
+
+from tg_model.execution.configured_model import ConfiguredModel
+from tg_model.execution.dependency_graph import DependencyGraph
+from tg_model.execution.evaluator import Evaluator, RunResult
+from tg_model.execution.graph_compiler import compile_graph
+from tg_model.execution.run_context import RunContext
+from tg_model.execution.validation import validate_graph
+from tg_model.execution.value_slots import ValueSlot
+
+VariantScenario: TypeAlias = tuple[str, ConfiguredModel, Mapping[str, Any]]  # noqa: UP040
+
+
+class CompareVariantsValidationError(Exception):
+    """Raised when :func:`~tg_model.execution.validation.validate_graph` fails for one variant."""
+
+    def __init__(self, label: str, failures: list[str]) -> None:
+        """Attach ``label`` and ``failures`` to the exception for programmatic handling."""
+        self.label = label
+        self.failures = list(failures)
+        detail = "; ".join(failures)
+        super().__init__(f"validate_graph failed for variant {label!r}: {detail}")
+
+
+@dataclass(frozen=True)
+class CapturedSlotOutput:
+    """Resolved output for one ``output_paths`` entry in :class:`VariantComparisonRow`."""
+
+    value: Any | None
+    present_in_run_outputs: bool
+    """True iff the slot's ``stable_id`` was present in ``RunResult.outputs``."""
+
+    @property
+    def realized(self) -> bool:
+        return self.present_in_run_outputs
+
+
+@dataclass(frozen=True)
+class VariantComparisonRow:
+    """One scenario row from :func:`compare_variants`."""
+
+    label: str
+    outputs: dict[str, CapturedSlotOutput]
+    result: RunResult
+
+
+def _assert_same_root_if_requested(
+    scenarios: Sequence[VariantScenario],
+    *,
+    require_same_root_definition_type: bool,
+) -> None:
+    if not require_same_root_definition_type or len(scenarios) <= 1:
+        return
+    t0 = scenarios[0][1].root.definition_type
+    for label, cm, _ in scenarios[1:]:
+        if cm.root.definition_type is not t0:
+            raise ValueError(
+                f"compare_variants: scenario {label!r} root type "
+                f"{cm.root.definition_type!r} differs from the first scenario ({t0!r}). "
+                "Set require_same_root_definition_type=False to compare structurally "
+                "different roots, or align your configured models."
+            )
+
+
+def _compile_and_maybe_validate(
+    label: str,
+    cm: ConfiguredModel,
+    *,
+    validate_before_run: bool,
+) -> tuple[DependencyGraph, dict[str, Any]]:
+    graph, handlers = compile_graph(cm)
+    if validate_before_run:
+        v = validate_graph(graph, configured_model=cm)
+        if not v.passed:
+            raise CompareVariantsValidationError(label, [f.message for f in v.failures])
+    return graph, handlers
+
+
+def _collect_outputs(cm: ConfiguredModel, result: RunResult, paths: Sequence[str]) -> dict[str, CapturedSlotOutput]:
+    out: dict[str, CapturedSlotOutput] = {}
+    for path in paths:
+        handle = cm.handle(path)
+        if not isinstance(handle, ValueSlot):
+            raise TypeError(f"output_paths entry {path!r} must resolve to a ValueSlot, got {type(handle).__name__}")
+        sid = handle.stable_id
+        present = sid in result.outputs
+        out[path] = CapturedSlotOutput(
+            value=result.outputs[sid] if present else None,
+            present_in_run_outputs=present,
+        )
+    return out
+
+
+def compare_variants(
+    *,
+    scenarios: Sequence[VariantScenario],
+    output_paths: Sequence[str],
+    validate_before_run: bool = True,
+    require_same_root_definition_type: bool = False,
+) -> list[VariantComparisonRow]:
+    """Evaluate each ``(label, configured_model, inputs)`` with a fresh graph and context.
+
+    Parameters
+    ----------
+    scenarios
+        Sequence of ``(label, configured_model, inputs)`` tuples.
+    output_paths
+        Dotted paths that must resolve to :class:`~tg_model.execution.value_slots.ValueSlot`.
+    validate_before_run : bool, default True
+        Run :func:`~tg_model.execution.validation.validate_graph` before each evaluation.
+    require_same_root_definition_type : bool, default False
+        When True, all roots must share the same Python type.
+
+    Returns
+    -------
+    list of VariantComparisonRow
+        One row per scenario in input order.
+
+    Raises
+    ------
+    CompareVariantsValidationError
+        When validation fails for a labeled scenario.
+    ValueError
+        When ``require_same_root_definition_type`` is violated.
+    TypeError
+        When an ``output_paths`` entry does not resolve to a ``ValueSlot``.
+
+    Notes
+    -----
+    ``inputs`` maps ``ValueSlot.stable_id`` strings to values, same as
+    :meth:`~tg_model.execution.evaluator.Evaluator.evaluate`. ``CapturedSlotOutput``
+    distinguishes absent outputs from ``None`` values via ``present_in_run_outputs``.
+    """
+    _assert_same_root_if_requested(scenarios, require_same_root_definition_type=require_same_root_definition_type)
+
+    rows: list[VariantComparisonRow] = []
+    for label, cm, inputs in scenarios:
+        graph, handlers = _compile_and_maybe_validate(
+            label,
+            cm,
+            validate_before_run=validate_before_run,
+        )
+        evaluator = Evaluator(graph, compute_handlers=handlers)
+        ctx = RunContext()
+        result = evaluator.evaluate(ctx, inputs=dict(inputs))
+        outputs = _collect_outputs(cm, result, output_paths)
+        rows.append(VariantComparisonRow(label=label, outputs=outputs, result=result))
+    return rows
+
+
+async def compare_variants_async(
+    *,
+    scenarios: Sequence[VariantScenario],
+    output_paths: Sequence[str],
+    validate_before_run: bool = True,
+    require_same_root_definition_type: bool = False,
+) -> list[VariantComparisonRow]:
+    """Async variant of :func:`compare_variants` (uses ``evaluate_async`` per scenario).
+
+    Raises
+    ------
+    CompareVariantsValidationError, ValueError, TypeError
+        Same families as :func:`compare_variants`.
+    """
+    _assert_same_root_if_requested(scenarios, require_same_root_definition_type=require_same_root_definition_type)
+
+    rows: list[VariantComparisonRow] = []
+    for label, cm, inputs in scenarios:
+        graph, handlers = _compile_and_maybe_validate(
+            label,
+            cm,
+            validate_before_run=validate_before_run,
+        )
+        evaluator = Evaluator(graph, compute_handlers=handlers)
+        ctx = RunContext()
+        result = await evaluator.evaluate_async(
+            ctx,
+            configured_model=cm,
+            inputs=dict(inputs),
+        )
+        outputs = _collect_outputs(cm, result, output_paths)
+        rows.append(VariantComparisonRow(label=label, outputs=outputs, result=result))
+    return rows

tg_model/analysis/impact.py

@@ -0,0 +1,101 @@
+"""Value-graph propagation (Phase 5): upstream / downstream **value slots** only.
+
+This is **dependency reachability** on one compiled :class:`~tg_model.execution.dependency_graph.DependencyGraph`.
+It does **not** aggregate requirements, hazards, behavior, interfaces, or other program semantics —
+do not treat it as a full “engineering impact” or FMEA surface without layering your own model.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from tg_model.execution.dependency_graph import DependencyGraph
+from tg_model.execution.value_slots import ValueSlot
+
+
+def _value_node_id(slot: ValueSlot) -> str:
+    return f"val:{slot.path_string}"
+
+
+def _slot_ids_for_nodes(graph: DependencyGraph, node_ids: set[str]) -> frozenset[str]:
+    ids: set[str] = set()
+    for nid in node_ids:
+        sid = graph.get_node(nid).slot_id
+        if sid is not None:
+            ids.add(sid)
+    return frozenset(ids)
+
+
+@dataclass(frozen=True)
+class ImpactReport:
+    """Value-graph reachability summary from a set of changed slots."""
+
+    changed_paths: tuple[str, ...]
+    upstream_slot_ids: frozenset[str]
+    downstream_slot_ids: frozenset[str]
+
+
+def dependency_impact(
+    graph: DependencyGraph,
+    changed: Sequence[ValueSlot],
+    *,
+    upstream: bool = True,
+    downstream: bool = True,
+) -> ImpactReport:
+    """Return other value slots reachable from ``changed`` on the value graph.
+
+    Parameters
+    ----------
+    graph : DependencyGraph
+        Compiled graph for the configuration under study.
+    changed : sequence of ValueSlot
+        Slots whose perturbation you want to analyze.
+    upstream, downstream : bool, default True
+        Include reachability in each direction.
+
+    Returns
+    -------
+    ImpactReport
+        Excludes the changed slots' own ``stable_id`` values from the sets.
+
+    Raises
+    ------
+    ValueError
+        If a changed slot does not map to a ``val:<path>`` node in ``graph``.
+
+    Notes
+    -----
+    This is **dependency reachability only**, not full engineering impact (see module docstring).
+    """
+    if not changed:
+        return ImpactReport((), frozenset(), frozenset())
+
+    seeds = [_value_node_id(s) for s in changed]
+    for vid in seeds:
+        if vid not in graph.nodes:
+            raise ValueError(
+                f"changed slot maps to unknown graph node {vid!r} "
+                f"(is this graph compiled for the same configured model?)"
+            )
+
+    seed_ids = {s.stable_id for s in changed}
+
+    up_ids: frozenset[str] = frozenset()
+    down_ids: frozenset[str] = frozenset()
+
+    if upstream:
+        up_ids = frozenset(
+            sid for sid in _slot_ids_for_nodes(graph, graph.dependency_closure(seeds)) if sid not in seed_ids
+        )
+    if downstream:
+        down_ids = frozenset(
+            sid for sid in _slot_ids_for_nodes(graph, graph.dependent_closure(seeds)) if sid not in seed_ids
+        )
+
+    paths = tuple(s.path_string for s in changed)
+    return ImpactReport(paths, up_ids, down_ids)
+
+
+# Explicit alias: prefer this name when “impact” would oversell scope.
+value_graph_propagation = dependency_impact

tg_model/analysis/sweep.py

@@ -0,0 +1,199 @@
+"""Parameter sweeps over a fixed dependency graph (Phase 5).
+
+Reuses :class:`tg_model.execution.evaluator.Evaluator` for each sample; every
+sample gets a fresh :class:`tg_model.execution.run_context.RunContext`.
+
+**Coherence:** Pass ``configured_model`` whenever you have it; the library then
+verifies sweep :class:`ValueSlot` handles match ``compile_graph(configured_model)``.
+
+**Throughput:** Samples run sequentially. This is not a parallel study runner.
+
+**Pruning:** ``prune_to_slots`` evaluates an *upstream-closed* subgraph only.
+Constraint (and other) nodes outside that closure are *not* executed —
+``RunResult.constraint_results`` may be empty. Do not treat a pruned sweep as a
+compliance run unless you know what you excluded.
+"""
+
+from __future__ import annotations
+
+import itertools
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from tg_model.analysis._coherence import assert_slots_align_with_graph, plan_sweep_axes
+from tg_model.execution.configured_model import ConfiguredModel
+from tg_model.execution.dependency_graph import DependencyGraph
+from tg_model.execution.evaluator import Evaluator, RunResult
+from tg_model.execution.run_context import RunContext
+from tg_model.execution.value_slots import ValueSlot
+
+
+@dataclass(frozen=True)
+class SweepRecord:
+    """One row from :func:`sweep` / :func:`sweep_async`."""
+
+    index: int
+    inputs: dict[str, Any]
+    result: RunResult
+
+
+def _value_node_id(slot: ValueSlot) -> str:
+    return f"val:{slot.path_string}"
+
+
+def _prepare_pruned(
+    graph: DependencyGraph,
+    handlers: dict[str, Any],
+    prune_to_slots: Sequence[ValueSlot] | None,
+) -> tuple[DependencyGraph, dict[str, Any]]:
+    if not prune_to_slots:
+        return graph, handlers
+    seeds = [_value_node_id(s) for s in prune_to_slots]
+    for vid in seeds:
+        if vid not in graph.nodes:
+            raise ValueError(
+                f"Prune target {vid!r} is not a graph node (expected val:<instance.path> for a compiled value slot)."
+            )
+    needed = graph.dependency_closure(seeds)
+    sub = graph.induced_subgraph(needed)
+    sub_handlers = {k: handlers[k] for k in sub.nodes if k in handlers}
+    return sub, sub_handlers
+
+
+def _maybe_assert_coherence(
+    configured_model: ConfiguredModel | None,
+    graph: DependencyGraph,
+    parameter_slots: Sequence[ValueSlot],
+    prune_slots: Sequence[ValueSlot] | None,
+) -> None:
+    if configured_model is None:
+        return
+    to_check = list(parameter_slots)
+    if prune_slots:
+        to_check.extend(prune_slots)
+    assert_slots_align_with_graph(
+        configured_model,
+        graph,
+        to_check,
+        context="sweep",
+    )
+
+
+def sweep(
+    *,
+    graph: DependencyGraph,
+    handlers: dict[str, Any],
+    parameter_values: Mapping[ValueSlot, Sequence[Any]],
+    configured_model: ConfiguredModel | None = None,
+    prune_to_slots: Sequence[ValueSlot] | None = None,
+    collect: bool = True,
+    sink: Callable[[SweepRecord], None] | None = None,
+) -> list[SweepRecord]:
+    """Cartesian product over ``parameter_values``; one synchronous evaluation per tuple.
+
+    Parameters
+    ----------
+    graph, handlers
+        From :func:`~tg_model.execution.graph_compiler.compile_graph`.
+    parameter_values
+        Maps each parameter :class:`~tg_model.execution.value_slots.ValueSlot` to a sequence
+        of values (axes). Dimension order is sorted by ``stable_id``.
+    configured_model : ConfiguredModel, optional
+        When passed, asserts sweep slots match the graph (coherence check).
+    prune_to_slots : sequence of ValueSlot, optional
+        Restricts to upstream closure of these slots (see module warnings).
+    collect : bool, default True
+        When False, return an empty list and stream via ``sink``.
+    sink : callable, optional
+        Receives each :class:`SweepRecord` when provided.
+
+    Returns
+    -------
+    list of SweepRecord
+        All samples when ``collect`` is True.
+
+    Raises
+    ------
+    ValueError
+        If ``collect=False`` without ``sink``, or prune targets are not graph nodes.
+    """
+    if not collect and sink is None:
+        raise ValueError("sweep(..., collect=False) requires a sink callable")
+
+    slots_sorted, combo_lists = plan_sweep_axes(parameter_values)
+    _maybe_assert_coherence(configured_model, graph, slots_sorted, prune_to_slots)
+
+    eval_graph, eval_handlers = _prepare_pruned(graph, handlers, prune_to_slots)
+    evaluator = Evaluator(eval_graph, compute_handlers=eval_handlers)
+
+    records: list[SweepRecord] = []
+    for idx, combo in enumerate(itertools.product(*combo_lists)):
+        inputs: dict[str, Any] = {}
+        for slot, val in zip(slots_sorted, combo, strict=True):
+            inputs[slot.stable_id] = val
+        ctx = RunContext()
+        result = evaluator.evaluate(ctx, inputs=inputs)
+        rec = SweepRecord(index=idx, inputs=dict(inputs), result=result)
+        if sink is not None:
+            sink(rec)
+        if collect:
+            records.append(rec)
+    return records
+
+
+async def sweep_async(
+    *,
+    configured_model: ConfiguredModel,
+    graph: DependencyGraph,
+    handlers: dict[str, Any],
+    parameter_values: Mapping[ValueSlot, Sequence[Any]],
+    prune_to_slots: Sequence[ValueSlot] | None = None,
+    collect: bool = True,
+    sink: Callable[[SweepRecord], None] | None = None,
+) -> list[SweepRecord]:
+    """Like :func:`sweep` but awaits :meth:`~tg_model.execution.evaluator.Evaluator.evaluate_async`.
+
+    Parameters
+    ----------
+    configured_model : ConfiguredModel
+        Required for async externals and always used for coherence checks.
+    graph, handlers, parameter_values, prune_to_slots, collect, sink
+        Same semantics as :func:`sweep`.
+
+    Returns
+    -------
+    list of SweepRecord
+        Same as :func:`sweep`.
+
+    Raises
+    ------
+    ValueError
+        Same as :func:`sweep`.
+    """
+    if not collect and sink is None:
+        raise ValueError("sweep_async(..., collect=False) requires a sink callable")
+
+    slots_sorted, combo_lists = plan_sweep_axes(parameter_values)
+    _maybe_assert_coherence(configured_model, graph, slots_sorted, prune_to_slots)
+
+    eval_graph, eval_handlers = _prepare_pruned(graph, handlers, prune_to_slots)
+    evaluator = Evaluator(eval_graph, compute_handlers=eval_handlers)
+
+    records: list[SweepRecord] = []
+    for idx, combo in enumerate(itertools.product(*combo_lists)):
+        inputs: dict[str, Any] = {}
+        for slot, val in zip(slots_sorted, combo, strict=True):
+            inputs[slot.stable_id] = val
+        ctx = RunContext()
+        result = await evaluator.evaluate_async(
+            ctx,
+            configured_model=configured_model,
+            inputs=inputs,
+        )
+        rec = SweepRecord(index=idx, inputs=dict(inputs), result=result)
+        if sink is not None:
+            sink(rec)
+        if collect:
+            records.append(rec)
+    return records