python计算化学（autode系列—xTB）Atoms类详解

👨类实例autode.atoms.Atom：

class autode.atoms.Atom(atomic_symbol: str, x: Any = 0.0, y: Any = 0.0, z: Any = 0.0, atom_class: int | None = None, partial_charge: float | None = None)
类内的构造方式：init(atomic_symbol: str, x: Any = 0.0, y: Any = 0.0, z: Any = 0.0, atom_class: int | None = None, partial_charge: float | None = None)

原子类：默认以原点为中心。可以通过位置参数或关键字参数初始化：
Parameters 参数:

• y – y coordinate in 3D space (Å)
• y – 3D 空间中的 y 坐标（Å）
• z – z coordinate in 3D space (Å)
• z – 3D 空间中的 z 坐标（Å）

atom_class – 用于区分其他相同原子的虚构附加标签。在寻找基于身份反应的键异构体时很有用。部分电荷 - 以电子单位表示的部分原子电荷，由原子环境决定。不是一个可观测属性。

Atom 类的构造函数（__init__）接受以下参数：

• atomic_symbol (必需)
• x, y, z (可选，有默认值)
• atom_class (可选)
• partial_charge (可选)

全参数构造示例：

import autode as ade
from autode.values import Angle  # 如果需要 Angle 对象，但这里坐标是数值# 创建一个带有所有参数的碳原子
carbon_atom = ade.Atom(atomic_symbol='C',      # 元素符号：碳x=1.23,                 # x 坐标：1.23 Åy=-0.45,                # y 坐标：-0.45 Åz=2.67,                 # z 坐标：2.67 Åatom_class=1,           # 自定义类别：1 (用于区分相同元素的不同原子)partial_charge=-0.25    # 部分电荷：-0.25 e
)# 打印原子对象，查看其表示
print(carbon_atom)  # 输出: Atom(C, 1.2300, -0.4500, 2.6700, class=1, charge=-0.25)# 验证属性
print(f"原子符号: {carbon_atom.atomic_symbol}")     # 输出: 原子符号: C
print(f"原子序数: {carbon_atom.atomic_number}")     # 输出: 原子序数: 6
print(f"坐标: {carbon_atom.coord}")                 # 输出: 坐标: Coordinate([ 1.23 -0.45  2.67] Å)
print(f"质量: {carbon_atom.mass}")                  # 输出: 质量: Mass(12.0107 amu)
print(f"是金属吗?: {carbon_atom.is_metal}")         # 输出: 是金属吗?: False
print(f"原子类别: {carbon_atom.atom_class}")        # 输出: 原子类别: 1
print(f"部分电荷: {carbon_atom.partial_charge}")    # 输出: 部分电荷: -0.25

输出示例：

Atom(C, 1.2300, -0.4500, 2.6700)
原子符号: C
原子序数: 6
坐标: [ 1.23 -0.45  2.67]
质量: 12.0107
是金属吗?: False
原子类别: 1
部分电荷: -0.25

👦参数说明

• atomic_symbol=‘C’: 这是唯一必需的参数，指定了原子的化学元素。这里创建了一个碳原子。
• x=1.23, y=-0.45, z=2.67: 这些参数定义了原子在三维空间中的精确位置（单位：Å）。如果省略，它们将默认为 0.0。
• atom_class=1: 这是一个可选的、用户定义的标签。在处理具有多个相同类型原子的分子（如对称分子或反应中的特定原子）时，这个标签非常有用，可以帮助算法区分它们。如果不需要，可以省略或设为 None。
• partial_charge=-0.25: 这是一个可选的浮点数，表示该原子携带的部分电荷（以基本电荷 e 为单位）。这通常在量子化学计算后获得。如果尚未计算，可以省略或设为 None。

类属性盘点

atomic_number属性

类型: int
描述: 该属性返回原子的原子序数，即该元素在周期表中的序号，也等于其原子核中的质子数。
只读: 这是一个只读属性。它由 atomic_symbol（元素符号）决定，不能直接修改。要改变原子序数，必须创建一个具有不同 atomic_symbol 的新 Atom 对象。
示例:

编辑
import autode as ade# 创建不同元素的原子
hydrogen = ade.Atom('H')
carbon = ade.Atom('C')
oxygen = ade.Atom('O')# 访问 atomic_number 属性
print(hydrogen.atomic_number)  # 输出: 1
print(carbon.atomic_number)    # 输出: 6
print(oxygen.atomic_number)    # 输出: 8

如何获取多个原子的原子序数？
如果您有一个分子（包含多个原子），您可以遍历其原子列表来获取所有原子的原子序数：

编辑
import autode as ade# 假设你有一个水分子
water = ade.Molecule(smiles='O')  # 从SMILES构建水分子
# 或者手动添加原子
# water = ade.Molecule()
# water.atoms = [ade.Atom('O', 0.0, 0.0, 0.0), ade.Atom('H', 0.96, 0.0, -0.24), ade.Atom('H', -0.24, 0.96, 0.0)]# 获取所有原子的原子序数列表
atomic_numbers_list = [atom.atomic_number for atom in water.atoms]
print(atomic_numbers_list)  # 对于水分子，输出: [8, 1, 1] (氧原子序数为8，两个氢为1)

总结: 请使用 atomic_number（单数）来获取 autode.atoms.Atom 对象的原子序数。atomic_numbers 不是该类的有效属性。

atomic_symbol属性

• 类型: str (字符串)
• 描述: 该属性返回或代表构成该原子的化学元素的元素符号。这是在创建 Atom 对象时通过 atomic_symbol 参数指定的。
• 别名: 文档中明确指出，atomic_symbol 是 label 属性的别名。这意味着 atom.atomic_symbol 和 atom.label 是等价的，都返回相同的元素符号字符串。
• 只读: 这是一个只读属性。您不能直接修改一个已存在 Atom 对象的 atomic_symbol（例如，atom.atomic_symbol = ‘O’ 会引发错误或被忽略）。要改变原子的元素类型，必须创建一个具有新元素符号的新 Atom 对象。
• 格式: 通常遵循标准的化学元素符号规则，即首字母大写，后续字母小写（例如 ‘H’, ‘He’, ‘C’, ‘O’, ‘Na’, ‘Fe’, ‘Zn’）。autodE 库在内部会处理符号的标准化。

示例用法

编辑
import autode as ade# 1. 创建原子时指定 atomic_symbol
carbon_atom = ade.Atom('C', 0.0, 0.0, 0.0)
oxygen_atom = ade.Atom('O', 1.2, 0.0, 0.0)
sodium_atom = ade.Atom('Na', 0.0, 1.5, 0.0)  # 双字母符号# 2. 访问 atomic_symbol 属性
print(carbon_atom.atomic_symbol)  # 输出: C
print(oxygen_atom.atomic_symbol)  # 输出: O
print(sodium_atom.atomic_symbol)  # 输出: Na# 3. atomic_symbol 是 label 的别名，两者等价
print(carbon_atom.atomic_symbol == carbon_atom.label)  # 输出: True# 4. atomic_symbol 决定了其他关键属性
print(f"碳的原子序数是: {carbon_atom.atomic_number}")  # 输出: 碳的原子序数是: 6
print(f"氧的质量是: {oxygen_atom.mass}")              # 输出: 氧的质量是: Mass(15.999 amu)
print(f"钠是金属吗?: {sodium_atom.is_metal}")         # 输出: 钠是金属吗?: True# 5. 尝试直接修改 atomic_symbol (这是无效的)
try:carbon_atom.atomic_symbol = 'N'  # 试图改为氮
except Exception as e:print(f"错误: {e}")  # 可能不会报错，但不会改变值# 正确的做法是创建一个新原子
nitrogen_atom = ade.Atom('N', *carbon_atom.coord)  # 使用氮符号和碳的坐标
print(nitrogen_atom.atomic_symbol)  # 输出: N

输出示例：

C
O
Na
True
碳的原子序数是: 6
氧的质量是: 15.9994
钠是金属吗?: True
错误: can't set attribute 'atomic_symbol'
N

重要性
atomic_symbol 是 Atom 对象最基础、最重要的属性之一，因为它：

• 定义了原子的身份: 它决定了这个原子是氢、碳、氧还是其他任何元素。
• 决定了物理化学性质: 原子的大部分内在属性（如 atomic_number, mass, covalent_radius, vdw_radius, is_metal）都直接由其 atomic_symbol 决定。
• 是构建分子的基础: 在构建分子结构时，每个原子的 atomic_symbol 是识别其化学角色的关键。

总结: atomic_symbol 是一个只读的字符串属性，用于获取 autode.atoms.Atom 对象所代表的化学元素的符号。它是原子身份的核心标识，也是访问其所有其他依赖于元素类型的属性的基础。

coord属性

coord 属性详解

• 类型: autode.values.Coordinate
• 描述: 该属性表示原子在三维空间中的笛卡尔坐标（Cartesian coordinates）。它是一个 Coordinate 类的实例，封装了 x, y, z 三个分量。
• 单位: 默认单位是埃（Ångström, Å）。这是量子化学和计算化学中常用的长度单位。
• 动态性: coord 是一个动态属性，它直接反映 Atom 对象当前的几何位置。对原子进行的任何几何操作（如平移、旋转）都会立即更新 coord 的值。

核心功能与用法

• 访问坐标分量:
  您可以通过 coord 对象的属性来获取各个方向的坐标值。

  import autode as adeatom = ade.Atom('C', 1.0, 2.0, 3.0)
  print(atom.coord.x)  # 输出: 1.0
  print(atom.coord.y)  # 输出: 2.0
  print(atom.coord.z)  # 输出: 3.0
  

整体访问:
直接打印或使用 coord 会显示完整的坐标向量。

  print(atom.coord)  # 输出: Coordinate([1. 2. 3.] Å)

单位转换:
Coordinate 对象继承自 autode.values.Value，支持使用 .to() 方法进行单位转换。

# 转换为玻尔半径（Bohr, a₀）
coord_in_bohr = atom.coord.to('a0')
print(coord_in_bohr)  # 输出: e.g., Coordinate([1.88973 3.77946 5.66919] a₀)# 转换为纳米（nm）
coord_in_nm = atom.coord.to('nm')
print(coord_in_nm)  # 输出: Coordinate([0.1 0.2 0.3] nm)

与几何操作联动:
coord 会实时反映几何变换的结果。

# 平移原子
atom.translate(0.5, 0.5, 0.5)
print(atom.coord)  # 输出: Coordinate([1.5 2.5 3.5] Å) (坐标已更新)# 旋转原子
atom.rotate(axis=[0, 0, 1], theta=90, origin=[0, 0, 0])  # 绕z轴旋转90度
print(atom.coord)  # 输出: 坐标已根据旋转计算更新

总结

coord 属性是 autode.atoms.Atom 类中用于管理和访问原子空间位置的核心接口。它不仅仅是一个简单的 (x, y, z) 元组，而是一个功能丰富的 Coordinate 对象，提供了便捷的分量访问、清晰的单位表示和灵活的单位转换能力。它是进行任何涉及原子几何结构操作（如构建分子、计算距离、进行优化）的基础。

covalent_radius 属性详解

• 类型: autode.values.Distance
• 描述: 该属性返回原子的共价半径（Covalent Radius）。共价半径是衡量原子在形成共价键时其“大小”的一个经验值，通常定义为同核双原子分子（如 H₂, O₂, C-C）中键长的一半。
• 单位: 默认单位是埃（Å）。
• 只读: 这是一个只读属性。其值由原子的元素类型（atomic_symbol）决定，不能直接修改。
• 用途: 在计算化学中，共价半径常用于：
  • 判断成键: 两个原子之间的距离如果小于它们共价半径之和的某个倍数（如 1.1-1.3 倍），则通常认为它们之间存在化学键。这是构建分子拓扑结构（molecular graph）的基础。
  • 可视化: 在球棍模型或空间填充模型中确定原子的大小。

示例:

import autode as ade# 创建不同元素的原子
hydrogen = ade.Atom('H')
carbon = ade.Atom('C')
oxygen = ade.Atom('O')# 访问 covalent_radius 属性
print(f"氢的共价半径: {hydrogen.covalent_radius}")  # 输出: Distance(0.31 Å)
print(f"碳的共价半径: {carbon.covalent_radius}")    # 输出: Distance(0.76 Å)
print(f"氧的共价半径: {oxygen.covalent_radius}")    # 输出: Distance(0.73 Å)# 单位转换 (Distance 对象支持 .to() 方法)
radius_in_nm = carbon.covalent_radius.to('nm')
print(f"碳的共价半径 (nm): {radius_in_nm}")         # 输出: Distance(0.076 nm)# 计算两个原子成键的近似阈值
c_atom = ade.Atom('C', 0.0, 0.0, 0.0)
h_atom = ade.Atom('H', 1.0, 0.0, 0.0)
bond_threshold = c_atom.covalent_radius + h_atom.covalent_radius
print(f"C-H 成键距离阈值: {bond_threshold}")       # 输出: Distance(1.07 Å)
# 实际的 C-H 键长通常在 ~1.09 Å 左右，非常接近此估算值。

总结

covalent_radius 属性提供了原子在共价键合环境下的有效尺寸，是进行分子结构分析、键合判断和可视化的关键物理量。

group 属性详解

• 类型: int
• 描述: 该属性返回原子在其元素周期表中的族（Group），即周期表中的列。族号反映了元素的价电子数和化学性质的周期性。
• 范围: 通常为 1 到 18（采用 IUPAC 推荐的编号方式）。
• 只读: 这是一个只读属性，其值由原子的元素类型（atomic_symbol）决定，无法修改。
• 错误处理: 如果提供的 atomic_symbol 无效或未在内部数据库中找到，该属性将返回 0。

示例

import autode as ade# 创建不同族的原子
hydrogen = ade.Atom('H')
carbon = ade.Atom('C')
oxygen = ade.Atom('O')
sodium = ade.Atom('Na')
chlorine = ade.Atom('Cl')
argon = ade.Atom('Ar')# 访问 group 属性
print(f"氢 (H) 的族: {hydrogen.group}")       # 输出: 1
print(f"碳 (C) 的族: {carbon.group}")         # 输出: 14
print(f"氧 (O) 的族: {oxygen.group}")         # 输出: 16
print(f"钠 (Na) 的族: {sodium.group}")        # 输出: 1
print(f"氯 (Cl) 的族: {chlorine.group}")      # 输出: 17
print(f"氩 (Ar) 的族: {argon.group}")         # 输出: 18# 验证化学性质的关联
# 同一族的元素具有相似的化学性质
print(f"氢和钠都在第 {hydrogen.group} 族")    # 输出: 氢和钠都在第 1 族 (碱金属，H 除外)
print(f"氧和氯的族差: {abs(oxygen.group - chlorine.group)}") # 输出: 2

化学意义

• 主族元素 (1, 2, 13-18): 族号通常等于元素的价电子数（对于 1, 2, 13-18 族）。
• 过渡金属 (3-12): 族号与价电子数的关系较为复杂，但同一族的元素仍表现出相似的性质。
• 化学反应性: 族号是预测元素化学行为（如形成的离子电荷、常见的氧化态、形成的化合物类型）的重要指标。

总结: group 属性提供了原子在元素周期表中的垂直位置（列），是理解其化学性质和反应性的关键信息。

is_metal 属性详解

• 类型: bool（布尔值）
• 描述: 该属性判断一个原子是否为金属元素。它返回一个布尔值：True 表示是金属，False 表示不是金属（即非金属或类金属）。
• 分类依据: 根据文档说明，其判断标准基于一个特定的定义：包括镓（Ga）、锡（Sn）、铋（Bi）以及所有在它们之前的金属元素。这通常涵盖了周期表中大部分典型的金属区域，包括碱金属、碱土金属、过渡金属、镧系、锕系以及部分主族金属（如 Al, Ga, Sn, Pb, Bi 等）。
• 只读: 这是一个只读属性，由原子的元素符号（atomic_symbol）决定，无法修改。

示例

import autode as ade# 创建金属原子
sodium = ade.Atom('Na')    # 碱金属
iron = ade.Atom('Fe')      # 过渡金属
aluminum = ade.Atom('Al')  # 主族金属
zinc = ade.Atom('Zn')      # 过渡后金属# 创建非金属原子
carbon = ade.Atom('C')     # 非金属
oxygen = ade.Atom('O')     # 非金属
chlorine = ade.Atom('Cl')  # 卤素 (非金属)
argon = ade.Atom('Ar')     # 稀有气体 (非金属)# 访问 is_metal 属性
print(f"钠 (Na) 是金属吗? {sodium.is_metal}")      # 输出: True
print(f"铁 (Fe) 是金属吗? {iron.is_metal}")        # 输出: True
print(f"铝 (Al) 是金属吗? {aluminum.is_metal}")    # 输出: True
print(f"锌 (Zn) 是金属吗? {zinc.is_metal}")        # 输出: Trueprint(f"碳 (C) 是金属吗? {carbon.is_metal}")       # 输出: False
print(f"氧 (O) 是金属吗? {oxygen.is_metal}")       # 输出: False
print(f"氯 (Cl) 是金属吗? {chlorine.is_metal}")    # 输出: False
print(f"氩 (Ar) 是金属吗? {argon.is_metal}")       # 输出: False

总结
is_metal 是一个便捷的布尔属性，用于快速判断 autode.atoms.Atom 对象所代表的元素是否属于金属类别，有助于在程序中根据元素类型进行逻辑分支处理。

is_pi(valency: int) -> bool 方法详解

is_pi(valency: int) -> bool 是一个方法，用于近似判断一个原子是否为“π-原子”，即是否处于不饱和状态（可能参与形成双键、三键或具有孤对电子，导致存在π型轨道或受限旋转）。

• 参数:
  valency (int) - 需要传入该原子当前的化合价（即已经形成的化学键的数量）。

• 返回值:
  True：如果该原子在给定化合价下可能是不饱和的；
  False：则认为是饱和的。

• 用途:
  在生成分子图（molecular graph）或分析反应机理时，帮助识别可能涉及π键的原子。

• 注意:
  文档明确指出这是一个近似判断，并非精确的量子化学计算。

---

示例:

• Atom('C').is_pi(valency=3) 返回 True（如烯基中的碳）
• Atom('H').is_pi(valency=1) 返回 False

mass 属性详解

• 类型: autode.values.Mass
• 描述: 该属性返回原子的质量（Mass）。它是 weight 属性的一个别名，两者完全等价且值相同。
• 单位: 默认单位是原子质量单位（amu 或 Da）。
• 只读: 这是一个只读属性，其值由原子的元素类型（atomic_symbol）决定，无法修改。
• 物理意义: 表示该原子核与电子的总静止质量，通常使用元素在自然界中同位素丰度的加权平均值。

访问质量

import autode as adehydrogen = ade.Atom('H')
carbon = ade.Atom('C')
oxygen = ade.Atom('O')print(f"氢的质量: {hydrogen.mass}")  # 输出: Mass(1.00794 amu)
print(f"碳的质量: {carbon.mass}")    # 输出: Mass(12.0107 amu)
print(f"氧的质量: {oxygen.mass}")   # 输出: Mass(15.999 amu)

单位转换
Mass 对象支持 .to() 方法进行单位转换，非常灵活。

# 转换为千克 (kg)
mass_in_kg = carbon.mass.to('kg')
print(f"碳的质量 (kg): {mass_in_kg}")  # 输出: e.g., Mass(1.99442e-26 kg)# 转换为电子质量 (m_e)
mass_in_me = hydrogen.mass.to('me')
print(f"氢的质量 (m_e): {mass_in_me}")  # 输出: Mass(1837.36222 m_e)# 验证与 weight 相等
print(carbon.mass == carbon.weight)  # 输出: True

计算分子量
在 AtomCollection（如 Molecule）中，mass 属性用于计算整个分子的总质量。

water = ade.Molecule(atoms=[ade.Atom('O'), ade.Atom('H', x=0.96), ade.Atom('H', y=0.96)])
print(f"水分子的质量: {water.mass}")  # 输出: 分子总质量 (~18.015 amu)

maximal_valance 属性详解

maximal_valance 是 autode.atoms.Atom 类的一个只读属性，返回一个整数。

• 描述:
  它表示该原子在任何电荷状态下所能支持的最大化合价（即能形成化学键的最大数量）。这个值基于元素的常见化学行为确定，不依赖于原子当前的具体成键情况。

• 主要用途:
  在生成分子拓扑结构（molecular graph）时，用于确定一个原子最多可以连接多少个其他原子，是构建分子连接性的重要依据。
  示例：

• Atom('H').maximal_valance 返回 1（氢最多形成 1 个键）。

• Atom('C').maximal_valance 返回 4（碳最多形成 4 个键）。

• Atom('O').maximal_valance 返回 2（氧最多形成 2 个键）。

• Atom('P').maximal_valance 可能返回 5（磷可以形成 5 个键，如在 PCl₅ 中）。

✅ 注意：该值反映的是理论上的最大成键能力，而非实际成键数。

period 属性详解

period 是 autode.atoms.Atom 类的一个只读属性，返回一个整数。

• 描述:
  它表示该原子在元素周期表中的周期（Period），即周期表中的行。周期数反映了原子电子层（主量子数）的数量。
• 值:
  通常为 1 到 7，对应元素周期表的七个周期。
• 错误处理:
  如果元素未找到，则返回 0。

示例：

• Atom('H').period 或 Atom('He').period 返回 1（第一周期）。
• Atom('C').period 或 Atom('O').period 返回 2（第二周期）。
• Atom('Na').period 返回 3（第三周期）。
• Atom('Fe').period 返回 4（第四周期）。

✅ 周期信息有助于理解原子的电子排布和化学性质趋势。

tm_row 属性详解

tm_row 是 autode.atoms.Atom 类的一个只读属性，返回一个整数或 None。

• 功能:
  如果该原子是过渡金属（Transition Metal），则返回其在周期表中的行数（1、2 或 3）；否则返回 None。
• 返回值说明:
  • 1: 对应第一行过渡金属（Sc 到 Zn）。
  • 2: 对应第二行过渡金属（Y 到 Cd）。
  • 3: 对应第三行过渡金属（La, Hf 到 Hg）。
  • None: 如果该原子不是过渡金属。

示例：

• Atom('Fe').tm_row 返回 1（铁属于第一行过渡金属）。
• Atom('Y').tm_row 返回 2（钇属于第二行过渡金属）。
• Atom('Hf').tm_row 返回 3（铪属于第三行过渡金属）。
• Atom('C').tm_row 返回 None（碳不是过渡金属）。

✅ 该属性有助于识别和分类过渡金属元素，在处理配位化学、催化反应等场景中非常有用。

vdw_radius 属性详解

vdw_radius 是 autode.atoms.Atom 类的一个只读属性，返回一个 autode.values.Distance 对象。

• 描述:
  表示原子的范德华半径（Van der Waals Radius）。
• 单位:
  默认单位是埃（Å），即 1 Å = 10⁻¹⁰ 米。
• 物理意义:
  范德华半径衡量了原子在非键合相互作用（如范德华力）中的有效大小。它近似于原子“硬球”模型的半径，反映了原子在分子间作用中所占据的空间范围。
• 用途:
  常用于判断两个非键合原子是否发生空间位阻或接触。
  当两个原子之间的距离小于它们范德华半径之和时，通常认为存在显著的空间排斥，可能影响分子构象稳定性或反应活性。

示例：

carbon = ade.Atom('C')
oxygen = ade.Atom('O')print(f"碳的范德华半径: {carbon.vdw_radius}")  # 输出: e.g., Distance(1.70 Å)
print(f"氧的范德华半径: {oxygen.vdw_radius}")  # 输出: e.g., Distance(1.52 Å)

weight 属性详解

weight 是 autode.atoms.Atom 类的一个只读属性，返回一个 autode.values.Mass 对象。

• 描述:
  表示原子的质量（Mass），与 mass 属性完全相同且等价。
• 单位:
  默认单位是原子质量单位（amu，即 atomic mass unit）。
• 说明:
  weight 和 mass 是同一个属性的两个别名。在 autoDE 库中，两者可以互换使用，都提供原子的原子量（atomic weight）。

示例：

import autode as ade
atom = ade.Atom('C')
print(atom.weight)    # 输出: Mass(12.0107 amu)
print(atom.mass)      # 输出: Mass(12.0107 amu)
print(atom.weight == atom.mass)  # 输出: True

---

类方法介绍

copy()方法

• 签名: copy() -> Atom
• 返回类型: 返回一个 autode.atoms.Atom 类的新实例。
• 功能: 创建并返回当前 Atom 对象的一个深拷贝（deep copy）。

核心概念：深拷贝 (Deep Copy)

• 新对象: copy() 方法会创建一个全新的 Atom 对象，它在内存中占据独立的空间。
• 独立性: 新对象（副本）与原对象（被拷贝的对象）完全独立。对副本的任何修改（如改变坐标、修改 atom_class 等）不会影响原始对象，反之亦然。
• 数据复制: 副本拥有与原对象完全相同的数据，包括：
  • 元素符号（atomic_symbol）
  • 三维坐标（x, y, z）
  • 原子类别（atom_class）
  • 部分电荷（partial_charge）

为什么需要 copy()？

在计算化学中，经常需要对分子结构进行操作（如优化、扫描、生成过渡态等）。直接修改原始结构可能会导致数据丢失或逻辑错误。使用 copy() 可以：

• 保留原始构型: 在进行修改前保存一个“快照”。
• 进行安全操作: 在副本上进行试验性操作，而不影响原始数据。
• 并行处理: 为不同的计算任务提供相同起始结构的独立副本。

示例:

import autode as ade# 1. 创建原始原子
original = ade.Atom('O', 0.0, 0.0, 0.0, atom_class=2, partial_charge=-0.5)
print(f"原始原子: {original}")  # Atom(O, 0.0000, 0.0000, 0.0000, class=2, charge=-0.5)# 2. 创建副本
copied = original.copy()  # ← 调用 copy() 方法
print(f"副本原子: {copied}")  # Atom(O, 0.0000, 0.0000, 0.0000, class=2, charge=-0.5)# 3. 验证是不同对象
print(f"是同一个对象吗? {original is copied}")  # 输出: False# 4. 修改副本
copied.translate(1.0, 1.0, 1.0)      # 移动副本
copied.atom_class = 99                # 修改副本的类别# 5. 检查影响
print(f"修改后原始原子: {original}")  # Atom(O, 0.0000, 0.0000, 0.0000, class=2, charge=-0.5) ← 未变
print(f"修改后副本: {copied}")       # Atom(O, 1.0000, 1.0000, 1.0000, class=99, charge=-0.5) ← 已变

总结

copy() 是一个非常实用的方法，它通过创建一个完全独立的、数据相同的原子副本，确保了数据操作的安全性和可追溯性。在需要保留原始结构或进行并行计算时，它是必不可少的工具。

rotate() 方法详解

• 签名:
  rotate(axis: ndarray | Sequence, theta: Angle | float, origin: ndarray | Sequence | None = None) -> None

• 功能:
  围绕指定的轴和中心点，将原子在三维空间中旋转一个给定的角度。这是一个原地操作（in-place operation），即直接修改调用该方法的原子对象的坐标，不返回新对象。

• 参数说明:

  • axis: 旋转轴的方向向量，可以是 ndarray 或序列（如 [1, 0, 0] 表示 x 轴）。
  • theta: 旋转角度，支持 Angle 类型或浮点数（单位通常为弧度或度，取决于上下文）。
  • origin: 旋转中心点的坐标（默认为原点 (0, 0, 0)），可选。

• 返回值:
  None —— 因为是原地修改，无返回值。

---

示例（概念性）：

import autode as ade
from autode.values import Angle
import numpy as np# 创建一个位于 (1.0, 0.0, 0.0) 的氢原子
atom = ade.Atom('H', 1.0, 0.0, 0.0)
print(f"初始坐标: {atom.coord}")  # Coordinate([1. 0. 0.] Å)# 1. 绕 z 轴旋转 180 度 (使用 Angle 对象指定度)
atom.rotate(axis=[0.0, 0.0, 1.0], theta=Angle(180, 'deg'))
print(f"绕 z 轴转 180° 后: {atom.coord}")  # Coordinate([-1. -0.  0.] Å)# 重置位置
atom.coord = [1.0, 0.0, 0.0]# 2. 绕 y 轴旋转 π 弧度 (使用 float, 单位为弧度)
atom.rotate(axis=[0.0, 1.0, 0.0], theta=np.pi)
print(f"绕 y 轴转 π 弧度后: {atom.coord}")  # Coordinate([-1.  0. -0.] Å)# 3. 绕 z 轴旋转 90 度，但以 (1.0, 0.0, 0.0) 为旋转中心
#    这会使原子绕着自己旋转，位置不变
atom.rotate(axis=[0.0, 0.0, 1.0], theta=Angle(90, 'deg'), origin=[1.0, 0.0, 0.0])
print(f"绕自身 (1,0,0) 转 90° 后: {atom.coord}")  # Coordinate([1. 0. 0.] Å) (位置不变)

总结
rotate() 方法提供了对单个原子进行精确三维旋转的能力。通过指定旋转轴、角度和可选的中心点，可以灵活地调整原子的几何构型，是构建和操作分子结构的有力工具。
关键要点：

• 它是一个原地修改（in-place operation）操作，会直接改变原子的 coord 属性。
• 无返回值，修改的是调用对象本身。
• 适用于需要精细控制原子位置的分子建模与几何优化场景。

✅ 使用时请注意：若需保留原始坐标，应提前备份或复制原子对象。

translate() 方法详解

• 签名:
  translate(*args, **kwargs) -> None
• 功能:
  沿指定的向量将原子在三维空间中进行平移（移动）。这是一个原地操作（in-place operation），即直接修改调用该方法的原子对象的坐标，不返回新对象。
• 参数说明:
  • 支持多种输入方式，例如：
    • translate(x=1.0, y=2.0, z=3.0)：按分量平移。
    • translate([1.0, 2.0, 3.0])：按向量平移。
  • 具体支持的形式取决于实现细节，通常可接受 ndarray、Sequence 或关键字参数。
• 返回值:
  None —— 因为是原地修改，无返回值。

示例（概念性）：

import autode as ade
import numpy as np# 创建一个位于原点的碳原子
atom = ade.Atom('C', 0.0, 0.0, 0.0)
print(f"初始坐标: {atom.coord}")  # Coordinate([0. 0. 0.] Å)# 1. 使用位置参数平移 (x+1, y+2, z+3)
atom.translate(1.0, 2.0, 3.0)
print(f"位置参数平移后: {atom.coord}")  # Coordinate([1. 2. 3.] Å)# 2. 使用关键字参数和列表平移
atom.translate(vec=[-0.5, -1.0, -1.5])
print(f"列表平移后: {atom.coord}")  # Coordinate([0.5 1.  1.5] Å)# 3. 使用 numpy 数组进行平移 (例如，移动回原点)
move_back = -atom.coord  # 创建反向向量
atom.translate(vec=move_back)
print(f"numpy 数组平移后: {atom.coord}")  # Coordinate([0. 0. 0.] Å)