CQL3D编译指南

CQL3D编译指南

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

编译前准备见前文【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: dependencies
    command

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

CQL3D 中的Makefile

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

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

生成的目标文件的对比

✅ 主要区别对比：

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

❗注：

1. 第二个 makefile 中使用了 -static，需要本地系统具备 .a 静态库版本（如 libnetcdf.a），否则会因找不到语构而报错；

2. 如果你遇到 ‘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 逃逸电子率计算

• 模拟经典的 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 计算结果与文献中的解析模型；

• 输出 ${\eta }_{\phi }=⟨E_{\phi }/R⟩/⟨j_{\phi }/R⟩$ ：

  • $resis{t}_{\varphi }$ ：电阻率（分布函数得出）
  • $<E_{\varphi }/R>/<j_{\varphi }/R>$ ：推导的平均电阻率

• 支持 $\epsilon =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 之外。

✅ test5 – 多离子种 + 多束 FW 注入的 DIII-D 实例（多种离子、多频加热）

• 同时模拟 D 和 H 两种离子；
• 包括 NBI 注入与快波 ICRF 加热；
• 使用 genrayfw_18rays.nc 提供的实际 DIII-D 输入射线实验数据；
• 使用简化版本输入 cqlinput_H0.short_mmsv8_adjust.4 ，支持扩展到完整运行。；
• 参考案例见 D3D_ngen2_urf_NBI_H.short_rerun_201018 （不在项目文件中）。

✅ test6 – 多磁通面下 Dreicer 逃逸速率 vs 逆环向比 ε

• $E/E\_D=0.16$， 可与 Kulsrud (1973) 实验中的理论曲线对比；
• 模拟多个 $r/R$ 点下的逃逸电子，可比较不同 $r/R$（等离子体小半径 / 大半径比）对逃逸速率的影响；
• lbdry(0)="conscalm" 保持总电子密度恒定；
• 使用碰撞模型 colmodl=1（背景离子碰撞模型），可切换碰撞模型： colmodl=3 ；
• 相比 Kulsrud 模型结果略小，误差来自于陷波区域处理。

表格摘要如下：

✅ test7 – TCV 装置的径向输运测试（未执行）

• 模拟电导、粒子密度在 $\rho$ (小半径) 上的变化；
• 用于评估 CQL3D 对 TCV 等离子体的径向粒子输运源项、背景剖面对演化的影响；
• 属于电磁波与输运耦合测试。

🧠 应用建议

• 🔬 理论验证：test1/test6 可用于经典理论验证（如 Dreicer runaway）。
• 🧪 建模仿真：test3/test4/test5 提供典型设备配置输入模板。
• 🧯 热输运评估：test2/test7 可测试新古典输运及背景影响。
• 🧰 代码测试：通过比对运行结果是否一致判断 CQL3D 编译或功能变更是否影响精度。

@Date: 2025.6.8
@Author: zkinglin
（完）