CQL3D输入文件及参数解释

CQL3D输入文件及参数解释

CQL3D 简介

​ CQL3D是一个相对论性碰撞/拟线性三维环形几何代码，它通过求解反弹平均福克-普朗克方程来计算电子和多组分离子的分布函数。这些分布是由碰撞、射频（RF）/中性束/粒子源、外加环形电场及径向扩散之间的平衡决定的。该程序支持稳态和时间相关的解决方案，并可选择同时求解环形电场的安培-法拉第方程。CQL3D的主要目标是为托卡马克装置中的加热和电流驱动提供精确计算的能力。

​ CQL3D能够与LH、FW、EC 和 EBW 射线追踪或全波（如 AORSA 和 TORIC-LH ）射频数据、FREYA 中性束沉积软件包以及给定的环形电场结合使用，从而模拟从等离子体外围注入的辅助加热和电流驱动导致的电子和离子分布函数的变化。代码基于假设：环境磁场的分布是环形对称的，且与环境磁场的方位角无关。径向漂移被忽略。随着反弹平均，考虑的变化作为一个函数 (非圆形) 径向坐标，极向角，和两个动量空间方向。包括动力学自举电流计算。该程序可以在每个通量面上进行单独的二维动量空间求解，在三维模式下根据给定的扩散项和箍缩项进行径向输运。

​ 此外，CQL3D还用于解释和影响了多个重要的射频电流驱动实验和建议，包括在 DIII-D 和 ITER 上的应用，并在逃逸电子问题的研究中找到了新的应用方向。其结果对实验设计和理论预测提供了重要支持，有助于优化托卡马克装置的性能。

​ 源代码地址: https://github.com/compxco

• 输入（Input）：

  • EQDSK equilibrium B field: EQDSK 格式的磁平衡数据，提供磁场配置信息。
  • Time-dependent radial plasma profiles: 随时间变化的径向等离子体参数剖面，如密度、温度等。

• CQL3D的核心功能（Features）：

• Bounce-Average $f_{e,i}(u_0,{\theta }_0,\rho ,t)$: 使用平均碰撞频率来求解 Fokker-Planck 方程，其中$u_0$是速度，${\theta }_0$是角度，$\rho$是径向坐标，$t$是时间。

• Multi-species: 支持多种粒子物种的模拟。

  • Fully 3D implicit Transport: 完全三维隐式传输模型，能够处理复杂的几何结构和物理过程。
  • Toroidal DC electric field: 托卡马克环向直流电场的影响。
  • Large-angle e-collisions (giving knock-on elec source): 大角度电子碰撞，产生次级电子源。
  • Full nonlinear relativistic collision coeffs.: 完全非线性的相对论碰撞系数。
  • Monte-Carlo NFREYA neutral beam source: 使用蒙特卡洛方法模拟 NFREYA 中性束源。
  • Loss regions in $u_0$-space: 在速度空间中定义损失区域，包括即时香蕉损失和涟漪损失。
  • Radial diffusion and pinch; $(u_0,{\theta }_0,\rho )$-dependence: 径向扩散和夹紧效应，依赖于速度、角度和径向坐标。
  • Up-down non-symmetrical equilibrium capability: 上下不对称平衡的能力。

• 存储/可视化（Storage / Visualization）：

• NetCDF data files → .nc files: 使用NetCDF格式存储数据文件，便于数据交换和分析。

  • PGPLOT → .ps files: 使用PGPLOT库生成PostScript文件，用于图形输出和可视化。

输入文件: cqlinput

​ CQL3D 输入文件（ cqlinput ）用于指定CQL3D射线追踪代码的运行参数。该文件采用名称列表（ namelist ）格式，每个名称列表包含一组相关的参数及其描述（CQL3D_Input_namelist_description）。

​ 以下是主要字段列表及其参数的详细描述。

namelist 组名	作用
&setup0	是对原始 &setup namelist 的拆分，主要包含一些基础配置参数，现推荐使用
&setup	原始配置段，保留主要的运行控制参数，如时间步进、网格设置、差分方法、物理模型选择等
&sousetup	解析源和反冲电子源设置
&eqsetup	磁平衡/磁几何输入设置，用于读取和处理等离子体的磁平衡几何结构
&rfsetup
&trsetup	粒子和能量的径向输运过程输入设置，提供了多种方法来求解包含径向扩散项的三维 Fokker-Planck 方程
&frsetup	模拟中性束注入（Neutral Beam Injection, NBI）粒子在等离子体中的沉积分布（基于 GA Technologies 的 ONETWO 代码中的 FREYA 子程序）

​ 在 cqlinput 输入文件中，"setup" 这个 namelist 组出现了两次（现已弃用该写法：虽然仍可使用，但建议改用 &setup0）。&setup0 为 新版设置（兼容 SWIM 集成等离子体模拟器平台等集成模拟），&setup 为 主控设置（包含时间步进与网格控制等），两者组合使用。

---

一、&setup0 基本运行控制信息配置

​ 以下变量必须放入 namelist 组 &setup0 中。

变量名	类型	功能	默认值
mnemonic	字符串	运行名称标识，生成输出文件（如： .ps 文件）的前缀 最多允许48个字符（即 a48）	"mnemonic"
ioutput	整数	图形输出控制（（目前仅支持PS格式，已废弃）	无定义
iuser / ibox	字符串	用户标识和盒子编号（目前无实际作用）	无定义
machinea	整数	指定整型字长。 代码中变量使用的最大维度由 param.h 文件设定。代码可以使用比这些参数小的维度，具体由以下 namelist 变量控制：lrz, lrzmax, ls, lsmax 等。	=1：8 字节整数；=2：4 字节整数
noplots	字符串	是否抑制绘图	"disabled"（默认）/ "enabled"
lnwidth	整数	设置绘图线宽属性。影响线条、标记和文字大小（单位：0.005 英寸）	3 建议使用较小的值，更适合矢量图，从 .ps 转成 .pdf 后图像质量更好
nmlstout	字符串	是否输出 namelist 到标准输出/终端 stdout	"trnscrib"（默认，直接复制 cqlinput 文件内容输出）/ "enabled"（打印）
special_calls	字符串	是否调用系统命令收集主机/环境信息	"enabled"：尝试调用 uname 和 pwd / "external"：使用外部文件 uname_output 和 pwd_output / "disabled"：不调用任何系统命令
※ cqlpmod	字符串	控制 CQLP 模式使用	无默认值
※ lrz	整数	在计算网格上求解 F-P 方程的径向通量面数量	根据 lrzdiff 决定（※ lrz = 1）
※ lrzmax	整数	总通量面数量（包括那些不进行F-P求解的）； lrzmax=1：单通量面运行（不读入背景剖面）； lrzmax ≥ 4：读入密度等剖面； lrzmax = 2,3：应避免使用（可能导致样条插值问题）； 如果 lrzdiff ≠ enabled，则 lrzmax = lrz	lrzmax = lrz
※ lrzdiff	字符串	是否只在部分网格点求解分布函数/精细剖分（启用可优化性能）。（如果只关心某些径向位置上的结果，可以用这个选项让程序只在这些位置求解分布函数，其余位置则通过插值等方式处理，从而节省计算资源。）	"disabled"
※ lrindx(1:lrz)	整数数组	指定哪些索引的网格点/通量面要进行F-P求解。若 lrz = lrzmax（默认值，即所有通量面都求解），就不需要设置这个数组。	[1:lrz]
※ ls / lsmax	整数	通量线数量相关参数	无默认值
※ lsdiff / lsindx	字符串 / 整数数组	与 ls 类似的差分控制	无默认值
※ nlwritf	字符串（原逻辑值）	是否在运行结束时将最终状态的粒子分布函数保存到文件 distrfunc.nc 中。便于后续重启或分析	"disabled"（默认）/ "enabled"：写入文本文件 / "ncdfdist"：不写入文本文件，而是使用 NetCDF 文件（mnemonic.nc）
※ nlrestrt	字符串（原逻辑值）	是否从文件 distrfunc.nc 中读取初始分布函数，重启模拟。便于从上次运行的结果继续模拟（热启动），而不是从头开始	"disabled"（默认）/ "enabled" ：从文本文件读取 / "ncdfdist" ：从 NetCDF 文件（如 distrfunc.nc）读取 / "ncregrid" ：同上，但可以重新设置速度空间/动量网格（如 enorm, jx, xfac）

⚠️注：带 ※ 的为可用于 CQLP模式 运行的参数。

CQLP模式

​ CQLP模式是 CQL3D 中的一个新的选项，它实际上代表了一种新的运行模式，用于求解沿磁场线方向的 Fokker-Planck 方程而不简化弹跳平均。这种模式的主要特点如下：

1. 解决FP方程时考虑了沿磁场线的变化：与传统的 CQL3D 相比，CQLP 不进行弹跳平均处理，而是直接在 $(u,theta,s)$ 三个维度上解决问题，其中s表示沿着磁场线的距离。

2. 空间维度变化：在实践中，只需将空间维度从 CQL3D 中的 $\rho$ （通常指径向位置）改为 $s$ （即沿磁场线的距离），并移除弹跳平均步骤即可实现 CQLP 模式。

3. 数组重用：大多数用于 CQL3D 的数组也可以用于 CQLP ，只是索引l现在遍历的是 $s$ 网格而不是径向网格。

4. 额外输入参数：启用 CQLP 模式需要在第一个 namelist &setup0 中设置一些额外的输入参数，例如：

   • cqlpmod: 设置为 "enabled" 来运行 CQLP （默认 "disabled" ）。
   • lsmax: 沿 $s$ 方向的最大网格点数。
   • ls: 实际上求解 F-P 方程的 $s$ 网格点数。
   • lsdiff: 如果设置为 "enabled" ，允许ls不等于lsmax。
   • lsindx(0:ls): 列出了求解FP方程的ls索引列表。
   • nlwritf: 如果设置为 "enabled" ，则保存运行结束时的分布函数（默认 "disabled" ）。
   • nlrestrt: 如果设置为 "enabled" ，则从文件distrfunc.nc读取初始分布函数（默认 "disabled" ）。

因此，CQLP 模式的主要作用在于提供了一种更精确的方法来模拟等离子体中粒子的行为，特别是在考虑沿磁场线方向的变化时，避免了弹跳平均带来的简化，从而可能提供更加准确的结果。这对于研究某些特定物理现象或条件下的等离子体行为可能是非常重要的。

二、&setup 运行控制参数

​ 控制等离子体几何、物理参数、粒子种类、能量网格等

​ 下表为该字段变量的类别，部分变量名及其类别说明。

类别	变量名	说明
时间控制	dtr, dtr1, nondtr1, nstop, nrstrt	时间步长与运行周期设置
网格设置	jx, iy, lz, vnorm, enorm, xfac, tfac, rfacz 等	各向速度与空间维度网格划分方式
计算方法	chang, implct, ineg, soln_method, manymat, droptol, lfil	差分格式、求解器、预条件器等控制
边界条件	lbdry(k), lbdry0, taunew	每种粒子的边界与传播方式设置
几何结构	machine, psimodel, radmin, radmaj, btor, bth 等	装置类型与参数（如托卡马克或镜面）
物理模型	colmodl, kfield(k), trapmod, scatmod, qsineut 等	碰撞模型、场影响、粒子损失控制等
物种设置	ngen, nmax, kspeci, fmass, bnumb, reden, temp, iprote, iproti 等	粒子物种及其密度温度剖面设置

---

🕒 主要时间步长控制（MAJOR TIME STEP CONTROLS）

​ 该字段用于控制模拟的时间推进方式。

参数名	类型/用途说明	默认值	补充描述
dtr	主时间步长（秒）。数值越大，模拟推进越快，但可能导致精度下降；数值太小会增加计算时间。	5.0	① 初始时，时间步计数器 n=0，每完成一步后自增。 ②在隐式稳态计算中（transp="disabled"），dtr 可以设得很大而不违反物理条件。 - 典型取值范围为：dtr = 1.0 ~ 10.0（当 implct="enabled" 时）。 - 这样可以让代码“跳跃”到稳态解（适用于线性问题）。 ③ 如果启用输运模型（transp="enabled"），则 dtr 应小于或接近非热粒子的碰撞时间，以保证结果准确性。
dtr1(1:10)	一个包含最多10个额外时间步长设置的数组，用于不同阶段。例如在物理过程变化剧烈时减小步长提高精度，在平稳阶段增大步长加快速度。	所有元素为 0.0	每个元素可以比主步长 dtr 更大或更小； 这些新步长从对应的时间步 nondtr1(i) 开始使用。
nondtr1(1:10)	指定每个 dtr1(i) 对应的新时间步长开始使用的起始时间步。配合 dtr1() 使用，用于在特定时间点切换时间步长大小。	所有元素为 -1（表示不启用）	若 nondtr1(i) > 0，则从该步开始使用对应的 dtr1(i) 若不满足模 mod(nondtr1(), nrstrt) = 0，则自动调整为下一个符合条件的步数
nstop	要运行的总时间步数或周期数	5	决定整个模拟总共进行多少次时间推进。例如：若 nstop=100，程序将从 n=0 推进到 n=99，共100步。
nrstrt	多通量面推进次数，即在移动到下一个通量面之前，在当前通量面上推进的循环次数（已弃用），仅支持默认值 nrstrt=1	1（唯一支持）	仅当 lrz > 1（即有多个径向通量面）时有效
nplot(1:nplota)	指定绘图的时间步	全0（表示无特殊绘图步）	用于指定哪些时间步需要输出绘图数据（针对各个通量面）。例如： nplot = 10, 20, 30 表示第10、20、30步输出图像。
iactst	调试模式开关，控制是否调用一些诊断子程序	"disabled"（默认）：不启用任何调试功能； "enabled"：启用调试诊断工具，如 diagimpd, exsweepx, exsweept； "abort"： 如果误差大于 1.e-8（相对误差），则终止程序	开发者调试选项，通常在开发和测试阶段使用，用于检查求解器的稳定性与精度

---

🧮网格控制（MESH CONTROLS）

​ 该字段描述了 CQL3D 模拟中使用的各种物理空间网格设置，包括速度、动量、极角、磁场线坐标等维度的离散化方式。这些参数对模拟精度和性能有重要影响。

参数名	类型	用途简述	默认值	补充描述
jx	整数	速度/动量网格点数，在相对论计算中表示动量/静止质量。	300（定义在 aindflt.f 文件中）；范围：0 ~ xmax=1.0	决定了分布函数在速度空间的分辨率。数值越大，精度越高，但计算成本也更高。
iy	整数	$\theta$ （俯仰角）方向上的网格点数。关于 $\pi /2$ 对称。	200，必须为偶数	当 $\theta$ 表示粒子速度与磁场方向之间的夹角，用于区分“平行”和“垂直”速度分量。此参数控制该角度方向的分辨率。urfmod="enabled" 时，若 iy > 255 可能会导致数组存储问题（BH070418 注释说已放宽限制）
lz	整数	极向/磁场线方向上的网格点数。用于计算弹跳平均。	约束条件：lz ≤ lza（lza 为一预设参数）	决定沿着磁场线方向的离散点数量，用于处理粒子在磁镜中的反弹行为。
vnorm	实数	速度归一化常数（单位：cm/s）。在相对论计算中表示最大动量/静止质量。	默认值由 enorm 设置决定	作为缩放因子，用于将实际速度映射到归一化的速度网格上
enorm	实数	能量归一化常数（单位：keV）。	200.0（kenorm=1）	用来指定某个离子的能量作为速度网格的最大值。如果指定了物种索引 kenorm，则使用该物种的能量来设定 vnorm。
tandem	字符串	是否启用电子-离子混合网格。	"disabled"	适用于需要同时研究电子和离子行为的情况，例如高能电子加速过程。启用后，速度网格扩展至电子能量 enorme 的上限，但在低速区域更密集地分布以更好描述离子。
enorme, enormi	实数	tandem 模式下的电子和离子能量上限	无默认值	配合 tandem="enabled" 使用，分别控制电子和离子部分的网格划分
relativ	字符串	是否启用相对论网格	"enabled"（默认）：启用准相对论计算网格； "fully"：完全相对论计算（有一定限制，如勒让德多项式展开阶数 mx ≤ 3）	选择是否考虑相对论效应，适用于高温等离子体或高能粒子模拟
xfac	实数	控制速度网格分布方式/速度网格间距参数	xfac=1（默认）：均匀网格； xfac<1：在 x=0 处加密； xfac>1：在 xmax 处加密； xfac<0：需手动输入 xpctlwr, xpctmdl, xlwr, xmdl 参数，用于三段式网格划分	用于调整速度网格密度分布，适合不同物理场景的需求
tfac	实数	$\theta$ 角度网格间距参数	tfac=1（默认）：除边界附近外为均匀网格； tfac<1：在 pass-trapped 边界附近加密； tfac>1：在 $0,\pi /2,\pi$ 附近加密 tfac=-1：适用于径向输运（transp="enabled"），保持各半径下 $\theta$ 均匀分布	控制俯仰角网格的分布，尤其在粒子从束缚态过渡到自由态的边界区域
yreset	字符串	是否在指定区域加密 θ 网格点数	"disabled" 注：当前不支持 lrz > 1 的情况	用于提高某些特定角度区间的分辨率，如靠近共振区域
numby	整数	在 yreset $\theta$ 加密区域内使用的额外网格点数	20（仅当 yreset="enabled" 时有效）	建议远小于 iy/2，否则其他区域分辨率会下降
ylower, yupper	实数	加密区域的上下限 / 弧度范围	低于 $\pi /2$	注意避免包含 pass-trapped 边界区域
tfacz	实数	磁场线坐标 z 的网格间距参数	1	对于 eqsym="none" 不起作用，此时 z 网格是均匀的
tbnd(1:lrorsa)	数组	pass-trapped 边界层宽度（单位：弧度）	tbnd=0.002, tbnd(2:lrorsa)=0.0	用于控制粒子在束缚态与自由态之间转换区域的网格精细程度
rfacz	实数	径向网格间距参数，类似于 xfac 对速度网格的作用	0.7	无
roveram	实数	控制最内侧通量面位置 / 最小通量面位置 $r/radmin=rya(1)$	1.e-8（即自动确定）	防止最内侧网格过于接近磁轴，造成数值不稳定
rzset	字符串	是否允许用户自定义径向网格 $rya(l)/radmin$	"disabled"	提供更大的灵活性，可直接指定每个通量面的位置
rya(l) (l=1,lrzmax)	数组	归一化的自定义径向网格值。代码内部数组，维数为 rya(0:lrza+1)	无默认值	用于精确控制径向网格划分，适用于非标准几何结构。用户可指定如 rya(1)=0.02, rya(2)=0.05, …, rya(23)=0.95（当 lrzmax=23 时）
radcoord	字符串	径向坐标的定义方式 / 选择径向坐标的类型	"sqtorflx"（默认值）：与 toroidal flux 的平方根成正比； "sqarea"：面积平方根； "sqvolume"：体积平方根； "rminmax"：通量面主半径差的一半； "polflx"：从磁轴到 LCFS 的归一化 poloidal flux； "sqpolflx"：poloidal flux 的平方根； ⚠️注：只有 "sqtorflx" 支持径向扩散方程	选择不同的径向坐标有助于适应不同的等离子体几何结构和物理模型

---

🧮差分格式和求解方法控制（DIFFERENCING and SOLUTION METHOD CONTROLS）

​ 该字段描述了 CQL3D 模拟中使用的数值差分格式、线性方程组求解方法、边界条件设置等关键参数。这些选项直接影响模拟的稳定性、精度和计算效率。

参数名	类型	用途简述	默认值	补充描述
chang	字符串	差分格式选择（Chang-Cooper / 中心 / noneg）	"enabled"（默认）：使用 Chang-Cooper 格式； "disabled"：使用标准中心差分格式； "noneg"：在强射频场驱动下，采用额外机制以最小化负分布值	见[Chang-Cooper 自适应差分格式](#· Chang-Cooper 自适应差分格式)
ineg	字符串	负分布处理方式（清零 / 归一 / 截断扩散）	"enabled"（默认）：每步后将负值重置为零（清零）； "renorm"：如果出现负值，则加上 $1.1\times \mid f_{min}\mid$ ，并乘以归一化因子以保持粒子总数不变（归一）； "trunc_d"：在最后10个速度网格点平滑减小 QL 扩散系数，并将负值重置为零（截断扩散）	由于数值误差，分布函数可能出现负值，这对物理意义是不合理的。此参数提供了三种处理方式，适用于不同情况。
implct	字符串	是否使用隐式差分方法	"enabled"（默认）：使用隐式差分 + 高斯消元法（调用 LAPACK 子程序）； "disabled"：使用算子分裂法（用于时间依赖问题）	隐式方法更稳定，适合稳态或缓慢变化的问题；显式方法适合快速变化的问题，但可能需要较小的时间步长。
manymat	字符串	是否保留所有通量面上的矩阵于磁盘（仅适用于soln_method="direct"）	"enabled"（默认）：保留所有已分解矩阵，避免重复因式分解，节省时间（推荐） "disabled"：每次重新计算，适用于单通量面问题	启用后可大幅提高多通量面模拟效率，尤其在多次时间步推进时效果显著
soln_method	字符串	求解方法（direct / itsol / it3dv / it3drv）	"direct"（默认）：使用 LAPACK 的 dgbtrf/dgbtrs 直接 LU 分解法； "itsol"：使用 SPARSKIT2 的 GMRES 迭代求解器 + ILUT 预处理； "itsol1"：将 LAPACK 矩阵转为 CSR 格式后使用 "itsol" 方法（用于交叉验证）； "it3dv"：全三维速度空间联合求解（支持多个通量面）； "it3drv"：包含径向输运项的全隐式三维求解	不同求解方法适用于不同规模和复杂度的问题。直接法稳定但内存消耗大；迭代法适合大规模稀疏矩阵。
droptol	实数	ILUT 预处理舍入容限	1.d-3	droptol 和 lfil 共同控制预处理的精度和效率。droptol 决定哪些小元素被忽略；lfil 控制每一行最多保留多少非零元素。
lfil	整数	LU 因子最大填充非零项数量	30	droptol 和 lfil 共同控制预处理的精度和效率。droptol 决定哪些小元素被忽略；lfil 控制每一行最多保留多少非零元素。
lbdry(k)	字符串数组	第 k 类物种在 v=0 处的边界条件	"conserv"（默认）：守恒型边界条件（v=0 处无净通量，且密度不变）； "fixed"：v=0 处分布值固定不变 ； "scale"：分布整体缩放以保持总密度不变	不同边界条件适用于不同的物理场景。例如，电子通常使用 "conserv"，而某些离子可用 "fixed" 或 "scale"。
lbdry0	字符串	隐式推进中 v=0 处 f 的处理方式（新/旧系统）（仅当 implct="enabled" 时有效）	"enabled"（默认）：使用新系统，调用 impavnc0 子程序，确保唯一解； 其他值：使用旧系统，调用 impavnc，先计算平均密度再设定 f(v=0)	新系统提高了数值稳定性，适用于大多数情况
taunew	字符串	$\tau$ 和 $d\tau$ 的计算方式	"disabled"（默认）：部分解析方法（Killeen 等人书中的传统方法）； "enabled"：完全数值积分（更精确）；	在非对称磁场配置（eqsym ≠ "none"）下，建议使用数值方法；但在 eqsym="none" 时，也可使用解析方法。
nstps	整数	用于 $\tau$ 和 $d\tau$ 积分的 $dz$ 子区间数	100	该参数决定沿磁场线方向积分的精度。数值越大越精确，但计算耗时增加。

· Chang-Cooper 自适应差分格式

​ Chang-Cooper 自适应差分能根据对流项与扩散项的比值自动调整为“中心”或“迎风”格式。在强 RF 场下，即使使用该格式也可能导致分布函数出现负值。为此，程序引入了一种改进方案，在速度方向上使用修正公式：
$$ratio=\frac{dx\cdot A\cdot B}{(B-B_{ql}{)}^2}$$
​ 其中 $B_{ql}$ 表示准线性扩散系数。当 $B_{ql}$ → 0 时，恢复为原始 Chang-Cooper 格式。

​ 对于俯仰角方向（$\theta$），若设为 "noneg"，则在之前时间步出现负值的区域强制使用单边差分。

⚠️ 注：所有这些调整都是实验性的，并未经过严格的数学证明。

---

🧱 机器几何（MACHINE GEOMETRY）

​ 该字段用于设置 CQL3D 模拟中所使用的磁场几何模型（托卡马克或镜像装置），以及相关的几何参数和磁位函数建模方法。

参数名	类型	用途简述	默认值	补充描述
machine	字符串	选择磁场类型（toroidal / mirror）	"toroidal"（默认）：环形磁场（托卡马克）； "mirror"：镜像磁场（磁镜装置）	此参数决定了整个模拟的空间结构。对于托卡马克等环形装置，通常使用 "toroidal"；而对称的镜像装置使用 "mirror"。 ⚠️注：若选择 "mirror"，则启用 Gary Smith 的 B 场模型选项。 当 &setup0 字段中的 lrz > 1（多通量面）时，不支持 "mirror"。
psimodel	字符串	磁位函数 $\psi (z)=B(z)/B(0)$ 的建模方式（axitorus / smith / spline）	"axitorus"（默认）：标准的 $1/R$ 变化形式，适用于圆形截面（推荐用于非 MHD 平衡情况）； "smith"：Gary Smith 提出的镜像场模型； "spline"：通过样条插值计算 $\psi (z)$ ，常用于 MHD 平衡模块（eqmod 启用时）结合 eqdsk 文件使用； ⚠️注：如果启用了 eqmod（即 eqmod ≠ "disabled"），则自动切换为 "spline"	该参数决定磁场沿磁力线方向的变化方式。在使用真实等离子体平衡数据时（如从 EFIT 获取的 eqdsk 文件），应使用 "spline"。
gsla, gslb, gsb, gszb	实数	[镜像装置磁场分布模型](#· 镜像装置（mirror machine）中的磁场分布模型)参数。gsla , gslb 为磁场尺度长度；gsb , gszb 为控制镜像峰位置与强度的参数（仅当 machine="mirror" 且 psimodel="smith" 时有效）	gsla=270 , gslb=35	这些参数用于构建镜像装置中的磁场分布，特别是两个“镜像峰”区域的位置和形状。
ephicc	实数	镜像喉部势能跳跃（单位：keV）	0	用于确定损失锥边界。该参数影响粒子在镜像装置中的捕获与逃逸行为，数值越大表示镜像比越强，损失锥范围越小。
zmax(1)	实数	从赤道面到镜像喉部的沿磁场线弧长（单位：cm），仅用于 machine="mirror"	无默认值	决定了粒子在磁场中的运动路径长度
rmirror	实数	镜像比（磁感应强度最大值与中心值之比）	2.0	镜像比越大，粒子被限制得越好，损失锥越小
radmin	实数	托卡马克小半径（单位：cm）	50.0	用于 machine="toroidal" 注意：若启用了 eqmod，则无需设置此项
rovera	实数数组	归一化小半径（$r/a$），用于指定当前模拟的通量面	0.1	仅用于 lrz=1（单通量面）且 rzset ≠ "enabled" 1° 若 rovera < 1e-8，将被重置为 1e-8； 2° 若 rovera < 0，必须启用 eqmod，并通过 povdelp 参数指定通量面
radmaj	实数	托卡马克大半径（单位：cm）	100.0	仅在 eqmod="disabled" 且 psimodel="axitorus" 时使用
btor	实数	轴心处环向磁场（单位：G）	1.e+4	仅在 eqmod="disabled" 且 psimodel="axitorus" 时使用
bth	实数	边缘处极向磁场（单位：G），定义于 $\pi /2$ 极角位置	1.e+3	仅在 eqmod="disabled" 且 psimodel="axitorus" 时使用

· 镜像装置（mirror machine）中的磁场分布模型

• $\psi (s)$ 表示的是归一化的磁感应强度分布，即：
  $$\psi (s)=\frac{B(s)}{B(0)}$$
  其中：

  • $s$ ：是沿磁力线从中心点（通常为镜像装置的赤道面）出发的距离；
  • $B(s)$ ：是位置 $s$ 处的磁感应强度；
  • $B(0)$ ：是中心点处的磁感应强度。

  因此，$\psi (s)$ 描述了磁场如何随位置变化。

• 该代码中的磁场强度沿磁力线方向变化的分布函数，由下式描述：

$$\psi (s)=\frac{1+(s/gsla{)}^2+gsb\cdot e^{-(s-gszb{)}^2/gsl{b}^2}+gsb\cdot e^{-(s+gszb{)}^2/gsl{b}^2}}{N}$$

• 上式中：
  • 基础项 $1+(s/gsla{)}^2$ ：抛物线型背景磁场项。它表示磁场在中心区域缓慢增加，形成一个基础的磁场平台。
    • gsla 为背景坡度，是一个尺度长度参数。
  • 镜像峰项 $gsb\cdot e^{-(s\pm gszb{)}^2/gsl{b}^2}$ ：这两项分别代表 2 个对称的镜像峰：第一个峰位于 $s=gszb$ ，第二个峰位于 $s=-gszb$ 。指数形式表示这些峰是高斯形状的，符合实际镜像装置中磁场增强的分布特征。
    • gsb 控制峰的高度；
    • gszb 控制峰的位置；
    • gslb 控制峰的宽度。
  • 归一化因子 $N$ ：在中心点 $s=0$ 处有 $\psi (0)=1$ ，即 $B(0)$ 被设为基准；并且 ${\psi }^{\prime }(0)=0$ ，即磁场梯度在中心为零，保证对称性。

---

🧪物种描述（SPECIES DESCRIPTORS）

​ 该字段详细说明了 CQL3D 模拟中所有粒子物种（species）的定义和初始化设置。包括类型索引 k 的含义；一般类型（general species）与背景麦克斯韦类型（background Maxwellian species）的区别；初始密度、温度剖面设置；有效电荷数 Zeff 的处理；分布函数的额外加载（用于研究电子击穿逃逸等现象）。

· 字段说明

1. 粒子物种索引 k

• 在以下描述中，索引 (k) 表示第 k 个粒子物种。

• 根据设定：

  • 如果 1 ≤ k ≤ ngen：表示该种粒子是 一般物种，其分布函数随时间演化。
  • 如果 k > ngen：表示该种粒子是 背景麦克斯韦分布物种，其分布为静态的、不随时间变化的麦克斯韦分布。

📌 通俗理解：

• 一般物种：模拟过程中需要求解其速度空间分布函数 $f(v,\theta )$ 的演化。

• 背景物种：作为静态背景存在，只提供温度 temp(k) 和密度 reden(k)。

2. 物种表示方式

类型	表示方法	描述
一般物种（General species）	f(theta, x, k, l_)	分布函数随时间演化，需要数值求解
背景物种（Background species）	temp(k) 和 reden(k)	温度和归一化密度，假设为麦克斯韦分布

3. 编号顺序规则

• 所有一般物种必须排在背景物种之前。

• 电子和离子可以混合编号。

• 同一种粒子可以同时出现在一般物种和背景物种中（例如：部分电子用动态分布函数建模，其余作为背景处理）。

📌 举例说明：若 ngen=2 ，则 k=1, 2 是一般物种（如快电子、离子束）；k=3, 4, ... 为背景麦克斯韦物种（如热电子、热离子）。

4. 多个麦克斯韦离子的排列要求

​ 如果存在多个麦克斯韦分布的离子物种（如 H⁺, D⁺, T⁺），它们之间不能被电子物种隔开。

⚠️ 错误排列示例：

k=1: H+ (Maxwellian)
k=2: e- (Maxwellian)
k=3: D+ (Maxwellian)
# 👉 会导致错误，因为 D⁺ 被电子隔开了。

✅ 正确排列示例：

k=1: H+
k=2: D+
k=3: T+
k=4: e-

或者：

k=1: H+
k=2: D+
k=3: e-
k=4: He+

5. 同类离子连续排列建议

​ 如果有多个具有相同电荷数的离子（例如 H⁺, D⁺, T⁺），应将它们连续排列在麦克斯韦离子物种的起始位置。

📌 目的： 便于程序内部识别和处理同位素或同类型离子，避免逻辑混乱。

✅ 示例：

k=1: H+
k=2: D+
k=3: T+
k=4: e-
k=5: Ar++

· 物种描述段参数表格

参数	类型	含义	默认值	补充描述
ngen	整数	一般物种数量	ngena	无
nmax	整数	背景麦克斯韦物种数量	nmaxa	无
ntotal	整数	总物种数量（=）	ngena + nmaxa	无
kspeci(1,k)	字符串	第 k 个物种的名称	无默认值	无
kspeci(2,k)	字符串	第 k 个物种的类型	"general" 或 "maxwell"	无
fmass(k)	实数	第 k 个物种的质量（单位：克）	1.e-29（默认值） ⚠️注：离子质量通常大于 1.e-27	无
bnumb(k)	实数	原子序数	1.（默认值） 电子为 -1.	无
iprote, iproti, iprone, iprozeff, iproelec, iprovphi, ipronn	字符串	电子温度、离子温度、密度剖面、有效电荷数 Zeff 剖面、电子密度是否独立设置、平行电势剖面、中性粒子密度剖面（见后）的类型	"parabola" （默认）：抛物线剖面模式； "spline" ：适用于用户提供了实验或模拟数据的情况； "asdex" ：ASDEX 是一种托卡马克装置，此模式内置指数形式剖面，用户无需手动输入	无
抛物线剖面模式（"parabola"）
npwr, mpwr	实数	抛物线剖面模式参数	npwr(k)=2.0， mpwr(0)=1.0（密度）， mpwr(k)=3.0（温度）	$Profile(r)=(center-edge)\cdot [1-(r/a{)}^{npwr}{]}^{mpwr}+edge$ center 为中心值，edge 为边缘值； npwr(k) 、 mpwr(k) ：实数，控制剖面形状； npwr(0) 、 mpwr(0) ：用于密度剖面；
reden(k,l)	实数数组	初始密度（单位： $particles/c{m}^3$ ）	1.0	l=1,lrzmax 1° 对于 lrz > 1： 用户指定 reden(k,0)（中心）、reden(k,1)（边缘） 中间点由代码自动插值得出； 2° 对于 lrz = 1（单通量面）： 只需指定 reden(k,1)
temp(k,l)	实数数组	初始温度（单位： $keV$）	1.0	同上
profpsi	字符串	是否使用 $\psi$ 函数构造剖面	"disabled"（默认）：使用上面的 npwr, mpwr 构造剖面； "enabled"：使用早期版本的老式方法（见右侧）（⚠️注：此模式已较少使用）	r e d e n ( k , l ) = r e d e n ( k , 0 ) ⋅ ( ψ ( l ) − ψ