lujingze/SystemSimulationApp
1
0 Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

现有组件功能与Amesim组件比较对齐，补全功能；仿真服务启动环境检测，旧版json工程文件适配读取

Browse Source
This commit is contained in:
ljz committed 2026-09-13 20:01:56 +08:00
1 parent b6c22a54f8
commit 6fc9afe41d
119 files changed
+260114 -351
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/other/Amesim元件语义核查与修复-2026-09-13.md
+69
View File
@@ -0,0 +1,69 @@
# Amesim 元件语义核查与修复
日期：2026-09-13；分支：`system-optimization`。本轮核查公开目录中的 22 个 Amesim 条目，重点是参数编码、选项是否实际参与计算、单位、力方向、初值和分段信号。对照本机 Amesim 2404 子模型 C 文件及其随附说明；没有复制其实现源码进入生产代码。
**同日复核补充：不能将下表理解为对应元件已全面对齐。后续发现 PNL0003 分端换热仍有计算错误，UD00 零时长及部分机械参数边界也有差异；详见 [已修复元件语义复核](Amesim已修复元件语义复核-2026-09-13.md)。本报告保留原修复记录，新增差异尚未修复。**
本轮没有修改 `native/runtime/` 中的积分器、停滞判断或事件恢复策略，也没有开展稀疏矩阵优化。公开参数名、端口名和 0/1 布尔编码不变；修复的是已有选项的实现及外部转换，故保持当前精确 `modelVersion`，避免已有 XML 被无关版本升级拒绝。
## 已修复的问题
| 元件 | 旧问题 | 修复后的行为 |
|---|---|---|
| UD00 | AME 的 `iscyclic=1` 被直接复制为本系统的 `1`，把不循环误作循环 | 外部转换明确为 **AME 1→公共 0，AME 2→公共 1**；浏览器 JSON/XML 不再次转换 |
| UD00 | 不循环时，末段斜坡在全部分段结束后仍向后延伸；未安排最后终点 | 最后终点以后保持末值；开始前保持首值；最后终点纳入分段通知。零时长分段跳过是本系统现有扩展，Amesim 拒绝有效段时长为零，不能称为语义对齐 |
| LSTP00A | 选择几何刚度后仍使用保存的 `kcont` | 使用 `G × wdiam⁴ / (8 × sdiam³ × na)`，几何参数须为正；接触力仍在 C 中计算 |
| MECMAS21 | `theta` 未参与计算 | 按度转换倾角，计入 `mass × 9.80665 × sin(theta)`；正负 90° 的加速度方向分别验证 |
| MECMAS21 | 弹性限位使用线性阻尼增长，与 LSTP00A 不同 | 二者共用指数接触公式；穿透量等于 Pdis/Pdmin/Pdmax 时达到约 63.2% 阻尼，并保留允许/禁止负接触力的选项 |
| MECMAS21 | 恢复碰撞模式仍计入隐藏的库仑摩擦 | 按原子模型，恢复碰撞只保留启用时的黏性摩擦、风阻；干摩擦不参与 |
| PNL0001/2/3 | `mode=1` 只是关闭环境换热，`k` 未生效 | 实现多方过程；`k=1` 等温，其他 k 按质量变化计算温度与压力；带换热模式保留质量/能量方程 |
| PNCH012 + PNRP17 | 初始储气量只按死容积/固定容积计算，随后加入活塞容积时初始 p/T 被改变 | 按活塞及相连质量块初始位置计算完整容积，再初始化储气量；紧凑和扩展 C 生成路径均已修复 |
多方模式对照 `pn2vol1` 说明：固定容积中 `dm/dt=Σ流量`、`dT/dt=(k−1)T/m × dm/dt`，且 `p=mRT/V`。实现使用质量/温度作为内部状态；U 作为结果由状态导出。和 Amesim 的这一简化模式一致，储气质量采用理想气体关系，流阻所用密度及端口焓仍来自所选介质；不能把这种模式解释成完整的真实气体能量守恒模型。直接相连的管路储气单元须采用相同热力学模式和多方指数。
### 尚未实现的能力改为明确拒绝
静摩擦保持、脱离和高级干摩擦/Stribeck 尚未实现，本轮不加入需要进一步讨论的摩擦切换机制。现在执行编译会拒绝这些激活的配置，不再忽略参数后给出看似正常的结果；关闭摩擦、恢复碰撞中的隐藏干摩擦参数仍按其不生效的语义处理，工程仍可编辑和保存。
同时补齐 MECMAS21 的活动参数约束：非恢复碰撞且启用摩擦时 `fcoul ≤ fstick`，`dvel/astrib > 0`；恢复碰撞要求 `restdvel > 0`。因此现阶段可完整执行黏性摩擦、风阻及无干摩擦的模式，不能宣称完整支持所有摩擦选项。
冻结 Python 基准有三组 `fcoul=2、fstick=0` 的活动干摩擦输入，Amesim 本身也拒绝这种组合。历史文件保持原样，回归改为确认两个 C 入口明确拒绝；恢复碰撞那组则用独立牛顿方程验证去掉干摩擦后的加速度。
## 其余条目的核查边界
| 条目 | 本轮核查结论 |
|---|---|
| 理想空气介质、氦气介质 | 是限定介质/物性方法的公开条目；`property_model=0` 是各自的公共编码，不是 PNGD00 所有气体/EOS 选项的原始编号 |
| STEP0、F000 | 已检查阶跃前后值与时刻、零力输出，未发现新的编码问题 |
| FORC | 公开 `direction=±1` 与原模型几何方向转换已有明确处理；图标旋转不代替方向参数 |
| LMECHN1 | `sum=1`、活动端口数量、公共力平衡规则已检查；公开最多 20 个支路端口是范围限制 |
| PNPL01 | 封闭口零流量语义已检查 |
| PNCH023 | 固定容积、初始绝对 p/T、换热系数与面积的组合已检查 |
| PNOR001、PNVO001、固定开度 PNVO001 | `flowset=1/2/3` 含义相同；Cv/Kv 采用各自单位定义换算；有效开度限制在 0–1。固定开度条目是明确的公开变体 |
| PNL00R | 阻性管段没有储气状态；管径、长度、相对粗糙度和反向流符号沿用既有已验证实现 |
| PN3NODE2、P4NODE2 | 参考量传递与支路汇总遵循公共供需合同，没有把原始有向变量符号直接视为公共端口符号 |
结合前表，覆盖全部 22 个公开条目。这里的“未发现新问题”限于本轮检查的编码、参数选择和接口约定，**不是逐点证明所有物性、所有工况都与 Amesim 相同**。公共端口统一采用连接守恒符号；例如本系统 Fvisc 是带方向的力贡献，而原模型展示量采用阻力约定，曲线比对仍需显式映射。PNCH012 的固定外部容积参数、固定开度阀也属于公开扩展，不应冒充原模型全部接口的一比一复制。
## 当前模型文件
四路、八路 corrected JSON 各仅修改两个 `iscyclic`，仿真时长仍为 10 秒，未修改 AME。网页里的已有存档不自动改写，请重新导入修正文件；不能把所有历史 JSON 中的 `1` 批量改为 `0`，其他工程可能确实需要循环。
| 文件 | 修复前 SHA-256 | 修复后 SHA-256 |
|---|---|---|
| `tests/data/test-mql-4-corrected.json` | `542494eed8e235cb36eae5f80a0776b812e547d9215fa370949b0882834ebc8b` | `c8ed9efa83d111e58aa9e20e158448a7a5f45d4bd1e2a6360dd929e34919b9eb` |
| `tests/data/test-mql-8-corrected.json` | `670977bef67e62d9c66e8af497bada208bd72a7301be45128d185d47282cf288` | `60ed16c71b72be4ae71ca7980f4f8cdcdf6b4c4c4c8950863c2390960b71ced4` |
默认八路 AME 仍为 `tests/data/test_mql.ame`，本次 SHA-256 为 `319b27ac1b8ceb7e960cc05592efbfc19664e70479fe9bf36000b823c3c928f8`。它保存 50 秒、0.05 秒输出间隔、rtol=1e-7；JSON 保存 10 秒、0.01 秒输出间隔，后台 rtol=1e-8。参数审计与时间配置差异分别报告，不再把时间配置不一致冒称为元件参数错误，也不把 AME 算法枚举等同于 CVODE BDF。
## 验证结果
- 两份 AME 图纸独立审计通过：八路 157 个元件、1092 个参数、178 条连接；四路 81 个元件、582 个参数、90 条连接。当前参数与精确端口连接均无待修正项。
- 八路只将修正 JSON 的时长延长为 50 秒，原 BDF 求解器完整结束：**纯求解 10.746 秒**，9576 个接受步、669 个拒绝步、1 次状态切换；5002 个输出时刻全部有限。56 个储气质量量总和约 5.566893015 kg，最大漂移 `1.69e-14 kg`。
- 四路原 10 秒配置完整结束：**纯求解 0.888 秒**，1003 个输出时刻全部有限。
- 多方管路实际 BDF 积分 0.02 秒，验证 `T/(m/m₀)^(k−1)` 不变量，相对误差 `3.35e-8` 以下；专项也覆盖三种管路、等温/多方、直接相连的储气单元和初始状态。
- 元件、XML、原生目录及启动自检综合回归完整通过 43 项；最终元件与原生目录回归 **14 项通过**，记录在 `final-component-tests-recheck.log`。上一轮有一个独立 `--probe` 进程返回空 stdout，原失败日志保留，重跑全部通过；没有修改原生探针来忽略空输出。`final-launch-and-contract-tests.log` 中 25 项通过，包含编译进程恢复、启动自检和冻结历史合同。最后循环事件去重与进程检查另有 9 项通过。
上述耗时是本轮功能回归的观察值，不是隔离负载的性能评测。本轮没有重跑 Amesim，也没有重新宣布完整曲线一致；原积分器停滞问题仍等用户审阅后另行处理。
证据在被 Git 忽略的 `test/component-semantics-20260913/`：输入变更、工具安装说明提取、专项测试日志、四路与多方运行结果。八路原始输出在 `test/mql8-50s-20260913/semantic-fixes-production-retry/`。所有正式实现继续使用 C 数值内核；未恢复 Python 积分器。C 修改使用跨平台 C11，构建继续兼容 Windows/Linux；本次真实运行平台为 Windows，未在 Linux 服务器实跑。
docs/other/Amesim已修复元件语义复核-2026-09-13.md
+92
View File
@@ -0,0 +1,92 @@
# Amesim 已修复元件语义复核
日期：2026-09-13；分支：`system-optimization`。
本次针对上一份报告“已修复的问题”涉及的 UD00、LSTP00A、MECMAS21、PNL0001/2/3、PNCH012 和 PNRP17 复核，排除已单独说明的静摩擦保持和高级干摩擦。依据本机 Amesim 2404 子模型源文件、随附帮助及当前生产 C 程序的最小探针结果。没有修改生产元件、积分器、工程参数或运行中的后端；没有重跑完整 Amesim 模型。
**结论：不能确认这些元件已经全面对齐。原先修改的若干核心公式已对齐，但还发现了 PNL0003 换热计算错误、若干活动参数边界不一致，以及环境参数和适用范围限制。上一份报告中把零时长分段跳过也列作对齐行为，不准确。**
## 逐项结论
| 元件 | 已核对一致的部分 | 仍有差异或验证边界 |
|---|---|---|
| UD00 | 外部循环编码转换；正时长分段的线性插值、开始前首值保持、非循环结束后末值保持 | 我们接受有效段时长为 0，Amesim 初始化拒绝；未使用段时长为 0 不属于这个问题。事件内部的试算调用约定不同，不能据函数值核对就宣布积分器事件处理等价 |
| LSTP00A | 几何刚度公式；按公共端口方向转换后的间隙/相对速度；指数接触阻尼；负接触力保留或截零 | 数值模式 kcont=0 我们接受而 Amesim 拒绝；几何模式 G=0 我们拒绝而 Amesim 的子模型初始化检查允许 |
| MECMAS21，排除未实现干摩擦 | 默认重力下的倾角分量；上下弹性限位的指数阻尼和方向；恢复碰撞模式不计算干摩擦，保留启用的黏性摩擦和风阻 | 弹性限位参数边界尚未对齐；重力固定为 9.80665，未实现 Amesim 的 GRAV0 环境覆盖；碰撞事件处理机制仍不能宣称全面等价 |
| PNL0001、PNL0002 | 固定容积、mode=1 多方储气方程；mode=2 本地温度换热项及质量/能量守恒形式 | 公开 k、rr 范围比原子模型检查更窄；本次未重新验证全部介质物性、流阻曲线和极端状态 |
| PNL0003 | 两个半容积、各自的多方储气方程、中心质量/焓流守恒方向 | **mode=2 的两个换热项错误使用平均温度，尚未对齐**；同样存在 k、rr 范围限制 |
| PNCH012 + PNRP17 | 直接相连活塞的初始完整容积；在该容积下满足指定初始绝对 p/T；气腔能量中的环境换热和压力做功项；有效活塞面积、相对运动对应的容积及变化率 | 气压力计算固定采用 101300 Pa 参考大气压，没有对应 PNATP00 的覆盖；固定外部容积参数是公共扩展，当前 C 生成器按直接相邻 PNRP17 收集动态容积，不能据此声称任意供容积元件/连接均已支持；极小容积/负状态时的求解恢复策略未对齐证明 |
“方程形式一致”以采用相同介质状态关系和统一单位、端口方向为前提。不同内部状态选择可以表达同一物理方程，不能把状态变量名称不同直接当成语义错误；同样，形式一致也不能替代完整曲线验证。
## 已复现的计算问题：PNL0003 分别换热
Amesim 对两个半容积分别使用自己的温度：
```text
Q1 = kth × A/2 × (Text − T1)
Q2 = kth × A/2 × (Text − T2)
```
当前实现先计算 `(T1+T2)/2`，再用这一温度计算两个相同的换热项。对两个半容积的总换热功率，这个写法可能恰好相同；但分配到每个半容积的能量不同，后续温度、压力及流量会受到影响。
最小算例使用理想气体，两端封闭、初始压力均为 200000 Pa，避免中心流量干扰；管径 0.02 m、管长 1 m、kth=10 W/(m²·K)，T1=400 K、T2=200 K、Text=300 K。
| 量 | 按 Amesim 方程独立计算 | 当前生产 EXE 探针 |
|---|---:|---:|
| 中心质量流量 | 0 kg/s | 0 kg/s |
| 半容积 1 的 dU/dt | −31.4159265359 W | 0 W |
| 半容积 2 的 dU/dt | +31.4159265359 W | 0 W |
这是实际方程差异，不是积分容差、求解速度或输出采样造成的。这里的 Amesim 预期值来自已核对的方程，不冒称本次运行了 Amesim EXE。
定位：本系统 `app/simulation/native_codegen/extended.py:577`；Amesim `F:/AMESim2404/Amesim/libpn/submodels/PNL0003.c:377` 和 `:382`。
建议后续使用当前半容积自己的温度，并补充两端温度不同、环境温度位于两者之间的回归。仅验证初始温度相同或 kth=0，无法发现该问题。
## 已复现的参数边界差异
以下本系统结果经过实际构建网络和执行编译校验确认。Amesim 一栏依据子模型初始化检查；不是逐个启动 Amesim 后得到的结果。
| 配置 | 本系统 | Amesim 初始化检查 |
|---|---|---|
| UD00 的有效段 t1=0、nstages=2 | 接受，跳过该段 | 拒绝，要求每个有效段终点严格晚于起点 |
| LSTP00A 数值模式 kcont=0 | 接受 | 拒绝，要求 >0 |
| LSTP00A 几何模式 G=0 | 拒绝 | 只拒绝 G<0 |
| MECMAS21 弹性限位 Kbmin=0 | 接受 | 拒绝，要求上下限位刚度均 >0 |
| MECMAS21 弹性限位 Dbmin=0 | 接受 | 拒绝，要求上下限位阻尼均 >0 |
| MECMAS21 弹性限位 xmin=1、xmax=−1 | 接受 | 拒绝，要求 xmin≤xmax |
| PNL 多方模式 k=2.5 | 拒绝，公开上限为 2 | 子模型只要求 k>0 |
| PNL 相对粗糙度 rr=0.2 | 拒绝，公开上限为 0.1 | 子模型只要求 rr≥0 |
前六项属于元件活动参数边界的差异；后两项属于已公开的支持范围限制，不表示共同支持范围内的方程一定错误。未启用参数的检查也需要单独规定，不应为对齐有效段限制而禁止 UD00 未使用段保存默认 0。
源码证据：UD00.c:318；LSTP00A.c:136、:152；MECMAS21.c:225、:234；PNL0001.c:159、:165，PNL0002/3 有对应检查。本系统位置：`signals/sources.py:12`、`semantics.py:43`、`mechanical/translational.py:61`、`flow/pipes.py:59`。
建议后续统一执行时的活动参数检查：既拒绝 Amesim 拒绝的组合，也避免错误拒绝原模型允许的活动参数；编辑、保存与求解校验仍应按现有协议各自承担责任。
## 两个默认环境条件
MECMAS21 的 Amesim 原模型从 `getgravity_()` 取重力；其随附帮助说明可由 GRAV0 改变，默认值为 9.80665 m/s²。目前本系统使用的就是这个默认值。因此倾角公式已经补上，但尚未支持自定义重力。
PNRP17 在 Amesim 中接收表压，本系统使用绝对压力后固定减去 101300 Pa。`pn2getatp` 随附帮助确认这是 Amesim 默认大气压，同时 PNATP00 可以改变该值。本系统尚未支持这种环境覆盖。不能把默认环境下对齐推广为任意环境配置下都对齐。
## 对当前四路、八路测试文件的影响
再次读取 `tests/data/test-mql-4-corrected.json` 和 `tests/data/test-mql-8-corrected.json`：
- UD00 的有效段时长均为 0.8 s、10 s，不存在有效零时长段。
- PNL0003 均使用 mode=2，但 kth=0，因此新发现的分端换热错误不会在这两份当前配置中生效。
- LSTP00A 使用数值刚度且 kcont>0；MECMAS21 使用理想限位或无限位，theta=0，不触发上述弹性限位参数问题。
- 当前目录中没有实现 GRAV0、PNATP00；默认对标模型的已审计元件清单也不包含它们。
这些判断只排除本次新发现的触发条件，**不表示完整曲线已经验证一致，也不否认尚待审阅的积分停滞问题。** PNCH012 在当前模型中有非零环境换热，该气腔项使用自身温度，不能把它与 PNL0003 的平均温度错误混为一谈。
## 本次验证与证据
- 原有 `tests.test_amesim_semantics` 共 10 项全部通过，耗时 31.444 s。说明原修复的专项检查仍通过；旧测试没有覆盖这次的非对称换热与若干参数边界。
- 新的独立审计探针确认上述 PNL0003 差异及 8 组参数边界行为。
- 证据脚本和输出：`test/component-semantics-20260913/followup_semantic_audit.py`、`followup-semantic-audit.json`、`followup-regression.log`。test 目录依仓库约定不纳入 Git。
- 真实运行平台为 Windows，未在 Linux 服务器运行；本次没有生产代码修复。
下一步应优先修复 PNL0003 分端换热，然后对齐活动参数校验；自定义重力、大气压和通用容积传递是需明确范围的能力补齐。完成相应元件级验证后，再对当前四路、八路做完整 Amesim 曲线对比。
docs/other/Amesim摩擦与管路功能补齐验证-2026-09-13.md
+143
View File
@@ -0,0 +1,143 @@
# Amesim 摩擦与管路功能补齐验证
日期：2026-09-13。分支：`system-optimization`。参照本机 Simcenter Amesim 2404。
## 结论与范围
已补齐 MECMAS21 静摩擦保持、高级干摩擦和 Stribeck 过渡，修正其弹性限位参数检查；调整 LSTP00A 的零刚度/零剪切模量边界、PNL0001/2 的多方指数范围，并修正 PNL0003 两段各自的换热温度。
本次新建并实际运行了 **13 个 Amesim 算例**，每个运行 3 秒；对应平台 C 程序均运行到 3 秒。另外用平台的 **JSON→XML→正式后端仿真函数**完整运行两个联合小系统，确认参数解析、连接编译、结果生成与组件单独执行一致。本次没有在浏览器界面点击运行，后端入口为 `app.main.run_system_xml_simulation`。
常规采样网格上的连续状态和力/热力学曲线吻合。简单摩擦恰好脱离时有一个左右取值不同的采样点，详见下文，不能将结果表述成逐点完全相等。
重力保持 9.80665 m/s²，大气压保持 101300 Pa。根据用户要求，本轮不增加环境重力、大气压的可调组件。没有修改 CVODE 积分公式、稠密分解/条件着色算法，也没有处理此前另行审阅的积分时间停滞问题。
## 已完成的功能
| 元件 | 本次行为 |
|---|---|
| MECMAS21 简单摩擦 | 静止时干摩擦抵消外力；超过静摩擦阈值进入滑动；滑动时使用库仑摩擦；减速停住后重新检查保持或反向启动。 |
| MECMAS21 高级摩擦 | 增加 ±dvel 低速保持区间；支持 Stribeck 过渡、黏性摩擦和风阻共同作用。Amesim 2404 在高级模式采用约 0.1% 的脱离滞环，5 N、7 N 两组实际运行分别验证了 5.005 N、7.007 N 附近脱离。 |
| MECMAS21 理想限位与摩擦 | 限位挡住质量时，由限位承担外力，干摩擦输出为零；反向外力足以脱离后恢复运动。碰撞后的摩擦状态随接受的事件一起更新。 |
| MECMAS21 弹性限位 | 活动模式要求 Kbmin、Kbmax、Dbmin、Dbmax 全部大于零，Pdmin/Pdmax 允许零，xmin≤xmax。参数检查在执行编译阶段进行。 |
| MECMAS21 恢复碰撞 | 延续 Amesim 该模式只计算黏性摩擦和风阻、忽略干摩擦的行为。原有两种积分方法的碰撞回归通过。 |
| LSTP00A | 数值模式 kcont 必须大于零；几何模式允许 G=0，sdiam、wdiam、na 必须大于零。G=0 时弹簧力为零，接触阻尼仍然有效。 |
| PNL0001/2 | k 必须大于零，取消原先的 k≤2 限制；实际以 k=2.5 验证。PNL0003 共用的 k 元数据同步采用相同边界。 |
| PNL0003 | 两半管分别使用自身温度计算对外换热，而不是共同使用两段平均温度。 |
高级摩擦滑动分支的阻力幅值为：
`Fcoul + (Fstick − Fcoul) × exp(−3 × |v| / astrib)`。
PNL0003 两段换热功率分别为：
`Q1 = kth × π × diam × le / 2 × (Text − T1)`，
`Q2 = kth × π × diam × le / 2 × (Text − T2)`。
以两段 400 K、200 K，外界 300 K，管径 0.02 m、管长 1 m、kth=10 为例，独立理想气体封闭初态的换热功率为 −31.4159265359 W 和 +31.4159265359 W。旧的平均温度写法会错误地把两段都算成零。
## 数值实现与状态保存
每个有干摩擦的刚性运动组增加一个内部状态 `_friction_mode`，取保持、正向滑动、反向滑动三个值。在连续积分期间其导数为零，只在接受的脱离/停止/反向/限位事件处修改并重新初始化积分历史。
每次计算先按现有机械连接求出不含干摩擦的驱动力，再计算干摩擦并代入同一组线性力平衡。这是两次已有的线性表达式求值，未引入压力、流量、焓的额外非线性迭代。低速事件检查会增加方程求值次数，本轮验收目标是功能与结果一致性，没有据此作性能收益承诺。
保持状态随采样状态一起保存，函数不会根据试算或绘制历史曲线改变全局摩擦标志。回归额外验证了乱序查询同一状态的输出一致。模型编译的依赖登记增加了新函数和内部状态；雅可比算法本身保持现状。
多质量刚性同速组中的静摩擦反力按各质量静摩擦容量分配。多个静摩擦约束同时保持时，单个元件反力可能存在不唯一性；本次 Amesim 联合验证中的两个质量通过弹性接触连接，并非两个质量直接刚性串联。不能把本次结果扩展成任意欠定静摩擦反力分配都已与 Amesim 逐元件验证。
## 对照条件与单位
- 所有实际 Amesim 算例：3 s，变步长隐式设置，误差限 1e-9，最大积分步长 0.002 s，输出间隔 0.001 s。
- 独立平台 C 程序：BDF，rtol=1e-9，最大积分步长 0.002 s，输出间隔 0.001 s。另有简单摩擦和大低速区间算例的 RK45 回归。
- 联合系统后端：保持平台默认误差设置，JSON 中选择 BDF、3 s、0.002 s 最大步长和 0.001 s 输出间隔。
- 气动介质：显式使用气体索引 1 的氦气 Peng–Robinson 设置；平台 JSON 已指定匹配的介质索引。导出时不得把默认介质索引 0 与显式氦气索引 1 混用。
- 表中误差：将平台输出插值到 Amesim 的 0.001 s 常规采样时刻，计算整个 0–3 s 区间最大绝对差。平台另存事件点，Amesim 固定间隔数据未必包含这些瞬时时刻。
- Amesim 管路压力变量本次使用 Pa 表压，比较时加 101300 Pa 转为绝压；不是再乘 1e5。MECMAS21 限位刚度的 N/mm、阻尼的 N/(mm/s)、穿透量的 mm，分别换算到平台 SI 单位。
- 机械联合系统的 Amesim v1/x1 与平台全局坐标相反；比较时反号，且交换上下限位力。LSTP00A 的 gap 从 mm 转为 m。单质量驱动算例则通过 FORC 方向设置使用相同 v1/x1 方向。
## 单元件实际运行结果
下列 11 个单元件算例全部完整运行 3 s；源 `.ame`、对应 JSON/XML、双方 CSV 已收入交付包。
| 算例 | 主要最大绝对差 |
|---|---|
| 简单摩擦 | 速度 3.79e-9 m/s；位移 5.47e-9 m；脱离单点例外见下文。 |
| 高级摩擦、无 Stribeck | 速度 3.79e-9 m/s；位移 8.68e-9 m。 |
| 高级 Stribeck | 速度 5.31e-8 m/s；位移 3.34e-8 m；干摩擦 3.01e-6 N。 |
| 高级摩擦叠加弹性限位 | 速度 6.89e-8 m/s；位移 2.42e-9 m；加速度 1.82e-5 m/s²。 |
| 高级摩擦叠加理想限位 | 速度 1.72e-8 m/s；位移 2.96e-9 m；干摩擦 4.85e-7 N。 |
| 扩大低速区间、非零初速、风阻 | dvel=0.005 m/s、初速 0.001 m/s；速度差 8.74e-9 m/s，位移差 2.10e-9 m；验证初始低速保持与后续停止。 |
| LSTP00A 几何刚度 | 接触力 6.70e-8 N，间隙 8.87e-10 m。 |
| LSTP00A 零剪切模量 | 接触力 2.89e-8 N；阻尼仍有非零力，间隙差 8.39e-10 m。 |
| PNL0001，k=2.5 | 管内压力 0.0205 Pa，温度 1.85e-5 K。 |
| PNL0002，k=2.5 | 管内压力 0.142 Pa，温度 1.28e-4 K；相连储气腔最大压力差 0.216 Pa。 |
| PNL0003，非对称温度换热 | 两半最大压力差 0.000169 Pa，最大温度差 8.42e-7 K。 |
管路对照并非按位相等；本次全区间最大压力差不足 0.22 Pa，相对于约 200000 Pa 的压力约为百万分之一。温度与多方关系、换热方向一致。现有管阻根求解实现及积分器误差控制不同仍可带来这种小量差异，本轮未继续修改其求解算法。
### 简单摩擦的单个切换采样点
外力在 t=0.15 s 达到 5 N。Amesim 的常规输出点保存切换前的静止分支，平台该事件点保存切换后的滑动分支，因此该点干摩擦差 2 N，加速度差 2 m/s²。
原始数据和 `comparison.json` 均保留这个最大差。单独注明并排除恰好该时刻后，干摩擦最大差 4.46e-10 N，加速度最大差 8.24e-10 m/s²；整个区间的速度、位移仍分别只有 3.79e-9 m/s、5.47e-9 m 的差异。回归同时保留 0.149 s 和 0.151 s 的前后分支检查，而不把瞬时跳变强行平滑成相同数据。
## 两个联合小系统
### 机械系统
连接：分段力信号 → FORC → 左质量（高级 Stribeck＋弹性限位）→ LSTP00A → 右质量（简单干摩擦＋弹性限位）→ 零力源。
三秒内发生启动、接触、脱离、换向、限位压缩和再次静止。独立 C 程序记录 12 次离散状态切换。
平台正式后端相对 Amesim 的最大差：
| 输出 | 最大绝对差 |
|---|---:|
| 左质量位移 | 3.26e-8 m |
| 右质量位移 | 3.75e-8 m |
| 左质量速度 | 1.09e-6 m/s |
| 右质量速度 | 6.03e-7 m/s |
| 接触力 | 8.20e-5 N |
| 左质量干摩擦 | 8.20e-5 N |
![机械联合系统](../../test/component-semantics-20260913/delivery/joint_mechanical.png)
### 气动系统
连接：封闭储气腔 → PNL0001（k=2.5）→ PNL0002（k=2.5）→ PNL0003（两半初始 320/280 K，与 300 K 环境换热）→ 封闭端。
平台正式后端相对 Amesim，四个管内压力输出最大差 **0.133 Pa**；管内温度输出最大差 **1.12e-4 K**。两个系统的后端均完整返回 3 s 结果。
![气动联合系统](../../test/component-semantics-20260913/delivery/joint_pneumatic.png)
## 回归与限制记录
- 元件语义测试：11 项通过，覆盖活动参数、零剪切模量、多方指数 2.5、两段独立换热等。
- Amesim 实测冻结数据回归：1 项测试内含 8 个算例、10 次积分运行，全部通过；覆盖 BDF 和 RK45、静止/启动/反向/限位和联合系统。
- 原生目录与机械 XML 回归：16 项通过，包含原有恢复碰撞和代数模型两种积分方法。
- 结构依赖回归：6 项通过。旧目录有 3 个 fcoul>fstick 的非法历史输入，已改为验证明确拒绝，未修改冻结输入。
- 以上相关测试合计 **34 项通过**。扩展运行的旧 `NativeJacobianProbeTests` 仍在预检失败：`native-jacobian-cache-state.json` 绑定的八路输入摘要与当前 corrected JSON 不符。该固定状态夹具、模型输入及其摘要均未在本轮改写；需要后续在求解器审阅中重新建立一致基准。不能将完整雅可比测试套件标记为全绿。
- `NativeJacobianRuntimeTests` 的独立私有 ABI 检查依赖 Linux SUNDIALS 静态库，本机 Windows 按其既有规则跳过。
- Windows 上实际通过原生 C 编译、链接、运行及 Amesim 对照。生产代码只使用 C11、现有构建器和跨平台状态/事件接口，无新增 Windows 专用工具链路径。本轮没有 Linux 实机结果。
- Amesim API 用于新建模型、生成代码及参数文件；本机 JobManager 无可用运行资源时，关闭 API 后独立启动其生成的本机可执行文件，均正常完成。原始运行日志和 `.results` 保留在 `test/component-semantics-20260913/feature-reference/*-run/`。
## 文件与复现
交付包：[amesim-component-validation-20260913.zip](../../test/component-semantics-20260913/amesim-component-validation-20260913.zip)。含 13 个新算例的 JSON/XML/AME、单位和坐标已统一的双方 CSV、两份后端 CSV、对照统计和曲线图。`.ame` 保存模型与设置，本次仿真测量值另存于 CSV。
平台可直接导入：
- [机械小系统 JSON](../../test/component-semantics-20260913/delivery/joint_mechanical.json)
- [气动小系统 JSON](../../test/component-semantics-20260913/delivery/joint_pneumatic.json)
运行中的后端需要重新启动以加载 Python 编译器及元件参数定义的修改；新生成的 C 模型通过已有构建指纹使用更新后的内核。
无需 Amesim 安装即可运行已冻结的实测回归：
```text
python -m unittest tests.test_amesim_semantics tests.test_native_friction tests.test_native_catalog tests.test_amesim_mechanical_xml tests.test_native_jacobian_structure.StructuralDependencyTests -v
```
本机 Amesim 构建脚本和对照脚本保留在 `test/component-semantics-20260913/`；实测冻结数据在 `tests/fixtures/amesim-component-semantics-2404.json`，带原始 Amesim 结果 SHA-256。交付内容不包含 Siemens 元件库实现源码。
docs/other/GCC偶发子进程启动失败定位与恢复-2026-09-13.md
+45
View File
@@ -0,0 +1,45 @@
# GCC 偶发子进程启动失败：定位与恢复
日期：2026-09-13；分支：`system-optimization`。用户要求在元件语义修复过程中继续定位并处理偶发 GCC 错误。
## 已定位的事实
本机 GCC 8.1 本体能运行，但在启动 `cc1.exe` 的过程中偶发失败。详细 `-v` 记录已经打印了实际存在的绝对路径；添加编译器目录到 PATH 后，192 次串行/并发对照中的一组仍有一次失败，因此不能把 PATH 补全或并发关闭当成已证明的根因修复。
对本轮自行启动的 GCC 诊断进程设置临时 Windows 调试断点，捕获到一次同类失败：
```text
CreateProcessA return = 0
GetLastError = 5 (ERROR_ACCESS_DENIED)
application = F:\Projects\mingw64\bin\..\libexec\gcc\x86_64-w64-mingw32\8.1.0\cc1.exe
gcc exit = 1
```
该样本是“拒绝访问”，不是“找不到 GCC 本体”。GCC 的 Windows 实现会把多种创建进程错误映射成 ENOENT，使终端只显示 `CreateProcess: No such file or directory`；这一信息损失也见 [GCC 官方讨论](https://gcc.gnu.org/pipermail/gcc-help/2025-May/144184.html)。
只读核查发现：cc1.exe 存在，普通用户有读取/执行权限，没有 Zone.Identifier 下载标记，未查到相关 Defender/Code Integrity 拦截事件。诊断进程不在作业对象中。**这些证据尚不能锁定 Windows 内部为何临时拒绝此次创建进程，也不能证明所有同类文本都对应错误 5。没有修改 ACL、安全配置、已安装 GCC 或系统 PATH。**
同时捕获到独立异常：`gcc --version` 有时退出码为 0，但 stdout 为空；旧代码直接取首行，产生 `IndexError`，进一步把工具链问题变成了不明确的后端异常。
## 后台修复
1. 保持 `SIMULATION_NATIVE_CC`/PATH 和 `SUNDIALS_ROOT` 的原查找规则，不写入任何本机绝对路径。Windows 将选中的编译器目录放入该子进程自己的 PATH；不修改后端全局环境。Linux 保留所配置命令及环境，包括依赖 argv[0] 的编译器包装器/符号链接。
2. 正式构建与启动自检统一使用有效的空标准输入、受控的标准输出/错误管道、关闭无关句柄继承；Windows 隐藏编译器窗口。
3. 正式构建只对已识别的 GCC 子进程启动错误、特定 Windows 临时进程错误，以及空编译器身份输出进行恢复。最多重试 5 次，间隔 0.05、0.1、0.2、0.35、0.5 秒。成功立即返回；失败日志保留，每次重试可追踪。
4. C 语法错误、未定义符号等链接错误、缺失编译器和超时不走上述重试。版本/目标查询必须有有效输出，空版本不会再触发 IndexError。
5. 启动自检的整轮重试仍由既有后台状态机管理：首次检测加最多 5 轮，编辑器可用，最终失败才展示详细错误。自检预处理/编译/链接命令不再额外叠加一层整轮重试；编译器身份查询可使用命令级恢复。
6. 正式构建记录 `compilerLaunchRetries`（构建命令的次数，独立的版本查询恢复在服务器日志中记录）；最终编译失败保留命令、退出码、stdout/stderr、尝试次数等详情。启动自检明确描述为“GCC 已启动，但无法启动编译子进程”，避免再让用户误以为只需重配 gcc 路径。
这修复了应用把一次可恢复启动失败直接判为仿真失败的行为；**没有声称消除了 Windows 层所有拒绝访问的根源**。若六次启动仍失败，仍会如实报错，不更换编译器、不绕过系统安全限制。
## 验证
- 修复后 **128 次、并发度 4 的真实预处理调用全部完成**。期间再次捕捉到 1 次相同 CreateProcess 失败，自动重试一次成功，无需手动重启后端。
- **连续 10 次完整启动自检全部通过**，每次均执行预处理、编译、SUNDIALS 链接和最小 BDF 程序运行，未使用模型缓存。
- 进程专项测试覆盖瞬时错误恢复、重试上限、日志保留、真实语法/链接错误不重试、空版本、超时/缺失文件、环境隔离、Linux 分支，以及最终身份查询失败的完整自检详情；最后检查见 `final-process-detail-tests.log`。
- 元件与启动自检综合 43 项回归通过；最终编译进程/启动自检/历史合同组合 25 项通过；最终元件/目录检查 14 项通过。后续四路真实构建过程中再出现两次启动抖动，也都自动恢复并完成仿真。独立数值探针曾有一次空输出导致测试失败，保留记录并完整重跑通过；没有据此扩大为任意仿真进程的自动重跑。
- Linux 适配由跨平台分支测试覆盖；本次未登录 Linux 服务器做实机验证。
证据目录：`test/component-semantics-20260913/`。原始对照为 `gcc-probe.json`；原始 Windows 错误码为 `gcc-debug4.log`；恢复压力测试为 `launch-verification.json`；专项为 `compiler-process-tests.log`、`final-launch-and-contract-tests.log`。调试程序仅留在被忽略的 test 目录，不加入生产程序，也未修改磁盘上的编译器。
修改后需要后端进程加载新代码。已有运行进程不会因磁盘文件变更自动得到新逻辑（除非本身启用了 reload）。
docs/other/八路50秒仿真在10.8秒终止的原因核查-2026-09-13.md
+101
View File
@@ -0,0 +1,101 @@
# 八路 50 秒仿真在 10.8 秒终止的原因核查
2026-09-13，Windows，本地 `system-optimization` 工作区。此次定位问题，在 `test/mql8-50s-20260913/` 创建独立输入、源码和日志副本，没有修改正式求解器、原始 JSON、AME 或运行中的后端。
**结论：已复现 10.8 秒终止，由两层问题叠加造成。AME 转换/审计遗漏 UD00 循环开关的枚举转换，使本应单次输出的两个信号周期重复；信号重启后，CVODE 成功完成一个小于当前时间浮点分辨率的步，外层封装因返回时间相同立即判失败。** 这不是此次运行超时，也没有观察到 CVODE 返回雅可比或线性分解错误。
## 1. 输入身份与参数核对
用户确认后续八路验证默认使用下列仓库文件，本次网页仅修改终止时间：
| 输入 | 本次 SHA-256 |
|---|---|
| `tests/data/test-mql-8-corrected.json` | `670977bef67e62d9c66e8af497bada208bd72a7301be45128d185d47282cf288` |
| `tests/data/test_mql.ame` | `319b27ac1b8ceb7e960cc05592efbfc19664e70479fe9bf36000b823c3c928f8` |
AME 已由用户更新，不能继续使用历史 `1ff0ea42…` 的 10 秒归档身份。本次归档 `.results` 有 1002 个时间点，覆盖 0～50 秒，所有具名保存值有限；本轮读取此归档，没有重新运行 Amesim。
以现有审计工具核对：157 个元件、178 条连接逐端口匹配，1092 项公开参数在原工具的数值/单位规则下全部相等；1015 项直接绑定参数也核对图纸与 `.param/.data`。但下文两个枚举的语义不相等，因此“数字全部相同”不能作为参数语义一致的结论。其余参数本轮未发现数值差异，不将此等同于全部元件实现已逐项验收。
| 设置 | 本次原生复现 | 当前 AME |
|---|---:|---:|
| 终止时间 | 50 s，副本仅由原 JSON 的 10 s 延长 | 50 s |
| 输出间隔 | 0.01 s | 0.05 s |
| 最大积分步长 | 1e30 s | 1e30 s |
| 相对误差限 | 后端默认 1e-8 | 1e-7 |
| 积分算法 | CVODE/BDF 7.4.0 | 保留归档设置，不把内部枚举直接等同于 BDF |
原 JSON 仍保存 10 s、输出间隔 0.01 s，所以原审计工具最后的时间设置断言按预期失败。其物理参数与连接审计记录已经写出，不能把该断言当作仿真故障。
## 2. 两个 UD00 的循环开关被错误对齐
当前应用公共协议由 `app/simulation/components/amesim/signals/sources.py` 定义为 `0=否、1=是`。本机 Amesim 2404 的 `libsig/submodels/UD00.c` 明确只有 `iscyclic == 2` 才执行循环分支，其余合法值 1 执行单次分支。
因此正确的外部转换应为 **AME 1 → 公共协议 0，AME 2 → 公共协议 1**。不能直接修改现有 C 内核中布尔值 1 的含义，否则会破坏用户合法创建的循环信号。
AME 图纸与 `.param/.data` 中两个开关均为 1；当前 JSON 也保存 1。`tests/test_test_mql_ame_contract.py::_expected_parameters` 按单位转换后直接比较数字，没有处理这一枚举映射；八路审计工具复用该方法，因而漏报。此前仅运行 10 秒，尚未越过这个差异首次产生影响的时刻。
两个信号有效阶段均为 0.8 秒 + 10 秒，总长度为 10.8 秒：
| 信号 | 0～0.8 s | 0.8～10.8 s | AME 在 10.8 s 后 | 原 JSON 在 10.8 s |
|---|---:|---:|---:|---:|
| `amesim_ud00_1` | 1e17 | 49000 | 保持 49000 | 跳回 1e17 |
| `amesim_ud00_2` | 1e12 | 0 | 保持 0 | 跳回 1e12 |
该差异既由源代码和参数表证实，也由 AME 保存的 `output@piecewiselinear`、`output@piecewiselinear_1` 曲线与原生失败结果最后一点直接证实。AME 在 10.8 s 邻近、11 s 和 50 s 均保持末段值。
## 3. 求解器封装过早终止
原生结果：`success=false`、`simulatedUntil=10.8`、`Native integration failed to advance.`，接受步 8848、拒绝步 669、雅可比计算 682 次、无着色回退。执行限额为 300 秒，而此次纯求解仅约 9.888 秒，排除超时。
在隔离 C 副本中仅增加日志，数值结果与原版的终点和求解计数相同。10.8 秒信号重启后，CVODE 返回：
```text
flag = 0 (CV_SUCCESS)
t = next = internal = 10.800000000000001
last step = actual initial step = 2.092542956622022e-16 s
next proposed step = 1.072750168401015e-14 s
internal accepted steps = 1
```
10.8 附近两个相邻双精度时间数的间隔约为 `1.7763568394002505e-15 s`，大于这一步。因此状态更新后返回的时间数字仍相同。`native/runtime/cvode_solver.c` 中的 `if (flag<0 || next<=t) goto cleanup;` 把“负返回码”和“成功但时间暂未改变”合并为同一种立即退出条件。CVODE 的 0 确实代表成功，见 [官方返回码说明](https://sundials.readthedocs.io/en/latest/cvode/Constants_link.html)。
诊断副本在 `CV_SUCCESS && next == t` 时允许有限次继续，不人工增加时间、不改变误差限，不执行零长度采样/碰撞处理。该诊断保留了原来的循环输入，仍完整到达 50 秒：总计出现 12 次这样的返回，最长连续 6 次，均恢复前进。这证明本次外层立即退出条件过早，不代表可以无限忽略不前进或接受任意不连续输入的精度。
## 4. 两个独立对照
所有对照使用相同物理参数、BDF、rtol=1e-8、最大步长 1e30 s、输出间隔 0.01 s。下列都是单次诊断观察，不作为性能优化统计。
| 对照 | 改动 | 结果 | C 求解墙钟 |
|---|---|---|---:|
| 原模型 + 正式内核 | 仅延长到 50 s | 停在 10.8 s | 9.888 s |
| 语义对齐模型 + 正式内核 | 两个 UD00 的 iscyclic 改为 0 | 完成 50 s | 9.851 s |
| 原循环模型 + 诊断内核 | 对成功但时间未变提供有限次继续 | 完成 50 s | 11.805 s |
第二项没有修改求解器，返回 5002 个严格递增采样点，全部数据有限；56 个气体质量状态的总质量最大漂移为 `1.2434497875801753e-14 kg`。两个信号的末段值与 AME 相符。此项证明对齐信号语义即可让当前模型完整运行，不宣称已通过双方全部 50 秒曲线的等精度验收。
第三项仍具有与 AME 不同的周期激励，产生 9 次机械状态转换，不能作为 AME 对照模型或直接交付为正式修复。诊断的连续 8 次保护上限只用于验证假设，正式实现需明确停滞处理规则和诊断。
## 5. 建议修复范围
1. 修正 AME→公共协议枚举映射及审计，按语义对齐这两个模型参数；保持公共协议 0/1 不变。补上“单次保持末值”和“循环跨周期”的转换与长时间测试，不能用双方都写 1 的测试继续自证正确。
2. 区分 CVODE 失败返回、时间倒退、成功但暂时无可表示时间增量。对最后一种提供有上限且可取消的继续机制，记录内部步数、实际步长和停滞次数；仍无法推进时明确报错，避免笼统提示。不得强行用 nextafter 推动系统时间以跳过积分。
3. 正式验收包括该八路 50 秒模型、真正的周期信号、单次斜坡结束后的保持行为、事件/采样完整性与失败诊断，并在 Windows 和 Linux 上分别验证。稀疏求解优化安排在这些正确性问题之后。
本轮未修改生产代码或原始工程，仅提供已经完成 50 秒运行的诊断 JSON：`test/mql8-50s-20260913/model-50s-semantic-aligned.json`。它与原 JSON 仅有终止时间及两个循环开关的差异。
## 6. 证据与复现
证据目录 `test/mql8-50s-20260913/`：
- `sources/identity.json`、输入快照：来源身份；检查结束时原始文件 SHA 未改变。
- `parameter-audit/audit.json`、`parameter-audit.log`：逐参数、逐端口映射与时间设置差异。
- `archive-summary.json`：AME 保存结果时间范围及有限性。
- `production-retry/`：正式内核复现；`traced-boundary/`：仅增加日志的同故障验证。
- `semantic-aligned/`：对齐开关后的完整结果，`validation.json` 包含采样、有限性与质量守恒检查。
- `stationary-probe/`：停滞继续的诊断源码、实际构建信息和完整结果；`cause-evidence.json` 汇总信号差异及 CVODE 返回信息。
- `diagnose.py`：复用正式输入、代码生成、构建与执行入口。重新运行需使用新的 `--name`，避免覆盖原始证据。`--trace --allow-stationary` 只修改 test 下的源码副本。
Windows 使用 `.venv-win/Scripts/python.exe -B test/mql8-50s-20260913/diagnose.py run --name 新目录名`。语义对齐组加 `--input model-50s-semantic-aligned.json`。本轮没有 Linux 实机结果。
最初一次诊断编译在受限进程环境中遇到 GCC CreateProcess 错误，尚未开始求解；保留 `production-default/input.xml`。随后正常 Windows 进程环境构建成功并稳定复现 10.8 秒中断，两者属于不同阶段的问题，不能混为同一根因。
docs/standard/README.md
+7 -3
View File
@@ -1,6 +1,6 @@
# 现行规范索引
索引版本：1.1.1；整理/复核日期：2026-09-12。
索引版本：1.1.2；整理/复核日期：2026-09-13。
新增组件从[注册流程](component-registration-workflow-v1.md)开始，再按涉及的能力读取专项规范。[注册示例](component-registration-example-v1.md)包含实际失败阶段、修订对照和复现方法。本目录保存现行版本，修订时更新正文版本、日期及变更说明；历史实现报告仍在 `docs/other/`，不覆盖其历史结论。
@@ -21,7 +21,7 @@
| 文件 | 文档版本 / 核对日期 | 本轮调整 |
| --- | --- | --- |
| [System XML v3](system-xml-v3.md) | 1.1.0 / 2026-09-12 | 求解方法、示例可执行边界、参数输入及连接检查层次 |
| [System XML v3](system-xml-v3.md) | 1.1.1 / 2026-09-13 | 纠正求解方法的 XSD 描述；说明示例可执行边界、参数输入及连接检查层次 |
| [优化基准模型](optimization-benchmark-model.md) | 1.1.0 / 2026-09-12 | 计时口径、当前/历史输入隔离、按需 XML 与可执行测试入口 |
以上版本仅表示文档，XML Schema 和用户指定的八路基准未改变。
@@ -42,7 +42,7 @@
| 核对项 | 确认的代码行为及本轮修订 | 主要代码依据 |
| --- | --- | --- |
| XML 积分方法 | XSD 列六种，语义层只接受 RK45/BDF；其余返回 SIMULATION_METHOD_UNSUPPORTED | [XML 校验](../../app/system_xml.py)、[XSD](../../schemas/system-simulation-v3.xsd)、[原生 runner](../../app/simulation/native_codegen/runner.py) |
| XML 积分方法 | XSD 仅要求 `method` 为非空字符串，不枚举方法；语义层和执行层只支持 RK45/BDF，其他值在语义层返回 SIMULATION_METHOD_UNSUPPORTED（2026-09-13 纠正原表述） | [XML 校验](../../app/system_xml.py)、[XSD](../../schemas/system-simulation-v3.xsd)、[原生 runner](../../app/simulation/native_codegen/runner.py) |
| XML 示例和编译 API | 文档示例是结构有效但机械无惯性锚点的系统；compile-model 只构造网络，C 生成仍可能失败 | [HTTP/网络入口](../../app/main.py)、[扩展生成](../../app/simulation/native_codegen/extended.py) |
| 存储与执行 | 版本不同在输入层警告后使用当前模型；类型/端口/参数仍严查，XML 精确版本不变 | [请求与存储](../../app/main.py)、[前端解析](../../frontend/src/App.tsx) |
| 参数表达式与单位 | 已统一：外部 v2 数值与表达式按所选单位，v1 保持旧 SI 数字；预处理后才进入数值内核 | [网页表达式](../../frontend/src/parameterExpression.ts)、[CLI 输入](../../app/simulation/native_codegen/input.py)、[HTTP 转换](../../app/main.py) |
@@ -57,3 +57,7 @@
## 输入合同实现 / 2026-09-12
旧组件版本警告、工程 JSON v2 参数单位与表达式统一的现行规则见[接口规范 1.2.0](backend-interface-version-spec-v1.md#61-工程存储与执行入口)。测试与独立版本检查计时见[验收报告](../other/2026-09-12-project-contract-acceptance.md)。端口快照精简及其他求解优化未纳入此改动。
## 求解方法说明纠正 / 2026-09-13
System XML 规范更新至 1.1.1，同步纠正本索引中“XSD 列六种”的错误描述：当前 XSD 只要求 `method` 为非空字符串，可执行方法由语义校验及原生执行入口限制为 RK45/BDF。本次仅修正文档并静态核对代码，未修改协议或业务实现，未重新运行上述历史验收测试。
docs/standard/backend-interface-version-spec-v1.md
+1 -1
View File
@@ -151,7 +151,7 @@ OpenAPI，但当前多数 JSON 响应仍以 `dict[str, object]` 构造，XML、C
**工程 JSON v2**：参数数值、十进制数字字符串、数学表达式，全部按 `parameterUnits[name]` 指定的单位解释；缺省使用目录 SI 单位。缺失参数采用目录 SI 默认值，不随显示单位二次换算。例如单位选 `bar` 时，`2.5`、`"2.5"`、`"=2.5"`、`"2+0.5"` 均得到 `250000 Pa`。温度使用仿射换算，`20 degC = 293.15 K`；压力是绝压，不添加大气压偏移。
**旧工程 JSON v1**：为保持已有模型物理输入不变，普通数值/十进制数字字符串仍按 SI，表达式按显示单位解释。不可只把版本号 1 改成 2。浏览器兼容读取后提示旧规则，手工导出时将 SI 数字转换回所选单位，写出 v2。若某参数经过显示单位往返会改变浮点末位，则该参数改用 SI 单位导出并提示，保持求解输入逐值精确不变。编辑器内存、浏览器草稿/本地保存和结果快照继续使用内部 v1/SI 数字表示，不是新的外部 JSON v2。无法转换的未知组件/参数草稿保留 v1 和原版本，发出警告供修复，不丢字段。
**旧工程 JSON v1**：为保持已有模型物理输入不变，普通数值/十进制数字字符串仍按 SI，表达式按显示单位解释。不可只把版本号 1 改成 2。旧文件和旧浏览器存档继续兼容读取并提示旧规则；后续手动保存、自动保存和 JSON 导出共用转换逻辑，将 SI 数字转换回所选单位，写出 v2。若某参数经过显示单位往返会改变浮点末位，则该参数改用 SI 单位保存，保持求解输入逐值精确不变；JSON 导出会报告此类参数数量。只有编辑器内存与结果快照继续使用内部 v1/SI 数字表示。不能转换的未知组件、参数或单位会使保存/导出明确失败：保留编辑器数据和此前的有效浏览器存档，不写出伪 v2，不自动下载旧格式文件；修复后再保存。
| 入口 | 输入处理 | 数值执行边界 |
| --- | --- | --- |
docs/standard/component-model-authoring-spec-v1.md
+2
View File
@@ -218,6 +218,8 @@ PortDefinition.pneumatic(
以明确的 Amesim 版本和**子模型编号**为依据读取端口变量表及其实现；图标相同或端口数量相同不足以证明模型等价。每个原始变量都应有映射记录：保留、换名、单位/符号变换、由其他量导出、仅保留默认值，或明确不支持。
枚举必须按含义转换，不能按数字相等判断匹配。已核查的直接选择参数集中在 `app/simulation/components/amesim/semantics.py`；例如 UD00 的 AME `1/2` 对应公共 `0/1`。转换仅应用于外部 AME 参数，禁止再次应用于已经采用公共编码的 JSON/XML。新增选择项须补映射覆盖测试；尚未实现的活动选项必须在执行编译时明确拒绝，不能静默沿用其他模式的公式。模型仍可保存，执行能力与保存能力分别说明。
既要记录普通输入/输出，也要记录状态、固定输出、别名、取反别名、可选输入及默认值。例如 PNCH012 的容积输入和 MECMAS21 的加速度端口量，不能因为当前四变量气动模板没有对应字段就不作说明。
接口方向对齐、局部公式对齐和完整仿真曲线对齐是三项不同的验证；不能用其中一项替代其他两项。实验组件及自行简化的变体，不应宣称与 Amesim 原子模型一比一相同。
docs/standard/optimization-benchmark-model.md
+3 -1
View File
@@ -8,11 +8,13 @@
优先使用 `tests/data/test-mql-8-corrected.json`，Amesim 来源严格对应 `tests/data/test_mql.ame`。先核实当次文件与物理输入，不按显示名、目录名或历史报告标题认定为同一模型。原始旧工程仅保留审计用途，不重新作为活动输入。
2026-09-13 用户再次确认上述两份文件为后续八路默认输入。UD00 曾存在“数字相同、枚举含义不同”的错误；当前四路、八路 corrected JSON 及审计均已修复。AME 的 `1=不循环/2=循环` 转为公共模型的 `0=不循环/1=循环`，不能直接复制数字。历史冻结输入保留旧编码，不能用于证明当前语义正确。详见 [元件语义核查与修复](../other/Amesim元件语义核查与修复-2026-09-13.md)。
只有八路模型确实跑不通，而且短期内没有可行修复时，才退回 `tests/data/test-mql-4-corrected.json` 与 `tests/data/test_mql_4.ame`。报告必须记录八路失败的实际终点、诊断、已排查内容及退回原因；四路结果不能代替八路验收。
## 当前入口与历史基准隔离（2026-09-12 补充）
- 当前八路核对：`.venv/bin/python tools/audit_test_mql8_model.py --check`。读取 corrected JSON 与当前 AME，证据写入 `test/model-audit/mql8/`，不修改工程。
- 当前八路核对：`.venv/bin/python tools/audit_test_mql8_model.py --check`。读取 corrected JSON 与当前 AME，证据写入 `test/model-audit/mql8/`，不修改工程。模型参数与连接为强制检查；时间配置差异单独报告，需强制相同时增加 `--require-same-time-settings`。二者都不将 AME 积分器枚举等同于 CVODE BDF。
- 当前四路核对：`.venv/bin/python tests/model_audit/audit_mql4_model.py --check`。XML 从四路 JSON 在内存中生成，再独立对照 AME 的参数与精确端口连接，不依赖已删除的 XML 夹具。
- 当前八路运行：`.venv/bin/python -m unittest tests.test_current_mql8_simulation -v`。完整使用工程所存区间和配置，验证原生执行、事件、采样完整性与数值有限。该项代替已删除的高刚度 XML 测试，不宣称覆盖原 RK45 专项或证明与 Amesim 曲线一致。
- 2026 年 8 月冻结输入在 `tests/baselines/simulation/test_mql_8/sources/`，对应 `tests/data/AmesimModels/test_mql.ame`。其字节数、SHA 和数值配置仍按 manifest 校验；历史记录中的旧路径不作为活动入口。普通前端大型画布测试使用当前 corrected JSON，历史 Python 活动遥测回放保持显式启用。
docs/standard/system-xml-v3.md
+10 -4
View File
@@ -1,6 +1,6 @@
# System XML v3 协议
文档版本：1.1.0；核对日期：2026-09-12；代码基线：`22579e5`。此版本标注文档修订，不改变 XML Schema 3。
文档版本：1.1.1；核对日期：2026-09-13；代码基线：`b6c22a5`。此版本标注文档修订，不改变 XML Schema 3。
System XML v3 是 SystemSimulationApp 当前唯一的 XML 求解输入格式。它只描述可执行模型，不再承担 ReactFlow 画布存档职责。
@@ -107,7 +107,9 @@ System
| `maxStep` | 自适应积分器单个内部步的上限 | 必须大于 0 |
| `method` | 积分方法 | 当前语义校验及 C 执行仅接受 `RK45`、`BDF` |
XSD 的枚举仍包含 `RK23/DOP853/Radau/LSODA`，但它们会被 `app/system_xml.py::SUPPORTED_SOLVER_METHODS` 在语义层以 `SIMULATION_METHOD_UNSUPPORTED` 拒绝。不能将 XSD 的结构允许集合当成运行能力。XML 当前没有 `rtol/atol/firstStep` 属性；网页和 XML API 由 `backends.simulation_config()` 设置 `rtol=1e-8`，绝对误差采用生成的逐状态尺度，见[求值与精度规范](native-evaluation-schedule.md)。
XSD 将 `method` 定义为必填的 `NonEmptyString`，只检查它是否为非空字符串，没有枚举可用求解方法。`app/system_xml.py::SUPPORTED_SOLVER_METHODS` 在语义层仅接受 `RK45`、`BDF`；其他值（例如 `RK23`、`DOP853`、`Radau`、`LSODA` 或任意未知名称）即使通过 XSD 检查，也会以 `SIMULATION_METHOD_UNSUPPORTED` 拒绝。原生 runner、Python CLI 和 C 程序同样仅支持 `RK45`、`BDF`。因此，通过 XSD 校验不代表该方法可执行。
XML 当前没有 `rtol/atol/firstStep` 属性；网页和 XML API 由 `backends.simulation_config()` 设置 `rtol=1e-8`，绝对误差采用生成的逐状态尺度，见[求值与精度规范](native-evaluation-schedule.md)。
`sampleStep` 和 `maxStep` 不是一回事：
@@ -261,8 +263,8 @@ XML 不能通过写一个新端口名来扩展组件，也不能通过修改字
| 层级 | 负责内容 |
| --- | --- |
| XML | 5 MiB 大小限制、语法、安全解析、禁止 DTD/实体和网络访问 |
| XSD | 元素顺序、必填属性、数量、基础数值类型、`schemaVersion=3`、`unitSystem=SI` |
| semantic | 模型及版本、完整参数、端点引用、注册端口兼容性、介质引用和拓扑占用 |
| XSD | 元素顺序、必填属性、数量、基础数值类型、非空字符串（含 `method`）、`schemaVersion=3`、`unitSystem=SI` |
| semantic | 支持的求解方法、仿真设置合法性、模型及版本、完整参数、端点引用、注册端口兼容性、介质引用和拓扑占用 |
当前相关接口都直接接收 `Content-Type: application/xml` 的原始 v3 XML：
@@ -294,3 +296,7 @@ XML 不能通过写一个新端口名来扩展组件，也不能通过修改字
- 前端 XML 生成：`frontend/src/App.tsx` 中的 `buildSystemXml()`
- 组件和端口事实来源：`app/simulation/registry.py`、`app/simulation/core/ports.py`
- 网络最终兼容检查：`app/simulation/systems/network.py`
## 12. 修订记录
- 2026-09-13 / 1.1.1：纠正“XSD 枚举六种求解方法”的错误描述，明确 XSD 的非空字符串检查与语义层、执行层的 RK45/BDF 支持范围。仅修正文档，未修改 XSD、校验器或求解实现。
docs/update-log/更新日志-2026-09-13.md
+87
View File
@@ -0,0 +1,87 @@
# 更新日志 — 2026-09-13
## 摩擦与管路功能补齐及 Amesim 实测验证
- 补齐 MECMAS21 静摩擦保持、高级低速保持和 Stribeck 过渡，协调理想限位与摩擦的优先关系；弹性限位执行检查要求刚度与阻尼为正。
- LSTP00A 数值刚度要求大于零，几何模式允许剪切模量为零；PNL0001/2 取消多方指数的 2.0 上限；PNL0003 两半使用各自温度计算换热。
- 新建 13 个 Amesim/平台对照算例，均完成 3 秒；机械与三管路两个联合系统另经平台 JSON→XML→后端入口验证。34 项相关自动测试通过；旧八路固定状态雅可比夹具仍有输入摘要不匹配，已单列记录。
- 本轮保留默认重力和大气压，未增加可调环境组件。未调整雅可比算法及此前单列的积分停滞处理。详情、曲线和可导入模型见 [功能验证报告](../other/Amesim摩擦与管路功能补齐验证-2026-09-13.md)。
下方“静摩擦尚未实现”的记录描述本日较早版本，现由本节功能补齐取代。
## Amesim 元件语义与 GCC 启动恢复
- 修复 UD00 外部循环枚举转换、非循环末值保持及终点通知；当前四路、八路 corrected JSON 各改两个循环参数，保存时长仍为 10 秒。
- 补全 LSTP00A 几何刚度、MECMAS21 倾角重力/指数限位阻尼/恢复碰撞中的摩擦选择，PNL0001/2/3 多方模式，以及 PNCH012 相连活塞容积的初始化。
- 静摩擦保持/高级干摩擦尚未实现的配置改为执行时明确拒绝，补齐活动参数约束；冻结历史输入不改写。
- GCC 同类错误捕获到 Windows 原始错误 5，被驱动统一显示为“找不到文件”。正式构建增加仅针对启动故障的短间隔恢复、空版本检查与诊断保留；Windows 子进程环境独立设置，Linux 编译器配置及环境继续保留。未修改安全设置，也未宣称消除 Windows 内部拒绝访问的根源。
- 八路原求解器完成 50 秒，纯求解约 10.75 秒；四路完成 10 秒，约 0.89 秒。128 次并发预处理全部完成，其中一次瞬时失败自动恢复；连续 10 次完整启动自检通过。
详见 [元件语义报告](../other/Amesim元件语义核查与修复-2026-09-13.md) 与 [GCC 定位及恢复报告](../other/GCC偶发子进程启动失败定位与恢复-2026-09-13.md)。本部分未修改积分器和停滞处理，等待用户审阅后继续。
## 后端异步自检与仿真控制台提示
后端启动后，编辑器/API 正常提供服务，后台每个应用生命周期启动一组最小原生程序的实际预处理、编译、链接、运行检查，失败后的重试规则见下文。测试程序求解一状态方程 `dy/dt=-y`，核对 `t=0.1` 的已知解及成功标记，覆盖正式 BDF 使用的 SUNDIALS 库。它不读取用户模型，也不命中或清理模型编译缓存。
新增 `GET /api/simulation/runtime-check`，返回检测标识、当前阶段、耗时、工具链信息及失败详情。仿真控制台显示阶段变化及最终结果；最终失败时显示阶段、命令、工作目录、退出码、错误类型和 stdout/stderr 尾部。后台不可达时自动重试；页面重新获得焦点时查询一次，可识别后端重启。同一状态不重复刷日志，消息不覆盖仿真进度。
保持 `SIMULATION_NATIVE_CC`/PATH、`SUNDIALS_ROOT` 和默认查找规则；未加入 Windows 专用 GCC 绝对路径或修改启动脚本。自检和正式构建共用平台选项、库选择及链接顺序。Windows 复制相同 DLL 并隐藏检查进程窗口；Linux 使用静态库及链接分组。自检临时目录放在应用数据目录所在文件系统，避免 Linux `/tmp` noexec 造成误报。正常结束、失败、取消后清理临时文件；超时/取消终止自检进程树。既有 `SIMULATIONAPP_WARMUP=off` 继续有效。
新增 Linux CI 作业，调用现有 `bat/setup-native-linux.sh` 后执行自检和原生缓存平台回归；Windows 原有完整回归会包含更新后的自检测试。未来系统相关改动应同时核查 Windows/Linux 分支，并分别记录实际运行的平台。
## 验证
- Windows 后端 20 项通过：自检 11 项、原生后端约束 2 项、跨平台缓存集成 1 项、结果传输 6 项。自检涵盖异步服务可用性、失败后编辑器可用性、重启恢复、禁用配置、缺失命令、非零退出码、超时和取消，以及 Windows/Linux 编译链接选项。
- 自检取消/超时终止子进程的补充修改后，11 项自检专项再次通过，用时 2.535 秒。
- Microsoft Edge 中 3 项界面用例通过：检测期间可编辑且消息去重；失败详情与重启恢复；后端初始不可用时重试恢复。前端 TypeScript 检查和生产构建通过。
- 已重启本机正式 8000 后端，实际观察到预处理、编译、链接、运行和完成阶段。检测期间组件目录接口均返回 HTTP 200；该次完整自检耗时 **1.3434 秒**。证据：`test/runtime-check-20260913/live-startup.json`。
- 未连接用户 Linux 服务器，也未取得本轮 Linux 实机运行结果；Linux 参数/库分支测试通过，新增 CI 作业尚未执行，不能据此声称已在服务器验收。
- 额外运行的既有 `native-result.spec.ts` 前两项在工程名断言处失败（期望 `demo-system`，实际导入文件名为 `native-result`），未进入仿真结果断言，不计入上述通过项。本次未修改该旧用例，结果传输另由 6 项真实原生/API 回归验证。
本次完成的是启动自检和故障定位能力，不自动修改系统环境，不将“检查通过”解释为所有模型都能运行，也未宣称历史偶发 GCC 故障已经得到唯一归因。
## 补充：启动自检自动重试与提示修正
针对首次启动偶发 `gcc.exe: error: CreateProcess: No such file or directory`、随后仿真又能运行的现象，增加有上限的自动重试。首次检测失败后最多再重试 5 轮（总计最多 6 次），每次间隔 0.5 秒；成功立即结束。等待使用可取消的后台事件，不阻塞编辑器或 API，关闭后端会中止等待及后续重试。保留原有 Windows/Linux 工具链探测与配置方式。
中间失败仅提示“未通过，正在重试”及轮次，控制台和后端均暂不输出详细异常；全部失败后才展示最后一次报错，后端记录各轮失败证据。API 仅在终态提供 `attemptHistory`，保存各轮阶段、耗时及失败详情；总耗时包含重试间隔，并增加开始/完成时间。提示改为“本次启动自检”，避免把历史检查结果理解为实时仿真状态。
自检 GET 只读取状态，不会重新编译。前端在检测结束后停止定时查询，切回页面仍会查询一次；后端不可达期间保留重连查询。
补充验证：
- Windows 后端自检专项 **13 项通过**（3.835 秒），覆盖首次成功、不同重试轮次成功、全部失败后停止、重试期间不泄漏报错详情及关闭时取消等待。
- Microsoft Edge 界面专项 **6 项通过**（26.2 秒），覆盖重试恢复、最终失败详情、编辑器可用性，以及终态后推进 31 秒仍无定时请求、切回页面只读取一次。
- 前端 TypeScript 检查及生产构建通过；构建仅提示既有主包体积超过 500 kB。
- 按实际 0.5 秒配置注入一次失败，随后调用真实 GCC 完成预处理、编译、链接和运行：第 2 次检测通过，总耗时 **1.863 秒**，等待 **0.501 秒**，未输出 ERROR 日志。
- 注入连续失败：第 6 次失败后结束，总耗时 **2.553 秒**，轮间间隔 **0.505–0.515 秒**，只输出一次最终 ERROR。上述注入验证证明重试行为，不代表复现或确定了历史 GCC 故障的根因。证据：`test/runtime-check-retry-20260913/verification.json`。
- 此次未重启用户正在使用的正式后端窗口；重试逻辑在后端下次启动时生效。Linux 分支沿用已覆盖的适配路径，本轮没有 Linux 实机运行结果。
## 工程存档规则统一、草稿恢复与初始视口优化
- 浏览器手动保存、自动保存与 JSON 导出共用 v2 编码：数值、数字字符串和表达式按所选单位解释。编辑器内存、求解输入和结果快照继续使用原有 SI 规则。旧 v1 存档仍可兼容读取，重新保存后升级，不再反复提示旧规则。
- 复用原有精确浮点往返保护；无法精确往返的参数改用 SI 单位保存。无法转换的未知组件、参数或单位会明确报错，保留当前编辑内容和此前有效存档，不再自动下载旧格式却提示导出成功。
- 启动时橙色恢复提示在无交互 5 秒后，用约 180 ms 淡出并移除；悬停或键盘聚焦时暂停计时。粘贴、连接提示出现时立即让位，操作结束后不重新弹出。淡出不会删除草稿。
- 顶部只保留“恢复草稿”操作，有待恢复草稿时可点，无草稿时置灰；点击直接恢复，不再弹出提示框。移除顶部保存状态文字与相关显示状态、样式。
- 待恢复草稿使用独立存储副本，不再暂停当前模型的自动保存。下次启动优先选择最近自动保存的非空工程，防止反复恢复更早的副本；保存副本失败则保留原数据并暂停自动保存。此机制是恢复检查点，不是多版本历史库。
- 自动保存仍在改动停稳 600 ms 后执行，不是每 30 秒才保存。仿真控制台每 30 秒汇总一次期间成功的非空工程自动保存，空闲不重复刷屏；失败及时报告，相同失败不反复刷屏。
- 工程名输入框从 150 px 加长到 240 px，保留窄屏适配。
- 导入 JSON、加载浏览器工程和恢复草稿共用初始适配流程。旧实现先绘制新节点、等待测量并延迟两帧才更新视口，因此会短暂显示旧比例。现在测量期间保留布局但隐藏图形，零动画适配完成后才显示；第一次可见的工程已处于适配窗口状态。普通拖入、滚轮缩放和页面往返仍保持原行为。
本次未修改求解器、后台仿真或启动自检功能。开发中保留工作区原有未提交改动。
验证结果：
- 最终版在 Windows / Microsoft Edge 下运行 **35 项回归全部通过**（1.9 分钟）：存档与提示 11 项、首次可见视口逐帧测试 3 项、建模及结果视口 11 项、压力单位 6 项、输入合同 4 项。
- 连续三轮保存/加载及 JSON 导出比较，确认 bar 数值、表达式和摄氏温度保持含义，XML 仍得到 250000 Pa 与 293.15 K；新版加载及恢复不出现旧规则提示。未知参数保存失败时旧存档不被覆盖。
- 虚拟时钟验证 5 秒淡出、悬停/焦点暂停、直接恢复、粘贴提示优先，以及 30 秒日志汇总、空闲无重复、未处理旧草稿仍自动保存、刷新后恢复最新模型。
- 逐帧验证三种加载入口，包含相同节点 ID 的工程替换：所有可见帧都已适配，首帧与后续帧视口变换一致。大型工程缩放、端口与连线对齐、结果页与建模页往返回归通过。
- 前端两份 TypeScript 配置检查与生产构建通过；仍有既有主包超过 500 kB 的警告。测试采用组件目录/结果夹具，部分启动自检请求因本地 8000 后端未运行返回连接失败，不影响上述前端回归；本轮未进行真实求解性能测试。
- 中间验证曾受开发热更新及重叠测试启动影响，最终在停止源码改动后完整重跑通过。临时本机测试启动配置已移除。
## PNCH012 参数显示与 Amesim 对齐
- PNCH012 参数表不再显示 `vol1`～`vol4`（端口外部容积）和 `dvol1`～`dvol4`（端口容积变化率）。按仓库所附 Amesim 子模型定义，这八项属于端口输入，而非用户设置参数。
- 保留气体类型、死容积、换热系数、换热面积、外部温度和初始压力/温度等常规设置；显示规则仅针对 PNCH012，不影响其他元件。
- 本次仅修改前端显示，不更改端口连接计算、求解方程、参数默认值或工程数据格式。新元件的八项兼容字段仍默认 0，旧工程的非零值及表达式继续保留并参与原有计算，不因隐藏而清零。
- 验证：Windows / Edge 下参数表与 PNCH012 共 22 项用例，首轮 21 项通过；另 1 项仍预期前轮修改前的保存版本，更新为当前合同后，连同 PNCH012 两项专项复测 3 项全部通过。确认常规参数可见、八项端口输入不可见、默认值为 0，旧非零值及表达式在浏览器保存/加载、JSON 导出与 XML 生成中保持含义。前端类型检查与生产构建通过，仅有既有主包体积警告；未运行真实求解器测试，未修改后端。