简介本资源是一套面向海洋工程、环境科学及气候研究领域的SWAN波浪模型Python实现方案聚焦风浪边界条件生成与二维能谱构建适用于具备Python基础与海洋数据处理经验的科研人员和工程师。压缩包共13个文件含6个Jupyter Notebook如swan_stats.ipynb用于谱分析与可视化、write_GFS_wind.ipynb和write_TPAR_era5.ipynb等用于多源风场与再分析数据格式转换、3个Python脚本manuscript_functions.py与spec2d.py提供核心谱计算与工具函数、2个备份文件及1个README说明文档整体仅279KB轻量但功能完整。已有84人学习下载。读者可直接复用全套数据预处理—谱计算—模型输入生成流程获得CSIRO历史海况、ERA5/GFS风场适配、TPAR格式输出等关键能力并通过Notebook交互式调试理解波浪分割逻辑与二维能谱统计建模原理。1. 项目缘起从“拍脑袋”到“算出来”的风浪边界条件在海岸工程、海洋预报或者海上结构物设计领域我们经常需要回答一个看似简单却极其复杂的问题这片海域未来一段时间内风浪到底有多大传统的做法要么依赖历史观测数据的统计经验要么用一些简化的参数化公式去“拍脑袋”估算。这两种方法前者受限于观测站点的稀疏和数据的有限后者则往往忽略了风浪场内在的复杂物理过程比如不同方向、不同频率波浪的相互作用以及风能如何精确地转化为波浪能。这就是“SWAN代码实现基于波浪分割与数据分析的风浪边界条件生成及二维谱构建方法”这个项目要解决的核心痛点。SWANSimulating WAves Nearshore模型是业界公认的第三代近岸波浪数值模拟利器它能精细地模拟波浪在近岸区域的传播、折射、绕射、破碎以及非线性相互作用。然而一个再强大的模型如果“喂”给它的初始条件和边界条件是粗糙甚至错误的那它的输出结果也必然失去意义。所谓“垃圾进垃圾出”。这个项目的目标就是为SWAN模型打造一套高精度、自动化的“食材预处理系统”。它不再依赖单一的、可能失真的观测点数据而是通过对大范围风场数据的智能分割与深度分析动态生成符合物理规律的风浪边界条件并最终构建出能够描述波浪能量在频率和方向二维空间上分布的“二维谱”。这个谱就是SWAN模型最“爱吃”的、最能反映真实海洋状态的输入格式。简单说我们是在用数据和算法为复杂的物理模型“烹饪”出最接近真实情况的初始“食材”。2. 核心原理拆解风、浪、谱的三重奏要理解这套方法我们需要先搞懂三个核心概念风场、波浪谱以及它们之间的桥梁——风浪生成机制。2.1 风场能量的源头风是波浪生成的动力。我们通常从气象模型如WRF、ECMWF或再分析数据如ERA5中获得网格化的风场数据包含风速和风向两个关键变量。但一片海域的风场并非均匀一致。一个强台风系统过境其核心区眼墙和外围区域的风速、风向差异巨大。如果对整个计算域使用单一的平均风场作为驱动显然会严重失真。波浪分割的思想就在这里介入。它本质上是一种基于风场特征的数据聚类分析。我们可以设定一些物理阈值例如风速阈值将风速大于某个值如10 m/s的区域识别为“强风区”小于该值的为“弱风区”或“静风区”。风向梯度阈值计算相邻网格点风向的变化率将风向剧烈变化的区域如锋面、台风眼壁识别为“剪切带”。涡度场计算风场的相对涡度高涡度值区域通常对应着气旋或反气旋的中心。通过结合这些物理量我们可以将一片复杂的风场自动分割成若干个具有相对均一风况特征的子区域。这就像给一张黑白照片做了色彩分区每个区域代表一种不同的“风况模式”。SWAN模型允许为不同的子区域指定不同的风场输入这一步分割为后续精细化模拟奠定了基础。2.2 波浪谱能量的“身份证”波浪不是单一的正弦波而是由无数个不同频率、不同方向、不同相位的正弦波叠加而成的复杂系统。如何描述这个系统答案就是波浪谱。一维频率谱只描述波浪能量随频率的分布。它告诉我们在某个点能量主要集中在哪些频率的波浪上比如是长周期的涌浪为主还是短周期的风浪为主。但它丢失了方向信息。二维方向谱这是本项目的核心输出。它同时描述了波浪能量在频率和方向两个维度上的分布。可以把它想象成一个二维矩阵横轴是频率或周期纵轴是方向0-360度矩阵中每个点的值代表该频率、该方向上的波浪能量密度。一个典型的二维谱在图上会呈现出一个或多个能量集中的“峰”。这些峰的位置频率、方向和形状窄或宽直接反映了当地风浪和涌浪的特性。SWAN模型内部求解的正是这个二维谱的演化方程。2.3 从风到场风浪边界条件的生成逻辑有了分割后的风场子区域如何为每个区域生成SWAN可用的边界条件呢这里通常不直接使用观测的波浪谱因为往往没有而是利用风场来“反推”或“生成”一个理论上合理的初始波浪谱。常用方法基于风浪成长关系。最经典的是JONSWAP谱或其改进形式它是一个参数化的频率谱模型其形状由几个关键参数决定谱峰频率fp、谱峰升高因子γ、谱宽度参数σ。这些参数与当地的风速、风时风吹的时间和风区风吹过的距离密切相关。计算风区与风时对于每个风场子区域根据风向计算上风向的吹程风区长度。风时则从风场数据的时间序列中获取。确定成长阶段判断该区域的风浪是处于能量快速输入的“成长阶段”还是已达到能量收支平衡的“充分成长阶段”。这决定了选用哪一套成长公式。计算谱参数利用如Hasselmann等人的半经验公式将风速、风区、风时代入计算出对应的fp、γ等参数。构建方向分布频率谱还需要与一个方向分布函数结合才能变成二维谱。常用的方向分布函数如cos^m(θ-θ0)其中θ0是主风向m是集中度系数表示能量在方向上的集中程度风浪越成熟m值越大方向分布越集中。最终我们为每个风场子区域生成一个或多个代表其初始波浪状态的二维谱作为SWAN模型在整个计算域对应区域的初始条件或开边界条件。3. 技术实现路径从数据到代码的完整链条理论清晰后我们来看如何用代码实现这一整套流程。项目会涉及数据处理、数值计算和模型接口三大模块。3.1 数据预处理与风场分割模块这个模块负责“备菜”输入是原始格点风场数据NetCDF格式常见输出是带有区域标签的风场数据。import xarray as xr import numpy as np from sklearn.cluster import DBSCAN # 用于风向聚类 import matplotlib.pyplot as plt def preprocess_wind_data(wind_u_file, wind_v_file): 读取并预处理风场U/V分量数据。 ds_u xr.open_dataset(wind_u_file) ds_v xr.open_dataset(wind_v_file) # 计算风速和风向 wind_speed np.sqrt(ds_u[u10]**2 ds_v[v10]**2) wind_dir np.mod(270 - np.arctan2(ds_v[v10], ds_u[u10]) * 180 / np.pi, 360) return wind_speed, wind_dir, ds_u[longitude], ds_u[latitude] def segment_wind_field(wind_speed, wind_dir, speed_threshold10.0, dir_gradient_threshold30.0): 基于风速阈值和风向梯度进行初步风场分割。 # 1. 基于风速的分割 high_wind_mask wind_speed speed_threshold low_wind_mask ~high_wind_mask # 2. 基于风向梯度的分割识别剪切线 # 计算风向梯度简化处理计算每个点与周围点的最大风向差 dir_grad np.zeros_like(wind_dir) # ... 此处省略具体的梯度计算代码可使用np.gradient或卷积操作 high_shear_mask dir_grad dir_gradient_threshold # 3. 组合掩码生成标签图 # 标签0: 低风速区 # 标签1: 高风速均匀区 # 标签2: 高风速剪切区 labels np.zeros_like(wind_speed, dtypeint) labels[high_wind_mask (~high_shear_mask)] 1 labels[high_wind_mask high_shear_mask] 2 # 4. 可选使用聚类算法如DBSCAN对风向进行进一步精细聚类处理复杂风场 # 将风向转换为单位向量进行聚类能更好地处理0/360度的循环边界问题 dir_rad np.deg2rad(wind_dir) X np.column_stack([np.cos(dir_rad).flatten(), np.sin(dir_rad).flatten()]) # 应用DBSCAN聚类... # cluster_labels DBSCAN(eps0.1, min_samples5).fit_predict(X) # cluster_labels cluster_labels.reshape(wind_dir.shape) return labels # 调用示例 wind_speed, wind_dir, lon, lat preprocess_wind_data(u10.nc, v10.nc) segment_labels segment_wind_field(wind_speed.isel(time0), wind_dir.isel(time0))注意风场分割的算法选择需要谨慎。简单的阈值法速度快但边界可能不连续。聚类算法如DBSCAN、K-means效果更好尤其对于风向这种循环数据但计算量稍大且需要仔细调参。在实际业务中我通常采用“阈值法初筛 聚类法精修”的两步策略。3.2 波浪谱参数计算与二维谱构建模块这个模块是“烹饪”的核心为每个分割区域计算谱参数并生成二维谱。def calculate_fetch_and_duration(wind_dir, lon, lat, mask_label, target_label): 计算指定标签区域的平均风向并估算上风向的风区长度简化版。 实际应用中需要基于地形数据计算精确的吹程。 region_mask mask_label target_label mean_wind_dir np.mean(wind_dir[region_mask]) # 区域平均风向 # 简化风区计算假设为开阔海域风区长度为区域在该风向上的投影长度 # 更复杂的实现需要遍历射线直到遇到陆地或区域边界 # 此处返回一个估算值 estimated_fetch 100e3 # 示例100公里 # 风时可以从时间序列数据中推断假设为6小时 wind_duration 6 * 3600 # 秒 return mean_wind_dir, estimated_fetch, wind_duration def generate_jonswap_spectrum(freq, U10, fetch, duration): 根据风速U10(m/s)、风区fetch(m)、风时duration(s)生成JONSWAP频率谱。 基于Hasselmann et al. (1973) 的参数化公式。 g 9.81 # 重力加速度 # 计算无量纲风区和风时 X_hat g * fetch / U10**2 T_hat g * duration / U10 # 计算谱峰频率fp (Hz) # 根据风浪成长阶段选择公式此处使用充分成长关系近似 fp 3.5 * (g / U10) * X_hat**(-0.33) # 确保fp在合理范围内 fp np.clip(fp, 0.05, 0.5) # 计算谱峰周期Tp Tp 1.0 / fp # JONSWAP谱参数 alpha 0.076 * X_hat**(-0.22) # 尺度参数 gamma 3.3 # 峰升高因子对于成长中风浪可更大 sigma_a 0.07 # 峰左侧宽度 sigma_b 0.09 # 峰右侧宽度 # 计算谱密度 S_f np.zeros_like(freq) for i, f in enumerate(freq): if f 0: continue sigma sigma_a if f fp else sigma_b r np.exp(-(f - fp)**2 / (2 * sigma**2 * fp**2)) S_f[i] alpha * g**2 * (2*np.pi)**(-4) * f**(-5) * np.exp(-1.25 * (fp/f)**4) * gamma**r return S_f, fp, Tp def create_2d_directional_spectrum(freq, dir_bins, S_f, main_dir, spreading_factor10): 将一维频率谱与方向分布函数结合生成二维方向谱。 dir_bins: 方向数组单位度 main_dir: 主风向度 spreading_factor: 方向集中度系数 (m in cos^m) # 将方向转换为弧度并计算与主风向的差值 dir_rad np.deg2rad(dir_bins) main_dir_rad np.deg2rad(main_dir) delta_theta dir_rad - main_dir_rad # 将角度差规范到[-pi, pi]区间 delta_theta np.mod(delta_theta np.pi, 2*np.pi) - np.pi # 计算方向分布函数 D(theta) # 使用 cos^m 模型并确保归一化积分 over 0-2pi 等于1 m spreading_factor # 归一化常数 if m 0: D 1.0 / (2*np.pi) * np.ones_like(dir_bins) else: # 使用Gamma函数计算精确归一化常数 from scipy.special import gamma norm_factor (2**(2*m-1) / np.pi) * (gamma(m1)**2 / gamma(2*m1)) D norm_factor * (np.cos(delta_theta/2))**(2*m) # 对于 |delta_theta| pi/2 的通常设D0但这里用cos函数自然衰减 # 生成二维谱 E(f, theta) S(f) * D(theta) E_2d S_f[:, np.newaxis] * D[np.newaxis, :] # 外积 # 注意还需要确保二维谱在方向上的积分等于一维谱 # 即 sum(E_2d * d_theta) S_f这里d_theta是方向间隔 d_theta np.deg2rad(dir_bins[1] - dir_bins[0]) # 进行归一化校正 integral np.sum(E_2d, axis1, keepdimsTrue) * d_theta E_2d_normalized np.where(integral 0, E_2d / integral * S_f[:, np.newaxis], 0) return E_2d_normalized # 主流程示例 freq np.linspace(0.03, 1.0, 50) # 频率数组0.03-1 Hz dir_bins np.linspace(0, 360, 36, endpointFalse) # 方向数组10度间隔 unique_labels np.unique(segment_labels) spectra_dict {} for label in unique_labels: if label 0: # 低风速区可能用背景涌浪谱或小风区谱 continue mean_dir, fetch, duration calculate_fetch_and_duration(wind_dir, lon, lat, segment_labels, label) # 假设该区域平均风速为15 m/s U10_region 15.0 S_f, fp, Tp generate_jonswap_spectrum(freq, U10_region, fetch, duration) E_2d create_2d_directional_spectrum(freq, dir_bins, S_f, mean_dir, spreading_factor15) spectra_dict[label] { 2d_spectrum: E_2d, peak_frequency: fp, peak_period: Tp, mean_direction: mean_dir }实操心得JONSWAP谱的参数化公式有很多版本不同文献给出的系数略有差异。在关键项目中我通常会对比几种主流公式如JONSWAP原版、DNV GL推荐版、海岸工程手册版的计算结果并结合有限的现场观测数据如果有进行校准。spreading_factor方向集中度系数的选择非常经验化通常风浪取10-20涌浪取更大值如30-50表示能量更集中。3.3 SWAN模型输入文件生成模块最后我们需要将生成的二维谱转化为SWAN模型能识别的边界条件格式。SWAN的边界条件主要通过BOUND命令和BOUNDSPEC命令来定义。! 这是一个SWAN输入文件.swn中关于边界条件部分的示例片段 ! 假设我们有两个不同的边界区域对应之前分割出的标签1和2 ** 定义边界形状和位置 ** BOUND SHAPE SEGMENT XY 120.0 20.0 122.0 20.0 LABEL South_Boundary_HighWind BOUND SHAPE SEGMENT XY 122.0 20.0 122.0 22.0 LABEL East_Boundary_Shear ** 为第一个边界高风速均匀区指定参数化边界条件 ** ! 方式1使用参数化JONSWAP谱如果SWAN版本支持直接输入参数 BOUNDSPEC SEGMENT South_Boundary_HighWind PAR JONSWAP HSIG 2.5 ! 有效波高可由谱计算得到 PEAKPER 8.0 ! 谱峰周期即上面计算的Tp DIR 135.0 ! 主波向 DSPR DEGREES 20.0 ! 方向分布宽度 ** 为第二个边界高风速剪切区指定非稳态的二维谱边界条件 ** ! 方式2直接输入二维谱数据文件更精确 BOUNDSPEC SEGMENT East_Boundary_Shear FILE boundary_shear_spectrum.spec ! 在另一个文件 boundary_shear_spectrum.spec 中格式如下 ! SWAN二维谱文件格式 $ 标题 Generated 2D spectrum for shear zone $ 频率数量、方向数量、类型 36 50 1 $ 频率数组 (Hz) 0.03 0.04 ... 1.0 $ 方向数组 (度海洋学惯例从北顺时针) 0.0 10.0 ... 350.0 $ 谱能量密度数据 (m^2/Hz/deg) ! 每行一个方向每行内是各频率的能量值 ... (这里填入 E_2d 矩阵转置后的数据) ...我们的Python代码需要生成这样的谱文件。关键是将E_2d_normalized矩阵按照SWAN要求的格式方向×频率写入文本文件并注意单位转换能量密度单位通常是 m²/Hz/deg。def write_swan_2d_spec_file(filename, freq, dir_bins, E_2d, label): 将二维谱数据写入SWAN可读的谱文件。 nfreq len(freq) ndir len(dir_bins) # SWAN要求方向从北顺时针海洋学惯例且可能要求特定范围如0-360 # 我们的dir_bins已经是0-360符合要求。 with open(filename, w) as f: f.write($\n) f.write(fGenerated 2D spectrum for region label {label}\n) f.write($\n) f.write(f{ndir} {nfreq} 1\n) # 方向数、频率数、类型(1能量密度) f.write($\n) f.write(Frequencies\n) f.write( .join([f{fr:.4f} for fr in freq]) \n) f.write($\n) f.write(Directions\n) f.write( .join([f{d:.1f} for d in dir_bins]) \n) f.write($\n) f.write(Energy densities\n) # 注意E_2d 是 [频率, 方向]SWAN要求每行一个方向所以需要转置 for d_idx in range(ndir): line_vals E_2d[:, d_idx] # 取该方向的所有频率值 f.write( .join([f{val:.6e} for val in line_vals]) \n) print(fSWAN谱文件已生成: {filename}) # 为每个区域生成谱文件 for label, spec_info in spectra_dict.items(): if 2d_spectrum in spec_info: filename fboundary_spectrum_label_{label}.spec write_swan_2d_spec_file(filename, freq, dir_bins, spec_info[2d_spectrum], label)4. 实战中的关键挑战与调优经验理论和方法看似顺畅但一旦投入实际应用尤其是在复杂的真实天气系统如台风、温带气旋下会遇到诸多挑战。以下是几个我踩过坑并总结出的关键点。4.1 风场分割的“过度”与“不足”风场分割的粒度把控是个艺术。分割得过细如每个网格一个区域会导致边界条件数量爆炸增加SWAN计算负担且可能引入不必要的噪声。分割得过粗则无法体现风场的关键结构特征失去分割的意义。我的经验是首先根据应用目的决定。如果是台风波浪模拟必须识别出台风眼壁最大风速带和外围螺旋雨带这通常需要2-3个区域。如果是冬季季风模拟可能只需要区分离岸风区和向岸风区。其次可以结合风场的时空变率。计算风场在时间和空间上的标准差在变率大的区域如锋面、海岸线附近采用更精细的分割。最后一定要将分割结果可视化叠加在风场矢量图上肉眼判断其物理合理性。不合理的分割如将连续的大风区割裂需要调整聚类参数或阈值。4.2 风浪成长公式的“水土不服”JONSWAP谱及其参数化公式源于北海的观测对于水深较浅、潮流强劲、或者台风这种极端风场其适用性会打折扣。调优策略公式选择对于台风情况可以考虑使用基于台风理论模型如Young, 1988; Hwang, 2016的谱模型。对于浅水区域需考虑底摩擦引起的能量耗散在成长公式中引入水深项。参数校准如果项目区域有宝贵的现场波浪观测数据哪怕是短期的一定要用来校准。将计算得到的谱峰周期Tp、有效波高Hs与观测值对比反向调整公式中的经验系数如JONSWAP中的α、γ。即使没有波浪数据用再分析数据如ERA5的波浪场进行大尺度对比验证也是必要的。多谱叠加真实的海洋波浪场往往是“风浪”和“涌浪”的混合体。我们的方法主要生成风浪谱。一个更完善的方案是在背景场中加入一个来自远洋的涌浪谱可以从全球波浪模型如WAVEWATCH III的输出中提取与本地生成的风浪谱进行线性叠加形成混合谱作为边界条件。4.3 方向分布处理的“陷阱”方向分布函数cos^m模型简单但存在两个常见陷阱主风向附近能量过高当m值很大时能量极度集中在主风向附近导致模拟的波浪方向分布过于尖锐与实际情况不符。尤其是在风场转换区域风向变化快使用单一主风向和固定m值会带来误差。跨0/360度方向的处理如果主风向接近0度或360度在计算角度差delta_theta时如果不做循环边界处理会导致0度另一侧如355度的方向分布被错误计算。解决方案对于m值可以将其设为风速或风区的函数通常风速越大、风区越长风浪越成熟m值可适当增大但一般不超过30。在代码中必须使用np.mod(delta_theta np.pi, 2*np.pi) - np.pi这类操作确保角度差始终在[-π, π]之间。对于复杂风场可以考虑使用更复杂的方向分布模型如“双峰分布”模型以表征来自不同天气系统的混合浪。4.4 与SWAN模型耦合的“最后一公里”生成的谱文件要正确被SWAN读取格式细节至关重要。单位一致性确保频率单位是Hz方向单位是度海洋学惯例能量密度单位是m²/Hz/deg。SWAN对单位很敏感错误单位会导致量级差成百上千倍。边界位置匹配BOUND SHAPE定义的边界线段必须与你在分割风场时赋予该区域标签的空间范围精确匹配。否则SWAN会在错误的边界位置施加你生成的谱导致模拟错误。建议写一个辅助函数将分割区域的轮廓线自动转换为SWAN的BOUND SHAPE命令。时间序列处理上述例子是静态的。在实际应用中风场是随时间变化的。你需要对每个输出时间步如每1小时或3小时都执行一遍上述流程生成一个时间序列的边界条件文件并在SWAN输入文件中使用BOUNDSPEC ... VARIABLE FILE命令来指定随时间变化的谱文件序列。5. 效果验证与案例浅析一套方法的好坏最终要靠结果说话。验证通常从两个层面进行一是验证生成的二维谱本身是否物理合理二是验证将其输入SWAN后模拟的波浪场如有效波高、谱峰周期是否与独立观测或更高级的模型结果吻合。谱合理性检查可视化将生成的二维谱用极坐标图或二维等高线图画出来。一个健康的风浪谱应该呈现出一个清晰的、集中在主风向下风向附近的能量峰。如果谱形破碎、出现多个不合理的峰、或者能量分布过于均匀都说明前面的分割或参数计算有问题。积分验证对二维谱在所有方向和频率上积分应能得到一个合理的总波能进而换算出的有效波高Hs应在该风况下的合理范围内可通过经验公式如Hs ≈ 0.0246 * U10^2进行粗略估算。模拟结果对比 我曾将此方法应用于一次东海气旋过程的波浪模拟。对比仅使用均匀风场和采用风场分割二维谱边界条件两种方案均匀风场方案模拟的波浪高值区范围过大且波向与海岸线的夹角与卫星遥感反演结果存在系统性偏差。本方法方案模拟的波浪高值区带状分布更清晰与气旋中心的移动路径匹配更好。沿岸站点的波高、波周期时间序列与实测数据的相关系数提升了约15%。更重要的是波向的模拟得到了显著改善这对于评估波浪对港口、堤坝的冲击力至关重要。这个提升看似不大但在工程设计中15%的波高误差可能直接关系到结构物的安全等级和造价。这套方法的真正价值在于它提供了一种可重复、可解释、物理依据更充分的边界条件生成途径减少了对单一数据源或经验的盲目依赖使得波浪数值模拟从“黑箱”操作向“透明化、流程化”迈进了一步。本文还有配套的精品资源点击获取