工具模块 (utils)

本模块提供各种辅助工具和实用函数。

通用工具

工具模块

包含 TensorConverter 类用于张量与 Voigt 表示之间的转换，DataCollector 类用于收集模拟过程中的数据，及一些常用的单位转换常量

class thermoelasticsim.utils.utils.TensorConverter[源代码]

基类：object

张量转换工具类，支持应力和应变张量的 Voigt 与 3x3 矩阵表示之间的相互转换。

Methods

`from_voigt`(voigt, tensor_type)	将 Voigt 表示的 6 元素向量转换为 3x3 的对称张量。
`to_voigt`(tensor, tensor_type[, tol])	将一个对称的 3x3 张量转换为 Voigt 表示的 6 元素向量。

static to_voigt(tensor, tensor_type, tol=1e-08)[源代码]

将一个对称的 3x3 张量转换为 Voigt 表示的 6 元素向量。

参数:

tensor (np.ndarray) -- 形状为 (3, 3) 的张量。
tensor_type (str) -- 张量类型，必须是 'stress' 或 'strain'。
tol (float, optional) -- 用于检查张量对称性的容差。如果非对称分量差异大于此值，将记录警告。

返回:

形状为 (6,) 的 Voigt 表示向量。

返回类型:

np.ndarray

static from_voigt(voigt, tensor_type)[源代码]

将 Voigt 表示的 6 元素向量转换为 3x3 的对称张量。

参数:

voigt (np.ndarray) -- 形状为 (6,) 的 Voigt 向量。
tensor_type (str) -- 张量类型，必须是 'stress' 或 'strain'。

返回:

形状为 (3, 3) 的对称张量。

返回类型:

np.ndarray

class thermoelasticsim.utils.utils.DataCollector(capacity=None, save_interval=1000, use_threading=False, output_file='trajectory.h5')[源代码]

基类：object

数据收集器，用于记录和分析模拟轨迹

提供了系统状态的收集、统计和保存功能，支持异步数据处理和自动保存。

参数:

capacity (int, optional) -- 存储容量限制，None 表示无限制
save_interval (int, optional) -- 数据自动保存间隔，默认为 1000 步
use_threading (bool, optional) -- 是否使用线程进行数据处理，默认为 False
output_file (str, optional) -- 数据保存的文件名，默认为 'trajectory.h5'

Methods

`collect`(cell[, potential])	收集完整的系统状态数据
`save_trajectory`()	将轨迹数据保存到 HDF5 文件

__init__(capacity=None, save_interval=1000, use_threading=False, output_file='trajectory.h5')[源代码]

参数:

capacity (int | None)
save_interval (int)
use_threading (bool)
output_file (str)

__del__()[源代码]: 确保线程池正确关闭

collect(cell, potential=None)[源代码]

收集完整的系统状态数据

参数:

cell (Cell) -- 当前的晶胞对象
potential (Potential, optional) -- 势能对象，用于计算系统能量

save_trajectory()[源代码]: 将轨迹数据保存到 HDF5 文件

class thermoelasticsim.utils.utils.NeighborList(cutoff, skin=0.3)[源代码]

基类：object

邻居列表类，用于生成和维护原子的邻居列表

提供高效的邻居搜索和更新功能，支持周期性边界条件。

参数:

cutoff (float) -- 截断半径，单位为 Å
skin (float, optional) -- 皮肤厚度，默认为 0.3 Å

Methods

`build`(cell)	构建邻居列表
`debug_neighbor_distribution`()	分析和打印邻居分布情况
`get_neighbor_stats`()	返回邻居列表的统计信息
`get_neighbors`(atom_index)	获取指定原子的邻居列表。
`need_refresh`()	判断是否需要更新邻居列表。
`update`()	更新邻居列表，如果需要的话。

__init__(cutoff, skin=0.3)[源代码]

参数:

cutoff (float)
skin (float)

get_neighbor_stats()[源代码]

返回邻居列表的统计信息

返回:: 包含最小、最大、平均邻居数等统计信息的字典
返回类型:: dict

build(cell)[源代码]: 构建邻居列表

need_refresh()[源代码]

判断是否需要更新邻居列表。

返回:: 如果需要更新，返回 True；否则返回 False。
返回类型:: bool

update()[源代码]: 更新邻居列表，如果需要的话。

get_neighbors(atom_index)[源代码]

获取指定原子的邻居列表。

参数:: atom_index (int) -- 原子的索引。
返回:: 邻居原子的索引列表。
返回类型:: list of int

debug_neighbor_distribution()[源代码]: 分析和打印邻居分布情况

thermoelasticsim.utils.utils.get_atomic_mass(symbol)[源代码]

根据原子符号获取原子质量（amu）

参数:: symbol (str) -- 原子符号，例如 'Al', 'Si'
返回:: 原子质量（amu）
返回类型:: float
抛出:: KeyError -- 如果原子符号不存在

优化器

分子动力学模拟优化器模块

提供多种优化算法用于原子结构优化，包括： - GradientDescentOptimizer: 带动量项的梯度下降 - BFGSOptimizer: 基于scipy.optimize.minimize的BFGS - LBFGSOptimizer: 改进的L-BFGS(有限内存BFGS)

class thermoelasticsim.utils.optimizers.Optimizer[源代码]

基类：object

优化器抽象基类，定义优化方法的接口

子类需要实现optimize()方法来执行具体的优化算法。

optimize(cell, potential)[源代码]

执行优化算法，需子类实现

参数:

cell (Cell)
potential (Potential)

返回类型:

tuple[bool, list]

Methods

optimize(cell, potential)

执行优化算法

optimize(cell, potential)[源代码]

执行优化算法

参数:

cell (Cell) -- 晶胞对象
potential (Potential) -- 势能函数

返回:

返回(是否收敛, 轨迹数据)

返回类型:

tuple[bool, list]

备注

轨迹数据包含每步的: - 原子位置 - 晶胞体积 - 晶格矢量

class thermoelasticsim.utils.optimizers.GradientDescentOptimizer(maxiter=10000, tol=0.001, step_size=0.001, energy_tol=0.0001, beta=0.9)[源代码]

基类：Optimizer

带动量项的梯度下降优化器

参数:

maxiter (int, optional) -- 最大迭代步数，默认10000
tol (float, optional) -- 力收敛阈值，默认1e-3 eV/Å
step_size (float, optional) -- 步长，默认1e-3 Å
energy_tol (float, optional) -- 能量变化阈值，默认1e-4 eV
beta (float, optional) -- 动量系数[0,1)，默认0.9

converged

优化是否收敛的标志

Type:: bool

trajectory

记录优化轨迹的列表

Type:: list

Methods

optimize(cell, potential)

执行带动量项的梯度下降优化

__init__(maxiter=10000, tol=0.001, step_size=0.001, energy_tol=0.0001, beta=0.9)[源代码]: 初始化带动量项的梯度下降优化器

optimize(cell, potential)[源代码]

执行带动量项的梯度下降优化

参数:

cell (Cell) -- 晶胞对象
potential (Potential) -- 势能函数

返回:

返回(是否收敛, 轨迹数据字典列表)

返回类型:

tuple[bool, list[dict]]

备注

收敛条件: - 最大原子力 < tol - 能量变化 < energy_tol

class thermoelasticsim.utils.optimizers.BFGSOptimizer(tol=1e-06, maxiter=10000)[源代码]

基类：Optimizer

BFGS准牛顿优化器

参数:

tol (float, optional) -- 收敛阈值，默认1e-6
maxiter (int, optional) -- 最大迭代步数，默认10000

converged

优化是否收敛的标志

Type:: bool

trajectory

记录优化轨迹的列表

Type:: list

备注

使用scipy.optimize.minimize的BFGS实现适用于中等规模系统优化

Methods

optimize(cell, potential)

执行 BFGS 优化

__init__(tol=1e-06, maxiter=10000)[源代码]: 初始化 BFGS 优化器

optimize(cell, potential)[源代码]

执行 BFGS 优化

参数:

cell (Cell) -- 晶胞对象
potential (Potential) -- 势能函数

返回:

返回(是否收敛, 轨迹数据字典列表)

返回类型:

tuple[bool, list[dict]]

class thermoelasticsim.utils.optimizers.CGOptimizer(tol=1e-06, maxiter=10000)[源代码]

基类：Optimizer

共轭梯度优化器（分数坐标），对剪切后的浅谷更稳健。

参数:

tol (float, optional) -- 梯度收敛阈值（映射到 scipy 的 gtol），默认 1e-6
maxiter (int, optional) -- 最大迭代步数，默认 10000

Methods

optimize(cell, potential)

执行 CG 优化（变量为分数坐标）。

__init__(tol=1e-06, maxiter=10000)[源代码]

参数:

tol (float)
maxiter (int)

optimize(cell, potential)[源代码]

执行 CG 优化（变量为分数坐标）。

参数:

cell (Cell)
potential (Potential)

返回类型:

tuple[bool, list[dict]]

class thermoelasticsim.utils.optimizers.LBFGSOptimizer(ftol=1e-08, gtol=1e-06, maxiter=1000, supercell_dims=None, **kwargs)[源代码]

基类：Optimizer

L-BFGS优化器(有限内存BFGS)

该优化器能够处理两种模式： 1. 仅优化原子位置 (默认)。 2. 同时优化原子位置和晶胞形状 (完全弛豫)。

参数:

ftol (float, optional) -- 函数收敛阈值，默认1e-8
gtol (float, optional) -- 梯度收敛阈值，默认1e-6
maxiter (int, optional) -- 最大迭代步数，默认1000
**kwargs (dict, optional) -- 其他要传递给 scipy.optimize.minimize 的选项, 例如 {'disp': True}

Methods

optimize(cell, potential[, relax_cell])

执行 L-BFGS 优化。

__init__(ftol=1e-08, gtol=1e-06, maxiter=1000, supercell_dims=None, **kwargs)[源代码]

optimize(cell, potential, relax_cell=False)[源代码]

执行 L-BFGS 优化。

参数:

cell (Cell)
potential (Potential)
relax_cell (bool)

返回类型:

tuple[bool, list[dict]]

轨迹记录

轨迹存储和管理系统

基于H5MD (HDF5 for Molecular Dynamics) 标准的轨迹存储系统。提供高效的数据压缩、并行I/O支持和丰富的元数据管理功能。

主要特性： - HDF5格式的高效存储 - 支持大规模轨迹数据 - 灵活的压缩选项 - 增量式写入支持 - 丰富的元数据记录

Author: Gilbert Young Created: 2025-08-15

class thermoelasticsim.utils.trajectory.TrajectoryWriter(filename, mode='w', compression='gzip', compression_opts=4, chunk_size=100)[源代码]

基类：object

H5MD格式轨迹文件写入器

遵循H5MD v1.1规范，提供高效的分子动力学轨迹存储。

参数:

filename (str) -- 输出文件名（.h5或.hdf5扩展名）
mode (str) -- 文件打开模式：'w'(覆盖), 'a'(追加), 'x'(创建新文件)
compression (str, optional) -- 压缩算法：'gzip', 'lzf', 'szip'等
compression_opts (int, optional) -- 压缩级别（gzip: 1-9）
chunk_size (int, optional) -- 块大小，影响I/O性能

示例

>>> writer = TrajectoryWriter('trajectory.h5', compression='gzip')
>>> writer.initialize(n_atoms=100, n_frames_estimate=1000)
>>> writer.write_frame(positions, box, time=0.0, step=0)
>>> writer.close()

Methods

`close`()	关闭文件
`initialize`(n_atoms[, n_frames_estimate, ...])	初始化H5MD文件结构
`open`()	打开HDF5文件
`write_frame`(positions[, box, time, step, ...])	写入单帧数据
`write_metadata`(metadata)	写入额外的元数据

__init__(filename, mode='w', compression='gzip', compression_opts=4, chunk_size=100)[源代码]

参数:

filename (str)
mode (str)
compression (str | None)
compression_opts (int | None)
chunk_size (int)

open()[源代码]: 打开HDF5文件

initialize(n_atoms, n_frames_estimate=1000, atom_types=None, metadata=None)[源代码]

初始化H5MD文件结构

参数:

n_atoms (int) -- 原子数量
n_frames_estimate (int) -- 预估帧数（用于优化存储）
atom_types (list, optional) -- 原子类型列表
metadata (dict, optional) -- 额外的元数据

write_frame(positions, box=None, time=None, step=None, velocities=None, forces=None, stress=None, energy=None, temperature=None, **kwargs)[源代码]

写入单帧数据

参数:

positions (np.ndarray) -- 原子位置 (n_atoms, 3)
box (np.ndarray, optional) -- 晶格矢量 (3, 3)
time (float, optional) -- 时间（ps）
step (int, optional) -- MD步数
velocities (np.ndarray, optional) -- 速度 (n_atoms, 3)
forces (np.ndarray, optional) -- 力 (n_atoms, 3)
stress (np.ndarray, optional) -- 应力张量 (3, 3)
energy (float, optional) -- 总能量
temperature (float, optional) -- 温度
**kwargs -- 其他观测量

write_metadata(metadata)[源代码]

写入额外的元数据

参数:: metadata (dict) -- 元数据字典

close()[源代码]: 关闭文件

class thermoelasticsim.utils.trajectory.TrajectoryReader(filename, mode='r', cache_size=100)[源代码]

基类：object

H5MD格式轨迹文件读取器

提供高效的轨迹数据读取和分析功能。

参数:

filename (str) -- 输入文件名
mode (str) -- 读取模式：'r'(只读), 'r+'(读写)
cache_size (int) -- 内存缓存帧数

示例

>>> reader = TrajectoryReader('trajectory.h5')
>>> reader.open()
>>> for frame_idx in range(reader.n_frames):
...     frame = reader.read_frame(frame_idx)
...     process_frame(frame)
>>> reader.close()

Methods

`close`()	关闭文件
`get_metadata`()	获取元数据
`get_trajectory_info`()	获取轨迹概要信息
`open`()	打开HDF5文件
`read_frame`(frame_idx)	读取指定帧
`read_frames`([start, stop, stride])	批量读取多帧

__init__(filename, mode='r', cache_size=100)[源代码]

参数:

filename (str)
mode (str)
cache_size (int)

open()[源代码]: 打开HDF5文件

read_frame(frame_idx)[源代码]

读取指定帧

参数:: frame_idx (int) -- 帧索引
返回:: 帧数据字典
返回类型:: dict

read_frames(start=0, stop=None, stride=1)[源代码]

批量读取多帧

参数:

start (int) -- 起始帧
stop (int, optional) -- 结束帧（不包含）
stride (int) -- 步长

返回:

帧数据列表

返回类型:

list

get_metadata()[源代码]

获取元数据

返回类型:: dict[str, Any]

get_trajectory_info()[源代码]

获取轨迹概要信息

返回类型:: dict[str, Any]

close()[源代码]: 关闭文件

thermoelasticsim.utils.trajectory.save_trajectory(filename, positions_list, boxes_list=None, times=None, **kwargs)[源代码]

便捷函数：保存轨迹数据

参数:

filename (str) -- 输出文件名
positions_list (list) -- 位置列表
boxes_list (list, optional) -- 晶格矢量列表
times (list, optional) -- 时间列表
**kwargs -- 其他数据

返回类型:

None

thermoelasticsim.utils.trajectory.load_trajectory(filename, start=0, stop=None, stride=1)[源代码]

便捷函数：加载轨迹数据

参数:

filename (str) -- 输入文件名
start (int) -- 起始帧
stop (int, optional) -- 结束帧
stride (int) -- 步长

返回:

轨迹数据字典

返回类型:

dict

带轨迹记录的优化器扩展

为现有优化器添加轨迹记录功能，在优化过程中自动捕获原子位置、晶格矢量、能量、应力等信息并保存到HDF5文件。

Author: Gilbert Young Created: 2025-08-15

class thermoelasticsim.utils.trajectory_recorder.TrajectoryRecorder(output_file, record_interval=1, record_forces=True, record_stress=True, record_energy=True, compression='gzip', compression_opts=4)[源代码]

基类：object

轨迹记录器

可以作为回调函数集成到优化器中，自动记录优化轨迹。

参数:

output_file (str) -- 输出轨迹文件名
record_interval (int) -- 记录间隔（每N步记录一次）
record_forces (bool) -- 是否记录力
record_stress (bool) -- 是否记录应力
record_energy (bool) -- 是否记录能量
compression (str) -- 压缩算法
compression_opts (int)

示例

>>> recorder = TrajectoryRecorder('optimization.h5')
>>> optimizer = LBFGSOptimizerWithTrajectory(recorder=recorder)
>>> optimizer.optimize(cell, potential)

Methods

`finalize`()	完成记录并关闭文件
`initialize`(cell[, metadata])	初始化记录器
`record`(cell, potential[, step])	记录当前状态

__init__(output_file, record_interval=1, record_forces=True, record_stress=True, record_energy=True, compression='gzip', compression_opts=4)[源代码]

参数:

output_file (str)
record_interval (int)
record_forces (bool)
record_stress (bool)
record_energy (bool)
compression (str)
compression_opts (int)

initialize(cell, metadata=None)[源代码]

初始化记录器

参数:

cell (Cell) -- 初始晶胞
metadata (dict, optional) -- 元数据

record(cell, potential, step=None)[源代码]

记录当前状态

参数:

cell (Cell) -- 当前晶胞
potential (Potential) -- 势能函数
step (int, optional) -- 优化步数

finalize()[源代码]: 完成记录并关闭文件

class thermoelasticsim.utils.trajectory_recorder.LBFGSOptimizerWithTrajectory(recorder=None, trajectory_file=None, record_interval=1, **kwargs)[源代码]

基类：LBFGSOptimizer

带轨迹记录功能的L-BFGS优化器

在原有L-BFGS优化器基础上添加轨迹记录功能。

参数:

recorder (TrajectoryRecorder, optional) -- 轨迹记录器
trajectory_file (str, optional) -- 轨迹文件名（如果不提供recorder）
record_interval (int) -- 记录间隔
**kwargs -- 其他L-BFGS参数

Methods

optimize(cell, potential[, relax_cell])

执行优化并记录轨迹

__init__(recorder=None, trajectory_file=None, record_interval=1, **kwargs)[源代码]

参数:

recorder (TrajectoryRecorder | None)
trajectory_file (str | None)
record_interval (int)

optimize(cell, potential, relax_cell=False)[源代码]

执行优化并记录轨迹

参数:

cell (Cell) -- 晶胞对象
potential (Potential) -- 势能函数
relax_cell (bool) -- 是否优化晶格

返回:

(是否收敛, 优化信息字典)

返回类型:

tuple

thermoelasticsim.utils.trajectory_recorder.create_optimizer_with_trajectory(optimizer_type='L-BFGS', trajectory_file=None, record_interval=1, **optimizer_params)[源代码]

创建带轨迹记录的优化器

参数:

optimizer_type (str) -- 优化器类型
trajectory_file (str, optional) -- 轨迹文件名
record_interval (int) -- 记录间隔
**optimizer_params -- 优化器参数

返回:

带轨迹记录的优化器实例

返回类型:

optimizer

class thermoelasticsim.utils.trajectory_recorder.DeformationTrajectoryRecorder(output_file)[源代码]

基类：object

专门用于形变计算的轨迹记录器

记录形变过程中的完整信息，包括应变、应力、能量等。

Methods

`finalize`()	完成记录
`initialize`(base_cell[, metadata])	初始化
`record_deformation`(cell, potential, strain, ...)	记录形变状态

参数:: output_file (str)

__init__(output_file)[源代码]

参数:: output_file (str)

initialize(base_cell, metadata=None)[源代码]

初始化

参数:

base_cell (Cell)
metadata (dict[str, Any] | None)

record_deformation(cell, potential, strain, stress, deformation_matrix, mode, converged)[源代码]

记录形变状态

参数:

cell (Cell) -- 形变后的晶胞
potential (Potential) -- 势能函数
strain (np.ndarray) -- 应变张量
stress (np.ndarray) -- 应力张量
deformation_matrix (np.ndarray) -- 形变矩阵
mode (str) -- 形变模式
converged (bool) -- 是否收敛

finalize()[源代码]: 完成记录

可视化

可视化模块

包含 Visualizer 类，用于可视化晶胞结构和应力-应变关系

class thermoelasticsim.utils.visualization.Visualizer[源代码]

基类：object

晶体结构和数据可视化工具类

Methods

`create_optimization_animation`(trajectory, ...)	创建优化过程的动画
`create_simulation_animation`(trajectory_data, ...)	创建分子动力学模拟过程的动画
`create_stress_strain_animation`(strain_data, ...)	创建应力-应变关系的动画
`plot_cell_structure`(cell_structure[, show])	绘制晶体结构的 3D 图形
`plot_deformation_stress_strain`(strains, ...)	为特定变形方式绘制所有应力分量的响应图
`plot_stress_strain_multiple`(strain_data, ...)	绘制多个应力-应变关系图，每个应力分量对应一个子图
`set_axes_equal`(ax)	使3D坐标轴比例相同

__init__()[源代码]: 初始化可视化工具类

plot_cell_structure(cell_structure, show=True)[源代码]

绘制晶体结构的 3D 图形

参数:

cell_structure (Cell) -- 包含原子的 Cell 实例
show (bool, optional) -- 是否立即显示图形，默认为 True

返回:

fig (matplotlib.figure.Figure) -- 绘制的图形对象
ax (matplotlib.axes._subplots.Axes3DSubplot) -- 3D 子图对象

set_axes_equal(ax)[源代码]

使3D坐标轴比例相同

参数:: ax (matplotlib.axes._subplots.Axes3DSubplot) -- 3D 子图对象

plot_stress_strain_multiple(strain_data, stress_data, show=True)[源代码]

绘制多个应力-应变关系图，每个应力分量对应一个子图

参数:

strain_data (numpy.ndarray) -- 应变数据，形状为 (N, 6)
stress_data (numpy.ndarray) -- 应力数据，形状为 (N, 6)
show (bool, optional) -- 是否立即显示图形，默认为 True

返回:

fig (matplotlib.figure.Figure) -- 绘制的图形对象
axes (numpy.ndarray) -- 子图对象数组

plot_deformation_stress_strain(strains, stresses, mode_index, save_path, show=False)[源代码]

为特定变形方式绘制所有应力分量的响应图

参数:

strains (numpy.ndarray) -- 该变形方式下的应变数据
stresses (numpy.ndarray) -- 该变形方式下的应力数据
mode_index (int) -- 变形模式索引 (0-5)
save_path (str) -- 保存路径
show (bool, optional) -- 是否显示图像，默认为 False

create_optimization_animation(trajectory, filename, title='Optimization', pbc=True, show=True)[源代码]

创建优化过程的动画

参数:

trajectory (list of dict) -- 记录的轨迹数据，每个元素包含 'positions', 'volume', 'lattice_vectors'
filename (str) -- 保存动画的文件名（包含路径）
title (str, optional) -- 动画标题，默认为 "Optimization"
pbc (bool, optional) -- 是否应用周期性边界条件，默认为 True
show (bool, optional) -- 是否立即显示动画，默认为 True

create_stress_strain_animation(strain_data, stress_data, filename, show=True)[源代码]

创建应力-应变关系的动画

参数:

strain_data (numpy.ndarray) -- 应变数据，形状为 (N, 6)
stress_data (numpy.ndarray) -- 应力数据，形状为 (N, 6)
filename (str) -- 保存动画的文件名（支持 .gif, .mp4 等格式）
show (bool, optional) -- 是否立即显示动画，默认为 True

create_simulation_animation(trajectory_data, filename, interval=100)[源代码]

创建分子动力学模拟过程的动画

参数:

trajectory_data (list of dict) -- 轨迹数据列表，每个字典包含: - positions: array_like, 原子位置 - cell: Cell object, 晶胞对象 - time: float, 时间 - temperature: float, 温度 - energy: float, 能量
filename (str) -- 保存动画的文件名
interval (int, optional) -- 帧之间的时间间隔(毫秒)，默认100

绘图配置

matplotlib字体配置模块

一劳永逸解决中文字体显示问题

Usage:

import matplotlib.pyplot as plt from thermoelasticsim.utils.plot_config import setup_matplotlib setup_matplotlib() # 之后就可以正常使用中文

# 或者直接导入已配置的pyplot from thermoelasticsim.utils.plot_config import plt

Created: 2025-08-17

thermoelasticsim.utils.plot_config.setup_matplotlib(force_english=False)[源代码]

设置matplotlib的字体配置

参数:: force_english (bool) -- 是否强制使用英文字体（当中文字体有问题时）

thermoelasticsim.utils.plot_config.get_chinese_font()[源代码]: 获取第一个可用的中文字体名称