# C 内核组件库覆盖记录

> 本文记录迁移当时的阶段结果；Python 参考实现已于 2026-09-10 退役，当前入口与保留范围见 [退役记录](Python数值实现退役记录.md)。

> 后续更新：本文下述高级摩擦、静摩擦、几何接触等限制已有后续实现，见 [2026-09-13 功能补齐与 Amesim 验证](Amesim摩擦与管路功能补齐验证-2026-09-13.md)；分块存储后的完整曲线复核见 [2026-09-15 验收项复核](分块存储未完成验收项复核-2026-09-15.md)。不要将本文历史限制作为当前组件能力判断。

日期：2026-09-10。范围是当前注册表中的全部模型：Amesim 库 22 类，实验库 5 类。这里的“覆盖”指项目现有模型方程有对应的 C 实现，不代表复刻完整 Siemens 元件库，也不代表任意拓扑、任意刚性模型均能快速求解。

## 实施步骤

1. 核对注册表、模型版本、全部活动端口、状态与结果变量，建立显式 C 合同白名单。
2. 补充空气物性、阀模式、管路、节点、换热、摩擦与反弹限位的 C 公式。
3. 扩展系统 C 生成：压力分组、串联阻力闭合、焓传播、常系数力/流量约束消元、刚性质量合并、兼容管路容腔状态投影。
4. 对照 Python 的状态导数和全部结果变量，执行 RK45/BDF 事件回归及实际 JSON 测试。

四步已经落实到代码。完整运行中的超时限制单独记录，不作为通过项。

## 组件清单

| 类别 | 已覆盖模型 | 主要补充 |
| --- | --- | --- |
| 介质，2 类 | Ideal Air Medium、Helium Medium | 编译期选择空气理想气体或氦气 Peng–Robinson C 物性；包括能量反解、密度、等熵因子和黏度。 |
| 气动边界，1 类 | PNPL01 | 零流量、连接侧焓传播。 |
| 信号，2 类 | STEP0、UD00 | 跳变、分段斜坡、循环与事件分段；纯信号模型也可运行。 |
| 机械，6 类 | F000、FORC、MECMAS21、LSTP00A、LMECHN1、PNRP17 | 力/速度/位移约束、可变端口节点、刚性质量合并、活塞容积与压力力。 |
| 气腔，2 类 | PNCH023、PNCH012 | 固定/可变容积、质量与内能守恒、换热与边界功。 |
| 阀，3 类 | PNOR001、PNVO001 Fixed、PNVO001 Signal | 面积/Cv/Kv 模式、限幅开度、正反向流动、近等压平滑及诊断。 |
| 管路，4 类 | PNL00R、PNL0001、PNL0002、PNL0003 | 无储能/单容腔/双容腔、摩阻与层流过渡、换热、流动诊断、兼容容腔合并。 |
| 气动节点，2 类 | PN3NODE2、P4NODE2 | 等压与质量守恒，端口 2 温度参考、平滑能量分配。 |
| 实验组件，5 类 | Cylinder、Tank、ResistivePipe、Orifice、Tee | 储能、Darcy 阻力、孔口和混合节点。 |

模型版本逐项固定于 `app/simulation/native_codegen/contracts.py`。回归检查注册表与此表完全一致；新增模型、未移植的版本和自定义子类会明确拒绝，不会因继承了一个 Python 类就被视为已移植。

## 参数模式与物理范围

- MECMAS21：`stoptype=1/2/3/4`，塑性、柔性、反弹及无限位；黏性摩擦、库仑摩擦和风阻使用现有方程。反弹使用 `restcoeff`/`restdvel`，刚性组冲击按活动端挡的最小反弹系数处理，塑性端挡优先。
- LSTP00A：接受 `stiffmode=1/2` 和两种 `discContactOption`。当前 Python 的接触力始终使用 `kcont`、`rcont`、`Pdis`，C 保持一致。几何模式参数目前未生成另一套刚度公式。
- 当前 Python 中 MECMAS21 的 `theta`、`fstick`、`strib`、`frictionType` 等参数没有对应的额外动力学分支，C 沿用其实际行为；不能把接受这些参数解释为已增加重力斜面、静摩擦锁止或完整 Stribeck 模型。
- 管路继续沿用当前 Python 的公式：PNL0003 是 Darcy 压降反解；PNL00R/0001/0002 是已有的可压缩摩擦流及过渡拟合。未更换为另一套 Amesim 库公式。

## 系统生成与运行

Python 读取/校验 XML、创建模型对象、整理连接与常量并生成 C。质量/内能初值也在预处理阶段计算。EXE 内执行物性反解、流量/焓闭合、机械力计算、状态导数、积分、事件定位和采样，不调用 Python 方程。

保留原来针对简单储能拓扑的紧凑生成路径；新增 `extended.py` 覆盖完整目录及扩展连接。两条路径都是 C。编译器不使用 Python 数值后端作为隐式备用。

兼容的 PNL0001/PNL0003 固定容腔可直接连接：初始压力/温度需一致，同组质量与内能按体积投影，导数按体积分配。独立气腔之间的无阻力直连仍按项目既有规则拒绝；无压力锚点、欠定机械约束及无法收敛的闭合也明确报错。

积分器仍为原生 RK45、CVODE BDF；没有修改 ODE 雅可比、稀疏性或线性求解策略。C 网络中的常系数连接消元属于系统组装。扩展编译器上限为 1024 状态、16384 输出；平台仍为 Windows x64。

## 验证及重要限制

回归入口：

```powershell
.venv-win/Scripts/python.exe -m unittest tests.test_native_catalog tests.test_native_codegen tests.test_simulation_warmup -v
```

27 项回归通过，包含空气/氦气、正反向流动、阀参数模式、管路换热/光滑壁、节点、串联阻力、兼容管路容腔、机械摩擦/柔性限位、接触和信号。状态导数及输出对照容限为 `rtol=2e-8, atol=2e-7`，原 skill fixture 的更严格对照仍保留。RK45/BDF 均验证了反弹解析解和纯信号运行。另补充四个质量块刚性相连的解析校验：总质量 10 kg、外力 30 N，C 得到共享加速度 3 m/s²；该测试通过。

实际 JSON、运行日志与报告存于 `test/native-catalog/`。最终构建的 `skill-test` 完成 10 s 仿真，RK45、最大步长 0.001 s、rtol=1e-7；预热后一次求解计时为 0.322429 s，进程墙钟 0.743252 s。它是功能回归期间的单次记录，不是严格性能基准。`test-mql-8` 的 132 个状态导数、1784 个输出量在初始、信号变化及保存的瞬态状态上与 Python 对照通过。

**test-mql-8 的完整 BDF 运行未通过**：`rtol=1e-7`、最大步长 0.02 s、60 s 求解超时，推进至约 0.0153307 s；记录为受控超时，不是完成 10 s 的耗时。当前 CVODE 多次重建默认数值雅可比，属于仍需处理的完整系统求解性能问题。本次保留用户要求的雅可比策略，不用降低刚度、放宽误差或更换物理方程来掩盖它。之前固定模型的 C BDF/NDF 程序与当前通用 CVODE 是不同求解实现，其既有完成时间不能直接套用到这里。

Python 参考方程暂保留以支撑这些数值对照，且模型描述、公共配置、XML/API 与旧示例仍有依赖。组件 C 覆盖完成并不等于可以整目录删除 Python。