1. 代码开发工具别只用来跑仿真:报告生成也该进版本管理
Simulink 模型跑完,波形拖进 Word,改一次参数就得重截六张图、重调一遍图号——这套动作我做过太多回,翻车往往不在仿真,而在报告。代码开发工具如果只用来启动 MATLAB、跑一次 sim,报告仍靠手工拼,模型和文档就是两条版本线。把 MATLAB 脚本、TeX Live 和一份 report_template.tex 接起来,让 Report_Generator.m 从仿真结果取数、填模板、编译 PDF,报告才能跟 .slx 一起迭代。这套做法适合已经能跑通 Simulink 闭环、但每次出报告都要耗掉半天的光伏并网仿真场景,也适合任何需要固定格式测试报告的嵌入式与控制系统项目。下面按工具链准备、脚本结构、模板调优、避坑和版本习惯五步走。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具选型:为什么让 MATLAB 调 TeX Live,而不是继续 Word
2.1 Word 手动排版在仿真迭代里的三个硬伤
光伏并网模型第一次跑通时,报告看起来只是“把图贴过去”。等模型改到第三版,问题就藏不住了。第一是图号对不上:关键波形有六幅,Word 里删一张、加一张,后面的图号全要手动改,正文里“见图 3”经常还指着旧图。第二是数据对不上:指标汇总表里的 THD 是手抄的,波形图是重新截的,两者来自不同时间的仿真,审阅的人一眼就能看出表格和曲线趋势不一致。第三是超标项漏标:材料里要求 THD 超标时用红色加粗,靠人眼在表格里找,改一次数据就要重新标一次,漏标是迟早的事。
这些问题的共同点不是 Word 不好用,而是报告里的数字、图号、颜色状态没有和模型输出建立固定关系。只要关系靠手工维护,模型每迭代一次,报告就多一次返工。代码开发工具的价值在这里不是“多写几行脚本”,而是把报告当成模型的一个构建产物:输入是仿真结果,输出是 PDF,中间过程可重复执行。
我一般会把报告返工拆成两类:一类是内容变化,比如指标从达标变成超标,这必须重新生成;另一类是版式变化,比如图号顺延、表格加注,这应该由模板自动处理。Word 把两类变化混在一起,每次都要人判断;MATLAB 脚本加 LaTeX 模板则把后一类交给模板,脚本只负责把最新数据填进去。这样改模型的人只需要关心数据对不对,不用再关心图号有没有顺延。
2.2 MATLAB + TeX Live 的分工:谁取数、谁排版、谁编译
这套工具链里,MATLAB 和 TeX Live 各管一段,边界清楚才不会互相打架。MATLAB 负责三件事:从 Simulink 结果里读出关键波形和指标,把数据替换进 LaTeX 模板的占位符,调用系统命令启动 TeX Live 编译。TeX Live 只负责排版:读 .tex 文件,处理图表、表格、交叉引用,输出 PDF。模板 report_template.tex 则是固定版式的载体,封面、仿真配置说明、六幅波形图、指标汇总表、附录这些结构都写在模板里,脚本不碰版式。
为什么不让 MATLAB 直接生成 PDF?MATLAB 也能拼报告,但固定条款号、表格自动加注、超标项红色加粗这些细节,用 LaTeX 模板表达更稳。模板里写一次 \caption{光伏并网电流波形(GB/T 19964-2012 6.2.1)},后面每幅图都按这个格式走;表格注释写在 table 环境里,表格挪到哪里注释跟到哪里。脚本只做字符串替换,模板负责“长什么样”,两边职责不混。
为什么不让 LaTeX 直接读 .slx?不现实。Simulink 模型是二进制格式,LaTeX 没有能力解析。正确路径是 MATLAB 先把结果落成中间文件,再让模板读中间结果。这个中间文件可以是 .mat,也可以是脚本生成的 .tex 片段,关键是它要能被重复生成。我一般会在脚本里固定一个中间目录,编译产生的 .aux、.log、临时 .tex 都放进去,源目录只留 .slx、模板和最终 PDF,找问题时不会翻半天。
2.3 最小工具链清单与版本确认
动手前先把工具链确认一遍,比写到一半发现 xelatex 不在 PATH 里要省事。材料里给出的环境是 MATLAB R2021b,模板文件名是 report_template.tex,主脚本是 Report_Generator.m。TeX Live 没有指定版本,只要求命令行能跑 xelatex。下面这张表是我一般会先核对的四项。
| 工具/文件 | 作用 | 确认方式 |
|---|---|---|
| MATLAB R2021b | 取数、替换占位符、调系统命令 | 能执行 system('xelatex --version') |
| TeX Live | 编译 .tex 生成 PDF |
命令行能直接跑 xelatex |
report_template.tex |
固定版式与图表格式 | 文件在脚本同目录或脚本能读到的路径 |
Report_Generator.m |
主流程入口 | 能读到仿真结果文件并写出临时 .tex |
确认命令不用写得太复杂,一段 MATLAB 检查就够:
matlab复制% 检查 TeX Live 是否在系统 PATH 里,避免脚本跑到一半才报错
[status, result] = system('xelatex --version');
if status ~= 0
error('未找到 xelatex,请先确认 TeX Live 已安装并加入 PATH');
end
disp(result);
system 返回的第一个值是退出码,0 表示命令执行成功;第二个值是命令输出,这里用来打印版本信息。把这段放在 Report_Generator.m 最前面,失败时直接停在工具链检查,不会等到编译阶段才报“找不到命令”。如果 status 非零,先解决 PATH 问题,不要急着改模板。
工具链确认完,还要确认模板能被单独编译。做法是在命令行进到模板目录,手动跑一次 xelatex report_template.tex,看能不能出 PDF。模板单独能过,后面脚本替换占位符出错时,才能判断是数据问题还是模板问题。这个顺序听起来笨,但比在脚本里一层层加打印要快。
3. 代码开发工具落地:Report_Generator.m 的三段结构
3.1 第一段:从 Simulink 结果里取数并落盘
Report_Generator.m 的第一段只做一件事:把仿真结果读进来,整理成模板需要的字段。材料里没有规定必须用哪种方式导出,常见做法是在 Simulink 里把关键信号送到工作区,或者仿真结束后用 save 落成 .mat。我一般会在模型旁边放一个固定的结果文件,脚本只认这个文件名,避免每次手动选文件。
matlab复制% 读取仿真结果,统一整理成报告模板需要的字段
S = load('sim_result.mat'); % 仿真前把关键信号存成 mat
t = S.tout; % 时间轴
i_grid = S.i_grid; % 并网电流波形
thd = S.thd; % THD 指标,单位 %
这段代码里,load 读的是仿真结果文件,变量名 tout、i_grid、thd 要按实际模型改。thd 单位是百分比,后面写进模板时不要再乘 100。取数段不要做排版,也不要在里面拼接 LaTeX 字符串,否则数据问题和格式问题会混在一起,排查时看不出是哪一层出错。
取数段还要做一次基本校验:波形长度和时间轴长度是否一致,THD 是不是空值。常见做法是用 assert 或 if isempty 提前停住,不要等到 PDF 生成出来才发现表格里是空白。材料里有一句话我印象很深:报告里的每一个数字都应该能在示波器上被实测捕捉。取数段就是保证这句话成立的地方,读不到就停,不要用默认值糊弄过去。
3.2 第二段:把数据填进 LaTeX 模板
第二段负责把数据填进模板。模板里预先留好占位符,比如 <<THD>>、<<MODEL>>,MATLAB 用 fileread 读整个模板,再用 strrep 做纯文本替换,最后写出一份临时 .tex。这样做的好处是模板仍然是普通 LaTeX 文件,排版的人可以直接改模板,不需要懂 MATLAB。
matlab复制% 读取模板,替换占位符,生成临时 tex
tpl = fileread('report_template.tex');
tpl = strrep(tpl, '<<THD>>', sprintf('%.1f', thd));
tpl = strrep(tpl, '<<MODEL>>', '光伏并网闭环模型');
fid = fopen('report_build.tex', 'w');
fprintf(fid, '%s', tpl);
fclose(fid);
fileread 按文本方式读入整个模板,适合模板不大的场景;strrep 是纯字符串替换,不解析 LaTeX 语法,所以占位符要选不容易和正文冲突的写法,比如双尖括号。sprintf('%.1f', thd) 控制小数位,报告里指标保留一位小数就够了,位数太多反而让表格看起来很乱。fopen 的 'w' 表示覆盖写,临时文件每次重新生成,不要追加。
占位符替换有一个容易忽略的点:LaTeX 的特殊字符。百分号在 LaTeX 里是注释符,5.3% 会把后面内容全注释掉,必须写成 5.3\%。如果 thd 直接替换进模板,替换后的字符串要带上转义。我一般会在模板里把百分号写死,占位符只替换数字,比如模板写 THD = <<THD>>\%,脚本只替换 <<THD>>。这样脚本不用关心 LaTeX 转义,模板作者自己控制格式。
3.3 第三段:调 TeX Live 编译并检查退出码
第三段启动 TeX Live 编译。材料里写的是“用 MATLAB 调用 TeX Live 编译”,具体命令可以用 system 拼。编译要跑两遍:第一遍生成 .aux,第二遍才能把图表编号和交叉引用填对。只跑一遍时,PDF 里的图号可能是问号,这个坑后面还会细说。
matlab复制% 调 xelatex 编译,跑两遍解决交叉引用
for k = 1:2
[status, log] = system('xelatex -interaction=nonstopmode report_build.tex');
if status ~= 0
error('第 %d 遍编译失败,查看 report_build.log:%s', k, log);
end
end
-interaction=nonstopmode 让 LaTeX 遇到错误时不要停下来等输入,否则脚本会卡住。status 非零表示这一遍编译失败,直接把遍数和日志内容抛出来,不要继续跑第二遍。log 里通常能看到缺宏包、缺文件或语法错误,先看第一行报错,不要从最后一页往前翻。
编译段还要注意工作目录。system 执行命令时用的是 MATLAB 当前目录,如果临时 .tex 写在别的目录,命令里要带路径,或者先用 cd 切过去。我一般会在脚本开头把当前目录切到模板所在目录,编译完再切回来,避免路径问题。编译成功后,把 report_build.pdf 改名成和模型同名的 PDF,放到固定输出目录,这一步放在最后,失败时不会留下半份报告。
4. 代码开发工具调优:report_template.tex 里的图表、表格与超标红字
4.1 图表标题带标准条款号
材料里的报告要求图表标题包含标准条款号,例如“图1 光伏并网电流波形(GB/T 19964-2012 6.2.1)”。这个格式不要写在 MATLAB 脚本里,应该写进模板的 \caption,这样每幅图都按同一规则生成,脚本只负责换图片文件名。
latex复制\begin{figure}[htbp]
\centering
\includegraphics[width=0.8\textwidth]{fig1_current.pdf}
\caption{光伏并网电流波形(GB/T 19964-2012 6.2.1)}
\label{fig:current}
\end{figure}
\caption 里直接带条款号,正文引用时用 \ref{fig:current},不要在正文里手写“图1”。\label 放在 \caption 后面,否则引用会指错。width=0.8\textwidth 控制图片宽度,六幅波形图用同一宽度,版面看起来才整齐。图片文件建议用 PDF 或 PNG,文件名用英文,避免编译时找不到。
模板里六幅关键波形图可以做成六个 figure 环境,每幅图对应一个固定文件名,比如 fig1_current.pdf 到 fig6_voltage.pdf。脚本不替换图片本身,只保证仿真结果更新后重新导出这些文件。这样模板和脚本的分工很清楚:模板管图号和图题,脚本管数据文件。
4.2 表格自动加注
材料里要求表格自动添加“注:数据由 Simulink 模型在 R2021b 环境下仿真获得”。这条注释要跟着表格走,不要写在表格外面,否则表格换页时注释可能留在上一页。
latex复制\begin{table}[htbp]
\centering
\caption{并网指标汇总}
\begin{tabular}{lcc}
\hline
指标 & 仿真值 & 是否达标 \\
\hline
THD & 5.3\% & 否 \\
\hline
\end{tabular}
\par\smallskip
\footnotesize 注:数据由 Simulink 模型在 R2021b 环境下仿真获得。
\end{table}
注释放在 table 环境内部,用 \par\smallskip 和表格隔开,\footnotesize 让注释比正文小一号。R2021b 是材料给出的仿真环境版本,换环境时改这一处即可。表格列格式 lcc 表示第一列左对齐、后两列居中,指标名长短不一时左对齐更好读。5.3\% 里的百分号必须转义,否则会把后面的 & 和 \\ 注释掉,表格直接报错。
指标汇总表里“是否达标”这一列建议由脚本根据阈值生成,不要手写。模板里可以留一个占位符,脚本判断 THD 是否超过限值,替换成“是”或“否”。这样表格里的结论和正文里的红字使用同一套判断,不会出现表格写“否”、正文却没标红的情况。
4.3 超标项红色加粗
材料里给出的写法是 THD = \textcolor{red}{\textbf{5.3\%}}。红色加粗适合放在指标汇总表或正文结论里,不要整表标红,否则读者找不到重点。
latex复制\usepackage{xcolor}
% ...
THD = \textcolor{red}{\textbf{5.3\%}}
xcolor 宏包要放在导言区,\textcolor{red} 只影响后面花括号里的内容,\textbf 再加粗。颜色名用 red 就够,不需要自定义 RGB。百分号仍然要写 \%,红色和转义是两件事,不要因为加了颜色就忘了转义。
模板里可以把超标项做成一个命令,比如 \newcommand{\fail}[1]{\textcolor{red}{\textbf{#1}}},正文里写 \fail{5.3\%}。这样以后换颜色或改加粗规则只改一处,不用满篇找 \textcolor。这个命令放在导言区,模板作者维护,脚本不碰。
5. 代码开发工具避坑:中文、路径、编译次数与图表编号
5.1 中文标题编译报错或输出乱码
现象:xelatex 编译到中文标题时报 Missing character,或者 PDF 里中文变成空白。原因通常是模板没有加载中文支持,或者用了 pdflatex 而不是 xelatex。材料里的图表标题是中文,模板必须能处理中文。
解决:模板用 ctexart 文档类,或者在导言区加 \usepackage{ctex};编译命令固定用 xelatex,不要用 pdflatex。如果模板是从英文模板改的,先检查文档类,再检查有没有手动设置不存在的字体。中文能正常输出后,再回头看图表标题,不要一开始就怀疑数据。
5.2 路径里有空格或中文,编译中途失败
现象:MATLAB 里 system 返回非零,日志里提示找不到 report_build.tex 或图片文件。原因多半是路径带空格或中文,system 拼命令时被拆开。Windows 下路径空格很常见,MATLAB 当前目录又经常是桌面或文档目录。
解决:脚本开头 cd 到模板所在目录,所有文件名用英文;如果必须带路径,给路径加双引号,或者用 fullfile 拼好再传给 system。临时文件统一放 build 子目录,源目录只留模板和最终 PDF。路径问题解决后,编译日志会干净很多,不会一堆“找不到文件”。
5.3 第一次编译后图表编号变成问号
现象:PDF 里图号显示 ??,正文引用也变成问号。原因不是图没插进去,而是 LaTeX 的交叉引用需要两遍编译:第一遍写 .aux,第二遍才读得到编号。只跑一遍 xelatex 就会出现这个问题。
解决:脚本里固定跑两遍,第二遍前不要删 .aux。如果两遍后还是问号,检查 \label 是不是写在 \caption 后面,以及引用时有没有用 \ref。还有一种情况是编译中途报错,.aux 没写完整,先解决报错再谈编号。
5.4 超标红字没生效或百分号报错
现象:PDF 里红色没出现,或者编译报 Missing $ inserted。前者通常是没加载 xcolor,后者是百分号没转义。材料里的 5.3\% 已经带了转义,但脚本替换时如果只替换数字、模板里写 %,仍然会出问题。
解决:导言区加 \usepackage{xcolor};模板里所有百分号写成 \%;脚本替换时不要把转义符吃掉。红色只用在超标项,不要给整行加红。改完模板先手动编译一次,确认颜色和百分号都正常,再让脚本跑。
5.5 报告和模型版本对不上
现象:PDF 里的波形是旧模型,.slx 已经改过两版。原因通常是脚本手动跑、想起来才跑,或者 PDF 用了通用文件名,分不清对应哪版模型。材料里提到一个习惯:每次模型更新后运行 Report_Generator.m,PDF 与 .slx 同名存放。
解决:把“跑报告”固定成模型更新后的最后一步,PDF 文件名和模型名一致,中间文件放 build 目录;脚本开头记录生成时间和模型名,写进 PDF 封面或页脚。这样拿任意一份 PDF,都能在目录里找到同名 .slx。版本对不上时,先看 PDF 里的生成时间,不要靠回忆。
6. 代码开发工具进阶:让报告与 .slx 同名同版本
报告生成跑通之后,真正省时间的是版本习惯。材料里那个做法我一直保留:PDF 与 .slx 同名存放,每次模型更新后强制跑一遍 Report_Generator.m。文件名相同,目录里一眼就能配对,不用在 PDF 属性里翻半天。中间文件全部丢进 build 目录,源目录只留模型、模板和最终 PDF,找问题时不会把 .aux 和 .log 当成正式文件。
脚本开头可以加一段最小检查,防止拿旧数据出报告:
matlab复制% 统一输出目录,PDF 与模型同名
modelName = 'pv_grid_model';
outDir = fullfile(pwd, 'report_out');
if ~exist(outDir, 'dir'); mkdir(outDir); end
pdfFile = fullfile(outDir, [modelName '.pdf']);
assert(exist('sim_result.mat', 'file') == 2, '缺少仿真结果,先跑模型');
modelName 换成实际模型名,outDir 是固定输出目录;assert 在结果文件不存在时直接停住,避免生成一份只有封面和空表格的 PDF。这个检查看起来多余,但比事后发现报告是旧数据要省心。PDF 生成后不要手动改名,脚本里用 movefile 或直接指定输出名,改名这一步也交给代码。
还有一个技巧:在模板页脚放生成时间和模型名,用占位符替换。这样打印出来的每一页都能追溯到哪次仿真,审阅的人不用翻封面。生成时间不要精确到秒,日期加时分就够,太长反而占版面。模型名用英文或拼音,避免 PDF 书签里出现乱码。
从那以后我每次改完模型,都先把 Report_Generator.m 跑一遍,看到 PDF 里的波形和表格都更新了,才去动别的文档。不是因为这套流程多高级,而是它把“报告”从手工活变成了模型的一个输出,改完模型不跑一遍,心里就不踏实。希望帮到你。
