完善仿真交互、结果展示与模型元数据

PythonModels/README.md

@@ -12,6 +12,7 @@
   包含组件基类、状态与端口数据结构、介质模型、网络装配、积分入口。
 - `components/`: 元件级 Python 实现
   目前有 `Cylinder`、`Tank`、`Pipe`、`Orifice`、`Tee` 五类元件。
+  新增或修改元件时先阅读 `components/example.md` 中的建模规范与完整示例。
 - `systems/`: 系统级装配与闭合
   当前只有 `TestModelSystem`，对应 `ModelicaModels/Testmodel.mo`。
 - `reporting/`: 结果导出与对比

PythonModels/components/cylinder.py

@@ -2,16 +2,53 @@ from __future__ import annotations
 
 from collections.abc import Mapping
 
-from PythonModels.core.base import DynamicComponent
+from PythonModels.core.base import ThermodynamicVolumeComponent
 from PythonModels.core.equations import EquationResidual
+from PythonModels.core.metadata import (
+    ParameterDefinition,
+    THERMODYNAMIC_VOLUME_RESULT_VARIABLES,
+)
 from PythonModels.core.medium import IdealGasMedium, ThermodynamicProperties
-from PythonModels.core.ports import PortState
+from PythonModels.core.ports import PortDefinition
 from PythonModels.core.state import VolumeState
 
 
-class Cylinder(DynamicComponent):
+class Cylinder(ThermodynamicVolumeComponent):
     """Python port of ModelicaModels.Mycylinder."""
 
+    MODEL_TYPE = "cylinder"
+    PORTS = (PortDefinition.pneumatic("port_b", nominal_role="outlet"),)
+    PARAMETERS = (
+        ParameterDefinition(
+            "volume",
+            0.01,
+            label="容积",
+            quantity="volume",
+            unit="m3",
+            minimum=0.0,
+            minimum_exclusive=True,
+        ),
+        ParameterDefinition(
+            "p0",
+            35e6,
+            label="初始压力",
+            quantity="pressure",
+            unit="Pa",
+            minimum=0.0,
+            minimum_exclusive=True,
+        ),
+        ParameterDefinition(
+            "T0",
+            300.0,
+            label="初始温度",
+            quantity="temperature",
+            unit="K",
+            minimum=0.0,
+            minimum_exclusive=True,
+        ),
+    )
+    RESULT_VARIABLES = THERMODYNAMIC_VOLUME_RESULT_VARIABLES
+
     def __init__(
         self,
         name: str,
@@ -21,14 +58,13 @@ class Cylinder(DynamicComponent):
         T0: float = 300.0,
     ) -> None:
         super().__init__(name=name)
+        self.set_parameter_values({"volume": V, "p0": p0, "T0": T0})
         self.medium = medium
         self.V = V
         m0 = p0 * V / (medium.R_gas * T0)
         U0 = m0 * medium.specific_internal_energy(T0)
         self.state = VolumeState(m=m0, U=U0)
-        self.port_b = self.register_port(
-            PortState.pneumatic("port_b", nominal_role="outlet")
-        )
+        self.port_b = self.register_declared_port("port_b")
 
     def get_state_vector(self) -> list[float]:
         return self.state.as_vector()

PythonModels/components/example.md

@@ -0,0 +1,240 @@
+# 元件建模规范与示例
+
+本文档是 `PythonModels/components` 下新增元件的最小开发规范。目标是让元件的端口、输入参数和可展示结果都由元件类显式声明，避免 XML 校验、求解器和前端分别维护同一份含义。
+
+## 一、元件类必须声明的内容
+
+每个元件类至少需要声明以下四个类属性：
+
+```python
+MODEL_TYPE = "example_component"
+PORTS = (...)
+PARAMETERS = (...)
+RESULT_VARIABLES = (...)
+```
+
+- `MODEL_TYPE`：稳定的模型类型标识，对应 System XML 中的 `Component/@type`。发布后不要随意改名。
+- `PORTS`：端口契约，包括端口名、物理域、变量和正流量方向。
+- `PARAMETERS`：用户可配置的输入参数，包括默认值、物理量、SI 单位和取值范围。
+- `RESULT_VARIABLES`：允许写入仿真结果并显示在结果页的组件级变量。端口结果由 `PORTS` 中的端口变量定义自动生成。
+
+元件构造函数还必须：
+
+1. 调用 `super().__init__(name)`。
+2. 使用 `set_parameter_values()` 保存规范化后的输入参数。
+3. 使用 `register_declared_port()` 创建已声明端口。
+4. 若声明了组件结果变量，实现 `component_result_values()` 并返回对应数值；标准热力学容腔可以直接继承 `ThermodynamicVolumeComponent` 的实现。
+
+## 二、输入参数与结果变量
+
+输入参数和仿真结果必须分开声明：
+
+- 输入参数描述一次仿真开始前由用户配置的量，例如 `volume`、`p0`、`T0`。
+- 结果变量描述随时间变化、允许绘图的量，例如 `p`、`T`、`m`、`m_flow`。
+- 求解器缓存、中间残差和调试字段不得自动暴露为结果变量。
+- 参数名和结果变量名使用稳定的英文机器标识；`label` 专门用于界面显示。
+
+参数定义示例：
+
+```python
+ParameterDefinition(
+    name="volume",
+    label="容积",
+    quantity="volume",
+    unit="m3",
+    default=0.1,
+    minimum=0.0,
+    minimum_exclusive=True,
+)
+```
+
+结果变量定义示例：
+
+```python
+ResultVariableDefinition(
+    name="p",
+    label="压力",
+    quantity="pressure",
+    unit="Pa",
+    category="thermodynamic",
+    order=30,
+)
+```
+
+## 三、命名和单位约定
+
+- 模型类型、参数、端口和变量名使用 `snake_case`，已有热力学惯例 `T`、`U` 可以保留。
+- 输入参数保存和计算统一使用 SI 基准值；界面单位换算不能改变后端存储值。
+- 无量纲参数的 `unit` 使用空字符串。
+- `quantity` 表示稳定的物理量类型，例如 `pressure`、`temperature`、`mass_flow`，不能使用界面文案代替。
+- 正质量流量统一定义为流入元件，即 `positiveFlowDirection="intoComponent"`。
+- 端口变量 `p`、`m_flow`、`h_outflow` 的连接规则由 `PortDefinition.pneumatic()` 统一提供。
+
+## 四、完整示例：单端口储气容腔
+
+下面的示例展示一个可直接接入当前框架的动态元件。真实新增元件时应放入独立的 `.py` 文件，并补充对应测试。
+
+```python
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from PythonModels.core.base import ThermodynamicVolumeComponent
+from PythonModels.core.equations import EquationResidual
+from PythonModels.core.metadata import (
+    ParameterDefinition,
+    THERMODYNAMIC_VOLUME_RESULT_VARIABLES,
+)
+from PythonModels.core.medium import IdealGasMedium, ThermodynamicProperties
+from PythonModels.core.ports import PortDefinition
+from PythonModels.core.state import VolumeState
+
+
+class ExampleVolume(ThermodynamicVolumeComponent):
+    MODEL_TYPE = "example_volume"
+    PORTS = (
+        PortDefinition.pneumatic("port_a", nominal_role="bidirectional"),
+    )
+    PARAMETERS = (
+        ParameterDefinition(
+            name="volume",
+            label="容积",
+            quantity="volume",
+            unit="m3",
+            default=0.1,
+            minimum=0.0,
+            minimum_exclusive=True,
+        ),
+        ParameterDefinition(
+            name="p0",
+            label="初始压力",
+            quantity="pressure",
+            unit="Pa",
+            default=100000.0,
+            minimum=0.0,
+            minimum_exclusive=True,
+        ),
+        ParameterDefinition(
+            name="T0",
+            label="初始温度",
+            quantity="temperature",
+            unit="K",
+            default=300.0,
+            minimum=0.0,
+            minimum_exclusive=True,
+        ),
+    )
+    RESULT_VARIABLES = THERMODYNAMIC_VOLUME_RESULT_VARIABLES
+
+    def __init__(
+        self,
+        name: str,
+        medium: IdealGasMedium,
+        volume: float = 0.1,
+        p0: float = 100000.0,
+        T0: float = 300.0,
+    ) -> None:
+        super().__init__(name)
+        self.set_parameter_values(
+            {"volume": volume, "p0": p0, "T0": T0}
+        )
+        self.medium = medium
+        self.V = volume
+        initial_mass = p0 * volume / (medium.R_gas * T0)
+        initial_energy = initial_mass * medium.specific_internal_energy(T0)
+        self.state = VolumeState(m=initial_mass, U=initial_energy)
+        self.port_a = self.register_declared_port("port_a")
+
+    def get_state_vector(self) -> list[float]:
+        return self.state.as_vector()
+
+    def set_state_vector(self, values: list[float]) -> None:
+        self.state = VolumeState.from_vector(values)
+
+    def refresh_thermodynamic_ports(self) -> ThermodynamicProperties:
+        properties = self.medium.properties_from_mU(
+            self.state.m, self.state.U, self.V
+        )
+        self.port_a.p = properties.p
+        self.port_a.h_outflow = properties.h
+        return properties
+
+    def state_derivative_from_ports(
+        self,
+        connected_h: Mapping[str, float],
+    ) -> list[float]:
+        properties = self.refresh_thermodynamic_ports()
+        inlet_h = self.connection_inlet_enthalpy(
+            port_m_flow=self.port_a.m_flow,
+            connected_h=connected_h["port_a"],
+            internal_h=properties.h,
+        )
+        return [self.port_a.m_flow, self.port_a.m_flow * inlet_h]
+
+    def pressure_flow_equation_residuals(
+        self,
+    ) -> tuple[EquationResidual, ...]:
+        pressure = self.medium.properties_from_mU(
+            self.state.m, self.state.U, self.V
+        ).p
+        return (
+            EquationResidual(
+                id=f"{self.name}:port_a_pressure_state",
+                owner="component",
+                owner_id=self.name,
+                relation="state",
+                variables=(f"{self.name}.port_a.p", f"{self.name}.state"),
+                role="effort",
+                value=self.port_a.p - pressure,
+            ),
+        )
+```
+
+注册时只引用元件类已经声明的契约，不要再复制参数和端口定义：
+
+```python
+def _example_volume_factory(name, medium, values):
+    return ExampleVolume(
+        name=name,
+        medium=medium,
+        volume=values["volume"],
+        p0=values["p0"],
+        T0=values["T0"],
+    )
+
+
+COMPONENT_MODEL_REGISTRY[ExampleVolume.MODEL_TYPE] = ComponentModelSpec(
+    model_type=ExampleVolume.MODEL_TYPE,
+    ports=ExampleVolume.PORTS,
+    parameters=ExampleVolume.PARAMETERS,
+    factory=_example_volume_factory,
+)
+```
+
+完成仿真后，每个已声明结果都会得到一条结构化元数据。前端应按字段筛选，不能再拆解 `key` 猜测含义：
+
+```json
+{
+  "key": "example_volume_1.port_a.m_flow",
+  "componentId": "example_volume_1",
+  "componentType": "example_volume",
+  "scope": "port",
+  "portName": "port_a",
+  "name": "m_flow",
+  "label": "质量流量",
+  "quantity": "mass_flow",
+  "unit": "kg/s",
+  "category": "flow",
+  "order": 20
+}
+```
+
+## 五、新增元件检查清单
+
+1. `MODEL_TYPE` 是否唯一，并与 XML、前端组件类型一致。
+2. 所有构造参数是否在 `PARAMETERS` 中声明并保存。
+3. 所有端口是否在 `PORTS` 中声明并通过 `register_declared_port()` 创建。
+4. `RESULT_VARIABLES` 与 `component_result_values()` 的键是否完全一致。
+5. 结果变量是否包含明确的 `quantity`、`label`、`unit` 和显示顺序。
+6. 是否只暴露有工程意义的结果，而非内部计算变量。
+7. 是否补充参数边界、端口契约、结果元数据和最小仿真的自动测试。

PythonModels/components/orifice.py

@@ -5,22 +5,44 @@ from math import sqrt
 
 from PythonModels.core.base import AlgebraicComponent
 from PythonModels.core.equations import EquationResidual
-from PythonModels.core.ports import PortState
+from PythonModels.core.metadata import ParameterDefinition
+from PythonModels.core.ports import PortDefinition
 
 
 class Orifice(AlgebraicComponent):
     """Python port of ModelicaModels.Myorifice."""
 
-    def __init__(self, name: str, opening: float = 1.0, K: float = 1e-7) -> None:
+    MODEL_TYPE = "orifice"
+    PORTS = (
+        PortDefinition.pneumatic("port_a", nominal_role="inlet"),
+        PortDefinition.pneumatic("port_b", nominal_role="outlet"),
+    )
+    PARAMETERS = (
+        ParameterDefinition(
+            "K",
+            1e-5,
+            label="流量系数",
+            quantity="flow_coefficient",
+            unit="kg/(s*Pa^0.5)",
+            minimum=0.0,
+        ),
+        ParameterDefinition(
+            "opening",
+            1.0,
+            label="开度",
+            minimum=0.0,
+            maximum=1.0,
+        ),
+    )
+    RESULT_VARIABLES = ()
+
+    def __init__(self, name: str, opening: float = 1.0, K: float = 1e-5) -> None:
         super().__init__(name=name)
+        self.set_parameter_values({"K": K, "opening": opening})
         self.opening = opening
         self.K = K
-        self.port_a = self.register_port(
-            PortState.pneumatic("port_a", nominal_role="inlet")
-        )
-        self.port_b = self.register_port(
-            PortState.pneumatic("port_b", nominal_role="outlet")
-        )
+        self.port_a = self.register_declared_port("port_a")
+        self.port_b = self.register_declared_port("port_b")
 
     @property
     def K_eff(self) -> float:

PythonModels/components/pipe.py

@@ -2,16 +2,71 @@ from __future__ import annotations
 
 from collections.abc import Mapping
 
-from PythonModels.core.base import DynamicComponent
+from PythonModels.core.base import ThermodynamicVolumeComponent
 from PythonModels.core.equations import EquationResidual
+from PythonModels.core.metadata import (
+    ParameterDefinition,
+    THERMODYNAMIC_VOLUME_RESULT_VARIABLES,
+)
 from PythonModels.core.medium import IdealGasMedium, ThermodynamicProperties
-from PythonModels.core.ports import PortState
+from PythonModels.core.ports import PortDefinition
 from PythonModels.core.state import VolumeState
 
 
-class Pipe(DynamicComponent):
+class Pipe(ThermodynamicVolumeComponent):
     """Python port of ModelicaModels.Mypipe."""
 
+    MODEL_TYPE = "pipe"
+    PORTS = (
+        PortDefinition.pneumatic("port_a", nominal_role="inlet"),
+        PortDefinition.pneumatic("port_b", nominal_role="outlet"),
+    )
+    PARAMETERS = (
+        ParameterDefinition(
+            "length",
+            5.0,
+            label="长度",
+            quantity="length",
+            unit="m",
+            minimum=0.0,
+            minimum_exclusive=True,
+        ),
+        ParameterDefinition(
+            "diameter",
+            0.02,
+            label="直径",
+            quantity="length",
+            unit="m",
+            minimum=0.0,
+            minimum_exclusive=True,
+        ),
+        ParameterDefinition(
+            "lambda_darcy",
+            0.02,
+            label="摩阻系数",
+            minimum=0.0,
+        ),
+        ParameterDefinition(
+            "p0",
+            1e5,
+            label="初始压力",
+            quantity="pressure",
+            unit="Pa",
+            minimum=0.0,
+            minimum_exclusive=True,
+        ),
+        ParameterDefinition(
+            "T0",
+            300.0,
+            label="初始温度",
+            quantity="temperature",
+            unit="K",
+            minimum=0.0,
+            minimum_exclusive=True,
+        ),
+    )
+    RESULT_VARIABLES = THERMODYNAMIC_VOLUME_RESULT_VARIABLES
+
     def __init__(
         self,
         name: str,
@@ -23,6 +78,15 @@ class Pipe(DynamicComponent):
         T0: float = 300.0,
     ) -> None:
         super().__init__(name=name)
+        self.set_parameter_values(
+            {
+                "length": L,
+                "diameter": D,
+                "lambda_darcy": lambda_darcy,
+                "p0": p0,
+                "T0": T0,
+            }
+        )
         self.medium = medium
         self.L = L
         self.D = D
@@ -32,12 +96,8 @@ class Pipe(DynamicComponent):
         m0 = p0 * self.V / (medium.R_gas * T0)
         U0 = m0 * medium.specific_internal_energy(T0)
         self.state = VolumeState(m=m0, U=U0)
-        self.port_a = self.register_port(
-            PortState.pneumatic("port_a", nominal_role="inlet")
-        )
-        self.port_b = self.register_port(
-            PortState.pneumatic("port_b", nominal_role="outlet")
-        )
+        self.port_a = self.register_declared_port("port_a")
+        self.port_b = self.register_declared_port("port_b")
 
     def get_state_vector(self) -> list[float]:
         return self.state.as_vector()

PythonModels/components/resistive_pipe.py

@@ -5,13 +5,65 @@ from math import pi
 
 from PythonModels.core.base import AlgebraicComponent
 from PythonModels.core.equations import EquationResidual
+from PythonModels.core.metadata import ParameterDefinition
 from PythonModels.core.medium import IdealGasMedium
-from PythonModels.core.ports import PortState
+from PythonModels.core.ports import PortDefinition
 
 
 class ResistivePipe(AlgebraicComponent):
     """Quasi-steady Darcy resistance used by topology-driven simulation."""
 
+    MODEL_TYPE = "pipe"
+    PORTS = (
+        PortDefinition.pneumatic("port_a", nominal_role="inlet"),
+        PortDefinition.pneumatic("port_b", nominal_role="outlet"),
+    )
+    PARAMETERS = (
+        ParameterDefinition(
+            "length",
+            5.0,
+            label="长度",
+            quantity="length",
+            unit="m",
+            minimum=0.0,
+            minimum_exclusive=True,
+        ),
+        ParameterDefinition(
+            "diameter",
+            0.02,
+            label="直径",
+            quantity="length",
+            unit="m",
+            minimum=0.0,
+            minimum_exclusive=True,
+        ),
+        ParameterDefinition(
+            "lambda_darcy",
+            0.02,
+            label="摩阻系数",
+            minimum=0.0,
+        ),
+        ParameterDefinition(
+            "p0",
+            1e5,
+            label="初始压力",
+            quantity="pressure",
+            unit="Pa",
+            minimum=0.0,
+            minimum_exclusive=True,
+        ),
+        ParameterDefinition(
+            "T0",
+            300.0,
+            label="初始温度",
+            quantity="temperature",
+            unit="K",
+            minimum=0.0,
+            minimum_exclusive=True,
+        ),
+    )
+    RESULT_VARIABLES = ()
+
     def __init__(
         self,
         name: str,
@@ -23,6 +75,15 @@ class ResistivePipe(AlgebraicComponent):
         T0: float = 300.0,
     ) -> None:
         super().__init__(name=name)
+        self.set_parameter_values(
+            {
+                "length": L,
+                "diameter": D,
+                "lambda_darcy": lambda_darcy,
+                "p0": p0,
+                "T0": T0,
+            }
+        )
         self.medium = medium
         self.L = L
         self.D = D
@@ -32,15 +93,13 @@ class ResistivePipe(AlgebraicComponent):
         self.area = pi * D * D / 4.0
         initial_h = medium.specific_enthalpy(T0)
 
-        self.port_a = PortState.pneumatic("port_a", nominal_role="inlet")
+        self.port_a = self.register_declared_port("port_a")
         self.port_a.p = p0
         self.port_a.h_outflow = initial_h
-        self.register_port(self.port_a)
 
-        self.port_b = PortState.pneumatic("port_b", nominal_role="outlet")
+        self.port_b = self.register_declared_port("port_b")
         self.port_b.p = p0
         self.port_b.h_outflow = initial_h
-        self.register_port(self.port_b)
 
     def pressure_drop(self, m_flow_a: float, p_a: float, p_b: float) -> float:
         average_pressure = max(0.5 * (p_a + p_b), 1.0)

PythonModels/components/tank.py

@@ -2,16 +2,53 @@ from __future__ import annotations
 
 from collections.abc import Mapping
 
-from PythonModels.core.base import DynamicComponent
+from PythonModels.core.base import ThermodynamicVolumeComponent
 from PythonModels.core.equations import EquationResidual
+from PythonModels.core.metadata import (
+    ParameterDefinition,
+    THERMODYNAMIC_VOLUME_RESULT_VARIABLES,
+)
 from PythonModels.core.medium import IdealGasMedium, ThermodynamicProperties
-from PythonModels.core.ports import PortState
+from PythonModels.core.ports import PortDefinition
 from PythonModels.core.state import VolumeState
 
 
-class Tank(DynamicComponent):
+class Tank(ThermodynamicVolumeComponent):
     """Python port of ModelicaModels.Mytank."""
 
+    MODEL_TYPE = "tank"
+    PORTS = (PortDefinition.pneumatic("port_a", nominal_role="inlet"),)
+    PARAMETERS = (
+        ParameterDefinition(
+            "volume",
+            0.1,
+            label="容积",
+            quantity="volume",
+            unit="m3",
+            minimum=0.0,
+            minimum_exclusive=True,
+        ),
+        ParameterDefinition(
+            "p0",
+            1e5,
+            label="初始压力",
+            quantity="pressure",
+            unit="Pa",
+            minimum=0.0,
+            minimum_exclusive=True,
+        ),
+        ParameterDefinition(
+            "T0",
+            300.0,
+            label="初始温度",
+            quantity="temperature",
+            unit="K",
+            minimum=0.0,
+            minimum_exclusive=True,
+        ),
+    )
+    RESULT_VARIABLES = THERMODYNAMIC_VOLUME_RESULT_VARIABLES
+
     def __init__(
         self,
         name: str,
@@ -21,14 +58,13 @@ class Tank(DynamicComponent):
         T0: float = 300.0,
     ) -> None:
         super().__init__(name=name)
+        self.set_parameter_values({"volume": V, "p0": p0, "T0": T0})
         self.medium = medium
         self.V = V
         m0 = p0 * V / (medium.R_gas * T0)
         U0 = m0 * medium.specific_internal_energy(T0)
         self.state = VolumeState(m=m0, U=U0)
-        self.port_a = self.register_port(
-            PortState.pneumatic("port_a", nominal_role="inlet")
-        )
+        self.port_a = self.register_declared_port("port_a")
 
     def get_state_vector(self) -> list[float]:
         return self.state.as_vector()

PythonModels/components/tee.py

@@ -4,23 +4,27 @@ from collections.abc import Mapping
 
 from PythonModels.core.base import AlgebraicComponent
 from PythonModels.core.equations import EquationResidual
-from PythonModels.core.ports import PortState
+from PythonModels.core.ports import PortDefinition
 
 
 class Tee(AlgebraicComponent):
     """Python port of ModelicaModels.Mytee."""
 
+    MODEL_TYPE = "tee"
+    PORTS = (
+        PortDefinition.pneumatic("port_in", nominal_role="bidirectional"),
+        PortDefinition.pneumatic("port_out1", nominal_role="bidirectional"),
+        PortDefinition.pneumatic("port_out2", nominal_role="bidirectional"),
+    )
+    PARAMETERS = ()
+    RESULT_VARIABLES = ()
+
     def __init__(self, name: str) -> None:
         super().__init__(name=name)
-        self.port_in = self.register_port(
-            PortState.pneumatic("port_in", nominal_role="bidirectional")
-        )
-        self.port_out1 = self.register_port(
-            PortState.pneumatic("port_out1", nominal_role="bidirectional")
-        )
-        self.port_out2 = self.register_port(
-            PortState.pneumatic("port_out2", nominal_role="bidirectional")
-        )
+        self.set_parameter_values({})
+        self.port_in = self.register_declared_port("port_in")
+        self.port_out1 = self.register_declared_port("port_out1")
+        self.port_out2 = self.register_declared_port("port_out2")
 
     def pressure_flow_equation_residuals(self) -> tuple[EquationResidual, ...]:
         return (

PythonModels/core/base.py

@@ -2,17 +2,29 @@ from __future__ import annotations
 
 from abc import ABC, abstractmethod
 from collections.abc import Mapping
-from typing import Any
+from typing import Any, ClassVar
 
 from PythonModels.core.equations import EquationResidual
+from PythonModels.core.metadata import (
+    ParameterDefinition,
+    ResultVariableDefinition,
+    ResultVariableMetadata,
+    THERMODYNAMIC_VOLUME_RESULT_VARIABLES,
+)
 from PythonModels.core.ports import PortDefinition, PortState
 
 
 class Component(ABC):
+    MODEL_TYPE: ClassVar[str | None] = None
+    PORTS: ClassVar[tuple[PortDefinition, ...]] = ()
+    PARAMETERS: ClassVar[tuple[ParameterDefinition, ...]] = ()
+    RESULT_VARIABLES: ClassVar[tuple[ResultVariableDefinition, ...]] = ()
+
     def __init__(self, name: str) -> None:
         self.name = name
-        self.model_type = self.__class__.__name__.lower()
+        self.model_type = self.MODEL_TYPE or self.__class__.__name__.lower()
         self._ports: dict[str, PortState] = {}
+        self._parameter_values: dict[str, float] = {}
 
     @property
     def ports(self) -> dict[str, PortState]:
@@ -35,12 +47,133 @@ class Component(ABC):
         self._ports[definition.name] = port
         return port
 
+    def register_declared_port(self, name: str) -> PortState:
+        try:
+            definition = next(item for item in self.PORTS if item.name == name)
+        except StopIteration as exc:
+            raise ValueError(
+                f"Component model {self.model_type} does not declare port {name}."
+            ) from exc
+        return self.register_port(PortState(definition=definition))
+
+    def set_parameter_values(self, values: Mapping[str, float]) -> None:
+        definitions = {definition.name: definition for definition in self.PARAMETERS}
+        unknown = sorted(set(values) - set(definitions))
+        if unknown:
+            raise ValueError(
+                f"Component {self.name} contains unsupported parameters: "
+                + ", ".join(unknown)
+                + "."
+            )
+        missing = sorted(set(definitions) - set(values))
+        if missing:
+            raise ValueError(
+                f"Component {self.name} is missing parameters: "
+                + ", ".join(missing)
+                + "."
+            )
+
+        resolved: dict[str, float] = {}
+        for name, definition in definitions.items():
+            value = float(values[name])
+            message = definition.validation_message(value)
+            if message is not None:
+                raise ValueError(
+                    f"Parameter '{name}' on component '{self.name}' {message}."
+                )
+            resolved[name] = value
+        self._parameter_values = resolved
+
+    @property
+    def parameter_values(self) -> dict[str, float]:
+        return dict(self._parameter_values)
+
     def get_port(self, name: str) -> PortState:
         try:
             return self._ports[name]
         except KeyError as exc:
             raise ValueError(f"Component {self.name} has no port named {name}.") from exc
 
+    def component_result_values(self) -> Mapping[str, float]:
+        return {}
+
+    def result_values(self) -> dict[str, float]:
+        component_values = dict(self.component_result_values())
+        declared = {definition.name: definition for definition in self.RESULT_VARIABLES}
+        unknown = sorted(set(component_values) - set(declared))
+        if unknown:
+            raise ValueError(
+                f"Component {self.name} returned undeclared result variables: "
+                + ", ".join(unknown)
+                + "."
+            )
+
+        values: dict[str, float] = {}
+        for name, definition in declared.items():
+            if not definition.visible:
+                continue
+            if name not in component_values:
+                raise ValueError(
+                    f"Component {self.name} did not provide declared result variable {name}."
+                )
+            values[name] = float(component_values[name])
+
+        for port_definition in self.port_definitions:
+            port = self.get_port(port_definition.name)
+            for variable in port_definition.variables:
+                if not variable.result_visible:
+                    continue
+                values[f"{port_definition.name}.{variable.name}"] = float(
+                    getattr(port, variable.name)
+                )
+        return values
+
+    def result_variable_metadata(self) -> tuple[ResultVariableMetadata, ...]:
+        metadata = [
+            ResultVariableMetadata(
+                key=f"{self.name}.{definition.name}",
+                component_id=self.name,
+                component_type=self.model_type,
+                scope="component",
+                name=definition.name,
+                label=definition.label,
+                quantity=definition.quantity,
+                unit=definition.unit,
+                category=definition.category,
+                order=definition.order,
+            )
+            for definition in self.RESULT_VARIABLES
+            if definition.visible
+        ]
+        for port_definition in self.port_definitions:
+            for variable in port_definition.variables:
+                if not variable.result_visible:
+                    continue
+                metadata.append(
+                    ResultVariableMetadata(
+                        key=f"{self.name}.{port_definition.name}.{variable.name}",
+                        component_id=self.name,
+                        component_type=self.model_type,
+                        scope="port",
+                        port_name=port_definition.name,
+                        name=variable.name,
+                        label=variable.label or variable.name,
+                        quantity=variable.quantity or variable.name,
+                        unit=variable.unit,
+                        category=variable.role,
+                        order=variable.order,
+                    )
+                )
+        return tuple(metadata)
+
+    def parameter_interface_dicts(self) -> list[dict[str, object]]:
+        return [
+            definition.as_interface_dict(
+                value=self._parameter_values.get(definition.name)
+            )
+            for definition in self.PARAMETERS
+        ]
+
     def pressure_flow_equation_residuals(self) -> tuple[EquationResidual, ...]:
         """Return algebraic residuals after the network assigns port states."""
 
@@ -97,5 +230,28 @@ class DynamicComponent(Component):
         raise NotImplementedError
 
 
+class ThermodynamicVolumeComponent(DynamicComponent):
+    """Two-state gas volume exposing the shared thermodynamic result contract."""
+
+    RESULT_VARIABLES = THERMODYNAMIC_VOLUME_RESULT_VARIABLES
+
+    def component_result_values(self) -> Mapping[str, float]:
+        state = self.get_state_vector()
+        if len(state) < 2:
+            raise ValueError(
+                f"Thermodynamic component {self.name} must expose mass and energy states."
+            )
+        properties = self.refresh_thermodynamic_ports()
+        return {
+            "m": float(state[0]),
+            "U": float(state[1]),
+            "p": float(properties.p),
+            "T": float(properties.T),
+            "rho": float(properties.rho),
+            "u": float(properties.u),
+            "h": float(properties.h),
+        }
+
+
 class AlgebraicComponent(Component):
     """Stateless element described by algebraic constraints only."""

PythonModels/core/metadata.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from math import isfinite
+from typing import Literal
+
+
+ResultVariableScope = Literal["component", "port"]
+
+
+@dataclass(frozen=True)
+class ParameterDefinition:
+    """User-configurable model input expressed in the backend SI contract."""
+
+    name: str
+    default: float
+    label: str = ""
+    quantity: str = "dimensionless"
+    unit: str = ""
+    minimum: float | None = None
+    maximum: float | None = None
+    minimum_exclusive: bool = False
+
+    def validation_message(self, value: float) -> str | None:
+        if not isfinite(value):
+            return "must be finite"
+        if self.minimum is not None:
+            if self.minimum_exclusive and value <= self.minimum:
+                return f"must be greater than {self.minimum:g}"
+            if not self.minimum_exclusive and value < self.minimum:
+                return f"must be at least {self.minimum:g}"
+        if self.maximum is not None and value > self.maximum:
+            return f"must be at most {self.maximum:g}"
+        return None
+
+    def as_interface_dict(self, *, value: float | None = None) -> dict[str, object]:
+        payload: dict[str, object] = {
+            "name": self.name,
+            "label": self.label or self.name,
+            "quantity": self.quantity,
+            "unit": self.unit,
+            "default": self.default,
+            "minimumExclusive": self.minimum_exclusive,
+        }
+        if self.minimum is not None:
+            payload["minimum"] = self.minimum
+        if self.maximum is not None:
+            payload["maximum"] = self.maximum
+        if value is not None:
+            payload["value"] = value
+        return payload
+
+
+@dataclass(frozen=True)
+class ResultVariableDefinition:
+    """Component-relative declaration of a user-visible simulation result."""
+
+    name: str
+    label: str
+    quantity: str
+    unit: str = ""
+    category: str = "derived"
+    order: int = 0
+    visible: bool = True
+
+
+@dataclass(frozen=True)
+class ResultVariableMetadata:
+    """A result declaration bound to one concrete component instance."""
+
+    key: str
+    component_id: str
+    component_type: str
+    scope: ResultVariableScope
+    name: str
+    label: str
+    quantity: str
+    unit: str
+    category: str
+    order: int
+    port_name: str | None = None
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "key": self.key,
+            "componentId": self.component_id,
+            "componentType": self.component_type,
+            "scope": self.scope,
+            "portName": self.port_name,
+            "name": self.name,
+            "label": self.label,
+            "quantity": self.quantity,
+            "unit": self.unit,
+            "category": self.category,
+            "order": self.order,
+        }
+
+
+THERMODYNAMIC_VOLUME_RESULT_VARIABLES = (
+    ResultVariableDefinition(
+        name="m",
+        label="质量",
+        quantity="mass",
+        unit="kg",
+        category="state",
+        order=10,
+    ),
+    ResultVariableDefinition(
+        name="U",
+        label="内能",
+        quantity="internal_energy",
+        unit="J",
+        category="state",
+        order=20,
+    ),
+    ResultVariableDefinition(
+        name="p",
+        label="压力",
+        quantity="pressure",
+        unit="Pa",
+        category="thermodynamic",
+        order=30,
+    ),
+    ResultVariableDefinition(
+        name="T",
+        label="温度",
+        quantity="temperature",
+        unit="K",
+        category="thermodynamic",
+        order=40,
+    ),
+    ResultVariableDefinition(
+        name="rho",
+        label="密度",
+        quantity="density",
+        unit="kg/m³",
+        category="thermodynamic",
+        order=50,
+    ),
+    ResultVariableDefinition(
+        name="u",
+        label="比内能",
+        quantity="specific_internal_energy",
+        unit="J/kg",
+        category="thermodynamic",
+        order=60,
+    ),
+    ResultVariableDefinition(
+        name="h",
+        label="比焓",
+        quantity="specific_enthalpy",
+        unit="J/kg",
+        category="thermodynamic",
+        order=70,
+    ),
+)

PythonModels/core/network.py

@@ -4,6 +4,7 @@ from dataclasses import dataclass
 
 from PythonModels.core.base import Component, DynamicComponent
 from PythonModels.core.equations import EquationResidual
+from PythonModels.core.metadata import ResultVariableMetadata
 from PythonModels.core.ports import PortState
 
 
@@ -257,6 +258,13 @@ class SimulationNetwork:
         if cursor != len(values):
             raise ValueError("State vector length does not match dynamic components.")
 
+    def result_variable_metadata(self) -> tuple[ResultVariableMetadata, ...]:
+        return tuple(
+            variable
+            for component in self.components.values()
+            for variable in component.result_variable_metadata()
+        )
+
     def summary(self) -> str:
         lines = [f"Network: {self.name}", "Components:"]
         for name, component in self.components.items():
@@ -281,10 +289,15 @@ class SimulationNetwork:
                 {
                     "id": component.name,
                     "type": component.model_type,
+                    "parameters": component.parameter_interface_dicts(),
                     "ports": [
                         definition.as_interface_dict()
                         for definition in component.port_definitions
                     ],
+                    "resultVariables": [
+                        variable.as_dict()
+                        for variable in component.result_variable_metadata()
+                    ],
                 }
                 for component in self.components.values()
             ],

PythonModels/core/ports.py

@@ -16,12 +16,22 @@ class PortVariableDefinition:
     name: str
     role: VariableRole
     connection_rule: ConnectionRule
+    label: str = field(default="", compare=False)
+    quantity: str = field(default="", compare=False)
+    unit: str = field(default="", compare=False)
+    result_visible: bool = field(default=True, compare=False)
+    order: int = field(default=0, compare=False)
 
-    def as_interface_dict(self) -> dict[str, str]:
+    def as_interface_dict(self) -> dict[str, object]:
         return {
             "name": self.name,
             "role": self.role,
             "connectionRule": self.connection_rule,
+            "label": self.label or self.name,
+            "quantity": self.quantity or self.name,
+            "unit": self.unit,
+            "resultVisible": self.result_visible,
+            "order": self.order,
         }
 
 
@@ -50,9 +60,33 @@ class PortDefinition:
             nominal_role=nominal_role,
             positive_flow_direction="intoComponent",
             variables=(
-                PortVariableDefinition("p", "effort", "equal"),
-                PortVariableDefinition("m_flow", "flow", "sumToZero"),
-                PortVariableDefinition("h_outflow", "stream", "streamMix"),
+                PortVariableDefinition(
+                    "p",
+                    "effort",
+                    "equal",
+                    label="压力",
+                    quantity="pressure",
+                    unit="Pa",
+                    order=10,
+                ),
+                PortVariableDefinition(
+                    "m_flow",
+                    "flow",
+                    "sumToZero",
+                    label="质量流量",
+                    quantity="mass_flow",
+                    unit="kg/s",
+                    order=20,
+                ),
+                PortVariableDefinition(
+                    "h_outflow",
+                    "stream",
+                    "streamMix",
+                    label="流出比焓",
+                    quantity="specific_enthalpy",
+                    unit="J/kg",
+                    order=30,
+                ),
             ),
         )
 

PythonModels/core/solver.py

@@ -1,7 +1,16 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Callable
+from typing import Callable, Literal
+
+
+CancellationCheck = Callable[[], bool]
+AcceptedStepCallback = Callable[[float], None]
+IntegrationStatus = Literal["completed", "cancelled", "failed"]
+
+
+class _IntegrationCancelled(Exception):
+    pass
 
 
 @dataclass(frozen=True)
@@ -20,17 +29,34 @@ class ODESolution:
     y: list[list[float]]
     success: bool
     message: str
+    status: IntegrationStatus = "completed"
+    error: Exception | None = None
 
 
 def _vector_add(a: list[float], b: list[float], scale: float = 1.0) -> list[float]:
     return [x + scale * y for x, y in zip(a, b)]
 
 
+def _append_solution_sample(
+    times: list[float],
+    states: list[list[float]],
+    time: float,
+    state: list[float],
+) -> None:
+    if times and time <= times[-1] + 1e-12:
+        return
+    times.append(float(time))
+    for index, value in enumerate(state):
+        states[index].append(float(value))
+
+
 def _runge_kutta_4(
     rhs: Callable[[float, list[float]], list[float]],
     initial_state: list[float],
     config: SolveIVPConfig,
     t_eval: list[float] | None,
+    cancel_check: CancellationCheck | None = None,
+    accepted_step_callback: AcceptedStepCallback | None = None,
 ) -> ODESolution:
     if t_eval is None:
         point_count = max(
@@ -44,29 +70,189 @@ def _runge_kutta_4(
     states = [[value] for value in state]
     times = [float(t_eval[0])]
     current_time = float(t_eval[0])
+    status: IntegrationStatus = "completed"
+    message = "Integrated with built-in RK4 fallback because SciPy is unavailable."
+    error: Exception | None = None
 
-    for target_time in t_eval[1:]:
-        while current_time < target_time - 1e-15:
-            dt = min(config.max_step, target_time - current_time)
-            k1 = rhs(current_time, state)
-            k2 = rhs(current_time + 0.5 * dt, _vector_add(state, k1, 0.5 * dt))
-            k3 = rhs(current_time + 0.5 * dt, _vector_add(state, k2, 0.5 * dt))
-            k4 = rhs(current_time + dt, _vector_add(state, k3, dt))
-            state = [
-                value + (dt / 6.0) * (a + 2.0 * b + 2.0 * c + d)
-                for value, a, b, c, d in zip(state, k1, k2, k3, k4)
-            ]
-            current_time += dt
+    try:
+        for target_time in t_eval[1:]:
+            while current_time < target_time - 1e-15:
+                if cancel_check is not None and cancel_check():
+                    raise _IntegrationCancelled
+                dt = min(config.max_step, target_time - current_time)
+                k1 = rhs(current_time, state)
+                k2 = rhs(current_time + 0.5 * dt, _vector_add(state, k1, 0.5 * dt))
+                k3 = rhs(current_time + 0.5 * dt, _vector_add(state, k2, 0.5 * dt))
+                k4 = rhs(current_time + dt, _vector_add(state, k3, dt))
+                state = [
+                    value + (dt / 6.0) * (a + 2.0 * b + 2.0 * c + d)
+                    for value, a, b, c, d in zip(state, k1, k2, k3, k4)
+                ]
+                current_time += dt
+                if accepted_step_callback is not None:
+                    accepted_step_callback(current_time)
 
-        times.append(float(target_time))
-        for index, value in enumerate(state):
-            states[index].append(value)
+            _append_solution_sample(times, states, target_time, state)
+    except _IntegrationCancelled:
+        status = "cancelled"
+        message = "Simulation was stopped before reaching the requested end time."
+        _append_solution_sample(times, states, current_time, state)
+    except Exception as exc:
+        status = "failed"
+        message = str(exc)
+        error = exc
+        _append_solution_sample(times, states, current_time, state)
 
     return ODESolution(
         t=times,
         y=states,
-        success=True,
-        message="Integrated with built-in RK4 fallback because SciPy is unavailable.",
+        success=status == "completed",
+        message=message,
+        status=status,
+        error=error,
+    )
+
+
+def _integrate_scipy_stepwise(
+    rhs: Callable[[float, list[float]], list[float]],
+    initial_state: list[float],
+    config: SolveIVPConfig,
+    t_eval: list[float] | None,
+    cancel_check: CancellationCheck,
+    accepted_step_callback: AcceptedStepCallback | None,
+) -> ODESolution:
+    import numpy as np
+    from scipy.integrate import BDF, DOP853, LSODA, RK23, RK45, Radau
+
+    solver_types = {
+        "BDF": BDF,
+        "DOP853": DOP853,
+        "LSODA": LSODA,
+        "RK23": RK23,
+        "RK45": RK45,
+        "Radau": Radau,
+    }
+    solver_type = solver_types.get(config.method)
+    if solver_type is None:
+        raise ValueError(f"Unsupported integration method: {config.method}")
+
+    times = [float(config.t_start)]
+    states = [[float(value)] for value in initial_state]
+    last_accepted_time = float(config.t_start)
+    last_accepted_state = [float(value) for value in initial_state]
+    sample_times = list(t_eval or [])
+    sample_index = 0
+    while (
+        sample_index < len(sample_times)
+        and sample_times[sample_index] <= config.t_start + 1e-12
+    ):
+        sample_index += 1
+
+    def cancellable_rhs(time, state):
+        if cancel_check():
+            raise _IntegrationCancelled
+        return rhs(float(time), [float(value) for value in state])
+
+    if cancel_check():
+        return ODESolution(
+            t=times,
+            y=states,
+            success=False,
+            message="Simulation was stopped before integration started.",
+            status="cancelled",
+        )
+
+    try:
+        solver = solver_type(
+            cancellable_rhs,
+            config.t_start,
+            np.asarray(initial_state, dtype=float),
+            config.t_stop,
+            rtol=config.rtol,
+            atol=config.atol,
+            max_step=config.max_step,
+        )
+    except _IntegrationCancelled:
+        return ODESolution(
+            t=times,
+            y=states,
+            success=False,
+            message="Simulation was stopped before integration started.",
+            status="cancelled",
+        )
+    except Exception as exc:
+        return ODESolution(
+            t=times,
+            y=states,
+            success=False,
+            message=str(exc),
+            status="failed",
+            error=exc,
+        )
+
+    status: IntegrationStatus = "completed"
+    message = "The solver successfully reached the end of the integration interval."
+    error: Exception | None = None
+
+    while solver.status == "running":
+        if cancel_check():
+            status = "cancelled"
+            message = "Simulation was stopped before reaching the requested end time."
+            break
+        try:
+            step_message = solver.step()
+        except _IntegrationCancelled:
+            status = "cancelled"
+            message = "Simulation was stopped before reaching the requested end time."
+            break
+        except Exception as exc:
+            status = "failed"
+            message = str(exc)
+            error = exc
+            break
+
+        if solver.status == "failed":
+            status = "failed"
+            message = str(step_message or "Integration step failed.")
+            break
+
+        last_accepted_time = float(solver.t)
+        last_accepted_state = [float(value) for value in solver.y]
+        if sample_times:
+            dense_output = solver.dense_output()
+            while (
+                sample_index < len(sample_times)
+                and sample_times[sample_index] <= last_accepted_time + 1e-12
+            ):
+                sample_time = float(sample_times[sample_index])
+                sample_state = [float(value) for value in dense_output(sample_time)]
+                _append_solution_sample(times, states, sample_time, sample_state)
+                sample_index += 1
+        else:
+            _append_solution_sample(
+                times,
+                states,
+                last_accepted_time,
+                last_accepted_state,
+            )
+        if accepted_step_callback is not None:
+            accepted_step_callback(last_accepted_time)
+
+    if status != "completed":
+        _append_solution_sample(
+            times,
+            states,
+            last_accepted_time,
+            last_accepted_state,
+        )
+
+    return ODESolution(
+        t=times,
+        y=states,
+        success=status == "completed",
+        message=message,
+        status=status,
+        error=error,
     )
 
 
@@ -75,6 +261,8 @@ def integrate_ode(
     initial_state: list[float],
     config: SolveIVPConfig,
     t_eval: list[float] | None = None,
+    cancel_check: CancellationCheck | None = None,
+    accepted_step_callback: AcceptedStepCallback | None = None,
 ):
     """Thin wrapper around scipy.integrate.solve_ivp with a pure-Python fallback."""
 
@@ -89,7 +277,24 @@ def integrate_ode(
     try:
         from scipy.integrate import solve_ivp
     except ImportError:
-        return _runge_kutta_4(rhs, initial_state, config, t_eval)
+        return _runge_kutta_4(
+            rhs,
+            initial_state,
+            config,
+            t_eval,
+            cancel_check,
+            accepted_step_callback,
+        )
+
+    if cancel_check is not None:
+        return _integrate_scipy_stepwise(
+            rhs,
+            initial_state,
+            config,
+            t_eval,
+            cancel_check,
+            accepted_step_callback,
+        )
 
     return solve_ivp(
         fun=rhs,

PythonModels/registry.py

@@ -2,7 +2,6 @@ from __future__ import annotations
 
 from collections.abc import Callable, Mapping
 from dataclasses import dataclass
-from math import isfinite
 
 from PythonModels.components.cylinder import Cylinder
 from PythonModels.components.orifice import Orifice
@@ -10,29 +9,12 @@ from PythonModels.components.resistive_pipe import ResistivePipe
 from PythonModels.components.tank import Tank
 from PythonModels.components.tee import Tee
 from PythonModels.core.base import Component
+from PythonModels.core.metadata import ParameterDefinition
 from PythonModels.core.medium import IdealGasMedium
 from PythonModels.core.ports import PortDefinition
 
 
-@dataclass(frozen=True)
-class ParameterSpec:
-    name: str
-    default: float
-    minimum: float | None = None
-    maximum: float | None = None
-    minimum_exclusive: bool = False
-
-    def validation_message(self, value: float) -> str | None:
-        if not isfinite(value):
-            return "must be finite"
-        if self.minimum is not None:
-            if self.minimum_exclusive and value <= self.minimum:
-                return f"must be greater than {self.minimum:g}"
-            if not self.minimum_exclusive and value < self.minimum:
-                return f"must be at least {self.minimum:g}"
-        if self.maximum is not None and value > self.maximum:
-            return f"must be at most {self.maximum:g}"
-        return None
+ParameterSpec = ParameterDefinition
 
 
 ComponentFactory = Callable[
@@ -45,11 +27,11 @@ ComponentFactory = Callable[
 class ComponentModelSpec:
     model_type: str
     ports: tuple[PortDefinition, ...]
-    parameters: tuple[ParameterSpec, ...]
+    parameters: tuple[ParameterDefinition, ...]
     factory: ComponentFactory
 
     @property
-    def parameter_by_name(self) -> dict[str, ParameterSpec]:
+    def parameter_by_name(self) -> dict[str, ParameterDefinition]:
         return {parameter.name: parameter for parameter in self.parameters}
 
     def create(
@@ -77,6 +59,15 @@ class ComponentModelSpec:
             )
         component = self.factory(name, medium, resolved)
         component.model_type = self.model_type
+        if component.port_definitions != self.ports:
+            raise ValueError(
+                f"Component implementation {self.model_type} does not match "
+                "its declared ports."
+            )
+        if component.parameter_values != resolved:
+            raise ValueError(
+                f"Component implementation {self.model_type} did not preserve its parameters."
+            )
         return component
 
 
@@ -142,60 +133,33 @@ def _tee_factory(
 
 COMPONENT_MODEL_REGISTRY: dict[str, ComponentModelSpec] = {
     "cylinder": ComponentModelSpec(
-        model_type="cylinder",
-        ports=(PortDefinition.pneumatic("port_b", nominal_role="outlet"),),
-        parameters=(
-            ParameterSpec("volume", 0.01, minimum=0.0, minimum_exclusive=True),
-            ParameterSpec("p0", 35e6, minimum=0.0, minimum_exclusive=True),
-            ParameterSpec("T0", 300.0, minimum=0.0, minimum_exclusive=True),
-        ),
+        model_type=Cylinder.MODEL_TYPE,
+        ports=Cylinder.PORTS,
+        parameters=Cylinder.PARAMETERS,
         factory=_cylinder_factory,
     ),
     "tank": ComponentModelSpec(
-        model_type="tank",
-        ports=(PortDefinition.pneumatic("port_a", nominal_role="inlet"),),
-        parameters=(
-            ParameterSpec("volume", 0.1, minimum=0.0, minimum_exclusive=True),
-            ParameterSpec("p0", 1e5, minimum=0.0, minimum_exclusive=True),
-            ParameterSpec("T0", 300.0, minimum=0.0, minimum_exclusive=True),
-        ),
+        model_type=Tank.MODEL_TYPE,
+        ports=Tank.PORTS,
+        parameters=Tank.PARAMETERS,
         factory=_tank_factory,
     ),
     "pipe": ComponentModelSpec(
-        model_type="pipe",
-        ports=(
-            PortDefinition.pneumatic("port_a", nominal_role="inlet"),
-            PortDefinition.pneumatic("port_b", nominal_role="outlet"),
-        ),
-        parameters=(
-            ParameterSpec("length", 5.0, minimum=0.0, minimum_exclusive=True),
-            ParameterSpec("diameter", 0.02, minimum=0.0, minimum_exclusive=True),
-            ParameterSpec("lambda_darcy", 0.02, minimum=0.0),
-            ParameterSpec("p0", 1e5, minimum=0.0, minimum_exclusive=True),
-            ParameterSpec("T0", 300.0, minimum=0.0, minimum_exclusive=True),
-        ),
+        model_type=ResistivePipe.MODEL_TYPE,
+        ports=ResistivePipe.PORTS,
+        parameters=ResistivePipe.PARAMETERS,
         factory=_pipe_factory,
     ),
     "orifice": ComponentModelSpec(
-        model_type="orifice",
-        ports=(
-            PortDefinition.pneumatic("port_a", nominal_role="inlet"),
-            PortDefinition.pneumatic("port_b", nominal_role="outlet"),
-        ),
-        parameters=(
-            ParameterSpec("K", 1e-5, minimum=0.0),
-            ParameterSpec("opening", 1.0, minimum=0.0, maximum=1.0),
-        ),
+        model_type=Orifice.MODEL_TYPE,
+        ports=Orifice.PORTS,
+        parameters=Orifice.PARAMETERS,
         factory=_orifice_factory,
     ),
     "tee": ComponentModelSpec(
-        model_type="tee",
-        ports=(
-            PortDefinition.pneumatic("port_in", nominal_role="bidirectional"),
-            PortDefinition.pneumatic("port_out1", nominal_role="bidirectional"),
-            PortDefinition.pneumatic("port_out2", nominal_role="bidirectional"),
-        ),
-        parameters=(),
+        model_type=Tee.MODEL_TYPE,
+        ports=Tee.PORTS,
+        parameters=Tee.PARAMETERS,
         factory=_tee_factory,
     ),
 }

PythonModels/systems/generic.py

@@ -1,15 +1,23 @@
 from __future__ import annotations
 
+from collections.abc import Callable
 from dataclasses import dataclass
 from math import floor, isfinite
+from typing import Literal
 
 from PythonModels.core.algebraic import PressureFlowSolver
 from PythonModels.core.base import DynamicComponent
+from PythonModels.core.metadata import ResultVariableMetadata
 from PythonModels.core.network import Endpoint, SimulationNetwork
-from PythonModels.core.solver import SolveIVPConfig, integrate_ode
+from PythonModels.core.solver import ODESolution, SolveIVPConfig, integrate_ode
 from PythonModels.core.stream import StreamResolver
 
 
+SimulationProgressCallback = Callable[[float, str], None]
+SimulationCancellationCheck = Callable[[], bool]
+SimulationRunStatus = Literal["completed", "cancelled", "failed"]
+
+
 @dataclass(frozen=True)
 class SimulationPreparationIssue:
     code: str
@@ -28,7 +36,11 @@ class SimulationPreparationError(ValueError):
 @dataclass(frozen=True)
 class GenericSimulationResult:
     success: bool
+    status: SimulationRunStatus
     message: str
+    simulated_until: float
+    requested_stop_time: float
+    variables: tuple[ResultVariableMetadata, ...]
     series: dict[str, list[float]]
     final: dict[str, float]
     diagnostics: dict[str, object]
@@ -36,7 +48,12 @@ class GenericSimulationResult:
     def as_dict(self) -> dict[str, object]:
         return {
             "success": self.success,
+            "status": self.status,
+            "partial": self.status != "completed",
             "message": self.message,
+            "simulatedUntil": self.simulated_until,
+            "requestedStopTime": self.requested_stop_time,
+            "variables": [variable.as_dict() for variable in self.variables],
             "series": self.series,
             "final": self.final,
             "diagnostics": self.diagnostics,
@@ -276,51 +293,121 @@ class GenericFluidSystem:
         return derivatives
 
     def _append_current_state(self, series: dict[str, list[float]]) -> None:
-        for component in self.dynamic_components:
-            properties = component.refresh_thermodynamic_ports()
-            state = component.get_state_vector()
-            if len(state) >= 2:
-                series.setdefault(f"{component.name}.m", []).append(float(state[0]))
-                series.setdefault(f"{component.name}.U", []).append(float(state[1]))
-            for name in ("p", "T", "rho", "u", "h"):
-                if hasattr(properties, name):
-                    series.setdefault(f"{component.name}.{name}", []).append(
-                        float(getattr(properties, name))
-                    )
-
         for component in self.network.components.values():
-            for port_name, port in component.ports.items():
-                prefix = f"{component.name}.{port_name}"
-                series.setdefault(f"{prefix}.p", []).append(float(port.p))
-                series.setdefault(f"{prefix}.m_flow", []).append(float(port.m_flow))
-                series.setdefault(f"{prefix}.h_outflow", []).append(
-                    float(port.h_outflow)
-                )
+            for relative_key, value in component.result_values().items():
+                series.setdefault(
+                    f"{component.name}.{relative_key}", []
+                ).append(value)
 
     def simulate(
         self,
         config: SolveIVPConfig,
         *,
         sample_step: float,
+        progress_callback: SimulationProgressCallback | None = None,
+        cancel_check: SimulationCancellationCheck | None = None,
     ) -> GenericSimulationResult:
+        last_reported_progress = -1.0
+        last_reported_phase = ""
+
+        def report_progress(
+            progress: float,
+            phase: str,
+            *,
+            force: bool = False,
+        ) -> None:
+            nonlocal last_reported_phase, last_reported_progress
+            if progress_callback is None:
+                return
+            bounded_progress = min(1.0, max(0.0, progress))
+            if (
+                force
+                or phase != last_reported_phase
+                or bounded_progress - last_reported_progress >= 0.0025
+            ):
+                last_reported_phase = phase
+                last_reported_progress = max(
+                    last_reported_progress,
+                    bounded_progress,
+                )
+                progress_callback(last_reported_progress, phase)
+
+        report_progress(0.0, "initializing", force=True)
         t_eval = simulation_sample_times(config, sample_step)
         initial_state = self.consistent_initial_state_vector()
+        report_progress(0.0, "integrating", force=True)
+        duration = config.t_stop - config.t_start
+        furthest_solver_time = config.t_start
+
+        def report_solver_time(time: float) -> None:
+            nonlocal furthest_solver_time
+            furthest_solver_time = max(furthest_solver_time, float(time))
+            time_fraction = (
+                (furthest_solver_time - config.t_start) / duration
+                if duration > 0.0
+                else 1.0
+            )
+            report_progress(time_fraction, "integrating")
+
+        def monitored_rhs(time: float, state_vector: list[float]) -> list[float]:
+            if cancel_check is None:
+                report_solver_time(time)
+            return self.rhs(time, state_vector)
+
         solution = integrate_ode(
-            rhs=self.rhs,
+            rhs=monitored_rhs,
             initial_state=initial_state,
             config=config,
             t_eval=t_eval,
+            cancel_check=cancel_check,
+            accepted_step_callback=(
+                report_solver_time if cancel_check is not None else None
+            ),
         )
+        if isinstance(solution, ODESolution):
+            run_status: SimulationRunStatus = solution.status
+            integration_error = solution.error
+        else:
+            run_status = "completed" if bool(solution.success) else "failed"
+            integration_error = None
+        result_message = str(solution.message)
+        postprocess_progress = (
+            1.0
+            if run_status == "completed"
+            else max(0.0, last_reported_progress)
+        )
+        report_progress(postprocess_progress, "postprocessing", force=True)
         times = [float(value) for value in solution.t]
-        series: dict[str, list[float]] = {"time": times}
+        series: dict[str, list[float]] = {"time": []}
+        postprocessing_error: Exception | None = None
         for time_index in range(len(times)):
+            if (
+                run_status == "completed"
+                and cancel_check is not None
+                and cancel_check()
+            ):
+                run_status = "cancelled"
+                result_message = "Simulation was stopped while preparing partial results."
+                break
             state = [
                 float(solution.y[state_index][time_index])
                 for state_index in range(len(solution.y))
             ]
-            self.apply_state_vector(state)
-            self._close_current_state()
-            self._append_current_state(series)
+            try:
+                self.apply_state_vector(state)
+                self._close_current_state()
+                self._append_current_state(series)
+                series["time"].append(times[time_index])
+            except Exception as exc:
+                run_status = "failed"
+                result_message = str(exc)
+                postprocessing_error = exc
+                break
+        if len(series["time"]) < 2:
+            if postprocessing_error is not None:
+                raise postprocessing_error
+            if integration_error is not None:
+                raise integration_error
 
         final = {
             key: values[-1]
@@ -347,11 +434,29 @@ class GenericFluidSystem:
                 ),
             },
             "stateCount": len(initial_state),
-            "sampleCount": len(times),
+            "sampleCount": len(series["time"]),
         }
+        variables = tuple(
+            variable
+            for variable in self.network.result_variable_metadata()
+            if variable.key in series
+        )
+        report_progress(
+            1.0 if run_status == "completed" else max(0.0, last_reported_progress),
+            "complete" if run_status == "completed" else run_status,
+            force=True,
+        )
         return GenericSimulationResult(
-            success=bool(solution.success),
-            message=str(solution.message),
+            success=run_status == "completed" and bool(solution.success),
+            status=run_status,
+            message=result_message,
+            simulated_until=(
+                float(series["time"][-1])
+                if series["time"]
+                else float(config.t_start)
+            ),
+            requested_stop_time=float(config.t_stop),
+            variables=variables,
             series=series,
             final=final,
             diagnostics=diagnostics,