本文详解 FMPy 高频单步仿真（如 5e-7 s 步长）中 FMU 输出 NaN 的典型成因，指出 simulate_fmu() 封装逻辑引发的隐式状态干扰问题，并提供基于底层 API 的可控单步执行方案，附可复用代码与关键注意事项。
本文详解 fmpy 高频单步仿真（如 5e-7 s 步长）中 fmu 输出 nan 的典型成因，指出 `simulate_fmu()` 封装逻辑引发的隐式状态干扰问题，并提供基于底层 api 的可控单步执行方案，附可复用代码与关键注意事项。
在基于 FMPy 集成 Simcenter 导出 FMU 的实时协同仿真场景中（例如与 Simulink 构建反馈闭环），当采用极小步长（如 5×10⁻⁷ s）进行严格单步推进式仿真时，频繁观察到 FMU 输出在第 7–10 步后迅速发散并返回 NaN 值。该现象并非 FMU 模型本身数值不稳定所致——同一 FMU 在 Simulink 原生环境中运行完全正常，而一旦通过 FMPy 封装为 MATLAB 函数并部署至 Azure 容器，问题即刻复现。根本原因在于：simulate_fmu() 是一个面向“全周期批量仿真”设计的高层封装函数，其内部自动执行初始化、事件检测、步长自适应、状态重置与终止逻辑等操作。在高频、非连续、外部驱动的单步模式下，这些默认行为（尤其是重复调用 initialize() 或隐式修改 fmi2SetTime()/fmi2SetContinuousStates()）极易破坏 FMU 内部连续状态的一致性，导致积分器失效或代数环求解崩溃，最终输出 NaN。
因此，正确路径是绕过 simulate_fmu()，直接使用 FMPy 的底层 FMU 实例 API 进行精细化控制。核心原则是：
✅ 仅执行必要动作：setReal() 输入 → doStep() 推进 → getReal() 读取输出；
✅ 严格管理仿真时间：手动维护 _current_simulation_time，避免 doStep() 参数与内部时钟冲突；
✅ 禁用所有自动生命周期干预：不调用 setupExperiment()、initialize()、terminate() 等，保持 FMU 实例长期驻留状态。
以下是一个生产就绪的单步执行函数示例（基于 custom_input.py 范式优化）：
def step_fmu(self, inputs_array_values, step_size=5e-7, interval=None):
"""
执行 FMU 单步（或指定时间间隔）仿真，返回 (time, output1, output2, ...) 元组
:param inputs_array_values: 当前输入值列表，顺序需与 self._vrs_inputs 严格一致
:param step_size: 通信步长（单位：秒），必须与 FMU 声明的最小步长兼容
:param interval: 实际推进的时间长度（默认等于 step_size），支持子步长对齐
"""
if interval is None:
interval = step_size
stop_time = self._current_simulation_time + interval
# 关键：在时间推进循环内精确控制每一步
while self._current_simulation_time < stop_time:
# 1. 设置输入变量（确保 value references 与输入值一一对应）
self._fmu.setReal(list(self._vrs_inputs.values()), inputs_array_values)
# 2. 执行单次通信步进（注意：currentCommunicationPoint 必须为当前时刻）
status = self._fmu.doStep(
currentCommunicationPoint=self._current_simulation_time,
communicationStepSize=step_size
)
if status != 0:
raise RuntimeError(f"FMI doStep failed with status {status}")
# 3. 手动更新仿真时钟（非依赖 FMU 内部时钟）
self._current_simulation_time += interval
# 4. 读取当前时刻输出
outputs = list(self._fmu.getReal(list(self._vrs_outputs.values())))
# 将当前仿真时间作为首元素返回，便于 Simulink 同步
result_row = [float(self._current_simulation_time)] + outputs
self._results.append(str(tuple(result_row))) # 可选：日志记录
return tuple(result_row)关键注意事项与最佳实践：
- ? 输入/输出变量引用（VRs）必须预先解析并缓存：在 FMU 加载后一次性调用 model_description.modelVariables 获取 valueReference，避免每次 step_fmu() 中重复查找；
- ? doStep() 的 communicationStepSize 应与 FMU 声明的 defaultStepSize 或 Simcenter 导出设置严格一致，不建议动态修改；
- ? 禁止在单步循环中调用 reset() 或 freeInstance()，FMU 实例需全程存活以维持状态连续性；
- ? Simulink 端务必使用 Unit Delay 模块打破代数环，确保 FMU 输出延迟一拍进入反馈回路——这与文中所述“1 step delay will be created in Simulink”设计完全吻合；
- ? 调试建议：启用 FMPy 日志（logging.basicConfig(level=logging.DEBUG)）并检查 fmi2DoStep 返回码，非零状态码（如 fmi2Error, fmi2Fatal）是定位底层 FMI 调用失败的直接依据。
通过该方案，用户不仅彻底消除了 NaN 问题，更获得了对仿真时序、状态流与错误处理的完全掌控力，为高精度、低延迟的跨工具链协同仿真奠定了坚实基础。
