叫个啥名字的 Blog

qchem_toolkit 使用手册

wangsy — Fri, 10 Apr 2026 03:45:37 +0800

qchem_toolkit 使用手册

qchem_toolkit.py 是一个专为 Q-Chem 批量 X-Ray 计算任务设计的后处理工具箱。它集成了状态监控、电离能（IP）计算、XAS 能量校准（Shift）以及数据自动化归档功能。

1. 目录结构规范

脚本基于数字命名的原子序号目录进行批量识别，请保持以下结构：

工作目录/
├── 1/                   # 原子序号文件夹
│   ├── GS/              # 基态输出 (1GS.out)
│   ├── LUMO/            # LUMO态输出 (1LUMO.out)
│   ├── FCH/             # 完全芯孔输出 (1FCH.out)
│   └── TD_XAS/          # TDDFT 输出 (1TD_XAS.out)
├── 2/
├── 3/
└── ...

2. 功能指令说明

2.1 check (任务状态监控)

自动遍历指定类型的 .out 日志，提取能量、收敛步数及状态。

全量检查（默认遍历 GS, FCH, FCH_R, LUMO, TD_XAS, Z+1）：
```
qchem_toolkit.py check
```
指定检查：
```
qchem_toolkit.py check GS
```

2.2 ip (垂直电离能计算)

基于 $\Delta$SCF 方法计算电离能。

计算逻辑：IP = (Energy_FCH - Energy_GS) * 27.2114 + Shift

用法示例：

qchem_toolkit.py ip           # 默认平移量为 0
qchem_toolkit.py ip -s 1.2    # 结果统一加上 1.2 eV 偏移

输出：生成 IP_ENERGY_ 文件，包含基态、芯孔态能量及最终 IP。

2.3 shift (光谱能量校准)

自动抓取各类 XAS 计算的首个吸收峰，并以 $\Delta$KS（LUMO - GS）为绝对基准计算能量校正值。

执行方式：
```
qchem_toolkit.py shift
```
输出：生成 ENERGY_XASshift 矩阵表，汇总所有方法（FCH, TD_XAS等）的校准偏移量。

2.4 collect (数据提取与自动化平移)

提取各原子目录下的光谱原始数据，自动执行去表头处理，并应用 shift 指令算出的偏移量。

全量收集（自动识别并提取所有包含光谱数据的目录）：
```
qchem_toolkit.py collect
```
指定类型收集（仅提取并处理指定计算类型的光谱数据）：
```
qchem_toolkit.py collect TD_XAS
qchem_toolkit.py collect FCH
```
处理结果：
1. 数据统一归档至 XASDATA/ 目录下（内部按计算类型分子目录）。
2. *.XAS：去表头后的原始光谱纯数据文件。
3. *.shift.XAS：自动校准后的光谱副本。该文件的横坐标（能量轴）已应用 Shift 值完成平移，可直接导入 Origin 等软件进行绘图比对。

Q-Chem软件计算XAS和XPS步骤

zhangjr — Thu, 02 Apr 2026 23:01:57 +0800

[该文章已设置加密]

X-Ray Spectrum Plotter 用户手册

wangsy — Wed, 21 Jan 2026 20:15:31 +0800

X-Ray Spectrum Plotter 用户手册

1. 简介 (Introduction)

X-Ray Spectrum Plotter 是一个专为处理和可视化 X 射线光谱（如 XAS, NEXAFS 等）设计的 Python 工具。它能够读取原始计算数据（棒状图），对其进行不同线型的展宽（Broadening），并生成高质量的 2D 堆叠图 和 3D 演化图（热力图/曲面图）。

主要功能

双区间展宽: 支持将光谱分为两个能量区间，分别应用不同的展宽参数（HWHM）和函数（高斯/洛伦兹/Stieltjes）。
自动化批处理: 自动扫描文件夹内的光谱文件，根据文件名自动归类。
3D 可视化: 支持生成随条件（如温度、时间、距离）变化的 3D 等高线图或曲面图。
高度可定制: 支持自定义颜色、字体、刻度方向、标签偏移及输出分辨率（DPI）。
实验谱对比: 支持将实验数据与计算光谱叠加对比。

2. 环境要求与安装 (Installation)

这一部分不想看文字，可以点击看图文版本

本程序依赖 Anaconda3 环境运行。请严格按照以下步骤完成环境配置和软件安装。

2.1 第一步：下载并安装 Anaconda3

本程序使用 Anaconda3 来管理 Python 环境，省去配置依赖库的麻烦。

下载安装包:
- 访问清华大学开源软件镜像站下载最新版 Anaconda3 (64-bit)。
- 下载地址: https://mirrors.tuna.tsinghua.edu.cn/anaconda/archive/
- 推荐版本: 选择 Windows x86_64 版本（如 Anaconda3-2024.10-1-Windows-x86_64.exe）。
安装向导设置:
- 运行安装包，点击 Next 直到出现 Select Installation Type。
- Install for: 选择 Just Me (recommended)。
- Destination Folder: 建议使用默认路径或简单的自定义路径（如 C:\Software\anaconda3），请记住此路径，后续配置环境变量需要用到。
- Advanced Installation Options (高级选项):
- [x] Add Anaconda3 to my PATH...: 勾选 (推荐)。
- [x] Register Anaconda3 as my default Python 3.12: 勾选 (推荐)。
- [x] Clear the package cache upon completion: 勾选 (推荐，节省空间)。

安装完成后，取消勾选 "Launch Anaconda Navigator" 和 "Getting Started"，点击 Finish。

2.2 第二步：配置环境变量 (关键步骤)

安装完成后，必须手动将 Anaconda 的路径添加到系统环境变量中，否则无法在终端直接运行命令。

打开环境变量设置:
- 按键盘 Win 键，输入“高级”，选择 查看高级系统设置。
- 在弹出的“系统属性”窗口中，点击右下角的 环境变量(N)...。
编辑 Path 变量:
- 在 系统变量(S) (或用户变量) 区域中，找到并选中 Path，点击 编辑(E)...。
添加路径:
- 如果不存在如下环境，需要点击 新建(N)，依次添加以下 5 条路径（假设安装路径为 C:\Software\anaconda3，如果您的安装路径不同，请相应修改盘符和文件夹名）：
C:\Software\anaconda3
C:\Software\anaconda3\Library\mingw-w64\bin
C:\Software\anaconda3\Library\usr\bin
C:\Software\anaconda3\Library\bin
C:\Software\anaconda3\Scripts

重要: 添加完成后，使用右侧的 上移(U) 按钮，将这 5 条路径移动到列表的最顶部。
依次点击确定保存所有设置并关闭窗口。

2.3 第三步：安装 plotterxray 程序

打开终端:
- 进入存放 plotterxray-5.7.2-py3-none-any.whl 安装包的文件夹。
- 按住键盘 Shift 键，同时在文件夹空白处点击 鼠标右键。
- 在菜单中选择 在此处打开 Powershell 窗口 (或 "在终端中打开")。
执行安装命令:
- 在终端窗口中输入以下命令并回车：plotterxray下载地址
```
pip install plotterxray-5.7.2-py3-none-any.whl
```


* **注意**: 请确保命令中的文件名与实际文件完全一致（支持按 `Tab` 键自动补全文件名）。
* 当显示 `Successfully installed ...` 即表示安装成功。

### 2.4 程序更新与卸载

* **卸载旧版本**:
在终端输入 `pip uninstall plotterxray`，出现提示时输入 `Y` 确认。
* **安装新版本**:
卸载后，参照“第三步”，使用 `pip install XXXXX.whl` 安装新版安装包即可。

---

## 3. 快速开始 (Quick Start)

1. **准备数据**: 将你的光谱数据文件（例如 `.dat` 或 `.txt`，格式为两列：能量 强度）放入任意工作文件夹。
2. **准备配置**: 复制 `plot_detailed.ini` 到该文件夹并重命名为 `plot.ini`（或者使用简单版 `plot_simple.ini`）。
3. **运行程序**:
* 进入数据文件夹，**Shift + 右键** 打开终端。
* 运行以下命令：
```bash
plotterxray plot.ini

查看结果: 程序运行结束后，会在当前目录下生成 spectrum/ 文件夹，里面包含生成的 .pdf 和 .jpg 图片。

4. 配置文件详解 (Configuration Guide)

配置文件是控制绘图行为的核心。以下是各部分的详细说明。

4.1 [auto] - 自动扫描设置

用于控制程序是否自动读取当前目录下的文件。

参数	说明	示例值
mode	开关。`True` 开启自动扫描；`False` 仅使用 `[spectra]` 中的手动列表。	`True`
suffix	待扫描文件的后缀名。	`dat`
category	分类策略。`auto` 会尝试从文件名提取数字作为类别；指定字符串则强制归类。	`auto`
weight	默认强度权重。	`0.02`
shift	默认能量平移量 (eV)。	`-3.5`
color	绘图颜色。`auto` 自动循环颜色；指定 hex 码 (如 `#FF0000`) 则固定颜色。	`#808080`

注意: 自动模式下生成的列表会缓存到 plot_list.cache 文件中。如果新增了文件，请删除该缓存或在提示时选择重新生成。

4.2 [calculation] - 光谱计算与展宽核心

程序支持将光谱分为两个区间进行不同程度的展宽（例如：Pre-edge 区间使用较小的展宽，EXAFS 区间使用较大的展宽）。

参数	格式 / 说明
hwhm1	`Start End HWHM` (例如 `500 541 0.8`)。

定义区间1的起始能量、结束能量和半高宽。 |
| hwhm2 | Start End HWHM (例如 541 600 1.5)。

支持的展宽函数代码:

G: 高斯函数 (Gaussian)
L: 洛伦兹函数 (Lorentzian)
S: Stieltjes 函数 (适用于连续态展宽)

4.3 [general] - 画布通用设置

控制图片的外观、尺寸和坐标轴。

figure_width / figure_height: 图片尺寸（英寸）。
dpi: 输出分辨率，出版级图像建议设为 300 或更高。
font_family / font_size: 字体（如 Arial）和字号。
xlim: X轴能量显示范围 (例如 520 550)。
plot_order: 堆叠顺序。
bottom_up: 类别从小到大，从下往上堆叠。
top_down: 类别从小到大，从上往下堆叠。
tick_direction: 刻度朝向 (in 或 out)。
mirror_ticks: 是否在顶部和右侧显示镜像刻度。

4.4 [plot_2d] - 2D 堆叠图设置

用于绘制传统的瀑布图/堆叠图。

show: 是否生成 2D 图。
vertical_spacing: 各条光谱之间的垂直间距。设为 auto 则自动根据画幅计算，也可指定具体数值。
show_total: 是否将所有类别的光谱加和，绘制一条总谱（黑色曲线）。
show_sticks: 是否在曲线下方绘制原始的棒状图（Stick plot），用于分析具体跃迁贡献。
info_label: 图内标注文字（如 "O K-edge"）。

4.5 [plot_3d] - 3D 演化图设置

用于绘制随参数连续变化的光谱图（例如随温度变化）。

参数	说明
show	是否生成 3D 图。
type	图表类型：`contour` (等高线/热力图) 或 `surf` (3D 立体曲面)。
cmap	颜色映射表 (Colormap)，如 `seismic`, `jet`, `viridis`。
sampling_y	Y轴（类别轴）插值倍数。数值越大，类别间的过渡越平滑。
sampling_x	X轴（能量轴）插值倍数。
colorbar_range	颜色条数值范围。`auto` 或指定范围（如 `0 1.5`），用于统一不同图片的色阶。
rasterize_content	`T`。是否对绘图内容进行栅格化（保留矢量文字）。强烈建议开启，否则 PDF 文件会非常巨大且卡顿。

4.6 [spectra] - 手动文件列表

当 [auto] mode = False 时，程序读取此列表。

格式:

; 文件名      权重   类别   个体位移   颜色
file1.dat    1.0   CatA   0.0       red
file2.dat    1.0   CatB   0.2       blue

shift: 全局手动平移量，会叠加在个体位移上。

4.7 [exp_spectra] - 实验谱数据

用于加载实验数据进行对比。

格式:

; 文件名      缩放   图例标签   颜色
exp_data.txt  0.5   Experiment black

5. 数据准备 (Data Preparation)

5.1 计算数据文件

格式: 纯文本文件。
内容: 至少包含两列数据。
第1列: 激发能量 (eV)
第2列: 振子强度 (Oscillator Strength) 或强度
注释: 支持 # 或 ! 开头的注释行。

5.2 实验数据文件

同上，通常为两列 (Energy, Intensity)。程序会自动扣除 Y 轴的最小值（Baseline subtraction）。

6. 高级用法与技巧 (Tips & Tricks)

6.1 缓存机制 (Cache System)

程序在 [auto] 模式下运行时，会生成 plot_list.cache 文件。

作用: 记录了扫描到的文件列表、分类和颜色。
技巧: 你可以直接编辑 plot_list.cache 文件来微调某个特定文件的颜色或位移，而无需关闭自动模式。
坑点: 如果你添加了新文件但程序没读到，请删除该缓存文件，程序下次运行时会重新扫描。

6.2 混合展宽策略 (Hybrid Broadening)

在 XAS 模拟中，边前峰（Pre-edge）通常寿命较长，展宽较小；而边后（Post-edge）受连续态影响，展宽较大。

推荐设置：
hwhm1 (边前): 使用 0.5 - 0.8 eV，配合 Gaussian (G) 函数。
hwhm2 (边后): 使用 1.0 - 2.0 eV，配合 Stieltjes (S) 或 Lorentzian (L) 函数。

6.3 3D图去噪

如果 3D 热力图背景很脏，可以调整 [plot_3d] 中的 background_threshold。

设置为 0.001 或更高，可以将低强度的底噪强制归零，使图面更干净。

6.4 批量修改颜色

在 [auto] 模块中：

设置 color = auto: 程序会自动给不同类别分配不同颜色。
设置 color = #FF0000: 所有线条都变为红色（适合用于生成单一色调的对比图）。

7. 常见问题 (Troubleshooting)

Q: 运行后报错 ValueError: Cannot read config file?
A: 请检查 .ini 文件的编码。建议使用 UTF-8 编码保存。同时确保文件名输入正确。

Q: 生成的 PDF 文件打开极慢？
A: 请确保 [plot_3d] 中的 rasterize_content = T。这会将复杂的纹理光栅化为像素图，而保留坐标轴文字为矢量，大大减小文件体积。

Q: 为什么我的 3D 图看起来也是一条条的，不平滑？
A: 增加 [plot_3d] 中的 sampling_y 值（例如设为 20 或 50），程序会在不同文件的数据之间进行插值，使其看起来连续。

Q: 如何让某些特定的线突出显示（例如加粗或变色）？
A: 建议先运行一次生成 plot_list.cache，然后手动编辑该缓存文件，修改特定行的颜色代码，最后再次运行程序。

8. 输出示例

程序将在 spectrum/ 目录下生成以下文件：

spectrum_stack_2d.jpg / .pdf: 2D 堆叠图。
spectrum_evolution_contour.jpg / .pdf: 3D 热力图（如果启用）。
*_broad.txt: 如果开启了 keep_intermediate，这里保存了展宽后的具体数据点。

Inkscape 原位缩放工具-SVGScaler.py使用手册

wangsy — Mon, 19 Jan 2026 01:05:56 +0800

Inkscape 原位缩放工具使用手册

1. 简介

通常在 Inkscape 中，如果你全选多个对象进行缩放，它们会相对于整个选区的中心缩放，导致位置发生偏移。本工具通过 Python 脚本计算每个对象的几何中心，逐个应用缩放变换，从而实现“变大变小，位置不动”的效果。

主要特性：

支持多种对象： 路径 (Path)、矩形、圆形、普通文本、流式文本 (FlowRoot)、图片等。
智能图层识别： 可指定处理特定图层（如只缩放 "text" 层）。
灵活的缩放系数： 支持放大倍数和倒数缩小（如输入 -2 代表缩小到 1/2）。

2. 环境准备

安装 Python： 确保电脑上安装了 Python 3.x 版本。
下载脚本： 下载地址

3. Inkscape 文件准备流程 (重要)

为了让脚本准确找到需要缩放的内容，建议在 Inkscape 中遵循以下操作规范：

步骤 A：整理图层

脚本默认处理名为 text 的图层。建议将需要调整大小的对象归类到一个专门的图层中。

打开 Inkscape (Ctrl+Shift+L 打开图层面板)。
新建一个图层，命名为 text (或者其他你喜欢的名字，运行时需指定)。
选中需要缩放的对象，右键点击 -> 移动到图层 -> 选择 text 图层。

步骤 B：群组逻辑 (关键)

脚本是逐个处理图层下的直接子对象的。

如果不群组： 图层里的每个独立元素（如每个字母、每根线条）都会以各自的中心单独缩放。
如果群组 (Ctrl+G)： 脚本会将整个群组视为一个对象，以群组的几何中心进行整体缩放。

场景举例：
如果你有一个“圆圈”和一个“数字”组成一个标号。

错误做法： 圆圈和数字分散在图层里。 -> 结果：圆圈变大了，数字变大了，但它们可能会轻微错位。

正确做法： 选中圆圈和数字，按下 Ctrl+G 编组。 -> 结果：整个标号以整体中心原位放大。

步骤 C：保存文件

将文件保存为 Inkscape SVG 或 普通 SVG 格式（例如 drawing.svg）。

4. 脚本运行方法

打开终端 (Command Prompt / Terminal)，进入脚本所在的目录。

基本语法

python scale_svg.py [输入文件] [缩放系数] [输出文件(可选)] [参数]

参数详解

参数位置/名称	说明
输入文件	SVG 文件的完整路径 (例如 `input.svg`)。
缩放系数	正数 (>0): 直接放大倍数。如 `1.5` (放大1.5倍), `0.8` (缩小到80%)。负数 (<0): 倒数缩小模式。如 `-2` 等同于 0.5 (缩小一半)，`-4` 等同于 0.25。
输出文件	(可选) 处理后的保存路径。如果不填，默认保存为 `原文件名_系数.svg`。
`--layer`	指定要处理的图层名称。默认为 `text`。
`-a` / `--all`	全局模式。忽略图层名称，处理 SVG 根目录下的所有顶层群组。

5. 使用案例

案例 1：将 "text" 图层中的内容放大 1.5 倍

这是最常用的场景。假设文件名为 map.svg。

python scale_svg.py map.svg 1.5

结果：生成 map_1.5.svg，其中 text 图层的对象原位放大了 50%。

案例 2：将 "labels" 图层的内容缩小一半

使用了负数参数技巧（-2 表示 1/2）。指定了 --layer 参数。

python scale_svg.py drawing.svg -2 --layer labels

结果：生成 drawing_-2.0.svg，labels 图层的内容尺寸减半。

案例 3：指定输出文件名

python scale_svg.py icon.svg 2.0 output_icon.svg

结果：生成 output_icon.svg。

案例 4：暴力处理所有图层

如果你想把整个文件里的所有顶层对象都分别原位缩放（慎用，可能会打乱布局）。

python scale_svg.py schematic.svg 0.9 --all

6. 常见问题排错 (Troubleshooting)

Q1: 运行后提示 "未找到可处理对象"？

检查图层名称： 确认 Inkscape 中的图层名称是否与命令行 --layer 参数一致（区分大小写，默认为 "text"）。
检查图层结构： 对象必须直接位于该图层（组）下，不能深埋在多个嵌套的组里（脚本目前主要扫描图层的直接子节点）。

Q2: 缩放后，文字跑偏了？

脚本通过计算 Bounding Box (包围盒) 的中心来进行变换。如果文字对象的对齐方式或坐标原点比较特殊，可能会有轻微视觉偏差。通常情况下，将文字转换为路径 (Path) 再缩放是最稳妥的，但本脚本已针对 Text 做了优化，通常无需转换。

Q3: 原文件被覆盖了吗？

默认不会。脚本会生成新文件。如果你手动指定输出文件名为原文件名，脚本会询问 是否覆盖? (y/N)。

Q4: 支持 Inkscape 的流式文本 (FlowRoot) 吗？

支持。 脚本包含了解析 flowRegion 的逻辑，可以正确计算流式文本框的中心并进行缩放。

7. 原理简述 (供高级用户参考)

该脚本的工作流程如下：

解析 XML： 使用 Python xml.etree 读取 SVG。
定位图层： 查找带有 inkscape:label="layer_name" 属性的标签。
计算包围盒 (BBox)： 递归解析路径 (d 属性)、形状属性 (x, y, width, height) 以及变换矩阵 (transform)，计算出对象的几何中心 $(C_x, C_y)$。
应用变换： 在对象现有的 transform 属性后追加矩阵运算：
$$ \text{translate}(C_x, C_y) \cdot \text{scale}(S) \cdot \text{translate}(-C_x, -C_y) $$
这确保了缩放是相对于对象自身中心进行的。

Q-chem 安装指南 (Linux 集群)

wangsy — Tue, 16 Dec 2025 23:58:33 +0800

[该文章已设置加密]

用于自动提取芯轨道(分子和原子轨道)的程序

wangsy — Fri, 05 Dec 2025 14:47:00 +0800

`extract_orbital_composition.py` 程序使用说明

本程序由wangsy于2025年11月19日完成。
如有需要，请联系wang.sy@vip.163.com 。

1. 简介 (Program Overview)

extract_orbital_composition.py 是一个用于量子化学计算的后处理工具。它旨在自动化地从.fchk (formatted checkpoint) 文件中提取指定原子在占据分子轨道中的成分百分比。

该脚本的核心功能是调用业界知名的波函数分析软件 Multiwfn，向其发送一系列自动化指令，然后解析其文本输出，最后将结果以清晰的表格或缓存文件的形式呈现给用户。

关键特性

自动化 Multiwfn 调用: 自动运行 Multiwfn 并执行轨道成分分析（菜单 8 -> 8 -> 1 -> -2）。
计算类型自动检测: 自动从 .fchk 文件中读取电子数和轨道信息，以判断计算是限制性 (Restricted, RHF/ROHF) 还是非限制性 (Unrestricted, UHF)。
MOKIT 自动局域化: 当脚本检测到轨道高度离域时（即，目标原子的最高轨道贡献低于 95%），它能自动调用 MOKIT 工具包执行 Pipek-Mezey (PM) 轨道局域化，并使用局域化后的新 fchk 文件重新进行分析。
灵活的输出:
1. 默认在屏幕上打印格式化的表格。
2. 可使用 -o 将表格保存到文件。
3. 可使用 -c 生成用于 qchem_xray.py 脚本的专用缓存文件。

⚠️ 重要：运行依赖

在运行此脚本之前，您必须确保满足以下环境要求：

Multiwfn: Multiwfn 的可执行文件必须位于您系统的 PATH 环境变量中。脚本会通过在 shell 中执行 Multiwfn 命令来调用它。
MOKIT (用于局域化):
- 您必须有一个名为 mokit-py39 的 conda 环境。
- 此环境中必须已正确安装 mokit 库及其依赖项。
- 脚本通过 conda run -n mokit-py39 ... 命令来执行局域化相关的 Python 和 fch2qchem 指令。

2. 逻辑和流程 (Logic and Flow)

该脚本的执行流程可以分为以下几个关键步骤：

参数解析: 脚本启动，读取用户提供的命令行参数（例如 fchk_file, atom_number, threshold 等）。
环境检查: 脚本首先检查 Multiwfn 是否在 PATH 中。如果找不到，程序将报错并退出。
文件初次分析 (Original FCHK):
- 脚本读取 .fchk 文件，提取 Alpha 电子数 (n_alpha)、Beta 电子数 (n_beta) 和总基函数数 (total_orbitals)。
- 通过检查文件中是否存在 "Beta MO coefficients" 等关键词，判断是限制性还是非限制性计算。
- 调用 Multiwfn: 脚本通过 subprocess 启动 Multiwfn [fchk_file] -isilent 进程。
- 发送指令: 它向 Multiwfn 的标准输入 (stdin) 发送一系列命令，以分析所有占据轨道 (RHF: 1 到 n_alpha；UHF: 1 到 n_alpha 以及 Beta 轨道 1 到 n_beta)。
- 解析输出: 脚本捕获 Multiwfn 的标准输出 (stdout)，并使用正则表达式解析表格，提取所有贡献超过指定阈值 (-t，默认 40%) 的轨道信息（编号、能量、占据数、百分比等）。
离域化检查:
- 脚本检查上一步中找到的所有轨道的最大贡献值 (max_comp)。
- 如果 0.0 < max_comp < 95.0% (95% 为 LOCALIZATION_TRIGGER_THRESHOLD)，则认为轨道高度离域，触发局域化流程。
MOKIT 局域化工作流 (可选):
- 如果触发了局域化（且用户未指定 --no-localize）：
- 交互式询问: 脚本会暂停并询问用户是否执行 MOKIT 局域化（y/n）。（如果使用 --force-localize 则跳过询问）。
- 执行局域化: 如果用户同意，脚本将：
  i. 生成一个临时的 Python 脚本，该脚本导入 mokit 库。
  ii. 调用 conda run -n mokit-py39 python ... 来执行 standardize_fch (标准化 fchk) 和 loc (PM 局域化)。
  iii. 这会生成一个新的 *_std_LMO.fch 文件。
  iv. 调用 conda run -n mokit-py39 fch2qchem ... 将新的 LMO fchk 转换为 Q-Chem save 目录。
  v. 将生成的 *_std_LMO 目录重命名为 save（如果 save 已存在，则备份为 save.bak）。
二次分析 (LMO FCHK):
- 如果成功执行了局域化，脚本将使用新生成的 *_std_LMO.fch 文件重复步骤 3。
- 此时，分析的是局域化分子轨道 (LMO)。
结果输出:
- 脚本将最终的分析结果（来自 LMO fchk 或原始 fchk）进行格式化。
- 标准模式: 打印一个详细的表格到屏幕（或用 -o 保存到文件）。
- 缓存模式 (-c): 生成一个 .cache 文件。
  - 标准: 2 列 (Alpha, Beta)。
  - 局域化后: 4 列 (LMO_Alpha, LMO_Beta, Orig_Alpha, Orig_Beta)，并包含特殊的页脚标记。

3. 程序的运行完整示例

假设我们有一个名为 complex.fchk 的非限制性 (UHF) 计算文件，我们关心的是 1 号原子（例如一个金属中心）的轨道贡献。

示例 1: 基本用法（打印到屏幕）

命令 (使用 10% 作为阈值):

python extract_orbital_composition.py complex.fchk 1 -t 10

输出 (无局域化):

如果轨道局域性良好（最高贡献 > 95%），脚本将直接打印分析结果。

==========================================================================================
                                原子 1 的轨道组成分析
==========================================================================================
文件: complex.fchk
计算类型: 非限制性 (Unrestricted)
Composition阈值: 10.0%
(注: 仅显示占据轨道)
==========================================================================================
注: 非限制性计算有两套独立的Alpha和Beta空间轨道。
------------------------------------------------------------------------------------------

Alpha 轨道:
------------------------------------------------------------------------------------------
      序号 类型                能量(a.u.)    占据     组成(%)         布居
------------------------------------------------------------------------------------------
       105 Alpha              -0.2512   1.000      98.501   1.000000
       100 Alpha              -0.4500   1.000      85.123   1.000000
        95 Alpha              -0.7800   1.000      15.300   1.000000

Beta 轨道:
------------------------------------------------------------------------------------------
      序号 类型                能量(a.u.)    占据     组成(%)         布居
------------------------------------------------------------------------------------------
    104(204) Beta               -0.2300   1.000      97.110   1.000000
     99(199) Beta               -0.4300   1.000      82.000   1.000000
------------------------------------------------------------------------------------------
注: Beta轨道序号格式为 真实序号(Multiwfn内部编号)。
------------------------------------------------------------------------------------------

示例 2: 交互式局域化

命令 (使用默认 40% 阈值):

python extract_orbital_composition.py complex.fchk 1

交互式提示:

假设脚本在第一次分析中发现最高贡献只有 85%（低于 95%）。

处理非限制性体系 (Unrestricted)...
 → 扫描范围 (Alpha,Beta): 1-105,201-204

警告: 排序第一的轨道百分比 (85.12%) 低于 95.0%。
      这可能表明轨道高度离域。

是否运行 MOKIT (PM) 局域化工作流? (y/n):

用户输入 y:

脚本将开始执行 MOKIT 工作流，并显示 MOKIT 的输出：

y
信息: 用户选择执行局域化。

============================================================
开始 MOKIT 局域化工作流 (目标原子: 1)
============================================================
--- [1/3] 正在 MOKIT 环境中运行 Python 脚本 (_temp_mokit_localize_...py)...
--- 正在导入 MOKIT...
--- [MOKIT 1/2] 正在标准化 complex.fchk -> complex_std.fch...
--- [MOKIT 2/2] 正在局域化 complex_std.fch (PM, 轨道 0-104)...
--- MOKIT Python 脚本执行完毕.
--- [2/3] 正在 MOKIT 环境中运行 fch2qchem (转换LMO fch为Q-Chem 'save' 目录)...
(fch2qchem output...)
--- [3/3] 正在重命名文件...
============================================================
局域化完成。生成新的fchk文件: complex_std_LMO.fch
============================================================

--- 正在分析局域化后的文件: complex_std_LMO.fch
处理非限制性体系 (Unrestricted)...
 → 扫描范围 (Alpha,Beta): 1-105,201-204

最终输出:

脚本现在打印的是对 complex_std_LMO.fch 文件的分析结果，轨道贡献现在应该更接近 100%。

==========================================================================================
                                原子 1 的轨道组成分析
==========================================================================================
文件: complex_std_LMO.fch
计算类型: 非限制性 (Unrestricted)
...
Alpha 轨道:
...
       105 Alpha              -0.2512   1.000      99.850   1.000000
       100 Alpha              -0.4500   1.000      99.100   1.000000
...

示例 3: 生成缓存文件（自动局域化）

命令 (使用 -c 生成缓存，使用 --force-localize 避免交互式询问):

python extract_orbital_composition.py complex.fchk 1 -c --force-localize

输出:

...
(MOKIT 局域化流程输出)
...

轨道缓存文件已成功生成: /path/to/project/1GS_orbital.cache

1GS_orbital.cache 文件内容:

由于执行了局域化，缓存文件将包含 4 列，并带有特殊的页脚。

n_alpha=105       n_beta=104
105|99.85        104|99.11        105|85.12        104|82.00
100|99.10        99|82.00         100|82.00        99|15.30

# --------------------------------------------------
# 警告: 原始fchk文件轨道百分比 < 95.0% (Max: 85.12%)
# LOCALIZED: LMO_A | LMO_B | ORIG_A | ORIG_B
# --------------------------------------------------

4. 高级选项 (Advanced Options)

以下是脚本支持的所有命令行参数的详细分类说明。

核心参数

fchk_file
- 必需。输入的 .fchk 文件路径。
atom_number
- 必需。要分析的目标原子的编号（从 1 开始）。

阈值与输出

-t, --threshold THRESHOLD
- 设置轨道组成贡献的百分比阈值。
- 示例: -t 10 (只显示贡献 > 10% 的轨道)。
- 默认: 40.0
-o, --output OUTPUT
- 将标准输出的表格重定向到指定的文本文件。

缓存模式 (qchem_xray.py)

-c, --cache
- 激活缓存模式。不打印标准表格，而是生成一个 qchem_xray.py 兼容的缓存文件。
- 默认文件名: [atom_number]GS_orbital.cache (例如: 1GS_orbital.cache)。
--cache-name CACHE_NAME
- 与 -c 配合使用，指定自定义的缓存文件名。

MOKIT 局域化控制

--force-localize
- 当检测到轨道离域时 (max comp \< 95%)，自动执行 MOKIT 局域化，不进行交互式询问。
- 适用于在其他脚本中调用此程序。
--no-localize
- 禁止 MOKIT 局域化。即使检测到离域，也只使用原始 fchk 文件进行分析。
--keep-temp-files
- 保留 MOKIT 局域化过程中产生的中间文件（例如 *_std.fch, *_std_LMO.in）。
- 默认情况下，这些文件会被自动清理。此选项用于调试 MOKIT 流程。

自旋控制 (Spin Control)

-a, --alpha-only
- 仅分析和输出 Alpha 轨道。
-b, --beta-only
- 仅分析和输出 Beta 轨道。
- (注: 这两个选项是互斥的)。

调试 (Debugging)

-v, --verbose
- 启用详细输出模式。
- 将显示操作系统信息、Multiwfn 路径、发送给 Multiwfn 的完整命令序列以及 MOKIT 调用的详细命令。
- 在排查错误时非常有用。

用于批量生成Q-Chem计算X-ray的程序

wangsy — Fri, 05 Dec 2025 14:43:25 +0800

📜 `qchem_xray.py` 详细使用说明

本程序由wangsy于2025年11月02日完成。
如有需要，请联系wang.sy@vip.163.com 。

1. 脚本概述

qchem_xray.py 是一个用于自动生成 Q-Chem 量子化学计算输入文件的 Python 脚本，专门针对 X 射线光谱 (XAS) 相关的计算。

该脚本的核心功能包括：

解析配置文件: 自动读取 input.ini 文件中的所有设置。
读取结构: 从指定的 XYZ 文件（如 pyridine.xyz）中提取分子结构。
生成输入文件: 根据用户指定的计算类型，自动生成 Q-Chem 输入文件 (.in)。
目录管理: 为每个计算的原子和计算类型创建独立的目录结构 ( 1/GS/, 1/FCH/, 1/FCH_R/, 1/LUMO/,1/TD_XAS/, 1/TD_XES/, 1/Z+1/)。
依赖管理: 自动处理激发态计算（FCH, FCH_R, LUMO, TD_XAS, TD_XES）对基态 (GS) 计算的依赖。
轨道检测: 自动调用外部脚本 extract_orbital_composition.py 来分析 GS 计算的 .fchk 文件，确定芯轨道的位置，并将其缓存在 [num]/GS/[num]GS_orbital.cache 文件中。
作业提交: (可选) 自动将生成的输入文件提交到计算队列 (通过 [submit]中的命令)。

2. 核心逻辑与工作流程

A. 配置文件 (`input.ini`)

脚本的所有行为都由 input.ini 控制。它分为几个关键部分：

[submit]: 定义如何提交作业 (qsub 命令)。
[xyz]: 定义结构文件名 (filename) 和每种计算类型的电荷/多重度。
[keys]: 定义每种计算类型所需的 Q-Chem 关键字 (REM 变量)。
[excited]: 定义要计算的原子 (num)、激发原子的基组 (basis) 以及电离哪个自旋轨道 (ionization_spin)。
[non_excited]: 定义非激发原子的基组，用于构建混合基组。

B. 依赖关系 (GS -> 激发态)

这是一个至关重要的流程：

必须首先运行基态 (GS) 计算 (qchem_xray.py GS)。
必须等待 GS 计算正常完成 (脚本会检查 .out 文件中是否包含 "Have a nice day.")。
GS 计算完成后，才能运行所有其他依赖于 GS 轨道的计算，包括 FCH, FCH_R, LUMO, TD_XAS, TD_XES 和 CACHE。
Z+1 计算不依赖于 GS，可以与 GS 同时运行。

C. 芯轨道自动检测 (缓存机制)

为了运行 FCH, FCH_R, LUMO, TD_XAS, TD_XES 和 CACHE 的计算，脚本必须知道要激发哪个芯轨道 (例如，N 1s)。这个过程是自动的：

当运行激发态计算（或 CACHE）时，脚本会首先在 [num]/GS/ 目录中寻找 [num]GS_orbital.cache 缓存文件。
如果缓存文件不存在，或者脚本发现缓存中的轨道局域化程度很差（默认阈值 \< 95.0%），它将自动调用 extract_orbital_composition.py 脚本。
extract_orbital_composition.py 脚本会读取 [num]/GS/ 目录下的 .fchk 文件，生成[num]GS_orbital.cache 文件（未找到 extract_orbital_composition.py 的情况），局域化并覆盖当前[num]GS_orbital.cache 文件（找到 extract_orbital_composition.py，但是相应芯轨道阈值 \< 95.0%的情况）。extract_orbital_composition.py 的更多用法请查阅其手册。
脚本随后读取这个缓存文件，根据 [excited] -> ionization_spin (alpha 或 beta) 的设置，找到能量最低的芯轨道及其编号 (eo)。
这个轨道编号 (eo) 将被用于生成激发态计算的输入文件 (写入 $occupied 、$reorder_mo或者$alist 部分)。

[num]GS_orbital.cache 文件内容示例如下（此格式由 extract_orbital_composition.py 生成并由 qchem_xray.py 读取）：

n_alpha=21       n_beta=21
2|98.83              2|98.83            2|49.63          2|49.63
9|54.20              9|54.20            3|49.30          3|49.30
19|45.25            19|45.25

--------------------------------------------------
警告: 原始fchk文件轨道百分比 < 95.0% (Max: 49.63%)
LOCALIZED: LMO_A | LMO_B | ORIG_A | ORIG_B
--------------------------------------------------

此文件包括局域化后的结果，如果原本波函数的芯轨道就是局域化的，就没有最右两列和最后四行内容，如下所示：

n_alpha=21       n_beta=21
2|98.83              2|98.83
9|54.20              9|54.20
19|45.25            19|45.25

3. 计算类型与选项详解

A. 支持的计算类型

脚本支持以下 8 种计算类型，必须在命令行中指定一种：

GS (Ground State): 基态计算。这是后续所有激发态计算的基础。
FCH (Final Core-Hole): 芯激发态计算（芯电离）。通过在 $occupied 部分移除一个芯轨道来实现。
FCH_R (FCH Reorganization): 芯激发态重排计算。通过 $reorder_mo 关键字实现，将芯轨道放到最外层轨道，然后控制电荷数来控制最外层电子电离（芯轨道）（通常用于 ROKS/ROHF 计算）。
LUMO (LUMO Excitation): 芯激发到 LUMO 或 LUMO+N 的近似计算。通过在 $occupied 部分将电子从芯轨道移动到指定的未占据轨道。
TD_XAS (Time-Dependent DFT): TDDFT 计算，用于模拟 XAS 吸收谱。通过 $alist 关键字指定芯轨道。
TD_XES (TDDFT for XES): TDDFT 计算，用于模拟 XES 发射谱。通过 $alist 关键字指定芯轨道，内置了FCH的计算。
Z+1 (Z+1 Approximation): Z+1 近似计算。将目标原子替换为周期表中的下一个元素（例如 N -> O）来模拟芯激发。此计算不依赖 GS。
CACHE (Cache Only): 仅生成或更新轨道缓存。用于检查 GS 计算的轨道局域化情况，或在运行激发态计算前强制生成缓存。

B. 命令行选项

[计算类型]: (必需) 上述 8 种类型之一。
-h, --help: 显示详细的帮助信息。
-r, --retry: 仅重试上次失败或跳过的原子。它会读取 [calc_type]_skipped.log 文件。
-y, --yes: 自动确认，覆盖所有已存在的计算目录。
-c CONFIG: 指定配置文件的路径 (默认: input.ini)。
-l LEVEL (仅用于 LUMO): (LUMO 专用选项) 指定激发能级，激发到 LUMO + LEVEL。
- -l 0 (默认) 表示激发到 LUMO。
- -l 1 表示激发到 LUMO+1。
-a ATOMS: 手动指定要计算的原子列表 (例如: '1 5 10-15 C')，这将覆盖 input.ini 中的 [excited] -> num 设置。
-co ORBITALS (高级): 手动覆盖芯轨道号，跳过自动检测。格式: 'atom1:orb1 atom2:orb2' (例如: '1:2 5:3')。

4. 完整运行示例

以下是使用示例 input.ini 和 pyridine.xyz 文件运行计算的完整分步指南。

A. 准备文件

文件 1: input.ini

# ====================================================================
#  重要提示:
#  此配置文件中的所有值都必须由三引号 """ ... """ 包裹。
#  这是为了确保程序能正确读取，请不要删除或修改这些引号。
#  您只需要修改引号内部的内容即可。
# ====================================================================

# ==========================================================
#               Q-Chem 作业提交配置
# ==========================================================
[submit]
# 设置用于提交计算的命令，如果留空或加#则不自动提交
qsub = """
qqchem 1 2 old
"""

# ==========================================================
#               分子结构与电荷/多重度配置
# ==========================================================
[xyz]
# xyz坐标文件名
filename          = """
pyridine.xyz
"""

# 1. 基态 (GS) 的电荷和自旋多重度
GS_charge_mult    = """
0 1
"""

# 2. 芯电离 (FCH / UKS) 的电荷和自旋多重度
FCH_charge_mult   = """
1 2
"""

# 3. 芯电离 (FCH_R / ROKS) 的电荷和自旋多重度
FCH_R_charge_mult = """
1 2
"""

# 4. LUMO+N 芯激发 (LUMO) 的电荷和自旋多重度 (中性激发)
LUMO_charge_mult  = """
0 1
"""

# 5. 芯激发 (TDDFT/XAS) 的电荷和自旋多重度
TD_XAS_charge_mult   = """
0 1
"""

# 6. XES 发射谱 (TD_XES) 的电荷和自旋多重度 (与FCH相同)
TD_XES_charge_mult = """
1 2
"""

# 7. Z+1 近似的电荷和自旋多重度
Z+1_charge_mult   = """
1 1
"""

# ==========================================================
#               Q-Chem 计算关键词 ($rem 部分)
# ==========================================================
[keys]
# ----------------- 1. 基态 (GS) 计算关键词 -----------------
GS = """
METHOD bp86
BASIS mixed
PURECART 1111
! GEN_SCFMAN true
SCF_ALGORITHM diis
BASIS2 def2-svp
UNRESTRICTED true
! SCF_GUESS_MIX 5
SCF_CONVERGENCE 8
INTEGRAL_SYMMETRY false
POINT_GROUP_SYMMETRY false
IQMOL_FCHK true
MAX_SCF_CYCLES 300
NBO_EXTERNAL TRUE
NBO true
"""

# ----------------- 2. 芯电离 (FCH / UKS) 计算关键词 -----------------
FCH = """
METHOD bp86
BASIS mixed
PURECART 1111
! GEN_SCFMAN false
SCF_ALGORITHM diis
SCF_GUESS read
UNRESTRICTED true
MOM_START 1
MOM_METHOD imom
SCF_CONVERGENCE 6
INTEGRAL_SYMMETRY false
POINT_GROUP_SYMMETRY false
IQMOL_FCHK true
MAX_SCF_CYCLES 300
"""

# ----------------- 3. 芯电离 (FCH_R / ROKS) 计算关键词 -----------------
FCH_R = """
METHOD bp86
BASIS mixed
PURECART 1111
! GEN_SCFMAN false
SCF_ALGORITHM sgm
SCF_GUESS read
UNRESTRICTED false
SCF_CONVERGENCE 6
INTEGRAL_SYMMETRY false
POINT_GROUP_SYMMETRY false
IQMOL_FCHK true
MAX_SCF_CYCLES 300
"""

# ----------------- 4. 芯激发 (LUMO+N) 计算关键词 -----------------
LUMO = """
METHOD bp86
BASIS mixed
PURECART 1111
! GEN_SCFMAN false
SCF_ALGORITHM diis
SCF_GUESS read
UNRESTRICTED true
MOM_START 1
MOM_METHOD imom
SCF_CONVERGENCE 6
INTEGRAL_SYMMETRY false
POINT_GROUP_SYMMETRY false
IQMOL_FCHK true
MAX_SCF_CYCLES 300
"""

# ----------------- 5. 芯激发 (TDDFT/XAS) 计算关键词 -----------------
TD_XAS = """
EXCHANGE bp86
BASIS mixed
PURECART 1111
SKIP_SCFMAN true
SCF_GUESS read
UNRESTRICTED true
CIS_N_ROOTS 300
CIS_TRIPLETS false
TRNSS true
TRTYPE 3
N_SOL 1
FAST_XAS true
! XAS_EDGE 6
! XAS_SCREEN_LEVEL 1
! REL_SHIFT 6
"""

# ----------------- 6. XES 发射 (TDDFT/XES) 计算关键词 -----------------
TD_XES = """
EXCHANGE bp86
BASIS mixed
PURECART 1111
SCF_GUESS read
UNRESTRICTED true
MOM_START 1
MOM_METHOD imom
SCF_CONVERGENCE 6
CIS_N_ROOTS 5
CIS_TRIPLETS false
"""

# ----------------- 7. Z+1 近似计算关键词 -----------------
Z+1 = """
METHOD bp86
BASIS mixed
PURECART 1111
! GEN_SCFMAN true
SCF_ALGORITHM diis
BASIS2 def2-svp
UNRESTRICTED true
! SCF_GUESS_MIX 5
SCF_CONVERGENCE 8
INTEGRAL_SYMMETRY false
POINT_GROUP_SYMMETRY false
IQMOL_FCHK true
MAX_SCF_CYCLES 300
"""

# ==========================================================
#               基组定义 ($basis 部分)
# ==========================================================
# ----------------- 激发原子配置 -----------------
[excited]
# 定义被激发的原子 (可以用原子序号、范围、元素符号)
# 示例: "1 3-5 N" 表示第1个原子、第3到5个原子、以及所有的N原子
num   = """
N 2
"""

# 为激发原子指定的基组
basis = """
6-311g
"""

# 指定从 'alpha' 还是 'beta' 轨道激发 (默认为 'beta')
ionization_spin = """
beta
"""

# ----------------- 非激发原子配置 -----------------
# 可以定义多组非激发原子及其基组
# 命名规则: num1/basis1, num2/basis2, ...
[non_excited]
num1    = """
1
"""
basis1  = """
3-21G
"""

num2    = """
C
"""
basis2  = """
6-31G
"""

num3    = """
H
"""
basis3  = """
STO-3G
"""

# 如果不需要第4组，可以将其留空
num4    = """
"""
basis4  = """
"""

文件 2: pyridine.xyz

11

N     -1.21390500   -0.76688800    0.00000000
C     -1.23050600    0.58519600    0.00000000
C     -0.07028600    1.38150500    0.00000000
C      1.18362600    0.74775800    0.00000000
C      1.21742000   -0.65680000    0.00000000
C      0.00000000   -1.36257100    0.00000000
H     -2.22120100    1.05147700    0.00000000
H     -0.15352900    2.47192200    0.00000000
H      2.10854100    1.33207700    0.00000000
H      2.16639700   -1.20029000    0.00000000
H     -0.00439300   -2.45750200    0.00000000

B. 步骤 1: 运行基态 (GS) 和 Z+1 计算

[excited] -> num 设置为 "N 2"，脚本会将其解析为 "所有 N 原子 (原子 1)" 和 "原子 2 (C 原子)"。

运行命令:

qchem_xray.py GS
qchem_xray.py Z+1

脚本行为:

创建目录 1/GS/ 和 2/GS/。
在 1/GS/ 中生成 1GS.in，在 2/GS/ 中生成 2GS.in。
创建目录 1/Z+1/ 和 2/Z+1/。
在 1/Z+1/ 中生成 1Z+1.in (N -> O)，在 2/Z+1/ 中生成 2Z+1.in (C -> N)。
在每个新创建的目录中执行 qqchem 1 2 old 命令提交作业。

示例: 生成的 1GS.in 文件内容
(注意 BASIS mixed 和混合基组的定义)

$rem
   METHOD bp86
   BASIS mixed
   PURECART 1111
   GEN_SCFMAN true
   SCF_ALGORITHM diis
   BASIS2 def2-svp
   UNRESTRICTED true
   SCF_GUESS_MIX 5
   SCF_CONVERGENCE 8
   INTEGRAL_SYMMETRY false
   POINT_GROUP_SYMMETRY false
   IQMOL_FCHK true
   MAX_SCF_CYCLES 300
   NBO true
$end

$nbo
naomo
$end

$molecule
0 1
 N     -1.21390500   -0.76688800    0.00000000
 C     -1.23050600    0.58519600    0.00000000
 C     -0.07028600    1.38150500    0.00000000
 C      1.18362600    0.74775800    0.00000000
 C      1.21742000   -0.65680000    0.00000000
 C      0.00000000   -1.36257100    0.00000000
 H     -2.22120100    1.05147700    0.00000000
 H     -0.15352900    2.47192200    0.00000000
 H      2.10854100    1.33207700    0.00000000
 H      2.16639700   -1.20029000    0.00000000
 H     -0.00439300   -2.45750200    0.00000000
$end

$basis
N 1
6-311g
****
C 2
6-31G
****
C 3
6-31G
****
C 4
6-31G
****
C 5
6-31G
****
C 6
6-31G
****
H 7
STO-3G
****
H 8
STO-3G
****
H 9
STO-3G
****
H 10
STO-3G
****
H 11
STO-3G
****
$end

注意: non_excited 中 num1=1 (3-21G) 被 num2=C (6-31G) 的规则覆盖了，因为原子 1 (N) 匹配了 excited 规则，而原子 2-6 (C) 匹配了 num2 规则。

注意: 如果计算关键词中含有 NBO，将会自动添加以下模块：
$nbo
naomo
$end

C. 步骤 2: (可选) 检查/生成轨道缓存

注意：如果不运行该步骤，不会生成[num]GS_orbital.cache文件。但是后续运行依赖于GS的计算类型，也会自动调用extract_orbital_composition.py生成[num]GS_orbital.cache文件，因此此步骤不是必选。但是推荐计算完所有GS后，进行此步骤，查看有没有异常轨道或者未局域化轨道，防止造成计算资源浪费。

等待步骤 1 中的 GS 计算全部完成。

运行命令:

qchem_xray.py CACHE

脚本行为:

脚本开始处理原子 1 (N) 和 2 (C)。
它将调用 extract_orbital_composition.py (因为缓存尚不存在)。
该脚本会分析 1/GS/1GS.fchk 和 2/GS/2GS.fchk。
如果轨道局域化程度低，extract_orbital_composition.py 可能会提示用户是否使用 MOKIT 进行局域化（这是交互式的）。
最终生成 1/GS/1GS_orbital.cache 和 2/GS/2GS_orbital.cache。
同时生成一个总结文件 orbital.cache。

D. 步骤 3: 运行激发态计算 ( `FCH`, `FCH_R`, `LUMO`, `TD_XAS`, `TD_XES` )

等待 GS 计算完成后，您可以运行所有依赖 GS 的计算。

运行命令:

qchem_xray.py FCH
qchem_xray.py FCH_R
qchem_xray.py LUMO
qchem_xray.py TD_XAS
qchem_xray.py TD_XES

脚本行为 (以 FCH 为例):

创建 1/FCH/ 和 2/FCH/。
读取缓存: 脚本读取 1/GS/1GS_orbital.cache 和 2/GS/2GS_orbital.cache (如果缓存不存在，它会像步骤 2 一样自动生成它们)。
确定轨道: 根据 [excited] -> ionization_spin = beta，它会查找 beta 轨道的最低芯轨道。假设对于原子 1 (N)，它找到的是轨道 2。
生成输入: 生成 1/FCH/1FCH.in。
提交作业: 在 1/FCH/ 目录中运行 qqchem 1 2 old。

示例: 生成的 1FCH.in 文件内容
(假设 GS 有 21 个 alpha 和 21 个 beta 电子, 且 N 1s (beta) 是轨道 2)

$occupied
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
1 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
$end

$rem
   METHOD bp86
   BASIS mixed
   PURECART 1111
   GEN_SCFMAN false
   SCF_ALGORITHM diis
   SCF_GUESS read
   UNRESTRICTED true
   MOM_START 1
   MOM_METHOD imom
   SCF_CONVERGENCE 6
   INTEGRAL_SYMMETRY false
   POINT_GROUP_SYMMETRY false
   IQMOL_FCHK true
  *MAX_SCF_CYCLES 300
$end

$molecule
1 2
 N     -1.21390500   -0.76688800    0.00000000
 C     -1.23050600    0.58519600    0.00000000
 C     -0.07028600    1.38150500    0.00000000
 C      1.18362600    0.74775800    0.00000000
 C      1.21742000   -0.65680000    0.00000000
 C      0.00000000   -1.36257100    0.00000000
 H     -2.22120100    1.05147700    0.00000000
 H     -0.15352900    2.47192200    0.00000000
 H      2.10854100    1.33207700    0.00000000
 H      2.16639700   -1.20029000    0.00000000
 H     -0.00439300   -2.45750200    0.00000000
$end

$basis
N 1
6-311g
****
C 2
6-31G
****
C 3
6-31G
****
C 4
6-31G
****
C 5
6-31G
****
C 6
6-31G
****
H 7
STO-3G
****
H 8
STO-3G
****
H 9
STO-3G
****
H 10
STO-3G
****
H 11
STO-3G
****
$end

(注意 $occupied 部分的 beta 轨道 (第二行) 中将会去掉轨道 2, 表示电离的芯轨道是2。)

E. 步骤 4: LUMO 专用额外计算

LUMO 计算的行为与 FCH 类似，但它会将电子移动到未占据轨道，并且受 -l 选项控制。

运行命令 (情况 A: 默认激发到 LUMO):

qchem_xray.py LUMO

这等同于 qchem_xray.py LUMO -l 0。
脚本会将电子从芯轨道 (例如轨道 2) 移动到 LUMO (即 n_beta + 1，如果 n_beta=21，则移动到轨道 22)。
生成的 1LUMO.in 中 $occupied 的 beta 列表将是: 1 3 4 ... 21 22。

运行命令 (情况 B: 激发到 LUMO+2):

qchem_xray.py LUMO -l 2

脚本使用 LEVEL = 2。
- 脚本会创建LUMO+2文件夹。
- 脚本会将电子从芯轨道 (例如轨道 2) 移动到 LUMO + 2 (即 (n_beta + 1) + 2，如果 n_beta=21，则移动到轨道 24)。
- 生成的 1LUMO+2.in 中 $occupied 的 beta 列表将是: 1 3 4 ... 21 24。

5. 高级选项详解

A. `-r, --retry` (重试失败/跳过选项)

功能:
--retry 选项允许您仅重试在上一次运行中生成失败或被用户手动跳过（例如，在提示覆盖时选择了 'n'）的原子。
适用场景:
假设您正在为 20 个原子运行 FCH 计算。
- 在第一次运行时，原子 1-15 成功生成。
- 原子 16 的 GS 计算未完成，导致生成失败。
- 当脚本提示是否覆盖原子 17 的现有目录时，您不小心选了 "n" (否)，导致它被跳过。
- 原子 18-20 成功。
在这种情况下，您不需要重新运行所有 20 个原子。您可以先修复原子 16 的问题（例如，重新运行 GS 计算），然后使用 --retry 标志。
工作原理:
1. 日志文件: 当 qchem_xray.py 运行 GS 之外的计算时，它会在 print_summary 函数中评估哪些原子生成失败 (self.failed_generations) 或被跳过 (self.skipped_atoms)。
2. 它会将这些失败/跳过的原子编号列表写入一个日志文件，命名格式为 [calc_type]_skipped.log（例如 FCH_skipped.log）。
3. 重试模式: 当您使用 qchem_xray.py FCH -r 再次运行脚本时：
  - 脚本会查找 FCH_skipped.log 文件。
  - 它会读取该文件中的所有原子编号。
  - 它会忽略 input.ini 中 [excited] -> num 的设置，转而只对从日志文件中读取的原子（在此例中为 16 和 17）执行计算。
注意: 此选项仅对 FCH, FCH_R, LUMO, TD_XAS, TD_XES 有效，因为它对 GS 或 Z+1 没有意义。

示例命令:

# 重试上次未生成的`FCH`计算任务, 读取的是`FCH_skipped.log`文件中的原子列表，可以自己调整。
qchem_xray.py FCH -r"

B. `-co ORBITALS, --core-orbital ORBITALS` (手动指定芯轨道)

功能:
这是一个非常高级的选项，允许您手动覆盖并指定用于计算的芯轨道编号，完全跳过脚本的自动轨道检测（即读取 .cache 文件或调用 extract_orbital_composition.py 的过程）。
格式:
必须使用 'atom1:orb1 atom2:orb2' 的格式，例如：-co "1:2 5:3"。
适用场景:
1. 自动检测失败: extract_orbital_composition.py 脚本可能因各种原因（如轨道混合严重、NBO 分析失败）无法正确识别您想要的 1s 芯轨道。
2. 选择特定轨道: 您可能不想激发能量最低的芯轨道（例如，对于硫 (S)，您可能想激发 1s，但自动检测却错误地选择了 2s/2p）。
3. 节省时间: 您已经通过其他方式（例如，手动检查 GS.fchk 或 GS.out）知道了芯轨道的编号，不想等待（可能很慢的）extract_orbital_composition.py 脚本再次运行。
工作原理:
1. 解析: 脚本启动时会解析您提供的字符串 (例如 "1:2 5:3")，并将其转换为一个字典：{1: 2, 5: 3}。
2. 传递: 这个字典被传递给 QchemInputGenerator。
3. 覆盖: 当脚本为激发态（如 FCH）准备输入文件时，在 _get_excited_orbital 函数中，它会首先检查当前原子编号是否在您的 "覆盖字典" 中。
4. 跳过检测:
  - 如果原子在字典中 (例如原子 1)，脚本会打印一条 "命令行覆盖" 消息，并立即使用您指定的轨道号 (轨道 2)。它不会尝试读取 1GS_orbital.cache 文件，也不会运行 extract_orbital_composition.py。
  - 如果原子不在字典中 (例如原子 2)，脚本将回退到标准的自动检测流程（读取缓存或运行外部脚本）。

示例命令:
假设 input.ini 中 num = "N 2" (即原子 1 和 2)。自动检测发现原子 1 的芯轨道是 2，但原子 2 (C) 的检测失败了。您手动检查发现原子 2 的芯轨道是 3。您可以使用以下命令：

# 运行 FCH
# - Atom 1: 使用 -co 指定的轨道 2
# - Atom 2: 使用 -co 指定的轨道 3
qchem_xray.py FCH -co "1:2 2:3"

C. 自定义计算类型

功能:
这是一个非常灵活的选项，允许您自定义一个计算类型，您只需要修改该程序表头部分，指定一个计算类型，并标记其采用的轨道处理类型即可。

修改.py格式:

# ==============================================================================
#  全局配置区域: 计算模式与轨道处理策略定义
# ==============================================================================

# 您可以在此处添加自定义的计算类型。
# 格式说明:
#   '计算类型名': {
#       'description': '描述文本',
#       'strategy':    '轨道处理策略', 
#                      可选值: 'none' (无操作), 'occupied' ($occupied), 
#                             'reorder' ($reorder_mo), 'alist' ($alist), 'lumo' (LUMO+N)
#       'requires_gs': True/False, (是否需要读取GS的轨道缓存和MO文件)
#       'handler':     '处理逻辑',
#                      可选值: 'standard' (标准生成), 'z_plus_1' (Z+1近似), 'cache' (仅缓存)
#   }
# === 在下方添加您的自定义计算类型 ===
# 'CUSTOM': {
#     'description': '自定义计算示例',
#     'strategy': 'occupied',  # 假设使用 $occupied 方法
#     'requires_gs': True,     # 假设基于GS
#     'handler': 'standard'
# },
# ===================================

修改.ini格式:

在 [xyz] 部分添加相应计算类型的电荷和自旋多重度, 例如:
```
CUSTOM_charge_mult = """
1 2
"""
```
在 [keys] 部分添加相应计算类型的关键词部分, 例如:
```
CUSTOM = """
PURECART 1111
INTEGRAL_SYMMETRY false
POINT_GROUP_SYMMETRY false
IQMOL_FCHK TRUE
MAX_SCF_CYCLES 300
"""
```

一键式轨道生成脚本

zhangjr — Mon, 17 Nov 2025 18:32:32 +0800

FCH（Q-Chem）
1. 在FCH文件夹下的文件中，查高强度峰对应的是哪个轨道
  bardata_beta.XAS（闭壳层情况下）；bardata.XAS（开壳层情况）
2. 在GS文件夹内运行
  Multiwfn XXX.fchk ➡ 200 ➡ 3 ➡ 输入轨道号（如519-530） ➡ 2 ➡ 1
3. vmd
  - shell下： orb 519 ➡ obiso 0.02
  - 本地电脑：拷贝XXX.cube到本地电脑
    在cube文件夹下，shift+右键 ➡ Powershell
    vmd ➡ orb 519 ➡ obiso 0.02 摆好位置
    vmd操作：Graphics ➡ colors ➡ element ➡
    Graphics ➡ colors ➡ Prepre..➡ CPK ➡ Coloring Method ➡ Element
    Graphics ➡ colors ➡ Prepre..➡ isosurface ➡ coborID ➡ 改颜色
    File ➡ save visuali.. ➡ orbnumb (保存的文件名称)
  将orbnumb拷贝到集群cub所在的位置 ➡ cub2bmp(对所有cub以orbnumb为模板进行渲染)
Z+1
1. gzip -d XXX.gz
2. Multiwfn XXX.fch
3. 同FCH
TDDFT（Q-Chem）
1. 在XAS.analyze下，拷贝GS/XXX.fchk ➡ XAS.fchk
2. Muttiwfn XAS.fchk ➡ 18 ➡ 6 ➡ 回车 ➡（在XAS.data内找高强度峰对应的轨道，如轨道30） ➡ 2 ➡ S30.fch ➡ 退出
3. Muttiwfn S30.fch ➡ 0 (看轨道) ➡ 找HOMO/LUMO, 即找2/0，如485（hoLe）,486(part) ➡ 退出
4. Muttiwfn S30.fch ➡ 200 ➡ 3 ➡ 485-486 ➡ 2 ➡ 退出
5. 将orbnumb拷贝到集群cub所在的位置 ➡ cub2bmp(对所有cub以orbnumb为模板进行渲染)

在Windows上使用ORCA计算旋轨耦合（SOC）矩阵元

wangsy — Fri, 15 Aug 2025 11:35:26 +0800

1. 引言

本文主要面向无Linux使用经验的实验组本科以及研究生，能够实现在windows上直接使用ORCA软件包进行旋轨耦合矩阵元的计算与分析，打破实验与理论分析的壁垒。
如有Linux使用经验，还有一批更简洁的使用脚本。准备好输入文件，能够做到Linux下一键式计算于结果分析。
任何问题可以联系作者：wang.sy@vip.163.com

1.1 为什么要计算旋轨耦合？

在非相对论量子力学的世界里，电子的自旋和它的轨道运动是完全独立的。这存在一个严格的规则：自旋多重度在电子跃迁过程中必须保持不变。也就是说，单重态（Singlet, S）只能跃迁到单重态，三重态（Triplet, T）只能跃迁到三重态。因此，像系间窜越（Intersystem Crossing, ISC）（例如，从S₁态到T₁态）和磷光发射（从T₁态回到S₀基态）这类改变自旋的“禁阻”过程，其理论上的发生概率为零。

然而，在现实世界中，这些过程广泛存在于有机发光二OLED、光动力疗法等领域。这背后的“魔法”就是旋轨耦合（Spin-Orbit Coupling, SOC）。

SOC是一种相对论效应，它描述了电子自旋磁矩和其轨道运动产生的磁场之间的相互作用。当考虑SOC时，哈密顿算符中会增加一项$H_{SO}$，它打破了自旋与轨道运动的独立性。这使得原本纯粹的单重态会“混入”一些三重态的成分，反之亦然。这样一来，S→T或T→S的跃迁就不再是完全禁阻的了，其跃迁概率的大小就直接与这两个态之间的旋轨耦合强度有关。

我们通常用旋轨耦合矩阵元 $\langle\Psii|H{SO}|\Psi_j\rangle$ 来定量描述两个电子态（例如一个单重态和一个三重态）之间的耦合强度。这个值越大，它们之间发生自旋翻转过程的速率就越快。因此，计算SOC矩阵元对于理解和设计具有特定光物理性质（如高磷光效率）的分子至关重要。

1.2 教程章节

本教程旨在为计算化学零基础的本科和研究生提供一个清晰、详尽的指南。我们将遵循以下步骤：
理论背景：用最通俗的语言解释SOC计算的核心思想。
准备工作与Windows系统操作：讲解如何在Windows上准备并运行ORCA计算。
实例一：简单有机分子（甲醛）：最基础的SOC计算流程，不涉及复杂的标量相对论效应。
实例二：重金属配合物（Ir(ppy)₃）：如何处理含有重金属的体系，必须考虑标量相对论效应。
实例三：周期性结构（石墨烯量子点）：如何将晶体等周期性结构简化为分子模型进行计算。
输出文件解读：如何从ORCA输出文件中提取和理解所有与SOC相关的数据。

2. 理论背景简介

我们计算的目标是求解旋轨耦合矩阵元 $\langle Sm | H{SO} | Tn \rangle$。这里的$H{SO}$就是旋轨耦合哈密顿算符。在ORCA等量子化学软件中，主要通过以下两种方法来处理$$H_{SO}$$：

旋轨耦合平均场 (Spin-Orbit Mean-Field, SOMF)：这是一种精度较高的方法。它将复杂的双电子SOC项通过平均场的方式进行简化，在保证精度的同时极大地降低了计算成本。这是ORCA中处理SOC的默认且推荐的方法。
有效核电荷 (Effective Nuclear Charge, Zeff)：这是一种更近似的方法。它认为双电子的SOC贡献与单电子的贡献有较好的比例关系，因此通过修正单电子项中的核电荷（使用一个“有效”值Zeff），来近似地包含双电子的贡献。这种方法计算速度最快，但精度相对较低。在pysoc中就是使用该方法。

对于含有重金属（如Ir, Os, Pt, Au等）的体系，除了SOC效应，标量相对论效应也非常重要。它主要影响电子的动能和势能，导致轨道收缩或扩张。在ORCA中，我们通常使用ZORA (Zeroth-Order Regular Approximation) 或 DKH2 (Douglas-Kroll-Hess, 2nd order) 哈密顿来处理标量相对论效应。

因此，我们的计算策略是：

对轻元素体系：直接在非相对论框架下计算SOC。
对重元素体系：同时使用标量相对论哈密顿（如ZORA/DKH2）和SOC计算。

3. 准备工作与Windows系统操作

3.1 必备软件

ORCA程序：点击此处免费注册并下载。下载后解压到一个没有中文和空格的路径，例如 D:\orca。
Windows环境变量配置：
- 右键“此电脑” -> 属性 -> 高级系统设置 -> 环境变量。
- 在“系统变量”中找到 Path，点击“编辑”。
- 点击“新建”，然后将你的ORCA程序路径（例如 D:\orca）添加进去。
- 这样，你就可以在任何位置通过命令行调用ORCA了。
文本编辑器：推荐使用 Notepad++ 或 Sublime Text。不要使用Windows自带的记事本，它可能会导致格式问题。

3.2 如何在Windows上运行ORCA计算

ORCA是一个命令行程序，操作流程如下：

创建工作文件夹：在电脑上创建一个新的文件夹用于存放计算文件，例如 D:\orca_calc\formaldehyde。
编写输入文件：在该文件夹中，使用文本编辑器创建一个新的文本文件，并将其命名为 calc.inp（.inp 是ORCA输入文件的常用扩展名）。将下文例子中的输入代码复制进去。
打开命令提示符 (CMD)：
- 在工作文件夹的地址栏输入 cmd 然后按回车，可以直接在该目录下打开命令提示符。
- 或者，通过开始菜单搜索 cmd 打开，然后使用 cd 命令切换到你的工作目录，例如：
```
D:
cd D:\orca_calc\formaldehyde
```
执行计算命令：在命令提示符窗口中，输入以下命令并按回车：
```
orca calc.inp > calc.out
```
- orca calc.inp：调用ORCA程序执行 calc.inp 文件中的计算任务。
- >：这是一个重定向符号，意思是将屏幕上本应显示的所有输出信息，全部“重定向”并写入到后面的文件中。
- calc.out：这是指定的输出文件名。计算过程和所有结果都将保存在这个文件里。
监控计算：计算开始后，你可以用文本编辑器打开 calc.out 文件。文件会实时更新，你可以通过查看文件末尾来判断计算是否正常进行。当命令提示符窗口出现新的可输入行，并且 calc.out 文件末尾出现 ****ORCA TERMINATED NORMALLY**** 时，表示计算成功结束。

4. 实例一：简单有机分子（甲醛 H₂CO）

甲醛是一个不含重元素的典型小分子，我们用它来演示最基本的SOC-TDDFT计算(默认使用SOMF处理旋轨耦合)。

4.1 步骤一：基态结构优化 (可选但推荐)

在计算激发态性质之前，通常需要先获得分子在基态下的稳定结构。
创建一个名为 formaldehyde_opt.inp 的输入文件。

! B3LYP def2-SVP Opt TightSCF

%pal
  nprocs 8
end

* xyz 0 1
  C    0.000000   0.000000  -0.525135
  H    0.000000   0.939879  -1.112613
  H    0.000000  -0.939879  -1.112613
  O    0.000000   0.000000   0.672004
*

! B3LYP def2-SVP Opt TightSCF：这是关键词行。
- B3LYP: 使用B3LYP泛函。
- def2-SVP: 使用def2-SVP基组。
- Opt: 进行几何结构优化。
- TightSCF: 使用更严格的SCF收敛标准，推荐用于后续的激发态计算。
%pal nprocs 8 end：设置并行计算，使用8个CPU核心。请根据你的电脑配置修改。
* xyz 0 1 ... *：分子坐标部分。
- xyz: 表示坐标格式为XYZ。
- 0: 分子总电荷。
- 1: 自旋多重度 (2S+1)，1表示单重态。
- 后面是原子和其三维坐标。

运行优化后，你会得到一个 formaldehyde_opt.xyz 文件，里面包含了优化好的结构坐标。

4.2 步骤二：旋轨耦合计算

使用上一步优化好的结构，创建 formaldehyde_soc.inp 文件。

! B3LYP def2-SVP TightSCF

%pal
  nprocs 8
end

%tddft
  nroots 5
  dosoc true
  tda false
end

* xyzfile 0 1 formaldehyde_opt.xyz

! B3LYP def2-SVP TightSCF：计算级别与优化保持一致。
%tddft ... end：这是TD-DFT计算的设置模块。
- nroots 5：计算5个激发态。当 dosoc开启时，ORCA会自动计算5个单重态激发态(S₁-S₅)和5个三重态激发态(T₁-T₅)。
- dosoc true：这是计算旋轨耦合的核心关键词。
- tda false：使用标准的、完整的TD-DFT方法，而不是TDA近似。通常结果更准确。
* xyzfile 0 1 formaldehyde_opt.xyz：从 formaldehyde_opt.xyz 文件中直接读取分子坐标、电荷和多重度。

运行此计算，结束后在 formaldehyde_soc.out 文件中就可以找到旋轨耦合矩阵元的结果了。具体如何解读，请见本文第7节。

5. 实例二：重金属配合物 (Ir(ppy)₃)

Ir(ppy)₃是磷光OLED中经典的绿光材料，含有重金属Ir，必须考虑相对论效应。

5.1 步骤一：基态结构优化

对于含重金属的配合物，优化时常用赝势基组（ECP）来替代重金属的内层电子。对于Ir这类重金属来收，def2系列基组直接采用了ECP形式，因此无需再newgto来指定ECP基组。其余基组需要基组使用规则来创建输入文件。

创建 Ir_ppy3_opt.inp 文件：

! B3LYP D3BJ def2-SVP def2/J CPCM(CH2Cl2) Opt TightSCF

%pal
  nprocs 8
end

* xyz 0 1
C        3.393895879     -0.289566719      2.776304932
C        4.076284431     -1.374299959      2.244246939
C        3.562788518     -2.026286944      1.144617313
C        2.365194919     -1.600441421      0.563698783
C        1.656920791     -0.490717084      1.087023288
C        2.209908242      0.138316955      2.204838066
C        1.779556093     -2.262575837     -0.593808565
C        2.310998596     -3.397126504     -1.214621244
C        1.678633212     -3.946679457     -2.310344980
C        0.513725976     -3.353425417     -2.779039051
C        0.041132843     -2.238327622     -2.115943483
N        0.643735830     -1.703611386     -1.062120264
C       -3.228320892     -2.843015891      2.244246939
C       -1.947720074     -2.794416690      2.776304932
C       -0.985168124     -1.982995155      2.204838066
C       -1.253433856     -1.189576955      1.087023288
C       -2.568620388     -1.248098174      0.563698783
C       -3.536210228     -2.072321893      1.144617313
C       -2.849226199     -0.409852865     -0.593808565
N       -1.797238653      0.294314111     -1.062120264
C       -1.959015004      1.083541724     -2.115943483
C       -3.161014589      1.231812963     -2.779039051
C       -4.257241276      0.519600723     -2.310344980
C       -4.097497151     -0.302820240     -1.214621244
C       -0.403486935      1.680294039      1.087023288
C       -1.224740118      1.844678200      2.204838066
C       -1.446175805      3.083983409      2.776304932
C       -0.847963539      4.217315849      2.244246939
C       -0.026578290      4.098608837      1.144617313
C        0.203425469      2.848539595      0.563698783
C        1.069670107      2.672428702     -0.593808565
C        1.786498555      3.699946745     -1.214621244
C        2.578608064      3.427078734     -2.310344980
C        2.647288613      2.121612454     -2.779039051
C        1.917882161      1.154785898     -2.115943483
N        1.153502823      1.409297275     -1.062120264
Ir       0.000000000      0.000000000      0.043448572
H        3.792342787      0.222162593      3.641507453
H        5.002872009     -1.707739869      2.689139743
H        4.102575829     -2.869480849      0.738507580
H        1.696641422      0.983426029      2.641159087
H        3.213678708     -3.847263406     -0.836341679
H        2.081671478     -4.823466100     -2.794933558
H       -0.013921102     -3.747584685     -3.633027960
H       -0.865398626     -1.751267403     -2.451342694
H       -3.980382114     -3.478744318      2.689139743
H       -1.703772945     -3.395346490      3.641507453
H        0.003351213     -1.961047587      2.641159087
H       -4.536331226     -2.118194464      0.738507580
H       -1.083942747      1.625090897     -2.451342694
H       -3.238542989      1.885848371     -3.633027960
H       -5.218079916      0.608952668     -2.794933558
H       -4.938667199     -0.859495698     -0.836341679
H       -1.699992635      0.977621558      2.641159087
H       -2.088569843      3.173183897      3.641507453
H       -1.022489895      5.186484186      2.689139743
H        0.433755396      4.987675313      0.738507580
H        1.724988490      4.706759104     -0.836341679
H        3.136408438      4.214513433     -2.794933558
H        3.252464091      1.861736314     -3.633027960
H        1.949341373      0.126176507     -2.451342694
*

D3BJ: 加入 Grimme 的 D3 色散校正（带BJ dampening），对于配合物这类大体系很重要。
def2/J: 使用 def2/J 作为 RI (Resolution of Identity) 近似的辅助基组，可以加速计算。
CPCM(CH2Cl2): 使用 CPCM 溶剂化模型模拟二氯甲烷溶剂环境。

5.2 步骤二：旋轨耦合计算

对于重金属，激发态计算必须包含标量相对论效应，此时需要使用全电子基组，而非优化时候的赝势基组。这里标量相对论效应有两种处理方法：ZORA/DKH。

5.21 使用ZORA方法考虑标量相对论效应

创建 Ir_ppy3_soc.inp 文件：

! B3LYP ZORA ZORA-def2-TZVP SARC/J RI-SOMF(1X) CPCM(CH2Cl2) TightSCF

%basis
  newgto Ir "SARC-ZORA-TZVP" end
end

%pal
  nprocs 8
end

%tddft
  nroots 10
  dosoc true
  tda false
end

* xyzfile 0 1 Ir_ppy3_opt.xyz

ZORA: 使用ZORA哈密顿来考虑标量相对论效应。
ZORA-def2-TZVP: 这是一个专门为ZORA方法优化的全电子基组，用于轻元素。
SARC/J: 用于ZORA计算的通用辅助基组。
RI-SOMF(1X): 使用RI近似来加速SOMF方法的SOC积分计算，兼顾速度和精度。
%basis ... end:
- newgto Ir "SARC-ZORA-TZVP" end: 为Ir原子指定专门适配ZORA的全电子基组 SARC-ZORA-TZVP。注意：在做含SOC的相对论计算时，重金属必须使用全电子基组，不能用赝势。
%tddft nroots 10 ... end：计算10个激发态并开启SOC。

5.22 使用DKH方法考虑标量相对论效应

创建 Ir_ppy3_soc.inp 文件：

! B3LYP DKH2 DKH-def2-TZVP SARC/J RI-SOMF(1X) CPCM(CH2Cl2) TightSCF

%basis
  newgto Ir "SARC-DKH-TZVP" end
end

%pal
  nprocs 8
end

%tddft
  nroots 10
  dosoc true
  tda false
end

* xyzfile 0 1 Ir_ppy3_opt.xyz

DKH: 使用DKHA哈密顿来考虑标量相对论效应。
DKH-def2-TZVP: 这是一个专门为DKH方法优化的全电子基组，用于轻元素。
SARC/J: 用于DKH计算的通用辅助基组。
RI-SOMF(1X): 使用RI近似来加速SOMF方法的SOC积分计算，兼顾速度和精度。
%basis ... end:
- newgto Ir "SARC-DKH-TZVP" end: 为Ir原子指定专门适配DKH的全电子基组 SARC-DKH-TZVP。注意：在做含SOC的相对论计算时，重金属必须使用全电子基组，不能用赝势。
%tddft nroots 10 ... end：计算10个激发态并开启SOC。

运行此计算，由于体系较大且计算级别较高，会比甲醛耗时得多。

6. 实例三：周期性结构（石墨烯量子点）

对于晶体、MOF等周期性结构，我们无法直接用ORCA计算。常用的方法是“团簇模型”：

从周期性结构中切出一个有代表性的、足够大的团簇。
对于团簇边缘被切断的化学键，用氢原子进行“饱和”，以消除悬挂键带来的不合理电子结构。
对这个饱和后的分子团簇进行计算。

这里，我们以单层石墨烯为例，构建一个 C₂₄H₁₂ 的石墨烯量子点模型。

6.1 步骤一：构建团簇模型

这一步通常使用 VESTA, Materials Studio, Avogadro 等软件完成。这里我们直接提供构建好的模型坐标。这个模型可以看作是一个普通的有机分子，不含重金属。
构建模型后，一般需要对用于饱和的H原子位置进行限制性优化，也就是冻结除H原子以外的所有原子进行优化。

6.2 步骤二：旋轨耦合计算

由于模型较大，我们可以使用计算成本稍低的泛函和基组。
创建 graphene_dot_soc.inp 文件：

! PBE0 def2-SVP def2/J RIJCOSX TightSCF

%pal
  nprocs 8
end

%tddft
  nroots 10
  dosoc true
  tda false
end

* xyz 0 1
 C   -1.22500000   -2.12176200    0.00000000
 C    1.22500000   -2.12176200    0.00000000
 C    2.45000000    0.00000000    0.00000000
 C    1.22500000    2.12176200    0.00000000
 C   -1.22500000    2.12176200    0.00000000
 C   -2.45000000    0.00000000    0.00000000
 H   -2.14500000   -3.71533400    0.00000000
 H    2.14500000   -3.71533400    0.00000000
 H    4.29000000    0.00000000    0.00000000
 H    2.14500000    3.71533400    0.00000000
 H   -2.14500000    3.71533400    0.00000000
 H   -4.29000000    0.00000000    0.00000000
 C    0.00000000   -2.83606200    0.00000000
 C    2.45000000   -1.41803100    0.00000000
 C    2.45000000    1.41803100    0.00000000
 C    0.00000000    2.83606200    0.00000000
 C   -2.45000000    1.41803100    0.00000000
 C   -2.45000000   -1.41803100    0.00000000
 C   -1.22500000   -0.70703100    0.00000000
 C    1.22500000   -0.70703100    0.00000000
 C    1.22500000    0.70703100    0.00000000
 C   -1.22500000    0.70703100    0.00000000
 C    0.00000000   -1.41406200    0.00000000
 C    0.00000000    1.41406200    0.00000000
 C    0.00000000    4.25412400    0.00000000
 H    0.00000000    5.17412400    0.00000000
 C    3.67500000    2.12176200    0.00000000
 H    4.59500000    2.12176200    0.00000000
 C    3.67500000   -2.12176200    0.00000000
 H    4.59500000   -2.12176200    0.00000000
 C    0.00000000   -4.25412400    0.00000000
 H    0.00000000   -5.17412400    0.00000000
 C   -3.67500000   -2.12176200    0.00000000
 H   -4.59500000   -2.12176200    0.00000000
 C   -3.67500000    2.12176200    0.00000000
 H   -4.59500000    2.12176200    0.00000000
*

! PBE0 def2-SVP ... RIJCOSX:
- PBE0: 使用PBE0杂化泛函。
- RIJCOSX: 一种加速DFT计算的组合近似方法，对大体系非常有效。
计算流程与甲醛的例子完全一样，只是分子体系变大了。

7. 详细解读ORCA输出文件中的旋轨耦合部分

无论你计算的是哪个体系，解读输出文件中SOC结果的方法都是一样的。用文本编辑器打开 .out 文件，查看计算结果。

7.1 TD-DFT 激发能

在SOC部分之前，ORCA会先列出常规的TD-DFT计算结果，包括单重态和三重态的激发能。这是未考虑SOC时的结果，可见单重态和三重态是分开的，这是由于未考虑旋轨耦合时，单重态和三重态之间的跃迁几率始终为0。
单重态结果：

------------------------------------
TD-DFT/TDA EXCITED STATES (SINGLETS)
------------------------------------

the weight of the individual excitations are printed if larger than 1.0e-02

STATE  1:  E=   0.011499 au      0.313 eV     2523.8 cm**-1  =   0.000000 Mult 1
   688a -> 691a  :     0.045345 (c= -0.21294353)
   688a -> 692a  :     0.937045 (c= -0.96801095)

STATE  2:  E=   0.011578 au      0.315 eV     2541.1 cm**-1  =   0.000000 Mult 1
   688a -> 690a  :     0.039691 (c= -0.19922532)
   688a -> 693a  :     0.942490 (c= -0.97081944)
   688a -> 695a  :     0.010863 (c= -0.10422655)

STATE  3:  E=   0.029631 au      0.806 eV     6503.2 cm**-1  =   0.000000 Mult 1
   688a -> 690a  :     0.040855 (c= -0.20212531)
   688a -> 695a  :     0.811000 (c=  0.90055524)
   688a -> 699a  :     0.131057 (c= -0.36201761)

STATE  4:  E=   0.029682 au      0.808 eV     6514.5 cm**-1  =   0.000000 Mult 1
   688a -> 691a  :     0.022647 (c= -0.15048828)
   688a -> 694a  :     0.824565 (c= -0.90805567)
   688a -> 698a  :     0.131656 (c=  0.36284478)
   688a -> 700a  :     0.010673 (c=  0.10331240)
...

三重态结果：

------------------------------------
TD-DFT/TDA EXCITED STATES (TRIPLETS)
------------------------------------

the weight of the individual excitations are printed if larger than 1.0e-02

STATE  6:  E=  -0.023756 au     -0.646 eV    -5213.9 cm**-1  =   2.000000 Mult 3
   688a -> 689a  :     0.975173 (c=  0.98750825)

STATE  7:  E=   0.001091 au      0.030 eV      239.4 cm**-1  =   2.000000 Mult 3
   688a -> 691a  :     0.937900 (c=  0.96845245)
   688a -> 692a  :     0.033122 (c= -0.18199350)
   688a -> 694a  :     0.010180 (c= -0.10089691)
   688a -> 698a  :     0.011507 (c= -0.10726846)

STATE  8:  E=   0.001401 au      0.038 eV      307.5 cm**-1  =   2.000000 Mult 3
   688a -> 690a  :     0.944689 (c= -0.97195090)
   688a -> 693a  :     0.024687 (c=  0.15712210)

STATE  9:  E=   0.008003 au      0.218 eV     1756.4 cm**-1  =   2.000000 Mult 3
   688a -> 691a  :     0.035685 (c=  0.18890439)
   688a -> 692a  :     0.955382 (c=  0.97743630)
...

7.2 SOC矩阵元

ORCA输出单重态与三重态三个子态（磁量子数 $M_S = -1, 0, +1$）之间的耦合矩阵。

            CALCULATED SOCME BETWEEN TRIPLETS AND SINGLETS
     --------------------------------------------------------------------------------
           Root                        (Re, Im) cm-1
         T     S           MS= 0                 -1                   +1
     --------------------------------------------------------------------------------
         1     0     (   0.00 ,  -63.78)   (  -0.00 ,    0.00)   (  -0.00 ,   -0.00)
         1     1     (   0.00 ,    0.00)   (  -0.00 ,   -0.00)   (  -0.00 ,    0.00)
         1     2     (   0.00 ,    0.00)   (   5.62 ,    0.00)   (   5.62 ,   -0.00)
...

解读:
- T 和 S 列表示三重态和单重态的序号（0代表基态S₀）。
- MS= 0, -1, +1 分别对应三重态的三个子态。
- 每个括号里是该单重态与特定三重态子态耦合的 (实部, 虚部)。
- 总SOC矩阵元大小: 将这一行6个数字（3个子态，每个子态有实部和虚部）全部平方求和再开根号，得到的结果就是我们需要SOC矩阵元的大小。例如，对于 $\langle T1 | H{SO} | S_0 \rangle$，总大小为 $\sqrt{(-63.78)^2} = 63.78$ cm⁻¹。
  点击这里下载python写的提取旋轨耦合矩阵元的小程序，运行方式：python3 orca_soc.py XXX.out。生成XXX.txt，里面的数据就是计算完的所有旋轨耦合矩阵元。

7.3 考虑SOC修正后的光谱

计算的最后，ORCA会输出一个非常重要的部分：考虑SOC修正后的激发光谱。

-------------------------------------------
SOC CORRECTED TD-DFT/TDA-EXCITATION SPECTRA
--------------------------------------------
Generating SOC_CIS transition densities           ... done 

--------------------------------------------------------------------------------------------------------
      SOC CORRECTED ABSORPTION SPECTRUM VIA TRANSITION ELECTRIC DIPOLE MOMENTS    
--------------------------------------------------------------------------------------------------------
      Transition         Energy     Energy  Wavelength fosc(D2)      D2       |DX|      |DY|      |DZ|  
                          (eV)      (cm-1)    (nm)                 (au**2)    (au)      (au)      (au)  
--------------------------------------------------------------------------------------------------------
  0-3.0A  ->  1-3.0A    0.000000       0.0     0.0   0.000000000   0.00000   0.00000   0.00000   0.00000
  0-3.0A  ->  2-3.0A    0.000000       0.0     0.0   0.000000000   0.00000   0.00000   0.00000   0.00000
  0-3.0A  ->  3-1.0A    0.646430    5213.8  1918.0   0.000000210   0.00001   0.00057   0.00025   0.00359
  0-3.0A  ->  4-3.0A    0.676123    5453.3  1833.8   0.006709842   0.40507   0.10334   0.07064   0.62402
  0-3.0A  ->  5-3.0A    0.676123    5453.3  1833.8   0.429775649  25.94526   0.83286   0.53841   4.99617
  0-3.0A  ->  6-3.0A    0.676127    5453.3  1833.7   0.001908716   0.11523   0.05612   0.03633   0.33280
...
--------------------------------------------------------------------------------------------------------

解读:
- 这里的 Transition 不再是纯粹的单重态或三重态，而是经过SOC混合后的新态。
- Energy: 激发能(eV/cm-1)。
- Wavelength: 波长（nm）。
- fosc: 振子强度 (Oscillator Strength)。这是最重要的信息！对于原本自旋禁阻的跃迁（如 T₁→S₀），其振子强度本应为0。在这里，由于态的混合，它会获得一个非零的 fosc 值。这个值可以直接用来评估磷光发射的速率。
- D2, DX, DY, DZ: 跃迁偶极矩的平方和以及各分量。

只需要把Energy(eV)和fosc这两列数据拷贝到一个文件中，就可以获得棍状光谱。对棍状光谱使用高斯或者洛伦兹展宽即可获得传统意义上的可与实验光谱对应的光谱。
点击这里下载matlab程序，用于光谱展宽。

7.4 零场分裂 (Zero-Field Splitting, ZFS)

对于重金属配合物，输出文件中还会包含一个名为 Eigenvalues of the SOC matrix 的部分。

Eigenvalues of the SOC matrix:

   State:         cm-1            eV
      0:         0.00          0.0000
      1:     19166.96          2.3764
      2:     19201.28          2.3807
      3:     19269.86          2.3892
...

解读:
- 在没有SOC时，T₁态的三个子态是能量简并的。
- 考虑SOC后，这种简并会解除，能量发生分裂，这就是零场分裂 (ZFS)。
- 在上表中，能量相近的 State 1, 2, 3 就对应于原来的T₁态分裂成的三个新子态。
- ZFS的大小通常定义为能量最高和最低的子态之间的能量差。在此例中，ZFS = 19269.86 - 19166.96 = 102.9 cm⁻¹。这个值可以和实验值进行比较。

参考：

X射线光谱的理论模拟(芯激发态光谱模拟)

wangsy — Tue, 07 Jan 2025 22:38:52 +0800

[该文章已设置加密]

叫个啥名字的 Blog

qchem_toolkit 使用手册

qchem_toolkit 使用手册

1. 目录结构规范

2. 功能指令说明

2.1 check (任务状态监控)

2.2 ip (垂直电离能计算)

2.3 shift (光谱能量校准)

2.4 collect (数据提取与自动化平移)

Q-Chem软件计算XAS和XPS步骤

X-Ray Spectrum Plotter 用户手册

X-Ray Spectrum Plotter 用户手册

1. 简介 (Introduction)

主要功能

2. 环境要求与安装 (Installation)

2.1 第一步：下载并安装 Anaconda3

2.2 第二步：配置环境变量 (关键步骤)

2.3 第三步：安装 plotterxray 程序

4. 配置文件详解 (Configuration Guide)

4.1 [auto] - 自动扫描设置

4.2 [calculation] - 光谱计算与展宽核心

4.3 [general] - 画布通用设置

4.4 [plot_2d] - 2D 堆叠图设置

4.5 [plot_3d] - 3D 演化图设置

4.6 [spectra] - 手动文件列表

4.7 [exp_spectra] - 实验谱数据

5. 数据准备 (Data Preparation)

5.1 计算数据文件

5.2 实验数据文件

6. 高级用法与技巧 (Tips & Tricks)

6.1 缓存机制 (Cache System)

6.2 混合展宽策略 (Hybrid Broadening)

6.3 3D图去噪

6.4 批量修改颜色

7. 常见问题 (Troubleshooting)

8. 输出示例

Inkscape 原位缩放工具-SVGScaler.py使用手册

Inkscape 原位缩放工具使用手册

1. 简介

2. 环境准备

3. Inkscape 文件准备流程 (重要)

步骤 A：整理图层

步骤 B：群组逻辑 (关键)

步骤 C：保存文件

4. 脚本运行方法

基本语法

参数详解

5. 使用案例

案例 1：将 "text" 图层中的内容放大 1.5 倍

案例 2：将 "labels" 图层的内容缩小一半

案例 3：指定输出文件名

案例 4：暴力处理所有图层

6. 常见问题排错 (Troubleshooting)

7. 原理简述 (供高级用户参考)

Q-chem 安装指南 (Linux 集群)

用于自动提取芯轨道(分子和原子轨道)的程序

extract_orbital_composition.py 程序使用说明

1. 简介 (Program Overview)

关键特性

⚠️ 重要：运行依赖

2. 逻辑和流程 (Logic and Flow)

3. 程序的运行完整示例

示例 1: 基本用法（打印到屏幕）

示例 2: 交互式局域化

示例 3: 生成缓存文件（自动局域化）

4. 高级选项 (Advanced Options)

核心参数

阈值与输出

缓存模式 (qchem_xray.py)

MOKIT 局域化控制

自旋控制 (Spin Control)

调试 (Debugging)

用于批量生成Q-Chem计算X-ray的程序

📜 qchem_xray.py 详细使用说明

1. 脚本概述

2. 核心逻辑与工作流程

A. 配置文件 (input.ini)

B. 依赖关系 (GS -> 激发态)

C. 芯轨道自动检测 (缓存机制)

3. 计算类型与选项详解

`extract_orbital_composition.py` 程序使用说明

📜 `qchem_xray.py` 详细使用说明

A. 配置文件 (`input.ini`)

D. 步骤 3: 运行激发态计算 ( `FCH`, `FCH_R`, `LUMO`, `TD_XAS`, `TD_XES` )

A. `-r, --retry` (重试失败/跳过选项)

B. `-co ORBITALS, --core-orbital ORBITALS` (手动指定芯轨道)