FMU 导入

---

功能概述

Sysplorer 支持导入外部 FMU 文件，并自动生成对应的Modelica模型，从而实现不同建模工具之间的协同仿真。FMU 导入后生成的Modelica模型是对 FMU 内部功能接口的封装，以下简称 FMU 封装模型。

所导入的 FMU 既可以由 Sysplorer 自身导出，也可以来自 Simulink、Dymola、Amesim 等第三方工具。Sysplorer 当前支持导入的 FMU 类型及版本如下表所示：

支持导入的 FMU 类型	支持的 FMI 版本	支持的平台	支持的位数	封装形式
Model Exchange	v1	Windows / Linux	32 位 / 64 位	二进制 / 源码
	v2
	v3
Co-Simulation	v1
	v2
	v3

提示

• 建议在使用 Sysplorer 导入 FMU 之前，先使用 FMPy 等验证工具对其进行检查，以确保 FMU 的正确性。详细信息，请参见 FMU 验证工具；

• 有关源码形式 FMU 的相关信息，请参见 FMU 文件结构。

功能面板

Sysplorer 中导入 FMU 的步骤如下：

1. 进入主页 > 导入，单击 FMU，弹出选择 FMU 文件对话框，选择已准备好的 FMU 文件，单击打开；

   
   

2. 在弹出的导入 FMU 对话框中，设置各个参数，然后单击确定按钮，即可完成导入。各参数的含义如下：

   

   • FMU文件：待导入的 FMU 文件的完整路径；

     提示

     • 一般情况下，当用户选择要导入的 FMU 后，FMU 文件路径由软件自动填充，用户无需手动修改；

     • 若需更换被导入的 FMU，用户可重新编辑 FMU 文件路径，或单击输入框右侧的...图标，在弹出的对话框中选择 FMU 文件。

     警告

     Windows 和 Linux 对单个文件名及完整路径长度均有限制：Windows 最多支持 255 个字符，Linux 最多支持 255 个字节。若 FMU 文件名超出限制，导入程序会尝试对其进行截断，但截断后的名称可能丢失.fmu后缀，或仍不符合路径长度要求，从而导致导入失败。

   • 模型名：FMU 导入后生成的封装模型名；

     注意

     模型名必须以字母或下划线开头，并且只能包含字母、数字或下划线。

     警告

     若模型名过长，也可能导致资源文件路径长度超出系统限制，从而导致导入失败。

   • 插入到：指定 FMU 导入后生成的封装模型被插入到的package。下拉列表中列出package类型的顶层类和嵌套类，缺省时<Top Model>表示创建顶层类；

     提示

     • FMU 本质是一个zip压缩包，导入后其内容会被解压至资源路径下，资源路径中包含modelDescription.xml和二进制库文件等；

     • 资源路径通常位于Resources文件夹下，而该文件夹一般位于插入到指定的package所属顶层包的同级目录中。资源路径的典型形式为Resources\模型名；

     • 建议用户显式指定插入的package，这样在后续整体复制或移动 FMU 封装模型时，可直接复制该package所在的整个目录；

     • 有关Modelica package的详细信息，请参见 Modelica 语言规范第 13 章 (opens new window)。

     注意

     复制 FMU 封装模型时，必须同步复制资源路径中的解压文件。

   • 模型文件存储位置：用于指定导入后生成的封装模型的保存路径。如果已指定插入的package，则该路径默认与package的存储位置一致；否则，默认为 Sysplorer 的工作目录；

     提示

     用户可进入主页 > 选项 > 系统目录，查看和编辑 Sysplorer 的工作目录。

   • 生成 FMU 资源路径采用模型全名：勾选该选项后，系统将在本地目录中以模型全名创建资源文件夹；若未勾选，则资源文件夹名称将使用模型简名。

     提示

     • 模型全名：包含完整包路径，形式为<顶层包>.<中间子包>.<底层子包>.<模型名>，例如TopPackage.SubPackage.BottomPackage.PIDController。以模型全名创建的资源路径示例为：Resources\SubPackage\BottomPackage\FMU_PID_Controller。其中，Resources目录与TopPackage位于同级目录下；

     • 模型简名：只包含模型自身名称，不含包路径，形式为<模型名>，例如PIDController。以模型简名创建的资源路径示例为：Resources\FMU_PID_Controller。其中，Resources目录与顶层包位于同级目录下；

     • 当同一 FMU 被导入至多级package的不同子包时，如果都使用相同的模型简名生成资源文件夹，可能会导致不同 FMU 的资源被覆盖或混淆。采用模型全名生成资源路径可以确保每个 FMU 的资源路径唯一，从而避免资源目录命名冲突。

使用导入后的模型

模型文本介绍

本节以如下Modelica模型Examples.Model4为例：

model Model4
  annotation(__MWORKS(version = "2025b"));
  input Real u;           // 输入变量
  output Real y;          // 输出变量
  Real x;                 // 局部变量
equation
  der(x) = sqrt(time);
  y = sin(u) + x;
end Model4;

将其导出为 V2 Co-Simulation 64 位的 FMU 后，再导入到 Sysplorer 中，得到名为FMU_Examples_Model4的 FMU 封装模型，以下对该模型文本中的重点内容进行介绍。

提示

单击主页 > 文本即可切换到模型文本视图。

以下仅对模型文本中的重点内容进行介绍。

• LibraryDirectory：FMU 封装模型通过外部函数constructor创建 FMU 实例，但外部函数的实现位于 FMU 解压后的库文件中，库文件路径由注解LibraryDirectory指定。

      function constructor
        input String strInstance;
        input String strLocation;
        input Boolean bLogging;
        output fmuModel fmuObject;
      external "C" fmuObject = Fmi2WrapCreateInst(strInstance, 1, "{e53cd404-5ec9-46fd-844b-9df487f9db3b}",
      strLocation, false, bLogging,
      "Examples_Model4.dll",
      "Examples_Model4");
      annotation (LibraryDirectory = "modelica://Examples/Resources/FMU_Examples_Model4/binaries");
      end constructor;
  

  提示

  • 有关外部函数的详细信息，请参见：Modelica 语言规范 12.9 节 (opens new window)；

  • 注解LibraryDirectory采用Modelica URI指定路径，相关详细信息，请参见 Modelica 语言规范第 12.9.4 节 (opens new window)。

  注意

  后续复制或移动 FMU 封装模型时，需同步复制 FMU 资源路径下的文件。如果改变了所属的package，还要相应更新 FMU 封装模型文本中的LibraryDirectory路径，否则仿真时可能因找不到库文件而报错。

• fmu_StepSize：用于控制 FMU 封装模型与 FMU 实例之间通过 FMI 接口进行输入/输出数据交换的时间间隔，也即通讯步长。Sysplorer 会从 FMU 的modelDescription.xml文件中读取DefaultExperiment元素的stepSize属性值，并将其作为fmu_StepSize的默认值。

  parameter Real fmu_StepSize = 0.002;
  

  提示

  • 用户也可自行调整通讯步长，fmu_StepSize越小，封装模型与 FMU 实例之间的数据交换越频繁，耦合越紧密，离散事件越多，仿真精度越高，但会降低仿真效率；

  • 仅 Co-Simulation 类型的 FMU 导入后具有fmu_StepSize参数。

• fmu_LoggingOn：用于控制是否启用 FMU 内部日志输出。其默认值为false，表示不输出 FMU 内部日志。

  parameter Boolean fmu_LoggingOn = false annotation (HideResult = true);
  

  提示

  • 如果 FMU 封装模型仿真有问题，用户可自行将 FMU 封装模型中的fmu_LoggingOn设为true，以查看 FMU 内部输出的日志信息，便于定位问题；

  • 如果想查看更多 FMU 日志信息，还需配合SetDebugLogging接口使用。相关详细信息，请参见：

    • FMI 3.0 规范第 2.3.1节 (opens new window)；
    • FMI 2.0 规范第 2.1.5 节：可前往 FMI 官网 (opens new window)下载PDF查阅。

• fmu_InputStartForInitialization：用于控制 FMU 输入变量u的初始化方式，默认值为false。若设为true，则u将采用常量fmu_Real_u_start的值进行初始化；若设为false，则u将直接使用其在初始时刻的自身数值完成初始。

  public
    Modelica.Blocks.Interfaces.RealInput u(start=fmu_Real_u_start[1]);    // 输入变量u
    parameter Boolean fmu_InputStartForInitialization = false annotation (HideResult = true);
    parameter Real fmu_Real_u_start[fmu_nRealInput] = {0.0} annotation (HideResult = true);
  initial algorithm
    if fmu_InputStartForInitialization then
      fmuFunctions.fmuSetReal(fmu_Object, {88}, fmu_Real_u_start);
    else
      fmuFunctions.fmuSetReal(fmu_Object, {88}, {u});
    end if;
  

  提示

  • 如果 FMU 封装模型位于代数环中，且fmu_InputStartForInitialization=false，则在初始化过程中需要通过求解非线性方程组来确定u的初始值。为避免这种情况，用户可将fmu_InputStartForInitialization设为true，并合理设置fmu_Real_u_start的值，使u直接采用该初值，从而打破环路。

  • 若确定封装模型在与外部模型集成过程中不存在输入依赖输出的情况，则可将fmu_InputStartForInitialization值设为false，使得输入变量初始时刻值生效。

  • 仅 Co-Simulation 类型的 FMU 导入后会生成fmu_InputStartForInitialization。

  • 有关SetReal接口的详细信息，请参见：

    • FMI 3.0 规范 2.2.7 节 (opens new window)；
    • FMI 2.0 规范 2.1.7 节：可前往 FMI 官网 (opens new window)下载PDF查阅。

组件参数

最新版本的 Sysplorer（20251130 及之后）中，前述 FMU 导入模型的几个关键参数现已支持在组件参数面板中直接修改，操作更加便捷高效。

图形视图调整

单击主页 > 图形，即可将导入之后的模型切换为图形视图：

在图形视图下，用户可通过拖拽鼠标自由调整 FMU 封装模型输入与输出端口的位置及其尺寸，优化视觉呈现效果。 FMU 封装模型还可以作为组件被其他模型引用，并与其输入、输出端口进行连接。

注意

在与 FMU 实例模型的输入、输出端口进行连接时，应确保端口的类型和维度均匹配。

导入失败问题

Sysplorer 导入 FMU 失败的常见原因及解决方法如下：

提示

如果在 Sysplorer 中导入 FMU 失败，建议您优先使用 FMPy 等 FMU 验证工具对该 FMU 进行验证与测试仿真。有关详细步骤，请参见 FMU 验证工具。

1. FMU 文件不存在：导入时所选 FMU 文件在选择后被删除或移动。报错信息示例如下：

   

   解决办法：请确保导入时所选 FMU 文件仍存在且路径有效。

2. FMU 内容缺失：FMU 压缩包内缺失XML或库文件，报错信息示例如下：

   错误(9205): C:\Users\fengb\Documents\MWORKS\PID_Controller.fmu 缺少必要的 modelDescription.xml 文件, 无法进行 FMU 的导入操作.
   导入FMU失败：FMU中没有xml文件！
   

   或者

   错误(9211): C:\Users\fengb\Documents\MWORKS\PID_Controller.fmu 缺少必要的 FMU 二进制程序文件.
   导入FMU失败：没有导入平台对应的动态库！
   

   解决办法：请确保 FMU 的文件内容完整。

3. FMU 解压路径无法写入：FMU 资源文件解压路径缺少写入权限，报错信息示例如下：

   无法创建路径 “C:\Users\fengb\Downloads\Test/Resources/FMU_PID_Controller”！
   

   解决办法：请确保 FMU 导入时指定的模型文件存储位置下的Resources目录具有完整的读写权限。

4. FMU 压缩方式错误：FMU 文件的压缩方式不是Zip格式，报错信息示例如下：

   导入FMU失败：解压FMU文件失败！
   

   解决办法：请确保 FMU 的压缩格式为Zip格式。

5. XML 文件中缺少或无效的版本信息：modelDescription.xml中的<fmiModelDescription>元素缺失fmiVersion属性，或该属性值不为1.0,2.0或3.0。报错信息示例如下：

   导入FMU失败：没有FMI版本信息。
   

   解决办法：请确保modelDescription.xml中<fmiModelDescription>元素具有fmiVersion属性且属性值正确。

6. XML 文件中缺少文件描述符：modelDescription.xml中的<CoSimulation>或<ModelExchange>元素缺失modelIdentifier属性。报错信息示例如下：

   导入FMU失败：没有模型标识符！
   

   解决办法：请确保modelDescription.xml中<CoSimulation>或<ModelExchange>元素具有modelIdentifier属性。

7. FMU 类型不为 Co-Simulation 或 ModelExchange：modelDescription.xml中的<CoSimulation>或<ModelExchange>元素的标准名称被篡改，未使用标准的CoSimulation或ModelExchange。报错信息示例如下：

   导入FMU失败：仅支持导入FMI 1.0 至 3.0 ModelExchange 和 CoSimulation 类型的FMU！
   

FMU 应用问题

FMU 自身问题

此类问题源于 FMU 本身的功能限制，与 Sysplorer 的导入功能无关。

1. FMU 自身不支持多实例运行：某些第三方仿真工具导出的 FMU 可能不支持多实例运行，即modelDescription.xml中<CoSimulation>或<ModelExchange>元素的canBeInstantiatedOnlyOncePerProcess属性值为true。如果在模型中创建了多个该 FMU 的实例，则可能导致仿真失败或结果异常。

2. FMU 不能独立运行：某些第三方仿真工具导出的 FMU 可能需要依赖特定工具才能运行，即modelDescription.xml中<CoSimulation>或<ModelExchange>元素的needsExecutionTool属性值为true。该 FMU 导入到 Sysplorer 中可能出现仿真失败。

3. FMU 具有与操作系统同名的动态库：如果 FMU 中的库文件与操作系统的库文件重名，可能导致仿真失败。

4. 外部函数导致仿真崩溃：FMU 所依赖的外部函数出现异常时，可能引发仿真崩溃。

5. 翻译报错：对于源码形式的 FMU，可根据C编译器的报错提示，勾选相应的编译选项。

   提示

   有关源码形式 FMU 编译阶段报错的相关问题及解决方案，请参见本手册常见问题案例库中的通过 MWORKS 仿真 FMU 章节。

导入参数配置问题

1. FMU 库文件的位数与当前编译器位数不匹配：如果 FMU 库文件的位数与所选编译器不一致，可能导致仿真失败。例如，FMU 仅包含 64 位库文件，但在 Sysplorer 中却选择了 32 位编译器。

2. 模型库迁移时未同步迁移库文件：FMU 导入成功后，如果仅移动了模型库而未同步迁移 FMU 解压生成的库文件，可能会因库文件缺失导致仿真失败。

提示

更多 FMU 应用问题请参见本手册常见问题案例库。