【WRF-Chem教程第六期】WRF-Chem KPP Coupler 简介
WRF-Chem KPP Coupler 简介
- 6.1 介绍（Introduction）
- 6.2 KPP 编译所需的系统环境（KPP Requirements）
- 6.3 编译 WKC（Compiling the WKC）
- 6.4 使用 WKC 实现化学机制（Implementing chemical mechanisms with WKC）
-
- 当前可用机制（基于 WKC 的 KPP 实现）
- 6.5 WKC 的目录组织结构（Layout of WKC）
-
- WKC 所在目录结构
- 6.6 WKC 生成的代码与用户修改（Code produced by WKC, User Modifications）
- 6.7 可用的积分器（Available Integrators）
- 6.8 使用 WKC 添加新机制（Adding mechanisms with WKC）
-
- 添加机制的基本步骤：
- 总结：使用 WKC 添加新机制流程
- 6.9 适配 KPP 方程文件（Adapting KPP Equation Files）
-
- 变量命名适配对照表
- 6.10 为 WKC 添加额外的 KPP 积分器（Adapting Additional KPP Integrators for WKC）
-
- 适配新积分器的步骤
- 参考
KPP（Kinetic PreProcessor）是一种自动生成化学机制程序代码的工具，WRF-Chem 通过 WKC（WRF-Chem KPP Coupler）实现与 KPP 的集成，极大简化了添加或修改化学反应机制的过程。
6.1 介绍（Introduction）
✅ 背景问题
在传统的 WRF-Chem 模拟中：
- 一个化学机制可能包含数百个反应和几十个化学物种
- 其求解过程涉及大型常微分方程组（ODEs）
- 若使用手写的数值求解器（如 Runge-Kutta），一旦机制更新（如添加反应或物种），就需要重写大量代码，既耗时又容易出错
✅ 解决方案：KPP + WKC
-
KPP（Kinetic PreProcessor）：
- 是一个程序，可以从文本文件读取化学反应方程和速率常数
- 自动生成用于数值积分的 Fortran/C 代码
- 提高效率：通过对雅可比矩阵进行稀疏优化，自动重排方程
-
WKC（WRF-Chem KPP Coupler）：
- 是连接 KPP 与 WRF-Chem 的桥梁
- 能根据 WRF-Chem 的配置文件自动生成「接口代码」
- 减少用户手动编写代码的负担，便于更新机制或添加新物种
✅ WKC 的特点
- 自动执行：在编译 WRF-Chem 时自动运行
- 减少用户负担：不需深入手动编辑 Fortran 代码
- 支持机制扩展：便于添加新的化学过程
- KPP v2.1 已成功集成进 WRF-Chem
注：WKC 的介绍最早出现在 2006 年 WRF 用户研讨会上（Barth & Lawrence）
相关文档：
- KPP 官网
- WRF KPP 文档摘要
6.2 KPP 编译所需的系统环境（KPP Requirements）
为了在系统中使用 KPP，你需要安装以下工具：
| 工具 | 说明 |
|---|---|
flex |
词法分析器 |
yacc |
语法解析器 |
sed |
文本处理工具 |
| C 编译器 | 默认由 configure_kpp 自动设置 |
FLEX 库路径设置
- 默认路径：
/usr/lib下的libfl.a或libfl.sh - 若路径不同，需设置环境变量：
export FLEX_LIB_DIR=/your/path/to/flex/lib
⚠️ 这些工具通常在 Linux 系统中可通过包管理器安装，如 apt, yum, brew 等。
6.3 编译 WKC（Compiling the WKC）
编译触发条件
-
编译 WRF-Chem 时，若设置了环境变量：
setenv WRF_KPP 1 # csh 用户 export WRF_KPP=1 # bash 用户 -
则 KPP 和 WKC 会自动运行并编译
⚙️ 编译流程概要
- KPP 读取机制描述文件
- 如
.eqn化学方程文件
- 如
- KPP 自动生成 Fortran 代码
- 包括反应速率、雅可比矩阵、积分器接口
- WKC 将其复制到
WRFV3/chem目录 - 修改
chem/Makefile- 确保 KPP 代码被编译并链接
- 编译后具有
kpp前缀的模块将被集成进模型
清理模块
- 若要清除由 KPP/WKC 生成的模块，可运行
clean脚本
6.4 使用 WKC 实现化学机制（Implementing chemical mechanisms with WKC）
KPP 文件位置
对于已经通过 WKC（WRF-Chem KPP Coupler） 实现的化学机制，其对应的 KPP 输入文件存放在：
WRFV3/chem/KPP/mechanisms/
这些子目录中包含了每种化学机制的定义文件（如 .eqn, .spc, .rate）。
注册机制
- 每种机制在
Registry/registry.chem文件中有注册。 - 它们的机制名称中包含后缀
kpp，用于标识为通过 KPP 实现的机制。
使用方法
若要在 namelist.input 中启用这些机制：
&chem
chem_opt = XXX ! 设置为对应机制的编号（大于 100）
/
当前可用机制（基于 WKC 的 KPP 实现）
| 化学机制名称 | 作者与特点 |
|---|---|
| RACM/SORGAM | 区域大气化学机制，适合模拟臭氧与二次有机气溶胶 |
| RACM（Stockwell et al. 1997） | 区域性机制，广泛用于城市/区域空气质量研究 |
| RACM-MIM（Geiger et al. 2003） | 将 RACM 与 MIM（Mechanism for Isoprene Mechanism）结合 |
| RACM/SORGAM（再列） | 与 SORGAM 气溶胶机制配套使用，适合模拟 SOA |
这些机制的
chem_opt设置值大于 100**，以与非 KPP 机制区分。**
6.5 WKC 的目录组织结构（Layout of WKC）
WKC 的核心作用是：
从
.spc文件和registry.chem自动生成 WRF-Chem 与 KPP 之间的接口 Fortran 90 代码。
WKC 所在目录结构
WKC 所在目录结构：
路径：chem/KPP/
该目录包含以下子目录和文件：
1. mechanisms/
- 包含各类化学机制的子目录
- 每个子目录中存放该机制的：
.eqn（反应方程）.spc（物种列表）.rate（反应速率）
- 示例路径：
chem/KPP/mechanisms/racm_kpp/
2. 编译/清理脚本
- compile script：用于编译 KPP 模块（由 WRF-Chem 编译脚本调用）
- clean script：清除 KPP 编译生成的中间文件
3. kpp/ 子目录（包含 KPP 源码）
- 包含 KPP v2.1 的源代码
- 此版本经改造以兼容 WRF-Chem
- 使用
.kpp文件中的#WRF Conform指令确保兼容性
- 使用
- 用于自动将机制输入转换成 Fortran 模块
4. util/wkc/
- 包含 WKC 自身的源代码
- 用于生成接口代码、管理变量映射等
5. wkpp_constants.F 模块
- 可配置 KPP 求解器的参数，如：
RTOL（相对误差容限）ATOL（绝对误差容限）
- 后续版本可能增加更多配置项
6. incare/ 目录
- 包含在编译时被
#include的代码文件 - 不会被
clean脚本删除 - 可用于用户自定义或修改由 WKC 自动生成的代码接口
总结：WKC 布局一览表
| 目录/文件 | 功能 |
|---|---|
KPP/mechanisms/ |
储存每个机制的 KPP 输入文件 |
KPP/kpp/ |
存放 KPP v2.1 源代码 |
KPP/util/wkc/ |
WKC 的核心代码 |
KPP/compile, KPP/clean |
编译/清理脚本 |
wkpp_constants.F |
调整 KPP 解算器误差容限参数 |
incare/ |
存放供用户修改的接口文件 |
6.6 WKC 生成的代码与用户修改（Code produced by WKC, User Modifications）
自动生成代码的特点
- WKC（WRF-Chem KPP Coupler）生成的代码是从主程序（chem driver）调用的。
- 其中许多文件是在编译过程中自动生成的，手动修改这些文件后再次编译会丢失更改（文件头部也会有此警告）。
推荐的修改方式：使用 #INCLUDE
-
WKC 生成的代码中包含大量
#INCLUDE指令 -
被包含的
.f文件位于：chem/KPP/inc/ -
这些
.f文件：- 不会被
clean脚本删除 - 可以安全地添加用户自定义代码（例如特定的反应率或转换）
- 不会被
修改自动生成文件的其他方法（不推荐）
- 重命名自动生成的文件使其不会被删除
- 修改生成这些文件的源程序（KPP 或 WKC 的 C 代码）
推荐方法：使用
chem/KPP/inc/目录下的#include文件进行插入式修改，既安全又便于维护。
6.7 可用的积分器（Available Integrators）
当前支持的积分器类型
-
WKC 目前仅支持 Rosenbrock 类型积分器
-
编译后，相应积分器模块保存在：
chem/kpp_my_mechanism_Integrator.f90其中
my_mechanism是 namelist 中设置的化学机制名。
后续扩展
- 后续章节会介绍如何添加更多积分器类型（如 Runge-Kutta、Gear 等）
6.8 使用 WKC 添加新机制（Adding mechanisms with WKC）
在使用 WKC 添加新的化学机制时，除了提供反应机制本身的定义外，通常还需要：
- 计算新的光解速率（photolysis）
- 包含新的排放数据集
- 指定初始边界条件
- 添加干沉降与湿沉降参数（如 Henry 常数）
添加机制的基本步骤：
① 编辑注册表文件 Registry.EM_CHEM
-
添加新物种到化学数组结构（如需）
-
添加机制项，名称以
_kpp结尾，例如：package my_mechanism_kpp
② 提供 KPP 所需的输入文件
将如下文件放入新的机制目录中，例如：
WRFV3/chem/KPP/mechanisms/my_mechanism/
| 文件名 | 说明 |
|---|---|
my_mechanism.eqn |
化学反应方程 |
my_mechanism.spc |
化学物种列表 |
my_mechanism.kpp |
KPP 配置文件 |
my_mechanism_wrfkpp.equiv |
可选映射表（WRF<->KPP 变量名） |
注意：机制目录名应为 my_mechanism，而不是 my_mechanism_kpp！
③ 可选：变量名映射文件（equiv 文件）
- 文件名：
my_mechanism_wrkfpp.equiv - 用于将 WRF-Chem 中的变量名映射为 KPP 中使用的变量名，如：
HO → OH
参考已有机制结构
建议复制一个已实现机制的目录作为模板，例如：
WRFV3/chem/KPP/mechanisms/racm_kpp/
然后修改：
.kpp文件中的#Model名称.def文件中引用的.eqn和.spc文件名
④ 设置 KPP 文件中的积分器
在你的 .kpp 文件中添加：
#INTEGRATOR WRF conform/rosenbrock
#WRFCONFORM
路径指向：
WRFV3/chem/KPP/kpp/kpp-2.1/int/WRF_conform/
⚠️ 注意事项：
- 目前 WKC 不支持
.spc文件中的注释！ - 并非所有 KPP 指令都被 WKC 支持，请查阅文档进行适配
总结：使用 WKC 添加新机制流程
| 步骤 | 操作说明 |
|---|---|
| 1️⃣ 注册机制 | 修改 Registry.EM_CHEM，添加化学包 |
| 2️⃣ 准备机制文件 | .eqn, .spc, .kpp, *.equiv |
| 3️⃣ 配置 KPP | 设置积分器、模型名等 |
| 4️⃣ 放入指定目录 | chem/KPP/mechanisms/my_mechanism/ |
| 5️⃣ 编译 WRF-Chem | 设置 WRF_KPP=1，自动运行 KPP 与 WKC |
6.9 适配 KPP 方程文件（Adapting KPP Equation Files）
目的： 要将 KPP 化学机制正确集成到 WRF-Chem 中，需要在 KPP 方程文件（.eqn） 里对某些变量名称进行适配，使其与 WRF-Chem 接口匹配。
变量命名适配对照表
下表列出了在 KPP .eqn 文件中使用的变量名及其含义、单位和在 WRF-Chem 注册表中的对应名称：
| 物理量 | KPP 中变量名 | 单位 | WRF-Chem 注册表中的变量名 |
|---|---|---|---|
| 光解速率 | J(Pj_no2) |
s⁻¹ | ph_no2 |
| 温度 | TEMP |
K | t_phy |
| 三体分子浓度 | C_M |
分子/立方厘米（湿空气） | 根据密度计算 |
| 水汽浓度 | C_H2O |
分子/立方厘米 | 根据 qvapor 计算 |
⚠️ 注意：这些变量在
.eqn文件中以名称出现，但在运行时由 WRF-Chem 的接口传递具体数值。
示例 .eqn 文件片段（RACM-MIM）
#EQUATIONS { racm-mim }
{001} NO2+hv=O3P+NO : j(Pj_no2) ;
{002} O3+hv=O1D+{O2} : j(Pj_o31d) ;
...
{242} MACP+HO2=MAHP : ARR2(1.82e-13, -1300.0, TEMP) ;
{243} MACP+MACP=HACE+MGLY+... : 2.00e-12 ;
{244} MSACP+NO2=MPAN : TROE(9.70e-29, 5.6, ..., TEMP, C_M) ;
j(Pj_no2)：读取 NO₂ 光解速率TEMP：温度C_M：三体分子浓度
内部说明
- 光解速率
j(Pj_xxx)会由 WRF-Chem 接口传入（例如ph_no2） - 所有这些变量通过自动生成的接口例程传入 KPP
- 用户自定义的变量（如 N₂O₅ 水解速率）可通过修改
chem/KPP/inc中的.inc文件进行传递
6.10 为 WKC 添加额外的 KPP 积分器（Adapting Additional KPP Integrators for WKC）
背景：
- 目前，WRF-Chem + WKC 默认只支持 Rosenbrock 类型 的 KPP 积分器（例如：
rosenbrock.f90）。 - 若用户希望使用其他积分器（如 RK4、Gear 等），需对其代码进行适配。
积分器文件位置
-
所有 KPP 积分器文件位于：
chem/KPP/kpp/kpp2.1/int/ -
已适配 WRF 的积分器存放在：
chem/KPP/kpp/kpp2.1/int/WRF_Conform/
适配新积分器的步骤
适配新积分器的步骤如下：
步骤 1：复制文件
- 将新积分器的
.f90和.def文件复制到WRF_Conform/目录
步骤 2：修改子程序名
- 在所有
SUBROUTINE和END SUBROUTINE中的子程序名加上前缀KPP_ROOT_- 例如：将
SUBROUTINE INTEGRATE(...)改为SUBROUTINE MYMECH_INTEGRATE(...)
- 例如：将
步骤 3：更改子程序参数
- 修改
SUBROUTINE的参数列表，使其与 WRF-Chem 的调用接口一致 - 可参考已有的 Rosenbrock 示例进行调整
步骤 4：删除不必要的 USE 语句
- 删除所有引用非常量数据的
USE模块语句 - 改为通过
SUBROUTINE参数传递数据
⚠️ 注意事项
- 适配过程可能因不同求解器结构而异
- 某些求解器可能需要额外步骤，如定义雅可比矩阵稀疏性等
- 由于这是底层数值解算器的修改，建议由有 Fortran 开发经验的用户操作