Package `dcg_sci_tool`

dcg-sci-tool is a Python package that provides utility functions for scientific computing. It includes functions for summing numbers to a target value and extracting atom types from molecular data. This package is designed to be easy to use and integrate into various scientific workflows.

Sub-modules

dcg_sci_tool.applications
dcg_sci_tool.cli
dcg_sci_tool.csv
dcg_sci_tool.plot
dcg_sci_tool.reaction
dcg_sci_tool.structures_analysis
dcg_sci_tool.structures_modifying

Functions

def add_config_to_xyz(input_file, output_file, Config_type='')

在.extxyz格式文件的header中添加Config_type，可用于NepTrainKit中的结构点部分选中。输出的.xyz文件中，新Config_type属性的键值对已添加

Args

input_file : str: 输入的.xyz轨迹文件
output_file : str: 输出的.xyz轨迹文件
Config_type : str: 要添加的Config_type值

def append_key_value_pairs_to_extxyz(input_file: str, key_value_pairs: List[Tuple[str, str]], output_file: str) ‑> str

在.extxyz格式轨迹文件的每一帧注释行追加键值对

Args

input_file (str): 输入的.extxyz格式轨迹文件路径 key_value_pairs (List[Tuple[str, str]]): 要追加的键值对列表，每个元组格式为(键, 值) output_file (str, optional): 输出文件路径，如果为None则自动生成

Returns

output_file (str): 输出文件路径

def atoms2lmps_resultData(atoms: ase.atoms.Atoms, output_file: str = 'FS.data')

将ASE Atoms对象转化为lammps跑neb时的FS.data格式的文件

格式：第一行：原子数后续行：原子序号(从1开始) X Y Z坐标

Args

atoms : Atoms: 要处理的Atoms对象
output_file : str: 输出的.data文件名，默认值为FS.data

def auto_neb_refine(lammps_in_file: str, left_idx, right_idx, max_round_num=3)

自动NEB优化：如果初次neb优化结果中出现中间态，则自动以中间态为初末态，重新优化NEB 直至neb优化出的能量-坐标图为单峰，最多执行max_round_num轮

Args

lammps_in_file : str: LAMMPS输入文件地址
left_idx : int: 要截取的NEB最高峰左侧端点序号
right_idx : int: 要截取的NEB最高峰右侧端点序号
max_round_num : int: 循环迭代的最大轮数，默认值为3

Returns

tuple: 最终优化结果的信息

Ea (float): 最终优化结果的能垒

dH (float): 最终优化结果的焓变

dir (str): 最终优化结果所在的地址

isConverged (bool): 最终优化结果是否力收敛（F < 0.05）

def averaging_count_matches(list_src: List[Tuple[Any, ...]], list_target: List[Tuple[Any, ...]], index_a: int = 3, index_b: int = 4) ‑> List[Tuple[Any, ...]]

统计list_src中元组的指定元素在list_target中的出现次数，并计算其他元素的平均值

Args

list_src : List[Tuple[Any, …]]: 源元组列表
list_target : List[Tuple[Any, …]]: 目标元组列表
index_a : int: 要统计第一个元素的索引
index_b : int: 要统计第二个元素的索引

Returns

List[Tuple[Any, …]]: 更新后的list_target，每个元组末尾添加了计数和平均值

def collect_pattern_files(pattern: str, target_dir: str)

将当下目录及子目录下所有满足特定正则表达式的文件复制到创建的新文件夹中

Args

pattern : str: 正则表达式字符串
target_dir : str: 目标新文件夹

def color_atoms_in_trajectory(trajectory_file: str, rgb_color: list, atom_indices: list, output_file: str = None)

将指定原子序号列表中的原子染成指定的RGB颜色，并生成新的轨迹文件

Args

trajectory_file : str: 输入轨迹文件的路径 (xyz格式)
rgb_color : list: RGB颜色值列表，范围[0.0, 1.0]，如[1.0, 0.0, 0.0]表示红色
atom_indices : list: 要染色的原子序号列表
output_file : str: 输出文件路径。如果不指定，则在原文件名后添加"_colored"

Returns

output_file (str): 输出文件路径

def color_atoms_in_trajectory_multicolor(trajectory_file: str, atom_color_map: dict, output_file: str = None)

将轨迹中不同原子染成不同颜色

Args

trajectory_file : str: 输入轨迹文件的路径 (xyz格式)
atom_color_map : dict: 字典，键为原子序号，值为RGB颜色列表示例: {0: [1.0, 0.0, 0.0], 1: [0.0, 1.0, 0.0]}
output_file : str: 输出文件路径

Returns

output_file (str): 输出文件路径

def construct_CO2_formation_FS(input_file: str, atom_indices: list)

调整轨迹结构第一帧，使反应物的吸附态CO和吸附态O相向移动，生成吸附态CO2；具体： 1.确定距离吸附态CO的C和吸附态O连线中点最近的Pd或Au原子：middle_metal。 2.使反应物的吸附态CO和吸附态O相向移动，使C和吸附O距离缩短到1.25Å， 3.调整吸附态CO中O的位置，使吸附态CO的C-O键长恢复到1.25Å， 4.整体平移这三个原子，使C和middle_metal距离调整到2.0Å

Args

input_file : str: 输入结构文件
atom_indices : list: 两个原子序号的列表 [C_idx, O_ads_idx]

Returns

atoms (Atoms): 构造的末态结构

def construct_final_state(minimized_is_path, target_atom_list)

在自动截取MD轨迹的算能垒的自动化流程中，构建末态结构

Args

minimized_is_path : Path: 最小化后的结构文件路径
target_atom_list : list: 目标原子列表

Returns

tuple: 包含末态结构对象和文件路径的元组

atoms_fs (ASE atoms object): 末态结构对象 fs_path (Path): 末态结构文件路径

def create_categorical_heatmap(data_tuples, x_label_index, y_label_index, value_index, x_labels_order=None, y_labels_order=None, title='Categorical Heatmap', xlabel=None, ylabel=None, cmap='YlGn', cbarlabel='Value', figsize=(10, 8))

从元组列表创建分类热力图（支持指定标签顺序）使用方法：执行完此函数后，执行plt.show()命令，即可将图片展示出来

Args

data_tuples : list of tuples: 输入数据，每个元组包含：横轴标签、纵轴标签、数值
x_label_index : int: 元组中横轴标签的索引位置
y_label_index : int: 元组中纵轴标签的索引位置
value_index : int: 元组中数值的索引位置
x_labels_order : list, optional: 横轴标签的排列顺序
y_labels_order : list, optional: 纵轴标签的排列顺序
title : str, optional: 热力图的标题
xlabel : str, optional: 横轴标签
ylabel : str, optional: 纵轴标签
cmap : str, optional: 颜色映射
cbarlabel : str, optional: 颜色条标签
figsize : tuple, optional: 图形大小

Returns

tuple: 包含创建的图形、坐标轴对象和数据矩阵 fig (matplotlib.figure.Figure): 创建的图形 ax (matplotlib.axes.Axes): 坐标轴对象 data_matrix (numpy.ndarray): 热力图数据矩阵

def create_categorical_heatmap_advanced(data_tuples, x_label_index, y_label_index, value_index, x_labels_order=None, y_labels_order=None, title='Categorical Heatmap', cmap='YlGn', cbarlabel='Value', figsize=(12, 10), annotate=True, valfmt='{x:.2f}', threshold=None, textcolors=('black', 'white'), grid_visible=True)

增强版的分类热力图创建函数（支持指定标签顺序）使用方法：执行完此函数后，执行plt.show()命令，即可将图片展示出来

Args

data_tuples : list of tuples: 输入数据，每个元组包含：横轴标签、纵轴标签、数值
x_label_index : int: 元组中横轴标签的索引位置
y_label_index : int: 元组中纵轴标签的索引位置
value_index : int: 元组中数值的索引位置
x_labels_order : list: 横轴标签的排列顺序
y_labels_order : list: 纵轴标签的排列顺序
y_labels_order : list, optional: 纵轴标签的排列顺序
annotate : bool, optional: 是否在方格中添加数值标注
valfmt : str, optional: 数值格式化字符串
threshold : float, optional: 文本颜色切换的阈值
textcolors : tuple, optional: 用于阈值上下方的文本颜色
grid_visible : bool, optional: 是否显示网格线

def create_filtered_structure(data, type_names_order: List[str], keep_indexes_list: List[int], old_indexes: List[int]) ‑> ase.atoms.Atoms

根据保留的原子索引创建新的ASE结构，并找到旧索引对应的新索引

Args

data: OVITO数据对象
type_names_order : list: 原子类型顺序列表
keep_indexes_list : list: 需要保留的原子索引列表
old_indexes : list: 要获得新索引的原子在旧索引中的索引列表

Returns

new_atoms (ASE Atoms): 新的ASE原子对象

new_indexes (list): 旧索引old_indexes对应的新的原子索引列表

def create_workspace(dir_name, required_files=None)

创建工作目录并复制必要文件

Args

dir_name : str: 工作目录名称
required_files : list, optional: 必要文件列表。默认值为空列表。

def csv2xyz(input_file: str, x_col: int, y_col: int, z_col: int, color_col: int, vmin=None, vmax=None, max_color=None)

将.csv文件中指定列的数据绘制成三维散点图，并将结果保存为plot.xyz文件

Args

input_file: 输入的CSV文件路径
x_col: 用于x坐标的列索引
y_col: 用于y坐标的列索引
z_col: 用于z坐标的列索引
color_col: 用于颜色映射的数值列索引
vmin: 可选的最小值，用于归一化。如果为None，将使用输入数组的最小值。
vmax: 可选的最大值，用于归一化。如果为None，将使用输入数组的最大值。
max_color: 可选的最大颜色值，用于超出范围时的颜色，如果为None，将使用黄色

def csv_to_tuples(csv_file: str, has_header: bool = True) ‑> list

将CSV文件转换为元组列表

Args

csv_file : str: CSV文件路径
has_header : bool: 是否包含表头

Returns

list: 元组列表

def detect_CO_CO2_molecules(data, type_names_order)

识别输入帧中的CO和CO2分子，返回输入帧中CO和CO2分子的数量，以及构成CO和CO2分子的原子序号列表。考虑了周期性边界条件。

Args

data : DataCollection: 结构的ovito数据集合
type_names_order : list: 原子类型名称列表，索引对应原子类型编号

Returns

tuple

CO和CO2分子信息

CO_amount (int): CO分子数量

CO2_amount (int): CO2分子数量

CO_atoms_indexes (list): CO分子中所有原子的序号列表

CO2_atoms_indexes (list): CO2分子中所有原子的序号列表

co_molecules (list): CO分子列表，每个元素是一个元组，包含C原子序号和O原子序号

co2_molecules (list): CO2分子列表，每个元素是一个元组，包含C原子序号和两个O原子序号

def detect_CO_coordinating_to_PdAu(data, type_names_order, co_molecules, c_pd_cutoff=2.5, o_pd_cutoff=2.5, c_au_cutoff=2.5, o_au_cutoff=2.5)

识别输入帧与PdAu配位的CO分子，返回与Pd配位的CO数量、总CO分子数，与Pd配位的CO分子详情列表。考虑了周期性边界条件。

Args

data : DataCollection: 结构的ovito数据集合
type_names_order : list: 原子类型名称列表，索引对应原子类型编号
co_molecules : list: 所有CO分子列表（包含气态），每个元素是一个元组，包含C原子序号和O原子序号
cpd_cutoff : float: C原子与Pd配位的距离阈值，单位为Å，默认为2.5 Å
opd_cutoff : float: O原子与Pd配位的距离阈值，单位为Å，默认为2.5 Å
cau_cutoff : float: C原子与Au配位的距离阈值，单位为Å，默认为2.5 Å
oau_cutoff : float: O原子与Au配位的距离阈值，单位为Å，默认为2.5 Å

Returns

tuple

CO分子信息

co_pd_count (int): 与Pd配位的CO分子数量

total_co (int): 总CO分子数量

co_pd_details (list): 与Pd配位的CO分子详情列表，每个元素是一个字典，包含'co'键（CO分子的原子序号元组）、'c_pd_neighbors'键（C原子与Pd配位的邻居列表）、 'o_pd_neighbors'键（O原子与Pd配位的邻居列表）

def detect_O2_coordinating_to_PdAu(data, type_names_order, o2_molecules, o_pd_cutoff=2.5, o_au_cutoff=2.5)

识别输入帧中与Pd或Au配位的O2分子，返回与Pd/Au配位的O2数量、总O2分子数，以及与Pd/Au配位的O2分子详情列表。考虑了周期性边界条件。

Args

data : DataCollection: 结构的ovito数据集合
type_names_order : list: 原子类型名称列表，索引对应原子类型编号
o2_molecules : list: 所有O2分子列表，每个元素是一个元组，包含第一个O原子序号和第二个O原子序号 (例如：[(o1_index1, o2_index1), (o1_index2, o2_index2), …])
o_pd_cutoff : float: O原子与Pd配位的距离阈值，单位为Å，默认为2.5 Å
o_au_cutoff : float: O原子与Au配位的距离阈值，单位为Å，默认为2.5 Å

Returns

tuple

O2分子信息 o2_pdau_count (int): 与Pd或Au配位的O2分子数量

total_o2 (int): 总O2分子数量

o2_pdau_details (list): 与Pd或Au配位的O2分子详情列表，每个元素是一个字典，包含以下键： - 'o2' (tuple): O2分子的原子序号元组 (o1_index, o2_index) - 'o1_pd_neighbors' (list): 第一个O原子与Pd配位的邻居列表 - 'o1_au_neighbors' (list): 第一个O原子与Au配位的邻居列表 - 'o2_pd_neighbors' (list): 第二个O原子与Pd配位的邻居列表 - 'o2_au_neighbors' (list): 第二个O原子与Au配位的邻居列表

def detect_O2_molecules(data, type_names_order)

识别输入帧的O2分子，输出输入帧中O2分子数量、O2的O原子序号列表、O2分子列表。考虑了周期性边界条件。

Args

data : DataCollection: 结构的ovito数据集合
type_names_order : list: 原子类型名称列表，索引对应原子类型编号

Returns

tuple

O2分子信息

O2_amount (int): O2分子数量

O2_indexes (list): O2分子中O原子的序号列表

o2_molecules (list): O2分子列表，每个元素是一个元组，包含两个O原子的序号

def detect_gas_molecules_for_deletion(data, type_names_order)

识别需要删除的气态分子：所有CO2，气态O2（即未与Pd/Au配位的O2），气态CO（即未与Pd配位的CO，包括C/O配位）。返回需要删除的气态分子原子索引列表。

Args

data : DataCollection: 结构的ovito数据集合
type_names_order : list: 原子类型名称列表，索引对应原子类型编号

Returns

gas_atoms_to_delete (list): 需要删除的气态分子原子索引列表

def detect_nearby_ads_for_deletion(data, type_names_order, c_idx, o_idx, cutoff=6.0)

找到距离反应物CO的C和反应物O连线中点一定距离内吸附态的原子序号，用于后续删除，分析没有第三方吸附物时的能垒

Args

data : Ovito DataCollection

type_names_order : list: 元素顺序列表
c_idx : int: 反应物CO中C原子序号
o_idx : int: 反应物O原子的序号
cutoff : float: 半径范围，默认6 Angstrom

def detect_single_adsorbed_O(data, type_names_order)

识别输入帧中单个吸附O原子（没有与C/O成键，与Pd/Au成键的O原子）返回与Pd配位的单个吸附O原子数量、单个吸附O原子序号列表。

Args

data : DataCollection: 结构的ovito数据集合
type_names_order : list: 原子类型名称列表，索引对应原子类型编号

Returns

tuple

单个吸附的O原子信息

single_O_count (int): 与Pd/Au配位的单个吸附O原子数量

single_O_indices (list): 与Pd/Au配位的单个吸附O原子序号列表

def extract_atom_types(trajectory_file: str) ‑> List[str]

获取.xyz文件第一帧原子类型的列表（保持原始顺序）。

Args

trajectory_file : str: 输入的xyz轨迹文件路径

Returns

element_list (list): 第一个构型中所有原子类型的列表，保持原始顺序

def fast_extract_frames(input_file, output_file, start_frame=0, end_frame=None)

提取.xyz轨迹文件中指定帧区间的轨迹到新文件

Args

input_file : str: 输入轨迹文件路径
output_file : str: 输出轨迹文件路径
start_frame : int: 起始帧索引（从0开始）
end_frame : int: 结束帧索引（包含），None表示到文件末尾

def find_and_preprocess_input()

在自动截取MD轨迹的算能垒的自动化流程中，查找并预处理输入文件

Returns

cleaned_atoms (ase.Atoms): 清理气体分子后的原子结构 target_atom_list (list): 目标原子列表 md_snapshot_file (str): MD 快照文件路径 co2_indexes (list): 生成的CO2 次序索引列表（非原子序号）

def find_and_preprocess_input_no_ads()

对于计算没有其他吸附物存在时，在自动截取MD轨迹的算能垒的自动化流程中，查找并预处理输入文件包括查找neb优化轨迹文件，删除反应中心附近一定范围内的吸附物，保存清理后的结构轨迹文件，获取CO2生成的序号

Returns

tuple:
no_pre_ads_atoms: 清理反应中心附近吸附物后的结构原子对象
target_atom_list: 目标原子列表
neb_traj_file: neb 优化轨迹文件路径
co2_indexes: CO2生成的序号列表

def find_cluster_surface_hollow_sites(data: ovito.data.DataCollection, type_names_order: list, max_triangle_side: float = 4.0, cutoff: float = 3.5, CN_threshold: int = 12) ‑> list

输出PdAu团簇表面构成Hollow位点的三原子对，每个三原子对由三个原子索引组成，且满足三原子之间的边长不超过max_triangle_side。默认处理对象为致密、严格对称的结构（如代码生成的PdAu标准正二十面体团簇），对于MD或者MD帧优化得到的结构，建议调整cutoff和CN_threshold参数以适用更广泛的情况。

Args

data : DataCollection: OVITO 数据对象，包含原子结构信息
type_names_order : list: 原子类型名称顺序列表，索引对应原子类型编号
max_triangle_side : float: 构成Hollow位点的三原子之间的最大边长，单位为 Å（默认 4.0 Å）
cutoff : float: 配位数计算的截断距离，单位为 Å（默认 3.5 Å，适用于致密、严格对称的结构）
CN_threshold : int: 体相配位数阈值，用于判断原子是否位于表面（默认 12）

Returns

hollowSites (list): 位于 PdAu 簇表面的Hollow位点三原子索引列表，每个元素为一个包含三个原子索引的元组

def find_elements_exclusively_frames(filename: str, allowed_elements={'C', 'Pd', 'O'})

找出.xyz轨迹中只含指定元素的帧

Args

filename : str: XYZ文件路径
allowed_elements : set: 允许的元素集合，默认为{'Pd', 'O', 'C'}

Returns

target_frames (list): 只含指定元素的帧索引列表

def find_matching_files(directory: str, pattern: str = None) ‑> List[str]

查找目录下所有满足模式的文件名（不支持shell通配符，只支持正则表达式）注意：正则表达式（regex）与shell的通配符（wildcard）语法完全不同！

Args

directory : str: 要搜索的目录路径
pattern : str: 正则表达式

Returns

matching_files (List[str]): 匹配的文件名列表

def find_nearest_hollow_site(data: ovito.data.DataCollection, type_names_order: list, c_index: int, o_index: int) ‑> pyparsing.core.Dict

找到距离C-O中点最近的hollow位点

Args

data : DataCollection: 结构的ovito数据集合
type_names_order : list: 原子类型名称列表，索引对应原子类型编号
c_index : int: 目标C原子索引
o_index : int: 目标O原子索引

Returns

tuple: nearest_hollow_indexes (list): 最近的Hollow位点对应的金属原子序号列表（长度为3）

nearby_hollow_sites_count (int): C-O中点附近合理的Hollow位点数量

def float_to_viridis_rgb(float_array: List[float] | numpy.ndarray, vmin: float | None = None, vmax: float | None = None, max_color: Tuple[float, float, float] | None = None) ‑> List[Tuple[int, int, int]]

将浮点数数组映射到Viridis色阶的RGB颜色列表，使用接近matplotlib Viridis的色阶

Args

float_array: 输入的浮点数数组，可以是列表或numpy数组
vmin: 可选的最小值，用于归一化。如果为None，将使用输入数组的最小值。
vmax: 可选的最大值，用于归一化。如果为None，将使用输入数组的最大值。
max_color: 可选的最大颜色值，用于超出范围时的颜色。如果为None，将使用黄色。

def getEachfromXYZ(input_file: str)

从XYZ文件中提取每个帧的结构数据，并生成可用来跑each模式的neb的对应的data文件

Args

input_file : str: 输入文件路径，包含XYZ格式的轨迹数据

def get_Ea_dH_from_file(filename='neb_mep.dat')

通过读取neb_mep.dat文件，获取能垒和焓变数值

Args

filename : str: neb_mep.dat文件地址，默认值为"neb_mep.dat"

Returns

tuple

能垒和焓变元组

Ea: 能垒数值

dH: 焓变数值

def get_OC_bonded_metal_atoms(data: ovito.data.DataCollection, type_names_order: list, c_index: int, o_index: int) ‑> List[int]

获取与目标C和目标O原子成键的金属原子序号列表

Args

data : DataCollection: 结构的ovito数据集合
type_names_order : list: 原子类型名称列表，索引对应原子类型编号
c_index : int: 目标C原子索引
o_index : int: 目标O原子索引

Returns

bonded_metal_atoms (list): 与C和O原子成键的金属原子索引列表

def get_atoms_near_point(data: ovito.data.DataCollection, point: numpy.ndarray, cutoff: float = 5.0)

获取距离指定点cutoff范围内的所有原子序号

Args

data : DataCollection: 结构的ovito数据集合
point : np.ndarray: 指定点坐标
cutoff : float: 截断距离（默认5Å）

Returns

atoms_within_cutoff (list): 在截断距离内的原子序号列表

def get_atoms_with_specific_color(xyz_file: str, target_color=[0.0, 1.0, 1.0])

从.xyz文件中找到color属性为特定值的原子序号

Args

xyz_file : str: 输入的.xyz文件路径
target_color : list: 目标颜色值，默认[0.0, 1.0, 1.0]

Returns

list: 颜色为target_color的原子序号列表

def get_detailed_MD_traj(frame_index_in_4w: int, atom_indexes: list)

从MD轨迹文件中提取详细信息，包括指定原子的轨迹文件, 并生成指定原子上色后的轨迹文件

Args

frame_index_in_4w : int: 在合并的dump_locate.xyz轨迹中的帧索引，在0-39999之间
atom_indexes : list: 要上色的原子索引列表

def get_hollowSite_Au_Disperation(data: ovito.data.DataCollection, type_names_order: List[str], hollowSite_atom_indexes: List[int]) ‑> Tuple[float, Dict]

计算Hollow位点表层外圈Au原子的分散度

Args

data: OVITO 数据对象
type_names_order : list of str: 原子类型名称顺序列表
hollowSite_atom_indexes : list of int: Hollow位点三个原子的索引列表

Returns

disperation_value (float): 分散度

def get_hollowSite_outer_neighbors_with_subsurface(data: ovito.data.DataCollection, type_names_order: list, hollow_site_atom_indexes: list) ‑> List[int]

获取hollow位点外围邻居原子，包括次表层原子。

Args

data : DataCollection: 结构的ovito数据集合
type_names_order : list: 原子类型名称列表，索引对应原子类型编号
hollow_site_atom_indexes : list: hollow位点原子索引列表

Returns

surface_neighbors (list): hollow位点外围表面邻居原子索引列表

def get_hollowSite_outer_surface_neighbors(data: ovito.data.DataCollection, type_names_order: list, hollow_site_atom_indexes: list) ‑> List[int]

获取hollow位点外围表面邻居原子

Args

data : DataCollection: 结构的ovito数据集合
type_names_order : list: 原子类型名称列表，索引对应原子类型编号
hollow_site_atom_indexes : list: hollow位点原git 子索引列表

Returns

surface_neighbors (list): hollow位点外围表面邻居原子索引列表

def get_indexes_symbols(input_file, indexes)

获取指定索引的原子符号列表

Args

input_file : str: 输入文件路径
indexes : list: 原子索引列表

Returns

symbols (list): 原子符号列表

def get_local_minima_sides_of_peak(mep_data_file='neb_mep.dat', neb_traj_file='result.xyz')

读取跑lmps-neb获得的MEP文件，找到处于能量峰值两侧的局部最小值对应的序号，如果没有，则输出端点序号（0或最大序号），并根据序号和优化后的neb轨迹，输出相应的.xyz文件:mid_IS.xyz和mid_FS.xyz。

Args

mep_data_file : str: MEP文件数据文件名（默认"neb_mep.dat"）
neb_traj_file : str: 优化后的neb轨迹文件名（默认"result.xyz"）

Returns

tuple: 是否找到中间态以及峰值左右两侧的局部最低点或端点的序号

found_local_minima (bool): 是否找到中间态

result_indices[0] (int)：左侧构象序号

result_indices[1] (int)：右侧构象序号

def get_pd3_hollow_sites(input_file, max_triangle_side=4.0, cutoff=3.5, CN_threshold=12)

从输入结构中提取Pd原子组成的表面Hollow位点。默认处理对象为致密、严格对称的结构（如代码生成的PdAu标准正二十面体团簇），对于MD或者MD帧优化得到的结构，建议调整cutoff和CN_threshold参数以适用更广泛的情况。

Args

input_file: 输入结构文件路径 (支持.xyz, .data, .dump等格式)
max_triangle_side: Hollow位点三角形最大边长(Å)，默认4.0
cutoff: 配位数计算截断距离(Å)，默认3.5
CN_threshold: 体相配位数阈值，默认12

Returns

list: 包含Hollow位点信息的列表，每个元素是包含三个Pd原子序号的元组

def get_pdau_cluster_center(data: ovito.data.DataCollection, type_names_order: list)

基于 OVITO 数据对象和原子类型顺序计算 PdAu 簇的几何中心坐标。

Args

data : DataCollection: OVITO 数据对象，包含原子结构信息
type_names_order : list: 原子类型名称顺序列表

Returns

np.ndarray: PdAu 簇的几何中心坐标，形状为 (3,)

Raises

ValueError: 如果未找到 Pd 或 Au 原子

def get_pdau_surface_atoms(data, type_names_order, cutoff=4.0, CN_threshold=12)

获取位于 PdAu 簇表面的原子索引列表，基于配位数。

对于致密、严格对称的结构（如代码生成的PdAu标准正二十面体团簇）：

cutoff = 3.5, CN_threshold = 12

对于MD或者MD帧优化得到的结构：

cutoff = 4.0, CN_thershold = 12

Args

data : DataCollection: OVITO 数据对象，包含原子结构信息
type_names_order : list: 原子类型名称顺序列表
cutoff : float: 配位数计算的截断距离，单位为 Å（默认 4.0 Å，可取范围内尽量取大，增大适用范围）
CN_thershold : int: 体相配位数阈值，用于判断原子是否位于表面（默认 12）

Returns

surface_atoms (list): 位于 PdAu 簇表面的原子索引列表

def get_reactants_ad_config(input_file, c_index, o_index, c_pd_cutoff=2.5, o_pd_cutoff=2.5, c_au_cutoff=2.5, o_au_cutoff=2.5)

Get the adsorption configuration of reactant atoms.

Args

input_file : str: Path to the input file containing the structure and related data
c_index : int: Index of the C atom in the reactant CO molecule
o_index : int: Index of the O atom in the reactant CO molecule
c_pd_cutoff : float: Cutoff distance for C atom coordination with Pd, default is 2.5 Å
o_pd_cutoff : float: Cutoff distance for O atom coordination with Pd, default is 2.5 Å
c_au_cutoff : float: Cutoff distance for C atom coordination with Au, default is 2.5 Å
o_au_cutoff : float: Cutoff distance for O atom coordination with Au, default is 2.5 Å

Returns

tuple

Adsorption configuration information

c_pdau_info (str): Adsorption configuration information for the C atom, including element type and geometry

o_pdau_info (str): Adsorption configuration information for the O atom, including element type and geometry

def get_reaction_local_atoms_list(data, type_names_order, c_index, o_index, cutoff=6.0)

获取反应局部结构：以目标C和O原子连线中点为中心，cutoff范围内的所有原子（排除气态分子原子），并且如果吸附态CO分子有一个原子在范围内，则添加另一个原子。返回满足条件的原子索引列表。

Args

data : DataCollection: 结构的ovito数据集合
type_names_order : list: 原子类型名称列表，索引对应原子类型编号
c_index : int: 目标C原子索引
o_index : int: 目标O原子索引
cutoff : float: 以C-O连线中点为中心的范围，单位为Å，默认为6.0 Å

Returns

final_atom_list (list): 满足条件的原子索引列表

def get_reaction_site_infos(input_file)

获取反应中心的结构信息

Args

input_file : Path: 输入文件路径

Returns

tuple: 包含反应中心结构信息的元组

N_hollow_sites (int): 反应中心的原子数

N_hollow_sites_Au_atoms (int): 反应中心的Au原子数

N_surface_neighbors (int): 反应中心外圈的表面原子数

N_surface_Au_neighbors (int): 反应中心外圈的表面Au原子数

N_subsurface_neighbors (int): 反应中心的次表面原子数

N_subsurface_Au_neighbors (int): 反应中心的次表面Au原子数

Au_Disperation (float): 反应中心外圈表层Au原子的分散度

Ea (float): 能垒

def get_struct_focusing_reaction_site(data, type_names_order, c_index, o_index, cutoff=6.0, target_vector=None, new_cell=None)

输入原始MD-neb结构文件，输出经过处理后的结构文件，将反应局部结构聚焦到小晶胞中，并使ovito观察视线方向（Y轴）经过反应区域和团簇中心输出聚焦后的结构文件（ASE ATOMS类）

参数:

data : ovito.data.DataCollection 包含原子结构和相关数据的Ovito DataCollection对象 type_names_order : list of str 原子类型名称的顺序列表 c_index : int 反应物CO的C原子的索引 o_index : int 反应物O原子的索引 cutoff : float 截止距离，单位为Å，默认为6.0 target_vector : np.ndarray 或 list/tuple 目标向量，形状为(3,)，旋转后当前向量将与此向量同向 new_cell : np.ndarray 或 list/tuple 新的晶胞尺寸，形状为(3,)，如 [a, b, c]

返回旋转并平移后的ASE Atoms对象 rotated_translated_struct : Atoms 旋转并平移后的ASE Atoms对象

def get_target_atoms_from_MD(input_file: str)

根据MD中截取的反应初态，找到兰色的原子序号，并输出要耦合的C和O原子的序号

Args

input_file : str: MD中截取反应的轨迹地址

Returns

target_atoms (list): 目标原子（要耦合的C和O原子）的序号列表

def get_target_atoms_from_file(filename='python.log')

通过读取python.log日志文件中获得目标原子列表

Args

filename : str: 日志文件名，默认 "python.log"

Returns

atom_list (list): 包含所有提取到的原子列表的列表

def get_traj_focusing_reaction_site(traj_file, c_index, o_index, cutoff=8.0, target_vector=None, new_cell=None)

参数:

traj_file : str 原始MD-neb结构文件路径 c_index : int 反应物CO的C原子的索引 o_index : int 反应物O原子的索引 cutoff : float 截止距离，单位为Å，默认为8.0 target_vector : np.ndarray 或 list/tuple 目标向量，形状为(3,)，旋转后当前向量将与此向量同向 new_cell : np.ndarray 或 list/tuple 新的晶胞尺寸，形状为(3,)，如 [a, b, c]

返回旋转并平移后的neb轨迹对象 focused_traj : list of Atoms 旋转并平移后的ASE Atoms对象列表 new_indexes : list 旋转并平移后的结构中，原始索引old_indexes对应的新的原子索引列表

def get_traj_focusing_reaction_site_batches(cutoff=8.0, target_vector=None, new_cell=[20, 20, 20])

批量处理当前目录下所有满足特定正则表达式的文件，调用get_traj_focusing_reaction_site函数进行处理，并将结果保存为新的文件。

Args

cutoff : float: 截止距离，单位为Å，默认为8.0

target_vector (np.ndarray 或 list/tuple): 目标向量，形状为(3,)，旋转后当前向量将与此向量同向

new_cell (np.ndarray 或 list/tuple): 新的晶胞尺寸，形状为(3,)，如 [a, b, c]

def get_unique_values_csv(csv_file, column_input, has_header=True)

使用csv模块获取CSV文件中指定列的唯一值列表

Args

csv_file : str: CSV文件路径
column_input : str or int: 列标识，可以是列名（字符串）或列索引（从0开始的整数）
has_header : bool: 是否有表头，默认True

def get_xyz_prop_columns(input_file: str, property: str)

获取.extxyz格式文件中某一个属性对应于原子数据的列号

Args

input_file : str: 输入的.xyz文件

propertyc(str): 要查找的属性名称

Returns

target_column_indexes (list): 目标属性对应的原子数据列号所在的列表

def indexes2expression(indexes_list)

打印将原子索引列表转换为ExpressionSelectionModifier的表达式字符串。

def label_barrier_batches()

给所有的.xyz格式的neb轨迹文件添加上能垒注释

def manual_name_xyz_png_at_nebdir()

将neb目录下的neb_graph.png和result.xyz重命名，使包含CO2序号、能垒、焓变、目标原子序号的信息

def mark_special_points(point_list=None)

在散点图上添加特定点并标注

Args

point_list : list: 包含点坐标和标签的字典列表，格式为 [{'coords': (x, y), 'label': '点标签'}, …]

def merge_xyz(file_list, output_file='merged.xyz')

合并多个xyz轨迹文件

def mpirun_lammps(np=None, exec_path=None, input_file='in.lammps_neb', partition=None)

通过python调用mpi命令，并行执行lammps

注意：

需要事先在LSF环境中通过export命令设置环境变量NP（并行核数）和LAMMPS_EXEC（Lammps可执行文件地址）

在LSF中运行: python -u run_lmps.py > out.log 2>&1，保证python执行结果能够实时输出

Args

np : int: 并行调用的CPU数量（默认环境变量中NP的值）
exec_path : str: lammps可执行文件的路径（默认环境变量中LAMMPS_EXEC的值）
input_file : str: lammps的in文件名
partition : str: lammps的-partition选项的参数

def neb_get_traj()

对NEB轨迹文件进行后处理

功能： 1. 查找所有dump.neb.*.lmpstrj轨迹文件 2. 按编号排序 3. 提取每个轨迹的首尾结构 4. 分别保存为check.xyz和result.xyz文件

def neb_post_process()

对NEB轨迹文件进行后处理

功能： 1. 生成初始插值轨迹和结束插值轨迹：check.xyz和result.xyz 2. 绘制势能变化图：neb_graph.png

def onekey_run_neb_normal(mode='ads', mpi_partition='40x1', neb_max_refine_rounds=3)

对于ads模式：提取单个MD反应快照（反应物原子需要染成兰色），计算neb过程的能垒，包括气体分子删除、初态优化、末态构建、NEB计算过程对于no_ads模式：或者根据已经优化好的有吸附物的neb轨迹，计算无吸附物的neb过程。包括反应位点附近吸附态原子删除、初态优化、末态构建、NEB 计过程。

Args

mode : str: 计算模式，"ads"或"no_ads"
mpi_partition : str: 跑lammps的neb环境配置参数
neb_max_refine_rounds : int: neb单峰优化过程最大迭代轮数

def onekey_run_neb_zbl(mode='ads', mpi_partition='40x1', neb_max_refine_rounds=3)

对于ads模式：提取单个MD反应快照（反应物原子需要染成兰色），计算neb过程的能垒，包括气体分子删除、初态优化、末态构建、NEB_zbl 计算、EACH NEB 计算过程对于no_ads模式：或者根据已经优化好的有吸附物的neb轨迹，计算无吸附物的neb过程。包括反应位点附近吸附态原子删除、初态优化、末态构建、NEB_zbl 计算、EACH NEB 计算过程。

Args

mode : str: 计算模式，"ads"或"no_ads"，前者意思是包含吸附物，后者意思是不包含吸附物计算。默认是"ads"。
mpi_partition : str: 跑lammps的neb环境配置参数
neb_max_refine_rounds : int: neb单峰优化过程最大迭代轮数，默认是3。

def ovito2atoms(data, type_names_order)

从 OVITO 的 data 对象创建 ASE Atoms 对象

Args

data: OVITO 的 DataCollection 对象
type_names_order: 类型名称列表，索引对应 particle_type

Returns

ase_atoms: ASE 的 Atoms 对象

def parse_nebTraj_file_name(file_name)

解析NEB轨迹文件名，提取Ea、dE、C_idx和O_idx信息

Args

file_name : str: NEB轨迹文件名，格式为"反应前CO2数-反应后CO2数_Ea_dE_Cidx_Oidx.xyz"

Returns

tuple

neb过程信息

co2_indexes (list): 生成的CO2的序号列表

Ea (float): 能垒

dE (float): 焓变

C_idx (int): 参与反应的CO的C原子索引

O_idx (int): 参与反应的氧原子索引

def place_co_on_hollow_site(cluster_file, hollow_atom_indices)

在PdAu团簇的hollow位点上放置CO分子

Args

cluster_file : str: PdAu团簇结构文件路径
hollow_atom_indices : list: 构成hollow位点的三个原子序号列表 [atom1, atom2, atom3]

def plot_basic_graph(src_file: str = 'neb_mep.dat', x_col: int = 0, y_cols: int | List[int] = 3, legend_loc='upper right', mode: str = 'line', x_label: str = 'Indexes', y_label: str = 'Potential Energy (eV)', output_file: str | None = None, colors: List[str] | None = None, labels: List[str] | None = None, title: str | None = None, config: Dict[str, Any] | None = None) ‑> matplotlib.figure.Figure

绘制基础折线图或散点图

注意： - 目前不支持图中的中文字符，请统一使用国际标准的英文 - 该函数只做前期基础配置，不输出图片，需要额外调用 plt.savefig() 输出图片 - 此设计方便在此基础上调用 plt 命令进行再加工

Parameters

src_file : str, optional

源数据文件路径，文件内容为多列数据，默认 'neb_mep.dat'

x_col : int, optional

X轴数据列索引，默认 0

y_cols : Union[int, List[int]], optional

Y轴数据列索引（单个整数或整数列表），默认 3

legend_loc : str, optional

图例的位置，'upper right' 右上角，'upper left' 左上角，

'lower right' 右下角，'lower left' 左下角。

默认 'upper right'，

mode : str, optional

绘图模式，'line' 为折线图，'scatter' 为散点图，默认 'line'

x_label : str, optional

X轴标签，默认 'Indexes'

y_label : str, optional

Y轴标签，默认 'Potential Energy (eV)'

output_file : Optional[str], optional

输出文件路径，如果为None则不自动保存

colors : Optional[List[str]], optional

颜色列表，如果为None则使用默认颜色

labels : Optional[List[str]], optional

图例标签列表，如果为None则自动生成

title : Optional[str], optional

图表标题

config : Optional[Dict[str, Any]], optional

自定义配置字典，覆盖默认配置

Returns

plt.Figure: 创建的matplotlib图形对象

Raises

FileNotFoundError: 当指定的源文件不存在时
ValueError: 当参数值不合法时
IndexError: 当指定的列索引超出数据范围时

Examples

>>> # 绘制单条折线
>>> fig = plot_basic_line_chart('data.dat', x_col=0, y_cols=1)
>>> plt.savefig('output.png', dpi=300, bbox_inches='tight')
>>> plt.show()

>>> # 绘制多条散点图
>>> fig = plot_basic_line_chart('data.dat', 
...                             x_col=0, 
...                             y_cols=[1, 2, 3],
...                             mode='scatter',
...                             labels=['Series A', 'Series B', 'Series C'])
>>> plt.savefig('scatter_plot.png', dpi=300)
>>> plt.close(fig)

def plot_neb_graph(src_file='neb_mep.dat', output_file='neb_graph.png')

绘制MEP能量曲线图，返回能垒、焓变和是否收敛的元组

def plot_scatter_color(input_csv_file: str, max_threshold=None, min_threshold=None, special_point_list=None, x_label: str = 'PCA 1', y_label: str = 'PCA 2', colorbar_label: str = 'Energy (eV/atom)')

绘制带颜色映射的散点图，可自定义阈值范围，高于或低于阈值的点将使用统一颜色。采用viridis（翠绿色）颜色映射方案，适合色盲友好型视觉效果。入参文件格式要求：CSV文件，前两列为点的X Y坐标，第三列为用于颜色映射的Z值。

Args

input_csv_file: 输入CSV文件路径，文件前两列是点的X Y坐标，第三列是用于颜色映射的Z值
max_threshold: 最大阈值，可选，默认为Z数据的最大值，如果不设，则没有色阶最大值截断
min_threshold: 最小阈值，可选，默认为Z数据的最小值，如果不设，则没有色阶最小值截断
special_point_list: 可选，包含特定点坐标和标签的字典列表，格式为 [{'coords': (x, y), 'label': '点标签'}, …]
x_label: X轴标签
y_label: Y轴标签
colorbar_label: Colorbar标签

示例用法：

调用函数 plot_scatter_color( input_csv_file='111.csv', max_threshold=-2, min_threshold=-6, x_label='PCA 1', y_label='PCA 2', colorbar_label='Energy (eV/atom)' )

def pre_del_ads(input_file: str, c_idx, o_idx, cutoff=6.0)

将优化后的反应中心附近有其他吸附物的neb轨迹文件第一帧结构中，距离目标C和O连线中点 cutoff距离内的其他C和O原子删去，如果某个半径范围内的原子是吸附态气体分子的一部分，则整个分子会被删去，输出新的Atoms对象以及目标C和O原子的新的原子索引

Args

input_file : str: 要处理的轨迹文件地址
c_idx : int: 反应物CO中C原子序号
o_idx : int: 反应物O原子的序号
cutoff : float: 半径范围，默认6 Angstrom

Returns

tuple

处理后的结果

filtered_atoms (Atoms): 处理后的Atoms对象

tranfered_indexes (list): 转化后的目标C和O原子索引列表[c_idx, o_idx]

def pre_del_gases(input_file: str, old_indexes_to_transfer: list)

将轨迹文件第一帧结构中，PdAu团簇上游离的气态分子删去，输出新的Atoms对象以及新的原子索引

Args

input_file : str: 要处理的轨迹文件地址
old_indexes_to_transfer : list: 要获得新索引列表的旧索引的列表

Returns

tuple

处理后的结果

filtered_atoms (Atoms): 处理后的Atoms对象

tranfered_indexes (list): 转化后的原子索引列表

def resultData2extxyz(input_file: str, output_file='structure.xyz')

将lammps的.data格式的文件转化为.extxyz格式的文件，同时保持原子排列顺序不变

注意：

只能处理含有元素信息的result.data文件，无法处理不含元素信息的ini.data。

元素原子量无须严格和代码内置的原子量-元素符号列表中对应原子量匹配，脚本会寻找最接近原子量的元素

Args

input_file : str: 要处理的lammps的data文件的地址
output_file : str: 转化后的.xyz文件名称（默认：structure.xyz）

def rotate_v1_around_p_to_v2(atoms, rotation_center, vector_endpoint, target_vector)

旋转结构中的所有原子，使从旋转中心到指定终点的向量与目标向量同向，这个函数会改变入参atoms的状态

Args

atoms : Atoms: 包含原子结构的ASE Atoms对象

rotation_center (np.ndarray 或 list/tuple): 旋转中心坐标，形状为(3,)，如 [x, y, z]

vector_endpoint (np.ndarray 或 list/tuple): 要旋转的向量的终点坐标，形状为(3,)

target_vector (np.ndarray 或 list/tuple): 目标向量，形状为(3,)，旋转后当前向量将与此向量同向

Returns

atoms: Atoms 旋转后的原子结构

def run_each_neb_calculation(target_atom_list, mpi_partition='40x1', co2_indexes=None)

在自动截取MD轨迹的算能垒的自动化流程中，基于NEB zbl基础继续运行 EACH NEB 计算

Args

target_atom_list : list: 目标原子列表
mpi_partition : str, optional: MPI 分区名称，默认 "40x1"
co2_indexes : list, optional: CO2 索引列表，默认 None

Returns

None

def run_initial_state_minimization()

在自动截取MD轨迹的算能垒的自动化流程中，运行初态结构优化包括创建1.IS_min目录，复制文件到该目录，运行LAMMPS最小化，转换结果为可读格式。返回优化后的结构文件路径

Returns

Path: 优化后的结构文件路径

def run_neb_calculation_normal(minimized_is_path, target_atom_list, mpi_partition='40x1', neb_max_refine_rounds=3, co2_indexes=None)

运行 NEB 计算

def run_neb_calculation_zbl(minimized_is_path, target_atom_list, mpi_partition='40x1', neb_max_refine_rounds=3)

在自动截取MD轨迹的算能垒的自动化流程中，运行 NEB_zbl 计算，用于避开初始线性插值导致的原子距离过近的问题

Args

minimized_is_path : Path: 最小化后的初始结构文件路径
target_atom_list : list: 目标原子列表
mpi_partition : str, optional: MPI 分区名称，默认 "40x1"

neb_max_refine_rounds (int, optional): 自动优化轮数，默认 3

def scatter_xyz(x_list: list, y_list: list, z_list: list, color_list: list, vmin, vmax, max_color=None)

将三维数据点按照color_list中的值映射到Viridis色阶的颜色，并将结果保存为plot.xyz文件

Args

x_list: x坐标列表
y_list: y坐标列表
z_list: z坐标列表
color_list: 用于颜色映射的数值列表
vmin: 可选的最小值，用于归一化。如果为None，将使用输入数组的最小值
vmax: 可选的最大值，用于归一化。如果为None，将使用输入数组的最大值
max_color: 可选的最大颜色值，用于超出范围时的颜色，如果为None，将使用黄色

def split_xyz_by_elements(filename: str)

按元素组合分割轨迹文件

Args

filename : str: 输入的.xyz轨迹文件地址

def traj2iniData(traj_file: str, specorder=['C', 'O', 'Pd', 'Au'], start_frame=0, end_frame=None)

将轨迹文件转换为LAMMPS ini data文件：0.data, 1.data, 2.data, …

Args

traj_file : str: 轨迹文件路径
specorder : list: 元素顺序列表，元素会按在表格中的顺序分别编号为1，2，3…
start_frame : int: 起始帧索引 (默认0)
end_frame : int: 结束帧索引 (默认None表示最后一帧)，-N表示倒数第N帧

def translate_structure_center(atoms, target_center)

将输入的ASE Atoms对象整体平移，使其中心平移到目标中心点

参数:

atoms : Atoms 输入的ASE原子结构对象 target_center : np.ndarray 或 list/tuple 目标中心点坐标，形状为(3,)，如 [x, y, z]

Atoms 平移后的新Atoms对象

异常:

ValueError: 如果输入参数无效