现有组件功能与Amesim组件比较对齐，补全功能；仿真服务启动环境检测，旧版json工程文件适配读取
This commit is contained in:
ljz committed
1 parent
b6c22a54f8
commit
6fc9afe41d
119 files changed
+260114
-351
No files matched your search
@@ -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。本次仅修正文档并静态核对代码，未修改协议或业务实现，未重新运行上述历史验收测试。
|
||||
@@ -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，不自动下载旧格式文件；修复后再保存。
|
||||
|
||||
| 入口 | 输入处理 | 数值执行边界 |
|
||||
| --- | --- | --- |
|
||||
|
||||
@@ -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 原子模型一比一相同。
|
||||
|
||||
@@ -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 活动遥测回放保持显式启用。
|
||||
|
||||
@@ -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、校验器或求解实现。
|
||||
Reference in new issue
Block a user