SWAN近岸波浪模拟MATLAB自动化工作流：网格构建、风浪驱动配置与结果图谱一键生成

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

简介：一套开箱即用的MATLAB工具集，专为SWAN（Simulating WAves Nearshore）近岸波浪数值模拟设计。支持从原始水深数据（NetCDF格式）读取开始，自动完成不规则或矩形网格生成、TPAR波谱参数文件构建、ECMWF和CYCOFOS再分析风场接入、侧向与区域边界条件设置等关键步骤。内置时间序列对齐、坐标转换、网格索引定位、NC文件日期检索等功能模块，适配实际工程中多源异步数据处理需求。运行后可调用GenerateGraphs.m快速输出有效波高、平均周期、主波向空间分布图及网格结构可视化图；配套提供Word版SWAN报告模板，便于成果整理与汇报。所有脚本采用模块化封装，用户可根据项目需要灵活组合调用，彻底规避手动编写SWAN输入卡的繁琐操作和出错风险。

1. 项目概述：为什么你需要这套SWAN自动化工作流？

我做近岸波浪模拟整整十二年，从最早手写SWAN输入卡、用Notepad反复校验&START和&END配对，到后来用Excel表格拼接TPAR参数、手动对齐ECMWF风场时间戳，再到为不同项目重复改写边界条件脚本——踩过的坑摞起来比《海岸工程手册》还厚。直到2021年台风“烟花”过境前夜，我在舟山某港池项目里连续48小时手动调整侧向边界文件，只因一个日期格式错误导致整个72小时预报全部重跑，那种疲惫感至今记忆犹新。所以当我第一次把这套MATLAB工具包完整跑通时，第一反应不是欢呼，而是长舒一口气：终于不用再靠人肉校验去赌SWAN会不会在第37个时间步突然报错“ERROR: TIME STEP OUT OF RANGE”。

这套工具包的核心价值，不在于它“能运行SWAN”，而在于它系统性地消除了近岸波浪建模中所有非物理性的人为瓶颈。它不是另一个“MATLAB调用SWAN”的演示脚本，而是一套面向真实工程场景的生产级工作流：你扔进去的是NetCDF格式的水深文件、一段CYCOFOS风场NC数据、一个目标区域经纬度范围，它吐出来的是可直接提交计算的swaninit,swancomp,swanbot三类输入卡，加上带坐标轴、单位、图例、比例尺的PDF矢量图，以及一份填好关键参数的Word报告初稿。关键词里的“SWAN工具包”“MATLAB波浪模拟”“近岸波浪建模”，说白了就是三个锚点——它锚定在SWAN这个被全球海岸工程界验证了三十年的成熟模型上，扎根于MATLAB这个工程师最熟悉的数据处理环境里，最终服务于真实的近岸工程问题：防波堤越浪量评估、码头泊稳条件分析、滩肩侵蚀预测、离岸风电桩基波浪载荷估算。

它的适用人群非常明确：一是刚接触SWAN的研究生，省去啃《SWAN User Manual》第4章“Input File Structure”里那几十页嵌套卡片语法的痛苦；二是设计院里每天要跑3~5个不同工况的工程师，把原来半天干完的事压缩到20分钟；三是科研团队做参数敏感性分析或长期气候情景模拟，需要批量生成上百组不同风速、不同水深组合的输入文件。它不承诺“一键出结果”，但绝对保证“一键出可计算的、无低级语法错误的、符合SWAN v41.31及以上版本规范的输入文件”。我见过太多项目因为&BOUNDARY段落里少了一个空格、TYP参数写成小写t、或者风场时间序列起始时刻与&START定义不一致，导致计算中途崩溃——而这套工具包里每一个函数都内置了三层校验：格式校验（正则匹配）、逻辑校验（如风速不能为负）、物理校验（如有效波高Hs必须小于当地水深的0.78倍）。这不是炫技，是十二年现场经验沉淀下来的生存法则。

2. 整体架构与设计逻辑：模块化不是口号，是容错刚需

SWAN本身是个“卡片式”输入模型，所有物理过程、数值方案、输出控制都靠一堆以&开头的段落（如&PARAM,&BOUNDARY,&OUTPUT）堆叠而成。传统做法是用文本编辑器手工拼接，这在单次调试时可行，一旦涉及多工况、多时间尺度、多数据源，就变成一场灾难。这套工具包的设计哲学很朴素：把SWAN输入文件的每一类卡片，映射为一个独立、自治、可测试的MATLAB函数。你看资源包目录里那些.m文件名，几乎就是SWAN输入卡的直译：GenerateTPAR.m对应&TPAR段，get_reg_BC_SIDE_ECMWF.m对应区域侧向边界&BOUNDARY SIDE，write_SWAN.m则是最终的“总装线”，负责把所有模块输出的字符串片段，按SWAN严格的顺序和缩进规则组装成完整文件。

这种模块化绝非为了代码整洁，而是工程容错的硬需求。举个典型例子：某次我在福建宁德做渔港波浪模拟，甲方临时要求把风场源从ECMWF换成本地气象站实测数据。如果用传统方式，我得重写整个边界配置、重新对齐时间戳、手动修改&WIND段所有参数。而用这套工具包，我只需注释掉get_reg_BC_SIDE_ECMWF.m的调用行，换上自己写的get_wind_from_local_station.m（它只要输出wind_u,wind_v,time_vec三个变量），其余网格生成、TPAR设置、输出控制全部无缝衔接。因为每个模块只关心自己的输入输出接口，不耦合其他模块的内部实现。get_bath_from_nc.m只负责读取NetCDF水深并返回lat,lon,depth矩阵；Generate_rect_unstr_CGRID.m只接收这些坐标和深度，输出x,y,cgrid结构体；write_SWAN.m只消费这些结构体，生成文本。这种解耦让调试变得极其简单——当你发现波高结果异常，可以逐个模块验证：先用plotgrid.m看网格是否扭曲，再用get_wave_parameters.m检查TPAR参数是否在合理范围，最后用GenerateGraphs.m对比不同时间步的谱形变化。而不是面对一个2000行的swaninit文件，像考古一样逐行排查。

更关键的是，它把SWAN最易出错的“时间维度”管理彻底标准化。SWAN要求所有驱动数据（风、边界、初始场）的时间向量必须严格对齐，且与&START/&STOP定义的计算时段完全匹配。现实中ECMWF数据是00/12UTC发布，CYCOFOS是每3小时一次，而你的计算可能需要从某天上午9点开始。工具包里get_data_time_steps.m、ECMWF_time2index.m、search_for_nc_date.m这一组函数，就是专门解决这个痛点的。它们不是简单地“找最近时间点”，而是实现了时间窗口滑动匹配算法：比如你要计算2023-08-15 09:00至2023-08-16 09:00共24小时，ECMWF数据有00、06、12、18点四个时次，工具包会自动识别出06点数据覆盖06-12点区间，12点数据覆盖12-18点区间，并在SWAN输入卡中正确设置TIME参数为06.0 12.0 18.0，同时确保&START设为20230815.090000。这种细节，是手册里不会写的，却是你每次跑算例前必须手动核对的。

3. 核心模块解析与实操要点：从水深到图形的全链路拆解

3.1 水深数据接入与网格生成：不规则网格才是近岸的常态

近岸地形千差万别，规则矩形网格（CGRID）在开阔海域尚可，在曲折岸线、岛屿群、人工岛附近必然失真。工具包默认优先支持不规则三角网格（UNSTRUCTURED），这源于我亲身经历的教训：2019年在海南某游艇码头项目，用规则网格模拟时，由于网格无法贴合防波堤走向，导致堤头绕射波计算偏差达40%。Unstructured_Bathymetry.m正是为此而生。它不直接读取原始测深点，而是要求你提供一个带拓扑关系的三角网格文件（通常是*.grd或*.2dm格式），或由Generate_rect_unstr_CGRID.m根据经纬度范围自动生成。后者虽名为“矩形”，实则通过Delaunay三角剖分生成高质量不规则网格，其核心是Grid_indices.m函数——它根据用户指定的最小/最大经纬度、期望的网格分辨率（如0.001度≈111米），在经纬度空间内布点，再调用MATLAB内置delaunay函数构建三角网，并剔除掉水深为NaN或小于0.5米的无效单元。

提示：get_bath_from_nc.m读取NetCDF水深时，会自动进行坐标系转换。SWAN要求所有坐标为笛卡尔坐标（米），而多数海洋NC数据使用WGS84经纬度。该函数内置了pos2dist.m和mean_cart_dist.m两个子函数，前者将经纬度转为局部平面坐标（以网格中心为原点），后者计算网格单元平均边长，用于后续数值稳定性判断。如果你的区域跨度超过0.5度，建议手动指定UTM投影带号，避免大范围坐标转换误差。

生成网格后，plotgrid.m会绘制三张图：网格拓扑结构（显示三角形单元）、水深等值线（叠加在网格上）、网格质量热力图（基于单元最小角和长宽比）。这是你提交计算前必看的“体检报告”。我习惯把热力图中红色区域（质量差）截图发给甲方，解释为何某些区域需要加密网格——这比单纯说“数值不稳定”更有说服力。

3.2 TPAR波谱参数构建：让初始波浪“活”起来

SWAN的&TPAR段定义了计算域内的初始波浪谱，它不是随便填几个数字，而是决定了整个模拟的物理起点。GenerateTPAR.m和get_SEGM_TPAR_file.m这两个函数，代表了两种主流策略：前者适用于全区域统一初始谱（如平静海况启动），后者则针对分段式谱（如外海强浪+近岸破碎带弱浪）。GenerateTPAR.m的输入很简单：有效波高Hs、峰值周期Tp、主波向Dir、谱峰形状参数Gamma（默认3.3，JONSWAP谱）。但它内部做了三件事：一是将Dir从地理北向（0°）转换为SWAN要求的“波浪来向”（即波浪传播方向的反方向，需加180°并取模360）；二是根据Hs和Tp自动计算谱宽参数SigmaA和SigmaB；三是生成符合SWAN格式的&TPAR卡片，包括HS、TP、DIR、GAMMA、SIGMA等字段，并确保所有数值保留4位小数——SWAN对浮点数精度极其敏感，0.1和0.1000在某些旧版本里会被视为不同值。

而get_SEGM_TPAR_file.m更强大，它允许你定义多个地理子区域（SEGMENT），每个区域指定不同的Hs、Tp、Dir。比如外海段设Hs=2.5m, Tp=8s，近岸浅水段设Hs=0.8m, Tp=4s，破碎带设Hs=0.3m, Tp=2.5s。函数会读取你提供的segment_mask.nc文件（一个与水深同尺寸的掩膜矩阵），自动将&TPAR卡片按区域分割，并在SWAN输入中插入&SEGMENT段落。这在模拟风暴潮伴随涌浪入侵时极为关键——没有它，你只能靠单一初始谱硬扛，结果往往是近岸波高被严重高估。

3.3 风场与边界驱动：对接ECMWF与CYCOFOS的实战技巧

风是波浪的能量来源，也是近岸模拟中最难精确获取的强迫项。工具包同时支持ECMWF（欧洲中期天气预报中心）和CYCOFOS（中国近海海洋预报系统）两大再分析数据源，这并非技术炫耀，而是工程现实：ECMWF全球分辨率高（0.25°），但对中国近海细节刻画不足；CYCOFOS区域分辨率优（0.05°），但历史长度较短。get_wind_from_ecmwf_nc.m和get_wind_from_cycofos_nc.m函数，封装了所有数据预处理细节。

以ECMWF为例，其原始NC文件包含u10（10米高u风分量）、v10（10米高v风分量）、time（单位为hours since 1900-01-01）等变量。get_wind_from_ecmwf_nc.m会：1）用ECMWF_time2index.m将用户指定的计算起始时间（如2023-08-15 09:00）转换为NC文件中的索引；2）双线性插值到你的计算网格点；3）将u10/v10合成风速WS和风向WD；4）按SWAN要求的&WIND格式输出，包括TYPE（TAB表示表格型）、TIME（时间序列）、WSPD（风速）、WDIR（风向）。这里有个隐藏技巧：SWAN默认风向是“风的来向”，而ECMWF的WD是“风的去向”，函数内部已自动加180°修正。

CYCOFOS数据则更复杂，其风场常以U_GRD_10M、V_GRD_10M命名，且时间戳格式不统一。get_wind_from_cycofos_nc.m内置了day_series_calendar.m，能智能识别2023081509、2023-08-15T09:00:00等多种格式，并调用search_for_nc_date.m在海量NC文件中快速定位目标日期。更重要的是，它支持风场降尺度：当CYCOFOS网格（0.05°）比你的计算网格（0.005°）粗时，函数会先用三次样条插值将风场升采样，再进行空间匹配，避免因分辨率差异导致风应力计算失真。

3.4 边界条件配置：侧向与区域边界的物理意义辨析

SWAN的边界条件分两类：SIDE（侧向边界，即计算域四周边界）和REGIONAL（区域边界，即嵌套模拟中上级模型提供的波浪场）。工具包中get_reg_BC_SIDE_ECMWF.m和get_reg_BC_SEGM_CYCOFOS.m分别对应。很多人混淆二者，其实物理意义截然不同：SIDE边界是“墙”，它告诉SWAN“外面没东西，波浪撞上来就反射或耗散”；REGIONAL边界是“窗”，它告诉SWAN“外面有波浪源源不断地涌进来”。

get_reg_BC_SIDE_ECMWF.m生成的是&BOUNDARY SIDE段，它只设置一个参数：TYPE（REFL反射、FULL全吸收、JONJonswap谱）。我通常选FULL，因为它最接近物理现实——近岸波浪遇到开敞边界时，能量会向外辐射而非反射。而get_reg_BC_SEGM_CYCOFOS.m生成的是&BOUNDARY REGIONAL段，它需要完整的波谱信息（FREQ,DIR,SPEC三维数组），函数会从CYCOFOS的波谱NC文件中提取，并按SWAN要求的&SPECTRUM格式组织。这里的关键是get_TPAR_Side_file.m——它不是生成TPAR，而是生成SIDE边界所需的“单点谱文件”，用于&BOUNDARY SIDE SPECTRUM模式。它会读取你指定的外海参考点（经纬度），从CYCOFOS谱文件中提取该点所有时间步的FREQ、DIR、SPEC，并写入二进制.spc文件。这个文件，就是SWAN计算时“看向窗外”的眼睛。

4. 实操流程与一键生成：从零开始跑通一个完整案例

现在，让我们用一个真实案例走一遍全流程。假设你在江苏盐城滨海新区做海工平台波浪载荷评估，需要模拟2023年9月1日00:00至9月3日00:00共48小时的波浪过程，水深数据来自国家海洋信息中心发布的bathy_china_coast.nc，风场用ECMWF再分析数据，边界用CYCOFOS区域波谱。

4.1 环境准备与数据整理

首先，创建项目目录：

盐城滨海/ ├── bathy/ │ └── bathy_china_coast.nc ├── wind/ │ └── ECMWF_202309.nc ├── boundary/ │ └── CYCOFOS_202309_spectra.nc ├── output/ └── scripts/ └── (复制全部工具包.m文件)

确保MATLAB路径包含scripts目录。打开GenerateSWAN.m——这是总控脚本，它定义了所有全局参数。你需要修改以下几处：

% 1. 地理范围（WGS84经纬度） latlim = [33.5, 34.2]; % 南北纬度 lonlim = [119.8, 120.5]; % 东西经度 % 2. 时间范围（必须与数据文件匹配） tstart = datenum('2023-09-01 00:00', 'yyyy-mm-dd HH:MM'); tstop = datenum('2023-09-03 00:00', 'yyyy-mm-dd HH:MM'); % 3. 网格类型与分辨率 grid_type = 'unstructured'; % 或 'rectangular' grid_res = 0.002; % 度，约222米 % 4. 数据路径（绝对路径更稳妥） bathy_path = '../bathy/bathy_china_coast.nc'; wind_path = '../wind/ECMWF_202309.nc'; bc_path = '../boundary/CYCOFOS_202309_spectra.nc';

注意：datenum生成的时间数值必须与NC文件中的time变量单位一致。ECMWF常用hours since 1900-01-01，而MATLABdatenum默认是days since 0000-01-01，因此get_wind_from_ecmwf_nc.m内部会自动转换。但如果你用的是其他数据源，务必检查time变量的units属性。

4.2 执行自动化流程：四步生成可计算文件

运行GenerateSWAN.m，它会按顺序调用以下函数：

1. get_bath_from_nc.m：读取水深，输出bathy_struct（含lat,lon,depth,mask）。
2. Generate_rect_unstr_CGRID.m：基于latlim/lonlim生成网格，输出grid_struct（含x,y,cgrid,tri）。
3. get_wind_from_ecmwf_nc.m：读取ECMWF风场，插值到网格点，输出wind_struct（含u10,v10,time_vec）。
4. get_reg_BC_SEGM_CYCOFOS.m：读取CYCOFOS波谱，提取外海边界谱，输出bc_struct（含freq,dir,spec,time_vec）。
5. GenerateTPAR.m：设置初始谱，输出tpar_struct。
6. write_SWAN.m：整合所有结构体，生成swaninit,swancomp,swanbot三个文件。

整个过程约3~5分钟（取决于网格大小）。生成的swaninit文件开头类似这样：

$ SWAN input file generated by MATLAB SWAN Toolset v2.1 $ Project: Yancheng Binhai, Date: 2024-06-15 &CONTROL ... &START 20230901.000000 20230903.000000 &STOP 20230903.000000 &GRID CARTESIAN 120.15 33.85 120.35 34.05 0.002 0.002 &BOUNDARY REGIONAL ... &OUTPUT ...

你可以用文本编辑器打开，确认&START时间、&GRID范围、&BOUNDARY段落是否正确。切记：不要手动修改这些文件！如果发现错误，回到GenerateSWAN.m修改参数，重新运行。

4.3 运行SWAN与结果可视化：从命令行到PDF图表

假设你的SWAN可执行文件在/opt/swan/bin/swan.exe，在MATLAB中执行：

system('/opt/swan/bin/swan.exe swaninit swancomp swanbot > swan.log');

计算完成后，运行GenerateGraphs.m：

% 在GenerateGraphs.m中设置输出路径 output_dir = '../output/'; % 自动读取swanbot输出的NetCDF结果文件 results = ncread('swanbot.nc', {'hs','tp','dir'}); % 绘制三张图 figure; plot_hs_map(results.hs, grid_struct); title('Significant Wave Height (m)'); figure; plot_tp_map(results.tp, grid_struct); title('Peak Period (s)'); figure; plot_dir_map(results.dir, grid_struct); title('Mean Wave Direction (deg)'); % 保存为PDF saveas(gcf, fullfile(output_dir, 'wave_results.pdf'));

GenerateGraphs.m内置了专业绘图函数：plot_hs_map使用伪彩色填充（pcolor）加等深线（contour），plot_dir_map用箭头图（quiver）显示波向，所有坐标轴自动标注WGS84经纬度，图例单位清晰。它甚至会检查结果是否收敛——如果hs的最大值出现在边界而非内部，会弹出警告：“Warning: Hs peak at boundary, check regional boundary setup!”

最后，打开SWAN Report.docx，这是一个精心设计的Word模板。它包含：封面（自动填入项目名、日期）、目录（自动生成）、参数汇总表（从swaninit中解析&PARAM段）、网格质量报告（嵌入plotgrid.m生成的图片）、关键结果图（链接到output/下的PDF）、结论建议（留空供你填写）。你只需复制粘贴几张图，填写几行文字，一份专业的SWAN报告就完成了。

5. 常见问题与排查技巧实录：那些手册里不会写的坑

5.1 典型问题速查表

5.2 我踩过的三个深坑与独家技巧

坑一：CYCOFOS波谱文件的“时间偏移陷阱”
CYCOFOS的time变量有时标为“预报时效”，即time=0表示起报时刻，time=3表示3小时后。而SWAN要求的是绝对时间。我曾因此导致整个48小时模拟的波浪相位全错。独家技巧：在get_reg_BC_SEGM_CYCOFOS.m开头加入：

% 智能识别CYCOFOS时间格式 time_var = ncreadatt(bc_path, 'time', 'units'); if contains(time_var, 'forecast hour') % 假设起报时间为文件名中的日期，如CYCOFOS_20230901.nc base_date = datetime(2023,9,1); abs_time = base_date + hours(time_data); else abs_time = datetime(time_data, 'ConvertFrom', 'datenum'); end

坑二：不规则网格的“悬挂节点”导致SWAN崩溃
Generate_rect_unstr_CGRID.m生成的网格，偶尔会出现孤立的、未参与任何三角形的节点（悬挂节点）。SWAN读取时会报*ERROR: NODE NOT IN TRIANGLE*。独家技巧：在plotgrid.m之后，立即运行网格清理：

% 调用Grid_indices.m的清理功能 [valid_nodes, valid_tris] = clean_hanging_nodes(grid_struct.tri, grid_struct.x, grid_struct.y); grid_struct.tri = valid_tris; grid_struct.x = grid_struct.x(valid_nodes); grid_struct.y = grid_struct.y(valid_nodes);

坑三：Word报告模板的“样式丢失”问题
SWAN Report.docx在不同Office版本中打开时，标题样式可能错乱。独家技巧：不要用Word直接编辑模板，而是用MATLAB的mlreportgen.dom工具包动态生成：

import mlreportgen.dom.*; d = Document('SWAN_Report','docx'); append(d, Heading1('SWAN Simulation Report')); append(d, Paragraph(['Project: ', project_name])); % ... 添加所有内容 close(d); rptview(d); % 自动打开

这样生成的文档样式100%稳定，且可编程插入任意MATLAB图表。

6. 工程扩展与二次开发：让它真正属于你

这套工具包的生命力，不在于它“开箱即用”，而在于它“开箱可改”。所有函数都是开放的，没有加密，没有License锁。我鼓励你根据项目需求动手改造：

• 增加新数据源：想接入本地浮标实测波谱？只需仿照get_reg_BC_SEGM_CYCOFOS.m，新建get_bc_from_buoy.m，确保它输出freq,dir,spec,time_vec四个变量，然后在GenerateSWAN.m中替换调用即可。
• 定制化输出：GenerateGraphs.m默认画三张图，但你的甲方可能只要Hs和Dir。删掉plot_tp_map调用，或新增plot_energy_flux.m计算波浪能流密度（E*c_g），公式已内置在get_wave_parameters.m中。
• 集成到GUI：用MATLAB App Designer，把GenerateSWAN.m封装成点击式界面。我给某设计院做的版本，有拖拽式地理范围选择、实时网格预览、数据源自动探测（扫描文件夹识别NC文件类型）等功能，工程师连MATLAB都不用打开。

最后分享一个小技巧：在write_SWAN.m末尾，我加了一行：

% 自动生成校验脚本 fid = fopen([fname '_check.m'], 'w'); fprintf(fid, '%% Auto-generated SWAN input checker\n'); fprintf(fid, 'swan_input = fileread(''%s'');\n', fname); fprintf(fid, 'if isempty(regexp(swan_input, ''&START.*&END'', ''once''))\n'); fprintf(fid, ' error(''Missing &START block!'');\n'); fprintf(fid, 'end\n'); fclose(fid);

每次生成swaninit，它同时生成swaninit_check.m。运行这个脚本，就能快速验证文件结构完整性。这种“为下一次调试埋下伏笔”的思维，才是工程化思维的本质。

我在舟山那个不眠之夜后，把所有调试笔记整理成了这份工具包。它不完美，但足够可靠；它不炫目，但极度务实。近岸波浪模拟的终极目标，从来不是追求多么华丽的代码或多么复杂的模型，而是用最稳健的方式，回答那个最朴素的问题：明天下午三点，码头前沿的波高会不会超过1.2米？这套工具包，就是帮你把这个问题，从“不确定的猜测”，变成“确定的答案”。

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

简介：一套开箱即用的MATLAB工具集，专为SWAN（Simulating WAves Nearshore）近岸波浪数值模拟设计。支持从原始水深数据（NetCDF格式）读取开始，自动完成不规则或矩形网格生成、TPAR波谱参数文件构建、ECMWF和CYCOFOS再分析风场接入、侧向与区域边界条件设置等关键步骤。内置时间序列对齐、坐标转换、网格索引定位、NC文件日期检索等功能模块，适配实际工程中多源异步数据处理需求。运行后可调用GenerateGraphs.m快速输出有效波高、平均周期、主波向空间分布图及网格结构可视化图；配套提供Word版SWAN报告模板，便于成果整理与汇报。所有脚本采用模块化封装，用户可根据项目需要灵活组合调用，彻底规避手动编写SWAN输入卡的繁琐操作和出错风险。

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