simulink-builder

name	simulink-builder
description	Programmatic Simulink model builder for power electronics via MATLAB MCP interface. Auto-create, wire, simulate and verify Simscape Electrical (powerlib) models with built-in error correction. Use when user mentions Simulink, Simscape, power electronics simulation, Buck/Boost/inverter, 电路仿真, 电力电子, Simulink建模, powerlib.

Simulink 程序化建模技能

快速开始

环境要求

• Windows 系统 + MATLAB R2024a+ 已安装
• Simulink + Simscape Electrical (Specialized Power Systems) 已安装
• MATLAB MCP Server 已配置并连接

工作流概览

用户输入（电路需求 + 参考图片）
    → 阶段1: 环境探测
    → 阶段2: 参数计算
    → 阶段3: 模型搭建+连线（含自动纠错）
    → 阶段4: 布局美化
    → 阶段5: 仿真验证（含自动纠错）
    → 阶段6: 输出归档

---

阶段1：环境探测

1.1 版本检测

% 检查 Simulink 和 Simscape Electrical
v = ver('simulink');     % Simulink 版本
v2 = ver('power_system'); % Simscape Electrical
if isempty(v), error('Simulink 未安装'); end

1.2 模块路径探测

核心问题：不同 MATLAB 版本的 powerlib 模块路径不同，不能硬编码。 必须用 try-add_block 方式逐个探测。

% 模块探测表：按优先级排列候选路径
BLOCK_CANDIDATES = struct();
BLOCK_CANDIDATES.switch = {'powerlib/Power Electronics/MOSFET', ...
                            'powerlib/Power Electronics/IGBT', ...
                            'powerlib/Power Electronics/Ideal Switch'};
BLOCK_CANDIDATES.diode = {'powerlib/Power Electronics/Diode'};
BLOCK_CANDIDATES.thyristor = {'powerlib/Power Electronics/Thyristor'};
BLOCK_CANDIDATES.bridge = {'powerlib/Power Electronics/Universal Bridge'};
BLOCK_CANDIDATES.ac_source = {'powerlib/Electrical Sources/AC Voltage Source'};
BLOCK_CANDIDATES.dc_source = {'powerlib/Electrical Sources/DC Voltage Source'};
BLOCK_CANDIDATES.ctrl_vsource = {'powerlib/Electrical Sources/Controlled Voltage Source'};
BLOCK_CANDIDATES.transformer = {'powerlib/Elements/Linear Transformer'};
BLOCK_CANDIDATES.rlc = {'powerlib/Elements/Series RLC Branch'};
BLOCK_CANDIDATES.ground = {'powerlib/Elements/Ground'};
BLOCK_CANDIDATES.v_measure = {'powerlib/Measurements/Voltage Measurement'};
BLOCK_CANDIDATES.i_measure = {'powerlib/Measurements/Current Measurement'};
BLOCK_CANDIDATES.powergui = {'powerlib/powergui'};

function path = discover_block(candidates, model, temp_name)
    path = '';
    for i = 1:length(candidates)
        try
            add_block(candidates{i}, [model '/' temp_name]);
            delete_block([model '/' temp_name]);
            path = candidates{i};
            return;
        catch
        end
    end
end

1.3 端口结构探测

Simscape Electrical 模块有两类端口：

端口类型	字段名	用途
物理左端口	LConn	电气连接（如集电极、阳极、输入端）
物理右端口	RConn	电气连接（如发射极、阴极、输出端）
信号输入	Inport	控制信号（如门极驱动、参考值）
信号输出	Outport	测量信号（如电压/电流测量值）

ph = get_param(block_path, 'PortHandles');
n_LConn = length(ph.LConn);  % 物理左端口数
n_RConn = length(ph.RConn);  % 物理右端口数
n_Inport = length(ph.Inport); % 信号输入数
n_Outport = length(ph.Outport); % 信号输出数

1.4 参数名探测

不同版本的参数名可能不同，必须动态获取。

p = get_param(block_path, 'DialogParameters');
available_params = fieldnames(p);
% 常见参数名变化：
%   变压器: 'Rm' vs 'RmLm'
%   锯齿波: 'SeqTime' vs 'rep_seq_t', 'SeqVal' vs 'rep_seq_y'
%   整流桥: 'PowerElectronicDevice' vs 'Device'

---

阶段2：参数计算

Buck 变换器参数公式

占空比:    D = V_out / V_in
电感:      L = (V_in - V_out) * D / (f_sw * delta_I_L)
           delta_I_L = 0.2~0.4 * I_out（纹波电流系数）
电容:      C = delta_I_L / (8 * f_sw * delta_V_out)
           delta_V_out = 0.005 * V_out（纹波电压指标）
负载电阻:  R = V_out / I_out

PI 控制器初始参数

Kp = 0.005  （比例增益，从小开始）
Ki = 0.5    （积分增益，根据系统带宽调整）

Boost 变换器参数公式

占空比:    D = 1 - V_in / V_out
电感:      L = V_in * D / (f_sw * delta_I_L)
电容:      C = I_out * D / (f_sw * delta_V_out)

---

阶段3：模型搭建 + 连线

3.1 创建模型框架

new_system(model_name);
open_system(model_name);
set_param(model_name, 'StopTime', '0.3', 'Solver', 'ode23tb', 'MaxStep', '1e-5');
add_block(BLOCK_CANDIDATES.powergui{1}, [model '/powergui']);
set_param([model '/powergui'], 'SimulationMode', 'discrete', 'SampleTime', '1e-6');

3.2 核心约束

1. 不要用 Simulink 子系统封装 Simscape 物理连接。 子系统的 In1/Out1 是信号端口，不支持 LConn/RConn 物理端口。 所有 Simscape Electrical 模块必须放在模型顶层。

2. 同一个物理端口不能有多条连线。 如需重新连线，必须先删除旧线或删除冲突模块。

3. 接地模块（Ground）不要随意添加。 powergui 会提供电气参考点，多余接地会导致连线冲突。

3.3 Buck 变换器连线模板

电力连线（物理端口 LConn/RConn）：
  DC+(Rectifier/RConn1) ──→ IGBT/LConn1           [DC+到开关管集电极]
  IGBT/RConn1 ──────────→ I_sense/LConn1           [开关管E极到电流传感器]
  I_sense/RConn1 ───────→ L_out/LConn1             [电流传感器到电感]
  L_out/RConn1 ────────→ C_out/LConn1              [电感到输出电容(+)]
  C_out/RConn1 ────────→ DC-(Rectifier/RConn2)     [电容(-)到DC-]
  D_fw/LConn1 ─────────→ DC-(Rectifier/RConn2)     [续流二极管阳极到DC-]
  D_fw/RConn1 ─────────→ IGBT/RConn1               [续流二极管阴极到E极]
  C_out/LConn1 ────────→ R_load/LConn1             [负载并联]
  C_out/RConn1 ────────→ R_load/RConn1
  C_out/LConn1 ────────→ V_sense/LConn1            [电压测量并联]
  C_out/RConn1 ────────→ V_sense/LConn2

信号连线（Inport/Outport）：
  V_ref/1 ────→ Sum/1          [参考电压到误差(+)]
  V_sense/1 ─→ Sum/2           [反馈电压到误差(-)]
  Sum/1 ─────→ PI/1            [误差到PI控制器]
  PI/1 ──────→ CMP/1           [PI输出到比较器]
  Sawtooth/1 → CMP/2           [锯齿波到比较器]
  CMP/1 ─────→ IGBT/1          [PWM到IGBT门极(Inport)]

3.4 Boost 变换器连线模板

  DC+(V_in/RConn1) ──→ L_out/LConn1              [输入到电感]
  L_out/RConn1 ─────→ IGBT/LConn1                [电感到IGBT集电极]
  IGBT/RConn1 ──────→ DC-(V_in/RConn2)           [IGBT发射极到GND]
  D_fw/LConn1 ──────→ L_out/RConn1               [二极管阳极到电感输出端]
  D_fw/RConn1 ──────→ C_out/LConn1               [二极管阴极到输出电容(+)]
  C_out/RConn1 ─────→ DC-(V_in/RConn2)           [电容(-)到GND]
  R_load / V_sense / 控制回路：同 Buck

---

自动纠错机制

A. 阶段3 纠错（模型构建）

遇到错误时解析信息，按类型处理：

错误类型                          处理策略
─────────────────────────────────────────────────────
"没有名为X的参数"         → 调用阶段1.4 重新探测参数名
                              用正确参数名重试（最多3次）

"没有名为X的模块"         → 调用阶段1.2 查找替代路径
                              无替代则报告缺失模块

"第二个端口已有信号线连接"  → 删除冲突模块或旧连线后重试
                              注意：delete_line 语法要求精确匹配

"参数必须是 N×M 向量"      → 调整参数格式
                              如变压器winding需要[V R L]三元素

"模型名冲突/shadowing"    → 换模型名（加时间戳或序号）重试

"回调计算出错"             → 参数组合不兼容，逐个参数验证

纠错上限：每步最多重试 3 次，超过则报告给用户。

B. 阶段5 纠错（仿真结果）

问题类型                    调整策略（最多5轮）
─────────────────────────────────────────────
电压误差大 (>2%)         → 增大 Ki（加快积分）
                            检查占空比计算是否正确
                            检查变压器变比是否合理

纹波过大 (>2%)           → 增大输出电容 C
                            增大电感 L
                            或提高开关频率 f_sw

振荡/不稳定              → 减小 Ki
                            增大 Kp
                            或降低积分增益

发散/NaN                 → 检查求解器（ode23tb 适合电力电子）
                            减小 MaxStep
                            检查电路拓扑是否有开路/短路
                            检查 powergui 采样时间

---

阶段4：布局美化

布局原则

X轴（从左到右，信号流方向）：
  50~100    输入源（AC, DC 电源）
  150~300   前级变换（变压器, 整流桥）
  400~550   DC母线（滤波电容, 电压测量）
  600~1100  功率变换器（开关管, 二极管, 电感, 电容, 负载）
  600~1200  控制电路（参考值, 求和, PI, PWM, 比较器）

Y轴（从上到下，按通道排列）：
  30~80     powergui
  80~250    通道1 功率电路
  260~400   通道1 控制电路
  480~650   通道2 功率电路
  660~800   通道2 控制电路
  880~1050  通道3 功率电路
  1060~1200 通道3 控制电路

间距：通道间留 200px 空白，功率与控制间留 100px

Position 格式

set_param([model '/block'], 'Position', [left, top, right, bottom]);
% 例：宽60高40的模块放在 (600, 100)
set_param([model '/block'], 'Position', [600, 100, 660, 140]);

---

阶段5：仿真验证

% 编译检查
set_param(model, 'SimulationCommand', 'update');
pause(3);

% 运行仿真
simOut = sim(model, 'ReturnWorkspaceOutputs', 'on');

% 结果分析
Vout = simOut.Vout1;
n = length(Vout);
ns = round(20e-3 / mean(diff(simOut.tout)));  % 最后20ms
vs = Vout(end-ns:end);
vm = mean(vs);
vr = max(vs) - min(vs);
err = abs(vm - Vref) / Vref * 100;
ripple_pct = vr / Vref * 100;

达标标准

指标	合格	优秀
稳态电压误差	< 1%	< 0.1%
电压纹波	< 2%	< 0.5%
动态响应时间	< 100ms	< 50ms

---

阶段6：输出归档

保存内容：
1. .slx 模型文件 → 项目目录/03_MATLAB仿真/
2. 模型布局截图  → 项目目录/05_仿真结果图/
3. 输出电压图    → 项目目录/05_仿真结果图/
4. 稳态纹波图    → 项目目录/05_仿真结果图/
5. 桌面副本      → ~/Desktop/

截图命令：
print('-sModelName', '-dpng', 'path/to/img.png')

---

已知限制

1. 子系统不支持物理端口：所有 Simscape Electrical 模块必须在模型顶层
2. 部分版本无独立 MOSFET 模块：用 IGBT 替代（电气特性近似）
3. add_line 自动走线可能不美观：需要手动调整 Position
4. 已验证拓扑：Buck（多路）、AC→整流→DC母线
5. 待扩展拓扑：Boost、Buck-Boost、全桥逆变器、PFC、LLC 谐振

---

典型使用示例

示例：三路输出直流稳压电源

用户说："帮我做一个AC220V输入，输出200V/2A、110V/3A、60V/5A的多路直流稳压电源Simulink仿真"

执行流程：

1. 环境探测 → 发现 IGBT 可用但 MOSFET 不可用，用 IGBT 替代
2. 参数计算 → L=2mH/4.7mH/2.2mH, C=470uF, f_sw=20kHz
3. 创建模型 → AC→变压器→整流→DC母线→三路Buck（每路IGBT+Diode+LC+PI）
4. 布局 → 前级在左，三路垂直排列在右
5. 仿真 → 验证三路输出精度均 < 0.2%
6. 归档 → .slx + 波形图 + 桌面副本