完善 XML 通用仿真与结果查看

PythonModels/core/ports.py

@@ -1,6 +1,70 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
+from typing import Literal
+
+
+PortKind = Literal["physical", "signal"]
+PortNominalRole = Literal["inlet", "outlet", "bidirectional", "input", "output"]
+ActualFlowDirection = Literal["in", "out", "stagnant"]
+VariableRole = Literal["effort", "flow", "stream", "signal"]
+ConnectionRule = Literal["equal", "sumToZero", "streamMix", "directed"]
+
+
+@dataclass(frozen=True)
+class PortVariableDefinition:
+    name: str
+    role: VariableRole
+    connection_rule: ConnectionRule
+
+    def as_interface_dict(self) -> dict[str, str]:
+        return {
+            "name": self.name,
+            "role": self.role,
+            "connectionRule": self.connection_rule,
+        }
+
+
+@dataclass(frozen=True)
+class PortDefinition:
+    """Stable connector contract shared by components, XML, and the compiler."""
+
+    name: str
+    kind: PortKind
+    domain: str
+    nominal_role: PortNominalRole
+    positive_flow_direction: Literal["intoComponent"] | None = None
+    variables: tuple[PortVariableDefinition, ...] = ()
+
+    @classmethod
+    def pneumatic(
+        cls,
+        name: str,
+        *,
+        nominal_role: Literal["inlet", "outlet", "bidirectional"] = "bidirectional",
+    ) -> PortDefinition:
+        return cls(
+            name=name,
+            kind="physical",
+            domain="pneumatic",
+            nominal_role=nominal_role,
+            positive_flow_direction="intoComponent",
+            variables=(
+                PortVariableDefinition("p", "effort", "equal"),
+                PortVariableDefinition("m_flow", "flow", "sumToZero"),
+                PortVariableDefinition("h_outflow", "stream", "streamMix"),
+            ),
+        )
+
+    def as_interface_dict(self) -> dict[str, object]:
+        return {
+            "name": self.name,
+            "kind": self.kind,
+            "domain": self.domain,
+            "nominalRole": self.nominal_role,
+            "positiveFlowDirection": self.positive_flow_direction,
+            "variables": [variable.as_interface_dict() for variable in self.variables],
+        }
 
 
 @dataclass
@@ -10,4 +74,29 @@ class PortState:
     p: float = 0.0
     m_flow: float = 0.0
     h_outflow: float = 0.0
+    definition: PortDefinition | None = field(default=None, repr=False, compare=False)
+
+    @classmethod
+    def pneumatic(
+        cls,
+        name: str,
+        *,
+        nominal_role: Literal["inlet", "outlet", "bidirectional"] = "bidirectional",
+    ) -> PortState:
+        return cls(definition=PortDefinition.pneumatic(name, nominal_role=nominal_role))
+
+    @property
+    def inflow_rate(self) -> float:
+        return max(self.m_flow, 0.0)
+
+    @property
+    def outflow_rate(self) -> float:
+        return max(-self.m_flow, 0.0)
+
+    def actual_direction(self, tolerance: float = 1e-12) -> ActualFlowDirection:
+        if self.m_flow > tolerance:
+            return "in"
+        if self.m_flow < -tolerance:
+            return "out"
+        return "stagnant"