当前位置：首页 > news >正文

CQL3D编译指南

news 来源：原创 2025/6/14 13:52:10

CQL3D编译指南

编译环境：Ubuntu 20.04（Windows11，VMWare17 Pro 虚拟机 - 版本：17.0.2 build）

CQL3D编译指南
- 一、CQL3D 下载（见 Github）
- - 1. 使用 git 指令
  - 2. 直接下载
- 二、Makefile 文件
- - 生成的目标文件的对比
  - 1. makefile_gfortran64（非并行版）
  - 2. makefile_mpi.gfortran64（并行版）
- 三、运行测试
- - tests.sh 测试
- 四、测试案例解释说明
- - 📋 测试案例一览表
  - ✅ test1.0 / test1.1 – Dreicer 逃逸电子率计算
  - ✅ test2 – 欧姆电阻率（Ohmic Resistivity）
  - ✅ test3 – DIII-D 装置中的单射线 ECRH 测试
  - ✅ test4 – EBW（电子伯恩斯坦波）disk-to-disk 射线传播/波导测试
  - ✅ test5 – 多离子种 + 多束 FW 注入的 DIII-D 实例（多种离子、多频加热）
  - ✅ test6 – 多磁通面下 Dreicer 逃逸速率 vs 逆环向比 ε
  - ✅ test7 – TCV 装置的径向输运测试（未执行）
  - 🧠 应用建议

编译前准备见前文【GENRAY编译指南】

一、CQL3D 下载（见 Github）

1. 使用 git 指令

git clone https://github.com/compxco/cql3d.git
# or
git clone git@github.com:compxco/cql3d.git

克隆到本地文件夹（文件夹默认名cql3d）。不会 git 的可以这里速成一下（上一篇忘记了，抱意思）。

2. 直接下载

在 https://github.com/compxco/cql3d.git 网址，点击 “Code” -> "Download ZIP"直接下载，并解压到本地。

在这里插入图片描述

二、Makefile 文件

Makefile 是 make 命令所读取的配置文件，包含了构建项目的规则。其主要作用是检查项目文件的依赖关系，自动执行必要的命令，从而更新目标文件。它通过定义规则和指令，自动化编译、链接等步骤，大大简化了开发者的工作。用于管理项目构建过程，广泛用于 C/C++ 等语言的编译。基础知识可见： Makefile入门。

一般来说，Makefile 的基本语法由规则（rule）组成，其格式如下：

target: dependenciescommand

目标（target）：需要生成的文件，例如可执行文件。
依赖（dependencies）：生成目标所依赖的文件或目标。
命令（commands）：构建目标时需要执行的命令，必须以 Tab 开头。

CQL3D 中的Makefile

首先进入cql3d文件夹，右键"在终端打开"：

在这里插入图片描述

make 时会发现很多 makefile ，除了 makefile_intel.edison 、 makefile_mpi.edison 和 makefile_mpi_intel.edison （Edison 版，Edison是美国国家能源研究科学计算中心（NERSC）曾经拥有的一台超级计算机，已于2019年退役）外，所用的编译器都是 gfortran 。

生成的目标文件的对比

✅ 主要区别对比：

🔧目标文件	`xcql3d_gfortran64`	`xcql3d_gfortran64_static`	`xcql3d_gfortran64_noplots`
🧱链接选项（是否静态链接）	否	✅是，使用 `-static`	否
🖼 是否包含绘图模块 (PGPLOT)	包含	包含	❌不包含
⚙️LDSPECIAL（链接器特殊参数）	无	`-Wl,-noinhibit-exec -static` 强制静态链接	`-Wl,-noinhibit-exec`
📦CSPECIAL（编译器特殊参数）	`-frecord-marker=4`（设定Fortran记录头大小）	无	无
📁LOCATION（链接库路径）	`/opt/local/lib`	`/usr/lib64 -L/usr/local/pgplot`	`/usr/lib64`（系统默认）
📁INCLUDE（头文件路径）	`/opt/local/include`	`/usr/include`	`/usr/include`
📚LIBRARIES（链接库）	`-lX11 -lnetcdff -lnetcdf -lpgplot -lblas`	同左	`-lX11 -lnetcdff -lnetcdf`（去掉了 `-lpgplot` 和 `-lblas`）
💻使用场景	默认开发环境	稳定部署版（无动态库依赖）	仅数值计算，不依赖绘图库环境

如果希望将程序打包分发，或者在没有预装依赖库的环境中运行，可选择第二个版本（static 静态链接版本），这样可以把所需的 .a 库打包进可执行文件中。

❗注：

第二个 makefile 中使用了 -static，需要本地系统具备 .a 静态库版本（如 libnetcdf.a），否则会因找不到语构而报错；
如果你遇到 ‘undefined reference’ 类链接错误，建议先用第一个 makefile 成功编译再试静态版本。

1. makefile_gfortran64（非并行版）

输入指令make -f ./makefile_gfortran64.CentOS （不带 mpi 的），不出意外等待一会即可得到 xcql3d 目标文件：

2. makefile_mpi.gfortran64（并行版）

① 输入指令make -f ./makefile_mpi.gfortran64，报错：

mpi/doparallel.py hpalloc0.f hpalloc0_mpitmp.f mpi/mpins_par.f
make: execvp: mpi/doparallel.py: 权限不够
make: *** [makefile_mpi.gfortran64:137：hpalloc0.o] 错误 127

显示权限不足，报错在文件的 137 行。

② 文件夹里搜了一下 doparallel.py 查看文件属性：

发现文件不允许作为程序执行，勾选上允许。

实际上还是报错【命令未找到】，因为其本身肯定不是命令，那在其前面加上 python2 （这里需要注意的是：由于代码年代比较早，当时用的 python 环境是 python2.x）应该可以运行了。
③ 打开 makefile_mpi.gfortran64 ，定位到 137 行看一下代码：

果然是缺少运行 .py 程序的命令，加上 python2 。
④ 修改后，再次运行，编译成功：

生成了 xcql3d_mpi.gfortran64。

在这里插入图片描述

成功！！

三、运行测试

tests.sh 测试

cd 或直接进入 /00_Cql3d_Regression_Tests ，运行 bash ./tests.sh。

下为 tests.sh 文件的内容：

#~/cql3d/git/cql3d/00_Cql3d_Regression_Tests/tests#Adjust path to the cql3d executable.  For example:
XCQL3D="../../xcql3d_gfortran64.1"#test1: Runaway electron rates vs rho
mkdir test1
cp cqlinput_eoved_.16_multi-flux-surface_test1.0 test1/
cp cqlinput_eoved_.16_multi-flux-surface_test1.1 test1/
cd test1/
cp cqlinput_eoved_.16_multi-flux-surface_test1.0 cqlinput
time $XCQL3D > log_test1.0    # 3.3s on compx2
cp cqlinput_eoved_.16_multi-flux-surface_test1.1 cqlinput
time $XCQL3D > log_test1.1    # 1.4s on compx2
cd ..#test2: DC electric field resistivity vs rho
mkdir test2
cp cqlinput_freidberg_full_eps.3_short_w_sxr_201024 test2/cqlinput
cd test2/
ln -s ../eqdsk_freidberg_full_eps
time $XCQL3D > log_test2   #4.7s on compx2
cd ..#test3: D3D shot 96143 one ray ECH test case
mkdir test3
cp cqlinput_96143_one_ray.1_short_201024 test3/cqlinput
cd test3/
ln -s ../g096143.01440
ln -s ../rayech_test3 rayech
time $XCQL3D > log_test3   #6.3s on compx2
cd ..#test4: MAST-like EBW OXB test case.  Ray data in companion genray test.
mkdir test4
cp cqlinput_MAST-like_test.0 test4/cqlinput
cp eqdsk_MAST-like test4
cd test4/
#Next line is assuming genray and cql3d distribution are both under a common
#directory,
#and genray test10 has been run and results are in the designated directory".
ln -s ../../../genray/00_Genray_Regression_Tests/test10/genray.nc genray_test4.nc
time $XCQL3D > log_test4   #32s on compx2
cd ..#test5  multiURF_multiSpecies+NBI test case with D+H plasma in DIII-D
mkdir test5
cp cqlinput_H0.short_mmsv8_adjust.4 test5/cqlinput
cd test5/
ln -s ../genrayfw_18rays.nc
ln -s ../g122080.03100
time $XCQL3D > log_test5   # 33s on compx2
cd ..#test6  Dreicer Runaway Electron Rate calculation for comparison with
#       Kulsrud et al, PRL 1973.
mkdir test6
cp cqlinput_eoved_.16_multi-flux-surface0.2.11 test6/cqlinput
cd test6/
time $XCQL3D > log_test6   # 3.2s on compx2
cd ..

① 运行 bash ./tests.sh后，发现没有 xcql3d_gfortran64.1 （肯定没有，因为咋们生成的是 xcql3d_gfortran64），遂修改代码第4行：

#~/cql3d/git/cql3d/00_Cql3d_Regression_Tests/tests#Adjust path to the cql3d executable.  For example:
# XCQL3D="../../xcql3d_gfortran64.1" 
# 修改为：
XCQL3D="../../xcql3d_gfortran64"

② 再次运行，不报错，生成6个测试结果：

四、测试案例解释说明

运行结果可以与归档文件 test_results_yymmdd.zip （如上图中黄色图标的 test_results_201026.zip ）中的标准结果进行对比分析。

📋 测试案例一览表

测试编号	测试主题	主要物理对象	特点与用途
test1.0 / test1.1	Dreicer 逃逸电子率	逃逸电子	分布函数时间演化与稳态率对比；用于验证`Kulsrud` 模型
test2	欧姆电阻率	$j_φ, η_φ$	低碰撞率下的新古典电阻率计算与文献比较
test3	DIII-D 单射线 ECRH	ECCD 电流驱动	使用老式 `rayech` 射线；低功率验证；二/三次谐波阻尼
test4	EBW 波导 + O-X-B 模式转换	MAST 等离子体边界传播	使用 `genray` 生成 `disk-disk` 模式射线；支持 LCFS 外启动追踪
test5	多种离子 + 多束波加热	$D, H + F W + NB$	两种离子协同加热；适配 `NetCDF` 射线输入；参考实验案例
test6	多磁通面下 Dreicer 率	$RE\ vs.\ r/R$	模拟不同 $r / R$ 下逃逸速率与 `Kulrsud` 比较
test7（未执行）	TCV 装置径向输运	$χ_\perp, n(ρ)$	用于测试 CQL3D 的输运模块建模能力

✅ test1.0 / test1.1 – Dreicer 逃逸电子率计算

模拟经典的 Dreicer 电子逃逸现象；
对应论文：Kulsrud & Sun et al., PRL (1973)；
test1.0: 模拟整个分布函数的演化（时间演化，耗时约3.2秒）；
test1.1: 用更大时间步长快速获得最终稳态结果（稳态近似，约1.3秒）；
可调 finer 网格，高精度版本推荐网格 iy=200, jx=300（但耗时更长约10倍）。

✅ test2 – 欧姆电阻率（Ohmic Resistivity）

模拟托卡马克中电阻加热对应的环向电阻率；
比较 CQL3D 计算结果与文献中的解析模型；
输出 $η_φ = ⟨E_φ/R⟩ / ⟨j_φ/R⟩$ ：
- $resist_\phi$ ：电阻率（分布函数得出）
- $<E_\phi/R>/<j_\phi/R>$ ：推导的平均电阻率
支持 $ε = r / R$ 从 0 ~ 1 的电导率扫描；
讨论包括低碰撞率下的新古典电阻率；
log_test2 文件中记录了结果对比。

✅ test3 – DIII-D 装置中的单射线 ECRH 测试

使用0.5W低功率模拟，用于与线性电子回旋共振加热（ECCD）理论比较；
使用旧式文本输入 rayech，现代推荐使用 netCDF 格式射线文件；
可通过 pwrscale 放大电场获得 QL 效应；
使用名为 pltlimm=0.2 的参数限制速度图绘制范围；
包含2阶和3阶谐波的阻尼效应（nharm1=2, nharms=2）。

✅ test4 – EBW（电子伯恩斯坦波）disk-to-disk 射线传播/波导测试

模拟 MAST 装置中**电子伯恩斯坦波（EBW）**通过 O-X-B 模式转换传播到等离子体内部的过程，适配 O-X-B 模式转换的边界传播建模；
射线数据需来自 genray/test10 的输出 genray.nc ；
使用 raypatt='diskdisk' 模拟圆盘发射；
istep_in_lcfs=0 允许从圆盘起始点直接开始追踪，即使其在 LCFS 之外。