完善系统仿真优化计划交互

新增系统仿真参数优化 Skill
支持后端解析参数表达式并保留工程JSON
2026-09-15 08:32:31 +00:00 · 2026-09-14 09:35:53 +00:00 · 2026-09-03 18:18:47 +08:00
647 changed files with 86665 additions and 285755 deletions
@@ -4,11 +4,7 @@

 # Regression manifests hash these files as raw bytes. Keep their checkout
 # representation identical on Windows and Linux so hashes remain portable.
-tests/baselines/simulation/test_mql_full_branches/sources/test_mql-full-branches-01-04.xml text eol=lf
+tests/data/test-mql-8.xml text eol=lf
+tests/data/test-mql-8.json text eol=lf
+tests/data/test_mql-full-branches-01-04.xml text eol=lf
 tests/baselines/simulation/**/*.json text eol=lf
-
-tests/baselines/simulation/**/sources/* text eol=lf
-
-# Browser projects and relocated native references.
-tests/data/*.json text eol=lf
-tests/baselines/native/*.json text eol=lf
@@ -1,31 +1,58 @@
-name: Native backend regression
+name: Solver regression

 on:
  push:
    paths:
-      - "app/**"
-      - "native/**"
-      - "schemas/**"
+      - "app/simulation/**"
      - "tests/**"
-      - "requirements*.txt"
+      - "requirements.txt"
      - "constraints/**"
      - ".python-version"
      - ".gitattributes"
+      - "README.md"
      - ".github/workflows/solver-regression.yml"
  pull_request:
    paths:
-      - "app/**"
-      - "native/**"
-      - "schemas/**"
+      - "app/simulation/**"
      - "tests/**"
-      - "requirements*.txt"
+      - "requirements.txt"
      - "constraints/**"
      - ".python-version"
      - ".gitattributes"
+      - "README.md"
      - ".github/workflows/solver-regression.yml"
  schedule:
-    - cron: "17 3 * * *"
+    - cron: "17 3 * * 1-6"
+    - cron: "17 3 * * 0"
  workflow_dispatch:
+    inputs:
+      suite:
+        description: Regression tier
+        required: true
+        default: quick
+        type: choice
+        options:
+          - quick
+          - historical
+          - main-long
+      case:
+        description: Longest main-model horizon (predecessors run first)
+        required: true
+        default: 0.2s
+        type: choice
+        options:
+          - 0.2s
+          - 1s
+          - 5s
+          - 10s
+      lane:
+        description: Output sampling lane
+        required: true
+        default: production
+        type: choice
+        options:
+          - solver-only
+          - production

 concurrency:
  group: solver-regression-${{ github.ref }}-${{ github.event_name }}
@@ -35,37 +62,32 @@ permissions:
  contents: read

 jobs:
-  contracts:
-    runs-on: ubuntu-24.04
-    timeout-minutes: 10
+  fixture-byte-contract:
+    if: >-
+      github.event_name == 'push' ||
+      github.event_name == 'pull_request' ||
+      (github.event_name == 'workflow_dispatch' && inputs.suite == 'quick')
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-24.04
+          - windows-2022
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version-file: .python-version
-          cache: pip
-          cache-dependency-path: constraints/python312-linux-x86_64.lock
-      - name: Install backend runtime without numerical Python packages
-        run: |
-          python -m pip install -r constraints/python312-linux-x86_64.lock
-          python -m pip check
-      - name: Validate portable metadata and XML contracts
-        env:
-          SYSTEM_SIMULATION_VERIFY_LOCKED_ENV: "1"
-        run: |
-          python -W error::ResourceWarning -m unittest \
-            tests.test_dependency_constraints \
-            tests.test_regression_fixture_line_endings \
-            tests.test_component_catalog \
-            tests.test_component_metadata \
-            tests.test_component_registry \
-            tests.test_port_computation \
-            tests.test_native_schedule.DependencyGraphTests \
-            tests.test_medium_reference_contract \
-            tests.test_system_xml_v3 \
-            tests.test_native_only_backend
+      - name: Verify portable regression fixture bytes
+        run: python -m unittest tests.test_regression_fixture_line_endings

-  native-linux:
+  quick:
+    if: >-
+      github.event_name == 'push' ||
+      github.event_name == 'pull_request' ||
+      (github.event_name == 'workflow_dispatch' && inputs.suite == 'quick')
    runs-on: ubuntu-24.04
    timeout-minutes: 15
    steps:
@@ -73,67 +95,109 @@ jobs:
      - uses: actions/setup-python@v5
        with:
          python-version-file: .python-version
-      - name: Install native dependencies with the existing Linux setup
+          cache: pip
+          cache-dependency-path: |
+            requirements.txt
+            constraints/python312-direct.txt
+            constraints/python312-linux-x86_64.lock
+      - name: Install hashed Linux release lock
        run: |
-          python -m venv .venv
-          .venv/bin/python -m pip install -r requirements-test.txt
-          bash bat/setup-native-linux.sh
-      - name: Check startup diagnostics, native cache and solver control on Linux
+          python -m pip install \
+            --force-reinstall \
+            -r constraints/python312-linux-x86_64.lock
+          python -m pip check
+      - name: Run solver foundation tests
        env:
-          SIMULATION_NATIVE_REQUIRE_TOOLCHAIN: "1"
+          SYSTEM_SIMULATION_VERIFY_LOCKED_ENV: "1"
        run: |
-          .venv/bin/python -W error::ResourceWarning -m unittest \
-            tests.test_simulation_warmup tests.test_native_cache_platform \
-            tests.test_native_solver_control tests.test_native_worker_control \
-            tests.test_result_storage tests.test_native_sample_storage tests.test_native_result_transport -v
+          python -W error::ResourceWarning -m unittest \
+            tests.test_dependency_constraints \
+            tests.test_benchmark_regression \
+            tests.test_physical_state_v21 \
+            tests.test_test_mql_ame_contract \
+            tests.test_test_mql_8_regression \
+            tests.test_mql_full_branches_regression \
+            tests.test_pressure_flow_causal_execution \
+            tests.test_stream_pressure_block_solver \
+            tests.test_core_solver \
+            tests.test_supported_piston_tangent \
+            tests.test_three_piston_tangent \
+            tests.test_sparse_secant_jacobian \
+            tests.test_generic_jacobian_sparsity \
+            tests.test_generic_system_xml_simulation

-  native-windows:
-    runs-on: windows-2022
-    timeout-minutes: 30
-    defaults:
-      run:
-        shell: pwsh
+  historical-nightly:
+    if: >-
+      (github.event_name == 'schedule' && github.event.schedule == '17 3 * * 1-6') ||
+      (github.event_name == 'workflow_dispatch' && inputs.suite == 'historical')
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
-      - uses: conda-incubator/setup-miniconda@v3
+      - uses: actions/setup-python@v5
        with:
-          python-version: "3.12"
-          activate-environment: simulation-native
-          auto-activate-base: false
-      - name: Install native compiler and SUNDIALS
+          python-version-file: .python-version
+          cache: pip
+          cache-dependency-path: |
+            requirements.txt
+            constraints/python312-direct.txt
+            constraints/python312-linux-x86_64.lock
+      - name: Install hashed Linux release lock
        run: |
-          conda install --yes -c conda-forge sundials=7.4.0 m2w64-gcc
-          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
-          "SUNDIALS_ROOT=$env:CONDA_PREFIX\Library" >> $env:GITHUB_ENV
-          "SIMULATION_NATIVE_CC=$env:CONDA_PREFIX\Library\mingw-w64\bin\gcc.exe" >> $env:GITHUB_ENV
-          python -m pip install -r requirements-test.txt
+          python -m pip install \
+            --force-reinstall \
+            -r constraints/python312-linux-x86_64.lock
          python -m pip check
-      - name: Verify native cache on the Windows runtime
+      - name: Run 0.81 and 2.10 second historical regression
+        run: |
+          mkdir -p artifacts
+          python -m app.simulation.benchmark_regression \
+            --manifest tests/baselines/simulation/test_mql_full_branches/manifest.json \
+            --lane production \
+            --output artifacts/test-mql-full-branches.json
+      - if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: historical-solver-regression
+          path: artifacts/*.json
+          if-no-files-found: warn
+
+  main-periodic:
+    if: >-
+      (github.event_name == 'schedule' && github.event.schedule == '17 3 * * 0') ||
+      (github.event_name == 'workflow_dispatch' && inputs.suite == 'main-long')
+    runs-on: ubuntu-24.04
+    timeout-minutes: 180
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version
+          cache: pip
+          cache-dependency-path: |
+            requirements.txt
+            constraints/python312-direct.txt
+            constraints/python312-linux-x86_64.lock
+      - name: Install hashed Linux release lock
+        run: |
+          python -m pip install \
+            --force-reinstall \
+            -r constraints/python312-linux-x86_64.lock
+          python -m pip check
+      - name: Run bounded progressive main-model regression
        env:
-          SIMULATION_NATIVE_REQUIRE_TOOLCHAIN: "1"
+          REQUESTED_CASE: ${{ github.event_name == 'workflow_dispatch' && inputs.case || '10s' }}
+          REQUESTED_LANE: ${{ github.event_name == 'workflow_dispatch' && inputs.lane || 'production' }}
        run: |
-          New-Item -ItemType Directory -Force test/ci-native-cache | Out-Null
-          python -W error::ResourceWarning -m unittest tests.test_native_cache_storage tests.test_native_cache_platform -v > test/ci-native-cache/regression.log 2>&1
-          $cacheRegressionExit = $LASTEXITCODE
-          Get-Content test/ci-native-cache/regression.log
-          if ($cacheRegressionExit -ne 0) { exit $cacheRegressionExit }
-      - name: Run catalog, numerical, API and schema regression
-        run: |
-          python -c "from app.simulation.native_codegen.build import toolchain; print(toolchain())"
-          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
-          python -W error::ResourceWarning -m unittest discover -s tests
-      - name: Complete the 10 second skill fixture in native RK45
-        run: |
-          python -m app.simulation.native_codegen tests/fixtures/native-skill-test.xml --output-dir test/ci-skill --method RK45 --max-step 0.001 --rtol 1e-7 --runs 1 --solve-only
+          mkdir -p artifacts
+          python -m app.simulation.benchmark_regression \
+            --manifest tests/baselines/simulation/test_mql_8/manifest.json \
+            --lane "$REQUESTED_LANE" \
+            --case "$REQUESTED_CASE" \
+            --output artifacts/test-mql-8-progressive.json
      - if: always()
        uses: actions/upload-artifact@v4
        with:
-          name: native-skill-regression
-          path: test/ci-skill/summary.json
-          if-no-files-found: warn
-      - if: always()
-        uses: actions/upload-artifact@v4
-        with:
-          name: native-windows-cache-regression
-          path: test/ci-native-cache/regression.log
+          name: main-model-progressive-regression
+          path: artifacts/*.json
          if-no-files-found: warn
@@ -15,13 +15,8 @@ htmlcov/

 # Local Linux toolchain (downloaded for the startup scripts)
 .tools/node-*-linux-x64/
-.tools/node-*-win-x64/
-
-# Local benchmark archives, generated executables and comparison outputs
-/test/

 app/data/
-/simresults/
 frontend/node_modules/
 frontend/dist/
 frontend/.vite/
@@ -12,7 +12,7 @@ Python 输出只有通过 AMESim baseline 对比后才能作为数值一致性

 ## 模型与源数据

- AMESim 源模型：`tests/data/AmesimModels/test_mql.ame`
+- AMESim 源模型：`AmesimModels/test_mql.ame`
 - Python 系统类：`app.simulation.examples.test_mql.system.TestMqlSystem`
 - 结构运行入口：`app.simulation.examples.test_mql.run`
 - 132 状态比较入口：`app.simulation.examples.test_mql.run_full_state_comparison`
@@ -4,9 +4,7 @@ ReactFlow 系统建模与 `app.simulation` 仿真后端。

 ## 开发环境准备

-Windows/Linux 的运行、测试、原生工具链及时间剖析依赖，统一见 [平台依赖说明](docs/standard/platform-dependencies.md)。2026-09-16 的 Jacobian 复用与剖析工具继续使用现有 SUNDIALS 7.4.0，本轮未新增运行库依赖；以下安装命令供准备环境时使用。
-
-后端编排层统一使用 Python 3.12；仓库根目录的 `.python-version` 记录本轮参考补丁版本
+后端统一使用 Python 3.12；仓库根目录的 `.python-version` 记录本轮参考补丁版本
 `3.12.3`。`requirements.txt` 保留支持范围，
 `constraints/python312-direct.txt` 固定跨平台开发环境的直接依赖参考版本；
 `constraints/python312-linux-x86_64.lock` 则完整固定发布与 CI 所用的 Linux x86_64
@@ -86,10 +84,6 @@ Linux：

 后端地址为 `http://127.0.0.1:8000`，前端地址为 `http://127.0.0.1:5173`。Windows 的 `start-all.bat` 会分别打开两个命令行窗口；Linux 的 `start-all.sh` 会在同一终端管理两个进程，按 `Ctrl+C` 会同时停止它们。

-网页的 System XML 仿真默认使用 C 内核（`native`）；后端入口和启动脚本使用同一默认值，不需要每次手动设置环境变量。启动日志显示 `Simulation numeric engine: native`，启动预热仅检查 C 工具链和 XML Schema，不执行 Python/SciPy 求解器预热。模型专用 EXE 在提交模型时生成或从缓存复用。
-
-当前 C 构建支持 Windows x64 和 Linux x86_64，已覆盖组件库当前注册的 27 类模型（22 类 Amesim、5 类实验组件）。具体公式范围与连接限制见[原生后端说明](native/README.md)；不支持的自定义模型或未收敛的连接会明确报错，不自动切回 Python。旧 Python 数值后端已删除；Linux 原生工具链安装与静态链接说明见 [C 后端说明](native/README.md)。旧固定拓扑示例接口返回 HTTP 410，请改用统一 XML 接口。
-
 ## 后端接口

 - `GET /api/components/catalog`：返回组件库与模型版本、分类、图标键、端口布局和参数契约，供 ReactFlow 启动时自动加载。
@@ -105,22 +99,16 @@ Linux：

 气动端口的后端契约采用 `p` 势变量相等、`m_flow` 流变量代数和为零、`h_outflow` 按 stream 规则混合。所有组件统一规定 `m_flow > 0` 表示流入组件，物理连接的端点顺序不表示流向。

-当前网络层按端口域处理气动压力/流量与 stream 焓、标量信号传播，以及一维机械 `x/v` 等值和 `f` 平衡。默认 C 后端在生成的 EXE 内完成连接闭合、RK45/CVODE BDF 积分及信号/限位事件。通用仿真仍有已声明的拓扑和物理公式范围，并不等价于完整 Amesim 或 Modelica.Fluid 实现。
+当前网络层可按端口域处理气动压力-流量残差与 stream 焓、标量信号传播，以及一维机械 `x/v` 等值和 `f` 平衡，并使用 SciPy 完成非线性代数闭合和时间积分。XML 通用仿真当前采用半显式 ODE/代数 MVP：气瓶和贮箱作为储能元件，孔板及 XML 管段作为阻性元件，三通作为等压零结点，同时支持已登记的信号和机械基础件。它不是完整 DAE 或事件求解器，也不等价于严格 Modelica.Fluid 实现。

 XML 解析依赖 `lxml` 执行本地 XSD 校验，该依赖已包含在 `requirements.txt` 中。

 ## 文档

 - [开发文档索引](docs/README.md)
- [现行规范索引与新组件注册流程](docs/standard/README.md)
 - [后端接口版本与定义规范 v1](docs/standard/backend-interface-version-spec-v1.md)
 - [组件模型建模规范 v1](docs/standard/component-model-authoring-spec-v1.md)
 - [组件库分类、发现与读取规范 v1](docs/standard/component-library-spec-v1.md)
 - [组件目录 JSON Schema v1](schemas/component-catalog-v1.schema.json)
 - [System XML v3 协议（当前规范）](docs/standard/system-xml-v3.md)
 - [System XML v3 XSD（当前 Schema）](schemas/system-simulation-v3.xsd)
-
-
-旧 Python 积分器、模型数值公式及物性缓存已移除。公共配置、进度和采样校验分别位于 `app/simulation/config.py` 与 `sampling.py`；模型 Python 文件仅保留参数、端口、结果和方程结构声明。质量/能量初值也由 C 计算。
-
-后端运行依赖不再包含 NumPy/SciPy；运行测试请安装 `requirements-test.txt`。Windows C 回归需要配置 GCC 与 SUNDIALS，见 [C 后端说明](native/README.md)。删除范围和验证见 [Python 数值实现退役记录](docs/other/Python数值实现退役记录.md)。
@@ -20,13 +20,16 @@ from xml.etree import ElementTree as ET

 from fastapi import FastAPI, HTTPException, Request, Response
 from fastapi.responses import FileResponse, HTMLResponse, StreamingResponse
-from pydantic import BaseModel, ConfigDict, Field, StrictFloat, StrictStr, ValidationError
-
-from app.project_parameters import prepare_project, version_warning
+from pydantic import BaseModel, ConfigDict, Field, ValidationError

+from app.parameter_expression import (
+    ParameterExpressionError,
+    evaluate_parameter_expression,
+    expression_value_to_base_unit,
+)
 from app.simulation.performance import performance_span, profile_phase, profile_run
-from app.simulation.native_codegen.transport import NativeSeriesJson, serialize_result_parts
-from app.simulation.config import SolverActivityTracker
+from app.simulation.property_cache import property_cache_run
+from app.simulation.solvers.solver import SolverActivityTracker
 from app.system_xml import (
    SystemXmlDocument,
    SystemXmlValidationReport,
@@ -43,22 +46,10 @@ if TYPE_CHECKING:

@asynccontextmanager
 async def _app_lifespan(application: FastAPI) -> AsyncIterator[None]:
-    import logging
+    from app.simulation.warmup import warm_up_simulation_runtime

-    from app.simulation.backends import numeric_engine_name
-    from app.simulation.warmup import SimulationRuntimeCheck
-
-    application.state.simulation_numeric_engine = numeric_engine_name()
-    logging.getLogger("uvicorn.error").info(
-        "Simulation numeric engine: %s", application.state.simulation_numeric_engine,
-    )
-    runtime_check = SimulationRuntimeCheck()
-    application.state.simulation_runtime_check = runtime_check
-    runtime_check.start()
-    try:
+    application.state.simulation_warmup = warm_up_simulation_runtime().as_dict()
    yield
-    finally:
-        runtime_check.close()


 app = FastAPI(
@@ -76,11 +67,6 @@ SimulationProgressEmitter = Callable[
 ]
 SIMULATION_PHASE_MESSAGES = {
    "initializing": "正在初始化状态与方程",
-    "native-generation": "正在生成原生模型代码",
-    "native-cache-check": "正在检查已编译模型缓存",
-    "native-cache-hit": "已复用模型缓存，正在启动求解器",
-    "native-compilation": "正在编译模型与缺失的原生模块",
-    "native-linking": "正在链接模型可执行文件",
    "integrating": "正在进行时间积分与压力流量求解",
    "postprocessing": "正在整理采样结果",
    "cancelled": "正在整理已终止仿真的部分结果",
@@ -154,8 +140,8 @@ class ReactFlowNodeData(BaseModel):
    componentType: str = "component"
    modelType: str = "component"
    # Optional at the storage boundary so an incompatible project can still be
-    # opened and inspected. Input adapters warn and select the current model;
-    # the normalized XML/numerical boundary still enforces an exact match.
+    # opened and inspected. Every execution path requires an exact registry
+    # match before defaults, equations, or ports are consumed.
    modelVersion: str | None = None
    ports: list[ReactFlowPortDefinition] = Field(default_factory=list)
    parameters: dict[str, Any] = Field(default_factory=dict)
@@ -192,17 +178,17 @@ class ReactFlowEdgePayload(BaseModel):


 class ReactFlowSimulationConfig(BaseModel):
-    t_start: StrictFloat | StrictStr = 0.0
-    t_stop: StrictFloat | StrictStr = 2.0
-    step: StrictFloat | StrictStr = 0.1
-    max_step: StrictFloat | StrictStr = 0.005
+    t_start: float = 0.0
+    t_stop: float = 2.0
+    step: float = 0.1
+    max_step: float = 0.005
    method: str = "BDF"


 class ReactFlowProjectPayload(BaseModel):
    model_config = ConfigDict(extra="forbid")

-    projectSchemaVersion: Literal[1, 2]
+    projectSchemaVersion: Literal[1]
    name: str = "untitled"
    nodes: list[ReactFlowNodePayload] = Field(default_factory=list)
    edges: list[ReactFlowEdgePayload] = Field(default_factory=list)
@@ -343,29 +329,13 @@ def get_component_catalog() -> dict[str, object]:
    return build_component_catalog()


-@app.get("/api/simulation/runtime-check")
-def get_simulation_runtime_check(request: Request) -> Response:
-    report = request.app.state.simulation_runtime_check.snapshot()
-    return Response(content=json.dumps(report, ensure_ascii=False), media_type="application/json",
-                    headers={"Cache-Control": "no-store"})
-
-
@app.post("/api/reactflow/system-xml")
 def export_reactflow_system_xml(payload: ReactFlowProjectPayload) -> Response:
    try:
-        normalized, notices = prepare_project(payload)
-        xml = build_reactflow_system_xml(normalized)
+        xml = build_reactflow_system_xml(payload)
    except ValueError as exc:
        raise HTTPException(status_code=400, detail=str(exc)) from exc
-    headers = {}
-    if notices:
-        warning = {**version_warning(notices), "totalCount": len(notices), "components": notices[:10]}
-        encoded = quote(json.dumps(warning, ensure_ascii=False))
-        while len(encoded) > 3800 and warning["components"]:
-            warning["components"] = warning["components"][:-1]
-            encoded = quote(json.dumps(warning, ensure_ascii=False))
-        headers["X-Component-Version-Warnings"] = encoded
-    return Response(content=xml, media_type="application/xml", headers=headers)
+    return Response(content=xml, media_type="application/xml")


@app.post("/api/simulation-results/csv")
@@ -533,11 +503,10 @@ def simulate_reactflow_test_mql(payload: ReactFlowProjectPayload) -> dict[str, o
@app.post("/api/reactflow/compile-model")
 def compile_reactflow_model(payload: ReactFlowProjectPayload) -> dict[str, object]:
    try:
-        normalized, notices = prepare_project(payload)
-        network = compile_reactflow_network(normalized)
+        network = compile_reactflow_network(payload)
    except ValueError as exc:
        raise HTTPException(status_code=400, detail=str(exc)) from exc
-    return {"success": True, **network.as_interface_dict(), "warnings": [version_warning(notices)] if notices else []}
+    return {"success": True, **network.as_interface_dict()}


@app.post("/api/system-xml/validate")
@@ -682,7 +651,7 @@ async def simulate_system_xml_stream(request: Request) -> StreamingResponse:
    simulation_id = request.headers.get("x-simulation-id") or uuid4().hex
    task = _register_simulation_task(simulation_id)
    return StreamingResponse(
-        simulation_event_stream(await request.body(), task=task, raw_series=True),
+        simulation_event_stream(await request.body(), task=task),
        media_type="application/x-ndjson",
        headers={
            "Cache-Control": "no-cache, no-transform",
@@ -709,17 +678,13 @@ def cancel_system_xml_simulation(
    }


-@app.get("/api/system-xml/simulations/{simulation_id}", response_model=None)
-def get_system_xml_simulation(simulation_id: str) -> dict[str, object] | Response:
+@app.get("/api/system-xml/simulations/{simulation_id}")
+def get_system_xml_simulation(simulation_id: str) -> dict[str, object]:
    with SIMULATION_TASKS_LOCK:
        task = SIMULATION_TASKS.get(simulation_id)
    if task is None:
        raise HTTPException(status_code=404, detail="Simulation task was not found.")
-    snapshot = _simulation_task_snapshot(task)
-    result = snapshot.get("result")
-    if isinstance(result, dict) and isinstance(result.get("series"), NativeSeriesJson):
-        return StreamingResponse(iter(serialize_result_parts(snapshot)), media_type="application/json")
-    return snapshot
+    return _simulation_task_snapshot(task)


 def run_system_xml_simulation(
@@ -727,18 +692,27 @@ def run_system_xml_simulation(
    progress_callback: SimulationProgressEmitter | None = None,
    cancel_check: Callable[[], bool] | None = None,
    activity_tracker: SolverActivityTracker | None = None,
-    *, raw_series: bool = False,
 ) -> dict[str, object]:
+    with property_cache_run() as property_cache:
        with profile_run() as trace:
            result = _run_system_xml_simulation_profiled(
                xml_bytes,
                progress_callback,
                cancel_check,
                activity_tracker,
-            raw_series=raw_series,
            )

    performance = trace.snapshot()
+    if performance.get("mode") == "audit" and property_cache is not None:
+        cache_info = property_cache.info()
+        performance["propertyCache"] = {
+            "hits": cache_info.hits,
+            "misses": cache_info.misses,
+            "maxEntriesPerCache": cache_info.max_entries_per_cache,
+            "cacheCount": cache_info.cache_count,
+            "currentEntries": cache_info.current_entries,
+            "evictions": cache_info.evictions,
+        }
    if performance.get("mode") != "off":
        diagnostics = dict(result.get("diagnostics", {}))
        diagnostics["performance"] = performance
@@ -751,10 +725,14 @@ def _run_system_xml_simulation_profiled(
    progress_callback: SimulationProgressEmitter | None = None,
    cancel_check: Callable[[], bool] | None = None,
    activity_tracker: SolverActivityTracker | None = None,
-    *, raw_series: bool = False,
 ) -> dict[str, object]:
-    from app.simulation.backends import simulate_network
-    from app.simulation.results import SimulationPreparationError
+    from app.simulation.solvers.algebraic import AlgebraicSolveError
+    from app.simulation.solvers.solver import SolveIVPConfig
+    from app.simulation.solvers.stream import StreamSolveError
+    from app.simulation.systems.generic import (
+        GenericFluidSystem,
+        SimulationPreparationError,
+    )

    def emit(
        progress: int,
@@ -775,9 +753,9 @@ def _run_system_xml_simulation_profiled(
    emit(0, "validation", "正在校验 System XML")
    report = validate_system_xml_document(xml_bytes)
    document = _validated_xml_document_or_422(report)
-    emit(0, "compilation", "正在解析组件与连接关系")
+    emit(0, "compilation", "正在编译组件与连接关系")
    network = _compile_xml_document_or_422(document)
-    emit(0, "initialization", "连接关系已解析，正在准备原生模型")
+    emit(0, "initialization", "模型编译完成，正在准备求解器")

    def report_system_progress(progress: float, phase: str) -> None:
        bounded_progress = min(1.0, max(0.0, progress))
@@ -792,21 +770,24 @@ def _run_system_xml_simulation_profiled(
            document.simulation.t_stop,
        )

-    def report_property_warning(warning: dict) -> None:
-        fraction = (warning["time"] - document.simulation.t_start) / (
-            document.simulation.t_stop - document.simulation.t_start)
-        emit(round(100 * min(1.0, max(0.0, fraction))), "property-warning",
-             warning["message"], warning["time"], document.simulation.t_stop)
-
    try:
-        result = simulate_network(
-            network,
-            document.simulation,
+        system = GenericFluidSystem(network)
+        result = system.simulate(
+            SolveIVPConfig(
+                t_start=document.simulation.t_start,
+                t_stop=document.simulation.t_stop,
+                method=document.simulation.method,
+                # The pressure-flow closure is solved to a scaled 1e-7
+                # residual. State-specific mechanical absolute tolerances now
+                # keep ideal-stop Jacobian perturbations stable, so the outer
+                # integrator can use its canonical 1e-6 relative accuracy.
+                rtol=1.0e-6,
+                max_step=document.simulation.max_step,
+            ),
+            sample_step=document.simulation.sample_step,
            progress_callback=report_system_progress,
-            warning_callback=report_property_warning,
            cancel_check=cancel_check,
            activity_tracker=activity_tracker,
-            raw_series=raw_series,
        )
    except SimulationPreparationError as exc:
        raise HTTPException(
@@ -823,6 +804,41 @@ def _run_system_xml_simulation_profiled(
                ],
            },
        ) from exc
+    except AlgebraicSolveError as exc:
+        algebraic_diagnostics = exc.diagnostics.as_dict()
+        algebraic_diagnostics["scopeKind"] = exc.scope_kind
+        algebraic_diagnostics["scopeComponents"] = list(exc.scope_components)
+        raise HTTPException(
+            status_code=422,
+            detail={
+                "message": str(exc),
+                "issues": [
+                    {
+                        "severity": "error",
+                        "layer": "simulation",
+                        "code": "PRESSURE_FLOW_SOLVE_FAILED",
+                        "message": str(exc),
+                    }
+                ],
+                "diagnostics": algebraic_diagnostics,
+            },
+        ) from exc
+    except StreamSolveError as exc:
+        raise HTTPException(
+            status_code=422,
+            detail={
+                "message": str(exc),
+                "issues": [
+                    {
+                        "severity": "error",
+                        "layer": "simulation",
+                        "code": "STREAM_SOLVE_FAILED",
+                        "message": str(exc),
+                    }
+                ],
+                "diagnostics": exc.diagnostics.as_dict(),
+            },
+        ) from exc
    except (RuntimeError, ValueError) as exc:
        raise HTTPException(
            status_code=422,
@@ -844,7 +860,7 @@ def _run_system_xml_simulation_profiled(
            "validation": report.as_dict(),
            "simulation": document.as_model_data()["simulation"],
            "model": network.as_interface_dict(),
-            **result.as_dict(raw_series=raw_series),
+            **result.as_dict(),
        }


@@ -852,8 +868,7 @@ def simulation_event_stream(
    xml_bytes: bytes,
    *,
    task: SimulationTaskRecord | None = None,
-    raw_series: bool = False,
-) -> Iterator[str | bytes]:
+) -> Iterator[str]:
    events: queue.Queue[dict[str, object] | object] = queue.Queue()
    finished = object()
    latest_progress = 0
@@ -874,14 +889,6 @@ def simulation_event_stream(
    ) -> None:
        nonlocal latest_message, latest_phase, latest_progress
        nonlocal latest_simulated_time, latest_total_time
-        if phase == "property-warning":
-            # A warning is an event, not the current integration phase. Keep
-            # heartbeat/progress state intact while delivering every warning.
-            events.put({"event": "progress", "progress": latest_progress,
-                        "phase": phase, "message": message,
-                        "simulatedTime": simulated_time, "totalTime": total_time,
-                        **activity_tracker.snapshot().as_dict()})
-            return
        latest_progress = max(latest_progress, min(100, max(0, progress)))
        latest_phase = phase
        latest_message = message
@@ -911,7 +918,6 @@ def simulation_event_stream(
                emit_progress,
                task.cancel_event.is_set if task is not None else None,
                activity_tracker,
-                **({"raw_series": True} if raw_series else {}),
            )
            if task is not None:
                result = _mark_simulation_task_result(task, result)
@@ -1013,10 +1019,6 @@ def simulation_event_stream(
                continue
            if event is finished:
                break
-            if raw_series and isinstance(event, dict) and event.get("event") == "result":
-                yield from serialize_result_parts(event)
-                yield b"\n"
-            else:
            yield json.dumps(event, ensure_ascii=False, separators=(",", ":")) + "\n"
    finally:
        if task is not None:
@@ -1064,7 +1066,7 @@ def validate_reactflow_component_contract(
    node: ReactFlowNodePayload,
    component_spec: "ComponentModelSpec",
 ) -> dict[str, float]:
-    """Validate the normalized SI model contract before consuming current defaults."""
+    """Validate the persisted model contract before consuming current defaults."""

    if (
        node.data.componentType != node.data.modelType
@@ -1103,7 +1105,14 @@ def validate_reactflow_component_contract(

    parameter_values: dict[str, float] = {}
    for parameter in component_spec.parameters:
-        value = parameter_float(node, parameter.name, parameter.default)
+        value = parameter_float(
+            node,
+            parameter.name,
+            parameter.default,
+            quantity=parameter.quantity,
+            base_unit=parameter.unit,
+            expressions_allowed=parameter.editor is None,
+        )
        validation_message = parameter.validation_message(value)
        if validation_message is not None:
            raise ValueError(
@@ -1133,7 +1142,6 @@ def validate_reactflow_execution_contract(
 def build_reactflow_system_xml(project: ReactFlowProjectPayload) -> bytes:
    from app.simulation.registry import get_component_model_spec

-    validate_si_project(project)
    system_attributes = {
        "schemaVersion": SYSTEM_XML_SCHEMA_VERSION,
        "unitSystem": SYSTEM_XML_UNIT_SYSTEM,
@@ -1211,8 +1219,7 @@ def build_reactflow_system_xml(project: ReactFlowProjectPayload) -> bytes:
            edge.targetHandle,
            edge.id,
        )
-        validate_compatible_ports(first, second, edge.id,
-                                  f"{edge.source}.{first.name}", f"{edge.target}.{second.name}")
+        validate_compatible_ports(first, second, edge.id)

        connection_node = ET.SubElement(
            connections_node,
@@ -1264,18 +1271,11 @@ def validate_compatible_ports(
    first: "PortDefinition",
    second: "PortDefinition",
    connection_id: str,
-    first_label: str | None = None,
-    second_label: str | None = None,
 ) -> None:
-    from app.simulation.core.port_computation import PortSupplyError, port_supply_issue
-
    if first.kind != second.kind:
        raise ValueError(f"Connection {connection_id} mixes physical and signal ports.")
    if first.domain != second.domain:
        raise ValueError(f"Connection {connection_id} connects incompatible domains.")
-    supply_issue = port_supply_issue(first, second, first_label, second_label)
-    if supply_issue:
-        raise PortSupplyError(supply_issue)
    if first.kind == "signal" and {first.nominal_role, second.nominal_role} != {
        "input",
        "output",
@@ -1340,7 +1340,6 @@ def _solver_model_from_reactflow(
 ) -> SolverModelInput:
    from app.simulation.registry import get_component_model_spec

-    validate_si_project(project)
    components: list[SolverComponentInput] = []
    for node in project.nodes:
        spec = get_component_model_spec(node.data.modelType)
@@ -1491,7 +1490,6 @@ def _compile_solver_network(
            edge.endpoint_b_port,
            connection_id=edge.id,
        )
-    network.validate_port_supplies()
    return network


@@ -1538,38 +1536,195 @@ def sanitize_project_id(project_id: str) -> str:


 def run_reactflow_testmodel(project: ReactFlowProjectPayload) -> dict[str, object]:
-    raise HTTPException(status_code=410, detail="The legacy Python example runner has been removed. Export System XML and use /api/system-xml/simulate.")
+    from app.simulation.examples.testmodel.run import (
+        TestModelExecutionConfig,
+        TestModelRunConfig,
+        TestModelSamplingConfig,
+        run_testmodel,
+    )
+    from app.simulation.examples.testmodel.system import (
+        BranchConfig,
+        CylinderConfig,
+        OrificeConfig,
+        PipeConfig,
+        TankConfig,
+        TestModelConfig,
+    )
+    from app.simulation.solvers.solver import SolveIVPConfig
+
+    validate_reactflow_execution_contract(project)
+
+    nodes_by_type: dict[str, list[ReactFlowNodePayload]] = {}
+    for node in project.nodes:
+        nodes_by_type.setdefault(node.data.modelType, []).append(node)
+
+    cylinder = first_node(nodes_by_type, "cylinder")
+    tank = first_node(nodes_by_type, "tank")
+    orifices = nodes_by_type.get("orifice", [])
+    pipes = nodes_by_type.get("pipe", [])
+
+    model_config = TestModelConfig(
+        cylinder=CylinderConfig(
+            volume=parameter_float(cylinder, "volume", 0.01),
+            p0=parameter_float(cylinder, "p0", 35e6),
+            T0=parameter_float(cylinder, "T0", 300.0),
+        ),
+        upper_branch=BranchConfig(
+            orifice=OrificeConfig(K=parameter_float(node_at(orifices, 0), "K", 1e-5)),
+            pipe=pipe_config_from_node(node_at(pipes, 0), PipeConfig),
+        ),
+        lower_branch=BranchConfig(
+            orifice=OrificeConfig(K=parameter_float(node_at(orifices, 1), "K", 1e-5)),
+            pipe=pipe_config_from_node(node_at(pipes, 1), PipeConfig),
+        ),
+        tank=TankConfig(
+            volume=parameter_float(tank, "volume", 0.1),
+            p0=parameter_float(tank, "p0", 1e5),
+            T0=parameter_float(tank, "T0", 300.0),
+        ),
+    )
+    run_config = TestModelRunConfig(
+        model=model_config,
+        solver=SolveIVPConfig(
+            t_start=project.simulation.t_start,
+            t_stop=project.simulation.t_stop,
+            method=project.simulation.method,
+            max_step=project.simulation.max_step,
+        ),
+        sampling=TestModelSamplingConfig(step=project.simulation.step),
+        execution=TestModelExecutionConfig(use_modelica_reference_if_available=False),
+    )
+    result = run_testmodel(run_config=run_config)
+    series_keys = ("time", "mytank.p", "mytank.T", "mycylinder.p", "mycylinder.T")
+    series = {
+        key: [float(value) for value in result.series[key]]
+        for key in series_keys
+        if key in result.series
+    }
+
+    return {
+        "success": bool(result.solution.success),
+        "message": str(result.solution.message),
+        "usedModelicaReference": result.used_modelica_reference,
+        "final": {
+            "time": series["time"][-1],
+            "tankPressure": series["mytank.p"][-1],
+            "tankTemperature": series["mytank.T"][-1],
+            "cylinderPressure": series["mycylinder.p"][-1],
+            "cylinderTemperature": series["mycylinder.T"][-1],
+        },
+        "series": series,
+        "artifacts": {
+            "primaryCsv": str(result.artifacts.primary_csv_path),
+            "temperatureCsv": str(result.artifacts.temperature_csv_path),
+            "temperatureSvg": str(result.artifacts.temperature_svg_path),
+            "runReport": str(result.artifacts.run_report_path),
+        },
+        "networkSummary": result.system.network.summary(),
+    }


 def run_reactflow_test_mql(project: ReactFlowProjectPayload) -> dict[str, object]:
-    raise HTTPException(status_code=410, detail="The legacy Python example runner has been removed. Export System XML and use /api/system-xml/simulate.")
+    from app.simulation.examples.test_mql.run import run_test_mql
+    from app.simulation.examples.test_mql.system import TestMqlRunConfig
+
+    validate_reactflow_execution_contract(project)
+
+    run_config = TestMqlRunConfig(
+        t_start=project.simulation.t_start,
+        t_stop=project.simulation.t_stop,
+        sample_step=project.simulation.step,
+    )
+    result = run_test_mql(run_config=run_config)
+    series = {
+        key: [float(value) for value in values]
+        for key, values in result.result.series.items()
+    }
+    final = {key: values[-1] for key, values in series.items() if values}
+    snapshot = result.system.snapshot()
+    return {
+        "success": True,
+        "message": "test_mql fixed-topology simulation completed.",
+        "model": {
+            "name": snapshot.model_name,
+            "componentCount": snapshot.component_count,
+            "connectionCount": snapshot.connection_count,
+            "continuousStateCount": snapshot.continuous_state_count,
+            "discreteStateCount": snapshot.discrete_state_count,
+        },
+        "final": final,
+        "series": series,
+        "artifacts": {
+            "summary": str(result.summary_path),
+        },
+    }


+def first_node(
+    nodes_by_type: dict[str, list[ReactFlowNodePayload]],
+    model_type: str,
+) -> ReactFlowNodePayload | None:
+    nodes = nodes_by_type.get(model_type, [])
+    return nodes[0] if nodes else None


+def node_at(
+    nodes: list[ReactFlowNodePayload],
+    index: int,
+) -> ReactFlowNodePayload | None:
+    return nodes[index] if index < len(nodes) else None


 def parameter_float(
    node: ReactFlowNodePayload | None,
    name: str,
    default: float,
+    *,
+    quantity: str = "dimensionless",
+    base_unit: str = "",
+    expressions_allowed: bool = True,
 ) -> float:
    if node is None:
        return default
    value = node.data.parameters.get(name, default)
    try:
-        if type(value) in (int, float) and isfinite(value):
-            return float(value)
-    except OverflowError:
-        pass
-    raise ValueError(f"Parameter '{name}' on component '{node.id}' must be a finite SI number; normalize expressions before execution.")
+        numeric_value = float(value)
+    except (TypeError, ValueError):
+        if not isinstance(value, str):
+            raise ValueError(
+                f"Parameter '{name}' on component '{node.id}' must be numeric."
+            )
+        if not expressions_allowed:
+            raise ValueError(
+                f"PARAMETER_EXPRESSION_FORBIDDEN: Parameter '{name}' on component "
+                f"'{node.id}' is a discrete selection and cannot use an expression."
+            )
+        try:
+            evaluated = evaluate_parameter_expression(value)
+            selected_unit = node.data.parameterUnits.get(name, base_unit)
+            return expression_value_to_base_unit(
+                evaluated,
+                quantity=quantity,
+                selected_unit=selected_unit,
+            )
+        except ParameterExpressionError as exc:
+            raise ValueError(
+                f"PARAMETER_EXPRESSION_INVALID: Parameter '{name}' on component "
+                f"'{node.id}' contains an invalid expression: {exc}."
+            ) from exc
+    if not isfinite(numeric_value):
+        raise ValueError(
+            f"Parameter '{name}' on component '{node.id}' must be a finite "
+            "numeric value."
+        )
+    return numeric_value


-def validate_si_project(project: ReactFlowProjectPayload) -> None:
-    """Guard the editor-independent numerical boundary, including time settings."""
-    if project.projectSchemaVersion != 1:
-        raise ValueError("Execution requires normalized SI data; preprocess project input first.")
-    for name in ("t_start", "t_stop", "step", "max_step"):
-        value = getattr(project.simulation, name)
-        if type(value) not in (int, float) or not isfinite(value):
-            raise ValueError(f"Simulation {name} must be a finite SI number.")
+def pipe_config_from_node(node: ReactFlowNodePayload | None, pipe_config_type):
+    return pipe_config_type(
+        length=parameter_float(node, "length", 5.0),
+        diameter=parameter_float(node, "diameter", 0.02),
+        lambda_darcy=parameter_float(node, "lambda_darcy", 0.02),
+        p0=parameter_float(node, "p0", 1e5),
+        T0=parameter_float(node, "T0", 300.0),
+    )
@@ -0,0 +1,408 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+import re
+from typing import Callable
+
+
+MAX_INPUT_LENGTH = 512
+MAX_TOKEN_COUNT = 256
+MAX_OPERATION_COUNT = 256
+MAX_NESTING_DEPTH = 32
+MAX_FUNCTION_ARGUMENTS = 16
+
+_UNSIGNED_NUMBER_PREFIX = re.compile(
+    r"(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?"
+)
+
+
+class ParameterExpressionError(ValueError):
+    """Raised when an editor parameter expression cannot be resolved safely."""
+
+
+@dataclass(frozen=True)
+class _Token:
+    kind: str
+    text: str
+    position: int
+    value: float | None = None
+
+
+def evaluate_parameter_expression(expression: str) -> float:
+    """Evaluate the same bounded arithmetic subset accepted by the frontend.
+
+    The parser never executes Python code and cannot access names other than
+    the constants ``pi`` and ``e`` or the explicitly supported functions.
+    """
+
+    source = expression.strip()
+    if source.startswith("="):
+        source = source[1:].strip()
+    if not source:
+        raise ParameterExpressionError("expression must not be empty")
+    if len(source) > MAX_INPUT_LENGTH:
+        raise ParameterExpressionError(
+            f"expression must not exceed {MAX_INPUT_LENGTH} characters"
+        )
+    return _ParameterExpressionParser(_tokenize(source)).parse()
+
+
+def expression_value_to_base_unit(
+    value: float,
+    *,
+    quantity: str,
+    selected_unit: str,
+) -> float:
+    """Convert an expression result from its editor unit to the SI contract.
+
+    Plain numeric JSON values are already stored in SI and must not pass
+    through this function. Only expression results use the selected display
+    unit, matching the existing frontend behavior.
+    """
+
+    conversions = _UNIT_CONVERSIONS.get(quantity)
+    if not conversions:
+        return _ensure_finite(value, "expression result")
+    conversion = conversions.get(selected_unit)
+    if conversion is None:
+        # The frontend falls back to the first (base) unit for an unknown or
+        # absent selection. Keep the execution boundary behavior identical.
+        conversion = next(iter(conversions.values()))
+    scale, offset = conversion
+    return _ensure_finite(value * scale + offset, "converted expression result")
+
+
+def _tokenize(source: str) -> tuple[_Token, ...]:
+    tokens: list[_Token] = []
+    position = 0
+
+    def append(token: _Token) -> None:
+        tokens.append(token)
+        if len(tokens) > MAX_TOKEN_COUNT:
+            raise ParameterExpressionError(
+                f"expression must not exceed {MAX_TOKEN_COUNT} tokens"
+            )
+
+    while position < len(source):
+        character = source[position]
+        if character.isspace():
+            position += 1
+            continue
+
+        if character.isdigit() or (
+            character == "."
+            and position + 1 < len(source)
+            and source[position + 1].isdigit()
+        ):
+            match = _UNSIGNED_NUMBER_PREFIX.match(source, position)
+            if match is None:
+                raise ParameterExpressionError(
+                    f"invalid number near character {position + 1}"
+                )
+            text = match.group(0)
+            value = _ensure_finite(float(text), f"number {text!r}")
+            append(_Token("number", text, position, value))
+            position = match.end()
+            continue
+
+        if character.isascii() and (character.isalpha() or character == "_"):
+            end = position + 1
+            while end < len(source):
+                candidate = source[end]
+                if not candidate.isascii() or not (
+                    candidate.isalnum() or candidate == "_"
+                ):
+                    break
+                end += 1
+            append(_Token("identifier", source[position:end], position))
+            position = end
+            continue
+
+        if character == "*" and source[position : position + 2] == "**":
+            append(_Token("operator", "**", position))
+            position += 2
+            continue
+        if character in "+-*/^":
+            append(_Token("operator", character, position))
+            position += 1
+            continue
+        if character == "(":
+            append(_Token("left_parenthesis", character, position))
+            position += 1
+            continue
+        if character == ")":
+            append(_Token("right_parenthesis", character, position))
+            position += 1
+            continue
+        if character == ",":
+            append(_Token("comma", character, position))
+            position += 1
+            continue
+
+        raise ParameterExpressionError(
+            f"unsupported symbol {character!r} at character {position + 1}"
+        )
+
+    tokens.append(_Token("end", "", len(source)))
+    return tuple(tokens)
+
+
+class _ParameterExpressionParser:
+    def __init__(self, tokens: tuple[_Token, ...]) -> None:
+        self._tokens = tokens
+        self._index = 0
+        self._operation_count = 0
+
+    def parse(self) -> float:
+        value = self._parse_additive(0)
+        trailing = self._current()
+        if trailing.kind != "end":
+            raise ParameterExpressionError(
+                f"unexpected content {trailing.text!r} near character "
+                f"{trailing.position + 1}"
+            )
+        return _ensure_finite(value, "expression result")
+
+    def _parse_additive(self, depth: int) -> float:
+        value = self._parse_multiplicative(depth)
+        while self._is_operator("+") or self._is_operator("-"):
+            operator = self._advance().text
+            right = self._parse_multiplicative(depth)
+            self._count_operation()
+            value = _safe_operation(
+                lambda: value + right if operator == "+" else value - right,
+                f"operation {operator!r}",
+            )
+        return value
+
+    def _parse_multiplicative(self, depth: int) -> float:
+        value = self._parse_unary(depth)
+        while self._is_operator("*") or self._is_operator("/"):
+            operator = self._advance().text
+            right = self._parse_unary(depth)
+            self._count_operation()
+            if operator == "/" and right == 0:
+                raise ParameterExpressionError("division by zero is not allowed")
+            value = _safe_operation(
+                lambda: value * right if operator == "*" else value / right,
+                f"operation {operator!r}",
+            )
+        return value
+
+    def _parse_unary(self, depth: int) -> float:
+        self._assert_depth(depth)
+        if self._is_operator("+") or self._is_operator("-"):
+            operator = self._advance().text
+            self._count_operation()
+            operand = self._parse_unary(depth + 1)
+            return _ensure_finite(
+                operand if operator == "+" else -operand,
+                f"unary operation {operator!r}",
+            )
+        return self._parse_power(depth)
+
+    def _parse_power(self, depth: int) -> float:
+        self._assert_depth(depth)
+        base = self._parse_primary(depth)
+        if not self._is_operator("^") and not self._is_operator("**"):
+            return base
+        operator = self._advance().text
+        exponent = self._parse_unary(depth + 1)
+        self._count_operation()
+        return _safe_operation(
+            lambda: math.pow(base, exponent),
+            f"operation {operator!r}",
+        )
+
+    def _parse_primary(self, depth: int) -> float:
+        self._assert_depth(depth)
+        token = self._current()
+        if token.kind == "number":
+            self._advance()
+            return _ensure_finite(
+                token.value if token.value is not None else math.nan,
+                f"number {token.text!r}",
+            )
+
+        if token.kind == "identifier":
+            self._advance()
+            normalized_name = token.text.casefold()
+            if self._current().kind == "left_parenthesis":
+                return self._parse_function_call(
+                    normalized_name,
+                    token.text,
+                    depth + 1,
+                )
+            if normalized_name == "pi":
+                return math.pi
+            if normalized_name == "e":
+                return math.e
+            raise ParameterExpressionError(f"unknown identifier {token.text!r}")
+
+        if token.kind == "left_parenthesis":
+            self._advance()
+            value = self._parse_additive(depth + 1)
+            self._expect("right_parenthesis", "missing closing parenthesis")
+            return value
+
+        if token.kind == "end":
+            raise ParameterExpressionError(
+                "expression ends before a number, constant, or function"
+            )
+        raise ParameterExpressionError(
+            f"expected a number, constant, or function near character "
+            f"{token.position + 1}"
+        )
+
+    def _parse_function_call(
+        self,
+        normalized_name: str,
+        source_name: str,
+        depth: int,
+    ) -> float:
+        self._assert_depth(depth)
+        self._expect(
+            "left_parenthesis",
+            f"function {source_name} is missing an opening parenthesis",
+        )
+        arguments: list[float] = []
+        if self._current().kind != "right_parenthesis":
+            while True:
+                if len(arguments) >= MAX_FUNCTION_ARGUMENTS:
+                    raise ParameterExpressionError(
+                        f"function {source_name} accepts at most "
+                        f"{MAX_FUNCTION_ARGUMENTS} arguments"
+                    )
+                arguments.append(self._parse_additive(depth))
+                if self._current().kind != "comma":
+                    break
+                self._advance()
+                if self._current().kind == "right_parenthesis":
+                    raise ParameterExpressionError(
+                        f"function {source_name} has no argument after its comma"
+                    )
+        self._expect(
+            "right_parenthesis",
+            f"function {source_name} is missing a closing parenthesis",
+        )
+        self._count_operation()
+        return _evaluate_function(normalized_name, source_name, arguments)
+
+    def _current(self) -> _Token:
+        return self._tokens[min(self._index, len(self._tokens) - 1)]
+
+    def _advance(self) -> _Token:
+        token = self._current()
+        if token.kind != "end":
+            self._index += 1
+        return token
+
+    def _expect(self, kind: str, message: str) -> _Token:
+        if self._current().kind != kind:
+            raise ParameterExpressionError(message)
+        return self._advance()
+
+    def _is_operator(self, operator: str) -> bool:
+        token = self._current()
+        return token.kind == "operator" and token.text == operator
+
+    def _assert_depth(self, depth: int) -> None:
+        if depth > MAX_NESTING_DEPTH:
+            raise ParameterExpressionError(
+                f"expression nesting must not exceed {MAX_NESTING_DEPTH} levels"
+            )
+
+    def _count_operation(self) -> None:
+        self._operation_count += 1
+        if self._operation_count > MAX_OPERATION_COUNT:
+            raise ParameterExpressionError(
+                f"expression must not exceed {MAX_OPERATION_COUNT} operations"
+            )
+
+
+def _evaluate_function(
+    normalized_name: str,
+    source_name: str,
+    arguments: list[float],
+) -> float:
+    def require_count(expected: int) -> None:
+        if len(arguments) != expected:
+            raise ParameterExpressionError(
+                f"function {source_name} requires {expected} arguments, "
+                f"received {len(arguments)}"
+            )
+
+    if normalized_name == "sqrt":
+        require_count(1)
+        if arguments[0] < 0:
+            raise ParameterExpressionError("sqrt argument must not be negative")
+        operation = lambda: math.sqrt(arguments[0])
+    elif normalized_name == "abs":
+        require_count(1)
+        operation = lambda: abs(arguments[0])
+    elif normalized_name in {"sin", "cos", "tan", "asin", "acos", "atan"}:
+        require_count(1)
+        if normalized_name in {"asin", "acos"} and not -1 <= arguments[0] <= 1:
+            raise ParameterExpressionError(
+                f"{source_name} argument must be between -1 and 1"
+            )
+        function = getattr(math, normalized_name)
+        operation = lambda: function(arguments[0])
+    elif normalized_name == "exp":
+        require_count(1)
+        operation = lambda: math.exp(arguments[0])
+    elif normalized_name in {"ln", "log"}:
+        require_count(1)
+        if arguments[0] <= 0:
+            raise ParameterExpressionError(f"{source_name} argument must be positive")
+        operation = lambda: math.log(arguments[0])
+    elif normalized_name == "log10":
+        require_count(1)
+        if arguments[0] <= 0:
+            raise ParameterExpressionError("log10 argument must be positive")
+        operation = lambda: math.log10(arguments[0])
+    elif normalized_name in {"min", "max"}:
+        if not arguments:
+            raise ParameterExpressionError(
+                f"function {source_name} requires at least one argument"
+            )
+        function = min if normalized_name == "min" else max
+        operation = lambda: float(function(arguments))
+    elif normalized_name == "pow":
+        require_count(2)
+        operation = lambda: math.pow(arguments[0], arguments[1])
+    else:
+        raise ParameterExpressionError(f"unsupported function {source_name!r}")
+    return _safe_operation(operation, f"function {source_name}")
+
+
+def _safe_operation(operation: Callable[[], float], context: str) -> float:
+    try:
+        value = operation()
+    except (ArithmeticError, ValueError) as exc:
+        raise ParameterExpressionError(f"{context} has no finite real result") from exc
+    return _ensure_finite(float(value), context)
+
+
+def _ensure_finite(value: float, context: str) -> float:
+    if not math.isfinite(value):
+        raise ParameterExpressionError(f"{context} is not finite")
+    return value
+
+
+# Ordered exactly like the editor's unit selector. The first entry is the
+# fallback SI unit when a persisted selection is absent or unknown.
+_UNIT_CONVERSIONS: dict[str, dict[str, tuple[float, float]]] = {
+    "area": {"m2": (1.0, 0.0), "cm2": (1.0e-4, 0.0), "mm2": (1.0e-6, 0.0)},
+    "heat_transfer_coefficient": {"W/(m2*K)": (1.0, 0.0)},
+    "pressure": {
+        "Pa": (1.0, 0.0),
+        "kPa": (1.0e3, 0.0),
+        "MPa": (1.0e6, 0.0),
+        "bar": (1.0e5, 0.0),
+    },
+    "volume": {"m3": (1.0, 0.0), "L": (1.0e-3, 0.0), "mL": (1.0e-6, 0.0)},
+    "temperature": {"K": (1.0, 0.0), "degC": (1.0, 273.15)},
+    "length": {"m": (1.0, 0.0), "cm": (1.0e-2, 0.0), "mm": (1.0e-3, 0.0)},
+}
@@ -1,250 +0,0 @@
-"""User-input adapter shared by HTTP and CLI; the numerical layer stays SI-only.
-
-JSON v1 numbers (including decimal strings) were SI, but expressions used the
-selected unit. JSON v2 consistently uses the selected unit for both. Missing
-parameters use catalog defaults, which are always SI. Never infer a format from
-magnitudes or relabel a legacy project without converting its values.
-"""
-from __future__ import annotations
-
-import json
-import math
-from pathlib import Path
-import re
-
-UNIT_TABLE = json.loads((Path(__file__).resolve().parent.parent / "schemas" / "parameter-units.json").read_text(encoding="utf-8"))
-DECIMAL = re.compile(r"[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?\Z", re.ASCII)
-TOKEN = re.compile(r"(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?|[A-Za-z_][A-Za-z_0-9]*|\*\*|[+*/^(),-]", re.ASCII)
-
-
-def finite(value: float) -> float:
-    if not math.isfinite(value):
-        raise ValueError("Parameter expression must produce a finite real number.")
-    return value
-
-
-def numeric_literal(value: object) -> float | None:
-    if type(value) in (int, float):
-        try:
-            return finite(float(value))
-        except OverflowError as exc:
-            raise ValueError("Parameter magnitude exceeds finite float range.") from exc
-    if isinstance(value, str) and DECIMAL.fullmatch(value.strip()):
-        return finite(float(value))
-    return None
-
-
-def expression_value(source: str) -> float:
-    """Same bounded recursive-descent grammar as parameterExpression.ts; no eval."""
-    source = source.strip().removeprefix("=").strip()
-    if not source or len(source) > 512:
-        raise ValueError("Parameter expression must contain 1..512 characters.")
-    tokens: list[str] = []
-    position = 0
-    while position < len(source):
-        if source[position].isspace():
-            position += 1
-            continue
-        match = TOKEN.match(source, position)
-        if match is None:
-            raise ValueError(f"Unsupported expression character at {position + 1}.")
-        tokens.append(match[0])
-        position = match.end()
-        if len(tokens) > 256:
-            raise ValueError("Parameter expression exceeds 256 tokens.")
-    tokens.append("")
-    index = 0
-    operations = 0
-
-    def current():
-        return tokens[index]
-
-    def take():
-        nonlocal index
-        token = current()
-        if token:
-            index += 1
-        return token
-
-    def operation():
-        nonlocal operations
-        operations += 1
-        if operations > 256:
-            raise ValueError("Parameter expression exceeds 256 operations.")
-
-    def depth_check(depth):
-        if depth > 32:
-            raise ValueError("Parameter expression exceeds 32 nesting levels.")
-
-    def additive(depth):
-        value = multiplicative(depth)
-        while current() in ("+", "-"):
-            op = take()
-            right = multiplicative(depth)
-            operation()
-            value = finite(value + right if op == "+" else value - right)
-        return value
-
-    def multiplicative(depth):
-        value = unary(depth)
-        while current() in ("*", "/"):
-            op = take()
-            right = unary(depth)
-            operation()
-            value = finite(value * right if op == "*" else value / right)
-        return value
-
-    def unary(depth):
-        depth_check(depth)
-        if current() in ("+", "-"):
-            op = take()
-            operation()
-            value = unary(depth + 1)
-            return value if op == "+" else -value
-        return power(depth)
-
-    def power(depth):
-        depth_check(depth)
-        value = primary(depth)
-        if current() in ("^", "**"):
-            take()
-            exponent = unary(depth + 1)
-            operation()
-            value = finite(math.pow(value, exponent))
-        return value
-
-    def primary(depth):
-        depth_check(depth)
-        token = take()
-        if token == "(":
-            value = additive(depth + 1)
-            if take() != ")":
-                raise ValueError("Missing closing parenthesis.")
-            return value
-        if token and (token[0].isdigit() or token[0] == "."):
-            return finite(float(token))
-        name = token.lower()
-        if token and (token[0].isalpha() or token[0] == "_"):
-            if current() != "(":
-                if name in ("pi", "e"):
-                    return math.pi if name == "pi" else math.e
-                raise ValueError(f"Unknown identifier: {token}.")
-            depth_check(depth + 1)
-            take()
-            args = []
-            if current() != ")":
-                while True:
-                    if len(args) >= 16:
-                        raise ValueError("Functions accept at most 16 arguments.")
-                    args.append(additive(depth + 1))
-                    if current() != ",":
-                        break
-                    take()
-            if take() != ")":
-                raise ValueError("Missing function closing parenthesis.")
-            operation()
-            functions = {"sqrt": math.sqrt, "abs": abs, "sin": math.sin,
-                         "cos": math.cos, "tan": math.tan, "asin": math.asin,
-                         "acos": math.acos, "atan": math.atan, "exp": math.exp,
-                         "ln": math.log, "log": math.log, "log10": math.log10,
-                         "pow": math.pow}
-            if name in ("min", "max") and args:
-                return finite((min if name == "min" else max)(args))
-            if name not in functions or len(args) != (2 if name == "pow" else 1):
-                raise ValueError(f"Unsupported function or argument count: {token}.")
-            return finite(functions[name](*args))
-        raise ValueError("Expected a number, constant or function.")
-
-    try:
-        result = additive(0)
-        if current():
-            raise ValueError("Unexpected trailing expression content.")
-        return finite(result)
-    except (ArithmeticError, RecursionError) as exc:
-        raise ValueError("Invalid arithmetic or expression domain.") from exc
-
-
-def unit_conversion(definition, unit: str) -> tuple[float, float]:
-    options = UNIT_TABLE.get(definition.quantity, {}) if definition.unit else {}
-    if unit in options:
-        scale, offset, _ = options[unit]
-        return scale, offset
-    if unit == definition.unit:
-        return 1.0, 0.0
-    raise ValueError(f"Unsupported unit '{unit}' for {definition.name} ({definition.quantity}).")
-
-
-def prepare_project(project):
-    """Copy external input to a current-version, numeric SI execution project.
-
-    Returns consolidated version notices to the caller. Does not mutate saved
-    data and does not weaken the strict XML/native model-version checks.
-    """
-    from app.simulation.registry import get_component_model_spec
-
-    normalized = project.model_copy(deep=True)
-    notices = []
-    specs = {}
-    for node in normalized.nodes:
-        model = node.data
-        spec = specs.get(model.modelType)
-        if spec is None:
-            spec = get_component_model_spec(model.modelType)
-            specs[model.modelType] = spec
-        if model.componentType != spec.model_type:
-            raise ValueError(f"COMPONENT_MODEL_TYPE_MISMATCH: {node.id}.")
-        if model.modelVersion != spec.model_version:
-            notices.append({"componentId": node.id, "label": model.label or node.id,
-                            "storedVersion": model.modelVersion,
-                            "currentVersion": spec.model_version})
-        for name, value in model.parameters.items():
-            definition = spec.parameter_by_name.get(name)
-            if definition is None:
-                raise ValueError(f"Component '{node.id}' contains unsupported parameters: {name}.")
-            try:
-                scale, offset = unit_conversion(definition, model.parameterUnits.get(name, definition.unit))
-                number = numeric_literal(value)
-                is_expression = number is None
-                if is_expression:
-                    if not isinstance(value, str) or definition.editor:
-                        raise ValueError("Expected a numeric value; discrete parameters cannot use expressions.")
-                    number = expression_value(value)
-                if project.projectSchemaVersion == 2 or is_expression:
-                    number = finite(number * scale + offset)
-                model.parameters[name] = number
-            except ValueError as exc:
-                raise ValueError(f"{node.id}.{name}: {exc}") from exc
-        # Explicit legacy migrations also used by the browser.
-        if model.modelVersion == "0.1.0" and model.modelType == "amesim_forc":
-            model.parameters.setdefault("direction", 1.0)
-        if model.modelVersion == "0.1.0" and model.modelType == "amesim_lmechn1":
-            count = model.parameters.get("v1")
-            if count in range(1, 9):
-                for edge in normalized.edges:
-                    if edge.source == node.id and edge.sourceHandle == "port_9":
-                        edge.sourceHandle = f"port_{int(count) + 1}"
-                    if edge.target == node.id and edge.targetHandle == "port_9":
-                        edge.targetHandle = f"port_{int(count) + 1}"
-                model.parameters["sum"] = 1.0
-                # Historical LMECHN1 exposed only nine ports; use its migrated contract.
-                from app.main import ReactFlowPortDefinition
-                model.ports = [ReactFlowPortDefinition(name=p.name, kind=p.kind, domain=p.domain,
-                    nominalRole=p.nominal_role, positiveFlowDirection=p.positive_flow_direction)
-                    for p in spec.ports]
-        model.modelVersion = spec.model_version
-        model.parameterUnits = {p.name: p.unit for p in spec.parameters}
-        model.parameterScientificNotation = {}
-    for name in ("t_start", "t_stop", "step", "max_step"):
-        value = getattr(normalized.simulation, name)
-        number = numeric_literal(value)
-        if number is None:
-            number = expression_value(value)
-        setattr(normalized.simulation, name, number)
-    normalized.projectSchemaVersion = 1  # Internal numeric SI contract, never a v2 wire payload.
-    return normalized, notices
-
-
-def version_warning(notices):
-    return {"code": "COMPONENT_MODEL_VERSION_WARNING",
-            "message": "旧版或版本未知的组件将使用当前模型执行，可能仿真失败或结果与实际不符。",
-            "components": notices}
@@ -1,19 +1,407 @@
 # 仿真后端

-当前采用 Python 编排、C 数值执行。输入 XML 经校验后，Python 根据模型参数和连接生成系统专用 C；GCC 编译成 EXE，EXE 内执行初始化、物性、流量、机械、RK45/CVODE BDF、事件和采样。求解循环不调用 Python。
+`app.simulation` 是 SystemSimulationApp 的仿真子包，用于承接模型定义、系统装配、数值求解和结果导出。

-## 目录
+目标不是逐行翻译源模型，而是建立可运行、可测试、可导出，并能与 OpenModelica 或 AMESim baseline 对比的 Python 仿真框架。

- `components/`：模型参数、端口、显示和结果声明。
- `core/`、`registry.py`、`systems/network.py`：模型合同与网络结构校验。
- `native_codegen/`：C 生成、构建、进程运行和 CLI。
- `config.py`、`sampling.py`、`results.py`：公共配置、进度、采样网格校验与结果类型。
- `performance.py`、`warmup.py`：编排计时和启动工具链检查。
- `reporting/amesim_results.py`：外部 Amesim 结果读取。
- 仓库根目录 `native/`：C 组件公式和求解器。
+当前包含两条模型线：`Testmodel` 已有可运行的 ODE 近似和 OpenModelica 对比能力；`test_mql` 已形成 132 状态气动机械总闭包，正在按 AMESim baseline 做数值校准。

-旧 Python 积分器、数值组件方法和固定算例专用求解器已经退役。旧 `/api/reactflow/simulate-testmodel`、`/api/reactflow/simulate-test-mql` 返回 410；使用 `/api/system-xml/simulate` 或流式接口。
+## 当前目录

-旧 `ir/` 包、专属 schema、规范与测试已删除。当前 C 生成器直接使用经过校验的网络结构，不依赖旧 System IR v2。
+- `core/`: 元件基类、端口、状态、介质、方程和元数据协议。
+- `solvers/`: ODE、压力流量代数方程和 stream 求解。
+- `components/experimental/`: 用于验证元件开发规范的临时组件库。
+- `components/experimental/storage/`: 气瓶和贮箱等储能元件。
+- `components/experimental/flow/`: 对外注册的阻性管道和孔板等流动元件。
+- `components/experimental/junctions/`: 三通等连接节点。
+- `components/amesim/`: AMESim 气动、信号和机械组件原语。
+- `systems/`: 通用仿真网络与 XML 驱动系统装配。
+- `examples/testmodel/`: 固定 TestModel、专用闭合逻辑和基线运行入口。
+- `examples/test_mql/`: AMESim `test_mql` 的系统装配、校准原语、诊断和运行入口。
+- `reporting/`: CSV、SVG、运行报告、Modelica 对比结果、AMESim 结果读取和诊断报告导出。
+- `registry.py`: 从已启用库清单受控发现、校验和实例化组件。
+- `paths.py`: 项目、运行产物、基准和 Modelica 参考结果路径。

-运行、支持范围与依赖见 [C 后端说明](../../native/README.md)。模型开发规则见 [组件规范](../../docs/standard/component-model-authoring-spec-v1.md)。历史性能、Amesim 差异和旧公式说明位于 `docs/other/` 及 Git 历史，不能作为当前运行入口。
+稳定基准存放在 `tests/baselines/simulation/`，实际运行产物默认写入被 Git 忽略的
+`app/data/simulation-runs/`。新增或修改元件时，先阅读 `components/example.md`。
+需要把运行产物写到仓库外时，可以设置 `SIMULATIONAPP_DATA_DIR` 环境变量。
+
+FastAPI 的 `GET /api/components/catalog` 会把注册表转换成前端组件目录。ReactFlow
+启动时自动读取该接口；接口暂时不可用时使用内置的同结构兜底定义。
+
+临时组件库的声明入口是 `components/experimental/library.py`，AMESim 第一版
+公开临时库入口是 `components/amesim/library.py`。公开模型必须在
+模型类中声明 `MODEL_TYPE / MODEL_VERSION / PORTS / PARAMETERS /
+RESULT_VARIABLES / DISPLAY / create()`，再把类路径加入库清单。完整规范参见
+[`组件模型建模规范 v1`](../../docs/standard/component-model-authoring-spec-v1.md)和
+[`组件库分类、发现与读取规范 v1`](../../docs/standard/component-library-spec-v1.md)。
+
+当前关键文件：
+
+- `core/medium.py`: 气体介质协议 `GasMedium` 与通用理想气体实现 `IdealGasMedium`
+- `components/amesim/media/`: AMESim 零端口介质物性定义元件；具体类型确定介质，`property_model` 下拉参数选择计算方法，当前提供空气理想气体和氦气 Peng-Robinson
+- `components/amesim/gases.py`: AMESim `gi` 介质物性实例注册表；`gi=0` 固定为空气（理想气体，内置默认），`gi=1..99` 引用画布中的显式介质定义
+- `core/peng_robinson.py`: `test_mql` 与公开氦气介质共用的 Peng-Robinson 状态方程
+- `performance.py`: 默认关闭、按单次仿真隔离的阶段与物性性能埋点
+- `benchmark_performance.py`: System XML 主求解路径的可重复命令行基准工具
+- `systems/network.py`: `SimulationNetwork`，负责组件注册、连接拓扑和状态向量拼装
+- `solvers/solver.py`: `integrate_ode()`，优先走 `SciPy solve_ivp`，缺依赖时回退到内置 RK4，并支持 `t_start == t_stop` 的零时长返回
+- `examples/testmodel/dynamic_pipe.py`: TestModel 专用单阻容管道近似，入口压降 + 出口直连内容腔
+- `components/experimental/junctions/tee.py`: 三通的最小 stream 混合 helper
+- `examples/testmodel/system.py`: `Testmodel` 的系统装配壳与外部运行入口
+- `examples/testmodel/closure.py`: `Testmodel` 当前专用的闭合、初始化投影、分支求解与端口回写
+- `examples/test_mql/system.py`: `test_mql` 系统装配、132 状态总闭包和关键输出映射
+- `examples/test_mql/closure.py`: `test_mql` 气动网络 closure、snapshot、流量计算和端口写回
+- `examples/test_mql/primitives/`: 固定算例专用的 Peng-Robinson 氦气、管路和机械校准原语
+- `examples/test_mql/structural_network.py`: 固定算例专用的结构网络；不替代带端口契约校验的通用网络
+- `reporting/testmodel_outputs.py`: `Testmodel` 的 CSV/SVG/对比摘要导出
+- `reporting/amesim_results.py`: AMESim 结果读取入口
+- `examples/test_mql/run_full_state_comparison.py`: `test_mql` 短时域 AMESim comparison 和诊断入口
+- `examples/test_mql/run.py`: `test_mql` 结构运行与程序化执行入口
+- `tests/`: 当前组件契约、XML、通用系统、AMESim 迁移和结果导出测试
+
+## 可选性能诊断
+
+`SIMULATIONAPP_PROFILE` 支持 `off`（默认）、`standard` 和 `audit`。`standard`
+只统计低频的大阶段；`audit` 才展开 RHS、代数闭合、stream 和物性调用，开销也
+明显更高。最终优化收益必须在 `off` 下复测。
+
+Peng–Robinson 氦气的高开销物性默认使用一次仿真内独立的精确 LRU 缓存；不同
+仿真任务不会共享条目，仿真结束后自动释放。可在启动进程前设置
+`SIMULATIONAPP_PROPERTY_CACHE=off` 做数值和性能 A/B，正常运行保持默认 `on`。
+缓存只复用完全相同的输入，不做四舍五入或容差匹配。
+
+FastAPI worker 默认在 lifespan 启动阶段预热 SciPy 积分、非线性求解、稀疏
+Jacobian 和 System XML XSD，完成后才开始接收请求。它不会运行业务模型，也不
+写入文件；如需诊断冷启动，可设置 `SIMULATIONAPP_WARMUP=off`。每个 worker 都会
+独立暖机一次。
+
+```powershell
+.venv-win\Scripts\python.exe -m app.simulation.benchmark_performance `
+  --mode audit --warmups 1 --runs 3 `
+  --factory "helium_step=tests.test_amesim_pnvo001_signal_xml:high_pressure_helium_step_project" `
+  --output app/data/performance-evaluations/helium-step.json
+```
+
+缓存关闭对照可在同一命令中增加 `--disable-property-cache`。缓存容量、命中、
+未命中和驱逐数会在 audit 响应的
+`diagnostics.performance.propertyCache` 中返回。
+
+基准原始 JSON 默认放到已忽略的 `app/data/` 下。指标字段、实测结果和使用边界见
+[`仿真性能评估 2026-08-15`](../../docs/other/仿真性能评估-2026-08-15.md)。
+
+## 当前阶段进度
+
+这一阶段原先有 4 件重点工作，现在的状态如下：
+
+1. `mytee1` 的 stream/焓传播语义：已完成当前阶段收紧
+   现在如果只有一条支路发生倒流，下游来流焓统一按 `tank.h` 处理，不再临时借另一条支路的焓来凑。
+2. 下游初始化/约束处理：已完成当前阶段收口
+   之前是“直接改对象状态再开始积分”，现在已经收成显式的 `consistent_initial_state_vector()` 初始化入口。当前这一步会在不改下游总质量、总内能的前提下，把几段直接相连的体积拉回同一个连接压力。
+3. 自动校验：已完成当前阶段首版
+   已经补了标准库 `unittest` 回归测试，先把初始化投影是否守恒、是否污染原始状态，以及 4 个主变量的提交基线锁住。
+4. 更严格介质模型：已完成当前阶段首版
+   已经从固定 `cp/cv` 的理想气体近似，推进到随温度变化的空气近似，并接上了内能反解和初始化求根。
+
+如果只看结果，可以把这一阶段理解成：
+
+- 连接器语义：首轮收紧已完成
+- 初始化入口：首轮收口已完成
+- 基线验证：首轮保护已完成
+- 介质精化：首轮近似已完成
+
+## 当前阶段收口
+
+上一轮 `N0-N3` 已全部完成首版，当前可以简单理解为：
+
+1. `N0`：系统层里最明显的流向/焓判断已经继续下沉到组件 helper。
+2. `N1`：模型参数和运行参数已经收口到配置对象。
+3. `N2`：运行接口已经分成“准备请求”和“执行请求”两层。
+4. `N3`：结果导出和命令行报告格式化已经统一收口到 `reporting/`。
+
+这一轮结束后，项目已经不缺“能不能跑”的能力，下一步更重要的是把后续开发最容易卡住的地方先处理掉。
+
+## 本次推送更新
+
+本次推送已经把上一轮建议里的 `M2-M5` 推进到下面这个状态：
+
+1. `M2`：已完成当前阶段首版
+   - 已把 `Testmodel` 的专用闭合、初始化投影、分支入口流量求解、下游支路出口流量闭合、端口状态回写，从 `examples/testmodel/system.py` 拆到 `examples/testmodel/closure.py`
+   - `TestModelSystem` 现在主要承担组件装配、网络注册和对闭合器的委托，不再继续堆积系统级手写细节
+
+2. `M3`：已完成当前阶段首版
+   - 已给两条支路入口流量固定点求解、下游公共压力投影补了显式诊断
+   - 诊断内容至少包含 `converged / iterations / residual`
+   - 已支持严格模式；内部求解不收敛时可以直接抛错，而不是静默返回最后一个近似值
+   - `run_testmodel()` 的结构化结果和 `testmodel_run_report.txt` 已能带出最后一次内部闭合求解诊断
+
+3. `M4`：已完成当前阶段首版
+   - 自动测试已不再只盯最终主变量结果
+   - 现在已经覆盖：
+     - 改支路参数后，初始支路入口流量是否按预期变化
+     - 更偏激配置下，初始化和内部闭合是否仍然收敛
+     - 有无 Modelica 参考两种运行路径下，程序接口与产物行为是否一致
+
+4. `M5`：已启动
+   - 当前已经明确选择优先走“更容易扩展”的方向，而不是先追求更贴近 Modelica
+   - 已完成第一步：把闭合器内部原来大量写死的 `upper/lower` 双支路逻辑，收成可复用的 `BranchClosureComponents / BranchClosureState` 结构
+   - 当前已继续推进到 `G1-G5` 的首轮兼容层改造：`snapshot` 已提供通用分支集合，系统层结果生成已拆成“通用键生成 + 旧键别名派生”两层，报告层已开始优先消费通用分支键，旧导出列名仍通过兼容映射保留，兼容测试已显式保护分支顺序和旧导出语义
+
+## 下一阶段接手建议
+
+如果继续往前推进，建议按下面顺序做，而不是再零散补功能：
+
+1. `G1`：已完成当前阶段首轮兼容接入
+   - `TestModelSnapshot` 已新增 `branches` 集合
+   - 每个分支当前至少带 `name / pipe / inlet_flow / outlet_flow / inlet_h / inlet_flow_diagnostics`
+   - `pipe_upper / pipe_lower / branch_inlet_flows / branch_outlet_flows` 目前仍保留为兼容属性，供旧调用方继续使用
+
+2. `G2`：已完成当前阶段首轮内部迁移
+   - `evaluate_solution()` 已改成从 `snapshot.branches` 读取数据，再通过显式分支名映射写回当前旧列名
+   - `rhs()` 里的分支导数计算已改成通过通用 helper 按分支循环生成，再按当前状态向量顺序拼回
+   - 当前外部导出列名仍保持兼容：
+     - `mypipe.p`
+     - `mypipe1.p`
+     - `branch_upper.in/out`
+     - `branch_lower.in/out`
+
+3. `G3`：已完成当前阶段首轮兼容测试
+   - 当前测试已经显式保护：
+     - `branches` 顺序是否稳定
+     - `snapshot` 新字段和兼容字段是否一致
+     - 旧导出列名是否仍映射到正确分支语义
+     - 参数变化后 `upper/lower` 的名字和顺序是否不会被打乱
+
+4. `G4`：已完成当前阶段首轮兼容拆层
+   - `evaluate_solution()` 现在会同时产出：
+     - 通用分支键：`branch.<branch_name>.p/in/out`
+     - 旧兼容键：`mypipe.p`、`mypipe1.p`、`branch_upper.*`、`branch_lower.*`
+   - 报告层当前已开始优先读取通用分支键，旧键只作为兼容后备
+   - 当前已经把“内部统一表达”和“旧接口兼容导出”拆成两层，但还没有把所有报告/导出逻辑都迁干净
+
+5. `G5`：已完成当前阶段首轮兼容收口
+   - `evaluate_solution()` 当前会先生成通用分支键，再统一派生旧兼容键
+   - 报告层当前已支持“通用键优先、旧键兼容后备”
+   - 当前已经把系统层和 reporting 层的主要旧专名读取入口收口到少量 helper 上，后续继续迁移不会再到处散改
+
+6. `P1`：下一阶段建议从这里接手
+   当前更合适的下一步，不是继续深挖内核通用化，而是切回结果导向主线：
+   - 定义一份稳定的外部输入参数 schema
+   - 明确这些结构化参数如何映射到 `TestModelConfig / TestModelRunConfig`
+   - 建立“结构化参数 -> 仿真执行 -> 结果产物/摘要”的稳定接口
+   这样可以直接服务后续文档解析、网页入口和报告生成，而不是继续在 `Testmodel` 内部做边际收益越来越低的抽象整理
+
+7. `P2`：在 `P1` 完成后，再推进文档解析或报告生成链路
+   更现实的顺序应是：
+   - 先把结构化输入跑通
+   - 再把结果摘要/产物组织成更接近最终产品的输出包
+   - 最后再接 Word 解析或页面入口
+
+如果后续继续推进，这个 README 也要一起更新，不要长期保留已经失效的路线描述。
+
+## 当前实现了什么
+
+当前代码已经实现：
+
+1. `m`、`U` 作为动态元件主状态，`p`、`T`、`rho`、`u`、`h` 作为派生量。
+2. `Cylinder`、`Tank`、`Pipe` 的刚性绝热容腔近似。
+3. `Orifice` 的压差开方流量关系。
+4. `Tee` 的简化混合焓处理。
+5. `Testmodel` 的系统级拓扑映射和一版可运行的 `rhs(t, x)`。
+6. 基于 `solve_ivp` 的积分入口，以及 SciPy 不可用时的 RK4 回退。
+7. 温度相关空气近似介质，包括 `cp(T)`、`h(T)`、`u(T)` 以及 `u -> T` 反解。
+8. 显式一致初值入口 `consistent_initial_state_vector()`，以及可迭代初始化器 `initialize_consistent_state()`。
+9. Python 主变量结果导出：
+   `mytank.p`、`mytank.T`、`mycylinder.p`、`mycylinder.T`
+10. 贮箱温度曲线导出：
+   `testmodel_tank_temperature.csv`
+   `testmodel_tank_temperature.svg`
+11. 基于 `ModelicaModels/Simulation/Testmodel_res.csv` 的逐时刻对比与误差摘要导出。
+12. 基于 `unittest` 的自动回归测试，当前已覆盖初始化守恒、主变量基线、运行接口、内部闭合诊断、通用分支兼容层、通用结果键与旧键别名一致性，以及部分中间闭合过程行为。
+13. 面向 System XML v3 的拓扑驱动仿真 MVP：压力-流量非线性闭合、stream 焓传播、动态状态自动拼装和端口结果序列。
+
+当前没有实现：
+
+- 通用 DAE 初始化器
+- `Modelica.Media.Air.SimpleAir` 的严格复刻
+- 一般高指数 DAE、事件和严格 Modelica `inStream/actualStream` 求解器
+
+## 当前怎么运行
+
+最小运行方式：
+
+```bash
+python -m app.simulation.examples.testmodel.run
+```
+
+如果要改模型参数或运行参数，建议直接改配置对象，而不是改源码里的默认值。例如：
+
+```python
+from app.simulation.examples.testmodel.run import (
+    TestModelRunConfig,
+    TestModelSamplingConfig,
+    run_testmodel,
+)
+from app.simulation.examples.testmodel.system import (
+    BranchConfig,
+    CylinderConfig,
+    OrificeConfig,
+    PipeConfig,
+    TankConfig,
+    TestModelConfig,
+)
+from app.simulation.solvers.solver import SolveIVPConfig
+
+run_config = TestModelRunConfig(
+    model=TestModelConfig(
+        cylinder=CylinderConfig(p0=30e6),
+        upper_branch=BranchConfig(
+            orifice=OrificeConfig(K=8e-6),
+            pipe=PipeConfig(length=6.0, diameter=0.03),
+        ),
+        tank=TankConfig(volume=0.12),
+    ),
+    solver=SolveIVPConfig(t_start=0.0, t_stop=10.0, method="BDF"),
+    sampling=TestModelSamplingConfig(step=0.05),
+)
+
+result = run_testmodel(run_config=run_config)
+```
+
+如果调用方想先确认“这次运行最后到底会用哪些路径、哪些采样点”，可以先准备请求，再执行：
+
+```python
+from app.simulation.examples.testmodel.run import (
+    prepare_testmodel_run,
+    run_prepared_testmodel,
+    TestModelRunConfig,
+)
+
+prepared = prepare_testmodel_run(run_config=TestModelRunConfig())
+print(prepared.output_dir)
+print(prepared.t_eval)
+
+result = run_prepared_testmodel(prepared)
+print(result.artifacts.primary_csv_path)
+print(result.used_modelica_reference)
+```
+
+当前脚本会：
+
+1. 构建 `TestModelSystem`
+2. 打印原始初值向量与约束一致后的初值向量
+3. 运行 `0 s -> 20 s` 的仿真，默认采样间隔 `0.1 s`
+4. 将结果写入 `app/data/simulation-runs/` 下本次运行专属的时间戳目录
+5. 若存在 `ModelicaModels/Simulation/Testmodel_res.csv`，自动生成 Python 与 OpenModelica 对比结果
+
+当前脚本默认不会把运行结果直接写到提交基线目录，而是会在
+`app/data/simulation-runs/` 下创建一个带时间戳的子目录，例如：
+
+- `app/data/simulation-runs/testmodel_20260512_103000_123456/`
+
+该目录里通常会包含：
+
+- `testmodel_primary_series.csv`
+- `testmodel_tank_temperature.csv`
+- `testmodel_tank_temperature.svg`
+- `testmodel_run_report.txt`
+- `testmodel_modelica_comparison.csv`
+- `testmodel_modelica_comparison_summary.txt`
+
+## 基线结果
+
+当前基线对比摘要来自：
+[`testmodel_modelica_comparison_summary.txt`](../../tests/data/testmodel/testmodel_modelica_comparison_summary.txt)
+
+当前四个主变量的最大误差为：
+
+- `mytank.p`: `max_abs_error = 134.960858 Pa`, `max_rel_error = 0.006798%`
+- `mytank.T`: `max_abs_error = 0.035507 K`, `max_rel_error = 0.009016%`
+- `mycylinder.p`: `max_abs_error = 1391.986349 Pa`, `max_rel_error = 0.009447%`
+- `mycylinder.T`: `max_abs_error = 0.009069 K`, `max_rel_error = 0.003870%`
+
+这说明在当前基线工况下，Python 版主变量已经能较好贴近 OpenModelica 结果。
+
+## AMESim test_mql 当前进度
+
+`test_mql` 从 `AmesimModels/test_mql.ame` 迁移，并与旧 `testmodel` 保持独立。
+固定算例实现统一位于 `examples/test_mql/`，结果读取和比较能力位于
+`reporting/`；公开拖拽组件由 `components/amesim/library.py` 单独登记。
+
+当前已形成 112 个气动状态和 20 个机械状态的总闭包、AMESim 原生结果读取、
+`Data_Path` 输出校验及短时域 comparison。这里不再复制易过期的数值进度；
+最新对比结果、运行命令、限制和下一步校准路径以
+[`AmesimModels/test_mql/README.md`](../../AmesimModels/test_mql/README.md)
+为唯一说明。当前仍不能宣称 Python 时域仿真与 AMESim 全局一致。
+
+## Testmodel 当前架构判断
+
+如果按“组件正确 -> 网络闭合 -> 积分可跑 -> 结果对齐 -> 去近似”来看，当前大致处于：
+
+- 组件级：已完成首版
+- 系统闭合：已完成首版
+- 积分入口：已完成首版
+- 基线结果对齐：已具备初步能力
+- 去近似：仍在进行中
+
+所以当前最准确的说法不是“已完成移植”，而是：
+
+`Testmodel` 已有一版可运行、可导出、可对比的 Python 近似实现。
+
+## Testmodel 已知限制
+
+当前最主要的限制可以直接理解成下面几条：
+
+- 介质模型已从常 `cp/cv` 推进到温度相关空气近似，但仍不是 `Modelica.Media.Air.SimpleAir` 的严格复刻。
+- 系统整体仍是 ODE 化近似，不是原始 Modelica DAE 的直接复现。
+- `mytee1 -> mytank` 这一段虽然已经去掉早期的“虚拟出口导通系数”，改成了基于压力一致性的下游能量闭合，但本质上仍是工程近似。
+- 通用 XML 求解链路已经支持按实际流向传播和三通混合 stream 焓，但仍是正则化 MVP，不是严格的 Modelica `inStream/actualStream` 框架。
+- 当前一致初值仍是 ODE 入口处的约束投影，不等同于真正的 DAE 初始化求解。
+- 当前自动校验主要锁的是 Python 提交基线，还不是稳定的 Modelica 阈值回归。
+- 当前闭合器、系统层和 reporting 层虽然已经开始做“双支路结构化”，但对外结果序列、报告字段和部分导出命名仍然保留 `Testmodel` 专名兼容层，还没有完全转成通用表达。
+- 当前内核已经足够支撑下一阶段“结构化参数 -> 仿真执行 -> 产物输出”的链路开发，但还没有现成的 Word 参数解析入口和正式报告生成链路。
+
+所以，当前版本适合：
+
+- 架构验证
+- 组件接口验证
+- 基线工况对比
+- 结果导出与误差定位
+
+但当前版本还不适合：
+
+- 直接宣称与 OpenModelica 严格等价
+- 作为最终工程结论的唯一依据
+- 直接扩展到更复杂拓扑而不补通用连接器语义
+
+## Testmodel 文件级现状
+
+按代码现状逐项看：
+
+- `core/base.py`: 正常
+  只提供最小抽象层，没有明显冗余。
+- `core/ports.py`: 正常
+  `PortState` 目前只保留 `p`、`m_flow`、`h_outflow` 三个必要字段。
+- `core/state.py`: 正常
+  `VolumeState` 只负责 `[m, U]` 状态打包。
+- `systems/network.py`: 正常
+  负责状态向量拼装和连接摘要，不参与物理求解。
+- `solvers/solver.py`: 正常
+  已支持 SciPy、RK4 回退和零时长仿真。
+- `components/experimental/**/*.py`: 正常
+  都是当前一版近似模型，没有发现与 README 明显冲突的“未记录能力”。
+- `examples/testmodel/system.py`: 是当前最重要的技术债集中区
+  这里承载了下游流向切换、焓混合、压力投影等近似逻辑，后续演进应主要落在这里。
+- `examples/testmodel/run.py`: 正常
+  已不是“最小打印脚本”，而是当前结果导出和对比入口。
+- `tests/baselines/simulation/`: 是当前稳定基线，不应该随着日常运行频繁改动。
+- `app/data/simulation-runs/`: 是默认运行产物目录，不是手写源代码，也不应该提交。
+
+## Testmodel 当前主技术债
+
+目前最主要的技术债，可以直接理解成下面 4 件事：
+
+1. 当前初始化虽然已经引入迭代诊断，但本质上仍是 ODE 入口近似，不是真正的 DAE 初始化器。
+2. `examples/testmodel/system.py` 还是承载了太多系统级闭合和初始化逻辑，只是主要端口的手写 stream 方向判断已经搬到组件 helper 里了，装配参数本身已经基本收口到配置对象。
+3. 自动校验现在主要锁的是 Python 这一版自己的基线，还不是稳定的 Modelica 阈值回归。
+4. 当前空气物性已经完成首轮基线校准，但还不是 `SimpleAir` 的严格复刻。以后如果换工况，或者拿到更多 Modelica 原始结果，参数大概率还要继续调。
@@ -1,38 +0,0 @@
-"""One execution boundary shared by XML API and native validation tools."""
-from __future__ import annotations
-
-import os
-
-from app.simulation.config import SolveIVPConfig
-
-
-DEFAULT_NUMERIC_ENGINE = "native"
-
-
-def numeric_engine_name(backend: str | None = None) -> str:
-    configured = backend or os.environ.get("SIMULATION_NUMERIC_ENGINE", "")
-    selected = configured.strip().lower() or DEFAULT_NUMERIC_ENGINE
-    if selected == "native-c":
-        return "native"
-    if selected == "native":
-        return selected
-    if selected == "python":
-        raise ValueError("The Python numerical backend has been removed. Use SIMULATION_NUMERIC_ENGINE=native.")
-    raise ValueError(f"Unknown simulation engine: {selected}.")
-
-
-def simulation_config(simulation) -> SolveIVPConfig:
-    # Match the validated native pipe/chamber accuracy. Per-state SI absolute
-    # floors are emitted by native_codegen.tolerances; XML tolerance fields
-    # remain a separate protocol change.
-    return SolveIVPConfig(t_start=simulation.t_start, t_stop=simulation.t_stop,
-                         method=simulation.method, rtol=1e-8, max_step=simulation.max_step)
-
-
-def simulate_network(network, simulation, *, progress_callback=None,
-                     warning_callback=None, cancel_check=None, activity_tracker=None, backend=None, raw_series=False):
-    numeric_engine_name(backend)
-    config = simulation_config(simulation)
-    from app.simulation.native_codegen.runner import simulate_native
-    return simulate_native(network, config, sample_step=simulation.sample_step, progress_callback=progress_callback,
-               warning_callback=warning_callback, cancel_check=cancel_check, activity_tracker=activity_tracker, raw_series=raw_series)
@@ -0,0 +1,244 @@
+from __future__ import annotations
+
+import argparse
+import hashlib
+import importlib
+import json
+import os
+import platform
+import statistics
+import sys
+from datetime import UTC, datetime
+from math import ceil
+from pathlib import Path
+from time import perf_counter_ns, process_time_ns
+from typing import Any
+
+
+def _named_value(value: str, *, option: str) -> tuple[str, str]:
+    name, separator, target = value.partition("=")
+    if not separator or not name.strip() or not target.strip():
+        raise ValueError(
+            f"{option} must use NAME=VALUE syntax, received {value!r}."
+        )
+    return name.strip(), target.strip()
+
+
+def _percentile(values: list[float], percentile: float) -> float:
+    ordered = sorted(values)
+    index = max(0, min(len(ordered) - 1, ceil(percentile * len(ordered)) - 1))
+    return ordered[index]
+
+
+def _duration_summary(values: list[float]) -> dict[str, object]:
+    return {
+        "samplesMs": values,
+        "minimumMs": min(values),
+        "medianMs": statistics.median(values),
+        "p95Ms": _percentile(values, 0.95),
+        "maximumMs": max(values),
+    }
+
+
+def _load_factory_xml(specification: str) -> bytes:
+    module_name, separator, member_name = specification.partition(":")
+    if not separator or not module_name or not member_name:
+        raise ValueError(
+            "Factory specifications must use module.path:callable syntax."
+        )
+    factory = getattr(importlib.import_module(module_name), member_name)
+    value = factory()
+    if isinstance(value, bytes):
+        return value
+    if isinstance(value, str):
+        return value.encode("utf-8")
+
+    from app.main import build_reactflow_system_xml
+
+    return build_reactflow_system_xml(value)
+
+
+def _serialize_result_event(result: dict[str, object]) -> bytes:
+    """Render the final NDJSON payload shape used by the streaming endpoint."""
+
+    status = str(result.get("status", "completed"))
+    event = {
+        "event": "result",
+        "progress": 100 if status == "completed" else 0,
+        "phase": status,
+        "message": "仿真完成" if status == "completed" else "仿真任务结束",
+        "simulatedTime": result.get("simulatedUntil"),
+        "totalTime": result.get("requestedStopTime"),
+        "result": result,
+    }
+    return (
+        json.dumps(event, ensure_ascii=False, separators=(",", ":")) + "\n"
+    ).encode("utf-8")
+
+
+def _run_case(
+    name: str,
+    xml_bytes: bytes,
+    *,
+    warmups: int,
+    runs: int,
+    cancellable_path: bool,
+    allow_failures: bool,
+) -> dict[str, object]:
+    from app.main import run_system_xml_simulation
+
+    cancel_check = (lambda: False) if cancellable_path else None
+    for _ in range(warmups):
+        result = run_system_xml_simulation(xml_bytes, cancel_check=cancel_check)
+        if not bool(result.get("success")) and not allow_failures:
+            raise RuntimeError(f"Warmup for {name!r} failed: {result.get('message')}")
+
+    wall_samples_ms: list[float] = []
+    cpu_samples_ms: list[float] = []
+    serialization_samples_ms: list[float] = []
+    serialized_sizes: list[int] = []
+    profiles: list[dict[str, object]] = []
+    final_result: dict[str, object] | None = None
+    for _ in range(runs):
+        wall_start = perf_counter_ns()
+        cpu_start = process_time_ns()
+        result = run_system_xml_simulation(xml_bytes, cancel_check=cancel_check)
+        cpu_samples_ms.append((process_time_ns() - cpu_start) / 1_000_000.0)
+        wall_samples_ms.append((perf_counter_ns() - wall_start) / 1_000_000.0)
+        if not bool(result.get("success")) and not allow_failures:
+            raise RuntimeError(f"Benchmark for {name!r} failed: {result.get('message')}")
+        diagnostics = result.get("diagnostics")
+        if isinstance(diagnostics, dict):
+            performance = diagnostics.get("performance")
+            if isinstance(performance, dict):
+                profiles.append(performance)
+        serialization_start = perf_counter_ns()
+        serialized_event = _serialize_result_event(result)
+        serialization_samples_ms.append(
+            (perf_counter_ns() - serialization_start) / 1_000_000.0
+        )
+        serialized_sizes.append(len(serialized_event))
+        final_result = result
+
+    assert final_result is not None
+    return {
+        "name": name,
+        "success": bool(final_result.get("success")),
+        "message": final_result.get("message"),
+        "inputBytes": len(xml_bytes),
+        "inputSha256": hashlib.sha256(xml_bytes).hexdigest(),
+        "status": final_result.get("status"),
+        "simulatedUntil": final_result.get("simulatedUntil"),
+        "requestedStopTime": final_result.get("requestedStopTime"),
+        "wall": _duration_summary(wall_samples_ms),
+        "cpu": _duration_summary(cpu_samples_ms),
+        "resultSerialization": _duration_summary(serialization_samples_ms),
+        "resultEventBytes": serialized_sizes,
+        "performanceRuns": profiles,
+    }
+
+
+def _parse_arguments(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Benchmark the real System XML simulation path with optional profiling."
+    )
+    parser.add_argument(
+        "--mode",
+        choices=("off", "standard", "audit"),
+        default="audit",
+        help="Instrumentation depth selected before importing the simulation modules.",
+    )
+    parser.add_argument("--warmups", type=int, default=1)
+    parser.add_argument("--runs", type=int, default=5)
+    parser.add_argument(
+        "--xml",
+        action="append",
+        default=[],
+        metavar="NAME=PATH",
+        help="Add an XML file benchmark case.",
+    )
+    parser.add_argument(
+        "--factory",
+        action="append",
+        default=[],
+        metavar="NAME=MODULE:CALLABLE",
+        help="Add a zero-argument factory returning XML or ReactFlowProjectPayload.",
+    )
+    parser.add_argument(
+        "--direct-path",
+        action="store_true",
+        help="Do not pass a cancel callback; use the one-shot SciPy path when eligible.",
+    )
+    parser.add_argument(
+        "--disable-property-cache",
+        action="store_true",
+        help="Disable the run-local exact property cache for an A/B comparison.",
+    )
+    parser.add_argument(
+        "--allow-failures",
+        action="store_true",
+        help="Record failed simulation runs instead of aborting the benchmark.",
+    )
+    parser.add_argument("--output", type=Path)
+    arguments = parser.parse_args(argv)
+    if arguments.warmups < 0:
+        parser.error("--warmups must not be negative.")
+    if arguments.runs <= 0:
+        parser.error("--runs must be positive.")
+    if not arguments.xml and not arguments.factory:
+        parser.error("At least one --xml or --factory case is required.")
+    return arguments
+
+
+def main(argv: list[str] | None = None) -> int:
+    arguments = _parse_arguments(argv)
+    os.environ["SIMULATIONAPP_PROFILE"] = arguments.mode
+    os.environ["SIMULATIONAPP_PROPERTY_CACHE"] = (
+        "off" if arguments.disable_property_cache else "on"
+    )
+
+    cases: list[tuple[str, bytes]] = []
+    for raw_case in arguments.xml:
+        name, raw_path = _named_value(raw_case, option="--xml")
+        cases.append((name, Path(raw_path).read_bytes()))
+    for raw_case in arguments.factory:
+        name, specification = _named_value(raw_case, option="--factory")
+        cases.append((name, _load_factory_xml(specification)))
+
+    report: dict[str, Any] = {
+        "generatedAt": datetime.now(UTC).isoformat(),
+        "profileMode": arguments.mode,
+        "cancellableSolverPath": not arguments.direct_path,
+        "propertyCacheEnabled": not arguments.disable_property_cache,
+        "allowFailures": bool(arguments.allow_failures),
+        "warmups": arguments.warmups,
+        "runs": arguments.runs,
+        "runtime": {
+            "python": sys.version,
+            "platform": platform.platform(),
+            "processor": platform.processor(),
+        },
+        "cases": [
+            _run_case(
+                name,
+                xml_bytes,
+                warmups=arguments.warmups,
+                runs=arguments.runs,
+                cancellable_path=not arguments.direct_path,
+                allow_failures=arguments.allow_failures,
+            )
+            for name, xml_bytes in cases
+        ],
+    }
+    text = json.dumps(report, ensure_ascii=False, indent=2)
+    if arguments.output is not None:
+        arguments.output.parent.mkdir(parents=True, exist_ok=True)
+        arguments.output.write_text(text + "\n", encoding="utf-8")
+        print(f"Performance report written to {arguments.output.resolve()}")
+    else:
+        print(text)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
@@ -1,11 +1,13 @@
-"""Component parameters, ports and output definitions; numerical equations execute in C."""
 from __future__ import annotations
+
 from collections.abc import Mapping
+
 from app.simulation.core.base import AlgebraicComponent
 from app.simulation.core.catalog import ComponentDisplaySpec, PortDisplaySpec
+from app.simulation.core.equations import EquationResidual
 from app.simulation.core.medium import IdealGasMedium
 from app.simulation.core.ports import PortDefinition
-from app.simulation.core.port_computation import ZERO_FLOW_SUPPLY
+

 class AmesimPnpl01(AlgebraicComponent):
    """AMESim PNPL01 zero pneumatic flow source.
@@ -14,19 +16,53 @@ class AmesimPnpl01(AlgebraicComponent):
    solver: it does not prescribe pressure, and only constrains its port mass
    flow to zero.
    """
-    MODEL_TYPE = 'amesim_pnpl01'
-    MODEL_VERSION = '0.1.0'
-    PORTS = (PortDefinition.pneumatic('port_1', computation=ZERO_FLOW_SUPPLY),)
+
+    MODEL_TYPE = "amesim_pnpl01"
+    MODEL_VERSION = "0.1.0"
+    PRESSURE_FLOW_DEPENDS_ON_STREAM = False
+    PORTS = (PortDefinition.pneumatic("port_1", nominal_role="bidirectional"),)
    PARAMETERS = ()
    RESULT_VARIABLES = ()
-    DISPLAY = ComponentDisplaySpec(label='PNPL01 零气动流边界', library_id='amesim', category_id='boundary', symbol='amesim_pnpl01', ports=(PortDisplaySpec('port_1', 'left', order=10),), order=10)
+    DISPLAY = ComponentDisplaySpec(
+        label="PNPL01 零气动流边界",
+        library_id="amesim",
+        category_id="boundary",
+        symbol="amesim_pnpl01",
+        ports=(PortDisplaySpec("port_1", "left", order=10),),
+        order=10,
+    )

    def __init__(self, name: str) -> None:
        super().__init__(name=name)
        self.set_parameter_values({})
-        self.port_1 = self.register_declared_port('port_1')
+        self.port_1 = self.register_declared_port("port_1")

    @classmethod
-    def create(cls, *, name: str, medium: IdealGasMedium, parameters: Mapping[str, float]) -> AmesimPnpl01:
+    def create(
+        cls,
+        *,
+        name: str,
+        medium: IdealGasMedium,
+        parameters: Mapping[str, float],
+    ) -> AmesimPnpl01:
        return cls(name=name)
-    EQUATIONS = ({'id': '__MODEL__:zero_mass_flow', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'constitutive', 'variables': ['__MODEL__.port_1.m_flow'], 'role': 'flow'},)
+
+    def pressure_flow_equation_values(self) -> tuple[float, ...]:
+        return (self.port_1.m_flow,)
+
+    def pressure_flow_equation_residuals(self) -> tuple[EquationResidual, ...]:
+        return (
+            EquationResidual(
+                id=f"{self.name}:zero_mass_flow",
+                owner="component",
+                owner_id=self.name,
+                relation="constitutive",
+                variables=(f"{self.name}.port_1.m_flow",),
+                role="flow",
+                value=self.port_1.m_flow,
+            ),
+        )
+
+    def update_stream_outflows(self, connected_h: Mapping[str, float]) -> None:
+        if "port_1" in connected_h:
+            self.port_1.h_outflow = connected_h["port_1"]
@@ -1,23 +1,43 @@
-"""Component parameters, ports and output definitions; numerical equations execute in C."""
 from __future__ import annotations
+
 from collections.abc import Mapping
+
 from app.simulation.core.base import AlgebraicComponent
 from app.simulation.core.catalog import ComponentDisplaySpec, PortDisplaySpec
+from app.simulation.core.equations import EquationResidual
 from app.simulation.core.medium import IdealGasMedium
-from app.simulation.core.ports import PortDefinition
-from app.simulation.core.port_computation import NODE_BRANCH, NODE_REFERENCE
+from app.simulation.core.ports import PortDefinition, PortState
+
+
+_REFERENCE_OUTFLOW_REGULARIZATION_RATIO = 0.05
+
+
+def _regularized_inverse_outflow(flow: float, transition_flow: float) -> float:
+    """Return a C1 inverse that tends to zero as a negative flow vanishes."""
+
+    if flow >= 0.0:
+        return 0.0
+    transition_flow = max(float(transition_flow), 1.0e-12)
+    if -flow >= transition_flow:
+        return 1.0 / flow
+    return (
+        flow
+        * (2.0 * transition_flow * transition_flow - flow * flow)
+        / transition_flow**4
+    )
+

 class _AmesimPneumaticNode(AlgebraicComponent):
    """Shared implementation for AMESim pneumatic junction submodels.

    PN3NODE2/P4NODE2 use port 2 as their pressure and temperature reference.
-    Non-reference outlet ports use that reference temperature. Signed branch
-    enthalpy flows are summed and delivered to port 2 independently of its net
-    mass flow, matching AMESim dh2 causality even at zero net mass flow.
-    The finite h_outflow diagnostic cannot encode that zero-flow energy.
-    Branch volumes and volume rates are also summed towards port 2.
+    Non-reference outlet ports use that reference temperature. When port 2 is
+    an outlet, its enthalpy is the residual that closes the junction energy
+    balance, matching the AMESim dh2 causality.
    """
-    REFERENCE_PORT = 'port_2'
+
+    PRESSURE_FLOW_DEPENDS_ON_STREAM = False
+    REFERENCE_PORT = "port_2"

    def __init__(self, name: str) -> None:
        super().__init__(name=name)
@@ -26,30 +46,194 @@ class _AmesimPneumaticNode(AlgebraicComponent):
        for definition in self.PORTS:
            setattr(self, definition.name, self.register_declared_port(definition.name))

+    def pressure_flow_equation_values(self) -> tuple[float, ...]:
+        reference = self.get_port(self.REFERENCE_PORT)
+        return tuple(
+            self.get_port(definition.name).p - reference.p
+            for definition in self.PORTS
+            if definition.name != self.REFERENCE_PORT
+        ) + (
+            sum(
+                self.get_port(definition.name).m_flow
+                for definition in self.PORTS
+            ),
+        )
+
+    def pressure_flow_equation_residuals(self) -> tuple[EquationResidual, ...]:
+        reference = self.get_port(self.REFERENCE_PORT)
+        residuals: list[EquationResidual] = []
+        for definition in self.PORTS:
+            if definition.name == self.REFERENCE_PORT:
+                continue
+            port = self.get_port(definition.name)
+            residuals.append(
+                EquationResidual(
+                    id=f"{self.name}:{definition.name}_pressure_reference",
+                    owner="component",
+                    owner_id=self.name,
+                    relation="equal",
+                    variables=(
+                        f"{self.name}.{definition.name}.p",
+                        f"{self.name}.{self.REFERENCE_PORT}.p",
+                    ),
+                    role="effort",
+                    value=port.p - reference.p,
+                )
+            )
+        residuals.append(
+            EquationResidual(
+                id=f"{self.name}:mass_flow_balance",
+                owner="component",
+                owner_id=self.name,
+                relation="sumToZero",
+                variables=tuple(
+                    f"{self.name}.{definition.name}.m_flow"
+                    for definition in self.PORTS
+                ),
+                role="flow",
+                value=sum(self.get_port(definition.name).m_flow for definition in self.PORTS),
+            )
+        )
+        return tuple(residuals)
+
+    def update_stream_outflows(self, connected_h: Mapping[str, float]) -> None:
+        self.temperature_reference_h = connected_h.get(
+            self.REFERENCE_PORT,
+            sum(connected_h.values()) / len(connected_h) if connected_h else 0.0,
+        )
+        incoming = [
+            (port.m_flow, connected_h[name])
+            for name, port in self.ports.items()
+            if port.m_flow > 1e-12
+        ]
+        total_flow = sum(m_flow for m_flow, _ in incoming)
+        if total_flow > 1e-12:
+            mixed_h = sum(m_flow * h for m_flow, h in incoming) / total_flow
+        else:
+            mixed_h = self.temperature_reference_h
+
+        reference_port = self.get_port(self.REFERENCE_PORT)
+        for name, port in self.ports.items():
+            port.h_outflow = (
+                mixed_h
+                if name == self.REFERENCE_PORT
+                else self.temperature_reference_h
+            )
+
+        if reference_port.m_flow < 0.0:
+            energy_without_reference = sum(
+                port.m_flow
+                * (
+                    connected_h[name]
+                    if port.m_flow > 1e-12
+                    else self.temperature_reference_h
+                )
+                for name, port in self.ports.items()
+                if name != self.REFERENCE_PORT
+            )
+            non_reference_flow_scale = sum(
+                abs(port.m_flow)
+                for name, port in self.ports.items()
+                if name != self.REFERENCE_PORT
+            )
+            transition_flow = (
+                _REFERENCE_OUTFLOW_REGULARIZATION_RATIO
+                * non_reference_flow_scale
+            )
+            # Port 2 carries AMESim's residual-energy causality.  Exact
+            # division is singular when its outflow reverses through zero, so
+            # use a C1 band that matches the exact balance at its boundary and
+            # tends to the mixed enthalpy at zero flow.
+            inverse_flow = _regularized_inverse_outflow(
+                reference_port.m_flow,
+                transition_flow,
+            )
+            energy_residual_at_mixed_h = (
+                energy_without_reference
+                + reference_port.m_flow * mixed_h
+            )
+            reference_port.h_outflow = (
+                mixed_h - energy_residual_at_mixed_h * inverse_flow
+            )
+
+
 class AmesimPn3Node2(_AmesimPneumaticNode):
    """AMESim PN3NODE2 pneumatic three-port junction."""
-    MODEL_TYPE = 'amesim_pn3node2'
-    MODEL_VERSION = '0.3.0'
-    PORTS = (PortDefinition.pneumatic('port_1', computation=NODE_BRANCH), PortDefinition.pneumatic('port_2', computation=NODE_REFERENCE), PortDefinition.pneumatic('port_3', computation=NODE_BRANCH))
+
+    MODEL_TYPE = "amesim_pn3node2"
+    MODEL_VERSION = "0.3.0"
+    PRESSURE_FLOW_DEPENDS_ON_STREAM = False
+    PRESSURE_FLOW_EXACT_SUM_TO_ZERO_EQUATION_SUFFIXES = frozenset(
+        ("mass_flow_balance",)
+    )
+    PORTS = (
+        PortDefinition.pneumatic("port_1", nominal_role="bidirectional"),
+        PortDefinition.pneumatic("port_2", nominal_role="bidirectional"),
+        PortDefinition.pneumatic("port_3", nominal_role="bidirectional"),
+    )
    PARAMETERS = ()
    RESULT_VARIABLES = ()
-    DISPLAY = ComponentDisplaySpec(label='PN3NODE2 三端气动节点', library_id='amesim', category_id='junctions', symbol='amesim_pn3node2', ports=(PortDisplaySpec('port_1', 'left', order=10), PortDisplaySpec('port_2', 'right', order=20), PortDisplaySpec('port_3', 'right', order=30)), order=10)
+    DISPLAY = ComponentDisplaySpec(
+        label="PN3NODE2 三端气动节点",
+        library_id="amesim",
+        category_id="junctions",
+        symbol="amesim_pn3node2",
+        ports=(
+            PortDisplaySpec("port_1", "left", order=10),
+            PortDisplaySpec("port_2", "right", order=20),
+            PortDisplaySpec("port_3", "right", order=30),
+        ),
+        order=10,
+    )

    @classmethod
-    def create(cls, *, name: str, medium: IdealGasMedium, parameters: Mapping[str, float]) -> AmesimPn3Node2:
+    def create(
+        cls,
+        *,
+        name: str,
+        medium: IdealGasMedium,
+        parameters: Mapping[str, float],
+    ) -> AmesimPn3Node2:
        return cls(name=name)
-    EQUATIONS = ({'id': '__MODEL__:port_1_pressure_reference', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'equal', 'variables': ['__MODEL__.port_1.p', '__MODEL__.port_2.p'], 'role': 'effort'}, {'id': '__MODEL__:port_3_pressure_reference', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'equal', 'variables': ['__MODEL__.port_3.p', '__MODEL__.port_2.p'], 'role': 'effort'}, {'id': '__MODEL__:mass_flow_balance', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'sumToZero', 'variables': ['__MODEL__.port_1.m_flow', '__MODEL__.port_2.m_flow', '__MODEL__.port_3.m_flow'], 'role': 'flow'})
+

 class AmesimP4Node2(_AmesimPneumaticNode):
    """AMESim P4NODE2 pneumatic four-port junction."""
-    MODEL_TYPE = 'amesim_p4node2'
-    MODEL_VERSION = '0.3.0'
-    PORTS = (PortDefinition.pneumatic('port_1', computation=NODE_BRANCH), PortDefinition.pneumatic('port_2', computation=NODE_REFERENCE), PortDefinition.pneumatic('port_3', computation=NODE_BRANCH), PortDefinition.pneumatic('port_4', computation=NODE_BRANCH))
+
+    MODEL_TYPE = "amesim_p4node2"
+    MODEL_VERSION = "0.3.0"
+    PRESSURE_FLOW_DEPENDS_ON_STREAM = False
+    PRESSURE_FLOW_EXACT_SUM_TO_ZERO_EQUATION_SUFFIXES = frozenset(
+        ("mass_flow_balance",)
+    )
+    PORTS = (
+        PortDefinition.pneumatic("port_1", nominal_role="bidirectional"),
+        PortDefinition.pneumatic("port_2", nominal_role="bidirectional"),
+        PortDefinition.pneumatic("port_3", nominal_role="bidirectional"),
+        PortDefinition.pneumatic("port_4", nominal_role="bidirectional"),
+    )
    PARAMETERS = ()
    RESULT_VARIABLES = ()
-    DISPLAY = ComponentDisplaySpec(label='P4NODE2 四端气动节点', library_id='amesim', category_id='junctions', symbol='amesim_p4node2', ports=(PortDisplaySpec('port_1', 'left', order=10), PortDisplaySpec('port_2', 'right', order=20), PortDisplaySpec('port_3', 'right', order=30), PortDisplaySpec('port_4', 'right', order=40)), order=20)
+    DISPLAY = ComponentDisplaySpec(
+        label="P4NODE2 四端气动节点",
+        library_id="amesim",
+        category_id="junctions",
+        symbol="amesim_p4node2",
+        ports=(
+            PortDisplaySpec("port_1", "left", order=10),
+            PortDisplaySpec("port_2", "right", order=20),
+            PortDisplaySpec("port_3", "right", order=30),
+            PortDisplaySpec("port_4", "right", order=40),
+        ),
+        order=20,
+    )

    @classmethod
-    def create(cls, *, name: str, medium: IdealGasMedium, parameters: Mapping[str, float]) -> AmesimP4Node2:
+    def create(
+        cls,
+        *,
+        name: str,
+        medium: IdealGasMedium,
+        parameters: Mapping[str, float],
+    ) -> AmesimP4Node2:
        return cls(name=name)
-    EQUATIONS = ({'id': '__MODEL__:port_1_pressure_reference', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'equal', 'variables': ['__MODEL__.port_1.p', '__MODEL__.port_2.p'], 'role': 'effort'}, {'id': '__MODEL__:port_3_pressure_reference', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'equal', 'variables': ['__MODEL__.port_3.p', '__MODEL__.port_2.p'], 'role': 'effort'}, {'id': '__MODEL__:port_4_pressure_reference', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'equal', 'variables': ['__MODEL__.port_4.p', '__MODEL__.port_2.p'], 'role': 'effort'}, {'id': '__MODEL__:mass_flow_balance', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'sumToZero', 'variables': ['__MODEL__.port_1.m_flow', '__MODEL__.port_2.m_flow', '__MODEL__.port_3.m_flow', '__MODEL__.port_4.m_flow'], 'role': 'flow'})
@@ -1,16 +1,36 @@
-"""Component parameters, ports and output definitions; numerical equations execute in C."""
 from __future__ import annotations
-from collections.abc import Mapping
-from math import pi
-from app.simulation.components.amesim.gases import AMESIM_GAS_INDEX_PARAMETER, normalize_amesim_gas_index
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from math import isfinite, pi
+
+from app.simulation.components.amesim.gases import (
+    AMESIM_GAS_INDEX_PARAMETER,
+    normalize_amesim_gas_index,
+)
 from app.simulation.core.base import AlgebraicComponent
 from app.simulation.core.catalog import ComponentDisplaySpec, PortDisplaySpec
+from app.simulation.core.equations import EquationResidual
 from app.simulation.core.metadata import ParameterDefinition, ResultVariableDefinition
 from app.simulation.core.medium import GasMedium
 from app.simulation.core.ports import PortDefinition
-from app.simulation.core.port_computation import FLOW_SUPPLY
+
+
 AMESIM_REFERENCE_PRESSURE_PA = 101300.0

+
+@dataclass(frozen=True)
+class Pnrp17Linearization:
+    volume: float
+    volume_flow: float
+    pressure_force: float
+    volume_tangent: tuple[float, ...]
+    volume_flow_tangent: tuple[float, ...]
+    pressure_force_tangent: tuple[float, ...]
+    valid: bool = True
+    reason: str | None = None
+
+
 class AmesimPnrp17(AlgebraicComponent):
    """AMESim PNRP17 pneumatic piston with two mechanical faces.

@@ -18,32 +38,268 @@ class AmesimPnrp17(AlgebraicComponent):
    cylinder-side motion. The pneumatic port contributes its swept volume and
    volume rate to the connected variable-volume chamber.
    """
-    MODEL_TYPE = 'amesim_pnrp17'
-    MODEL_VERSION = '0.1.0'
-    PORTS = (PortDefinition.pneumatic('port_1', computation=FLOW_SUPPLY), PortDefinition.mechanical_translational('port_2'), PortDefinition.mechanical_translational('port_3'), PortDefinition.mechanical_translational('port_4'), PortDefinition.mechanical_translational('port_5'))
-    PARAMETERS = (AMESIM_GAS_INDEX_PARAMETER, ParameterDefinition('dp', 0.2, label='活塞直径', quantity='length', unit='m', minimum=0.0, minimum_exclusive=True, description='活塞外径；与活塞杆直径共同确定有效受压面积。'), ParameterDefinition('dr', 0.001, label='活塞杆直径', quantity='length', unit='m', minimum=0.0, description='穿过气室一侧的活塞杆直径，必须不大于活塞直径。'), ParameterDefinition('x0', 0.0, label='初始腔长', quantity='length', unit='m', description='机械端位移均为零时的气动腔长度。'))
-    RESULT_VARIABLES = (ResultVariableDefinition('volume', '扫掠容积', 'volume', 'm3', 'derived', 10), ResultVariableDefinition('volume_flow', '扫掠容积变化率', 'volume_flow', 'm3/s', 'derived', 20), ResultVariableDefinition('length', '气动腔长度', 'length', 'm', 'derived', 30), ResultVariableDefinition('pressure_force', '气压力', 'force', 'N', 'derived', 40))
-    DISPLAY = ComponentDisplaySpec(label='PNRP17 气动活塞', library_id='amesim', category_id='mechanical', symbol='amesim_pnrp17', ports=(PortDisplaySpec('port_1', 'left', order=10), PortDisplaySpec('port_3', 'left', order=20), PortDisplaySpec('port_2', 'left', order=30), PortDisplaySpec('port_4', 'right', order=40), PortDisplaySpec('port_5', 'right', order=50)), order=60)

-    def __init__(self, name: str, medium: GasMedium, *, gi: float=0.0, dp: float=0.2, dr: float=0.001, x0: float=0.0) -> None:
+    MODEL_TYPE = "amesim_pnrp17"
+    MODEL_VERSION = "0.1.0"
+    PRESSURE_FLOW_DEPENDS_ON_STREAM = False
+    PORTS = (
+        PortDefinition.pneumatic("port_1", nominal_role="bidirectional"),
+        PortDefinition.mechanical_translational("port_2"),
+        PortDefinition.mechanical_translational("port_3"),
+        PortDefinition.mechanical_translational("port_4"),
+        PortDefinition.mechanical_translational("port_5"),
+    )
+    PARAMETERS = (
+        AMESIM_GAS_INDEX_PARAMETER,
+        ParameterDefinition(
+            "dp",
+            0.2,
+            label="活塞直径",
+            quantity="length",
+            unit="m",
+            minimum=0.0,
+            minimum_exclusive=True,
+            description="活塞外径；与活塞杆直径共同确定有效受压面积。",
+        ),
+        ParameterDefinition(
+            "dr",
+            0.001,
+            label="活塞杆直径",
+            quantity="length",
+            unit="m",
+            minimum=0.0,
+            description="穿过气室一侧的活塞杆直径，必须不大于活塞直径。",
+        ),
+        ParameterDefinition(
+            "x0",
+            0.0,
+            label="初始腔长",
+            quantity="length",
+            unit="m",
+            description="机械端位移均为零时的气动腔长度。",
+        ),
+    )
+    RESULT_VARIABLES = (
+        ResultVariableDefinition("volume", "扫掠容积", "volume", "m3", "derived", 10),
+        ResultVariableDefinition(
+            "volume_flow",
+            "扫掠容积变化率",
+            "volume_flow",
+            "m3/s",
+            "derived",
+            20,
+        ),
+        ResultVariableDefinition("length", "气动腔长度", "length", "m", "derived", 30),
+        ResultVariableDefinition(
+            "pressure_force",
+            "气压力",
+            "force",
+            "N",
+            "derived",
+            40,
+        ),
+    )
+    DISPLAY = ComponentDisplaySpec(
+        label="PNRP17 气动活塞",
+        library_id="amesim",
+        category_id="mechanical",
+        symbol="amesim_pnrp17",
+        ports=(
+            PortDisplaySpec("port_1", "left", order=10),
+            PortDisplaySpec("port_3", "left", order=20),
+            PortDisplaySpec("port_2", "left", order=30),
+            PortDisplaySpec("port_4", "right", order=40),
+            PortDisplaySpec("port_5", "right", order=50),
+        ),
+        order=60,
+    )
+
+    def __init__(
+        self,
+        name: str,
+        medium: GasMedium,
+        *,
+        gi: float = 0.0,
+        dp: float = 0.2,
+        dr: float = 0.001,
+        x0: float = 0.0,
+    ) -> None:
        super().__init__(name=name)
-        self.set_parameter_values({'gi': gi, 'dp': dp, 'dr': dr, 'x0': x0})
+        self.set_parameter_values({"gi": gi, "dp": dp, "dr": dr, "x0": x0})
        self.medium = medium
        self.gi = normalize_amesim_gas_index(gi)
        self.dp = float(dp)
        self.dr = float(dr)
        self.x0 = float(x0)
        if self.dr > self.dp:
-            raise ValueError('PNRP17 rod diameter dr must not exceed piston diameter dp.')
+            raise ValueError("PNRP17 rod diameter dr must not exceed piston diameter dp.")
        for definition in self.PORTS:
            port = self.register_declared_port(definition.name)
            setattr(self, definition.name, port)
+        self.port_1.h_outflow = medium.specific_enthalpy(medium.T_ref)

    @classmethod
-    def create(cls, *, name: str, medium: GasMedium, parameters: Mapping[str, float]) -> 'AmesimPnrp17':
+    def create(
+        cls,
+        *,
+        name: str,
+        medium: GasMedium,
+        parameters: Mapping[str, float],
+    ) -> "AmesimPnrp17":
        return cls(name=name, medium=medium, **dict(parameters))

    @property
    def effective_area(self) -> float:
        return pi * (self.dp * self.dp - self.dr * self.dr) / 4.0
-    EQUATIONS = ({'id': '__MODEL__:pneumatic_zero_mass_flow', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'constitutive', 'variables': ['__MODEL__.port_1.m_flow'], 'role': 'flow'}, {'id': '__MODEL__:port_2_port_5_x_equal', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'equal', 'variables': ['__MODEL__.port_2.x', '__MODEL__.port_5.x'], 'role': 'effort'}, {'id': '__MODEL__:port_2_port_5_v_equal', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'equal', 'variables': ['__MODEL__.port_2.v', '__MODEL__.port_5.v'], 'role': 'effort'}, {'id': '__MODEL__:port_3_port_4_x_equal', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'equal', 'variables': ['__MODEL__.port_3.x', '__MODEL__.port_4.x'], 'role': 'effort'}, {'id': '__MODEL__:port_3_port_4_v_equal', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'equal', 'variables': ['__MODEL__.port_3.v', '__MODEL__.port_4.v'], 'role': 'effort'}, {'id': '__MODEL__:piston_side_force_balance', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'constitutive', 'variables': ['__MODEL__.port_2.f', '__MODEL__.port_5.f', '__MODEL__.port_1.p'], 'role': 'flow'}, {'id': '__MODEL__:cylinder_side_force_balance', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'constitutive', 'variables': ['__MODEL__.port_3.f', '__MODEL__.port_4.f', '__MODEL__.port_1.p'], 'role': 'flow'})
+
+    @property
+    def chamber_length(self) -> float:
+        return self.x0 + self.port_5.x - self.port_4.x
+
+    @property
+    def chamber_volume(self) -> float:
+        return self.effective_area * self.chamber_length
+
+    @property
+    def chamber_volume_flow(self) -> float:
+        return self.effective_area * (self.port_5.v - self.port_4.v)
+
+    @property
+    def pressure_force(self) -> float:
+        return (self.port_1.p - AMESIM_REFERENCE_PRESSURE_PA) * self.effective_area
+
+    def pressure_flow_equation_values(self) -> tuple[float, ...]:
+        values = [self.port_1.m_flow]
+        effort_pairs = (("port_2", "port_5"), ("port_3", "port_4"))
+        for first_name, second_name in effort_pairs:
+            first = self.get_port(first_name)
+            second = self.get_port(second_name)
+            values.extend((first.x - second.x, first.v - second.v))
+        force = self.pressure_force
+        values.extend(
+            (
+                self.port_2.f + self.port_5.f + force,
+                self.port_3.f + self.port_4.f - force,
+            )
+        )
+        return tuple(values)
+
+    def pressure_flow_equation_residuals(self) -> tuple[EquationResidual, ...]:
+        effort_pairs = (("port_2", "port_5"), ("port_3", "port_4"))
+        residuals: list[EquationResidual] = [
+            EquationResidual(
+                id=f"{self.name}:pneumatic_zero_mass_flow",
+                owner="component",
+                owner_id=self.name,
+                relation="constitutive",
+                variables=(f"{self.name}.port_1.m_flow",),
+                role="flow",
+                value=self.port_1.m_flow,
+            )
+        ]
+        for first_name, second_name in effort_pairs:
+            first = self.get_port(first_name)
+            second = self.get_port(second_name)
+            for variable in ("x", "v"):
+                residuals.append(
+                    EquationResidual(
+                        id=f"{self.name}:{first_name}_{second_name}_{variable}_equal",
+                        owner="component",
+                        owner_id=self.name,
+                        relation="equal",
+                        variables=(
+                            f"{self.name}.{first_name}.{variable}",
+                            f"{self.name}.{second_name}.{variable}",
+                        ),
+                        role="effort",
+                        value=getattr(first, variable) - getattr(second, variable),
+                    )
+                )
+        force = self.pressure_force
+        residuals.extend(
+            (
+                EquationResidual(
+                    id=f"{self.name}:piston_side_force_balance",
+                    owner="component",
+                    owner_id=self.name,
+                    relation="constitutive",
+                    variables=(f"{self.name}.port_2.f", f"{self.name}.port_5.f", f"{self.name}.port_1.p"),
+                    role="flow",
+                    value=self.port_2.f + self.port_5.f + force,
+                ),
+                EquationResidual(
+                    id=f"{self.name}:cylinder_side_force_balance",
+                    owner="component",
+                    owner_id=self.name,
+                    relation="constitutive",
+                    variables=(f"{self.name}.port_3.f", f"{self.name}.port_4.f", f"{self.name}.port_1.p"),
+                    role="flow",
+                    value=self.port_3.f + self.port_4.f - force,
+                ),
+            )
+        )
+        return tuple(residuals)
+
+    def pneumatic_volume_outputs(self) -> Mapping[str, tuple[float, float]]:
+        return {"port_1": (self.chamber_volume, self.chamber_volume_flow)}
+
+    def linearize_geometry_and_force(
+        self,
+        port_4_x_tangent: Sequence[float],
+        port_5_x_tangent: Sequence[float],
+        port_4_v_tangent: Sequence[float],
+        port_5_v_tangent: Sequence[float],
+        port_1_pressure_tangent: Sequence[float],
+    ) -> Pnrp17Linearization:
+        """Return exact piston geometry and pressure-force tangents."""
+
+        vectors = tuple(
+            tuple(float(value) for value in values)
+            for values in (
+                port_4_x_tangent,
+                port_5_x_tangent,
+                port_4_v_tangent,
+                port_5_v_tangent,
+                port_1_pressure_tangent,
+            )
+        )
+        widths = {len(values) for values in vectors}
+        if len(widths) != 1:
+            raise ValueError("PNRP17 tangent vectors must have equal lengths.")
+        valid = all(isfinite(value) for values in vectors for value in values)
+        area = self.effective_area
+        volume_tangent = tuple(
+            area * (right - left)
+            for left, right in zip(vectors[0], vectors[1], strict=True)
+        )
+        volume_flow_tangent = tuple(
+            area * (right - left)
+            for left, right in zip(vectors[2], vectors[3], strict=True)
+        )
+        pressure_force_tangent = tuple(
+            area * value for value in vectors[4]
+        )
+        return Pnrp17Linearization(
+            volume=self.chamber_volume,
+            volume_flow=self.chamber_volume_flow,
+            pressure_force=self.pressure_force,
+            volume_tangent=volume_tangent,
+            volume_flow_tangent=volume_flow_tangent,
+            pressure_force_tangent=pressure_force_tangent,
+            valid=valid,
+            reason=None if valid else "non_finite_tangent_input",
+        )
+
+    def update_stream_outflows(self, connected_h: Mapping[str, float]) -> None:
+        self.port_1.h_outflow = connected_h.get(
+            "port_1",
+            self.medium.specific_enthalpy(self.medium.T_ref),
+        )
+
+    def component_result_values(self) -> Mapping[str, float]:
+        return {
+            "volume": self.chamber_volume,
+            "volume_flow": self.chamber_volume_flow,
+            "length": self.chamber_length,
+            "pressure_force": self.pressure_force,
+        }
@@ -1,48 +1,488 @@
-"""Gas identities and constants passed to the native compiler."""
 from __future__ import annotations
-from collections.abc import Callable
+
+from collections.abc import Callable, Sequence
 from dataclasses import dataclass
+from math import exp, isfinite, log
 from typing import ClassVar
-from app.simulation.core.medium import GasMedium, IdealGasMedium
+
+from app.simulation.core.errors import RecoverableTrialStateError
+from app.simulation.core.medium import (
+    GasMedium,
+    IdealGasMedium,
+    ThermodynamicProperties,
+    ThermodynamicPropertiesLinearization,
+    ThermodynamicPropertyTangents,
+)
+from app.simulation.core.peng_robinson import HELIUM_PR, PengRobinsonFluid
+from app.simulation.performance import profile_property, record_property_iterations
+from app.simulation.property_cache import cache_property_calculation
+

@dataclass(frozen=True)
 class AmesimIdealAirMedium(IdealGasMedium):
-    SUBSTANCE_ID: ClassVar[str] = 'air'
-    PROPERTY_METHOD_ID: ClassVar[str] = 'ideal_gas'
-    name: str = 'AMESimAirIdealGas'
+    """AMESim air properties evaluated with the ideal-gas method.
+
+    Substance identity and property method are part of the concrete Python
+    type.  A future air correlation or helium Peng-Robinson implementation can
+    therefore coexist as a sibling type without turning ``gi`` into a fluid
+    enumeration.
+    """
+
+    SUBSTANCE_ID: ClassVar[str] = "air"
+    PROPERTY_METHOD_ID: ClassVar[str] = "ideal_gas"
+
+    name: str = "AMESimAirIdealGas"
    R_gas: float = 287.0
    cp_ref: float = 1005.0
    T_ref: float = 300.0
    cp_slope: float = 0.0
-    viscosity_ref: float = 1.82e-05
+    viscosity_ref: float = 1.82e-5
    viscosity_T_ref: float = 293.15
    sutherland_constant: float = 110.4

+
@dataclass(frozen=True)
 class AmesimHeliumPengRobinsonMedium(IdealGasMedium):
-    """Helium identity; reference constants below describe the lower range.
+    """AMESim helium with a Peng-Robinson mechanical equation of state.

-    The native evaluator uses Amesim's piecewise NASA heat capacity/enthalpy
-    (6000 K transition) and viscosity (1000/5000 K transitions), together
-    with PR departure properties. ``cp_ref`` is not a global constant Cp.
+    The pressure-density-temperature relation is evaluated by the shared
+    ``HELIUM_PR`` fluid.  The caloric reference follows the constant NASA
+    polynomial from Simcenter Amesim 2404 ``helium_cp_h_s.data``.
    """
-    SUBSTANCE_ID: ClassVar[str] = 'helium'
-    PROPERTY_METHOD_ID: ClassVar[str] = 'peng_robinson'
+
+    SUBSTANCE_ID: ClassVar[str] = "helium"
+    PROPERTY_METHOD_ID: ClassVar[str] = "peng_robinson"
+    fluid: ClassVar[PengRobinsonFluid] = HELIUM_PR
    nasa_cp_over_R: ClassVar[float] = 2.5
    nasa_enthalpy_constant_K: ClassVar[float] = -745.375
-    nasa_viscosity_coefficients: ClassVar[tuple[float, float, float, float]] = (0.7501594, 35.76324, -2212.129, 0.9212635)
-    name: str = 'AMESimHeliumPengRobinson'
-    R_gas: float = 8.31446261815324 / 0.004002602
-    cp_ref: float = 2.5 * (8.31446261815324 / 0.004002602)
+    nasa_viscosity_coefficients: ClassVar[tuple[float, float, float, float]] = (
+        0.7501594,
+        35.76324,
+        -2212.129,
+        0.9212635,
+    )
+
+    name: str = "AMESimHeliumPengRobinson"
+    R_gas: float = HELIUM_PR.specific_gas_constant
+    cp_ref: float = nasa_cp_over_R * HELIUM_PR.specific_gas_constant
    T_ref: float = 293.15
    cp_slope: float = 0.0
-    viscosity_ref: float = 1.96e-05
+    viscosity_ref: float = 1.96e-5
    viscosity_T_ref: float = 293.15
    sutherland_constant: float = 79.4

+    @property
+    def cv(self) -> float:
+        return (self.nasa_cp_over_R - 1.0) * self.R_gas
+
+    def cv_at_temperature(self, T: float) -> float:
+        del T
+        return self.cv
+
+    def diagnostic_dynamic_viscosity(self, T: float) -> float:
+        """Return the AMESim NASA-table viscosity used by pipe diagnostics.
+
+        pn2pipefr reports Reynolds number with sagum viscosity. Keep this
+        separate from dynamic_viscosity so matching that diagnostic cannot
+        alter the already-validated pipe flow or friction dynamics.
+        """
+
+        if T <= 0.0:
+            raise ValueError("Temperature must be positive.")
+        a, b, c, d = self.nasa_viscosity_coefficients
+        return 1.0e-7 * exp(a * log(T) + b / T + c / (T * T) + d)
+
+    @profile_property("density")
+    @cache_property_calculation("density")
+    def density(self, p: float, T: float) -> float:
+        return self.fluid.density(p, T)
+
+    def _real_heat_capacities(
+        self,
+        p: float,
+        T: float,
+    ) -> tuple[float, float, float, float, float]:
+        density = self.density(p, T)
+        pressure_density_derivative = (
+            self.fluid.pressure_density_derivative_at_temperature(
+                T,
+                density,
+            )
+        )
+        pressure_temperature_derivative = (
+            self.fluid.pressure_temperature_derivative_at_density(
+                T,
+                density,
+            )
+        )
+        cv = (
+            self.cv_at_temperature(T)
+            + self.fluid.residual_isochoric_heat_capacity_at_density(T, density)
+        )
+        cp = (
+            cv
+            + T
+            * pressure_temperature_derivative
+            * pressure_temperature_derivative
+            / (density * density * pressure_density_derivative)
+        )
+        if cp <= 0.0 or cv <= 0.0:
+            raise ValueError("Real-gas heat capacities must be positive.")
+        return (
+            cp,
+            cv,
+            density,
+            pressure_density_derivative,
+            pressure_temperature_derivative,
+        )
+
+    def _local_isentropic_density_pressure_factor(
+        self,
+        p: float,
+        T: float,
+    ) -> tuple[float, float]:
+        cp, cv, density, pressure_density_derivative, pressure_temperature_derivative = (
+            self._real_heat_capacities(p, T)
+        )
+        heat_capacity_ratio = cp / cv
+        factor = p / (
+            density * pressure_density_derivative * heat_capacity_ratio
+        )
+        exponent = (
+            p
+            * (heat_capacity_ratio - 1.0)
+            / (
+                heat_capacity_ratio
+                * T
+                * pressure_temperature_derivative
+            )
+        )
+        return factor, exponent
+
+    @profile_property("isentropic_density_pressure_factor")
+    @cache_property_calculation("isentropic_density_pressure_factor")
+    def isentropic_density_pressure_factor(
+        self,
+        p: float,
+        T: float,
+        downstream_pressure: float | None = None,
+    ) -> float:
+        upstream_factor, isentropic_temperature_exponent = (
+            self._local_isentropic_density_pressure_factor(p, T)
+        )
+        if downstream_pressure is None or downstream_pressure >= p:
+            return upstream_factor
+
+        pressure_ratio = max(downstream_pressure / p, 1.0e-12)
+        isentropic_temperature = max(
+            T * pressure_ratio**isentropic_temperature_exponent,
+            2.2,
+        )
+        downstream_factor, _unused_exponent = (
+            self._local_isentropic_density_pressure_factor(
+                max(downstream_pressure, 1.0),
+                isentropic_temperature,
+            )
+        )
+        # AMESim 2404 saggs_ evaluates the local factor at the upstream
+        # state and at an approximate isentropic downstream state.
+        return 0.5 * (upstream_factor + downstream_factor)
+
+    def pressure(self, m: float, T: float, V: float) -> float:
+        if V <= 0.0:
+            raise ValueError("Volume must stay positive.")
+        return self.fluid.pressure_from_density(T, m / V)
+
+    @profile_property("specific_internal_energy")
+    def specific_internal_energy(self, T: float) -> float:
+        return self.R_gas * (
+            (self.nasa_cp_over_R - 1.0) * T
+            + self.nasa_enthalpy_constant_K
+        )
+
+    @profile_property("specific_internal_energy_at_pressure")
+    def specific_internal_energy_at_pressure(self, p: float, T: float) -> float:
+        density = self.density(p, T)
+        return (
+            self.specific_internal_energy(T)
+            + self.fluid.residual_specific_internal_energy_at_density(T, density)
+        )
+
+    @profile_property("specific_enthalpy")
+    def specific_enthalpy(self, T: float) -> float:
+        return self.R_gas * (
+            self.nasa_cp_over_R * T
+            + self.nasa_enthalpy_constant_K
+        )
+
+    @profile_property("specific_enthalpy_at_pressure")
+    def specific_enthalpy_at_pressure(self, p: float, T: float) -> float:
+        return self.specific_enthalpy(T) + self.fluid.residual_specific_enthalpy(p, T)
+
+    def temperature_from_internal_energy(self, u: float) -> float:
+        return (
+            u / self.R_gas - self.nasa_enthalpy_constant_K
+        ) / (self.nasa_cp_over_R - 1.0)
+
+    def temperature_from_enthalpy(self, h: float) -> float:
+        return (
+            h / self.R_gas - self.nasa_enthalpy_constant_K
+        ) / self.nasa_cp_over_R
+
+    @profile_property("temperature_from_pressure_enthalpy")
+    @cache_property_calculation("temperature_from_pressure_enthalpy")
+    def temperature_from_pressure_enthalpy(self, p: float, h: float) -> float:
+        temperature = max(self.temperature_from_enthalpy(h), 2.2)
+        for _iteration in range(16):
+            residual_enthalpy = self.fluid.residual_specific_enthalpy(p, temperature)
+            next_temperature = max(
+                self.temperature_from_enthalpy(h - residual_enthalpy),
+                2.2,
+            )
+            if abs(next_temperature - temperature) <= 1.0e-10 * max(
+                temperature,
+                1.0,
+            ):
+                record_property_iterations(
+                    "temperature_from_pressure_enthalpy",
+                    _iteration + 1,
+                    True,
+                )
+                return next_temperature
+            temperature = next_temperature
+        record_property_iterations(
+            "temperature_from_pressure_enthalpy",
+            16,
+            False,
+        )
+        return temperature
+
+    def temperature_from_mass_internal_energy(self, m: float, U: float) -> float:
+        if m <= 0.0:
+            raise RecoverableTrialStateError(
+                "Mass must stay positive when recovering temperature."
+            )
+        return self.temperature_from_internal_energy(U / m)
+
+    @profile_property("properties_from_mU")
+    @cache_property_calculation("properties_from_mU")
+    def properties_from_mU(
+        self,
+        m: float,
+        U: float,
+        V: float,
+    ) -> ThermodynamicProperties:
+        """Recover a real-gas state, reusing exact repeated evaluations.
+
+        Implicit integration asks several component interfaces for the same
+        ``(m, U, V)`` state while closing one RHS evaluation and while building
+        finite-difference Jacobians. The calculation is pure and its result is
+        immutable, so an exact-key bounded cache avoids repeating the
+        Peng-Robinson temperature iteration without changing model semantics.
+        """
+        if m <= 0.0:
+            raise RecoverableTrialStateError(
+                "Mass must stay positive when recovering temperature."
+            )
+        if V <= 0.0:
+            raise ValueError("Volume must stay positive.")
+        density = m / V
+        target_internal_energy = U / m
+        temperature = max(
+            self.temperature_from_internal_energy(target_internal_energy),
+            2.2,
+        )
+        converged = False
+        for _iteration in range(16):
+            residual_internal_energy = (
+                self.fluid.residual_specific_internal_energy_at_density(
+                    temperature,
+                    density,
+                )
+            )
+            next_temperature = max(
+                self.temperature_from_internal_energy(
+                    target_internal_energy - residual_internal_energy
+                ),
+                2.2,
+            )
+            if abs(next_temperature - temperature) <= 1.0e-10 * max(
+                temperature,
+                1.0,
+            ):
+                temperature = next_temperature
+                converged = True
+                break
+            temperature = next_temperature
+        record_property_iterations(
+            "properties_from_mU",
+            _iteration + 1,
+            converged,
+        )
+        pressure = self.fluid.pressure_from_density(temperature, density)
+        return ThermodynamicProperties(
+            p=pressure,
+            T=temperature,
+            rho=density,
+            u=target_internal_energy,
+            h=self.specific_enthalpy_at_pressure(
+                pressure,
+                temperature,
+            ),
+        )
+
+    def linearize_properties_from_mU(
+        self,
+        m: float,
+        U: float,
+        V: float,
+        dm: Sequence[float],
+        dU: Sequence[float],
+        dV: Sequence[float],
+        *,
+        properties: ThermodynamicProperties | None = None,
+    ) -> ThermodynamicPropertiesLinearization:
+        """Implicitly differentiate the Peng-Robinson m/U/V recovery."""
+
+        dm_values = tuple(float(value) for value in dm)
+        dU_values = tuple(float(value) for value in dU)
+        dV_values = tuple(float(value) for value in dV)
+        if not (len(dm_values) == len(dU_values) == len(dV_values)):
+            raise ValueError("Thermodynamic tangent vectors must have equal lengths.")
+        props = properties or self.properties_from_mU(m, U, V)
+        width = len(dm_values)
+
+        def invalid(reason: str) -> ThermodynamicPropertiesLinearization:
+            return ThermodynamicPropertiesLinearization(
+                properties=props,
+                tangents=ThermodynamicPropertyTangents.zeros(width),
+                valid=False,
+                reason=reason,
+            )
+
+        expected_density = m / V
+        expected_internal_energy = U / m
+        if (
+            abs(props.rho - expected_density)
+            > 1.0e-12 * max(abs(expected_density), 1.0)
+            or abs(props.u - expected_internal_energy)
+            > 1.0e-12 * max(abs(expected_internal_energy), 1.0)
+        ):
+            return invalid("properties_primal_mismatch")
+        if not all(
+            isfinite(value)
+            for values in (dm_values, dU_values, dV_values)
+            for value in values
+        ):
+            return invalid("non_finite_tangent_input")
+        if props.T <= 2.2 * (1.0 + 1.0e-10):
+            return invalid("temperature_floor_boundary")
+
+        pressure_temperature_derivative = (
+            self.fluid.pressure_temperature_derivative_at_density(
+                props.T,
+                props.rho,
+            )
+        )
+        pressure_density_derivative = (
+            self.fluid.pressure_density_derivative_at_temperature(
+                props.T,
+                props.rho,
+            )
+        )
+        cv = (
+            self.cv_at_temperature(props.T)
+            + self.fluid.residual_isochoric_heat_capacity_at_density(
+                props.T,
+                props.rho,
+            )
+        )
+        recovered_internal_energy = (
+            self.specific_internal_energy(props.T)
+            + self.fluid.residual_specific_internal_energy_at_density(
+                props.T,
+                props.rho,
+            )
+        )
+        recovery_scale = max(
+            abs(props.u),
+            abs(cv * props.T) if isfinite(cv) else 0.0,
+            1.0,
+        )
+        if (
+            not all(
+                isfinite(value)
+                for value in (
+                    pressure_temperature_derivative,
+                    pressure_density_derivative,
+                    cv,
+                    recovered_internal_energy,
+                )
+            )
+            or cv <= 0.0
+        ):
+            return invalid("invalid_peng_robinson_derivative")
+        if abs(recovered_internal_energy - props.u) > 1.0e-8 * recovery_scale:
+            return invalid("properties_recovery_not_converged")
+
+        internal_energy_density_derivative = (
+            props.p - props.T * pressure_temperature_derivative
+        ) / (props.rho * props.rho)
+        drho: list[float] = []
+        du: list[float] = []
+        dT: list[float] = []
+        dp: list[float] = []
+        dh: list[float] = []
+        for mass_tangent, energy_tangent, volume_tangent in zip(
+            dm_values,
+            dU_values,
+            dV_values,
+            strict=True,
+        ):
+            density_tangent = (
+                mass_tangent / V - m * volume_tangent / (V * V)
+            )
+            internal_energy_tangent = (
+                energy_tangent / m - U * mass_tangent / (m * m)
+            )
+            temperature_tangent = (
+                internal_energy_tangent
+                - internal_energy_density_derivative * density_tangent
+            ) / cv
+            pressure_tangent = (
+                pressure_temperature_derivative * temperature_tangent
+                + pressure_density_derivative * density_tangent
+            )
+            enthalpy_tangent = (
+                internal_energy_tangent
+                + pressure_tangent / props.rho
+                - props.p * density_tangent / (props.rho * props.rho)
+            )
+            drho.append(density_tangent)
+            du.append(internal_energy_tangent)
+            dT.append(temperature_tangent)
+            dp.append(pressure_tangent)
+            dh.append(enthalpy_tangent)
+
+        tangent_values = (*drho, *du, *dT, *dp, *dh)
+        if not all(isfinite(value) for value in tangent_values):
+            return invalid("non_finite_property_tangent")
+        return ThermodynamicPropertiesLinearization(
+            properties=props,
+            tangents=ThermodynamicPropertyTangents(
+                p=tuple(dp),
+                T=tuple(dT),
+                rho=tuple(drho),
+                u=tuple(du),
+                h=tuple(dh),
+            ),
+        )
+
+
@dataclass(frozen=True)
 class AmesimGasPropertyModelSpec:
    """A selectable calculation method for one AMESim gas substance."""
+
    value: int
    label: str
    method_id: str
@@ -51,7 +491,27 @@ class AmesimGasPropertyModelSpec:

    def build_medium(self) -> GasMedium:
        return self.factory()
+
+
 AMESIM_AIR_IDEAL_GAS_PROPERTY_MODEL = 0
-AMESIM_AIR_PROPERTY_MODELS = (AmesimGasPropertyModelSpec(value=AMESIM_AIR_IDEAL_GAS_PROPERTY_MODEL, label='理想气体', method_id=AmesimIdealAirMedium.PROPERTY_METHOD_ID, factory=AmesimIdealAirMedium, eos_type=1),)
+AMESIM_AIR_PROPERTY_MODELS = (
+    AmesimGasPropertyModelSpec(
+        value=AMESIM_AIR_IDEAL_GAS_PROPERTY_MODEL,
+        label="理想气体",
+        method_id=AmesimIdealAirMedium.PROPERTY_METHOD_ID,
+        factory=AmesimIdealAirMedium,
+        eos_type=1,
+    ),
+)
+
+
 AMESIM_HELIUM_PENG_ROBINSON_PROPERTY_MODEL = 0
-AMESIM_HELIUM_PROPERTY_MODELS = (AmesimGasPropertyModelSpec(value=AMESIM_HELIUM_PENG_ROBINSON_PROPERTY_MODEL, label='Peng–Robinson', method_id=AmesimHeliumPengRobinsonMedium.PROPERTY_METHOD_ID, factory=AmesimHeliumPengRobinsonMedium, eos_type=6),)
+AMESIM_HELIUM_PROPERTY_MODELS = (
+    AmesimGasPropertyModelSpec(
+        value=AMESIM_HELIUM_PENG_ROBINSON_PROPERTY_MODEL,
+        label="Peng–Robinson",
+        method_id=AmesimHeliumPengRobinsonMedium.PROPERTY_METHOD_ID,
+        factory=AmesimHeliumPengRobinsonMedium,
+        eos_type=6,
+    ),
+)
@@ -1,74 +0,0 @@
-"""External Amesim encodings, separate from the saved public model contract.
-
-Apply these mappings only when reading Amesim parameters. A browser JSON/XML
-already uses public values: applying the mapping again changes its meaning.
-Reviewed against the installed Amesim 2404 submodel parameter declarations.
-"""
-from __future__ import annotations
-
-
-AMESIM_CHOICE_VALUES = {
-    ("amesim_ud00", "nstages"): {i: i for i in range(1, 9)},
-    ("amesim_ud00", "iscyclic"): {1: 0, 2: 1},
-    ("amesim_lstp00a", "stiffmode"): {1: 1, 2: 2},
-    ("amesim_lstp00a", "discContactOption"): {1: 1, 2: 2},
-    ("amesim_mecmas21", "useFriction"): {1: 1, 2: 2},
-    ("amesim_mecmas21", "stoptype"): {1: 1, 2: 2, 3: 3, 4: 4},
-    ("amesim_mecmas21", "discContactOption"): {1: 1, 2: 2},
-    ("amesim_mecmas21", "strib"): {1: 1, 2: 2},
-    ("amesim_mecmas21", "frictionType"): {1: 1, 2: 2},
-    ("amesim_lmechn1", "sum"): {1: 1},
-    **{(model, "mode"): {1: 1, 2: 2} for model in
-       ("amesim_pnl0001", "amesim_pnl0002", "amesim_pnl0003")},
-    **{(model, "flowset"): {1: 1, 2: 2, 3: 3} for model in
-       ("amesim_pnor001", "amesim_pnvo001", "amesim_pnvo001_fixed")},
-}
-
-
-def amesim_choice_to_public(model_type: str, parameter: str, value: float) -> float:
-    mapping = AMESIM_CHOICE_VALUES.get((model_type, parameter))
-    if mapping is None:
-        return value
-    if value not in mapping:
-        raise ValueError(f"{model_type}.{parameter}: unknown Amesim encoding {value}; "
-                         f"expected one of {tuple(mapping)}")
-    return float(mapping[value])
-
-
-def contact_stiffness(component) -> float:
-    """SI constant lowering; the contact force is evaluated in C."""
-    if int(component.stiffmode) == 1:
-        if component.kcont <= 0:
-            raise ValueError(f"{component.name}: LSTP00A 数值刚度模式要求 kcont > 0")
-        return component.kcont
-    if component.G < 0:
-        raise ValueError(f"{component.name}: LSTP00A 几何刚度模式要求 G >= 0")
-    for name in ("sdiam", "wdiam", "na"):
-        if getattr(component, name) <= 0:
-            raise ValueError(f"{component.name}: LSTP00A 几何刚度模式要求 {name} > 0")
-    return component.G * component.wdiam**4 / (8 * component.sdiam**3 * component.na)
-
-
-def validate_numerical_semantics(component) -> None:
-    """Reject requested behavior that cannot yet be faithfully executed.
-
-    Keep this at numerical compilation, so incomplete/future configurations
-    can still be edited and saved. Disabled friction settings have no effect.
-    """
-    if component.model_type == "amesim_mecmas21" and component.use_friction and int(component.stoptype) != 3:
-        for name in ('dvel', 'astrib'):
-            if getattr(component, name) <= 0:
-                raise ValueError(f"{component.name}: MECMAS21 启用摩擦时 {name} 必须大于零（Amesim 参数约束）")
-        if component.fcoul > component.fstick:
-            raise ValueError(f"{component.name}: MECMAS21 库仑摩擦 fcoul 不能大于静摩擦 fstick（Amesim 参数约束）")
-    if component.model_type == 'amesim_mecmas21':
-        if int(component.stoptype) in (1, 2, 3) and component.xmin > component.xmax:
-            raise ValueError(f'{component.name}: MECMAS21 限位要求 xmin <= xmax')
-        if int(component.stoptype) == 2:
-            for name in ('Kbmin', 'Kbmax', 'Dbmin', 'Dbmax'):
-                if getattr(component, name) <= 0:
-                    raise ValueError(f'{component.name}: MECMAS21 弹性限位要求 {name} > 0')
-    if component.model_type == 'amesim_mecmas21' and int(component.stoptype) == 3 and component.restdvel <= 0:
-        raise ValueError(f'{component.name}: MECMAS21 恢复碰撞模式要求 restdvel > 0（Amesim 参数约束）')
-    if component.model_type == "amesim_lstp00a":
-        contact_stiffness(component)
@@ -1,79 +1,355 @@
-"""Component parameters, ports and output definitions; numerical equations execute in C."""
 from __future__ import annotations
+
 from collections.abc import Mapping
+from math import floor
+
 from app.simulation.core.base import AlgebraicComponent
-from app.simulation.core.catalog import ComponentDisplaySpec, ParameterGroupDisplaySpec, PortDisplaySpec
-from app.simulation.core.metadata import ParameterCondition, ParameterDefinition, ParameterOption, ResultVariableDefinition
+from app.simulation.core.catalog import (
+    ComponentDisplaySpec,
+    ParameterGroupDisplaySpec,
+    PortDisplaySpec,
+)
+from app.simulation.core.metadata import (
+    ParameterCondition,
+    ParameterDefinition,
+    ParameterOption,
+    ResultVariableDefinition,
+)
 from app.simulation.core.medium import IdealGasMedium
 from app.simulation.core.ports import PortDefinition
-def _ud00_stage_parameters(index: int) -> tuple[ParameterDefinition, ...]:
-    visible_when = () if index == 1 else (ParameterCondition('nstages', tuple((float(stage_count) for stage_count in range(index, 9)))),)
-    return (ParameterDefinition(f'start{index}', 0.0 if index == 1 else 1.0, label=f'第 {index} 段起点', quantity='dimensionless', unit='', description=f'第 {index} 段开始时的输出值。', visible_when=visible_when), ParameterDefinition(f'end{index}', 1.0, label=f'第 {index} 段终点', quantity='dimensionless', unit='', description=f'第 {index} 段结束时的输出值。', visible_when=visible_when), ParameterDefinition(f't{index}', 1.0 if index == 1 else 0.0, label=f'第 {index} 段时长', quantity='time', unit='s', minimum=0.0, description=f'第 {index} 段的持续时间。', visible_when=visible_when))

-_UD00_STAGE_PARAMETERS = tuple((parameter for stage_index in range(1, 9) for parameter in _ud00_stage_parameters(stage_index)))
+
+def _ud00_stage_parameters(index: int) -> tuple[ParameterDefinition, ...]:
+    visible_when = (
+        ()
+        if index == 1
+        else (
+            ParameterCondition(
+                "nstages",
+                tuple(float(stage_count) for stage_count in range(index, 9)),
+            ),
+        )
+    )
+    return (
+        ParameterDefinition(
+            f"start{index}",
+            0.0 if index == 1 else 1.0,
+            label=f"第 {index} 段起点",
+            quantity="dimensionless",
+            unit="",
+            description=f"第 {index} 段开始时的输出值。",
+            visible_when=visible_when,
+        ),
+        ParameterDefinition(
+            f"end{index}",
+            1.0,
+            label=f"第 {index} 段终点",
+            quantity="dimensionless",
+            unit="",
+            description=f"第 {index} 段结束时的输出值。",
+            visible_when=visible_when,
+        ),
+        ParameterDefinition(
+            f"t{index}",
+            1.0 if index == 1 else 0.0,
+            label=f"第 {index} 段时长",
+            quantity="time",
+            unit="s",
+            minimum=0.0,
+            description=f"第 {index} 段的持续时间。",
+            visible_when=visible_when,
+        ),
+    )
+
+
+_UD00_STAGE_PARAMETERS = tuple(
+    parameter
+    for stage_index in range(1, 9)
+    for parameter in _ud00_stage_parameters(stage_index)
+)
+

 class AmesimStep0(AlgebraicComponent):
    """AMESim STEP0 scalar step signal source."""
-    MODEL_TYPE = 'amesim_step0'
-    MODEL_VERSION = '0.1.0'
-    PORTS = (PortDefinition.signal('out', nominal_role='output'),)
-    PARAMETERS = (ParameterDefinition('initial', 0.0, label='初始值', quantity='dimensionless', unit=''), ParameterDefinition('final', 1.0, label='阶跃后值', quantity='dimensionless', unit=''), ParameterDefinition('time', 0.0, label='阶跃时间', quantity='time', unit='s'))
-    RESULT_VARIABLES = (ResultVariableDefinition('y', '输出', 'dimensionless', '', 'signal', 10),)
-    DISPLAY = ComponentDisplaySpec(label='STEP0 阶跃信号', library_id='amesim', category_id='signals', symbol='amesim_step0', ports=(PortDisplaySpec('out', 'right', order=10),), order=10)

-    def __init__(self, name: str, medium: IdealGasMedium, *, initial: float=0.0, final: float=1.0, time: float=0.0) -> None:
+    MODEL_TYPE = "amesim_step0"
+    MODEL_VERSION = "0.1.0"
+    PORTS = (PortDefinition.signal("out", nominal_role="output"),)
+    PARAMETERS = (
+        ParameterDefinition("initial", 0.0, label="初始值", quantity="dimensionless", unit=""),
+        ParameterDefinition("final", 1.0, label="阶跃后值", quantity="dimensionless", unit=""),
+        ParameterDefinition("time", 0.0, label="阶跃时间", quantity="time", unit="s"),
+    )
+    RESULT_VARIABLES = (
+        ResultVariableDefinition("y", "输出", "dimensionless", "", "signal", 10),
+    )
+    DISPLAY = ComponentDisplaySpec(
+        label="STEP0 阶跃信号",
+        library_id="amesim",
+        category_id="signals",
+        symbol="amesim_step0",
+        ports=(PortDisplaySpec("out", "right", order=10),),
+        order=10,
+    )
+
+    def __init__(
+        self,
+        name: str,
+        medium: IdealGasMedium,
+        *,
+        initial: float = 0.0,
+        final: float = 1.0,
+        time: float = 0.0,
+    ) -> None:
        super().__init__(name=name)
-        self.set_parameter_values({'initial': initial, 'final': final, 'time': time})
+        self.set_parameter_values({"initial": initial, "final": final, "time": time})
        self.initial = float(initial)
        self.final = float(final)
        self.time = float(time)
-        self.out = self.register_declared_port('out')
+        self.out = self.register_declared_port("out")
+        self.out.signal = self.output_at(0.0)

    @classmethod
-    def create(cls, *, name: str, medium: IdealGasMedium, parameters: Mapping[str, float]) -> 'AmesimStep0':
-        return cls(name=name, medium=medium, initial=parameters['initial'], final=parameters['final'], time=parameters['time'])
-    EQUATIONS = ()
+    def create(
+        cls,
+        *,
+        name: str,
+        medium: IdealGasMedium,
+        parameters: Mapping[str, float],
+    ) -> "AmesimStep0":
+        return cls(
+            name=name,
+            medium=medium,
+            initial=parameters["initial"],
+            final=parameters["final"],
+            time=parameters["time"],
+        )
+
+    def output_at(self, time: float) -> float:
+        return self.final if time >= self.time else self.initial
+
+    def signal_output_values(self, time: float) -> dict[str, float]:
+        return {"out": self.output_at(time)}
+
+    def signal_event_times(
+        self,
+        start_time: float,
+        stop_time: float,
+    ) -> tuple[float, ...]:
+        """Expose the exact STEP0 switch time as an integration split point."""
+
+        return (self.time,) if start_time < self.time < stop_time else ()
+
+    def component_result_values(self) -> Mapping[str, float]:
+        return {"y": self.out.signal}
+

 class AmesimUd00(AlgebraicComponent):
    """AMESim UD00 piecewise-linear scalar signal source."""
-    MODEL_TYPE = 'amesim_ud00'
-    MODEL_VERSION = '0.2.0'
-    PORTS = (PortDefinition.signal('out', nominal_role='output'),)
-    PARAMETERS = (ParameterDefinition('tstart', 0.0, label='启动时间', quantity='time', unit='s', description='分段信号开始输出第一段之前的等待时间。'), *_UD00_STAGE_PARAMETERS, ParameterDefinition('nstages', 1.0, label='段数', quantity='dimensionless', unit='', minimum=1.0, maximum=8.0, editor='choice', options=tuple((ParameterOption(float(stage_count), str(stage_count)) for stage_count in range(1, 9))), description='参与输出计算的有效线性分段数量。'), ParameterDefinition('iscyclic', 0.0, label='循环', quantity='dimensionless', unit='', minimum=0.0, maximum=1.0, editor='choice', options=(ParameterOption(0.0, '否'), ParameterOption(1.0, '是')), description='当前公共协议编码：0 表示单次输出，1 表示循环输出。'))
-    RESULT_VARIABLES = (ResultVariableDefinition('y', '输出', 'dimensionless', '', 'signal', 10),)
-    DISPLAY = ComponentDisplaySpec(label='UD00 分段线性信号', library_id='amesim', category_id='signals', symbol='amesim_ud00', ports=(PortDisplaySpec('out', 'right', order=10),), order=20, parameter_groups=(ParameterGroupDisplaySpec(id='stages', label='分段参数', parameters=tuple((parameter.name for parameter in _UD00_STAGE_PARAMETERS)), order=10),))

-    def __init__(self, name: str, medium: IdealGasMedium, *, tstart: float=0.0, starts: tuple[float, ...]=(0.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0), ends: tuple[float, ...]=(1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0), durations: tuple[float, ...]=(1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0), nstages: int=1, iscyclic: bool=False) -> None:
+    MODEL_TYPE = "amesim_ud00"
+    MODEL_VERSION = "0.2.0"
+    PORTS = (PortDefinition.signal("out", nominal_role="output"),)
+    PARAMETERS = (
+        ParameterDefinition(
+            "tstart",
+            0.0,
+            label="启动时间",
+            quantity="time",
+            unit="s",
+            description="分段信号开始输出第一段之前的等待时间。",
+        ),
+        *_UD00_STAGE_PARAMETERS,
+        ParameterDefinition(
+            "nstages",
+            1.0,
+            label="段数",
+            quantity="dimensionless",
+            unit="",
+            minimum=1.0,
+            maximum=8.0,
+            editor="choice",
+            options=tuple(
+                ParameterOption(float(stage_count), str(stage_count))
+                for stage_count in range(1, 9)
+            ),
+            description="参与输出计算的有效线性分段数量。",
+        ),
+        ParameterDefinition(
+            "iscyclic",
+            0.0,
+            label="循环",
+            quantity="dimensionless",
+            unit="",
+            minimum=0.0,
+            maximum=1.0,
+            editor="choice",
+            options=(
+                ParameterOption(0.0, "否"),
+                ParameterOption(1.0, "是"),
+            ),
+            description="当前公共协议编码：0 表示单次输出，1 表示循环输出。",
+        ),
+    )
+    RESULT_VARIABLES = (
+        ResultVariableDefinition("y", "输出", "dimensionless", "", "signal", 10),
+    )
+    DISPLAY = ComponentDisplaySpec(
+        label="UD00 分段线性信号",
+        library_id="amesim",
+        category_id="signals",
+        symbol="amesim_ud00",
+        ports=(PortDisplaySpec("out", "right", order=10),),
+        order=20,
+        parameter_groups=(
+            ParameterGroupDisplaySpec(
+                id="stages",
+                label="分段参数",
+                parameters=tuple(
+                    parameter.name for parameter in _UD00_STAGE_PARAMETERS
+                ),
+                order=10,
+            ),
+        ),
+    )
+
+    def __init__(
+        self,
+        name: str,
+        medium: IdealGasMedium,
+        *,
+        tstart: float = 0.0,
+        starts: tuple[float, ...] = (0.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0),
+        ends: tuple[float, ...] = (1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0),
+        durations: tuple[float, ...] = (1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0),
+        nstages: int = 1,
+        iscyclic: bool = False,
+    ) -> None:
        super().__init__(name=name)
        if len(starts) != 8 or len(ends) != 8 or len(durations) != 8:
-            raise ValueError('UD00 requires exactly eight start, end, and duration values.')
+            raise ValueError("UD00 requires exactly eight start, end, and duration values.")
        if nstages < 1 or nstages > 8:
-            raise ValueError('UD00 nstages must be between 1 and 8.')
+            raise ValueError("UD00 nstages must be between 1 and 8.")
        self.tstart = float(tstart)
-        self.starts = tuple((float(value) for value in starts))
-        self.ends = tuple((float(value) for value in ends))
-        self.durations = tuple((float(value) for value in durations))
+        self.starts = tuple(float(value) for value in starts)
+        self.ends = tuple(float(value) for value in ends)
+        self.durations = tuple(float(value) for value in durations)
        self.nstages = int(nstages)
        self.iscyclic = bool(iscyclic)
-        values: dict[str, float] = {'tstart': self.tstart, 'nstages': float(self.nstages), 'iscyclic': float(int(self.iscyclic))}
+        values: dict[str, float] = {"tstart": self.tstart, "nstages": float(self.nstages), "iscyclic": float(int(self.iscyclic))}
        for index in range(1, 9):
-            values[f'start{index}'] = self.starts[index - 1]
-            values[f'end{index}'] = self.ends[index - 1]
-            values[f't{index}'] = self.durations[index - 1]
+            values[f"start{index}"] = self.starts[index - 1]
+            values[f"end{index}"] = self.ends[index - 1]
+            values[f"t{index}"] = self.durations[index - 1]
        self.set_parameter_values(values)
-        self.out = self.register_declared_port('out')
+        self.out = self.register_declared_port("out")
+        self.out.signal = self.output_at(0.0)

    @classmethod
-    def create(cls, *, name: str, medium: IdealGasMedium, parameters: Mapping[str, float]) -> 'AmesimUd00':
-        nstages = parameters['nstages']
-        iscyclic = parameters['iscyclic']
+    def create(
+        cls,
+        *,
+        name: str,
+        medium: IdealGasMedium,
+        parameters: Mapping[str, float],
+    ) -> "AmesimUd00":
+        nstages = parameters["nstages"]
+        iscyclic = parameters["iscyclic"]
        definitions = {definition.name: definition for definition in cls.PARAMETERS}
-        for parameter_name, value in (('nstages', nstages), ('iscyclic', iscyclic)):
+        for parameter_name, value in (
+            ("nstages", nstages),
+            ("iscyclic", iscyclic),
+        ):
            numeric_value = float(value)
            if not numeric_value.is_integer():
-                raise ValueError(f'UD00 {parameter_name} must be an integer.')
+                raise ValueError(f"UD00 {parameter_name} must be an integer.")
            message = definitions[parameter_name].validation_message(numeric_value)
            if message is not None:
-                raise ValueError(f'UD00 {parameter_name} {message}.')
-        return cls(name=name, medium=medium, tstart=parameters['tstart'], starts=tuple((parameters[f'start{index}'] for index in range(1, 9))), ends=tuple((parameters[f'end{index}'] for index in range(1, 9))), durations=tuple((parameters[f't{index}'] for index in range(1, 9))), nstages=int(nstages), iscyclic=bool(int(iscyclic)))
-    EQUATIONS = ()
+                raise ValueError(f"UD00 {parameter_name} {message}.")
+        return cls(
+            name=name,
+            medium=medium,
+            tstart=parameters["tstart"],
+            starts=tuple(parameters[f"start{index}"] for index in range(1, 9)),
+            ends=tuple(parameters[f"end{index}"] for index in range(1, 9)),
+            durations=tuple(parameters[f"t{index}"] for index in range(1, 9)),
+            nstages=int(nstages),
+            iscyclic=bool(int(iscyclic)),
+        )
+
+    def output_at(self, time: float) -> float:
+        elapsed = max(float(time) - self.tstart, 0.0)
+        active_durations = self.durations[: self.nstages]
+        total_duration = sum(active_durations)
+        if self.iscyclic and total_duration > 0.0:
+            elapsed = elapsed % total_duration
+
+        stage_start_time = 0.0
+        for index, duration in enumerate(active_durations):
+            stage_end_time = stage_start_time + duration
+            if elapsed < stage_end_time or index == self.nstages - 1:
+                if duration <= 0.0:
+                    return self.ends[index]
+                fraction = (elapsed - stage_start_time) / duration
+                return self.starts[index] + fraction * (self.ends[index] - self.starts[index])
+            stage_start_time = stage_end_time
+        return self.ends[self.nstages - 1]
+
+    def signal_output_values(self, time: float) -> dict[str, float]:
+        return {"out": self.output_at(time)}
+
+    def signal_event_times(
+        self,
+        start_time: float,
+        stop_time: float,
+    ) -> tuple[float, ...]:
+        """Return UD00 start, stage, and repeated cycle boundaries.
+
+        The final non-cyclic stage is intentionally not given an end event:
+        ``output_at`` continues that stage's slope after its configured duration.
+        """
+
+        if stop_time <= start_time:
+            return ()
+
+        active_durations = self.durations[: self.nstages]
+        stage_offsets = [0.0]
+        elapsed = 0.0
+        for duration in active_durations[:-1]:
+            elapsed += duration
+            stage_offsets.append(elapsed)
+
+        if not self.iscyclic:
+            return tuple(
+                sorted(
+                    {
+                        event_time
+                        for offset in stage_offsets
+                        if start_time
+                        < (event_time := self.tstart + offset)
+                        < stop_time
+                    }
+                )
+            )
+
+        cycle_duration = sum(active_durations)
+        if cycle_duration <= 0.0:
+            return ()
+
+        events: set[float] = set()
+        for offset in stage_offsets:
+            first_boundary = self.tstart + offset
+            cycle_index = max(
+                0,
+                floor((start_time - first_boundary) / cycle_duration) + 1,
+            )
+            event_time = first_boundary + cycle_index * cycle_duration
+            while event_time < stop_time:
+                if event_time > start_time:
+                    events.add(event_time)
+                cycle_index += 1
+                event_time = first_boundary + cycle_index * cycle_duration
+        return tuple(sorted(events))
+
+    def component_result_values(self) -> Mapping[str, float]:
+        return {"y": self.out.signal}
@@ -1,13 +1,38 @@
-"""Component parameters, ports and output definitions; numerical equations execute in C."""
 from __future__ import annotations
-from collections.abc import Mapping
-from app.simulation.components.amesim.gases import AMESIM_GAS_INDEX_PARAMETER, normalize_amesim_gas_index
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from math import isfinite
+
+from app.simulation.components.amesim.gases import (
+    AMESIM_GAS_INDEX_PARAMETER,
+    normalize_amesim_gas_index,
+)
 from app.simulation.core.base import ThermodynamicVolumeComponent
 from app.simulation.core.catalog import ComponentDisplaySpec, PortDisplaySpec
-from app.simulation.core.metadata import ParameterDefinition, ResultVariableDefinition, THERMODYNAMIC_VOLUME_RESULT_VARIABLES
-from app.simulation.core.medium import GasMedium
+from app.simulation.core.equations import EquationResidual
+from app.simulation.core.metadata import (
+    ParameterDefinition,
+    ResultVariableDefinition,
+    THERMODYNAMIC_VOLUME_RESULT_VARIABLES,
+)
+from app.simulation.core.medium import (
+    GasMedium,
+    ThermodynamicProperties,
+    ThermodynamicPropertiesLinearization,
+)
 from app.simulation.core.ports import PortDefinition
-from app.simulation.core.port_computation import THERMODYNAMIC_SUPPLY
+from app.simulation.core.state import VolumeState
+
+
+@dataclass(frozen=True)
+class Pnch012DerivativeLinearization:
+    derivative: tuple[float, float]
+    tangents: tuple[tuple[float, ...], tuple[float, ...]]
+    properties: ThermodynamicPropertiesLinearization
+    valid: bool = True
+    reason: str | None = None
+

 class AmesimPnch023(ThermodynamicVolumeComponent):
    """AMESim PNCH023 simple pneumatic chamber with heat exchange.
@@ -17,16 +42,112 @@ class AmesimPnch023(ThermodynamicVolumeComponent):
    framework's mass/internal-energy volume state and keeps the AMESim
    heat-transfer contract `kth * sth * (extemp - T)`.
    """
-    MODEL_TYPE = 'amesim_pnch023'
-    MODEL_VERSION = '0.1.0'
-    PORTS = (PortDefinition.pneumatic('port_1', computation=THERMODYNAMIC_SUPPLY), PortDefinition.pneumatic('port_2', computation=THERMODYNAMIC_SUPPLY))
-    PARAMETERS = (AMESIM_GAS_INDEX_PARAMETER, ParameterDefinition('cvol', 0.057, label='气室容积', quantity='volume', unit='m3', minimum=0.0, minimum_exclusive=True, description='气室内部用于储存气体的固定有效容积。'), ParameterDefinition('kth', 0.0, label='换热系数', quantity='heat_transfer_coefficient', unit='W/(m2*K)', minimum=0.0, description='气室与环境之间的对流换热系数，与换热面积共同决定换热功率。'), ParameterDefinition('sth', 0.1, label='换热面积', quantity='area', unit='m2', minimum=0.0, description='气室与环境进行热交换的有效表面积。'), ParameterDefinition('extemp', 293.15, label='外部温度', quantity='temperature', unit='K', minimum=0.0, minimum_exclusive=True, description='气室外部环境的绝对温度，用于计算气体与环境之间的换热。'), ParameterDefinition('p0', 100000.0, label='初始压力', quantity='pressure', unit='Pa', minimum=0.0, minimum_exclusive=True, description='仿真开始时气室内气体的绝对压力。'), ParameterDefinition('T0', 293.15, label='初始温度', quantity='temperature', unit='K', minimum=0.0, minimum_exclusive=True, description='仿真开始时气室内气体的绝对温度。'))
-    RESULT_VARIABLES = THERMODYNAMIC_VOLUME_RESULT_VARIABLES
-    DISPLAY = ComponentDisplaySpec(label='PNCH023 固定容积气室', library_id='amesim', category_id='storage', symbol='amesim_pnch023', ports=(PortDisplaySpec('port_1', 'left', order=10), PortDisplaySpec('port_2', 'right', order=20)), order=10)

-    def __init__(self, name: str, medium: GasMedium, *, cvol: float=0.057, kth: float=0.0, sth: float=0.1, extemp: float=293.15, gi: float=1.0, p0: float=100000.0, T0: float=293.15) -> None:
+    MODEL_TYPE = "amesim_pnch023"
+    MODEL_VERSION = "0.1.0"
+    PORTS = (
+        PortDefinition.pneumatic("port_1", nominal_role="bidirectional"),
+        PortDefinition.pneumatic("port_2", nominal_role="bidirectional"),
+    )
+    PARAMETERS = (
+        AMESIM_GAS_INDEX_PARAMETER,
+        ParameterDefinition(
+            "cvol",
+            0.057,
+            label="气室容积",
+            quantity="volume",
+            unit="m3",
+            minimum=0.0,
+            minimum_exclusive=True,
+            description="气室内部用于储存气体的固定有效容积。",
+        ),
+        ParameterDefinition(
+            "kth",
+            0.0,
+            label="换热系数",
+            quantity="heat_transfer_coefficient",
+            unit="W/(m2*K)",
+            minimum=0.0,
+            description="气室与环境之间的对流换热系数，与换热面积共同决定换热功率。",
+        ),
+        ParameterDefinition(
+            "sth",
+            0.1,
+            label="换热面积",
+            quantity="area",
+            unit="m2",
+            minimum=0.0,
+            description="气室与环境进行热交换的有效表面积。",
+        ),
+        ParameterDefinition(
+            "extemp",
+            293.15,
+            label="外部温度",
+            quantity="temperature",
+            unit="K",
+            minimum=0.0,
+            minimum_exclusive=True,
+            description="气室外部环境的绝对温度，用于计算气体与环境之间的换热。",
+        ),
+        ParameterDefinition(
+            "p0",
+            100000.0,
+            label="初始压力",
+            quantity="pressure",
+            unit="Pa",
+            minimum=0.0,
+            minimum_exclusive=True,
+            description="仿真开始时气室内气体的绝对压力。",
+        ),
+        ParameterDefinition(
+            "T0",
+            293.15,
+            label="初始温度",
+            quantity="temperature",
+            unit="K",
+            minimum=0.0,
+            minimum_exclusive=True,
+            description="仿真开始时气室内气体的绝对温度。",
+        ),
+    )
+    RESULT_VARIABLES = THERMODYNAMIC_VOLUME_RESULT_VARIABLES
+    DISPLAY = ComponentDisplaySpec(
+        label="PNCH023 固定容积气室",
+        library_id="amesim",
+        category_id="storage",
+        symbol="amesim_pnch023",
+        ports=(
+            PortDisplaySpec("port_1", "left", order=10),
+            PortDisplaySpec("port_2", "right", order=20),
+        ),
+        order=10,
+    )
+
+    def __init__(
+        self,
+        name: str,
+        medium: GasMedium,
+        *,
+        cvol: float = 0.057,
+        kth: float = 0.0,
+        sth: float = 0.1,
+        extemp: float = 293.15,
+        gi: float = 1.0,
+        p0: float = 100000.0,
+        T0: float = 293.15,
+    ) -> None:
        super().__init__(name=name)
-        self.set_parameter_values({'cvol': cvol, 'kth': kth, 'sth': sth, 'extemp': extemp, 'gi': gi, 'p0': p0, 'T0': T0})
+        self.set_parameter_values(
+            {
+                "cvol": cvol,
+                "kth": kth,
+                "sth": sth,
+                "extemp": extemp,
+                "gi": gi,
+                "p0": p0,
+                "T0": T0,
+            }
+        )
        self.medium = medium
        self.cvol = float(cvol)
        self.kth = float(kth)
@@ -35,33 +156,266 @@ class AmesimPnch023(ThermodynamicVolumeComponent):
        self.gi = normalize_amesim_gas_index(gi)
        self.p0 = float(p0)
        self.T0 = float(T0)
-        self.port_1 = self.register_declared_port('port_1')
-        self.port_2 = self.register_declared_port('port_2')
+        m0 = medium.density(self.p0, self.T0) * self.cvol
+        U0 = m0 * medium.specific_internal_energy_at_pressure(self.p0, self.T0)
+        self.state = VolumeState(m=m0, U=U0)
+        initial_h = medium.specific_enthalpy_at_pressure(self.p0, self.T0)
+        self.port_1 = self.register_declared_port("port_1")
+        self.port_1.p = self.p0
+        self.port_1.h_outflow = initial_h
+        self.port_2 = self.register_declared_port("port_2")
+        self.port_2.p = self.p0
+        self.port_2.h_outflow = initial_h

    @classmethod
-    def create(cls, *, name: str, medium: GasMedium, parameters: Mapping[str, float]) -> AmesimPnch023:
-        return cls(name=name, medium=medium, cvol=parameters['cvol'], kth=parameters['kth'], sth=parameters['sth'], extemp=parameters['extemp'], gi=parameters['gi'], p0=parameters['p0'], T0=parameters['T0'])
-    EQUATIONS = ({'id': '__MODEL__:port_1_pressure_state', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'state', 'variables': ['__MODEL__.port_1.p', '__MODEL__.state'], 'role': 'effort'}, {'id': '__MODEL__:port_2_pressure_state', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'state', 'variables': ['__MODEL__.port_2.p', '__MODEL__.state'], 'role': 'effort'})
+    def create(
+        cls,
+        *,
+        name: str,
+        medium: GasMedium,
+        parameters: Mapping[str, float],
+    ) -> AmesimPnch023:
+        return cls(
+            name=name,
+            medium=medium,
+            cvol=parameters["cvol"],
+            kth=parameters["kth"],
+            sth=parameters["sth"],
+            extemp=parameters["extemp"],
+            gi=parameters["gi"],
+            p0=parameters["p0"],
+            T0=parameters["T0"],
+        )
+
+    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 properties(self) -> ThermodynamicProperties:
+        props = self.medium.properties_from_mU(self.state.m, self.state.U, self.cvol)
+        self.port_1.p = props.p
+        self.port_1.h_outflow = props.h
+        self.port_2.p = props.p
+        self.port_2.h_outflow = props.h
+        return props
+
+    def refresh_thermodynamic_ports(self) -> ThermodynamicProperties:
+        return self.properties()
+
+    def thermal_energy_flow_w(self, temperature: float) -> float:
+        return self.kth * self.sth * (self.extemp - temperature)
+
+    def state_derivative_from_ports(
+        self,
+        connected_h: Mapping[str, float],
+    ) -> list[float]:
+        props = self.properties()
+        inlet_h_1 = self.connection_inlet_enthalpy(
+            port_m_flow=self.port_1.m_flow,
+            connected_h=connected_h["port_1"],
+            internal_h=props.h,
+        )
+        inlet_h_2 = self.connection_inlet_enthalpy(
+            port_m_flow=self.port_2.m_flow,
+            connected_h=connected_h["port_2"],
+            internal_h=props.h,
+        )
+        derivative = VolumeState(
+            m=self.port_1.m_flow + self.port_2.m_flow,
+            U=(
+                self.port_1.m_flow * inlet_h_1
+                + self.port_2.m_flow * inlet_h_2
+                + self.thermal_energy_flow_w(props.T)
+            ),
+        )
+        return derivative.as_vector()
+
+    def pressure_flow_equation_values(self) -> tuple[float, ...]:
+        pressure = self.medium.properties_from_mU(
+            self.state.m,
+            self.state.U,
+            self.cvol,
+        ).p
+        return (
+            self.port_1.p - pressure,
+            self.port_2.p - pressure,
+        )
+
+    def pressure_flow_equation_residuals(self) -> tuple[EquationResidual, ...]:
+        pressure = self.medium.properties_from_mU(
+            self.state.m,
+            self.state.U,
+            self.cvol,
+        ).p
+        return (
+            EquationResidual(
+                id=f"{self.name}:port_1_pressure_state",
+                owner="component",
+                owner_id=self.name,
+                relation="state",
+                variables=(f"{self.name}.port_1.p", f"{self.name}.state"),
+                role="effort",
+                value=self.port_1.p - pressure,
+            ),
+            EquationResidual(
+                id=f"{self.name}:port_2_pressure_state",
+                owner="component",
+                owner_id=self.name,
+                relation="state",
+                variables=(f"{self.name}.port_2.p", f"{self.name}.state"),
+                role="effort",
+                value=self.port_2.p - pressure,
+            ),
+        )
+

 class AmesimPnch012(ThermodynamicVolumeComponent):
    """AMESim PNCH012 variable-volume pneumatic chamber.

    AMESim supplies four external volume and volume-rate inputs through the
-    chamber ports. The SI vol1..4 parameters specify initial external volumes;
-    dvol1..4 prescribe constant rates integrated from the simulation start.
-    Connected moving boundaries supply their live geometry and rate directly,
-    including through reference nodes, without integrating that geometry again.
+    chamber ports. Fixed/prescribed contributions remain available as SI
+    parameters, while connected moving-boundary components can now add live
+    volume and volume-rate values through the pneumatic connector contract.
    """
-    MODEL_TYPE = 'amesim_pnch012'
-    MODEL_VERSION = '0.1.0'
-    PORTS = tuple(PortDefinition.pneumatic(f'port_{i}', computation=THERMODYNAMIC_SUPPLY) for i in range(1, 5))
-    PARAMETERS = (AMESIM_GAS_INDEX_PARAMETER, ParameterDefinition('cvol0', 0.015, label='死容积', quantity='volume', unit='m3', minimum=0.0, minimum_exclusive=True, description='变容气室在所有外部容积为零时仍保留的基础容积。'), ParameterDefinition('kth', 0.0, label='换热系数', quantity='heat_transfer_coefficient', unit='W/(m2*K)', minimum=0.0, description='气室与环境之间的对流换热系数，与换热面积共同决定换热功率。'), ParameterDefinition('sth', 0.1, label='换热面积', quantity='area', unit='m2', minimum=0.0, description='气室与环境进行热交换的有效表面积。'), ParameterDefinition('extemp', 293.15, label='外部温度', quantity='temperature', unit='K', minimum=0.0, minimum_exclusive=True, description='气室外部环境的绝对温度，用于计算气体与环境之间的换热。'), ParameterDefinition('p0', 100000.0, label='初始压力', quantity='pressure', unit='Pa', minimum=0.0, minimum_exclusive=True, description='仿真开始时气室内气体的绝对压力。'), ParameterDefinition('T0', 293.15, label='初始温度', quantity='temperature', unit='K', minimum=0.0, minimum_exclusive=True, description='仿真开始时气室内气体的绝对温度。'), ParameterDefinition('vol1', 0.0, label='端口 1 外部容积', quantity='volume', unit='m3', description='仿真开始时的预设外部容积；对应容积变化率从此初值起积分，并叠加连接元件提供的实时容积。'), ParameterDefinition('vol2', 0.0, label='端口 2 外部容积', quantity='volume', unit='m3', description='仿真开始时的预设外部容积；对应容积变化率从此初值起积分，并叠加连接元件提供的实时容积。'), ParameterDefinition('vol3', 0.0, label='端口 3 外部容积', quantity='volume', unit='m3', description='仿真开始时的预设外部容积；对应容积变化率从此初值起积分，并叠加连接元件提供的实时容积。'), ParameterDefinition('vol4', 0.0, label='端口 4 外部容积', quantity='volume', unit='m3', description='仿真开始时的预设外部容积；对应容积变化率从此初值起积分，并叠加连接元件提供的实时容积。'), ParameterDefinition('dvol1', 0.0, label='端口 1 容积变化率', quantity='volume_flow', unit='m3/s', description='预设外部容积的恒定变化率，从仿真开始时积分；连接元件的实时容积及变化率另行叠加。'), ParameterDefinition('dvol2', 0.0, label='端口 2 容积变化率', quantity='volume_flow', unit='m3/s', description='预设外部容积的恒定变化率，从仿真开始时积分；连接元件的实时容积及变化率另行叠加。'), ParameterDefinition('dvol3', 0.0, label='端口 3 容积变化率', quantity='volume_flow', unit='m3/s', description='预设外部容积的恒定变化率，从仿真开始时积分；连接元件的实时容积及变化率另行叠加。'), ParameterDefinition('dvol4', 0.0, label='端口 4 容积变化率', quantity='volume_flow', unit='m3/s', description='预设外部容积的恒定变化率，从仿真开始时积分；连接元件的实时容积及变化率另行叠加。'))
-    RESULT_VARIABLES = THERMODYNAMIC_VOLUME_RESULT_VARIABLES + (ResultVariableDefinition('vol', '气室总容积', 'volume', 'm3', 'derived', 100), ResultVariableDefinition('dvol', '总容积变化率', 'volume_flow', 'm3/s', 'derived', 110))
-    DISPLAY = ComponentDisplaySpec(label='PNCH012 变容气室', library_id='amesim', category_id='storage', symbol='amesim_pnch012', ports=(PortDisplaySpec('port_1', 'left', order=10), PortDisplaySpec('port_2', 'right', order=20), PortDisplaySpec('port_3', 'left', order=30), PortDisplaySpec('port_4', 'right', order=40)), order=20)

-    def __init__(self, name: str, medium: GasMedium, *, cvol0: float=0.015, kth: float=0.0, sth: float=0.1, extemp: float=293.15, gi: float=1.0, p0: float=100000.0, T0: float=293.15, vol1: float=0.0, vol2: float=0.0, vol3: float=0.0, vol4: float=0.0, dvol1: float=0.0, dvol2: float=0.0, dvol3: float=0.0, dvol4: float=0.0) -> None:
+    MODEL_TYPE = "amesim_pnch012"
+    MODEL_VERSION = "0.1.0"
+    PORTS = (
+        PortDefinition.pneumatic("port_1", nominal_role="bidirectional"),
+        PortDefinition.pneumatic("port_2", nominal_role="bidirectional"),
+        PortDefinition.pneumatic("port_3", nominal_role="bidirectional"),
+        PortDefinition.pneumatic("port_4", nominal_role="bidirectional"),
+    )
+    PARAMETERS = (
+        AMESIM_GAS_INDEX_PARAMETER,
+        ParameterDefinition(
+            "cvol0",
+            0.015,
+            label="死容积",
+            quantity="volume",
+            unit="m3",
+            minimum=0.0,
+            minimum_exclusive=True,
+            description="变容气室在所有外部容积为零时仍保留的基础容积。",
+        ),
+        ParameterDefinition(
+            "kth",
+            0.0,
+            label="换热系数",
+            quantity="heat_transfer_coefficient",
+            unit="W/(m2*K)",
+            minimum=0.0,
+            description="气室与环境之间的对流换热系数，与换热面积共同决定换热功率。",
+        ),
+        ParameterDefinition(
+            "sth",
+            0.1,
+            label="换热面积",
+            quantity="area",
+            unit="m2",
+            minimum=0.0,
+            description="气室与环境进行热交换的有效表面积。",
+        ),
+        ParameterDefinition(
+            "extemp",
+            293.15,
+            label="外部温度",
+            quantity="temperature",
+            unit="K",
+            minimum=0.0,
+            minimum_exclusive=True,
+            description="气室外部环境的绝对温度，用于计算气体与环境之间的换热。",
+        ),
+        ParameterDefinition(
+            "p0",
+            100000.0,
+            label="初始压力",
+            quantity="pressure",
+            unit="Pa",
+            minimum=0.0,
+            minimum_exclusive=True,
+            description="仿真开始时气室内气体的绝对压力。",
+        ),
+        ParameterDefinition(
+            "T0",
+            293.15,
+            label="初始温度",
+            quantity="temperature",
+            unit="K",
+            minimum=0.0,
+            minimum_exclusive=True,
+            description="仿真开始时气室内气体的绝对温度。",
+        ),
+        ParameterDefinition("vol1", 0.0, label="端口 1 外部容积", quantity="volume", unit="m3"),
+        ParameterDefinition("vol2", 0.0, label="端口 2 外部容积", quantity="volume", unit="m3"),
+        ParameterDefinition("vol3", 0.0, label="端口 3 外部容积", quantity="volume", unit="m3"),
+        ParameterDefinition("vol4", 0.0, label="端口 4 外部容积", quantity="volume", unit="m3"),
+        ParameterDefinition("dvol1", 0.0, label="端口 1 容积变化率", quantity="volume_flow", unit="m3/s"),
+        ParameterDefinition("dvol2", 0.0, label="端口 2 容积变化率", quantity="volume_flow", unit="m3/s"),
+        ParameterDefinition("dvol3", 0.0, label="端口 3 容积变化率", quantity="volume_flow", unit="m3/s"),
+        ParameterDefinition("dvol4", 0.0, label="端口 4 容积变化率", quantity="volume_flow", unit="m3/s"),
+    )
+    RESULT_VARIABLES = THERMODYNAMIC_VOLUME_RESULT_VARIABLES + (
+        ResultVariableDefinition("vol", "气室总容积", "volume", "m3", "derived", 100),
+        ResultVariableDefinition("dvol", "总容积变化率", "volume_flow", "m3/s", "derived", 110),
+    )
+    DISPLAY = ComponentDisplaySpec(
+        label="PNCH012 变容气室",
+        library_id="amesim",
+        category_id="storage",
+        symbol="amesim_pnch012",
+        ports=(
+            PortDisplaySpec("port_1", "left", order=10),
+            PortDisplaySpec("port_2", "right", order=20),
+            PortDisplaySpec("port_3", "left", order=30),
+            PortDisplaySpec("port_4", "right", order=40),
+        ),
+        order=20,
+    )
+
+    def __init__(
+        self,
+        name: str,
+        medium: GasMedium,
+        *,
+        cvol0: float = 0.015,
+        kth: float = 0.0,
+        sth: float = 0.1,
+        extemp: float = 293.15,
+        gi: float = 1.0,
+        p0: float = 100000.0,
+        T0: float = 293.15,
+        vol1: float = 0.0,
+        vol2: float = 0.0,
+        vol3: float = 0.0,
+        vol4: float = 0.0,
+        dvol1: float = 0.0,
+        dvol2: float = 0.0,
+        dvol3: float = 0.0,
+        dvol4: float = 0.0,
+    ) -> None:
        super().__init__(name=name)
-        self.set_parameter_values({'cvol0': cvol0, 'kth': kth, 'sth': sth, 'extemp': extemp, 'gi': gi, 'p0': p0, 'T0': T0, 'vol1': vol1, 'vol2': vol2, 'vol3': vol3, 'vol4': vol4, 'dvol1': dvol1, 'dvol2': dvol2, 'dvol3': dvol3, 'dvol4': dvol4})
+        self.set_parameter_values(
+            {
+                "cvol0": cvol0,
+                "kth": kth,
+                "sth": sth,
+                "extemp": extemp,
+                "gi": gi,
+                "p0": p0,
+                "T0": T0,
+                "vol1": vol1,
+                "vol2": vol2,
+                "vol3": vol3,
+                "vol4": vol4,
+                "dvol1": dvol1,
+                "dvol2": dvol2,
+                "dvol3": dvol3,
+                "dvol4": dvol4,
+            }
+        )
        self.medium = medium
        self.cvol0 = float(cvol0)
        self.kth = float(kth)
@@ -70,13 +424,267 @@ class AmesimPnch012(ThermodynamicVolumeComponent):
        self.gi = normalize_amesim_gas_index(gi)
        self.p0 = float(p0)
        self.T0 = float(T0)
-        self.external_volumes = {'port_1': float(vol1), 'port_2': float(vol2), 'port_3': float(vol3), 'port_4': float(vol4)}
-        self.external_volume_rates = {'port_1': float(dvol1), 'port_2': float(dvol2), 'port_3': float(dvol3), 'port_4': float(dvol4)}
-        for port_name in ('port_1', 'port_2', 'port_3', 'port_4'):
+        self.external_volumes = {
+            "port_1": float(vol1),
+            "port_2": float(vol2),
+            "port_3": float(vol3),
+            "port_4": float(vol4),
+        }
+        self.external_volume_rates = {
+            "port_1": float(dvol1),
+            "port_2": float(dvol2),
+            "port_3": float(dvol3),
+            "port_4": float(dvol4),
+        }
+        if self.total_volume() <= 0.0:
+            raise ValueError("PNCH012 total volume must be positive.")
+        m0 = medium.density(self.p0, self.T0) * self.total_volume()
+        U0 = m0 * medium.specific_internal_energy_at_pressure(self.p0, self.T0)
+        self.state = VolumeState(m=m0, U=U0)
+        initial_h = medium.specific_enthalpy_at_pressure(self.p0, self.T0)
+        for port_name in ("port_1", "port_2", "port_3", "port_4"):
            port = self.register_declared_port(port_name)
+            port.p = self.p0
+            port.h_outflow = initial_h
            setattr(self, port_name, port)

    @classmethod
-    def create(cls, *, name: str, medium: GasMedium, parameters: Mapping[str, float]) -> 'AmesimPnch012':
+    def create(
+        cls,
+        *,
+        name: str,
+        medium: GasMedium,
+        parameters: Mapping[str, float],
+    ) -> "AmesimPnch012":
        return cls(name=name, medium=medium, **dict(parameters))
-    EQUATIONS = ({'id': '__MODEL__:port_1_pressure_state', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'state', 'variables': ['__MODEL__.port_1.p', '__MODEL__.state'], 'role': 'effort'}, {'id': '__MODEL__:port_2_pressure_state', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'state', 'variables': ['__MODEL__.port_2.p', '__MODEL__.state'], 'role': 'effort'}, {'id': '__MODEL__:port_3_pressure_state', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'state', 'variables': ['__MODEL__.port_3.p', '__MODEL__.state'], 'role': 'effort'}, {'id': '__MODEL__:port_4_pressure_state', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'state', 'variables': ['__MODEL__.port_4.p', '__MODEL__.state'], 'role': 'effort'})
+
+    def connected_external_volume(self) -> float:
+        return sum(
+            getattr(getattr(self, port_name, None), "volume", 0.0)
+            for port_name in self.external_volumes
+        )
+
+    def connected_external_volume_rate(self) -> float:
+        return sum(
+            getattr(getattr(self, port_name, None), "volume_flow", 0.0)
+            for port_name in self.external_volume_rates
+        )
+
+    def total_volume(self) -> float:
+        minimum_volume = self.cvol0 / 100.0
+        return max(
+            self.cvol0 + sum(self.external_volumes.values()) + self.connected_external_volume(),
+            minimum_volume,
+        )
+
+    def total_volume_rate(self) -> float:
+        if self.total_volume() <= self.cvol0 / 100.0:
+            return 0.0
+        return sum(self.external_volume_rates.values()) + self.connected_external_volume_rate()
+
+    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 properties(self) -> ThermodynamicProperties:
+        props = self.medium.properties_from_mU(self.state.m, self.state.U, self.total_volume())
+        for port_name in ("port_1", "port_2", "port_3", "port_4"):
+            port = self.get_port(port_name)
+            port.p = props.p
+            port.h_outflow = props.h
+        return props
+
+    def refresh_thermodynamic_ports(self) -> ThermodynamicProperties:
+        return self.properties()
+
+    def thermal_energy_flow_w(self, temperature: float) -> float:
+        return self.kth * self.sth * (self.extemp - temperature)
+
+    def component_result_values(self) -> Mapping[str, float]:
+        props = self.properties()
+        return {
+            "m": self.state.m,
+            "U": self.state.U,
+            "p": props.p,
+            "T": props.T,
+            "rho": props.rho,
+            "u": props.u,
+            "h": props.h,
+            "vol": self.total_volume(),
+            "dvol": self.total_volume_rate(),
+        }
+
+    def state_derivative_from_ports(self, connected_h: Mapping[str, float]) -> list[float]:
+        props = self.properties()
+        mass_derivative = 0.0
+        energy_derivative = 0.0
+        for port_name in ("port_1", "port_2", "port_3", "port_4"):
+            port = self.get_port(port_name)
+            inlet_h = self.connection_inlet_enthalpy(
+                port_m_flow=port.m_flow,
+                connected_h=connected_h[port_name],
+                internal_h=props.h,
+            )
+            mass_derivative += port.m_flow
+            energy_derivative += port.m_flow * inlet_h
+        energy_derivative += self.thermal_energy_flow_w(props.T)
+        energy_derivative -= props.p * self.total_volume_rate()
+        return VolumeState(m=mass_derivative, U=energy_derivative).as_vector()
+
+    def linearize_state_derivative(
+        self,
+        connected_h: Mapping[str, float],
+        *,
+        state_mass_tangent: Sequence[float],
+        state_energy_tangent: Sequence[float],
+        external_volume_tangent: Sequence[float],
+        external_volume_rate_tangent: Sequence[float],
+        port_mass_flow_tangents: Mapping[str, Sequence[float]],
+        connected_h_tangents: Mapping[str, Sequence[float]],
+        property_linearization: ThermodynamicPropertiesLinearization | None = None,
+        flow_boundary_tolerance: float = 1.0e-12,
+    ) -> Pnch012DerivativeLinearization:
+        """Linearize the chamber balance while keeping stream modes fixed."""
+
+        port_names = ("port_1", "port_2", "port_3", "port_4")
+        vectors = {
+            "state_mass": tuple(float(value) for value in state_mass_tangent),
+            "state_energy": tuple(float(value) for value in state_energy_tangent),
+            "volume": tuple(float(value) for value in external_volume_tangent),
+            "volume_rate": tuple(
+                float(value) for value in external_volume_rate_tangent
+            ),
+        }
+        for port_name in port_names:
+            vectors[f"flow:{port_name}"] = tuple(
+                float(value) for value in port_mass_flow_tangents[port_name]
+            )
+            vectors[f"enthalpy:{port_name}"] = tuple(
+                float(value) for value in connected_h_tangents[port_name]
+            )
+        widths = {len(values) for values in vectors.values()}
+        if len(widths) != 1:
+            raise ValueError("PNCH012 tangent vectors must have equal lengths.")
+        width = len(vectors["state_mass"])
+        invalid_reason: str | None = None
+        if not all(isfinite(value) for values in vectors.values() for value in values):
+            invalid_reason = "non_finite_tangent_input"
+
+        raw_volume = (
+            self.cvol0
+            + sum(self.external_volumes.values())
+            + self.connected_external_volume()
+        )
+        minimum_volume = self.cvol0 / 100.0
+        volume_scale = max(abs(raw_volume), abs(minimum_volume), 1.0e-18)
+        on_volume_boundary = (
+            abs(raw_volume - minimum_volume) <= 1.0e-12 * volume_scale
+        )
+        supplied_volume_tangent = vectors["volume"]
+        if raw_volume < minimum_volume or on_volume_boundary:
+            used_volume_tangent = (0.0,) * width
+            used_volume_rate_tangent = (0.0,) * width
+            if on_volume_boundary and any(
+                value != 0.0
+                for value in (
+                    *supplied_volume_tangent,
+                    *vectors["volume_rate"],
+                )
+            ):
+                invalid_reason = invalid_reason or "volume_floor_boundary"
+        else:
+            used_volume_tangent = supplied_volume_tangent
+            used_volume_rate_tangent = vectors["volume_rate"]
+
+        properties = property_linearization or self.medium.linearize_properties_from_mU(
+            self.state.m,
+            self.state.U,
+            self.total_volume(),
+            vectors["state_mass"],
+            vectors["state_energy"],
+            used_volume_tangent,
+        )
+        if properties.tangents.width != width:
+            raise ValueError(
+                "PNCH012 property tangent width must match balance tangents."
+            )
+        props = properties.properties
+        if not properties.valid:
+            invalid_reason = invalid_reason or properties.reason
+
+        mass_derivative = sum(
+            self.get_port(port_name).m_flow for port_name in port_names
+        )
+        volume_rate = self.total_volume_rate()
+        energy_derivative = self.thermal_energy_flow_w(props.T) - props.p * volume_rate
+        mass_tangent = [0.0] * width
+        energy_tangent = [
+            -self.kth * self.sth * properties.tangents.T[index]
+            - volume_rate * properties.tangents.p[index]
+            - props.p * used_volume_rate_tangent[index]
+            for index in range(width)
+        ]
+
+        for port_name in port_names:
+            port = self.get_port(port_name)
+            flow_tangent = vectors[f"flow:{port_name}"]
+            if (
+                abs(port.m_flow) <= flow_boundary_tolerance
+                and any(value != 0.0 for value in flow_tangent)
+            ):
+                invalid_reason = invalid_reason or (
+                    f"flow_direction_boundary:{port_name}"
+                )
+            if port.m_flow > 0.0:
+                inlet_h = connected_h[port_name]
+                inlet_h_tangent = vectors[f"enthalpy:{port_name}"]
+            else:
+                inlet_h = props.h
+                inlet_h_tangent = properties.tangents.h
+            energy_derivative += port.m_flow * inlet_h
+            for index in range(width):
+                mass_tangent[index] += flow_tangent[index]
+                energy_tangent[index] += (
+                    inlet_h * flow_tangent[index]
+                    + port.m_flow * inlet_h_tangent[index]
+                )
+
+        return Pnch012DerivativeLinearization(
+            derivative=(mass_derivative, energy_derivative),
+            tangents=(tuple(mass_tangent), tuple(energy_tangent)),
+            properties=properties,
+            valid=invalid_reason is None,
+            reason=invalid_reason,
+        )
+
+    def pressure_flow_equation_values(self) -> tuple[float, ...]:
+        pressure = self.medium.properties_from_mU(
+            self.state.m,
+            self.state.U,
+            self.total_volume(),
+        ).p
+        return tuple(
+            self.get_port(port_name).p - pressure
+            for port_name in ("port_1", "port_2", "port_3", "port_4")
+        )
+
+    def pressure_flow_equation_residuals(self) -> tuple[EquationResidual, ...]:
+        pressure = self.medium.properties_from_mU(
+            self.state.m,
+            self.state.U,
+            self.total_volume(),
+        ).p
+        return tuple(
+            EquationResidual(
+                id=f"{self.name}:{port_name}_pressure_state",
+                owner="component",
+                owner_id=self.name,
+                relation="state",
+                variables=(f"{self.name}.{port_name}.p", f"{self.name}.state"),
+                role="effort",
+                value=self.get_port(port_name).p - pressure,
+            )
+            for port_name in ("port_1", "port_2", "port_3", "port_4")
+        )
@@ -0,0 +1,282 @@
+# 元件建模规范与示例
+
+规范的权威版本位于
+[`docs/standard/component-model-authoring-spec-v1.md`](../../../docs/standard/component-model-authoring-spec-v1.md)。
+本文档保留在组件目录中，作为离模型源码最近的完整示例；若两者不一致，应在同一次
+修改中同步，不能让示例形成另一套规则。
+
+本文档是 `app/simulation/components` 下新增元件的最小开发规范。当前
+`experimental` 是用于验证规范的临时组件库；后续正式模型应建立独立组件库，
+不要继续堆放在 `experimental` 中。
+
+目标是让元件的端口、输入参数和可展示结果都由元件类显式声明，避免 XML
+校验、求解器和前端分别维护同一份含义。
+
+## 一、元件类必须声明的内容
+
+每个对外注册的元件类至少需要声明以下六个类属性：
+
+```python
+MODEL_TYPE = "example_component"
+MODEL_VERSION = "1.0.0"
+PORTS = (...)
+PARAMETERS = (...)
+RESULT_VARIABLES = (...)
+DISPLAY = ...
+```
+
+- `MODEL_TYPE`：稳定的模型类型标识，对应 System XML 中的 `Component/@type`。发布后不要随意改名。
+- `MODEL_VERSION`：模型契约版本，采用 `主版本.次版本.修订版本`。
+- `PORTS`：端口契约，包括端口名、物理域、变量和正流量方向。
+- `PARAMETERS`：用户可配置的输入参数，包括默认值、物理量、SI 单位和取值范围。
+- `RESULT_VARIABLES`：允许写入仿真结果并显示在结果页的组件级变量。端口结果由 `PORTS` 中的端口变量定义自动生成。
+- `DISPLAY`：组件库名称、分类、图标、排序和端口画布位置，不参与物理求解。
+
+元件构造函数还必须：
+
+1. 调用 `super().__init__(name)`。
+2. 使用 `set_parameter_values()` 保存规范化后的输入参数。
+3. 使用 `register_declared_port()` 创建已声明端口。
+4. 若声明了组件结果变量，实现 `component_result_values()` 并返回对应数值；标准热力学容腔可以直接继承 `ThermodynamicVolumeComponent` 的实现。
+5. 实现统一的类方法 `create()`，接收规范化后的 SI 参数。
+
+## 二、输入参数与结果变量
+
+输入参数和仿真结果必须分开声明：
+
+- 输入参数描述一次仿真开始前由用户配置的量，例如 `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 app.simulation.core.base import ThermodynamicVolumeComponent
+from app.simulation.core.catalog import ComponentDisplaySpec, PortDisplaySpec
+from app.simulation.core.equations import EquationResidual
+from app.simulation.core.metadata import (
+    ParameterDefinition,
+    THERMODYNAMIC_VOLUME_RESULT_VARIABLES,
+)
+from app.simulation.core.medium import IdealGasMedium, ThermodynamicProperties
+from app.simulation.core.ports import PortDefinition
+from app.simulation.core.state import VolumeState
+
+
+class ExampleVolume(ThermodynamicVolumeComponent):
+    MODEL_TYPE = "example_volume"
+    MODEL_VERSION = "1.0.0"
+    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
+    DISPLAY = ComponentDisplaySpec(
+        label="示例容腔",
+        library_id="experimental",
+        category_id="storage",
+        symbol="generic",
+        ports=(PortDisplaySpec("port_a", "left"),),
+        order=90,
+    )
+
+    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")
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        name: str,
+        medium: IdealGasMedium,
+        parameters: Mapping[str, float],
+    ) -> ExampleVolume:
+        return cls(
+            name=name,
+            medium=medium,
+            volume=parameters["volume"],
+            p0=parameters["p0"],
+            T0=parameters["T0"],
+        )
+
+    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,
+            ),
+        )
+```
+
+模型文件不再直接修改全局注册表。完成模型类后，只把类路径加入所属库
+`library.py` 的 `models` 清单：
+
+```python
+models=(
+    # ...已有模型
+    "app.simulation.components.experimental.storage.example_volume:ExampleVolume",
+)
+```
+
+后端会受控导入清单中的类，校验版本、分类、端口、参数、单位、显示信息和默认实例，
+再自动建立注册表。校验通过后，`GET /api/components/catalog` 会输出该元件，
+前端刷新时即可加载。
+当前 `experimental` 仅用于规范验证；正式模型应先建立新的库声明，再把
+`library_id` 指向正式库。
+
+完成仿真后，每个已声明结果都会得到一条结构化元数据。前端应按字段筛选，不能再拆解 `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. `MODEL_VERSION` 和 `DISPLAY` 是否完整，显示端口是否与物理端口完全一致。
+8. 是否实现统一的 `create()`，并能用默认参数创建模型。
+9. 模型类路径是否只加入所属库的 `library.py` 清单。
+10. 是否补充参数边界、端口契约、目录输出、结果元数据和最小仿真的自动测试。
+
+组件库、分类和自动发现的完整规则参见
+[`组件库分类、发现与读取规范 v1`](../../../docs/standard/component-library-spec-v1.md)。
@@ -1,35 +1,121 @@
-"""Component parameters, ports and output definitions; numerical equations execute in C."""
 from __future__ import annotations
+
 from collections.abc import Mapping
+from math import sqrt
+
 from app.simulation.core.base import AlgebraicComponent
 from app.simulation.core.catalog import ComponentDisplaySpec, PortDisplaySpec
+from app.simulation.core.equations import EquationResidual
 from app.simulation.core.metadata import ParameterDefinition
 from app.simulation.core.medium import IdealGasMedium
 from app.simulation.core.ports import PortDefinition
-from app.simulation.core.port_computation import FLOW_SUPPLY
+

 class Orifice(AlgebraicComponent):
    """Python port of ModelicaModels.Myorifice."""
-    MODEL_TYPE = 'orifice'
-    MODEL_VERSION = '1.0.0'
-    PORTS = (PortDefinition.pneumatic('port_a', nominal_role='inlet', computation=FLOW_SUPPLY), PortDefinition.pneumatic('port_b', nominal_role='outlet', computation=FLOW_SUPPLY))
-    PARAMETERS = (ParameterDefinition('K', 1e-05, 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 = ()
-    DISPLAY = ComponentDisplaySpec(label='孔板/阀门', library_id='experimental', category_id='flow', symbol='orifice', ports=(PortDisplaySpec('port_a', 'left', order=10), PortDisplaySpec('port_b', 'right', order=20)), order=40)

-    def __init__(self, name: str, opening: float=1.0, K: float=1e-05) -> None:
+    MODEL_TYPE = "orifice"
+    MODEL_VERSION = "1.0.0"
+    PRESSURE_FLOW_DEPENDS_ON_STREAM = False
+    PRESSURE_FLOW_EXACT_SUM_TO_ZERO_EQUATION_SUFFIXES = frozenset(
+        ("mass_flow_balance",)
+    )
+    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 = ()
+    DISPLAY = ComponentDisplaySpec(
+        label="孔板/阀门",
+        library_id="experimental",
+        category_id="flow",
+        symbol="orifice",
+        ports=(
+            PortDisplaySpec("port_a", "left", order=10),
+            PortDisplaySpec("port_b", "right", order=20),
+        ),
+        order=40,
+    )
+
+    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.set_parameter_values({"K": K, "opening": opening})
        self.opening = opening
        self.K = K
-        self.port_a = self.register_declared_port('port_a')
-        self.port_b = self.register_declared_port('port_b')
+        self.port_a = self.register_declared_port("port_a")
+        self.port_b = self.register_declared_port("port_b")

    @classmethod
-    def create(cls, *, name: str, medium: IdealGasMedium, parameters: Mapping[str, float]) -> Orifice:
-        return cls(name=name, opening=parameters['opening'], K=parameters['K'])
+    def create(
+        cls,
+        *,
+        name: str,
+        medium: IdealGasMedium,
+        parameters: Mapping[str, float],
+    ) -> Orifice:
+        return cls(
+            name=name,
+            opening=parameters["opening"],
+            K=parameters["K"],
+        )

    @property
    def K_eff(self) -> float:
        return self.K * max(self.opening, 0.001)
-    EQUATIONS = ({'id': '__MODEL__:mass_flow_balance', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'sumToZero', 'variables': ['__MODEL__.port_a.m_flow', '__MODEL__.port_b.m_flow'], 'role': 'flow'}, {'id': '__MODEL__:pressure_flow_relation', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'constitutive', 'variables': ['__MODEL__.port_a.p', '__MODEL__.port_b.p', '__MODEL__.port_a.m_flow'], 'role': 'flow'})
+
+    def mass_flow(self, p_a: float, p_b: float) -> float:
+        dp = p_a - p_b
+        if dp == 0.0:
+            return 0.0
+        return self.K_eff * sqrt(abs(dp)) * (1.0 if dp > 0.0 else -1.0)
+
+    def pressure_flow_equation_residuals(self) -> tuple[EquationResidual, ...]:
+        return (
+            EquationResidual(
+                id=f"{self.name}:mass_flow_balance",
+                owner="component",
+                owner_id=self.name,
+                relation="sumToZero",
+                variables=(
+                    f"{self.name}.port_a.m_flow",
+                    f"{self.name}.port_b.m_flow",
+                ),
+                role="flow",
+                value=self.port_a.m_flow + self.port_b.m_flow,
+            ),
+            EquationResidual(
+                id=f"{self.name}:pressure_flow_relation",
+                owner="component",
+                owner_id=self.name,
+                relation="constitutive",
+                variables=(
+                    f"{self.name}.port_a.p",
+                    f"{self.name}.port_b.p",
+                    f"{self.name}.port_a.m_flow",
+                ),
+                role="flow",
+                value=self.port_a.m_flow
+                - self.mass_flow(self.port_a.p, self.port_b.p),
+            ),
+        )
+
+    def update_stream_outflows(self, connected_h: Mapping[str, float]) -> None:
+        self.port_a.h_outflow = connected_h["port_b"]
+        self.port_b.h_outflow = connected_h["port_a"]
@@ -0,0 +1,10 @@
+"""Compatibility import for the TestModel-only dynamic pipe.
+
+The public ``pipe`` catalog model is ``ResistivePipe``. New code should import
+this legacy dynamic model from ``app.simulation.examples.testmodel.dynamic_pipe``.
+"""
+
+from app.simulation.examples.testmodel.dynamic_pipe import Pipe
+
+
+__all__ = ("Pipe",)
@@ -1,26 +1,106 @@
-"""Component parameters, ports and output definitions; numerical equations execute in C."""
 from __future__ import annotations
+
 from collections.abc import Mapping
 from math import pi
+
 from app.simulation.core.base import AlgebraicComponent
 from app.simulation.core.catalog import ComponentDisplaySpec, PortDisplaySpec
+from app.simulation.core.equations import EquationResidual
 from app.simulation.core.metadata import ParameterDefinition
 from app.simulation.core.medium import IdealGasMedium
 from app.simulation.core.ports import PortDefinition
-from app.simulation.core.port_computation import FLOW_SUPPLY
+

 class ResistivePipe(AlgebraicComponent):
    """Quasi-steady Darcy resistance used by topology-driven simulation."""
-    MODEL_TYPE = 'pipe'
-    MODEL_VERSION = '1.0.0'
-    PORTS = (PortDefinition.pneumatic('port_a', nominal_role='inlet', computation=FLOW_SUPPLY), PortDefinition.pneumatic('port_b', nominal_role='outlet', computation=FLOW_SUPPLY))
-    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', 100000.0, 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 = ()
-    DISPLAY = ComponentDisplaySpec(label='管段', library_id='experimental', category_id='flow', symbol='pipe', ports=(PortDisplaySpec('port_a', 'left', order=10), PortDisplaySpec('port_b', 'right', order=20)), order=30)

-    def __init__(self, name: str, medium: IdealGasMedium, L: float=5.0, D: float=0.02, lambda_darcy: float=0.02, p0: float=100000.0, T0: float=300.0) -> None:
+    MODEL_TYPE = "pipe"
+    MODEL_VERSION = "1.0.0"
+    PRESSURE_FLOW_DEPENDS_ON_STREAM = False
+    PRESSURE_FLOW_EXACT_SUM_TO_ZERO_EQUATION_SUFFIXES = frozenset(
+        ("mass_flow_balance",)
+    )
+    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 = ()
+    DISPLAY = ComponentDisplaySpec(
+        label="管段",
+        library_id="experimental",
+        category_id="flow",
+        symbol="pipe",
+        ports=(
+            PortDisplaySpec("port_a", "left", order=10),
+            PortDisplaySpec("port_b", "right", order=20),
+        ),
+        order=30,
+    )
+
+    def __init__(
+        self,
+        name: str,
+        medium: IdealGasMedium,
+        L: float = 5.0,
+        D: float = 0.02,
+        lambda_darcy: float = 0.02,
+        p0: float = 1e5,
+        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.set_parameter_values(
+            {
+                "length": L,
+                "diameter": D,
+                "lambda_darcy": lambda_darcy,
+                "p0": p0,
+                "T0": T0,
+            }
+        )
        self.medium = medium
        self.L = L
        self.D = D
@@ -28,10 +108,82 @@ class ResistivePipe(AlgebraicComponent):
        self.p0 = p0
        self.T0 = T0
        self.area = pi * D * D / 4.0
-        self.port_a = self.register_declared_port('port_a')
-        self.port_b = self.register_declared_port('port_b')
+        initial_h = medium.specific_enthalpy(T0)
+
+        self.port_a = self.register_declared_port("port_a")
+        self.port_a.p = p0
+        self.port_a.h_outflow = initial_h
+
+        self.port_b = self.register_declared_port("port_b")
+        self.port_b.p = p0
+        self.port_b.h_outflow = initial_h

    @classmethod
-    def create(cls, *, name: str, medium: IdealGasMedium, parameters: Mapping[str, float]) -> ResistivePipe:
-        return cls(name=name, medium=medium, L=parameters['length'], D=parameters['diameter'], lambda_darcy=parameters['lambda_darcy'], p0=parameters['p0'], T0=parameters['T0'])
-    EQUATIONS = ({'id': '__MODEL__:mass_flow_balance', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'sumToZero', 'variables': ['__MODEL__.port_a.m_flow', '__MODEL__.port_b.m_flow'], 'role': 'flow'}, {'id': '__MODEL__:darcy_pressure_loss', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'constitutive', 'variables': ['__MODEL__.port_a.p', '__MODEL__.port_b.p', '__MODEL__.port_a.m_flow'], 'role': 'effort'})
+    def create(
+        cls,
+        *,
+        name: str,
+        medium: IdealGasMedium,
+        parameters: Mapping[str, float],
+    ) -> ResistivePipe:
+        return cls(
+            name=name,
+            medium=medium,
+            L=parameters["length"],
+            D=parameters["diameter"],
+            lambda_darcy=parameters["lambda_darcy"],
+            p0=parameters["p0"],
+            T0=parameters["T0"],
+        )
+
+    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)
+        density = max(self.medium.density(average_pressure, self.T0), 1e-12)
+        resistance = self.lambda_darcy * (self.L / self.D)
+        return (
+            resistance
+            * m_flow_a
+            * abs(m_flow_a)
+            / (2.0 * density * self.area * self.area)
+        )
+
+    def pressure_flow_equation_residuals(self) -> tuple[EquationResidual, ...]:
+        return (
+            EquationResidual(
+                id=f"{self.name}:mass_flow_balance",
+                owner="component",
+                owner_id=self.name,
+                relation="sumToZero",
+                variables=(
+                    f"{self.name}.port_a.m_flow",
+                    f"{self.name}.port_b.m_flow",
+                ),
+                role="flow",
+                value=self.port_a.m_flow + self.port_b.m_flow,
+            ),
+            EquationResidual(
+                id=f"{self.name}:darcy_pressure_loss",
+                owner="component",
+                owner_id=self.name,
+                relation="constitutive",
+                variables=(
+                    f"{self.name}.port_a.p",
+                    f"{self.name}.port_b.p",
+                    f"{self.name}.port_a.m_flow",
+                ),
+                role="effort",
+                value=(
+                    self.port_a.p
+                    - self.port_b.p
+                    - self.pressure_drop(
+                        self.port_a.m_flow,
+                        self.port_a.p,
+                        self.port_b.p,
+                    )
+                ),
+            ),
+        )
+
+    def update_stream_outflows(self, connected_h: Mapping[str, float]) -> None:
+        self.port_a.h_outflow = connected_h["port_b"]
+        self.port_b.h_outflow = connected_h["port_a"]
@@ -1,28 +1,270 @@
-"""Component parameters, ports and output definitions; numerical equations execute in C."""
 from __future__ import annotations
+
 from collections.abc import Mapping
+
 from app.simulation.core.base import AlgebraicComponent
 from app.simulation.core.catalog import ComponentDisplaySpec, PortDisplaySpec
+from app.simulation.core.equations import EquationResidual
 from app.simulation.core.medium import IdealGasMedium
 from app.simulation.core.ports import PortDefinition

+
 class Tee(AlgebraicComponent):
    """Python port of ModelicaModels.Mytee."""
-    MODEL_TYPE = 'tee'
-    MODEL_VERSION = '1.0.0'
-    PORTS = (PortDefinition.pneumatic('port_in', nominal_role='bidirectional'), PortDefinition.pneumatic('port_out1', nominal_role='bidirectional'), PortDefinition.pneumatic('port_out2', nominal_role='bidirectional'))
+
+    MODEL_TYPE = "tee"
+    MODEL_VERSION = "1.0.0"
+    PRESSURE_FLOW_DEPENDS_ON_STREAM = False
+    PRESSURE_FLOW_EXACT_SUM_TO_ZERO_EQUATION_SUFFIXES = frozenset(
+        ("mass_flow_balance",)
+    )
+    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 = ()
-    DISPLAY = ComponentDisplaySpec(label='三通', library_id='experimental', category_id='junctions', symbol='tee', ports=(PortDisplaySpec('port_in', 'left', order=10), PortDisplaySpec('port_out1', 'right', order=20), PortDisplaySpec('port_out2', 'right', order=30)), order=50)
+    DISPLAY = ComponentDisplaySpec(
+        label="三通",
+        library_id="experimental",
+        category_id="junctions",
+        symbol="tee",
+        ports=(
+            PortDisplaySpec("port_in", "left", order=10),
+            PortDisplaySpec("port_out1", "right", order=20),
+            PortDisplaySpec("port_out2", "right", order=30),
+        ),
+        order=50,
+    )

    def __init__(self, name: str) -> None:
        super().__init__(name=name)
        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')
+        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")

    @classmethod
-    def create(cls, *, name: str, medium: IdealGasMedium, parameters: Mapping[str, float]) -> Tee:
+    def create(
+        cls,
+        *,
+        name: str,
+        medium: IdealGasMedium,
+        parameters: Mapping[str, float],
+    ) -> Tee:
        return cls(name=name)
-    EQUATIONS = ({'id': '__MODEL__:common_pressure_out1', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'equal', 'variables': ['__MODEL__.port_in.p', '__MODEL__.port_out1.p'], 'role': 'effort'}, {'id': '__MODEL__:common_pressure_out2', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'equal', 'variables': ['__MODEL__.port_in.p', '__MODEL__.port_out2.p'], 'role': 'effort'}, {'id': '__MODEL__:mass_flow_balance', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'sumToZero', 'variables': ['__MODEL__.port_in.m_flow', '__MODEL__.port_out1.m_flow', '__MODEL__.port_out2.m_flow'], 'role': 'flow'})
+
+    def pressure_flow_equation_residuals(self) -> tuple[EquationResidual, ...]:
+        return (
+            EquationResidual(
+                id=f"{self.name}:common_pressure_out1",
+                owner="component",
+                owner_id=self.name,
+                relation="equal",
+                variables=(f"{self.name}.port_in.p", f"{self.name}.port_out1.p"),
+                role="effort",
+                value=self.port_in.p - self.port_out1.p,
+            ),
+            EquationResidual(
+                id=f"{self.name}:common_pressure_out2",
+                owner="component",
+                owner_id=self.name,
+                relation="equal",
+                variables=(f"{self.name}.port_in.p", f"{self.name}.port_out2.p"),
+                role="effort",
+                value=self.port_in.p - self.port_out2.p,
+            ),
+            EquationResidual(
+                id=f"{self.name}:mass_flow_balance",
+                owner="component",
+                owner_id=self.name,
+                relation="sumToZero",
+                variables=(
+                    f"{self.name}.port_in.m_flow",
+                    f"{self.name}.port_out1.m_flow",
+                    f"{self.name}.port_out2.m_flow",
+                ),
+                role="flow",
+                value=(
+                    self.port_in.m_flow
+                    + self.port_out1.m_flow
+                    + self.port_out2.m_flow
+                ),
+            ),
+        )
+
+    def update_stream_outflows(self, connected_h: Mapping[str, float]) -> None:
+        incoming = [
+            (port.m_flow, connected_h[name])
+            for name, port in self.ports.items()
+            if port.m_flow > 1e-12
+        ]
+        total_flow = sum(m_flow for m_flow, _ in incoming)
+        if total_flow > 1e-12:
+            mixed_h = sum(
+                m_flow * enthalpy for m_flow, enthalpy in incoming
+            ) / total_flow
+        else:
+            values = list(connected_h.values())
+            mixed_h = sum(values) / len(values) if values else 0.0
+        for port in self.ports.values():
+            port.h_outflow = mixed_h
+
+    def mixed_inlet_enthalpy(
+        self,
+        branch1_m_flow: float,
+        branch1_h: float,
+        branch2_m_flow: float,
+        branch2_h: float,
+        fallback_h: float = 0.0,
+    ) -> float:
+        positive_1 = max(branch1_m_flow, 0.0)
+        positive_2 = max(branch2_m_flow, 0.0)
+        total = positive_1 + positive_2
+        if total <= 1e-9:
+            return fallback_h
+        return (positive_1 * branch1_h + positive_2 * branch2_h) / total
+
+    def inlet_stream_enthalpy(
+        self,
+        branch1_m_flow: float,
+        branch1_h: float,
+        branch2_m_flow: float,
+        branch2_h: float,
+        fallback_h: float,
+    ) -> float:
+        """Approximate `inStream(port_in.h_outflow)` for the current tee topology."""
+
+        return self.mixed_inlet_enthalpy(
+            branch1_m_flow,
+            branch1_h,
+            branch2_m_flow,
+            branch2_h,
+            fallback_h=fallback_h,
+        )
+
+    def branch_actual_stream_enthalpy(
+        self,
+        branch_m_flow: float,
+        branch_h: float,
+        inlet_h: float,
+    ) -> float:
+        """Approximate `actualStream(branch.h_outflow)` for a tee branch port."""
+
+        return inlet_h if branch_m_flow > 0.0 else branch_h
+
+    @staticmethod
+    def _solve_linear_2x2(
+        a11: float,
+        a12: float,
+        a21: float,
+        a22: float,
+        b1: float,
+        b2: float,
+    ) -> tuple[float, float] | None:
+        determinant = a11 * a22 - a12 * a21
+        if abs(determinant) <= 1e-12:
+            return None
+        x1 = (b1 * a22 - b2 * a12) / determinant
+        x2 = (a11 * b2 - a21 * b1) / determinant
+        return x1, x2
+
+    def solve_branch_outlet_flows_from_energy_balance(
+        self,
+        *,
+        ratio_branch1: float,
+        ratio_branch2: float,
+        inlet_h_branch1: float,
+        inlet_h_branch2: float,
+        branch1_h: float,
+        branch2_h: float,
+        inlet_h: float,
+        q_in_branch1: float,
+        q_in_branch2: float,
+        tolerance: float = 1e-12,
+    ) -> tuple[float, float]:
+        """Solve branch outlet flows for the current three-port downstream tee use-case."""
+
+        rhs_branch1 = q_in_branch1 * inlet_h_branch1
+        rhs_branch2 = q_in_branch2 * inlet_h_branch2
+
+        def solve_both_forward() -> tuple[float, float] | None:
+            return self._solve_linear_2x2(
+                (1.0 + ratio_branch1) * branch1_h,
+                ratio_branch1 * branch2_h,
+                ratio_branch2 * branch1_h,
+                (1.0 + ratio_branch2) * branch2_h,
+                rhs_branch1,
+                rhs_branch2,
+            )
+
+        def solve_one_reverse(
+            *,
+            branch1_reverse: bool,
+        ) -> tuple[float, float] | None:
+            if branch1_reverse:
+                return self._solve_linear_2x2(
+                    inlet_h * (1.0 + ratio_branch1),
+                    ratio_branch1 * inlet_h,
+                    ratio_branch2 * inlet_h,
+                    branch2_h + ratio_branch2 * inlet_h,
+                    rhs_branch1,
+                    rhs_branch2,
+                )
+
+            return self._solve_linear_2x2(
+                branch1_h + ratio_branch1 * inlet_h,
+                ratio_branch1 * inlet_h,
+                ratio_branch2 * inlet_h,
+                inlet_h * (1.0 + ratio_branch2),
+                rhs_branch1,
+                rhs_branch2,
+            )
+
+        def solve_both_reverse() -> tuple[float, float] | None:
+            return self._solve_linear_2x2(
+                inlet_h * (1.0 + ratio_branch1),
+                ratio_branch1 * inlet_h,
+                ratio_branch2 * inlet_h,
+                inlet_h * (1.0 + ratio_branch2),
+                rhs_branch1,
+                rhs_branch2,
+            )
+
+        candidate_solvers = (
+            (
+                solve_both_forward,
+                lambda q1, q2: q1 >= -tolerance and q2 >= -tolerance,
+            ),
+            (
+                lambda: solve_one_reverse(branch1_reverse=True),
+                lambda q1, q2: q1 < -tolerance and q2 >= -tolerance and q1 + q2 > tolerance,
+            ),
+            (
+                lambda: solve_one_reverse(branch1_reverse=True),
+                lambda q1, q2: q1 < -tolerance and q2 >= -tolerance and q1 + q2 <= tolerance,
+            ),
+            (
+                lambda: solve_one_reverse(branch1_reverse=False),
+                lambda q1, q2: q2 < -tolerance and q1 >= -tolerance and q1 + q2 > tolerance,
+            ),
+            (
+                lambda: solve_one_reverse(branch1_reverse=False),
+                lambda q1, q2: q2 < -tolerance and q1 >= -tolerance and q1 + q2 <= tolerance,
+            ),
+            (
+                solve_both_reverse,
+                lambda q1, q2: q1 < -tolerance and q2 < -tolerance,
+            ),
+        )
+
+        for solver, predicate in candidate_solvers:
+            candidate = solver()
+            if candidate is None:
+                continue
+            q_out_branch1, q_out_branch2 = candidate
+            if predicate(q_out_branch1, q_out_branch2):
+                return q_out_branch1, q_out_branch2
+
+        return solve_both_forward() or (0.0, 0.0)
@@ -1,30 +1,155 @@
-"""Component parameters, ports and output definitions; numerical equations execute in C."""
 from __future__ import annotations
+
 from collections.abc import Mapping
+
 from app.simulation.core.base import ThermodynamicVolumeComponent
 from app.simulation.core.catalog import ComponentDisplaySpec, PortDisplaySpec
-from app.simulation.core.metadata import ParameterDefinition, THERMODYNAMIC_VOLUME_RESULT_VARIABLES
-from app.simulation.core.medium import IdealGasMedium
+from app.simulation.core.equations import EquationResidual
+from app.simulation.core.metadata import (
+    ParameterDefinition,
+    THERMODYNAMIC_VOLUME_RESULT_VARIABLES,
+)
+from app.simulation.core.medium import IdealGasMedium, ThermodynamicProperties
 from app.simulation.core.ports import PortDefinition
-from app.simulation.core.port_computation import THERMODYNAMIC_SUPPLY
+from app.simulation.core.state import VolumeState
+

 class Cylinder(ThermodynamicVolumeComponent):
    """Python port of ModelicaModels.Mycylinder."""
-    MODEL_TYPE = 'cylinder'
-    MODEL_VERSION = '1.0.0'
-    PORTS = (PortDefinition.pneumatic('port_b', nominal_role='outlet', computation=THERMODYNAMIC_SUPPLY),)
-    PARAMETERS = (ParameterDefinition('volume', 0.01, label='容积', quantity='volume', unit='m3', minimum=0.0, minimum_exclusive=True), ParameterDefinition('p0', 35000000.0, 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
-    DISPLAY = ComponentDisplaySpec(label='气瓶', library_id='experimental', category_id='storage', symbol='cylinder', ports=(PortDisplaySpec('port_b', 'right'),), order=10)

-    def __init__(self, name: str, medium: IdealGasMedium, V: float=0.01, p0: float=35000000.0, T0: float=300.0) -> None:
+    MODEL_TYPE = "cylinder"
+    MODEL_VERSION = "1.0.0"
+    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
+    DISPLAY = ComponentDisplaySpec(
+        label="气瓶",
+        library_id="experimental",
+        category_id="storage",
+        symbol="cylinder",
+        ports=(PortDisplaySpec("port_b", "right"),),
+        order=10,
+    )
+
+    def __init__(
+        self,
+        name: str,
+        medium: IdealGasMedium,
+        V: float = 0.01,
+        p0: float = 35e6,
+        T0: float = 300.0,
+    ) -> None:
        super().__init__(name=name)
-        self.set_parameter_values({'volume': V, 'p0': p0, 'T0': T0})
+        self.set_parameter_values({"volume": V, "p0": p0, "T0": T0})
        self.medium = medium
        self.V = V
-        self.port_b = self.register_declared_port('port_b')
+        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_declared_port("port_b")

    @classmethod
-    def create(cls, *, name: str, medium: IdealGasMedium, parameters: Mapping[str, float]) -> Cylinder:
-        return cls(name=name, medium=medium, V=parameters['volume'], p0=parameters['p0'], T0=parameters['T0'])
-    EQUATIONS = ({'id': '__MODEL__:port_b_pressure_state', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'state', 'variables': ['__MODEL__.port_b.p', '__MODEL__.state'], 'role': 'effort'},)
+    def create(
+        cls,
+        *,
+        name: str,
+        medium: IdealGasMedium,
+        parameters: Mapping[str, float],
+    ) -> Cylinder:
+        return cls(
+            name=name,
+            medium=medium,
+            V=parameters["volume"],
+            p0=parameters["p0"],
+            T0=parameters["T0"],
+        )
+
+    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 properties(self) -> ThermodynamicProperties:
+        props = self.medium.properties_from_mU(self.state.m, self.state.U, self.V)
+        self.port_b.p = props.p
+        self.port_b.h_outflow = props.h
+        return props
+
+    def refresh_thermodynamic_ports(self) -> ThermodynamicProperties:
+        return self.properties()
+
+    def state_derivative_from_ports(
+        self,
+        connected_h: Mapping[str, float],
+    ) -> list[float]:
+        properties = self.properties()
+        derivative = self.derivatives_from_connection(
+            connected_h=connected_h["port_b"],
+            port_m_flow=self.port_b.m_flow,
+            internal_h=properties.h,
+        )
+        return derivative.as_vector()
+
+    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_b_pressure_state",
+                owner="component",
+                owner_id=self.name,
+                relation="state",
+                variables=(f"{self.name}.port_b.p", f"{self.name}.state"),
+                role="effort",
+                value=self.port_b.p - pressure,
+            ),
+        )
+
+    def derivatives_from_connection(
+        self,
+        *,
+        connected_h: float,
+        port_m_flow: float,
+        internal_h: float,
+    ) -> VolumeState:
+        inlet_h = self.connection_inlet_enthalpy(
+            port_m_flow=port_m_flow,
+            connected_h=connected_h,
+            internal_h=internal_h,
+        )
+        return self.derivatives(inlet_h, port_m_flow)
+
+    def derivatives(self, inlet_h: float, m_flow: float) -> VolumeState:
+        return VolumeState(m=m_flow, U=m_flow * inlet_h)
@@ -1,30 +1,155 @@
-"""Component parameters, ports and output definitions; numerical equations execute in C."""
 from __future__ import annotations
+
 from collections.abc import Mapping
+
 from app.simulation.core.base import ThermodynamicVolumeComponent
 from app.simulation.core.catalog import ComponentDisplaySpec, PortDisplaySpec
-from app.simulation.core.metadata import ParameterDefinition, THERMODYNAMIC_VOLUME_RESULT_VARIABLES
-from app.simulation.core.medium import IdealGasMedium
+from app.simulation.core.equations import EquationResidual
+from app.simulation.core.metadata import (
+    ParameterDefinition,
+    THERMODYNAMIC_VOLUME_RESULT_VARIABLES,
+)
+from app.simulation.core.medium import IdealGasMedium, ThermodynamicProperties
 from app.simulation.core.ports import PortDefinition
-from app.simulation.core.port_computation import THERMODYNAMIC_SUPPLY
+from app.simulation.core.state import VolumeState
+

 class Tank(ThermodynamicVolumeComponent):
    """Python port of ModelicaModels.Mytank."""
-    MODEL_TYPE = 'tank'
-    MODEL_VERSION = '1.0.0'
-    PORTS = (PortDefinition.pneumatic('port_a', nominal_role='inlet', computation=THERMODYNAMIC_SUPPLY),)
-    PARAMETERS = (ParameterDefinition('volume', 0.1, label='容积', quantity='volume', unit='m3', minimum=0.0, minimum_exclusive=True), ParameterDefinition('p0', 100000.0, 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
-    DISPLAY = ComponentDisplaySpec(label='贮箱', library_id='experimental', category_id='storage', symbol='tank', ports=(PortDisplaySpec('port_a', 'left'),), order=20)

-    def __init__(self, name: str, medium: IdealGasMedium, V: float=0.1, p0: float=100000.0, T0: float=300.0) -> None:
+    MODEL_TYPE = "tank"
+    MODEL_VERSION = "1.0.0"
+    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
+    DISPLAY = ComponentDisplaySpec(
+        label="贮箱",
+        library_id="experimental",
+        category_id="storage",
+        symbol="tank",
+        ports=(PortDisplaySpec("port_a", "left"),),
+        order=20,
+    )
+
+    def __init__(
+        self,
+        name: str,
+        medium: IdealGasMedium,
+        V: float = 0.1,
+        p0: float = 1e5,
+        T0: float = 300.0,
+    ) -> None:
        super().__init__(name=name)
-        self.set_parameter_values({'volume': V, 'p0': p0, 'T0': T0})
+        self.set_parameter_values({"volume": V, "p0": p0, "T0": T0})
        self.medium = medium
        self.V = V
-        self.port_a = self.register_declared_port('port_a')
+        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_declared_port("port_a")

    @classmethod
-    def create(cls, *, name: str, medium: IdealGasMedium, parameters: Mapping[str, float]) -> Tank:
-        return cls(name=name, medium=medium, V=parameters['volume'], p0=parameters['p0'], T0=parameters['T0'])
-    EQUATIONS = ({'id': '__MODEL__:port_a_pressure_state', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'state', 'variables': ['__MODEL__.port_a.p', '__MODEL__.state'], 'role': 'effort'},)
+    def create(
+        cls,
+        *,
+        name: str,
+        medium: IdealGasMedium,
+        parameters: Mapping[str, float],
+    ) -> Tank:
+        return cls(
+            name=name,
+            medium=medium,
+            V=parameters["volume"],
+            p0=parameters["p0"],
+            T0=parameters["T0"],
+        )
+
+    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 properties(self) -> ThermodynamicProperties:
+        props = self.medium.properties_from_mU(self.state.m, self.state.U, self.V)
+        self.port_a.p = props.p
+        self.port_a.h_outflow = props.h
+        return props
+
+    def refresh_thermodynamic_ports(self) -> ThermodynamicProperties:
+        return self.properties()
+
+    def state_derivative_from_ports(
+        self,
+        connected_h: Mapping[str, float],
+    ) -> list[float]:
+        properties = self.properties()
+        derivative = self.derivatives_from_connection(
+            connected_h=connected_h["port_a"],
+            port_m_flow=self.port_a.m_flow,
+            internal_h=properties.h,
+        )
+        return derivative.as_vector()
+
+    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,
+            ),
+        )
+
+    def derivatives_from_connection(
+        self,
+        *,
+        connected_h: float,
+        port_m_flow: float,
+        internal_h: float,
+    ) -> VolumeState:
+        inlet_h = self.connection_inlet_enthalpy(
+            port_m_flow=port_m_flow,
+            connected_h=connected_h,
+            internal_h=internal_h,
+        )
+        return self.derivatives(inlet_h, port_m_flow)
+
+    def derivatives(self, inlet_h: float, m_flow: float) -> VolumeState:
+        return VolumeState(m=m_flow, U=m_flow * inlet_h)
@@ -1,148 +0,0 @@
-"""Simulation options and progress data; no numerical solver implementation."""
-from __future__ import annotations
-from dataclasses import dataclass
-from typing import Sequence
-
-@dataclass(frozen=True)
-class SolverActivitySnapshot:
-    """Low-cost, additive view of work inside an integration task.
-
-    ``accepted_time`` deliberately changes only after an accepted solver step.
-    Trial evaluations may continue to advance ``activity_sequence`` and
-    ``current_trial_time`` while that public progress value stays fixed.
-    """
-
-    activity_sequence: int
-    activity_kind: str
-    current_trial_time: float | None
-    rhs_call_count: int
-    accepted_step_sequence: int
-    accepted_time: float | None
-    solver_step_sequence: int
-    jacobian_evaluation_count: int
-    thermofluid_closure_count: int
-
-    def as_dict(self) -> dict[str, object]:
-        return {
-            "activitySequence": self.activity_sequence,
-            "activityKind": self.activity_kind,
-            "currentTrialTime": self.current_trial_time,
-            "rhsCallCount": self.rhs_call_count,
-            "acceptedStepSequence": self.accepted_step_sequence,
-            "acceptedTime": self.accepted_time,
-            "solverStepSequence": self.solver_step_sequence,
-            "jacobianEvaluationCount": self.jacobian_evaluation_count,
-            "thermofluidClosureCount": self.thermofluid_closure_count,
-        }
-
-class SolverActivityTracker:
-    """Single-writer activity telemetry for a solver worker.
-
-    The solver thread is the only writer and the stream thread only snapshots
-    scalar attributes. The sequence is published last, so a reader never
-    treats partially published fields as a newer completed activity update.
-    The tracker receives aggregate counters from the independent C worker.
-    """
-
-    __slots__ = (
-        "_accepted_step_sequence",
-        "_accepted_time",
-        "_activity_kind",
-        "_activity_sequence",
-        "_current_trial_time",
-        "_jacobian_evaluation_count",
-        "_rhs_call_count",
-        "_solver_step_sequence",
-        "_thermofluid_closure_count",
-    )
-
-    def __init__(self) -> None:
-        self._activity_sequence = 0
-        self._activity_kind = "idle"
-        self._current_trial_time: float | None = None
-        self._rhs_call_count = 0
-        self._accepted_step_sequence = 0
-        self._accepted_time: float | None = None
-        self._solver_step_sequence = 0
-        self._jacobian_evaluation_count = 0
-        self._thermofluid_closure_count = 0
-
-    def _publish(self, kind: str, time: float | None = None) -> None:
-        self._activity_kind = kind
-        if time is not None:
-            self._current_trial_time = float(time)
-        self._activity_sequence += 1
-
-    def start_integration(self, time: float) -> None:
-        self._accepted_time = float(time)
-        self._publish("solver_initialization", time)
-
-    def record_phase(self, kind: str, time: float | None = None) -> None:
-        self._publish(kind, time)
-
-    def record_solver_step(self, time: float) -> None:
-        self._solver_step_sequence += 1
-        self._publish("solver_step", time)
-
-    def record_rhs(self, time: float) -> None:
-        self._rhs_call_count += 1
-        self._publish("rhs", time)
-
-    def record_native_progress(self, time: float, rhs_count: int, accepted_count: int) -> None:
-        """Publish aggregate counters from an isolated C worker without per-RHS callbacks."""
-        self._rhs_call_count = max(self._rhs_call_count, rhs_count)
-        self._accepted_step_sequence = max(self._accepted_step_sequence, accepted_count)
-        self._accepted_time = max(self._accepted_time or time, time)
-        self._publish("native_solver", time)
-
-    def record_jacobian(self, time: float) -> None:
-        self._jacobian_evaluation_count += 1
-        self._publish("jacobian", time)
-
-    def record_thermofluid_closure(self, time: float) -> None:
-        self._thermofluid_closure_count += 1
-        self._publish("thermofluid_closure", time)
-
-    def record_accepted_step(self, time: float) -> None:
-        accepted_time = float(time)
-        if (
-            self._accepted_time is not None
-            and accepted_time <= self._accepted_time
-        ):
-            return
-        self._accepted_step_sequence += 1
-        self._accepted_time = accepted_time
-        self._publish("accepted_step", accepted_time)
-
-    def snapshot(self) -> SolverActivitySnapshot:
-        # ``activity_sequence`` is read last because writers publish it last.
-        activity_kind = self._activity_kind
-        current_trial_time = self._current_trial_time
-        rhs_call_count = self._rhs_call_count
-        accepted_step_sequence = self._accepted_step_sequence
-        accepted_time = self._accepted_time
-        solver_step_sequence = self._solver_step_sequence
-        jacobian_evaluation_count = self._jacobian_evaluation_count
-        thermofluid_closure_count = self._thermofluid_closure_count
-        activity_sequence = self._activity_sequence
-        return SolverActivitySnapshot(
-            activity_sequence=activity_sequence,
-            activity_kind=activity_kind,
-            current_trial_time=current_trial_time,
-            rhs_call_count=rhs_call_count,
-            accepted_step_sequence=accepted_step_sequence,
-            accepted_time=accepted_time,
-            solver_step_sequence=solver_step_sequence,
-            jacobian_evaluation_count=jacobian_evaluation_count,
-            thermofluid_closure_count=thermofluid_closure_count,
-        )
-
-@dataclass(frozen=True)
-class SolveIVPConfig:
-    t_start: float = 0.0
-    t_stop: float = 20.0
-    method: str = "BDF"
-    rtol: float = 1e-6
-    atol: float | Sequence[float] = 1e-8
-    max_step: float = 1e-3
-    first_step: float | None = None
@@ -1,17 +1,40 @@
 from __future__ import annotations
-from abc import ABC
-from collections.abc import Mapping
-from typing import TYPE_CHECKING, ClassVar
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Mapping
+from typing import TYPE_CHECKING, Any, ClassVar
+
 from app.simulation.core.catalog import ComponentDisplaySpec
-from app.simulation.core.equations import EquationDefinition
-from app.simulation.core.metadata import ParameterDefinition, ResultVariableDefinition, ResultVariableMetadata, THERMODYNAMIC_VOLUME_RESULT_VARIABLES
+from app.simulation.core.equations import EquationResidual
+from app.simulation.core.metadata import (
+    ParameterDefinition,
+    ResultVariableDefinition,
+    ResultVariableMetadata,
+    THERMODYNAMIC_VOLUME_RESULT_VARIABLES,
+)
 from app.simulation.core.ports import PortDefinition, PortState
+
 if TYPE_CHECKING:
    from app.simulation.core.medium import GasMedium

+
 class Component(ABC):
    MODEL_TYPE: ClassVar[str | None] = None
    MODEL_VERSION: ClassVar[str | None] = None
+    # ``True`` means that pressure/flow residuals read values written by
+    # ``update_stream_outflows`` or ``update_flow_temperature_references``.
+    # ``False`` is an explicit promise that those residuals are independent of
+    # stream propagation.  ``None`` keeps custom components conservative: when
+    # they override either stream hook, the closure planner retains the legacy
+    # full-network thermofluid fixed point.
+    PRESSURE_FLOW_DEPENDS_ON_STREAM: ClassVar[bool | None] = None
+    # Exact residual suffixes whose declared variables are summed, in order,
+    # to form a ``sumToZero`` flow equation.  The causal solver deliberately
+    # reads this capability from the concrete class ``__dict__``: subclasses
+    # must repeat the promise after changing any equation semantics.
+    PRESSURE_FLOW_EXACT_SUM_TO_ZERO_EQUATION_SUFFIXES: ClassVar[
+        frozenset[str]
+    ] = frozenset()
    PORTS: ClassVar[tuple[PortDefinition, ...]] = ()
    PARAMETERS: ClassVar[tuple[ParameterDefinition, ...]] = ()
    RESULT_VARIABLES: ClassVar[tuple[ResultVariableDefinition, ...]] = ()
@@ -29,53 +52,80 @@ class Component(ABC):

    @property
    def port_definitions(self) -> tuple[PortDefinition, ...]:
-        return tuple((port.definition for port in self._ports.values() if port.definition is not None))
+        return tuple(
+            port.definition
+            for port in self._ports.values()
+            if port.definition is not None
+        )

    @classmethod
-    def active_port_definitions_for_parameters(cls, parameters: Mapping[str, float]) -> tuple[PortDefinition, ...]:
+    def active_port_definitions_for_parameters(
+        cls,
+        parameters: Mapping[str, float],
+    ) -> tuple[PortDefinition, ...]:
        """Declared ports enabled by one normalized parameter set."""
+
        return cls.PORTS

    @property
    def active_port_definitions(self) -> tuple[PortDefinition, ...]:
        """Instance ports that participate in execution and result reporting."""
+
        return self.port_definitions

    @property
    def required_connection_ports(self) -> tuple[str, ...]:
        """Physical ports that must have an external connection before simulation."""
-        return tuple((definition.name for definition in self.active_port_definitions if definition.kind == 'physical'))
+
+        return tuple(
+            definition.name
+            for definition in self.active_port_definitions
+            if definition.kind == "physical"
+        )

    def register_port(self, port: PortState) -> PortState:
        definition = port.definition
        if definition is None:
-            raise ValueError(f'Component {self.name} cannot register an undefined port.')
+            raise ValueError(f"Component {self.name} cannot register an undefined port.")
        if definition.name in self._ports:
-            raise ValueError(f'Duplicate port {self.name}.{definition.name}.')
+            raise ValueError(f"Duplicate port {self.name}.{definition.name}.")
        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))
+            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
+            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) + '.')
+            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) + '.')
+            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}.")
+                raise ValueError(
+                    f"Parameter '{name}' on component '{self.name}' {message}."
+                )
            resolved[name] = value
        self._parameter_values = resolved

@@ -87,40 +137,229 @@ class Component(ABC):
        try:
            return self._ports[name]
        except KeyError as exc:
-            raise ValueError(f'Component {self.name} has no port named {name}.') from 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.active_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]
+        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.active_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))
+                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]
+        return [
+            definition.as_interface_dict(
+                value=self._parameter_values.get(definition.name)
+            )
+            for definition in self.PARAMETERS
+        ]

    @classmethod
-    def create(cls, *, name: str, medium: GasMedium, parameters: Mapping[str, float]) -> Component:
+    def create(
+        cls,
+        *,
+        name: str,
+        medium: GasMedium,
+        parameters: Mapping[str, float],
+    ) -> Component:
        """Create a catalog model from normalized SI parameters."""
-        raise NotImplementedError(f'Component model {cls.__name__} must implement create().')
-    EQUATIONS = ()

-    def equation_definitions(self):
+        raise NotImplementedError(
+            f"Component model {cls.__name__} must implement create()."
+        )
+
+    def pressure_flow_equation_residuals(self) -> tuple[EquationResidual, ...]:
+        """Return algebraic residuals after the network assigns port states."""
+
+        return ()
+
+    def pressure_flow_equation_values(self) -> tuple[float, ...]:
+        """Return live residual values in the declared equation order.
+
+        Components with frequently evaluated equations can override this
+        method to avoid rebuilding immutable equation metadata during closure.
+        The default keeps third-party components compatible with the public
+        residual API.
+        """
+
+        return tuple(
+            float(equation.value)
+            for equation in self.pressure_flow_equation_residuals()
+        )
+
+    def pressure_flow_equation_value_readers(
+        self,
+    ) -> Mapping[str, Callable[[], float]]:
+        """Return explicitly separable scalar residual readers.
+
+        The solver consumes this optional capability only when the concrete
+        component class declares the method itself.  Subclasses therefore
+        cannot accidentally inherit an equation-purity promise.
+        """
+
+        return {}
+
+    def update_stream_outflows(self, connected_h: Mapping[str, float]) -> None:
+        """Update connector outflow properties from current flow directions."""
+
+        return None
+
+    def update_flow_temperature_references(
+        self,
+        connected_h: Mapping[str, float],
+    ) -> None:
+        """Update enthalpy references used only by pressure-flow laws.
+
+        Most components use the normal stream enthalpy for both energy
+        transport and upstream-property evaluation. AMESim node submodels can
+        expose a distinct temperature reference, so the default is a no-op.
+        """
+
+        return None
+
+    def pneumatic_volume_outputs(self) -> Mapping[str, tuple[float, float]]:
+        """Return directed ``volume``/``volume_flow`` values by pneumatic port.
+
+        Most pneumatic components contribute no external chamber volume. Moving
+        boundaries such as PNRP17 override this hook; the network resolver then
+        propagates the pair to the component connected at the same physical port.
+        """
+
+        return {}

-        def bind(value):
-            if isinstance(value, str):
-                return value.replace('__MODEL__', self.name)
-            return tuple((bind(v) for v in value))
-        return tuple((EquationDefinition(id=bind(e['id']), owner=e['owner'], owner_id=self.name, relation=e['relation'], variables=bind(e['variables']), role=e['role']) for e in self.EQUATIONS))

 class DynamicComponent(Component):
    state_size = 2

+    @staticmethod
+    def actual_stream_enthalpy(
+        port_m_flow: float,
+        connected_h: float,
+        internal_h: float,
+    ) -> float:
+        """Approximate `actualStream(port.h_outflow)` for a mixed control volume port."""
+
+        return connected_h if port_m_flow > 0.0 else internal_h
+
+    def connection_inlet_enthalpy(
+        self,
+        port_m_flow: float,
+        connected_h: float,
+        internal_h: float,
+    ) -> float:
+        """Resolve the enthalpy convected into this control volume through one port."""
+
+        return self.actual_stream_enthalpy(
+            port_m_flow=port_m_flow,
+            connected_h=connected_h,
+            internal_h=internal_h,
+        )
+
+    @abstractmethod
+    def get_state_vector(self) -> list[float]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def set_state_vector(self, values: list[float]) -> None:
+        raise NotImplementedError
+
+    def refresh_thermodynamic_ports(self) -> Any:
+        raise NotImplementedError
+
+    def state_derivative_from_ports(
+        self,
+        connected_h: Mapping[str, float],
+    ) -> list[float]:
+        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."""
@@ -11,14 +11,15 @@ EquationRelation = Literal["equal", "sumToZero", "constitutive", "state"]


@dataclass(frozen=True, slots=True)
-class EquationDefinition:
-    """One declarative equation in the compiled model interface."""
+class EquationResidual:
+    """One executable scalar equation in the pressure-flow subsystem."""

    id: str
    owner: EquationOwner
    owner_id: str
    relation: EquationRelation
    variables: tuple[str, ...]
+    value: float
    role: VariableRole | None = None

    def as_definition_dict(self) -> dict[str, object]:
@@ -32,4 +33,4 @@ class EquationDefinition:
        }

    def as_interface_dict(self) -> dict[str, object]:
-        return self.as_definition_dict()
+        return {**self.as_definition_dict(), "residual": self.value}
@@ -1,16 +1,378 @@
-"""Compile-time gas property constants. No Python property evaluator."""
 from __future__ import annotations
+
 from dataclasses import dataclass
+from math import isfinite
+from typing import Protocol, Sequence
+
+from app.simulation.core.errors import RecoverableTrialStateError
+from app.simulation.performance import profile_property
+
+
+@dataclass(frozen=True)
+class ThermodynamicProperties:
+    p: float
+    T: float
+    rho: float
+    u: float
+    h: float
+
+
+@dataclass(frozen=True)
+class ThermodynamicPropertyTangents:
+    """Directional derivatives of a recovered thermodynamic state."""
+
+    p: tuple[float, ...]
+    T: tuple[float, ...]
+    rho: tuple[float, ...]
+    u: tuple[float, ...]
+    h: tuple[float, ...]
+
+    @property
+    def width(self) -> int:
+        return len(self.p)
+
+    @classmethod
+    def zeros(cls, width: int) -> "ThermodynamicPropertyTangents":
+        values = (0.0,) * width
+        return cls(p=values, T=values, rho=values, u=values, h=values)
+
+
+@dataclass(frozen=True)
+class ThermodynamicPropertiesLinearization:
+    """Primal properties and a validity-checked directional linearization."""
+
+    properties: ThermodynamicProperties
+    tangents: ThermodynamicPropertyTangents
+    valid: bool = True
+    reason: str | None = None
+
+
+class GasMedium(Protocol):
+    """Thermodynamic contract required by pneumatic components.
+
+    ``IdealGasMedium`` is the default implementation.  Keeping the component
+    boundary structural allows a later helium/Peng-Robinson implementation to
+    be registered without changing every AMESim component constructor.
+    """
+
+    name: str
+    R_gas: float
+    cp_ref: float
+    T_ref: float
+
+    @property
+    def cv(self) -> float: ...
+
+    @property
+    def gamma(self) -> float: ...
+
+    def cp_at_temperature(self, T: float) -> float: ...
+
+    def cv_at_temperature(self, T: float) -> float: ...
+
+    def density(self, p: float, T: float) -> float: ...
+
+    def isentropic_density_pressure_factor(
+        self,
+        p: float,
+        T: float,
+        downstream_pressure: float | None = None,
+    ) -> float: ...
+
+    def dynamic_viscosity(self, T: float) -> float: ...
+
+    def diagnostic_dynamic_viscosity(self, T: float) -> float: ...
+
+    def specific_internal_energy(self, T: float) -> float: ...
+
+    def specific_internal_energy_at_pressure(self, p: float, T: float) -> float: ...
+
+    def specific_enthalpy(self, T: float) -> float: ...
+
+    def specific_enthalpy_at_pressure(self, p: float, T: float) -> float: ...
+
+    def temperature_from_internal_energy(self, u: float) -> float: ...
+
+    def temperature_from_enthalpy(self, h: float) -> float: ...
+
+    def temperature_from_pressure_enthalpy(self, p: float, h: float) -> float: ...
+
+    def temperature_from_mass_internal_energy(self, m: float, U: float) -> float: ...
+
+    def pressure(self, m: float, T: float, V: float) -> float: ...
+
+    def properties_from_mU(
+        self,
+        m: float,
+        U: float,
+        V: float,
+    ) -> ThermodynamicProperties: ...
+
+    def linearize_properties_from_mU(
+        self,
+        m: float,
+        U: float,
+        V: float,
+        dm: Sequence[float],
+        dU: Sequence[float],
+        dV: Sequence[float],
+        *,
+        properties: ThermodynamicProperties | None = None,
+    ) -> ThermodynamicPropertiesLinearization: ...
+

@dataclass(frozen=True)
 class IdealGasMedium:
-    name: str = 'SimpleAirApprox'
+    """Temperature-dependent ideal-gas air approximation.
+
+    This is still not a strict clone of `Modelica.Media.Air.SimpleAir`.
+    The small linear `cp(T)` term is kept configurable for calibration, but the
+    current default is calibrated against the committed Testmodel baseline and
+    therefore falls back to the constant-heat-capacity limit.
+    """
+
+    name: str = "SimpleAirApprox"
    R_gas: float = 287.0
    cp_ref: float = 1005.0
    T_ref: float = 300.0
    cp_slope: float = 0.0
-    viscosity_ref: float = 1.82e-05
+    viscosity_ref: float = 1.82e-5
    viscosity_T_ref: float = 293.15
    sutherland_constant: float = 110.4

-GasMedium = IdealGasMedium
+    @property
+    def cv(self) -> float:
+        return self.cv_at_temperature(self.T_ref)
+
+    @property
+    def gamma(self) -> float:
+        return self.cp_at_temperature(self.T_ref) / self.cv
+
+    def cp_at_temperature(self, T: float) -> float:
+        return self.cp_ref + self.cp_slope * (T - self.T_ref)
+
+    def cv_at_temperature(self, T: float) -> float:
+        return self.cp_at_temperature(T) - self.R_gas
+
+    @profile_property("density")
+    def density(self, p: float, T: float) -> float:
+        return p / (self.R_gas * T)
+
+    @profile_property("isentropic_density_pressure_factor")
+    def isentropic_density_pressure_factor(
+        self,
+        p: float,
+        T: float,
+        downstream_pressure: float | None = None,
+    ) -> float:
+        del p
+        del downstream_pressure
+        cp = self.cp_at_temperature(T)
+        cv = self.cv_at_temperature(T)
+        return cv / cp
+
+    @profile_property("dynamic_viscosity")
+    def dynamic_viscosity(self, T: float) -> float:
+        """Return dynamic viscosity using the default air Sutherland law."""
+
+        if T <= 0.0:
+            raise ValueError("Temperature must be positive.")
+        return (
+            self.viscosity_ref
+            * (T / self.viscosity_T_ref) ** 1.5
+            * (self.viscosity_T_ref + self.sutherland_constant)
+            / (T + self.sutherland_constant)
+        )
+
+    def diagnostic_dynamic_viscosity(self, T: float) -> float:
+        """Return the viscosity convention used by derived diagnostics.
+
+        Most media use the same transport property for dynamics and reported
+        diagnostics. Reference-library media may override this without
+        changing a calibrated constitutive flow relation.
+        """
+
+        return self.dynamic_viscosity(T)
+
+    @profile_property("specific_internal_energy")
+    def specific_internal_energy(self, T: float) -> float:
+        delta_T = T - self.T_ref
+        return (
+            self.cv * self.T_ref
+            + self.cv * delta_T
+            + 0.5 * self.cp_slope * delta_T * delta_T
+        )
+
+    @profile_property("specific_internal_energy_at_pressure")
+    def specific_internal_energy_at_pressure(self, p: float, T: float) -> float:
+        del p
+        return self.specific_internal_energy(T)
+
+    @profile_property("specific_enthalpy")
+    def specific_enthalpy(self, T: float) -> float:
+        delta_T = T - self.T_ref
+        return (
+            self.cp_ref * self.T_ref
+            + self.cp_ref * delta_T
+            + 0.5 * self.cp_slope * delta_T * delta_T
+        )
+
+    @profile_property("specific_enthalpy_at_pressure")
+    def specific_enthalpy_at_pressure(self, p: float, T: float) -> float:
+        del p
+        return self.specific_enthalpy(T)
+
+    def temperature_from_internal_energy(self, u: float) -> float:
+        reference_internal_energy = self.cv * self.T_ref
+        delta_u = u - reference_internal_energy
+
+        if abs(self.cp_slope) <= 1e-15:
+            return self.T_ref + delta_u / self.cv
+
+        a = 0.5 * self.cp_slope
+        b = self.cv
+        c = -delta_u
+        discriminant = max(b * b - 4.0 * a * c, 0.0)
+        positive_root = (-b + discriminant**0.5) / (2.0 * a)
+        negative_root = (-b - discriminant**0.5) / (2.0 * a)
+        delta_T = positive_root if abs(positive_root) <= abs(negative_root) else negative_root
+        return self.T_ref + delta_T
+
+    def temperature_from_enthalpy(self, h: float) -> float:
+        reference_enthalpy = self.cp_ref * self.T_ref
+        delta_h = h - reference_enthalpy
+
+        if abs(self.cp_slope) <= 1e-15:
+            return self.T_ref + delta_h / self.cp_ref
+
+        a = 0.5 * self.cp_slope
+        b = self.cp_ref
+        c = -delta_h
+        discriminant = max(b * b - 4.0 * a * c, 0.0)
+        positive_root = (-b + discriminant**0.5) / (2.0 * a)
+        negative_root = (-b - discriminant**0.5) / (2.0 * a)
+        delta_T = positive_root if abs(positive_root) <= abs(negative_root) else negative_root
+        return self.T_ref + delta_T
+
+    @profile_property("temperature_from_pressure_enthalpy")
+    def temperature_from_pressure_enthalpy(self, p: float, h: float) -> float:
+        del p
+        return self.temperature_from_enthalpy(h)
+
+    def temperature_from_mass_internal_energy(self, m: float, U: float) -> float:
+        if m <= 0.0:
+            raise RecoverableTrialStateError(
+                "Mass must stay positive when recovering temperature."
+            )
+        return self.temperature_from_internal_energy(U / m)
+
+    def pressure(self, m: float, T: float, V: float) -> float:
+        if V <= 0.0:
+            raise ValueError("Volume must stay positive.")
+        return m * self.R_gas * T / V
+
+    @profile_property("properties_from_mU")
+    def properties_from_mU(self, m: float, U: float, V: float) -> ThermodynamicProperties:
+        T = self.temperature_from_mass_internal_energy(m, U)
+        p = self.pressure(m, T, V)
+        rho = m / V
+        u = U / m
+        h = self.specific_enthalpy(T)
+        return ThermodynamicProperties(p=p, T=T, rho=rho, u=u, h=h)
+
+    def linearize_properties_from_mU(
+        self,
+        m: float,
+        U: float,
+        V: float,
+        dm: Sequence[float],
+        dU: Sequence[float],
+        dV: Sequence[float],
+        *,
+        properties: ThermodynamicProperties | None = None,
+    ) -> ThermodynamicPropertiesLinearization:
+        """Linearize properties_from_mU for several seed directions."""
+
+        dm_values = tuple(float(value) for value in dm)
+        dU_values = tuple(float(value) for value in dU)
+        dV_values = tuple(float(value) for value in dV)
+        if not (len(dm_values) == len(dU_values) == len(dV_values)):
+            raise ValueError("Thermodynamic tangent vectors must have equal lengths.")
+        props = properties or self.properties_from_mU(m, U, V)
+        width = len(dm_values)
+        expected_density = m / V
+        expected_internal_energy = U / m
+        if (
+            abs(props.rho - expected_density)
+            > 1.0e-12 * max(abs(expected_density), 1.0)
+            or abs(props.u - expected_internal_energy)
+            > 1.0e-12 * max(abs(expected_internal_energy), 1.0)
+        ):
+            return ThermodynamicPropertiesLinearization(
+                properties=props,
+                tangents=ThermodynamicPropertyTangents.zeros(width),
+                valid=False,
+                reason="properties_primal_mismatch",
+            )
+        if not all(
+            isfinite(value)
+            for values in (dm_values, dU_values, dV_values)
+            for value in values
+        ):
+            return ThermodynamicPropertiesLinearization(
+                properties=props,
+                tangents=ThermodynamicPropertyTangents.zeros(width),
+                valid=False,
+                reason="non_finite_tangent_input",
+            )
+
+        cv = self.cv_at_temperature(props.T)
+        cp = self.cp_at_temperature(props.T)
+        if not isfinite(cv) or not isfinite(cp) or cv <= 0.0 or cp <= 0.0:
+            return ThermodynamicPropertiesLinearization(
+                properties=props,
+                tangents=ThermodynamicPropertyTangents.zeros(width),
+                valid=False,
+                reason="non_positive_heat_capacity",
+            )
+
+        drho: list[float] = []
+        du: list[float] = []
+        dT: list[float] = []
+        dp: list[float] = []
+        dh: list[float] = []
+        for mass_tangent, energy_tangent, volume_tangent in zip(
+            dm_values,
+            dU_values,
+            dV_values,
+            strict=True,
+        ):
+            density_tangent = mass_tangent / V - m * volume_tangent / (V * V)
+            internal_energy_tangent = (
+                energy_tangent / m - U * mass_tangent / (m * m)
+            )
+            temperature_tangent = internal_energy_tangent / cv
+            pressure_tangent = self.R_gas * (
+                props.T * density_tangent + props.rho * temperature_tangent
+            )
+            enthalpy_tangent = cp * temperature_tangent
+            drho.append(density_tangent)
+            du.append(internal_energy_tangent)
+            dT.append(temperature_tangent)
+            dp.append(pressure_tangent)
+            dh.append(enthalpy_tangent)
+
+        tangent_values = (*drho, *du, *dT, *dp, *dh)
+        valid = all(isfinite(value) for value in tangent_values)
+        return ThermodynamicPropertiesLinearization(
+            properties=props,
+            tangents=ThermodynamicPropertyTangents(
+                p=tuple(dp),
+                T=tuple(dT),
+                rho=tuple(drho),
+                u=tuple(du),
+                h=tuple(dh),
+            ),
+            valid=valid,
+            reason=None if valid else "non_finite_property_tangent",
+        )
@@ -0,0 +1,424 @@
+from __future__ import annotations
+
+from app.simulation.core.errors import RecoverableTrialStateError
+
+from dataclasses import dataclass
+from math import acos, cos, isfinite, log, pi, sqrt
+
+from app.simulation.performance import profile_property
+
+UNIVERSAL_GAS_CONSTANT = 8.31446261815324
+# Simcenter Amesim 2404 ``sag_reinit_eos_`` keeps more digits than the
+# commonly printed Peng-Robinson constants 0.45724 and 0.07780.
+PENG_ROBINSON_A_COEFFICIENT = 0.457235583
+PENG_ROBINSON_B_COEFFICIENT = 0.07779607
+
+
+@dataclass(frozen=True)
+class PengRobinsonFluid:
+    """Pure-fluid Peng-Robinson equation-of-state helper.
+
+    The class covers the equation-of-state layer plus the enthalpy departure
+    needed to compare AMESim pneumatic ``pn2hpti`` reference enthalpy flows.
+    """
+
+    name: str
+    molar_mass: float
+    critical_temperature: float
+    critical_pressure: float
+    acentric_factor: float
+
+    @property
+    def specific_gas_constant(self) -> float:
+        return UNIVERSAL_GAS_CONSTANT / self.molar_mass
+
+    @property
+    def a_parameter(self) -> float:
+        return (
+            PENG_ROBINSON_A_COEFFICIENT
+            * UNIVERSAL_GAS_CONSTANT
+            * UNIVERSAL_GAS_CONSTANT
+            * self.critical_temperature
+            * self.critical_temperature
+            / self.critical_pressure
+        )
+
+    @property
+    def b_parameter(self) -> float:
+        return (
+            PENG_ROBINSON_B_COEFFICIENT
+            * UNIVERSAL_GAS_CONSTANT
+            * self.critical_temperature
+            / self.critical_pressure
+        )
+
+    @property
+    def kappa(self) -> float:
+        omega = self.acentric_factor
+        return 0.37464 + 1.54226 * omega - 0.26992 * omega * omega
+
+    def alpha(self, temperature: float) -> float:
+        self._validate_temperature(temperature)
+        reduced_temperature = temperature / self.critical_temperature
+        return (1.0 + self.kappa * (1.0 - sqrt(reduced_temperature))) ** 2.0
+
+    def alpha_temperature_derivative(self, temperature: float) -> float:
+        self._validate_temperature(temperature)
+        reduced_temperature = temperature / self.critical_temperature
+        sqrt_reduced_temperature = sqrt(reduced_temperature)
+        alpha_base = 1.0 + self.kappa * (1.0 - sqrt_reduced_temperature)
+        return -(
+            alpha_base
+            * self.kappa
+            / (self.critical_temperature * sqrt_reduced_temperature)
+        )
+
+    def alpha_temperature_second_derivative(self, temperature: float) -> float:
+        self._validate_temperature(temperature)
+        reduced_temperature = temperature / self.critical_temperature
+        sqrt_reduced_temperature = sqrt(reduced_temperature)
+        alpha_base = 1.0 + self.kappa * (1.0 - sqrt_reduced_temperature)
+        return (
+            self.kappa
+            / (2.0 * self.critical_temperature * self.critical_temperature)
+            * (
+                self.kappa / reduced_temperature
+                + alpha_base / (reduced_temperature * sqrt_reduced_temperature)
+            )
+        )
+
+    def attractive_parameter(self, temperature: float) -> float:
+        return self.a_parameter * self.alpha(temperature)
+
+    def attractive_parameter_temperature_derivative(self, temperature: float) -> float:
+        return self.a_parameter * self.alpha_temperature_derivative(temperature)
+
+    def attractive_parameter_temperature_second_derivative(
+        self,
+        temperature: float,
+    ) -> float:
+        return self.a_parameter * self.alpha_temperature_second_derivative(temperature)
+
+    @profile_property(
+        "pressure_from_molar_volume",
+        layer="kernel",
+        minimum_mode="audit",
+    )
+    def pressure_from_molar_volume(self, temperature: float, molar_volume: float) -> float:
+        self._validate_temperature(temperature)
+        if molar_volume <= self.b_parameter:
+            raise RecoverableTrialStateError("Molar volume must be larger than Peng-Robinson b parameter.")
+        a_alpha = self.attractive_parameter(temperature)
+        b = self.b_parameter
+        repulsive = UNIVERSAL_GAS_CONSTANT * temperature / (molar_volume - b)
+        attractive = a_alpha / (molar_volume * (molar_volume + b) + b * (molar_volume - b))
+        return repulsive - attractive
+
+    @profile_property(
+        "pressure_from_density",
+        layer="kernel",
+        minimum_mode="audit",
+    )
+    def pressure_from_density(self, temperature: float, density: float) -> float:
+        if density <= 0.0:
+            raise ValueError("Density must be positive.")
+        return self.pressure_from_molar_volume(temperature, self.molar_mass / density)
+
+    @profile_property(
+        "pressure_temperature_derivative_at_density",
+        layer="kernel",
+        minimum_mode="audit",
+    )
+    def pressure_temperature_derivative_at_density(
+        self,
+        temperature: float,
+        density: float,
+    ) -> float:
+        self._validate_temperature(temperature)
+        if density <= 0.0:
+            raise ValueError("Density must be positive.")
+        molar_volume = self.molar_mass / density
+        if molar_volume <= self.b_parameter:
+            raise RecoverableTrialStateError(
+                "Molar volume must be larger than Peng-Robinson b parameter."
+            )
+        b = self.b_parameter
+        denominator = molar_volume * (molar_volume + b) + b * (molar_volume - b)
+        return (
+            UNIVERSAL_GAS_CONSTANT / (molar_volume - b)
+            - self.attractive_parameter_temperature_derivative(temperature) / denominator
+        )
+
+    @profile_property(
+        "pressure_density_derivative_at_temperature",
+        layer="kernel",
+        minimum_mode="audit",
+    )
+    def pressure_density_derivative_at_temperature(
+        self,
+        temperature: float,
+        density: float,
+    ) -> float:
+        self._validate_temperature(temperature)
+        if density <= 0.0:
+            raise ValueError("Density must be positive.")
+        molar_volume = self.molar_mass / density
+        if molar_volume <= self.b_parameter:
+            raise RecoverableTrialStateError(
+                "Molar volume must be larger than Peng-Robinson b parameter."
+            )
+        b = self.b_parameter
+        denominator = molar_volume * (molar_volume + b) + b * (molar_volume - b)
+        pressure_molar_volume_derivative = (
+            -UNIVERSAL_GAS_CONSTANT * temperature / (molar_volume - b) ** 2
+            + self.attractive_parameter(temperature)
+            * 2.0
+            * (molar_volume + b)
+            / denominator**2
+        )
+        molar_volume_density_derivative = -self.molar_mass / (density * density)
+        return pressure_molar_volume_derivative * molar_volume_density_derivative
+
+    def reduced_parameters(self, pressure: float, temperature: float) -> tuple[float, float]:
+        self._validate_pressure_temperature(pressure, temperature)
+        a_alpha = self.attractive_parameter(temperature)
+        b = self.b_parameter
+        A = a_alpha * pressure / (UNIVERSAL_GAS_CONSTANT * UNIVERSAL_GAS_CONSTANT * temperature * temperature)
+        B = b * pressure / (UNIVERSAL_GAS_CONSTANT * temperature)
+        return A, B
+
+    @profile_property(
+        "compressibility_roots",
+        layer="kernel",
+        minimum_mode="audit",
+    )
+    def compressibility_roots(self, pressure: float, temperature: float) -> tuple[float, ...]:
+        A, B = self.reduced_parameters(pressure, temperature)
+        coefficients = (
+            -(1.0 - B),
+            A - 3.0 * B * B - 2.0 * B,
+            -(A * B - B * B - B * B * B),
+        )
+        roots = _real_cubic_roots(*coefficients)
+        physical_roots = tuple(sorted(root for root in roots if root > B and isfinite(root)))
+        if not physical_roots:
+            raise ValueError("Peng-Robinson cubic produced no physical compressibility root.")
+        return physical_roots
+
+    @profile_property(
+        "compressibility_factor",
+        layer="kernel",
+        minimum_mode="audit",
+    )
+    def compressibility_factor(
+        self,
+        pressure: float,
+        temperature: float,
+        phase: str = "vapor",
+    ) -> float:
+        roots = self.compressibility_roots(pressure, temperature)
+        if phase == "vapor":
+            return roots[-1]
+        if phase == "liquid":
+            return roots[0]
+        if phase == "stable-single-root":
+            return roots[-1]
+        raise ValueError(f"Unsupported phase selector: {phase!r}")
+
+    @profile_property(
+        "molar_volume",
+        layer="kernel",
+        minimum_mode="audit",
+    )
+    def molar_volume(
+        self,
+        pressure: float,
+        temperature: float,
+        phase: str = "vapor",
+    ) -> float:
+        z = self.compressibility_factor(pressure, temperature, phase=phase)
+        return z * UNIVERSAL_GAS_CONSTANT * temperature / pressure
+
+    @profile_property("density", layer="kernel", minimum_mode="audit")
+    def density(
+        self,
+        pressure: float,
+        temperature: float,
+        phase: str = "vapor",
+    ) -> float:
+        return self.molar_mass / self.molar_volume(pressure, temperature, phase=phase)
+
+    @profile_property(
+        "residual_specific_enthalpy",
+        layer="kernel",
+        minimum_mode="audit",
+    )
+    def residual_specific_enthalpy(
+        self,
+        pressure: float,
+        temperature: float,
+        phase: str = "vapor",
+    ) -> float:
+        """Return Peng-Robinson enthalpy departure from ideal gas, J/kg."""
+        self._validate_pressure_temperature(pressure, temperature)
+        z = self.compressibility_factor(pressure, temperature, phase=phase)
+        _, B = self.reduced_parameters(pressure, temperature)
+        b = self.b_parameter
+        attractive = self.attractive_parameter(temperature)
+        d_attractive_d_temperature = (
+            self.attractive_parameter_temperature_derivative(temperature)
+        )
+        log_argument = (z + (1.0 + sqrt(2.0)) * B) / (
+            z + (1.0 - sqrt(2.0)) * B
+        )
+        residual_molar_enthalpy = (
+            UNIVERSAL_GAS_CONSTANT * temperature * (z - 1.0)
+            + (
+                temperature * d_attractive_d_temperature
+                - attractive
+            )
+            * log(log_argument)
+            / (2.0 * sqrt(2.0) * b)
+        )
+        return residual_molar_enthalpy / self.molar_mass
+
+    @profile_property(
+        "residual_specific_internal_energy_at_density",
+        layer="kernel",
+        minimum_mode="audit",
+    )
+    def residual_specific_internal_energy_at_density(
+        self,
+        temperature: float,
+        density: float,
+    ) -> float:
+        """Return Peng-Robinson internal-energy departure, J/kg."""
+        self._validate_temperature(temperature)
+        if density <= 0.0:
+            raise ValueError("Density must be positive.")
+        molar_volume = self.molar_mass / density
+        b = self.b_parameter
+        if molar_volume <= b:
+            raise RecoverableTrialStateError(
+                "Molar volume must be larger than Peng-Robinson b parameter."
+            )
+        attractive = self.attractive_parameter(temperature)
+        d_attractive_d_temperature = (
+            self.attractive_parameter_temperature_derivative(temperature)
+        )
+        log_argument = (
+            molar_volume + (1.0 + sqrt(2.0)) * b
+        ) / (
+            molar_volume + (1.0 - sqrt(2.0)) * b
+        )
+        residual_molar_internal_energy = (
+            temperature * d_attractive_d_temperature - attractive
+        ) * log(log_argument) / (2.0 * sqrt(2.0) * b)
+        return residual_molar_internal_energy / self.molar_mass
+
+    @profile_property(
+        "residual_isochoric_heat_capacity_at_density",
+        layer="kernel",
+        minimum_mode="audit",
+    )
+    def residual_isochoric_heat_capacity_at_density(
+        self,
+        temperature: float,
+        density: float,
+    ) -> float:
+        """Return the constant-volume heat-capacity departure, J/kg/K."""
+        self._validate_temperature(temperature)
+        if density <= 0.0:
+            raise ValueError("Density must be positive.")
+        molar_volume = self.molar_mass / density
+        b = self.b_parameter
+        if molar_volume <= b:
+            raise RecoverableTrialStateError(
+                "Molar volume must be larger than Peng-Robinson b parameter."
+            )
+        log_argument = (
+            molar_volume + (1.0 + sqrt(2.0)) * b
+        ) / (
+            molar_volume + (1.0 - sqrt(2.0)) * b
+        )
+        residual_molar_cv = (
+            temperature
+            * self.attractive_parameter_temperature_second_derivative(temperature)
+            * log(log_argument)
+            / (2.0 * sqrt(2.0) * b)
+        )
+        return residual_molar_cv / self.molar_mass
+
+    @staticmethod
+    def _validate_temperature(temperature: float) -> None:
+        if temperature <= 0.0:
+            raise RecoverableTrialStateError("Temperature must be positive.")
+
+    @classmethod
+    def _validate_pressure_temperature(cls, pressure: float, temperature: float) -> None:
+        if pressure <= 0.0:
+            raise RecoverableTrialStateError("Pressure must be positive.")
+        cls._validate_temperature(temperature)
+
+HELIUM_PR = PengRobinsonFluid(
+    name="helium",
+    molar_mass=0.004002602,
+    critical_temperature=5.1953,
+    critical_pressure=227_460.0,
+    # Simcenter Amesim 2404 helium_eos.data.
+    acentric_factor=-0.382,
+)
+
+NITROGEN_PR = PengRobinsonFluid(
+    name="nitrogen",
+    molar_mass=0.0280134,
+    critical_temperature=126.192,
+    critical_pressure=3.3958e6,
+    acentric_factor=0.0372,
+)
+
+AIR_PR = PengRobinsonFluid(
+    name="air",
+    molar_mass=0.02896513,
+    critical_temperature=132.5306,
+    critical_pressure=3.786e6,
+    acentric_factor=0.0335,
+)
+
+
+def _real_cubic_roots(a: float, b: float, c: float) -> tuple[float, ...]:
+    """Return real roots for x**3 + a*x**2 + b*x + c = 0."""
+
+    depressed_p = b - a * a / 3.0
+    depressed_q = 2.0 * a * a * a / 27.0 - a * b / 3.0 + c
+    discriminant = (depressed_q / 2.0) ** 2.0 + (depressed_p / 3.0) ** 3.0
+    offset = -a / 3.0
+    tolerance = 1e-14
+
+    if discriminant > tolerance:
+        sqrt_discriminant = sqrt(discriminant)
+        u = _real_cube_root(-depressed_q / 2.0 + sqrt_discriminant)
+        v = _real_cube_root(-depressed_q / 2.0 - sqrt_discriminant)
+        return (u + v + offset,)
+
+    if abs(discriminant) <= tolerance:
+        u = _real_cube_root(-depressed_q / 2.0)
+        return tuple(sorted({2.0 * u + offset, -u + offset}))
+
+    if depressed_p >= 0.0:
+        raise ValueError("Unexpected cubic state with three real roots and non-negative p.")
+    radius = 2.0 * sqrt(-depressed_p / 3.0)
+    argument = (3.0 * depressed_q / (2.0 * depressed_p)) * sqrt(-3.0 / depressed_p)
+    argument = max(-1.0, min(1.0, argument))
+    theta = acos(argument) / 3.0
+    roots = [
+        radius * cos(theta - 2.0 * pi * index / 3.0) + offset
+        for index in range(3)
+    ]
+    return tuple(sorted(roots))
+
+
+def _real_cube_root(value: float) -> float:
+    if value == 0.0:
+        return 0.0
+    return (1.0 if value > 0.0 else -1.0) * abs(value) ** (1.0 / 3.0)
@@ -1,152 +0,0 @@
-"""Compile-time variable supply contracts, separate from physical flow direction.
-
-Equation ports may participate in a simultaneous solve. Fixed ports (for example
-an Amesim node's reference/branch ports) require complementary local supplies.
-These declarations do not add numerical state or Python evaluation callbacks.
-"""
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import TYPE_CHECKING, Literal, Mapping
-
-if TYPE_CHECKING:
-    from .ports import PortDefinition
-
-
-VARIABLE_LABELS = {
-    "p": "压力", "T": "温度", "m_flow": "质量流率", "H_flow": "能量流率",
-}
-
-
-@dataclass(frozen=True)
-class PortComputation:
-    inputs: tuple[str, ...] = ()
-    outputs: tuple[str, ...] = ()
-    mode: Literal["equation", "fixed"] = "equation"
-    # Output p/T aliases an input on another port of the same component.
-    reference_port: str | None = None
-
-    def __post_init__(self) -> None:
-        if self.mode not in {"equation", "fixed"}:
-            raise ValueError(f"Unknown port computation mode: {self.mode}")
-        members = (*self.inputs, *self.outputs)
-        if len(set(members)) != len(members) or set(members) - VARIABLE_LABELS.keys():
-            raise ValueError("Port computation variables must be unique, supported quantities.")
-        if self.reference_port and not {"p", "T"}.issubset(self.outputs):
-            raise ValueError("A reference alias must supply pressure and temperature.")
-
-    def as_dict(self) -> dict[str, object]:
-        return {
-            "mode": self.mode,
-            "inputs": list(self.inputs),
-            "outputs": list(self.outputs),
-            **({"referencePort": self.reference_port} if self.reference_port else {}),
-        }
-
-
-THERMODYNAMIC_SUPPLY = PortComputation(inputs=("m_flow", "H_flow"), outputs=("p", "T"))
-FLOW_SUPPLY = PortComputation(inputs=("p", "T"), outputs=("m_flow", "H_flow"))
-ZERO_FLOW_SUPPLY = PortComputation(outputs=("m_flow", "H_flow"))
-IMPLICIT_PNEUMATIC = PortComputation()
-NODE_REFERENCE = PortComputation(inputs=("p", "T"), outputs=("m_flow", "H_flow"), mode="fixed")
-NODE_BRANCH = PortComputation(inputs=("m_flow", "H_flow"), outputs=("p", "T"),
-                              mode="fixed", reference_port="port_2")
-
-
-@dataclass(frozen=True)
-class PortSupplyIssue:
-    code: str
-    message: str
-    endpoint: tuple[str, str] | None = None
-
-
-class PortSupplyError(ValueError):
-    def __init__(self, issue: PortSupplyIssue):
-        self.issue = issue
-        super().__init__(f"{issue.code}: {issue.message}")
-
-
-def port_supply_issue(first: PortDefinition, second: PortDefinition,
-                      first_label: str | None = None, second_label: str | None = None
-                      ) -> PortSupplyIssue | None:
-    """Check fixed causality; ordinary equation-to-equation links stay legal."""
-    if first.kind != second.kind or first.domain != second.domain:
-        return None  # Domain/type checks own their existing, more specific errors.
-    a, b = first.computation, second.computation
-    if not any(item and item.mode == "fixed" for item in (a, b)):
-        return None
-    for consumer, supplier, consumer_label, supplier_label in (
-        (a, b, first_label or first.name, second_label or second.name),
-        (b, a, second_label or second.name, first_label or first.name),
-    ):
-        if consumer is None:
-            continue
-        missing = [name for name in consumer.inputs
-                   if supplier is None or name not in supplier.outputs]
-        if missing:
-            quantities = "、".join(VARIABLE_LABELS[name] for name in missing)
-            return PortSupplyIssue(
-                "CONNECTION_VARIABLE_SUPPLY_MISSING",
-                f"{consumer_label} 需要对端提供{quantities}，但 {supplier_label} 未提供；"
-                "请检查参考口与支路口的连接。气体流向反转不会改变这一供需关系。",
-            )
-    return None
-
-
-def reference_supply_issues(
-    ports: Mapping[tuple[str, str], PortDefinition],
-    adjacency: Mapping[tuple[str, str], tuple[str, str]],
-) -> list[PortSupplyIssue]:
-    """Follow declared aliases to reject a reference ring without an origin.
-
-    This is a supply check, not a whole-system execution scheduler. Reference
-    chains are iterative to support deep networks without Python recursion.
-    """
-    issues = []
-    resolved: dict[str, set[tuple[str, str]]] = {'p': set(), 'T': set()}
-    for endpoint, port in ports.items():
-        contract = port.computation
-        if not contract or contract.mode != "fixed" or not {"p", "T"}.issubset(contract.inputs):
-            continue
-        if endpoint not in adjacency:
-            continue  # Existing unconnected-port checks handle incomplete drawings.
-        for variable in ("p", "T"):
-            current = endpoint
-            visited: set[tuple[str, str]] = set()
-            chain: list[str] = []
-            while True:
-                if current in resolved[variable]:
-                    resolved[variable].update(visited)
-                    break
-                if current in visited:
-                    issues.append(PortSupplyIssue(
-                        "REFERENCE_SUPPLY_CYCLE",
-                        f"{'.'.join(endpoint)} 的{VARIABLE_LABELS[variable]}参考形成循环，"
-                        f"没有实际提供者：{' → '.join(chain)} → {'.'.join(current)}。",
-                        endpoint,
-                    ))
-                    break
-                visited.add(current)
-                chain.append('.'.join(current))
-                supplier = adjacency.get(current)
-                if supplier is None:
-                    issues.append(PortSupplyIssue(
-                        "REFERENCE_SUPPLY_UNCONNECTED",
-                        f"{'.'.join(endpoint)} 的{VARIABLE_LABELS[variable]}参考链在 "
-                        f"{'.'.join(current)} 中断：该参考输入尚未连接。", endpoint,
-                    ))
-                    break
-                supplied = ports.get(supplier)
-                supply = supplied.computation if supplied else None
-                if supply is None or variable not in supply.outputs:
-                    # Direct errors are already reported per connection. An
-                    # indirect failure is explained at that failing connection.
-                    break
-                if supply.reference_port is None:
-                    resolved[variable].update(visited)
-                    break
-                chain.append('.'.join(supplier))
-                current = supplier[0], supply.reference_port
-                if current not in ports:
-                    raise ValueError(f"Invalid reference port declaration: {current}")
-    return issues
@@ -3,8 +3,6 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import Literal

-from .port_computation import IMPLICIT_PNEUMATIC, PortComputation
-

 PortKind = Literal["physical", "signal"]
 PortNominalRole = Literal["inlet", "outlet", "bidirectional", "input", "output"]
@@ -47,7 +45,6 @@ class PortDefinition:
    nominal_role: PortNominalRole
    positive_flow_direction: Literal["intoComponent"] | None = None
    variables: tuple[PortVariableDefinition, ...] = ()
-    computation: PortComputation | None = None

    @classmethod
    def pneumatic(
@@ -55,7 +52,6 @@ class PortDefinition:
        name: str,
        *,
        nominal_role: Literal["inlet", "outlet", "bidirectional"] = "bidirectional",
-        computation: PortComputation = IMPLICIT_PNEUMATIC,
    ) -> PortDefinition:
        return cls(
            name=name,
@@ -63,7 +59,6 @@ class PortDefinition:
            domain="pneumatic",
            nominal_role=nominal_role,
            positive_flow_direction="intoComponent",
-            computation=computation,
            variables=(
                PortVariableDefinition(
                    "p",
@@ -193,7 +188,6 @@ class PortDefinition:
            "nominalRole": self.nominal_role,
            "positiveFlowDirection": self.positive_flow_direction,
            "variables": [variable.as_interface_dict() for variable in self.variables],
-            **({"computation": self.computation.as_dict()} if self.computation else {}),
        }


@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class VolumeState:
+    """Primary dynamic state for rigid adiabatic control volumes."""
+
+    m: float
+    U: float
+
+    def as_vector(self) -> list[float]:
+        return [self.m, self.U]
+
+    @classmethod
+    def from_vector(cls, values: list[float]) -> "VolumeState":
+        if len(values) != 2:
+            raise ValueError("VolumeState requires exactly two values: [m, U].")
+        return cls(m=values[0], U=values[1])
+
@@ -0,0 +1 @@
+"""Reference systems and regression examples."""
@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from app.simulation.examples.test_mql.system import (
+    TestMqlRunConfig,
+    TestMqlSimulationResult,
+    TestMqlSystem,
+)
+from app.simulation.examples.test_mql.run import (
+    PreparedTestMqlRun,
+    TestMqlRunResult,
+    prepare_test_mql_run,
+    run_prepared_test_mql,
+    run_test_mql,
+)
+
+__all__ = [
+    "PreparedTestMqlRun",
+    "TestMqlRunConfig",
+    "TestMqlRunResult",
+    "TestMqlSimulationResult",
+    "TestMqlSystem",
+    "prepare_test_mql_run",
+    "run_prepared_test_mql",
+    "run_test_mql",
+]
@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from app.simulation.reporting.amesim_results import AmesimResults, load_test_mql_amesim_results
+from app.simulation.reporting.test_mql_comparison import TestMqlComparisonResult
+from app.simulation.reporting.test_mql_observations import (
+    TestMqlObservationCatalog,
+    build_test_mql_observation_catalog,
+)
+from app.simulation.reporting.test_mql_output_schema import (
+    TestMqlOutputSchema,
+    build_test_mql_output_schema,
+)
+from app.simulation.reporting.test_mql_output_validation import (
+    TestMqlValidatedOutput,
+    compare_validated_test_mql_output,
+    validate_test_mql_output,
+)
+
+
+@dataclass(frozen=True)
+class TestMqlBaselineRun:
+    amesim_results: AmesimResults
+    observation_catalog: TestMqlObservationCatalog
+    output_schema: TestMqlOutputSchema
+    output: TestMqlValidatedOutput
+    comparison: TestMqlComparisonResult
+
+    @property
+    def sample_count(self) -> int:
+        return len(self.output.times)
+
+    @property
+    def signal_count(self) -> int:
+        return len(self.output.data_paths)
+
+
+def run_test_mql_baseline_passthrough(
+    archive_path: Path,
+    *,
+    data_paths: tuple[str, ...] | list[str] | None = None,
+) -> TestMqlBaselineRun:
+    amesim_results = load_test_mql_amesim_results(archive_path)
+    observation_catalog = build_test_mql_observation_catalog(amesim_results)
+    output_schema = build_test_mql_output_schema(
+        amesim_results,
+        observation_catalog=observation_catalog,
+    )
+    selected_paths = tuple(data_paths) if data_paths is not None else output_schema.data_paths()
+    baseline_series = observation_catalog.baseline_series_by_data_path(
+        amesim_results,
+        selected_paths,
+    )
+    output = validate_test_mql_output(
+        times=amesim_results.times,
+        series_by_data_path=baseline_series,
+        schema=output_schema,
+        data_paths=selected_paths,
+        require_all_schema_paths=data_paths is None,
+    )
+    comparison = compare_validated_test_mql_output(
+        times=output.times,
+        series_by_data_path=output.series_by_data_path,
+        schema=output_schema,
+        amesim_results=amesim_results,
+        data_paths=output.data_paths,
+        require_all_schema_paths=data_paths is None,
+    )
+    return TestMqlBaselineRun(
+        amesim_results=amesim_results,
+        observation_catalog=observation_catalog,
+        output_schema=output_schema,
+        output=output,
+        comparison=comparison,
+    )
@@ -0,0 +1,468 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from app.simulation.examples.test_mql.primitives.pneumatic import m3_to_cm3
+from app.simulation.reporting.amesim_results import AmesimResults, load_test_mql_amesim_results
+from app.simulation.reporting.test_mql_comparison import TestMqlComparisonResult
+from app.simulation.reporting.test_mql_observations import (
+    TestMqlObservationCatalog,
+    build_test_mql_observation_catalog,
+)
+from app.simulation.reporting.test_mql_output_schema import (
+    TestMqlOutputSchema,
+    build_test_mql_output_schema,
+)
+from app.simulation.reporting.test_mql_output_validation import (
+    TestMqlValidatedOutput,
+    compare_validated_test_mql_output,
+    validate_test_mql_output,
+)
+from app.simulation.reporting.test_mql_variables import build_test_mql_variable_catalog
+from app.simulation.examples.test_mql.mechanical import (
+    TestMqlMechanicalAssembly,
+    build_test_mql_mechanical_assembly,
+)
+from app.simulation.examples.test_mql.pneumatic import (
+    TestMqlPneumaticAssembly,
+    build_test_mql_pneumatic_assembly,
+)
+
+
+@dataclass(frozen=True)
+class TestMqlComputedPistonGeometryRun:
+    amesim_results: AmesimResults
+    observation_catalog: TestMqlObservationCatalog
+    output_schema: TestMqlOutputSchema
+    mechanical_assembly: TestMqlMechanicalAssembly
+    output: TestMqlValidatedOutput
+    comparison: TestMqlComparisonResult
+
+    @property
+    def sample_count(self) -> int:
+        return len(self.output.times)
+
+    @property
+    def signal_count(self) -> int:
+        return len(self.output.data_paths)
+
+
+@dataclass(frozen=True)
+class TestMqlComputedGeometryRun:
+    amesim_results: AmesimResults
+    observation_catalog: TestMqlObservationCatalog
+    output_schema: TestMqlOutputSchema
+    mechanical_assembly: TestMqlMechanicalAssembly
+    pneumatic_assembly: TestMqlPneumaticAssembly
+    output: TestMqlValidatedOutput
+    comparison: TestMqlComparisonResult
+
+    @property
+    def sample_count(self) -> int:
+        return len(self.output.times)
+
+    @property
+    def signal_count(self) -> int:
+        return len(self.output.data_paths)
+
+
+@dataclass(frozen=True)
+class TestMqlComputedLineRelationsRun:
+    amesim_results: AmesimResults
+    observation_catalog: TestMqlObservationCatalog
+    output_schema: TestMqlOutputSchema
+    output: TestMqlValidatedOutput
+    comparison: TestMqlComparisonResult
+
+    @property
+    def sample_count(self) -> int:
+        return len(self.output.times)
+
+    @property
+    def signal_count(self) -> int:
+        return len(self.output.data_paths)
+
+
+@dataclass(frozen=True)
+class TestMqlComputedPneumaticRelationsRun:
+    amesim_results: AmesimResults
+    observation_catalog: TestMqlObservationCatalog
+    output_schema: TestMqlOutputSchema
+    output: TestMqlValidatedOutput
+    comparison: TestMqlComparisonResult
+
+    @property
+    def sample_count(self) -> int:
+        return len(self.output.times)
+
+    @property
+    def signal_count(self) -> int:
+        return len(self.output.data_paths)
+
+
+@dataclass(frozen=True)
+class TestMqlComputedMechanicalRelationsRun:
+    amesim_results: AmesimResults
+    observation_catalog: TestMqlObservationCatalog
+    output_schema: TestMqlOutputSchema
+    mechanical_assembly: TestMqlMechanicalAssembly
+    output: TestMqlValidatedOutput
+    comparison: TestMqlComparisonResult
+
+    @property
+    def sample_count(self) -> int:
+        return len(self.output.times)
+
+    @property
+    def signal_count(self) -> int:
+        return len(self.output.data_paths)
+
+
+def run_test_mql_computed_piston_geometry(
+    archive_path: Path,
+) -> TestMqlComputedPistonGeometryRun:
+    amesim_results = load_test_mql_amesim_results(archive_path)
+    observation_catalog = build_test_mql_observation_catalog(amesim_results)
+    output_schema = build_test_mql_output_schema(
+        amesim_results,
+        observation_catalog=observation_catalog,
+    )
+    variable_catalog = build_test_mql_variable_catalog(amesim_results)
+    mechanical_assembly = build_test_mql_mechanical_assembly(
+        amesim_results=amesim_results,
+        variable_catalog=variable_catalog,
+    )
+    output_series = _compute_piston_geometry_series(amesim_results, mechanical_assembly)
+    output_data_paths = tuple(output_series)
+    output = validate_test_mql_output(
+        times=amesim_results.times,
+        series_by_data_path=output_series,
+        schema=output_schema,
+        data_paths=output_data_paths,
+    )
+    comparison = compare_validated_test_mql_output(
+        times=output.times,
+        series_by_data_path=output.series_by_data_path,
+        schema=output_schema,
+        amesim_results=amesim_results,
+        data_paths=output.data_paths,
+    )
+    return TestMqlComputedPistonGeometryRun(
+        amesim_results=amesim_results,
+        observation_catalog=observation_catalog,
+        output_schema=output_schema,
+        mechanical_assembly=mechanical_assembly,
+        output=output,
+        comparison=comparison,
+    )
+
+
+def run_test_mql_computed_geometry(
+    archive_path: Path,
+) -> TestMqlComputedGeometryRun:
+    amesim_results = load_test_mql_amesim_results(archive_path)
+    observation_catalog = build_test_mql_observation_catalog(amesim_results)
+    output_schema = build_test_mql_output_schema(
+        amesim_results,
+        observation_catalog=observation_catalog,
+    )
+    variable_catalog = build_test_mql_variable_catalog(amesim_results)
+    mechanical_assembly = build_test_mql_mechanical_assembly(
+        amesim_results=amesim_results,
+        variable_catalog=variable_catalog,
+    )
+    pneumatic_assembly = build_test_mql_pneumatic_assembly()
+    output_series = {
+        **_compute_piston_geometry_series(amesim_results, mechanical_assembly),
+        **_compute_variable_chamber_volume_series(
+            amesim_results,
+            mechanical_assembly,
+            pneumatic_assembly,
+        ),
+    }
+    output_data_paths = tuple(output_series)
+    output = validate_test_mql_output(
+        times=amesim_results.times,
+        series_by_data_path=output_series,
+        schema=output_schema,
+        data_paths=output_data_paths,
+    )
+    comparison = compare_validated_test_mql_output(
+        times=output.times,
+        series_by_data_path=output.series_by_data_path,
+        schema=output_schema,
+        amesim_results=amesim_results,
+        data_paths=output.data_paths,
+    )
+    return TestMqlComputedGeometryRun(
+        amesim_results=amesim_results,
+        observation_catalog=observation_catalog,
+        output_schema=output_schema,
+        mechanical_assembly=mechanical_assembly,
+        pneumatic_assembly=pneumatic_assembly,
+        output=output,
+        comparison=comparison,
+    )
+
+
+def run_test_mql_computed_line_relations(
+    archive_path: Path,
+) -> TestMqlComputedLineRelationsRun:
+    amesim_results = load_test_mql_amesim_results(archive_path)
+    observation_catalog = build_test_mql_observation_catalog(amesim_results)
+    output_schema = build_test_mql_output_schema(
+        amesim_results,
+        observation_catalog=observation_catalog,
+    )
+    output_series = _compute_line_reversed_series(amesim_results, observation_catalog)
+    output_data_paths = tuple(output_series)
+    output = validate_test_mql_output(
+        times=amesim_results.times,
+        series_by_data_path=output_series,
+        schema=output_schema,
+        data_paths=output_data_paths,
+    )
+    comparison = compare_validated_test_mql_output(
+        times=output.times,
+        series_by_data_path=output.series_by_data_path,
+        schema=output_schema,
+        amesim_results=amesim_results,
+        data_paths=output.data_paths,
+    )
+    return TestMqlComputedLineRelationsRun(
+        amesim_results=amesim_results,
+        observation_catalog=observation_catalog,
+        output_schema=output_schema,
+        output=output,
+        comparison=comparison,
+    )
+
+
+def run_test_mql_computed_pneumatic_relations(
+    archive_path: Path,
+) -> TestMqlComputedPneumaticRelationsRun:
+    amesim_results = load_test_mql_amesim_results(archive_path)
+    observation_catalog = build_test_mql_observation_catalog(amesim_results)
+    output_schema = build_test_mql_output_schema(
+        amesim_results,
+        observation_catalog=observation_catalog,
+    )
+    output_series = {
+        **_compute_chamber_duplicate_series(amesim_results, observation_catalog),
+        **_compute_orifice_reversed_series(amesim_results, observation_catalog),
+    }
+    output_data_paths = tuple(output_series)
+    output = validate_test_mql_output(
+        times=amesim_results.times,
+        series_by_data_path=output_series,
+        schema=output_schema,
+        data_paths=output_data_paths,
+    )
+    comparison = compare_validated_test_mql_output(
+        times=output.times,
+        series_by_data_path=output.series_by_data_path,
+        schema=output_schema,
+        amesim_results=amesim_results,
+        data_paths=output.data_paths,
+    )
+    return TestMqlComputedPneumaticRelationsRun(
+        amesim_results=amesim_results,
+        observation_catalog=observation_catalog,
+        output_schema=output_schema,
+        output=output,
+        comparison=comparison,
+    )
+
+
+def run_test_mql_computed_mechanical_relations(
+    archive_path: Path,
+) -> TestMqlComputedMechanicalRelationsRun:
+    amesim_results = load_test_mql_amesim_results(archive_path)
+    observation_catalog = build_test_mql_observation_catalog(amesim_results)
+    output_schema = build_test_mql_output_schema(
+        amesim_results,
+        observation_catalog=observation_catalog,
+    )
+    variable_catalog = build_test_mql_variable_catalog(amesim_results)
+    mechanical_assembly = build_test_mql_mechanical_assembly(
+        amesim_results=amesim_results,
+        variable_catalog=variable_catalog,
+    )
+    output_series = {
+        **_compute_mass_duplicate_series(amesim_results, mechanical_assembly),
+        **_compute_inactive_mass_force_series(amesim_results, mechanical_assembly),
+        **_compute_zero_force_source_series(amesim_results, mechanical_assembly),
+    }
+    output_data_paths = tuple(output_series)
+    output = validate_test_mql_output(
+        times=amesim_results.times,
+        series_by_data_path=output_series,
+        schema=output_schema,
+        data_paths=output_data_paths,
+    )
+    comparison = compare_validated_test_mql_output(
+        times=output.times,
+        series_by_data_path=output.series_by_data_path,
+        schema=output_schema,
+        amesim_results=amesim_results,
+        data_paths=output.data_paths,
+    )
+    return TestMqlComputedMechanicalRelationsRun(
+        amesim_results=amesim_results,
+        observation_catalog=observation_catalog,
+        output_schema=output_schema,
+        mechanical_assembly=mechanical_assembly,
+        output=output,
+        comparison=comparison,
+    )
+
+
+def _compute_piston_geometry_series(
+    amesim_results: AmesimResults,
+    mechanical_assembly: TestMqlMechanicalAssembly,
+) -> dict[str, tuple[float, ...]]:
+    series_by_data_path: dict[str, tuple[float, ...]] = {}
+    for alias in sorted(mechanical_assembly.pistons):
+        piston = mechanical_assembly.pistons[alias]
+        geometry = piston.geometry()
+        x4 = amesim_results.series(f"x4@{alias}")
+        x5 = amesim_results.series(f"x5@{alias}")
+        v4 = amesim_results.series(f"v4@{alias}")
+        v5 = amesim_results.series(f"v5@{alias}")
+        series_by_data_path[f"length@{alias}"] = tuple(
+            geometry.chamber_length_mm(port4, port5)
+            for port4, port5 in zip(x4, x5)
+        )
+        series_by_data_path[f"vol1@{alias}"] = tuple(
+            geometry.chamber_volume_cm3(port4, port5)
+            for port4, port5 in zip(x4, x5)
+        )
+        series_by_data_path[f"vvol1@{alias}"] = tuple(
+            geometry.chamber_volume_rate_l_min(port4, port5)
+            for port4, port5 in zip(v4, v5)
+        )
+    return series_by_data_path
+
+
+def _compute_variable_chamber_volume_series(
+    amesim_results: AmesimResults,
+    mechanical_assembly: TestMqlMechanicalAssembly,
+    pneumatic_assembly: TestMqlPneumaticAssembly,
+) -> dict[str, tuple[float, ...]]:
+    series_by_data_path: dict[str, tuple[float, ...]] = {}
+    for chamber_alias in sorted(pneumatic_assembly.variable_chambers):
+        chamber = pneumatic_assembly.variable_chambers[chamber_alias]
+        piston_alias = _piston_alias_for_variable_chamber(chamber_alias)
+        piston = mechanical_assembly.pistons[piston_alias]
+        geometry = piston.geometry()
+        x4 = amesim_results.series(f"x4@{piston_alias}")
+        x5 = amesim_results.series(f"x5@{piston_alias}")
+        dead_volume_cm3 = m3_to_cm3(chamber.dead_volume)
+        series_by_data_path[f"vol@{chamber_alias}"] = tuple(
+            dead_volume_cm3 + geometry.chamber_volume_cm3(port4, port5)
+            for port4, port5 in zip(x4, x5)
+        )
+    return series_by_data_path
+
+
+def _piston_alias_for_variable_chamber(chamber_alias: str) -> str:
+    if not chamber_alias.startswith("pn_c1"):
+        raise ValueError(f"Unexpected PNCH012 alias: {chamber_alias}")
+    return chamber_alias.replace("pn_c1", "pn_brp2", 1)
+
+
+def _compute_mass_duplicate_series(
+    amesim_results: AmesimResults,
+    mechanical_assembly: TestMqlMechanicalAssembly,
+) -> dict[str, tuple[float, ...]]:
+    series_by_data_path: dict[str, tuple[float, ...]] = {}
+    for alias in sorted(mechanical_assembly.masses):
+        for signal_name in ("x1", "v1", "acc1"):
+            source_path = f"{signal_name}@{alias}"
+            duplicate_path = f"{signal_name}dup@{alias}"
+            series_by_data_path[duplicate_path] = tuple(
+                -value for value in amesim_results.series(source_path)
+            )
+    return series_by_data_path
+
+
+def _compute_inactive_mass_force_series(
+    amesim_results: AmesimResults,
+    mechanical_assembly: TestMqlMechanicalAssembly,
+) -> dict[str, tuple[float, ...]]:
+    series_by_data_path: dict[str, tuple[float, ...]] = {}
+    for alias in sorted(mechanical_assembly.masses):
+        mass = mechanical_assembly.masses[alias].endstop()
+        x1 = amesim_results.series(f"x1@{alias}")
+        v1 = amesim_results.series(f"v1@{alias}")
+        series_by_data_path[f"Fmin@{alias}"] = tuple(
+            mass.lower_static_force_magnitude(displacement)
+            for displacement in x1
+        )
+        series_by_data_path[f"Fvisc@{alias}"] = tuple(
+            mass.viscous_friction_force(velocity)
+            for velocity in v1
+        )
+        series_by_data_path[f"Ffric@{alias}"] = tuple(0.0 for _ in x1)
+    return series_by_data_path
+
+
+def _compute_zero_force_source_series(
+    amesim_results: AmesimResults,
+    mechanical_assembly: TestMqlMechanicalAssembly,
+) -> dict[str, tuple[float, ...]]:
+    return {
+        f"fzero@{alias}": tuple(0.0 for _ in amesim_results.times)
+        for alias in sorted(mechanical_assembly.zero_force_sources)
+    }
+
+
+def _compute_chamber_duplicate_series(
+    amesim_results: AmesimResults,
+    observation_catalog: TestMqlObservationCatalog,
+) -> dict[str, tuple[float, ...]]:
+    series_by_data_path: dict[str, tuple[float, ...]] = {}
+    for binding in observation_catalog.chambers.bindings:
+        pressure_series = amesim_results.series(binding.pressure_path)
+        temperature_series = amesim_results.series(binding.temperature_path)
+        for duplicate_path in binding.pressure_duplicate_paths:
+            series_by_data_path[duplicate_path] = tuple(pressure_series)
+        for duplicate_path in binding.temperature_duplicate_paths:
+            series_by_data_path[duplicate_path] = tuple(temperature_series)
+    return series_by_data_path
+
+
+def _compute_orifice_reversed_series(
+    amesim_results: AmesimResults,
+    observation_catalog: TestMqlObservationCatalog,
+) -> dict[str, tuple[float, ...]]:
+    series_by_data_path: dict[str, tuple[float, ...]] = {}
+    for binding in observation_catalog.orifices.bindings:
+        series_by_data_path[binding.reversed_mass_flow_path] = tuple(
+            -value for value in amesim_results.series(binding.primary_mass_flow_path)
+        )
+        series_by_data_path[binding.reversed_enthalpy_flow_path] = tuple(
+            -value for value in amesim_results.series(binding.primary_enthalpy_flow_path)
+        )
+    return series_by_data_path
+
+
+def _compute_line_reversed_series(
+    amesim_results: AmesimResults,
+    observation_catalog: TestMqlObservationCatalog,
+) -> dict[str, tuple[float, ...]]:
+    series_by_data_path: dict[str, tuple[float, ...]] = {}
+    for binding in observation_catalog.lines.by_submodel("PNL00R"):
+        if len(binding.mass_flow_paths) != 2 or len(binding.enthalpy_flow_paths) != 2:
+            raise ValueError(f"Expected two PNL00R flow paths for {binding.alias}.")
+        primary_mass_path, reversed_mass_path = binding.mass_flow_paths
+        primary_enthalpy_path, reversed_enthalpy_path = binding.enthalpy_flow_paths
+        series_by_data_path[reversed_mass_path] = tuple(
+            -value for value in amesim_results.series(primary_mass_path)
+        )
+        series_by_data_path[reversed_enthalpy_path] = tuple(
+            -value for value in amesim_results.series(primary_enthalpy_path)
+        )
+    return series_by_data_path
+
@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import ast
+import operator
+from dataclasses import dataclass
+from math import isfinite
+from typing import Any
+
+from app.simulation.core.peng_robinson import HELIUM_PR, PengRobinsonFluid
+from app.simulation.examples.test_mql.system import COMPONENT_SPECS, GLOBAL_PARAMETERS
+
+
+_BINARY_OPERATORS = {
+    ast.Add: operator.add,
+    ast.Sub: operator.sub,
+    ast.Mult: operator.mul,
+    ast.Div: operator.truediv,
+    ast.Pow: operator.pow,
+}
+_UNARY_OPERATORS = {
+    ast.UAdd: operator.pos,
+    ast.USub: operator.neg,
+}
+
+
+class TestMqlExpressionError(ValueError):
+    """Raised when an AMESim parameter expression cannot be resolved safely."""
+
+
+@dataclass(frozen=True)
+class TestMqlResolvedParameter:
+    name: str
+    title: str
+    raw_value: str
+    units: str
+    value: float | None
+
+    @property
+    def is_numeric(self) -> bool:
+        return self.value is not None
+
+
+@dataclass(frozen=True)
+class TestMqlResolvedComponent:
+    alias: str
+    component_name: str
+    submodel: str
+    label: str
+    parameters: dict[str, TestMqlResolvedParameter]
+
+    def parameter_value(self, name: str) -> float:
+        parameter = self.parameters[name]
+        if parameter.value is None:
+            raise KeyError(f"Parameter {name!r} on {self.alias!r} is not numeric")
+        return parameter.value
+
+
+@dataclass(frozen=True)
+class TestMqlConfig:
+    raw_global_parameters: dict[str, str]
+    global_parameters: dict[str, float]
+    fluid: PengRobinsonFluid
+    components: tuple[TestMqlResolvedComponent, ...]
+
+    @classmethod
+    def from_amesim_specs(cls) -> "TestMqlConfig":
+        raw_globals = dict(GLOBAL_PARAMETERS)
+        numeric_globals = {
+            name: value
+            for name, raw in raw_globals.items()
+            if (value := resolve_numeric_expression(raw, {})) is not None
+        }
+        components = tuple(
+            _resolve_component(spec, numeric_globals)
+            for spec in COMPONENT_SPECS
+        )
+        return cls(
+            raw_global_parameters=raw_globals,
+            global_parameters=numeric_globals,
+            fluid=HELIUM_PR,
+            components=components,
+        )
+
+    def component(self, alias: str) -> TestMqlResolvedComponent:
+        for component in self.components:
+            if component.alias == alias:
+                return component
+        raise KeyError(alias)
+
+    def components_by_submodel(self, submodel: str) -> tuple[TestMqlResolvedComponent, ...]:
+        return tuple(component for component in self.components if component.submodel == submodel)
+
+
+def _resolve_component(
+    spec: dict[str, Any],
+    variables: dict[str, float],
+) -> TestMqlResolvedComponent:
+    parameters = {}
+    for parameter in spec.get("parameters", []):
+        name = str(parameter["name"])
+        raw_value = str(parameter["value"])
+        parameters[name] = TestMqlResolvedParameter(
+            name=name,
+            title=str(parameter["title"]),
+            raw_value=raw_value,
+            units=str(parameter["units"]),
+            value=resolve_numeric_expression(raw_value, variables),
+        )
+    return TestMqlResolvedComponent(
+        alias=str(spec["alias"]),
+        component_name=str(spec["component_name"]),
+        submodel=str(spec["submodel"]),
+        label=str(spec["label"]),
+        parameters=parameters,
+    )
+
+
+def resolve_numeric_expression(
+    expression: str,
+    variables: dict[str, float],
+) -> float | None:
+    expression = expression.strip()
+    if not expression:
+        return None
+    normalized = expression.replace("^", "**")
+    try:
+        parsed = ast.parse(normalized, mode="eval")
+        value = float(_eval_node(parsed.body, variables))
+    except (SyntaxError, TestMqlExpressionError, ValueError, TypeError, ZeroDivisionError):
+        return None
+    return value if isfinite(value) else None
+
+
+def _eval_node(node: ast.AST, variables: dict[str, float]) -> float:
+    if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):
+        return float(node.value)
+    if isinstance(node, ast.Name):
+        if node.id not in variables:
+            raise TestMqlExpressionError(f"Unknown variable: {node.id}")
+        return float(variables[node.id])
+    if isinstance(node, ast.BinOp):
+        operator_type = type(node.op)
+        if operator_type not in _BINARY_OPERATORS:
+            raise TestMqlExpressionError(f"Unsupported binary operator: {operator_type}")
+        return float(_BINARY_OPERATORS[operator_type](_eval_node(node.left, variables), _eval_node(node.right, variables)))
+    if isinstance(node, ast.UnaryOp):
+        operator_type = type(node.op)
+        if operator_type not in _UNARY_OPERATORS:
+            raise TestMqlExpressionError(f"Unsupported unary operator: {operator_type}")
+        return float(_UNARY_OPERATORS[operator_type](_eval_node(node.operand, variables)))
+    raise TestMqlExpressionError(f"Unsupported expression node: {type(node)}")
@@ -0,0 +1,451 @@
+from __future__ import annotations
+
+import re
+import tarfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from app.simulation.examples.test_mql.system import CONNECTION_SPECS, GLOBAL_PARAMETERS
+from app.simulation.examples.test_mql.config import resolve_numeric_expression
+
+
+AMESIM_REFERENCE_PRESSURE_PA = 101_300.0
+
+
+@dataclass(frozen=True)
+class TestMqlPnl0001Spec:
+    alias: str
+    source_component: str
+    source_port: str
+    target_component: str
+    target_port: str
+    diameter_mm: float
+    length_m: float
+    relative_roughness: float
+    polytropic_constant: float
+    heat_transfer_coefficient: float
+    external_temperature_k: float
+    gas_type_index: int
+    mode: int
+    initial_temperature_k: float
+    initial_gauge_pressure_pa: float
+
+    @property
+    def initial_absolute_pressure_pa(self) -> float:
+        return self.initial_gauge_pressure_pa + AMESIM_REFERENCE_PRESSURE_PA
+
+
+@dataclass(frozen=True)
+class TestMqlPnl0002Spec:
+    alias: str
+    source_component: str
+    source_port: str
+    target_component: str
+    target_port: str
+    diameter_mm: float
+    length_m: float
+    relative_roughness: float
+    polytropic_constant: float
+    heat_transfer_coefficient: float
+    external_temperature_k: float
+    gas_type_index: int
+    mode: int
+    initial_center_temperature_k: float
+    initial_center_gauge_pressure_pa: float
+
+    @property
+    def initial_center_absolute_pressure_pa(self) -> float:
+        return self.initial_center_gauge_pressure_pa + AMESIM_REFERENCE_PRESSURE_PA
+
+
+@dataclass(frozen=True)
+class TestMqlPnl0003Spec:
+    alias: str
+    source_component: str
+    source_port: str
+    target_component: str
+    target_port: str
+    diameter_mm: float
+    length_m: float
+    relative_roughness: float
+    polytropic_constant: float
+    heat_transfer_coefficient: float
+    external_temperature_k: float
+    gas_type_index: int
+    mode: int
+    initial_temperature_1_k: float
+    initial_gauge_pressure_1_pa: float
+    initial_temperature_2_k: float
+    initial_gauge_pressure_2_pa: float
+
+    @property
+    def initial_absolute_pressure_1_pa(self) -> float:
+        return self.initial_gauge_pressure_1_pa + AMESIM_REFERENCE_PRESSURE_PA
+
+    @property
+    def initial_absolute_pressure_2_pa(self) -> float:
+        return self.initial_gauge_pressure_2_pa + AMESIM_REFERENCE_PRESSURE_PA
+
+
+@dataclass(frozen=True)
+class TestMqlPnl00rSpec:
+    alias: str
+    source_component: str
+    source_port: str
+    target_component: str
+    target_port: str
+    diameter_mm: float
+    length_m: float
+    relative_roughness: float
+    gas_type_index: int
+
+
+def load_test_mql_pnl0001_specs(
+    archive_path: str | Path,
+    *,
+    cir_member: str = "test_mql_.cir",
+) -> tuple[TestMqlPnl0001Spec, ...]:
+    """Load resolved PNL0001 geometry and initial states from the AMESim source."""
+    with tarfile.open(archive_path) as archive:
+        cir_file = archive.extractfile(cir_member)
+        if cir_file is None:
+            raise ValueError(f"Missing AMESim circuit member: {cir_member}")
+        cir_text = cir_file.read().decode("latin1")
+
+    numeric_globals = {
+        name: value
+        for name, expression in GLOBAL_PARAMETERS.items()
+        if (value := resolve_numeric_expression(expression, {})) is not None
+    }
+    connections = {
+        str(connection["alias"]): connection
+        for connection in CONNECTION_SPECS
+        if connection["submodel"] == "PNL0001"
+    }
+    specs = []
+    for block in re.findall(r"<LINE>.*?</LINE>", cir_text, flags=re.DOTALL):
+        if _optional_text(block, "SUB_NAME") != "PNL0001":
+            continue
+        alias = _required_text(block, "ALIAS")
+        connection = connections.get(alias)
+        if connection is None:
+            raise ValueError(f"PNL0001 line {alias!r} is absent from CONNECTION_SPECS")
+        real_parameters = _parameter_expressions(block, "RPARAM")
+        integer_parameters = _parameter_expressions(block, "IPARAM")
+        state_values = _evar_values(block)
+        specs.append(
+            TestMqlPnl0001Spec(
+                alias=alias,
+                source_component=str(connection["source_component"]),
+                source_port=str(connection["source_port"]),
+                target_component=str(connection["target_component"]),
+                target_port=str(connection["target_port"]),
+                diameter_mm=_required_numeric(
+                    alias, "diam", real_parameters, numeric_globals
+                ),
+                length_m=_required_numeric(alias, "le", real_parameters, numeric_globals),
+                relative_roughness=_required_numeric(
+                    alias, "rr", real_parameters, numeric_globals
+                ),
+                polytropic_constant=_required_numeric(
+                    alias, "k", real_parameters, numeric_globals
+                ),
+                heat_transfer_coefficient=_required_numeric(
+                    alias, "kth", real_parameters, numeric_globals
+                ),
+                external_temperature_k=_required_numeric(
+                    alias, "extemp", real_parameters, numeric_globals
+                ),
+                gas_type_index=int(
+                    _required_numeric(alias, "gi", integer_parameters, numeric_globals)
+                ),
+                mode=int(
+                    _required_numeric(alias, "mode", integer_parameters, numeric_globals)
+                ),
+                initial_temperature_k=_required_numeric(
+                    alias, "t2", state_values, numeric_globals
+                ),
+                initial_gauge_pressure_pa=_required_numeric(
+                    alias, "p2", state_values, numeric_globals
+                ),
+            )
+        )
+    if set(connections) != {spec.alias for spec in specs}:
+        missing = sorted(set(connections) - {spec.alias for spec in specs})
+        raise ValueError(f"Missing PNL0001 parameter blocks: {missing}")
+    return tuple(specs)
+
+
+def load_test_mql_pnl0002_specs(
+    archive_path: str | Path,
+    *,
+    cir_member: str = "test_mql_.cir",
+) -> tuple[TestMqlPnl0002Spec, ...]:
+    """Load resolved PNL0002 geometry and center compliance initial state."""
+    with tarfile.open(archive_path) as archive:
+        cir_file = archive.extractfile(cir_member)
+        if cir_file is None:
+            raise ValueError(f"Missing AMESim circuit member: {cir_member}")
+        cir_text = cir_file.read().decode("latin1")
+
+    numeric_globals = {
+        name: value
+        for name, expression in GLOBAL_PARAMETERS.items()
+        if (value := resolve_numeric_expression(expression, {})) is not None
+    }
+    connections = {
+        str(connection["alias"]): connection
+        for connection in CONNECTION_SPECS
+        if connection["submodel"] == "PNL0002"
+    }
+    specs = []
+    for block in re.findall(r"<LINE>.*?</LINE>", cir_text, flags=re.DOTALL):
+        if _optional_text(block, "SUB_NAME") != "PNL0002":
+            continue
+        alias = _required_text(block, "ALIAS")
+        connection = connections.get(alias)
+        if connection is None:
+            raise ValueError(f"PNL0002 line {alias!r} is absent from CONNECTION_SPECS")
+        real_parameters = _parameter_expressions(block, "RPARAM")
+        integer_parameters = _parameter_expressions(block, "IPARAM")
+        state_values = _ivar_values(block)
+        specs.append(
+            TestMqlPnl0002Spec(
+                alias=alias,
+                source_component=str(connection["source_component"]),
+                source_port=str(connection["source_port"]),
+                target_component=str(connection["target_component"]),
+                target_port=str(connection["target_port"]),
+                diameter_mm=_required_numeric(
+                    alias, "diam", real_parameters, numeric_globals
+                ),
+                length_m=_required_numeric(alias, "le", real_parameters, numeric_globals),
+                relative_roughness=_required_numeric(
+                    alias, "rr", real_parameters, numeric_globals
+                ),
+                polytropic_constant=_required_numeric(
+                    alias, "k", real_parameters, numeric_globals
+                ),
+                heat_transfer_coefficient=_required_numeric(
+                    alias, "kth", real_parameters, numeric_globals
+                ),
+                external_temperature_k=_required_numeric(
+                    alias, "extemp", real_parameters, numeric_globals
+                ),
+                gas_type_index=int(
+                    _required_numeric(alias, "gi", integer_parameters, numeric_globals)
+                ),
+                mode=int(
+                    _required_numeric(alias, "mode", integer_parameters, numeric_globals)
+                ),
+                initial_center_temperature_k=_required_numeric(
+                    alias, "tctr", state_values, numeric_globals
+                ),
+                initial_center_gauge_pressure_pa=_required_numeric(
+                    alias, "pctr", state_values, numeric_globals
+                ),
+            )
+        )
+    if set(connections) != {spec.alias for spec in specs}:
+        missing = sorted(set(connections) - {spec.alias for spec in specs})
+        raise ValueError(f"Missing PNL0002 parameter blocks: {missing}")
+    return tuple(specs)
+
+
+def load_test_mql_pnl0003_specs(
+    archive_path: str | Path,
+    *,
+    cir_member: str = "test_mql_.cir",
+) -> tuple[TestMqlPnl0003Spec, ...]:
+    """Load resolved PNL0003 geometry and both compliance initial states."""
+    with tarfile.open(archive_path) as archive:
+        cir_file = archive.extractfile(cir_member)
+        if cir_file is None:
+            raise ValueError(f"Missing AMESim circuit member: {cir_member}")
+        cir_text = cir_file.read().decode("latin1")
+
+    numeric_globals = {
+        name: value
+        for name, expression in GLOBAL_PARAMETERS.items()
+        if (value := resolve_numeric_expression(expression, {})) is not None
+    }
+    connections = {
+        str(connection["alias"]): connection
+        for connection in CONNECTION_SPECS
+        if connection["submodel"] == "PNL0003"
+    }
+    specs = []
+    for block in re.findall(r"<LINE>.*?</LINE>", cir_text, flags=re.DOTALL):
+        if _optional_text(block, "SUB_NAME") != "PNL0003":
+            continue
+        alias = _required_text(block, "ALIAS")
+        connection = connections.get(alias)
+        if connection is None:
+            raise ValueError(f"PNL0003 line {alias!r} is absent from CONNECTION_SPECS")
+        real_parameters = _parameter_expressions(block, "RPARAM")
+        integer_parameters = _parameter_expressions(block, "IPARAM")
+        state_values = _evar_values(block)
+        specs.append(
+            TestMqlPnl0003Spec(
+                alias=alias,
+                source_component=str(connection["source_component"]),
+                source_port=str(connection["source_port"]),
+                target_component=str(connection["target_component"]),
+                target_port=str(connection["target_port"]),
+                diameter_mm=_required_numeric(
+                    alias, "diam", real_parameters, numeric_globals
+                ),
+                length_m=_required_numeric(alias, "le", real_parameters, numeric_globals),
+                relative_roughness=_required_numeric(
+                    alias, "rr", real_parameters, numeric_globals
+                ),
+                polytropic_constant=_required_numeric(
+                    alias, "k", real_parameters, numeric_globals
+                ),
+                heat_transfer_coefficient=_required_numeric(
+                    alias, "kth", real_parameters, numeric_globals
+                ),
+                external_temperature_k=_required_numeric(
+                    alias, "extemp", real_parameters, numeric_globals
+                ),
+                gas_type_index=int(
+                    _required_numeric(alias, "gi", integer_parameters, numeric_globals)
+                ),
+                mode=int(
+                    _required_numeric(alias, "mode", integer_parameters, numeric_globals)
+                ),
+                initial_temperature_1_k=_required_numeric(
+                    alias, "t1", state_values, numeric_globals
+                ),
+                initial_gauge_pressure_1_pa=_required_numeric(
+                    alias, "p1", state_values, numeric_globals
+                ),
+                initial_temperature_2_k=_required_numeric(
+                    alias, "t2", state_values, numeric_globals
+                ),
+                initial_gauge_pressure_2_pa=_required_numeric(
+                    alias, "p2", state_values, numeric_globals
+                ),
+            )
+        )
+    if set(connections) != {spec.alias for spec in specs}:
+        missing = sorted(set(connections) - {spec.alias for spec in specs})
+        raise ValueError(f"Missing PNL0003 parameter blocks: {missing}")
+    return tuple(specs)
+
+
+def load_test_mql_pnl00r_specs(
+    archive_path: str | Path,
+    *,
+    cir_member: str = "test_mql_.cir",
+) -> tuple[TestMqlPnl00rSpec, ...]:
+    """Load resolved PNL00R geometry from the AMESim source."""
+    with tarfile.open(archive_path) as archive:
+        cir_file = archive.extractfile(cir_member)
+        if cir_file is None:
+            raise ValueError(f"Missing AMESim circuit member: {cir_member}")
+        cir_text = cir_file.read().decode("latin1")
+
+    numeric_globals = {
+        name: value
+        for name, expression in GLOBAL_PARAMETERS.items()
+        if (value := resolve_numeric_expression(expression, {})) is not None
+    }
+    connections = {
+        str(connection["alias"]): connection
+        for connection in CONNECTION_SPECS
+        if connection["submodel"] == "PNL00R"
+    }
+    specs = []
+    for block in re.findall(r"<LINE>.*?</LINE>", cir_text, flags=re.DOTALL):
+        if _optional_text(block, "SUB_NAME") != "PNL00R":
+            continue
+        alias = _required_text(block, "ALIAS")
+        connection = connections.get(alias)
+        if connection is None:
+            raise ValueError(f"PNL00R line {alias!r} is absent from CONNECTION_SPECS")
+        real_parameters = _parameter_expressions(block, "RPARAM")
+        integer_parameters = _parameter_expressions(block, "IPARAM")
+        specs.append(
+            TestMqlPnl00rSpec(
+                alias=alias,
+                source_component=str(connection["source_component"]),
+                source_port=str(connection["source_port"]),
+                target_component=str(connection["target_component"]),
+                target_port=str(connection["target_port"]),
+                diameter_mm=_required_numeric(
+                    alias, "diam", real_parameters, numeric_globals
+                ),
+                length_m=_required_numeric(alias, "le", real_parameters, numeric_globals),
+                relative_roughness=_required_numeric(
+                    alias, "rr", real_parameters, numeric_globals
+                ),
+                gas_type_index=int(
+                    _required_numeric(alias, "gi", integer_parameters, numeric_globals)
+                ),
+            )
+        )
+    if set(connections) != {spec.alias for spec in specs}:
+        missing = sorted(set(connections) - {spec.alias for spec in specs})
+        raise ValueError(f"Missing PNL00R parameter blocks: {missing}")
+    return tuple(specs)
+
+
+def _parameter_expressions(block: str, tag_name: str) -> dict[str, str]:
+    parameters = {}
+    for parameter_block in re.findall(
+        rf"<{tag_name}>.*?</{tag_name}>",
+        block,
+        flags=re.DOTALL,
+    ):
+        parameters[_required_text(parameter_block, "VARNAME")] = _required_text(
+            parameter_block,
+            "VALUE",
+        )
+    return parameters
+
+
+def _ivar_values(block: str) -> dict[str, str]:
+    values = {}
+    for variable_block in re.findall(r"<IVAR>.*?</IVAR>", block, flags=re.DOTALL):
+        value = _optional_text(variable_block, "VALUE")
+        if value:
+            values[_required_text(variable_block, "VARNAME")] = value
+    return values
+
+
+def _evar_values(block: str) -> dict[str, str]:
+    values = {}
+    for variable_block in re.findall(r"<EVAR>.*?</EVAR>", block, flags=re.DOTALL):
+        value = _optional_text(variable_block, "VALUE")
+        if value:
+            values[_required_text(variable_block, "VARNAME")] = value
+    return values
+
+
+def _required_numeric(
+    alias: str,
+    name: str,
+    expressions: dict[str, str],
+    variables: dict[str, float],
+) -> float:
+    if name not in expressions:
+        raise ValueError(f"Missing {name!r} on line {alias!r}")
+    value = resolve_numeric_expression(expressions[name], variables)
+    if value is None:
+        raise ValueError(
+            f"Cannot resolve {name!r}={expressions[name]!r} on line {alias!r}"
+        )
+    return value
+
+
+def _required_text(block: str, tag_name: str) -> str:
+    value = _optional_text(block, tag_name)
+    if value is None:
+        raise ValueError(f"Missing AMESim circuit element: {tag_name}")
+    return value
+
+
+def _optional_text(block: str, tag_name: str) -> str | None:
+    match = re.search(rf"<{tag_name}>(.*?)</{tag_name}>", block, flags=re.DOTALL)
+    return match.group(1).strip() if match is not None else None
@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import re
+from collections import Counter
+from dataclasses import dataclass
+
+from app.simulation.reporting.amesim_results import AmesimResults
+from app.simulation.reporting.test_mql_variables import (
+    TestMqlVariableCatalog,
+    build_test_mql_variable_catalog,
+)
+from app.simulation.examples.test_mql.system import CONNECTION_SPECS
+
+
+TEST_MQL_PNEUMATIC_LINE_SUBMODELS = ("PNL0001", "PNL0002", "PNL0003", "PNL00R")
+_LINE_PATTERN_RE = re.compile(r"\(([^()]+)\)\s*$")
+
+
+@dataclass(frozen=True)
+class TestMqlLineConnection:
+    index: int
+    alias: str
+    submodel: str
+    pattern: str
+    source_component: str
+    source_port: str
+    target_component: str
+    target_port: str
+    label: str
+    data_paths: tuple[str, ...]
+    signal_names: tuple[str, ...]
+
+    @property
+    def has_compliance(self) -> bool:
+        return "C" in self.pattern
+
+    @property
+    def has_resistance(self) -> bool:
+        return "R" in self.pattern
+
+
+@dataclass(frozen=True)
+class TestMqlLineAssembly:
+    lines: tuple[TestMqlLineConnection, ...]
+
+    @property
+    def line_count(self) -> int:
+        return len(self.lines)
+
+    def by_alias(self, alias: str) -> TestMqlLineConnection:
+        for line in self.lines:
+            if line.alias == alias:
+                return line
+        raise KeyError(alias)
+
+    def by_submodel(self, submodel: str) -> tuple[TestMqlLineConnection, ...]:
+        return tuple(line for line in self.lines if line.submodel == submodel)
+
+    def counts_by_submodel(self) -> dict[str, int]:
+        return dict(Counter(line.submodel for line in self.lines))
+
+    def aliases(self) -> tuple[str, ...]:
+        return tuple(line.alias for line in self.lines)
+
+
+def build_test_mql_line_assembly(
+    amesim_results: AmesimResults,
+    variable_catalog: TestMqlVariableCatalog | None = None,
+) -> TestMqlLineAssembly:
+    variable_catalog = variable_catalog or build_test_mql_variable_catalog(amesim_results)
+    lines = []
+    for spec in CONNECTION_SPECS:
+        submodel = str(spec["submodel"])
+        if submodel not in TEST_MQL_PNEUMATIC_LINE_SUBMODELS:
+            continue
+        data_paths = variable_catalog.data_paths_for_owner(str(spec["alias"]))
+        signal_names = tuple(path.rsplit("@", 1)[0] for path in data_paths)
+        lines.append(
+            TestMqlLineConnection(
+                index=int(spec["index"]),
+                alias=str(spec["alias"]),
+                submodel=submodel,
+                pattern=_line_pattern(str(spec["label"]), submodel),
+                source_component=str(spec["source_component"]),
+                source_port=str(spec["source_port"]),
+                target_component=str(spec["target_component"]),
+                target_port=str(spec["target_port"]),
+                label=str(spec["label"]),
+                data_paths=data_paths,
+                signal_names=signal_names,
+            )
+        )
+    return TestMqlLineAssembly(lines=tuple(lines))
+
+
+def _line_pattern(label: str, submodel: str) -> str:
+    match = _LINE_PATTERN_RE.search(label)
+    if match is not None:
+        return match.group(1)
+    if submodel == "PNL00R":
+        return "R"
+    return submodel
@@ -0,0 +1,544 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from app.simulation.examples.test_mql.primitives.mechanical import (
+    AmesimElasticEndstop,
+    AmesimMassFrictionEndstops,
+    AmesimPistonGeometry,
+    circular_area,
+    mm_to_m,
+)
+from app.simulation.reporting.amesim_results import AmesimResults
+from app.simulation.reporting.test_mql_variables import (
+    TestMqlVariableCatalog,
+    build_test_mql_variable_catalog,
+)
+from app.simulation.examples.test_mql.config import TestMqlConfig, TestMqlResolvedComponent
+
+
+MM_TO_M = 1.0e-3
+N_PER_MM_TO_N_PER_M = 1.0e3
+N_PER_MM_PER_S_TO_N_PER_M_PER_S = 1.0e3
+
+
+@dataclass(frozen=True)
+class TestMqlPistonSpec:
+    alias: str
+    piston_diameter_m: float
+    rod_diameter_m: float
+    zero_displacement_m: float
+    piston_area_m2: float
+    rod_area_m2: float
+    annulus_area_m2: float
+    data_paths: tuple[str, ...]
+
+    def geometry(self) -> AmesimPistonGeometry:
+        return AmesimPistonGeometry(
+            piston_diameter_m=self.piston_diameter_m,
+            rod_diameter_m=self.rod_diameter_m,
+            zero_length_m=self.zero_displacement_m,
+        )
+
+
+@dataclass(frozen=True)
+class TestMqlMassEndstopSpec:
+    alias: str
+    mass_kg: float
+    xmin_m: float
+    xmax_m: float
+    min_stiffness_n_per_m: float
+    max_stiffness_n_per_m: float
+    min_damping_n_per_m_per_s: float
+    max_damping_n_per_m_per_s: float
+    min_penetration_m: float
+    max_penetration_m: float
+    stiction_force_n: float
+    coulomb_friction_n: float
+    viscous_friction_n_per_m_per_s: float
+    windage_n_per_m2_per_s2: float
+    stick_velocity_threshold_m_s: float
+    reset_velocity_threshold_m_s: float
+    rest_coeff: float
+    stribeck_constant_m_s: float
+    use_friction: bool
+    stop_type: int
+    initial_velocity_m_s: float
+    initial_displacement_m: float
+    data_paths: tuple[str, ...]
+
+    def endstop(self) -> AmesimMassFrictionEndstops:
+        return AmesimMassFrictionEndstops(
+            mass_kg=self.mass_kg,
+            lower_limit_m=self.xmin_m,
+            upper_limit_m=self.xmax_m,
+            lower_stiffness_n_per_m=self.min_stiffness_n_per_m,
+            upper_stiffness_n_per_m=self.max_stiffness_n_per_m,
+            lower_damping_n_per_m_per_s=self.min_damping_n_per_m_per_s,
+            upper_damping_n_per_m_per_s=self.max_damping_n_per_m_per_s,
+            viscous_friction_n_per_m_per_s=self.viscous_friction_n_per_m_per_s,
+            coulomb_friction_n=self.coulomb_friction_n,
+            stiction_force_n=self.stiction_force_n,
+            windage_n_per_m2_per_s2=self.windage_n_per_m2_per_s2,
+        )
+
+
+@dataclass(frozen=True)
+class TestMqlElasticEndstopSpec:
+    alias: str
+    gap_m: float
+    contact_stiffness_n_per_m: float
+    contact_damping_n_per_m_per_s: float
+    spring_diameter_m: float
+    wire_diameter_m: float
+    data_paths: tuple[str, ...]
+
+    def endstop(self) -> AmesimElasticEndstop:
+        return AmesimElasticEndstop(
+            contact_stiffness_n_per_m=self.contact_stiffness_n_per_m,
+            contact_damping_n_per_m_per_s=self.contact_damping_n_per_m_per_s,
+            gap0_m=self.gap_m,
+        )
+
+
+@dataclass(frozen=True)
+class TestMqlMechanicalNodeSpec:
+    alias: str
+    port_count: int
+    sum_mode: int
+    data_paths: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class TestMqlPiecewiseLinearSignalSpec:
+    alias: str
+    t_start_s: float
+    starts: tuple[float, ...]
+    ends: tuple[float, ...]
+    durations_s: tuple[float, ...]
+    stage_count: int
+    is_cyclic: bool
+    data_paths: tuple[str, ...]
+
+    def output_at(self, time_s: float) -> float:
+        if self.stage_count <= 0:
+            return 0.0
+        elapsed = max(time_s - self.t_start_s, 0.0)
+        active_durations = self.durations_s[: self.stage_count]
+        total_duration = sum(active_durations)
+        if self.is_cyclic and total_duration > 0.0:
+            elapsed = elapsed % total_duration
+
+        stage_start_time = 0.0
+        for index, duration in enumerate(active_durations):
+            stage_end_time = stage_start_time + duration
+            if elapsed < stage_end_time or index == self.stage_count - 1:
+                if duration <= 0.0:
+                    return self.ends[index]
+                fraction = (elapsed - stage_start_time) / duration
+                return self.starts[index] + fraction * (self.ends[index] - self.starts[index])
+            stage_start_time = stage_end_time
+        return self.ends[self.stage_count - 1]
+
+
+@dataclass(frozen=True)
+class TestMqlForceConnectorSpec:
+    alias: str
+    signal_alias: str
+    target_mass_alias: str
+    data_paths: tuple[str, ...]
+
+    def force_at(
+        self,
+        time_s: float,
+        signals: dict[str, TestMqlPiecewiseLinearSignalSpec],
+    ) -> float:
+        return signals[self.signal_alias].output_at(time_s)
+
+
+@dataclass(frozen=True)
+class TestMqlMechanicalAssembly:
+    pistons: dict[str, TestMqlPistonSpec]
+    masses: dict[str, TestMqlMassEndstopSpec]
+    elastic_endstops: dict[str, TestMqlElasticEndstopSpec]
+    mechanical_nodes: dict[str, TestMqlMechanicalNodeSpec]
+    piecewise_signals: dict[str, TestMqlPiecewiseLinearSignalSpec]
+    force_connectors: dict[str, TestMqlForceConnectorSpec]
+    zero_force_sources: tuple[str, ...]
+
+    @property
+    def component_count(self) -> int:
+        return (
+            len(self.pistons)
+            + len(self.masses)
+            + len(self.elastic_endstops)
+            + len(self.mechanical_nodes)
+            + len(self.piecewise_signals)
+            + len(self.force_connectors)
+            + len(self.zero_force_sources)
+        )
+
+    @property
+    def aliases(self) -> tuple[str, ...]:
+        return tuple(
+            [
+                *self.pistons,
+                *self.masses,
+                *self.elastic_endstops,
+                *self.mechanical_nodes,
+                *self.piecewise_signals,
+                *self.force_connectors,
+                *self.zero_force_sources,
+            ]
+        )
+
+
+@dataclass(frozen=True)
+class TestMqlMechanicalMassState:
+    alias: str
+    velocity_m_s: float
+    displacement_m: float
+
+    def as_vector(self) -> list[float]:
+        return [self.velocity_m_s, self.displacement_m]
+
+
+@dataclass(frozen=True)
+class TestMqlMechanicalNodeKinematics:
+    alias: str
+    velocities_m_s: dict[int, float]
+    displacements_m: dict[int, float]
+
+
+@dataclass(frozen=True)
+class TestMqlPistonKinematics:
+    alias: str
+    port_2_velocity_m_s: float
+    port_2_displacement_m: float
+    port_3_velocity_m_s: float
+    port_3_displacement_m: float
+
+
+@dataclass(frozen=True)
+class TestMqlMechanicalMassSnapshot:
+    states: tuple[TestMqlMechanicalMassState, ...]
+    node_kinematics_by_alias: dict[str, TestMqlMechanicalNodeKinematics]
+    piston_kinematics_by_alias: dict[str, TestMqlPistonKinematics]
+
+    @property
+    def state_count(self) -> int:
+        return 2 * len(self.states)
+
+
+class TestMqlMechanicalMassClosure:
+    def __init__(self, assembly: TestMqlMechanicalAssembly) -> None:
+        self.assembly = assembly
+        self.mass_aliases = tuple(assembly.masses)
+
+    def initial_state_vector(self) -> list[float]:
+        state: list[float] = []
+        for alias in self.mass_aliases:
+            spec = self.assembly.masses[alias]
+            state.extend([spec.initial_velocity_m_s, spec.initial_displacement_m])
+        return state
+
+    def snapshot(self, state_vector: list[float] | None = None) -> TestMqlMechanicalMassSnapshot:
+        values = self.initial_state_vector() if state_vector is None else list(state_vector)
+        if len(values) != 2 * len(self.mass_aliases):
+            raise ValueError("mechanical mass state vector requires two values per mass")
+        states = tuple(
+            TestMqlMechanicalMassState(
+                alias=alias,
+                velocity_m_s=values[2 * index],
+                displacement_m=values[2 * index + 1],
+            )
+            for index, alias in enumerate(self.mass_aliases)
+        )
+        node_kinematics = self._node_kinematics_by_alias(states)
+        return TestMqlMechanicalMassSnapshot(
+            states=states,
+            node_kinematics_by_alias=node_kinematics,
+            piston_kinematics_by_alias=self._piston_kinematics_by_alias(
+                states,
+                node_kinematics,
+            ),
+        )
+
+    def _node_kinematics_by_alias(
+        self,
+        states: tuple[TestMqlMechanicalMassState, ...],
+    ) -> dict[str, TestMqlMechanicalNodeKinematics]:
+        state_by_alias = {state.alias: state for state in states}
+        front = state_by_alias["mass_friction_endstops_18"]
+        rear = state_by_alias["mass_friction_endstops_19"]
+        return {
+            "dynamic_mechanical_node_alternative_2": TestMqlMechanicalNodeKinematics(
+                alias="dynamic_mechanical_node_alternative_2",
+                velocities_m_s={port: -front.velocity_m_s for port in range(1, 9)},
+                displacements_m={port: -front.displacement_m for port in range(1, 9)},
+            ),
+            "dynamic_mechanical_node_alternative_3": TestMqlMechanicalNodeKinematics(
+                alias="dynamic_mechanical_node_alternative_3",
+                velocities_m_s={port: rear.velocity_m_s for port in range(1, 9)},
+                displacements_m={port: rear.displacement_m for port in range(1, 9)},
+            ),
+        }
+
+    def _piston_kinematics_by_alias(
+        self,
+        states: tuple[TestMqlMechanicalMassState, ...],
+        node_kinematics_by_alias: dict[str, TestMqlMechanicalNodeKinematics],
+    ) -> dict[str, TestMqlPistonKinematics]:
+        state_by_alias = {state.alias: state for state in states}
+        rear_node = node_kinematics_by_alias["dynamic_mechanical_node_alternative_3"]
+        piston_bindings = (
+            ("pn_brp2_8", "mass_friction_endstops_10", 8),
+            ("pn_brp2_9", "mass_friction_endstops_11", 7),
+            ("pn_brp2_10", "mass_friction_endstops_12", 6),
+            ("pn_brp2_11", "mass_friction_endstops_13", 5),
+            ("pn_brp2_12", "mass_friction_endstops_14", 4),
+            ("pn_brp2_13", "mass_friction_endstops_15", 3),
+            ("pn_brp2_14", "mass_friction_endstops_16", 2),
+            ("pn_brp2_15", "mass_friction_endstops_17", 1),
+        )
+        return {
+            piston_alias: TestMqlPistonKinematics(
+                alias=piston_alias,
+                port_2_velocity_m_s=state_by_alias[mass_alias].velocity_m_s,
+                port_2_displacement_m=state_by_alias[mass_alias].displacement_m,
+                port_3_velocity_m_s=rear_node.velocities_m_s[rear_node_port],
+                port_3_displacement_m=rear_node.displacements_m[rear_node_port],
+            )
+            for piston_alias, mass_alias, rear_node_port in piston_bindings
+        }
+
+    def rhs(
+        self,
+        state_vector: list[float],
+        *,
+        force_by_mass_alias: dict[str, float] | None = None,
+        constrained_mass_aliases: set[str] | None = None,
+    ) -> list[float]:
+        snapshot = self.snapshot(state_vector)
+        force_by_mass_alias = force_by_mass_alias or {}
+        constrained_mass_aliases = constrained_mass_aliases or set()
+        derivatives: list[float] = []
+        for state in snapshot.states:
+            spec = self.assembly.masses[state.alias]
+            mass = spec.endstop()
+            applied_force = force_by_mass_alias.get(state.alias, 0.0)
+            acceleration, velocity = mass.derivatives(
+                velocity_m_s=state.velocity_m_s,
+                displacement_m=state.displacement_m,
+                port_1_force_n=applied_force,
+            )
+            if state.alias in constrained_mass_aliases and _limit_constraint_holds(
+                spec,
+                state,
+                applied_force,
+            ):
+                acceleration = 0.0
+                velocity = 0.0
+            derivatives.extend([acceleration, velocity])
+        return derivatives
+
+
+def build_test_mql_mechanical_assembly(
+    config: TestMqlConfig | None = None,
+    amesim_results: AmesimResults | None = None,
+    variable_catalog: TestMqlVariableCatalog | None = None,
+) -> TestMqlMechanicalAssembly:
+    config = config or TestMqlConfig.from_amesim_specs()
+    if variable_catalog is None and amesim_results is not None:
+        variable_catalog = build_test_mql_variable_catalog(amesim_results)
+
+    pistons = {
+        component.alias: _build_piston(component, variable_catalog)
+        for component in config.components_by_submodel("PNRP17")
+    }
+    masses = {
+        component.alias: _build_mass(component, variable_catalog, amesim_results)
+        for component in config.components_by_submodel("MECMAS21")
+    }
+    elastic_endstops = {
+        component.alias: _build_elastic_endstop(component, variable_catalog)
+        for component in config.components_by_submodel("LSTP00A")
+    }
+    mechanical_nodes = {
+        component.alias: _build_mechanical_node(component, variable_catalog)
+        for component in config.components_by_submodel("LMECHN1")
+    }
+    piecewise_signals = {
+        component.alias: _build_piecewise_signal(component, variable_catalog)
+        for component in config.components_by_submodel("UD00")
+    }
+    force_connectors = {
+        component.alias: _build_force_connector(component, variable_catalog)
+        for component in config.components_by_submodel("FORC")
+    }
+    zero_force_sources = tuple(component.alias for component in config.components_by_submodel("F000"))
+    return TestMqlMechanicalAssembly(
+        pistons=pistons,
+        masses=masses,
+        elastic_endstops=elastic_endstops,
+        mechanical_nodes=mechanical_nodes,
+        piecewise_signals=piecewise_signals,
+        force_connectors=force_connectors,
+        zero_force_sources=zero_force_sources,
+    )
+
+
+def _build_piston(
+    component: TestMqlResolvedComponent,
+    variable_catalog: TestMqlVariableCatalog | None,
+) -> TestMqlPistonSpec:
+    geometry = AmesimPistonGeometry(
+        piston_diameter_m=mm_to_m(component.parameter_value("dp")),
+        rod_diameter_m=mm_to_m(component.parameter_value("dr")),
+        zero_length_m=mm_to_m(component.parameter_value("x0")),
+    )
+    return TestMqlPistonSpec(
+        alias=component.alias,
+        piston_diameter_m=geometry.piston_diameter_m,
+        rod_diameter_m=geometry.rod_diameter_m,
+        zero_displacement_m=geometry.zero_length_m,
+        piston_area_m2=geometry.piston_area_m2,
+        rod_area_m2=geometry.rod_area_m2,
+        annulus_area_m2=geometry.annulus_area_m2,
+        data_paths=_data_paths(variable_catalog, component.alias),
+    )
+
+
+def _build_mass(
+    component: TestMqlResolvedComponent,
+    variable_catalog: TestMqlVariableCatalog | None,
+    amesim_results: AmesimResults | None,
+) -> TestMqlMassEndstopSpec:
+    return TestMqlMassEndstopSpec(
+        alias=component.alias,
+        mass_kg=component.parameter_value("mass"),
+        xmin_m=component.parameter_value("xmin"),
+        xmax_m=component.parameter_value("xmax"),
+        min_stiffness_n_per_m=n_per_mm_to_n_per_m(component.parameter_value("Kbmin")),
+        max_stiffness_n_per_m=n_per_mm_to_n_per_m(component.parameter_value("Kbmax")),
+        min_damping_n_per_m_per_s=n_per_mm_per_s_to_n_per_m_per_s(component.parameter_value("Dbmin")),
+        max_damping_n_per_m_per_s=n_per_mm_per_s_to_n_per_m_per_s(component.parameter_value("Dbmax")),
+        min_penetration_m=mm_to_m(component.parameter_value("Pdmin")),
+        max_penetration_m=mm_to_m(component.parameter_value("Pdmax")),
+        stiction_force_n=component.parameter_value("fstick"),
+        coulomb_friction_n=component.parameter_value("fcoul"),
+        viscous_friction_n_per_m_per_s=component.parameter_value("rvisc"),
+        windage_n_per_m2_per_s2=component.parameter_value("wind"),
+        stick_velocity_threshold_m_s=component.parameter_value("dvel"),
+        reset_velocity_threshold_m_s=component.parameter_value("restdvel"),
+        rest_coeff=component.parameter_value("restcoeff"),
+        stribeck_constant_m_s=component.parameter_value("astrib"),
+        use_friction=int(component.parameter_value("useFriction")) == 2,
+        stop_type=int(component.parameter_value("stoptype")),
+        initial_velocity_m_s=_initial_value(amesim_results, f"v1@{component.alias}"),
+        initial_displacement_m=_initial_value(amesim_results, f"x1@{component.alias}"),
+        data_paths=_data_paths(variable_catalog, component.alias),
+    )
+
+
+def _build_elastic_endstop(
+    component: TestMqlResolvedComponent,
+    variable_catalog: TestMqlVariableCatalog | None,
+) -> TestMqlElasticEndstopSpec:
+    return TestMqlElasticEndstopSpec(
+        alias=component.alias,
+        gap_m=mm_to_m(component.parameter_value("gap0")),
+        contact_stiffness_n_per_m=component.parameter_value("kcont"),
+        contact_damping_n_per_m_per_s=component.parameter_value("rcont"),
+        spring_diameter_m=mm_to_m(component.parameter_value("sdiam")),
+        wire_diameter_m=mm_to_m(component.parameter_value("wdiam")),
+        data_paths=_data_paths(variable_catalog, component.alias),
+    )
+
+
+def _build_mechanical_node(
+    component: TestMqlResolvedComponent,
+    variable_catalog: TestMqlVariableCatalog | None,
+) -> TestMqlMechanicalNodeSpec:
+    return TestMqlMechanicalNodeSpec(
+        alias=component.alias,
+        port_count=int(component.parameter_value("v1")),
+        sum_mode=int(component.parameter_value("sum")),
+        data_paths=_data_paths(variable_catalog, component.alias),
+    )
+
+
+def _limit_constraint_holds(
+    spec: TestMqlMassEndstopSpec,
+    state: TestMqlMechanicalMassState,
+    applied_force_n: float,
+) -> bool:
+    if abs(state.velocity_m_s) > spec.stick_velocity_threshold_m_s:
+        return False
+    at_lower_limit = state.displacement_m <= spec.xmin_m + spec.min_penetration_m
+    at_upper_limit = state.displacement_m >= spec.xmax_m - spec.max_penetration_m
+    return (at_lower_limit and applied_force_n <= 0.0) or (
+        at_upper_limit and applied_force_n >= 0.0
+    )
+
+
+def _build_piecewise_signal(
+    component: TestMqlResolvedComponent,
+    variable_catalog: TestMqlVariableCatalog | None,
+) -> TestMqlPiecewiseLinearSignalSpec:
+    starts = tuple(component.parameter_value(f"start{index}") for index in range(1, 9))
+    ends = tuple(component.parameter_value(f"end{index}") for index in range(1, 9))
+    durations = tuple(component.parameter_value(f"t{index}") for index in range(1, 9))
+    return TestMqlPiecewiseLinearSignalSpec(
+        alias=component.alias,
+        t_start_s=component.parameter_value("tstart"),
+        starts=starts,
+        ends=ends,
+        durations_s=durations,
+        stage_count=int(component.parameter_value("nstages")),
+        is_cyclic=bool(int(component.parameter_value("iscyclic"))),
+        data_paths=_data_paths(variable_catalog, component.alias),
+    )
+
+
+def _build_force_connector(
+    component: TestMqlResolvedComponent,
+    variable_catalog: TestMqlVariableCatalog | None,
+) -> TestMqlForceConnectorSpec:
+    signal_alias_by_force_connector = {
+        "forcecon_1": "piecewiselinear",
+        "forcecon_2": "piecewiselinear_1",
+    }
+    target_mass_by_force_connector = {
+        "forcecon_1": "mass_friction_endstops_19",
+        "forcecon_2": "mass_friction_endstops_18",
+    }
+    return TestMqlForceConnectorSpec(
+        alias=component.alias,
+        signal_alias=signal_alias_by_force_connector[component.alias],
+        target_mass_alias=target_mass_by_force_connector[component.alias],
+        data_paths=_data_paths(variable_catalog, component.alias),
+    )
+
+
+def n_per_mm_to_n_per_m(value: float) -> float:
+    return value * N_PER_MM_TO_N_PER_M
+
+
+def n_per_mm_per_s_to_n_per_m_per_s(value: float) -> float:
+    return value * N_PER_MM_PER_S_TO_N_PER_M_PER_S
+
+
+def _initial_value(amesim_results: AmesimResults | None, data_path: str) -> float:
+    if amesim_results is None:
+        return 0.0
+    return float(amesim_results.series(data_path)[0])
+
+
+def _data_paths(
+    variable_catalog: TestMqlVariableCatalog | None,
+    alias: str,
+) -> tuple[str, ...]:
+    if variable_catalog is None:
+        return ()
+    return variable_catalog.data_paths_for_owner(alias)
@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from app.simulation.examples.test_mql.system import COMPONENT_SPECS
+
+
+@dataclass(frozen=True)
+class TestMqlPneumaticNode3Balance:
+    temperature_k: float
+    pressure_pa: float
+    port_1_enthalpy_flow_w: float
+    port_1_mass_flow_g_s: float
+    port_1_volume_derivative_l_min: float
+    port_1_volume_cm3: float
+    port_2_enthalpy_flow_w: float
+    port_2_mass_flow_g_s: float
+    port_2_volume_derivative_l_min: float
+    port_2_volume_cm3: float
+    port_3_enthalpy_flow_w: float
+    port_3_mass_flow_g_s: float
+    port_3_volume_derivative_l_min: float
+    port_3_volume_cm3: float
+
+
+@dataclass(frozen=True)
+class TestMqlPneumaticNode3:
+    """Exact algebraic contract of AMESim ``PN3NODE2``.
+
+    Pressure and temperature are fixed by port 2 and duplicated to ports 1 and
+    3. Flow and volume signals at port 2 are the sums of ports 1 and 3, matching
+    the ``EXPRESS2`` equations stored in ``test_mql_.cir``.
+    """
+
+    alias: str
+
+    def balance(
+        self,
+        *,
+        port_2_temperature_k: float,
+        port_2_pressure_pa: float,
+        port_1_enthalpy_flow_w: float,
+        port_1_mass_flow_g_s: float,
+        port_3_enthalpy_flow_w: float,
+        port_3_mass_flow_g_s: float,
+        port_1_volume_derivative_l_min: float = 0.0,
+        port_1_volume_cm3: float = 0.0,
+        port_3_volume_derivative_l_min: float = 0.0,
+        port_3_volume_cm3: float = 0.0,
+    ) -> TestMqlPneumaticNode3Balance:
+        if port_2_temperature_k <= 0.0:
+            raise ValueError("port_2_temperature_k must be positive")
+        if port_2_pressure_pa <= 0.0:
+            raise ValueError("port_2_pressure_pa must be positive")
+        return TestMqlPneumaticNode3Balance(
+            temperature_k=port_2_temperature_k,
+            pressure_pa=port_2_pressure_pa,
+            port_1_enthalpy_flow_w=port_1_enthalpy_flow_w,
+            port_1_mass_flow_g_s=port_1_mass_flow_g_s,
+            port_1_volume_derivative_l_min=port_1_volume_derivative_l_min,
+            port_1_volume_cm3=port_1_volume_cm3,
+            port_2_enthalpy_flow_w=(
+                port_1_enthalpy_flow_w + port_3_enthalpy_flow_w
+            ),
+            port_2_mass_flow_g_s=port_1_mass_flow_g_s + port_3_mass_flow_g_s,
+            port_2_volume_derivative_l_min=(
+                port_1_volume_derivative_l_min + port_3_volume_derivative_l_min
+            ),
+            port_2_volume_cm3=port_1_volume_cm3 + port_3_volume_cm3,
+            port_3_enthalpy_flow_w=port_3_enthalpy_flow_w,
+            port_3_mass_flow_g_s=port_3_mass_flow_g_s,
+            port_3_volume_derivative_l_min=port_3_volume_derivative_l_min,
+            port_3_volume_cm3=port_3_volume_cm3,
+        )
+
+
+@dataclass(frozen=True)
+class TestMqlPneumaticNode4Balance:
+    temperature_k: float
+    pressure_pa: float
+    port_1_enthalpy_flow_w: float
+    port_1_mass_flow_g_s: float
+    port_1_volume_derivative_l_min: float
+    port_1_volume_cm3: float
+    port_2_enthalpy_flow_w: float
+    port_2_mass_flow_g_s: float
+    port_2_volume_derivative_l_min: float
+    port_2_volume_cm3: float
+    port_3_enthalpy_flow_w: float
+    port_3_mass_flow_g_s: float
+    port_3_volume_derivative_l_min: float
+    port_3_volume_cm3: float
+    port_4_enthalpy_flow_w: float
+    port_4_mass_flow_g_s: float
+    port_4_volume_derivative_l_min: float
+    port_4_volume_cm3: float
+
+
+@dataclass(frozen=True)
+class TestMqlPneumaticNode4:
+    """Exact algebraic contract of AMESim ``P4NODE2``.
+
+    Pressure and temperature are fixed by port 2 and duplicated to ports 1, 3,
+    and 4. Flow and volume signals at port 2 are the sums of ports 1, 3, and
+    4, matching the saved AMESim variables for ``pnnode4_*`` instances.
+    """
+
+    alias: str
+
+    def balance(
+        self,
+        *,
+        port_2_temperature_k: float,
+        port_2_pressure_pa: float,
+        port_1_enthalpy_flow_w: float,
+        port_1_mass_flow_g_s: float,
+        port_3_enthalpy_flow_w: float,
+        port_3_mass_flow_g_s: float,
+        port_4_enthalpy_flow_w: float,
+        port_4_mass_flow_g_s: float,
+        port_1_volume_derivative_l_min: float = 0.0,
+        port_1_volume_cm3: float = 0.0,
+        port_3_volume_derivative_l_min: float = 0.0,
+        port_3_volume_cm3: float = 0.0,
+        port_4_volume_derivative_l_min: float = 0.0,
+        port_4_volume_cm3: float = 0.0,
+    ) -> TestMqlPneumaticNode4Balance:
+        if port_2_temperature_k <= 0.0:
+            raise ValueError("port_2_temperature_k must be positive")
+        if port_2_pressure_pa <= 0.0:
+            raise ValueError("port_2_pressure_pa must be positive")
+        return TestMqlPneumaticNode4Balance(
+            temperature_k=port_2_temperature_k,
+            pressure_pa=port_2_pressure_pa,
+            port_1_enthalpy_flow_w=port_1_enthalpy_flow_w,
+            port_1_mass_flow_g_s=port_1_mass_flow_g_s,
+            port_1_volume_derivative_l_min=port_1_volume_derivative_l_min,
+            port_1_volume_cm3=port_1_volume_cm3,
+            port_2_enthalpy_flow_w=(
+                port_1_enthalpy_flow_w
+                + port_3_enthalpy_flow_w
+                + port_4_enthalpy_flow_w
+            ),
+            port_2_mass_flow_g_s=(
+                port_1_mass_flow_g_s
+                + port_3_mass_flow_g_s
+                + port_4_mass_flow_g_s
+            ),
+            port_2_volume_derivative_l_min=(
+                port_1_volume_derivative_l_min
+                + port_3_volume_derivative_l_min
+                + port_4_volume_derivative_l_min
+            ),
+            port_2_volume_cm3=(
+                port_1_volume_cm3 + port_3_volume_cm3 + port_4_volume_cm3
+            ),
+            port_3_enthalpy_flow_w=port_3_enthalpy_flow_w,
+            port_3_mass_flow_g_s=port_3_mass_flow_g_s,
+            port_3_volume_derivative_l_min=port_3_volume_derivative_l_min,
+            port_3_volume_cm3=port_3_volume_cm3,
+            port_4_enthalpy_flow_w=port_4_enthalpy_flow_w,
+            port_4_mass_flow_g_s=port_4_mass_flow_g_s,
+            port_4_volume_derivative_l_min=port_4_volume_derivative_l_min,
+            port_4_volume_cm3=port_4_volume_cm3,
+        )
+
+
+@dataclass(frozen=True)
+class TestMqlP4NodePortConnection:
+    line_alias: str
+    local_node_alias: str
+    local_port: str
+    remote_node_alias: str
+    remote_port: str
+
+
+@dataclass(frozen=True)
+class TestMqlP4NodePrimaryConnection:
+    line_alias: str
+    node_alias: str
+    node_port: str
+    chamber_alias: str
+    chamber_port: str
+
+
+@dataclass(frozen=True)
+class TestMqlP4NodeOrificeConnection:
+    orifice_alias: str
+    node_alias: str
+    node_port: str
+    direct_line_alias: str
+
+
+@dataclass(frozen=True)
+class TestMqlP4NodeNeighborhood:
+    node_alias: str
+    primary: TestMqlP4NodePrimaryConnection
+    port_1: TestMqlP4NodePortConnection
+    port_3: TestMqlP4NodePortConnection
+    port_4: TestMqlP4NodeOrificeConnection
+
+
+def build_test_mql_node3_assembly() -> dict[str, TestMqlPneumaticNode3]:
+    return {
+        str(spec["alias"]): TestMqlPneumaticNode3(alias=str(spec["alias"]))
+        for spec in COMPONENT_SPECS
+        if spec["submodel"] == "PN3NODE2"
+    }
+
+def build_test_mql_node4_assembly() -> dict[str, TestMqlPneumaticNode4]:
+    return {
+        str(spec["alias"]): TestMqlPneumaticNode4(alias=str(spec["alias"]))
+        for spec in COMPONENT_SPECS
+        if spec["submodel"] == "P4NODE2"
+    }
@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from app.simulation.examples.test_mql.primitives.pneumatic import (
+    HELIUM_PNEUMATIC_GAS,
+    AmesimPneumaticGas,
+    AmesimPneumaticOrifice,
+    AmesimPneumaticVolume,
+    AmesimVariablePneumaticVolume,
+)
+from app.simulation.examples.test_mql.config import TestMqlConfig, TestMqlResolvedComponent
+
+
+AMESIM_REFERENCE_PRESSURE_PA = 101_300.0
+BAR_TO_PA = 1.0e5
+DEFAULT_TEST_MQL_TEMPERATURE_K = 293.15
+DEFAULT_VARIABLE_CHAMBER_PRESSURE_BAR = 1.0
+# Matched to PNVO001 event-window mass flow near the 0.04 s opening event.
+TEST_MQL_PNVO001_FLOW_COEFFICIENT_MULTIPLIER = 0.99805
+
+
+@dataclass(frozen=True)
+class TestMqlStepSignalSpec:
+    alias: str
+    initial_output: float
+    final_output: float
+    step_time_s: float
+    transition_duration_s: float
+    transition_type: int
+
+    def output_at(self, time_s: float) -> float:
+        if self.transition_type != 1:
+            raise ValueError(
+                f"unsupported STEP0 transition type {self.transition_type} on {self.alias}"
+            )
+        return self.initial_output if time_s < self.step_time_s else self.final_output
+
+
+@dataclass(frozen=True)
+class TestMqlVariableOrificeControl:
+    orifice_alias: str
+    step: TestMqlStepSignalSpec
+
+    def opening_at(self, time_s: float) -> float:
+        return self.step.output_at(time_s)
+
+
+@dataclass(frozen=True)
+class TestMqlPneumaticAssembly:
+    fixed_chambers: dict[str, AmesimPneumaticVolume]
+    variable_chambers: dict[str, AmesimVariablePneumaticVolume]
+    fixed_orifices: dict[str, AmesimPneumaticOrifice]
+    variable_orifices: dict[str, AmesimPneumaticOrifice]
+    variable_orifice_controls: dict[str, TestMqlVariableOrificeControl]
+    fixed_initial_absolute_pressure_pa: float
+    variable_initial_absolute_pressure_pa: float
+
+    @property
+    def initial_pressure_pa(self) -> float:
+        return pressure_to_amesim_gauge_pa(self.fixed_initial_absolute_pressure_pa)
+
+    @property
+    def fixed_initial_gauge_pressure_pa(self) -> float:
+        return pressure_to_amesim_gauge_pa(self.fixed_initial_absolute_pressure_pa)
+
+    @property
+    def variable_initial_gauge_pressure_pa(self) -> float:
+        return pressure_to_amesim_gauge_pa(self.variable_initial_absolute_pressure_pa)
+
+    @property
+    def chamber_count(self) -> int:
+        return len(self.fixed_chambers) + len(self.variable_chambers)
+
+    @property
+    def orifice_count(self) -> int:
+        return len(self.fixed_orifices) + len(self.variable_orifices)
+
+    @property
+    def component_count(self) -> int:
+        return self.chamber_count + self.orifice_count
+
+    @property
+    def variable_orifice_control_count(self) -> int:
+        return len(self.variable_orifice_controls)
+
+    def set_variable_orifice_openings(self, time_s: float) -> None:
+        for alias, control in self.variable_orifice_controls.items():
+            self.variable_orifices[alias].opening = control.opening_at(time_s)
+
+    @property
+    def aliases(self) -> tuple[str, ...]:
+        return tuple(
+            [
+                *self.fixed_chambers,
+                *self.variable_chambers,
+                *self.fixed_orifices,
+                *self.variable_orifices,
+            ]
+        )
+
+
+def build_test_mql_pneumatic_assembly(
+    config: TestMqlConfig | None = None,
+    gas: AmesimPneumaticGas = HELIUM_PNEUMATIC_GAS,
+) -> TestMqlPneumaticAssembly:
+    config = config or TestMqlConfig.from_amesim_specs()
+    fixed_initial_absolute_pressure_pa = absolute_pressure_from_amesim_bar_parameter(
+        config.global_parameters["P0"]
+    )
+    variable_initial_absolute_pressure_pa = absolute_pressure_from_amesim_bar_parameter(
+        DEFAULT_VARIABLE_CHAMBER_PRESSURE_BAR
+    )
+    fixed_chambers = {
+        component.alias: _build_chamber(
+            component,
+            volume_parameter="cvol",
+            gas=gas,
+            initial_pressure_pa=fixed_initial_absolute_pressure_pa,
+        )
+        for component in config.components_by_submodel("PNCH023")
+    }
+    variable_chambers = {
+        component.alias: _build_chamber(
+            component,
+            volume_parameter="cvol0",
+            gas=gas,
+            initial_pressure_pa=variable_initial_absolute_pressure_pa,
+        )
+        for component in config.components_by_submodel("PNCH012")
+    }
+    fixed_orifices = {
+        component.alias: _build_orifice(
+            component,
+            area_parameter="area",
+            gas=gas,
+            opening=1.0,
+        )
+        for component in config.components_by_submodel("PNOR001")
+    }
+    variable_orifice_controls = _build_variable_orifice_controls(config)
+    variable_orifices = {
+        component.alias: _build_orifice(
+            component,
+            area_parameter="area0",
+            gas=gas,
+            opening=variable_orifice_controls[component.alias].opening_at(0.0),
+        )
+        for component in config.components_by_submodel("PNVO001")
+    }
+    return TestMqlPneumaticAssembly(
+        fixed_chambers=fixed_chambers,
+        variable_chambers=variable_chambers,
+        fixed_orifices=fixed_orifices,
+        variable_orifices=variable_orifices,
+        variable_orifice_controls=variable_orifice_controls,
+        fixed_initial_absolute_pressure_pa=fixed_initial_absolute_pressure_pa,
+        variable_initial_absolute_pressure_pa=variable_initial_absolute_pressure_pa,
+    )
+
+
+def _build_variable_orifice_controls(
+    config: TestMqlConfig,
+) -> dict[str, TestMqlVariableOrificeControl]:
+    from app.simulation.examples.test_mql.system import CONNECTION_SPECS
+
+    components_by_alias = {component.alias: component for component in config.components}
+    variable_orifice_aliases = {
+        component.alias for component in config.components_by_submodel("PNVO001")
+    }
+    controls: dict[str, TestMqlVariableOrificeControl] = {}
+    for connection in CONNECTION_SPECS:
+        if connection["submodel"] != "DIRECT":
+            continue
+        source_alias = str(connection["source_component"])
+        target_alias = str(connection["target_component"])
+        if target_alias in variable_orifice_aliases:
+            orifice_alias = target_alias
+            step_alias = source_alias
+        elif source_alias in variable_orifice_aliases:
+            orifice_alias = source_alias
+            step_alias = target_alias
+        else:
+            continue
+        step_component = components_by_alias.get(step_alias)
+        if step_component is None or step_component.submodel != "STEP0":
+            continue
+        controls[orifice_alias] = TestMqlVariableOrificeControl(
+            orifice_alias=orifice_alias,
+            step=TestMqlStepSignalSpec(
+                alias=step_alias,
+                initial_output=step_component.parameter_value("out0"),
+                final_output=step_component.parameter_value("out1"),
+                step_time_s=step_component.parameter_value("t0"),
+                transition_duration_s=step_component.parameter_value("td"),
+                transition_type=int(step_component.parameter_value("transitionType")),
+            ),
+        )
+    missing = variable_orifice_aliases - controls.keys()
+    if missing:
+        raise ValueError(
+            "missing STEP0 controls for PNVO001 components: "
+            + ", ".join(sorted(missing))
+        )
+    return controls
+
+
+def absolute_pressure_from_amesim_bar_parameter(pressure_bar: float) -> float:
+    return pressure_bar * BAR_TO_PA
+
+
+def pressure_to_amesim_gauge_pa(absolute_pressure_pa: float) -> float:
+    return absolute_pressure_pa - AMESIM_REFERENCE_PRESSURE_PA
+
+
+def pressure_from_amesim_bar_parameter(pressure_bar: float) -> float:
+    return pressure_to_amesim_gauge_pa(absolute_pressure_from_amesim_bar_parameter(pressure_bar))
+
+
+def _build_chamber(
+    component: TestMqlResolvedComponent,
+    *,
+    volume_parameter: str,
+    gas: AmesimPneumaticGas,
+    initial_pressure_pa: float,
+) -> AmesimPneumaticVolume:
+    if volume_parameter == "cvol0":
+        return AmesimVariablePneumaticVolume.from_liters(
+            name=component.alias,
+            dead_volume_liters=component.parameter_value(volume_parameter),
+            gas=gas,
+            p0=initial_pressure_pa,
+            T0=_component_temperature(component),
+            heat_transfer_coefficient=component.parameter_value("kth"),
+            heat_transfer_area=component.parameter_value("sth"),
+            external_temperature_k=_component_temperature(component),
+        )
+    return AmesimPneumaticVolume.from_liters(
+        name=component.alias,
+        volume_liters=component.parameter_value(volume_parameter),
+        gas=gas,
+        p0=initial_pressure_pa,
+        T0=_component_temperature(component),
+        heat_transfer_coefficient=component.parameter_value("kth"),
+        heat_transfer_area=component.parameter_value("sth"),
+        external_temperature_k=_component_temperature(component),
+    )
+
+
+def _build_orifice(
+    component: TestMqlResolvedComponent,
+    *,
+    area_parameter: str,
+    gas: AmesimPneumaticGas,
+    opening: float,
+) -> AmesimPneumaticOrifice:
+    flow_coefficient = component.parameter_value("cq")
+    if component.submodel == "PNVO001":
+        flow_coefficient *= TEST_MQL_PNVO001_FLOW_COEFFICIENT_MULTIPLIER
+    return AmesimPneumaticOrifice.from_mm2(
+        name=component.alias,
+        area_mm2=component.parameter_value(area_parameter),
+        flow_coefficient=flow_coefficient,
+        gas=gas,
+        opening=opening,
+    )
+
+
+def _component_temperature(component: TestMqlResolvedComponent) -> float:
+    parameter = component.parameters.get("extemp")
+    if parameter is None or parameter.value is None:
+        return DEFAULT_TEST_MQL_TEMPERATURE_K
+    return parameter.value
@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from app.simulation.examples.test_mql.primitives.pneumatic import (
+    HELIUM_PNEUMATIC_GAS,
+    AmesimPneumaticGas,
+)
+from app.simulation.examples.test_mql.primitives.pneumatic_lines import (
+    AmesimPnl0001Pipe,
+    AmesimPnl0002Pipe,
+    AmesimPnl0003Pipe,
+    AmesimPnl00rPipe,
+)
+from app.simulation.examples.test_mql.line_parameters import (
+    TestMqlPnl0001Spec,
+    TestMqlPnl0002Spec,
+    TestMqlPnl0003Spec,
+    TestMqlPnl00rSpec,
+    load_test_mql_pnl0001_specs,
+    load_test_mql_pnl0002_specs,
+    load_test_mql_pnl0003_specs,
+    load_test_mql_pnl00r_specs,
+)
+
+
+TEST_MQL_PNL0001_D20_L1_LINEAR_CONDUCTANCE = 5.5636e-6
+
+
+@dataclass(frozen=True)
+class TestMqlPnl0001Assembly:
+    specs: tuple[TestMqlPnl0001Spec, ...]
+    lines: dict[str, AmesimPnl0001Pipe]
+
+    def spec(self, alias: str) -> TestMqlPnl0001Spec:
+        for spec in self.specs:
+            if spec.alias == alias:
+                return spec
+        raise KeyError(alias)
+
+
+@dataclass(frozen=True)
+class TestMqlPnl0002Assembly:
+    specs: tuple[TestMqlPnl0002Spec, ...]
+    lines: dict[str, AmesimPnl0002Pipe]
+
+    def spec(self, alias: str) -> TestMqlPnl0002Spec:
+        for spec in self.specs:
+            if spec.alias == alias:
+                return spec
+        raise KeyError(alias)
+
+
+@dataclass(frozen=True)
+class TestMqlPnl0003Assembly:
+    specs: tuple[TestMqlPnl0003Spec, ...]
+    lines: dict[str, AmesimPnl0003Pipe]
+
+    def spec(self, alias: str) -> TestMqlPnl0003Spec:
+        for spec in self.specs:
+            if spec.alias == alias:
+                return spec
+        raise KeyError(alias)
+
+
+@dataclass(frozen=True)
+class TestMqlPnl00rAssembly:
+    specs: tuple[TestMqlPnl00rSpec, ...]
+    lines: dict[str, AmesimPnl00rPipe]
+
+    def spec(self, alias: str) -> TestMqlPnl00rSpec:
+        for spec in self.specs:
+            if spec.alias == alias:
+                return spec
+        raise KeyError(alias)
+
+
+def build_test_mql_pnl0001_assembly(
+    archive_path: str | Path,
+    *,
+    gas: AmesimPneumaticGas = HELIUM_PNEUMATIC_GAS,
+) -> TestMqlPnl0001Assembly:
+    specs = load_test_mql_pnl0001_specs(archive_path)
+    lines = {
+        spec.alias: AmesimPnl0001Pipe(
+            name=spec.alias,
+            diameter_mm=spec.diameter_mm,
+            length_m=spec.length_m,
+            relative_roughness=spec.relative_roughness,
+            polytropic_constant=spec.polytropic_constant,
+            heat_transfer_coefficient=spec.heat_transfer_coefficient,
+            external_temperature_k=spec.external_temperature_k,
+            calibrated_linear_conductance=(
+                _test_mql_pnl0001_calibrated_linear_conductance(spec)
+            ),
+            gas=gas,
+            p0=spec.initial_absolute_pressure_pa,
+            T0=spec.initial_temperature_k,
+        )
+        for spec in specs
+    }
+    return TestMqlPnl0001Assembly(specs=specs, lines=lines)
+
+
+def _test_mql_pnl0001_calibrated_linear_conductance(
+    spec: TestMqlPnl0001Spec,
+) -> float | None:
+    if spec.target_component.startswith("pn_c1_") and _matches_geometry(
+        spec, diameter_mm=20.0, length_m=1.0
+    ):
+        return TEST_MQL_PNL0001_D20_L1_LINEAR_CONDUCTANCE
+    return None
+
+
+def _matches_geometry(
+    spec: TestMqlPnl0001Spec,
+    *,
+    diameter_mm: float,
+    length_m: float,
+) -> bool:
+    return (
+        abs(spec.diameter_mm - diameter_mm) < 1.0e-12
+        and abs(spec.length_m - length_m) < 1.0e-12
+    )
+
+
+def build_test_mql_pnl0002_assembly(
+    archive_path: str | Path,
+    *,
+    gas: AmesimPneumaticGas = HELIUM_PNEUMATIC_GAS,
+) -> TestMqlPnl0002Assembly:
+    specs = load_test_mql_pnl0002_specs(archive_path)
+    lines = {
+        spec.alias: AmesimPnl0002Pipe(
+            name=spec.alias,
+            diameter_mm=spec.diameter_mm,
+            length_m=spec.length_m,
+            relative_roughness=spec.relative_roughness,
+            polytropic_constant=spec.polytropic_constant,
+            heat_transfer_coefficient=spec.heat_transfer_coefficient,
+            external_temperature_k=spec.external_temperature_k,
+            gas=gas,
+            pctr_0=spec.initial_center_absolute_pressure_pa,
+            Tctr_0=spec.initial_center_temperature_k,
+        )
+        for spec in specs
+    }
+    return TestMqlPnl0002Assembly(specs=specs, lines=lines)
+
+
+def build_test_mql_pnl0003_assembly(
+    archive_path: str | Path,
+    *,
+    gas: AmesimPneumaticGas = HELIUM_PNEUMATIC_GAS,
+) -> TestMqlPnl0003Assembly:
+    specs = load_test_mql_pnl0003_specs(archive_path)
+    lines = {
+        spec.alias: AmesimPnl0003Pipe(
+            name=spec.alias,
+            diameter_mm=spec.diameter_mm,
+            length_m=spec.length_m,
+            relative_roughness=spec.relative_roughness,
+            polytropic_constant=spec.polytropic_constant,
+            heat_transfer_coefficient=spec.heat_transfer_coefficient,
+            external_temperature_k=spec.external_temperature_k,
+            gas=gas,
+            p1_0=spec.initial_absolute_pressure_1_pa,
+            T1_0=spec.initial_temperature_1_k,
+            p2_0=spec.initial_absolute_pressure_2_pa,
+            T2_0=spec.initial_temperature_2_k,
+        )
+        for spec in specs
+    }
+    return TestMqlPnl0003Assembly(specs=specs, lines=lines)
+
+
+def build_test_mql_pnl00r_assembly(
+    archive_path: str | Path,
+    *,
+    gas: AmesimPneumaticGas = HELIUM_PNEUMATIC_GAS,
+) -> TestMqlPnl00rAssembly:
+    specs = load_test_mql_pnl00r_specs(archive_path)
+    lines = {
+        spec.alias: AmesimPnl00rPipe(
+            name=spec.alias,
+            diameter_mm=spec.diameter_mm,
+            length_m=spec.length_m,
+            relative_roughness=spec.relative_roughness,
+            gas=gas,
+        )
+        for spec in specs
+    }
+    return TestMqlPnl00rAssembly(specs=specs, lines=lines)
@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from app.simulation.examples.test_mql.closure import TestMqlPneumaticChamberSegmentSpec
+from app.simulation.examples.test_mql.topology import TestMqlCirTopology
+
+
+def discover_fixed_chamber_segments(
+    topology: TestMqlCirTopology,
+    component_specs: list[dict[str, object]],
+    connection_specs: list[dict[str, object]],
+) -> tuple[TestMqlPneumaticChamberSegmentSpec, ...]:
+    submodel_by_alias = {
+        str(component["alias"]): str(component["submodel"])
+        for component in component_specs
+    }
+    segments = []
+    for component in component_specs:
+        volume_alias = str(component["alias"])
+        if component["submodel"] != "PNCH023":
+            continue
+
+        orifice_contacts = []
+        for contact in topology.contacts_for(volume_alias):
+            other_alias, other_port = contact.other_endpoint(volume_alias)
+            if submodel_by_alias.get(other_alias) == "PNOR001":
+                orifice_contacts.append(
+                    (
+                        other_alias,
+                        other_port,
+                        contact.port_for(volume_alias),
+                    )
+                )
+        if len(orifice_contacts) != 2:
+            raise ValueError(
+                f"{volume_alias} must contact exactly two PNOR001 orifices; "
+                f"found {len(orifice_contacts)}"
+            )
+
+        sides = [
+            _resolve_orifice_boundary(
+                orifice_alias=orifice_alias,
+                orifice_volume_port=orifice_volume_port,
+                volume_port=volume_port,
+                connection_specs=connection_specs,
+                submodel_by_alias=submodel_by_alias,
+            )
+            for orifice_alias, orifice_volume_port, volume_port in orifice_contacts
+        ]
+        inlet_sides = [side for side in sides if side["role"] == "inlet"]
+        outlet_sides = [side for side in sides if side["role"] == "outlet"]
+        if len(inlet_sides) != 1 or len(outlet_sides) != 1:
+            raise ValueError(
+                f"{volume_alias} requires one inlet and one outlet topology side"
+            )
+        inlet = inlet_sides[0]
+        outlet = outlet_sides[0]
+        segments.append(
+            TestMqlPneumaticChamberSegmentSpec(
+                name=f"{volume_alias}_segment",
+                inlet_node_alias=inlet["node_alias"],
+                inlet_line_alias=inlet["line_alias"],
+                inlet_orifice_alias=inlet["orifice_alias"],
+                inlet_orifice_boundary_port=inlet["orifice_boundary_port"],
+                inlet_orifice_volume_port=inlet["orifice_volume_port"],
+                volume_alias=volume_alias,
+                volume_inlet_port=inlet["volume_port"],
+                volume_outlet_port=outlet["volume_port"],
+                outlet_orifice_alias=outlet["orifice_alias"],
+                outlet_orifice_volume_port=outlet["orifice_volume_port"],
+                outlet_orifice_boundary_port=outlet["orifice_boundary_port"],
+                outlet_line_alias=outlet["line_alias"],
+                outlet_node_alias=outlet["node_alias"],
+            )
+        )
+    return tuple(segments)
+
+
+def _resolve_orifice_boundary(
+    *,
+    orifice_alias: str,
+    orifice_volume_port: str,
+    volume_port: str,
+    connection_specs: list[dict[str, object]],
+    submodel_by_alias: dict[str, str],
+) -> dict[str, str]:
+    boundary_connections = []
+    for connection in connection_specs:
+        if (
+            connection["source_component"] == orifice_alias
+            and connection["source_port"] != orifice_volume_port
+        ) or (
+            connection["target_component"] == orifice_alias
+            and connection["target_port"] != orifice_volume_port
+        ):
+            boundary_connections.append(connection)
+    if len(boundary_connections) != 1:
+        raise ValueError(
+            f"{orifice_alias} must have exactly one non-volume boundary connection; "
+            f"found {len(boundary_connections)}"
+        )
+
+    connection = boundary_connections[0]
+    if connection["submodel"] != "PNL0001":
+        raise ValueError(
+            f"{orifice_alias} boundary must use PNL0001, got {connection['submodel']}"
+        )
+    if connection["target_component"] == orifice_alias:
+        role = "inlet"
+        node_alias = str(connection["source_component"])
+        orifice_boundary_port = str(connection["target_port"])
+    else:
+        role = "outlet"
+        node_alias = str(connection["target_component"])
+        orifice_boundary_port = str(connection["source_port"])
+    if submodel_by_alias.get(node_alias) != "PN3NODE2":
+        raise ValueError(
+            f"{orifice_alias} PNL0001 boundary must terminate at PN3NODE2, "
+            f"got {node_alias}"
+        )
+    return {
+        "role": role,
+        "node_alias": node_alias,
+        "line_alias": str(connection["alias"]),
+        "orifice_alias": orifice_alias,
+        "orifice_boundary_port": orifice_boundary_port,
+        "orifice_volume_port": orifice_volume_port,
+        "volume_port": volume_port,
+    }
@@ -0,0 +1 @@
+"""Calibrated component primitives used only by the ``test_mql`` example."""
@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from math import pi
+
+
+MM_TO_M = 1.0e-3
+M_TO_MM = 1.0e3
+M3_TO_CM3 = 1.0e6
+M3_PER_S_TO_L_PER_MIN = 60_000.0
+
+
+def circular_area(diameter_m: float) -> float:
+    if diameter_m < 0.0:
+        raise ValueError("diameter_m must be non-negative.")
+    return pi * diameter_m * diameter_m / 4.0
+
+
+def mm_to_m(value: float) -> float:
+    return value * MM_TO_M
+
+
+def m_to_mm(value: float) -> float:
+    return value * M_TO_MM
+
+
+@dataclass(frozen=True)
+class AmesimPistonGeometry:
+    """Geometry relations used by AMESim PNRP17 pneumatic piston variables."""
+
+    piston_diameter_m: float
+    rod_diameter_m: float = 0.0
+    zero_length_m: float = 0.0
+
+    @property
+    def piston_area_m2(self) -> float:
+        return circular_area(self.piston_diameter_m)
+
+    @property
+    def rod_area_m2(self) -> float:
+        return circular_area(self.rod_diameter_m)
+
+    @property
+    def annulus_area_m2(self) -> float:
+        return self.piston_area_m2 - self.rod_area_m2
+
+    def chamber_length_m(self, port4_displacement_m: float, port5_displacement_m: float) -> float:
+        return self.zero_length_m + port5_displacement_m - port4_displacement_m
+
+    def chamber_length_mm(self, port4_displacement_m: float, port5_displacement_m: float) -> float:
+        return m_to_mm(self.chamber_length_m(port4_displacement_m, port5_displacement_m))
+
+    @property
+    def chamber_area_m2(self) -> float:
+        return self.annulus_area_m2
+
+    def chamber_volume_m3(self, port4_displacement_m: float, port5_displacement_m: float) -> float:
+        return self.chamber_area_m2 * self.chamber_length_m(
+            port4_displacement_m,
+            port5_displacement_m,
+        )
+
+    def chamber_volume_cm3(self, port4_displacement_m: float, port5_displacement_m: float) -> float:
+        return self.chamber_volume_m3(port4_displacement_m, port5_displacement_m) * M3_TO_CM3
+
+    def chamber_volume_rate_m3_s(self, port4_velocity_m_s: float, port5_velocity_m_s: float) -> float:
+        return self.chamber_area_m2 * (port5_velocity_m_s - port4_velocity_m_s)
+
+    def chamber_volume_rate_l_min(self, port4_velocity_m_s: float, port5_velocity_m_s: float) -> float:
+        return self.chamber_volume_rate_m3_s(
+            port4_velocity_m_s,
+            port5_velocity_m_s,
+        ) * M3_PER_S_TO_L_PER_MIN
+
+
+@dataclass(frozen=True)
+class AmesimElasticEndstop:
+    """Contact force part of AMESim LSTP00A elastic endstop."""
+
+    contact_stiffness_n_per_m: float
+    contact_damping_n_per_m_per_s: float = 0.0
+    gap0_m: float = 0.0
+
+    def penetration_m_from_gap_mm(self, gap_mm: float) -> float:
+        return max(-(mm_to_m(gap_mm) - self.gap0_m), 0.0)
+
+    def static_contact_force(self, gap_mm: float) -> float:
+        return self.contact_stiffness_n_per_m * self.penetration_m_from_gap_mm(gap_mm)
+
+    def contact_force(self, gap_mm: float, penetration_velocity_m_s: float = 0.0) -> float:
+        if self.penetration_m_from_gap_mm(gap_mm) <= 0.0:
+            return 0.0
+        damping_force = self.contact_damping_n_per_m_per_s * penetration_velocity_m_s
+        return max(self.static_contact_force(gap_mm) + damping_force, 0.0)
+
+
+@dataclass(frozen=True)
+class AmesimMassFrictionEndstops:
+    """Parameter and observable helpers for AMESim MECMAS21 translation masses."""
+
+    mass_kg: float
+    lower_limit_m: float
+    upper_limit_m: float
+    lower_stiffness_n_per_m: float
+    upper_stiffness_n_per_m: float
+    lower_damping_n_per_m_per_s: float = 0.0
+    upper_damping_n_per_m_per_s: float = 0.0
+    viscous_friction_n_per_m_per_s: float = 0.0
+    coulomb_friction_n: float = 0.0
+    stiction_force_n: float = 0.0
+    windage_n_per_m2_per_s2: float = 0.0
+
+    def lower_penetration_m(self, displacement_m: float) -> float:
+        return max(self.lower_limit_m - displacement_m, 0.0)
+
+    def upper_penetration_m(self, displacement_m: float) -> float:
+        return max(displacement_m - self.upper_limit_m, 0.0)
+
+    def lower_static_force_magnitude(self, displacement_m: float) -> float:
+        return self.lower_stiffness_n_per_m * self.lower_penetration_m(displacement_m)
+
+    def upper_static_force_magnitude(self, displacement_m: float) -> float:
+        return self.upper_stiffness_n_per_m * self.upper_penetration_m(displacement_m)
+
+    def viscous_friction_force(self, velocity_m_s: float) -> float:
+        return -self.viscous_friction_n_per_m_per_s * velocity_m_s
+
+    def windage_force(self, velocity_m_s: float) -> float:
+        return -self.windage_n_per_m2_per_s2 * velocity_m_s * abs(velocity_m_s)
+
+    def dry_friction_force(self, velocity_m_s: float) -> float:
+        if velocity_m_s > 0.0:
+            return -self.coulomb_friction_n
+        if velocity_m_s < 0.0:
+            return self.coulomb_friction_n
+        return 0.0
+
+    def limit_contact_force(self, displacement_m: float, velocity_m_s: float) -> float:
+        lower_force = self.lower_static_force_magnitude(displacement_m)
+        if lower_force > 0.0:
+            lower_force += max(-self.lower_damping_n_per_m_per_s * velocity_m_s, 0.0)
+
+        upper_force = self.upper_static_force_magnitude(displacement_m)
+        if upper_force > 0.0:
+            upper_force += max(self.upper_damping_n_per_m_per_s * velocity_m_s, 0.0)
+
+        return lower_force - upper_force
+
+    def derivatives(
+        self,
+        *,
+        velocity_m_s: float,
+        displacement_m: float,
+        port_1_force_n: float = 0.0,
+        port_2_force_n: float = 0.0,
+        external_force_n: float = 0.0,
+    ) -> tuple[float, float]:
+        total_force = (
+            port_1_force_n
+            + port_2_force_n
+            + external_force_n
+            + self.viscous_friction_force(velocity_m_s)
+            + self.windage_force(velocity_m_s)
+            + self.dry_friction_force(velocity_m_s)
+            + self.limit_contact_force(displacement_m, velocity_m_s)
+        )
+        return total_force / self.mass_kg, velocity_m_s
+
@@ -0,0 +1,437 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from math import pi, sqrt
+
+from app.simulation.core.base import AlgebraicComponent, DynamicComponent
+from app.simulation.core.medium import ThermodynamicProperties
+from app.simulation.core.peng_robinson import HELIUM_PR, PengRobinsonFluid
+from app.simulation.core.ports import PortState
+from app.simulation.core.state import VolumeState
+
+
+@dataclass(frozen=True)
+class AmesimPneumaticGas:
+    """Caloric constants plus Peng-Robinson EOS for AMESim pneumatic components."""
+
+    fluid: PengRobinsonFluid = HELIUM_PR
+    cp: float = 5193.0
+    cv: float = 3116.0
+
+    @property
+    def gamma(self) -> float:
+        return self.cp / self.cv
+
+    @property
+    def R_gas(self) -> float:
+        return self.fluid.specific_gas_constant
+
+    def density(self, pressure: float, temperature: float) -> float:
+        return self.fluid.density(pressure, temperature)
+
+    def pressure(self, density: float, temperature: float) -> float:
+        return self.fluid.pressure_from_density(temperature, density)
+
+    def specific_internal_energy(self, temperature: float) -> float:
+        return self.cv * temperature
+
+    def specific_enthalpy(self, temperature: float) -> float:
+        return self.cp * temperature
+
+    def specific_reference_enthalpy(
+        self,
+        temperature: float,
+        reference_temperature: float = 298.15,
+    ) -> float:
+        return self.cp * (temperature - reference_temperature)
+
+    def reference_temperature_from_specific_enthalpy(
+        self,
+        specific_enthalpy: float,
+        reference_temperature: float = 298.15,
+    ) -> float:
+        if self.cp <= 0.0:
+            raise ValueError("cp must be positive.")
+        return reference_temperature + specific_enthalpy / self.cp
+
+    def pressure_reference_enthalpy(
+        self,
+        pressure: float,
+        temperature: float,
+        reference_pressure: float = 101_300.0,
+        reference_temperature: float = 298.15,
+    ) -> float:
+        return (
+            self.specific_reference_enthalpy(temperature, reference_temperature)
+            + self.fluid.residual_specific_enthalpy(pressure, temperature)
+            - self.fluid.residual_specific_enthalpy(
+                reference_pressure,
+                reference_temperature,
+            )
+        )
+
+    def pressure_transport_enthalpy(
+        self,
+        pressure: float,
+        temperature: float,
+        reference_pressure: float = 101_300.0,
+        reference_temperature: float = 298.15,
+    ) -> float:
+        """Convert AMESim reference enthalpy to the absolute-energy state basis."""
+        return (
+            self.pressure_reference_enthalpy(
+                pressure,
+                temperature,
+                reference_pressure,
+                reference_temperature,
+            )
+            + self.cp * reference_temperature
+        )
+
+    def temperature_from_internal_energy(self, specific_internal_energy: float) -> float:
+        if self.cv <= 0.0:
+            raise ValueError("cv must be positive.")
+        return specific_internal_energy / self.cv
+
+
+HELIUM_PNEUMATIC_GAS = AmesimPneumaticGas()
+
+
+def liters_to_m3(value: float) -> float:
+    return value * 1.0e-3
+
+
+def m3_to_cm3(value: float) -> float:
+    return value * 1.0e6
+
+
+def cm3_to_m3(value: float) -> float:
+    return value * 1.0e-6
+
+
+def kg_to_g(value: float) -> float:
+    return value * 1.0e3
+
+
+def mm2_to_m2(value: float) -> float:
+    return value * 1.0e-6
+
+
+def diameter_mm_to_area_m2(diameter_mm: float) -> float:
+    diameter_m = diameter_mm * 1.0e-3
+    return pi * diameter_m * diameter_m / 4.0
+
+
+class AmesimPneumaticVolume(DynamicComponent):
+    """First-pass AMESim pneumatic control volume using helium PR pressure closure."""
+
+    def __init__(
+        self,
+        name: str,
+        volume: float,
+        gas: AmesimPneumaticGas = HELIUM_PNEUMATIC_GAS,
+        p0: float = 101_325.0,
+        T0: float = 293.15,
+        heat_transfer_coefficient: float = 0.0,
+        heat_transfer_area: float = 0.0,
+        external_temperature_k: float = 293.15,
+    ) -> None:
+        if volume <= 0.0:
+            raise ValueError("volume must be positive.")
+        if heat_transfer_coefficient < 0.0:
+            raise ValueError("heat_transfer_coefficient must be non-negative.")
+        if heat_transfer_area < 0.0:
+            raise ValueError("heat_transfer_area must be non-negative.")
+        if external_temperature_k <= 0.0:
+            raise ValueError("external_temperature_k must be positive.")
+        super().__init__(name=name)
+        self.volume = volume
+        self.gas = gas
+        self.heat_transfer_coefficient = heat_transfer_coefficient
+        self.heat_transfer_area = heat_transfer_area
+        self.external_temperature = external_temperature_k
+        rho0 = gas.density(p0, T0)
+        m0 = rho0 * volume
+        U0 = m0 * gas.specific_internal_energy(T0)
+        self.state = VolumeState(m=m0, U=U0)
+        self.port_a = PortState()
+        self.port_b = PortState()
+
+    @classmethod
+    def from_liters(
+        cls,
+        name: str,
+        volume_liters: float,
+        gas: AmesimPneumaticGas = HELIUM_PNEUMATIC_GAS,
+        p0: float = 101_325.0,
+        T0: float = 293.15,
+        heat_transfer_coefficient: float = 0.0,
+        heat_transfer_area: float = 0.0,
+        external_temperature_k: float = 293.15,
+    ) -> "AmesimPneumaticVolume":
+        return cls(
+            name=name,
+            volume=liters_to_m3(volume_liters),
+            gas=gas,
+            p0=p0,
+            T0=T0,
+            heat_transfer_coefficient=heat_transfer_coefficient,
+            heat_transfer_area=heat_transfer_area,
+            external_temperature_k=external_temperature_k,
+        )
+
+    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 volume_cm3(self) -> float:
+        return m3_to_cm3(self.volume)
+
+    def volume_rate_m3_s(self) -> float:
+        return 0.0
+
+    def thermal_energy_flow_w(self, temperature_k: float | None = None) -> float:
+        temperature = self.properties().T if temperature_k is None else temperature_k
+        return (
+            self.heat_transfer_coefficient
+            * self.heat_transfer_area
+            * (self.external_temperature - temperature)
+        )
+
+    def gas_mass_g(self) -> float:
+        return kg_to_g(self.state.m)
+
+    def pressure_gauge_pa(self, reference_pressure_pa: float = 101_300.0) -> float:
+        return self.properties().p - reference_pressure_pa
+
+    def properties(self) -> ThermodynamicProperties:
+        if self.state.m <= 0.0:
+            raise ValueError("volume mass must stay positive.")
+        T = self.gas.temperature_from_internal_energy(self.state.U / self.state.m)
+        rho = self.state.m / self.volume
+        p = self.gas.pressure(rho, T)
+        u = self.state.U / self.state.m
+        h = self.gas.specific_enthalpy(T)
+        self.port_a.p = p
+        self.port_a.h_outflow = h
+        self.port_b.p = p
+        self.port_b.h_outflow = h
+        return ThermodynamicProperties(p=p, T=T, rho=rho, u=u, h=h)
+
+    def derivatives(self, inlet_h: float, m_flow: float) -> VolumeState:
+        return VolumeState(
+            m=m_flow,
+            U=m_flow * inlet_h + self.thermal_energy_flow_w(),
+        )
+
+    def derivatives_from_two_connections(
+        self,
+        *,
+        port_a_m_flow: float,
+        connected_h_a: float,
+        port_b_m_flow: float,
+        connected_h_b: float,
+        internal_h: float,
+        volume_rate_m3_s: float | None = None,
+    ) -> VolumeState:
+        properties = self.properties()
+        inlet_h_a = self.connection_inlet_enthalpy(
+            port_m_flow=port_a_m_flow,
+            connected_h=connected_h_a,
+            internal_h=internal_h,
+        )
+        inlet_h_b = self.connection_inlet_enthalpy(
+            port_m_flow=port_b_m_flow,
+            connected_h=connected_h_b,
+            internal_h=internal_h,
+        )
+        return VolumeState(
+            m=port_a_m_flow + port_b_m_flow,
+            U=(
+                port_a_m_flow * inlet_h_a
+                + port_b_m_flow * inlet_h_b
+                + self.thermal_energy_flow_w(properties.T)
+                - properties.p * (
+                    self.volume_rate_m3_s()
+                    if volume_rate_m3_s is None
+                    else volume_rate_m3_s
+                )
+            ),
+        )
+
+
+class AmesimVariablePneumaticVolume(AmesimPneumaticVolume):
+    """PNCH012-style volume with a dead volume plus an external moving volume."""
+
+    def __init__(
+        self,
+        name: str,
+        dead_volume: float,
+        gas: AmesimPneumaticGas = HELIUM_PNEUMATIC_GAS,
+        p0: float = 101_325.0,
+        T0: float = 293.15,
+        external_volume: float = 0.0,
+        heat_transfer_coefficient: float = 0.0,
+        heat_transfer_area: float = 0.0,
+        external_temperature_k: float = 293.15,
+    ) -> None:
+        if dead_volume <= 0.0:
+            raise ValueError("dead_volume must be positive.")
+        if dead_volume + external_volume <= 0.0:
+            raise ValueError("total volume must be positive.")
+        self.dead_volume = dead_volume
+        self.external_volume = external_volume
+        self.external_volume_rate = 0.0
+        super().__init__(
+            name=name,
+            volume=dead_volume + external_volume,
+            gas=gas,
+            p0=p0,
+            T0=T0,
+            heat_transfer_coefficient=heat_transfer_coefficient,
+            heat_transfer_area=heat_transfer_area,
+            external_temperature_k=external_temperature_k,
+        )
+
+    @classmethod
+    def from_liters(
+        cls,
+        name: str,
+        dead_volume_liters: float,
+        gas: AmesimPneumaticGas = HELIUM_PNEUMATIC_GAS,
+        p0: float = 101_325.0,
+        T0: float = 293.15,
+        external_volume_liters: float = 0.0,
+        heat_transfer_coefficient: float = 0.0,
+        heat_transfer_area: float = 0.0,
+        external_temperature_k: float = 293.15,
+    ) -> "AmesimVariablePneumaticVolume":
+        return cls(
+            name=name,
+            dead_volume=liters_to_m3(dead_volume_liters),
+            gas=gas,
+            p0=p0,
+            T0=T0,
+            external_volume=liters_to_m3(external_volume_liters),
+            heat_transfer_coefficient=heat_transfer_coefficient,
+            heat_transfer_area=heat_transfer_area,
+            external_temperature_k=external_temperature_k,
+        )
+
+    def volume_rate_m3_s(self) -> float:
+        return self.external_volume_rate
+
+    def set_external_volume_m3(
+        self,
+        external_volume: float,
+        external_volume_rate_m3_s: float = 0.0,
+    ) -> None:
+        if self.dead_volume + external_volume <= 0.0:
+            raise ValueError("total volume must be positive.")
+        self.external_volume = external_volume
+        self.external_volume_rate = external_volume_rate_m3_s
+        self.volume = self.dead_volume + self.external_volume
+
+
+class AmesimPneumaticOrifice(AlgebraicComponent):
+    """First-pass PNOR001/PNVO001-style compressible helium orifice.
+
+    This is a calibrated placeholder boundary for the Python port. It preserves
+    AMESim-style area and coefficient inputs, but final parity must be checked
+    against AMESim CSV results before treating it as numerically equivalent.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        area: float,
+        flow_coefficient: float = 1.0,
+        gas: AmesimPneumaticGas = HELIUM_PNEUMATIC_GAS,
+        opening: float = 1.0,
+    ) -> None:
+        if area < 0.0:
+            raise ValueError("area must be non-negative.")
+        if flow_coefficient < 0.0:
+            raise ValueError("flow_coefficient must be non-negative.")
+        super().__init__(name=name)
+        self.area = area
+        self.flow_coefficient = flow_coefficient
+        self.gas = gas
+        self.opening = opening
+        self.port_a = PortState()
+        self.port_b = PortState()
+
+    @classmethod
+    def from_mm2(
+        cls,
+        name: str,
+        area_mm2: float,
+        flow_coefficient: float = 1.0,
+        gas: AmesimPneumaticGas = HELIUM_PNEUMATIC_GAS,
+        opening: float = 1.0,
+    ) -> "AmesimPneumaticOrifice":
+        return cls(
+            name=name,
+            area=mm2_to_m2(area_mm2),
+            flow_coefficient=flow_coefficient,
+            gas=gas,
+            opening=opening,
+        )
+
+    @property
+    def effective_area(self) -> float:
+        opening = min(max(self.opening, 0.0), 1.0)
+        return self.area * opening
+
+    def mass_flow(self, p_a: float, p_b: float, upstream_temperature: float) -> float:
+        if p_a == p_b or self.effective_area == 0.0 or self.flow_coefficient == 0.0:
+            return 0.0
+        if p_a > p_b:
+            return compressible_orifice_mass_flow(
+                upstream_pressure=p_a,
+                downstream_pressure=p_b,
+                upstream_temperature=upstream_temperature,
+                area=self.effective_area,
+                flow_coefficient=self.flow_coefficient,
+                gas=self.gas,
+            )
+        return -compressible_orifice_mass_flow(
+            upstream_pressure=p_b,
+            downstream_pressure=p_a,
+            upstream_temperature=upstream_temperature,
+            area=self.effective_area,
+            flow_coefficient=self.flow_coefficient,
+            gas=self.gas,
+        )
+
+
+def compressible_orifice_mass_flow(
+    *,
+    upstream_pressure: float,
+    downstream_pressure: float,
+    upstream_temperature: float,
+    area: float,
+    flow_coefficient: float,
+    gas: AmesimPneumaticGas = HELIUM_PNEUMATIC_GAS,
+) -> float:
+    if upstream_pressure <= 0.0 or downstream_pressure < 0.0:
+        raise ValueError("pressures must be non-negative and upstream pressure must be positive.")
+    if upstream_temperature <= 0.0:
+        raise ValueError("upstream_temperature must be positive.")
+    if area < 0.0 or flow_coefficient < 0.0:
+        raise ValueError("area and flow_coefficient must be non-negative.")
+    if downstream_pressure >= upstream_pressure or area == 0.0 or flow_coefficient == 0.0:
+        return 0.0
+
+    gamma = gas.gamma
+    pressure_ratio = max(downstream_pressure / upstream_pressure, 0.0)
+    critical_ratio = (2.0 / (gamma + 1.0)) ** (gamma / (gamma - 1.0))
+    coefficient = flow_coefficient * area * upstream_pressure / sqrt(gas.R_gas * upstream_temperature)
+    if pressure_ratio <= critical_ratio:
+        flow_function = sqrt(gamma) * (2.0 / (gamma + 1.0)) ** ((gamma + 1.0) / (2.0 * (gamma - 1.0)))
+    else:
+        term = pressure_ratio ** (2.0 / gamma) - pressure_ratio ** ((gamma + 1.0) / gamma)
+        flow_function = sqrt((2.0 * gamma / (gamma - 1.0)) * max(term, 0.0))
+    return coefficient * flow_function
@@ -0,0 +1,881 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from math import log10, pi, sqrt
+
+from app.simulation.examples.test_mql.primitives.pneumatic import (
+    HELIUM_PNEUMATIC_GAS,
+    AmesimPneumaticGas,
+    compressible_orifice_mass_flow,
+    diameter_mm_to_area_m2,
+)
+from app.simulation.core.base import AlgebraicComponent, DynamicComponent
+from app.simulation.core.medium import ThermodynamicProperties
+from app.simulation.core.ports import PortState
+from app.simulation.core.state import VolumeState
+
+
+@dataclass(frozen=True)
+class AmesimPnl0001Diagnostics:
+    mass_flow_kg_s: float
+    reynolds_number: float
+    gas_velocity_m_s: float
+    friction_factor: float
+    pressure_drop_pa: float
+
+
+class _DarcyPipeResistanceMixin:
+    diameter: float
+    length: float
+    relative_roughness: float
+    area: float
+
+    def _mass_flow_for_pressure_drop(
+        self,
+        pressure_drop_pa: float,
+        *,
+        density: float,
+        temperature: float,
+    ) -> float:
+        if pressure_drop_pa <= 0.0:
+            return 0.0
+        upper = 1.0e-9
+        while self._darcy_pressure_drop(
+            upper,
+            density=density,
+            temperature=temperature,
+        ) < pressure_drop_pa:
+            upper *= 10.0
+            if upper > 1.0e3:
+                raise ValueError("unable to bracket pneumatic pipe resistance flow")
+        lower = 0.0
+        for _ in range(48):
+            middle = 0.5 * (lower + upper)
+            if self._darcy_pressure_drop(
+                middle,
+                density=density,
+                temperature=temperature,
+            ) < pressure_drop_pa:
+                lower = middle
+            else:
+                upper = middle
+        return 0.5 * (lower + upper)
+
+    def pn2pipefr_mass_flow(
+        self,
+        *,
+        port_1_pressure_pa: float,
+        port_1_temperature_k: float,
+        port_2_pressure_pa: float,
+        port_2_temperature_k: float,
+        length: float | None = None,
+    ) -> float:
+        pressure_difference = port_1_pressure_pa - port_2_pressure_pa
+        if pressure_difference == 0.0:
+            return 0.0
+        upstream_pressure = max(port_1_pressure_pa, port_2_pressure_pa)
+        downstream_pressure = min(port_1_pressure_pa, port_2_pressure_pa)
+        upstream_temperature = (
+            port_1_temperature_k
+            if pressure_difference > 0.0
+            else port_2_temperature_k
+        )
+        resistance_length = self.length if length is None else length
+        if resistance_length <= 0.0:
+            raise ValueError("length must be positive")
+
+        def target_flow(mass_flow_kg_s: float) -> float:
+            reynolds = self._reynolds_number(mass_flow_kg_s, upstream_temperature)
+            friction_factor = self._friction_factor(reynolds)
+            flow_coefficient = sqrt(
+                self.diameter / (resistance_length * friction_factor)
+            )
+            return compressible_orifice_mass_flow(
+                upstream_pressure=upstream_pressure,
+                downstream_pressure=downstream_pressure,
+                upstream_temperature=upstream_temperature,
+                area=self.area,
+                flow_coefficient=flow_coefficient,
+                gas=self.gas,
+            )
+
+        flow_coefficient = sqrt(self.diameter / (resistance_length * 0.02))
+        magnitude = compressible_orifice_mass_flow(
+            upstream_pressure=upstream_pressure,
+            downstream_pressure=downstream_pressure,
+            upstream_temperature=upstream_temperature,
+            area=self.area,
+            flow_coefficient=flow_coefficient,
+            gas=self.gas,
+        )
+        for _ in range(12):
+            next_magnitude = target_flow(magnitude)
+            if abs(next_magnitude - magnitude) <= max(1.0e-12, abs(magnitude) * 1.0e-9):
+                magnitude = next_magnitude
+                break
+            magnitude = 0.5 * (magnitude + next_magnitude)
+        return magnitude if pressure_difference > 0.0 else -magnitude
+
+    def _darcy_pressure_drop(
+        self,
+        mass_flow_kg_s: float,
+        *,
+        density: float,
+        temperature: float,
+    ) -> float:
+        if mass_flow_kg_s == 0.0:
+            return 0.0
+        reynolds = self._reynolds_number(mass_flow_kg_s, temperature)
+        friction_factor = self._friction_factor(reynolds)
+        velocity = mass_flow_kg_s / (density * self.area)
+        magnitude = (
+            friction_factor
+            * (self.length / self.diameter)
+            * density
+            * velocity
+            * velocity
+            / 2.0
+        )
+        return magnitude if mass_flow_kg_s > 0.0 else -magnitude
+
+    def _reynolds_number(self, mass_flow_kg_s: float, temperature: float) -> float:
+        viscosity = helium_dynamic_viscosity(temperature)
+        return 4.0 * abs(mass_flow_kg_s) / (pi * self.diameter * viscosity)
+
+    def _friction_factor(self, reynolds_number: float) -> float:
+        if reynolds_number <= 0.0:
+            return 64_000_000.0
+        laminar = 64.0 / reynolds_number
+        if reynolds_number <= 2_300.0:
+            return laminar
+        turbulent = 1.0 / (
+            -1.8
+            * log10(
+                (self.relative_roughness / 3.7) ** 1.11
+                + 6.9 / reynolds_number
+            )
+        ) ** 2
+        if reynolds_number >= 4_000.0:
+            return turbulent
+        fraction = (reynolds_number - 2_300.0) / 1_700.0
+        return laminar + fraction * (turbulent - laminar)
+
+
+class AmesimPnl0001Pipe(_DarcyPipeResistanceMixin, DynamicComponent):
+    """Physical first-pass implementation of AMESim ``PNL0001`` (C-R).
+
+    Port 2 owns the lumped gas storage. Port 1 is connected through a Darcy
+    resistance. Both connection mass flows use the simulation convention:
+    positive values enter the pipe storage.
+
+    AMESim's proprietary ``pn2pipefr`` utility is represented by an
+    optional calibrated linear conductance when a model-specific baseline
+    supports it; otherwise the component falls back to an auditable
+    Darcy-Weisbach law. Both paths preserve the real geometry, state count,
+    mass/energy balance, heat-transfer parameter, and observable diagnostics.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        diameter_mm: float,
+        length_m: float,
+        relative_roughness: float,
+        polytropic_constant: float = 1.35,
+        heat_transfer_coefficient: float = 0.0,
+        external_temperature_k: float = 293.15,
+        calibrated_linear_conductance: float | None = None,
+        gas: AmesimPneumaticGas = HELIUM_PNEUMATIC_GAS,
+        p0: float = 101_325.0,
+        T0: float = 293.15,
+    ) -> None:
+        if diameter_mm <= 0.0:
+            raise ValueError("diameter_mm must be positive")
+        if length_m <= 0.0:
+            raise ValueError("length_m must be positive")
+        if relative_roughness < 0.0:
+            raise ValueError("relative_roughness must be non-negative")
+        if polytropic_constant <= 0.0:
+            raise ValueError("polytropic_constant must be positive")
+        if heat_transfer_coefficient < 0.0:
+            raise ValueError("heat_transfer_coefficient must be non-negative")
+        if external_temperature_k <= 0.0:
+            raise ValueError("external_temperature_k must be positive")
+        if (
+            calibrated_linear_conductance is not None
+            and calibrated_linear_conductance <= 0.0
+        ):
+            raise ValueError("calibrated_linear_conductance must be positive")
+
+        super().__init__(name=name)
+        self.diameter = diameter_mm * 1.0e-3
+        self.length = length_m
+        self.relative_roughness = relative_roughness
+        self.polytropic_constant = polytropic_constant
+        self.heat_transfer_coefficient = heat_transfer_coefficient
+        self.external_temperature = external_temperature_k
+        self.calibrated_linear_conductance = calibrated_linear_conductance
+        self.gas = gas
+        self.area = diameter_mm_to_area_m2(diameter_mm)
+        self.volume = self.area * self.length
+        self.heat_transfer_area = pi * self.diameter * self.length
+
+        rho0 = gas.density(p0, T0)
+        mass0 = rho0 * self.volume
+        self.state = VolumeState(
+            m=mass0,
+            U=mass0 * gas.specific_internal_energy(T0),
+        )
+        self.port_1 = PortState()
+        self.port_2 = PortState()
+
+    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 properties(self) -> ThermodynamicProperties:
+        if self.state.m <= 0.0:
+            raise ValueError("pipe mass must stay positive")
+        temperature = self.gas.temperature_from_internal_energy(
+            self.state.U / self.state.m
+        )
+        density = self.state.m / self.volume
+        pressure = self.gas.pressure(density, temperature)
+        properties = ThermodynamicProperties(
+            p=pressure,
+            T=temperature,
+            rho=density,
+            u=self.state.U / self.state.m,
+            h=self.gas.specific_enthalpy(temperature),
+        )
+        self.port_2.p = pressure
+        self.port_2.h_outflow = properties.h
+        return properties
+
+    def gas_mass_g(self) -> float:
+        return self.state.m * 1.0e3
+
+    def resistance_mass_flow(
+        self,
+        *,
+        port_1_pressure_pa: float,
+        port_1_temperature_k: float,
+    ) -> float:
+        """Return mass flow from port 1 into the port-2 storage in kg/s."""
+        if port_1_pressure_pa <= 0.0:
+            raise ValueError("port_1_pressure_pa must be positive")
+        if port_1_temperature_k <= 0.0:
+            raise ValueError("port_1_temperature_k must be positive")
+
+        internal = self.properties()
+        pressure_difference = port_1_pressure_pa - internal.p
+        if pressure_difference == 0.0:
+            return 0.0
+        if self.calibrated_linear_conductance is not None:
+            return (
+                self.calibrated_linear_conductance
+                * pressure_difference
+                / sqrt(internal.T)
+            )
+        upstream_pressure = max(port_1_pressure_pa, internal.p)
+        upstream_temperature = (
+            port_1_temperature_k if pressure_difference > 0.0 else internal.T
+        )
+        density = self.gas.density(upstream_pressure, upstream_temperature)
+        magnitude = self._mass_flow_for_pressure_drop(
+            abs(pressure_difference),
+            density=density,
+            temperature=upstream_temperature,
+        )
+        return magnitude if pressure_difference > 0.0 else -magnitude
+
+    def diagnostics(
+        self,
+        *,
+        mass_flow_kg_s: float,
+        temperature_k: float | None = None,
+    ) -> AmesimPnl0001Diagnostics:
+        properties = self.properties()
+        temperature = temperature_k or properties.T
+        reynolds = self._reynolds_number(mass_flow_kg_s, temperature)
+        friction_factor = self._friction_factor(reynolds)
+        velocity = mass_flow_kg_s / (properties.rho * self.area)
+        pressure_drop = self._darcy_pressure_drop(
+            mass_flow_kg_s,
+            density=properties.rho,
+            temperature=temperature,
+        )
+        return AmesimPnl0001Diagnostics(
+            mass_flow_kg_s=mass_flow_kg_s,
+            reynolds_number=reynolds,
+            gas_velocity_m_s=velocity,
+            friction_factor=friction_factor,
+            pressure_drop_pa=pressure_drop,
+        )
+
+    def darcy_pressure_drop_for_state(
+        self,
+        *,
+        mass_flow_kg_s: float,
+        pressure_pa: float,
+        temperature_k: float,
+    ) -> float:
+        if pressure_pa <= 0.0:
+            raise ValueError("pressure_pa must be positive")
+        if temperature_k <= 0.0:
+            raise ValueError("temperature_k must be positive")
+        density = self.gas.density(pressure_pa, temperature_k)
+        return self._darcy_pressure_drop(
+            mass_flow_kg_s,
+            density=density,
+            temperature=temperature_k,
+        )
+
+    def derivatives_from_connections(
+        self,
+        *,
+        port_1_m_flow: float,
+        connected_h_1: float,
+        port_2_m_flow: float,
+        connected_h_2: float,
+    ) -> VolumeState:
+        internal = self.properties()
+        # Default first-pass PNL0001 behavior uses the historical internal-energy
+        # approximation. AMESim-specific transport-enthalpy corrections are kept
+        # behind derivatives_from_transport_enthalpy_connections so they can be
+        # applied only where validated against baseline data.
+        inlet_u_1 = (
+            connected_h_1 / self.gas.gamma
+            if port_1_m_flow > 0.0
+            else internal.u
+        )
+        inlet_u_2 = (
+            connected_h_2 / self.gas.gamma
+            if port_2_m_flow > 0.0
+            else internal.u
+        )
+        heat_flow = (
+            self.heat_transfer_coefficient
+            * self.heat_transfer_area
+            * (self.external_temperature - internal.T)
+        )
+        return VolumeState(
+            m=port_1_m_flow + port_2_m_flow,
+            U=port_1_m_flow * inlet_u_1 + port_2_m_flow * inlet_u_2 + heat_flow,
+        )
+
+    def derivatives_from_transport_enthalpy_connections(
+        self,
+        *,
+        port_1_m_flow: float,
+        connected_h_1: float,
+        port_2_m_flow: float,
+        connected_h_2: float,
+    ) -> VolumeState:
+        internal = self.properties()
+        inlet_h_1 = connected_h_1 if port_1_m_flow > 0.0 else internal.h
+        inlet_h_2 = connected_h_2 if port_2_m_flow > 0.0 else internal.h
+        heat_flow = (
+            self.heat_transfer_coefficient
+            * self.heat_transfer_area
+            * (self.external_temperature - internal.T)
+        )
+        return VolumeState(
+            m=port_1_m_flow + port_2_m_flow,
+            U=port_1_m_flow * inlet_h_1 + port_2_m_flow * inlet_h_2 + heat_flow,
+        )
+
+
+class AmesimPnl0003Pipe(_DarcyPipeResistanceMixin, DynamicComponent):
+    """First-pass AMESim ``PNL0003`` (C-R-C) pipe.
+
+    The two pipe-end compliances are represented as equal half-volume gas
+    stores connected by the same auditable Darcy resistance used for PNL0001.
+    Center flow is positive from port 1 storage to port 2 storage.
+    """
+
+    state_size = 4
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        diameter_mm: float,
+        length_m: float,
+        relative_roughness: float,
+        polytropic_constant: float = 1.35,
+        heat_transfer_coefficient: float = 0.0,
+        external_temperature_k: float = 293.15,
+        gas: AmesimPneumaticGas = HELIUM_PNEUMATIC_GAS,
+        p1_0: float = 101_325.0,
+        T1_0: float = 293.15,
+        p2_0: float = 101_325.0,
+        T2_0: float = 293.15,
+    ) -> None:
+        if diameter_mm <= 0.0:
+            raise ValueError("diameter_mm must be positive")
+        if length_m <= 0.0:
+            raise ValueError("length_m must be positive")
+        if relative_roughness < 0.0:
+            raise ValueError("relative_roughness must be non-negative")
+        if polytropic_constant <= 0.0:
+            raise ValueError("polytropic_constant must be positive")
+        if heat_transfer_coefficient < 0.0:
+            raise ValueError("heat_transfer_coefficient must be non-negative")
+        if external_temperature_k <= 0.0:
+            raise ValueError("external_temperature_k must be positive")
+
+        super().__init__(name=name)
+        self.diameter = diameter_mm * 1.0e-3
+        self.length = length_m
+        self.relative_roughness = relative_roughness
+        self.polytropic_constant = polytropic_constant
+        self.heat_transfer_coefficient = heat_transfer_coefficient
+        self.external_temperature = external_temperature_k
+        self.gas = gas
+        self.area = diameter_mm_to_area_m2(diameter_mm)
+        self.volume = self.area * self.length
+        self.compliance_volume = self.volume / 2.0
+        self.heat_transfer_area = pi * self.diameter * self.length
+
+        self.state_1 = self._initial_state(p1_0, T1_0)
+        self.state_2 = self._initial_state(p2_0, T2_0)
+        self.port_1 = PortState()
+        self.port_2 = PortState()
+
+    def _initial_state(self, pressure: float, temperature: float) -> VolumeState:
+        rho = self.gas.density(pressure, temperature)
+        mass = rho * self.compliance_volume
+        return VolumeState(
+            m=mass,
+            U=mass * self.gas.specific_internal_energy(temperature),
+        )
+
+    def get_state_vector(self) -> list[float]:
+        return [*self.state_1.as_vector(), *self.state_2.as_vector()]
+
+    def set_state_vector(self, values: list[float]) -> None:
+        if len(values) != 4:
+            raise ValueError("PNL0003 state vector requires four values")
+        self.state_1 = VolumeState.from_vector(values[:2])
+        self.state_2 = VolumeState.from_vector(values[2:])
+
+    def properties_1(self) -> ThermodynamicProperties:
+        properties = self._properties(self.state_1)
+        self.port_1.p = properties.p
+        self.port_1.h_outflow = properties.h
+        return properties
+
+    def properties_2(self) -> ThermodynamicProperties:
+        properties = self._properties(self.state_2)
+        self.port_2.p = properties.p
+        self.port_2.h_outflow = properties.h
+        return properties
+
+    def _properties(self, state: VolumeState) -> ThermodynamicProperties:
+        if state.m <= 0.0:
+            raise ValueError("pipe mass must stay positive")
+        temperature = self.gas.temperature_from_internal_energy(state.U / state.m)
+        density = state.m / self.compliance_volume
+        pressure = self.gas.pressure(density, temperature)
+        return ThermodynamicProperties(
+            p=pressure,
+            T=temperature,
+            rho=density,
+            u=state.U / state.m,
+            h=self.gas.specific_enthalpy(temperature),
+        )
+
+    def gas_mass_g(self) -> float:
+        return (self.state_1.m + self.state_2.m) * 1.0e3
+
+    def resistance_mass_flow(self) -> float:
+        """Return center mass flow from port 1 storage to port 2 storage."""
+        port_1 = self.properties_1()
+        port_2 = self.properties_2()
+        pressure_difference = port_1.p - port_2.p
+        if pressure_difference == 0.0:
+            return 0.0
+        upstream = port_1 if pressure_difference > 0.0 else port_2
+        magnitude = self._mass_flow_for_pressure_drop(
+            abs(pressure_difference),
+            density=upstream.rho,
+            temperature=upstream.T,
+        )
+        return magnitude if pressure_difference > 0.0 else -magnitude
+
+    def diagnostics(
+        self,
+        *,
+        mass_flow_kg_s: float,
+        temperature_k: float | None = None,
+    ) -> AmesimPnl0001Diagnostics:
+        port_1 = self.properties_1()
+        port_2 = self.properties_2()
+        temperature = temperature_k or (port_1.T if mass_flow_kg_s >= 0.0 else port_2.T)
+        density = port_1.rho if mass_flow_kg_s >= 0.0 else port_2.rho
+        reynolds = self._reynolds_number(mass_flow_kg_s, temperature)
+        friction_factor = self._friction_factor(reynolds)
+        velocity = mass_flow_kg_s / (density * self.area)
+        pressure_drop = self._darcy_pressure_drop(
+            mass_flow_kg_s,
+            density=density,
+            temperature=temperature,
+        )
+        return AmesimPnl0001Diagnostics(
+            mass_flow_kg_s=mass_flow_kg_s,
+            reynolds_number=reynolds,
+            gas_velocity_m_s=velocity,
+            friction_factor=friction_factor,
+            pressure_drop_pa=pressure_drop,
+        )
+
+    def derivatives_from_connections(
+        self,
+        *,
+        port_1_m_flow: float,
+        connected_h_1: float,
+        port_2_m_flow: float,
+        connected_h_2: float,
+    ) -> tuple[VolumeState, VolumeState]:
+        port_1 = self.properties_1()
+        port_2 = self.properties_2()
+        center_flow = self.resistance_mass_flow()
+        heat_flow_each = (
+            self.heat_transfer_coefficient
+            * self.heat_transfer_area
+            * (self.external_temperature - 0.5 * (port_1.T + port_2.T))
+            / 2.0
+        )
+        port_1_external_h = self.connection_inlet_enthalpy(
+            port_m_flow=port_1_m_flow,
+            connected_h=connected_h_1,
+            internal_h=port_1.h,
+        )
+        port_2_external_h = self.connection_inlet_enthalpy(
+            port_m_flow=port_2_m_flow,
+            connected_h=connected_h_2,
+            internal_h=port_2.h,
+        )
+        port_1_center_h = self.connection_inlet_enthalpy(
+            port_m_flow=-center_flow,
+            connected_h=port_2.h,
+            internal_h=port_1.h,
+        )
+        port_2_center_h = self.connection_inlet_enthalpy(
+            port_m_flow=center_flow,
+            connected_h=port_1.h,
+            internal_h=port_2.h,
+        )
+        return (
+            VolumeState(
+                m=port_1_m_flow - center_flow,
+                U=(
+                    port_1_m_flow * port_1_external_h
+                    - center_flow * port_1_center_h
+                    + heat_flow_each
+                ),
+            ),
+            VolumeState(
+                m=port_2_m_flow + center_flow,
+                U=(
+                    port_2_m_flow * port_2_external_h
+                    + center_flow * port_2_center_h
+                    + heat_flow_each
+                ),
+            ),
+        )
+
+
+class AmesimPnl0002Pipe(_DarcyPipeResistanceMixin, DynamicComponent):
+    """First-pass AMESim ``PNL0002`` (R-C-R) pipe.
+
+    The center compliance owns the gas state. Positive connection mass flows
+    enter that center storage from each external port.
+    """
+
+    state_size = 2
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        diameter_mm: float,
+        length_m: float,
+        relative_roughness: float,
+        polytropic_constant: float = 1.35,
+        heat_transfer_coefficient: float = 0.0,
+        external_temperature_k: float = 293.15,
+        gas: AmesimPneumaticGas = HELIUM_PNEUMATIC_GAS,
+        pctr_0: float = 101_325.0,
+        Tctr_0: float = 293.15,
+    ) -> None:
+        if diameter_mm <= 0.0:
+            raise ValueError("diameter_mm must be positive")
+        if length_m <= 0.0:
+            raise ValueError("length_m must be positive")
+        if relative_roughness < 0.0:
+            raise ValueError("relative_roughness must be non-negative")
+        if polytropic_constant <= 0.0:
+            raise ValueError("polytropic_constant must be positive")
+        if heat_transfer_coefficient < 0.0:
+            raise ValueError("heat_transfer_coefficient must be non-negative")
+        if external_temperature_k <= 0.0:
+            raise ValueError("external_temperature_k must be positive")
+
+        super().__init__(name=name)
+        self.diameter = diameter_mm * 1.0e-3
+        self.length = length_m
+        self.relative_roughness = relative_roughness
+        self.polytropic_constant = polytropic_constant
+        self.heat_transfer_coefficient = heat_transfer_coefficient
+        self.external_temperature = external_temperature_k
+        self.gas = gas
+        self.area = diameter_mm_to_area_m2(diameter_mm)
+        self.volume = self.area * self.length
+        self.heat_transfer_area = pi * self.diameter * self.length
+        self._resistance_length = self.length / 2.0
+
+        rho0 = gas.density(pctr_0, Tctr_0)
+        mass0 = rho0 * self.volume
+        self.state = VolumeState(
+            m=mass0,
+            U=mass0 * gas.specific_internal_energy(Tctr_0),
+        )
+        self.port_1 = PortState()
+        self.port_2 = PortState()
+
+    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 properties(self) -> ThermodynamicProperties:
+        if self.state.m <= 0.0:
+            raise ValueError("pipe mass must stay positive")
+        temperature = self.gas.temperature_from_internal_energy(
+            self.state.U / self.state.m
+        )
+        density = self.state.m / self.volume
+        pressure = self.gas.pressure(density, temperature)
+        properties = ThermodynamicProperties(
+            p=pressure,
+            T=temperature,
+            rho=density,
+            u=self.state.U / self.state.m,
+            h=self.gas.specific_enthalpy(temperature),
+        )
+        self.port_1.p = pressure
+        self.port_1.h_outflow = properties.h
+        self.port_2.p = pressure
+        self.port_2.h_outflow = properties.h
+        return properties
+
+    def gas_mass_g(self) -> float:
+        return self.state.m * 1.0e3
+
+    def port_mass_flow(
+        self,
+        *,
+        port_pressure_pa: float,
+        port_temperature_k: float,
+    ) -> float:
+        """Return mass flow from an external port into the center storage."""
+        if port_pressure_pa <= 0.0:
+            raise ValueError("port_pressure_pa must be positive")
+        if port_temperature_k <= 0.0:
+            raise ValueError("port_temperature_k must be positive")
+
+        center = self.properties()
+        pressure_difference = port_pressure_pa - center.p
+        if pressure_difference == 0.0:
+            return 0.0
+        upstream_pressure = max(port_pressure_pa, center.p)
+        upstream_temperature = (
+            port_temperature_k if pressure_difference > 0.0 else center.T
+        )
+        density = self.gas.density(upstream_pressure, upstream_temperature)
+        magnitude = self._mass_flow_for_resistance_pressure_drop(
+            abs(pressure_difference),
+            density=density,
+            temperature=upstream_temperature,
+        )
+        return magnitude if pressure_difference > 0.0 else -magnitude
+
+    def _mass_flow_for_resistance_pressure_drop(
+        self,
+        pressure_drop_pa: float,
+        *,
+        density: float,
+        temperature: float,
+    ) -> float:
+        original_length = self.length
+        self.length = self._resistance_length
+        try:
+            return self._mass_flow_for_pressure_drop(
+                pressure_drop_pa,
+                density=density,
+                temperature=temperature,
+            )
+        finally:
+            self.length = original_length
+
+    def diagnostics(
+        self,
+        *,
+        mass_flow_kg_s: float,
+        temperature_k: float | None = None,
+    ) -> AmesimPnl0001Diagnostics:
+        properties = self.properties()
+        temperature = temperature_k or properties.T
+        reynolds = self._reynolds_number(mass_flow_kg_s, temperature)
+        friction_factor = self._friction_factor(reynolds)
+        velocity = mass_flow_kg_s / (properties.rho * self.area)
+        original_length = self.length
+        self.length = self._resistance_length
+        try:
+            pressure_drop = self._darcy_pressure_drop(
+                mass_flow_kg_s,
+                density=properties.rho,
+                temperature=temperature,
+            )
+        finally:
+            self.length = original_length
+        return AmesimPnl0001Diagnostics(
+            mass_flow_kg_s=mass_flow_kg_s,
+            reynolds_number=reynolds,
+            gas_velocity_m_s=velocity,
+            friction_factor=friction_factor,
+            pressure_drop_pa=pressure_drop,
+        )
+
+    def derivatives_from_connections(
+        self,
+        *,
+        port_1_m_flow: float,
+        connected_h_1: float,
+        port_2_m_flow: float,
+        connected_h_2: float,
+    ) -> VolumeState:
+        center = self.properties()
+        inlet_h_1 = self.connection_inlet_enthalpy(
+            port_m_flow=port_1_m_flow,
+            connected_h=connected_h_1,
+            internal_h=center.h,
+        )
+        inlet_h_2 = self.connection_inlet_enthalpy(
+            port_m_flow=port_2_m_flow,
+            connected_h=connected_h_2,
+            internal_h=center.h,
+        )
+        heat_flow = (
+            self.heat_transfer_coefficient
+            * self.heat_transfer_area
+            * (self.external_temperature - center.T)
+        )
+        return VolumeState(
+            m=port_1_m_flow + port_2_m_flow,
+            U=port_1_m_flow * inlet_h_1 + port_2_m_flow * inlet_h_2 + heat_flow,
+        )
+
+
+class AmesimPnl00rPipe(_DarcyPipeResistanceMixin, AlgebraicComponent):
+    """First-pass AMESim ``PNL00R`` (R) pipe resistance."""
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        diameter_mm: float,
+        length_m: float,
+        relative_roughness: float,
+        gas: AmesimPneumaticGas = HELIUM_PNEUMATIC_GAS,
+    ) -> None:
+        if diameter_mm <= 0.0:
+            raise ValueError("diameter_mm must be positive")
+        if length_m <= 0.0:
+            raise ValueError("length_m must be positive")
+        if relative_roughness < 0.0:
+            raise ValueError("relative_roughness must be non-negative")
+
+        super().__init__(name=name)
+        self.diameter = diameter_mm * 1.0e-3
+        self.length = length_m
+        self.relative_roughness = relative_roughness
+        self.gas = gas
+        self.area = diameter_mm_to_area_m2(diameter_mm)
+        self.port_1 = PortState()
+        self.port_2 = PortState()
+
+    def mass_flow(
+        self,
+        *,
+        port_1_pressure_pa: float,
+        port_1_temperature_k: float,
+        port_2_pressure_pa: float,
+        port_2_temperature_k: float,
+    ) -> float:
+        """Return mass flow from port 1 to port 2 in kg/s."""
+        if port_1_pressure_pa <= 0.0 or port_2_pressure_pa <= 0.0:
+            raise ValueError("port pressures must be positive")
+        if port_1_temperature_k <= 0.0 or port_2_temperature_k <= 0.0:
+            raise ValueError("port temperatures must be positive")
+        pressure_difference = port_1_pressure_pa - port_2_pressure_pa
+        if pressure_difference == 0.0:
+            return 0.0
+        upstream_pressure = max(port_1_pressure_pa, port_2_pressure_pa)
+        upstream_temperature = (
+            port_1_temperature_k
+            if pressure_difference > 0.0
+            else port_2_temperature_k
+        )
+        density = self.gas.density(upstream_pressure, upstream_temperature)
+        magnitude = self._mass_flow_for_pressure_drop(
+            abs(pressure_difference),
+            density=density,
+            temperature=upstream_temperature,
+        )
+        return magnitude if pressure_difference > 0.0 else -magnitude
+
+    def diagnostics(
+        self,
+        *,
+        mass_flow_kg_s: float,
+        pressure_pa: float,
+        temperature_k: float,
+    ) -> AmesimPnl0001Diagnostics:
+        density = self.gas.density(pressure_pa, temperature_k)
+        reynolds = self._reynolds_number(mass_flow_kg_s, temperature_k)
+        friction_factor = self._friction_factor(reynolds)
+        velocity = mass_flow_kg_s / (density * self.area)
+        pressure_drop = self._darcy_pressure_drop(
+            mass_flow_kg_s,
+            density=density,
+            temperature=temperature_k,
+        )
+        return AmesimPnl0001Diagnostics(
+            mass_flow_kg_s=mass_flow_kg_s,
+            reynolds_number=reynolds,
+            gas_velocity_m_s=velocity,
+            friction_factor=friction_factor,
+            pressure_drop_pa=pressure_drop,
+        )
+
+
+def helium_dynamic_viscosity(temperature_k: float) -> float:
+    """Sutherland approximation centered on the test_mql initial condition."""
+    if temperature_k <= 0.0:
+        raise ValueError("temperature_k must be positive")
+    reference_temperature = 293.15
+    reference_viscosity = 2.0e-5
+    sutherland_constant = 79.4
+    return (
+        reference_viscosity
+        * (temperature_k / reference_temperature) ** 1.5
+        * (reference_temperature + sutherland_constant)
+        / (temperature_k + sutherland_constant)
+    )
@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+from app.simulation.paths import PROJECT_ROOT, SIMULATION_RUNS_DIR
+from app.simulation.examples.test_mql.system import (
+    TestMqlRunConfig,
+    TestMqlSimulationResult,
+    TestMqlSystem,
+)
+
+
+@dataclass(frozen=True)
+class PreparedTestMqlRun:
+    run_config: TestMqlRunConfig
+    repo_root: Path
+    output_dir: Path
+
+
+@dataclass(frozen=True)
+class TestMqlRunResult:
+    run_config: TestMqlRunConfig
+    prepared_run: PreparedTestMqlRun
+    system: TestMqlSystem
+    result: TestMqlSimulationResult
+    summary_path: Path
+
+
+def format_test_mql_summary(system: TestMqlSystem) -> str:
+    snapshot = system.snapshot()
+    lines = [
+        "Model: test_mql",
+        f"Source archive: {system.archive_path}",
+        f"Components: {snapshot.component_count}",
+        f"Connections: {snapshot.connection_count}",
+        f"Continuous states in AMESim modelinfo: {snapshot.continuous_state_count}",
+        f"Discrete states in AMESim modelinfo: {snapshot.discrete_state_count}",
+        "Global parameters:",
+    ]
+    for name, value in sorted(snapshot.global_parameters.items()):
+        lines.append(f"  - {name}: {value}")
+    lines.append("Component submodels:")
+    for name, count in sorted(snapshot.submodel_counts.items()):
+        lines.append(f"  - {name}: {count}")
+    return "\n".join(lines) + "\n"
+
+
+def _default_run_output_dir() -> Path:
+    timestamp = datetime.now(UTC).strftime("test_mql_%Y%m%d_%H%M%S_%f")
+    return SIMULATION_RUNS_DIR / timestamp
+
+
+def prepare_test_mql_run(
+    *,
+    run_config: TestMqlRunConfig | None = None,
+    output_dir: Path | None = None,
+) -> PreparedTestMqlRun:
+    return PreparedTestMqlRun(
+        run_config=run_config or TestMqlRunConfig(),
+        repo_root=PROJECT_ROOT,
+        output_dir=output_dir or _default_run_output_dir(),
+    )
+
+
+def run_prepared_test_mql(prepared_run: PreparedTestMqlRun) -> TestMqlRunResult:
+    system = TestMqlSystem()
+    result = system.simulate(prepared_run.run_config)
+    prepared_run.output_dir.mkdir(parents=True, exist_ok=True)
+    summary_path = prepared_run.output_dir / "test_mql_model_summary.txt"
+    summary_path.write_text(format_test_mql_summary(system), encoding="utf-8")
+    return TestMqlRunResult(
+        run_config=prepared_run.run_config,
+        prepared_run=prepared_run,
+        system=system,
+        result=result,
+        summary_path=summary_path,
+    )
+
+
+def run_test_mql(
+    *,
+    run_config: TestMqlRunConfig | None = None,
+    output_dir: Path | None = None,
+) -> TestMqlRunResult:
+    return run_prepared_test_mql(
+        prepare_test_mql_run(run_config=run_config, output_dir=output_dir)
+    )
+
+
+def main() -> None:
+    run = run_test_mql()
+    print(format_test_mql_summary(run.system), end="")
+    print(f"Samples: {len(run.result.t)}")
+    print(f"Output directory: {run.prepared_run.output_dir}")
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+
+from app.simulation.examples.test_mql.baseline import (
+    TestMqlBaselineRun,
+    run_test_mql_baseline_passthrough,
+)
+from app.simulation.paths import (
+    AMESIM_TEST_MQL_ARCHIVE_PATH,
+    SIMULATION_RUNS_DIR,
+)
+
+
+@dataclass(frozen=True)
+class TestMqlBaselinePathConfig:
+    archive_path: Path = field(
+        default_factory=lambda: AMESIM_TEST_MQL_ARCHIVE_PATH
+    )
+    output_dir: Path | None = None
+
+
+@dataclass(frozen=True)
+class TestMqlBaselineExecutionConfig:
+    write_summary: bool = True
+    data_paths: tuple[str, ...] | None = None
+
+
+@dataclass(frozen=True)
+class TestMqlBaselineScriptConfig:
+    paths: TestMqlBaselinePathConfig = field(default_factory=TestMqlBaselinePathConfig)
+    execution: TestMqlBaselineExecutionConfig = field(default_factory=TestMqlBaselineExecutionConfig)
+
+
+def _default_output_dir() -> Path:
+    timestamp = datetime.now(UTC).strftime("test_mql_baseline_%Y%m%d_%H%M%S_%f")
+    return SIMULATION_RUNS_DIR / timestamp
+
+
+def format_test_mql_baseline_summary(run: TestMqlBaselineRun) -> str:
+    return "\n".join(
+        [
+            "Model: test_mql",
+            "Mode: AMESim baseline passthrough",
+            f"Samples: {run.sample_count}",
+            f"Output schema signals: {run.output_schema.signal_count}",
+            f"Compared signals: {run.signal_count}",
+            f"Observation bindings: {run.observation_catalog.binding_count}",
+            f"Max absolute error: {run.comparison.max_abs_error}",
+            f"Max relative error: {run.comparison.max_rel_error}",
+        ]
+    ) + "\n"
+
+
+def run_test_mql_baseline(config: TestMqlBaselineScriptConfig | None = None):
+    config = config or TestMqlBaselineScriptConfig()
+    run = run_test_mql_baseline_passthrough(
+        config.paths.archive_path,
+        data_paths=config.execution.data_paths,
+    )
+    output_dir = config.paths.output_dir or _default_output_dir()
+    if config.execution.write_summary:
+        output_dir.mkdir(parents=True, exist_ok=True)
+        (output_dir / "test_mql_baseline_summary.txt").write_text(
+            format_test_mql_baseline_summary(run),
+            encoding="utf-8",
+        )
+    return run, output_dir
+
+
+def main() -> None:
+    run, output_dir = run_test_mql_baseline()
+    print(format_test_mql_baseline_summary(run), end="")
+    print(f"Output directory: {output_dir}")
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from app.simulation.solvers.solver import (
+    SolveIVPConfig as _BaseSolveIVPConfig,
+    integrate_ode,
+)
+
+
+@dataclass(frozen=True)
+class SolveIVPConfig(_BaseSolveIVPConfig):
+    """Solver defaults used by the calibrated ``test_mql`` example."""
+
+    atol: float = 1e-10
+
+
+__all__ = ["SolveIVPConfig", "integrate_ode"]
@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from app.simulation.core.base import Component, DynamicComponent
+
+
+@dataclass(frozen=True)
+class Connection:
+    source_component: str
+    source_port: str
+    target_component: str
+    target_port: str
+
+
+class SimulationNetwork:
+    """Container for components, topology, and state-vector bookkeeping."""
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        self.components: dict[str, Component] = {}
+        self.connections: list[Connection] = []
+
+    def add_component(self, component: Component) -> None:
+        if component.name in self.components:
+            raise ValueError(f"Duplicate component name: {component.name}")
+        self.components[component.name] = component
+
+    def connect(
+        self,
+        source_component: str,
+        source_port: str,
+        target_component: str,
+        target_port: str,
+    ) -> None:
+        self.connections.append(
+            Connection(
+                source_component=source_component,
+                source_port=source_port,
+                target_component=target_component,
+                target_port=target_port,
+            )
+        )
+
+    def dynamic_components(self) -> list[DynamicComponent]:
+        return [
+            component
+            for component in self.components.values()
+            if isinstance(component, DynamicComponent)
+        ]
+
+    def initial_state_vector(self) -> list[float]:
+        values: list[float] = []
+        for component in self.dynamic_components():
+            values.extend(component.get_state_vector())
+        return values
+
+    def apply_state_vector(self, values: list[float]) -> None:
+        cursor = 0
+        for component in self.dynamic_components():
+            next_cursor = cursor + component.state_size
+            component.set_state_vector(values[cursor:next_cursor])
+            cursor = next_cursor
+        if cursor != len(values):
+            raise ValueError("State vector length does not match dynamic components.")
+
+    def summary(self) -> str:
+        lines = [f"Network: {self.name}", "Components:"]
+        for name, component in self.components.items():
+            lines.append(f"  - {name}: {component.__class__.__name__}")
+        lines.append("Connections:")
+        for conn in self.connections:
+            lines.append(
+                f"  - {conn.source_component}.{conn.source_port}"
+                f" -> {conn.target_component}.{conn.target_port}"
+            )
+        return "\n".join(lines)
+
@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import re
+import tarfile
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class TestMqlComponentContact:
+    component_a: str
+    port_a: str
+    component_b: str
+    port_b: str
+
+    def other_endpoint(self, component_alias: str) -> tuple[str, str]:
+        if component_alias == self.component_a:
+            return self.component_b, self.port_b
+        if component_alias == self.component_b:
+            return self.component_a, self.port_a
+        raise KeyError(component_alias)
+
+    def port_for(self, component_alias: str) -> str:
+        if component_alias == self.component_a:
+            return self.port_a
+        if component_alias == self.component_b:
+            return self.port_b
+        raise KeyError(component_alias)
+
+
+@dataclass(frozen=True)
+class TestMqlCirTopology:
+    component_contacts: tuple[TestMqlComponentContact, ...]
+
+    def contacts_for(self, component_alias: str) -> tuple[TestMqlComponentContact, ...]:
+        return tuple(
+            contact
+            for contact in self.component_contacts
+            if component_alias in (contact.component_a, contact.component_b)
+        )
+
+
+def load_test_mql_cir_topology(
+    archive_path: str | Path,
+    *,
+    cir_member: str = "test_mql_.cir",
+) -> TestMqlCirTopology:
+    with tarfile.open(archive_path) as archive:
+        cir_file = archive.extractfile(cir_member)
+        if cir_file is None:
+            raise ValueError(f"Missing AMESim circuit member: {cir_member}")
+        cir_text = cir_file.read().decode("latin1")
+
+    root = ET.fromstring(_topology_only_xml(cir_text))
+    components = root.findall(".//COMPS_LIST/COMP")
+    aliases = tuple(_required_text(component, "ALIAS") for component in components)
+    contacts: dict[
+        tuple[tuple[int, int], tuple[int, int]],
+        TestMqlComponentContact,
+    ] = {}
+    directed_contacts: set[tuple[tuple[int, int], tuple[int, int]]] = set()
+
+    for component_index, component in enumerate(components):
+        ports = component.findall("./COMP_PORTS_LIST/COMP_PORT")
+        for port_index, port in enumerate(ports):
+            if port.findtext("PORT_CONNECT") != "1":
+                continue
+            for connection in port.findall("./CONNECT_LIST/CONNECT"):
+                target_index = int(_required_text(connection, "CONNECT_ENTITY_NUM"))
+                target_port_index = int(_required_text(connection, "CONNECT_ENTITY_PORT"))
+                if target_index < 0 or target_index >= len(components):
+                    raise ValueError(f"Component contact references unknown entity {target_index}")
+                target_ports = components[target_index].findall("./COMP_PORTS_LIST/COMP_PORT")
+                if target_port_index < 0 or target_port_index >= len(target_ports):
+                    raise ValueError(
+                        f"Component contact references unknown port {target_port_index} "
+                        f"on {aliases[target_index]}"
+                    )
+
+                endpoint = (component_index, port_index)
+                target_endpoint = (target_index, target_port_index)
+                directed_contacts.add((endpoint, target_endpoint))
+                key = tuple(sorted((endpoint, target_endpoint)))
+                first, second = key
+                contacts[key] = TestMqlComponentContact(
+                    component_a=aliases[first[0]],
+                    port_a=f"port_{first[1] + 1}",
+                    component_b=aliases[second[0]],
+                    port_b=f"port_{second[1] + 1}",
+                )
+
+    for endpoint, target_endpoint in directed_contacts:
+        if (target_endpoint, endpoint) not in directed_contacts:
+            raise ValueError(
+                "AMESim component contact is not reciprocal: "
+                f"{endpoint} -> {target_endpoint}"
+            )
+
+    return TestMqlCirTopology(component_contacts=tuple(contacts.values()))
+
+
+def _topology_only_xml(cir_text: str) -> str:
+    # AMESim expressions inside SUBMODEL contain unescaped && and <= operators.
+    # Topology lives outside those blocks, so omit them before XML parsing.
+    return re.sub(
+        r"<SUBMODEL>.*?</SUBMODEL>",
+        "<SUBMODEL />",
+        cir_text,
+        flags=re.DOTALL,
+    )
+
+
+def _required_text(element: ET.Element, child_name: str) -> str:
+    value = element.findtext(child_name)
+    if value is None:
+        raise ValueError(f"Missing AMESim circuit element: {child_name}")
+    return value
@@ -0,0 +1 @@
+"""Legacy TestModel reference system."""
@@ -0,0 +1,668 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable
+
+from app.simulation.components.experimental.flow.orifice import Orifice
+from app.simulation.examples.testmodel.dynamic_pipe import Pipe
+from app.simulation.components.experimental.junctions.tee import Tee
+from app.simulation.components.experimental.storage.cylinder import Cylinder
+from app.simulation.components.experimental.storage.tank import Tank
+from app.simulation.core.medium import IdealGasMedium, ThermodynamicProperties
+from app.simulation.core.state import VolumeState
+
+
+@dataclass(frozen=True)
+class BranchInletFlowDiagnostics:
+    converged: bool
+    iterations: int
+    residual: float
+    m_flow: float
+    inlet_pressure: float
+
+
+@dataclass(frozen=True)
+class DownstreamPressureDiagnostics:
+    converged: bool
+    iterations: int
+    residual: float
+    pressure: float
+    target_total_internal_energy: float
+
+
+@dataclass(frozen=True)
+class TestModelSolveDiagnostics:
+    upper_branch_inlet: BranchInletFlowDiagnostics
+    lower_branch_inlet: BranchInletFlowDiagnostics
+    downstream_pressure_projection: DownstreamPressureDiagnostics | None
+
+
+@dataclass(frozen=True)
+class BranchClosureComponents:
+    name: str
+    orifice: Orifice
+    pipe: Pipe
+
+
+@dataclass(frozen=True)
+class BranchClosureState:
+    name: str
+    pipe: ThermodynamicProperties
+    inlet_flow: float
+    outlet_flow: float
+    inlet_h: float
+    inlet_flow_diagnostics: BranchInletFlowDiagnostics
+
+
+@dataclass(frozen=True)
+class BranchSnapshot:
+    name: str
+    pipe: ThermodynamicProperties
+    inlet_flow: float
+    outlet_flow: float
+    inlet_h: float
+    inlet_flow_diagnostics: BranchInletFlowDiagnostics
+
+
+@dataclass(frozen=True)
+class TestModelSnapshot:
+    cylinder: ThermodynamicProperties
+    tank: ThermodynamicProperties
+    tee_upstream_h: float
+    tee_downstream_h: float
+    branches: tuple[BranchSnapshot, ...] = field(default_factory=tuple)
+    solve_diagnostics: TestModelSolveDiagnostics | None = None
+
+    @property
+    def pipe_upper(self) -> ThermodynamicProperties:
+        return self.branches[0].pipe
+
+    @property
+    def pipe_lower(self) -> ThermodynamicProperties:
+        return self.branches[1].pipe
+
+    @property
+    def branch_inlet_flows(self) -> tuple[float, ...]:
+        return tuple(branch.inlet_flow for branch in self.branches)
+
+    @property
+    def branch_outlet_flows(self) -> tuple[float, ...]:
+        return tuple(branch.outlet_flow for branch in self.branches)
+
+
+@dataclass(frozen=True)
+class InitializationDiagnostics:
+    converged: bool
+    iterations: int
+    max_state_delta: float
+    max_flow_delta: float
+    max_enthalpy_delta: float
+    downstream_pressure_spread: float
+    state_vector: tuple[float, ...]
+
+
+@dataclass(frozen=True)
+class TestModelClosureComponents:
+    cylinder: Cylinder
+    upstream_tee: Tee
+    upper_branch: BranchClosureComponents
+    lower_branch: BranchClosureComponents
+    downstream_tee: Tee
+    tank: Tank
+
+    def branches(self) -> tuple[BranchClosureComponents, BranchClosureComponents]:
+        return (self.upper_branch, self.lower_branch)
+
+
+class TestModelClosure:
+    """Owns Testmodel-specific closure, projection and port-writeback logic."""
+
+    def __init__(
+        self,
+        *,
+        medium: IdealGasMedium,
+        components: TestModelClosureComponents,
+        initial_state_vector: Callable[[], list[float]],
+        apply_state_vector: Callable[[list[float]], None],
+    ) -> None:
+        self.medium = medium
+        self.components = components
+        self._initial_state_vector = initial_state_vector
+        self._apply_state_vector = apply_state_vector
+        self.last_solve_diagnostics: TestModelSolveDiagnostics | None = None
+        self.last_downstream_pressure_diagnostics: DownstreamPressureDiagnostics | None = None
+
+    @staticmethod
+    def _downstream_pressure_spread(snapshot: TestModelSnapshot) -> float:
+        downstream_pressures = tuple(branch.pipe.p for branch in snapshot.branches) + (
+            snapshot.tank.p,
+        )
+        return max(downstream_pressures) - min(downstream_pressures)
+
+    @staticmethod
+    def _initialization_flow_delta(
+        previous_snapshot: TestModelSnapshot | None,
+        current_snapshot: TestModelSnapshot,
+    ) -> float:
+        if previous_snapshot is None:
+            return max(abs(branch.outlet_flow) for branch in current_snapshot.branches)
+        return max(
+            abs(curr - prev)
+            for curr, prev in zip(
+                current_snapshot.branch_outlet_flows,
+                previous_snapshot.branch_outlet_flows,
+            )
+        )
+
+    @staticmethod
+    def _initialization_enthalpy_delta(
+        previous_snapshot: TestModelSnapshot | None,
+        current_snapshot: TestModelSnapshot,
+    ) -> float:
+        if previous_snapshot is None:
+            return abs(current_snapshot.tee_downstream_h - current_snapshot.tank.h)
+        return max(
+            abs(current_snapshot.tee_upstream_h - previous_snapshot.tee_upstream_h),
+            abs(current_snapshot.tee_downstream_h - previous_snapshot.tee_downstream_h),
+        )
+
+    def consistent_initial_state_vector(self) -> list[float]:
+        return list(self.initialize_consistent_state().state_vector)
+
+    def initialize_consistent_state(
+        self,
+        max_iterations: int = 12,
+        state_tolerance: float = 1e-9,
+        flow_tolerance: float = 1e-9,
+        enthalpy_tolerance: float = 1e-6,
+        pressure_tolerance: float = 1e-6,
+        strict_internal_solvers: bool = False,
+    ) -> InitializationDiagnostics:
+        raw_state = self._initial_state_vector()
+        previous_snapshot: TestModelSnapshot | None = None
+        diagnostics: InitializationDiagnostics | None = None
+
+        for iteration in range(1, max_iterations + 1):
+            state_before_projection = self._initial_state_vector()
+            self.snapshot(state_before_projection, strict=strict_internal_solvers)
+
+            self.project_downstream_pressure_constraints(strict=strict_internal_solvers)
+
+            state_after_projection = self._initial_state_vector()
+            snapshot_after_projection = self.snapshot(
+                state_after_projection,
+                strict=strict_internal_solvers,
+            )
+
+            max_state_delta = max(
+                abs(after - before)
+                for before, after in zip(state_before_projection, state_after_projection)
+            )
+            max_flow_delta = self._initialization_flow_delta(
+                previous_snapshot,
+                snapshot_after_projection,
+            )
+            max_enthalpy_delta = self._initialization_enthalpy_delta(
+                previous_snapshot,
+                snapshot_after_projection,
+            )
+            downstream_pressure_spread = self._downstream_pressure_spread(
+                snapshot_after_projection,
+            )
+
+            diagnostics = InitializationDiagnostics(
+                converged=(
+                    max_state_delta <= state_tolerance
+                    and max_flow_delta <= flow_tolerance
+                    and max_enthalpy_delta <= enthalpy_tolerance
+                    and downstream_pressure_spread <= pressure_tolerance
+                ),
+                iterations=iteration,
+                max_state_delta=max_state_delta,
+                max_flow_delta=max_flow_delta,
+                max_enthalpy_delta=max_enthalpy_delta,
+                downstream_pressure_spread=downstream_pressure_spread,
+                state_vector=tuple(state_after_projection),
+            )
+            previous_snapshot = snapshot_after_projection
+
+            if diagnostics.converged:
+                self._apply_state_vector(raw_state)
+                return diagnostics
+
+        assert diagnostics is not None
+        self._apply_state_vector(raw_state)
+        return diagnostics
+
+    def _solve_branch_inlet_flow(
+        self,
+        orifice: Orifice,
+        pipe: Pipe,
+        p_upstream: float,
+        pipe_props: ThermodynamicProperties,
+        *,
+        strict: bool = False,
+    ) -> tuple[float, BranchInletFlowDiagnostics]:
+        m_flow = orifice.mass_flow(p_upstream, pipe_props.p)
+        rho = max(pipe_props.rho, 1e-9)
+        p_inlet = pipe.inlet_pressure(m_flow, rho, pipe_props.p)
+        residual = abs(orifice.mass_flow(p_upstream, p_inlet) - m_flow)
+        converged = False
+        iterations = 0
+        for iteration in range(1, 9):
+            p_inlet = pipe.inlet_pressure(m_flow, rho, pipe_props.p)
+            next_m_flow = orifice.mass_flow(p_upstream, p_inlet)
+            residual = abs(next_m_flow - m_flow)
+            iterations = iteration
+            if residual <= 1e-9 * max(1.0, abs(next_m_flow)):
+                m_flow = next_m_flow
+                converged = True
+                break
+            m_flow = next_m_flow
+        diagnostics = BranchInletFlowDiagnostics(
+            converged=converged,
+            iterations=iterations,
+            residual=residual,
+            m_flow=m_flow,
+            inlet_pressure=p_inlet,
+        )
+        if strict and not diagnostics.converged:
+            raise RuntimeError(
+                f"Branch inlet flow solve did not converge for {pipe.name}: residual={residual:.6e}"
+            )
+        return m_flow, diagnostics
+
+    def _solve_downstream_branch_flows(
+        self,
+        cylinder: ThermodynamicProperties,
+        tank: ThermodynamicProperties,
+        branch_states: tuple[BranchClosureState, BranchClosureState],
+    ) -> tuple[float, float]:
+        return self._solve_downstream_branch_flows_from_state(
+            inlet_h_upper=branch_states[0].inlet_h,
+            inlet_h_lower=branch_states[1].inlet_h,
+            pipe_upper_h=max(branch_states[0].pipe.h, 1e-9),
+            pipe_lower_h=max(branch_states[1].pipe.h, 1e-9),
+            tank_h=max(tank.h, 1e-9),
+            q_in_upper=branch_states[0].inlet_flow,
+            q_in_lower=branch_states[1].inlet_flow,
+        )
+
+    def _project_volume_energy_to_pressure(
+        self,
+        component: Pipe | Tank,
+        target_pressure: float,
+    ) -> None:
+        target_temperature = target_pressure * component.V / (
+            max(component.state.m, 1e-12) * self.medium.R_gas
+        )
+        target_internal_energy = (
+            component.state.m * self.medium.specific_internal_energy(target_temperature)
+        )
+        component.state = VolumeState(m=component.state.m, U=target_internal_energy)
+
+    def _downstream_total_internal_energy_for_pressure(
+        self,
+        target_pressure: float,
+        downstream_components: tuple[Pipe | Tank, ...],
+    ) -> float:
+        total_internal_energy = 0.0
+        for component in downstream_components:
+            target_temperature = target_pressure * component.V / (
+                max(component.state.m, 1e-12) * self.medium.R_gas
+            )
+            total_internal_energy += (
+                component.state.m * self.medium.specific_internal_energy(target_temperature)
+            )
+        return total_internal_energy
+
+    def _solve_downstream_common_pressure(
+        self,
+        downstream_components: tuple[Pipe | Tank, ...],
+        target_total_internal_energy: float,
+        *,
+        strict: bool = False,
+    ) -> tuple[float, DownstreamPressureDiagnostics]:
+        lower_pressure = 1.0
+        upper_pressure = max(component.properties().p for component in downstream_components)
+        upper_pressure = max(upper_pressure, 1e5)
+
+        def residual(pressure: float) -> float:
+            return (
+                self._downstream_total_internal_energy_for_pressure(
+                    pressure,
+                    downstream_components,
+                )
+                - target_total_internal_energy
+            )
+
+        upper_residual = residual(upper_pressure)
+        iteration_count = 0
+
+        while upper_residual < 0.0:
+            upper_pressure *= 2.0
+            upper_residual = residual(upper_pressure)
+
+        final_pressure = 0.5 * (lower_pressure + upper_pressure)
+        final_residual = residual(final_pressure)
+        converged = False
+        for iteration in range(1, 81):
+            middle_pressure = 0.5 * (lower_pressure + upper_pressure)
+            middle_residual = residual(middle_pressure)
+            iteration_count = iteration
+            final_pressure = middle_pressure
+            final_residual = middle_residual
+            if abs(middle_residual) <= 1e-12 * max(1.0, target_total_internal_energy):
+                converged = True
+                break
+            if middle_residual > 0.0:
+                upper_pressure = middle_pressure
+            else:
+                lower_pressure = middle_pressure
+
+        diagnostics = DownstreamPressureDiagnostics(
+            converged=converged,
+            iterations=iteration_count,
+            residual=final_residual,
+            pressure=final_pressure,
+            target_total_internal_energy=target_total_internal_energy,
+        )
+        if strict and not diagnostics.converged:
+            raise RuntimeError(
+                "Downstream common-pressure solve did not converge: "
+                f"residual={final_residual:.6e}"
+            )
+        return final_pressure, diagnostics
+
+    def project_downstream_pressure_constraints(self, *, strict: bool = False) -> None:
+        downstream_components = (
+            self.components.upper_branch.pipe,
+            self.components.lower_branch.pipe,
+            self.components.tank,
+        )
+        total_internal_energy = sum(component.state.U for component in downstream_components)
+        common_pressure, diagnostics = self._solve_downstream_common_pressure(
+            downstream_components,
+            total_internal_energy,
+            strict=strict,
+        )
+        self.last_downstream_pressure_diagnostics = diagnostics
+
+        for component in downstream_components:
+            self._project_volume_energy_to_pressure(component, common_pressure)
+
+    def _downstream_connection_enthalpy(
+        self,
+        q_out_upper: float,
+        q_out_lower: float,
+        pipe_upper_h: float,
+        pipe_lower_h: float,
+        tank_h: float,
+    ) -> float:
+        return self.components.downstream_tee.inlet_stream_enthalpy(
+            q_out_lower,
+            pipe_lower_h,
+            q_out_upper,
+            pipe_upper_h,
+            fallback_h=tank_h,
+        )
+
+    def _solve_downstream_branch_flows_from_state(
+        self,
+        *,
+        inlet_h_upper: float,
+        inlet_h_lower: float,
+        pipe_upper_h: float,
+        pipe_lower_h: float,
+        tank_h: float,
+        q_in_upper: float,
+        q_in_lower: float,
+    ) -> tuple[float, float]:
+        return self.components.downstream_tee.solve_branch_outlet_flows_from_energy_balance(
+            ratio_branch1=self.components.upper_branch.pipe.V / self.components.tank.V,
+            ratio_branch2=self.components.lower_branch.pipe.V / self.components.tank.V,
+            inlet_h_branch1=inlet_h_upper,
+            inlet_h_branch2=inlet_h_lower,
+            branch1_h=pipe_upper_h,
+            branch2_h=pipe_lower_h,
+            inlet_h=tank_h,
+            q_in_branch1=q_in_upper,
+            q_in_branch2=q_in_lower,
+        )
+
+    def _evaluate_branch_states(
+        self,
+        cylinder: ThermodynamicProperties,
+    ) -> tuple[BranchClosureState, BranchClosureState]:
+        states: list[BranchClosureState] = []
+        for branch in self.components.branches():
+            pipe_properties = branch.pipe.properties()
+            inlet_flow, inlet_flow_diagnostics = self._solve_branch_inlet_flow(
+                branch.orifice,
+                branch.pipe,
+                cylinder.p,
+                pipe_properties,
+            )
+            inlet_h = branch.pipe.port_a_inlet_enthalpy(
+                port_a_m_flow=inlet_flow,
+                connected_h=cylinder.h,
+                internal_h=pipe_properties.h,
+            )
+            states.append(
+                BranchClosureState(
+                    name=branch.name,
+                    pipe=pipe_properties,
+                    inlet_flow=inlet_flow,
+                    outlet_flow=0.0,
+                    inlet_h=inlet_h,
+                    inlet_flow_diagnostics=inlet_flow_diagnostics,
+                )
+            )
+        return (states[0], states[1])
+
+    @staticmethod
+    def _with_branch_outlet_flows(
+        branch_states: tuple[BranchClosureState, BranchClosureState],
+        outlet_flows: tuple[float, float],
+    ) -> tuple[BranchClosureState, BranchClosureState]:
+        return (
+            BranchClosureState(
+                name=branch_states[0].name,
+                pipe=branch_states[0].pipe,
+                inlet_flow=branch_states[0].inlet_flow,
+                outlet_flow=outlet_flows[0],
+                inlet_h=branch_states[0].inlet_h,
+                inlet_flow_diagnostics=branch_states[0].inlet_flow_diagnostics,
+            ),
+            BranchClosureState(
+                name=branch_states[1].name,
+                pipe=branch_states[1].pipe,
+                inlet_flow=branch_states[1].inlet_flow,
+                outlet_flow=outlet_flows[1],
+                inlet_h=branch_states[1].inlet_h,
+                inlet_flow_diagnostics=branch_states[1].inlet_flow_diagnostics,
+            ),
+        )
+
+    @staticmethod
+    def _branch_snapshots(
+        branch_states: tuple[BranchClosureState, BranchClosureState],
+    ) -> tuple[BranchSnapshot, BranchSnapshot]:
+        return (
+            BranchSnapshot(
+                name=branch_states[0].name,
+                pipe=branch_states[0].pipe,
+                inlet_flow=branch_states[0].inlet_flow,
+                outlet_flow=branch_states[0].outlet_flow,
+                inlet_h=branch_states[0].inlet_h,
+                inlet_flow_diagnostics=branch_states[0].inlet_flow_diagnostics,
+            ),
+            BranchSnapshot(
+                name=branch_states[1].name,
+                pipe=branch_states[1].pipe,
+                inlet_flow=branch_states[1].inlet_flow,
+                outlet_flow=branch_states[1].outlet_flow,
+                inlet_h=branch_states[1].inlet_h,
+                inlet_flow_diagnostics=branch_states[1].inlet_flow_diagnostics,
+            ),
+        )
+
+    def snapshot(
+        self,
+        state_vector: list[float] | None = None,
+        *,
+        strict: bool = False,
+    ) -> TestModelSnapshot:
+        if state_vector is not None:
+            self._apply_state_vector(list(state_vector))
+
+        cylinder = self.components.cylinder.properties()
+        tank = self.components.tank.properties()
+        branch_states = self._evaluate_branch_states(cylinder)
+        if strict:
+            for branch_state in branch_states:
+                if not branch_state.inlet_flow_diagnostics.converged:
+                    raise RuntimeError(
+                        "Branch inlet flow solve did not converge for "
+                        f"{branch_state.name}: residual="
+                        f"{branch_state.inlet_flow_diagnostics.residual:.6e}"
+                    )
+        outlet_flows = self._solve_downstream_branch_flows(cylinder, tank, branch_states)
+        branch_states = self._with_branch_outlet_flows(branch_states, outlet_flows)
+
+        tee_upstream_h = self.components.upstream_tee.inlet_stream_enthalpy(
+            -branch_states[0].inlet_flow,
+            branch_states[0].pipe.h,
+            -branch_states[1].inlet_flow,
+            branch_states[1].pipe.h,
+            fallback_h=cylinder.h,
+        )
+        tee_downstream_h = self._downstream_connection_enthalpy(
+            branch_states[0].outlet_flow,
+            branch_states[1].outlet_flow,
+            branch_states[0].pipe.h,
+            branch_states[1].pipe.h,
+            tank.h,
+        )
+
+        self._write_port_states(
+            cylinder,
+            tank,
+            branch_states,
+            tee_upstream_h,
+            tee_downstream_h,
+        )
+
+        solve_diagnostics = TestModelSolveDiagnostics(
+            upper_branch_inlet=branch_states[0].inlet_flow_diagnostics,
+            lower_branch_inlet=branch_states[1].inlet_flow_diagnostics,
+            downstream_pressure_projection=self.last_downstream_pressure_diagnostics,
+        )
+        self.last_solve_diagnostics = solve_diagnostics
+        branch_snapshots = self._branch_snapshots(branch_states)
+
+        return TestModelSnapshot(
+            cylinder=cylinder,
+            tank=tank,
+            tee_upstream_h=tee_upstream_h,
+            tee_downstream_h=tee_downstream_h,
+            branches=branch_snapshots,
+            solve_diagnostics=solve_diagnostics,
+        )
+
+    def _write_port_states(
+        self,
+        cylinder: ThermodynamicProperties,
+        tank: ThermodynamicProperties,
+        branch_states: tuple[BranchClosureState, BranchClosureState],
+        tee_upstream_h: float,
+        tee_downstream_h: float,
+    ) -> None:
+        cylinder_m_flow = -sum(branch_state.inlet_flow for branch_state in branch_states)
+        tank_m_flow = sum(branch_state.outlet_flow for branch_state in branch_states)
+
+        self.components.cylinder.port_b.m_flow = cylinder_m_flow
+
+        self.components.upstream_tee.port_in.p = cylinder.p
+        self.components.upstream_tee.port_out1.p = cylinder.p
+        self.components.upstream_tee.port_out2.p = cylinder.p
+        self.components.upstream_tee.port_in.m_flow = -cylinder_m_flow
+        self.components.upstream_tee.port_in.h_outflow = tee_upstream_h
+        self.components.upstream_tee.port_out1.h_outflow = cylinder.h
+        self.components.upstream_tee.port_out2.h_outflow = cylinder.h
+        self.components.upstream_tee.port_out1.m_flow = -branch_states[0].inlet_flow
+        self.components.upstream_tee.port_out2.m_flow = -branch_states[1].inlet_flow
+
+        for branch_components, branch_state in zip(self.components.branches(), branch_states):
+            branch_components.orifice.port_a.p = cylinder.p
+            branch_components.orifice.port_b.p = branch_components.pipe.inlet_pressure(
+                branch_state.inlet_flow,
+                max(branch_state.pipe.rho, 1e-9),
+                branch_state.pipe.p,
+            )
+            branch_components.orifice.port_a.m_flow = branch_state.inlet_flow
+            branch_components.orifice.port_b.m_flow = -branch_state.inlet_flow
+            branch_components.orifice.port_a.h_outflow = cylinder.h
+            branch_components.orifice.port_b.h_outflow = branch_state.pipe.h
+
+            branch_components.pipe.port_a.p = branch_components.orifice.port_b.p
+            branch_components.pipe.port_a.m_flow = branch_state.inlet_flow
+            branch_components.pipe.port_b.m_flow = -branch_state.outlet_flow
+            branch_components.pipe.port_b.p = branch_state.pipe.p
+
+        self.components.downstream_tee.port_in.p = tank.p
+        self.components.downstream_tee.port_out1.p = tank.p
+        self.components.downstream_tee.port_out2.p = tank.p
+        self.components.downstream_tee.port_in.m_flow = -tank_m_flow
+        self.components.downstream_tee.port_out1.m_flow = branch_states[1].outlet_flow
+        self.components.downstream_tee.port_out2.m_flow = branch_states[0].outlet_flow
+        self.components.downstream_tee.port_in.h_outflow = tee_downstream_h
+        self.components.downstream_tee.port_out1.h_outflow = tank.h
+        self.components.downstream_tee.port_out2.h_outflow = tank.h
+
+        self.components.tank.port_a.m_flow = tank_m_flow
+
+    def _branch_derivative_states(
+        self,
+        snapshot: TestModelSnapshot,
+    ) -> tuple[VolumeState, VolumeState]:
+        derivative_states: list[VolumeState] = []
+        for branch_components, branch_snapshot in zip(self.components.branches(), snapshot.branches):
+            derivative_states.append(
+                branch_components.pipe.derivatives_from_connections(
+                    port_a_m_flow=branch_snapshot.inlet_flow,
+                    connected_h_a=snapshot.cylinder.h,
+                    port_b_m_flow=-branch_snapshot.outlet_flow,
+                    connected_h_b=snapshot.tank.h,
+                    internal_h=branch_snapshot.pipe.h,
+                )
+            )
+        return (derivative_states[0], derivative_states[1])
+
+    def rhs(self, state_vector: list[float]) -> list[float]:
+        snapshot = self.snapshot(state_vector)
+
+        cylinder_m_flow = -sum(branch.inlet_flow for branch in snapshot.branches)
+        tank_m_flow = sum(branch.outlet_flow for branch in snapshot.branches)
+        d_cylinder = self.components.cylinder.derivatives_from_connection(
+            connected_h=snapshot.tee_upstream_h,
+            port_m_flow=cylinder_m_flow,
+            internal_h=snapshot.cylinder.h,
+        )
+        branch_derivatives = self._branch_derivative_states(snapshot)
+        d_tank = self.components.tank.derivatives_from_connection(
+            connected_h=snapshot.tee_downstream_h,
+            port_m_flow=tank_m_flow,
+            internal_h=snapshot.tank.h,
+        )
+
+        return [
+            d_cylinder.m,
+            d_cylinder.U,
+            branch_derivatives[0].m,
+            branch_derivatives[0].U,
+            branch_derivatives[1].m,
+            branch_derivatives[1].U,
+            d_tank.m,
+            d_tank.U,
+        ]
@@ -0,0 +1,272 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from app.simulation.core.base import ThermodynamicVolumeComponent
+from app.simulation.core.equations import EquationResidual
+from app.simulation.core.metadata import (
+    ParameterDefinition,
+    THERMODYNAMIC_VOLUME_RESULT_VARIABLES,
+)
+from app.simulation.core.medium import IdealGasMedium, ThermodynamicProperties
+from app.simulation.core.ports import PortDefinition
+from app.simulation.core.state import VolumeState
+
+
+class Pipe(ThermodynamicVolumeComponent):
+    """Dynamic pipe retained for the fixed TestModel compatibility example."""
+
+    MODEL_TYPE = "pipe"
+    MODEL_VERSION = "0.1.0"
+    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,
+        medium: IdealGasMedium,
+        L: float = 5.0,
+        D: float = 0.02,
+        lambda_darcy: float = 0.02,
+        p0: float = 1e5,
+        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
+        self.lambda_darcy = lambda_darcy
+        self.area = 3.141592653589793 * D * D / 4.0
+        self.V = self.area * L
+        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_declared_port("port_a")
+        self.port_b = self.register_declared_port("port_b")
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        name: str,
+        medium: IdealGasMedium,
+        parameters: Mapping[str, float],
+    ) -> Pipe:
+        return cls(
+            name=name,
+            medium=medium,
+            L=parameters["length"],
+            D=parameters["diameter"],
+            lambda_darcy=parameters["lambda_darcy"],
+            p0=parameters["p0"],
+            T0=parameters["T0"],
+        )
+
+    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 properties(self) -> ThermodynamicProperties:
+        props = self.medium.properties_from_mU(self.state.m, self.state.U, self.V)
+        self.port_b.p = props.p
+        self.port_a.h_outflow = props.h
+        self.port_b.h_outflow = props.h
+        return props
+
+    def refresh_thermodynamic_ports(self) -> ThermodynamicProperties:
+        return self.properties()
+
+    def state_derivative_from_ports(
+        self,
+        connected_h: Mapping[str, float],
+    ) -> list[float]:
+        properties = self.properties()
+        derivative = self.derivatives_from_connections(
+            port_a_m_flow=self.port_a.m_flow,
+            connected_h_a=connected_h["port_a"],
+            port_b_m_flow=self.port_b.m_flow,
+            connected_h_b=connected_h["port_b"],
+            internal_h=properties.h,
+        )
+        return derivative.as_vector()
+
+    def inlet_pressure(self, m_flow_a: float, rho: float, core_pressure: float) -> float:
+        resistance = self.lambda_darcy * (self.L / self.D)
+        dynamic_term = m_flow_a * abs(m_flow_a) / (2.0 * rho * self.area * self.area)
+        return core_pressure + resistance * dynamic_term
+
+    def pressure_flow_equation_residuals(self) -> tuple[EquationResidual, ...]:
+        properties = self.medium.properties_from_mU(
+            self.state.m,
+            self.state.U,
+            self.V,
+        )
+        expected_inlet_pressure = self.inlet_pressure(
+            self.port_a.m_flow,
+            max(properties.rho, 1e-12),
+            properties.p,
+        )
+        return (
+            EquationResidual(
+                id=f"{self.name}:darcy_pressure_loss",
+                owner="component",
+                owner_id=self.name,
+                relation="constitutive",
+                variables=(
+                    f"{self.name}.port_a.p",
+                    f"{self.name}.port_a.m_flow",
+                    f"{self.name}.state",
+                ),
+                role="effort",
+                value=self.port_a.p - expected_inlet_pressure,
+            ),
+            EquationResidual(
+                id=f"{self.name}:port_b_pressure_state",
+                owner="component",
+                owner_id=self.name,
+                relation="state",
+                variables=(f"{self.name}.port_b.p", f"{self.name}.state"),
+                role="effort",
+                value=self.port_b.p - properties.p,
+            ),
+        )
+
+    def port_a_inlet_enthalpy(
+        self,
+        *,
+        port_a_m_flow: float,
+        connected_h: float,
+        internal_h: float,
+    ) -> float:
+        return self.connection_inlet_enthalpy(
+            port_m_flow=port_a_m_flow,
+            connected_h=connected_h,
+            internal_h=internal_h,
+        )
+
+    def port_b_inlet_enthalpy(
+        self,
+        *,
+        port_b_m_flow: float,
+        connected_h: float,
+        internal_h: float,
+    ) -> float:
+        return self.connection_inlet_enthalpy(
+            port_m_flow=port_b_m_flow,
+            connected_h=connected_h,
+            internal_h=internal_h,
+        )
+
+    def connection_inlet_enthalpies(
+        self,
+        *,
+        port_a_m_flow: float,
+        connected_h_a: float,
+        port_b_m_flow: float,
+        connected_h_b: float,
+        internal_h: float,
+    ) -> tuple[float, float]:
+        return (
+            self.port_a_inlet_enthalpy(
+                port_a_m_flow=port_a_m_flow,
+                connected_h=connected_h_a,
+                internal_h=internal_h,
+            ),
+            self.port_b_inlet_enthalpy(
+                port_b_m_flow=port_b_m_flow,
+                connected_h=connected_h_b,
+                internal_h=internal_h,
+            ),
+        )
+
+    def derivatives_from_connections(
+        self,
+        *,
+        port_a_m_flow: float,
+        connected_h_a: float,
+        port_b_m_flow: float,
+        connected_h_b: float,
+        internal_h: float,
+    ) -> VolumeState:
+        inlet_h_a, inlet_h_b = self.connection_inlet_enthalpies(
+            port_a_m_flow=port_a_m_flow,
+            connected_h_a=connected_h_a,
+            port_b_m_flow=port_b_m_flow,
+            connected_h_b=connected_h_b,
+            internal_h=internal_h,
+        )
+        return self.derivatives(
+            inlet_h_a=inlet_h_a,
+            inlet_h_b=inlet_h_b,
+            m_flow_a=port_a_m_flow,
+            m_flow_b=port_b_m_flow,
+        )
+
+    def derivatives(
+        self,
+        inlet_h_a: float,
+        inlet_h_b: float,
+        m_flow_a: float,
+        m_flow_b: float,
+    ) -> VolumeState:
+        dm_dt = m_flow_a + m_flow_b
+        dU_dt = m_flow_a * inlet_h_a + m_flow_b * inlet_h_b
+        return VolumeState(m=dm_dt, U=dU_dt)
@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+
+from app.simulation.examples.testmodel.closure import TestModelSolveDiagnostics
+from app.simulation.examples.testmodel.system import (
+    InitializationDiagnostics,
+    TestModelConfig,
+    TestModelSystem,
+)
+from app.simulation.paths import (
+    MODELICA_TESTMODEL_RESULT_PATH,
+    PROJECT_ROOT,
+    SIMULATION_RUNS_DIR,
+)
+from app.simulation.reporting import (
+    COMPARISON_KEYS,
+    PRIMARY_KEYS,
+    TestModelArtifacts,
+    export_testmodel_artifacts,
+    format_testmodel_run_report,
+    load_modelica_series,
+    write_testmodel_run_report,
+)
+from app.simulation.solvers.solver import SolveIVPConfig
+
+
+@dataclass(frozen=True)
+class TestModelSamplingConfig:
+    step: float = 0.1
+
+
+@dataclass(frozen=True)
+class TestModelPathConfig:
+    output_dir: Path | None = None
+    modelica_result_path: Path | None = None
+
+
+@dataclass(frozen=True)
+class TestModelExecutionConfig:
+    use_modelica_reference_if_available: bool = True
+
+
+@dataclass(frozen=True)
+class TestModelRunConfig:
+    model: TestModelConfig = field(default_factory=TestModelConfig)
+    solver: SolveIVPConfig = field(default_factory=SolveIVPConfig)
+    sampling: TestModelSamplingConfig = field(default_factory=TestModelSamplingConfig)
+    paths: TestModelPathConfig = field(default_factory=TestModelPathConfig)
+    execution: TestModelExecutionConfig = field(default_factory=TestModelExecutionConfig)
+
+    @property
+    def sample_step(self) -> float:
+        return self.sampling.step
+
+    def sample_times(self) -> list[float]:
+        return _sample_times(
+            self.solver.t_start,
+            self.solver.t_stop,
+            step=self.sampling.step,
+        )
+
+
+@dataclass(frozen=True)
+class PreparedTestModelRun:
+    run_config: TestModelRunConfig
+    repo_root: Path
+    output_dir: Path
+    modelica_result_path: Path
+    t_eval: tuple[float, ...]
+    use_modelica_reference_if_available: bool
+    modelica_reference_exists: bool
+
+
+@dataclass(frozen=True)
+class TestModelRunResult:
+    run_config: TestModelRunConfig
+    prepared_run: PreparedTestModelRun
+    system: TestModelSystem
+    initialization: InitializationDiagnostics
+    raw_initial_state: tuple[float, ...]
+    consistent_initial_state: tuple[float, ...]
+    solution: object
+    series: dict[str, list[float]]
+    solve_diagnostics: TestModelSolveDiagnostics | None
+    artifacts: TestModelArtifacts
+    comparison_summary: dict[str, tuple[float, float]] | None
+    used_modelica_reference: bool
+
+
+def _sample_times(t_start: float, t_stop: float, step: float) -> list[float]:
+    point_count = int(round((t_stop - t_start) / step))
+    return [t_start + index * step for index in range(point_count + 1)]
+
+
+def _default_run_output_dir() -> Path:
+    timestamp = datetime.now(UTC).strftime("testmodel_%Y%m%d_%H%M%S_%f")
+    return SIMULATION_RUNS_DIR / timestamp
+
+
+def prepare_testmodel_run(
+    *,
+    run_config: TestModelRunConfig | None = None,
+    output_dir: Path | None = None,
+    modelica_result_path: Path | None = None,
+) -> PreparedTestModelRun:
+    run_config = run_config or TestModelRunConfig()
+    resolved_output_dir = (
+        output_dir
+        or run_config.paths.output_dir
+        or _default_run_output_dir()
+    )
+    resolved_modelica_result_path = (
+        modelica_result_path
+        or run_config.paths.modelica_result_path
+        or MODELICA_TESTMODEL_RESULT_PATH
+    )
+    t_eval = tuple(run_config.sample_times())
+    return PreparedTestModelRun(
+        run_config=run_config,
+        repo_root=PROJECT_ROOT,
+        output_dir=resolved_output_dir,
+        modelica_result_path=resolved_modelica_result_path,
+        t_eval=t_eval,
+        use_modelica_reference_if_available=run_config.execution.use_modelica_reference_if_available,
+        modelica_reference_exists=resolved_modelica_result_path.exists(),
+    )
+
+
+def run_prepared_testmodel(prepared_run: PreparedTestModelRun) -> TestModelRunResult:
+    run_config = prepared_run.run_config
+    system = TestModelSystem(config=run_config.model)
+    raw_initial_state = tuple(system.initial_state_vector())
+    initialization = system.initialize_consistent_state()
+    consistent_initial_state = tuple(initialization.state_vector)
+    solution = system.simulate(config=run_config.solver, t_eval=list(prepared_run.t_eval))
+    series = system.evaluate_solution(solution)
+    solve_diagnostics = system.last_solve_diagnostics
+
+    modelica_series = None
+    used_modelica_reference = False
+    if (
+        prepared_run.use_modelica_reference_if_available
+        and prepared_run.modelica_reference_exists
+    ):
+        modelica_series = load_modelica_series(
+            prepared_run.modelica_result_path,
+            COMPARISON_KEYS,
+        )
+        used_modelica_reference = True
+
+    artifacts, comparison_summary = export_testmodel_artifacts(
+        output_dir=prepared_run.output_dir,
+        series=series,
+        modelica_series=modelica_series,
+    )
+    report_text = format_testmodel_run_report(
+        network_summary=system.network.summary(),
+        initialization=initialization,
+        raw_initial_state=raw_initial_state,
+        consistent_initial_state=consistent_initial_state,
+        solution=solution,
+        series=series,
+        solve_diagnostics=solve_diagnostics,
+        artifacts=artifacts,
+        comparison_summary=comparison_summary,
+    )
+    write_testmodel_run_report(prepared_run.output_dir, report_text)
+
+    return TestModelRunResult(
+        run_config=run_config,
+        prepared_run=prepared_run,
+        system=system,
+        initialization=initialization,
+        raw_initial_state=raw_initial_state,
+        consistent_initial_state=consistent_initial_state,
+        solution=solution,
+        series=series,
+        solve_diagnostics=solve_diagnostics,
+        artifacts=artifacts,
+        comparison_summary=comparison_summary,
+        used_modelica_reference=used_modelica_reference,
+    )
+
+
+def run_testmodel(
+    *,
+    run_config: TestModelRunConfig | None = None,
+    output_dir: Path | None = None,
+    modelica_result_path: Path | None = None,
+) -> TestModelRunResult:
+    prepared_run = prepare_testmodel_run(
+        run_config=run_config,
+        output_dir=output_dir,
+        modelica_result_path=modelica_result_path,
+    )
+    return run_prepared_testmodel(prepared_run)
+
+
+def main() -> None:
+    run_config = TestModelRunConfig()
+    result = run_testmodel(run_config=run_config)
+    print(
+        format_testmodel_run_report(
+            network_summary=result.system.network.summary(),
+            initialization=result.initialization,
+            raw_initial_state=result.raw_initial_state,
+            consistent_initial_state=result.consistent_initial_state,
+            solution=result.solution,
+            series=result.series,
+            solve_diagnostics=result.solve_diagnostics,
+            artifacts=result.artifacts,
+            comparison_summary=result.comparison_summary,
+        ),
+        end="",
+    )
+
+
+if __name__ == "__main__":
+    main()
Author	SHA1	Message	Date
huojiarong	50c9f59d78	完善系统仿真优化计划交互	2026-09-15 08:32:31 +00:00
huojiarong	42ffdfff7d	新增系统仿真参数优化 Skill	2026-09-14 09:35:53 +00:00
ljz	a87d462e94	支持后端解析参数表达式并保留工程JSON	2026-09-03 18:18:47 +08:00
				`@@ -0,0 +1 @@`
				`"""Reference systems and regression examples."""`
				`@@ -0,0 +1 @@`
				"""Calibrated component primitives used only by the ``test_mql`` example."""