Simulink中M文件S函数实现与自动调参工程实践

简介：面向需要在Simulink环境中调试S函数参数的MATLAB学习者与工程人员，这份资料围绕M文件驱动的自动调参展开，可用于减少手工反复修改参数的繁琐流程，适合具备一定Simulink建模与脚本基础的中级用户。压缩包共4个文件，由3个m脚本和1个slx模型组成，整体约24KB，脚本承担参数扫描、仿真控制与结果筛选等任务，模型文件提供可运行的S函数仿真载体。已有3819人学习下载，说明该主题在控制系统仿真与算法验证中具有一定关注度。读者可据此理解自动调参的组织方式，复用脚本框架完成批量仿真、参数对比与较优参数选取，并借助配套模型快速验证思路，降低重复搭建与调试成本。

1. 从一次通宵调参说起：S 函数参数化能省掉什么

某开发者接了个控制回路整定的活，被控对象和控制器都封在 Simulink 模型里，控制器本体是一个 S 函数，真正要动的只有 Kp、Ki 两个增益。他一开始靠手改对话框、点一次运行、看一眼示波器，改到第八版时已经分不清哪条曲线对应哪组数了。后来他把 S 函数换成 M 文件实现，参数从模块对话框读，再写一个脚本循环喂参数、跑仿真、算误差积分，一晚上扫完两百多组，第二天拿最优值收工。这套「MATLAB 里用 M 文件写 Simulink 的 S 函数，再挂一层自动调参脚本」的组合，适合控制逻辑已经沉淀在 S 函数里、又不想靠手感试参数的人，也适合刚接触 Level-2 M 文件 S 函数、想弄清它和外部脚本怎么配合的读者。下面按工程骨架、回调实现、调参引擎、踩坑排查、二次开发几段拆开讲。

2. 工程骨架：M 文件 S 函数、调参脚本与结果目录怎么摆

2.1 目录结构与文件职责

这类项目最怕的是所有东西堆在一个文件夹里：模型、S 函数、临时脚本、结果数据混在一起，跑上十几轮以后自己都找不到哪个 .mat 是哪次实验的。我一般按「模型 / 被调对象 / 调参逻辑 / 结果」四层拆，目录名尽量短，方便addpath之后一眼看出哪个文件归哪一层。

sfunc_tune/ ├─ init_project.m % 统一入口：加路径、清缓存、设默认参数 ├─ models/ │ └─ loop_model.slx % 顶层模型，里面放 S-Function 模块 ├─ sfunc/ │ └─ msfcn_pid.m % Level-2 M 文件 S 函数本体 ├─ tune/ │ ├─ tune_main.m % 调参主流程：网格 + 局部搜索 │ ├─ cost_once.m % 目标函数：一次仿真返回一个标量代价 │ ├─ build_grid.m % 生成候选参数组合 │ └─ save_result.m % 结果落盘，带时间戳 └─ results/ ├─ run_20240101_0930.mat └─ run_20240101_0930.csv

init_project.m里干三件事：把sfunc和tune加进搜索路径；检查loop_model.slx能不能load_system；清掉上一次可能残留的基础工作区变量。第三件事看着多余，实际能避免很多「明明改了参数结果没变」的假象——变量名撞上旧值，仿真照样跑，只是跑的是旧参数。

function init_project() % 工程统一入口：路径、模型、残留变量三件事 root = fileparts(mfilename('fullpath')); addpath(fullfile(root, 'sfunc')); addpath(fullfile(root, 'tune')); mdl = 'loop_model'; if ~bdIsLoaded(mdl) load_system(fullfile(root, 'models', [mdl '.slx'])); end % 清掉可能被上一次实验写脏的变量 vars = {'Kp', 'Ki', 'simOut', 'yout'}; for k = 1:numel(vars) if evalin('base', ['exist(''' vars{k} ''', ''var'')']) evalin('base', ['clear ' vars{k}]); end end fprintf('[init] 工程已就绪，模型：%s\n', mdl); end

mfilename('fullpath')拿的是当前文件所在目录，这样整个工程搬到别的机器上不用改路径。bdIsLoaded判断模型是否已经在内存里，避免重复load_system报警告。最后那段循环用evalin('base', ...)而不是直接clear，是因为函数里的工作区和基础工作区是两回事，S 函数读的是基础工作区里的变量，清错地方等于没清。

2.2 一条参数从脚本到 S 函数的完整链路

很多人卡在第一步：脚本里算出来的参数，怎么让 Simulink 里的 S 函数读到。常见做法有三条路，选哪条取决于你要不要保留「手动改参数」的能力。

第一条是直接把数值写进 S-Function 模块的对话框参数，用set_param改。好处是自包含，坏处是每改一次都要动模型，反复set_param会让模型变脏，跑完还得决定要不要保存。

第二条是模块对话框里填变量名（比如Kp、Ki），脚本往基础工作区里写同名变量。这条路最灵活，同一个模型既能手动跑也能脚本跑，缺点是变量泄漏，跑完不清理会污染下一轮。

第三条是用Simulink.SimulationInput的setVariable，把变量绑定到这一次仿真上，作用域干净，还能配合parsim并行。我一般首选这条，只有在需要兼容老版本模型时才退回第二条。

完整链路是这样的：tune_main生成候选参数 →cost_once用SimulationInput绑定Kp/Ki→sim跑一次 → 从输出对象里取响应 → 算出代价 → 返回给搜索器 → 记录一行结果。S 函数那一端只认模块对话框里的两个变量名，完全不知道外面在扫参。

2.3 为什么用 Level-2 M 文件 S 函数而不是 C-MEX

标题里点的是 M 文件实现，这里得说清楚取舍。Level-2 M 文件 S 函数是解释执行的，每个仿真步都要回调一次 MATLAB 函数，步长小、仿真时间长的时候慢得明显，比 C-MEX 版本慢一个数量级不夸张。自动调参要跑几十上百次仿真，这个开销会直接翻倍。

但它有三个好处，在调参场景里权重很高。一是不用mex编译，改完公式保存就能跑，调参过程中你随时可能想改控制律，C 文件编译一遍再链接的反馈循环太长。二是出错信息是 MATLAB 的堆栈，哪一行越界、哪个维度对不上，点进去就能看，不像 MEX 那样只剩一句笼统的崩溃。三是它能直接调用工作区里的函数和参数结构体，写代价函数、写辅助逻辑不用重复实现。

所以我的判断标准很粗暴：算法还在试、参数还在扫，用 M 文件版；算法定型、要交给别人跑长仿真，再翻译成 C-MEX 或者改成 MATLAB Function 块。中间不要来回折腾，先让参数定下来。

提示：msfcn_开头的函数名不是强制的，但约定俗成，sfundemos里的例子基本都是这个前缀，排查问题时搜起来方便。

3. S 函数本体拆解：六个回调里哪些和调参直接相关

3.1 setup 回调：参数个数、采样时间与状态维度

Level-2 M 文件 S 函数的结构是固定的：主函数同名，里面调setup，setup负责声明这个块的输入输出、参数个数、状态个数，然后用RegBlockMethod把各个回调注册进去。自动调参要动的参数，全部在NumDialogPrms里声明。

function msfcn_pid(block) % Level-2 M 文件 S 函数入口，名字必须和文件名一致 setup(block); end function setup(block) % 两个可调参数：Kp、Ki；一个误差输入，一个控制输出 block.NumDialogPrms = 2; block.NumInputPorts = 1; block.NumOutputPorts = 1; % 输入端口：标量误差，直通 block.InputPort(1).Dimensions = 1; block.InputPort(1).DatatypeID = 0; % double block.InputPort(1).Complexity = 'Real'; block.InputPort(1).DirectFeedthrough = true; % 输出依赖当前输入 % 输出端口：标量控制量 block.OutputPort(1).Dimensions = 1; block.OutputPort(1).DatatypeID = 0; block.OutputPort(1).Complexity = 'Real'; % 一个连续状态：积分项 block.NumContStates = 1; block.SampleTimes = [-1 0]; % 继承上游采样时间 % 注册回调，注意顺序无所谓，但名字必须对 block.RegBlockMethod('Start', @Start); block.RegBlockMethod('Outputs', @Outputs); block.RegBlockMethod('Derivatives', @Derivatives); block.RegBlockMethod('Terminate', @Terminate); end

NumDialogPrms = 2决定了模块对话框里会出现两个参数框，多一个少一个都会在编译阶段报参数数量不匹配。DirectFeedthrough = true是因为输出直接用了当前步的输入误差，如果你的 S 函数输出只依赖状态，这里要设成false，否则会凭空造出代数环。SampleTimes = [-1 0]表示继承采样时间，调参时上游信号源的步长改了，S 函数跟着变，不用同步改两处。连续状态个数写 1，对应积分项，这个数字和后面Derivatives里赋值的维度必须一致。

3.2 Outputs 与 Update：把可调参数真正用起来

Outputs每个仿真步都会被调用，是控制律真正生效的地方。参数从block.DialogPrm(k).Data取，第 k 个对应对话框里第 k 个框，索引从 1 开始，这里最容易写错。

function Outputs(block) % 每个仿真步计算控制量：u = Kp*e + xi Kp = block.DialogPrm(1).Data; Ki = block.DialogPrm(2).Data; e = block.InputPort(1).Data; xi = block.ContStates.Data(1); u = Kp * e + Ki * xi; block.OutputPort(1).Data = u; end function Derivatives(block) % 积分项导数：dxi/dt = e e = block.InputPort(1).Data; block.Derivatives(1).Data = e; end

这里把积分增益放在Outputs里乘，而不是在Derivatives里乘，是为了让 Kp、Ki 两个参数在同一个函数里出现，改公式的时候不容易漏。block.ContStates.Data(1)读当前状态值，block.Derivatives(1).Data写导数，两者维度都必须是 1，写错会报「derivative dimension mismatch」。参数读取用DialogPrm(k).Data而不是DialogPrm(k)，少写.Data拿到的是结构体，参与运算会直接报类型错误。

如果你想在仿真过程中打印参数确认脚本确实传进来了，别用disp——每个步长打一行会把命令行刷爆。用persistent记一个首次标志，只在第一步打印一次：

function Outputs(block) persistent printed if isempty(printed) fprintf('[sfunc] Kp=%.4f, Ki=%.4f\n', ... block.DialogPrm(1).Data, block.DialogPrm(2).Data); printed = true; end % ... 后续控制律 end

persistent变量在两次sim之间不会自动清空，这一点在调参场景里是个隐患，后面避坑章节会专门讲。

3.3 Start 与 Terminate：每次仿真前的状态复位

自动调参要跑几十次仿真，每次都必须是干净起点，否则第二轮继承第一轮的积分器残值，结果没有可比性。Start回调就是干这个的。

function Start(block) % 每次仿真开始把连续状态清零 block.ContStates.Data = 0; end function Terminate(block) % 仿真结束时的收尾：记录、清理、关文件 fprintf('[sfunc] 本次仿真结束\n'); end

Start里给ContStates.Data赋初值，等价于在连续系统里设初始条件。不写这一句，Simulink 会用上一次的值或者默认零，短仿真看不出差别，长仿真和多次连续调用时会出现莫名其妙的漂移。Terminate里不要做重活，打印一行、关一个文件句柄就够了，它会在每次仿真结束时被调用，写太多会拖慢整体扫参速度。

有人喜欢在Start里用assignin往外写变量做记录，这个习惯要克制。S 函数执行在仿真引擎内部，往里塞副作用容易和并行仿真冲突，记录的事情交给外层的cost_once更稳妥。

3.4 用 block 参数做在线可调的入口

除了对话框参数，Level-2 S 函数还支持运行时参数（Run-time Parameter），注册之后可以在仿真运行过程中用set_param改，不用重启仿真。做参数扫描时用不上，但做「参数自适应」或者「手动拖滑块看响应」的场景很有用。

function setup(block) block.NumDialogPrms = 2; % 把第一个参数注册成运行时参数，可在仿真中修改 block.RegBlockMethod('PostPropagationSetup', @DoPostPropSetup); end function DoPostPropSetup(block) block.NumDworks = 1; block.Dwork(1).Name = 'KpRt'; block.Dwork(1).Dimensions = 1; block.Dwork(1).DatatypeID = 0; block.Dwork(1).Complexity = 'Real'; block.Dwork(1).UsedAsDiscState = true; end

这段是给你留个口子：真要做在线调参，把Kp从对话框搬到运行时参数，外部用set_param在仿真中途改值，就能看到响应实时变化。代价是代码复杂度上去一截，而且运行时参数在代码生成里支持有限。我一般只在演示或者交互式调试时用，批量扫参还是走对话框参数那条路，逻辑简单、可复现。

4. 自动调参引擎：把 sim 命令包进一个可迭代的目标函数

4.1 目标函数：一次仿真返回一个标量代价

搜索器只认一个东西：输入一组参数，输出一个越小越好的标量。所以第一件事是把「跑仿真 + 算指标」封成一个函数，中间过程全部藏在里面。

function J = cost_once(p, cfg) % p : 候选参数 [Kp, Ki] % cfg : 配置结构体，含模型名、仿真时长、上下界、惩罚值 % J : 标量代价，越小越好 % 越界直接给惩罚，不去跑仿真，省时间 if any(p < cfg.lb) || any(p > cfg.ub) J = cfg.penalty; return; end in = Simulink.SimulationInput(cfg.model); in = in.setVariable('Kp', p(1)); in = in.setVariable('Ki', p(2)); in = in.setModelParameter('StopTime', num2str(cfg.tStop)); in = in.setModelParameter('SimulationMode', 'normal'); in = in.setModelParameter('SaveFormat', 'Structure with time'); in = in.setModelParameter('SaveOutput', 'on'); in = in.setModelParameter('OutputSaveName', 'yout'); try out = sim(in); catch ME % 仿真炸了也给惩罚，但把原因记下来 fprintf('[cost] 仿真失败：%s\n', ME.message); J = cfg.penalty; return; end y = out.get('yout'); t = y.time; sig = y.signals.values; ref = cfg.ref; % 参考信号，标量或同长度向量 e = ref - sig; J = trapz(t, abs(e)); % IAE 指标 J = J + cfg.wOvershoot * max(0, max(sig) - max(ref)); % 超调惩罚 end

setVariable绑定的变量只在这一次仿真里有效，跑完自动释放，不会污染基础工作区，这是它比assignin干净的地方。SimulationMode必须显式设成normal，M 文件 S 函数在加速模式下不支持，不设的话模型上次保存成 Accelerator 就会直接报错。try/catch里返回惩罚值而不是抛出去，是因为搜索器遇到一次失败就中断太浪费，给个大代价让它自己绕开这组参数更划算。

指标用trapz算 IAE，比简单求和更贴近连续系统的定义。超调惩罚单独加权，权重wOvershoot放在配置里，方便你在「快但抖」和「慢但稳」之间调倾向。

4.2 主循环：网格扫描与局部搜索的组合

纯网格扫得全但慢，纯梯度搜索快但容易掉进局部极小。控制参数这类问题，我一般先用粗网格框出大致区域，再用fminsearch在局部细化，两段式比单用一种稳。

function best = tune_main() cfg = struct('model', 'loop_model', 'tStop', 10, 'ref', 1, ... 'lb', [0 0], 'ub', [10 3], 'penalty', 1e6, ... 'wOvershoot', 2); KpGrid = linspace(0.2, 5.0, 8); KiGrid = linspace(0.0, 2.0, 6); records = zeros(numel(KpGrid) * numel(KiGrid), 3); % Kp, Ki, J idx = 0; best = struct('J', inf, 'p', [NaN NaN]); for kp = KpGrid for ki = KiGrid idx = idx + 1; p = [kp ki]; J = cost_once(p, cfg); records(idx, :) = [kp ki J]; if J < best.J best.J = J; best.p = p; fprintf('[grid] 新最优 J=%.4f @ Kp=%.3f, Ki=%.3f\n', J, kp, ki); end end end % 局部细化：从网格最优点出发 opts = optimset('Display', 'iter', 'TolX', 1e-3, 'MaxIter', 40); pFine = fminsearch(@(p) cost_once(p, cfg), best.p, opts); JFine = cost_once(pFine, cfg); if JFine < best.J best.p = pFine; best.J = JFine; end save_result(records, best, cfg); end

网格那段是双循环，每个组合调一次cost_once，records矩阵把三元组存下来，最后一起落盘。fminsearch从网格最优点出发，TolX控制参数收敛精度，MaxIter防止它在一个平坦区域里磨太久。注意fminsearch本身不管边界，越界的情况靠cost_once开头的惩罚兜住——这也是为什么惩罚值要给得足够大，太小的话搜索器会心安理得地待在界外。

4.3 接入 fminsearch / ga 的写法与边界约束

fminsearch够用，但它对初值敏感、不支持约束。参数维度上去了、或者你明确知道 Kp 和 Ki 有耦合关系，换遗传算法或者模式搜索更合适。接口是一模一样的，都是「输入向量、输出标量」。

% 方案一：模式搜索，自带边界约束 opts = optimoptions('patternsearch', 'Display', 'iter', ... 'MaxIterations', 60, 'MeshTolerance', 1e-3); [pOpt, JOpt] = patternsearch(@(p) cost_once(p, cfg), best.p, ... [], [], [], [], cfg.lb, cfg.ub, [], opts); % 方案二：遗传算法，适合多峰、参数多于 3 个的情况 opts = optimoptions('ga', 'Display', 'iter', 'PopulationSize', 20, ... 'MaxGenerations', 30, 'UseParallel', false); [pOpt, JOpt] = ga(@(p) cost_once(p, cfg), 2, ... [], [], [], [], cfg.lb, cfg.ub, [], opts);

patternsearch的好处是边界直接作为参数传进去，不用靠惩罚，收敛过程更干净，代价是每轮要评估的点数比fminsearch多。ga适合参数多、代价函数有多个局部极小的情况，但它的随机性意味着两次跑出来的结果可能不一样，做实验记录的时候要把随机种子固定下来，否则复现不了。

UseParallel那一项先关掉，等单机流程跑通了再打开，不然出错时你分不清是并行的问题还是代价函数的问题。

4.4 结果落盘与最优参数回写

扫完一轮，结果要能查、能对比、能复现。save_result干三件事：存.mat方便下次直接load，写.csv方便丢进表格里看趋势，把最优参数写回基础工作区方便立刻手动验证。

function save_result(records, best, cfg) stamp = datestr(now, 'yyyymmdd_HHMM'); matFile = fullfile('results', ['run_' stamp '.mat']); csvFile = fullfile('results', ['run_' stamp '.csv']); save(matFile, 'records', 'best', 'cfg'); fid = fopen(csvFile, 'w'); fprintf(fid, 'Kp,Ki,J\n'); for k = 1:size(records, 1) fprintf(fid, '%.6f,%.6f,%.6f\n', records(k, 1), records(k, 2), records(k, 3)); end fclose(fid); % 回写最优值，方便立刻手动跑一次确认 assignin('base', 'Kp', best.p(1)); assignin('base', 'Ki', best.p(2)); fprintf('[save] 最优 J=%.4f, Kp=%.4f, Ki=%.4f\n', best.J, best.p(1), best.p(2)); end

文件名带时间戳，跑一百轮也不会互相覆盖。.mat里存了cfg，下次想复现同一组实验，把cfg取出来直接用，不用回忆当时设的仿真时长和惩罚权重。最后那两行assignin是给手动验证留的口子：模型对话框里填的是变量名Kp、Ki，脚本跑完工作区里就是最优值，打开模型点一次运行就能看响应。

5. 避坑与排查：五类让调参结果不可信的坑

5.1 参数个数不匹配，S 函数在编译阶段就挂

现象很直接：点运行，命令行报S-function 'msfcn_pid' has fewer parameters in its dialog than it expects，或者反过来多了一个。原因通常是setup里NumDialogPrms改了，但模型里那个 S-Function 模块的对话框没同步改，两个地方各说各话。

解决方法是把「声明」和「实例」当成一对强耦合的东西来维护。改NumDialogPrms之后，一定打开模型确认参数框数量和顺序，顺序错了不会报错，但 Kp 会读到 Ki 的值，跑出来的结果看着像那么回事，其实全错。我一般会在setup里加一段自检，参数个数不对时直接error并打印期望值，比等到仿真跑一半再发现强。

function setup(block) block.NumDialogPrms = 2; if numel(block.DialogPrm) ~= 2 error('msfcn_pid:prmCount', ... '期望 2 个参数，实际收到 %d 个', numel(block.DialogPrm)); end end

5.2 加速模式与 M 文件 S 函数不兼容

现象是仿真刚启动就报M-file S-function cannot be used in accelerated mode，或者切到 Accelerator 之后模型直接编译失败。原因是 Level-2 M 文件 S 函数是解释执行的，加速模式要把它编译成目标代码，两者天然冲突。

解决方式只有两条：要么在调参脚本里强制SimulationMode为normal，要么把逻辑改写成 MATLAB Function 块或 C-MEX。前一条是调参阶段的默认选择，写进cost_once里就不会忘。真正要跑长仿真、要加速的时候，说明参数已经定得差不多了，那时候再做移植，顺序不要反。

5.3 状态未复位，第二轮结果开始漂移

这个坑最阴。第一轮仿真结果正常，从第二轮开始响应曲线整体偏移一点，越往后偏得越多，但脚本、参数、模型一个都没改。原因有两类：一类是Start里没给ContStates.Data赋初值，积分器继承了上一轮的值；另一类是 S 函数里用了persistent变量做计数或缓存，两次sim之间不会被清空。

排查方法是把同一组参数连续跑三次，比较三次的输出是否逐位相同。不相同就顺着persistent关键字和ContStates找。解决上，状态一律在Start里显式清零，persistent能不用就不用，非要用就在Start里重置：

function Start(block) block.ContStates.Data = 0; clear msfcn_pid % 清掉本函数内的 persistent end

5.4 数据记录格式选错，指标算出来是错的

现象是从out里取出来的yout维度不对，signals.values是双列或者时间向量长度和信号长度对不上，trapz算出来的 IAE 数量级明显离谱。原因是SaveFormat设成了Dataset或者Array，读取方式和Structure with time完全不同。

两种读法要分清楚：Structure with time用y.time和y.signals.values；Dataset用y.get('信号名').Values.Data和.Time。调参脚本里统一用一种，别一半脚本用这种一半用那种。我习惯在cost_once开头就把SaveFormat钉死，读的时候加一句维度断言：

assert(size(sig, 2) == 1, 'yout 维度异常，检查 SaveFormat 设置');

5.5 路径与命名冲突

现象是Undefined function 'msfcn_pid'，或者改完文件内容运行结果不变。原因通常有三个：函数名和文件名不一致（Level-2 M 文件 S 函数要求严格同名）；文件所在目录没加进搜索路径；工作区里存在同名变量遮蔽了函数。

排查顺序是which msfcn_pid -all看有几个同名文件、path看目录在不在、whos msfcn_pid看有没有变量撞名。这三个命令跑一遍，九成问题当场现形。工程里我固定用init_project统一加路径，就是为了把这类问题挡在入口。

6. 二次开发：把单机扫参改成可复用的调参流水线

单机脚本跑通之后，最值得做的改造是并行。cost_once之间互不依赖，把网格那层双循环换成parfor，或者直接用parsim批量提交SimulationInput数组，四核机器上差不多能压到四分之一时间。改的时候注意两件事：cost_once里不能有对基础工作区的写操作，SimulationInput要提前构造成数组再一次性提交，否则并行收益会被调度开销吃掉。

第二个改造方向是把代价函数从单目标扩成多目标，比如同时看调节时间和超调量，用加权和或者 Pareto 前沿。加权系数放在cfg里，别硬编码在函数内部，否则每换一个工况就要改代码。

第三个方向是把最优参数自动回写到模块的 mask 或者数据字典里，形成「扫参—定参—固化」的闭环。这一步我建议保留人工确认环节，脚本只负责把候选值和对应的响应曲线存成图，最终写不写回由人拍板。自动写回看着省事，一旦代价函数设计得有偏，固化的就是一组错参数。

验证方法上，我固定做三件事：拿最优参数手动跑一次，和脚本记录的最优代价对比，误差超过百分之一就说明记录链路有问题；换一组没参与搜索的工况参数跑一次，看泛化；把随机种子固定下来重复跑一遍，结果应当逐位一致，不一致就回去查persistent和状态复位。

有一回我图省事，把cost_once里的SimulationMode那行删了，想着模型默认就是 normal，结果模型被同事存成了 Accelerator，一整晚的扫参全部作废，最优值是一组随机数。从那以后我每次开新工程，都强制先跑一遍init_project加三次重复性自检，确认三次输出完全一致再开始扫参。希望这套流程能帮到你，少走一遍我踩过的弯路。

本文还有配套的精品资源，点击获取