更新v2版本适配skill

相较上一版 Jacobian 确定性复用更新，本次补齐事件边界一致性、结果两侧采样及接触事件定位；保留已有物性复用和组件力学公式。

- 统一 UD00 信号求值与下一事件查询的绝对时间边界，修复循环边界浮点舍入导致的阶段错位、重复或漏报，并覆盖零时长、多阶段及长周期场景。
- 引入原生输出语义 v2：保留规则网格真实时间，补充内部时间事件和状态事件的左邻及事件后采样，按保存时间、状态和离散模式重放结果。
- 两条代码生成路径均发出 LSTP 接触描述，默认定位间隙过零及非负力模式的力截断；仅在接受事件时更新防重复记录，增加 contactEvents 诊断计数。
- 补充 MASS/LSTP 独立事件实验、八路全曲线与驱动阶段配对评估，以及 Amesim 不连续点输出对照和力差定位报告；MASS 新增释放机制仍保留为独立实验。
- 保存局部 probe、context 访问与回退、shadow replay、R288 real skip/typed replay 及阀门数值尾部诊断工具和报告；未证明净收益的实验不启用为生产默认优化。
- 更新原生运行说明和元件建模规范，补充信号边界、输出语义、接触事件和实验依赖回归测试。

验证：五组专项回归共 34 项全部通过；37 个待提交 Python 文件语法检查通过；git diff --cached --check 通过。

.gitattributes

@@ -0,0 +1,14 @@
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.sh text eol=lf
+
+# 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/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

.github/workflows/solver-regression.yml

@@ -0,0 +1,139 @@
+name: Native backend regression
+
+on:
+  push:
+    paths:
+      - "app/**"
+      - "native/**"
+      - "schemas/**"
+      - "tests/**"
+      - "requirements*.txt"
+      - "constraints/**"
+      - ".python-version"
+      - ".gitattributes"
+      - ".github/workflows/solver-regression.yml"
+  pull_request:
+    paths:
+      - "app/**"
+      - "native/**"
+      - "schemas/**"
+      - "tests/**"
+      - "requirements*.txt"
+      - "constraints/**"
+      - ".python-version"
+      - ".gitattributes"
+      - ".github/workflows/solver-regression.yml"
+  schedule:
+    - cron: "17 3 * * *"
+  workflow_dispatch:
+
+concurrency:
+  group: solver-regression-${{ github.ref }}-${{ github.event_name }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  contracts:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    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
+
+  native-linux:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version
+      - name: Install native dependencies with the existing Linux setup
+        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
+        env:
+          SIMULATION_NATIVE_REQUIRE_TOOLCHAIN: "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
+
+  native-windows:
+    runs-on: windows-2022
+    timeout-minutes: 30
+    defaults:
+      run:
+        shell: pwsh
+    steps:
+      - uses: actions/checkout@v4
+      - uses: conda-incubator/setup-miniconda@v3
+        with:
+          python-version: "3.12"
+          activate-environment: simulation-native
+          auto-activate-base: false
+      - name: Install native compiler and SUNDIALS
+        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 check
+      - name: Verify native cache on the Windows runtime
+        env:
+          SIMULATION_NATIVE_REQUIRE_TOOLCHAIN: "1"
+        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
+      - 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
+          if-no-files-found: warn

.gitignore

@@ -12,7 +12,16 @@ htmlcov/
 # Local virtual environments
 .venv/
 .venv-win/
+
+# 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/

.python-version

@@ -0,0 +1 @@
+3.12.3

README.md

@@ -2,6 +2,94 @@
 
 ReactFlow 系统建模与 `app.simulation` 仿真后端。
 
+## 开发环境准备
+
+Windows/Linux 的运行、测试、原生工具链及时间剖析依赖，统一见 [平台依赖说明](docs/standard/platform-dependencies.md)。2026-09-16 的 Jacobian 复用与剖析工具继续使用现有 SUNDIALS 7.4.0，本轮未新增运行库依赖；以下安装命令供准备环境时使用。
+
+后端编排层统一使用 Python 3.12；仓库根目录的 `.python-version` 记录本轮参考补丁版本
+`3.12.3`。`requirements.txt` 保留支持范围，
+`constraints/python312-direct.txt` 固定跨平台开发环境的直接依赖参考版本；
+`constraints/python312-linux-x86_64.lock` 则完整固定发布与 CI 所用的 Linux x86_64
+wheel、全部传递依赖及其 SHA-256。
+
+Windows：
+
+```powershell
+py -3.12 -m venv .venv-win
+.\.venv-win\Scripts\python.exe -m pip install `
+  -r requirements.txt `
+  -c constraints/python312-direct.txt
+.\.venv-win\Scripts\python.exe -m pip check
+```
+
+Linux：
+
+```bash
+python3.12 -m venv .venv
+./.venv/bin/python -m pip install \
+  -r constraints/python312-linux-x86_64.lock
+./.venv/bin/python -m pip check
+```
+
+Linux 发布锁仅适用于兼容 manylinux_2_28 的 Linux x86_64 和 CPython 3.12。它启用
+`--only-binary=:all:` 与 `--require-hashes`，因此不会静默改用源码包或未审计 wheel；
+CI 和正式性能复测必须直接以 `-r` 安装该文件。Windows 或其他平台的开发环境继续
+使用 `requirements.txt` 加 `constraints/python312-direct.txt`。若要测试
+`requirements.txt` 声明的兼容范围，可显式省略约束，但这类结果不应与锁定环境的
+性能数据直接比较。
+
+升级参考版本时，应在干净的 Python 3.12 Linux x86_64 虚拟环境中解析范围文件，
+仅下载兼容 wheel，逐个记录 wheel 的 SHA-256，再从空环境安装发布锁并运行
+`pip check`、依赖契约测试与后端测试。不能只复制 `pip freeze`，因为它既不证明
+依赖来源，也不校验安装产物。
+
+前端使用 Vite 8，需要 Node.js `20.19+` 或 `22.12+`。首次启动前安装前端依赖。
+
+Windows（PowerShell，使用仓库内的便携 Node.js）：
+
+```powershell
+$nodeDir = Get-ChildItem .tools -Directory -Filter "node-*-win-x64" |
+  Where-Object { (Test-Path "$($_.FullName)\node.exe") -and (Test-Path "$($_.FullName)\npm.cmd") } |
+  Select-Object -First 1
+& "$($nodeDir.FullName)\npm.cmd" --prefix frontend ci
+```
+
+Linux：
+
+```bash
+cd frontend
+npm ci
+cd ..
+```
+
+Windows 启动脚本会自动使用 `.tools/node-*-win-x64` 下兼容的便携 Node.js；Linux 启动脚本优先使用 `.tools/node-*-linux-x64` 下兼容的运行时（如果存在），否则使用 `PATH` 中的 `node` 和 `npm`。`start-all.sh` 需要 Bash 4.3 或更高版本。
+
+## 启动项目
+
+脚本统一存放在 `bat/` 目录。三个入口分别用于同时启动、只启动后端、只启动前端。
+
+Windows：
+
+```bat
+bat\start-all.bat
+bat\start-backend.bat
+bat\start-reactflow.bat
+```
+
+Linux：
+
+```bash
+./bat/start-all.sh
+./bat/start-backend.sh
+./bat/start-reactflow.sh
+```
+
+后端地址为 `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 启动时自动加载。
@@ -17,21 +105,22 @@ ReactFlow 系统建模与 `app.simulation` 仿真后端。
 
 气动端口的后端契约采用 `p` 势变量相等、`m_flow` 流变量代数和为零、`h_outflow` 按 stream 规则混合。所有组件统一规定 `m_flow > 0` 表示流入组件，物理连接的端点顺序不表示流向。
 
-当前网络层可按端口域处理气动压力-流量残差与 stream 焓、标量信号传播，以及一维机械 `x/v` 等值和 `f` 平衡，并使用 SciPy 完成非线性代数闭合和时间积分。XML 通用仿真当前采用半显式 ODE/代数 MVP：气瓶和贮箱作为储能元件，孔板及 XML 管段作为阻性元件，三通作为等压零结点，同时支持已登记的信号和机械基础件。它不是完整 DAE 或事件求解器，也不等价于严格 Modelica.Fluid 实现。
+当前网络层按端口域处理气动压力/流量与 stream 焓、标量信号传播，以及一维机械 `x/v` 等值和 `f` 平衡。默认 C 后端在生成的 EXE 内完成连接闭合、RK45/CVODE BDF 积分及信号/限位事件。通用仿真仍有已声明的拓扑和物理公式范围，并不等价于完整 Amesim 或 Modelica.Fluid 实现。
 
-XML 解析依赖 `lxml` 执行本地 XSD 校验。安装或更新 Python 环境时使用：
-
-```powershell
-.\.venv-win\Scripts\python.exe -m pip install -r requirements.txt
-```
+XML 解析依赖 `lxml` 执行本地 XSD 校验，该依赖已包含在 `requirements.txt` 中。
 
 ## 文档
 
 - [开发文档索引](docs/README.md)
-- [后端接口版本与定义规范 v1](docs/backend-interface-version-spec-v1.md)
-- [组件模型建模规范 v1](docs/component-model-authoring-spec-v1.md)
-- [组件库分类、发现与读取规范 v1](docs/component-library-spec-v1.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/system-xml-v3.md)
+- [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)。

app/main.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from collections.abc import AsyncIterator, Callable, Iterator, Mapping
 from contextlib import asynccontextmanager
 import csv
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from datetime import datetime, timezone
 import io
 import json
@@ -20,10 +20,13 @@ 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, ValidationError
+from pydantic import BaseModel, ConfigDict, Field, StrictFloat, StrictStr, ValidationError
+
+from app.project_parameters import prepare_project, version_warning
 
 from app.simulation.performance import performance_span, profile_phase, profile_run
-from app.simulation.property_cache import property_cache_run
+from app.simulation.native_codegen.transport import NativeSeriesJson, serialize_result_parts
+from app.simulation.config import SolverActivityTracker
 from app.system_xml import (
     SystemXmlDocument,
     SystemXmlValidationReport,
@@ -40,10 +43,22 @@ if TYPE_CHECKING:
 
 @asynccontextmanager
 async def _app_lifespan(application: FastAPI) -> AsyncIterator[None]:
-    from app.simulation.warmup import warm_up_simulation_runtime
+    import logging
 
-    application.state.simulation_warmup = warm_up_simulation_runtime().as_dict()
+    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:
         yield
+    finally:
+        runtime_check.close()
 
 
 app = FastAPI(
@@ -61,6 +76,11 @@ SimulationProgressEmitter = Callable[
 ]
 SIMULATION_PHASE_MESSAGES = {
     "initializing": "正在初始化状态与方程",
+    "native-generation": "正在生成原生模型代码",
+    "native-cache-check": "正在检查已编译模型缓存",
+    "native-cache-hit": "已复用模型缓存，正在启动求解器",
+    "native-compilation": "正在编译模型与缺失的原生模块",
+    "native-linking": "正在链接模型可执行文件",
     "integrating": "正在进行时间积分与压力流量求解",
     "postprocessing": "正在整理采样结果",
     "cancelled": "正在整理已终止仿真的部分结果",
@@ -86,6 +106,9 @@ SimulationTaskStatus = Literal[
 class SimulationTaskRecord:
     simulation_id: str
     cancel_event: threading.Event
+    activity_tracker: SolverActivityTracker = field(
+        default_factory=SolverActivityTracker
+    )
     status: SimulationTaskStatus = "queued"
     cancel_reason: SimulationCancelReason | None = None
     result: dict[str, object] | None = None
@@ -131,8 +154,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. Every execution path requires an exact registry
-    # match before defaults, equations, or ports are consumed.
+    # opened and inspected. Input adapters warn and select the current model;
+    # the normalized XML/numerical boundary still enforces an exact match.
     modelVersion: str | None = None
     ports: list[ReactFlowPortDefinition] = Field(default_factory=list)
     parameters: dict[str, Any] = Field(default_factory=dict)
@@ -169,17 +192,17 @@ class ReactFlowEdgePayload(BaseModel):
 
 
 class ReactFlowSimulationConfig(BaseModel):
-    t_start: float = 0.0
-    t_stop: float = 2.0
-    step: float = 0.1
-    max_step: float = 0.005
+    t_start: StrictFloat | StrictStr = 0.0
+    t_stop: StrictFloat | StrictStr = 2.0
+    step: StrictFloat | StrictStr = 0.1
+    max_step: StrictFloat | StrictStr = 0.005
     method: str = "BDF"
 
 
 class ReactFlowProjectPayload(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
-    projectSchemaVersion: Literal[1]
+    projectSchemaVersion: Literal[1, 2]
     name: str = "untitled"
     nodes: list[ReactFlowNodePayload] = Field(default_factory=list)
     edges: list[ReactFlowEdgePayload] = Field(default_factory=list)
@@ -320,13 +343,29 @@ 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:
-        xml = build_reactflow_system_xml(payload)
+        normalized, notices = prepare_project(payload)
+        xml = build_reactflow_system_xml(normalized)
     except ValueError as exc:
         raise HTTPException(status_code=400, detail=str(exc)) from exc
-    return Response(content=xml, media_type="application/xml")
+    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)
 
 
 @app.post("/api/simulation-results/csv")
@@ -494,10 +533,11 @@ 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:
-        network = compile_reactflow_network(payload)
+        normalized, notices = prepare_project(payload)
+        network = compile_reactflow_network(normalized)
     except ValueError as exc:
         raise HTTPException(status_code=400, detail=str(exc)) from exc
-    return {"success": True, **network.as_interface_dict()}
+    return {"success": True, **network.as_interface_dict(), "warnings": [version_warning(notices)] if notices else []}
 
 
 @app.post("/api/system-xml/validate")
@@ -574,6 +614,7 @@ def _simulation_task_snapshot(task: SimulationTaskRecord) -> dict[str, object]:
             "cancelReason": task.cancel_reason,
             "result": task.result,
             "error": task.error,
+            **task.activity_tracker.snapshot().as_dict(),
         }
 
 
@@ -641,7 +682,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),
+        simulation_event_stream(await request.body(), task=task, raw_series=True),
         media_type="application/x-ndjson",
         headers={
             "Cache-Control": "no-cache, no-transform",
@@ -668,39 +709,36 @@ def cancel_system_xml_simulation(
     }
 
 
-@app.get("/api/system-xml/simulations/{simulation_id}")
-def get_system_xml_simulation(simulation_id: str) -> dict[str, object]:
+@app.get("/api/system-xml/simulations/{simulation_id}", response_model=None)
+def get_system_xml_simulation(simulation_id: str) -> dict[str, object] | Response:
     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.")
-    return _simulation_task_snapshot(task)
+    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
 
 
 def run_system_xml_simulation(
     xml_bytes: bytes,
     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
@@ -712,14 +750,11 @@ def _run_system_xml_simulation_profiled(
     xml_bytes: bytes,
     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.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,
-    )
+    from app.simulation.backends import simulate_network
+    from app.simulation.results import SimulationPreparationError
 
     def emit(
         progress: int,
@@ -740,9 +775,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))
@@ -757,23 +792,21 @@ 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:
-        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,
+        result = simulate_network(
+            network,
+            document.simulation,
             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(
@@ -790,41 +823,6 @@ 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,
@@ -846,7 +844,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(),
+            **result.as_dict(raw_series=raw_series),
         }
 
 
@@ -854,7 +852,8 @@ def simulation_event_stream(
     xml_bytes: bytes,
     *,
     task: SimulationTaskRecord | None = None,
-) -> Iterator[str]:
+    raw_series: bool = False,
+) -> Iterator[str | bytes]:
     events: queue.Queue[dict[str, object] | object] = queue.Queue()
     finished = object()
     latest_progress = 0
@@ -862,6 +861,9 @@ def simulation_event_stream(
     latest_message = "正在等待仿真任务启动"
     latest_simulated_time: float | None = None
     latest_total_time: float | None = None
+    activity_tracker = (
+        task.activity_tracker if task is not None else SolverActivityTracker()
+    )
 
     def emit_progress(
         progress: int,
@@ -872,6 +874,14 @@ 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
@@ -889,6 +899,7 @@ def simulation_event_stream(
             event["simulatedTime"] = latest_simulated_time
         if latest_total_time is not None:
             event["totalTime"] = latest_total_time
+        event.update(activity_tracker.snapshot().as_dict())
         events.put(event)
 
     def worker() -> None:
@@ -899,18 +910,33 @@ def simulation_event_stream(
                 xml_bytes,
                 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)
             result_status = str(result.get("status", "completed"))
+            final_simulated_time = result.get("simulatedUntil")
+            final_activity_kind = (
+                "complete" if result_status == "completed" else result_status
+            )
+            if activity_tracker.snapshot().activity_kind != final_activity_kind:
+                activity_tracker.record_phase(
+                    final_activity_kind,
+                    (
+                        float(final_simulated_time)
+                        if isinstance(final_simulated_time, (int, float))
+                        and isfinite(final_simulated_time)
+                        else None
+                    ),
+                )
             result_messages = {
                 "completed": "仿真完成",
                 "stopped": "仿真已由用户终止，已保留部分结果",
                 "stalled": "仿真因进度连接异常而终止，已保留部分结果",
                 "failed": "仿真异常终止，已保留可用的部分结果",
             }
-            events.put(
-                {
+            result_event = {
                 "event": "result",
                 "progress": 100 if result_status == "completed" else latest_progress,
                 "phase": result_status,
@@ -919,8 +945,10 @@ def simulation_event_stream(
                 "totalTime": result.get("requestedStopTime"),
                 "result": result,
             }
-            )
+            result_event.update(activity_tracker.snapshot().as_dict())
+            events.put(result_event)
         except HTTPException as exc:
+            activity_tracker.record_phase("failed")
             detail = exc.detail
             message = (
                 str(detail.get("message", "仿真失败"))
@@ -935,10 +963,12 @@ def simulation_event_stream(
                 "message": message,
                 "detail": detail,
             }
+            error_event.update(activity_tracker.snapshot().as_dict())
             if task is not None:
                 _mark_simulation_task_error(task, error_event)
             events.put(error_event)
         except Exception as exc:  # pragma: no cover - last-resort stream guard
+            activity_tracker.record_phase("failed")
             error_event = {
                 "event": "error",
                 "progress": latest_progress,
@@ -947,6 +977,7 @@ def simulation_event_stream(
                 "message": "仿真服务发生未预期错误。",
                 "detail": str(exc),
             }
+            error_event.update(activity_tracker.snapshot().as_dict())
             if task is not None:
                 _mark_simulation_task_error(task, error_event)
             events.put(error_event)
@@ -964,8 +995,7 @@ def simulation_event_stream(
             try:
                 event = events.get(timeout=SIMULATION_STREAM_HEARTBEAT_SECONDS)
             except queue.Empty:
-                yield json.dumps(
-                    {
+                heartbeat_event = {
                     "event": "progress",
                     "progress": latest_progress,
                     "phase": latest_phase,
@@ -973,13 +1003,20 @@ def simulation_event_stream(
                     "heartbeat": True,
                     "simulatedTime": latest_simulated_time,
                     "totalTime": latest_total_time,
-                    },
+                }
+                heartbeat_event.update(activity_tracker.snapshot().as_dict())
+                yield json.dumps(
+                    heartbeat_event,
                     ensure_ascii=False,
                     separators=(",", ":"),
                 ) + "\n"
                 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:
@@ -1027,7 +1064,7 @@ def validate_reactflow_component_contract(
     node: ReactFlowNodePayload,
     component_spec: "ComponentModelSpec",
 ) -> dict[str, float]:
-    """Validate the persisted model contract before consuming current defaults."""
+    """Validate the normalized SI model contract before consuming current defaults."""
 
     if (
         node.data.componentType != node.data.modelType
@@ -1096,6 +1133,7 @@ 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,
@@ -1173,7 +1211,8 @@ def build_reactflow_system_xml(project: ReactFlowProjectPayload) -> bytes:
             edge.targetHandle,
             edge.id,
         )
-        validate_compatible_ports(first, second, edge.id)
+        validate_compatible_ports(first, second, edge.id,
+                                  f"{edge.source}.{first.name}", f"{edge.target}.{second.name}")
 
         connection_node = ET.SubElement(
             connections_node,
@@ -1225,11 +1264,18 @@ 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",
@@ -1294,6 +1340,7 @@ 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)
@@ -1444,6 +1491,7 @@ def _compile_solver_network(
             edge.endpoint_b_port,
             connection_id=edge.id,
         )
+    network.validate_port_supplies()
     return network
 
 
@@ -1490,143 +1538,15 @@ def sanitize_project_id(project_id: str) -> str:
 
 
 def run_reactflow_testmodel(project: ReactFlowProjectPayload) -> dict[str, object]:
-    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(),
-    }
+    raise HTTPException(status_code=410, detail="The legacy Python example runner has been removed. Export System XML and use /api/system-xml/simulate.")
 
 
 def run_reactflow_test_mql(project: ReactFlowProjectPayload) -> dict[str, object]:
-    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),
-        },
-    }
+    raise HTTPException(status_code=410, detail="The legacy Python example runner has been removed. Export System XML and use /api/system-xml/simulate.")
 
 
-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(
@@ -1638,16 +1558,18 @@ def parameter_float(
         return default
     value = node.data.parameters.get(name, default)
     try:
+        if type(value) in (int, float) and isfinite(value):
             return float(value)
-    except (TypeError, ValueError):
-        raise ValueError(f"Parameter '{name}' on component '{node.id}' must be numeric.")
+    except OverflowError:
+        pass
+    raise ValueError(f"Parameter '{name}' on component '{node.id}' must be a finite SI number; normalize expressions before execution.")
 
 
-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),
-    )
+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.")

app/project_parameters.py

@@ -0,0 +1,250 @@
+"""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}

app/simulation/README.md

@@ -1,407 +1,19 @@
 # 仿真后端
 
-`app.simulation` 是 SystemSimulationApp 的仿真子包，用于承接模型定义、系统装配、数值求解和结果导出。
+当前采用 Python 编排、C 数值执行。输入 XML 经校验后，Python 根据模型参数和连接生成系统专用 C；GCC 编译成 EXE，EXE 内执行初始化、物性、流量、机械、RK45/CVODE BDF、事件和采样。求解循环不调用 Python。
 
-目标不是逐行翻译源模型，而是建立可运行、可测试、可导出，并能与 OpenModelica 或 AMESim baseline 对比的 Python 仿真框架。
+## 目录
 
-当前包含两条模型线：`Testmodel` 已有可运行的 ODE 近似和 OpenModelica 对比能力；`test_mql` 已形成 132 状态气动机械总闭包，正在按 AMESim baseline 做数值校准。
+- `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 组件公式和求解器。
 
-## 当前目录
+旧 Python 积分器、数值组件方法和固定算例专用求解器已经退役。旧 `/api/reactflow/simulate-testmodel`、`/api/reactflow/simulate-test-mql` 返回 410；使用 `/api/system-xml/simulate` 或流式接口。
 
-- `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 参考结果路径。
+旧 `ir/` 包、专属 schema、规范与测试已删除。当前 C 生成器直接使用经过校验的网络结构，不依赖旧 System IR v2。
 
-稳定基准存放在 `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/component-model-authoring-spec-v1.md)和
-[`组件库分类、发现与读取规范 v1`](../../docs/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/仿真性能评估-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/baselines/simulation/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 原始结果，参数大概率还要继续调。
+运行、支持范围与依赖见 [C 后端说明](../../native/README.md)。模型开发规则见 [组件规范](../../docs/standard/component-model-authoring-spec-v1.md)。历史性能、Amesim 差异和旧公式说明位于 `docs/other/` 及 Git 历史，不能作为当前运行入口。

app/simulation/backends.py

@@ -0,0 +1,38 @@
+"""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)

app/simulation/benchmark_performance.py

@@ -1,244 +0,0 @@
-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())

app/simulation/components/amesim/boundary/sources.py

@@ -1,13 +1,11 @@
+"""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.
@@ -16,53 +14,19 @@ 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"
-    PRESSURE_FLOW_DEPENDS_ON_STREAM = False
-    PORTS = (PortDefinition.pneumatic("port_1", nominal_role="bidirectional"),)
+    MODEL_TYPE = 'amesim_pnpl01'
+    MODEL_VERSION = '0.1.0'
+    PORTS = (PortDefinition.pneumatic('port_1', computation=ZERO_FLOW_SUPPLY),)
     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)
-
-    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"]
+    EQUATIONS = ({'id': '__MODEL__:zero_mass_flow', 'owner': 'component', 'ownerId': '__MODEL__', 'relation': 'constitutive', 'variables': ['__MODEL__.port_1.m_flow'], 'role': 'flow'},)

app/simulation/components/amesim/junctions/nodes.py

@@ -1,25 +1,23 @@
+"""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, PortState
-
+from app.simulation.core.ports import PortDefinition
+from app.simulation.core.port_computation import NODE_BRANCH, NODE_REFERENCE
 
 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. When port 2 is
-    an outlet, its enthalpy is the residual that closes the junction energy
-    balance, matching the AMESim dh2 causality.
+    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.
     """
-
-    PRESSURE_FLOW_DEPENDS_ON_STREAM = False
-    REFERENCE_PORT = "port_2"
+    REFERENCE_PORT = 'port_2'
 
     def __init__(self, name: str) -> None:
         super().__init__(name=name)
@@ -28,167 +26,30 @@ 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 < -1e-12:
-            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
-            )
-            reference_port.h_outflow = (
-                -energy_without_reference / reference_port.m_flow
-            )
-
-
 class AmesimPn3Node2(_AmesimPneumaticNode):
     """AMESim PN3NODE2 pneumatic three-port junction."""
-
-    MODEL_TYPE = "amesim_pn3node2"
-    MODEL_VERSION = "0.3.0"
-    PRESSURE_FLOW_DEPENDS_ON_STREAM = False
-    PORTS = (
-        PortDefinition.pneumatic("port_1", nominal_role="bidirectional"),
-        PortDefinition.pneumatic("port_2", nominal_role="bidirectional"),
-        PortDefinition.pneumatic("port_3", nominal_role="bidirectional"),
-    )
+    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))
     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"
-    PRESSURE_FLOW_DEPENDS_ON_STREAM = False
-    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"),
-    )
+    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))
     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'})

app/simulation/components/amesim/mechanical/pistons.py

@@ -1,23 +1,16 @@
+"""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 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
 
-
 class AmesimPnrp17(AlgebraicComponent):
     """AMESim PNRP17 pneumatic piston with two mechanical faces.
 
@@ -25,221 +18,32 @@ 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)
 
-    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:
+    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
-
-    @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 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,
-        }
+    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'})

app/simulation/components/amesim/media/mediums.py

@@ -1,319 +1,48 @@
+"""Gas identities and constants passed to the native compiler."""
 from __future__ import annotations
-
 from collections.abc import Callable
 from dataclasses import dataclass
 from typing import ClassVar
-
-from app.simulation.core.errors import RecoverableTrialStateError
-from app.simulation.core.medium import (
-    GasMedium,
-    IdealGasMedium,
-    ThermodynamicProperties,
-)
-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
-
+from app.simulation.core.medium import GasMedium, IdealGasMedium
 
 @dataclass(frozen=True)
 class AmesimIdealAirMedium(IdealGasMedium):
-    """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"
+    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-5
+    viscosity_ref: float = 1.82e-05
     viscosity_T_ref: float = 293.15
     sutherland_constant: float = 110.4
 
-
 @dataclass(frozen=True)
 class AmesimHeliumPengRobinsonMedium(IdealGasMedium):
-    """AMESim helium with a Peng-Robinson mechanical equation of state.
+    """Helium identity; reference constants below describe the lower range.
 
-    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``.
+    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.
     """
-
-    SUBSTANCE_ID: ClassVar[str] = "helium"
-    PROPERTY_METHOD_ID: ClassVar[str] = "peng_robinson"
-    fluid: ClassVar[PengRobinsonFluid] = HELIUM_PR
+    SUBSTANCE_ID: ClassVar[str] = 'helium'
+    PROPERTY_METHOD_ID: ClassVar[str] = 'peng_robinson'
     nasa_cp_over_R: ClassVar[float] = 2.5
     nasa_enthalpy_constant_K: ClassVar[float] = -745.375
-
-    name: str = "AMESimHeliumPengRobinson"
-    R_gas: float = HELIUM_PR.specific_gas_constant
-    cp_ref: float = nasa_cp_over_R * HELIUM_PR.specific_gas_constant
+    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)
     T_ref: float = 293.15
     cp_slope: float = 0.0
-    viscosity_ref: float = 1.96e-5
+    viscosity_ref: float = 1.96e-05
     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
-
-    @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,
-            ),
-        )
-
-
 @dataclass(frozen=True)
 class AmesimGasPropertyModelSpec:
     """A selectable calculation method for one AMESim gas substance."""
-
     value: int
     label: str
     method_id: str
@@ -322,27 +51,7 @@ 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),)

app/simulation/components/amesim/semantics.py

@@ -0,0 +1,74 @@
+"""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)

app/simulation/components/amesim/signals/sources.py

@@ -1,355 +1,79 @@
+"""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)
-)
+    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)
 
-    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:
+    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.signal = self.output_at(0.0)
+        self.out = self.register_declared_port('out')
 
     @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"],
-        )
-
-    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}
-
+    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 = ()
 
 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),))
 
-    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:
+    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.signal = self.output_at(0.0)
+        self.out = self.register_declared_port('out')
 
     @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)),
-        )
-
-    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}
+                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 = ()

app/simulation/components/amesim/storage/chambers.py

@@ -1,23 +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.components.amesim.gases import (
-    AMESIM_GAS_INDEX_PARAMETER,
-    normalize_amesim_gas_index,
-)
+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.equations import EquationResidual
-from app.simulation.core.metadata import (
-    ParameterDefinition,
-    ResultVariableDefinition,
-    THERMODYNAMIC_VOLUME_RESULT_VARIABLES,
-)
-from app.simulation.core.medium import GasMedium, ThermodynamicProperties
+from app.simulation.core.metadata import ParameterDefinition, ResultVariableDefinition, THERMODYNAMIC_VOLUME_RESULT_VARIABLES
+from app.simulation.core.medium import GasMedium
 from app.simulation.core.ports import PortDefinition
-from app.simulation.core.state import VolumeState
-
+from app.simulation.core.port_computation import THERMODYNAMIC_SUPPLY
 
 class AmesimPnch023(ThermodynamicVolumeComponent):
     """AMESim PNCH023 simple pneumatic chamber with heat exchange.
@@ -27,112 +17,16 @@ 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", 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="仿真开始时气室内气体的绝对温度。",
-        ),
-    )
+    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,
-    )
+    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:
+    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)
@@ -141,266 +35,33 @@ class AmesimPnch023(ThermodynamicVolumeComponent):
         self.gi = normalize_amesim_gas_index(gi)
         self.p0 = float(p0)
         self.T0 = float(T0)
-        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
+        self.port_1 = self.register_declared_port('port_1')
+        self.port_2 = self.register_declared_port('port_2')
 
     @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"],
-        )
-
-    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,
-            ),
-        )
-
+    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'})
 
 class AmesimPnch012(ThermodynamicVolumeComponent):
     """AMESim PNCH012 variable-volume pneumatic chamber.
 
     AMESim supplies four external volume and volume-rate inputs through the
-    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.
+    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.
     """
+    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)
 
-    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:
+    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)
@@ -409,141 +70,13 @@ 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),
-        }
-        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"):
+        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'):
             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))
-
-    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 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")
-        )
+    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'})

app/simulation/components/example.md

@@ -1,282 +0,0 @@
-# 元件建模规范与示例
-
-规范的权威版本位于
-[`docs/component-model-authoring-spec-v1.md`](../../../docs/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/component-library-spec-v1.md)。

app/simulation/components/experimental/flow/orifice.py

@@ -1,119 +1,35 @@
+"""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"
-    PRESSURE_FLOW_DEPENDS_ON_STREAM = False
-    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,
-        ),
-    )
+    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,
-    )
+    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:
+    def __init__(self, name: str, opening: float=1.0, K: float=1e-05) -> 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)
-
-    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"]
-
+    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'})

app/simulation/components/experimental/flow/pipe.py

@@ -1,10 +0,0 @@
-"""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",)

app/simulation/components/experimental/flow/resistive_pipe.py

@@ -1,103 +1,26 @@
+"""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"
-    PRESSURE_FLOW_DEPENDS_ON_STREAM = False
-    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,
-        ),
-    )
+    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,
-    )
+    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:
+    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:
         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
@@ -105,82 +28,10 @@ class ResistivePipe(AlgebraicComponent):
         self.p0 = p0
         self.T0 = T0
         self.area = pi * D * D / 4.0
-        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
+        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],
-    ) -> 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"]
+    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'})

app/simulation/components/experimental/junctions/tee.py

@@ -1,267 +1,28 @@
+"""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"
-    PRESSURE_FLOW_DEPENDS_ON_STREAM = False
-    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'
+    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)
-
-    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)
+    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'})

app/simulation/components/experimental/storage/cylinder.py

@@ -1,155 +1,30 @@
+"""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.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.metadata import ParameterDefinition, THERMODYNAMIC_VOLUME_RESULT_VARIABLES
+from app.simulation.core.medium import IdealGasMedium
 from app.simulation.core.ports import PortDefinition
-from app.simulation.core.state import VolumeState
-
+from app.simulation.core.port_computation import THERMODYNAMIC_SUPPLY
 
 class Cylinder(ThermodynamicVolumeComponent):
     """Python port of ModelicaModels.Mycylinder."""
-
-    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,
-        ),
-    )
+    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,
-    )
+    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:
+    def __init__(self, name: str, medium: IdealGasMedium, V: float=0.01, p0: float=35000000.0, 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
-        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")
+        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"],
-        )
-
-    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)
+    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'},)

app/simulation/components/experimental/storage/tank.py

@@ -1,155 +1,30 @@
+"""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.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.metadata import ParameterDefinition, THERMODYNAMIC_VOLUME_RESULT_VARIABLES
+from app.simulation.core.medium import IdealGasMedium
 from app.simulation.core.ports import PortDefinition
-from app.simulation.core.state import VolumeState
-
+from app.simulation.core.port_computation import THERMODYNAMIC_SUPPLY
 
 class Tank(ThermodynamicVolumeComponent):
     """Python port of ModelicaModels.Mytank."""
-
-    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,
-        ),
-    )
+    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,
-    )
+    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:
+    def __init__(self, name: str, medium: IdealGasMedium, V: float=0.1, p0: float=100000.0, 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
-        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")
+        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"],
-        )
-
-    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)
+    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'},)

app/simulation/config.py

@@ -0,0 +1,148 @@
+"""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

app/simulation/core/base.py

@@ -1,33 +1,17 @@
 from __future__ import annotations
-
-from abc import ABC, abstractmethod
+from abc import ABC
 from collections.abc import Mapping
-from typing import TYPE_CHECKING, Any, ClassVar
-
+from typing import TYPE_CHECKING, ClassVar
 from app.simulation.core.catalog import ComponentDisplaySpec
-from app.simulation.core.equations import EquationResidual
-from app.simulation.core.metadata import (
-    ParameterDefinition,
-    ResultVariableDefinition,
-    ResultVariableMetadata,
-    THERMODYNAMIC_VOLUME_RESULT_VARIABLES,
-)
+from app.simulation.core.equations import EquationDefinition
+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
     PORTS: ClassVar[tuple[PortDefinition, ...]] = ()
     PARAMETERS: ClassVar[tuple[ParameterDefinition, ...]] = ()
     RESULT_VARIABLES: ClassVar[tuple[ResultVariableDefinition, ...]] = ()
@@ -45,80 +29,53 @@ 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
 
@@ -130,217 +87,40 @@ 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
-
-    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
+            raise ValueError(f'Component {self.name} has no port named {name}.') from exc
 
     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 = ()
 
-        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 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 equation_definitions(self):
 
+        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."""

app/simulation/core/equations.py

@@ -11,15 +11,14 @@ EquationRelation = Literal["equal", "sumToZero", "constitutive", "state"]
 
 
 @dataclass(frozen=True, slots=True)
-class EquationResidual:
-    """One executable scalar equation in the pressure-flow subsystem."""
+class EquationDefinition:
+    """One declarative equation in the compiled model interface."""
 
     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]:
@@ -33,4 +32,4 @@ class EquationResidual:
         }
 
     def as_interface_dict(self) -> dict[str, object]:
-        return {**self.as_definition_dict(), "residual": self.value}
+        return self.as_definition_dict()

app/simulation/core/medium.py

@@ -1,226 +1,16 @@
+"""Compile-time gas property constants. No Python property evaluator."""
 from __future__ import annotations
-
 from dataclasses import dataclass
-from typing import Protocol
-
-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
-
-
-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 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: ...
-
 
 @dataclass(frozen=True)
 class IdealGasMedium:
-    """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"
+    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-5
+    viscosity_ref: float = 1.82e-05
     viscosity_T_ref: float = 293.15
     sutherland_constant: float = 110.4
 
-    @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)
-        )
-
-    @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)
+GasMedium = IdealGasMedium

app/simulation/core/peng_robinson.py

@@ -1,424 +0,0 @@
-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)

app/simulation/core/port_computation.py

@@ -0,0 +1,152 @@
+"""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

app/simulation/core/ports.py

@@ -3,6 +3,8 @@ 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"]
@@ -45,6 +47,7 @@ class PortDefinition:
     nominal_role: PortNominalRole
     positive_flow_direction: Literal["intoComponent"] | None = None
     variables: tuple[PortVariableDefinition, ...] = ()
+    computation: PortComputation | None = None
 
     @classmethod
     def pneumatic(
@@ -52,6 +55,7 @@ class PortDefinition:
         name: str,
         *,
         nominal_role: Literal["inlet", "outlet", "bidirectional"] = "bidirectional",
+        computation: PortComputation = IMPLICIT_PNEUMATIC,
     ) -> PortDefinition:
         return cls(
             name=name,
@@ -59,6 +63,7 @@ class PortDefinition:
             domain="pneumatic",
             nominal_role=nominal_role,
             positive_flow_direction="intoComponent",
+            computation=computation,
             variables=(
                 PortVariableDefinition(
                     "p",
@@ -188,6 +193,7 @@ 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 {}),
         }
 
 

app/simulation/core/state.py

@@ -1,21 +0,0 @@
-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])
-

app/simulation/examples/__init__.py

@@ -1 +0,0 @@
-"""Reference systems and regression examples."""

app/simulation/examples/test_mql/__init__.py

@@ -1,25 +0,0 @@
-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",
-]

app/simulation/examples/test_mql/baseline.py

@@ -1,77 +0,0 @@
-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,
-    )

app/simulation/examples/test_mql/computed.py

@@ -1,468 +0,0 @@
-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
-

app/simulation/examples/test_mql/config.py

@@ -1,151 +0,0 @@
-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)}")

app/simulation/examples/test_mql/line_parameters.py

@@ -1,451 +0,0 @@
-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

app/simulation/examples/test_mql/lines.py

@@ -1,102 +0,0 @@
-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

app/simulation/examples/test_mql/mechanical.py

@@ -1,544 +0,0 @@
-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)

app/simulation/examples/test_mql/nodes.py

@@ -1,215 +0,0 @@
-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"
-    }

app/simulation/examples/test_mql/pneumatic.py

@@ -1,273 +0,0 @@
-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

app/simulation/examples/test_mql/pneumatic_lines.py

@@ -1,194 +0,0 @@
-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)

app/simulation/examples/test_mql/pneumatic_topology.py

@@ -1,128 +0,0 @@
-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,
-    }

app/simulation/examples/test_mql/primitives/__init__.py

@@ -1 +0,0 @@
-"""Calibrated component primitives used only by the ``test_mql`` example."""

app/simulation/examples/test_mql/primitives/mechanical.py

@@ -1,168 +0,0 @@
-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
-

app/simulation/examples/test_mql/primitives/pneumatic.py

@@ -1,437 +0,0 @@
-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

app/simulation/examples/test_mql/primitives/pneumatic_lines.py

@@ -1,881 +0,0 @@
-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)
-    )

app/simulation/examples/test_mql/run.py

@@ -1,100 +0,0 @@
-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()

app/simulation/examples/test_mql/run_baseline.py

@@ -1,80 +0,0 @@
-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()

app/simulation/examples/test_mql/solver.py

@@ -1,18 +0,0 @@
-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"]

app/simulation/examples/test_mql/structural_network.py

@@ -1,78 +0,0 @@
-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)
-

app/simulation/examples/test_mql/topology.py

@@ -1,118 +0,0 @@
-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

app/simulation/examples/testmodel/__init__.py

@@ -1 +0,0 @@
-"""Legacy TestModel reference system."""

app/simulation/examples/testmodel/closure.py

@@ -1,668 +0,0 @@
-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,
-        ]

app/simulation/examples/testmodel/dynamic_pipe.py

@@ -1,272 +0,0 @@
-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)

app/simulation/examples/testmodel/run.py

@@ -1,222 +0,0 @@
-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()

app/simulation/examples/testmodel/system.py

@@ -1,303 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from typing import Any
-
-from app.simulation.components.experimental.flow.orifice import Orifice
-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
-from app.simulation.examples.testmodel.closure import (
-    BranchClosureComponents,
-    InitializationDiagnostics,
-    TestModelClosure,
-    TestModelClosureComponents,
-    TestModelSnapshot,
-)
-from app.simulation.examples.testmodel.dynamic_pipe import Pipe
-from app.simulation.solvers.solver import SolveIVPConfig, integrate_ode
-from app.simulation.systems.network import SimulationNetwork
-
-
-@dataclass(frozen=True)
-class CylinderConfig:
-    volume: float = 0.01
-    p0: float = 35e6
-    T0: float = 300.0
-
-
-@dataclass(frozen=True)
-class OrificeConfig:
-    K: float = 1e-5
-
-
-@dataclass(frozen=True)
-class TankConfig:
-    volume: float = 0.1
-    p0: float = 1e5
-    T0: float = 300.0
-
-
-@dataclass(frozen=True)
-class PipeConfig:
-    length: float = 5.0
-    diameter: float = 0.02
-    lambda_darcy: float = 0.02
-    p0: float = 1e5
-    T0: float = 300.0
-
-
-@dataclass(frozen=True)
-class BranchConfig:
-    orifice: OrificeConfig = field(default_factory=OrificeConfig)
-    pipe: PipeConfig = field(default_factory=PipeConfig)
-
-
-@dataclass(frozen=True)
-class TestModelConfig:
-    cylinder: CylinderConfig = field(default_factory=CylinderConfig)
-    upper_branch: BranchConfig = field(default_factory=BranchConfig)
-    lower_branch: BranchConfig = field(default_factory=BranchConfig)
-    tank: TankConfig = field(default_factory=TankConfig)
-
-
-class TestModelSystem:
-    """Runnable first-pass Python system for the current Testmodel topology.
-
-    This version keeps the component split from the Modelica model while keeping
-    the downstream tee-tank pressure coupling in the ODE framework. The original
-    Modelica system is a tighter DAE because both pipe outlets discharge into an
-    ideal lossless junction directly connected to the tank. Here the branch
-    outlet flows are solved from a pressure-consistent energy balance so the
-    outlet is no longer driven by an arbitrary conductance parameter.
-    """
-
-    def __init__(
-        self,
-        medium: IdealGasMedium | None = None,
-        config: TestModelConfig | None = None,
-    ) -> None:
-        self.medium = medium or IdealGasMedium()
-        self.config = config or TestModelConfig()
-
-        self.mycylinder = Cylinder(
-            name="mycylinder",
-            medium=self.medium,
-            V=self.config.cylinder.volume,
-            p0=self.config.cylinder.p0,
-            T0=self.config.cylinder.T0,
-        )
-        self.mytee = Tee(name="mytee")
-        self.myorifice = Orifice(name="myorifice", K=self.config.upper_branch.orifice.K)
-        self.mypipe = Pipe(
-            name="mypipe",
-            medium=self.medium,
-            L=self.config.upper_branch.pipe.length,
-            D=self.config.upper_branch.pipe.diameter,
-            lambda_darcy=self.config.upper_branch.pipe.lambda_darcy,
-            p0=self.config.upper_branch.pipe.p0,
-            T0=self.config.upper_branch.pipe.T0,
-        )
-        self.myorifice1 = Orifice(name="myorifice1", K=self.config.lower_branch.orifice.K)
-        self.mypipe1 = Pipe(
-            name="mypipe1",
-            medium=self.medium,
-            L=self.config.lower_branch.pipe.length,
-            D=self.config.lower_branch.pipe.diameter,
-            lambda_darcy=self.config.lower_branch.pipe.lambda_darcy,
-            p0=self.config.lower_branch.pipe.p0,
-            T0=self.config.lower_branch.pipe.T0,
-        )
-        self.mytee1 = Tee(name="mytee1")
-        self.mytank = Tank(
-            name="mytank",
-            medium=self.medium,
-            V=self.config.tank.volume,
-            p0=self.config.tank.p0,
-            T0=self.config.tank.T0,
-        )
-
-        self.network = SimulationNetwork(name="Testmodel")
-        for component in (
-            self.mycylinder,
-            self.mytee,
-            self.myorifice,
-            self.mypipe,
-            self.myorifice1,
-            self.mypipe1,
-            self.mytee1,
-            self.mytank,
-        ):
-            self.network.add_component(component)
-
-        self.network.connect("mycylinder", "port_b", "mytee", "port_in")
-        self.network.connect("mytee", "port_out1", "myorifice", "port_a")
-        self.network.connect("myorifice", "port_b", "mypipe", "port_a")
-        self.network.connect("mypipe", "port_b", "mytee1", "port_out2")
-        self.network.connect("mytee", "port_out2", "myorifice1", "port_a")
-        self.network.connect("myorifice1", "port_b", "mypipe1", "port_a")
-        self.network.connect("mypipe1", "port_b", "mytee1", "port_out1")
-        self.network.connect("mytee1", "port_in", "mytank", "port_a")
-
-        self.closure = TestModelClosure(
-            medium=self.medium,
-            components=TestModelClosureComponents(
-                cylinder=self.mycylinder,
-                upstream_tee=self.mytee,
-                upper_branch=BranchClosureComponents(
-                    name="upper_branch",
-                    orifice=self.myorifice,
-                    pipe=self.mypipe,
-                ),
-                lower_branch=BranchClosureComponents(
-                    name="lower_branch",
-                    orifice=self.myorifice1,
-                    pipe=self.mypipe1,
-                ),
-                downstream_tee=self.mytee1,
-                tank=self.mytank,
-            ),
-            initial_state_vector=self.initial_state_vector,
-            apply_state_vector=self.apply_state_vector,
-        )
-
-    def initial_state_vector(self) -> list[float]:
-        return self.network.initial_state_vector()
-
-    def apply_state_vector(self, values: list[float]) -> None:
-        self.network.apply_state_vector(values)
-
-    def consistent_initial_state_vector(self) -> list[float]:
-        return self.closure.consistent_initial_state_vector()
-
-    @property
-    def last_solve_diagnostics(self):
-        return self.closure.last_solve_diagnostics
-
-    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:
-        return self.closure.initialize_consistent_state(
-            max_iterations=max_iterations,
-            state_tolerance=state_tolerance,
-            flow_tolerance=flow_tolerance,
-            enthalpy_tolerance=enthalpy_tolerance,
-            pressure_tolerance=pressure_tolerance,
-            strict_internal_solvers=strict_internal_solvers,
-        )
-
-    def project_downstream_pressure_constraints(self, *, strict: bool = False) -> None:
-        self.closure.project_downstream_pressure_constraints(strict=strict)
-
-    def snapshot(
-        self,
-        state_vector: list[float] | None = None,
-        *,
-        strict: bool = False,
-    ) -> TestModelSnapshot:
-        return self.closure.snapshot(state_vector, strict=strict)
-
-    def rhs(self, _t: float, state_vector: list[float]) -> list[float]:
-        return self.closure.rhs(state_vector)
-
-    @staticmethod
-    def _legacy_branch_series_key_map() -> tuple[tuple[str, str, str], tuple[str, str, str]]:
-        return (
-            ("upper_branch", "branch_upper.in", "branch_upper.out"),
-            ("lower_branch", "branch_lower.in", "branch_lower.out"),
-        )
-
-    @classmethod
-    def _legacy_branch_series_keys_by_name(cls) -> dict[str, tuple[str, str]]:
-        return {
-            branch_name: (inlet_key, outlet_key)
-            for branch_name, inlet_key, outlet_key in cls._legacy_branch_series_key_map()
-        }
-
-    @staticmethod
-    def _generic_branch_series_keys(branch_name: str) -> tuple[str, str, str]:
-        return (
-            f"branch.{branch_name}.p",
-            f"branch.{branch_name}.in",
-            f"branch.{branch_name}.out",
-        )
-
-    @staticmethod
-    def _legacy_branch_pressure_keys_by_name() -> dict[str, str]:
-        return {
-            "upper_branch": "mypipe.p",
-            "lower_branch": "mypipe1.p",
-        }
-
-    @classmethod
-    def _append_legacy_branch_series_aliases(
-        cls,
-        series: dict[str, list[float]],
-    ) -> dict[str, list[float]]:
-        legacy_branch_series_keys = cls._legacy_branch_series_keys_by_name()
-        legacy_branch_pressure_keys = cls._legacy_branch_pressure_keys_by_name()
-        for branch_name, (legacy_inlet_key, legacy_outlet_key) in legacy_branch_series_keys.items():
-            pressure_key, generic_inlet_key, generic_outlet_key = cls._generic_branch_series_keys(
-                branch_name
-            )
-            series[legacy_branch_pressure_keys[branch_name]] = list(series[pressure_key])
-            series[legacy_inlet_key] = list(series[generic_inlet_key])
-            series[legacy_outlet_key] = list(series[generic_outlet_key])
-        return series
-
-    def simulate(
-        self,
-        config: SolveIVPConfig | None = None,
-        t_eval: list[float] | None = None,
-    ) -> Any:
-        return integrate_ode(
-            rhs=self.rhs,
-            initial_state=self.consistent_initial_state_vector(),
-            config=config or SolveIVPConfig(),
-            t_eval=t_eval,
-        )
-
-    def evaluate_solution(self, solution: Any) -> dict[str, list[float]]:
-        series = {
-            "time": [],
-            "mycylinder.p": [],
-            "mycylinder.T": [],
-            "mytank.p": [],
-            "mytank.T": [],
-        }
-        for branch_name, _, _ in self._legacy_branch_series_key_map():
-            pressure_key, inlet_key, outlet_key = self._generic_branch_series_keys(branch_name)
-            series[pressure_key] = []
-            series[inlet_key] = []
-            series[outlet_key] = []
-
-        for index, time_value in enumerate(solution.t):
-            state_vector = [row[index] for row in solution.y]
-            snapshot = self.snapshot(state_vector)
-            series["time"].append(float(time_value))
-            series["mycylinder.p"].append(snapshot.cylinder.p)
-            series["mycylinder.T"].append(snapshot.cylinder.T)
-            series["mytank.p"].append(snapshot.tank.p)
-            series["mytank.T"].append(snapshot.tank.T)
-            for branch in snapshot.branches:
-                pressure_key, generic_inlet_key, generic_outlet_key = self._generic_branch_series_keys(
-                    branch.name
-                )
-                series[pressure_key].append(branch.pipe.p)
-                series[generic_inlet_key].append(branch.inlet_flow)
-                series[generic_outlet_key].append(branch.outlet_flow)
-
-        return self._append_legacy_branch_series_aliases(series)
-
-
-def build_testmodel() -> SimulationNetwork:
-    """Compatibility helper for callers that only need the topology."""
-
-    return TestModelSystem().network

app/simulation/native_codegen/__init__.py

@@ -0,0 +1 @@
+"""Compilation of supported XML networks to independent native executables."""

app/simulation/native_codegen/__main__.py

@@ -0,0 +1,82 @@
+"""python -m app.simulation.native_codegen INPUT.xml|json --output-dir DIR"""
+from __future__ import annotations
+
+import argparse
+from dataclasses import replace
+from hashlib import sha256
+import json
+from pathlib import Path
+import shutil
+import statistics
+import time
+
+from app.main import compile_system_xml_network
+from app.simulation.backends import simulation_config
+from .build import build_native
+from .compiler import compile_native_program
+from .input import load_input
+from .runner import execute_native
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("input", type=Path)
+    parser.add_argument("--output-dir", type=Path, required=True)
+    parser.add_argument("--method", choices=("RK45", "BDF"))
+    parser.add_argument("--max-step", type=float)
+    parser.add_argument("--rtol", type=float)
+    parser.add_argument("--runs", type=int, default=3)
+    parser.add_argument("--timeout", type=float, default=300)
+    parser.add_argument("--solve-only", action="store_true")
+    args = parser.parse_args()
+    if args.runs < 1:
+        parser.error("--runs must be positive")
+    out = args.output_dir.resolve()
+    out.mkdir(parents=True, exist_ok=True)
+    if (out / "summary.json").exists():
+        parser.error("Output directory already contains a completed run; choose a new directory.")
+    started = time.perf_counter()
+    xml, document = load_input(args.input)
+    program = compile_native_program(compile_system_xml_network(document))
+    config = simulation_config(document.simulation)
+    for name in ("method", "max_step", "rtol"):
+        if getattr(args, name) is not None:
+            config = replace(config, **{name: getattr(args, name)})
+    preparation = time.perf_counter()-started
+    (out / "input.xml").write_bytes(xml)
+    build = build_native(program)
+    package = out / "program"
+    package.mkdir(exist_ok=True)
+    for name in (*build.manifest["artifacts"], "manifest.json"):
+        shutil.copy2(build.executable.parent / name, package / name)
+    (out / "model-manifest.json").write_text(json.dumps(build.manifest, ensure_ascii=False, indent=2), encoding="utf-8")
+    rows = []
+    for i in range(args.runs+1):
+        data = execute_native(build, config, document.simulation.sample_step,
+                              run_dir=out / ("warmup" if i == 0 else f"run-{i}"),
+                              record_samples=not args.solve_only, timeout=args.timeout)
+        row = {k: v for k, v in data.items() if k not in ("series", "final", "finalState")}
+        row["run"] = "warmup" if i == 0 else i
+        rows.append(row)
+        print(json.dumps(row, ensure_ascii=False), flush=True)
+        if not data["success"]:
+            break
+    measured = rows[1:]
+    summary = {
+        "source": str(args.input.resolve()), "sourceSha256": sha256(args.input.read_bytes()).hexdigest(),
+        "xmlSha256": sha256(xml).hexdigest(), "executable": str(package / build.executable.name),
+        "cachedExecutable": str(build.executable),
+        "buildKey": build.manifest["buildKey"], "buildSeconds": build.seconds,
+        "preparationSeconds": preparation, "cacheHit": build.cache_hit,
+        "settings": vars(config), "sampleStep": document.simulation.sample_step,
+        "recordSamples": not args.solve_only, "runs": rows,
+        "success": len(measured) == args.runs and all(row["success"] for row in rows),
+        "medianSolveSeconds": statistics.median(row["solveSeconds"] for row in measured) if measured else None,
+    }
+    (out / "summary.json").write_text(json.dumps(summary, ensure_ascii=False, indent=2), encoding="utf-8")
+    print(json.dumps({k: v for k, v in summary.items() if k != "runs"}, ensure_ascii=False))
+    return 0 if summary["success"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

app/simulation/native_codegen/build.py

@@ -0,0 +1,403 @@
+"""On-demand native modules, checked object reuse and bounded executable caches."""
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from hashlib import sha256
+import json
+import logging
+import os
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+from typing import Any, Callable
+
+from .compiler import NativeProgram
+from .modules import component_modules
+from .processes import command_environment, is_driver_launch_failure, is_transient_process_error, LAUNCH_RETRY_DELAYS
+from .cache_storage import acquire_cache_lease, touch_cache_entry, prune_cache
+
+LOGGER = logging.getLogger(__name__)
+WINDOWS = os.name == 'nt'
+
+
+class NativeCommandError(RuntimeError):
+    def __init__(self, message, command, *, exit_code=None, stdout=b'', stderr='', error_type='CalledProcessError', attempts=1):
+        super().__init__(message)
+        self.details = {'command': list(command), 'cwd': str(Path.cwd()), 'exitCode': exit_code,
+                        'stdout': stdout.decode('utf-8',errors='replace')[-8000:], 'stderr': stderr[-8000:],
+                        'errorType': error_type, 'attempts': attempts}
+
+ROOT = Path(__file__).resolve().parents[3]
+NATIVE = ROOT / "native"
+CACHE = ROOT / "app/data/native-builds"
+LIBRARIES = ("cvode", "core", "nvecserial", "sunmatrixdense", "sunlinsoldense")
+COMPILER_FLAGS = ("-std=c11", "-O3", "-Wall", "-Wextra", "-Werror", "-ffp-contract=off", "-fno-fast-math")
+RUNTIME_SOURCES = ("runtime/main.c", "runtime/common.c", "runtime/sample_storage.c", "runtime/rk45.c",
+                   "runtime/cvode_solver.c", "runtime/json_numbers.c", "encoding/ryu/d2s.c")
+
+
+@dataclass(frozen=True)
+class NativeBuild:
+    executable: Path
+    manifest: dict
+    cache_hit: bool
+    seconds: float
+    details: dict = field(default_factory=dict)
+    _lease: Any = field(default=None, repr=False, compare=False)
+    _cache: Path | None = field(default=None, repr=False, compare=False)
+
+    def close(self) -> None:
+        """Release this caller's executable pin after its last use."""
+        if self._lease is not None:
+            self._lease.close()
+        if self._cache is not None:
+            _prune(self._cache)
+
+
+def _hash(path: Path) -> str:
+    return sha256(path.read_bytes()).hexdigest()
+
+
+def _key(value: object) -> str:
+    return sha256(json.dumps(value, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+
+
+def _runtime_sources(program: NativeProgram) -> list[Path]:
+    return [NATIVE / name for name in RUNTIME_SOURCES] + [
+        NATIVE / "components/modules" / f"{name}.c"
+        for name in component_modules(program.source + "\n" + program.header)
+    ]
+
+
+def _budget(name: str, default: int) -> int:
+    value = os.environ.get(name, str(default))
+    if not re.fullmatch(r"[0-9]+", value):
+        raise ValueError(f"{name} must be a nonnegative integer in MiB.")
+    return int(value) * 1024**2
+
+
+def _prune(cache: Path) -> dict:
+    return prune_cache(cache,
+        model_limit_bytes=_budget("SIMULATION_NATIVE_MODEL_CACHE_MB", 256),
+        object_limit_bytes=_budget("SIMULATION_NATIVE_OBJECT_CACHE_MB", 128))
+
+
+def _checked_manifest(target: Path, key_name: str, key: str, version: int, required: set[str]) -> dict | None:
+    if not target.exists() and not target.is_symlink():
+        return None
+    message = f"Native cache integrity check failed: {target}"
+    if target.is_symlink() or not target.is_dir():
+        raise RuntimeError(message)
+    try:
+        path = target / "manifest.json"
+        if path.is_symlink():
+            raise ValueError("linked manifest")
+        manifest = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(manifest, dict) or manifest.get(key_name) != key or manifest.get("cacheVersion") != version:
+            raise ValueError("identity mismatch")
+        artifacts = manifest.get("artifacts")
+        if not isinstance(artifacts, dict) or set(artifacts) != required:
+            raise ValueError("incomplete artifacts")
+        if key_name == "objectKey":
+            recipe = {name: manifest[name] for name in ("cacheVersion", "sourceName", "preprocessedSha256", "compiler")}
+            if _key(recipe) != key:
+                raise ValueError("object identity mismatch")
+        else:
+            recipe = manifest.get("buildIdentity")
+            if not isinstance(recipe, dict) or _key(recipe) != key or manifest.get("objectKeys") != recipe["objectKeys"]:
+                raise ValueError("model identity mismatch")
+            if artifacts["model.c"] != recipe["sourceSha256"] or artifacts["model.h"] != recipe["headerSha256"]:
+                raise ValueError("model source identity mismatch")
+            if _key({name: manifest[name] for name in recipe["contractKeys"]}) != recipe["contractSha256"]:
+                raise ValueError("model contract mismatch")
+            if artifacts["THIRD_PARTY_NOTICES.txt"] != recipe["notice"]:
+                raise ValueError("license artifact mismatch")
+            for name in required:
+                if name.lower().endswith(".dll") and artifacts[name] != recipe["dependencies"][name]:
+                    raise ValueError("runtime dependency artifact mismatch")
+        for name, digest in artifacts.items():
+            if not re.fullmatch(r"[A-Za-z0-9_.-]+", name) or name in (".", ".."):
+                raise ValueError("invalid artifact name")
+            path = target / name
+            if path.is_symlink() or not path.is_file() or not isinstance(digest, str) or _hash(path) != digest:
+                raise ValueError("artifact mismatch")
+        return manifest
+    except (OSError, ValueError, TypeError, KeyError) as exc:
+        raise RuntimeError(message) from exc
+
+
+def _publish(stage: Path, target: Path, key_name: str, key: str, version: int, required: set[str]) -> dict:
+    try:
+        stage.rename(target)
+    except OSError:
+        # Another reader/build may publish the same content while we compile.
+        # Its artifacts need not be byte-identical (e.g. PE timestamps), but
+        # must satisfy the same complete identity and its own recorded hashes.
+        winner = _checked_manifest(target, key_name, key, version, required)
+        if winner is None:
+            raise
+        shutil.rmtree(stage)
+        return winner
+    manifest = _checked_manifest(target, key_name, key, version, required)
+    assert manifest is not None
+    return manifest
+
+
+def _command(command: list[str], *, log: list[str], timeout: float = 120,
+             require_stdout: bool = False) -> bytes:
+    environment = command_environment(command[0])
+    for attempt in range(len(LAUNCH_RETRY_DELAYS) + 1):
+        try:
+            result = subprocess.run(command, capture_output=True, timeout=timeout,
+                                    stdin=subprocess.DEVNULL, close_fds=True, env=environment,
+                                    creationflags=subprocess.CREATE_NO_WINDOW if WINDOWS else 0)
+        except OSError as exc:
+            if not is_transient_process_error(exc) or attempt == len(LAUNCH_RETRY_DELAYS):
+                raise
+            reason = f'{type(exc).__name__}: {exc}'
+        else:
+            stderr = result.stderr.decode('utf-8', errors='replace')
+            log.append(' '.join(command) + '\n' + stderr)
+            empty = result.returncode == 0 and require_stdout and not result.stdout.strip()
+            transient = is_driver_launch_failure(stderr) or (empty and WINDOWS)
+            if not result.returncode and not empty:
+                return result.stdout
+            reason = 'Compiler returned no identification output.' if empty else stderr[-3000:]
+            if not transient or attempt == len(LAUNCH_RETRY_DELAYS):
+                prefix = ('GCC 已启动，但编译子进程启动失败（已完成短间隔重试）；'
+                          if is_driver_launch_failure(stderr) else 'Native compilation failed: ')
+                raise NativeCommandError(prefix + reason, command, exit_code=result.returncode,
+                    stdout=result.stdout, stderr=stderr, error_type='EmptyCompilerOutput' if empty else 'CalledProcessError',
+                    attempts=attempt+1)
+        delay = LAUNCH_RETRY_DELAYS[attempt]
+        log.append(f'Compiler launch retry {attempt+1}/{len(LAUNCH_RETRY_DELAYS)} after {delay:g}s: {reason}')
+        LOGGER.warning('Compiler process launch failed; retry %d/%d in %.2fs: %s',
+                       attempt+1, len(LAUNCH_RETRY_DELAYS), delay, reason.strip())
+        time.sleep(delay)
+    raise AssertionError('Unreachable compiler retry state')
+
+
+def toolchain() -> tuple[str, Path, str]:
+    if os.name != "nt" and not sys.platform.startswith("linux"):
+        raise RuntimeError("Native builds support Windows and Linux; this platform is not supported.")
+    compiler = os.environ.get("SIMULATION_NATIVE_CC") or shutil.which("gcc")
+    if not compiler:
+        raise RuntimeError("C compiler not found; set SIMULATION_NATIVE_CC to gcc.")
+    configured = os.environ.get("SUNDIALS_ROOT")
+    candidates = ([Path(configured)] if configured else
+                  [Path(sys.base_prefix) / "Library"] if os.name == "nt" else
+                  [Path(sys.prefix) / "native/sundials-7.4.0", Path("/usr/local"), Path("/usr")])
+    base = next((path for path in candidates if (path / "include/cvode/cvode.h").is_file()), candidates[0])
+    if not (base / "include/cvode/cvode.h").is_file():
+        raise RuntimeError("SUNDIALS C development files not found; set SUNDIALS_ROOT.")
+    if os.name == 'nt':
+        compiler = str(Path(shutil.which(compiler) or compiler).resolve())
+    version = _command([compiler, '--version'], log=[], timeout=15, require_stdout=True).decode('utf-8', errors='replace').strip().splitlines()[0]
+    return compiler, base, version
+
+
+def platform_build_inputs(sundials: Path) -> tuple[list[str], list[Path], list[Path], str]:
+    """Share production flags and dependencies with the startup smoke check."""
+    flags = list(COMPILER_FLAGS)
+    executable_name = "model.exe" if os.name == "nt" else "model"
+    if os.name == "nt":
+        flags += ["-D__USE_MINGW_ANSI_STDIO=1", "-static-libgcc"]
+        libraries = [sundials / "lib" / f"sundials_{name}.lib" for name in LIBRARIES]
+        dlls = [sundials / "bin" / f"sundials_{name}.dll" for name in LIBRARIES]
+        if (sundials / "bin/vcruntime140.dll").is_file():
+            dlls.append(sundials / "bin/vcruntime140.dll")
+    else:
+        flags += ["-D_POSIX_C_SOURCE=200809L"]
+        candidates = [sundials / "lib", sundials / "lib64", sundials / "lib/x86_64-linux-gnu"]
+        directory = next((p for p in candidates if all((p / f"libsundials_{name}.a").is_file() for name in LIBRARIES)), None)
+        if directory is None:
+            raise RuntimeError("SUNDIALS static libraries not found; set SUNDIALS_ROOT.")
+        libraries = [directory / f"libsundials_{name}.a" for name in LIBRARIES]
+        dlls = []
+    return flags, libraries, dlls, executable_name
+
+
+def link_library_arguments(libraries: list[Path]) -> list[str]:
+    arguments = list(map(str, libraries))
+    if sys.platform.startswith("linux"):
+        arguments = ["-Wl,--start-group", *arguments, "-Wl,--end-group"]
+    return arguments
+
+
+def build_native(program: NativeProgram, *, cache_dir: Path | None = None,
+                 progress_callback: Callable[[str], None] | None = None) -> NativeBuild:
+    started = time.perf_counter()
+    if progress_callback:
+        progress_callback("native-cache-check")
+    compiler, sundials, compiler_version = toolchain()
+    flags, libraries, dlls, executable_name = platform_build_inputs(sundials)
+    cache = (cache_dir or CACHE).resolve()
+    cache.mkdir(parents=True, exist_ok=True)
+    for kind in ("models", "objects"):
+        path = cache / kind
+        if path.is_symlink():
+            raise RuntimeError(f"Native cache directory must not be a symbolic link: {path}")
+        path.mkdir(exist_ok=True)
+    _budget("SIMULATION_NATIVE_MODEL_CACHE_MB", 256)
+    _budget("SIMULATION_NATIVE_OBJECT_CACHE_MB", 128)
+    work_key = sha256(os.urandom(32)).hexdigest()
+    work_lease = acquire_cache_lease(cache, "models", work_key)
+    try:
+        stage = Path(tempfile.mkdtemp(prefix=f"building-{work_key}-", dir=cache))
+    except BaseException:
+        work_lease.close()
+        raise
+    logs: list[str] = []
+    model_lease = None
+    try:
+        (stage / "model.c").write_text(program.source, encoding="utf-8", newline="\n")
+        (stage / "model.h").write_text(program.header, encoding="utf-8", newline="\n")
+        compiler_path = Path(shutil.which(compiler) or compiler).resolve()
+        compiler_identity = {"version": compiler_version, "binarySha256": _hash(compiler_path),
+                             "target": _command([compiler, "-dumpmachine"], log=logs, require_stdout=True).decode().strip(),
+                             "flags": flags, "platform": sys.platform}
+        runtime = _runtime_sources(program)
+        sources = [stage / "model.c", *runtime]
+        native_headers = {p: _hash(p) for p in (NATIVE / "include").rglob("*.h")}
+        dependency_headers = {p: _hash(p) for directory in ("sundials", "cvode", "nvector", "sunmatrix", "sunlinsol")
+                              for p in (sundials / "include" / directory).glob("*.h")}
+        preprocessing_start = time.perf_counter()
+        # Preprocessed bytes include the actual transitive headers and all
+        # effective macros/ABI switches. Compile precisely these bytes, so a
+        # header edit cannot race the cache identity and the compiler input.
+        def preprocess(source: Path) -> dict:
+            local_log: list[str] = []
+            source_hash = _hash(source)
+            data = _command([compiler, *flags, "-E", "-P", f"-fmacro-prefix-map={stage}=/generated",
+                             "-I", str(stage), "-I", str(NATIVE / "include"), "-I", str(sundials / "include"),
+                             str(source)], log=local_log)
+            name = "model.c" if source == stage / "model.c" else "native/" + source.relative_to(NATIVE).as_posix()
+            if _hash(source) != source_hash:
+                raise RuntimeError(f"Native source changed during preprocessing: {source}")
+            digest = sha256(data).hexdigest()
+            identity = {"cacheVersion": 1, "sourceName": name, "preprocessedSha256": digest, "compiler": compiler_identity}
+            return {"sourceName": name, "sourceSha256": source_hash, "data": data,
+                    "objectKey": _key(identity), "identity": identity, "log": local_log}
+        with ThreadPoolExecutor(max_workers=min(4, len(sources))) as pool:
+            units = list(pool.map(preprocess, sources))
+        for unit in units:
+            logs.extend(unit.pop("log"))
+        preprocessing_seconds = time.perf_counter() - preprocessing_start
+        if any(_hash(path) != digest for path, digest in {**native_headers, **dependency_headers}.items()):
+            raise RuntimeError("Native headers changed during preprocessing; retry with stable sources.")
+        dependencies = {p.name: _hash(p) for p in libraries + dlls}
+        notice = (NATIVE / "THIRD_PARTY_NOTICES.txt").read_bytes()
+        identity = {"cacheVersion": 2, "sourceSha256": sha256(program.source.encode()).hexdigest(),
+                    "headerSha256": sha256(program.header.encode()).hexdigest(),
+                    "contractSha256": _key(program.manifest()), "contractKeys": sorted(program.manifest()),
+                    "objectKeys": [unit["objectKey"] for unit in units],
+                    "compiler": compiler_identity, "dependencies": dependencies, "notice": sha256(notice).hexdigest()}
+        signature = _key(identity)
+        target = cache / "models" / signature
+        required = {"model.c", "model.h", executable_name, "THIRD_PARTY_NOTICES.txt", *(p.name for p in dlls)}
+        model_lease = acquire_cache_lease(cache, "models", signature)
+        manifest = _checked_manifest(target, "buildKey", signature, 2, required)
+        details = {"selectedModules": list(component_modules(program.source + "\n" + program.header)),
+                   "unitCount": len(units), "objectCacheHits": 0, "objectCompilations": 0,
+                   "preprocessSeconds": preprocessing_seconds, "compileSeconds": 0.0,
+                   "compileWallSeconds": 0.0, "linkSeconds": 0.0, "modelCacheHit": manifest is not None}
+        details['compilerLaunchRetries'] = sum(line.startswith('Compiler launch retry ') for line in logs)
+        if manifest is not None:
+            if progress_callback:
+                progress_callback("native-cache-hit")
+            touch_cache_entry(cache, "models", signature)
+            details["pruning"] = _prune(cache)
+            result = NativeBuild(target / executable_name, manifest, True, time.perf_counter() - started,
+                                 details, model_lease, cache)
+            model_lease = None
+            return result
+        if progress_callback:
+            progress_callback("native-compilation")
+        compile_start = time.perf_counter()
+        def compile_unit(index_unit: tuple[int, dict]) -> dict:
+            index, unit = index_unit
+            key = unit["objectKey"]
+            destination = cache / "objects" / key
+            with acquire_cache_lease(cache, "objects", key):
+                object_manifest = _checked_manifest(destination, "objectKey", key, 1, {"unit.o"})
+                hit = object_manifest is not None
+                elapsed = 0.0
+                local_log: list[str] = []
+                if not hit:
+                    temporary = Path(tempfile.mkdtemp(prefix=f"building-{key}-", dir=cache / "objects"))
+                    try:
+                        (temporary / "unit.i").write_bytes(unit["data"])
+                        before = time.perf_counter()
+                        _command([compiler, *flags, "-x", "cpp-output", "-c", str(temporary / "unit.i"),
+                                  "-o", str(temporary / "unit.o")], log=local_log)
+                        elapsed = time.perf_counter() - before
+                        (temporary / "unit.i").unlink()
+                        object_manifest = {**unit["identity"], "objectKey": key, "artifacts": {"unit.o": _hash(temporary / "unit.o")}}
+                        (temporary / "manifest.json").write_text(json.dumps(object_manifest, indent=2) + "\n")
+                        _publish(temporary, destination, "objectKey", key, 1, {"unit.o"})
+                    finally:
+                        if temporary.exists():
+                            shutil.rmtree(temporary)
+                # Linking uses private copies, so another model's LRU pass can
+                # safely reclaim the shared object after this lease is released.
+                local_object = stage / f"object-{index}.o"
+                shutil.copyfile(destination / "unit.o", local_object)
+                touch_cache_entry(cache, "objects", key)
+                return {"path": local_object, "hit": hit, "seconds": elapsed, "log": local_log}
+        with ThreadPoolExecutor(max_workers=min(4, len(units))) as pool:
+            objects = list(pool.map(compile_unit, enumerate(units)))
+        details["compileWallSeconds"] = time.perf_counter() - compile_start
+        details["compileSeconds"] = sum(item["seconds"] for item in objects)
+        details["objectCacheHits"] = sum(item["hit"] for item in objects)
+        details["objectCompilations"] = len(objects) - details["objectCacheHits"]
+        for item in objects:
+            logs.extend(item["log"])
+        link_libraries = link_library_arguments(libraries)
+        if progress_callback:
+            progress_callback("native-linking")
+        before_link = time.perf_counter()
+        _command([compiler, *flags, *[str(item["path"]) for item in objects], *link_libraries,
+                  "-lm", "-o", str(stage / executable_name)], log=logs)
+        details['compilerLaunchRetries'] = sum(line.startswith('Compiler launch retry ') for line in logs)
+        details["linkSeconds"] = time.perf_counter() - before_link
+        if {p.name: _hash(p) for p in libraries + dlls} != dependencies:
+            raise RuntimeError("Native dependencies changed during linking; retry with a stable toolchain.")
+        for item in objects:
+            item["path"].unlink()
+        for library in dlls:
+            shutil.copyfile(library, stage / library.name)
+            if _hash(stage / library.name) != dependencies[library.name]:
+                raise RuntimeError("Native runtime dependency changed during copying; retry with a stable toolchain.")
+        (stage / "THIRD_PARTY_NOTICES.txt").write_bytes(notice)
+        (stage / "build.log").write_text("\n".join(logs), encoding="utf-8")
+        manifest = {**program.manifest(), "cacheVersion": 2, "buildKey": signature, "buildIdentity": identity,
+                    "compiler": compiler_version, "compilerFlags": flags,
+                    "sourceHashes": {unit["sourceName"]: unit["sourceSha256"] for unit in units},
+                    "nativeHeaderHashes": {"native/" + p.relative_to(NATIVE).as_posix(): digest
+                                           for p, digest in native_headers.items()},
+                    "dependencyHashes": dependencies, "selectedModules": details["selectedModules"],
+                    "objectKeys": [unit["objectKey"] for unit in units],
+                    "artifacts": {name: _hash(stage / name) for name in sorted(required)}}
+        (stage / "manifest.json").write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        manifest = _publish(stage, target, "buildKey", signature, 2, required)
+        touch_cache_entry(cache, "models", signature)
+        details["pruning"] = _prune(cache)
+        result = NativeBuild(target / executable_name, manifest, False, time.perf_counter() - started,
+                             details, model_lease, cache)
+        model_lease = None
+        return result
+    finally:
+        if model_lease is not None:
+            model_lease.close()
+        # Failed compilations never publish partial entries or retain unlimited
+        # model sources/preprocessed files. Error stderr is included in the exception.
+        try:
+            if stage.exists():
+                shutil.rmtree(stage)
+        finally:
+            work_lease.close()

app/simulation/native_codegen/cache_storage.py

@@ -0,0 +1,459 @@
+"""Leases and bounded LRU eviction for immutable native cache entries.
+
+Builds publish and validate their own artifacts. Readers hold a shared lease
+before checking an entry and until they finish using it. Eviction only removes
+an entry while holding the corresponding nonblocking exclusive lease.
+"""
+from __future__ import annotations
+
+from contextlib import suppress
+from dataclasses import dataclass
+import errno
+import os
+from pathlib import Path
+import re
+import shutil
+import stat
+import weakref
+
+
+MODEL_LIMIT_BYTES = 256 * 1024**2
+OBJECT_LIMIT_BYTES = 128 * 1024**2
+LOCK_SHARDS = 128
+_KINDS = frozenset(("models", "objects"))
+_KEY = re.compile(r"[0-9a-f]{64}\Z")
+# tempfile.mkdtemp uses eight lowercase letters, digits or underscores. Older
+# stages lacking a lease key are deliberately outside automatic cleanup.
+_STAGE = re.compile(r"building-([0-9a-f]{64})-[a-z0-9_]{8}\Z")
+
+if os.name == "nt":
+    import ctypes
+    from ctypes import wintypes
+    import msvcrt
+
+    class _Offset(ctypes.Structure):
+        _fields_ = [("Offset", wintypes.DWORD), ("OffsetHigh", wintypes.DWORD)]
+
+    class _OffsetUnion(ctypes.Union):
+        _fields_ = [("offset", _Offset), ("Pointer", ctypes.c_void_p)]
+
+    class _Overlapped(ctypes.Structure):
+        _fields_ = [
+            ("Internal", ctypes.c_size_t), ("InternalHigh", ctypes.c_size_t),
+            ("offset", _OffsetUnion), ("hEvent", wintypes.HANDLE),
+        ]
+
+    _kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    _lock_file = _kernel32.LockFileEx
+    _lock_file.argtypes = [
+        wintypes.HANDLE, wintypes.DWORD, wintypes.DWORD,
+        wintypes.DWORD, wintypes.DWORD, ctypes.POINTER(_Overlapped),
+    ]
+    _lock_file.restype = wintypes.BOOL
+    _unlock_file = _kernel32.UnlockFileEx
+    _unlock_file.argtypes = [
+        wintypes.HANDLE, wintypes.DWORD, wintypes.DWORD,
+        wintypes.DWORD, ctypes.POINTER(_Overlapped),
+    ]
+    _unlock_file.restype = wintypes.BOOL
+else:
+    import fcntl
+
+
+def _validate(kind: str, key: str) -> None:
+    if kind not in _KINDS or not isinstance(key, str) or _KEY.fullmatch(key) is None:
+        raise ValueError("Native cache leases require models/objects and a lowercase SHA-256 key.")
+
+
+def _reparse(info: os.stat_result) -> bool:
+    # Junctions as well as symbolic links are excluded on Windows.
+    return stat.S_ISLNK(info.st_mode) or bool(
+        getattr(info, "st_file_attributes", 0)
+        & getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
+    )
+
+
+def _directory(path: Path) -> os.stat_result | None:
+    try:
+        info = path.lstat()
+    except FileNotFoundError:
+        return None
+    if _reparse(info) or not stat.S_ISDIR(info.st_mode):
+        return None
+    return info
+
+
+def _require_directory(path: Path, *, create: bool = False) -> None:
+    if create:
+        path.mkdir(parents=True, exist_ok=True)
+    if _directory(path) is None:
+        raise RuntimeError(f"Native cache directory must be a real directory: {path}")
+
+
+def _lock(fd: int, *, exclusive: bool, blocking: bool) -> bool:
+    if os.name == "nt":
+        # os.open supplies a synchronous handle. LockFileEx therefore really
+        # waits without FAIL_IMMEDIATELY; unlike msvcrt.locking it also supports
+        # overlapping shared leases, including multiple builds in one process.
+        # The one-byte lock may extend beyond EOF, so lock files remain empty.
+        overlapped = _Overlapped()
+        flags = (2 if exclusive else 0) | (0 if blocking else 1)
+        if _lock_file(msvcrt.get_osfhandle(fd), flags, 0, 1, 0, ctypes.byref(overlapped)):
+            return True
+        code = ctypes.get_last_error()
+        if not blocking and code == 33:  # ERROR_LOCK_VIOLATION
+            return False
+        raise ctypes.WinError(code)
+    operation = fcntl.LOCK_EX if exclusive else fcntl.LOCK_SH
+    if not blocking:
+        operation |= fcntl.LOCK_NB
+    while True:
+        try:
+            fcntl.flock(fd, operation)
+            return True
+        except InterruptedError:
+            continue
+        except OSError as exc:
+            if not blocking and exc.errno in (errno.EACCES, errno.EAGAIN):
+                return False
+            raise
+
+
+def _release(fd: int, owner_pid: int) -> None:
+    # A forked child's finalizer must not explicitly unlock its parent's flock.
+    # Closing the inherited descriptor alone leaves the parent's lease intact.
+    with suppress(OSError):
+        if os.getpid() == owner_pid:
+            if os.name == "nt":
+                overlapped = _Overlapped()
+                _unlock_file(msvcrt.get_osfhandle(fd), 0, 1, 0, ctypes.byref(overlapped))
+            else:
+                fcntl.flock(fd, fcntl.LOCK_UN)
+    with suppress(OSError):
+        os.close(fd)
+
+
+class CacheLease:
+    """An acquired cache-use lock; close explicitly or use as a context manager."""
+
+    __slots__ = ("path", "kind", "key", "exclusive", "_finalizer", "__weakref__")
+
+    def __init__(self, fd: int, path: Path, kind: str, key: str, exclusive: bool):
+        self.path = path
+        self.kind = kind
+        self.key = key
+        self.exclusive = exclusive
+        self._finalizer = weakref.finalize(self, _release, fd, os.getpid())
+
+    @property
+    def closed(self) -> bool:
+        return not self._finalizer.alive
+
+    def close(self) -> None:
+        self._finalizer()
+
+    def __enter__(self) -> CacheLease:
+        if self.closed:
+            raise RuntimeError("Cannot reuse a closed native cache lease.")
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+def acquire_cache_lease(
+    cache_dir: Path, kind: str, key: str, *, exclusive: bool = False,
+    blocking: bool = True,
+) -> CacheLease | None:
+    """Acquire a shared-use/exclusive-eviction lease; return None only if busy.
+
+    Locks use 128 stable shards per namespace, bounding metadata as model keys
+    accumulate. A collision can defer eviction but cannot admit unsafe deletion.
+    Lock files must never be unlinked while the application is running: waiters
+    may already hold the old inode. There are at most 256 empty lock files.
+    """
+    _validate(kind, key)
+    shard = int(key[:8], 16) % LOCK_SHARDS
+    return _acquire_lock_file(
+        Path(cache_dir).absolute(), kind, key, f"{kind}-{shard:03d}.lock",
+        exclusive=exclusive, blocking=blocking,
+    )
+
+
+def _acquire_lock_file(
+    cache: Path, kind: str, key: str, lock_name: str, *, exclusive: bool,
+    blocking: bool,
+) -> CacheLease | None:
+    _require_directory(cache, create=True)
+    lock_dir = cache / ".locks"
+    _require_directory(lock_dir, create=True)
+    lock_path = lock_dir / lock_name
+    try:
+        info = lock_path.lstat()
+    except FileNotFoundError:
+        info = None
+    if info is not None and (_reparse(info) or not stat.S_ISREG(info.st_mode)):
+        raise RuntimeError(f"Native cache lock must be a regular file: {lock_path}")
+    flags = os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_BINARY", 0)
+    fd = os.open(lock_path, flags, 0o600)
+    try:
+        if not stat.S_ISREG(os.fstat(fd).st_mode):
+            raise RuntimeError(f"Native cache lock must be a regular file: {lock_path}")
+        os.set_inheritable(fd, False)
+        if not _lock(fd, exclusive=exclusive, blocking=blocking):
+            os.close(fd)
+            return None
+        return CacheLease(fd, cache / kind / key, kind, key, exclusive)
+    except BaseException:
+        os.close(fd)
+        raise
+
+
+def touch_cache_entry(cache_dir: Path, kind: str, key: str) -> None:
+    """Mark an immutable entry as recently used while its caller holds a lease."""
+    _validate(kind, key)
+    cache = Path(cache_dir).absolute()
+    _require_directory(cache)
+    _require_directory(cache / kind)
+    entry = cache / kind / key
+    _require_directory(entry)
+    # Directory mtime is separate from the checksummed artifact/manifest bytes.
+    # Windows Python may expose utime without the no-follow operation. The
+    # checks above reject symlinks and reparse points before either call, and
+    # the caller's use lease protects the entry from application eviction.
+    if os.utime in os.supports_follow_symlinks:
+        os.utime(entry, None, follow_symlinks=False)
+    else:
+        os.utime(entry, None)
+
+
+@dataclass(frozen=True)
+class _Entry:
+    path: Path
+    size: int
+    mtime_ns: int
+    device: int
+    inode: int
+
+
+def _tree_size(path: Path) -> int | None:
+    """Count regular file bytes without reading files or following any links."""
+    size = 0
+    try:
+        with os.scandir(path) as children:
+            for child in children:
+                info = child.stat(follow_symlinks=False)
+                if _reparse(info):
+                    return None
+                if stat.S_ISREG(info.st_mode):
+                    size += info.st_size
+                elif stat.S_ISDIR(info.st_mode):
+                    nested = _tree_size(Path(child.path))
+                    if nested is None:
+                        return None
+                    size += nested
+                else:
+                    return None
+    except FileNotFoundError:
+        return None  # A concurrent sweep may already have removed this entry.
+    return size
+
+
+def _scan(namespace: Path) -> tuple[list[_Entry], int]:
+    entries = []
+    skipped = 0
+    if _directory(namespace) is None:
+        try:
+            namespace.lstat()
+        except FileNotFoundError:
+            return entries, 0
+        return entries, 1
+    with os.scandir(namespace) as children:
+        for child in children:
+            if _KEY.fullmatch(child.name) is None:
+                skipped += 1
+                continue
+            path = Path(child.path)
+            info = _directory(path)
+            if info is None:
+                skipped += 1
+                continue
+            size = _tree_size(path)
+            if size is None:
+                skipped += 1
+                continue
+            entries.append(_Entry(path, size, info.st_mtime_ns, info.st_dev, info.st_ino))
+    return entries, skipped
+
+
+def _empty_report(limit: int) -> dict:
+    return {
+        "limitBytes": limit, "beforeBytes": 0, "afterBytes": 0,
+        "removedBytes": 0, "removedEntries": 0, "skippedInUse": 0,
+        "skippedChanged": 0, "skippedUnmanaged": 0, "oversizedEntries": 0,
+        "overLimitBytes": 0, "skippedConcurrentSweep": False, "errors": [],
+    }
+
+
+def _prune_kind(cache: Path, kind: str, limit: int) -> dict:
+    report = _empty_report(limit)
+    namespace = cache / kind
+    try:
+        entries, skipped = _scan(namespace)
+    except OSError as exc:
+        report["errors"].append(str(exc))
+        return report
+    report["skippedUnmanaged"] = skipped
+    remaining = report["beforeBytes"] = sum(entry.size for entry in entries)
+    remaining_count = len(entries)
+    for entry in sorted(entries, key=lambda item: (item.mtime_ns, item.path.name)):
+        if remaining <= limit:
+            break
+        # Keep the last entry if it alone exceeds the budget. Older oversized
+        # entries are still evictable, so they cannot accumulate unboundedly.
+        if remaining_count == 1 and entry.size > limit:
+            continue
+        try:
+            lease = acquire_cache_lease(cache, kind, entry.path.name, exclusive=True, blocking=False)
+            if lease is None:
+                report["skippedInUse"] += 1
+                continue
+            with lease:
+                info = _directory(entry.path)
+                if info is None:
+                    report["skippedChanged"] += 1
+                    continue
+                if (info.st_dev, info.st_ino, info.st_mtime_ns) != (
+                    entry.device, entry.inode, entry.mtime_ns,
+                ):
+                    # It was republished or reused after sorting; defer it to
+                    # the next sweep instead of evicting a freshly used build.
+                    report["skippedChanged"] += 1
+                    continue
+                size = _tree_size(entry.path)
+                if size is None:
+                    report["skippedUnmanaged"] += 1
+                    continue
+                shutil.rmtree(entry.path)
+                remaining -= entry.size
+                remaining_count -= 1
+                report["removedBytes"] += size
+                report["removedEntries"] += 1
+        except (OSError, RuntimeError) as exc:
+            # Cleanup is best effort. A locked executable, permissions or a
+            # damaged unrelated cache entry must not fail a valid simulation.
+            report["errors"].append(str(exc))
+    try:
+        current, _ = _scan(namespace)
+        report["afterBytes"] = sum(entry.size for entry in current)
+        report["oversizedEntries"] = sum(entry.size > limit for entry in current)
+    except OSError as exc:
+        report["errors"].append(str(exc))
+        report["afterBytes"] = remaining
+    report["overLimitBytes"] = max(0, report["afterBytes"] - limit)
+    return report
+
+
+
+def _empty_orphan_report() -> dict:
+    return {
+        "orphanStagesRemoved": 0, "orphanStagesBytes": 0,
+        "skippedInUse": 0, "skippedUnmanaged": 0,
+        "skippedConcurrentSweep": False, "errors": [],
+    }
+
+
+def _prune_orphan_stages(cache: Path) -> dict:
+    """Remove only named stages whose builder's lease is no longer held.
+
+    Callers acquire the embedded key's shared lease BEFORE creating the stage
+    and retain it until publication or cleanup. The OS releases that protection
+    if the builder is killed; no age threshold or unreliable PID test is needed.
+    Root/models stages use models leases; objects stages use objects leases.
+    """
+    report = _empty_orphan_report()
+    for namespace, kind in ((cache, "models"), (cache / "models", "models"),
+                            (cache / "objects", "objects")):
+        try:
+            if _directory(namespace) is None:
+                continue
+            with os.scandir(namespace) as children:
+                candidates = []
+                for child in children:
+                    match = _STAGE.fullmatch(child.name)
+                    if match is not None:
+                        candidates.append((Path(child.path), match.group(1)))
+                    elif child.name.startswith("building-"):
+                        report["skippedUnmanaged"] += 1
+        except OSError as exc:
+            report["errors"].append(f"{namespace}: {exc}")
+            continue
+        for stage, key in candidates:
+            try:
+                lease = acquire_cache_lease(cache, kind, key, exclusive=True, blocking=False)
+                if lease is None:
+                    report["skippedInUse"] += 1
+                    continue
+                with lease:
+                    if _directory(stage) is None:
+                        report["skippedUnmanaged"] += 1
+                        continue
+                    size = _tree_size(stage)
+                    if size is None:
+                        report["skippedUnmanaged"] += 1
+                        continue
+                    shutil.rmtree(stage)
+                    report["orphanStagesRemoved"] += 1
+                    report["orphanStagesBytes"] += size
+            except (OSError, RuntimeError) as exc:
+                report["errors"].append(f"{stage}: {exc}")
+    return report
+
+
+def prune_cache(
+    cache_dir: Path, *, model_limit_bytes: int = MODEL_LIMIT_BYTES,
+    object_limit_bytes: int = OBJECT_LIMIT_BYTES,
+) -> dict:
+    """Apply separate soft LRU byte budgets to managed models and objects.
+
+    In-use entries (including conservative shard collisions), the final entry
+    when it alone exceeds the budget, unknown names, links and legacy root-level
+    builds are retained. Returned counts explain any remaining overage. The
+    cache may transiently exceed its budgets while builds or solvers are active.
+    Strictly named stages abandoned by killed builders are removed under their
+    matching lease and counted separately in the orphanStages report.
+    """
+    for limit in (model_limit_bytes, object_limit_bytes):
+        if isinstance(limit, bool) or not isinstance(limit, int) or limit < 0:
+            raise ValueError("Native cache byte limits must be nonnegative integers.")
+    cache = Path(cache_dir).absolute()
+    empty = {
+        "models": _empty_report(model_limit_bytes),
+        "objects": _empty_report(object_limit_bytes),
+        "orphanStages": _empty_orphan_report(),
+    }
+    try:
+        if _directory(cache) is None:
+            # Do not create a missing cache or inspect an alias to a directory.
+            return empty
+        # One additional stable lock file (257 total) serializes sweep decisions
+        # without serializing readers/builds. Otherwise simultaneous sweeps can
+        # each remove a different entry and incorrectly discard the final one.
+        sweep = _acquire_lock_file(
+            cache, "models", "0" * 64, "prune.lock", exclusive=True, blocking=False,
+        )
+        if sweep is None:
+            for report in empty.values():
+                report["skippedConcurrentSweep"] = True
+            return empty
+        with sweep:
+            orphan_stages = _prune_orphan_stages(cache)
+            return {
+                "models": _prune_kind(cache, "models", model_limit_bytes),
+                "objects": _prune_kind(cache, "objects", object_limit_bytes),
+                "orphanStages": orphan_stages,
+            }
+    except (OSError, RuntimeError) as exc:
+        for report in empty.values():
+            report["errors"].append(str(exc))
+        return empty

app/simulation/native_codegen/compiler.py

@@ -0,0 +1,427 @@
+"""Lower reviewed component contracts to a static C evaluation schedule.
+
+The compact storage-anchored schedule and the extended catalog schedule both
+produce standalone C numerics, without Python callbacks or numerical fallback.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from math import isfinite
+
+from app.simulation.core.metadata import ResultVariableMetadata
+from app.simulation.systems.network import SimulationNetwork
+from .contracts import SUPPORTED_TYPES, SUPPORTED_VERSIONS
+from .tolerances import state_absolute_tolerance
+from .jacobian import JacobianStructure
+
+
+class NativeCapabilityError(ValueError):
+    """The complete model cannot be represented by this native backend."""
+
+
+_STORAGE_ANCHORED_TYPES = frozenset(
+    "amesim_" + name for name in (
+        "pnch023", "pnch012", "pnvo001", "pnpl01", "step0", "ud00",
+        "forc", "pnrp17", "mecmas21", "f000", "lstp00a",
+    )
+)
+
+
+@dataclass(frozen=True)
+class NativeProgram:
+    source: str
+    header: str
+    state_keys: tuple[str, ...]
+    variables: tuple[ResultVariableMetadata, ...]
+    component_types: tuple[str, ...]
+    evaluation_schedule: dict | None = None
+    jacobian_structure: dict | None = None
+
+    def manifest(self) -> dict:
+        return {
+            "abiVersion": 1, "stateKeys": self.state_keys,
+            "variables": [v.as_dict() for v in self.variables],
+            "componentTypes": self.component_types,
+            "componentVersions": {name: SUPPORTED_VERSIONS[name] for name in self.component_types},
+            "jacobianPolicy": (self.jacobian_structure or {}).get("policy", "CVODE default; no custom Jacobian"),
+            "jacobianStructure": self.jacobian_structure,
+            "evaluationSchedule": self.evaluation_schedule or {"strategy": "storage-anchored", "cyclicBlockCount": 0},
+        }
+
+
+class _Groups:
+    def __init__(self, items):
+        self.parent = {x: x for x in items}
+
+    def find(self, x):
+        if self.parent[x] != x:
+            self.parent[x] = self.find(self.parent[x])
+        return self.parent[x]
+
+    def union(self, a, b):
+        self.parent[self.find(b)] = self.find(a)
+
+
+def _number(value):
+    value = float(value)
+    if not isfinite(value):
+        raise NativeCapabilityError("Native constants must be finite.")
+    return repr(value)
+
+
+def compile_native_program(network: SimulationNetwork) -> NativeProgram:
+    network.validate_port_supplies()
+    from .extended import catalog_contracts
+    contracts = catalog_contracts()
+    from app.simulation.components.amesim.semantics import validate_numerical_semantics
+    for component in network.components.values():
+        if type(component) is not contracts.get(component.model_type):
+            raise NativeCapabilityError(f'{component.name}: no native contract for {component.model_type}')
+        if component.MODEL_VERSION != SUPPORTED_VERSIONS.get(component.model_type):
+            raise NativeCapabilityError(f'{component.name}: native kernel version does not match the component contract')
+        try:
+            validate_numerical_semantics(component)
+        except ValueError as exc:
+            raise NativeCapabilityError(str(exc)) from exc
+    # Preserve the compact, verified schedule for its supported topology.
+    # Both paths emit C; this never falls back to Python numerical execution.
+    try:
+        return _compile_storage_anchored_program(network)
+    except NativeCapabilityError:
+        from .extended import compile_extended_program
+        return compile_extended_program(network)
+
+
+def _compile_storage_anchored_program(network: SimulationNetwork) -> NativeProgram:
+    components = list(network.components.values())
+    if not components:
+        raise NativeCapabilityError("Native simulation requires a dynamic model.")
+    for c in components:
+        if c.model_type not in _STORAGE_ANCHORED_TYPES:
+            raise NativeCapabilityError(f"{c.name}: unsupported native component {c.model_type}.")
+        if c.MODEL_VERSION != SUPPORTED_VERSIONS[c.model_type]:
+            raise NativeCapabilityError(f"{c.name}: native kernel version does not match the component contract.")
+        if c.model_type == "amesim_pnch023" and c.kth*c.sth != 0:
+            raise NativeCapabilityError(f"{c.name}: native v1 supports adiabatic PNCH023 only.")
+        medium = getattr(c, "medium", None)
+        if medium is not None and (
+            getattr(medium, "SUBSTANCE_ID", None),
+            getattr(medium, "PROPERTY_METHOD_ID", None),
+        ) != ("helium", "peng_robinson"):
+            raise NativeCapabilityError(f"{c.name}: native v1 requires helium / Peng-Robinson.")
+        if c.model_type == "amesim_mecmas21":
+            if int(c.stoptype) not in (1, 4) or any(
+                getattr(c, key) != 0 for key in ("fcoul", "fstick", "rvisc", "wind", "theta")
+            ):
+                raise NativeCapabilityError(f"{c.name}: native v1 supports friction-free masses with stoptype 1 or 4.")
+        if c.model_type == "amesim_lstp00a" and int(c.stiffmode) != 1:
+            raise NativeCapabilityError(f"{c.name}: native v1 requires explicit contact stiffness.")
+    ports = {
+        (c.name, p.name): p for c in components for p in c.active_port_definitions
+    }
+    adjacent = {}
+    groups = _Groups(ports)
+    for edge in network.connections:
+        a, b = (p.key for p in edge.endpoints)
+        # Signal fan-out is allowed; physical ports have one external connection.
+        if edge.kind == "physical":
+            if a in adjacent or b in adjacent:
+                raise NativeCapabilityError("Native physical ports require one connection each.")
+            adjacent[a], adjacent[b] = b, a
+            groups.union(a, b)
+        else:
+            source, target = (a, b) if ports[a].nominal_role == "output" else (b, a)
+            adjacent[target] = source
+    for c in components:
+        for name in c.required_connection_ports:
+            if (c.name, name) not in adjacent:
+                raise NativeCapabilityError(f"{c.name}.{name}: unconnected physical port.")
+        names = [p.name for p in c.active_port_definitions if p.domain == "pneumatic"]
+        if c.model_type in ("amesim_pnch023", "amesim_pnch012"):
+            for name in names[1:]:
+                groups.union((c.name, names[0]), (c.name, name))
+        if c.model_type == "amesim_mecmas21":
+            groups.union((c.name, "port_1"), (c.name, "port_2"))
+        if c.model_type == "amesim_pnrp17":
+            groups.union((c.name, "port_2"), (c.name, "port_5"))
+            groups.union((c.name, "port_3"), (c.name, "port_4"))
+
+    chambers = [c for c in components if c.model_type in ("amesim_pnch023", "amesim_pnch012")]
+    masses = [c for c in components if c.model_type == "amesim_mecmas21"]
+    chamber_by_group, mass_by_group = {}, {}
+    for items, mapping in ((chambers, chamber_by_group), (masses, mass_by_group)):
+        for c in items:
+            root = groups.find((c.name, "port_1"))
+            if root in mapping:
+                raise NativeCapabilityError(f"{c.name}: coupled storage/mass reduction is outside native v1.")
+            mapping[root] = c
+    for ep, port in ports.items():
+        mapping = chamber_by_group if port.domain == "pneumatic" else mass_by_group
+        if port.kind == "physical" and groups.find(ep) not in mapping:
+            raise NativeCapabilityError(f"{ep}: no unique storage/mass anchor; native v1 cannot close this block.")
+
+    variables = tuple(v for c in components for v in c.result_variable_metadata())
+    slots = {v.key: i for i, v in enumerate(variables)}
+    assigned = set()
+    lines, init, declarations = [], [], []
+    state_keys, state_index = [], {}
+    for c in components:
+        fields = ("m", "U") if c in chambers else (("v", "x") if c in masses else ())
+        if c.model_type == "amesim_pnch012" and sum(c.external_volume_rates.values()) != 0:
+            fields += ("_volume_displacement",)
+        for field in fields:
+            key = f"{c.name}.{field}"
+            state_index[key] = len(state_keys)
+            state_keys.append(key)
+    if not state_keys:
+        raise NativeCapabilityError("Native v1 requires continuous states.")
+    if len(state_keys) > 256 or len(variables) > 8192:
+        raise NativeCapabilityError("Native v1 supports at most 256 states and 8192 outputs per model.")
+
+    def w(key):
+        return f"w[{slots[key]}]"
+
+    def key(c, field):
+        return f"{c.name}.{field}"
+
+    def get(c, field):
+        return w(key(c, field))
+
+    def put(c, field, expression):
+        k = key(c, field)
+        lines.append(f"{w(k)} = {expression};")
+        assigned.add(k)
+
+    def si(c, field):
+        return state_index[key(c, field)]
+
+    def mass_at(c, port):
+        return mass_by_group[groups.find((c.name, port))]
+
+    def chamber_at(c, port):
+        return chamber_by_group[groups.find((c.name, port))]
+
+    for c in masses:
+        init.extend([f"y[{si(c, 'v')}] = {_number(c.v0)};", f"y[{si(c, 'x')}] = {_number(c.x0)};"])
+        for field in ("v", "x"):
+            put(c, field, f"y[{si(c, field)}]")
+    for (cid, pname), port in ports.items():
+        if port.domain == "mechanical":
+            m = mass_by_group[groups.find((cid, pname))]
+            for field in ("v", "x"):
+                k = f"{cid}.{pname}.{field}"
+                lines.append(f"{w(k)} = y[{si(m, field)}];")
+                assigned.add(k)
+
+    signal_specs = []
+    for c in components:
+        if c.model_type == "amesim_step0":
+            put(c, "y", f"t < {_number(c.time)} ? {_number(c.initial)} : {_number(c.final)}")
+            signal_specs.append(("step", c))
+        elif c.model_type == "amesim_ud00":
+            index = len(signal_specs)
+            declarations.append(f"static const double signal_{index}[24] = {{" + ",".join(
+                _number(v) for values in (c.starts, c.ends, c.durations) for v in values
+            ) + "};")
+            put(c, "y", f"native_signal(t, {_number(c.tstart)}, {c.nstages}, {int(c.iscyclic)}, signal_{index})")
+            signal_specs.append((index, c))
+        else:
+            continue
+        put(c, "out.signal", get(c, "y"))
+    for c in components:
+        for port in c.active_port_definitions:
+            if port.kind == "signal" and port.nominal_role == "input":
+                ep = (c.name, port.name)
+                if ep not in adjacent:
+                    # PNVO's explicit unconnected opening is a supported default.
+                    if c.model_type == "amesim_pnvo001":
+                        put(c, port.name + ".signal", _number(c.opening0))
+                        continue
+                    raise NativeCapabilityError(f"{ep}: missing signal input.")
+                source = adjacent[ep]
+                source_key = f"{source[0]}.{source[1]}.signal"
+                if source_key not in assigned:
+                    raise NativeCapabilityError(f"{ep}: unsupported signal dependency.")
+                put(c, port.name + ".signal", w(source_key))
+
+    pistons = [c for c in components if c.model_type == "amesim_pnrp17"]
+    for c in pistons:
+        put(c, "length", f"{_number(c.x0)} + {get(c, 'port_5.x')} - {get(c, 'port_4.x')}")
+        put(c, "volume", f"{_number(c.effective_area)} * {get(c, 'length')}")
+        put(c, "volume_flow", f"{_number(c.effective_area)} * ({get(c, 'port_5.v')} - {get(c, 'port_4.v')})")
+        if chamber_at(c, "port_1").model_type != "amesim_pnch012":
+            raise NativeCapabilityError(f"{c.name}: moving volume requires PNCH012.")
+    volume_expressions = {}
+    for gi, c in enumerate(chambers):
+        connected = [p for p in pistons if chamber_at(p, "port_1") is c]
+        base = c.cvol if c.model_type == "amesim_pnch023" else c.cvol0 + sum(c.external_volumes.values())
+        volume = _number(base)
+        rate = "0.0"
+        if c.model_type == "amesim_pnch012":
+            volume += "".join(" + " + get(p, "volume") for p in connected)
+            if key(c, '_volume_displacement') in state_index:
+                index = si(c, '_volume_displacement')
+                init.append(f"y[{index}] = 0.0;")
+                lines.append(f"dy[{index}] = {_number(sum(c.external_volume_rates.values()))};")
+                volume += f" + y[{index}]"
+            put(c, "vol", f"fmax({_number(c.cvol0 / 100)}, {volume})")
+            rate = _number(sum(c.external_volume_rates.values())) + "".join(" + " + get(p, "volume_flow") for p in connected)
+            limit = _number(c.cvol0 / 100)
+            put(c, "dvol", f"({volume}) < {limit} || (({volume}) <= {limit} && ({rate}) < 0) ? 0.0 : ({rate})")
+            volume, rate = get(c, "vol"), get(c, "dvol")
+        volume_expressions[c.name] = (volume, rate)
+        # p0/T0 refer to the complete connected volume at the initial positions.
+        initial_volume = base
+        if c.model_type == "amesim_pnch012":
+            initial_volume += sum(p.effective_area * (p.x0 + mass_at(p, "port_5").x0 - mass_at(p, "port_4").x0) for p in connected)
+            initial_volume = max(initial_volume, c.cvol0 / 100)
+        init.append(f"if (!native_gas_init({_number(c.p0)}, {_number(c.T0)}, {_number(initial_volume)}, &y[{si(c, 'm')}])) return 0;")
+        lines.append(f"NativeGas gas_{gi};")
+        lines.append(f"if (!native_gas_context(properties, y[{si(c, 'm')}], y[{si(c, 'U')}], {volume}, &gas_{gi})) return 0;")
+        for field in ("m", "U"):
+            put(c, field, f"y[{si(c, field)}]")
+        for field in ("p", "T", "rho", "u", "h"):
+            put(c, field, f"gas_{gi}.{field}")
+    for (cid, pname), port in ports.items():
+        if port.domain == "pneumatic":
+            c = chamber_by_group[groups.find((cid, pname))]
+            for field, expr in (("p", get(c, "p")), ("h_outflow", get(c, "h")), ("m_flow", "0.0")):
+                k = f"{cid}.{pname}.{field}"
+                lines.append(f"{w(k)} = {expr};")
+                assigned.add(k)
+    for c in components:
+        if c.model_type != "amesim_pnvo001":
+            continue
+        a, b = chamber_at(c, "port_2"), chamber_at(c, "port_3")
+        put(c, "xv", f"fmax(0.0, fmin(1.0, {get(c, 'res.signal')}))")
+        lines.append(f"if (!native_orifice_context(properties, {get(a, 'p')}, {get(b, 'p')}, {get(a, 'h')}, {get(b, 'h')}, {_number(c.effective_cq * c.maximum_area)}, {get(c, 'xv')}, &{get(c, 'port_2.m_flow')}, &{get(c, 'cm')}, &{get(c, 'gasvel')})) return 0;")
+        assigned.update((key(c, "cm"), key(c, "gasvel")))
+        put(c, "port_3.m_flow", f"-{get(c, 'port_2.m_flow')}")
+        put(c, "port_2.h_outflow", get(b, "h"))
+        put(c, "port_3.h_outflow", get(a, "h"))
+        for pname in ("port_2", "port_3"):
+            other = adjacent[c.name, pname]
+            # Resistance-to-resistance streams need the extended pressure/enthalpy closure.
+            if network.components[other[0]] not in chambers:
+                raise NativeCapabilityError(f"{c.name}: native v1 requires valve ports directly connected to storage.")
+            lines.append(f"{w(f'{other[0]}.{other[1]}.m_flow')} = -{get(c, pname + '.m_flow')};")
+
+    force_known = set()
+    def force(c, port, expr):
+        put(c, port + ".f", expr)
+        force_known.add((c.name, port))
+    equations = []
+    for c in components:
+        if c.model_type == "amesim_forc":
+            put(c, "force", f"{_number(c.direction)} * {get(c, 'res.signal')}")
+            force(c, "port_2", f"-{get(c, 'force')}")
+        elif c.model_type == "amesim_f000":
+            force(c, "port_1", "0.0")
+        elif c.model_type == "amesim_lstp00a":
+            put(c, "gap", f"{_number(c.gap0)} + ({get(c, 'port_2.x')} - {get(c, 'port_1.x')})")
+            put(c, "penetration", f"fmax(-{get(c, 'gap')}, 0.0)")
+            put(c, "force", f"native_contact({get(c, 'penetration')}, {get(c, 'port_1.v')} - {get(c, 'port_2.v')}, {_number(c.kcont)}, {_number(c.rcont)}, {_number(c.Pdis)}, {int(c.discContactOption)})")
+            force(c, "port_1", get(c, "force"))
+            force(c, "port_2", f"-{get(c, 'force')}")
+        elif c.model_type == "amesim_pnrp17":
+            put(c, "pressure_force", f"({get(c, 'port_1.p')} - 101300.0) * {_number(c.effective_area)}")
+            equations.extend([
+                ((c.name, "port_2"), (c.name, "port_5"), f"-{get(c, 'pressure_force')}"),
+                ((c.name, "port_3"), (c.name, "port_4"), get(c, "pressure_force")),
+            ])
+    for edge in network.connections:
+        if edge.domain == "mechanical":
+            equations.append((*[p.key for p in edge.endpoints], "0.0"))
+    pending = equations
+    while pending:
+        remaining = []
+        for a, b, total in pending:
+            if a in force_known and b in force_known:
+                raise NativeCapabilityError("Overconstrained native force balance.")
+            if a not in force_known and b not in force_known:
+                remaining.append((a, b, total))
+                continue
+            target, source = (b, a) if a in force_known else (a, b)
+            c = network.components[target[0]]
+            force(c, target[1], f"({total}) - {w(f'{source[0]}.{source[1]}.f')}")
+        if len(remaining) == len(pending):
+            raise NativeCapabilityError("Native v1 cannot resolve this mechanical force loop.")
+        pending = remaining
+    for c in masses:
+        expression = f"({get(c, 'port_1.f')} + {get(c, 'port_2.f')}) / {_number(c.mass)}"
+        put(c, "a", expression)
+        lines.append(f"dy[{si(c, 'v')}] = {get(c, 'a')}; dy[{si(c, 'x')}] = {get(c, 'v')};")
+        if int(c.stoptype) == 1:
+            lines.append(f"native_stop_motion({get(c, 'x')}, {get(c, 'v')}, {_number(c.xmin)}, {_number(c.xmax)}, &dy[{si(c, 'v')}], &dy[{si(c, 'x')}]);")
+            put(c, "a", f"dy[{si(c, 'v')}]")
+        for field in ("Fvisc", "Ffric", "Fmin", "Fmax"):
+            put(c, field, "0.0")
+    for c in chambers:
+        mass_terms, energy_terms = [], []
+        for port in c.active_port_definitions:
+            q = get(c, port.name + ".m_flow")
+            other = adjacent[c.name, port.name]
+            inlet_h = w(f"{other[0]}.{other[1]}.h_outflow")
+            mass_terms.append(q)
+            energy_terms.append(f"{q} * ({q} > 0.0 ? {inlet_h} : {get(c, 'h')})")
+        volume, rate = volume_expressions[c.name]
+        energy_terms.extend([f"{_number(c.kth*c.sth)} * ({_number(c.extemp)} - {get(c, 'T')})", f"-{get(c, 'p')} * ({rate})"])
+        lines.extend([f"dy[{si(c, 'm')}] = " + " + ".join(mass_terms) + ";", f"dy[{si(c, 'U')}] = " + " + ".join(energy_terms) + ";"])
+    missing = set(slots) - assigned
+    if missing:
+        raise NativeCapabilityError(f"Native output coverage is incomplete: {sorted(missing)}")
+
+    stops = [(si(c, "v"), c.xmin, c.xmax) for c in masses if int(c.stoptype) == 1]
+    from .contacts import contact_table
+    contact_source, contact_header = contact_table([
+        (si(mass_at(c, 'port_1'), 'v'), si(mass_at(c, 'port_2'), 'v'),
+         c.gap0, c.kcont, c.rcont, c.Pdis, int(c.discContactOption), 1)
+        for c in components if c.model_type == 'amesim_lstp00a'])
+    stop_c = ",".join(f"{{{v},{_number(lo)},{_number(hi)},0,0,0,0}}" for v, lo, hi in stops) or "{0,0,0,0,0,0,0}"
+    next_event = []
+    for index, c in signal_specs:
+        if index == "step":
+            next_event.append(f"if (t < {_number(c.time)}) result = fmin(result, {_number(c.time)});")
+        else:
+            next_event.append(f"result = fmin(result, native_signal_break(t, end, {_number(c.tstart)}, {c.nstages}, {int(c.iscyclic)}, signal_{index}));")
+    jacobian = JacobianStructure.dense(len(state_keys), 'Compact storage-anchored lowering retains default differences')
+    source = '\n'.join([
+        '#include "model.h"', '#include <math.h>', *declarations,
+        f"const NativeStop model_stops[{max(1,len(stops))}] = {{{stop_c}}};",
+        contact_source,
+        f"const double model_atol[NSTATES] = {{{','.join(map(state_absolute_tolerance, state_keys))}}};",
+        "const char *const model_output_keys[NOUTPUTS] = {" + ",".join(json.dumps(v.key, ensure_ascii=True) for v in variables) + "};",
+        "int model_init(double *y) {", *init, "return 1; }",
+        "static int model_eval_internal(double t, const double *y, double *dy, double *w, NativePropertyTemperatures *temperatures) {", "(void)t;",
+        f"NativePropertyState property_states[{min(256,max(16,4*len(components)))}];",
+        "NativePropertyCache property_cache, *properties=&property_cache;",
+        "native_properties_init(properties,property_states,sizeof(property_states)/sizeof(property_states[0]));",
+        "properties->temperatures=temperatures;", *lines,
+        "for (int i=0;i<NSTATES;i++) if (!isfinite(dy[i])) return 0;",
+        "for (int i=0;i<NOUTPUTS;i++) if (!isfinite(w[i])) return 0;",
+        "return 1; }",
+        "int model_eval(double t,const double *y,double *dy,double *w) {return model_eval_internal(t,y,dy,w,NULL);}",
+        "int model_property_temperatures(double t,const double *y,NativePropertyTemperatures *temperatures) {double dy[NSTATES],w[NOUTPUTS];return model_eval_internal(t,y,dy,w,temperatures);}",
+        "double model_next_break(double t, double end) { (void)t; double result=end;", *next_event,
+        "return result; }", "",
+    ])
+    header = f'''#ifndef GENERATED_NATIVE_MODEL_H
+#define GENERATED_NATIVE_MODEL_H
+#include "kernels.h"
+#define MODEL_PROPERTY_TEMPERATURES 1
+int model_property_temperatures(double t,const double *y,NativePropertyTemperatures *temperatures);
+#define NSTATES {len(state_keys)}
+#define NOUTPUTS {len(variables)}
+#define NSTOPS {len(stops)}
+{contact_header}
+extern const NativeStop model_stops[{max(1,len(stops))}];
+extern const double model_atol[NSTATES];
+extern const char *const model_output_keys[NOUTPUTS];
+{chr(10).join(jacobian.header_lines())}
+int model_init(double *y);
+int model_eval(double t, const double *y, double *dy, double *w);
+double model_next_break(double t, double end);
+#endif
+'''
+    return NativeProgram(source, header, tuple(state_keys), variables, tuple(sorted({c.model_type for c in components})),jacobian_structure=jacobian.manifest())

app/simulation/native_codegen/contacts.py

@@ -0,0 +1,24 @@
+"""Emit state-only LSTP event descriptors for both native lowering paths."""
+from .compiler import _number
+
+
+def contact_table(contacts):
+    """Rows: velocity indices, gap, stiffness, damping, depth, force option,
+    subtract-first flag. Keep the force expression's floating operation order.
+    Position follows velocity in each reviewed mechanical state pair.
+    """
+    rows = []
+    for v1, v2, gap, stiffness, damping, depth, option, subtract_first in contacts:
+        rows.append('{' + ','.join((str(v1), str(v2), _number(gap),
+            _number(stiffness), _number(damping), _number(depth),
+            str(option), str(subtract_first))) + '}')
+    count = len(rows)
+    header = f'''#define NCONTACTS {count}
+typedef struct {{
+    int velocity1, velocity2;
+    double gap0, stiffness, damping, depth;
+    int signed_force, subtract_first;
+}} NativeContact;
+extern const NativeContact model_contacts[{max(1, count)}];'''
+    source = f'const NativeContact model_contacts[{max(1, count)}] = {{' + (','.join(rows) or '{0,0,0,0,0,0,0,0}') + '};'
+    return source, header

app/simulation/native_codegen/contracts.py

@@ -0,0 +1,32 @@
+"""Reviewed model contract versions implemented by the C kernels.
+
+A new registration/version must be explicitly ported and tested; it does not
+gain native support just by inheriting a supported Python component class.
+"""
+SUPPORTED_VERSIONS = {
+    'amesim_ideal_air_medium': '0.2.0',
+    'amesim_helium_medium': '0.1.0',
+    'amesim_pnpl01': '0.1.0',
+    'amesim_step0': '0.1.0',
+    'amesim_ud00': '0.2.0',
+    'amesim_f000': '0.1.0',
+    'amesim_forc': '0.2.0',
+    'amesim_mecmas21': '0.2.0',
+    'amesim_lstp00a': '0.2.0',
+    'amesim_lmechn1': '0.2.0',
+    'amesim_pnrp17': '0.1.0',
+    'amesim_pnch023': '0.1.0',
+    'amesim_pnch012': '0.1.0',
+    'amesim_pnor001': '0.3.0',
+    'amesim_pnvo001_fixed': '0.2.0',
+    'amesim_pnvo001': '0.2.0',
+    'amesim_pnl00r': '0.3.0',
+    'amesim_pnl0001': '0.4.0',
+    'amesim_pnl0002': '0.6.0',
+    'amesim_pnl0003': '0.4.0',
+    'amesim_pn3node2': '0.3.0',
+    'amesim_p4node2': '0.3.0',
+    'cylinder': '1.0.0', 'tank': '1.0.0', 'pipe': '1.0.0',
+    'orifice': '1.0.0', 'tee': '1.0.0',
+}
+SUPPORTED_TYPES = frozenset(SUPPORTED_VERSIONS)

app/simulation/native_codegen/extended.py

@@ -0,0 +1,796 @@
+"""Static C lowering for the complete built-in component catalog.
+
+Python constructs the graph and eliminates constant linear constraints once.
+All thermodynamics, flow/stream closure and derivatives execute in the EXE.
+"""
+from __future__ import annotations
+
+import json
+import math
+import re
+from importlib import import_module
+from graphlib import TopologicalSorter
+
+from .compiler import NativeCapabilityError, NativeProgram, _Groups, _number as num
+from .contracts import SUPPORTED_VERSIONS
+from .schedule import Computation, EvaluationSchedule, references
+from .tolerances import state_absolute_tolerance
+from .jacobian import StateDependencies, expression_inputs
+from app.simulation.components.amesim.semantics import contact_stiffness, validate_numerical_semantics
+
+
+GAS_TYPES = {'amesim_pnch023', 'amesim_pnch012', 'amesim_pnl0001',
+             'amesim_pnl0002', 'amesim_pnl0003', 'cylinder', 'tank'}
+NODES = {'amesim_pn3node2', 'amesim_p4node2', 'tee'}
+RESISTORS = {'amesim_pnor001', 'amesim_pnvo001_fixed', 'amesim_pnvo001',
+             'amesim_pnl00r', 'pipe', 'orifice'}
+
+
+def is_polytropic(c):
+    return c.model_type in {'amesim_pnl0001', 'amesim_pnl0002', 'amesim_pnl0003'} and int(c.mode) == 1
+
+
+def catalog_contracts():
+    from app.simulation.components.amesim.library import LIBRARY as a
+    from app.simulation.components.experimental.library import LIBRARY as e
+    result = {}
+    for entry in (*a.models, *e.models):
+        module, name = entry.split(':')
+        cls = getattr(import_module(module), name)
+        result[cls.MODEL_TYPE] = cls
+    return result
+
+
+def linear_assignments(equations, unknowns, free_flows=()):
+    """Eliminate constant coefficients; retain RHS expressions as C temporaries.
+
+    Exact pivot elimination avoids a numeric pseudoinverse and its tiny spurious
+    dependencies. Redundant rows are left to the nodal pressure closure.
+    """
+    rows = [[dict(a), {i: 1.0}] for i, (a, _) in enumerate(equations)]
+    pivots = []
+    for key in unknowns:
+        found = next((i for i in range(len(pivots), len(rows)) if abs(rows[i][0].get(key, 0)) > 1e-14), None)
+        if found is None and key in free_flows:
+            # Ideal coupled pipe compliances have a redundant internal flow.
+            # Their total m/U derivative is distributed by physical volume.
+            index = len(equations)
+            equations.append(({key: 1.0}, '0.0'))
+            rows.append([{key: 1.0}, {index: 1.0}])
+            found = len(rows)-1
+        if found is None:
+            raise NativeCapabilityError(f'Underdetermined native connection constraint: {key}')
+        j = len(pivots)
+        rows[j], rows[found] = rows[found], rows[j]
+        a, b = rows[j]
+        pivot = a[key]
+        rows[j] = [{k: v/pivot for k, v in a.items()}, {k: v/pivot for k, v in b.items()}]
+        for i, (a, b) in enumerate(rows):
+            if i == j:
+                continue
+            scale = a.get(key, 0)
+            if not scale:
+                continue
+            for target, source in zip((a, b), rows[j]):
+                for k, v in source.items():
+                    value = target.get(k, 0) - scale*v
+                    if abs(value) < 1e-14:
+                        target.pop(k, None)
+                    else:
+                        target[k] = value
+        pivots.append(key)
+    lines = [(f'b{i}', expr) for i, (_, expr) in enumerate(equations)
+             if any(i in rows[j][1] for j in range(len(pivots)))]
+    for j, key in enumerate(pivots):
+        expr = ' + '.join(f'({num(v)})*b{i}' for i, v in rows[j][1].items()) or '0.0'
+        lines.append((key, expr))
+    return lines
+
+
+def linear_schedule(equations, unknowns, free_flows=()):
+    return [f'{"double " if key.startswith("b") else ""}{key} = {expr};'
+            for key, expr in linear_assignments(equations, unknowns, free_flows)]
+
+
+def compile_extended_program(network):
+    network.validate_port_supplies()
+    components = list(network.components.values())
+    contracts = catalog_contracts()
+    for c in components:
+        if type(c) is not contracts.get(c.model_type):
+            raise NativeCapabilityError(f'{c.name}: no native contract for {c.model_type} / {type(c).__name__}')
+        if c.MODEL_VERSION != SUPPORTED_VERSIONS.get(c.model_type):
+            raise NativeCapabilityError(f'{c.name}: native kernel version does not match the component contract')
+        try:
+            validate_numerical_semantics(c)
+        except ValueError as exc:
+            raise NativeCapabilityError(str(exc)) from exc
+    variables = tuple(v for c in components for v in c.result_variable_metadata())
+    if not variables:
+        raise NativeCapabilityError('Simulation requires a runtime component; medium definitions alone have no outputs')
+    slots = {v.key: i for i, v in enumerate(variables)}
+    ports = {(c.name, p.name): p for c in components for p in c.active_port_definitions}
+    groups = _Groups(ports)
+    adjacent = {}
+    for edge in network.connections:
+        a, b = (p.key for p in edge.endpoints)
+        if edge.kind == 'physical':
+            adjacent[a], adjacent[b] = b, a
+            groups.union(a, b)
+        else:
+            source, target = (a, b) if ports[a].nominal_role == 'output' else (b, a)
+            adjacent[target] = source
+    for c in components:
+        for port in c.required_connection_ports:
+            if (c.name, port) not in adjacent:
+                raise NativeCapabilityError(f'{c.name}.{port}: unconnected required port')
+        names = [p.name for p in c.active_port_definitions]
+        if c.model_type in NODES | {'amesim_pnch023', 'amesim_pnch012', 'amesim_mecmas21', 'amesim_lmechn1'} or (c.model_type=='pipe' and c.lambda_darcy==0):
+            for p in names[1:]:
+                groups.union((c.name, names[0]), (c.name, p))
+        if c.model_type == 'amesim_pnrp17':
+            for a, b in [('port_2', 'port_5'), ('port_3', 'port_4')]:
+                groups.union((c.name, a), (c.name, b))
+
+    state_keys, initial, gas_initializers = [], [], []
+    states = {}
+    def add_states(c, fields, values):
+        for field, value in zip(fields, values):
+            states[c.name, field] = len(state_keys)
+            state_keys.append(f'{c.name}.{field}')
+            initial.append(float(value))
+    mass_groups = {}
+    for c in components:
+        if c.model_type in GAS_TYPES:
+            thermal = 'T' if is_polytropic(c) else 'U'
+            fields = ('m1', thermal+'1', 'm2', thermal+'2') if c.model_type == 'amesim_pnl0003' else ('m', thermal)
+            add_states(c, fields, [0.0]*len(fields))
+            if c.model_type == 'amesim_pnch012' and sum(c.external_volume_rates.values()) != 0:
+                add_states(c, ('_volume_displacement',), (0.0,))
+        elif c.model_type == 'amesim_mecmas21':
+            root = groups.find((c.name, 'port_1'))
+            mass_groups.setdefault(root, []).append(c)
+            if len(mass_groups[root]) == 1:
+                add_states(c, ('v', 'x'), (c.v0, c.x0))
+            else:
+                ref = mass_groups[root][0]
+                if abs(c.v0-ref.v0)>1e-10*max(abs(c.v0),1) or abs(c.x0-ref.x0)>1e-10*max(abs(c.x0),1):
+                    raise NativeCapabilityError('Rigidly connected masses require consistent initial x/v')
+                for field in ('v', 'x'):
+                    states[c.name, field] = states[ref.name, field]
+    friction_groups = []
+    for group in mass_groups.values():
+        dry = [c for c in group if c.use_friction and int(c.stoptype) != 3 and c.fstick > 0]
+        if dry:
+            ref = group[0]
+            threshold = min(c.dvel if int(c.frictionType) == 2 else 0 for c in dry)
+            mode = (1 if ref.v0 > 0 else -1) if abs(ref.v0) > threshold else 0
+            if mode == 0:
+                initial[states[ref.name, 'v']] = 0.0
+            add_states(ref, ('_friction_mode',), (mode,))
+            friction_groups.append((group, dry, threshold))
+    if len(state_keys)>1024 or len(variables)>16384:
+        raise NativeCapabilityError('Native model exceeds the 1024-state / 16384-output resource limit')
+    # Algebraic models use an internal constant state; the public state map stays empty.
+    nstates = max(len(state_keys), 1)
+    if not initial:
+        initial = [0.0]
+    dependencies = StateDependencies(len(state_keys))
+    lines, declarations, breaks = [], [], []
+    assigned = set()
+    def w(c, field):
+        name = c if isinstance(c, str) else c.name
+        return f'w[{slots[name+"."+field]}]'
+    def put(c, field, expr, dest=None):
+        (lines if dest is None else dest).append(f'{w(c,field)} = {expr};')
+        dependencies.expression(w(c,field), expr)
+        assigned.add((c if isinstance(c,str) else c.name)+'.'+field)
+    def y(c, field):
+        return f'y[{states[c.name,field]}]'
+    def ep(c, port):
+        return c.name, port
+    def pnames(c):
+        return [p.name for p in c.active_port_definitions if p.domain == 'pneumatic']
+    def mnames(c):
+        return [p.name for p in c.active_port_definitions if p.domain == 'mechanical']
+    for c in components:
+        if c.model_type == 'amesim_mecmas21':
+            for f in ('v', 'x'):
+                put(c, f, y(c, f))
+        for name in mnames(c):
+            root = groups.find(ep(c, name))
+            if root not in mass_groups:
+                raise NativeCapabilityError(f'{c.name}.{name}: mechanical group has no inertia anchor')
+            mass = mass_groups[root][0]
+            for f in ('v', 'x'):
+                put(c, name+'.'+f, y(mass, f))
+        if c.model_type == 'amesim_step0':
+            put(c, 'y', f't < {num(c.time)} ? {num(c.initial)} : {num(c.final)}')
+            breaks.append(f'if(t < {num(c.time)}) result=fmin(result,{num(c.time)});')
+        elif c.model_type == 'amesim_ud00':
+            ident = 'signal_'+str(len(declarations))
+            declarations.append(f'static const double {ident}[24] = {{'+','.join(num(v) for vs in (c.starts,c.ends,c.durations) for v in vs)+'};')
+            args=f'{num(c.tstart)}, {c.nstages}, {int(c.iscyclic)}, {ident}'
+            put(c, 'y', f'native_signal(t, {args})')
+            breaks.append(f'result=fmin(result,native_signal_break(t,end,{args}));')
+        else:
+            continue
+        put(c, 'out.signal', w(c, 'y'))
+    for c in components:
+        for port in c.active_port_definitions:
+            if port.kind == 'signal' and port.nominal_role == 'input':
+                target = adjacent.get(ep(c, port.name))
+                if target:
+                    expr = w(target[0], target[1]+'.signal')
+                elif c.model_type == 'amesim_pnvo001':
+                    expr = num(c.opening0)
+                else:
+                    raise NativeCapabilityError(f'{c.name}.{port.name}: signal input missing')
+                put(c, port.name+'.signal', expr)
+
+    media = {}
+    def medium(c):
+        m = c.medium
+        key = (getattr(m, 'SUBSTANCE_ID', None), getattr(m, 'PROPERTY_METHOD_ID', None),
+               m.R_gas, m.cp_ref, m.T_ref, m.cp_slope, m.viscosity_ref, m.viscosity_T_ref, m.sutherland_constant)
+        if key not in media:
+            if key[1] not in (None, 'ideal_gas', 'peng_robinson') or (key[1]=='peng_robinson' and key[0]!='helium'):
+                raise NativeCapabilityError(f'{c.name}: unsupported medium contract {key[:2]}')
+            ident = f'medium_{len(media)}'
+            declarations.append(f'static const NativeMedium {ident} = {{'+str(int(key[1]=='peng_robinson'))+','+','.join(num(v) for v in key[2:])+'};')
+            media[key]=ident
+        return '&'+media[key]
+
+    pistons = [c for c in components if c.model_type == 'amesim_pnrp17']
+    for c in pistons:
+        put(c, 'length', f'{num(c.x0)}+{w(c,"port_5.x")}-{w(c,"port_4.x")}')
+        put(c, 'volume', f'{num(c.effective_area)}*{w(c,"length")}')
+        put(c, 'volume_flow', f'{num(c.effective_area)}*({w(c,"port_5.v")}-{w(c,"port_4.v")})')
+
+    pneu = [endpoint for endpoint, port in ports.items() if port.domain == 'pneumatic']
+    pi = {endpoint: i for i, endpoint in enumerate(pneu)}
+    pgroups = list(dict.fromkeys(groups.find(endpoint) for endpoint in pneu))
+    pgi = {root: i for i, root in enumerate(pgroups)}
+    def p(c, name): return f'p[{pgi[groups.find(ep(c,name))]}]'
+    def q(c, name): return f'q[{pi[ep(c,name)]}]'
+    def h(c, name): return f'h[{pi[ep(c,name)]}]'
+    def hin(c, name, temperature=False):
+        other = adjacent[ep(c,name)]
+        obj = network.components[other[0]]
+        if temperature and obj.model_type in NODES-{'tee'}:
+            other = adjacent[(obj.name, 'port_2')]
+        return f'h[{pi[other]}]'
+
+    # Reference nodes aggregate branch quantities towards port 2. Follow this
+    # directed contract, not the undirected pressure group (which can span
+    # unrelated volumes). Port-supply validation has already rejected cycles.
+    reference_nodes = {c.name: c for c in components if c.model_type in NODES-{'tee'}}
+    node_graph = {c.name: [other[0] for name in pnames(c) if name != 'port_2'
+                          for other in [adjacent[ep(c, name)]]
+                          if other[0] in reference_nodes and other[1] == 'port_2']
+                  for c in reference_nodes.values()}
+    node_order = [reference_nodes[name] for name in TopologicalSorter(node_graph).static_order()]
+    volume_sources = {ep(c, 'port_1'): [c] for c in pistons}
+    node_energy = {ep(c, 'port_2'): f'node_energy[{i}]' for i, c in enumerate(node_order)}
+    for c in node_order:
+        volume_sources[ep(c, 'port_2')] = [source for name in pnames(c) if name != 'port_2'
+            for source in volume_sources.get(adjacent[ep(c, name)], ())]
+
+    def energy_into(c, name, outflow_h):
+        other = adjacent[ep(c, name)]
+        # Net mass flow can be zero while the sum of branch enthalpy flows
+        # remains nonzero. Carry that signed energy directly, without H/q.
+        if other in node_energy:
+            return node_energy[other]
+        return f'{q(c,name)}*({q(c,name)}>0?{hin(c,name)}:{outflow_h})'
+
+    gases, anchor, port_gas, volume_rate = {}, {}, {}, {}
+    anchor_partitions = {}
+    gas_count = 0
+    for c in components:
+        if c.model_type not in GAS_TYPES:
+            continue
+        kind = c.model_type
+        if kind == 'amesim_pnch023':
+            volume, rate = num(c.cvol), '0.0'
+        elif kind == 'amesim_pnch012':
+            attached = [source for name in pnames(c)
+                        for source in volume_sources.get(adjacent[ep(c, name)], ())]
+            volume = num(c.cvol0+sum(c.external_volumes.values()))+''.join('+'+w(d,'volume') for d in attached)
+            if (c.name, '_volume_displacement') in states:
+                volume += '+'+y(c, '_volume_displacement')
+                target = f'dy[{states[c.name,"_volume_displacement"]}]'
+                expr = num(sum(c.external_volume_rates.values()))
+                lines.append(f'{target}={expr};')
+                dependencies.expression(target, expr)
+            put(c, 'vol', f'fmax({num(c.cvol0/100)}, {volume})')
+            rate = num(sum(c.external_volume_rates.values()))+''.join('+'+w(d,'volume_flow') for d in attached)
+            limit = num(c.cvol0/100)
+            put(c, 'dvol', f'({volume}) < {limit} || (({volume}) <= {limit} && ({rate}) < 0) ? 0.0 : ({rate})')
+            volume, rate = w(c,'vol'), w(c,'dvol')
+        elif kind in ('cylinder', 'tank'):
+            volume, rate = num(c.V), '0.0'
+        else:
+            volume, rate = num(c.volume), '0.0'
+        volume_rate[c.name] = rate
+        halves = (1,2) if kind == 'amesim_pnl0003' else (0,)
+        for half in halves:
+            suffix = str(half) if half else ''
+            gas = f'g[{gas_count}]';gas_count += 1
+            gases[c.name,half] = gas
+            V = num(c.compliance_volume) if half else volume
+            if half:
+                p0,T0=c.parameter_values[f'p{half}_0'],c.parameter_values[f'T{half}_0']
+                initial_volume=c.compliance_volume
+            else:
+                p0,T0=c.parameter_values['p0'],c.parameter_values['T0']
+                initial_volume=(max(c.cvol0+sum(c.external_volumes.values()),c.cvol0/100)
+                                if kind=='amesim_pnch012' else
+                                c.cvol if kind=='amesim_pnch023' else c.V if kind in ('cylinder','tank') else c.volume)
+                if kind == 'amesim_pnch012':
+                    def initial_x(d, port):
+                        return mass_groups[groups.find(ep(d, port))][0].x0
+                    initial_volume = max(c.cvol0 + sum(c.external_volumes.values()) + sum(
+                        d.effective_area * (d.x0 + initial_x(d, 'port_5') - initial_x(d, 'port_4'))
+                        for d in attached), c.cvol0 / 100)
+            thermal = ('T' if is_polytropic(c) else 'U') + suffix
+            if is_polytropic(c):
+                gas_initializers += [f'{y(c,"m"+suffix)}={num(p0*initial_volume/(c.medium.R_gas*T0))};', f'{y(c,thermal)}={num(T0)};']
+                gas_function = 'native_polytropic_gas_context'
+            else:
+                gas_initializers.append(f'if(!native_medium_init({medium(c)},{num(p0)},{num(T0)},{num(initial_volume)},{int(kind in ("cylinder","tank"))},&y[{states[c.name,"m"+suffix]}])) return 0;')
+                gas_function = 'native_medium_gas_context'
+            gas_arguments = f'{medium(c)}, {y(c,"m"+suffix)}, {y(c,thermal)}, {V}, &{gas}'
+            lines.append(f'if(!(jacobian ? native_jacobian_gas(&jacobian->gases[{gas_count-1}],{gas_function},{gas_arguments},&jacobian->stats) : '
+                         f'{gas_function}(gas_properties,{gas_arguments}))) return 0;')
+            gas_inputs = expression_inputs(f'{y(c,"m"+suffix)}+{y(c,thermal)}+({V})')
+            for field in ('p','T','rho','u','h'):
+                dependencies.assign(gas+'.'+field, gas_inputs)
+            put(c, 'm'+suffix, y(c, 'm'+suffix))
+            put(c, 'U'+suffix, f'{y(c,"m"+suffix)}*{gas}.u' if is_polytropic(c) else y(c,'U'+suffix))
+            for field in ('p','T','rho','u','h'):
+                put(c, field+suffix, gas+'.'+field)
+            anchored = pnames(c)
+            if kind == 'amesim_pnl0001': anchored=['port_2']
+            if kind == 'amesim_pnl0002': anchored=[]
+            if half: anchored=['port_'+suffix]
+            for name in anchored:
+                root=groups.find(ep(c,name))
+                anchor[root]=gas
+                partition=(c.name,half)
+                anchor_partitions.setdefault(root, {})[partition]=(c, float(c.compliance_volume if half else c.volume) if kind in ('amesim_pnl0001','amesim_pnl0003') else None)
+            for name in (['port_'+suffix] if half else pnames(c)):
+                port_gas[ep(c,name)]=gas
+    coupled=[]
+    project=[]
+    for root,partitions in anchor_partitions.items():
+        if len(partitions)<2: continue
+        if any(volume is None for _,volume in partitions.values()) or len({id(c.medium) for c,_ in partitions.values()})!=1:
+            raise NativeCapabilityError('Direct gas-storage coupling requires compatible fixed pipe compliances; insert a resistance between independent chambers')
+        laws = {(is_polytropic(c), c.k if is_polytropic(c) else None) for c,_ in partitions.values()}
+        if len(laws) != 1:
+            raise NativeCapabilityError('Directly coupled pipe compliances require the same thermodynamic mode and polytropic exponent')
+        poly = next(iter(laws))[0]
+        offsets=[];volumes=[]
+        for (name,half),(c,volume) in partitions.items():
+            offsets.append(states[name,'m'+(str(half) if half else '')]);volumes.append(volume)
+        for prefix in ('p','T'):
+            values=[c.parameter_values[f'{prefix}{half}_0'] if half else getattr(c,prefix+'0')
+                    for (_,half),(c,_) in partitions.items()]
+            if max(values)-min(values)>1e-9*max(1,*map(abs,values)):
+                raise NativeCapabilityError('Ideally coupled pipe compliances require consistent initial pressure and temperature')
+        total=sum(volumes)
+        thermal_sum = '+'.join(f'y[{i+1}]*{num(v/total)}' if poly else f'y[{i+1}]' for i,v in zip(offsets,volumes))
+        project.append('{ double mass='+ '+'.join(f'y[{i}]' for i in offsets)+',thermal='+thermal_sum+';')
+        for i,volume in zip(offsets,volumes):
+            project += [f'projected[{i}]=mass*{num(volume/total)};projected[{i+1}]=thermal*{num(1 if poly else volume/total)};']
+        project.append('}')
+        coupled.append((root,offsets,volumes,poly))
+        dependencies.project_states(offsets)
+        dependencies.project_states([i+1 for i in offsets])
+    for root, gas in anchor.items():
+        lines.append(f'p[{pgi[root]}]={gas}.p;')
+        dependencies.assign(f'p[{pgi[root]}]', (gas+'.p',))
+    h_initial = {f'h[{pi[endpoint]}]': gas+'.h' for endpoint,gas in port_gas.items()}
+
+    operations, flow_known, flow_eq = [], set(), []
+    pipe_cache_count = 0
+    def pipe_flow(expression):
+        nonlocal pipe_cache_count
+        result = f'native_pipe_flow_cached_context(properties,&pipe_cache[{pipe_cache_count}],{expression})'
+        pipe_cache_count += 1
+        return result
+    def flow(c, name, expr):
+        target=q(c,name)
+        operations.append(Computation.assignment(f'flow:{c.name}.{name}',target,expr))
+        flow_known.add(target)
+    def flow_equation(terms):
+        flow_eq.append(({q(c,name):coef for c,name,coef in terms},'0.0'))
+    for c in components:
+        kind=c.model_type
+        names=pnames(c)
+        if kind in RESISTORS or kind in NODES:
+            flow_equation([(c,name,1) for name in names])
+        if kind in {'amesim_pnpl01','amesim_pnrp17'}:
+            flow(c,'port_1','0.0')
+        if kind in RESISTORS:
+            a,b=names
+            pa,pb=p(c,a),p(c,b)
+            if kind=='pipe' and c.lambda_darcy==0:
+                # A zero-loss pipe is an ideal connection, whose flow is
+                # determined by the neighbouring constitutive equations.
+                continue
+            if kind=='orifice':
+                flow(c,a,f'{num(c.K_eff)}*copysign(sqrt(fabs({pa}-{pb})),{pa}-{pb})')
+            elif kind=='pipe':
+                resistance=c.lambda_darcy*c.L/c.D
+                flow(c,a,f'copysign(sqrt(fabs({pa}-{pb})*2*fmax(native_density_context(properties,{medium(c)},fmax(.5*({pa}+{pb}),1),{num(c.T0)}),1e-12)*{num(c.area*c.area/resistance)}),{pa}-{pb})')
+            elif kind=='amesim_pnl00r':
+                T=f'native_temperature_ph_context(properties,{medium(c)},fmax(fmax({pa},{pb}),1),{pa}>={pb}?{hin(c,a,True)}:{hin(c,b,True)})'
+                flow(c,a,pipe_flow(f'{medium(c)},{pa},{pb},{T},{num(c.diam)},{num(c.le)},{num(c.rr)},0'))
+            else:
+                opening = w(c,'xv') if kind!='amesim_pnor001' else '1.0'
+                if kind!='amesim_pnor001':
+                    value = f'fmax(0,fmin(1,{w(c,"res.signal")}))' if kind=='amesim_pnvo001' else num(c.opening)
+                    put(c,'xv',value)
+                area = c.effective_cq*(c.effective_area if kind=='amesim_pnor001' else c.maximum_area)
+                inputs=f'{medium(c)},{pa},{pb},{hin(c,a)},{hin(c,b)},{num(area)},{opening}'
+                outputs=(q(c,a),w(c,'cm'),w(c,'gasvel'))
+                code=f'if(!native_medium_orifice_context(properties,{inputs},&{outputs[0]},&{outputs[1]},&{outputs[2]})) return 0;'
+                operations.append(Computation(f'flow:{c.name}.{a}',outputs,references(inputs),(code,)))
+                flow_known.add(q(c,a));assigned.update((c.name+'.cm',c.name+'.gasvel'))
+            flow(c,b,f'-{q(c,a)}')
+        elif kind in ('amesim_pnl0001','amesim_pnl0002'):
+            gas=gases[c.name,0]
+            for name in (['port_1'] if kind.endswith('1') else names):
+                # Resistance uses the gas arriving from the upstream side,
+                # including inflow into a PNL0001 storage volume.
+                T=f'({p(c,name)}>{gas}.p?native_temperature_ph_context(properties,{medium(c)},fmax({p(c,name)},1),{hin(c,name,True)}):{gas}.T)'
+                flow(c,name,pipe_flow(f'{medium(c)},{p(c,name)},{gas}.p,{T},{num(c.diam)},{num(c.le/(2 if kind.endswith("2") else 1))},{num(c.rr)},1'))
+    for edge in network.connections:
+        if edge.domain=='pneumatic':
+            flow_eq.append(({f'q[{pi[e.key]}]':1 for e in edge.endpoints},'0.0'))
+    unknownq=[f'q[{i}]' for i in range(len(pneu)) if f'q[{i}]' not in flow_known]
+    reduced=[]
+    for terms,rhs in flow_eq:
+        known=''.join(f'-({num(v)})*{k}' for k,v in terms.items() if k in flow_known)
+        reduced.append(({k:v for k,v in terms.items() if k not in flow_known},rhs+known))
+    free_flows={f'q[{pi[e]}]' for root,_,_,_ in coupled for e in pneu if groups.find(e)==root}
+    flow_bindings=linear_assignments(reduced,unknownq,free_flows)
+    flow_temporary_count=max((int(key[1:])+1 for key,_ in flow_bindings if key.startswith('b')),default=0)
+    for key,expr in flow_bindings:
+        target=re.sub(r'\bb(\d+)\b',r'fb[\1]',key)
+        value=re.sub(r'\bb(\d+)\b',r'fb[\1]',expr)
+        operations.append(Computation.assignment('connection:'+key,target,value,'linear'))
+
+    unknownp=[root for root in pgroups if root not in anchor]
+    for root in unknownp:
+        terms=[f'q[{pi[e]}]' for e in pneu if groups.find(e)==root and f'q[{pi[e]}]' in flow_known]
+        if not terms:
+            raise NativeCapabilityError('Unanchored pneumatic pressure group has no constitutive flow relation')
+        expr=' + '.join(terms)
+        operations.append(Computation('pressure:'+str(root),(f'p[{pgi[root]}]',),references(expr),(),'pressure',expr))
+
+    for c in components:
+        names=pnames(c);kind=c.model_type
+        if kind in {'amesim_pnpl01','amesim_pnrp17'}:
+            operations.append(Computation.assignment(f'alias:{c.name}.port_1',h(c,'port_1'),hin(c,'port_1'),'alias'))
+        elif kind in RESISTORS:
+            a,b=names
+            for name,other in ((a,b),(b,a)):
+                operations.append(Computation.assignment(f'alias:{c.name}.{name}',h(c,name),hin(c,other),'alias'))
+        elif kind in NODES:
+            if kind!='tee':
+                # Reference copies have no flow dependency. Keep them separate
+                # from the reference port's finite h_outflow diagnostic below;
+                # actual reference energy is carried by node_energy, not q*h.
+                for name in names:
+                    if name!='port_2':
+                        operations.append(Computation.assignment(f'alias:{c.name}.{name}',h(c,name),hin(c,'port_2'),'alias'))
+            stream_lines = ['{ double total=0,energy=0,average=0;', *[f'if({q(c,name)}>1e-12) {{total+={q(c,name)};energy+={q(c,name)}*{hin(c,name)};}} average+={hin(c,name)};' for name in names]]
+            if kind=='tee':
+                stream_lines += [f'double mixed=total>1e-12?energy/total:average/{len(names)};', *[f'{h(c,name)}=mixed;' for name in names]]
+            else:
+                stream_lines += [f'double ref={hin(c,"port_2")},mixed=total>1e-12?energy/total:ref;', f'{h(c,"port_2")}=mixed;',f'if({q(c,"port_2")}<0) {{ double e=0,scale=0;',
+                                 *[f'e+={q(c,name)}*({q(c,name)}>1e-12?{hin(c,name)}:ref);scale+=fabs({q(c,name)});' for name in names if name!='port_2'],
+                                 f'double flow={q(c,"port_2")},transition=fmax(.05*scale,1e-12);',
+                                 'double inv=-flow>=transition?1/flow:flow*(2*transition*transition-flow*flow)/pow(transition,4);',
+                                 f'{h(c,"port_2")}=mixed-(e+flow*mixed)*inv;','}']
+                # Nodes expose their reference temperature as an output too.
+                if c.name+'.T' in slots:
+                    raise NativeCapabilityError('Unexpected node temperature output contract')
+            stream_lines += ['}']
+            outputs=tuple(h(c,name) for name in (names if kind=='tee' else ['port_2']))
+            inputs=frozenset(q(c,name) for name in names)|frozenset(hin(c,name) for name in names)
+            operations.append(Computation(f'stream:{c.name}',outputs,inputs,tuple(stream_lines),'stream'))
+
+    # Current state/parameter/signal values are available before this phase.
+    # Default h guesses are deliberately absent from the known-source map.
+    labels={f'w[{i}]': key for key,i in slots.items()}
+    known={f'w[{slots[key]}]': 'prepared:'+key for key in assigned}
+    gas_origins={gas: 'state:'+','.join(f'{name}.{field}{str(half) if half else ""}' for field in ('m','U'))
+                 for (name,half),gas in gases.items()}
+    for gas,origin in gas_origins.items():
+        for field in ('p','T','rho','u','h'):
+            known[gas+'.'+field]=origin
+    for root,gas in anchor.items():
+        known[f'p[{pgi[root]}]']=gas_origins[gas]
+    for endpoint,gas in port_gas.items():
+        known[f'h[{pi[endpoint]}]']=gas_origins[gas]
+    for endpoint,index in pi.items():
+        labels[f'h[{index}]']='.'.join(endpoint)+'.h_outflow'
+        labels[f'q[{index}]']='.'.join(endpoint)+'.m_flow'
+    for root,index in pgi.items():
+        labels[f'p[{index}]']='pressure:'+','.join('.'.join(ep) for ep in pneu if groups.find(ep)==root)
+    schedule=EvaluationSchedule(operations,known,labels)
+    for operation in operations:
+        dependencies.computation(operation)
+    for target,expr in h_initial.items():
+        if target not in schedule.producers:
+            lines.append(f'{target}={expr};')
+            dependencies.expression(target, expr)
+    schedule_helpers, scheduled_lines=schedule.emit()
+    lines += scheduled_lines
+    if node_order:
+        lines.append(f'double node_energy[{len(node_order)}];')
+    for c in node_order:
+        target = node_energy[ep(c, 'port_2')]
+        expr = ' + '.join(energy_into(c, name, h(c, name)) for name in pnames(c) if name != 'port_2')
+        lines.append(f'{target}={expr};')
+        dependencies.expression(target, expr)
+    for c in components:
+        for name in pnames(c):
+            for field,expr in [('p',p(c,name)),('m_flow',q(c,name)),('h_outflow',h(c,name))]:
+                put(c,name+'.'+field,expr)
+
+    # Mechanical force balance includes shared accelerations for rigid groups.
+    feq=[]
+    for edge in network.connections:
+        if edge.domain=='mechanical':
+            feq.append(({w(e.component,e.port+'.f'):1 for e in edge.endpoints},'0.0'))
+    for c in components:
+        kind=c.model_type
+        if kind=='amesim_forc':
+            put(c,'force',f'{num(c.direction)}*{w(c,"res.signal")}')
+            feq.append(({w(c,'port_2.f'):1},'-'+w(c,'force')))
+        elif kind=='amesim_f000':
+            feq.append(({w(c,'port_1.f'):1},'0.0'))
+        elif kind=='amesim_lstp00a':
+            put(c,'gap',f'{num(c.gap0)}+{w(c,"port_2.x")}-{w(c,"port_1.x")}')
+            put(c,'penetration',f'fmax(-{w(c,"gap")},0)')
+            put(c,'force',f'native_contact({w(c,"penetration")},{w(c,"port_1.v")}-{w(c,"port_2.v")},{num(contact_stiffness(c))},{num(c.rcont)},{num(c.Pdis)},{int(c.discContactOption)})')
+            feq += [({w(c,'port_1.f'):1},w(c,'force')),({w(c,'port_2.f'):1},'-'+w(c,'force'))]
+        elif kind=='amesim_pnrp17':
+            put(c,'pressure_force',f'({w(c,"port_1.p")}-101300)*{num(c.effective_area)}')
+            feq += [({w(c,'port_2.f'):1,w(c,'port_5.f'):1},'-'+w(c,'pressure_force')),({w(c,'port_3.f'):1,w(c,'port_4.f'):1},w(c,'pressure_force'))]
+        elif kind=='amesim_lmechn1':
+            feq.append(({w(c,name+'.f'):1 for name in mnames(c)},'0.0'))
+        elif kind=='amesim_mecmas21':
+            v,x=w(c,'v'),w(c,'x')
+            put(c,'Fvisc',f'-{num(c.rvisc)}*{v}' if c.use_friction else '0.0')
+            put(c,'Ffric','0.0')
+            for field,penetration,velocity,suffix in [('Fmin',num(c.xmin)+'-'+x,'-'+v,'min'),('Fmax',x+'-'+num(c.xmax),v,'max')]:
+                expr=f'native_limit_force({penetration},{velocity},{num(getattr(c,"Kb"+suffix))},{num(getattr(c,"Db"+suffix))},{num(getattr(c,"Pd"+suffix))},{int(c.discContactOption)})' if int(c.stoptype)==2 else '0.0'
+                put(c,field,expr)
+            ref=mass_groups[groups.find(ep(c,'port_1'))][0]
+            extra=f'{w(c,"Fvisc")}+{w(c,"Ffric")}+{w(c,"Fmin")}-{w(c,"Fmax")}'
+            if c.use_friction: extra+=f'-{num(c.wind)}*{v}*fabs({v})'
+            extra += f'+({num(c.mass * 9.80665 * math.sin(math.radians(c.theta)))})'
+            feq.append(({w(c,'port_1.f'):1,w(c,'port_2.f'):1,w(ref,'a'):-c.mass},f'-({extra})'))
+    unknownf=[w(c,name+'.f') for c in components for name in mnames(c)]+[w(group[0],'a') for group in mass_groups.values()]
+    # Keep the same elimination/order while registering its structured bindings.
+    mechanical_assignments = linear_assignments(feq, unknownf)
+    for target, expression in mechanical_assignments:
+        lines.append(f'{"double " if target.startswith("b") else ""}{target} = {expression};')
+        dependencies.expression(target, expression)
+    for index, (group, dry, threshold) in enumerate(friction_groups):
+        ref = group[0]
+        drive = f'friction_drive_{index}'
+        expression = f'{num(sum(c.mass for c in group))}*{w(ref,"a")}'
+        lines.append(f'double {drive}={expression};')
+        dependencies.expression(drive, expression)
+        # Amesim ideal stops take priority over dry friction. A blocked mass
+        # carries its load through the stop, not through an extra friction force.
+        blocked = f'friction_blocked_{index}'
+        ideal = [c for c in group if int(c.stoptype) == 1]
+        conditions = []
+        for c in ideal:
+            x, v = y(ref, 'x'), y(ref, 'v')
+            conditions += [f'({x}<={num(c.xmin+1e-12*max(abs(c.xmin),1))} && {v}<=1e-12 && {drive}<=0)',
+                           f'({x}>={num(c.xmax-1e-12*max(abs(c.xmax),1))} && {v}>=-1e-12 && {drive}>=0)']
+        blocked_expression = ' || '.join(conditions) or '0'
+        lines.append(f'double {blocked}=({blocked_expression});')
+        dependencies.expression(blocked, blocked_expression)
+        lines.append(f'{drive}={blocked}?0:{drive};')
+        dependencies.expression(drive, f'{blocked}?0:{drive}')
+        lines.append(f'if(friction_drives) friction_drives[{index}]={drive};')
+        capacity = sum(c.fstick for c in dry)
+        for c in dry:
+            put(c, 'Ffric', f'{blocked}?0:native_dry_friction({y(ref,"v")},{drive}*{num(c.fstick/capacity)},'
+                f'{num(c.fcoul)},{num(c.fstick)},{num(c.astrib)},'
+                f'{int(int(c.frictionType)==2 and int(c.strib)==2)},{y(ref,"_friction_mode")})')
+        lines.append(f'dy[{states[ref.name,"_friction_mode"]}]=0;')
+        dependencies.expression(f'dy[{states[ref.name,"_friction_mode"]}]', '0')
+    if friction_groups:
+        # The first linear solve supplies the drive without dry friction. The
+        # second redistributes actual friction forces through the same network.
+        # No pressure/flow iteration or mutable RHS mode is introduced.
+        for target, expression in mechanical_assignments:
+            lines.append(f'{target}={expression};')
+            dependencies.expression(target, expression)
+    for c in components:
+        for name in mnames(c): assigned.add(c.name+'.'+name+'.f')
+        if c.model_type=='amesim_lmechn1':
+            put(c,'tforce',' + '.join(w(c,name+'.f') for name in mnames(c)[:-1]))
+    stops=[]
+    for group in mass_groups.values():
+        ref=group[0];vi=states[ref.name,'v'];xi=states[ref.name,'x']
+        limits=[c for c in group if int(c.stoptype) in (1,3)]
+        lines += [f'dy[{vi}]={w(ref,"a")};dy[{xi}]={y(ref,"v")};']
+        dependencies.expression(f'dy[{vi}]', w(ref,'a'))
+        dependencies.expression(f'dy[{xi}]', y(ref,'v'))
+        if limits:
+            lower=max(c.xmin for c in limits);upper=min(c.xmax for c in limits)
+            if lower>upper or ref.x0<lower-1e-12 or ref.x0>upper+1e-12:
+                raise NativeCapabilityError('Inconsistent discrete endstop bounds or initial position')
+            restitution, thresholds = [], []
+            for parameter, bound in [('xmin',lower),('xmax',upper)]:
+                active=[c for c in limits if abs(getattr(c,parameter)-bound)<=1e-12*max(abs(bound),1)]
+                restitution.append(0 if any(int(c.stoptype)==1 for c in active) else min(c.restcoeff for c in active))
+                thresholds.append(max((c.restdvel for c in active if int(c.stoptype)==3),default=0))
+            stops.append((vi,lower,upper,*restitution,*thresholds))
+            lines.append(f'native_stop_motion({y(ref,"x")},{y(ref,"v")},{num(lower)},{num(upper)},&dy[{vi}],&dy[{xi}]);')
+            dependencies.stop_motion(vi, xi)
+        for c in group: put(c,'a',f'dy[{vi}]')
+
+    for c in components:
+        kind=c.model_type
+        if kind not in GAS_TYPES and kind!='amesim_pnl00r': continue
+        if kind in GAS_TYPES:
+            halves=(1,2) if kind=='amesim_pnl0003' else (0,)
+            center='0.0'
+            if kind=='amesim_pnl0003':
+                a,b=gases[c.name,1],gases[c.name,2]
+                center=w(c,'dmctr')
+                put(c,'dmctr',f'native_pipe_flow_context(properties,{medium(c)},{a}.p,{b}.p,{a}.p>={b}.p?{a}.T:{b}.T,{num(c.diam)},{num(c.le)},{num(c.rr)},3)')
+            for half in halves:
+                gas=gases[c.name,half];suffix=str(half) if half else ''
+                names=['port_'+suffix] if half else pnames(c)
+                mass=' + '.join(q(c,name) for name in names)
+                energy=' + '.join(energy_into(c, name, gas+'.h') for name in names)
+                if half:
+                    sign='-' if half==1 else '+'
+                    mass+=sign+center
+                    energy+=f'{sign}{center}*({center}>0?{gases[c.name,1]}.h:{gases[c.name,2]}.h)'
+                heat='0.0'
+                if kind.startswith('amesim_pnch'):
+                    heat=f'{num(c.kth*c.sth)}*({num(c.extemp)}-{gas}.T)-{gas}.p*({volume_rate[c.name]})'
+                elif kind.startswith('amesim_pnl') and int(c.mode)!=1:
+                    temp=gas+'.T'
+                    heat=f'{num(c.kth*c.exchange_area/(2 if half else 1))}*({num(c.extemp)}-({temp}))'
+                thermal = ('T' if is_polytropic(c) else 'U') + suffix
+                thermal_rhs = f'{num(c.k-1)}*{gas}.T/({y(c,"m"+suffix)})*({mass})' if is_polytropic(c) else f'{energy}+({heat})'
+                lines += [f'dy[{states[c.name,"m"+suffix]}]={mass};',f'dy[{states[c.name,thermal]}]={thermal_rhs};']
+                dependencies.expression(f'dy[{states[c.name,"m"+suffix]}]', mass)
+                dependencies.expression(f'dy[{states[c.name,thermal]}]', thermal_rhs)
+        if kind.startswith('amesim_pnl'):
+            diag=[]
+            if kind=='amesim_pnl0002':
+                gas=gases[c.name,0]
+                for name in pnames(c):
+                    flow=q(c,name);pp=f'({flow}>=0?fmax({p(c,name)},1):fmax({gas}.p,1))'
+                    temp=f'({flow}>=0?fmax(native_temperature_ph_context(properties,{medium(c)},{pp},{hin(c,name,True)}),1):{gas}.T)'
+                    diag.append((flow,pp,temp,c.le/2,0))
+            elif kind=='amesim_pnl0003':
+                a,b=gases[c.name,1],gases[c.name,2];flow=w(c,'dmctr')
+                diag=[(flow,f'fmax(fmax({a}.p,{b}.p),1)',f'({flow}>=0?{a}.T:{b}.T)',c.le,1)]
+            else:
+                pa,pb=p(c,'port_1'),p(c,'port_2');pp=f'fmax(fmax({pa},{pb}),1)'
+                if kind=='amesim_pnl0001':
+                    gas=gases[c.name,0]
+                    temp=f'({pa}>{gas}.p?fmax(native_temperature_ph_context(properties,{medium(c)},{pp},{hin(c,"port_1",True)}),1):{gas}.T)'
+                else:
+                    temp=f'fmax(native_temperature_ph_context(properties,{medium(c)},{pp},{pa}>={pb}?{hin(c,"port_1",True)}:{hin(c,"port_2",True)}),1)'
+                diag=[(q(c,'port_1'),pp,temp,c.le,0)]
+            lines.append('{ double d[4],acc[4]={0};')
+            for flow,pp,temp,length,diagnostic in diag:
+                lines.append(f'native_pipe_diagnostics_context(properties,{medium(c)},{flow},{pp},{temp},{num(c.diam)},{num(length)},{num(c.rr)},{diagnostic},d);')
+                if len(diag)>1: lines.append('d[2]=fabs(d[2]);')
+                lines.append('for(int i=0;i<4;i++) acc[i]+=d[i];')
+            for i,field in enumerate(('re','cm','v','ff')):
+                expr=f'acc[{i}]/{len(diag)}'
+                put(c,field,f'fmin({expr},64000000)' if field=='ff' else expr)
+            lines.append('}')
+    for _,offsets,volumes,poly in coupled:
+        thermal_sum = '+'.join(f'dy[{i+1}]*{num(v/sum(volumes))}' if poly else f'dy[{i+1}]' for i,v in zip(offsets,volumes))
+        lines.append('{ double mass='+ '+'.join(f'dy[{i}]' for i in offsets)+',thermal='+thermal_sum+';')
+        for i,volume in zip(offsets,volumes):
+            lines.append(f'dy[{i}]=mass*{num(volume/sum(volumes))};dy[{i+1}]=thermal*{num(1 if poly else volume/sum(volumes))};')
+            dependencies.assign(f'dy[{i}]', (f'dy[{j}]' for j in offsets))
+            dependencies.assign(f'dy[{i+1}]', (f'dy[{j+1}]' for j in offsets))
+        lines.append('}')
+    missing=set(slots)-assigned
+    if missing: raise NativeCapabilityError(f'Native output mapping incomplete: {sorted(missing)}')
+    if not state_keys: lines.append('dy[0]=0;')
+    jacobian = dependencies.build()
+    memo_kernels = ('native_temperature_ph_context(', 'native_density_context(',
+                    'native_pipe_flow_context(', 'native_pipe_flow_cached_context(')
+    has_memo_work = gas_count > 0 or any(name in '\n'.join([*lines,*schedule_helpers]) for name in memo_kernels)
+    reuse_enabled = jacobian.enabled and 0 < jacobian.color_count < nstates and has_memo_work
+    jacobian_info = jacobian.manifest(canonical_rhs=True)
+    jacobian_info['reuse'] = dict(enabled=reuse_enabled,gasSlots=gas_count,scalarSlots=1024,
+        scope='one Jacobian construction',key='kernel and bit-exact complete physical inputs',
+        policy='immutable canonical baseline for gas, PH inversion, density and pipe roots; changed inputs recomputed',
+        verification='uncached canonical dense differences')
+    np,ng,nq=max(1,len(pgroups)),max(1,gas_count),max(1,len(pneu))
+    from .contacts import contact_table
+    contact_source, contact_header = contact_table([
+        (states[mass_groups[groups.find(ep(c, 'port_1'))][0].name, 'v'],
+         states[mass_groups[groups.find(ep(c, 'port_2'))][0].name, 'v'],
+         c.gap0, contact_stiffness(c), c.rcont, c.Pdis, int(c.discContactOption), 0)
+        for c in components if c.model_type == 'amesim_lstp00a'])
+    # Advanced-friction reference runs at 5 N and 7 N confirm Amesim 2404's
+    # 0.1% breakaway hysteresis. Simple friction uses the exact static threshold.
+    source='\n'.join(['#include "model.h"','#include <math.h>','#include <string.h>',*declarations,
+        f'const NativeFriction model_frictions[{max(1,len(friction_groups))}] = {{'+(','.join(
+            '{'+str(states[group[0].name,'v'])+','+str(states[group[0].name,'_friction_mode'])+','+num(threshold)+','+
+            num(sum(c.fstick*(1.001 if int(c.frictionType)==2 else 1) for c in dry))+'}'
+            for group,dry,threshold in friction_groups) or '{0,0,0,0}')+'};',
+        f'const NativeStop model_stops[{max(1,len(stops))}] = {{'+(','.join('{'+str(s[0])+','+','.join(num(v) for v in s[1:])+'}' for s in stops) or '{0,0,0,0,0,0,0}')+'};',
+        contact_source,
+        'const double model_atol[NSTATES] = {'+','.join(map(state_absolute_tolerance, state_keys or ['dummy']))+'};',
+        'const char *const model_output_keys[NOUTPUTS] = {'+(','.join(json.dumps(v.key,ensure_ascii=True) for v in variables) or '""')+'};',
+        *jacobian.source_lines(),
+        *schedule_helpers,
+        'int model_init(double *y) {',*[f'y[{i}]={num(v)};' for i,v in enumerate(initial)],*gas_initializers,'return 1;}',
+        'static int model_eval_internal(double t,const double *y,double *dy,double *w,int canonical,double *friction_drives,NativePropertyTemperatures *temperatures,ModelJacobianWorkspace *jacobian) {',
+        '(void)friction_drives;(void)jacobian;',
+        f'NativePropertyState property_states[{min(256,max(16,4*gas_count+2*len(components)))}];',
+        'NativePropertyCache property_cache, *properties=&property_cache;',
+        'native_properties_init(properties,property_states,sizeof(property_states)/sizeof(property_states[0]));',
+        'properties->temperatures=temperatures;',
+        'properties->jacobian=jacobian?&jacobian->scalars:NULL;',
+        'NativePropertyCache *gas_properties=canonical?NULL:properties;(void)gas_properties;',
+        *(['double projected[NSTATES];for(int i=0;i<NSTATES;i++) projected[i]=y[i];',*project,'y=projected;'] if project else []),
+        f'double p[{np}]={{0}},h[{nq}]={{0}},q[{nq}]={{0}};NativeGas g[{ng}];',
+        f'double fb[{max(1,flow_temporary_count)}]={{0}};(void)fb;',
+        *([f'NativePipeCache pipe_cache[{max(1,pipe_cache_count)}]={{0}};(void)pipe_cache;'] if pneu else []),
+        '(void)t;(void)y;(void)w;(void)p;(void)h;(void)q;(void)g;',*lines,
+        'for(int i=0;i<NSTATES;i++) if(!isfinite(dy[i])) return 0;',
+        'for(int i=0;i<NOUTPUTS;i++) if(!isfinite(w[i])) return 0;','return 1;}',
+        'int model_eval(double t,const double *y,double *dy,double *w) {return model_eval_internal(t,y,dy,w,0,NULL,NULL,NULL);}',
+        'int model_eval_jacobian(double t,const double *y,double *dy,double *w) {return model_eval_internal(t,y,dy,w,1,NULL,NULL,NULL);}',
+        'void model_jacobian_begin(ModelJacobianWorkspace *workspace) {memset(workspace,0,sizeof(*workspace));workspace->scalars.entries=workspace->scalar_entries;workspace->scalars.capacity=MODEL_JACOBIAN_SCALAR_COUNT;workspace->scalars.recording=1;}',
+        'int model_eval_jacobian_reuse(double t,const double *y,double *dy,double *w,ModelJacobianWorkspace *workspace) {int ok=model_eval_internal(t,y,dy,w,1,NULL,NULL,workspace);if(workspace)workspace->scalars.recording=0;return ok;}',
+        'int model_friction_drives(double t,const double *y,double *drives) {double dy[NSTATES],w[NOUTPUTS];return model_eval_internal(t,y,dy,w,0,drives,NULL,NULL);}',
+        'int model_property_temperatures(double t,const double *y,NativePropertyTemperatures *temperatures) {double dy[NSTATES],w[NOUTPUTS];return model_eval_internal(t,y,dy,w,0,NULL,temperatures,NULL);}',
+        'double model_next_break(double t,double end) { double result=end;(void)t;',*breaks,'return result;}',''])
+    header=f'''#ifndef GENERATED_NATIVE_MODEL_H
+#define GENERATED_NATIVE_MODEL_H
+#include "kernels.h"
+#define MODEL_JACOBIAN_GAS_REUSE {int(reuse_enabled)}
+#define MODEL_JACOBIAN_GAS_COUNT {gas_count}
+#define MODEL_JACOBIAN_SCALAR_COUNT 1024
+typedef struct {{ NativeJacobianGasMemo gases[{ng}]; NativeJacobianGasStats stats;
+    NativeJacobianScalars scalars; NativeJacobianScalarEntry scalar_entries[MODEL_JACOBIAN_SCALAR_COUNT]; }} ModelJacobianWorkspace;
+void model_jacobian_begin(ModelJacobianWorkspace *workspace);
+int model_eval_jacobian_reuse(double t,const double *y,double *dy,double *w,ModelJacobianWorkspace *workspace);
+#define MODEL_PROPERTY_TEMPERATURES {int(any(key[1] == 'peng_robinson' for key in media))}
+int model_property_temperatures(double t,const double *y,NativePropertyTemperatures *temperatures);
+#define NSTATES {nstates}
+#define NOUTPUTS {max(1,len(variables))}
+#define NSTOPS {len(stops)}
+#define NFRICTIONS {len(friction_groups)}
+{contact_header}
+extern const NativeFriction model_frictions[{max(1,len(friction_groups))}];
+int model_friction_drives(double t,const double *y,double *drives);
+extern const NativeStop model_stops[{max(1,len(stops))}];
+extern const double model_atol[NSTATES];
+extern const char *const model_output_keys[NOUTPUTS];
+{chr(10).join(jacobian.header_lines(canonical_rhs=True))}
+int model_init(double *y);
+int model_eval(double t,const double *y,double *dy,double *w);
+double model_next_break(double t,double end);
+#endif
+'''
+    return NativeProgram(source,header,tuple(state_keys),variables,tuple(sorted({c.model_type for c in components})),schedule.report(),jacobian_info)

app/simulation/native_codegen/input.py

@@ -0,0 +1,25 @@
+"""CLI input adapter shared with HTTP; numerical execution accepts SI XML only."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import warnings
+
+from app.project_parameters import expression_value as arithmetic_value, prepare_project, version_warning
+from app.system_xml import validate_system_xml_document
+
+
+def project_xml(data: dict) -> bytes:
+    from app.main import ReactFlowProjectPayload, build_reactflow_system_xml
+    normalized, notices = prepare_project(ReactFlowProjectPayload.model_validate(data))
+    if notices:
+        warnings.warn(json.dumps(version_warning(notices), ensure_ascii=False), UserWarning, stacklevel=2)
+    return build_reactflow_system_xml(normalized)
+
+
+def load_input(path: Path):
+    xml = project_xml(json.loads(path.read_text(encoding="utf-8"))) if path.suffix.lower() == ".json" else path.read_bytes()
+    report = validate_system_xml_document(xml)
+    if not report.valid or report.document is None:
+        raise ValueError(f"Invalid simulation XML: {report.as_dict()}")
+    return xml, report.document

app/simulation/native_codegen/jacobian.py

@@ -0,0 +1,214 @@
+"""Conservative state dependencies for compiler-owned expressions.
+
+This is structural bookkeeping, not C parsing or numerical Jacobian evaluation.
+Native multi-output operations, projections and mode-dependent writes must be
+registered explicitly by the lowering path. Unresolved reachable inputs disable
+coloring for the complete model.
+"""
+from collections import deque
+from dataclasses import dataclass
+import hashlib
+import json
+import re
+
+
+# Reviewed expression leaves. Unknown arrays/scalars remain unresolved instead
+# of silently becoming constants; the flow schedule supplies its own explicit IR.
+_ARRAY = re.compile(r'\b[A-Za-z_]\w*\[\d+\](?:\.[A-Za-z_]\w*)?|\bgas_\d+\.[A-Za-z_]\w*')
+_IDENTIFIER = re.compile(r'\b[A-Za-z_]\w*\b')
+_NUMBER = re.compile(r'(?<![\w.])(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?')
+_FUNCTIONS = frozenset({
+    'fmax', 'fmin', 'fabs', 'sqrt', 'copysign', 'pow',
+    'native_signal', 'native_contact', 'native_limit_force', 'native_dry_friction',
+    'native_pipe_flow_context', 'native_pipe_flow_cached_context',
+    'native_temperature_ph_context', 'native_density_context',
+})
+_CONSTANTS = frozenset({'t', 'properties', 'NAN', 'INFINITY', 'NULL', 'true', 'false'})
+
+
+def expression_inputs(expression):
+    """Extract leaves from a reviewed expression; unfamiliar names fail closed."""
+    inputs = set()
+    def leaf(match):
+        key = match.group()
+        # Per-evaluation cache scratch is an implementation detail of reviewed
+        # kernels; each value is determined by that kernel's explicit arguments.
+        if not re.fullmatch(r'pipe_cache\[\d+\]', key):
+            inputs.add(key)
+        return ' '
+    remainder = _ARRAY.sub(leaf, expression)
+    remainder = _NUMBER.sub(' ', remainder)
+    for name in _IDENTIFIER.findall(remainder):
+        if name in _FUNCTIONS or name in _CONSTANTS or re.fullmatch(r'(?:medium|signal)_\d+', name):
+            continue
+        inputs.add(name)
+    return frozenset(inputs)
+
+
+@dataclass(frozen=True)
+class JacobianStructure:
+    state_count: int
+    rows: tuple[tuple[int, ...], ...] = ()
+    colors: tuple[int, ...] = ()
+    reason: str | None = None
+
+    @classmethod
+    def dense(cls, state_count, reason):
+        return cls(state_count, reason=reason)
+
+    @property
+    def enabled(self):
+        return self.reason is None
+
+    @property
+    def color_count(self):
+        return max(self.colors, default=-1) + 1 if self.enabled else self.state_count
+
+    @property
+    def nonzeros(self):
+        return sum(map(len, self.rows)) if self.enabled else self.state_count ** 2
+
+    def manifest(self, *, canonical_rhs=False):
+        # Use proven coloring automatically when it reduces finite-difference
+        # groups; unsupported or unhelpful patterns retain dense differences.
+        runtime_eligible = self.enabled and 0 < self.color_count < self.state_count
+        fallback_reason = None if runtime_eligible else (
+            self.reason or 'Coloring does not reduce finite-difference groups')
+        pattern = {'rows': self.rows, 'columnColors': self.colors}
+        policy = ('CVODE colored forward differences; canonical-property-cache RHS' if canonical_rhs else 'CVODE colored forward differences') if runtime_eligible else 'CVODE default dense differences'
+        return {
+            'policyScope': 'default-runtime',
+            'defaultRuntimePolicy': policy,
+            'verification': '--verify-jacobian',
+            'policy': policy,
+            'rhsPolicy': 'canonical-property-cache finite differences' if canonical_rhs and runtime_eligible else 'ordinary model_eval',
+            'runtimeEligible': runtime_eligible, 'runtimeFallbackReason': fallback_reason,
+            'canonicalRhs': canonical_rhs, 'ordinaryRhsUnchanged': True,
+            'enabled': self.enabled, 'reason': self.reason, 'stateCount': self.state_count,
+            'nonzeros': self.nonzeros, 'density': self.nonzeros / self.state_count ** 2 if self.state_count else 0,
+            'colorCount': self.color_count,
+            'patternSha256': hashlib.sha256(json.dumps(pattern, separators=(',', ':')).encode()).hexdigest() if self.enabled else None,
+            'columnColors': list(self.colors) if self.enabled else None,
+        }
+
+    def header_lines(self, *, canonical_rhs=False):
+        lines = [f'#define MODEL_JACOBIAN_COLORED {int(self.enabled)}',
+                 f'#define MODEL_JACOBIAN_CANONICAL_RHS {int(canonical_rhs)}',
+                 f'#define MODEL_JACOBIAN_COLOR_COUNT {self.color_count}',
+                 f'#define MODEL_JACOBIAN_NNZ {self.nonzeros}']
+        if canonical_rhs:
+            lines += ['int model_eval_jacobian(double t, const double *y, double *dy, double *w);']
+        if self.enabled:
+            lines += ['extern const int model_jacobian_column_color[NSTATES];',
+                      'extern const int model_jacobian_col_ptr[NSTATES+1];',
+                      'extern const int model_jacobian_row_index[MODEL_JACOBIAN_NNZ];']
+        return lines
+
+    def source_lines(self):
+        if not self.enabled:
+            return []
+        columns = [[] for _ in range(self.state_count)]
+        for row, entries in enumerate(self.rows):
+            for column in entries:
+                columns[column].append(row)
+        pointers = [0]
+        indices = []
+        for column in columns:
+            indices.extend(column)
+            pointers.append(len(indices))
+        return [f'const int {name}[{len(values)}] = {{'+','.join(map(str, values))+'};'
+                for name, values in [('model_jacobian_column_color', self.colors),
+                                     ('model_jacobian_col_ptr', pointers),
+                                     ('model_jacobian_row_index', indices)]]
+
+
+class StateDependencies:
+    def __init__(self, state_count):
+        self.state_count = state_count
+        self.seeds = {f'y[{i}]': 1 << i for i in range(state_count)}
+        self.inputs = {}
+
+    def assign(self, target, inputs):
+        # Union repeated writes, rather than dropping dependencies from another
+        # branch or an earlier in-place value (stop motion is mode dependent).
+        self.inputs.setdefault(target, set()).update(inputs)
+
+    def expression(self, target, expression):
+        self.assign(target, expression_inputs(expression))
+
+    def project_states(self, offsets):
+        refs = {f'y[{i}]' for i in offsets}
+        for target in refs:
+            self.assign(target, refs)
+
+    def stop_motion(self, velocity_index, position_index):
+        refs = {f'y[{velocity_index}]', f'y[{position_index}]',
+                f'dy[{velocity_index}]', f'dy[{position_index}]'}
+        for target in (f'dy[{velocity_index}]', f'dy[{position_index}]'):
+            self.assign(target, refs)
+
+    def computation(self, operation):
+        # A schedule SCC reaches a fixed point in build(), so every member gains
+        # every external state dependency even through pressure/stream loops.
+        for output in operation.outputs:
+            self.assign(output, operation.inputs)
+
+    def build(self):
+        if self.state_count == 0:
+            return JacobianStructure.dense(1, 'Algebraic-only internal state uses default differences')
+        required = {f'dy[{i}]' for i in range(self.state_count)}
+        pending = list(required)
+        reachable = set()
+        missing = set()
+        while pending:
+            key = pending.pop()
+            if key in reachable:
+                continue
+            reachable.add(key)
+            if key not in self.inputs and key not in self.seeds:
+                missing.add(key)
+            pending.extend(self.inputs.get(key, ()))
+        if missing:
+            return JacobianStructure.dense(self.state_count,
+                'Unresolved structural inputs: '+', '.join(sorted(missing)[:16]))
+        consumers = {key: set() for key in reachable}
+        for target in reachable:
+            for source in self.inputs.get(target, ()):
+                consumers[source].add(target)
+        masks = dict(self.seeds)
+        queue = deque(key for key in self.seeds if key in reachable)
+        queued = set(queue)
+        while queue:
+            source = queue.popleft()
+            queued.remove(source)
+            for target in consumers[source]:
+                merged = masks.get(target, 0) | masks[source]
+                if merged != masks.get(target, 0):
+                    masks[target] = merged
+                    if target not in queued:
+                        queue.append(target)
+                        queued.add(target)
+        # A diagonal overestimate is safe and keeps isolated/dummy rows valid
+        # without introducing zero-length C arrays or uncolored state columns.
+        rows = tuple(tuple(column for column in range(self.state_count)
+                           if (masks.get(f'dy[{row}]', 0) | (1 << row)) >> column & 1)
+                     for row in range(self.state_count))
+        conflicts = [set() for _ in range(self.state_count)]
+        for entries in rows:
+            for column in entries:
+                conflicts[column].update(set(entries) - {column})
+        colors = {}
+        while len(colors) < self.state_count:
+            column = max((i for i in range(self.state_count) if i not in colors),
+                         key=lambda i: (len({colors[j] for j in conflicts[i] if j in colors}),
+                                        len(conflicts[i]), -i))
+            used = {colors[j] for j in conflicts[column] if j in colors}
+            color = 0
+            while color in used:
+                color += 1
+            colors[column] = color
+        ordered = tuple(colors[i] for i in range(self.state_count))
+        for entries in rows:
+            if len({ordered[column] for column in entries}) != len(entries):
+                raise AssertionError('Jacobian coloring contains a row conflict')
+        return JacobianStructure(self.state_count, rows, ordered)

app/simulation/native_codegen/modules.py

@@ -0,0 +1,36 @@
+"""Reviewed native component module exports and their compilation dependencies."""
+from __future__ import annotations
+
+import re
+
+EXPORTS = {
+    "properties": frozenset({
+        "native_properties_init", "native_temperature_ph_context", "native_density_context",
+        "native_gas_init", "native_gas", "native_gas_context", "native_medium_init",
+        "native_density", "native_temperature_ph", "native_viscosity",
+        "native_medium_gas", "native_medium_gas_context", "native_polytropic_gas_context",
+        "native_jacobian_gas",
+        "native_jacobian_scalar_get", "native_jacobian_scalar_put",
+    }),
+    "orifice": frozenset({"native_orifice", "native_orifice_context", "native_medium_orifice", "native_medium_orifice_context"}),
+    "pipe": frozenset({"native_pipe_resistance", "native_pipe_flow", "native_pipe_flow_context",
+                        "native_pipe_flow_cached", "native_pipe_flow_cached_context",
+                        "native_pipe_diagnostics", "native_pipe_diagnostics_context"}),
+    "mechanics": frozenset({"native_contact", "native_stop_motion", "native_limit_force", "native_dry_friction"}),
+    "signal": frozenset({"native_signal", "native_signal_break"}),
+}
+DEPENDENCIES = {"orifice": ("properties",), "pipe": ("properties",)}
+
+
+def component_modules(source: str) -> tuple[str, ...]:
+    # Generated C refers to these functions directly. Include identifier uses
+    # (also function pointers), conservatively including any comments/strings.
+    identifiers = set(re.findall(r"\bnative_[A-Za-z0-9_]+\b", source))
+    selected = {name for name, exports in EXPORTS.items() if identifiers & exports}
+    pending = list(selected)
+    while pending:
+        for dependency in DEPENDENCIES.get(pending.pop(), ()):
+            if dependency not in selected:
+                selected.add(dependency)
+                pending.append(dependency)
+    return tuple(name for name in EXPORTS if name in selected)

app/simulation/native_codegen/processes.py

@@ -0,0 +1,35 @@
+"""Portable process setup and classification for the native compiler driver.
+
+MinGW maps different CreateProcess failures to ENOENT. That text does not prove
+the compiler/subprogram is missing; never treat a C diagnostic as a launch retry.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import re
+import shutil
+
+IS_WINDOWS = os.name == 'nt'
+LAUNCH_RETRY_DELAYS = (0.05, 0.1, 0.2, 0.35, 0.5)
+
+
+def command_environment(executable: str) -> dict[str, str] | None:
+    if not IS_WINDOWS:
+        return None  # Preserve the Linux toolchain and environment unchanged.
+    env = os.environ.copy()
+    path_key = next((key for key in env if key.upper() == 'PATH'), 'PATH')
+    directory = str(Path(shutil.which(executable) or executable).resolve().parent)
+    env[path_key] = directory + os.pathsep + env.get(path_key, '')
+    return env
+
+
+def is_driver_launch_failure(stderr: str) -> bool:
+    # GCC 8 emits "gcc.exe: error: CreateProcess: ..."; other releases add
+    # "cannot execute 'cc1':". Anchor the driver diagnostic, not source text.
+    return IS_WINDOWS and bool(re.search(
+        r'(?im)^(?:[^\r\n]*[/\\])?[\w.+-]*gcc(?:\.exe)?: (?:fatal )?error: (?:cannot execute [^\r\n]*: )?CreateProcess:', stderr))
+
+
+def is_transient_process_error(exc: OSError) -> bool:
+    return IS_WINDOWS and getattr(exc, 'winerror', None) in (5, 32, 1450, 1455)

app/simulation/native_codegen/property_warnings.py

@@ -0,0 +1,17 @@
+"""User-facing wording shared by live events and saved result diagnostics."""
+
+
+def format_property_warning(warning: dict) -> dict:
+    domains = {
+        "equation-of-state": "状态方程及热力性质的真实气体修正项",
+        "ideal-caloric": "理想气体热容、焓和内能",
+        "dynamic-viscosity": "动力黏度",
+    }
+    high = warning["direction"] == "high"
+    message = (
+        f"氦气物性有效温度越界：{domains[warning['property']]}，"
+        f"t = {warning['time']:.9g} s，T = {warning['temperature']:.9g} K "
+        f"{'>' if high else '<'} {'Tmax' if high else 'Tmin'} = {warning['limit']:.9g} K。"
+        "仿真继续计算，超范围物性不保证有效性。"
+    )
+    return {**warning, "message": message}

app/simulation/native_codegen/result_storage.py

@@ -0,0 +1,327 @@
+"""Quota-controlled, append-only result archives in PROJECT/simresults.
+
+Reservations cover state AND future output blocks before the worker may write.
+A global process lock serializes grants; per-run leases protect active writers.
+Grants are persisted in bounded windows; individual blocks consume local credit
+without scanning history or synchronously rewriting the manifest.
+Only recognized archives are evicted, oldest first. Unknown user files count
+toward the quota but are never deleted. File sizes are logical bytes, not the
+filesystem's allocation-unit overhead.
+"""
+from __future__ import annotations
+
+from contextlib import contextmanager
+import ctypes
+import json
+import os
+from pathlib import Path
+import re
+import stat
+import struct
+import threading
+import time
+from uuid import uuid4
+import zlib
+
+from .cache_storage import acquire_cache_lease, _acquire_lock_file, _reparse, _require_directory
+
+RESULT_ROOT = Path(__file__).resolve().parents[3] / "simresults"
+DEFAULT_LIMIT_BYTES = 1024**3
+_RESERVATION_WINDOW_BYTES = 16 * 1024**2
+_RUN = re.compile(r"run-([0-9a-f]{64})\Z")
+_FILES = frozenset(("manifest.json", "manifest.tmp", "states.bin", "outputs.bin"))
+_HEADER = struct.Struct("<8sQQQQ")
+
+
+class ResultQuotaError(RuntimeError):
+    pass
+
+
+def result_archive_path(result_id: str, *, root: Path | None = None) -> Path:
+    """Locate an archive by ID under this installation's result root.
+
+    Never use a saved absolute directory as a locator: older manifests may
+    contain one from a different machine. Moving a stopped project and starting
+    it again establishes its new root through __file__ above.
+    """
+    if not isinstance(result_id, str) or _RUN.fullmatch(result_id) is None:
+        raise ValueError("Invalid result archive ID.")
+    base = Path(root or RESULT_ROOT).absolute()
+    _require_directory(base)
+    path = base / result_id
+    _require_directory(path)
+    return path
+
+
+def result_limit_bytes() -> int:
+    raw = os.environ.get("SIMULATION_RESULT_STORAGE_MB", str(DEFAULT_LIMIT_BYTES // 1024**2))
+    if not re.fullmatch(r"[0-9]+", raw) or int(raw) < 1:
+        raise ValueError("SIMULATION_RESULT_STORAGE_MB must be a positive integer in MiB.")
+    return int(raw) * 1024**2
+
+
+def _alive(pid: int | None) -> bool:
+    if not pid:
+        return False
+    if os.name == "nt":
+        kernel = ctypes.WinDLL("kernel32", use_last_error=True)
+        kernel.OpenProcess.argtypes = [ctypes.c_ulong, ctypes.c_int, ctypes.c_ulong]
+        kernel.OpenProcess.restype = ctypes.c_void_p
+        kernel.WaitForSingleObject.argtypes = [ctypes.c_void_p, ctypes.c_ulong]
+        kernel.CloseHandle.argtypes = [ctypes.c_void_p]
+        handle = kernel.OpenProcess(0x100000, False, pid)  # SYNCHRONIZE
+        if not handle:
+            return ctypes.get_last_error() == 5  # Access denied: conservatively pin.
+        try:
+            return kernel.WaitForSingleObject(handle, 0) != 0
+        finally:
+            kernel.CloseHandle(handle)
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+
+
+def _size(path: Path) -> int:
+    info = path.lstat()
+    if _reparse(info) or not stat.S_ISDIR(info.st_mode):
+        return info.st_size
+    return sum(_size(child) for child in path.iterdir())
+
+
+def _record(path: Path) -> dict | None:
+    try:
+        info = (path / "manifest.json").lstat()
+        if _reparse(info) or not stat.S_ISREG(info.st_mode):
+            return None
+        data = json.loads((path / "manifest.json").read_bytes())
+        if (data.get("format") != "simulation-blocks-v1" or
+                data.get("id") != path.name or type(data.get("reservedBytes")) is not int or
+                data["reservedBytes"] < 0 or type(data.get("createdAt")) is not int or
+                type(data.get("finishedAt", data["createdAt"])) is not int or
+                data.get("status") not in ("running", "completed", "cancelled", "failed", "interrupted") or
+                (data.get("workerPid") is not None and
+                 (type(data["workerPid"]) is not int or data["workerPid"] <= 0))):
+            return None
+        return data
+    except (OSError, ValueError, AttributeError):
+        return None
+
+
+def scan_blocks(path: Path, *, expected_columns: int | None = None) -> dict:
+    """Validate a committed prefix using bounded reads; ignore an incomplete tail.
+
+    A CRC mismatch is reported as corruption, never a valid sample. This reader
+    works after process termination without loading the trajectory into RAM.
+    """
+    result = {"blocks": 0, "samples": 0, "validBytes": 0, "storedUntil": None,
+              "incompleteTail": False, "corrupt": False}
+    if not path.exists():
+        return result
+    with path.open("rb") as stream:
+        size = os.fstat(stream.fileno()).st_size
+        while stream.tell() < size:
+            raw = stream.read(_HEADER.size)
+            if len(raw) != _HEADER.size:
+                result["incompleteTail"] = True
+                break
+            magic, sequence, rows, columns, expected_crc = _HEADER.unpack(raw)
+            if (magic != b"SIMBLK01" or sequence != result["blocks"] or not 0 < rows <= 1024 or
+                    not columns or (expected_columns is not None and columns != expected_columns)):
+                result["corrupt"] = True
+                break
+            length = rows * columns * 8
+            if length + 8 > size - stream.tell():
+                result["incompleteTail"] = True
+                break
+            # The first column is always time; at most 1024 timestamps.
+            times = stream.read(rows * 8)
+            crc = zlib.crc32(times)
+            remaining = length - len(times)
+            while remaining:
+                block = stream.read(min(65536, remaining))
+                if not block:
+                    raise OSError("Result block changed during inspection.")
+                crc = zlib.crc32(block, crc)
+                remaining -= len(block)
+            if stream.read(8) != b"COMMIT01" or crc != expected_crc:
+                result["corrupt"] = True
+                break
+            result["blocks"] += 1
+            result["samples"] += rows
+            result["validBytes"] = stream.tell()
+            result["storedUntil"] = struct.unpack_from("<d", times, len(times) - 8)[0]
+    return result
+
+
+class ResultArchive:
+    def __init__(self, metadata: dict, *, root: Path | None = None, limit_bytes: int | None = None):
+        self.root = Path(root or RESULT_ROOT).absolute()
+        _require_directory(self.root, create=True)
+        self.limit = result_limit_bytes() if limit_bytes is None else limit_bytes
+        if self.limit <= 0:
+            raise ValueError("Result quota must be positive.")
+        self.key = uuid4().hex + uuid4().hex
+        self.path = self.root / ("run-" + self.key)
+        self.lease = acquire_cache_lease(self.root, "models", self.key)
+        self.closed = False
+        self._mutex = threading.RLock()
+        self._credit = 0
+        # This is accounting credit, not an allocated memory/disk buffer. Bound
+        # speculative grants for small quotas and concurrent simulations.
+        self._reservation_window = min(_RESERVATION_WINDOW_BYTES, self.limit // 16)
+        self.data = {"format": "simulation-blocks-v1", "id": self.path.name,
+                     "createdAt": time.time_ns(), "status": "running", "workerPid": None,
+                     "metadata": metadata, "reservedBytes": 0}
+        # Covers final scalars, JSON framing and both copies during atomic update.
+        self.metadata_budget = max(65536, len(json.dumps(self.data).encode()) * 8)
+        self.data["reservedBytes"] = self.metadata_budget
+        try:
+            with self._locked():
+                self._make_room(self.metadata_budget)
+                self.path.mkdir()
+                self._publish()
+        except BaseException:
+            self.lease.close()
+            raise
+
+    @contextmanager
+    def _locked(self):
+        with _acquire_lock_file(self.root, "models", "0" * 64, "results-quota.lock",
+                                exclusive=True, blocking=True):
+            yield
+
+    def _publish(self):
+        encoded = json.dumps(self.data, ensure_ascii=False, allow_nan=False,
+                             separators=(",", ":")).encode("utf-8")
+        if len(encoded) * 2 > self.metadata_budget:
+            raise ResultQuotaError("Result metadata exceeded its reserved space.")
+        temporary = self.path / "manifest.tmp"
+        with temporary.open("wb") as stream:
+            stream.write(encoded)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, self.path / "manifest.json")
+
+    def _make_room(self, extra: int) -> int:
+        """Make room for required bytes and return free bytes BEFORE this grant.
+
+        Caller holds the global quota lock through publishing the reservation.
+        Optional ahead-of-write credit must never trigger extra eviction.
+        """
+        usage = 0
+        candidates = []
+        for path in self.root.iterdir():
+            info = path.lstat()
+            actual = _size(path)
+            match = _RUN.fullmatch(path.name)
+            record = (_record(path) if match and stat.S_ISDIR(info.st_mode) and not _reparse(info) else None)
+            if record is None:
+                usage += actual
+                continue
+            lease = acquire_cache_lease(self.root, "models", match[1], exclusive=True, blocking=False)
+            active = lease is None or (record.get("status") == "running" and _alive(record.get("workerPid")))
+            if lease is not None:
+                lease.close()
+            usage += max(actual, record["reservedBytes"]) if active else actual
+            if not active and path != self.path:
+                candidates.append((record.get("finishedAt", record["createdAt"]), path, match[1], actual))
+        if usage + extra <= self.limit:
+            return self.limit - usage
+        for _, path, key, actual in sorted(candidates):
+            lease = acquire_cache_lease(self.root, "models", key, exclusive=True, blocking=False)
+            if lease is None:
+                continue
+            with lease:
+                # No recursive deletion, links, unknown files, or paths outside
+                # the configured root. User-owned additions prevent eviction.
+                if path.resolve().parent != self.root.resolve():
+                    continue
+                files = list(path.iterdir())
+                if any(p.name not in _FILES or _reparse(p.lstat()) or
+                       not stat.S_ISREG(p.lstat().st_mode) for p in files):
+                    continue
+                for item in files:
+                    item.unlink()
+                path.rmdir()
+                usage -= actual
+            if usage + extra <= self.limit:
+                return self.limit - usage
+        raise ResultQuotaError("Result storage quota exhausted; active runs and unrelated files were retained.")
+
+    def worker_started(self, pid: int):
+        with self._mutex, self._locked():
+            self._ensure_open()
+            self.data["workerPid"] = pid
+            self._publish()
+
+    def _ensure_open(self):
+        if self.closed:
+            raise OSError("Result archive is closed.")
+
+    def reserve(self, amount: int):
+        if type(amount) is not int or not 0 < amount <= self.limit:
+            raise ResultQuotaError("Invalid or oversized result block reservation.")
+        with self._mutex:
+            self._ensure_open()
+            if amount <= self._credit:
+                self._credit -= amount
+                return
+            needed = amount - self._credit
+            with self._locked():
+                available = self._make_room(needed)
+                grant = min(available, max(needed, self._reservation_window))
+                previous = self.data["reservedBytes"]
+                self.data["reservedBytes"] += grant
+                try:
+                    # Publish BEFORE granting permission to write, so another
+                    # process (or an orphan worker) cannot reuse our quota.
+                    self._publish()
+                except BaseException:
+                    self.data["reservedBytes"] = previous
+                    raise
+                self._credit += grant - amount
+
+    def finish(self, payload: dict | None = None, error: str | None = None) -> dict:
+        with self._mutex:
+            self._ensure_open()
+            return self._finish(payload, error)
+
+    def _finish(self, payload: dict | None, error: str | None) -> dict:
+        try:
+            metadata = self.data["metadata"]
+            states = scan_blocks(self.path / "states.bin",
+                                 expected_columns=len(metadata["stateColumns"]) if "stateColumns" in metadata
+                                 else max(1, len(metadata["stateKeys"])) + 1 if "stateKeys" in metadata else None)
+            outputs = scan_blocks(self.path / "outputs.bin",
+                                  expected_columns=len(metadata["outputColumns"]) if "outputColumns" in metadata
+                                  else max(1, len(metadata["variables"])) + 1 if "variables" in metadata else None)
+            status = payload.get("status", "failed") if payload is not None else "interrupted"
+            if states["corrupt"] or outputs["corrupt"]:
+                status = "failed"
+            summary = {"id": self.path.name, "directory": f"simresults/{self.path.name}",
+                       "directoryBase": "project", "limitBytes": self.limit,
+                       "status": status, "states": states, "outputs": outputs}
+            with self._locked():
+                # Release unused ahead-of-write credit even if a result reader
+                # subsequently pins this completed archive with a shared lease.
+                self.data["reservedBytes"] -= self._credit
+                self._credit = 0
+                self.data.update(status=status, finishedAt=time.time_ns(), blocks=summary,
+                                 error=error, workerPid=None)
+                if payload is not None:
+                    self.data["result"] = {k: v for k, v in payload.items()
+                                           if k not in ("series", "buildDetails", "resultStorage")}
+                self._publish()
+            return summary
+        finally:
+            self.closed = True
+            self.lease.close()
+
+    def close(self):
+        with self._mutex:
+            if not self.closed:
+                self.finish(error="Execution ended before a result was returned.")

app/simulation/native_codegen/runner.py

@@ -0,0 +1,260 @@
+"""Isolated native numerical execution; Python only handles process I/O."""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import queue
+import subprocess
+import tempfile
+import threading
+import time
+
+from app.simulation.config import SolveIVPConfig
+from app.simulation.results import GenericSimulationResult
+from .transport import NativeSeriesJson, read_indexed_result
+from .build import NativeBuild, build_native
+from .compiler import NativeCapabilityError, compile_native_program
+from .result_storage import ResultArchive, ResultQuotaError
+from .property_warnings import format_property_warning
+
+_WORKER_SHUTDOWN_GRACE_SECONDS = 5.0
+
+
+def execute_native(build: NativeBuild, config: SolveIVPConfig, sample_step: float, *,
+                   run_dir: Path, record_samples=True, cancel_check=None,
+                   progress_callback=None, warning_callback=None, activity_tracker=None, timeout=300.0, raw_series=False) -> dict:
+    # Reject unsupported calls before allocating quota or evicting any history.
+    if config.method not in ("RK45", "BDF"):
+        raise NativeCapabilityError(f"Native v1 does not support method {config.method}.")
+    if not isinstance(config.atol, (int, float)) or config.atol != 1e-8 or config.first_step is not None:
+        raise NativeCapabilityError("Native uses generated per-state absolute tolerances and automatic initial step; custom config.atol/first_step are not supported.")
+    if any((run_dir / name).exists() for name in ("result.json", "cancel.request", "result-index.json")):
+        raise ValueError("Native execution requires a fresh run directory.")
+    archive = None
+    if record_samples:
+        metadata = {key: build.manifest[key] for key in ("buildKey", "stateKeys", "variables")
+                    if key in build.manifest}
+        if "stateKeys" in metadata:
+            # Algebraic-only models carry one private constant integrator state.
+            metadata["stateColumns"] = ["time", *(metadata["stateKeys"] or [None])]
+        if "variables" in metadata:
+            metadata["outputColumns"] = ["time", *([v["key"] for v in metadata["variables"]] or [""])]
+        metadata["simulation"] = {"method": config.method, "start": config.t_start,
+                                  "stop": config.t_stop, "sampleStep": sample_step,
+                                  "maxStep": config.max_step, "rtol": config.rtol}
+        archive = ResultArchive(metadata)
+    try:
+        payload = _execute_native(build, config, sample_step, run_dir=run_dir,
+            record_samples=record_samples, cancel_check=cancel_check,
+            progress_callback=progress_callback, warning_callback=warning_callback, activity_tracker=activity_tracker,
+            timeout=timeout, raw_series=raw_series, archive=archive)
+        if archive is not None:
+            payload["resultStorage"] = archive.finish(payload)
+        return payload
+    except BaseException as exc:
+        if archive is not None and not archive.closed:
+            try:
+                archive.finish(error=str(exc))
+            except Exception as storage_error:
+                exc.add_note(f"Could not finalize result archive: {storage_error}")
+        raise
+    finally:
+        if archive is not None:
+            archive.close()
+
+
+def _execute_native(build: NativeBuild, config: SolveIVPConfig, sample_step: float, *,
+                    run_dir: Path, record_samples=True, cancel_check=None,
+                    progress_callback=None, warning_callback=None, activity_tracker=None, timeout=300.0, raw_series=False,
+                    archive: ResultArchive | None = None) -> dict:
+    run_dir.mkdir(parents=True, exist_ok=True)
+    output = run_dir / "result.json"
+    cancel_path = run_dir / "cancel.request"
+    index_path = run_dir / "result-index.json"
+    command = [str(build.executable), "--method", config.method,
+               "--start", str(config.t_start), "--stop", str(config.t_stop),
+               "--sample-step", str(sample_step), "--max-step", str(config.max_step),
+               "--rtol", str(config.rtol), "--timeout", str(timeout),
+               "--cancel-file", str(cancel_path.resolve()), "--output", str(output.resolve())]
+    if raw_series:
+        command.extend(["--result-index", str(index_path.resolve())])
+    if not record_samples:
+        command.append("--solve-only")
+    if archive is not None:
+        command.extend(["--sample-file", str(archive.path / "states.bin"),
+                        "--output-block-file", str(archive.path / "outputs.bin"), "--storage-control"])
+    creationflags = subprocess.CREATE_NO_WINDOW if os.name == "nt" else 0
+    started = time.perf_counter()
+    # A fast worker may finish before the monitor's first iteration. Honor a
+    # cancellation already requested during preparation before spawning it.
+    cancelled_at = started if cancel_check is not None and cancel_check() else None
+    if cancelled_at is not None:
+        cancel_path.write_text("cancel\n", encoding="ascii")
+    process = subprocess.Popen(command, cwd=build.executable.parent,
+                               stdin=subprocess.PIPE if archive is not None else subprocess.DEVNULL,
+                               stdout=subprocess.DEVNULL, stderr=subprocess.PIPE,
+                               text=True, encoding="utf-8", errors="replace", creationflags=creationflags)
+    messages: queue.Queue[str] = queue.Queue(maxsize=128)
+    reader_stop = threading.Event()
+    def read_stderr():
+        assert process.stderr is not None
+        for line in process.stderr:
+            while not reader_stop.is_set():
+                try:
+                    messages.put(line, timeout=.1)
+                    break
+                except queue.Full:
+                    continue
+            if reader_stop.is_set():
+                break
+    reader = threading.Thread(target=read_stderr, daemon=True)
+    reader.start()
+    last_time = config.t_start
+    last_nfev = last_accepted = 0
+    forced_cancel = False
+    property_warnings = []
+    try:
+        if archive is not None:
+            archive.worker_started(process.pid)
+        if activity_tracker is not None:
+            activity_tracker.start_integration(config.t_start)
+        with (run_dir / "worker.log").open("w", encoding="utf-8") as log:
+            while process.poll() is None or not messages.empty() or reader.is_alive():
+                now = time.perf_counter()
+                if cancel_check is not None and cancel_check() and cancelled_at is None:
+                    cancel_path.write_text("cancel\n", encoding="ascii")
+                    cancelled_at = now
+                cancellation_expired = (cancelled_at is not None and
+                                        now-cancelled_at > _WORKER_SHUTDOWN_GRACE_SECONDS)
+                deadline_expired = timeout > 0 and now-started > timeout+_WORKER_SHUTDOWN_GRACE_SECONDS
+                if process.poll() is None and (cancellation_expired or deadline_expired):
+                    process.kill()
+                    process.wait(timeout=5)
+                    if cancelled_at is not None:
+                        forced_cancel = True
+                        break
+                    raise RuntimeError("Native worker time limit expired; the unresponsive process was terminated before it returned results.")
+                try:
+                    line = messages.get(timeout=0.05)
+                except queue.Empty:
+                    continue
+                log.write(line)
+                try:
+                    event = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                if event.get("phase") == "storage-reserve" and archive is not None:
+                    reply = "ok\n"
+                    try:
+                        archive.reserve(event.get("bytes"))
+                    except ResultQuotaError as exc:
+                        reply = "full\n"
+                        log.write(f"Result storage reservation failed: {exc}\n")
+                    except OSError as exc:
+                        reply = "io\n"
+                        log.write(f"Result storage I/O failed: {exc}\n")
+                    try:
+                        process.stdin.write(reply)
+                        process.stdin.flush()
+                    except (BrokenPipeError, OSError):
+                        if process.poll() is None:
+                            raise
+                    continue
+                if event.get("phase") == "property-warning":
+                    warning = format_property_warning(event["warning"])
+                    property_warnings.append(warning)
+                    if warning_callback:
+                        warning_callback(warning)
+                    continue
+                if event.get("phase") == "integrating":
+                    last_time = max(last_time, min(config.t_stop, float(event["time"])))
+                    last_nfev = int(event["nfev"])
+                    last_accepted = int(event["acceptedSteps"])
+                    if progress_callback:
+                        progress_callback((last_time-config.t_start)/(config.t_stop-config.t_start), "integrating")
+                    if activity_tracker is not None:
+                        activity_tracker.record_native_progress(last_time, int(event["nfev"]), int(event["acceptedSteps"]))
+    finally:
+        if process.poll() is None:
+            process.kill()
+        process.wait(timeout=5)
+        reader_stop.set()
+        reader.join(timeout=2)
+        if process.stdin is not None:
+            process.stdin.close()
+        if process.stderr is not None:
+            process.stderr.close()
+    if forced_cancel:
+        # A killed worker cannot publish trustworthy result artifacts. Retain
+        # only its last progress report; do not invent a trajectory or totals.
+        payload = {
+            "success": False, "status": "cancelled",
+            "message": "Simulation cancelled; the unresponsive worker was terminated. No complete result artifact is available; time and counters are the last reported progress.",
+            "backend": "native-c", "method": config.method,
+            "simulatedUntil": last_time, "nfev": last_nfev, "acceptedSteps": last_accepted,
+            "series": {}, "final": {}, "finalState": [],
+            "solverControl": {"reason": "cancelled", "operation": "worker-termination",
+                              "forcedTermination": True, "workerExitCode": process.returncode,
+                              "resultAvailable": False, "statisticsComplete": False},
+        }
+    else:
+        if not output.is_file():
+            raise RuntimeError(f"Native worker exited with code {process.returncode} without results; see {run_dir / 'worker.log'}.")
+        if process.returncode not in (0, 2):
+            raise RuntimeError(f"Native worker failed with exit code {process.returncode}.")
+        try:
+            payload = (read_indexed_result(output, index_path) if raw_series
+                       else json.loads(output.read_text(encoding="utf-8")))
+        except OSError as exc:
+            raise RuntimeError(f"Cannot read native worker result artifacts: {exc}") from exc
+    payload["propertyWarnings"] = (
+        property_warnings if forced_cancel else
+        [format_property_warning(w) for w in payload.get("propertyWarnings", [])])
+    payload["processWallSeconds"] = time.perf_counter()-started
+    payload["buildKey"] = build.manifest["buildKey"]
+    payload["cacheHit"] = build.cache_hit
+    payload["buildSeconds"] = build.seconds
+    payload["buildDetails"] = build.details
+    if activity_tracker is not None:
+        activity_tracker.record_native_progress(payload["simulatedUntil"], payload["nfev"], payload["acceptedSteps"])
+    return payload
+
+
+def simulate_native(network, config, *, sample_step, progress_callback=None,
+                    warning_callback=None, cancel_check=None, activity_tracker=None, raw_series=False):
+    if config.method not in ("RK45", "BDF"):
+        raise NativeCapabilityError(f"Native v1 does not support method {config.method}.")
+    if progress_callback:
+        progress_callback(0.0, "native-generation")
+    program = compile_native_program(network)
+    build = build_native(program, progress_callback=(
+        (lambda phase: progress_callback(0.0, phase)) if progress_callback else None
+    ))
+    try:
+        with tempfile.TemporaryDirectory(prefix="native-simulation-") as directory:
+            data = execute_native(build, config, sample_step, run_dir=Path(directory),
+                                  cancel_check=cancel_check, progress_callback=progress_callback,
+                                  warning_callback=warning_callback,
+                                  activity_tracker=activity_tracker, raw_series=raw_series)
+    finally:
+        # Keep the executable pinned through process exit and result reading;
+        # only then may cache eviction reclaim this completed model version.
+        build.close()
+    totals = {target: data[source] for source, target in (
+        ("nfev", "nfev"), ("njev", "njev"), ("nlu", "nlu"),
+        ("acceptedSteps", "acceptedStepCount"), ("rejectedSteps", "rejectedStepCount"),
+        ("stateTransitions", "stateTransitionCount"), ("solverStarts", "solverStartCount"),
+    ) if source in data}
+    if progress_callback:
+        fraction = (data["simulatedUntil"]-config.t_start)/(config.t_stop-config.t_start)
+        progress_callback(fraction, "complete" if data["success"] else data["status"])
+    return GenericSimulationResult(
+        success=data["success"], status=data["status"], message=data["message"],
+        simulated_until=data["simulatedUntil"], requested_stop_time=config.t_stop,
+        variables=program.variables, series=data["series"], final=data["final"],
+        diagnostics={"backend": "native-c", "propertyWarnings": data.get("propertyWarnings", []), "native": {k: v for k, v in data.items()
+                     if k not in ("series", "final", "finalState")}, "integration": {"method": config.method, "rtol": config.rtol, "totals": totals},
+                     "stateCount": len(program.state_keys), "sampleCount": (data["series"].sample_count if isinstance(data["series"], NativeSeriesJson)
+                                     else len(data["series"].get("time", [])))},
+    )

app/simulation/native_codegen/schedule.py

@@ -0,0 +1,257 @@
+"""Dependency ordering and local algebraic blocks for generated C expressions.
+
+This module only arranges reviewed C computations. It never evaluates a model
+numerically and has no dependency on the retired Python numerical backend.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import heapq
+import re
+
+from .compiler import NativeCapabilityError
+
+
+# Only compiler-owned array expressions are inspected, never arbitrary user C.
+_REFERENCE = re.compile(r"\b(?:[phqw]|fb)\[\d+\]|\bg\[\d+\]\.[A-Za-z_]\w*")
+
+
+def references(expression: str) -> frozenset[str]:
+    return frozenset(_REFERENCE.findall(expression))
+
+
+@dataclass(frozen=True)
+class Computation:
+    key: str
+    outputs: tuple[str, ...]
+    inputs: frozenset[str]
+    code: tuple[str, ...]
+    kind: str = "flow"
+    residual: str | None = None
+
+    @classmethod
+    def assignment(cls, key, target, expression, kind="flow"):
+        return cls(key, (target,), references(expression), (f'{target}={expression};',), kind)
+
+
+@dataclass(frozen=True)
+class Block:
+    members: tuple[int, ...]
+    cyclic: bool
+
+
+class EvaluationSchedule:
+    def __init__(self, computations, known, labels=None):
+        self.computations = tuple(computations)
+        self.labels = labels or {}
+        self.producers = {}
+        for i, op in enumerate(self.computations):
+            for output in op.outputs:
+                if output in self.producers:
+                    raise NativeCapabilityError(f'Multiple native producers for {self.label(output)}')
+                self.producers[output] = i
+        # An iterative initial guess is not a known source if an equation owns it.
+        used = set().union(*(op.inputs for op in self.computations)) if self.computations else set()
+        self.known = {key: value for key, value in known.items() if key not in self.producers and key in used}
+        self.dependencies = []
+        for op in self.computations:
+            missing = op.inputs - self.producers.keys() - self.known.keys()
+            if missing:
+                raise NativeCapabilityError(f'{op.key}: missing native input sources: {sorted(map(self.label, missing))}')
+            self.dependencies.append({self.producers[key] for key in op.inputs if key in self.producers})
+        self.blocks = self._blocks()
+
+    def label(self, key):
+        return self.labels.get(key, key)
+
+    def _blocks(self):
+        """Iterative SCC discovery followed by deterministic topological order."""
+        count = len(self.computations)
+        consumers = [set() for _ in range(count)]
+        for target, sources in enumerate(self.dependencies):
+            for source in sources:
+                consumers[source].add(target)
+        visited, finish = set(), []
+        for start in range(count):
+            if start in visited:
+                continue
+            visited.add(start)
+            stack = [(start, iter(sorted(consumers[start])))]
+            while stack:
+                node, edges = stack[-1]
+                child = next(edges, None)
+                if child is None:
+                    finish.append(node)
+                    stack.pop()
+                elif child not in visited:
+                    visited.add(child)
+                    stack.append((child, iter(sorted(consumers[child]))))
+        groups, owner = [], {}
+        for start in reversed(finish):
+            if start in owner:
+                continue
+            index = len(groups)
+            owner[start] = index
+            members, stack = [], [start]
+            while stack:
+                node = stack.pop()
+                members.append(node)
+                for child in sorted(self.dependencies[node]):
+                    if child not in owner:
+                        owner[child] = index
+                        stack.append(child)
+            groups.append(tuple(sorted(members)))
+        incoming = [set() for _ in groups]
+        outgoing = [set() for _ in groups]
+        for target, sources in enumerate(self.dependencies):
+            for source in sources:
+                a, b = owner[source], owner[target]
+                if a != b:
+                    incoming[b].add(a)
+                    outgoing[a].add(b)
+        ready = [(min(groups[i]), i) for i, inputs in enumerate(incoming) if not inputs]
+        heapq.heapify(ready)
+        blocks = []
+        while ready:
+            _, index = heapq.heappop(ready)
+            members = groups[index]
+            cyclic = len(members) > 1 or members[0] in self.dependencies[members[0]]
+            blocks.append(Block(members, cyclic))
+            for child in sorted(outgoing[index]):
+                incoming[child].remove(index)
+                if not incoming[child]:
+                    heapq.heappush(ready, (min(groups[child]), child))
+        return tuple(blocks)
+
+    def ordered_subset(self, members):
+        """Order a trial's computations while pressure/stream guesses are fixed."""
+        pending = set(members)
+        result = []
+        while pending:
+            ready = sorted(i for i in pending if not self.dependencies[i] & pending)
+            if not ready:
+                raise NativeCapabilityError('Unsupported cycle within native flow expressions')
+            result.extend(ready)
+            pending.difference_update(ready)
+        return result
+
+    def ancestors(self, inputs, allowed):
+        pending = [self.producers[key] for key in inputs if key in self.producers]
+        found = set()
+        while pending:
+            index = pending.pop()
+            if index in found or index not in allowed:
+                continue
+            found.add(index)
+            pending.extend(self.dependencies[index])
+        return self.ordered_subset(found)
+
+    def report(self):
+        result = []
+        sources = {key: {str(origin)} for key, origin in self.known.items()}
+        for block in self.blocks:
+            outputs = {key for i in block.members for key in self.computations[i].outputs}
+            inputs = {key for i in block.members for key in self.computations[i].inputs} - outputs
+            origins = set().union(*(sources[key] for key in inputs)) if inputs else set()
+            for key in outputs:
+                sources[key] = origins
+            result.append({
+                'cyclic': block.cyclic,
+                'inputs': sorted(map(self.label, inputs)),
+                'outputs': sorted(map(self.label, outputs)),
+                'origins': sorted(origins),
+                'operations': [self.computations[i].key for i in block.members],
+                'pressureUnknowns': [self.label(key) for i in block.members
+                                     if self.computations[i].kind == 'pressure'
+                                     for key in self.computations[i].outputs],
+            })
+        return {
+            'strategy': 'dependency-blocks',
+            'operationCount': len(self.computations),
+            'cyclicBlockCount': sum(b.cyclic for b in self.blocks),
+            'knownSources': {self.label(key): value for key, value in self.known.items()},
+            'blocks': result,
+            'operations': [{'key': op.key, 'kind': op.kind,
+                            'inputs': sorted(map(self.label, op.inputs)),
+                            'outputs': list(map(self.label, op.outputs))}
+                           for op in self.computations],
+        }
+
+    def emit(self):
+        """Return C helper definitions and a straight-line/local-block schedule.
+
+        Existing scalar pressure bisection and stream convergence tolerances are
+        retained. Only the computations in the relevant SCC participate in each
+        closure; a pressure trial further restricts work to its residual inputs.
+        """
+        helpers, lines = [], []
+        args = 'p,h,g,w,q,fb,pipe_cache,properties'
+        signature = ('double *p,double *h,const NativeGas *g,double *w,double *q,'
+                     'double *fb,NativePipeCache *pipe_cache,NativePropertyCache *properties')
+
+        def code(indices):
+            return [line for i in indices for line in
+                    (f'/* schedule operation {i}: {self.computations[i].kind} */', *self.computations[i].code)]
+
+        def helper(name, indices):
+            helpers.extend([f'static int {name}({signature}) {{',
+                            '(void)p;(void)h;(void)g;(void)w;(void)q;(void)fb;(void)pipe_cache;(void)properties;',
+                            *code(indices), 'return 1;', '}'])
+            return f'if(!{name}({args})) return 0;'
+
+        for number, block in enumerate(self.blocks):
+            if not block.cyclic:
+                if self.computations[block.members[0]].kind == 'pressure':
+                    raise NativeCapabilityError('Pressure balance has no pressure-dependent flow relation')
+                lines.extend(code(block.members))
+                continue
+            pressures = [i for i in block.members if self.computations[i].kind == 'pressure']
+            streams = [i for i in block.members if self.computations[i].kind in ('stream', 'alias')]
+            flows = set(block.members) - set(pressures) - set(streams)
+            if all(self.computations[i].kind == 'alias' for i in block.members):
+                raise NativeCapabilityError('Enthalpy reference cycle has no thermodynamic source: ' +
+                                            ', '.join(self.computations[i].key for i in block.members))
+            refresh = helper(f'model_block_{number}_flows', self.ordered_subset(flows)) if flows else ''
+            lines.append(f'{{ /* local algebraic block {number} */')
+            hvars = [key for i in streams for key in self.computations[i].outputs]
+            outputs = {key for i in block.members for key in self.computations[i].outputs}
+            inputs = sorted({key for i in block.members for key in self.computations[i].inputs} - outputs)
+            if hvars:
+                seeds = [key for key in inputs if key.startswith('h[') or key.endswith('.h')]
+                if not seeds:
+                    raise NativeCapabilityError('Local stream loop has no supplied thermodynamic state')
+                lines.extend([*[f'{key}={seeds[0]};' for key in hvars], 'int closure_ok=0;',
+                              f'for(int closure=0;closure<{max(64,4*len(hvars))};closure++) {{',
+                              'double previous[]={' + ','.join(hvars) + '};'])
+            if pressures:
+                pressure_bounds = [key for key in inputs if key.startswith('p[') or key.endswith('.p')]
+                if not pressure_bounds:
+                    raise NativeCapabilityError('Local pressure block has no pressure boundary')
+                lines.extend(['double plo=INFINITY,phi=0;',
+                              *[f'plo=fmin(plo,{p});phi=fmax(phi,{p});' for p in pressure_bounds],
+                              *[f'{self.computations[i].outputs[0]}=.5*(plo+phi);' for i in pressures],
+                              'int pressure_ok=0;', 'for(int sweep=0;sweep<256;sweep++) {'])
+                for i in pressures:
+                    op = self.computations[i]
+                    p = op.outputs[0]
+                    trial = helper(f'model_block_{number}_pressure_{i}', self.ancestors(op.inputs, flows))
+                    lines.extend(['{ double lo=plo,hi=phi;', 'for(int bisect=0;bisect<48;bisect++) {',
+                                  f'{p}=.5*(lo+hi);', trial,
+                                  f'double balance={op.residual};if(!isfinite(balance)) return 0;',
+                                  f'if(balance>0) hi={p};else lo={p};', '}}'])
+                lines.extend([refresh, 'double residual=0;',
+                              *[f'{{double balance={self.computations[i].residual};if(!isfinite(balance)) return 0;residual=fmax(residual,fabs(balance));}}' for i in pressures],
+                              'if(residual<1e-11) {pressure_ok=1;break;}', '}',
+                              'if(!pressure_ok) return 0;'])
+            elif refresh:
+                lines.append(refresh)
+            if hvars:
+                # Gauss-Seidel within a genuine stream loop, in stable emission order.
+                lines.extend([*code(streams), 'double change=0;',
+                              *[line for j,key in enumerate(hvars) for line in
+                                (f'if(!isfinite({key})) return 0;',
+                                 f'change=fmax(change,fabs({key}-previous[{j}])/fmax(1,fabs({key})));')],
+                              'if(change<1e-12) {closure_ok=1;break;}', '}',
+                              'if(!closure_ok) return 0;', refresh])
+            lines.append('}')
+        return helpers, lines

app/simulation/native_codegen/self_test.py

@@ -0,0 +1,208 @@
+"""Small, uncached compile/link/run check using the production native toolchain."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import shutil
+import signal
+import subprocess
+import tempfile
+from threading import Event
+from time import monotonic
+from typing import Callable
+
+from .build import CACHE, NativeCommandError, link_library_arguments, platform_build_inputs, toolchain
+from .processes import command_environment, is_driver_launch_failure
+
+STAGE_MESSAGES = {
+    "toolchain": "正在查找编译器与 SUNDIALS",
+    "preparing": "正在准备最小自检程序",
+    "preprocessing": "正在预处理最小自检程序",
+    "compiling": "正在编译最小自检程序",
+    "linking": "正在链接最小自检程序",
+    "running": "正在运行最小自检程序",
+    "schema": "正在检查模型 XML 解析环境",
+}
+OUTPUT_MARKER = "native-runtime-check-ok"
+# One smooth scalar equation exercises every library used by production BDF.
+# Its known answer is independent of the user's model and cannot hit model cache.
+SOURCE = r'''
+#include <cvode/cvode.h>
+#include <cvode/cvode_ls.h>
+#include <nvector/nvector_serial.h>
+#include <sunmatrix/sunmatrix_dense.h>
+#include <sunlinsol/sunlinsol_dense.h>
+#include <math.h>
+#include <stdio.h>
+static int rhs(sunrealtype t, N_Vector y, N_Vector dy, void *data) {
+    (void)t; (void)data;
+    NV_Ith_S(dy,0)=-NV_Ith_S(y,0);
+    return 0;
+}
+int main(void) {
+    SUNContext context=NULL;
+    N_Vector y=NULL;
+    SUNMatrix matrix=NULL;
+    SUNLinearSolver linear=NULL;
+    void *solver=NULL;
+    int result=1;
+    sunrealtype time=0;
+    if (SUNContext_Create(SUN_COMM_NULL,&context)) goto done;
+    y=N_VNew_Serial(1,context);
+    if (!y) goto done;
+    NV_Ith_S(y,0)=1;
+    matrix=SUNDenseMatrix(1,1,context);
+    if (!matrix) goto done;
+    linear=SUNLinSol_Dense(y,matrix,context);
+    solver=CVodeCreate(CV_BDF,context);
+    if (!linear || !solver) goto done;
+    if (CVodeInit(solver,rhs,0,y)<0 ||
+        CVodeSStolerances(solver,1e-8,1e-10)<0 ||
+        CVodeSetLinearSolver(solver,linear,matrix)<0 ||
+        CVode(solver,0.1,y,&time,CV_NORMAL)<0) goto done;
+    if (!isfinite(NV_Ith_S(y,0)) || fabs(NV_Ith_S(y,0)-exp(-0.1))>1e-6) goto done;
+    puts("native-runtime-check-ok");
+    result=0;
+done:
+    if (result) fputs("Minimal BDF self-check failed.\n",stderr);
+    if (solver) CVodeFree(&solver);
+    if (linear) SUNLinSolFree(linear);
+    if (matrix) SUNMatDestroy(matrix);
+    if (y) N_VDestroy(y);
+    if (context) SUNContext_Free(&context);
+    return result;
+}
+'''
+
+
+class CheckCancelled(Exception):
+    pass
+
+
+class CheckFailure(RuntimeError):
+    def __init__(self, message: str, *, command=(), cwd=None, exit_code=None,
+                 stdout="", stderr="", error_type="RuntimeError"):
+        super().__init__(message)
+        self.details = {"command": list(command), "cwd": str(cwd) if cwd else None,
+                        "exitCode": exit_code, "stdout": stdout[-8000:],
+                        "stderr": stderr[-8000:], "errorType": error_type}
+
+
+def _stop_process_tree(process: subprocess.Popen) -> None:
+    # GCC starts cc1/as/ld. Killing only its driver can leave inherited pipes open.
+    if os.name == "nt":
+        try:
+            subprocess.run(["taskkill", "/PID", str(process.pid), "/T", "/F"],
+                           stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
+                           stderr=subprocess.DEVNULL, timeout=5,
+                           creationflags=subprocess.CREATE_NO_WINDOW)
+        except (OSError, subprocess.SubprocessError):
+            pass
+        if process.poll() is None:
+            process.kill()
+    else:
+        try:
+            os.killpg(process.pid, signal.SIGKILL)
+        except ProcessLookupError:
+            pass
+
+
+def _command(command: list[str], directory: Path, stop: Event, timeout: float = 30) -> str:
+    if stop.is_set():
+        raise CheckCancelled()
+    try:
+        with subprocess.Popen(command, cwd=directory, stdin=subprocess.DEVNULL,
+                              stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                              env=command_environment(command[0]), close_fds=True,
+                              start_new_session=os.name != "nt",
+                              creationflags=subprocess.CREATE_NO_WINDOW if os.name == "nt" else 0) as process:
+            deadline = monotonic() + timeout
+            while True:
+                try:
+                    stdout, stderr = process.communicate(timeout=0.2)
+                    break
+                except subprocess.TimeoutExpired:
+                    if stop.is_set() or monotonic() >= deadline:
+                        _stop_process_tree(process)
+                        stdout, stderr = process.communicate()
+                        if stop.is_set():
+                            raise CheckCancelled()
+                        raise CheckFailure(f"命令执行超过 {timeout:g} 秒", command=command,
+                                           cwd=directory, exit_code=process.returncode,
+                                           stdout=stdout.decode("utf-8", errors="replace"),
+                                           stderr=stderr.decode("utf-8", errors="replace"),
+                                           error_type="TimeoutExpired")
+    except OSError as exc:
+        raise CheckFailure(str(exc), command=command, cwd=directory,
+                           error_type=type(exc).__name__) from exc
+    output = stdout.decode("utf-8", errors="replace")
+    if process.returncode:
+        stderr_text = stderr.decode('utf-8', errors='replace')
+        message = ('GCC 已启动，但无法启动编译子进程；该错误不能直接判定为编译器不存在'
+                   if is_driver_launch_failure(stderr_text) else '命令执行失败')
+        # Whole-check retries remain owned by warmup (initial check + 5 rounds).
+        raise CheckFailure(message, command=command, cwd=directory,
+                           exit_code=process.returncode, stdout=output,
+                           stderr=stderr_text,
+                           error_type="CalledProcessError")
+    return output
+
+
+def check_native_runtime(progress: Callable[..., None], stop: Event) -> None:
+    def stage(name: str, **details):
+        if stop.is_set():
+            raise CheckCancelled()
+        progress(stage=name, message=STAGE_MESSAGES[name], **details)
+
+    candidate = os.environ.get("SIMULATION_NATIVE_CC") or shutil.which("gcc")
+    stage("toolchain", compiler=candidate)
+    try:
+        compiler, sundials, version = toolchain()
+    except NativeCommandError as exc:
+        details = exc.details
+        failure = CheckFailure(str(exc), command=details['command'], cwd=details['cwd'],
+            exit_code=details['exitCode'], stdout=details['stdout'], stderr=details['stderr'],
+            error_type=details['errorType'])
+        failure.details['attempts'] = details['attempts']
+        raise failure from exc
+    except subprocess.SubprocessError as exc:
+        def decoded(value):
+            return value.decode("utf-8", errors="replace") if isinstance(value, bytes) else (value or "")
+        raise CheckFailure(str(exc), command=getattr(exc, "cmd", ()), cwd=Path.cwd(),
+                           exit_code=getattr(exc, "returncode", None),
+                           stdout=decoded(getattr(exc, "stdout", "")),
+                           stderr=decoded(getattr(exc, "stderr", "")),
+                           error_type=type(exc).__name__) from exc
+    except OSError as exc:
+        raise CheckFailure(str(exc), command=[candidate, "--version"] if candidate else [],
+                           cwd=Path.cwd(), error_type=type(exc).__name__) from exc
+    compiler = str(Path(shutil.which(compiler) or compiler).resolve())
+    stage("preparing", compiler=compiler, compilerVersion=version, sundialsRoot=str(sundials))
+    flags, libraries, dlls, executable_name = platform_build_inputs(sundials)
+    # Keep the probe on the build filesystem: Linux /tmp may be mounted noexec.
+    # Disposable probes never populate or evict the model/object caches.
+    directory_root = CACHE.parent / "native-runtime-checks"
+    directory_root.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix="check-", dir=directory_root) as temporary:
+        directory = Path(temporary).resolve()
+        source, preprocessed, obj = directory / "check.c", directory / "check.i", directory / "check.o"
+        executable = directory / executable_name
+        source.write_text(SOURCE, encoding="utf-8", newline="\n")
+        stage("preprocessing")
+        _command([compiler, *flags, "-E", "-P", f"-fmacro-prefix-map={directory}=/generated",
+                  "-I", str(sundials / "include"), str(source), "-o", str(preprocessed)], directory, stop)
+        stage("compiling")
+        _command([compiler, *flags, "-x", "cpp-output", "-c", str(preprocessed), "-o", str(obj)], directory, stop)
+        stage("linking")
+        _command([compiler, *flags, str(obj), *link_library_arguments(libraries),
+                  "-lm", "-o", str(executable)], directory, stop)
+        stage("running")
+        for dll in dlls:
+            shutil.copyfile(dll, directory / dll.name)
+        output = _command([str(executable)], directory, stop, timeout=10)
+        if output.strip() != OUTPUT_MARKER:
+            raise CheckFailure("最小程序未返回预期的自检成功标记", command=[str(executable)],
+                               cwd=directory, exit_code=0, stdout=output, error_type="UnexpectedOutput")
+    stage("schema")
+    from app.system_xml import validate_system_xml_document
+    validate_system_xml_document(b"<System/>")

app/simulation/native_codegen/tolerances.py

@@ -0,0 +1,18 @@
+"""SI absolute error floors shared by both native code generators.
+
+Mass must not inherit the energy floor: 1e-8 kg overwhelmed relative error
+control in small pipe volumes. These conservative defaults were validated on
+the pipe and chamber regressions; model-scale/user tolerance settings remain
+a separate protocol change.
+"""
+
+
+def state_absolute_tolerance(key: str) -> str:
+    field = key.rsplit('.', 1)[-1]
+    if field in ('m', 'm1', 'm2'):
+        return '1e-14'  # kg
+    if field in ('v', 'x'):
+        return '1e-12'  # m/s or m
+    if field == '_volume_displacement':
+        return '1e-14'  # m3, prescribed external volume change
+    return '1e-8'  # J (or the internal constant state of an algebraic model)

app/simulation/native_codegen/transport.py

@@ -0,0 +1,63 @@
+"""Carry trusted C-generated series JSON without a Python float-array round trip.
+
+Only native output plus its byte index may construct this transport object. Public
+JSON still has the ordinary object/array schema; synchronous callers materialize
+it explicitly. Bytes own their lifetime independently of the worker directory.
+"""
+from dataclasses import dataclass
+import json
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class NativeSeriesJson:
+    data: bytes
+    sample_count: int
+
+    def materialize(self) -> dict[str, list[float]]:
+        return json.loads(self.data)
+
+
+def read_indexed_result(output: Path, index_path: Path) -> dict:
+    index = json.loads(index_path.read_bytes())
+    if not isinstance(index, dict) or type(index.get('version')) is not int or index['version'] != 1:
+        raise ValueError('Unsupported native result index.')
+    names = ('seriesStart', 'seriesEnd', 'resultBytes', 'sampleCount')
+    if any(type(index.get(key)) is not int for key in names):
+        raise ValueError('Invalid native result index integers.')
+    start, end, length, count = (index[key] for key in names)
+    if not (0 < start < end < length and count >= 0):
+        raise ValueError('Invalid native result index bounds.')
+    if output.stat().st_size != length:
+        raise ValueError('Incomplete native result file.')
+    raw = output.read_bytes()
+    if (len(raw) != length or not raw[:start].endswith(b'"series":')
+            or raw[start:start+1] != b'{' or raw[end-1:end] != b'}'
+            or not raw[end:].startswith(b',"final":')):
+        raise ValueError('Native result index does not match the output layout.')
+    # The C writer supplies exact boundaries. No search through strings or numeric
+    # arrays, and no large json.loads call: only diagnostics/final values are read.
+    metadata = json.loads(raw[:start] + b'{}' + raw[end:])
+    if not isinstance(metadata, dict) or metadata.get('series') != {}:
+        raise ValueError('Invalid native result metadata.')
+    metadata['series'] = NativeSeriesJson(raw[start:end], count)
+    return metadata
+
+
+def serialize_result_parts(payload: dict) -> tuple[bytes, ...]:
+    """Return one JSON object in three byte segments, without copying its series.
+
+    The only raw position is payload.result.series, produced by our C writer;
+    all model-provided labels, messages and keys use the standard JSON encoder.
+    """
+    result = payload.get('result')
+    series = result.get('series') if isinstance(result, dict) else None
+    if not isinstance(series, NativeSeriesJson):
+        return (json.dumps(payload, ensure_ascii=False, separators=(',', ':')).encode('utf-8'),)
+    metadata = {key: value for key, value in result.items() if key != 'series'}
+    outer = {key: value for key, value in payload.items() if key != 'result'}
+    encoded = json.dumps(metadata, ensure_ascii=False, separators=(',', ':')).encode('utf-8')
+    remainder = json.dumps(outer, ensure_ascii=False, separators=(',', ':')).encode('utf-8')
+    prefix = b'{"result":' + encoded[:-1] + (b',' if metadata else b'') + b'"series":'
+    suffix = b'}' + (b',' + remainder[1:] if outer else b'}')
+    return prefix, series.data, suffix

app/simulation/paths.py

@@ -15,8 +15,16 @@ DATA_DIR = (
 )
 
 SIMULATION_RUNS_DIR = DATA_DIR / "simulation-runs"
-SIMULATION_BASELINES_DIR = PROJECT_ROOT / "tests" / "baselines" / "simulation"
-AMESIM_TEST_MQL_ARCHIVE_PATH = PROJECT_ROOT / "AmesimModels" / "test_mql.ame"
+SIMULATION_BASELINES_DIR = PROJECT_ROOT / "tests" / "baselines"
+# Current browser/solver input and the matching AME drawing (September 2026).
+CURRENT_MQL8_PROJECT_PATH = PROJECT_ROOT / "tests" / "data" / "test-mql-8-corrected.json"
+CURRENT_MQL8_AME_PATH = PROJECT_ROOT / "tests" / "data" / "test_mql.ame"
+
+# Frozen August reference: its AME bytes differ from the current drawing.
+HISTORICAL_MQL8_AME_PATH = PROJECT_ROOT / "tests" / "data" / "AmesimModels" / "test_mql.ame"
+HISTORICAL_MQL8_PROJECT_PATH = SIMULATION_BASELINES_DIR / "simulation" / "test_mql_8" / "sources" / "test-mql-8.json"
+HISTORICAL_MQL8_XML_PATH = HISTORICAL_MQL8_PROJECT_PATH.with_suffix(".xml")
+AMESIM_TEST_MQL_ARCHIVE_PATH = HISTORICAL_MQL8_AME_PATH
 MODELICA_TESTMODEL_RESULT_PATH = (
     PROJECT_ROOT / "ModelicaModels" / "Simulation" / "Testmodel_res.csv"
 )

app/simulation/performance.py

@@ -1,32 +1,19 @@
-"""Low-overhead, run-local performance instrumentation for simulations.
-
-The profiling mode is intentionally read once when this module is imported.
-``standard`` records low-frequency pipeline stages, while ``audit`` also wraps
-hot RHS/property operations and computes exact-input reuse metrics.  With
-profiling disabled, decorators return the original callable while classes are
-being defined, so ordinary simulation calls do not pass through a wrapper.
-"""
-
+"""Run-local timing of Python orchestration; numeric timings come from C."""
 from __future__ import annotations
-
 from collections.abc import Callable, Generator, Mapping
 from contextlib import contextmanager
-from contextvars import ContextVar, Token
+from contextvars import ContextVar
 from dataclasses import dataclass, field
 from functools import wraps
 import inspect
 import os
-import struct
 from time import perf_counter_ns
 from typing import Any, Literal, ParamSpec, TypeVar, cast
 
-
-ProfileMode = Literal["off", "standard", "audit"]
-
-_P = ParamSpec("_P")
-_R = TypeVar("_R")
-_MODE_RANK: Mapping[ProfileMode, int] = {"off": 0, "standard": 1, "audit": 2}
-
+ProfileMode = Literal['off', 'standard', 'audit']
+_P = ParamSpec('_P')
+_R = TypeVar('_R')
+_MODE_RANK: Mapping[ProfileMode, int] = {'off': 0, 'standard': 1, 'audit': 2}
 
 def _read_startup_mode() -> ProfileMode:
     raw_mode = os.getenv("SIMULATIONAPP_PROFILE", "off").strip().lower()
@@ -50,17 +37,12 @@ def _read_startup_mode() -> ProfileMode:
             "SIMULATIONAPP_PROFILE must be one of: off, standard, audit."
         ) from exc
 
-
-PROFILE_MODE: ProfileMode = _read_startup_mode()
-
-
 def _minimum_mode(value: str) -> ProfileMode:
     normalized = value.strip().lower()
     if normalized not in _MODE_RANK:
         raise ValueError("minimum_mode must be one of: off, standard, audit.")
     return cast(ProfileMode, normalized)
 
-
 def _mode_enabled(minimum_mode: ProfileMode) -> bool:
     # ``off`` is an unconditional zero-wrapper mode, even if a caller passes
     # ``minimum_mode="off"`` by mistake.
@@ -69,7 +51,6 @@ def _mode_enabled(minimum_mode: ProfileMode) -> bool:
         and _MODE_RANK[PROFILE_MODE] >= _MODE_RANK[minimum_mode]
     )
 
-
 @dataclass
 class _TimingStats:
     calls: int = 0
@@ -95,311 +76,10 @@ class _TimingStats:
             "errors": self.errors,
         }
 
-
-@dataclass
-class _PropertyStats(_TimingStats):
-    operation: str = ""
-    layer: str = "semantic"
-    medium: str = "unknown"
-    exact_input_unique: int = 0
-    exact_input_repeats: int = 0
-    iteration_calls: int = 0
-    iteration_total: int = 0
-    iteration_max: int = 0
-    iteration_converged: int = 0
-    iteration_nonconverged: int = 0
-    cache_lookups: int = 0
-    cache_hits: int = 0
-    cache_misses: int = 0
-
-    def snapshot(self, *, audit: bool) -> dict[str, object]:
-        result: dict[str, object] = super().snapshot()
-        result.update(
-            {
-                "operation": self.operation,
-                "layer": self.layer,
-                "medium": self.medium,
-                "cacheLookups": self.cache_lookups,
-                "cacheHits": self.cache_hits,
-                "cacheMisses": self.cache_misses,
-            }
-        )
-        if audit:
-            result.update(
-                {
-                    "exactInputUnique": self.exact_input_unique,
-                    "exactInputRepeats": self.exact_input_repeats,
-                    "iterationCalls": self.iteration_calls,
-                    "iterationTotal": self.iteration_total,
-                    "iterationMax": self.iteration_max,
-                    "iterationConverged": self.iteration_converged,
-                    "iterationNonconverged": self.iteration_nonconverged,
-                }
-            )
-        return result
-
-
-@dataclass
-class _ActiveSpan:
-    trace: PerformanceTrace
-    name: str
-    started_ns: int
-    property_key: str | None = None
-    property_operation: str | None = None
-    property_outermost: bool = False
-    child_ns: int = 0
-
-
-@dataclass
-class PerformanceTrace:
-    """Mutable counters owned by exactly one :func:`profile_run` context."""
-
-    mode: ProfileMode
-    _phases: dict[str, _TimingStats] = field(default_factory=dict, repr=False)
-    _properties: dict[str, _PropertyStats] = field(default_factory=dict, repr=False)
-    _property_outermost_ns: int = field(default=0, repr=False)
-
-    @property
-    def enabled(self) -> bool:
-        return self.mode != "off"
-
-    def _property_stats(
-        self,
-        key: str,
-        *,
-        operation: str,
-        layer: str,
-        medium: str,
-    ) -> _PropertyStats:
-        stats = self._properties.get(key)
-        if stats is None:
-            stats = _PropertyStats(
-                operation=operation,
-                layer=layer,
-                medium=medium,
-            )
-            self._properties[key] = stats
-        return stats
-
-    def _record_span(self, frame: _ActiveSpan, elapsed_ns: int, error: bool) -> None:
-        self_ns = max(0, elapsed_ns - frame.child_ns)
-        if frame.property_key is None:
-            stats = self._phases.setdefault(frame.name, _TimingStats())
-        else:
-            layer, medium, operation = frame.property_key.split("|", 2)
-            stats = self._property_stats(
-                frame.property_key,
-                operation=operation,
-                layer=layer,
-                medium=medium,
-            )
-            if frame.property_outermost:
-                self._property_outermost_ns += elapsed_ns
-        stats.record(elapsed_ns, self_ns, error)
-
-    def _record_exact_input(
-        self,
-        key: str,
-        *,
-        operation: str,
-        layer: str,
-        medium: str,
-        fingerprint: object,
-    ) -> None:
-        stats = self._property_stats(
-            key,
-            operation=operation,
-            layer=layer,
-            medium=medium,
-        )
-        shadow_key = (key, fingerprint)
-        shadow = _PROPERTY_SHADOW.get()
-        if shadow is None:
-            # A trace normally installs its own set in ``profile_run``.  Keep
-            # the ContextVar default immutable so no task can accidentally
-            # share a process-global shadow set.
-            shadow = set()
-            _PROPERTY_SHADOW.set(shadow)
-        if shadow_key in shadow:
-            stats.exact_input_repeats += 1
-        else:
-            shadow.add(shadow_key)
-            stats.exact_input_unique += 1
-
-    def _record_iterations(
-        self,
-        key: str,
-        *,
-        operation: str,
-        layer: str,
-        medium: str,
-        iterations: int,
-        converged: bool,
-    ) -> None:
-        stats = self._property_stats(
-            key,
-            operation=operation,
-            layer=layer,
-            medium=medium,
-        )
-        iteration_count = max(0, int(iterations))
-        stats.iteration_calls += 1
-        stats.iteration_total += iteration_count
-        stats.iteration_max = max(stats.iteration_max, iteration_count)
-        if converged:
-            stats.iteration_converged += 1
-        else:
-            stats.iteration_nonconverged += 1
-
-    def _record_cache(
-        self,
-        key: str,
-        *,
-        operation: str,
-        layer: str,
-        medium: str,
-        hits: int,
-        misses: int,
-    ) -> None:
-        stats = self._property_stats(
-            key,
-            operation=operation,
-            layer=layer,
-            medium=medium,
-        )
-        hit_delta = max(0, hits)
-        miss_delta = max(0, misses)
-        stats.cache_hits += hit_delta
-        stats.cache_misses += miss_delta
-        stats.cache_lookups += hit_delta + miss_delta
-
-    def snapshot(self) -> dict[str, object]:
-        """Return a detached, JSON-serializable copy of all counters."""
-
-        audit = self.mode == "audit"
-        return {
-            "mode": self.mode,
-            "phases": {
-                name: self._phases[name].snapshot()
-                for name in sorted(self._phases)
-            },
-            "properties": {
-                _public_property_key(key): self._properties[key].snapshot(audit=audit)
-                for key in sorted(self._properties)
-            },
-            "propertyOutermostNs": self._property_outermost_ns,
-        }
-
-
-_CURRENT_TRACE: ContextVar[PerformanceTrace | None] = ContextVar(
-    "simulation_performance_trace",
-    default=None,
-)
-_ACTIVE_SPANS: ContextVar[tuple[_ActiveSpan, ...]] = ContextVar(
-    "simulation_performance_spans",
-    default=(),
-)
-_PROPERTY_SHADOW: ContextVar[set[object] | None] = ContextVar(
-    "simulation_property_shadow",
-    default=None,
-)
-
-
-def _public_property_key(key: str) -> str:
-    layer, medium, operation = key.split("|", 2)
-    return f"{layer}.{medium}.{operation}"
-
-
-@contextmanager
-def _tracked_span(
-    trace: PerformanceTrace,
-    name: str,
-    *,
-    property_key: str | None = None,
-    property_operation: str | None = None,
-    reset_property_shadow: bool = False,
-) -> Generator[None, None, None]:
-    stack = _ACTIVE_SPANS.get()
-    property_outermost = property_key is not None and not any(
-        item.property_key is not None for item in stack
-    )
-    frame = _ActiveSpan(
-        trace=trace,
-        name=name,
-        started_ns=perf_counter_ns(),
-        property_key=property_key,
-        property_operation=property_operation,
-        property_outermost=property_outermost,
-    )
-    stack_token = _ACTIVE_SPANS.set((*stack, frame))
-    shadow_token: Token[set[object] | None] | None = None
-    if reset_property_shadow and trace.mode == "audit":
-        shadow_token = _PROPERTY_SHADOW.set(set())
-    error = False
-    try:
-        yield
-    except BaseException:
-        error = True
-        raise
-    finally:
-        elapsed_ns = max(0, perf_counter_ns() - frame.started_ns)
-        _ACTIVE_SPANS.reset(stack_token)
-        if shadow_token is not None:
-            _PROPERTY_SHADOW.reset(shadow_token)
-        if stack:
-            stack[-1].child_ns += elapsed_ns
-        trace._record_span(frame, elapsed_ns, error)
-
-
-@contextmanager
-def profile_run() -> Generator[PerformanceTrace, None, None]:
-    """Create and bind an isolated trace for one simulation run.
-
-    The yielded trace remains usable after the context exits, which lets the
-    caller attach ``trace.snapshot()`` to a result without exposing live state.
-    """
-
-    trace = PerformanceTrace(mode=PROFILE_MODE)
-    trace_token = _CURRENT_TRACE.set(trace)
-    spans_token = _ACTIVE_SPANS.set(())
-    shadow_token = _PROPERTY_SHADOW.set(set())
-    try:
-        if trace.enabled:
-            with _tracked_span(trace, "simulation.total"):
-                yield trace
-        else:
-            yield trace
-    finally:
-        _PROPERTY_SHADOW.reset(shadow_token)
-        _ACTIVE_SPANS.reset(spans_token)
-        _CURRENT_TRACE.reset(trace_token)
-
-
-@contextmanager
-def performance_span(
-    name: str,
-    minimum_mode: str = "standard",
-    reset_property_shadow: bool = False,
-) -> Generator[None, None, None]:
-    """Time a block in the current run, or act as a no-op outside one."""
-
-    minimum = _minimum_mode(minimum_mode)
-    trace = _CURRENT_TRACE.get()
-    if trace is None or not _mode_enabled(minimum):
-        yield
-        return
-    with _tracked_span(
-        trace,
-        name,
-        reset_property_shadow=reset_property_shadow,
-    ):
-        yield
-
-
 def profile_phase(
     name: str,
     minimum_mode: str = "standard",
-    reset_property_shadow: bool = False,
+
 ) -> Callable[[Callable[_P, _R]], Callable[_P, _R]]:
     """Decorate a simulation phase while preserving the off-mode callable."""
 
@@ -419,7 +99,7 @@ def profile_phase(
                 with _tracked_span(
                     trace,
                     name,
-                    reset_property_shadow=reset_property_shadow,
+
                 ):
                     return await function(*args, **kwargs)
 
@@ -433,7 +113,7 @@ def profile_phase(
             with _tracked_span(
                 trace,
                 name,
-                reset_property_shadow=reset_property_shadow,
+
             ):
                 return function(*args, **kwargs)
 
@@ -441,249 +121,68 @@ def profile_phase(
 
     return decorate
 
+PROFILE_MODE = _read_startup_mode()
 
-def _medium_name(args: tuple[object, ...]) -> str:
-    if not args:
-        return "unknown"
-    owner = args[0]
-    configured_name = getattr(owner, "name", None)
-    if isinstance(configured_name, str) and configured_name:
-        return configured_name
-    return type(owner).__name__
+@dataclass
+class _ActiveSpan:
+    name: str
+    started_ns: int
+    child_ns: int = 0
 
+@dataclass
+class PerformanceTrace:
+    mode: ProfileMode
+    _phases: dict[str, _TimingStats] = field(default_factory=dict, repr=False)
 
-def _fingerprint(value: object) -> object:
-    """Build a hashable, bit-exact token without retaining arbitrary objects."""
+    @property
+    def enabled(self):
+        return self.mode != 'off'
 
-    if value is None or isinstance(value, (bool, int, str, bytes)):
-        return (type(value).__name__, value)
-    if isinstance(value, float):
-        return ("float64", struct.pack("!d", value))
-    if isinstance(value, tuple):
-        return ("tuple", tuple(_fingerprint(item) for item in value))
-    if isinstance(value, list):
-        return ("list", tuple(_fingerprint(item) for item in value))
-    if isinstance(value, Mapping):
-        items = [(_fingerprint(key), _fingerprint(item)) for key, item in value.items()]
-        items.sort(key=repr)
-        return ("mapping", tuple(items))
-    return (
-        "object",
-        type(value).__module__,
-        type(value).__qualname__,
-        id(value),
-    )
+    def snapshot(self):
+        return {'mode': self.mode, 'phases': {key: value.snapshot() for key, value in sorted(self._phases.items())}}
 
+_CURRENT_TRACE = ContextVar('simulation_trace', default=None)
+_ACTIVE_SPANS = ContextVar('simulation_spans', default=())
 
-def _input_fingerprint(
-    signature: inspect.Signature | None,
-    args: tuple[object, ...],
-    kwargs: dict[str, object],
-) -> object:
-    if signature is not None:
+@contextmanager
+def _tracked_span(trace, name):
+    stack = _ACTIVE_SPANS.get()
+    frame = _ActiveSpan(name, perf_counter_ns())
+    token = _ACTIVE_SPANS.set((*stack, frame))
+    error = False
     try:
-            bound = signature.bind(*args, **kwargs)
-            bound.apply_defaults()
-            return tuple(
-                (name, _fingerprint(value))
-                for name, value in bound.arguments.items()
-            )
-        except TypeError:
-            pass
-    return (
-        _fingerprint(args),
-        tuple(sorted((name, _fingerprint(value)) for name, value in kwargs.items())),
-    )
+        yield
+    except BaseException:
+        error = True
+        raise
+    finally:
+        elapsed = max(0, perf_counter_ns()-frame.started_ns)
+        _ACTIVE_SPANS.reset(token)
+        if stack:
+            stack[-1].child_ns += elapsed
+        trace._phases.setdefault(name, _TimingStats()).record(elapsed, max(0, elapsed-frame.child_ns), error)
 
-
-def _cache_counts(function: Callable[..., object]) -> tuple[int, int] | None:
-    cache_info = getattr(function, "cache_info", None)
-    if not callable(cache_info):
-        return None
+@contextmanager
+def profile_run():
+    trace = PerformanceTrace(PROFILE_MODE)
+    token = _CURRENT_TRACE.set(trace)
+    spans = _ACTIVE_SPANS.set(())
     try:
-        info = cache_info()
-        return int(info.hits), int(info.misses)
-    except (AttributeError, TypeError, ValueError):
-        return None
-
-
-def _copy_cache_api(source: Callable[..., object], target: Callable[..., object]) -> None:
-    for attribute in ("cache_clear", "cache_info", "cache_parameters"):
-        value = getattr(source, attribute, None)
-        if value is not None:
-            setattr(target, attribute, value)
-
-
-def profile_property(
-    operation: str,
-    layer: str = "semantic",
-    minimum_mode: str = "audit",
-    capture_inputs: bool = True,
-    track_cache: bool = False,
-) -> Callable[[Callable[_P, _R]], Callable[_P, _R]]:
-    """Decorate one thermodynamic property operation."""
+        if trace.enabled:
+            with _tracked_span(trace, 'simulation.total'):
+                yield trace
+        else:
+            yield trace
+    finally:
+        _ACTIVE_SPANS.reset(spans)
+        _CURRENT_TRACE.reset(token)
 
+@contextmanager
+def performance_span(name: str, minimum_mode: str = 'standard'):
     minimum = _minimum_mode(minimum_mode)
-
-    def decorate(function: Callable[_P, _R]) -> Callable[_P, _R]:
-        if not _mode_enabled(minimum):
-            return function
-        try:
-            signature: inspect.Signature | None = inspect.signature(function)
-        except (TypeError, ValueError):
-            signature = None
-
-        def prepare(
-            args: tuple[object, ...],
-            kwargs: dict[str, object],
-        ) -> tuple[PerformanceTrace | None, str, str, tuple[int, int] | None]:
     trace = _CURRENT_TRACE.get()
-            medium = _medium_name(args)
-            key = f"{layer}|{medium}|{operation}"
-            if trace is not None and trace.mode == "audit" and capture_inputs:
-                trace._record_exact_input(
-                    key,
-                    operation=operation,
-                    layer=layer,
-                    medium=medium,
-                    fingerprint=_input_fingerprint(signature, args, kwargs),
-                )
-            before = _cache_counts(function) if trace is not None and track_cache else None
-            return trace, medium, key, before
-
-        def finish_cache(
-            trace: PerformanceTrace | None,
-            medium: str,
-            key: str,
-            before: tuple[int, int] | None,
-        ) -> None:
-            if trace is None or before is None:
+    if trace is None or not _mode_enabled(minimum):
+        yield
         return
-            after = _cache_counts(function)
-            if after is None:
-                return
-            trace._record_cache(
-                key,
-                operation=operation,
-                layer=layer,
-                medium=medium,
-                hits=after[0] - before[0],
-                misses=after[1] - before[1],
-            )
-
-        if inspect.iscoroutinefunction(function):
-
-            @wraps(function)
-            async def async_wrapper(*args: _P.args, **kwargs: _P.kwargs) -> Any:
-                object_args = cast(tuple[object, ...], args)
-                object_kwargs = cast(dict[str, object], kwargs)
-                trace, medium, key, before = prepare(object_args, object_kwargs)
-                try:
-                    if trace is None:
-                        return await function(*args, **kwargs)
-                    with _tracked_span(
-                        trace,
-                        f"property.{_public_property_key(key)}",
-                        property_key=key,
-                        property_operation=operation,
-                    ):
-                        return await function(*args, **kwargs)
-                finally:
-                    finish_cache(trace, medium, key, before)
-
-            _copy_cache_api(function, async_wrapper)
-            return cast(Callable[_P, _R], async_wrapper)
-
-        @wraps(function)
-        def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _R:
-            object_args = cast(tuple[object, ...], args)
-            object_kwargs = cast(dict[str, object], kwargs)
-            trace, medium, key, before = prepare(object_args, object_kwargs)
-            try:
-                if trace is None:
-                    return function(*args, **kwargs)
-                with _tracked_span(
-                    trace,
-                    f"property.{_public_property_key(key)}",
-                    property_key=key,
-                    property_operation=operation,
-                ):
-                    return function(*args, **kwargs)
-            finally:
-                finish_cache(trace, medium, key, before)
-
-        _copy_cache_api(function, wrapper)
-        return wrapper
-
-    return decorate
-
-
-def record_property_iterations(
-    operation: str,
-    iterations: int,
-    converged: bool,
-) -> None:
-    """Record inverse-property solver iterations in audit mode."""
-
-    trace = _CURRENT_TRACE.get()
-    if trace is None or trace.mode != "audit":
-        return
-    for frame in reversed(_ACTIVE_SPANS.get()):
-        if (
-            frame.property_key is not None
-            and frame.property_operation == operation
-        ):
-            layer, medium, _unused_operation = frame.property_key.split("|", 2)
-            trace._record_iterations(
-                frame.property_key,
-                operation=operation,
-                layer=layer,
-                medium=medium,
-                iterations=iterations,
-                converged=converged,
-            )
-            return
-    key = f"semantic|unknown|{operation}"
-    trace._record_iterations(
-        key,
-        operation=operation,
-        layer="semantic",
-        medium="unknown",
-        iterations=iterations,
-        converged=converged,
-    )
-
-
-def record_property_cache(operation: str, *, hit: bool) -> None:
-    """Record one run-local property-cache lookup in audit mode."""
-
-    trace = _CURRENT_TRACE.get()
-    if trace is None or trace.mode != "audit":
-        return
-    for frame in reversed(_ACTIVE_SPANS.get()):
-        if (
-            frame.property_key is not None
-            and frame.property_operation == operation
-        ):
-            layer, medium, _unused_operation = frame.property_key.split("|", 2)
-            trace._record_cache(
-                frame.property_key,
-                operation=operation,
-                layer=layer,
-                medium=medium,
-                hits=1 if hit else 0,
-                misses=0 if hit else 1,
-            )
-            return
-
-
-__all__ = [
-    "PROFILE_MODE",
-    "PerformanceTrace",
-    "performance_span",
-    "profile_phase",
-    "profile_property",
-    "profile_run",
-    "record_property_cache",
-    "record_property_iterations",
-]
+    with _tracked_span(trace, name):
+        yield

app/simulation/property_cache.py

@@ -1,234 +0,0 @@
-"""Run-local, exact-key cache for expensive thermodynamic calculations.
-
-The cache is deliberately bound to one simulation through ``ContextVar``.
-That keeps concurrent runs isolated and releases all cached states when the
-run finishes.  Keys use the original Python values with no rounding or
-tolerance-based reuse that could flatten numerical residuals seen by ODE and
-nonlinear solvers.
-"""
-
-from __future__ import annotations
-
-from collections.abc import Callable, Generator
-from contextlib import contextmanager
-from contextvars import ContextVar
-from dataclasses import dataclass
-from functools import lru_cache, wraps
-import os
-from typing import ParamSpec, TypeVar
-
-from app.simulation.performance import PROFILE_MODE, record_property_cache
-
-
-_P = ParamSpec("_P")
-_R = TypeVar("_R")
-DEFAULT_PROPERTY_CACHE_MAX_ENTRIES = 8192
-
-
-def _read_cache_enabled() -> bool:
-    raw_value = os.getenv("SIMULATIONAPP_PROPERTY_CACHE", "on").strip().lower()
-    if raw_value in {"", "1", "true", "yes", "on"}:
-        return True
-    if raw_value in {"0", "false", "no", "off"}:
-        return False
-    raise ValueError(
-        "SIMULATIONAPP_PROPERTY_CACHE must be one of: on, off, true, false, 1, 0."
-    )
-
-
-PROPERTY_CACHE_ENABLED = _read_cache_enabled()
-
-
-@dataclass(frozen=True)
-class PropertyCacheInfo:
-    hits: int
-    misses: int
-    max_entries_per_cache: int
-    cache_count: int
-    current_entries: int
-    evictions: int
-
-
-class SimulationPropertyCache:
-    """Bounded C-level LRUs owned by one simulation run."""
-
-    def __init__(self, max_entries: int = DEFAULT_PROPERTY_CACHE_MAX_ENTRIES) -> None:
-        if max_entries <= 0:
-            raise ValueError("Property cache max_entries must be positive.")
-        self.max_entries_per_cache = int(max_entries)
-        self._functions: dict[
-            tuple[str, int, Callable[..., object]],
-            Callable[..., object],
-        ] = {}
-        self._failed_misses: dict[
-            tuple[str, int, Callable[..., object]],
-            int,
-        ] = {}
-        self._owners: dict[int, tuple[object, int]] = {}
-        self._next_owner_token = 0
-
-    def owner_token(self, owner: object) -> int:
-        """Return a stable identity token and retain its owner for this run."""
-
-        identity = id(owner)
-        existing = self._owners.get(identity)
-        if existing is not None and existing[0] is owner:
-            return existing[1]
-        self._next_owner_token += 1
-        self._owners[identity] = (owner, self._next_owner_token)
-        return self._next_owner_token
-
-    def get_or_compute(
-        self,
-        operation: str,
-        owner: object,
-        function: Callable[..., _R],
-        args: tuple[object, ...],
-        kwargs: dict[str, object],
-    ) -> _R:
-        cache_key = (operation, self.owner_token(owner), function)
-        cached_function = self._functions.get(cache_key)
-        if cached_function is None:
-
-            @lru_cache(maxsize=self.max_entries_per_cache, typed=True)
-            def invoke(*cached_args: object, **cached_kwargs: object) -> _R:
-                return function(owner, *cached_args, **cached_kwargs)
-
-            cached_function = invoke
-            self._functions[cache_key] = cached_function
-
-        if PROFILE_MODE != "audit":
-            try:
-                return cached_function(*args, **kwargs)
-            except Exception:
-                self._failed_misses[cache_key] = (
-                    self._failed_misses.get(cache_key, 0) + 1
-                )
-                raise
-
-        before = cached_function.cache_info()  # type: ignore[attr-defined]
-        try:
-            value = cached_function(*args, **kwargs)
-        except Exception:
-            self._failed_misses[cache_key] = (
-                self._failed_misses.get(cache_key, 0) + 1
-            )
-            raise
-        finally:
-            after = cached_function.cache_info()  # type: ignore[attr-defined]
-            hit = after.hits > before.hits
-            record_property_cache(operation, hit=hit)
-        return value
-
-    def info(self) -> PropertyCacheInfo:
-        cache_infos = {
-            key: cached.cache_info()  # type: ignore[attr-defined]
-            for key, cached in self._functions.items()
-        }
-        return PropertyCacheInfo(
-            hits=sum(info.hits for info in cache_infos.values()),
-            misses=sum(info.misses for info in cache_infos.values()),
-            max_entries_per_cache=self.max_entries_per_cache,
-            cache_count=len(self._functions),
-            current_entries=sum(info.currsize for info in cache_infos.values()),
-            evictions=sum(
-                max(
-                    0,
-                    info.misses
-                    - self._failed_misses.get(key, 0)
-                    - info.currsize,
-                )
-                for key, info in cache_infos.items()
-            ),
-        )
-
-
-_CURRENT_PROPERTY_CACHE: ContextVar[SimulationPropertyCache | None] = ContextVar(
-    "simulation_property_cache",
-    default=None,
-)
-
-
-def current_property_cache() -> SimulationPropertyCache | None:
-    return _CURRENT_PROPERTY_CACHE.get()
-
-
-@contextmanager
-def property_cache_run(
-    *,
-    max_entries: int = DEFAULT_PROPERTY_CACHE_MAX_ENTRIES,
-) -> Generator[SimulationPropertyCache | None, None, None]:
-    """Bind a fresh cache to one top-level simulation run.
-
-    Nested uses reuse the existing cache so lower-level simulation helpers can
-    safely opt in without replacing the cache created by the API entry point.
-    """
-
-    existing = _CURRENT_PROPERTY_CACHE.get()
-    if existing is not None:
-        yield existing
-        return
-    if not PROPERTY_CACHE_ENABLED:
-        yield None
-        return
-
-    cache = SimulationPropertyCache(max_entries=max_entries)
-    token = _CURRENT_PROPERTY_CACHE.set(cache)
-    try:
-        yield cache
-    finally:
-        _CURRENT_PROPERTY_CACHE.reset(token)
-
-
-def cache_property_calculation(
-    operation: str,
-) -> Callable[[Callable[_P, _R]], Callable[_P, _R]]:
-    """Cache one pure property calculation with hashable arguments per run."""
-
-    def decorate(function: Callable[_P, _R]) -> Callable[_P, _R]:
-        if not PROPERTY_CACHE_ENABLED:
-            return function
-
-        @wraps(function)
-        def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _R:
-            cache = _CURRENT_PROPERTY_CACHE.get()
-            if cache is None:
-                return function(*args, **kwargs)
-            owner = args[0] if args else function
-            return cache.get_or_compute(
-                operation,
-                owner,
-                function,
-                tuple(args[1:] if args else ()),
-                dict(kwargs),
-            )
-
-        return wrapper
-
-    return decorate
-
-
-def with_property_cache(function: Callable[_P, _R]) -> Callable[_P, _R]:
-    """Ensure a simulation entry point has a run-local cache."""
-
-    if not PROPERTY_CACHE_ENABLED:
-        return function
-
-    @wraps(function)
-    def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _R:
-        with property_cache_run():
-            return function(*args, **kwargs)
-
-    return wrapper
-
-
-__all__ = [
-    "DEFAULT_PROPERTY_CACHE_MAX_ENTRIES",
-    "PROPERTY_CACHE_ENABLED",
-    "PropertyCacheInfo",
-    "SimulationPropertyCache",
-    "cache_property_calculation",
-    "current_property_cache",
-    "property_cache_run",
-    "with_property_cache",
-]

app/simulation/registry.py

@@ -24,6 +24,7 @@ from app.simulation.core.metadata import (
 )
 from app.simulation.core.medium import GasMedium, IdealGasMedium
 from app.simulation.core.ports import PortDefinition, PortVariableDefinition
+from app.simulation.core.port_computation import PortComputation
 
 
 ParameterSpec = ParameterDefinition
@@ -877,8 +878,18 @@ def validate_component_model_class(
             f"Component '{model_type}' RESULT_VARIABLES must be a tuple."
         )
 
+    port_by_name = {port.name: port for port in ports if isinstance(port, PortDefinition)}
     for port in ports:
         _validate_port(port, model_type=model_type)
+        contract = port.computation
+        if contract is not None:
+            if port.domain != 'pneumatic' or not isinstance(contract, PortComputation):
+                raise ValueError(f"Component '{model_type}' has an invalid pneumatic computation contract.")
+            if contract.reference_port:
+                reference = port_by_name.get(contract.reference_port)
+                if (reference is None or reference.computation is None
+                        or not {'p', 'T'}.issubset(reference.computation.inputs)):
+                    raise ValueError(f"Component '{model_type}.{port.name}' must alias a pressure/temperature input port.")
     for parameter in parameters:
         _validate_parameter(parameter, model_type=model_type)
     for variable in result_variables:

app/simulation/reporting/__init__.py

@@ -1,23 +1 @@
-from app.simulation.reporting.testmodel_outputs import (
-    COMPARISON_KEYS,
-    MODELICA_COMPARISON_COLUMNS,
-    PRIMARY_KEYS,
-    TestModelArtifacts,
-    export_testmodel_artifacts,
-    format_testmodel_run_report,
-    load_modelica_series,
-    write_testmodel_run_report,
-    write_modelica_comparison,
-)
-
-__all__ = [
-    "COMPARISON_KEYS",
-    "MODELICA_COMPARISON_COLUMNS",
-    "PRIMARY_KEYS",
-    "TestModelArtifacts",
-    "export_testmodel_artifacts",
-    "format_testmodel_run_report",
-    "load_modelica_series",
-    "write_testmodel_run_report",
-    "write_modelica_comparison",
-]
+"""Readers for external simulation results."""

app/simulation/reporting/pnl0002_replay.py

@@ -1,263 +0,0 @@
-from __future__ import annotations
-
-import argparse
-import json
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Mapping
-
-from app.simulation.components.amesim.flow.pipes import AmesimPnl0002
-from app.simulation.reporting.amesim_results import (
-    AmesimResults,
-    load_test_mql_amesim_results,
-)
-
-
-@dataclass(frozen=True, slots=True)
-class Pnl0002ReplayPaths:
-    """AMESim data paths needed to replay one PNL0002 resistance."""
-
-    center_pressure: str
-    center_temperature: str
-    port_1_pressure: str
-    port_1_temperature: str
-    port_1_mass_flow: str
-    port_2_pressure: str
-    port_2_temperature: str
-    port_2_mass_flow: str
-    reynolds: str
-    friction_factor: str
-
-
-PNL83_REPLAY_PATHS = Pnl0002ReplayPaths(
-    center_pressure="pctr@pneumatic_83",
-    center_temperature="tctr@pneumatic_83",
-    port_1_pressure="press1@pnnode4_16",
-    port_1_temperature="temp1@pnnode4_16",
-    port_1_mass_flow="dm1@pneumatic_83",
-    port_2_pressure="press3@pnnode4_17",
-    port_2_temperature="temp3@pnnode4_17",
-    port_2_mass_flow="dm2@pneumatic_83",
-    reynolds="re@pneumatic_83",
-    friction_factor="ff@pneumatic_83",
-)
-
-
-def _required_series(
-    results: AmesimResults,
-    path: str,
-) -> tuple[float, ...]:
-    try:
-        values = results.series(path)
-    except KeyError as exc:
-        raise ValueError(f"AMESim replay variable is not saved: {path}") from exc
-    if len(values) != len(results.times):
-        raise ValueError(f"AMESim replay variable has an invalid length: {path}")
-    return values
-
-
-def _metric_summary(
-    rows: list[dict[str, float]],
-    key: str,
-) -> dict[str, float]:
-    values = [float(row[key]) for row in rows]
-    max_index = max(range(len(values)), key=lambda index: abs(values[index]))
-    return {
-        "maxAbs": abs(values[max_index]),
-        "maxAbsTime": rows[max_index]["time"],
-        "finalSigned": values[-1],
-    }
-
-
-def replay_pnl0002_amesim_states(
-    pipe: AmesimPnl0002,
-    results: AmesimResults,
-    paths: Pnl0002ReplayPaths,
-    *,
-    amesim_mass_flow_scale: float = -1.0e-3,
-) -> dict[str, object]:
-    """Replay saved AMESim states through current PNL0002 flow functions.
-
-    This is a calibration-only, no-integration calculation. It does not write
-    states into the pipe or alter the production simulation path.
-    """
-
-    series_by_field = {
-        field: _required_series(results, getattr(paths, field))
-        for field in paths.__dataclass_fields__
-    }
-    rows: list[dict[str, float]] = []
-    for index, time_s in enumerate(results.times):
-        center_pressure = series_by_field["center_pressure"][index]
-        center_temperature = series_by_field["center_temperature"][index]
-        port_1_pressure = series_by_field["port_1_pressure"][index]
-        port_2_pressure = series_by_field["port_2_pressure"][index]
-        observed_flow_1 = (
-            amesim_mass_flow_scale
-            * series_by_field["port_1_mass_flow"][index]
-        )
-        observed_flow_2 = (
-            amesim_mass_flow_scale
-            * series_by_field["port_2_mass_flow"][index]
-        )
-        upstream_temperature_1 = (
-            series_by_field["port_1_temperature"][index]
-            if observed_flow_1 >= 0.0
-            else center_temperature
-        )
-        upstream_temperature_2 = (
-            series_by_field["port_2_temperature"][index]
-            if observed_flow_2 >= 0.0
-            else center_temperature
-        )
-        predicted_flow_1 = pipe.mass_flow(
-            port_1_pressure,
-            center_pressure,
-            upstream_temperature_1,
-        )
-        predicted_flow_2 = pipe.mass_flow(
-            port_2_pressure,
-            center_pressure,
-            upstream_temperature_2,
-        )
-        reynolds_1 = pipe.reynolds_number(
-            observed_flow_1,
-            upstream_temperature_1,
-        )
-        reynolds_2 = pipe.reynolds_number(
-            observed_flow_2,
-            upstream_temperature_2,
-        )
-        friction_1 = pipe.friction_factor(reynolds_1)
-        friction_2 = pipe.friction_factor(reynolds_2)
-        replay_reynolds = 0.5 * (reynolds_1 + reynolds_2)
-        replay_friction = 0.5 * (friction_1 + friction_2)
-        rows.append(
-            {
-                "time": float(time_s),
-                "centerPressure": center_pressure,
-                "centerTemperature": center_temperature,
-                "port1Pressure": port_1_pressure,
-                "port2Pressure": port_2_pressure,
-                "observedPort1MassFlow": observed_flow_1,
-                "observedPort2MassFlow": observed_flow_2,
-                "predictedPort1MassFlow": predicted_flow_1,
-                "predictedPort2MassFlow": predicted_flow_2,
-                "port1MassFlowError": predicted_flow_1 - observed_flow_1,
-                "port2MassFlowError": predicted_flow_2 - observed_flow_2,
-                "amesimReynolds": series_by_field["reynolds"][index],
-                "replayReynolds": replay_reynolds,
-                "reynoldsError": (
-                    replay_reynolds - series_by_field["reynolds"][index]
-                ),
-                "amesimFrictionFactor": series_by_field["friction_factor"][index],
-                "replayFrictionFactor": replay_friction,
-                "frictionFactorError": (
-                    replay_friction
-                    - series_by_field["friction_factor"][index]
-                ),
-            }
-        )
-
-    metric_keys = (
-        "port1MassFlowError",
-        "port2MassFlowError",
-        "reynoldsError",
-        "frictionFactorError",
-    )
-    return {
-        "mode": "amesim-state-replay-no-integration",
-        "component": pipe.name,
-        "pointCount": len(rows),
-        "massFlowScale": amesim_mass_flow_scale,
-        "paths": {
-            field: getattr(paths, field)
-            for field in paths.__dataclass_fields__
-        },
-        "parameters": dict(pipe.parameter_values),
-        "summary": {
-            key: _metric_summary(rows, key)
-            for key in metric_keys
-        },
-        "rows": rows,
-    }
-
-
-def _compile_project_pipe(
-    project_path: Path,
-    component_name: str,
-) -> AmesimPnl0002:
-    from app.main import (
-        ReactFlowProjectPayload,
-        _compile_xml_document_or_422,
-        _validated_xml_document_or_422,
-        build_reactflow_system_xml,
-        validate_system_xml_document,
-    )
-
-    payload = ReactFlowProjectPayload.model_validate_json(
-        project_path.read_text(encoding="utf-8")
-    )
-    xml_bytes = build_reactflow_system_xml(payload)
-    document = _validated_xml_document_or_422(
-        validate_system_xml_document(xml_bytes)
-    )
-    _project, network = _compile_xml_document_or_422(document)
-    try:
-        component = network.components[component_name]
-    except KeyError as exc:
-        raise ValueError(f"Project component does not exist: {component_name}") from exc
-    if not isinstance(component, AmesimPnl0002):
-        raise ValueError(f"Project component is not PNL0002: {component_name}")
-    return component
-
-
-def _paths_from_arguments(arguments: argparse.Namespace) -> Pnl0002ReplayPaths:
-    values: Mapping[str, str] = {
-        field: getattr(arguments, field)
-        for field in PNL83_REPLAY_PATHS.__dataclass_fields__
-    }
-    return Pnl0002ReplayPaths(**values)
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(
-        description="Replay saved AMESim p/T/m_flow through a PNL0002 model without integration."
-    )
-    parser.add_argument("project", type=Path)
-    parser.add_argument("amesim_archive", type=Path)
-    parser.add_argument("output", type=Path)
-    parser.add_argument("--component", default="pneumatic_83")
-    parser.add_argument("--mass-flow-scale", type=float, default=-1.0e-3)
-    for field in PNL83_REPLAY_PATHS.__dataclass_fields__:
-        parser.add_argument(
-            "--" + field.replace("_", "-"),
-            dest=field,
-            default=getattr(PNL83_REPLAY_PATHS, field),
-        )
-    arguments = parser.parse_args()
-
-    pipe = _compile_project_pipe(arguments.project, arguments.component)
-    results = load_test_mql_amesim_results(arguments.amesim_archive)
-    report = replay_pnl0002_amesim_states(
-        pipe,
-        results,
-        _paths_from_arguments(arguments),
-        amesim_mass_flow_scale=arguments.mass_flow_scale,
-    )
-    arguments.output.parent.mkdir(parents=True, exist_ok=True)
-    arguments.output.write_text(
-        json.dumps(report, ensure_ascii=False, indent=2) + "\n",
-        encoding="utf-8",
-    )
-    print(json.dumps({key: report[key] for key in (
-        "mode",
-        "component",
-        "pointCount",
-        "parameters",
-        "summary",
-    )}, ensure_ascii=False, indent=2))
-
-
-if __name__ == "__main__":
-    main()

app/simulation/reporting/test_mql_chamber_observations.py

@@ -1,195 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-from app.simulation.reporting.amesim_results import AmesimResults
-from app.simulation.reporting.test_mql_variables import (
-    TestMqlVariableBinding,
-    TestMqlVariableCatalog,
-    build_test_mql_variable_catalog,
-)
-from app.simulation.examples.test_mql.pneumatic import (
-    TestMqlPneumaticAssembly,
-    build_test_mql_pneumatic_assembly,
-)
-
-
-@dataclass(frozen=True)
-class TestMqlChamberObservation:
-    time: float
-    pressure_pa: float
-    temperature_k: float
-    gas_mass_g: float
-    volume_cm3: float | None
-
-
-@dataclass(frozen=True)
-class TestMqlChamberBinding:
-    alias: str
-    submodel: str
-    pressure_path: str
-    temperature_path: str
-    gas_mass_path: str
-    pressure_duplicate_paths: tuple[str, ...]
-    temperature_duplicate_paths: tuple[str, ...]
-    volume_path: str | None
-
-    @property
-    def is_variable(self) -> bool:
-        return self.volume_path is not None
-
-    def observation_at(self, results: AmesimResults, index: int) -> TestMqlChamberObservation:
-        return TestMqlChamberObservation(
-            time=results.times[index],
-            pressure_pa=results.series(self.pressure_path)[index],
-            temperature_k=results.series(self.temperature_path)[index],
-            gas_mass_g=results.series(self.gas_mass_path)[index],
-            volume_cm3=(
-                results.series(self.volume_path)[index]
-                if self.volume_path is not None
-                else None
-            ),
-        )
-
-
-@dataclass(frozen=True)
-class TestMqlChamberObservationCatalog:
-    bindings: tuple[TestMqlChamberBinding, ...]
-
-    @property
-    def fixed_count(self) -> int:
-        return sum(1 for binding in self.bindings if binding.submodel == "PNCH023")
-
-    @property
-    def variable_count(self) -> int:
-        return sum(1 for binding in self.bindings if binding.submodel == "PNCH012")
-
-    def by_alias(self, alias: str) -> TestMqlChamberBinding:
-        for binding in self.bindings:
-            if binding.alias == alias:
-                return binding
-        raise KeyError(alias)
-
-
-def build_test_mql_chamber_observation_catalog(
-    results: AmesimResults,
-    *,
-    variable_catalog: TestMqlVariableCatalog | None = None,
-    assembly: TestMqlPneumaticAssembly | None = None,
-) -> TestMqlChamberObservationCatalog:
-    variable_catalog = variable_catalog or build_test_mql_variable_catalog(results)
-    assembly = assembly or build_test_mql_pneumatic_assembly()
-    chamber_aliases = {
-        **{alias: "PNCH023" for alias in assembly.fixed_chambers},
-        **{alias: "PNCH012" for alias in assembly.variable_chambers},
-    }
-    bindings = []
-    for alias, submodel in chamber_aliases.items():
-        variables = tuple(
-            variable
-            for variable in variable_catalog.variables
-            if variable.owner_alias == alias
-        )
-        pressure = _primary_observable(variables, "press", expected_units="Pa")
-        temperature = _primary_observable(variables, "temp", expected_units="K")
-        gas_mass = _required_path(
-            variables,
-            "mgas1" if submodel == "PNCH012" else "mgas",
-            expected_units="g",
-        )
-        volume = _optional_path(variables, "vol", expected_units="cm**3")
-        bindings.append(
-            TestMqlChamberBinding(
-                alias=alias,
-                submodel=submodel,
-                pressure_path=pressure.data_path,
-                temperature_path=temperature.data_path,
-                gas_mass_path=gas_mass,
-                pressure_duplicate_paths=_duplicate_paths(variables, "press", expected_units="Pa"),
-                temperature_duplicate_paths=_duplicate_paths(variables, "temp", expected_units="K"),
-                volume_path=volume,
-            )
-        )
-    return TestMqlChamberObservationCatalog(
-        bindings=tuple(sorted(bindings, key=lambda binding: binding.alias))
-    )
-
-
-def _primary_observable(
-    variables: tuple[TestMqlVariableBinding, ...],
-    signal_prefix: str,
-    *,
-    expected_units: str,
-) -> TestMqlVariableBinding:
-    matches = tuple(
-        variable
-        for variable in variables
-        if variable.signal_name == signal_prefix
-        and "duplicate" not in variable.label
-    )
-    variable = _single(matches, f"primary {signal_prefix}")
-    _assert_units(variable, expected_units)
-    return variable
-
-
-def _duplicate_paths(
-    variables: tuple[TestMqlVariableBinding, ...],
-    signal_prefix: str,
-    *,
-    expected_units: str,
-) -> tuple[str, ...]:
-    matches = tuple(
-        variable
-        for variable in variables
-        if variable.signal_name.startswith(signal_prefix)
-        and variable.signal_name != signal_prefix
-        and "duplicate" in variable.label
-    )
-    for variable in matches:
-        _assert_units(variable, expected_units)
-    return tuple(variable.data_path for variable in matches)
-
-
-def _required_path(
-    variables: tuple[TestMqlVariableBinding, ...],
-    signal_name: str,
-    *,
-    expected_units: str,
-) -> str:
-    variable = _single(
-        tuple(variable for variable in variables if variable.signal_name == signal_name),
-        signal_name,
-    )
-    _assert_units(variable, expected_units)
-    return variable.data_path
-
-
-def _optional_path(
-    variables: tuple[TestMqlVariableBinding, ...],
-    signal_name: str,
-    *,
-    expected_units: str,
-) -> str | None:
-    matches = tuple(variable for variable in variables if variable.signal_name == signal_name)
-    if not matches:
-        return None
-    variable = _single(matches, signal_name)
-    _assert_units(variable, expected_units)
-    return variable.data_path
-
-
-def _single(
-    matches: tuple[TestMqlVariableBinding, ...],
-    description: str,
-) -> TestMqlVariableBinding:
-    if len(matches) != 1:
-        raise ValueError(f"Expected one {description} variable, found {len(matches)}.")
-    return matches[0]
-
-
-def _assert_units(variable: TestMqlVariableBinding, expected_units: str) -> None:
-    if variable.units != expected_units:
-        raise ValueError(
-            f"Unexpected units for {variable.data_path}: "
-            f"{variable.units!r}, expected {expected_units!r}."
-        )

app/simulation/reporting/test_mql_comparison.py

@@ -1,237 +0,0 @@
-from __future__ import annotations
-
-from bisect import bisect_left
-import csv
-from dataclasses import dataclass
-from pathlib import Path
-
-from app.simulation.reporting.amesim_results import AmesimResults
-
-
-DEFAULT_TEST_MQL_ALIGNMENT_PATHS = (
-    "temp3@pn_c1_8",
-    "press3@pn_c1_8",
-    "vvol1@pn_brp2_8",
-    "vol1@pn_brp2_8",
-)
-
-
-@dataclass(frozen=True)
-class TestMqlComparisonMetric:
-    data_path: str
-    sample_count: int
-    max_abs_error: float
-    mean_abs_error: float
-    max_rel_error: float
-    final_abs_error: float
-
-
-@dataclass(frozen=True)
-class TestMqlComparisonResult:
-    metrics: tuple[TestMqlComparisonMetric, ...]
-
-    def metric(self, data_path: str) -> TestMqlComparisonMetric:
-        for metric in self.metrics:
-            if metric.data_path == data_path:
-                return metric
-        raise KeyError(data_path)
-
-    @property
-    def max_abs_error(self) -> float:
-        return max((metric.max_abs_error for metric in self.metrics), default=0.0)
-
-    @property
-    def max_rel_error(self) -> float:
-        return max((metric.max_rel_error for metric in self.metrics), default=0.0)
-
-
-class TestMqlComparisonError(ValueError):
-    """Raised when Python and AMESim series cannot be aligned."""
-
-
-def compare_test_mql_series(
-    *,
-    python_times: tuple[float, ...] | list[float],
-    python_series_by_data_path: dict[str, tuple[float, ...] | list[float]],
-    amesim_results: AmesimResults,
-    data_paths: tuple[str, ...] | list[str] | None = None,
-    relative_floor: float = 1.0e-12,
-) -> TestMqlComparisonResult:
-    _validate_time_axis(python_times)
-    selected_paths = _select_data_paths(python_series_by_data_path, amesim_results, data_paths)
-    metrics = []
-    for data_path in selected_paths:
-        python_values = tuple(float(value) for value in python_series_by_data_path[data_path])
-        if len(python_values) != len(python_times):
-            raise TestMqlComparisonError(
-                f"Python series length mismatch for {data_path!r}: "
-                f"{len(python_values)} values for {len(python_times)} time samples."
-            )
-        amesim_values = amesim_results.series(data_path)
-        abs_errors = []
-        rel_errors = []
-        for time_value, python_value in zip(python_times, python_values):
-            amesim_value = interpolate_series_value(amesim_results.times, amesim_values, time_value)
-            abs_error = abs(python_value - amesim_value)
-            abs_errors.append(abs_error)
-            rel_errors.append(abs_error / max(abs(amesim_value), relative_floor))
-        final_amesim_value = interpolate_series_value(
-            amesim_results.times,
-            amesim_values,
-            float(python_times[-1]),
-        )
-        metrics.append(
-            TestMqlComparisonMetric(
-                data_path=data_path,
-                sample_count=len(python_times),
-                max_abs_error=max(abs_errors, default=0.0),
-                mean_abs_error=sum(abs_errors) / max(len(abs_errors), 1),
-                max_rel_error=max(rel_errors, default=0.0),
-                final_abs_error=abs(python_values[-1] - final_amesim_value),
-            )
-        )
-    return TestMqlComparisonResult(metrics=tuple(metrics))
-
-
-def write_test_mql_amesim_baseline_csv(
-    output_dir: Path,
-    amesim_results: AmesimResults,
-    data_paths: tuple[str, ...] | list[str] = DEFAULT_TEST_MQL_ALIGNMENT_PATHS,
-) -> Path:
-    output_dir.mkdir(parents=True, exist_ok=True)
-    csv_path = output_dir / "test_mql_amesim_baseline.csv"
-    _validate_amesim_data_paths(amesim_results, data_paths)
-    with csv_path.open("w", newline="", encoding="utf-8") as handle:
-        writer = csv.writer(handle)
-        writer.writerow(["time_s", *data_paths])
-        for index, time_value in enumerate(amesim_results.times):
-            writer.writerow(
-                [time_value, *(amesim_results.series(data_path)[index] for data_path in data_paths)]
-            )
-    return csv_path
-
-
-def write_test_mql_comparison_csv(
-    *,
-    output_dir: Path,
-    python_times: tuple[float, ...] | list[float],
-    python_series_by_data_path: dict[str, tuple[float, ...] | list[float]],
-    amesim_results: AmesimResults,
-    data_paths: tuple[str, ...] | list[str] | None = None,
-) -> tuple[Path, Path, TestMqlComparisonResult]:
-    output_dir.mkdir(parents=True, exist_ok=True)
-    selected_paths = _select_data_paths(python_series_by_data_path, amesim_results, data_paths)
-    comparison = compare_test_mql_series(
-        python_times=python_times,
-        python_series_by_data_path=python_series_by_data_path,
-        amesim_results=amesim_results,
-        data_paths=selected_paths,
-    )
-    csv_path = output_dir / "test_mql_amesim_comparison.csv"
-    summary_path = output_dir / "test_mql_amesim_comparison_summary.txt"
-
-    with csv_path.open("w", newline="", encoding="utf-8") as handle:
-        writer = csv.writer(handle)
-        header = ["time_s"]
-        for data_path in selected_paths:
-            header.extend(
-                [
-                    f"python.{data_path}",
-                    f"amesim.{data_path}",
-                    f"abs_error.{data_path}",
-                    f"rel_error.{data_path}",
-                ]
-            )
-        writer.writerow(header)
-        for index, time_value in enumerate(python_times):
-            row = [time_value]
-            for data_path in selected_paths:
-                python_value = float(python_series_by_data_path[data_path][index])
-                amesim_value = interpolate_series_value(
-                    amesim_results.times,
-                    amesim_results.series(data_path),
-                    float(time_value),
-                )
-                abs_error = abs(python_value - amesim_value)
-                rel_error = abs_error / max(abs(amesim_value), 1.0e-12)
-                row.extend([python_value, amesim_value, abs_error, rel_error])
-            writer.writerow(row)
-
-    summary_lines = [
-        (
-            f"{metric.data_path}: samples={metric.sample_count}, "
-            f"max_abs_error={metric.max_abs_error:.12g}, "
-            f"mean_abs_error={metric.mean_abs_error:.12g}, "
-            f"max_rel_error={metric.max_rel_error:.12%}, "
-            f"final_abs_error={metric.final_abs_error:.12g}"
-        )
-        for metric in comparison.metrics
-    ]
-    summary_path.write_text("\n".join(summary_lines) + "\n", encoding="utf-8")
-    return csv_path, summary_path, comparison
-
-
-def interpolate_series_value(
-    time_values: tuple[float, ...] | list[float],
-    values: tuple[float, ...] | list[float],
-    target_time: float,
-) -> float:
-    if len(time_values) != len(values):
-        raise TestMqlComparisonError("time and value series lengths differ.")
-    if not time_values:
-        raise TestMqlComparisonError("cannot interpolate an empty series.")
-    if target_time <= time_values[0]:
-        return float(values[0])
-    if target_time >= time_values[-1]:
-        return float(values[-1])
-
-    right_index = bisect_left(time_values, target_time)
-    if right_index < len(time_values) and abs(time_values[right_index] - target_time) <= 1.0e-12:
-        return float(values[right_index])
-
-    left_index = right_index - 1
-    left_time = float(time_values[left_index])
-    right_time = float(time_values[right_index])
-    fraction = (target_time - left_time) / (right_time - left_time)
-    return float(values[left_index]) + fraction * (float(values[right_index]) - float(values[left_index]))
-
-
-def _select_data_paths(
-    python_series_by_data_path: dict[str, tuple[float, ...] | list[float]],
-    amesim_results: AmesimResults,
-    data_paths: tuple[str, ...] | list[str] | None,
-) -> tuple[str, ...]:
-    if data_paths is None:
-        data_paths = tuple(
-            data_path
-            for data_path in python_series_by_data_path
-            if data_path in amesim_results.series_by_data_path
-        )
-    selected_paths = tuple(data_paths)
-    if not selected_paths:
-        raise TestMqlComparisonError("no common Data_Path values are available for comparison.")
-    missing_python = [data_path for data_path in selected_paths if data_path not in python_series_by_data_path]
-    if missing_python:
-        raise TestMqlComparisonError(f"Python series missing Data_Path values: {missing_python}")
-    _validate_amesim_data_paths(amesim_results, selected_paths)
-    return selected_paths
-
-
-def _validate_amesim_data_paths(
-    amesim_results: AmesimResults,
-    data_paths: tuple[str, ...] | list[str],
-) -> None:
-    missing_amesim = [data_path for data_path in data_paths if data_path not in amesim_results.series_by_data_path]
-    if missing_amesim:
-        raise TestMqlComparisonError(f"AMESim results missing Data_Path values: {missing_amesim}")
-
-
-def _validate_time_axis(time_values: tuple[float, ...] | list[float]) -> None:
-    if not time_values:
-        raise TestMqlComparisonError("Python time axis is empty.")
-    previous = float(time_values[0])
-    for value in time_values[1:]:
-        value = float(value)
-        if value < previous:
-            raise TestMqlComparisonError("Python time axis must be monotonically increasing.")
-        previous = value

app/simulation/reporting/test_mql_line_observations.py

@@ -1,211 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-from app.simulation.reporting.amesim_results import AmesimResults
-from app.simulation.reporting.test_mql_variables import (
-    TestMqlVariableBinding,
-    TestMqlVariableCatalog,
-    build_test_mql_variable_catalog,
-)
-from app.simulation.examples.test_mql.lines import (
-    TestMqlLineAssembly,
-    build_test_mql_line_assembly,
-)
-
-
-G_PER_S_TO_KG_PER_S = 1.0e-3
-
-
-@dataclass(frozen=True)
-class TestMqlLineObservation:
-    time: float
-    mass_flows_kg_s: dict[str, float]
-    enthalpy_flows_w: dict[str, float]
-    pressures_pa: dict[str, float]
-    temperatures_k: dict[str, float]
-    gas_mass_g: float | None
-    reynolds_number: float
-    mass_flow_parameter: float
-    gas_velocity_m_s: float
-    friction_factor: float
-
-
-@dataclass(frozen=True)
-class TestMqlLineObservationBinding:
-    alias: str
-    submodel: str
-    pattern: str
-    mass_flow_paths: tuple[str, ...]
-    enthalpy_flow_paths: tuple[str, ...]
-    pressure_paths: tuple[str, ...]
-    temperature_paths: tuple[str, ...]
-    gas_mass_path: str | None
-    reynolds_path: str
-    mass_flow_parameter_path: str
-    gas_velocity_path: str
-    friction_factor_path: str
-
-    def mass_flow_kg_s_series(
-        self,
-        results: AmesimResults,
-        data_path: str | None = None,
-    ) -> tuple[float, ...]:
-        path = data_path or self.mass_flow_paths[0]
-        if path not in self.mass_flow_paths:
-            raise KeyError(path)
-        return tuple(value * G_PER_S_TO_KG_PER_S for value in results.series(path))
-
-    def observation_at(self, results: AmesimResults, index: int) -> TestMqlLineObservation:
-        return TestMqlLineObservation(
-            time=results.times[index],
-            mass_flows_kg_s={
-                path: results.series(path)[index] * G_PER_S_TO_KG_PER_S
-                for path in self.mass_flow_paths
-            },
-            enthalpy_flows_w={
-                path: results.series(path)[index]
-                for path in self.enthalpy_flow_paths
-            },
-            pressures_pa={
-                path: results.series(path)[index]
-                for path in self.pressure_paths
-            },
-            temperatures_k={
-                path: results.series(path)[index]
-                for path in self.temperature_paths
-            },
-            gas_mass_g=(
-                results.series(self.gas_mass_path)[index]
-                if self.gas_mass_path is not None
-                else None
-            ),
-            reynolds_number=results.series(self.reynolds_path)[index],
-            mass_flow_parameter=results.series(self.mass_flow_parameter_path)[index],
-            gas_velocity_m_s=results.series(self.gas_velocity_path)[index],
-            friction_factor=results.series(self.friction_factor_path)[index],
-        )
-
-
-@dataclass(frozen=True)
-class TestMqlLineObservationCatalog:
-    bindings: tuple[TestMqlLineObservationBinding, ...]
-
-    @property
-    def line_count(self) -> int:
-        return len(self.bindings)
-
-    def by_alias(self, alias: str) -> TestMqlLineObservationBinding:
-        for binding in self.bindings:
-            if binding.alias == alias:
-                return binding
-        raise KeyError(alias)
-
-    def by_submodel(self, submodel: str) -> tuple[TestMqlLineObservationBinding, ...]:
-        return tuple(binding for binding in self.bindings if binding.submodel == submodel)
-
-
-def build_test_mql_line_observation_catalog(
-    results: AmesimResults,
-    *,
-    variable_catalog: TestMqlVariableCatalog | None = None,
-    line_assembly: TestMqlLineAssembly | None = None,
-) -> TestMqlLineObservationCatalog:
-    variable_catalog = variable_catalog or build_test_mql_variable_catalog(results)
-    line_assembly = line_assembly or build_test_mql_line_assembly(results, variable_catalog)
-    bindings = []
-    for line in line_assembly.lines:
-        variables = tuple(
-            variable
-            for variable in variable_catalog.variables
-            if variable.owner_alias == line.alias
-        )
-        bindings.append(
-            TestMqlLineObservationBinding(
-                alias=line.alias,
-                submodel=line.submodel,
-                pattern=line.pattern,
-                mass_flow_paths=_paths_with_prefix(variables, "dm", expected_units="g/s"),
-                enthalpy_flow_paths=_paths_with_prefix(variables, "dh", expected_units="J/s"),
-                pressure_paths=_paths_with_prefix(variables, "p", expected_units="Pa"),
-                temperature_paths=_paths_with_prefix(variables, "t", expected_units="K"),
-                gas_mass_path=_optional_path(variables, "mgas", expected_units="g"),
-                reynolds_path=_required_path(variables, "re", expected_units=None),
-                mass_flow_parameter_path=_required_path(
-                    variables,
-                    "cm",
-                    expected_units="(kg*K/J)**(1/2)",
-                ),
-                gas_velocity_path=_required_path(variables, "v", expected_units="m/s"),
-                friction_factor_path=_required_path(variables, "ff", expected_units=None),
-            )
-        )
-    return TestMqlLineObservationCatalog(bindings=tuple(bindings))
-
-
-def _paths_with_prefix(
-    variables: tuple[TestMqlVariableBinding, ...],
-    prefix: str,
-    *,
-    expected_units: str | None,
-) -> tuple[str, ...]:
-    matches = tuple(
-        variable
-        for variable in variables
-        if variable.signal_name.startswith(prefix)
-    )
-    for variable in matches:
-        _assert_units(variable, expected_units)
-    return tuple(variable.data_path for variable in matches)
-
-
-def _required_path(
-    variables: tuple[TestMqlVariableBinding, ...],
-    signal_name: str,
-    *,
-    expected_units: str | None,
-) -> str:
-    variable = _single_signal(variables, signal_name)
-    _assert_units(variable, expected_units)
-    return variable.data_path
-
-
-def _optional_path(
-    variables: tuple[TestMqlVariableBinding, ...],
-    signal_name: str,
-    *,
-    expected_units: str | None,
-) -> str | None:
-    matches = tuple(variable for variable in variables if variable.signal_name == signal_name)
-    if not matches:
-        return None
-    variable = _single(matches, signal_name)
-    _assert_units(variable, expected_units)
-    return variable.data_path
-
-
-def _single_signal(
-    variables: tuple[TestMqlVariableBinding, ...],
-    signal_name: str,
-) -> TestMqlVariableBinding:
-    return _single(
-        tuple(variable for variable in variables if variable.signal_name == signal_name),
-        signal_name,
-    )
-
-
-def _single(
-    matches: tuple[TestMqlVariableBinding, ...],
-    description: str,
-) -> TestMqlVariableBinding:
-    if len(matches) != 1:
-        raise ValueError(f"Expected one {description} variable, found {len(matches)}.")
-    return matches[0]
-
-
-def _assert_units(variable: TestMqlVariableBinding, expected_units: str | None) -> None:
-    if variable.units != expected_units:
-        raise ValueError(
-            f"Unexpected units for {variable.data_path}: "
-            f"{variable.units!r}, expected {expected_units!r}."
-        )

app/simulation/reporting/test_mql_mechanical_observations.py

@@ -1,395 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-from app.simulation.reporting.amesim_results import AmesimResults
-from app.simulation.reporting.test_mql_variables import (
-    TestMqlVariableBinding,
-    TestMqlVariableCatalog,
-    build_test_mql_variable_catalog,
-)
-from app.simulation.examples.test_mql.mechanical import (
-    TestMqlMechanicalAssembly,
-    build_test_mql_mechanical_assembly,
-)
-
-
-@dataclass(frozen=True)
-class TestMqlPistonObservation:
-    time: float
-    chamber_volume_cm3: float
-    chamber_volume_rate_l_min: float
-    chamber_length_mm: float
-    force_port_2_n: float
-    force_port_3_n: float
-    displacement_port_2_m: float
-    velocity_port_2_m_s: float
-    displacement_port_3_m: float
-    velocity_port_3_m_s: float
-
-
-@dataclass(frozen=True)
-class TestMqlMassEndstopObservation:
-    time: float
-    displacement_m: float
-    velocity_m_s: float
-    acceleration_m_s2: float
-    lower_contact_force_n: float
-    upper_contact_force_n: float
-    viscous_friction_force_n: float
-    dry_friction_force_n: float
-    stick_flag: float
-
-
-@dataclass(frozen=True)
-class TestMqlElasticEndstopObservation:
-    time: float
-    force_n: float
-    duplicate_force_n: float
-    gap_mm: float
-    stiffness_n_m: float
-
-
-@dataclass(frozen=True)
-class TestMqlForceSourceObservation:
-    time: float
-    force_n: float
-
-
-@dataclass(frozen=True)
-class TestMqlForceConnectorObservation:
-    time: float
-    force_n: float
-
-
-@dataclass(frozen=True)
-class TestMqlMechanicalNodeObservation:
-    time: float
-    velocities_m_s: dict[int, float]
-    displacements_m: dict[int, float]
-    total_force_n: float
-
-
-@dataclass(frozen=True)
-class TestMqlPistonObservationBinding:
-    alias: str
-    volume_path: str
-    volume_rate_path: str
-    length_path: str
-    force_port_2_path: str
-    force_port_3_path: str
-    displacement_port_2_path: str
-    velocity_port_2_path: str
-    displacement_port_3_path: str
-    velocity_port_3_path: str
-
-    def observation_at(self, results: AmesimResults, index: int) -> TestMqlPistonObservation:
-        return TestMqlPistonObservation(
-            time=results.times[index],
-            chamber_volume_cm3=results.series(self.volume_path)[index],
-            chamber_volume_rate_l_min=results.series(self.volume_rate_path)[index],
-            chamber_length_mm=results.series(self.length_path)[index],
-            force_port_2_n=results.series(self.force_port_2_path)[index],
-            force_port_3_n=results.series(self.force_port_3_path)[index],
-            displacement_port_2_m=results.series(self.displacement_port_2_path)[index],
-            velocity_port_2_m_s=results.series(self.velocity_port_2_path)[index],
-            displacement_port_3_m=results.series(self.displacement_port_3_path)[index],
-            velocity_port_3_m_s=results.series(self.velocity_port_3_path)[index],
-        )
-
-
-@dataclass(frozen=True)
-class TestMqlMassEndstopObservationBinding:
-    alias: str
-    displacement_path: str
-    velocity_path: str
-    acceleration_path: str
-    displacement_duplicate_path: str
-    velocity_duplicate_path: str
-    acceleration_duplicate_path: str
-    lower_contact_force_path: str
-    upper_contact_force_path: str
-    viscous_friction_force_path: str
-    dry_friction_force_path: str
-    stick_flag_path: str
-
-    def observation_at(self, results: AmesimResults, index: int) -> TestMqlMassEndstopObservation:
-        return TestMqlMassEndstopObservation(
-            time=results.times[index],
-            displacement_m=results.series(self.displacement_path)[index],
-            velocity_m_s=results.series(self.velocity_path)[index],
-            acceleration_m_s2=results.series(self.acceleration_path)[index],
-            lower_contact_force_n=results.series(self.lower_contact_force_path)[index],
-            upper_contact_force_n=results.series(self.upper_contact_force_path)[index],
-            viscous_friction_force_n=results.series(self.viscous_friction_force_path)[index],
-            dry_friction_force_n=results.series(self.dry_friction_force_path)[index],
-            stick_flag=results.series(self.stick_flag_path)[index],
-        )
-
-
-@dataclass(frozen=True)
-class TestMqlElasticEndstopObservationBinding:
-    alias: str
-    force_path: str
-    duplicate_force_path: str
-    gap_path: str
-    stiffness_path: str
-
-    def observation_at(self, results: AmesimResults, index: int) -> TestMqlElasticEndstopObservation:
-        return TestMqlElasticEndstopObservation(
-            time=results.times[index],
-            force_n=results.series(self.force_path)[index],
-            duplicate_force_n=results.series(self.duplicate_force_path)[index],
-            gap_mm=results.series(self.gap_path)[index],
-            stiffness_n_m=results.series(self.stiffness_path)[index],
-        )
-
-
-@dataclass(frozen=True)
-class TestMqlForceSourceObservationBinding:
-    alias: str
-    force_path: str
-
-    def observation_at(self, results: AmesimResults, index: int) -> TestMqlForceSourceObservation:
-        return TestMqlForceSourceObservation(
-            time=results.times[index],
-            force_n=results.series(self.force_path)[index],
-        )
-
-
-@dataclass(frozen=True)
-class TestMqlForceConnectorObservationBinding:
-    alias: str
-    force_path: str
-
-    def observation_at(self, results: AmesimResults, index: int) -> TestMqlForceConnectorObservation:
-        return TestMqlForceConnectorObservation(
-            time=results.times[index],
-            force_n=results.series(self.force_path)[index],
-        )
-
-
-@dataclass(frozen=True)
-class TestMqlMechanicalNodeObservationBinding:
-    alias: str
-    velocity_paths_by_port: dict[int, str]
-    displacement_paths_by_port: dict[int, str]
-    total_force_path: str
-
-    def observation_at(self, results: AmesimResults, index: int) -> TestMqlMechanicalNodeObservation:
-        return TestMqlMechanicalNodeObservation(
-            time=results.times[index],
-            velocities_m_s={
-                port: results.series(path)[index]
-                for port, path in self.velocity_paths_by_port.items()
-            },
-            displacements_m={
-                port: results.series(path)[index]
-                for port, path in self.displacement_paths_by_port.items()
-            },
-            total_force_n=results.series(self.total_force_path)[index],
-        )
-
-
-@dataclass(frozen=True)
-class TestMqlMechanicalObservationCatalog:
-    pistons: dict[str, TestMqlPistonObservationBinding]
-    masses: dict[str, TestMqlMassEndstopObservationBinding]
-    elastic_endstops: dict[str, TestMqlElasticEndstopObservationBinding]
-    zero_force_sources: dict[str, TestMqlForceSourceObservationBinding]
-    force_connectors: dict[str, TestMqlForceConnectorObservationBinding]
-    mechanical_nodes: dict[str, TestMqlMechanicalNodeObservationBinding]
-
-    @property
-    def binding_count(self) -> int:
-        return (
-            len(self.pistons)
-            + len(self.masses)
-            + len(self.elastic_endstops)
-            + len(self.zero_force_sources)
-            + len(self.force_connectors)
-            + len(self.mechanical_nodes)
-        )
-
-
-def build_test_mql_mechanical_observation_catalog(
-    results: AmesimResults,
-    *,
-    variable_catalog: TestMqlVariableCatalog | None = None,
-    mechanical_assembly: TestMqlMechanicalAssembly | None = None,
-) -> TestMqlMechanicalObservationCatalog:
-    variable_catalog = variable_catalog or build_test_mql_variable_catalog(results)
-    mechanical_assembly = mechanical_assembly or build_test_mql_mechanical_assembly(
-        amesim_results=results,
-        variable_catalog=variable_catalog,
-    )
-    return TestMqlMechanicalObservationCatalog(
-        pistons={
-            alias: _build_piston_binding(alias, variable_catalog)
-            for alias in mechanical_assembly.pistons
-        },
-        masses={
-            alias: _build_mass_binding(alias, variable_catalog)
-            for alias in mechanical_assembly.masses
-        },
-        elastic_endstops={
-            alias: _build_elastic_endstop_binding(alias, variable_catalog)
-            for alias in mechanical_assembly.elastic_endstops
-        },
-        zero_force_sources={
-            alias: _build_zero_force_source_binding(alias, variable_catalog)
-            for alias in mechanical_assembly.zero_force_sources
-        },
-        force_connectors={
-            alias: _build_force_connector_binding(alias, variable_catalog)
-            for alias in mechanical_assembly.force_connectors
-        },
-        mechanical_nodes={
-            alias: _build_mechanical_node_binding(alias, variable_catalog)
-            for alias in mechanical_assembly.mechanical_nodes
-        },
-    )
-
-
-def _build_piston_binding(
-    alias: str,
-    variable_catalog: TestMqlVariableCatalog,
-) -> TestMqlPistonObservationBinding:
-    variables = _owner_variables(variable_catalog, alias)
-    return TestMqlPistonObservationBinding(
-        alias=alias,
-        volume_path=_required_path(variables, "vol1", expected_units="cm**3"),
-        volume_rate_path=_required_path(variables, "vvol1", expected_units="L/min"),
-        length_path=_required_path(variables, "length", expected_units="mm"),
-        force_port_2_path=_required_path(variables, "f2", expected_units="N"),
-        force_port_3_path=_required_path(variables, "f3", expected_units="N"),
-        displacement_port_2_path=_required_path(variables, "x5", expected_units="m"),
-        velocity_port_2_path=_required_path(variables, "v5", expected_units="m/s"),
-        displacement_port_3_path=_required_path(variables, "x4", expected_units="m"),
-        velocity_port_3_path=_required_path(variables, "v4", expected_units="m/s"),
-    )
-
-
-def _build_mass_binding(
-    alias: str,
-    variable_catalog: TestMqlVariableCatalog,
-) -> TestMqlMassEndstopObservationBinding:
-    variables = _owner_variables(variable_catalog, alias)
-    return TestMqlMassEndstopObservationBinding(
-        alias=alias,
-        displacement_path=_required_path(variables, "x1", expected_units="m"),
-        velocity_path=_required_path(variables, "v1", expected_units="m/s"),
-        acceleration_path=_required_path(variables, "acc1", expected_units="m/s/s"),
-        displacement_duplicate_path=_required_path(variables, "x1dup", expected_units="m"),
-        velocity_duplicate_path=_required_path(variables, "v1dup", expected_units="m/s"),
-        acceleration_duplicate_path=_required_path(variables, "acc1dup", expected_units="m/s/s"),
-        lower_contact_force_path=_required_path(variables, "Fmin", expected_units="N"),
-        upper_contact_force_path=_required_path(variables, "Fmax", expected_units="N"),
-        viscous_friction_force_path=_required_path(variables, "Fvisc", expected_units="N"),
-        dry_friction_force_path=_required_path(variables, "Ffric", expected_units="N"),
-        stick_flag_path=_required_path(variables, "stick", expected_units=None),
-    )
-
-
-def _build_elastic_endstop_binding(
-    alias: str,
-    variable_catalog: TestMqlVariableCatalog,
-) -> TestMqlElasticEndstopObservationBinding:
-    variables = _owner_variables(variable_catalog, alias)
-    return TestMqlElasticEndstopObservationBinding(
-        alias=alias,
-        force_path=_required_path(variables, "f1", expected_units="N"),
-        duplicate_force_path=_required_path(variables, "f2", expected_units="N"),
-        gap_path=_required_path(variables, "gap", expected_units="mm"),
-        stiffness_path=_required_path(variables, "kval", expected_units="N/m"),
-    )
-
-
-def _build_zero_force_source_binding(
-    alias: str,
-    variable_catalog: TestMqlVariableCatalog,
-) -> TestMqlForceSourceObservationBinding:
-    variables = _owner_variables(variable_catalog, alias)
-    return TestMqlForceSourceObservationBinding(
-        alias=alias,
-        force_path=_required_path(variables, "fzero", expected_units="N"),
-    )
-
-
-def _build_force_connector_binding(
-    alias: str,
-    variable_catalog: TestMqlVariableCatalog,
-) -> TestMqlForceConnectorObservationBinding:
-    variables = _owner_variables(variable_catalog, alias)
-    return TestMqlForceConnectorObservationBinding(
-        alias=alias,
-        force_path=_required_path(variables, "force", expected_units="N"),
-    )
-
-
-def _build_mechanical_node_binding(
-    alias: str,
-    variable_catalog: TestMqlVariableCatalog,
-) -> TestMqlMechanicalNodeObservationBinding:
-    variables = _owner_variables(variable_catalog, alias)
-    velocity_paths_by_port = {}
-    displacement_paths_by_port = {}
-    for port in range(1, 9):
-        velocity_paths_by_port[port] = _required_path(
-            variables,
-            f"p{port}__vt",
-            expected_units="m/s",
-        )
-        displacement_paths_by_port[port] = _required_path(
-            variables,
-            f"p{port}__xt",
-            expected_units="m",
-        )
-    return TestMqlMechanicalNodeObservationBinding(
-        alias=alias,
-        velocity_paths_by_port=velocity_paths_by_port,
-        displacement_paths_by_port=displacement_paths_by_port,
-        total_force_path=_required_path(variables, "tforce", expected_units="N"),
-    )
-
-
-def _owner_variables(
-    variable_catalog: TestMqlVariableCatalog,
-    alias: str,
-) -> tuple[TestMqlVariableBinding, ...]:
-    return tuple(
-        variable
-        for variable in variable_catalog.variables
-        if variable.owner_alias == alias
-    )
-
-
-def _required_path(
-    variables: tuple[TestMqlVariableBinding, ...],
-    signal_name: str,
-    *,
-    expected_units: str | None,
-) -> str:
-    variable = _single(
-        tuple(variable for variable in variables if variable.signal_name == signal_name),
-        signal_name,
-    )
-    _assert_units(variable, expected_units)
-    return variable.data_path
-
-
-def _single(
-    matches: tuple[TestMqlVariableBinding, ...],
-    description: str,
-) -> TestMqlVariableBinding:
-    if len(matches) != 1:
-        raise ValueError(f"Expected one {description} variable, found {len(matches)}.")
-    return matches[0]
-
-
-def _assert_units(variable: TestMqlVariableBinding, expected_units: str | None) -> None:
-    if variable.units != expected_units:
-        raise ValueError(
-            f"Unexpected units for {variable.data_path}: "
-            f"{variable.units!r}, expected {expected_units!r}."
-        )

app/simulation/reporting/test_mql_observations.py

@@ -1,210 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-from app.simulation.reporting.amesim_results import AmesimResults
-from app.simulation.reporting.test_mql_chamber_observations import (
-    TestMqlChamberObservationCatalog,
-    build_test_mql_chamber_observation_catalog,
-)
-from app.simulation.reporting.test_mql_line_observations import (
-    TestMqlLineObservationCatalog,
-    build_test_mql_line_observation_catalog,
-)
-from app.simulation.reporting.test_mql_mechanical_observations import (
-    TestMqlMechanicalObservationCatalog,
-    build_test_mql_mechanical_observation_catalog,
-)
-from app.simulation.reporting.test_mql_orifice_observations import (
-    TestMqlOrificeObservationCatalog,
-    build_test_mql_orifice_observation_catalog,
-)
-from app.simulation.reporting.test_mql_variables import (
-    TestMqlVariableCatalog,
-    build_test_mql_variable_catalog,
-)
-
-
-@dataclass(frozen=True)
-class TestMqlObservationCatalog:
-    variable_catalog: TestMqlVariableCatalog
-    chambers: TestMqlChamberObservationCatalog
-    orifices: TestMqlOrificeObservationCatalog
-    lines: TestMqlLineObservationCatalog
-    mechanical: TestMqlMechanicalObservationCatalog
-
-    @property
-    def binding_count(self) -> int:
-        return (
-            len(self.chambers.bindings)
-            + len(self.orifices.bindings)
-            + self.lines.line_count
-            + self.mechanical.binding_count
-        )
-
-    def data_paths_by_domain(self) -> dict[str, tuple[str, ...]]:
-        return {
-            "chambers": _sorted_unique(_chamber_data_paths(self.chambers)),
-            "orifices": _sorted_unique(_orifice_data_paths(self.orifices)),
-            "lines": _sorted_unique(_line_data_paths(self.lines)),
-            "mechanical": _sorted_unique(_mechanical_data_paths(self.mechanical)),
-        }
-
-    def data_paths(self) -> tuple[str, ...]:
-        paths = []
-        for domain_paths in self.data_paths_by_domain().values():
-            paths.extend(domain_paths)
-        return _sorted_unique(paths)
-
-    def baseline_series_by_data_path(
-        self,
-        results: AmesimResults,
-        data_paths: tuple[str, ...] | list[str] | None = None,
-    ) -> dict[str, tuple[float, ...]]:
-        selected_paths = tuple(data_paths) if data_paths is not None else self.data_paths()
-        _validate_observed_paths(self, selected_paths)
-        return {data_path: results.series(data_path) for data_path in selected_paths}
-
-
-def build_test_mql_observation_catalog(results: AmesimResults) -> TestMqlObservationCatalog:
-    variable_catalog = build_test_mql_variable_catalog(results)
-    return TestMqlObservationCatalog(
-        variable_catalog=variable_catalog,
-        chambers=build_test_mql_chamber_observation_catalog(
-            results,
-            variable_catalog=variable_catalog,
-        ),
-        orifices=build_test_mql_orifice_observation_catalog(
-            results,
-            variable_catalog=variable_catalog,
-        ),
-        lines=build_test_mql_line_observation_catalog(
-            results,
-            variable_catalog=variable_catalog,
-        ),
-        mechanical=build_test_mql_mechanical_observation_catalog(
-            results,
-            variable_catalog=variable_catalog,
-        ),
-    )
-
-
-def _chamber_data_paths(catalog: TestMqlChamberObservationCatalog) -> tuple[str, ...]:
-    paths = []
-    for binding in catalog.bindings:
-        paths.extend(
-            [
-                binding.pressure_path,
-                binding.temperature_path,
-                binding.gas_mass_path,
-                *binding.pressure_duplicate_paths,
-                *binding.temperature_duplicate_paths,
-            ]
-        )
-        if binding.volume_path is not None:
-            paths.append(binding.volume_path)
-    return tuple(paths)
-
-
-def _orifice_data_paths(catalog: TestMqlOrificeObservationCatalog) -> tuple[str, ...]:
-    paths = []
-    for binding in catalog.bindings:
-        paths.extend(
-            [
-                binding.primary_mass_flow_path,
-                binding.primary_enthalpy_flow_path,
-                binding.reversed_mass_flow_path,
-                binding.reversed_enthalpy_flow_path,
-                binding.mass_flow_parameter_path,
-                binding.gas_velocity_path,
-            ]
-        )
-        if binding.opening_path is not None:
-            paths.append(binding.opening_path)
-    return tuple(paths)
-
-
-def _line_data_paths(catalog: TestMqlLineObservationCatalog) -> tuple[str, ...]:
-    paths = []
-    for binding in catalog.bindings:
-        paths.extend(binding.mass_flow_paths)
-        paths.extend(binding.enthalpy_flow_paths)
-        paths.extend(binding.pressure_paths)
-        paths.extend(binding.temperature_paths)
-        if binding.gas_mass_path is not None:
-            paths.append(binding.gas_mass_path)
-        paths.extend(
-            [
-                binding.reynolds_path,
-                binding.mass_flow_parameter_path,
-                binding.gas_velocity_path,
-                binding.friction_factor_path,
-            ]
-        )
-    return tuple(paths)
-
-
-def _mechanical_data_paths(catalog: TestMqlMechanicalObservationCatalog) -> tuple[str, ...]:
-    paths = []
-    for binding in catalog.pistons.values():
-        paths.extend(
-            [
-                binding.volume_path,
-                binding.volume_rate_path,
-                binding.length_path,
-                binding.force_port_2_path,
-                binding.force_port_3_path,
-                binding.displacement_port_2_path,
-                binding.velocity_port_2_path,
-                binding.displacement_port_3_path,
-                binding.velocity_port_3_path,
-            ]
-        )
-    for binding in catalog.masses.values():
-        paths.extend(
-            [
-                binding.displacement_path,
-                binding.velocity_path,
-                binding.acceleration_path,
-                binding.displacement_duplicate_path,
-                binding.velocity_duplicate_path,
-                binding.acceleration_duplicate_path,
-                binding.lower_contact_force_path,
-                binding.upper_contact_force_path,
-                binding.viscous_friction_force_path,
-                binding.dry_friction_force_path,
-                binding.stick_flag_path,
-            ]
-        )
-    for binding in catalog.elastic_endstops.values():
-        paths.extend(
-            [
-                binding.force_path,
-                binding.duplicate_force_path,
-                binding.gap_path,
-                binding.stiffness_path,
-            ]
-        )
-    for binding in catalog.zero_force_sources.values():
-        paths.append(binding.force_path)
-    for binding in catalog.force_connectors.values():
-        paths.append(binding.force_path)
-    for binding in catalog.mechanical_nodes.values():
-        paths.extend(binding.velocity_paths_by_port.values())
-        paths.extend(binding.displacement_paths_by_port.values())
-        paths.append(binding.total_force_path)
-    return tuple(paths)
-
-
-def _validate_observed_paths(
-    catalog: TestMqlObservationCatalog,
-    data_paths: tuple[str, ...],
-) -> None:
-    observed_paths = set(catalog.data_paths())
-    missing = [data_path for data_path in data_paths if data_path not in observed_paths]
-    if missing:
-        raise KeyError(f"Data_Path values are not in the test_mql observation catalog: {missing}")
-
-
-def _sorted_unique(data_paths: tuple[str, ...] | list[str]) -> tuple[str, ...]:
-    return tuple(sorted(set(data_paths)))

app/simulation/reporting/test_mql_orifice_observations.py

@@ -1,194 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-from app.simulation.reporting.amesim_results import AmesimResults
-from app.simulation.reporting.test_mql_variables import (
-    TestMqlVariableBinding,
-    TestMqlVariableCatalog,
-    build_test_mql_variable_catalog,
-)
-from app.simulation.examples.test_mql.pneumatic import (
-    TestMqlPneumaticAssembly,
-    build_test_mql_pneumatic_assembly,
-)
-
-
-G_PER_S_TO_KG_PER_S = 1.0e-3
-
-
-@dataclass(frozen=True)
-class TestMqlOrificeObservation:
-    time: float
-    mass_flow_kg_s: float
-    enthalpy_flow_w: float
-    mass_flow_parameter: float
-    gas_velocity_m_s: float
-    opening: float
-    effective_area_m2: float
-
-
-@dataclass(frozen=True)
-class TestMqlOrificeBinding:
-    alias: str
-    submodel: str
-    nominal_area_m2: float
-    flow_coefficient: float
-    primary_mass_flow_path: str
-    primary_enthalpy_flow_path: str
-    reversed_mass_flow_path: str
-    reversed_enthalpy_flow_path: str
-    mass_flow_parameter_path: str
-    gas_velocity_path: str
-    opening_path: str | None
-
-    @property
-    def is_variable(self) -> bool:
-        return self.opening_path is not None
-
-    def opening_series(self, results: AmesimResults) -> tuple[float, ...]:
-        if self.opening_path is None:
-            return tuple(1.0 for _ in results.times)
-        return tuple(results.series(self.opening_path))
-
-    def mass_flow_kg_s_series(self, results: AmesimResults) -> tuple[float, ...]:
-        return tuple(value * G_PER_S_TO_KG_PER_S for value in results.series(self.primary_mass_flow_path))
-
-    def reversed_mass_flow_kg_s_series(self, results: AmesimResults) -> tuple[float, ...]:
-        return tuple(value * G_PER_S_TO_KG_PER_S for value in results.series(self.reversed_mass_flow_path))
-
-    def effective_area_series(self, results: AmesimResults) -> tuple[float, ...]:
-        return tuple(self.nominal_area_m2 * max(opening, 0.0) for opening in self.opening_series(results))
-
-    def observation_at(self, results: AmesimResults, index: int) -> TestMqlOrificeObservation:
-        opening = self.opening_series(results)[index]
-        return TestMqlOrificeObservation(
-            time=results.times[index],
-            mass_flow_kg_s=results.series(self.primary_mass_flow_path)[index] * G_PER_S_TO_KG_PER_S,
-            enthalpy_flow_w=results.series(self.primary_enthalpy_flow_path)[index],
-            mass_flow_parameter=results.series(self.mass_flow_parameter_path)[index],
-            gas_velocity_m_s=results.series(self.gas_velocity_path)[index],
-            opening=opening,
-            effective_area_m2=self.nominal_area_m2 * max(opening, 0.0),
-        )
-
-
-@dataclass(frozen=True)
-class TestMqlOrificeObservationCatalog:
-    bindings: tuple[TestMqlOrificeBinding, ...]
-
-    @property
-    def fixed_count(self) -> int:
-        return sum(1 for binding in self.bindings if binding.submodel == "PNOR001")
-
-    @property
-    def variable_count(self) -> int:
-        return sum(1 for binding in self.bindings if binding.submodel == "PNVO001")
-
-    def by_alias(self, alias: str) -> TestMqlOrificeBinding:
-        for binding in self.bindings:
-            if binding.alias == alias:
-                return binding
-        raise KeyError(alias)
-
-
-def build_test_mql_orifice_observation_catalog(
-    results: AmesimResults,
-    *,
-    variable_catalog: TestMqlVariableCatalog | None = None,
-    assembly: TestMqlPneumaticAssembly | None = None,
-) -> TestMqlOrificeObservationCatalog:
-    variable_catalog = variable_catalog or build_test_mql_variable_catalog(results)
-    assembly = assembly or build_test_mql_pneumatic_assembly()
-    bindings = []
-    for alias, orifice in {
-        **assembly.fixed_orifices,
-        **assembly.variable_orifices,
-    }.items():
-        owner_variables = tuple(
-            variable
-            for variable in variable_catalog.variables
-            if variable.owner_alias == alias
-        )
-        primary_mass_flow = _find_primary(owner_variables, signal_prefix="dm")
-        primary_enthalpy_flow = _find_primary(owner_variables, signal_prefix="dh")
-        reversed_mass_flow = _find_reversed(owner_variables, signal_prefix="dm")
-        reversed_enthalpy_flow = _find_reversed(owner_variables, signal_prefix="dh")
-        mass_flow_parameter = _find_by_signal(owner_variables, "cm")
-        gas_velocity = _find_by_signal(owner_variables, "gasvel")
-        opening = _find_optional_by_signal(owner_variables, "xv")
-        bindings.append(
-            TestMqlOrificeBinding(
-                alias=alias,
-                submodel=primary_mass_flow.submodel,
-                nominal_area_m2=orifice.area,
-                flow_coefficient=orifice.flow_coefficient,
-                primary_mass_flow_path=primary_mass_flow.data_path,
-                primary_enthalpy_flow_path=primary_enthalpy_flow.data_path,
-                reversed_mass_flow_path=reversed_mass_flow.data_path,
-                reversed_enthalpy_flow_path=reversed_enthalpy_flow.data_path,
-                mass_flow_parameter_path=mass_flow_parameter.data_path,
-                gas_velocity_path=gas_velocity.data_path,
-                opening_path=opening.data_path if opening is not None else None,
-            )
-        )
-    return TestMqlOrificeObservationCatalog(
-        bindings=tuple(sorted(bindings, key=lambda binding: binding.alias))
-    )
-
-
-def _find_primary(
-    variables: tuple[TestMqlVariableBinding, ...],
-    *,
-    signal_prefix: str,
-) -> TestMqlVariableBinding:
-    matches = [
-        variable
-        for variable in variables
-        if variable.signal_name.startswith(signal_prefix)
-        and "sign reversed duplicate" not in variable.label
-    ]
-    return _single(matches, f"primary {signal_prefix}")
-
-
-def _find_reversed(
-    variables: tuple[TestMqlVariableBinding, ...],
-    *,
-    signal_prefix: str,
-) -> TestMqlVariableBinding:
-    matches = [
-        variable
-        for variable in variables
-        if variable.signal_name.startswith(signal_prefix)
-        and "sign reversed duplicate" in variable.label
-    ]
-    return _single(matches, f"reversed {signal_prefix}")
-
-
-def _find_by_signal(
-    variables: tuple[TestMqlVariableBinding, ...],
-    signal_name: str,
-) -> TestMqlVariableBinding:
-    return _single(
-        [variable for variable in variables if variable.signal_name == signal_name],
-        signal_name,
-    )
-
-
-def _find_optional_by_signal(
-    variables: tuple[TestMqlVariableBinding, ...],
-    signal_name: str,
-) -> TestMqlVariableBinding | None:
-    matches = [variable for variable in variables if variable.signal_name == signal_name]
-    if not matches:
-        return None
-    return _single(matches, signal_name)
-
-
-def _single(
-    matches: list[TestMqlVariableBinding],
-    description: str,
-) -> TestMqlVariableBinding:
-    if len(matches) != 1:
-        raise ValueError(f"Expected one {description} variable, found {len(matches)}.")
-    return matches[0]

app/simulation/reporting/test_mql_output_schema.py

@@ -1,100 +0,0 @@
-from __future__ import annotations
-
-from collections import Counter
-from dataclasses import dataclass
-
-from app.simulation.reporting.amesim_results import AmesimResults
-from app.simulation.reporting.test_mql_observations import (
-    TestMqlObservationCatalog,
-    build_test_mql_observation_catalog,
-)
-from app.simulation.reporting.test_mql_variables import TestMqlVariableBinding
-
-
-@dataclass(frozen=True)
-class TestMqlOutputSignal:
-    data_path: str
-    domain: str
-    owner_alias: str
-    owner_kind: str
-    submodel: str
-    signal_name: str
-    units: str | None
-    amesim_index: int
-    saved: bool
-
-
-@dataclass(frozen=True)
-class TestMqlOutputSchema:
-    signals: tuple[TestMqlOutputSignal, ...]
-
-    @property
-    def signal_count(self) -> int:
-        return len(self.signals)
-
-    def by_data_path(self, data_path: str) -> TestMqlOutputSignal:
-        for signal in self.signals:
-            if signal.data_path == data_path:
-                return signal
-        raise KeyError(data_path)
-
-    def data_paths(self) -> tuple[str, ...]:
-        return tuple(signal.data_path for signal in self.signals)
-
-    def data_paths_by_domain(self, domain: str) -> tuple[str, ...]:
-        return tuple(signal.data_path for signal in self.signals if signal.domain == domain)
-
-    def counts_by_domain(self) -> dict[str, int]:
-        return dict(Counter(signal.domain for signal in self.signals))
-
-    def counts_by_submodel(self) -> dict[str, int]:
-        return dict(Counter(signal.submodel for signal in self.signals))
-
-    def counts_by_owner_kind(self) -> dict[str, int]:
-        return dict(Counter(signal.owner_kind for signal in self.signals))
-
-    def counts_by_units(self) -> dict[str | None, int]:
-        return dict(Counter(signal.units for signal in self.signals))
-
-
-def build_test_mql_output_schema(
-    results: AmesimResults,
-    *,
-    observation_catalog: TestMqlObservationCatalog | None = None,
-) -> TestMqlOutputSchema:
-    observation_catalog = observation_catalog or build_test_mql_observation_catalog(results)
-    domain_by_data_path = _domain_by_data_path(observation_catalog)
-    signals = []
-    for data_path in sorted(domain_by_data_path):
-        variable = observation_catalog.variable_catalog.by_data_path(data_path)
-        signals.append(_signal_from_variable(variable, domain_by_data_path[data_path]))
-    return TestMqlOutputSchema(signals=tuple(signals))
-
-
-def _domain_by_data_path(
-    observation_catalog: TestMqlObservationCatalog,
-) -> dict[str, str]:
-    domain_by_data_path = {}
-    for domain, data_paths in observation_catalog.data_paths_by_domain().items():
-        for data_path in data_paths:
-            if data_path in domain_by_data_path:
-                raise ValueError(f"Data_Path {data_path!r} is assigned to multiple domains.")
-            domain_by_data_path[data_path] = domain
-    return domain_by_data_path
-
-
-def _signal_from_variable(
-    variable: TestMqlVariableBinding,
-    domain: str,
-) -> TestMqlOutputSignal:
-    return TestMqlOutputSignal(
-        data_path=variable.data_path,
-        domain=domain,
-        owner_alias=variable.owner_alias,
-        owner_kind=variable.owner_kind,
-        submodel=variable.submodel,
-        signal_name=variable.signal_name,
-        units=variable.units,
-        amesim_index=variable.index,
-        saved=variable.saved,
-    )

app/simulation/reporting/test_mql_output_validation.py

@@ -1,161 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-from math import isfinite
-
-from app.simulation.reporting.amesim_results import AmesimResults
-from app.simulation.reporting.test_mql_comparison import (
-    TestMqlComparisonResult,
-    compare_test_mql_series,
-)
-from app.simulation.reporting.test_mql_output_schema import TestMqlOutputSchema
-
-
-class TestMqlOutputValidationError(ValueError):
-    """Raised when a Python test_mql output does not satisfy the AMESim output contract."""
-
-
-@dataclass(frozen=True)
-class TestMqlValidatedOutput:
-    times: tuple[float, ...]
-    series_by_data_path: dict[str, tuple[float, ...]]
-    data_paths: tuple[str, ...]
-
-    def series(self, data_path: str) -> tuple[float, ...]:
-        if data_path not in self.series_by_data_path:
-            raise KeyError(data_path)
-        return self.series_by_data_path[data_path]
-
-
-def validate_test_mql_output(
-    *,
-    times: tuple[float, ...] | list[float],
-    series_by_data_path: dict[str, tuple[float, ...] | list[float]],
-    schema: TestMqlOutputSchema,
-    data_paths: tuple[str, ...] | list[str] | None = None,
-    allow_extra_paths: bool = False,
-    require_all_schema_paths: bool = False,
-) -> TestMqlValidatedOutput:
-    validated_times = _validate_time_axis(times)
-    selected_paths = _select_paths(
-        series_by_data_path=series_by_data_path,
-        schema=schema,
-        data_paths=data_paths,
-        allow_extra_paths=allow_extra_paths,
-        require_all_schema_paths=require_all_schema_paths,
-    )
-    validated_series = {
-        data_path: _validate_series(
-            data_path=data_path,
-            values=series_by_data_path[data_path],
-            expected_count=len(validated_times),
-        )
-        for data_path in selected_paths
-    }
-    return TestMqlValidatedOutput(
-        times=validated_times,
-        series_by_data_path=validated_series,
-        data_paths=selected_paths,
-    )
-
-
-def compare_validated_test_mql_output(
-    *,
-    times: tuple[float, ...] | list[float],
-    series_by_data_path: dict[str, tuple[float, ...] | list[float]],
-    schema: TestMqlOutputSchema,
-    amesim_results: AmesimResults,
-    data_paths: tuple[str, ...] | list[str] | None = None,
-    allow_extra_paths: bool = False,
-    require_all_schema_paths: bool = False,
-    relative_floor: float = 1.0e-12,
-) -> TestMqlComparisonResult:
-    validated = validate_test_mql_output(
-        times=times,
-        series_by_data_path=series_by_data_path,
-        schema=schema,
-        data_paths=data_paths,
-        allow_extra_paths=allow_extra_paths,
-        require_all_schema_paths=require_all_schema_paths,
-    )
-    return compare_test_mql_series(
-        python_times=validated.times,
-        python_series_by_data_path=validated.series_by_data_path,
-        amesim_results=amesim_results,
-        data_paths=validated.data_paths,
-        relative_floor=relative_floor,
-    )
-
-
-def _validate_time_axis(times: tuple[float, ...] | list[float]) -> tuple[float, ...]:
-    if not times:
-        raise TestMqlOutputValidationError("Python time axis is empty.")
-    validated = tuple(_finite_float("time", value) for value in times)
-    previous = validated[0]
-    for value in validated[1:]:
-        if value < previous:
-            raise TestMqlOutputValidationError("Python time axis must be monotonically increasing.")
-        previous = value
-    return validated
-
-
-def _select_paths(
-    *,
-    series_by_data_path: dict[str, tuple[float, ...] | list[float]],
-    schema: TestMqlOutputSchema,
-    data_paths: tuple[str, ...] | list[str] | None,
-    allow_extra_paths: bool,
-    require_all_schema_paths: bool,
-) -> tuple[str, ...]:
-    schema_paths = set(schema.data_paths())
-    provided_paths = set(series_by_data_path)
-    if not allow_extra_paths:
-        extra_paths = sorted(provided_paths - schema_paths)
-        if extra_paths:
-            raise TestMqlOutputValidationError(
-                f"Python output contains Data_Path values outside test_mql schema: {extra_paths}"
-            )
-    if require_all_schema_paths:
-        missing_schema_paths = sorted(schema_paths - provided_paths)
-        if missing_schema_paths:
-            raise TestMqlOutputValidationError(
-                f"Python output is missing required test_mql schema Data_Path values: {missing_schema_paths}"
-            )
-    selected_paths = tuple(data_paths) if data_paths is not None else tuple(sorted(provided_paths & schema_paths))
-    if not selected_paths:
-        raise TestMqlOutputValidationError("no test_mql schema Data_Path values are available.")
-    unknown_selected = [data_path for data_path in selected_paths if data_path not in schema_paths]
-    if unknown_selected:
-        raise TestMqlOutputValidationError(
-            f"Requested Data_Path values are outside test_mql schema: {unknown_selected}"
-        )
-    missing_selected = [data_path for data_path in selected_paths if data_path not in series_by_data_path]
-    if missing_selected:
-        raise TestMqlOutputValidationError(
-            f"Python output is missing selected Data_Path values: {missing_selected}"
-        )
-    return selected_paths
-
-
-def _validate_series(
-    *,
-    data_path: str,
-    values: tuple[float, ...] | list[float],
-    expected_count: int,
-) -> tuple[float, ...]:
-    if len(values) != expected_count:
-        raise TestMqlOutputValidationError(
-            f"Python series length mismatch for {data_path!r}: "
-            f"{len(values)} values for {expected_count} time samples."
-        )
-    return tuple(_finite_float(data_path, value) for value in values)
-
-
-def _finite_float(label: str, value: float) -> float:
-    try:
-        numeric_value = float(value)
-    except (TypeError, ValueError) as exc:
-        raise TestMqlOutputValidationError(f"{label!r} contains a non-numeric value: {value!r}") from exc
-    if not isfinite(numeric_value):
-        raise TestMqlOutputValidationError(f"{label!r} contains a non-finite value: {value!r}")
-    return numeric_value

app/simulation/reporting/test_mql_variables.py

@@ -1,111 +0,0 @@
-from __future__ import annotations
-
-import re
-from collections import Counter
-from dataclasses import dataclass
-
-from app.simulation.reporting.amesim_results import AmesimResults, AmesimVariable
-from app.simulation.examples.test_mql.system import COMPONENT_SPECS, CONNECTION_SPECS
-
-
-_UNIT_RE = re.compile(r"\[([^\]]+)\]\s*$")
-
-
-@dataclass(frozen=True)
-class TestMqlVariableBinding:
-    index: int
-    data_path: str
-    signal_name: str
-    owner_alias: str
-    owner_kind: str
-    submodel: str
-    label: str
-    units: str | None
-    saved: bool
-
-
-@dataclass(frozen=True)
-class TestMqlVariableCatalog:
-    variables: tuple[TestMqlVariableBinding, ...]
-
-    @property
-    def data_path_count(self) -> int:
-        return len(self.variables)
-
-    @property
-    def saved_data_path_count(self) -> int:
-        return sum(1 for variable in self.variables if variable.saved)
-
-    def by_data_path(self, data_path: str) -> TestMqlVariableBinding:
-        for variable in self.variables:
-            if variable.data_path == data_path:
-                return variable
-        raise KeyError(data_path)
-
-    def counts_by_submodel(self) -> dict[str, int]:
-        return dict(Counter(variable.submodel for variable in self.variables))
-
-    def counts_by_owner_kind(self) -> dict[str, int]:
-        return dict(Counter(variable.owner_kind for variable in self.variables))
-
-    def data_paths_for_owner(self, owner_alias: str) -> tuple[str, ...]:
-        return tuple(
-            variable.data_path
-            for variable in self.variables
-            if variable.owner_alias == owner_alias
-        )
-
-
-def build_test_mql_variable_catalog(amesim_results: AmesimResults) -> TestMqlVariableCatalog:
-    owner_map = _build_owner_map()
-    saved_indices = set(amesim_results.saved_variable_indices)
-    bindings = []
-    for variable in amesim_results.variables:
-        if variable.data_path is None:
-            continue
-        signal_name, owner_alias = split_data_path(variable.data_path)
-        owner_kind, submodel = owner_map[owner_alias]
-        bindings.append(
-            TestMqlVariableBinding(
-                index=variable.index,
-                data_path=variable.data_path,
-                signal_name=signal_name,
-                owner_alias=owner_alias,
-                owner_kind=owner_kind,
-                submodel=submodel,
-                label=variable.label,
-                units=_extract_units(variable),
-                saved=variable.index in saved_indices,
-            )
-        )
-    return TestMqlVariableCatalog(variables=tuple(bindings))
-
-
-def split_data_path(data_path: str) -> tuple[str, str]:
-    if "@" not in data_path:
-        raise ValueError(f"AMESim Data_Path does not contain an owner alias: {data_path!r}")
-    signal_name, owner_alias = data_path.rsplit("@", 1)
-    if not signal_name or not owner_alias:
-        raise ValueError(f"Invalid AMESim Data_Path: {data_path!r}")
-    return signal_name, owner_alias
-
-
-def _build_owner_map() -> dict[str, tuple[str, str]]:
-    owner_map = {
-        str(spec["alias"]): ("component", str(spec["submodel"]))
-        for spec in COMPONENT_SPECS
-    }
-    owner_map.update(
-        {
-            str(spec["alias"]): ("connection", str(spec["submodel"]))
-            for spec in CONNECTION_SPECS
-        }
-    )
-    return owner_map
-
-
-def _extract_units(variable: AmesimVariable) -> str | None:
-    match = _UNIT_RE.search(variable.label)
-    if match is None:
-        return None
-    return match.group(1)

app/simulation/reporting/testmodel_outputs.py

@@ -1,393 +0,0 @@
-from __future__ import annotations
-
-from bisect import bisect_left
-import csv
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Any
-
-
-PRIMARY_KEYS = (
-    "mytank.p",
-    "mytank.T",
-    "mycylinder.p",
-    "mycylinder.T",
-)
-
-MODELICA_COMPARISON_COLUMNS = {
-    "mytank.p": "mytank.p",
-    "mytank.T": "mytank.T",
-    "mycylinder.p": "mycylinder.p",
-    "mycylinder.T": "mycylinder.T",
-    "branch.upper_branch.p": "mypipe.p",
-    "branch.upper_branch.in": "myorifice.port_a.m_flow",
-    "branch.upper_branch.out": "mytee1.port_out2.m_flow",
-    "branch.lower_branch.p": "mypipe1.p",
-    "branch.lower_branch.in": "myorifice1.port_a.m_flow",
-    "branch.lower_branch.out": "mytee1.port_out1.m_flow",
-}
-
-COMPARISON_KEYS = tuple(MODELICA_COMPARISON_COLUMNS.keys())
-
-
-def _branch_series_values(
-    series: dict[str, list[float]],
-    branch_name: str,
-    legacy_key: str,
-) -> list[float]:
-    generic_key = f"branch.{branch_name}.{legacy_key.split('.')[-1]}"
-    if generic_key in series:
-        return series[generic_key]
-    return series[legacy_key]
-
-
-@dataclass(frozen=True)
-class TestModelArtifacts:
-    primary_csv_path: Path
-    temperature_csv_path: Path
-    temperature_svg_path: Path
-    run_report_path: Path
-    comparison_csv_path: Path | None = None
-    comparison_summary_path: Path | None = None
-
-
-def format_testmodel_run_report(
-    *,
-    network_summary: str,
-    initialization: Any,
-    raw_initial_state: tuple[float, ...],
-    consistent_initial_state: tuple[float, ...],
-    solution: Any,
-    series: dict[str, list[float]],
-    solve_diagnostics: Any,
-    artifacts: TestModelArtifacts,
-    comparison_summary: dict[str, tuple[float, float]] | None,
-) -> str:
-    lines = [
-        network_summary,
-        "",
-        f"Initialization converged: {initialization.converged}",
-        f"Initialization iterations: {initialization.iterations}",
-        f"Initialization max state delta: {initialization.max_state_delta:.6e}",
-        f"Initialization max flow delta: {initialization.max_flow_delta:.6e}",
-        f"Initialization max enthalpy delta: {initialization.max_enthalpy_delta:.6e}",
-        (
-            "Initialization downstream pressure spread: "
-            f"{initialization.downstream_pressure_spread:.6e}"
-        ),
-        "",
-        "Raw initial state vector:",
-        str(list(raw_initial_state)),
-        "",
-        "Constraint-consistent initial state vector:",
-        str(list(consistent_initial_state)),
-        "",
-        f"Solver success: {solution.success}",
-        f"Solver message: {solution.message}",
-        f"Final time: {solution.t[-1]:.2f} s",
-        f"Final tank pressure: {series['mytank.p'][-1]:.3f} Pa",
-        f"Final tank temperature: {series['mytank.T'][-1]:.3f} K",
-        f"Final cylinder pressure: {series['mycylinder.p'][-1]:.3f} Pa",
-        (
-            "Final branch inflow: "
-            f"{_branch_series_values(series, 'upper_branch', 'branch_upper.in')[-1] + _branch_series_values(series, 'lower_branch', 'branch_lower.in')[-1]:.6f} kg/s"
-        ),
-    ]
-
-    if solve_diagnostics is not None:
-        lines.extend(
-            [
-                "",
-                "Final closure solve diagnostics:",
-                (
-                    "Upper branch inlet solve: "
-                    f"converged={solve_diagnostics.upper_branch_inlet.converged}, "
-                    f"iterations={solve_diagnostics.upper_branch_inlet.iterations}, "
-                    f"residual={solve_diagnostics.upper_branch_inlet.residual:.6e}"
-                ),
-                (
-                    "Lower branch inlet solve: "
-                    f"converged={solve_diagnostics.lower_branch_inlet.converged}, "
-                    f"iterations={solve_diagnostics.lower_branch_inlet.iterations}, "
-                    f"residual={solve_diagnostics.lower_branch_inlet.residual:.6e}"
-                ),
-            ]
-        )
-        if solve_diagnostics.downstream_pressure_projection is not None:
-            lines.append(
-                "Downstream pressure projection: "
-                f"converged={solve_diagnostics.downstream_pressure_projection.converged}, "
-                f"iterations={solve_diagnostics.downstream_pressure_projection.iterations}, "
-                f"residual={solve_diagnostics.downstream_pressure_projection.residual:.6e}"
-            )
-
-    lines.extend(
-        [
-        f"Primary series CSV: {artifacts.primary_csv_path}",
-        f"Temperature CSV: {artifacts.temperature_csv_path}",
-        f"Temperature plot: {artifacts.temperature_svg_path}",
-        f"Run report TXT: {artifacts.run_report_path}",
-        ]
-    )
-
-    if (
-        artifacts.comparison_csv_path is not None
-        and artifacts.comparison_summary_path is not None
-    ):
-        lines.extend(
-            [
-                f"Modelica comparison CSV: {artifacts.comparison_csv_path}",
-                f"Modelica comparison summary: {artifacts.comparison_summary_path}",
-            ]
-        )
-        if comparison_summary is not None:
-            for key, (max_abs_error, max_rel_error) in comparison_summary.items():
-                lines.append(
-                    f"{key} max abs error: {max_abs_error:.6f}, "
-                    f"max rel error: {max_rel_error:.6%}"
-                )
-
-    return "\n".join(lines) + "\n"
-
-
-def write_testmodel_run_report(output_dir: Path, report_text: str) -> Path:
-    report_path = output_dir / "testmodel_run_report.txt"
-    report_path.write_text(report_text, encoding="utf-8")
-    return report_path
-
-
-def _write_primary_series_csv(output_dir: Path, series: dict[str, list[float]]) -> Path:
-    csv_path = output_dir / "testmodel_primary_series.csv"
-    with csv_path.open("w", newline="", encoding="utf-8") as handle:
-        writer = csv.writer(handle)
-        writer.writerow(["time_s", *PRIMARY_KEYS])
-        for index, time_value in enumerate(series["time"]):
-            writer.writerow([time_value, *(series[key][index] for key in PRIMARY_KEYS)])
-    return csv_path
-
-
-def _write_temperature_csv(output_dir: Path, time_values: list[float], temperatures: list[float]) -> Path:
-    csv_path = output_dir / "testmodel_tank_temperature.csv"
-    with csv_path.open("w", newline="", encoding="utf-8") as handle:
-        writer = csv.writer(handle)
-        writer.writerow(["time_s", "mytank_T_K"])
-        writer.writerows(zip(time_values, temperatures))
-    return csv_path
-
-
-def _write_temperature_svg(output_dir: Path, time_values: list[float], temperatures: list[float]) -> Path:
-    svg_path = output_dir / "testmodel_tank_temperature.svg"
-
-    width = 900
-    height = 520
-    left = 90
-    right = 40
-    top = 60
-    bottom = 70
-    plot_width = width - left - right
-    plot_height = height - top - bottom
-
-    min_time = min(time_values)
-    max_time = max(time_values)
-    min_temp = min(temperatures)
-    max_temp = max(temperatures)
-    temp_padding = max(1.0, (max_temp - min_temp) * 0.08)
-    min_temp -= temp_padding
-    max_temp += temp_padding
-
-    def scale_x(value: float) -> float:
-        return left + (value - min_time) / max(max_time - min_time, 1e-12) * plot_width
-
-    def scale_y(value: float) -> float:
-        return top + (max_temp - value) / max(max_temp - min_temp, 1e-12) * plot_height
-
-    points = " ".join(
-        f"{scale_x(time_value):.2f},{scale_y(temperature):.2f}"
-        for time_value, temperature in zip(time_values, temperatures)
-    )
-
-    x_ticks = 5
-    y_ticks = 5
-    x_tick_markup = []
-    y_tick_markup = []
-
-    for index in range(x_ticks + 1):
-        fraction = index / x_ticks
-        time_value = min_time + fraction * (max_time - min_time)
-        x = left + fraction * plot_width
-        x_tick_markup.append(
-            f'<line x1="{x:.2f}" y1="{top}" x2="{x:.2f}" y2="{top + plot_height}" '
-            'stroke="#d9e2ec" stroke-width="1" />'
-        )
-        x_tick_markup.append(
-            f'<text x="{x:.2f}" y="{height - 30}" text-anchor="middle" '
-            'font-size="14" fill="#102a43">'
-            f"{time_value:.1f}</text>"
-        )
-
-    for index in range(y_ticks + 1):
-        fraction = index / y_ticks
-        temp_value = min_temp + fraction * (max_temp - min_temp)
-        y = top + plot_height - fraction * plot_height
-        y_tick_markup.append(
-            f'<line x1="{left}" y1="{y:.2f}" x2="{left + plot_width}" y2="{y:.2f}" '
-            'stroke="#d9e2ec" stroke-width="1" />'
-        )
-        y_tick_markup.append(
-            f'<text x="{left - 12}" y="{y + 5:.2f}" text-anchor="end" '
-            'font-size="14" fill="#102a43">'
-            f"{temp_value:.1f}</text>"
-        )
-
-    svg_content = f"""<svg xmlns="http://www.w3.org/2000/svg" width="{width}" height="{height}" viewBox="0 0 {width} {height}">
-  <rect width="{width}" height="{height}" fill="#f7fafc" rx="18" ry="18" />
-  <text x="{width / 2:.0f}" y="32" text-anchor="middle" font-size="24" fill="#102a43">Python Testmodel Tank Temperature</text>
-  <text x="{width / 2:.0f}" y="{height - 8}" text-anchor="middle" font-size="16" fill="#486581">Time (s)</text>
-  <text x="26" y="{height / 2:.0f}" text-anchor="middle" font-size="16" fill="#486581" transform="rotate(-90 26 {height / 2:.0f})">Temperature (K)</text>
-  <rect x="{left}" y="{top}" width="{plot_width}" height="{plot_height}" fill="#ffffff" stroke="#bcccdc" stroke-width="1.5" />
-  {''.join(x_tick_markup)}
-  {''.join(y_tick_markup)}
-  <polyline fill="none" stroke="#d64545" stroke-width="3" stroke-linejoin="round" stroke-linecap="round" points="{points}" />
-</svg>
-"""
-    svg_path.write_text(svg_content, encoding="utf-8")
-    return svg_path
-
-
-def load_modelica_series(csv_path: Path, variable_names: tuple[str, ...]) -> dict[str, list[float]]:
-    series = {"time": []}
-    for variable_name in variable_names:
-        series[variable_name] = []
-
-    with csv_path.open("r", newline="", encoding="utf-8") as handle:
-        reader = csv.DictReader(handle)
-        available_variable_names = tuple(
-            variable_name
-            for variable_name in variable_names
-            if MODELICA_COMPARISON_COLUMNS.get(variable_name, variable_name) in (reader.fieldnames or ())
-        )
-        for row in reader:
-            series["time"].append(float(row["time"]))
-            for variable_name in available_variable_names:
-                modelica_column = MODELICA_COMPARISON_COLUMNS.get(variable_name, variable_name)
-                series[variable_name].append(float(row[modelica_column]))
-
-    return series
-
-
-def _interpolate_series_value(time_values: list[float], values: list[float], target_time: float) -> float:
-    if target_time <= time_values[0]:
-        return values[0]
-    if target_time >= time_values[-1]:
-        return values[-1]
-
-    right_index = bisect_left(time_values, target_time)
-    if right_index < len(time_values) and abs(time_values[right_index] - target_time) <= 1e-12:
-        return values[right_index]
-
-    left_index = right_index - 1
-    left_time = time_values[left_index]
-    right_time = time_values[right_index]
-    fraction = (target_time - left_time) / (right_time - left_time)
-    return values[left_index] + fraction * (values[right_index] - values[left_index])
-
-
-def write_modelica_comparison(
-    output_dir: Path,
-    python_series: dict[str, list[float]],
-    modelica_series: dict[str, list[float]],
-) -> tuple[Path, Path, dict[str, tuple[float, float]]]:
-    comparison_csv_path = output_dir / "testmodel_modelica_comparison.csv"
-    summary_path = output_dir / "testmodel_modelica_comparison_summary.txt"
-    summary: dict[str, tuple[float, float]] = {}
-
-    with comparison_csv_path.open("w", newline="", encoding="utf-8") as handle:
-        writer = csv.writer(handle)
-        header = ["time_s"]
-        comparison_keys = tuple(
-            key
-            for key in COMPARISON_KEYS
-            if key in python_series and key in modelica_series and modelica_series[key]
-        )
-        for key in comparison_keys:
-            header.extend(
-                [
-                    f"python.{key}",
-                    f"modelica.{key}",
-                    f"abs_error.{key}",
-                    f"rel_error.{key}",
-                ]
-            )
-        writer.writerow(header)
-
-        max_abs_errors = {key: 0.0 for key in comparison_keys}
-        max_rel_errors = {key: 0.0 for key in comparison_keys}
-
-        for index, time_value in enumerate(python_series["time"]):
-            row = [time_value]
-            for key in comparison_keys:
-                python_value = python_series[key][index]
-                modelica_value = _interpolate_series_value(
-                    modelica_series["time"],
-                    modelica_series[key],
-                    time_value,
-                )
-                abs_error = abs(python_value - modelica_value)
-                rel_error = abs_error / max(abs(modelica_value), 1e-9)
-                max_abs_errors[key] = max(max_abs_errors[key], abs_error)
-                max_rel_errors[key] = max(max_rel_errors[key], rel_error)
-                row.extend([python_value, modelica_value, abs_error, rel_error])
-            writer.writerow(row)
-
-    summary_lines = []
-    for key in comparison_keys:
-        summary[key] = (max_abs_errors[key], max_rel_errors[key])
-        summary_lines.append(
-            f"{key}: max_abs_error={max_abs_errors[key]:.6f}, "
-            f"max_rel_error={max_rel_errors[key]:.6%}"
-        )
-    summary_path.write_text("\n".join(summary_lines) + "\n", encoding="utf-8")
-    return comparison_csv_path, summary_path, summary
-
-
-def export_testmodel_artifacts(
-    *,
-    output_dir: Path,
-    series: dict[str, list[float]],
-    modelica_series: dict[str, list[float]] | None = None,
-) -> tuple[TestModelArtifacts, dict[str, tuple[float, float]] | None]:
-    output_dir.mkdir(parents=True, exist_ok=True)
-
-    primary_csv_path = _write_primary_series_csv(output_dir, series)
-    temperature_csv_path = _write_temperature_csv(
-        output_dir,
-        series["time"],
-        series["mytank.T"],
-    )
-    temperature_svg_path = _write_temperature_svg(
-        output_dir,
-        series["time"],
-        series["mytank.T"],
-    )
-
-    comparison_csv_path = None
-    comparison_summary_path = None
-    comparison_summary = None
-    if modelica_series is not None:
-        (
-            comparison_csv_path,
-            comparison_summary_path,
-            comparison_summary,
-        ) = write_modelica_comparison(output_dir, series, modelica_series)
-
-    return (
-        TestModelArtifacts(
-            primary_csv_path=primary_csv_path,
-            temperature_csv_path=temperature_csv_path,
-            temperature_svg_path=temperature_svg_path,
-            run_report_path=output_dir / "testmodel_run_report.txt",
-            comparison_csv_path=comparison_csv_path,
-            comparison_summary_path=comparison_summary_path,
-        ),
-        comparison_summary,
-    )

app/simulation/results.py

@@ -0,0 +1,56 @@
+"""Backend-neutral simulation result and preparation error contracts."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from app.simulation.native_codegen.transport import NativeSeriesJson
+from app.simulation.core.metadata import ResultVariableMetadata
+
+SimulationRunStatus = Literal["completed", "cancelled", "failed"]
+
+@dataclass(frozen=True)
+class SimulationPreparationIssue:
+    code: str
+    message: str
+
+    def as_dict(self) -> dict[str, str]:
+        return {"code": self.code, "message": self.message}
+
+
+class SimulationPreparationError(ValueError):
+    def __init__(self, issues: tuple[SimulationPreparationIssue, ...]) -> None:
+        super().__init__("The compiled model is not ready for simulation.")
+        self.issues = issues
+
+
+@dataclass(frozen=True)
+class GenericSimulationResult:
+    success: bool
+    status: SimulationRunStatus
+    message: str
+    simulated_until: float
+    requested_stop_time: float
+    variables: tuple[ResultVariableMetadata, ...]
+    series: dict[str, list[float]] | NativeSeriesJson
+    final: dict[str, float]
+    diagnostics: dict[str, object]
+
+    def as_dict(self, *, raw_series: bool = False) -> dict[str, object]:
+        from app.simulation.native_codegen.transport import NativeSeriesJson
+        series = self.series
+        if isinstance(series, NativeSeriesJson) and not raw_series:
+            series = series.materialize()
+        return {
+            "success": self.success,
+            "status": self.status,
+            "partial": self.status != "completed",
+            "message": self.message,
+            "simulatedUntil": self.simulated_until,
+            "requestedStopTime": self.requested_stop_time,
+            "variables": [variable.as_dict() for variable in self.variables],
+            "series": series,
+            "final": self.final,
+            "diagnostics": self.diagnostics,
+        }