Skip to content

README_CN.md

Latest commit

 

History

History
362 lines (273 loc) · 9.95 KB

README_CN.md

File metadata and controls

362 lines (273 loc) · 9.95 KB
Raw

AlMP 模型生成器 (AlMPModelGenerator)

一个用于生成和拟合电子激发态模型的综合工具包，专注于原子芯层离子群模型 (AIMP, Atom In Molecules Potential Model) 的构建。

项目概述

该项目用于计算和拟合晶体结构中特定原子位点周围的静电势，通过 Ewald 求和方法和有限半径截断势来进行精确的电势计算，最终生成适用于量子化学计算的原子电荷模型。

主要功能

1. Madelung 势计算 (calcmad)

  • 使用 Ewald 求和或直接求和方法计算晶体中任意位置的 Madelung 静电势
  • 支持三维 (3D) 和二维 (2D) 结构
  • 可自动优化 Ewald 参数以获得最佳收敛
  • 输出包括 Madelung 常数、晶胞能量等

2. 表面电荷拟合 (Potential Fitting)

  • 通过奇异值分解 (SVD) 进行线性最小二乘拟合
  • 拟合截断半径内 (rCut ~ rSurface) 的表面电荷
  • 目标：使有限势与精确势的差异最小化
  • 自动过滤接近原子位置的不合理候选点

3. 晶体结构处理

  • 支持 POSCAR 格式的结构文件 (VASP)
  • 支持 CIF 格式的结构文件
  • 自动计算原子邻域和对称性信息

4. 随机位点生成

  • 在晶胞内生成指定数量的随机采样点
  • 自动排除过于接近原子的采样点
  • 支持指定中心原子的邻近位点生成

5. 静电势评估

  • 计算精确的全晶体静电势 (通过 calcmad)
  • 计算有限半径截断的静电势
  • 对两者进行比较和分析

项目结构

AlMPModelGenerator-main/
├── src_calcmad/              # Fortran 代码（Madelung 势计算核心）
│   ├── calcmad               # 编译后的可执行文件
│   ├── calcmad.f90           # 主程序
│   ├── calcmadModule.f90      # 核心模块
│   ├── DirectMadModule.f90    # 直接求和方法
│   ├── EwaldModule.f90        # Ewald 求和方法
│   ├── structMod.f90          # 晶体结构定义
│   └── Makefile              # 编译脚本
│
├── fitting_ewald/             # Python 拟合模块
│   ├── __init__.py
│   ├── potential_fitting.py   # 电势拟合主类
│   ├── exact_potential.py     # 精确势计算
│   ├── finite_potential.py    # 有限势计算
│   ├── neighborTools.py       # 邻域计算工具
│   ├── genSites.py            # 随机点生成
│   ├── constant_calcmad.py    # 常数定义
│   ├── surface_plot.py        # 可视化工具
│   └── calcmad                # calcmad 可执行文件链接
│
├── 04YAG_Ce3+/               # 示例工作文件 (YAG:Ce³⁺)
│   ├── 01_3/                 # 示例 1
│   ├── 02_3_4/               # 示例 2
│   ├── 03_3_7/               # 示例 3
│   ├── ... 等其他示例
│   └── OPT/                  # 优化结果
│
├── SMS_Eu2+/                 # 待运行示例 (SrMg3SiN4:Eu²⁺)
│   ├── SrMg3SiN4.cif
│   └── SrMg3SiN4.vasp
│
└── README.md                  # 项目说明

安装与编译

前置要求

  • Python 3.6 及以上
  • Fortran 编译器 (gfortran 或 ifort)
  • ASE (Atomic Simulation Environment)
  • NumPy
  • 必要时：SLURM 集群环境

编译 Fortran 代码

cd src_calcmad
make clean
make
# 生成的 calcmad 可执行文件将被创建

安装 Python 依赖

pip install ase numpy

使用方法

基本工作流

该项目的典型工作流为：

  1. 准备晶体结构文件 (POSCAR 或 CIF)
  2. 创建输入配置文件 (input_file.yaml)
  3. 运行主程序进行电势拟合
  4. 分析输出结果

步骤 1：准备配置文件

在工作目录中创建 input_file.yaml：

# 输入文件示例
poscarfile: "YAG_Ce.vasp"      # 结构文件名
rCluster: 3                     # 中心簇半径 (Å)
rAIMP: 8                        # AIMP 半径 (Å)
rChgs: 18                       # 表面电荷半径 (Å)
rSurface: 19                    # 表面延伸半径 (Å)
cAtom: "Y"                      # 中心原子类型
cAtomIndex: 5                   # 第几个该类型原子 (从 1 开始)
num_sites: 1200                 # 拟合用采样点数

参数说明：

参数 说明 单位
poscarfile 结构文件路径 -
rCluster 中心簇原子的截断半径 Å
rAIMP AIMP 核心区域的半径 Å
rChgs 表面电荷所在球面内半径 Å
rSurface 外包围球的半径 Å
cAtom 中心原子的化学符号 -
cAtomIndex 指定哪个该元素原子作为中心 序号
num_sites 拟合时生成的采样点数 个

步骤 2：运行拟合程序

方式 A：本地运行

# 在包含 input_file.yaml 的目录中运行
python /path/to/main.py -i input_file.yaml

方式 B：SLURM 集群运行（推荐）

创建 job_submit.sh：

#!/bin/bash
#SBATCH -p queue_name           # 队列名
#SBATCH -o output.log           # 输出日志
#SBATCH -J job_name             # 任务名
#SBATCH -n 112                  # CPU 核心数

python /path/to/main.py -i input_file.yaml

提交任务：

sbatch job_submit.sh

步骤 3：查看结果

程序运行完成后，在工作目录生成以下结果文件：

  • rawChgs.xyz: 原始表面电荷坐标和数值
  • surfChgs.xyz: 拟合后的表面电荷坐标和数值
  • aimp.xyz: AIMP 模型中的所有原子和电荷
  • calcmad.in: 传递给 calcmad 的输入文件
  • calcmad.log: calcmad 计算结果日志

示例

示例 1：YAG:Ce³⁺ 系统

项目的 04YAG_Ce3+ 目录包含多个完整的计算示例：

cd 04YAG_Ce3+/01_3
python /path/to/main.py -i input_file.yaml

此示例将：

  • 读入 YAG:Ce³⁺ 晶体结构
  • 以第 5 个 Y 原子为中心
  • 计算并拟合表面电荷
  • 输出最终的 AIMP 模型

待运行示例：SMS:Eu²⁺

SMS_Eu2+ 目录包含 SrMg₃SiN₄:Eu²⁺ 的晶体结构文件，可作为新系统的模板：

cd SMS_Eu2+
# 根据需要准备 input_file.yaml
cp /path/to/template/input_file.yaml .
# 编辑配置文件以适应 SMS:Eu²⁺ 系统
vim input_file.yaml
# 运行拟合
python /path/to/main.py -i input_file.yaml

核心模块详解

fitting_ewald 模块

neighborTools.py

计算指定原子的邻近原子，支持：

  • 指定原子类型和序号定位中心原子
  • 任意截断半径的邻域计算
  • 内外双层定义

主要类：

neighbors(structFile, atom=0, rCut=10.0, cAtom=None, cAtomIndex=None, 
          rCore=-1.0, sort=False)

genSites.py

在晶胞内生成随机采样点：

  • 自动避开原子位置
  • 可指定中心原子周围生成
  • 返回分数坐标

主要函数：

gen_random_sites(poscarfile, num=100, deps=0.02, atom=None, 
                 cAtom=None, cAtomIndex=None)

exact_potential.py 和 finite_potential.py

计算精确和有限势：

  • exact_potential: 使用 calcmad 计算全晶体势
  • finite_potential: 计算截断半径内的势

potential_fitting.py

核心拟合类 PotentialFitOnlyCharges：

初始化：

from fitting_ewald.potential_fitting import PotentialFitOnlyCharges

fitter = PotentialFitOnlyCharges(
    poscarfile="YAG_Ce.vasp",
    atom=0,                    # 中心原子索引
    rCut=10,                   # 内层截断
    rSurface=12.0,            # 外层截断
    num_sites=500,            # 采样点数
    cAtom="Y",                # 中心原子类型
    cAtomIndex=5              # 第几个 Y 原子
)

运行拟合：

fitter.run_fit(sigma_threshold=1.0e-8)
surf_chgs = fitter.surf_chgs  # 拟合得到的表面电荷

calcmad Fortran 程序

Fortran 代码实现了 Ewald 求和和直接求和算法。

Ewald 方法特点：

  • 将长程库仑相互作用分解为实空间短程和倒数空间长程两部分
  • 自动优化高斯参数 (alpha) 以加快收敛
  • 收敛标准可由用户指定

形式电荷约定

程序预定义了各元素的形式电荷（见 exact_potential.py），部分列表：

元素 电荷 元素 电荷
Na, K, Rb, Cs +1 F, Cl, Br, I -1
Mg, Ca, Sr, Ba +2 O, S -2
Al +3 N -3
La, Ce, Y +3 Si +4
Cu, Ag +1 - -

若需处理其他元素，请编辑 exact_potential.py 中的 formal_charges 字典。

输出格式

rawChgs.xyz 和 surfChgs.xyz

XYZ 格式，可用 OVITO、VESTA 等工具可视化：

第一行: 原子数
第二行: 注释行
后续行: 原子符号  x坐标  y坐标  z坐标  [电荷值]

aimp.xyz

完整的 AIMP 模型，包含：

  • 中心原子及其邻域原子
  • 拟合得到的表面电荷位置

性能提示

  1. 采样点数 (num_sites)：

    • 通常设为表面电荷数的 2-4 倍
    • 过少会导致欠定，过多计算时间增加

  2. 截断半径选择：

    • rCut 应包含中心原子及邻近层
    • rSurface 通常大于 rChgs 的 1-2 Å

  3. 收敛标准 (sigma_threshold)：

    • 默认 1.0e-8，对应 SVD 奇异值过滤
    • 可根据需要调整精度-速度的平衡

故障排除

calcmad 找不到或运行失败

  • 检查 Fortran 代码是否成功编译
  • 确保 calcmad 路径在代码中正确指定
  • 检查输入文件 (calcmad.in) 格式是否正确

采样点不足错误

"The number of potential sites used for fitting must be larger than the number of charges!"

解决方案：

  • 增加 num_sites 参数
  • 或减小 rChgs 值减少表面电荷数

结果不合理

  • 检查形式电荷设置是否正确
  • 验证结构文件是否完整和无错误
  • 尝试调整截断半径 rCut 和 rSurface

引用

若使用本项目的代码或算法，请参考相关文献：

项目作者：Zhang Teng 维护者：Hao Jiangh

许可

[待补充]

更新日志

v1.0

  • 初始版本
  • 完整的 Ewald 求和实现
  • SVD 基础的电荷拟合

最后更新：2026年1月