xTB命令与C接口功能导航
按任务整理当前93个长选项与40个C接口符号，连接真实实例并明确别名、外部条件和无效模式。
阅读本篇目录
下载xTB操作、筛选和IFF完整输入与真实结果，保存为example.zip：
python3 -m zipfile -e example.zip .
cd xtb-operations-examples
bash results.sh
bash plot.sh
以上只读取参考数据并画图，不启动新计算。本组使用xTB6.7.1官方预编译x86_64程序，直接加载xtb/6.7.1模块，无需自己编译；实际运行每个进程使用1个CPU线程。完整输入在inputs/，原生文本结果在reference-results/，六份CSV在data/。独立提交模板为job.slurm，请在Slurm分配的资源中执行计算命令。
1. 从任务进入，不必背93个选项#
当前6.7.1固定源码解析器有93个长选项，包含别名、输出控制、外部程序和已失效入口，不是93种独立计算方法，也不表示每个开关都已成功运行。下表逐项列出名字、用途和对应操作指南；本批实际新增20个短条件，其中18个正常，2个确认无效。
module load xtb/6.7.1
xtb --help
xtb --version
python3 -m json.tool CLI-REGISTRY.json
| 功能 | 对应选项 | 操作入口与边界 |
|---|---|---|
| 模型与电子数 | --gfn、--gfn0、--gfn1、--gfn2、--gfnff、--gff、--tblite、--ptb、--ceh、--spinpol、--chrg、--charge、--uhf |
操作指南。GFN编号/方法别名、tblite后端、PTB/CEH、电荷与未成对电子。PTB不提供普通总能/力。 |
| 单点与收敛 | --scc、--sp、--grad、--acc、--etemp、--iterations、--maxiterations、--cycles |
操作指南。单点、梯度、SCC精度/电子温度/迭代上限、几何优化步数；不同停止条件分别解释。 |
| 优化与声子 | --opt、--hess、--ohess、--bhess、--modef |
操作指南。优化、Hessian、优化后频率、有偏Hessian和模式跟随；模式跟随需要已生成的Hessian。 |
| 反应性 | --vip、--vea、--vipea、--vomega、--vfukui |
操作指南。垂直IP/EA、全局亲电性与Fukui指标；保持核坐标相同，注意模型和电荷设置。 |
| 电子性质与图件 | --pop、--wbo、--dipole、--molden、--lmo、--esp、--fod、--stm、--alpha、--raman、--dipro |
操作指南。电荷/键级/偶极、轨道、ESP/FOD/STM、极化率/拉曼和分子电子耦合。各专题提供相应模型与输出边界。 |
| 溶剂与电场 | --gbsa、--alpb、--cosmo、--tmcosmo、--cpcmx、--efield |
操作指南。GBSA/ALPB和COSMO类模型不同；外场结合对应后端使用。API GBSA网格旋转精度限制见专门说明。 |
| 分区嵌入 | --oniom、--cut |
操作指南。ONIOM内外层模型与原子划分；cut为源码中的内区截取开关，本批未将它单独作为已运行方法。 |
| 周期及特殊力场 | --mcgfnff、--nocellopt、--iff、--nat |
操作指南。IFF分子划分/作用能与周期设置。当前周期mcGFN-FF条件曾失败，不推荐据此运行晶体MD；nocellopt只控制晶胞自由度。 |
| MD与势垒探索 | --md、--omd、--metadyn、--metaopt、--path |
操作指南。普通/优化后MD、RMSD元动力学、极小值跳跃与引导路径；短路径不能直接视作严格过渡态。 |
| 已有轨迹与筛选 | --mdopt、--screen、--ewin |
操作指南。逐帧优化、结构筛选与构型能量窗口，文件名和跳帧间隔必须正确。 |
| 有偏输入 | --bias-input、--gesc |
操作指南。两个参数是同一RMSD偏置输入入口；需匹配参考结构和bias文件格式，本批未宣称该参数已独立完成。 |
| 当前无效运行模式 | --gmd、--siman |
操作指南。本次两者均实际返回无效runtyp；源码还把gmd标为弃用。不要依据解析器名字认为这些模式可用。 |
| 外部引擎 | --driver、--orca、--tm、--mopac |
操作指南。driver回调已有真实示例；其他三种需要对应外部程序、配置与格式，不宣称本批已运行。 |
| 参数与配置 | --input、--define、--vparam、--strict、--copy、--nocopy、--cma |
操作指南。xcontrol、输入设置、tblite参数TOML、严格解析、配置复制与质心/主轴坐标变换。自定义vparam需要可用且适配的参数文件，本包未提供自定义模型。 |
| 文件与运行控制 | --namespace、--restart、--norestart、--ceasefiles、--json、--wrtopo、--enso、--parallel |
操作指南。命名空间、重启/禁用重启、输出抑制、JSON/拓扑、ENSO接口与线程数；输出文件数不等于物理功能数。 |
| 帮助与显示 | --help、--version、--license、--citation、--verbose、--very-verbose、--color、--coffee |
操作指南。帮助、版本、许可、引用和显示控制；coffee只是显示选项，不是计算方法。 |
逐选项表也保存在CLI-function-map.csv，便于用终端筛选：
python3 - <<'PY'
import csv
for r in csv.DictReader(open('CLI-function-map.csv')):
if r['family'] in ['已有轨迹与筛选','当前无效运行模式']:
print(r['flag'],r['guide'],r['scope'])
PY
2. 专题入口怎样选#
- 先准备分子、优化与频率：看优化与频率。
- 轨道、ESP、STM、FOD、极化率与拉曼：分别看局域轨道与ESP、GFN1 STM、FOD温度、PTB极化率与拉曼。
- 周期输入和后端差异：看周期GFN-FF与tblite。
- 真实短轨迹、路径与模式跟随：看MD与元动力学、近似反应路径、Hessian与模式跟随。
- 分子片段耦合与多层模型：看DIPRO、ONIOM。
3. C接口的40个符号怎么对应任务#
已安装头文件的40个符号在之前的C接口小例中均有实际调用记录，分为：环境/错误/输出管理、分子与计算器生命周期、GFN0/1/2/GFN-FF加载、精度/电子温度、单点与结果复制、能量/梯度/点电荷梯度/virial/偶极/电荷/键级、轨道及外部电荷/溶剂。调用过符号不等于每一种模式和精度都无条件适用。
操作和完整C程序分别见生命周期、结果读取、GFN0与GFN-FF、外部电荷、GBSA网格。分子virial不能直接解释为体材料压力，稀疏CLI键级文件也不等于完整API矩阵。
python3 -m json.tool C-API-EXTENSIONS.json
GBSA网格下的旋转残余转矩、周期mcGFN-FF、外部模型参数和本版失效入口继续按各自说明处理；不要把其他方法已运行当作这些条件也已完成。参数的一般含义可对照xTB官方命令行说明，实际可用写法优先使用本包固定版本。