简介：面向Simulink控制系统建模与仿真学习者的自动调参示例包，聚焦用MATLAB M文件驱动S函数模块完成参数扫描与择优，缓解手工反复改参、对比仿真结果的低效问题，适合具备一定MATLAB基础、正在做课程实验或课题验证的读者参考。压缩包共4个文件，约24KB，含3个.m脚本与1个.slx模型：模型文件承载S函数仿真框架，M文件负责设置仿真时间、组织变量变化并自动运行与筛选较优参数，二者配合形成闭环调参流程。已有3819人学习下载，说明该主题在自动控制与系统仿真场景中具有一定关注度。读者可据此理解S函数模块的接口配置、参数批量变化与仿真结果比较方法，并在此基础上改造成自己的被控对象或评价指标，用于验证不同参数组合对系统输出的影响，积累程序化调参和排错思路。

1. 一个 S-Function 模块 125 种组合：为什么要在 M 文件里做自动调参数

三个可调参数、每个五档，手动改对话框就是 125 次点击，外加 125 次肉眼比对波形和手抄误差。真正折磨人的不是点击次数，而是中途接个电话回来，已经分不清当前这组数到底跑没跑过。这篇讲的是一套用 MATLAB 的 M 文件在 Simulink 外面套壳的做法：把 S 函数对话框里的参数抽成参数表，用脚本批量灌进模块、批量跑仿真、批量算代价并落盘，让“改一个数点一次运行”变成一次配置、整夜跑完。它适合已经能让 M 文件 S 函数在模型里正常输出、但还在靠手改参数试错的人；如果 S 函数本身还没跑通，第 2 章的骨架可以先补地基。

2. S 函数的参数入口：从 NumDialogPrms 到 Parameters 字符串的完整契约

2.1 M 文件 S 函数的可调参数到底存在哪

M 文件 S 函数的所有外部可调量，最终都收敛到block.DialogPrm(i).Data这一个入口。它对应模型里 S-Function 模块对话框中的 “S-function parameters” 字段，模块参数名是Parameters。一条必须记住的规则是：Parameters是逗号分隔的字符串，第 i 个值对应block.DialogPrm(i)，顺序错一位，整轮调参就是白跑。下面是最小可调参骨架，两个参数做y = gain*u + bias：

function sfun_demo(block) % 最小可调参 M 文件 S-Function：y = gain*u + bias % 文件名必须与函数名一致，模块里 Function name 填 sfun_demo setup(block); end function setup(block) block.NumInputPorts = 1; block.NumOutputPorts = 1; block.SetPreCompInpPortInfoToDynamic; block.InputPort(1).Dimensions = 1; block.InputPort(1).DirectFeedthrough = true; block.OutputPort(1).Dimensions = 1; % 关键：声明有几个对话框参数，决定 Parameters 字段要填几个值 block.NumDialogPrms = 2; block.DialogPrm(1).Name = 'gain'; block.DialogPrm(2).Name = 'bias'; for k = 1:block.NumDialogPrms block.DialogPrm(k).DataTypeId = 0; % 0 表示 double end block.SampleTimes = [-1 0]; % 继承上游采样时间 block.RegBlockMethod('Outputs', @Output); end function Output(block) % Data 字段在 setup 阶段拿不到，必须放到 Outputs 等回调里取 g = block.DialogPrm(1).Data; b = block.DialogPrm(2).Data; block.OutputPort(1).Data = g .* block.InputPort(1).Data + b; end

逐处说明。SetPreCompInpPortInfoToDynamic让输入端口维度跟随上游，适合做通用测试台；如果信号维度固定，直接写死数值可以减少一次编译开销。DirectFeedthrough = true表示输出直接依赖当前步输入，写 false 会让 Simulink 在代数环判断上走另一条路径，输出会对不上，这是很多人第一次写 S 函数踩的坑。SampleTimes = [-1 0]是继承采样时间，配合测试台的固定步长求解器最省事。最关键的是NumDialogPrms与Parameters的数量约定，它没有默认值，少填一个就报参数个数不匹配。

还有一个容易忽略的细节：DialogPrm(i).Name只是给模块参数化界面看的标签，和你调参脚本里的字段名没有绑定关系，真正绑定的是序号。所以调参脚本里必须单独维护一份顺序常量，例如order = {'gain','bias'}，并且和这里的DialogPrm(1)、DialogPrm(2)严格对齐。这份顺序常量一旦改动，历史结果文件里的参数列就得跟着改，否则回看旧数据会张冠李戴。

如果参数本身是向量或矩阵，Parameters字段要写成[1 2 3]或[1 2;3 4]这样的字符串形式，M 文件 S 函数解析后Data直接就是对应维度的数组。这时调参脚本不能再用单值格式化拼接，得给矩阵参数单独写序列化函数，否则会得到一个被压平的错误字符串。

2.2 手改对话框为什么撑不住多参数场景

单参数、三五档，手改确实快。参数一多，问题立刻从“麻烦”变成“不可信”。第一是组合爆炸后的记录失真：三个参数各五档是 125 组，人眼对齐波形时容易把第 37 组的结果记到第 38 组名下，等回头挑最优参数，发现最优那组根本复现不出来。第二是没有失败留痕，某组参数让求解器步长崩了，报错一闪而过，你只知道“跑到一半停了”，不知道停在哪一组。第三是没法做真正的搜索，手改只能做网格，做不了模式搜索、遗传算法这类需要几百次函数评估的方法。

用 M 文件在外面套一层，本质上换了个执行模型：参数从“一次性输入”变成“可索引的数据”，一次仿真从“一次点击”变成“一次函数调用”。这一步跨过去之后，断点续跑、并行、和优化器对接都是顺带的事。我一般会把调参脚本单独放一个目录，模型文件和 S 函数放另一个目录，脚本开头统一addpath，避免模型换机器后路径失效。

2.3 三种参数注入路径的边界

把参数塞进 S-Function 模块，常见有三条路，选错会在并行环节翻车。

第一种最直观，缺点是它直接改模型，跑完一批模型处于“脏”状态，下次打开不知道当前是哪组参数。第二种在单机交互时舒服，但它依赖 base 工作区，parfor的工作进程看不到你主进程里assignin的变量，除非每个 worker 自己再赋一遍。第三种是批量场景的默认答案：SimulationInput是一个值对象，每次循环新建一个，参数跟着对象走，天然适合切片分发，也不污染模型。

选择标准很朴素：要并行、要断点续跑、要结果可复现，就用SimulationInput；只是临时验证一个想法，set_param最快。不要混用，同一个脚本里一半set_param一半SimulationInput，最后排查参数到底生效没生效会非常痛苦。

3. 参数表与批量仿真骨架：用 SimulationInput 把一组参数灌进模型

3.1 参数表用结构体数组，不要用散装变量

参数表的第一原则是“一行就是一次完整运行”。散装变量gain1、gain2、bias1在参数一多后根本没法用索引切片，也没法直接喂给parfor。用结构体数组可以同时满足索引、落盘和并行分发：

% 每档取值用 cell 包裹，才能生成 1xN 的结构体数组 grid = struct( ... 'gain', {0.5, 1.0, 1.5, 2.0}, ... 'bias', {0.0, 0.2, 0.4}); % 做笛卡尔积，得到每一组待跑参数 [gi, bi] = ndgrid(1:numel(grid.gain), 1:numel(grid.bias)); pSet = struct('gain', {}, 'bias', {}); for k = 1:numel(gi) pSet(end+1).gain = grid.gain{gi(k)}; pSet(end).bias = grid.bias{bi(k)}; end fprintf('待跑参数组数：%d\n', numel(pSet));

这里有个 MATLAB 的语法细节值得单独说：struct('gain',{0.5,1.0})生成的是 1×2 结构体数组，而struct('gain',[0.5 1.0])生成的是标量结构体、字段是一个数组。前者才是我们要的“每组一行”，后者会让后续pSet(k).gain直接报索引越界。ndgrid而不是meshgrid，是因为参数超过两维时ndgrid的维度顺序和线性索引更一致，写循环不容易绕晕。

参数表定好之后，建议立刻做两件事：一是把表本身存一份params_grid.mat，二是打印组数和前几组，确认没有因为 cell 写法错误变成一组。这两步花十秒，能省掉后面半小时的“为什么只跑了一组”的排查。

3.2 把一组参数打包成 Parameters 字符串

参数表是结构体，模块要的是逗号分隔字符串，中间这层转换必须有且只有一个函数，避免各处手写格式不一致：

function s = packParams(p, order) % p : 单组参数结构体 % order : 与 S-Function 中 NumDialogPrms 顺序严格一致的字段名元胞 n = numel(order); vals = cell(1, n); for k = 1:n v = p.(order{k}); if isscalar(v) vals{k} = sprintf('%.10g', v); % 避免科学计数法与精度丢失 else vals{k} = mat2str(v, 10); % 向量/矩阵参数走这里 end end s = strjoin(vals, ','); end

%.10g而不是%f，原因是%f固定六位小数，像1e-7这种量级会被打成0.000000，S 函数拿到的就是一个零，而模型不报错，结果全错，这类问题最难查。%g会自动选最短表示，10位有效数字对双精度参数足够。矩阵分支用mat2str，它输出的[1 2;3 4]正好是 S 函数能解析的语法。

order这个元胞建议写成脚本顶部的常量，并且和 S 函数里的DialogPrm序号并排放注释。我见过最冤的一次翻车，是有人在 S 函数里把两个参数的声明顺序调换了，调参脚本没改，结果整批数据里 gain 和 bias 是反的，曲线看着“也能跑”，但最优参数怎么解释都不对。

3.3 单次仿真的最小闭环

有了参数表和打包函数，单次仿真就是一个 try/catch 包住的函数调用。用SimulationInput的好处是参数、停止时间、输出保存选项都在一个对象里，不会漏：

mdl = 'demo_mdl'; blk = [mdl '/S-Function']; order = {'gain', 'bias'}; for k = 1:numel(pSet) pstr = packParams(pSet(k), order); try in = Simulink.SimulationInput(mdl); % 每轮新建，不复用 in = in.setBlockParameter(blk, 'Parameters', pstr); in = in.setModelParameter('StopTime', '10', ... 'SaveOutput', 'on', ... 'OutputSaveName', 'yout'); out = sim(in); y = readYout(out); peak = max(abs(y)); fprintf('[%03d] gain=%.3f bias=%.3f peak=%.4f\n', ... k, pSet(k).gain, pSet(k).bias, peak); catch ME fprintf('[%03d] 失败：%s\n', k, ME.message); end end

几处参数说明。StopTime必须和手动验证时完全一致，调参期间改停止时间等于换了评价标准，前后的结果不可比。SaveOutput显式打开，是因为部分模型的配置里默认不保存输出，out拿回来是空的，而代码不报错。OutputSaveName指定成yout，后面读取时就不依赖默认命名。in在循环内新建，这是硬性纪律：SimulationInput复用后再改参数，某些情况下旧设置会残留，表现为“第一组对、后面全一样”。

3.4 不同版本下读取输出要写兼容分支

sim返回的SimulationOutput里，yout的形态随版本和模型配置变化，可能是timeseries，也可能是带signals.values的结构体。直接把读取写死，换台机器就变成“结果全空”：

function y = readYout(out) % 兼容 timeseries / struct / Dataset 三种常见形态 y = out.get('yout'); if isa(y, 'timeseries') y = y.Data; elseif isstruct(y) && isfield(y, 'signals') y = y.signals.values; elseif isa(y, 'Simulink.SimulationData.Dataset') y = y.getElement(1).Values.Data; end y = squeeze(y); if isempty(y) error('yout 为空，检查 SaveOutput 与 StopTime 设置'); end end

这个函数看着琐碎，但它是“结果可信”的第一道闸。空输出如果不在这里拦下来，会一路传到目标函数里变成NaN，优化器收到NaN后的行为很不讲道理，可能直接停止迭代，也可能给出一个看似合法但毫无意义的最优点。早报错比晚报错便宜得多。

4. 目标函数与搜索策略：把仿真输出压成标量并让它收敛

4.1 目标函数要处理失败、维度与量纲

自动调参的核心不是循环，是目标函数。它必须满足三个条件：输入是一组参数，输出是一个标量，任何异常都要变成可识别的惩罚值而不是崩溃：

function J = costOne(p, cfg) % cfg 里带模型名、模块路径、参数顺序、参考信号、时间向量 pstr = packParams(p, cfg.order); try in = Simulink.SimulationInput(cfg.mdl); in = in.setBlockParameter(cfg.blk, 'Parameters', pstr); in = in.setModelParameter('StopTime', num2str(cfg.tEnd), ... 'SaveOutput', 'on', 'OutputSaveName', 'yout'); out = sim(in); y = readYout(out); y = y(:); r = cfg.ref(:); n = min(numel(y), numel(r)); if n < 0.9 * numel(r) J = cfg.penalty; % 仿真提前结束，按失败处理 return; end e = y(1:n) - r(1:n); J = sqrt(mean(e.^2)) / (max(abs(r)) + eps); % 归一化 RMSE catch J = cfg.penalty; end end

失败惩罚cfg.penalty建议取一个比正常代价大两三个数量级的有限值，比如正常 RMSE 在 0.01 量级，惩罚取 1e3。不要用Inf，部分优化器在初始单纯形里遇到Inf会直接报错退出，或者用NaN传染整代种群。归一化那一步也不能省，参考信号幅值大的通道会天然主导误差，最后调出来的参数只对大幅值段好看。

n < 0.9 * numel(r)这个判断是血泪经验：有些参数组合会让求解器把步长压到极小，仿真没报错但只跑完了前 10% 的时间，输出长度短一截。如果不检查长度直接相减，MATLAB 会因维度不一致报错，被 catch 吞掉变成惩罚值，你还以为是参数太差，其实是仿真根本没跑完。

4.2 优化器的适用边界

一次仿真零点几秒到几秒，这个成本决定了不能无脑上遗传算法。选型看三件事：参数是否连续、目标是否光滑、有没有边界约束。

我一般的顺序是：先用网格扫一遍看代价地形，确认没有明显的多峰，再用patternsearch在最优网格点附近做局部细化，边界设为网格步长的正负两档。这样总评估次数通常在几十到一两百次，一晚上能跑完好几轮。直接上ga的心理预期要放平：种群 20、迭代 30 就是 600 次仿真，按每次 2 秒算也要二十分钟，模型再重一点就是几小时。

4.3 结果落盘与断点续跑

调参脚本最常见的失败不是算法不收敛，是跑到第 80 组时机器休眠、MATLAB 崩了，前面 79 组结果全在内存里。落盘要放在循环体内，每组跑完立刻追加：

function appendResult(fn, row) % row 是 table 的一行，追加写入 csv，不存在则新建 if exist(fn, 'file') writetable(row, fn, 'WriteMode', 'append', 'WriteVariableNames', false); else writetable(row, fn, 'WriteMode', 'overwrite', 'WriteVariableNames', true); end end

配套的断点续跑逻辑是：脚本启动时先读已有 csv，取出已完成的参数组合，用ismember做行匹配，跳过已完成项。参数组合的匹配要对浮点做容差比较，直接==会因为%.10g往返转换的末位差异判成不等，导致重复跑。我习惯在参数表里额外加一列runId，用参数索引拼成字符串做主键，比浮点比较省心。

% 断点续跑：按 runId 跳过已完成组合 if exist(csvFile, 'file') done = readtable(csvFile); doneId = string(done.runId); else doneId = strings(0,1); end for k = 1:numel(pSet) rid = sprintf('g%03d_b%03d', gi(k), bi(k)); if any(doneId == rid), continue; end % ... 跑仿真、算代价、appendResult ... end

4.4 一个可直接改的主脚本

把上面的零件串起来，主脚本的结构是：配置 → 生成参数表 → 读断点 → 循环跑 → 落盘 → 排序取最优。配置区集中放模型名、模块路径、参数顺序、停止时间、惩罚值，这五样是每次换项目唯一要改的地方。其余代码原样复用，能显著降低“换个模型就重写一遍脚本”的重复劳动。跑完之后用sortrows按代价值升序取前三组，别只看第一名，前三名的参数如果分散在参数空间两端，说明代价地形有多个谷，单点最优的可信度要打折扣。

5. 调参路上的五类翻车：参数不生效、输出为空与并行不一致

5.1 参数与编译类问题

第一条：改了 Parameters，曲线纹丝不动。现象是脚本打印的参数确实变了，仿真也不报错，但输出和上一组完全一致。原因通常有三个：一是 S 函数里把DialogPrm(i).Data缓存进了persistent变量，第二次调用直接用了旧值；二是Parameters字符串用了中文逗号或带了空格，模块解析失败后回退到上一次的合法值；三是SimulationInput对象被复用，setBlockParameter没有真正刷新。解决方式是三件事一起做：S 函数内禁止用persistent存参数，所有状态走Dwork；打包函数里加断言，检查字符串里只有英文逗号和数字；循环内每次新建SimulationInput。排查时最有效的一招是在 S 函数的Outputs里临时fprintf一次参数值，看它到底收到了什么。

第二条：报参数个数不匹配或非法设置。现象是sim直接抛错，提示 S-Function 模块的Parameters设置有误。原因是packParams输出的值个数与NumDialogPrms不一致，常见于参数表里某个字段是空数组，sprintf打出了空串，逗号数量对不上。解决方式是在packParams末尾加assert(numel(strsplit(s,',')) == n)，让错误在打包阶段就暴露，而不是等到仿真阶段被 Simulink 报一个指向不明的错。

第三条：参数是矩阵时被压平。现象是传了[1 2;3 4]，S 函数里Data拿到的却是 1×4 向量，后续按矩阵索引取值全部错位。原因是矩阵参数走了标量分支，被sprintf按元素展开。解决办法是在packParams里用isscalar判断，非标量一律走mat2str，并且在 S 函数里对Data的维度做一次assert。这类问题不会报错，只会让结果“看起来差不多但就是不对”，属于典型的黑匣子故障。

5.2 结果与并行类问题

第四条：串行正常，并行后部分组结果不一致。现象是同样的参数表，parfor跑出来的代价值与串行对不上，且每次不一致的组还不固定。原因主要有两个：S 函数内部用了全局变量或写文件，多个 worker 互相覆盖；或者并行池的工作进程复用了上一次的persistent状态。解决方式是先把 S 函数改成无状态，所有需要跨步保存的量放block.Dwork；并行前用parpool显式指定进程数并预热；如果模型里有随机源，给每组参数固定rng种子。改完之后用前五组参数做一次串并行对照，代价差异应小于千分之一，超过就说明还有共享状态没清干净。

第五条：输出为空或维度不对，优化器给出莫名其妙的最优点。现象是循环能跑完，但部分组的yout是空的，代价值变成NaN，最后排序时NaN被排到最前或最后，取出来的“最优参数”其实是一次失败运行。原因包括SaveOutput没开、StopTime设得太短、S 函数输出端口维度声明与实际赋值不符。解决办法是在readYout里对空值和维度做硬校验，失败直接抛错由外层 catch 转成惩罚值；同时在落盘表里保留一列ok标志，取最优时先按ok == true过滤。这一步做完，至少不会再把失败样本当成最优解。

6. 进阶：并行扫描、归一化与回灌验证

参数组数超过五十之后，串行跑就开始影响作息了。并行有两种写法：parfor配costOne，或者用parsim直接吃SimulationInput数组。后者更贴近 Simulink 的原生批量接口，前者更灵活，因为可以在循环体里塞自定义的后处理和落盘逻辑。

% 方式一：parfor 扫参数表，注意每个 worker 都要能访问模型路径 pool = gcp('nocreate'); if isempty(pool), parpool('Processes', 4); end % 老版本写 parpool(4) J = zeros(numel(pSet), 1); parfor k = 1:numel(pSet) J(k) = costOne(pSet(k), cfg); end

% 方式二：parsim 批量提交，参数已在 SimulationInput 里 ins = repmat(Simulink.SimulationInput(mdl), 1, numel(pSet)); for k = 1:numel(pSet) ins(k) = ins(k).setBlockParameter(blk, 'Parameters', packParams(pSet(k), order)); ins(k) = ins(k).setModelParameter('StopTime', '10', 'SaveOutput', 'on'); end outs = parsim(ins, 'ShowProgress', 'on', 'UseFastRestart', 'off');

两段代码的取舍很清楚：parsim省心，但错误处理粒度粗，某一组失败会影响整批的返回结构；parfor里自己 try/catch，失败组能单独标记，方便续跑。UseFastRestart在参数只改模块参数时能省编译时间，但它对 S 函数的状态清理有额外要求，第一次用建议先关掉，确认结果与串行一致再打开。

并行之外，第二个值得花时间的是参数归一化。gain 的量级可能是 0.1 到 10，bias 可能是 1e-4 到 1e-3，直接把它们丢进同一个优化器，步长会被大量级参数支配，小量级参数几乎不动。做法是给每个参数定义上下界，映射到[-1,1]再搜，搜完反变换回物理量。patternsearch的ScaleMesh选项也能缓解，但不如显式归一化可控。

最后一步是回灌验证，也是最容易被跳过的一步。把最优参数用packParams打成字符串，手动填回模块对话框，用和人眼验证时完全相同的方式跑一遍，对比脚本里记录的代价值。两者对不上，说明脚本里还有隐藏状态，或者输出读取路径与手动观察的不是同一个信号。我吃过一次亏：脚本读的是yout第一个通道，手动看的是示波器上第二个通道，调了两天参数，其实一直在优化一个不相关的信号。从那以后，每次跑完批量调参，我都会强制走一遍“最优参数回灌 + 示波器对照”，确认曲线形状、稳态值、超调量三项都对得上，才把结果写进报告。这个习惯多花十分钟，能挡掉后面几天的返工。希望帮到你。

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