1. 为什么需要 Model Reference 模块1.1 模型复用与协同建模的痛点在 Simulink 中做复杂系统建模时很多工程师一开始都是把所有功能堆在同一个模型里。需求简单的时候问题不大但随着模型变大比如同时包含电机控制、电池管理、车辆动力学、热管理等多个子系统麻烦就会一个接一个地出现。首先是多人协同的问题。同一个模型文件里两个人同时修改就会出现版本冲突经常是 A 刚改完总线信号定义B 又覆盖了一版辛苦改好的接口对不上。其次是复用问题。项目 A 已经验证过的控制算法项目 B 想直接用传统做法是复制一个同样的子系统过来。可一旦算法更新所有复制过的模型都要手动同步漏掉一个就可能导致多个项目行为不一致。更麻烦的是代码生成模型庞大之后每次生成代码都要全量编译一个小参数改动往往要等很久。这时候就需要 Model Reference模型引用模块来解决这些问题。它让模型能够在文件级别被独立管理、独立复用、独立构建是 Simulink 在中大型工程和团队开发中的核心手段。1.2 Model Reference 模块是什么Model Reference 是 SimulinkPorts Subsystems端口与子系统模块库中的一个重要模块。它提供一种“模型级复用”的能力在父模型Parent Model中放置一个 Model 模块通过该模块引用另一个独立的.slx或.mdl模型文件。被引用的模型称为被引用模型Referenced Model。父模型并不会把被引用模型的内部实现复制过来而是建立一种引用关系。仿真或代码生成时Simulink 会直接加载被引用模型的计算逻辑外部只能看到这个模型暴露出来的输入输出端口看不到内部结构也无法直接访问内部信号。这种机制带来的直接好处有三个一是模型文件独立版本管理更清晰二是多个模型可以并行开发互不阻塞三是构建和代码生成可以增量进行被引用模型没有变化时不需要重新编译。1.3 与 Subsystem、Library 的核心区别很多初学者第一次看到 Model Reference 时会自然地想到 Subsystem子系统和 Library库模块。它们确实都解决“复用”问题但使用场景差异很大。对比项Subsystem 子系统Library 库模块Model Reference 模型引用是否有独立文件否保存在父模型中是库文件独立是被引用模型文件独立工作区变量继承父模型工作区由库链接决定独立的模型工作区 / 数据字典内部信号可见性可通过 Goto/From 或输出端口访问按链接方式同步只能通过 Inport/Outport 暴露版本管理随父模型一起库文件独立管理每个被引用模型可独立管理代码生成内联到父模型代码中按链接逻辑展开可生成模型级独立代码支持增量构建多人并行开发同一个文件编辑易冲突库维护者与使用者分工多个模型并行开发互不阻塞复用粒度子系统级模块级模型级适合大算法单元从表格可以看出Subsystem 适合在一个模型内部做结构化拆分Library 适合共享通用模块而 Model Reference 更适合被多个项目或者多个团队复用的完整算法单元。实际项目中三者经常组合使用并不互斥。2. Model Reference 的工作机制2.1 被引用模型与父模型的关系在 Model Reference 架构中模型之间的关系是“父子”关系父模型通过 Model 模块引用被引用模型。被引用模型通过 Inport输入端口和 Outport输出端口定义对外接口父模型通过连线与这些端口交换信号。由于被引用模型是独立文件父模型不能直接使用 Goto/From 标签来访问被引用模型内部的信号。如果确实需要监视中间变量有几种方案把需要的信号引出为调试输出端口、使用信号记录Signal Logging、或者在调试阶段临时打开被引用模型观察。这种边界限制其实是一种保护机制它强制建模者把接口设计清楚不会因为内部改动破坏外部连接。另外被引用模型的参数可以存放在模型工作区Model Workspace或数据字典Data Dictionary中父模型默认无法直接访问这些内部参数。如果需要在父模型侧配置被引用模型的某些参数可以使用 Model 模块的Parameters选项卡进行参数映射或者通过Simulink.Parameter对象配合数据字典实现共享。2.2 仿真模式Normal、Accelerator、Rapid AcceleratorModel Reference 支持多种仿真模式这也是它与普通子系统差异较大的地方。在 Model 模块参数对话框中Simulation mode选项可以设置为Normal正常模式被引用模型以较常规的方式参与仿真便于调试可以进入被引用模型内部查看信号。首次仿真时Simulink 仍会在工作目录的slprj文件夹中生成仿真目标缓存用来描述被引用模型的接口和依赖关系。Normal 模式对模型本身的改动不敏感适合开发调试阶段。Accelerator加速模式被引用模型会被编译生成 C 代码仿真运行时直接执行编译后的代码速度明显提升。这种模式适合仿真逻辑基本稳定、需要反复执行验证的场景。Rapid Accelerator快速加速模式整个父模型以外部模式或快速加速方式运行被引用模型可以复用目标代码。多个实例共用同一个被引用模型时这种模式的构建优势最明显特别适合参数扫描、批量仿真和硬件在环HIL准备。选择仿真模式的核心思路是开发初期用 Normal 方便调试仿真验证阶段用 Accelerator 或 Rapid Accelerator 提升效率。需要注意的是切换到 Accelerator 模式通常需要编译器环境正常否则会出现仿真目标构建失败的问题。2.3 信号边界与数据字典Model Reference 的另一个关键点是“边界”。被引用模型的输入端口必须和父模型连接信号的数据类型、维度、采样时间完全匹配。如果被引用模型内部使用int16数据类型父模型连接的是doubleSimulink 会报错或自动做类型转换具体取决于信号转换配置。数据字典方面被引用模型可以关联自己的.sldd数据字典文件例如定义参数对象、信号对象、总线对象等。如果在仿真时出现“找不到数据字典 xxx.sldd”的错误多半是字典文件路径失效或该模型不再关联这个字典这个坑在团队协作中非常常见。后面第 5 章我们会专门讲排查方法。3. 创建 Model Reference 的完整实操下面通过一个具体案例演示如何从零搭建一个 Model Reference 模型。例子采用一个比例控制器P 控制器作为被引用模型父模型模拟一个简单速度控制场景。3.1 创建被引用模型先创建一个独立的 Simulink 模型文件命名为speed_controller.slx。该模型包含两个输入端口目标速度ref_speed、当前速度cur_speed一个输出端口控制量control_u内部用求差模块计算误差再用增益模块kp放大误差作为控制量。在 Simulink 编辑器中操作步骤如下新建模型保存为speed_controller.slx。从Ports Subsystems模块库中拖入两个 Inport 和一个 Outport。从Math Operations模块库中拖入一个 Sum 模块。从Math Operations模块库中拖入一个 Gain 模块。修改端口名称例如ref_speed、cur_speed、control_u。双击 Sum 模块把符号设置为-表示第一个输入减去第二个输入。双击 Gain 模块设置 Gain 值为2.5。连接信号ref_speed连到 Sum 的第一个输入cur_speed连到 Sum 的第二个输入Sum 输出连到 GainGain 输出连到control_u。保存模型。如果你习惯用命令行创建可以参考下面这段 MATLAB 脚本思路完全一致% 创建被引用模型 speed_controller.slx new_system(speed_controller); open_system(speed_controller); % 添加输入输出端口 add_block(built-in/Inport, speed_controller/ref_speed); add_block(built-in/Inport, speed_controller/cur_speed); add_block(built-in/Sum, speed_controller/error); add_block(built-in/Gain, speed_controller/kp); add_block(built-in/Outport, speed_controller/control_u); % 配置端口和增益 set_param(speed_controller/error, Inputs, -); set_param(speed_controller/kp, Gain, 2.5); % 连线 add_line(speed_controller, ref_speed/1, error/1); add_line(speed_controller, cur_speed/1, error/2); add_line(speed_controller, error/1, kp/1); add_line(speed_controller, kp/1, control_u/1); % 保存 save_system(speed_controller);注意add_block中使用的built-in/Inport、built-in/Sum等是 Simulink 内部模块路径不同语言版本下显示名称可能不同但代码中的内部标识一般保持一致。如果命令行报错优先在图形界面中手动添加即可。3.2 在父模型中添加 Model 模块接下来创建父模型vehicle_level.slx用来引用刚刚创建的speed_controller模型。操作步骤如下新建模型保存为vehicle_level.slx。打开 Simulink Library Browser库浏览器在Ports Subsystems中搜索Model模块。把Model模块拖入父模型画布。双击 Model 模块在Model name一栏填写speed_controller点击确定。此时 Model 模块会自动显示speed_controller的输入输出端口分别是ref_speed、cur_speed和control_u。在父模型中添加两个 Inport 和一个 Outport分别连接到 Model 模块对应的端口上。保存父模型。命令行方式也可以实现% 创建父模型并添加 Model 模块 new_system(vehicle_level); open_system(vehicle_level); add_block(built-in/Inport, vehicle_level/ref_speed); add_block(built-in/Inport, vehicle_level/cur_speed); add_block(built-in/Outport, vehicle_level/control_u); % 添加 Model 模块并指定被引用模型 add_block(simulink/Ports Subsystems/Model, vehicle_level/speed_controller_ref); set_param(vehicle_level/speed_controller_ref, ModelName, speed_controller); % 连线 add_line(vehicle_level, ref_speed/1, speed_controller_ref/1); add_line(vehicle_level, cur_speed/1, speed_controller_ref/2); add_line(vehicle_level, speed_controller_ref/1, control_u/1); save_system(vehicle_level);3.3 设置被引用模型的仿真参数如果你希望被引用模型以加速模式运行可以在父模型中双击 Model 模块在Simulation mode下拉框中选择Accelerator或Rapid Accelerator。此外在父模型的Model Configuration Parameters中有一个Model Referencing配置页建议按下面的思路设置Rebuild options重建选项建议保持默认的If structure or underlying content has changed。这会保证被引用模型内容变化后自动重建仿真目标内容没变则直接复用兼顾正确性和效率。Enable parallel builds启用并行构建如果电脑是多核处理器且项目中存在多个被引用模型可以勾选减少总构建时间。Number of workers并行工作进程根据需要调整不要设置过大避免内存占用过高。配置完成后点击父模型工具栏的Run按钮进行仿真。首次仿真会因为需要构建被引用模型的仿真目标而稍慢后续没有变化时就会直接使用缓存结果速度显著提升。3.4 将已有 Subsystem 转换为 Model Reference如果你已经写好了子系统想把它转成 Model Reference可以使用 Simulink 提供的转换功能。在比新版本的 MATLAB 中选中 Subsystem 模块后可以右键选择Refactor Model或Convert Subsystem to Model Reference之后填写生成的新模型名称Simulink 会自动完成转换。不同 MATLAB 版本的菜单位置有所差异如果找不到这个选项可以检查当前模型是否处于“非保护”状态以及版本是否支持该功能。转换完成后原来 Subsystem 内部的 Inport/Outport 会自动对齐外部连线保持不变体验比较顺畅。但要注意如果 Subsystem 内部使用了 Goto/From 跨越父模型共享信号转换可能会报错需要先调整信号接口。4. Model Reference 常用配置与参数详解4.1 Model 模块参数对话框双击 Model 模块后可以看到几个关键选项卡Model name模型名称指定被引用模型的文件名。点击右侧的浏览按钮可以选择当前路径或 MATLAB 路径下的模型。Parameters参数用于把父模型工作区中的变量映射给被引用模型的参数。如果被引用模型定义了Simulink.Parameter对象或使用了模型工作区变量可以在这里建立映射关系。Ports端口显示当前被引用模型暴露出的输入输出端口及顺序可以快速了解接口匹配情况。Metadata元数据显示被引用模型的版本、路径等信息适合排查版本不一致问题。4.2 采样时间与代数环被引用模型的端口采样时间必须是显式的要么在端口上直接指定采样时间要么允许 Simulink 根据模型内部逻辑自动推断。如果父模型信号采样时间与被引用模型不一致Simulink 会通过“有效采样时间传播”机制进行匹配但有时候会报采样时间不一致的错误。推荐的做法是在 Inport 模块的Sample Time参数中明确设置采样时间比如0.01避免歧义。代数环Algebraic Loop在 Model Reference 中也很常见。如果被引用模型输入到输出之间存在直通路径而父模型又把输出反馈回输入就容易形成代数环。排查时可以在诊断信息中定位到代数环所在的模块路径尝试在环中增加 Unit Delay、Memory 模块或者调整代数环求解器选项。4.3 代码生成中的模型引用如果最终目标是生成 C 代码Model Reference 的价值更加明显。在配置参数中把System target file设置为ert.tlcEmbedded Coder然后启用代码生成。被引用模型会生成独立的 C 函数例如speed_controller_step()和speed_controller_initialize()。如果父模型中同一个被引用模型被使用了多次还可以在代码生成选项中启用Model reference reuse让多个实例共用同一份代码函数只是传进去的实例参数不同这样能明显减小生成代码的体积也更适合嵌入式场景。需要说明的是代码生成的详细配置与目标编译器、硬件平台强相关实际工程中不建议直接套用他人配置应该按照项目的 Target 配置文档来设置。4.4 子模型与模型工作区被引用模型内部可以使用模型工作区Model Workspace存放参数例如 PID 增益、滤波器系数等。模型工作区中的变量可以定义成Simulink.Parameter对象并设置存储类Storage Class这样在代码生成时可以直接映射到全局变量或宏定义。父模型默认看不到模型工作区的内容。如果你觉得这个限制太严格可以把需要共享的参数集中放到一个数据字典中父模型和被引用模型都关联同一个字典文件这样两边就都能访问同一组参数对象既保持接口清晰又兼顾参数共享。5. 常见错误与排查思路Model Reference 虽然好用但在实际项目中遇到的问题也不少。下面整理了几类高频问题并给出排查顺序。问题现象常见原因解决思路仿真报错找不到数据字典xxx.sldd字典文件路径失效、文件被移动或删除确认字典文件位置重新关联数据字典或刷新 MATLAB 路径仿真目标构建失败缺少编译器、模型配置不合法、路径包含中文或空格检查编译器配置用mex -setup设置清理slprj缓存端口数据类型不匹配Inport/Outport 的数据类型与父模型信号不一致打开端口属性检查数据类型、维度、总线对象采样时间不一致被引用模型内部采样时间与父模型不兼容为 Inport/Outport 显式设置采样时间Model 模块显示为灰色或不可用被引用模型被锁定、版本过大或保护模型检查被引用模型是否只读确认模型版本兼容性转换子系统为 Model Reference 时报错子系统内部使用了跨层 Goto/From 或某些不支持的模式先清理信号跨层共享把需要的外部信号改为 Inport/Outport5.1 找不到数据字典这是团队协作中最常见的错误之一尤其是在使用 Git 或 SVN 管理模型文件时。某个被引用模型本来关联了can.sldd但同事拿到代码后字典文件没有同步到本地或者路径变了Simulink 打开模型时就报“找不到数据字典”的错误。排查步骤建议如下检查报错信息中提到的字典文件在本地是否存在。如果存在确认当前模型关联的字典路径是否正确。可以在模型属性Model Properties中的Data Dictionary栏查看。如果路径错误使用Simulink.DataDictionary.open(xxx.sldd)手动打开字典然后重新关联。如果字典文件缺失需要从版本库同步或者与创建字典的同事确认文件位置。更好的做法是把数据字典文件放在与模型同级的固定目录中并使用相对路径引用避免不同电脑上绝对路径不一致。5.2 仿真目标构建失败仿真目标Simulation Target构建失败的表现是点击 Run 后进度条在“Building Simulation Target”阶段卡住或弹出红色错误。常见原因有三个本机没有安装可用的 C 编译器。运行mex -setup查看当前编译器情况如果提示找不到编译器需要安装 MinGW-w64 或 Visual Studio Build Tools。MATLAB 路径中包含中文、空格或特殊字符导致编译临时文件路径异常。建议把整个工作目录调整到纯英文路径。之前构建产生的slprj缓存损坏。可以删除当前工程目录下的slprj文件夹重新仿真让 Simulink 重新生成缓存。5.3 端口类型与维度不匹配Model Reference 对接口匹配要求比较严格。被引用模型的 Inport 如果设置成double类型、1x1维度父模型连接了一个int16类型或4x1维度的信号仿真时就会报错。解决办法是在父模型中使用 Signal Conversion 模块、Data Type Conversion 模块进行显式转换。更推荐的做法是在项目早期就统一信号类型规范例如所有物理量使用double枚举量使用Simulink.Bus总线对象这样接口匹配问题会大幅减少。6. Model Reference 工程最佳实践6.1 为每个被引用模型建立独立数据字典在复杂项目中建议每个被引用模型都关联一个独立的数据字典而不是把所有参数都放到父模型工作区。这样做的好处是模型自包含、可移植、方便团队并行修改。例如speed_controller.slx对应speed_controller.sldd里面定义控制器的全部参数和信号对象。需要注意的是数据字典的引入也带来了文件同步的工作量。使用版本控制时.sldd文件必须和.slx文件一并提交否则同事拉取代码后会遇到数据字典缺失的报错。6.2 接口设计要稳定Model Reference 的接口一旦确定后续修改成本会比较高。所以在设计被引用模型时要格外重视输入输出接口输入输出端口数量尽量精简只暴露必须的信号。端口顺序固定且建议在端口名称中体现物理含义。优先使用Simulink.Bus定义总线信号减少端口数量。数据类型、采样时间要在建模初期明确避免后期大量转换。一个稳定接口的核心是“变化尽量发生在内部接口保持长期稳定”。这样其他团队在集成时不会被频繁变更打断。6.3 合理利用增量构建Model Reference 的增量构建能力是替代 Subsystem 的重要理由。使用时要注意不要频繁修改被引用模型的结构增删端口、改变内部模块连接因为结构变化会导致更多模型需要重新构建。只修改参数值时可以优先通过 Model 模块的 Parameters 映射传入而不是直接修改被引用模型内部。在 CI 自动构建脚本中可以设置 Rebuild 选项为按需构建以节省时间。6.4 代码生成阶段注意事项在嵌入式代码生成项目中Model Reference 通常配合 Embedded Coder 使用。一些工程建议包括为每个被引用模型配置独立的代码生成目录便于排查生成的.c、.h文件。在代码生成前执行模型检查使用 Model Advisor 检查模型规范和代码生成兼容性。如果被引用模型被复用多次务必确认代码生成选项中的实例复用配置避免生成重复函数。常见的一种做法是父模型只负责系统集成和调用关系真正的算法全部放在被引用模型中生成独立函数。这样维护算法时只需要重新生成被引用模型的代码不会影响整个系统的代码结构。6.5 团队协作与版本管理多人建模时建议遵循以下协作规则每位工程师负责一个或多个被引用模型不要在同一个模型文件上频繁合并修改。父模型统一保存到独立的目录例如models/integration/被引用模型保存在models/components/。提交代码时同时提交.slx、.sldd、slprj的忽略规则避免缓存文件进入版本库。在合并分支时优先使用 MATLAB 自带的模型比较和合并工具Simulink Model Comparison不要直接手动编辑 XML 内容。如果公司已经使用 Git可以在 Git LFS 中管理模型文件减少大文件冲突的概率。另外每次修改模型前最好用模型差异工具确认改动范围降低无意识改动带来的风险。7. 总结与下一步学习建议到这里关于 Model Reference 模块的核心内容就梳理完了。我们从模块库中的位置出发对比了它与 Subsystem、Library 的区别讲了它的工作机制并通过一个速度控制器的例子完整演示了创建被引用模型、在父模型中引用、配置仿真模式和代码生成的过程。也整理了数据字典缺失、仿真目标构建失败、端口类型不匹配等高频问题的排查方案。如果你正在从单体大模型向模型架构拆分转型建议先挑一个边界清晰的算法单元比如 PID 控制器、滤波器或状态观测器把它转换为 Model Reference先在一个模型内跑通再逐步扩展到多模型协作。过程中注意观察slprj目录的构建日志和仿真速度变化这些都是理解 Model Reference 底层行为的好素材。接下来可以继续学习的方向包括Simulink 数据字典的深入应用、Rapid Accelerator 模式下的参数批量扫描、Embedded Coder 的代码生成配置、以及如何用 Simulink Test 对 Model Reference 做单元测试和覆盖率分析。理解这些内容后再把 Model Reference 用于实际项目你会明显感受到它在团队协同和工程交付上的价值。 Simulink Model Reference模块详解：模型复用与协同建模
1. 为什么需要 Model Reference 模块1.1 模型复用与协同建模的痛点在 Simulink 中做复杂系统建模时很多工程师一开始都是把所有功能堆在同一个模型里。需求简单的时候问题不大但随着模型变大比如同时包含电机控制、电池管理、车辆动力学、热管理等多个子系统麻烦就会一个接一个地出现。首先是多人协同的问题。同一个模型文件里两个人同时修改就会出现版本冲突经常是 A 刚改完总线信号定义B 又覆盖了一版辛苦改好的接口对不上。其次是复用问题。项目 A 已经验证过的控制算法项目 B 想直接用传统做法是复制一个同样的子系统过来。可一旦算法更新所有复制过的模型都要手动同步漏掉一个就可能导致多个项目行为不一致。更麻烦的是代码生成模型庞大之后每次生成代码都要全量编译一个小参数改动往往要等很久。这时候就需要 Model Reference模型引用模块来解决这些问题。它让模型能够在文件级别被独立管理、独立复用、独立构建是 Simulink 在中大型工程和团队开发中的核心手段。1.2 Model Reference 模块是什么Model Reference 是 SimulinkPorts Subsystems端口与子系统模块库中的一个重要模块。它提供一种“模型级复用”的能力在父模型Parent Model中放置一个 Model 模块通过该模块引用另一个独立的.slx或.mdl模型文件。被引用的模型称为被引用模型Referenced Model。父模型并不会把被引用模型的内部实现复制过来而是建立一种引用关系。仿真或代码生成时Simulink 会直接加载被引用模型的计算逻辑外部只能看到这个模型暴露出来的输入输出端口看不到内部结构也无法直接访问内部信号。这种机制带来的直接好处有三个一是模型文件独立版本管理更清晰二是多个模型可以并行开发互不阻塞三是构建和代码生成可以增量进行被引用模型没有变化时不需要重新编译。1.3 与 Subsystem、Library 的核心区别很多初学者第一次看到 Model Reference 时会自然地想到 Subsystem子系统和 Library库模块。它们确实都解决“复用”问题但使用场景差异很大。对比项Subsystem 子系统Library 库模块Model Reference 模型引用是否有独立文件否保存在父模型中是库文件独立是被引用模型文件独立工作区变量继承父模型工作区由库链接决定独立的模型工作区 / 数据字典内部信号可见性可通过 Goto/From 或输出端口访问按链接方式同步只能通过 Inport/Outport 暴露版本管理随父模型一起库文件独立管理每个被引用模型可独立管理代码生成内联到父模型代码中按链接逻辑展开可生成模型级独立代码支持增量构建多人并行开发同一个文件编辑易冲突库维护者与使用者分工多个模型并行开发互不阻塞复用粒度子系统级模块级模型级适合大算法单元从表格可以看出Subsystem 适合在一个模型内部做结构化拆分Library 适合共享通用模块而 Model Reference 更适合被多个项目或者多个团队复用的完整算法单元。实际项目中三者经常组合使用并不互斥。2. Model Reference 的工作机制2.1 被引用模型与父模型的关系在 Model Reference 架构中模型之间的关系是“父子”关系父模型通过 Model 模块引用被引用模型。被引用模型通过 Inport输入端口和 Outport输出端口定义对外接口父模型通过连线与这些端口交换信号。由于被引用模型是独立文件父模型不能直接使用 Goto/From 标签来访问被引用模型内部的信号。如果确实需要监视中间变量有几种方案把需要的信号引出为调试输出端口、使用信号记录Signal Logging、或者在调试阶段临时打开被引用模型观察。这种边界限制其实是一种保护机制它强制建模者把接口设计清楚不会因为内部改动破坏外部连接。另外被引用模型的参数可以存放在模型工作区Model Workspace或数据字典Data Dictionary中父模型默认无法直接访问这些内部参数。如果需要在父模型侧配置被引用模型的某些参数可以使用 Model 模块的Parameters选项卡进行参数映射或者通过Simulink.Parameter对象配合数据字典实现共享。2.2 仿真模式Normal、Accelerator、Rapid AcceleratorModel Reference 支持多种仿真模式这也是它与普通子系统差异较大的地方。在 Model 模块参数对话框中Simulation mode选项可以设置为Normal正常模式被引用模型以较常规的方式参与仿真便于调试可以进入被引用模型内部查看信号。首次仿真时Simulink 仍会在工作目录的slprj文件夹中生成仿真目标缓存用来描述被引用模型的接口和依赖关系。Normal 模式对模型本身的改动不敏感适合开发调试阶段。Accelerator加速模式被引用模型会被编译生成 C 代码仿真运行时直接执行编译后的代码速度明显提升。这种模式适合仿真逻辑基本稳定、需要反复执行验证的场景。Rapid Accelerator快速加速模式整个父模型以外部模式或快速加速方式运行被引用模型可以复用目标代码。多个实例共用同一个被引用模型时这种模式的构建优势最明显特别适合参数扫描、批量仿真和硬件在环HIL准备。选择仿真模式的核心思路是开发初期用 Normal 方便调试仿真验证阶段用 Accelerator 或 Rapid Accelerator 提升效率。需要注意的是切换到 Accelerator 模式通常需要编译器环境正常否则会出现仿真目标构建失败的问题。2.3 信号边界与数据字典Model Reference 的另一个关键点是“边界”。被引用模型的输入端口必须和父模型连接信号的数据类型、维度、采样时间完全匹配。如果被引用模型内部使用int16数据类型父模型连接的是doubleSimulink 会报错或自动做类型转换具体取决于信号转换配置。数据字典方面被引用模型可以关联自己的.sldd数据字典文件例如定义参数对象、信号对象、总线对象等。如果在仿真时出现“找不到数据字典 xxx.sldd”的错误多半是字典文件路径失效或该模型不再关联这个字典这个坑在团队协作中非常常见。后面第 5 章我们会专门讲排查方法。3. 创建 Model Reference 的完整实操下面通过一个具体案例演示如何从零搭建一个 Model Reference 模型。例子采用一个比例控制器P 控制器作为被引用模型父模型模拟一个简单速度控制场景。3.1 创建被引用模型先创建一个独立的 Simulink 模型文件命名为speed_controller.slx。该模型包含两个输入端口目标速度ref_speed、当前速度cur_speed一个输出端口控制量control_u内部用求差模块计算误差再用增益模块kp放大误差作为控制量。在 Simulink 编辑器中操作步骤如下新建模型保存为speed_controller.slx。从Ports Subsystems模块库中拖入两个 Inport 和一个 Outport。从Math Operations模块库中拖入一个 Sum 模块。从Math Operations模块库中拖入一个 Gain 模块。修改端口名称例如ref_speed、cur_speed、control_u。双击 Sum 模块把符号设置为-表示第一个输入减去第二个输入。双击 Gain 模块设置 Gain 值为2.5。连接信号ref_speed连到 Sum 的第一个输入cur_speed连到 Sum 的第二个输入Sum 输出连到 GainGain 输出连到control_u。保存模型。如果你习惯用命令行创建可以参考下面这段 MATLAB 脚本思路完全一致% 创建被引用模型 speed_controller.slx new_system(speed_controller); open_system(speed_controller); % 添加输入输出端口 add_block(built-in/Inport, speed_controller/ref_speed); add_block(built-in/Inport, speed_controller/cur_speed); add_block(built-in/Sum, speed_controller/error); add_block(built-in/Gain, speed_controller/kp); add_block(built-in/Outport, speed_controller/control_u); % 配置端口和增益 set_param(speed_controller/error, Inputs, -); set_param(speed_controller/kp, Gain, 2.5); % 连线 add_line(speed_controller, ref_speed/1, error/1); add_line(speed_controller, cur_speed/1, error/2); add_line(speed_controller, error/1, kp/1); add_line(speed_controller, kp/1, control_u/1); % 保存 save_system(speed_controller);注意add_block中使用的built-in/Inport、built-in/Sum等是 Simulink 内部模块路径不同语言版本下显示名称可能不同但代码中的内部标识一般保持一致。如果命令行报错优先在图形界面中手动添加即可。3.2 在父模型中添加 Model 模块接下来创建父模型vehicle_level.slx用来引用刚刚创建的speed_controller模型。操作步骤如下新建模型保存为vehicle_level.slx。打开 Simulink Library Browser库浏览器在Ports Subsystems中搜索Model模块。把Model模块拖入父模型画布。双击 Model 模块在Model name一栏填写speed_controller点击确定。此时 Model 模块会自动显示speed_controller的输入输出端口分别是ref_speed、cur_speed和control_u。在父模型中添加两个 Inport 和一个 Outport分别连接到 Model 模块对应的端口上。保存父模型。命令行方式也可以实现% 创建父模型并添加 Model 模块 new_system(vehicle_level); open_system(vehicle_level); add_block(built-in/Inport, vehicle_level/ref_speed); add_block(built-in/Inport, vehicle_level/cur_speed); add_block(built-in/Outport, vehicle_level/control_u); % 添加 Model 模块并指定被引用模型 add_block(simulink/Ports Subsystems/Model, vehicle_level/speed_controller_ref); set_param(vehicle_level/speed_controller_ref, ModelName, speed_controller); % 连线 add_line(vehicle_level, ref_speed/1, speed_controller_ref/1); add_line(vehicle_level, cur_speed/1, speed_controller_ref/2); add_line(vehicle_level, speed_controller_ref/1, control_u/1); save_system(vehicle_level);3.3 设置被引用模型的仿真参数如果你希望被引用模型以加速模式运行可以在父模型中双击 Model 模块在Simulation mode下拉框中选择Accelerator或Rapid Accelerator。此外在父模型的Model Configuration Parameters中有一个Model Referencing配置页建议按下面的思路设置Rebuild options重建选项建议保持默认的If structure or underlying content has changed。这会保证被引用模型内容变化后自动重建仿真目标内容没变则直接复用兼顾正确性和效率。Enable parallel builds启用并行构建如果电脑是多核处理器且项目中存在多个被引用模型可以勾选减少总构建时间。Number of workers并行工作进程根据需要调整不要设置过大避免内存占用过高。配置完成后点击父模型工具栏的Run按钮进行仿真。首次仿真会因为需要构建被引用模型的仿真目标而稍慢后续没有变化时就会直接使用缓存结果速度显著提升。3.4 将已有 Subsystem 转换为 Model Reference如果你已经写好了子系统想把它转成 Model Reference可以使用 Simulink 提供的转换功能。在比新版本的 MATLAB 中选中 Subsystem 模块后可以右键选择Refactor Model或Convert Subsystem to Model Reference之后填写生成的新模型名称Simulink 会自动完成转换。不同 MATLAB 版本的菜单位置有所差异如果找不到这个选项可以检查当前模型是否处于“非保护”状态以及版本是否支持该功能。转换完成后原来 Subsystem 内部的 Inport/Outport 会自动对齐外部连线保持不变体验比较顺畅。但要注意如果 Subsystem 内部使用了 Goto/From 跨越父模型共享信号转换可能会报错需要先调整信号接口。4. Model Reference 常用配置与参数详解4.1 Model 模块参数对话框双击 Model 模块后可以看到几个关键选项卡Model name模型名称指定被引用模型的文件名。点击右侧的浏览按钮可以选择当前路径或 MATLAB 路径下的模型。Parameters参数用于把父模型工作区中的变量映射给被引用模型的参数。如果被引用模型定义了Simulink.Parameter对象或使用了模型工作区变量可以在这里建立映射关系。Ports端口显示当前被引用模型暴露出的输入输出端口及顺序可以快速了解接口匹配情况。Metadata元数据显示被引用模型的版本、路径等信息适合排查版本不一致问题。4.2 采样时间与代数环被引用模型的端口采样时间必须是显式的要么在端口上直接指定采样时间要么允许 Simulink 根据模型内部逻辑自动推断。如果父模型信号采样时间与被引用模型不一致Simulink 会通过“有效采样时间传播”机制进行匹配但有时候会报采样时间不一致的错误。推荐的做法是在 Inport 模块的Sample Time参数中明确设置采样时间比如0.01避免歧义。代数环Algebraic Loop在 Model Reference 中也很常见。如果被引用模型输入到输出之间存在直通路径而父模型又把输出反馈回输入就容易形成代数环。排查时可以在诊断信息中定位到代数环所在的模块路径尝试在环中增加 Unit Delay、Memory 模块或者调整代数环求解器选项。4.3 代码生成中的模型引用如果最终目标是生成 C 代码Model Reference 的价值更加明显。在配置参数中把System target file设置为ert.tlcEmbedded Coder然后启用代码生成。被引用模型会生成独立的 C 函数例如speed_controller_step()和speed_controller_initialize()。如果父模型中同一个被引用模型被使用了多次还可以在代码生成选项中启用Model reference reuse让多个实例共用同一份代码函数只是传进去的实例参数不同这样能明显减小生成代码的体积也更适合嵌入式场景。需要说明的是代码生成的详细配置与目标编译器、硬件平台强相关实际工程中不建议直接套用他人配置应该按照项目的 Target 配置文档来设置。4.4 子模型与模型工作区被引用模型内部可以使用模型工作区Model Workspace存放参数例如 PID 增益、滤波器系数等。模型工作区中的变量可以定义成Simulink.Parameter对象并设置存储类Storage Class这样在代码生成时可以直接映射到全局变量或宏定义。父模型默认看不到模型工作区的内容。如果你觉得这个限制太严格可以把需要共享的参数集中放到一个数据字典中父模型和被引用模型都关联同一个字典文件这样两边就都能访问同一组参数对象既保持接口清晰又兼顾参数共享。5. 常见错误与排查思路Model Reference 虽然好用但在实际项目中遇到的问题也不少。下面整理了几类高频问题并给出排查顺序。问题现象常见原因解决思路仿真报错找不到数据字典xxx.sldd字典文件路径失效、文件被移动或删除确认字典文件位置重新关联数据字典或刷新 MATLAB 路径仿真目标构建失败缺少编译器、模型配置不合法、路径包含中文或空格检查编译器配置用mex -setup设置清理slprj缓存端口数据类型不匹配Inport/Outport 的数据类型与父模型信号不一致打开端口属性检查数据类型、维度、总线对象采样时间不一致被引用模型内部采样时间与父模型不兼容为 Inport/Outport 显式设置采样时间Model 模块显示为灰色或不可用被引用模型被锁定、版本过大或保护模型检查被引用模型是否只读确认模型版本兼容性转换子系统为 Model Reference 时报错子系统内部使用了跨层 Goto/From 或某些不支持的模式先清理信号跨层共享把需要的外部信号改为 Inport/Outport5.1 找不到数据字典这是团队协作中最常见的错误之一尤其是在使用 Git 或 SVN 管理模型文件时。某个被引用模型本来关联了can.sldd但同事拿到代码后字典文件没有同步到本地或者路径变了Simulink 打开模型时就报“找不到数据字典”的错误。排查步骤建议如下检查报错信息中提到的字典文件在本地是否存在。如果存在确认当前模型关联的字典路径是否正确。可以在模型属性Model Properties中的Data Dictionary栏查看。如果路径错误使用Simulink.DataDictionary.open(xxx.sldd)手动打开字典然后重新关联。如果字典文件缺失需要从版本库同步或者与创建字典的同事确认文件位置。更好的做法是把数据字典文件放在与模型同级的固定目录中并使用相对路径引用避免不同电脑上绝对路径不一致。5.2 仿真目标构建失败仿真目标Simulation Target构建失败的表现是点击 Run 后进度条在“Building Simulation Target”阶段卡住或弹出红色错误。常见原因有三个本机没有安装可用的 C 编译器。运行mex -setup查看当前编译器情况如果提示找不到编译器需要安装 MinGW-w64 或 Visual Studio Build Tools。MATLAB 路径中包含中文、空格或特殊字符导致编译临时文件路径异常。建议把整个工作目录调整到纯英文路径。之前构建产生的slprj缓存损坏。可以删除当前工程目录下的slprj文件夹重新仿真让 Simulink 重新生成缓存。5.3 端口类型与维度不匹配Model Reference 对接口匹配要求比较严格。被引用模型的 Inport 如果设置成double类型、1x1维度父模型连接了一个int16类型或4x1维度的信号仿真时就会报错。解决办法是在父模型中使用 Signal Conversion 模块、Data Type Conversion 模块进行显式转换。更推荐的做法是在项目早期就统一信号类型规范例如所有物理量使用double枚举量使用Simulink.Bus总线对象这样接口匹配问题会大幅减少。6. Model Reference 工程最佳实践6.1 为每个被引用模型建立独立数据字典在复杂项目中建议每个被引用模型都关联一个独立的数据字典而不是把所有参数都放到父模型工作区。这样做的好处是模型自包含、可移植、方便团队并行修改。例如speed_controller.slx对应speed_controller.sldd里面定义控制器的全部参数和信号对象。需要注意的是数据字典的引入也带来了文件同步的工作量。使用版本控制时.sldd文件必须和.slx文件一并提交否则同事拉取代码后会遇到数据字典缺失的报错。6.2 接口设计要稳定Model Reference 的接口一旦确定后续修改成本会比较高。所以在设计被引用模型时要格外重视输入输出接口输入输出端口数量尽量精简只暴露必须的信号。端口顺序固定且建议在端口名称中体现物理含义。优先使用Simulink.Bus定义总线信号减少端口数量。数据类型、采样时间要在建模初期明确避免后期大量转换。一个稳定接口的核心是“变化尽量发生在内部接口保持长期稳定”。这样其他团队在集成时不会被频繁变更打断。6.3 合理利用增量构建Model Reference 的增量构建能力是替代 Subsystem 的重要理由。使用时要注意不要频繁修改被引用模型的结构增删端口、改变内部模块连接因为结构变化会导致更多模型需要重新构建。只修改参数值时可以优先通过 Model 模块的 Parameters 映射传入而不是直接修改被引用模型内部。在 CI 自动构建脚本中可以设置 Rebuild 选项为按需构建以节省时间。6.4 代码生成阶段注意事项在嵌入式代码生成项目中Model Reference 通常配合 Embedded Coder 使用。一些工程建议包括为每个被引用模型配置独立的代码生成目录便于排查生成的.c、.h文件。在代码生成前执行模型检查使用 Model Advisor 检查模型规范和代码生成兼容性。如果被引用模型被复用多次务必确认代码生成选项中的实例复用配置避免生成重复函数。常见的一种做法是父模型只负责系统集成和调用关系真正的算法全部放在被引用模型中生成独立函数。这样维护算法时只需要重新生成被引用模型的代码不会影响整个系统的代码结构。6.5 团队协作与版本管理多人建模时建议遵循以下协作规则每位工程师负责一个或多个被引用模型不要在同一个模型文件上频繁合并修改。父模型统一保存到独立的目录例如models/integration/被引用模型保存在models/components/。提交代码时同时提交.slx、.sldd、slprj的忽略规则避免缓存文件进入版本库。在合并分支时优先使用 MATLAB 自带的模型比较和合并工具Simulink Model Comparison不要直接手动编辑 XML 内容。如果公司已经使用 Git可以在 Git LFS 中管理模型文件减少大文件冲突的概率。另外每次修改模型前最好用模型差异工具确认改动范围降低无意识改动带来的风险。7. 总结与下一步学习建议到这里关于 Model Reference 模块的核心内容就梳理完了。我们从模块库中的位置出发对比了它与 Subsystem、Library 的区别讲了它的工作机制并通过一个速度控制器的例子完整演示了创建被引用模型、在父模型中引用、配置仿真模式和代码生成的过程。也整理了数据字典缺失、仿真目标构建失败、端口类型不匹配等高频问题的排查方案。如果你正在从单体大模型向模型架构拆分转型建议先挑一个边界清晰的算法单元比如 PID 控制器、滤波器或状态观测器把它转换为 Model Reference先在一个模型内跑通再逐步扩展到多模型协作。过程中注意观察slprj目录的构建日志和仿真速度变化这些都是理解 Model Reference 底层行为的好素材。接下来可以继续学习的方向包括Simulink 数据字典的深入应用、Rapid Accelerator 模式下的参数批量扫描、Embedded Coder 的代码生成配置、以及如何用 Simulink Test 对 Model Reference 做单元测试和覆盖率分析。理解这些内容后再把 Model Reference 用于实际项目你会明显感受到它在团队协同和工程交付上的价值。