采样 API

水分子

用于 Monte Carlo 采样的水分子表示。

此模块提供 WaterMolecule 类，用于表示具有位置和方向（Euler 角）的 TIP3P 水分子。

class q2m3.sampling.water_molecule.WaterMolecule(position, euler_angles=<factory>)

基类：object

具有位置和方向的 TIP3P 水分子。

水分子定义为：- position：氧原子（分子中心）的 3D 坐标；- euler_angles：以弧度为单位的 [roll, pitch, yaw] 旋转。

默认方向下，氢原子位于 xy 平面内，关于 x 轴对称。

参数:

• position (ndarray)

• euler_angles (ndarray)

position

氧原子位置，单位为埃

类型:

numpy.ndarray

euler_angles

Euler 角 [roll, pitch, yaw]，单位为弧度

类型:

numpy.ndarray

property oxygen_position: ndarray

返回氧原子位置（与分子位置相同）。

get_atom_coords()

获取三个原子（O、H1、H2）的坐标。

返回:

形状为 (3, 3) 的数组，包含以埃为单位的 [O, H1, H2] 坐标。

返回类型:

ndarray

get_charges()

获取所有原子的 TIP3P 部分电荷。

返回:

形状为 (3,) 的数组，包含 [O_charge, H1_charge, H2_charge]。

返回类型:

ndarray

copy()

创建此水分子的独立副本。

返回类型:

WaterMolecule

移动生成

水分子的 Monte Carlo 移动生成器。

此模块提供随机平移和旋转移动，用于水分子构型的 Monte Carlo 采样。

class q2m3.sampling.mc_moves.MCMoveGenerator(translation_step=0.3, rotation_step=np.float64(0.2617993877991494))

基类：object

Monte Carlo 移动（平移和旋转）生成器。

参数:

• translation_step (float)

• rotation_step (float)

translation_step

每个方向的最大平移量（埃）

类型:

float

rotation_step

每个 Euler 角的最大旋转量（弧度）

类型:

float

propose_translation(water)

提出随机平移移动。

参数:

water (WaterMolecule) -- 原始水分子

返回:

平移后得到的新水分子

返回类型:

WaterMolecule

propose_rotation(water)

提出随机旋转移动。

参数:

water (WaterMolecule) -- 原始水分子

返回:

旋转后得到的新水分子

返回类型:

WaterMolecule

propose_move(water)

以相等概率提出平移或旋转移动。

参数:

water (WaterMolecule) -- 原始水分子

返回:

应用所提移动后得到的新水分子

返回类型:

WaterMolecule

propose_move_for_system(waters)

为系统中随机选中的一个水分子提出移动。

参数:

waters (list[WaterMolecule]) -- 水分子列表

返回:

• new_waters: 复制 waters 列表并移动其中一个水分子

• moved_index: 被移动水分子的索引

返回类型:

Tuple of (new_waters, moved_index)

Metropolis 采样

用于溶剂化结构优化的 Metropolis-Hastings 采样器。

此模块提供 Metropolis-Hastings 算法，用于在固定溶质分子周围采样水分子构型。

class q2m3.sampling.metropolis.MetropolisSampler(waters, energy_function, temperature=300.0, translation_step=0.3, rotation_step=np.float64(0.2617993877991494))

基类：object

用于水分子构型优化的 Metropolis-Hastings 采样器。

使用 MC 移动采样构型，并根据给定能量函数，按 Metropolis 准则接受或拒绝移动。

参数:

• waters (list[WaterMolecule])

• energy_function (Callable[[list[WaterMolecule]], float])

• temperature (float)

• translation_step (float)

• rotation_step (float)

waters

WaterMolecule 对象列表（MM 区域）

类型:

list[q2m3.sampling.water_molecule.WaterMolecule]

energy_function

接收 waters 并返回以 Hartree 为单位的能量的函数

类型:

collections.abc.Callable[[list[q2m3.sampling.water_molecule.WaterMolecule]], float]

temperature

Boltzmann 接受准则的温度，单位为 Kelvin

类型:

float

translation_step

每次移动的最大平移量（埃）

类型:

float

rotation_step

每次移动的最大旋转量（弧度）

类型:

float

run(n_steps)

运行 n_steps 步 Metropolis-Hastings 采样。

参数:

n_steps (int) -- 要运行的 MC 步数

返回:

• energies: 每一步的能量列表

• acceptance_rate: 接受移动的比例

• best_energy: 已找到的最低能量

• best_config: 最低能量对应的水分子构型

返回类型:

Dictionary containing

力场

水分子间相互作用的 TIP3P 力场。

此模块计算 TIP3P 水分子的能量，包括 Lennard-Jones 和 Coulomb 相互作用。

class q2m3.sampling.mm_forcefield.TIP3PForceField(sigma_oo=3.15061, epsilon_oo=0.152)

基类：object

用于 MM 能量计算的 TIP3P 水模型力场。

计算：- Lennard-Jones 能量（仅 O-O 相互作用）；- Coulomb 能量（所有原子对）。

所有能量均以 Hartree 返回，以兼容量子力学计算。

参数:

• sigma_oo (float)

• epsilon_oo (float)

__init__(sigma_oo=3.15061, epsilon_oo=0.152)

初始化 TIP3P 力场。

参数:

• sigma_oo (float) -- O-O 相互作用的 LJ sigma 参数（埃）

• epsilon_oo (float) -- O-O 相互作用的 LJ epsilon 参数（kcal/mol）

compute_lj_energy(waters)

计算所有水分子对之间的 Lennard-Jones 能量。

仅包含 O-O 相互作用（TIP3P 约定）。

参数:

waters (list[WaterMolecule]) -- WaterMolecule 对象列表

返回:

LJ 总能量，单位为 Hartree

返回类型:

float

compute_coulomb_energy(waters)

计算所有水分子对之间的 Coulomb 能量。

包含不同分子之间所有原子对的相互作用。

参数:

waters (list[WaterMolecule]) -- WaterMolecule 对象列表

返回:

Coulomb 总能量，单位为 Hartree

返回类型:

float

compute_mm_energy(waters)

计算所有水分子对之间的 MM 总能量（LJ + Coulomb）。

参数:

waters (list[WaterMolecule]) -- WaterMolecule 对象列表

返回:

MM 总能量，单位为 Hartree

返回类型:

float