⋮

# FMI 基础知识

# FMI

FMI（Functional Mock-up Interface）是一项与工具无关的开放接口规范，由 Modelica 协会持续维护与发展，旨在为跨工具、跨平台的模型交换与协同仿真提供统一接口规范。

FMI 规范目前已迭代至 1.0、2.0 和 3.0 三个主要版本，能够全面覆盖从基础到复杂的系统建模与仿真需求，并广泛应用于以下关键领域：

  • 多领域系统集成
  • 控制算法验证
  • 数字孪生构建
  • 硬件在环（HIL）测试
  • 协同设计平台开发

基于其跨学科特性，FMI 规范尤为适用于复杂工程系统的集成与验证，已成为汽车、航空航天、能源电力、工业自动化等行业的核心数字基座技术。

截至目前，已有 200 余种商业及开源工具支持 FMI 规范，使其成为工业界和学术界公认的系统仿真与集成的重要技术规范。

提示

# FMU

# FMU 简介

FMI 规范定义了一种基于zip压缩包的模型封装格式及其应用程序编程接口（API），用于将模型及其相关资源打包为独立可复用的单元，称为 FMU（Functional Mock-up Unit）。FMI 规范定义了两种接口类型：模型交换（Model Exchange，简称 ME）接口和协同仿真（Co-Simulation，简称 CS）接口，相应地，FMU 也分为这两种类型。

FMU 文件以.fmu为扩展名，本质上是一个遵循 FMI 规范的zip压缩包，其内部目录结构规范统一，具备高度的模块化与可移植性，可在支持 FMI 的不同仿真平台之间实现无缝集成与高效复用。

提示

有关zip格式规范的详细信息，请参见：ZIP File Format Specification (opens new window)。

仿真工具（即导入方）会通过 FMI API 创建一个或多个 FMU 实例并对其进行仿真，可与其他模型协同运行，从而实现多工具、多领域的联合仿真与系统集成。

提示

# FMU 文件结构

一个典型的符合 FMI 2.0 规范的 FMU 文件结构如下所示：

MyModel.fmu
├── modelDescription.xml		  ← 必须：模型接口与数据信息描述文件
├── model.png		  			  ← 可选：模型图标（在部分工具中用于显示）
├── binaries/					  ← 可选：包含编译好的各平台的动态链接库
│   ├── win32/
│   │   └── MyModel.dll
│   │   └── MyModel.lib
│   ├── win64/
│   │   └── MyModel.dll
│   │   └── MyModel.lib
│   ├── linux32/
│   │   └── MyModel.so
│   │   └── MyModel.a
│   ├── linux64/
│   │   └── MyModel.so
│   │   └── MyModel.a
├── sources/                      ← 可选：提供 C 语言源代码
│   └── MyModel.c / ...
├── resources/                    ← 可选：模型运行所需的其他资源（例如数据文件等）
│   └── my_table.csv
├── documentation/                ← 可选：包含 HTML、PDF 等文档
│   └── readme.html
└── extra/		  			  	  ← 可选：FMU 所需的附加数据

  • modelDescription.xml：FMU 的核心文件之一，包含所有对外暴露变量的定义，以及用于标识 FMU 功能的关键信息。

  • binaries：基于二进制的 FMU 必须在该文件夹中包含至少一种受支持平台所需的、在链接或加载时使用的二进制文件。binaries文件夹下的子文件夹命名规范如下：

FMI 2.0 FMI 3.0 平台描述
win32 x86-windows Windows on 32-bit x86
win64 x86_64-windows Windows on 64-bit x86
linux32 x86-linux Linux on 32-bit x86
linux64 x86_64-linux Linux on 64-bit x86
darwin32 x86-darwin Macintosh on 32-bit x86
darwin64 x86_64-darwin Macintosh on 64-bit x86

  • sources：基于C语言源码的 FMU 必须在该文件夹中包含模型的完整C源代码。源码形式的 FMU 主要用于支持事先未知的平台，例如 HIL（Hardware-in-the-Loop）平台或微控制器，并可能需要用户进行一定的人工干预以确保其可用性。部分导出工具还会在source文件夹中提供针对特定目标平台的makefile模板，用户可据此为其目标平台生成相应的makefile。更多详细信息，请参见模型交换。

    注意

    FMU 必须至少包含一种实现，即必须提供源代码或针对特定目标平台的二进制文件之一。也可以在同一个zip文件中同时打包源代码及面向不同目标平台的二进制文件，以满足多平台使用需求。其中，FMU 的源代码必须采用ANSI-C，即C89标准编写。

    提示

  • resources：在该文件夹中可存放以特定格式保存的附加数据，通常用于 FMU 中的查表和映射等操作。此外，还可以根据工具或模型的需要在该目录下添加更多子文件夹。

  • documentation：该文件夹用于集中管理模型的静态技术文档，包括但不限于使用说明、外部库依赖声明及许可协议等。

    提示

    导出源码形式的 FMU 时，导出工具会在documentation文件夹中提供关于如何构建可执行文件的说明。

提示

有关 FMU 文件结构的详细信息，请参见 ：

# XML 文件结构

FMU 核心功能的所有静态信息均存储于模型描述文件modelDescription.xml中，所有的 FMU 必须包含该文件。下图展示了 FMI 2.0 规范中modelDescription.xml文件的根级架构定义（图片来源：Functional Mock-up Interface Specification 2.0.4, Page 31 of 132）：

提示

警告

为确保与二进制或源代码实现的一致性，原则上不允许自行修改modelDescription.xml文件。

以下对modelDescription.xml的根级架构中的重点元素进行介绍：

  • fmiModelDescription：整个XML文件的根元素，包含版本、模型名、导出工具、导出时间等属性，示例：

    <fmiModelDescription fmiVersion="2.0" modelName="Modelica.Blocks.Examples.PID_Controller" guid="{4eb90fc0-e337-409a-a2e5-ce31e92e45a0}" generationTool="Sysplorer" generationDateAndTime="2025-07-31T11:42:17Z" variableNamingConvention="structured">
    • fmiVersion：FMI 版本信息；
    • modelName：导出 FMU 的原始模型的名称；
    • guid：全局唯一模型标识符，用于验证XML文件与 FMU 的二进制文件或源代码之间的一致性，以检测模型是否被篡改；
    • generationTool：生成 FMU 的工具名称；
    • generationDateAndTime：生成 FMU 的日期和时间；
    • variableNamingConvention：指定变量名的风格。
      • structured：采用以.作为层级分隔符的层次化命名方式，例如controller.pid.k；
      • flat：平坦化字符串的命名方式，例如controller_pid_k。

    提示

    有关fmiModelDescription元素的详细信息，请参见：

  • ModelExchange/CoSimulation：根据 FMU 类型生成的XML元素，请参见模型交换和协同仿真。

  • UnitDefinitions：单位（unit）和显示单位（display unit）的全局定义列表，这些单位将在XML元素 <ModelVariables> 中被引用。

    提示

    有关UnitDefinitions元素的详细信息，请参见：

  • DefaultExperiment：该元素为可选，用于向导入方求解器提供默认仿真参数。导入方可选择使用或忽略这些配置。当用户自行实现 FMU 调用程序时，应特别留意该元素的设置。该元素的配置示例如下：

    <DefaultExperiment startTime="0" stopTime="4" tolerance="0.0001" stepSize="0.002"/>

    • startTime：仿真的默认起始时间。在 Sysplorer 导出的 FMU 中，该值取自原模型仿真设置中的起始时间。

    • stopTime：仿真的默认终止时间。在 Sysplorer 导出的 FMU 中，该值取自原模型仿真设置中的终止时间。

    • tolerance：积分算法的默认相对容差。在 Sysplorer 导出的 FMU 中，该值为 FMU 导出面板中用户设定的精度参数，请参见积分算法。

    • stepSize：默认积分步长。在 Sysplorer 导出的 FMU 中，该值为 FMU 导出面板中用户设定的初始积分步长（用于变步长算法）或固定积分步长（用于定步长算法），请参见积分算法。

    提示

    stepSize属性的作用：

    • 对于 Model Exchange 类型的 FMU，通常情况下stepSize作用不大，可忽略；也可以将其作为导入方在使用定步长求解器时的默认积分步长；
    • 对于 Co-Simulation 类型的 FMU，stepSize至关重要，不可忽略，它代表导入后的建议通讯步长。特别是对于内部采用定步长算法的 FMU，导入方应使用stepSize或stepSize的整数倍作为通讯步长。

    提示

    有关DefaultExperiment元素的详细信息，请参见：

  • ModelVariables：FMU 的核心数据结构，定义了 FMU 向外暴露的所有变量信息。示例：

    <ModelVariables>
<ScalarVariable name="driveAngle" valueReference="848" description="Reference distance to move" variability="tunable" causality="parameter" initial="exact">
<Real quantity="Angle" unit="rad" start="1.570796326794897"/>
</ScalarVariable>
<!--  index = 1  -->
<ScalarVariable name="PI.u_s" valueReference="6017" description="Connector of setpoint input signal">
<Real/>
</ScalarVariable>
<!--  index = 2  -->
</ModelVariables>

    ModelVariables元素由一组有序的ScalarVariable元素组成，

    • name：变量的全局唯一全名；

    • valueReference：仿真工具高效访问 FMU 内部变量值的唯一标识；

    • description：描述变量具体含义的字符串；

    • causality：变量的因果性，其取值与变量的可变性 variability密切相关。二者的取值需遵循以下允许的组合规则（图片来源：Functional Mock-up Interface Specification 2.0.4, Page 51 of 132）：

      其中，红色字母标注的为不允许的组合，绿色数字标注的为允许的组合。

      用户可借助 FMU 验证工具 FMPy 检查XML文件中因果性与可变性的组合是否合法。具体操作指南和使用示例请参见 FMU 验证工具。

      注意

      • FMI 规范定义了 ModelExchange 与 Co-Simulation 两类 FMU 的运行状态机，用于约束 FMI 接口调用的顺序和时机；

      • 因果性与可变性的组合还决定了变量可通过相应Set接口赋值的时机。即在不同的仿真运行模式下，可通过Set接口修改的变量范围各不相同。

      提示

      有关 FMI 规范中状态机以及各运行模式下可Set的变量详细信息，请参见：

    • initial：与变量的start属性结合使用，用于决定变量的初始化方式：

      • 若initial = "exact"，变量将在初始化时被严格赋值为其start属性值；
      • 若initial = "approx"，变量作为代数环中的迭代变量，其初始化迭代过程将以start属性值作为初始猜测值；
      • 若initial = "calculated"，变量的值在初始化过程中由其他变量计算得出，因此不允许显式提供start属性值。

    • quantity：变量所描述的物理量；

    • unit：变量的单位。

    提示

    有关ModelVariables元素的详细信息，尤其是变量的因果性、可变性、initial属性等重点内容，请参见：

# 模型交换

# 功能概述

模型交换（Model Exchange）类型的 FMU 具有如下特点：

  • 核心思想：FMU 仅提供模型的数学描述（微分、代数、离散方程等），不包含求解器；

  • 执行机制：由导入方仿真环境提供求解算法（如 ODE/DAE 求解器），负责时间推进、状态更新、事件处理。FMU 本身只实现模型方程的计算；

  • 适用场景：适用于耦合较紧密、需要统一求解器实现高精度求解的复杂系统仿真。特别适合存在代数环的模型。

Model Exchange 类型的 FMU 求解示意图如下所示（图片来源：Functional Mock-up Interface Specification 2.0.4, Page 73 of 132）：

  • External Model：指 FMU 实例本身；

  • Enclosing Model：指外层的宿主模型，即用于加载并驱动 FMU 的外部仿真环境或模型，也即导入方；

  • 宿主模型通过调用 FMU 接口完成状态更新与导数获取，结合宿主自身求解器进行数值积分和时间步进控制，进而驱动整个仿真流程。

# XML 属性

以 FMI 2.0 为例，模型交换类型的 FMU 会在modelDescription.xml中会生成如下内容：

<ModelExchange modelIdentifier="Examples_Model1" needsExecutionTool="false" completedIntegratorStepNotNeeded="false" canBeInstantiatedOnlyOncePerProcess="true" canGetAndSetFMUstate="false" canSerializeFMUstate="false"/>

以下仅对用户使用频率较高的属性进行介绍：

  • modelIdentifier：根据C语言语法的简短类名，形式为A_B_C。例如，若原模型名为Examples.Model1，则其简短名为modelIdentifier="Examples_Model1"。此外，modelIdentifier还会被用作binaries/目录下静态库和动态库的名称。

  • needsExecutionTool：如果为true，则表示该 FMU 无法独立运行，执行该 FMU 需要依赖特定工具，且 FMU 自身实现了与该工具的通信。这些工具依赖必须在documentation目录的文档中明确说明。如果为false，则表示该 FMU 可独立运行，无需额外依赖其他工具。

    提示

    无法独立运行相关的 FMU 应用问题，请参见常见问题案例库 #1402。

  • canBeInstantiatedOnlyOncePerProcess：如果为true，则该 FMU 在每个进程中只能被实例化一次；如果为false，则该 FMU 在每个进程中允许被实例化多次。

    提示

    无法独立运行相关的 FMU 应用问题，请参见常见问题案例库 #1630。

  • canGetAndSetFMUstate：如果为true，则仿真环境可以查询并恢复 FMU 的内部状态。即该 FMU 支持调用fmi2GetFMUState、fmi2SetFMUState和fmi2FreeFMUState等函数。

  • canSerializeFMUstate：如果为true，则仿真环境可以序列化 FMU 的内部状态。即该 FMU 支持调用fmi2SerializedFMUStateSize、fmi2SerializeFMUState和fmi2DeserializeFMUState等函数。此外，如果该值为true，则canGetAndSetFMUState标志也必须为true。

注意

对于以源码形式导出的模型交换 FMU，所有需要由编译器显式引用的C源文件，都必须在XML文件中的<ModelExchange><SourceFiles>结构中声明。

<ModelExchange> <!-- 上述属性此处省略 -->
  <SourceFiles>
    <File
      name="all.c"/>
  </SourceFiles>
</ModelExchange>

提示

# 协同仿真

# 功能概述

协同仿真（Co-Simulation）类型的 FMU 具有如下特点：

  • 核心思想：FMU 内部不仅封装模型，还集成了自带的求解器，可在无需外部干预的情况下独立推进时间步长。导入方主要负责协调各 FMU 之间的数据交换与同步；

  • 执行机制：在每个通信步长点，导入方将输入数据传递给 FMU，FMU 通过其内部求解器完成积分计算，并返回输出结果。因此，导入方不参与 FMU 的内部积分过程，二者在求解上是解耦的。在一个通信区间内，FMU 始终使用上一个通信点的输入值，而非外部系统的即时更新值，这导致了与外部仿真环境之间存在时序差，因此无法形成代数环；

  • 适用场景：适用于模型各部分由不同工具生成且各部分之间耦合程度较低的系统，尤其适合多工具协作和系统级仿真集成。

Co-Simulation 类型的 FMU 求解示意图如下所示（图片来源：Functional Mock-up Interface Specification 2.0.4, Page 99 of 132）：

  • Co-Simulation Master：通常指用于加载并驱动 FMU 的外部仿真环境或模型，也即导入方。作为协同仿真的主控单元，负责在预定的通讯步长和执行顺序下，协调和调度一个或多个从属 FMU 的运行；

  • Co-Simulation Slave：Co-Simulation 类型的 FMU 实例，作为从属方，内部集成了独立求解器，能够自主完成仿真步骤，并响应主控单元的调度命令，实现与其他 FMU 的协同仿真；

  • 在每个通讯步长点，Master 与 Slave 通过 FMI 接口函数进行输入输出数据交换，确保仿真状态的同步与协同推进。

# XML 属性

以 FMI 2.0 为例，协同仿真类型的 FMU 会在modelDescription.xml中生成如下内容：

<CoSimulation modelIdentifier="Examples_Model1" needsExecutionTool="false" canHandleVariableCommunicationStepSize="true" canInterpolateInputs="false" maxOutputDerivativeOrder="0" canRunAsynchronuously="false" canBeInstantiatedOnlyOncePerProcess="false" canNotUseMemoryManagementFunctions="false" canGetAndSetFMUstate="false" canSerializeFMUstate="false" providesDirectionalDerivative="false"/>

使用频率较高的属性与模型交换相同，不再赘述。

注意

此外，对于以源码形式导出的协同仿真 FMU，所有需要由编译器显式引用的C源文件，都必须在XML文件中的<CoSimulation><SourceFiles>结构中声明。详细信息，请参见模型交换。

提示

有关协同仿真的详细信息，请参见：