引言两个视角一个真相理解 Sysplorer/MWorks 的外部函数调用机制可以围绕一个核心问题展开Modelica声明式建模语言如何与 C/Fortran过程式编程语言实现无缝集成但这个问题有一个容易被忽视的前提——带着过程式编程的直觉进入这个领域我写了一个函数仿真步进一次它应该被调用一次。真实情况并非如此。Modelica 外部函数不是由用户显式按顺序调用的而是被翻译进求解器生成的代码中由求解器在初始化、事件处理、方程残差计算、非线性迭代、终止等阶段按需调用。因此完整的理解需要两个视角的结合宏观视角六维度框架从声明契约、数据映射、生命周期、构建链接、调试排错到高级边界建立认知微观视角求解器调度机制深入when/if/sample的本质区别、代数环导致的调用次数放大、pre()打破环、ExternalObject管理跨调用状态。本文把两者融合成一个统一的框架——先用六维度建立理解地图再在每个维度下填充求解器调度机制的深度细节。一、六维度理解框架总览维度核心问题关键机制维度一声明与实现的契约如何告知系统调用外部函数external语句 Include/Library注解维度二数据如何过桥Modelica 类型如何映射到 C/Fortran按值/指针/结构体映射ModelicaUtilities.h维度三调用在何时发生生命周期与执行时机如何控制行为区段 when/if/sample的本质区别维度四构建与链接代码如何被装配进仿真编译器一致性、库路径、依赖管理维度五调试与故障排查出了问题怎么办打印、附加调试、常见错误模式维度六高级特性与边界机制的延伸与局限在哪性能动机、语言支持边界、ExternalObject下面逐一展开并在每个维度中嵌入求解器调度的深层机制。二、维度一声明与实现的契约在 Modelica 模型中调用外部函数遵循一种声明与实现分离的契约模式。2.1 声明方Modelica Function你需要在模型中定义一个function但它没有algorithm区域取而代之的是一条external语句function foo input Real x; output Real y; external C y c_foo(x) annotation(Includec_foo.h, IncludeDirectorymodelica://MyLib/Resources/Include, Librarymyfoo, LibraryDirectorymodelica://MyLib/Resources/Library); end foo;这条语句同时指定了外部语言如C和调用语法。Include、IncludeDirectory、Library、LibraryDirectory决定头文件、源文件和库的搜索位置。2.2 实现方外部代码的多种集成方式Sysplorer 支持多种集成方式灵活性很高直接包含源文件通过annotation(Include#include \my_func.c\)直接嵌入 C 代码链接库文件通过annotation(Librarymylib)指定链接库支持动态库.dll/.so或静态库.lib使用头文件通过Include和IncludeDirectory注解指定头文件及其路径环境变量配置Sysplorer 也支持在环境变量中配置外部函数路径可视化外部函数编辑器简化导入和路径配置过程。2.3 函数名映射规则如果external语句中显式指定了函数名如external C y sin(u)则调用该名称的 C 函数如果只写external C;则 Modelica 函数的名称就被用作 C 函数名C 语言区分大小写Fortran 77 不区分。三、维度二数据如何过桥——参数映射与类型兼容这是机制的核心即 Modelica 的数据类型如何安全、正确地映射到 C/Fortran。Sysplorer 主要支持C 语言和FORTRAN 77。3.1 映射速查表Modelica 类型C 输入C 输出Realdoubledouble *Integerintint *BooleanModelicaBoolean优先来自ModelicaUtilities.hModelicaBoolean *Stringconst char*const char **必须使用ModelicaAllocateString分配Enumerationintint *输入参数按值传递输出参数传递指针地址。ModelicaBoolean是 Modelica 官方头文件ModelicaUtilities.h中定义的一个类型别名底层就是int推荐用它代替裸int来表示 Modelica 的Boolean类型目的是语义清晰、便于维护和跨工具兼容值映射上false对应0、true对应1但 C 侧返回时任何非零值都应视为true编写者不应假设传入的true一定是1。3.2 数组与记录数组固定维数组默认行优先annotation(arrayLayoutcolumnMajor)修改为列优先传递首地址 各维度长度动态数组规则不同需单独处理。Record 记录映射为 Cstruct重点坑C 结构体内存对齐与 Modelica 记录布局不一致极易出现字段错位。从2023b 版本开始Sysplorer 支持在外部函数中使用记录当记录作为参数传递给 C 函数时传递的是指向该结构体的指针。function fcn input R r;// R是Modelica中定义的recordoutput Real x;externalCxFuncDemo(r)annotation(Include#include \YourStructDef.c\);// 必须包含结构体定义end fcn;// Modelica 记录 Rec 作为参数传给 C 函数// Sysplorer 实际传递的是指向 struct Rec 的指针doubleFuncDemo(conststructRec*r){// 正确通过指针访问returnr-xr-y;}3.3 输出结果的四种方式函数返回值所有参数都是输入返回单个值通过输出参数返回值函数返回void既有返回值又附带输出参数C 代码直接写在Include注解内适合简单逻辑不适合复杂调试。3.4 字符串输出与错误处理必须使用ModelicaAllocateString/ModelicaAllocateStringWithErrorReturn内存由 Modelica 运行时释放配套打印报错ModelicaMessage、ModelicaError头文件ModelicaUtilities.h。四、维度三调用在何时发生——生命周期与执行时机机制核心这是外部函数集成中最容易踩坑的维度也是两份视角交汇最深的地方。4.1 宏观行为区段简化视图Sysplorer 的仿真引擎将外部函数的执行时机与特定的行为区段绑定行为区段执行时机典型用途Start开始仿真开始时执行一次初始化全局变量、打开文件等一次性设置Init初始化仿真开始或条件子系统启用时执行根据条件进行初始化Step输出/步进每个仿真时间步执行核心计算如根据当前输入计算输出Terminate终止仿真结束时执行一次资源清理、关闭文件等4.2 微观求解器按需调用真实机制上表是宏观生命周期的简化视图。真实机制是调用次数不由仿真步数唯一决定。官方文档明确说明函数调用的次数跟求解步没有必然联系。同一个仿真步内求解器可能为了残差计算或非线性迭代多次调用外部函数。调用点可能出现在初始化阶段、连续方程计算、事件处理、非线性方程迭代、when条件触发、initial algorithm/terminal等算法段、外部对象构造/析构时。由此引出三条必须记住的机制性结论调用次数不可假定调用顺序默认不确定多个方程中调用外部函数时语句执行顺序不确定外部函数优先设计成可重复调用、接口稳定、不依赖隐式调用顺序的纯函数形式。4.3 when vs if vs sample本质区别这是调用次数控制的核心。when事件触发器。仅在条件从false跳变为true的上升沿瞬间产生一个事件点条件持续为true时不会在连续时间切片重复触发新事件。但在同一个事件点内部如果存在代数环求解器仍会迭代求值多次调用外部函数。when time 0.5 then y foo(x); end when;if连续选择器。写在普通方程里求解器在每一个需要计算该方程的时刻包括仿真步点以及非线性迭代中的每一次试探都会对条件求值并执行对应分支里的函数。y if time 0.5 then foo(x) else -time;sample周期事件触发。作为when的条件可保证when内语句按固定周期产生事件when sample(0, 0.1) then y foo(x); end when;一句话总结when关心的是状态切换的事件点if关心的是当前连续时刻选择哪条分支。4.4 对比示例观察调用次数差异C 侧计数器counter.cstaticintcall_count0;doublecount_call(doublex){call_count;return(double)call_count;}Modelica 侧对比模型model testCount annotation(__MWORKS(version26.3.0),experiment(AlgorithmDassl,InlineIntegratorfalse,InlineStepSizefalse,Interval0.002,StartTime0,StopTime2,StoreEventValue0,Tolerance0.0001)); function count_call input Real x; output Real y; external C y count_call(x) annotation( Include #include \counter.c\, IncludeDirectory . ); end count_call; discrete Real y_when; // 离散变量在 when 中赋值 Real y_if; // 连续变量不需要 discrete Real x sin(time); initial equation y_when 0; // y_if 是连续变量无需强制 initial equation equation when time 0.5 then y_when count_call(x); // 仅在事件瞬间调用一次 end when; y_if if time 0.5 then count_call(x) else 0; // 连续求值调用次数不确定 end testCount;仿真后现象y_when在time 0.5后保持一个固定值无代数环前提下仅调用一次而y_if的计数会随着求解器的每一次方程求值持续增长速率高于输出步数非线性迭代会放大调用次数。4.5 非线性方程块调用次数放大的根源非线性方程块源于模型中的代数环——一组在同一时刻相互依赖的方程典型形式是y f(x)且x g(y)。求解器处理这种闭环的方式是迭代先给未知量一个猜测值计算方程残差再根据残差调整猜测值反复尝试。如果外部函数被包含在这个迭代环里求解器在每一次迭代试探中都必须调用它。官方文档中有一个典型示例when sample(0,0.1)触发了 10 次方程求解但由于方程存在代数环和非线性迭代外部函数实际被调用了43 次。有代数环的版本调用次数不可控model AlgebraicLoopBad function ExtLib_StepRun input Real u; output Real y; external C y ext_step_run(u); end ExtLib_StepRun; Real x, y; when sample(0, 0.1) then (x, y) ExtLib_StepRun(x); // x 既是输入又是输出形成代数环 end when; end AlgebraicLoopBad;用pre(x)打破代数环的版本【推荐写法】model AlgebraicLoopFixed function ExtLib_StepRun input Real u; output Real y; external C y ext_step_run(u); end ExtLib_StepRun; Real x, y; when sample(0, 0.1) then (x, y) ExtLib_StepRun(pre(x)); // pre(x) 使用上一时刻已知值消除代数环 end when; end AlgebraicLoopFixed;pre(x)取上一时刻的已知值使得ExtLib_StepRun的输入不再依赖当前时刻的输出代数环被打破方程退化为显式计算每次事件触发只调用一次外部函数。原则外部函数尽量不要放进非线性方程块对调用次数敏感、带副作用的外部函数应使用whensample配合显式状态保存。4.6 调用顺序控制不能依赖书写顺序如果两个外部函数的调用顺序必须固定不能依赖方程书写顺序。方案优先级首选放入algorithm算法段段内语句严格按书写顺序执行次选构造业务天然的数据依赖后执行函数输入使用前一个函数的输出推荐标准写法algorithm 段algorithm y : getreal_arg(x); z : getreal_arg(y);五、维度四构建与链接——代码如何被装配进仿真5.1 编译器一致性外部库必须使用与 Sysplorer相同版本、相同位数32/64 位的编译器进行编译。位数不兼容是无法解析的外部符号等错误的常见原因。32 位 MWorks 不能调用 64 位 DLL反之亦然分平台库放在win32、win64子目录。5.2 链接配置通过Library和LibraryDirectory注解告知 Sysplorer 库文件的位置。对于动态库还需要确保运行时.dll/.so文件在系统路径或模型目录下可被找到。Linux 库静态库libtest.a、动态库libtest.so注解内库名填写test去掉前缀后缀。5.3 依赖管理如果外部函数依赖于其他动态库需要确保这些依赖库也位于可被加载的路径中可以使用depends等工具检查依赖关系。DLL 导出检查使用depends工具确认目标函数已导出无 lib 时编写.def文件导出符号。DLL 依赖链依赖的子 DLL 需要和主 DLL 放在同一搜索目录。5.4 路径规范统一使用 Modelica URI loadResource打包 FMU 时所有资源使用相对 modelica 路径。六、维度五调试与故障排查由于外部函数运行在 Sysplorer 内部调试相对复杂但有一些成熟的排查路径。6.1 日志与打印最直接的方式是在 C 代码中向文件或控制台打印关键信息以观察函数的运行状态和中间变量。注意print打印调试会引入额外事件点改变求解行为正式版本全部删除调试打印。6.2 单步调试可以使用Visual Studio等工具搭建调试环境将调试器附加到 Sysplorer 的求解器进程上对 C 代码进行单步调试这是定位复杂逻辑错误的有效手段。6.3 常见错误模式空指针、野指针、数组越界是导致仿真崩溃的常见原因。此外无效的外部函数接口注解通常意味着路径配置有误可使用外部函数编辑器重新设置。6.4 故障排查速查表现象根因修复方案外部函数调用次数远大于 sample 采样次数when内部存在代数环事件迭代反复求值pre()提取上一时刻状态打断代数环相同输入C 函数返回值不稳定代码使用全局/静态变量多实例互相污染状态迁移至ExternalObject上下文初始化阶段 DLL 加载崩溃位数不匹配、依赖 DLL 缺失、导出符号不存在统一 x64/x32、检查依赖、用depends校验导出Record 传入 C struct 后字段值错乱C 结构体内存对齐和 Modelica 记录布局不一致手动强制对齐、避免复合记录嵌套FMU 打包后找不到 dll/头文件使用绝对路径未使用loadResource全部改为modelica://URI通过loadResource转路径仿真结束内存泄漏、文件句柄不释放没有调用destructor/terminal释放逻辑检查ExternalObject析构、terminal钩子是否正常触发6.5 集成测试流程C 侧独立调用 DLL 验证接口 → Modelica 封装 → 同输入对比 C 侧结果 → 接入系统模型关注步长、初值、求解器类型。七、维度六高级特性与边界7.1 性能考量引入外部函数的一个重要动机就是提升性能例如调用高度优化的数值计算库来完成 Modelica 难以快速求解的任务。7.2 ExternalObject跨调用状态的容器【Modelica 标准优先推荐】普通外部函数默认是**无记忆纯函数**——规范假定相同输入产生相同输出。但很多时候你需要跨调用保留数据比如只在仿真开始时从文件读入一张大表后续插值时反复使用它。ExternalObject就是用来合法地保存这种跨调用内存的标准机制。constructor构造函数在对象第一次被使用之前由系统自动调用且仅调用一次。职责是初始化分配内存、打开文件、加载数据表返回void*给 Modelica 环境保存。destructor析构函数在对象最后一次被使用之后由系统自动调用且仅调用一次。职责是清理释放内存、关闭文件。关键规则你永远不能在代码里手动调用它们。它们的执行时机完全由求解器根据对象的生命周期自动决定。可以类比为constructor 是打开文件destructor 是关闭文件你写的插值函数是读文件——你只负责中间读写打开和关闭的时机由系统管理。C 侧实现table.c#includestdlib.h#includestdio.htypedefstruct{intn;double*x;double*y;}Table;void*table_constructor(constchar*filename){Table*t(Table*)malloc(sizeof(Table));FILE*ffopen(filename,r);if(!f)returnNULL;t-n0;t-x(double*)malloc(1000*sizeof(double));t-y(double*)malloc(1000*sizeof(double));while(fscanf(f,%lf,%lf,t-x[t-n],t-y[t-n])2){t-n;}fclose(f);return(void*)t;}doubletable_interp(void*obj,doublexq){Table*t(Table*)obj;for(inti0;it-n-1;i){if(xqt-x[i]xqt-x[i1]){doubleratio(xq-t-x[i])/(t-x[i1]-t-x[i]);returnt-y[i]ratio*(t-y[i1]-t-y[i]);}}returnt-y[t-n-1];}voidtable_destructor(void*obj){Table*t(Table*)obj;free(t-x);free(t-y);free(t);}Modelica 侧封装model TableLookup class TableObject extends ExternalObject; function constructor input String filename; output TableObject table; external C table table_constructor(filename) annotation(Includetable.c); end constructor; function destructor input TableObject table; external C table_destructor(table) annotation(Includetable.c); end destructor; end TableObject; function interp input TableObject table; input Real xq; output Real yq; external C yq table_interp(table, xq) annotation(Includetable.c); end interp; TableObject myTable TableObject( Modelica.Utilities.Files.loadResource(modelica://MyLib/Resources/Data/table.csv)); Real xq time; Real yq interp(myTable, xq); end TableLookup;在这个例子中table_constructor只在myTable第一次被使用时调用一次读入整个 CSVinterp在仿真过程中可能被调用成百上千次但每次都只是内存插值不再读文件table_destructor在仿真结束时自动调用释放内存。when控制何时调用ExternalObject管理调用之间留下的状态二者配合兼顾时序精确性与性能。7.3 DLL 生命周期管理Initialize / DoStep / Terminate 模式【兼容遗留 DLL 的备选方案】对于需要封装遗留 DLL 的场景可以采用生命周期钩子模式model DLLWrapper function UserDLL_Initialize input String dllPath; output Integer handle; external C handle user_dll_initialize(dllPath) annotation(Includedll_wrapper.c); end UserDLL_Initialize; function UserDLL_DoStep input Integer handle; input Real a, b; output Real c; external C c user_dll_do_step(handle, a, b) annotation(Includedll_wrapper.c); end UserDLL_DoStep; function UserDLL_Terminate input Integer handle; external C user_dll_terminate(handle) annotation(Includedll_wrapper.c); end UserDLL_Terminate; Integer handle; Real a sin(time), b cos(time), c; when initial() then handle UserDLL_Initialize( Modelica.Utilities.Files.loadResource(modelica://MyLib/Resources/Library/mydll.dll)); end when; when sample(0, 0.01) then c UserDLL_DoStep(handle, a, b); end when; when terminal() then UserDLL_Terminate(handle); end when; end DLLWrapper;机制要点Initialize在when initial()中调用一次负责LoadLibrary、GetProcAddress、申请内存DoStep在when sample(0, stepSize)中按周期调用使用已保存的句柄不要每次 DoStep 都 LoadLibraryTerminate在when terminal()中调用一次负责FreeLibrary和free。7.4 局限性目前 Sysplorer 主要支持 C 和 FORTRAN 77C 需通过extern C封装。对于其他语言如 Python、JuliaMWORKS 平台提供了更广泛的接口支持但这超出了经典外部函数机制的范畴属于更高层次的联合仿真或模块集成。7.5 全局/静态变量严禁滥用C、DLL 内部静态变量会在多实例模型中互相干扰多实例场景全部迁移状态至ExternalObject上下文。7.6 实时仿真补充强实时场景必须搭配固定步长求解器变步长求解器事件点不固定不适合硬件 IO、周期控制类副作用逻辑。八、注意事项调用次数不可假定普通方程中可能因非线性迭代多次调用when仅产生事件点事件内部仍可迭代重复调用if满足条件时所有求值时刻调用调用次数和仿真步无必然绑定。调用顺序不可依赖书写顺序优先algorithm段、业务数据依赖冗余参数造假依赖属于临时手段。避免非线性代数环外部函数落入代数环会造成调用次数爆炸带副作用逻辑必须用pre()打破环。资源生命周期DLL 加载、文件打开、内存申请放constructor/when initial()释放放destructor/when terminal()禁止在 DoStep 里重复 LoadLibrary。类型映射严格匹配布尔优先用ModelicaBoolean记录警惕struct对齐字符串输出使用官方分配接口。位数匹配32 位 MWorks 不能调用 64 位 DLL反之亦然分平台库放在win32、win64子目录。DLL 导出检查使用depends工具确认目标函数已导出无 lib 时编写.def文件导出符号。DLL 依赖链依赖的子 DLL 需要和主 DLL 放在同一搜索目录。路径规范统一使用 Modelica URI loadResource打包 FMU 时所有资源使用相对 modelica 路径。全局/静态变量严禁滥用C、DLL 内部静态变量会在多实例模型中互相干扰多实例场景全部迁移状态至ExternalObject上下文。Linux 库静态库libtest.a、动态库libtest.so注解内库名填写test去掉前缀后缀。C 封装MWorks 不支持直接调用 C 成员函数必须使用extern C封装 wrapper。FORTRANSUBROUTINE全部参数传指针包含输入参数。调试约束print打印调试会引入额外事件点改变求解行为正式版本全部删除调试打印。集成测试流程C 侧独立调用 DLL 验证接口 → Modelica 封装 → 同输入对比 C 侧结果 → 接入系统模型关注步长、初值、求解器类型。实时仿真补充强实时场景必须搭配固定步长求解器变步长求解器事件点不固定不适合硬件 IO、周期控制类副作用逻辑。九、总结Sysplorer/MWorks 的外部函数调用机制本质是一个在 Modelica 的声明式世界与 C/Fortran 的过程式世界之间建立映射和通信的桥梁。理解它需要双重视角宏观上用声明契约、数据映射、构建配置、运行时生命周期、调试排错、高级边界六个维度建立工程认知地图微观上牢牢记住求解器按需调用这一真相——普通方程中可能被迭代多次when/sample仅产生事件点事件点内部仍可能迭代if条件成立时在所有连续求值时刻调用。理解这套机制的关键是把思维从“我按顺序调用函数”切换到“我声明函数求解器按需调用它”。一旦接受这个前提when与if的区别、pre()打破代数环、constructor/destructor的生命周期管理、六维度框架中的每一个环节都会变得顺理成章——它们都是在回答同一个问题如何在一个由求解器驱动的黑箱调用模型里可靠地控制一个外部函数的执行并正确地完成数据与资源的过桥。 
长河君 · 2026/10/29 11:09:13 · 阅读 1.2k Sysplorer/MWorks 外部函数调用机制
引言两个视角一个真相理解 Sysplorer/MWorks 的外部函数调用机制可以围绕一个核心问题展开Modelica声明式建模语言如何与 C/Fortran过程式编程语言实现无缝集成但这个问题有一个容易被忽视的前提——带着过程式编程的直觉进入这个领域我写了一个函数仿真步进一次它应该被调用一次。真实情况并非如此。Modelica 外部函数不是由用户显式按顺序调用的而是被翻译进求解器生成的代码中由求解器在初始化、事件处理、方程残差计算、非线性迭代、终止等阶段按需调用。因此完整的理解需要两个视角的结合宏观视角六维度框架从声明契约、数据映射、生命周期、构建链接、调试排错到高级边界建立认知微观视角求解器调度机制深入when/if/sample的本质区别、代数环导致的调用次数放大、pre()打破环、ExternalObject管理跨调用状态。本文把两者融合成一个统一的框架——先用六维度建立理解地图再在每个维度下填充求解器调度机制的深度细节。一、六维度理解框架总览维度核心问题关键机制维度一声明与实现的契约如何告知系统调用外部函数external语句 Include/Library注解维度二数据如何过桥Modelica 类型如何映射到 C/Fortran按值/指针/结构体映射ModelicaUtilities.h维度三调用在何时发生生命周期与执行时机如何控制行为区段 when/if/sample的本质区别维度四构建与链接代码如何被装配进仿真编译器一致性、库路径、依赖管理维度五调试与故障排查出了问题怎么办打印、附加调试、常见错误模式维度六高级特性与边界机制的延伸与局限在哪性能动机、语言支持边界、ExternalObject下面逐一展开并在每个维度中嵌入求解器调度的深层机制。二、维度一声明与实现的契约在 Modelica 模型中调用外部函数遵循一种声明与实现分离的契约模式。2.1 声明方Modelica Function你需要在模型中定义一个function但它没有algorithm区域取而代之的是一条external语句function foo input Real x; output Real y; external C y c_foo(x) annotation(Includec_foo.h, IncludeDirectorymodelica://MyLib/Resources/Include, Librarymyfoo, LibraryDirectorymodelica://MyLib/Resources/Library); end foo;这条语句同时指定了外部语言如C和调用语法。Include、IncludeDirectory、Library、LibraryDirectory决定头文件、源文件和库的搜索位置。2.2 实现方外部代码的多种集成方式Sysplorer 支持多种集成方式灵活性很高直接包含源文件通过annotation(Include#include \my_func.c\)直接嵌入 C 代码链接库文件通过annotation(Librarymylib)指定链接库支持动态库.dll/.so或静态库.lib使用头文件通过Include和IncludeDirectory注解指定头文件及其路径环境变量配置Sysplorer 也支持在环境变量中配置外部函数路径可视化外部函数编辑器简化导入和路径配置过程。2.3 函数名映射规则如果external语句中显式指定了函数名如external C y sin(u)则调用该名称的 C 函数如果只写external C;则 Modelica 函数的名称就被用作 C 函数名C 语言区分大小写Fortran 77 不区分。三、维度二数据如何过桥——参数映射与类型兼容这是机制的核心即 Modelica 的数据类型如何安全、正确地映射到 C/Fortran。Sysplorer 主要支持C 语言和FORTRAN 77。3.1 映射速查表Modelica 类型C 输入C 输出Realdoubledouble *Integerintint *BooleanModelicaBoolean优先来自ModelicaUtilities.hModelicaBoolean *Stringconst char*const char **必须使用ModelicaAllocateString分配Enumerationintint *输入参数按值传递输出参数传递指针地址。ModelicaBoolean是 Modelica 官方头文件ModelicaUtilities.h中定义的一个类型别名底层就是int推荐用它代替裸int来表示 Modelica 的Boolean类型目的是语义清晰、便于维护和跨工具兼容值映射上false对应0、true对应1但 C 侧返回时任何非零值都应视为true编写者不应假设传入的true一定是1。3.2 数组与记录数组固定维数组默认行优先annotation(arrayLayoutcolumnMajor)修改为列优先传递首地址 各维度长度动态数组规则不同需单独处理。Record 记录映射为 Cstruct重点坑C 结构体内存对齐与 Modelica 记录布局不一致极易出现字段错位。从2023b 版本开始Sysplorer 支持在外部函数中使用记录当记录作为参数传递给 C 函数时传递的是指向该结构体的指针。function fcn input R r;// R是Modelica中定义的recordoutput Real x;externalCxFuncDemo(r)annotation(Include#include \YourStructDef.c\);// 必须包含结构体定义end fcn;// Modelica 记录 Rec 作为参数传给 C 函数// Sysplorer 实际传递的是指向 struct Rec 的指针doubleFuncDemo(conststructRec*r){// 正确通过指针访问returnr-xr-y;}3.3 输出结果的四种方式函数返回值所有参数都是输入返回单个值通过输出参数返回值函数返回void既有返回值又附带输出参数C 代码直接写在Include注解内适合简单逻辑不适合复杂调试。3.4 字符串输出与错误处理必须使用ModelicaAllocateString/ModelicaAllocateStringWithErrorReturn内存由 Modelica 运行时释放配套打印报错ModelicaMessage、ModelicaError头文件ModelicaUtilities.h。四、维度三调用在何时发生——生命周期与执行时机机制核心这是外部函数集成中最容易踩坑的维度也是两份视角交汇最深的地方。4.1 宏观行为区段简化视图Sysplorer 的仿真引擎将外部函数的执行时机与特定的行为区段绑定行为区段执行时机典型用途Start开始仿真开始时执行一次初始化全局变量、打开文件等一次性设置Init初始化仿真开始或条件子系统启用时执行根据条件进行初始化Step输出/步进每个仿真时间步执行核心计算如根据当前输入计算输出Terminate终止仿真结束时执行一次资源清理、关闭文件等4.2 微观求解器按需调用真实机制上表是宏观生命周期的简化视图。真实机制是调用次数不由仿真步数唯一决定。官方文档明确说明函数调用的次数跟求解步没有必然联系。同一个仿真步内求解器可能为了残差计算或非线性迭代多次调用外部函数。调用点可能出现在初始化阶段、连续方程计算、事件处理、非线性方程迭代、when条件触发、initial algorithm/terminal等算法段、外部对象构造/析构时。由此引出三条必须记住的机制性结论调用次数不可假定调用顺序默认不确定多个方程中调用外部函数时语句执行顺序不确定外部函数优先设计成可重复调用、接口稳定、不依赖隐式调用顺序的纯函数形式。4.3 when vs if vs sample本质区别这是调用次数控制的核心。when事件触发器。仅在条件从false跳变为true的上升沿瞬间产生一个事件点条件持续为true时不会在连续时间切片重复触发新事件。但在同一个事件点内部如果存在代数环求解器仍会迭代求值多次调用外部函数。when time 0.5 then y foo(x); end when;if连续选择器。写在普通方程里求解器在每一个需要计算该方程的时刻包括仿真步点以及非线性迭代中的每一次试探都会对条件求值并执行对应分支里的函数。y if time 0.5 then foo(x) else -time;sample周期事件触发。作为when的条件可保证when内语句按固定周期产生事件when sample(0, 0.1) then y foo(x); end when;一句话总结when关心的是状态切换的事件点if关心的是当前连续时刻选择哪条分支。4.4 对比示例观察调用次数差异C 侧计数器counter.cstaticintcall_count0;doublecount_call(doublex){call_count;return(double)call_count;}Modelica 侧对比模型model testCount annotation(__MWORKS(version26.3.0),experiment(AlgorithmDassl,InlineIntegratorfalse,InlineStepSizefalse,Interval0.002,StartTime0,StopTime2,StoreEventValue0,Tolerance0.0001)); function count_call input Real x; output Real y; external C y count_call(x) annotation( Include #include \counter.c\, IncludeDirectory . ); end count_call; discrete Real y_when; // 离散变量在 when 中赋值 Real y_if; // 连续变量不需要 discrete Real x sin(time); initial equation y_when 0; // y_if 是连续变量无需强制 initial equation equation when time 0.5 then y_when count_call(x); // 仅在事件瞬间调用一次 end when; y_if if time 0.5 then count_call(x) else 0; // 连续求值调用次数不确定 end testCount;仿真后现象y_when在time 0.5后保持一个固定值无代数环前提下仅调用一次而y_if的计数会随着求解器的每一次方程求值持续增长速率高于输出步数非线性迭代会放大调用次数。4.5 非线性方程块调用次数放大的根源非线性方程块源于模型中的代数环——一组在同一时刻相互依赖的方程典型形式是y f(x)且x g(y)。求解器处理这种闭环的方式是迭代先给未知量一个猜测值计算方程残差再根据残差调整猜测值反复尝试。如果外部函数被包含在这个迭代环里求解器在每一次迭代试探中都必须调用它。官方文档中有一个典型示例when sample(0,0.1)触发了 10 次方程求解但由于方程存在代数环和非线性迭代外部函数实际被调用了43 次。有代数环的版本调用次数不可控model AlgebraicLoopBad function ExtLib_StepRun input Real u; output Real y; external C y ext_step_run(u); end ExtLib_StepRun; Real x, y; when sample(0, 0.1) then (x, y) ExtLib_StepRun(x); // x 既是输入又是输出形成代数环 end when; end AlgebraicLoopBad;用pre(x)打破代数环的版本【推荐写法】model AlgebraicLoopFixed function ExtLib_StepRun input Real u; output Real y; external C y ext_step_run(u); end ExtLib_StepRun; Real x, y; when sample(0, 0.1) then (x, y) ExtLib_StepRun(pre(x)); // pre(x) 使用上一时刻已知值消除代数环 end when; end AlgebraicLoopFixed;pre(x)取上一时刻的已知值使得ExtLib_StepRun的输入不再依赖当前时刻的输出代数环被打破方程退化为显式计算每次事件触发只调用一次外部函数。原则外部函数尽量不要放进非线性方程块对调用次数敏感、带副作用的外部函数应使用whensample配合显式状态保存。4.6 调用顺序控制不能依赖书写顺序如果两个外部函数的调用顺序必须固定不能依赖方程书写顺序。方案优先级首选放入algorithm算法段段内语句严格按书写顺序执行次选构造业务天然的数据依赖后执行函数输入使用前一个函数的输出推荐标准写法algorithm 段algorithm y : getreal_arg(x); z : getreal_arg(y);五、维度四构建与链接——代码如何被装配进仿真5.1 编译器一致性外部库必须使用与 Sysplorer相同版本、相同位数32/64 位的编译器进行编译。位数不兼容是无法解析的外部符号等错误的常见原因。32 位 MWorks 不能调用 64 位 DLL反之亦然分平台库放在win32、win64子目录。5.2 链接配置通过Library和LibraryDirectory注解告知 Sysplorer 库文件的位置。对于动态库还需要确保运行时.dll/.so文件在系统路径或模型目录下可被找到。Linux 库静态库libtest.a、动态库libtest.so注解内库名填写test去掉前缀后缀。5.3 依赖管理如果外部函数依赖于其他动态库需要确保这些依赖库也位于可被加载的路径中可以使用depends等工具检查依赖关系。DLL 导出检查使用depends工具确认目标函数已导出无 lib 时编写.def文件导出符号。DLL 依赖链依赖的子 DLL 需要和主 DLL 放在同一搜索目录。5.4 路径规范统一使用 Modelica URI loadResource打包 FMU 时所有资源使用相对 modelica 路径。六、维度五调试与故障排查由于外部函数运行在 Sysplorer 内部调试相对复杂但有一些成熟的排查路径。6.1 日志与打印最直接的方式是在 C 代码中向文件或控制台打印关键信息以观察函数的运行状态和中间变量。注意print打印调试会引入额外事件点改变求解行为正式版本全部删除调试打印。6.2 单步调试可以使用Visual Studio等工具搭建调试环境将调试器附加到 Sysplorer 的求解器进程上对 C 代码进行单步调试这是定位复杂逻辑错误的有效手段。6.3 常见错误模式空指针、野指针、数组越界是导致仿真崩溃的常见原因。此外无效的外部函数接口注解通常意味着路径配置有误可使用外部函数编辑器重新设置。6.4 故障排查速查表现象根因修复方案外部函数调用次数远大于 sample 采样次数when内部存在代数环事件迭代反复求值pre()提取上一时刻状态打断代数环相同输入C 函数返回值不稳定代码使用全局/静态变量多实例互相污染状态迁移至ExternalObject上下文初始化阶段 DLL 加载崩溃位数不匹配、依赖 DLL 缺失、导出符号不存在统一 x64/x32、检查依赖、用depends校验导出Record 传入 C struct 后字段值错乱C 结构体内存对齐和 Modelica 记录布局不一致手动强制对齐、避免复合记录嵌套FMU 打包后找不到 dll/头文件使用绝对路径未使用loadResource全部改为modelica://URI通过loadResource转路径仿真结束内存泄漏、文件句柄不释放没有调用destructor/terminal释放逻辑检查ExternalObject析构、terminal钩子是否正常触发6.5 集成测试流程C 侧独立调用 DLL 验证接口 → Modelica 封装 → 同输入对比 C 侧结果 → 接入系统模型关注步长、初值、求解器类型。七、维度六高级特性与边界7.1 性能考量引入外部函数的一个重要动机就是提升性能例如调用高度优化的数值计算库来完成 Modelica 难以快速求解的任务。7.2 ExternalObject跨调用状态的容器【Modelica 标准优先推荐】普通外部函数默认是**无记忆纯函数**——规范假定相同输入产生相同输出。但很多时候你需要跨调用保留数据比如只在仿真开始时从文件读入一张大表后续插值时反复使用它。ExternalObject就是用来合法地保存这种跨调用内存的标准机制。constructor构造函数在对象第一次被使用之前由系统自动调用且仅调用一次。职责是初始化分配内存、打开文件、加载数据表返回void*给 Modelica 环境保存。destructor析构函数在对象最后一次被使用之后由系统自动调用且仅调用一次。职责是清理释放内存、关闭文件。关键规则你永远不能在代码里手动调用它们。它们的执行时机完全由求解器根据对象的生命周期自动决定。可以类比为constructor 是打开文件destructor 是关闭文件你写的插值函数是读文件——你只负责中间读写打开和关闭的时机由系统管理。C 侧实现table.c#includestdlib.h#includestdio.htypedefstruct{intn;double*x;double*y;}Table;void*table_constructor(constchar*filename){Table*t(Table*)malloc(sizeof(Table));FILE*ffopen(filename,r);if(!f)returnNULL;t-n0;t-x(double*)malloc(1000*sizeof(double));t-y(double*)malloc(1000*sizeof(double));while(fscanf(f,%lf,%lf,t-x[t-n],t-y[t-n])2){t-n;}fclose(f);return(void*)t;}doubletable_interp(void*obj,doublexq){Table*t(Table*)obj;for(inti0;it-n-1;i){if(xqt-x[i]xqt-x[i1]){doubleratio(xq-t-x[i])/(t-x[i1]-t-x[i]);returnt-y[i]ratio*(t-y[i1]-t-y[i]);}}returnt-y[t-n-1];}voidtable_destructor(void*obj){Table*t(Table*)obj;free(t-x);free(t-y);free(t);}Modelica 侧封装model TableLookup class TableObject extends ExternalObject; function constructor input String filename; output TableObject table; external C table table_constructor(filename) annotation(Includetable.c); end constructor; function destructor input TableObject table; external C table_destructor(table) annotation(Includetable.c); end destructor; end TableObject; function interp input TableObject table; input Real xq; output Real yq; external C yq table_interp(table, xq) annotation(Includetable.c); end interp; TableObject myTable TableObject( Modelica.Utilities.Files.loadResource(modelica://MyLib/Resources/Data/table.csv)); Real xq time; Real yq interp(myTable, xq); end TableLookup;在这个例子中table_constructor只在myTable第一次被使用时调用一次读入整个 CSVinterp在仿真过程中可能被调用成百上千次但每次都只是内存插值不再读文件table_destructor在仿真结束时自动调用释放内存。when控制何时调用ExternalObject管理调用之间留下的状态二者配合兼顾时序精确性与性能。7.3 DLL 生命周期管理Initialize / DoStep / Terminate 模式【兼容遗留 DLL 的备选方案】对于需要封装遗留 DLL 的场景可以采用生命周期钩子模式model DLLWrapper function UserDLL_Initialize input String dllPath; output Integer handle; external C handle user_dll_initialize(dllPath) annotation(Includedll_wrapper.c); end UserDLL_Initialize; function UserDLL_DoStep input Integer handle; input Real a, b; output Real c; external C c user_dll_do_step(handle, a, b) annotation(Includedll_wrapper.c); end UserDLL_DoStep; function UserDLL_Terminate input Integer handle; external C user_dll_terminate(handle) annotation(Includedll_wrapper.c); end UserDLL_Terminate; Integer handle; Real a sin(time), b cos(time), c; when initial() then handle UserDLL_Initialize( Modelica.Utilities.Files.loadResource(modelica://MyLib/Resources/Library/mydll.dll)); end when; when sample(0, 0.01) then c UserDLL_DoStep(handle, a, b); end when; when terminal() then UserDLL_Terminate(handle); end when; end DLLWrapper;机制要点Initialize在when initial()中调用一次负责LoadLibrary、GetProcAddress、申请内存DoStep在when sample(0, stepSize)中按周期调用使用已保存的句柄不要每次 DoStep 都 LoadLibraryTerminate在when terminal()中调用一次负责FreeLibrary和free。7.4 局限性目前 Sysplorer 主要支持 C 和 FORTRAN 77C 需通过extern C封装。对于其他语言如 Python、JuliaMWORKS 平台提供了更广泛的接口支持但这超出了经典外部函数机制的范畴属于更高层次的联合仿真或模块集成。7.5 全局/静态变量严禁滥用C、DLL 内部静态变量会在多实例模型中互相干扰多实例场景全部迁移状态至ExternalObject上下文。7.6 实时仿真补充强实时场景必须搭配固定步长求解器变步长求解器事件点不固定不适合硬件 IO、周期控制类副作用逻辑。八、注意事项调用次数不可假定普通方程中可能因非线性迭代多次调用when仅产生事件点事件内部仍可迭代重复调用if满足条件时所有求值时刻调用调用次数和仿真步无必然绑定。调用顺序不可依赖书写顺序优先algorithm段、业务数据依赖冗余参数造假依赖属于临时手段。避免非线性代数环外部函数落入代数环会造成调用次数爆炸带副作用逻辑必须用pre()打破环。资源生命周期DLL 加载、文件打开、内存申请放constructor/when initial()释放放destructor/when terminal()禁止在 DoStep 里重复 LoadLibrary。类型映射严格匹配布尔优先用ModelicaBoolean记录警惕struct对齐字符串输出使用官方分配接口。位数匹配32 位 MWorks 不能调用 64 位 DLL反之亦然分平台库放在win32、win64子目录。DLL 导出检查使用depends工具确认目标函数已导出无 lib 时编写.def文件导出符号。DLL 依赖链依赖的子 DLL 需要和主 DLL 放在同一搜索目录。路径规范统一使用 Modelica URI loadResource打包 FMU 时所有资源使用相对 modelica 路径。全局/静态变量严禁滥用C、DLL 内部静态变量会在多实例模型中互相干扰多实例场景全部迁移状态至ExternalObject上下文。Linux 库静态库libtest.a、动态库libtest.so注解内库名填写test去掉前缀后缀。C 封装MWorks 不支持直接调用 C 成员函数必须使用extern C封装 wrapper。FORTRANSUBROUTINE全部参数传指针包含输入参数。调试约束print打印调试会引入额外事件点改变求解行为正式版本全部删除调试打印。集成测试流程C 侧独立调用 DLL 验证接口 → Modelica 封装 → 同输入对比 C 侧结果 → 接入系统模型关注步长、初值、求解器类型。实时仿真补充强实时场景必须搭配固定步长求解器变步长求解器事件点不固定不适合硬件 IO、周期控制类副作用逻辑。九、总结Sysplorer/MWorks 的外部函数调用机制本质是一个在 Modelica 的声明式世界与 C/Fortran 的过程式世界之间建立映射和通信的桥梁。理解它需要双重视角宏观上用声明契约、数据映射、构建配置、运行时生命周期、调试排错、高级边界六个维度建立工程认知地图微观上牢牢记住求解器按需调用这一真相——普通方程中可能被迭代多次when/sample仅产生事件点事件点内部仍可能迭代if条件成立时在所有连续求值时刻调用。理解这套机制的关键是把思维从“我按顺序调用函数”切换到“我声明函数求解器按需调用它”。一旦接受这个前提when与if的区别、pre()打破代数环、constructor/destructor的生命周期管理、六维度框架中的每一个环节都会变得顺理成章——它们都是在回答同一个问题如何在一个由求解器驱动的黑箱调用模型里可靠地控制一个外部函数的执行并正确地完成数据与资源的过桥。