thundergraph-model 1.4.1__tar.gz → 1.4.2__tar.gz

{thundergraph_model-1.4.1 → thundergraph_model-1.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thundergraph-model
-Version: 1.4.1
+Version: 1.4.2
 Summary: Executable systems modeling in Python
 License-File: LICENSE
 Requires-Python: >=3.11

{thundergraph_model-1.4.1 → thundergraph_model-1.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "thundergraph-model"
-version = "1.4.1"
+version = "1.4.2"
 description = "Executable systems modeling in Python"
 readme = "PYPI.md"
 requires-python = ">=3.11"

thundergraph_model-1.4.2/tests/integration/structural_models/test_requirement_class_dedupe.py

@@ -0,0 +1,269 @@
+"""Integration tests for Requirement class-identity deduplication.
+
+A Requirement class is a specification statement. When the same Requirement
+subclass is composed in multiple places from DIFFERENT defining classes (e.g.
+inside a domain System AND inside a top-level rollup package), tg-model treats
+them as ONE shared RequirementPackageInstance with multiple navigation paths.
+
+When the SAME defining class introduces the same Requirement multiple times
+(because that class is instantiated more than once), each instance gets its own
+independent RequirementPackageInstance. This is the multi-instantiation case
+and must NOT be deduped.
+
+Parts and Systems are unaffected — they always retain distinct-instance semantics.
+"""
+
+from __future__ import annotations
+
+import pytest
+from unitflow import Quantity
+from unitflow.catalogs.si import kN
+
+from tg_model.execution.configured_model import instantiate
+from tg_model.model.elements import Part, Requirement, System
+
+
+# ── Shared leaf declarations ─────────────────────────────────────────────────
+
+class _Thruster(Part):
+    @classmethod
+    def define(cls, model):  # type: ignore[override]
+        model.name("thruster")
+        model.parameter("thrust", unit=kN)
+
+
+class _ThrustReq(Requirement):
+    @classmethod
+    def define(cls, model):  # type: ignore[override]
+        model.name("thrust_req")
+        model.doc("Thrust shall meet the floor.")
+        declared = model.parameter("declared", unit=kN)
+        floor    = model.parameter("floor",    unit=kN)
+        margin   = model.attribute("margin", unit=kN, expr=declared - floor)
+        model.constraint("margin_non_negative", expr=margin >= Quantity(0, kN))
+
+
+class _CapacityReq(Requirement):
+    @classmethod
+    def define(cls, model):  # type: ignore[override]
+        model.name("capacity_req")
+        model.doc("Capacity shall meet the minimum.")
+        capacity = model.parameter("capacity", unit=kN)
+        minimum  = model.parameter("minimum",  unit=kN)
+        headroom = model.attribute("headroom", unit=kN, expr=capacity - minimum)
+        model.constraint("headroom_non_negative", expr=headroom >= Quantity(0, kN))
+
+
+# ── Programs for dedupe scenarios ────────────────────────────────────────────
+
+class _RollupReqs(Requirement):
+    """Top-level rollup that re-composes _ThrustReq — should alias the domain System's instance."""
+    @classmethod
+    def define(cls, model):  # type: ignore[override]
+        model.name("rollup")
+        model.doc("Top-level rollup view.")
+        model.composed_of("thrust", _ThrustReq)
+
+
+class _DomainSystem(System):
+    """Domain System that owns _ThrustReq and allocates it to the thruster."""
+    @classmethod
+    def define(cls, model):  # type: ignore[override]
+        model.name("domain")
+        floor = model.parameter("floor_kN", unit=kN)
+        thr   = model.composed_of("thruster", _Thruster)
+        req   = model.composed_of("thrust_req", _ThrustReq)
+        model.allocate(req, thr, inputs={
+            "declared": thr.thrust,
+            "floor":    floor,
+        })
+
+
+class _ProgramWithRollup(System):
+    """Top-level program: domain System + rollup that also composes the same Requirement."""
+    @classmethod
+    def define(cls, model):  # type: ignore[override]
+        model.name("program_with_rollup")
+        model.composed_of("domain",   _DomainSystem)
+        model.composed_of("rollup",   _RollupReqs)
+
+
+# ── Programs for multi-instantiation (no-dedupe) scenario ────────────────────
+
+class _SubSystem(System):
+    """Sub-system that composes _ThrustReq internally."""
+    @classmethod
+    def define(cls, model):  # type: ignore[override]
+        model.name("subsystem")
+        floor = model.parameter("floor_kN", unit=kN)
+        thr   = model.composed_of("thruster", _Thruster)
+        req   = model.composed_of("thrust_req", _ThrustReq)
+        model.allocate(req, thr, inputs={
+            "declared": thr.thrust,
+            "floor":    floor,
+        })
+
+
+class _ProgramWithTwoSubSystems(System):
+    """Two instances of the same sub-System class — each should get its own Requirement instance."""
+    @classmethod
+    def define(cls, model):  # type: ignore[override]
+        model.name("program_two_subsystems")
+        model.composed_of("sub_a", _SubSystem)
+        model.composed_of("sub_b", _SubSystem)
+
+
+# ── Programs for regression tests ───────────────────────────────────────────
+
+class _Motor(Part):
+    @classmethod
+    def define(cls, model):  # type: ignore[override]
+        model.name("motor")
+        model.parameter("torque", unit=kN)
+
+
+class _ProgramTwoDistinctParts(System):
+    @classmethod
+    def define(cls, model):  # type: ignore[override]
+        model.name("program_two_parts")
+        model.composed_of("motor_a", _Motor)
+        model.composed_of("motor_b", _Motor)
+
+
+class _InnerSystem(System):
+    @classmethod
+    def define(cls, model):  # type: ignore[override]
+        model.name("inner")
+        model.parameter("p", unit=kN)
+
+
+class _ProgramTwoDistinctSystems(System):
+    @classmethod
+    def define(cls, model):  # type: ignore[override]
+        model.name("program_two_systems")
+        model.composed_of("inner_a", _InnerSystem)
+        model.composed_of("inner_b", _InnerSystem)
+
+
+def setup_function() -> None:
+    for cls in (
+        _Thruster, _ThrustReq, _CapacityReq, _RollupReqs, _DomainSystem,
+        _ProgramWithRollup, _SubSystem, _ProgramWithTwoSubSystems,
+        _Motor, _ProgramTwoDistinctParts, _InnerSystem, _ProgramTwoDistinctSystems,
+    ):
+        cls._reset_compilation()
+
+
+# ── 1) Dedupe: same Requirement class composed by two DIFFERENT classes ──────
+
+def test_same_req_class_two_parents_is_one_instance() -> None:
+    """DomainSystem and RollupReqs both compose _ThrustReq — only one instance."""
+    cm = instantiate(_ProgramWithRollup)
+    domain_req  = cm.handle("_ProgramWithRollup.domain.thrust_req")
+    rollup_req  = cm.handle("_ProgramWithRollup.rollup.thrust")
+    assert domain_req is rollup_req, "Both paths must resolve to the SAME RequirementPackageInstance"
+
+
+def test_alias_path_resolves_to_canonical_slots() -> None:
+    """Both navigation paths point to the same ValueSlot objects."""
+    cm = instantiate(_ProgramWithRollup)
+    canonical_declared = cm.handle("_ProgramWithRollup.domain.thrust_req.declared")
+    alias_declared     = cm.handle("_ProgramWithRollup.rollup.thrust.declared")
+    assert canonical_declared is alias_declared
+
+
+def test_id_registry_has_one_entry_per_req_instance() -> None:
+    """id_registry dedupe: only one stable_id entry for _ThrustReq."""
+    cm = instantiate(_ProgramWithRollup)
+    thrust_req_entries = [
+        (sid, obj) for sid, obj in cm.id_registry.items()
+        if hasattr(obj, "package_type") and obj.package_type is _ThrustReq
+    ]
+    assert len(thrust_req_entries) == 1, (
+        f"Expected exactly one id_registry entry for _ThrustReq, got {len(thrust_req_entries)}"
+    )
+
+
+def test_allocation_wires_shared_instance() -> None:
+    """Allocation declared in DomainSystem uses the shared instance and correct source slots."""
+    cm = instantiate(_ProgramWithRollup)
+    assert len(cm.allocations) == 1
+    alloc = cm.allocations[0]
+    # Requirement points at the shared (canonical) instance
+    assert alloc.requirement.path_string == "_ProgramWithRollup.domain.thrust_req"
+    # parameter_overrides maps req-param-name → SOURCE slot (the Part side of the wiring)
+    assert set(alloc.parameter_overrides.keys()) == {"declared", "floor"}
+    assert alloc.parameter_overrides["declared"].path_string == "_ProgramWithRollup.domain.thruster.thrust"
+    assert alloc.parameter_overrides["floor"].path_string == "_ProgramWithRollup.domain.floor_kN"
+
+
+def test_end_to_end_evaluates_constraint_once() -> None:
+    """Only one constraint result — not two copies of the same constraint."""
+    cm = instantiate(_ProgramWithRollup)
+    result = cm.evaluate(inputs={
+        cm.domain.floor_kN.stable_id:        Quantity(50, kN),
+        cm.domain.thruster.thrust.stable_id: Quantity(80, kN),
+    })
+    assert result.passed
+    assert len(result.constraint_results) == 1, (
+        f"Expected 1 constraint result (not duplicated), got {len(result.constraint_results)}"
+    )
+
+
+# ── 2) No-dedupe: same class instantiated multiple times ─────────────────────
+
+def test_multi_instantiation_produces_distinct_req_instances() -> None:
+    """sub_a and sub_b each get their OWN _ThrustReq instance (different subsystem instances)."""
+    cm = instantiate(_ProgramWithTwoSubSystems)
+    req_a = cm.handle("_ProgramWithTwoSubSystems.sub_a.thrust_req")
+    req_b = cm.handle("_ProgramWithTwoSubSystems.sub_b.thrust_req")
+    assert req_a is not req_b, "_SubSystem instances must each own their own _ThrustReq"
+
+
+def test_multi_instantiation_distinct_slots() -> None:
+    slot_a = cm_two = instantiate(_ProgramWithTwoSubSystems)
+    slot_a_declared = cm_two.handle("_ProgramWithTwoSubSystems.sub_a.thrust_req.declared")
+    slot_b_declared = cm_two.handle("_ProgramWithTwoSubSystems.sub_b.thrust_req.declared")
+    assert slot_a_declared is not slot_b_declared
+
+
+def test_multi_instantiation_two_allocations() -> None:
+    cm = instantiate(_ProgramWithTwoSubSystems)
+    assert len(cm.allocations) == 2
+    targets = {a.target.path_string for a in cm.allocations}
+    assert targets == {
+        "_ProgramWithTwoSubSystems.sub_a.thruster",
+        "_ProgramWithTwoSubSystems.sub_b.thruster",
+    }
+
+
+def test_multi_instantiation_evaluates_each_subsystem() -> None:
+    cm = instantiate(_ProgramWithTwoSubSystems)
+    result = cm.evaluate(inputs={
+        cm.sub_a.floor_kN.stable_id:        Quantity(50, kN),
+        cm.sub_a.thruster.thrust.stable_id: Quantity(80, kN),  # passes
+        cm.sub_b.floor_kN.stable_id:        Quantity(50, kN),
+        cm.sub_b.thruster.thrust.stable_id: Quantity(30, kN),  # fails
+    })
+    assert not result.passed
+    assert len(result.constraint_results) == 2
+    states = {cr.state for cr in result.constraint_results}
+    assert "passed" in states and "failed" in states
+
+
+# ── 3) Regression: Parts and Systems always produce distinct instances ────────
+
+def test_part_composed_twice_distinct_instances() -> None:
+    cm = instantiate(_ProgramTwoDistinctParts)
+    motor_a = cm.handle("_ProgramTwoDistinctParts.motor_a")
+    motor_b = cm.handle("_ProgramTwoDistinctParts.motor_b")
+    assert motor_a is not motor_b
+    assert motor_a.stable_id != motor_b.stable_id
+
+
+def test_system_composed_twice_distinct_instances() -> None:
+    cm = instantiate(_ProgramTwoDistinctSystems)
+    inner_a = cm.handle("_ProgramTwoDistinctSystems.inner_a")
+    inner_b = cm.handle("_ProgramTwoDistinctSystems.inner_b")
+    assert inner_a is not inner_b
+    assert inner_a.stable_id != inner_b.stable_id

{thundergraph_model-1.4.1 → thundergraph_model-1.4.2}/tg_model/execution/configured_model.py

@@ -241,6 +241,22 @@ def instantiate(root_type: type) -> ConfiguredModel:
     id_registry: dict[str, ElementInstance | ValueSlot] = {}
     requirement_value_slots: list[ValueSlot] = []
 
+    # Requirement classes are specification statements — there is no such thing
+    # as "two copies of the same requirement." When the same Requirement subclass
+    # is composed in multiple places from DIFFERENT defining classes (e.g. once
+    # inside FacilitySystem and again inside DataCenterCapabilityRequirements),
+    # tg-model treats them as ONE shared RequirementPackageInstance with multiple
+    # navigation paths in path_registry.
+    #
+    # However, when the SAME defining class introduces a Requirement multiple times
+    # (because that class is itself instantiated more than once — e.g. two motor
+    # sub-systems each owning their own thrust requirement), each instance gets its
+    # own independent RequirementPackageInstance. This is the multi-instantiation
+    # case and must NOT be deduped.
+    #
+    # Registry maps: Requirement class → (introducing_class, canonical_instance)
+    pkg_class_registry: dict[type, tuple[type, RequirementPackageInstance]] = {}
+
     root_path = (root_type.__name__,)
     root_id = derive_declaration_id(root_type, *root_path)
     root_instance = PartInstance(
@@ -260,6 +276,7 @@ def instantiate(root_type: type) -> ConfiguredModel:
         id_registry,
         ref_accumulator,
         requirement_value_slots,
+        pkg_class_registry,
     )
 
     connections = _instantiate_all_connections(root_instance, path_registry, root_type)
@@ -279,6 +296,45 @@ def instantiate(root_type: type) -> ConfiguredModel:
     )
 
 
+def _register_pkg_alias(
+    existing: RequirementPackageInstance,
+    alias_path: tuple[str, ...],
+    path_registry: dict[str, ElementInstance | ValueSlot],
+) -> None:
+    """Register an already-instantiated RequirementPackageInstance under a new path prefix.
+
+    When the same Requirement class is composed a second time, we do not create a
+    new instance. Instead, all navigation paths under ``alias_path`` are added to
+    ``path_registry`` pointing at the SAME descendant objects as the canonical path.
+    ``id_registry`` is NOT touched — each object retains exactly one stable_id.
+
+    This walk mirrors the structure produced by _instantiate_requirement_block_children:
+    it recurses into nested RequirementPackageInstances so deeply-nested members are
+    also aliased.
+    """
+    canonical_prefix = existing.instance_path
+    canonical_len = len(canonical_prefix)
+    alias_str = ".".join(alias_path)
+    path_registry[alias_str] = existing
+
+    # Walk _members which contains: ElementInstance (requirement/constraint/citation),
+    # ValueSlot (parameter/attribute), and nested RequirementPackageInstance.
+    stack: list[RequirementPackageInstance] = [existing]
+    while stack:
+        pkg = stack.pop()
+        pkg_alias_prefix = alias_path + pkg.instance_path[canonical_len:]
+        for member_name, member in pkg._members.items():
+            # Compute the alias path for this member.
+            member_alias = (*pkg_alias_prefix, member_name)
+            member_alias_str = ".".join(member_alias)
+            if isinstance(member, RequirementPackageInstance):
+                path_registry[member_alias_str] = member
+                stack.append(member)
+            else:
+                # ElementInstance (requirement, constraint, citation) or ValueSlot.
+                path_registry[member_alias_str] = member
+
+
 def _instantiate_children(
     parent: PartInstance,
     compiled: dict[str, Any],
@@ -287,9 +343,12 @@ def _instantiate_children(
     id_registry: dict[str, ElementInstance | ValueSlot],
     ref_accumulator: list[ReferenceBinding] | None = None,
     requirement_value_slots: list[ValueSlot] | None = None,
+    pkg_class_registry: dict[type, RequirementPackageInstance] | None = None,
 ) -> None:
     """Walk compiled nodes and create child instances under parent."""
     type_registry: dict[str, type] = compiled.get("_type_registry", {})
+    if pkg_class_registry is None:
+        pkg_class_registry = {}
 
     for name, node in compiled["nodes"].items():
         kind = node["kind"]
@@ -319,6 +378,7 @@ def _instantiate_children(
                     id_registry,
                     ref_accumulator,
                     requirement_value_slots,
+                    pkg_class_registry,
                 )
 
         elif kind == "port":
@@ -361,26 +421,64 @@ def _instantiate_children(
             block_type = type_registry.get(name)
             if block_type is None:
                 raise ValueError(f"requirement_block {name!r} has no target_type (internal compile error)")
-            pkg_inst = RequirementPackageInstance(
-                stable_id=child_id,
-                definition_type=root_type,
-                definition_path=(name,),
-                instance_path=child_path,
-                package_type=block_type,
-                metadata=metadata,
-            )
-            parent.add_requirement_package(name, pkg_inst)
-            _register(pkg_inst, path_registry, id_registry)
-            _instantiate_requirement_block_children(
-                pkg_inst,
-                _requirement_block_compiled_artifact(block_type),
-                root_type,
-                root_type,
-                path_registry,
-                id_registry,
-                ref_accumulator,
-                requirement_value_slots,
-            )
+            introducing_class = parent.definition_type
+            registry_entry = pkg_class_registry.get(block_type)
+            if registry_entry is not None:
+                prior_introducing_class, existing_inst = registry_entry
+                if prior_introducing_class is not introducing_class:
+                    # Different class introduces the same Requirement — cross-tree
+                    # sharing (e.g. rollup package referencing a domain requirement).
+                    # Alias to the canonical instance; don't recurse.
+                    parent.add_requirement_package(name, existing_inst)
+                    _register_pkg_alias(existing_inst, alias_path=child_path, path_registry=path_registry)
+                else:
+                    # Same class introduces the same Requirement again — this class
+                    # is instantiated multiple times and each instance gets its own
+                    # independent Requirement instance. Don't dedupe.
+                    pkg_inst = RequirementPackageInstance(
+                        stable_id=child_id,
+                        definition_type=root_type,
+                        definition_path=(name,),
+                        instance_path=child_path,
+                        package_type=block_type,
+                        metadata=metadata,
+                    )
+                    parent.add_requirement_package(name, pkg_inst)
+                    _register(pkg_inst, path_registry, id_registry)
+                    _instantiate_requirement_block_children(
+                        pkg_inst,
+                        _requirement_block_compiled_artifact(block_type),
+                        root_type,
+                        root_type,
+                        path_registry,
+                        id_registry,
+                        ref_accumulator,
+                        requirement_value_slots,
+                        pkg_class_registry,
+                    )
+            else:
+                pkg_inst = RequirementPackageInstance(
+                    stable_id=child_id,
+                    definition_type=root_type,
+                    definition_path=(name,),
+                    instance_path=child_path,
+                    package_type=block_type,
+                    metadata=metadata,
+                )
+                parent.add_requirement_package(name, pkg_inst)
+                _register(pkg_inst, path_registry, id_registry)
+                pkg_class_registry[block_type] = (introducing_class, pkg_inst)
+                _instantiate_requirement_block_children(
+                    pkg_inst,
+                    _requirement_block_compiled_artifact(block_type),
+                    root_type,
+                    root_type,
+                    path_registry,
+                    id_registry,
+                    ref_accumulator,
+                    requirement_value_slots,
+                    pkg_class_registry,
+                )
 
         elif kind == "constraint":
             constraint_instance = ElementInstance(
@@ -414,10 +512,13 @@ def _instantiate_requirement_block_children(
     id_registry: dict[str, ElementInstance | ValueSlot],
     ref_accumulator: list[ReferenceBinding] | None = None,
     requirement_value_slots: list[ValueSlot] | None = None,
+    pkg_class_registry: dict[type, RequirementPackageInstance] | None = None,
 ) -> None:
     """Materialize members under a composable requirement package (dot-access under the root part)."""
     type_registry: dict[str, type] = compiled.get("_type_registry", {})
     prefix_path = package.instance_path
+    if pkg_class_registry is None:
+        pkg_class_registry = {}
 
     for name, node in compiled["nodes"].items():
         kind = node["kind"]
@@ -451,26 +552,60 @@ def _instantiate_requirement_block_children(
             block_type = type_registry.get(name)
             if block_type is None:
                 raise ValueError(f"requirement_block {name!r} has no target_type (internal compile error)")
-            inner_pkg = RequirementPackageInstance(
-                stable_id=child_id,
-                definition_type=definition_root_type,
-                definition_path=tuple(child_path[1:]),
-                instance_path=child_path,
-                package_type=block_type,
-                metadata=metadata,
-            )
-            package.add_member(name, inner_pkg)
-            _register(inner_pkg, path_registry, id_registry)
-            _instantiate_requirement_block_children(
-                inner_pkg,
-                _requirement_block_compiled_artifact(block_type),
-                definition_root_type,
-                root_type,
-                path_registry,
-                id_registry,
-                ref_accumulator,
-                requirement_value_slots,
-            )
+            introducing_class = package.package_type
+            registry_entry = pkg_class_registry.get(block_type)
+            if registry_entry is not None:
+                prior_introducing_class, existing_inst = registry_entry
+                if prior_introducing_class is not introducing_class:
+                    # Different Requirement class is introducing this — alias.
+                    package.add_member(name, existing_inst)
+                    _register_pkg_alias(existing_inst, alias_path=child_path, path_registry=path_registry)
+                else:
+                    # Same package type introduces it again (multi-instantiation).
+                    inner_pkg = RequirementPackageInstance(
+                        stable_id=child_id,
+                        definition_type=definition_root_type,
+                        definition_path=tuple(child_path[1:]),
+                        instance_path=child_path,
+                        package_type=block_type,
+                        metadata=metadata,
+                    )
+                    package.add_member(name, inner_pkg)
+                    _register(inner_pkg, path_registry, id_registry)
+                    _instantiate_requirement_block_children(
+                        inner_pkg,
+                        _requirement_block_compiled_artifact(block_type),
+                        definition_root_type,
+                        root_type,
+                        path_registry,
+                        id_registry,
+                        ref_accumulator,
+                        requirement_value_slots,
+                        pkg_class_registry,
+                    )
+            else:
+                inner_pkg = RequirementPackageInstance(
+                    stable_id=child_id,
+                    definition_type=definition_root_type,
+                    definition_path=tuple(child_path[1:]),
+                    instance_path=child_path,
+                    package_type=block_type,
+                    metadata=metadata,
+                )
+                package.add_member(name, inner_pkg)
+                _register(inner_pkg, path_registry, id_registry)
+                pkg_class_registry[block_type] = (introducing_class, inner_pkg)
+                _instantiate_requirement_block_children(
+                    inner_pkg,
+                    _requirement_block_compiled_artifact(block_type),
+                    definition_root_type,
+                    root_type,
+                    path_registry,
+                    id_registry,
+                    ref_accumulator,
+                    requirement_value_slots,
+                    pkg_class_registry,
+                )
 
         elif kind in ("parameter", "attribute"):
             slot = ValueSlot(