13.2.1. 快速距离数组计算 `MDAnalysis.lib.distances`

从坐标数组计算距离数组或角度数组的快速C例程。距离函数可以接受NumPy np.ndarray 或者是一个 AtomGroup 。许多函数也存在于并行版本中，它们通常提供比串行码更高的性能。布尔属性 MDAnalysis.lib.distances.USED_OPENMP 可以查看在编译MDAnalysis时是否使用了OpenMP。

13.2.1.1. 选择加速(“后台”)

所有函数都使用OPTIONAL关键字 backend ，它决定了加速的类型。目前，实现了以下选择 (backend 不区分大小写)：

可用后端用于加速距离函数。
后端	模块	描述
《连载》	`c_distances`	C/Cython语言中的串口实现
“OpenMP”	`c_distances_openmp`	OpenMP在C/Cython中的并行实现

13.2.1.2. Destopia类库的使用

MDAnalysis开发了一个独立库， distopia 使用显式SIMD矢量化加速此模块中的距离函数。这可以在计算距离时提供成倍的加速。Disopia正在积极开发中，因此只介绍了本模块中的部分功能。请参考下表，查看您希望使用的功能是否包含在Disopia中。有关更多信息，请参阅 distopia documentation 。

可使用的功能 distopia 后端。
功能	注意事项
MDAnalysis.lib.distances.calc_bonds	不支持三斜线盒

如果 distopia ，则此表中的函数将接受 backend 关键字参数。如果选择了Disopia后端， distopia 库将用于计算距离。请注意，对于此表中列出的函数 distopia is not the default backend if and must be selected.

备注

Disopia目前不支持Triclinic模拟盒。如果您指定 distopia 由于后端和您的模拟框是Triclinic的，因此该函数将回退到默认设置 serial 后端。

备注

由于使用了指令集体系结构 (ISA) 远视中的特定SIMD固有基因 VCL2 ，结果的精度可能取决于您的计算机上可用的ISA。然而，在所有测试的情况下，视差都达到了用于该模块中的功能的准确度阈值。请将您遇到的任何与Disopia的准确性有关的问题记录在 relevant distopia issue 在MDAnalysis GitHub存储库上。

在 0.13.0 版本加入.

在 2.3.0 版本发生变更: 距离函数现在可以接受 AtomGroup 或者是一个 np.ndarray

在 2.5.0 版本发生变更: 接口连接到 distopia 已添加包。

13.2.1.3. 功能

MDAnalysis.lib.distances.distance_array(reference: ndarray[Any, dtype[_ScalarType_co]] | AtomGroup, configuration: ndarray[Any, dtype[_ScalarType_co]] | AtomGroup, box: ndarray[Any, dtype[_ScalarType_co]] | None = None, result: ndarray[Any, dtype[_ScalarType_co]] | None = None, backend: str = 'serial') → ndarray[Any, dtype[_ScalarType_co]][源代码]

计算参考集和另一配置之间的所有可能距离。

如果有 n 职位在 reference 和 m 职位在 configuration ，形状的距离数组 (n, m) 将会被计算出来。

如果可选参数 box ，则在计算距离时应用最小图像约定。支持正交盒或三斜盒。

如果数据类型2DNumPy数组 numpy.float64 其形状为 (n, m) 中提供的 result ，则填充该预分配的数组。这可以加快计算速度。

参数:

reference (numpy.ndarray or AtomGroup) -- 形状的参考坐标数组 (3,) 或 (n, 3) (数据类型是任意的，将被转换为 numpy.float32 内部)。还接受一个 AtomGroup 。
configuration (numpy.ndarray or AtomGroup) -- 形状的配置坐标数组 (3,) 或 (m, 3) (数据类型是任意的，将被转换为 numpy.float32 内部)。还接受一个 AtomGroup 。
box (array_like, optional) -- 系统的单位单元尺寸，可以是正交的或三斜的，并且必须以与返回的相同格式提供 MDAnalysis.coordinates.timestep.Timestep.dimensions ： [lx, ly, lz, alpha, beta, gamma] 。
result (numpy.ndarray, optional) -- 必须具有以下形状的预分配结果数组 (n, m) 和数据类型 numpy.float64 。避免在重复调用函数时创建可节省时间的数组。
backend ({'serial', 'OpenMP'}, optional) -- 关键字选择加速类型。

返回:

d --包含距离的数组 d[i,j] 在参考坐标之间 i 和配置坐标 j 。

返回类型:

numpy.ndarray (dtype=numpy.float64 ， shape=(n, m) )

在 0.13.0 版本发生变更: 已添加后端关键字。

在 0.19.0 版本发生变更: 将输入坐标的内部数据类型转换为 numpy.float32 。现在还接受单个坐标作为输入。

在 2.3.0 版本发生变更: 现在可以接受 AtomGroup 作为任意位置的参数，并使用类型提示检查输入。

MDAnalysis.lib.distances.self_distance_array(reference: ndarray[Any, dtype[_ScalarType_co]] | AtomGroup, box: ndarray[Any, dtype[_ScalarType_co]] | None = None, result: ndarray[Any, dtype[_ScalarType_co]] | None = None, backend: str = 'serial') → ndarray[Any, dtype[_ScalarType_co]][源代码]

计算配置内所有可能的距离 reference 。

如果可选参数 box ，则在计算距离时应用最小图像约定。支持正交盒或三斜盒。

如果数据类型1DNumy数组 numpy.float64 其形状为 (n*(n-1)/2,) 中提供的 result ，则填充该预分配的数组。这可以加快计算速度。

参数:

reference (numpy.ndarray or AtomGroup) -- 形状的参考坐标数组 (3,) 或 (n, 3) (数据类型是任意的，将被转换为 numpy.float32 内部)。还接受一个 AtomGroup 。
box (array_like, optional) -- 系统的单位单元尺寸，可以是正交的或三斜的，并且必须以与返回的相同格式提供 MDAnalysis.coordinates.timestep.Timestep.dimensions ： [lx, ly, lz, alpha, beta, gamma] 。
result (numpy.ndarray, optional) -- 必须具有以下形状的预分配结果数组 (n*(n-1)/2,) 和数据类型 numpy.float64 。避免在重复调用函数时创建可节省时间的数组。
backend ({'serial', 'OpenMP'}, optional) -- 关键字选择加速类型。

返回:

d --包含距离的数组 dist[i,j] 在参考坐标之间 i 和 j 在位置 d[k] 。循环通过 d ：..范围(N)中i的代码块：：Python：范围(i+1，n)中的j的代码块：k+=1距离 [i, j] =d [k]

返回类型:

numpy.ndarray (dtype=numpy.float64 ， shape=(n*(n-1)/2,) )

在 0.13.0 版本发生变更: 已添加后端关键字。

在 0.19.0 版本发生变更: 将输入坐标的内部数据类型转换为 numpy.float32 。

在 2.3.0 版本发生变更: 现在可以接受 AtomGroup 作为任意位置的参数，并使用类型提示检查输入。

MDAnalysis.lib.distances.capped_distance(reference: ndarray[Any, dtype[_ScalarType_co]] | AtomGroup, configuration: ndarray[Any, dtype[_ScalarType_co]] | AtomGroup, max_cutoff: float, min_cutoff: float | None = None, box: ndarray[Any, dtype[_ScalarType_co]] | None = None, method: str | None = None, return_distances: bool | None = True)[源代码]

中的条目对应的索引对。 reference 和 configuration 在指定的截止点内相隔一定距离的数组。或者，也可以返回这些距离。

如果可选参数 box ，则在计算距离时应用最小图像约定。支持正交盒或三斜盒。

该功能包括自动猜测计算距离的最佳方法。还提供了该方法的可选关键字。用户可以使用此功能强制使用特定方法。目前实现了暴力、网格搜索和周期性的KDtree方法。

参数:

reference (numpy.ndarray or AtomGroup) -- 带形状的参考坐标数组 (3,) 或 (n, 3) 。还接受一个 AtomGroup 。
configuration (numpy.ndarray or AtomGroup) -- 带形状的构形坐标数组 (3,) 或 (m, 3) 。还接受一个 AtomGroup 。
max_cutoff (float) -- 参考和配置之间的最大截止距离。
min_cutoff (float, optional) -- 参考和配置之间的最小截止距离。
box (array_like, optional) -- 系统的单位单元尺寸，可以是正交的或三斜的，并且必须以与返回的相同格式提供 MDAnalysis.coordinates.timestep.Timestep.dimensions ： [lx, ly, lz, alpha, beta, gamma] 。
method ({'bruteforce', 'nsgrid', 'pkdtree'}, optional) -- 关键字来覆盖所采用的搜索方法的自动猜测。
return_distances (bool, optional) -- 如果设置为 True ，距离也将返回。

返回:

成对 (数字.ndarray (dtype=numpy.int64 ， shape=(n_pairs, 2) )--索引对，对应于 reference 和 configuration 数组，使它们之间的距离在间隔内 (min_cutoff ， max_cutoff ]。中的每行 pairs 是索引对 [i, j] 对应于 i -TH坐标在 reference 以及 j -TH坐标在 configuration 。

距离 (数字.ndarray (dtype=numpy.float64 ， shape=(n_pairs,) )，可选)--对应于每对索引的距离。仅在以下情况下返回 return_distances 是 True 。 distances[k] 对应于 k -返回的第1对 pairs 并给出坐标之间的距离 reference[pairs[k, 0]] 和 configuration[pairs[k, 1]] 。

pairs, distances = capped_distances(reference, configuration,
                                    max_cutoff, return_distances=True)
for k, [i, j] in enumerate(pairs):
    coord1 = reference[i]
    coord2 = configuration[j]
    distance = distances[k]

参见

distance_array, MDAnalysis.lib.pkdtree.PeriodicKDTree.search, MDAnalysis.lib.nsgrid.FastNS.search

在 1.0.1 版本发生变更: 由于与可靠性和准确性有关的问题，nsgrid已暂时删除，并替换为pkdtree(问题#2919、#2229、#2345、#2670、#2930)

在 1.0.2 版本发生变更: Nsgrid再次启用

在 2.3.0 版本发生变更: 现在可以接受 AtomGroup 作为任意位置的参数，并使用类型提示检查输入。

MDAnalysis.lib.distances.self_capped_distance(reference: ndarray[Any, dtype[_ScalarType_co]] | AtomGroup, max_cutoff: float, min_cutoff: float | None = None, box: ndarray[Any, dtype[_ScalarType_co]] | None = None, method: str | None = None, return_distances: bool | None = True)[源代码]

中的条目对应的索引对。 reference 数组，这些数组由位于指定截止点内的距离分隔。或者，也可以返回这些距离。

如果可选参数 box ，则在计算距离时应用最小图像约定。支持正交盒或三斜盒。

该功能包括自动猜测计算距离的最佳方法。还提供了该方法的可选关键字。用户可以使用此功能强制使用特定方法。目前实现了暴力、网格搜索和周期性的KDtree方法。

参数:

reference (numpy.ndarray or AtomGroup) -- 带形状的参考坐标数组 (3,) 或 (n, 3) 。还接受一个 AtomGroup 。
max_cutoff (float) -- 之间的最大截止距离 reference 坐标。
min_cutoff (float, optional) -- 之间的最小截止距离 reference 坐标。
box (array_like, optional) -- 系统的单位单元尺寸，可以是正交的或三斜的，并且必须以与返回的相同格式提供 MDAnalysis.coordinates.timestep.Timestep.dimensions ： [lx, ly, lz, alpha, beta, gamma] 。
method ({'bruteforce', 'nsgrid', 'pkdtree'}, optional) -- 关键字来覆盖所采用的搜索方法的自动猜测。
return_distances (bool, optional) -- 如果设置为 True ，距离也将返回。

返回:

成对 (数字.ndarray (dtype=numpy.int64 ， shape=(n_pairs, 2) )--索引对，对应于 reference 数组，以使它们之间的距离在间隔内 (min_cutoff ， max_cutoff ]。中的每行 pairs 是索引对 [i, j] 对应于 i -TH和 j -TH坐标在 reference 。

距离 (数字.ndarray (dtype=numpy.float64 ， shape=(n_pairs,) ))--对应于每对索引的距离。仅在以下情况下返回 return_distances 是 True 。 distances[k] 对应于 k -返回的第1对 pairs 并给出坐标之间的距离 reference[pairs[k, 0]] 和 reference[pairs[k, 1]] 。

pairs, distances = self_capped_distances(reference, max_cutoff,
                                         return_distances=True)
for k, [i, j] in enumerate(pairs):
    coord1 = reference[i]
    coord2 = reference[j]
    distance = distances[k]

备注

目前支持暴力、基于网格和周期性的KDtree搜索方法。

参见

self_distance_array, MDAnalysis.lib.pkdtree.PeriodicKDTree.search, MDAnalysis.lib.nsgrid.FastNS.self_search

在 0.20.0 版本发生变更: 已添加 return_distances 关键字。

在 1.0.1 版本发生变更: 由于与可靠性和准确性有关的问题，nsgrid已暂时删除，并替换为pkdtree(问题#2919、#2229、#2345、#2670、#2930)

在 1.0.2 版本发生变更: 再次启用nsgrid

在 2.3.0 版本发生变更: 现在可以接受 AtomGroup 作为任意位置的参数，并使用类型提示检查输入。

MDAnalysis.lib.distances.calc_bonds(coords1: ndarray[Any, dtype[_ScalarType_co]] | AtomGroup, coords2: ndarray[Any, dtype[_ScalarType_co]] | AtomGroup, box: ndarray[Any, dtype[_ScalarType_co]] | None = None, result: ndarray[Any, dtype[_ScalarType_co]] | None = None, backend: str = 'serial') → ndarray[Any, dtype[_ScalarType_co]][源代码]

从两个坐标数组计算原子位置对之间的键长 coords1 和 coords2 ，它必须包含相同数量的坐标。 coords1[i] 和 coords2[i] 连接的原子的位置。 i -TH债券。如果提供单一坐标，则返回单一距离。

与之相比 distance_array() 和 self_distance_array() ，它计算所有可能的坐标组合之间的距离， calc_bonds() 仅计算成对坐标之间的距离，类似于：

numpy.linalg.norm(a - b) for a, b in zip(coords1, coords2)

如果可选参数 box ，则在计算距离时应用最小图像约定。支持正交盒或三斜盒。

如果数据类型Numy数组 numpy.float64 有形状的 (n,) (为 n 坐标对)在中提供 result ，则填充该预分配的数组。这可以加快计算速度。

参数:

coords1 (numpy.ndarray or AtomGroup) -- 形状的坐标数组 (3,) 或 (n, 3) 单曲的一半或 n 债券(dtype是任意的，将分别转换为 numpy.float32 内部)。还接受一个 AtomGroup 。
coords2 (numpy.ndarray or AtomGroup) -- 形状的坐标数组 (3,) 或 (n, 3) 单曲的另一半或 n 债券(dtype是任意的，将分别转换为 numpy.float32 内部)。还接受一个 AtomGroup 。
box (numpy.ndarray, optional) -- 系统的单位单元尺寸，可以是正交的或三斜的，并且必须以与返回的相同格式提供 MDAnalysis.coordinates.timestep.Timestep.dimensions ： [lx, ly, lz, alpha, beta, gamma] 。
result (numpy.ndarray, optional) -- 数据类型的预分配结果数组 numpy.float64 和形状 (n,) (为 n 坐标对)。避免在重复的函数调用中重新创建数组。
backend ({'serial', 'OpenMP', 'distopia'}, optional) -- 关键字选择加速类型。默认为‘Serial’。

返回:

bondlengths --NUMPY.FLOAT64包含每对坐标之间的键合长度的数组。如果提供了两个单独的坐标，则它们的距离将以单个数字而不是数组的形式返回。

返回类型:

numpy.ndarray (dtype=numpy.float64 ， shape=(n,) )或

在 0.8 版本加入.

在 0.13.0 版本发生变更: 已添加后端关键字。

在 0.19.0 版本发生变更: 将输入坐标的内部数据类型转换为 numpy.float32 。现在还接受单个坐标作为输入。

在 2.3.0 版本发生变更: 现在可以接受 AtomGroup 作为任意位置的参数，并使用类型提示检查输入。

在 2.5.0 版本发生变更: 现在可以选择使用距离较远的快速距离功能

MDAnalysis.lib.distances.calc_angles(coords1: ndarray[Any, dtype[_ScalarType_co]] | AtomGroup, coords2: ndarray[Any, dtype[_ScalarType_co]] | AtomGroup, coords3: ndarray[Any, dtype[_ScalarType_co]] | AtomGroup, box: ndarray[Any, dtype[_ScalarType_co]] | None = None, result: ndarray[Any, dtype[_ScalarType_co]] | None = None, backend: str = 'serial') → ndarray[Any, dtype[_ScalarType_co]][源代码]

从三个坐标数组计算原子位置的三元组之间形成的角度 coords1 ， coords2 ，以及 coords3 。所有坐标数组必须包含相同数量的坐标。

中的坐标 coords2 表示角度的顶点：：

  2---3
 /
1

角度未定义的配置(例如，当三元组的坐标1或3与坐标2重合时)会产生值 zero 为了那个角度。

如果可选参数 box ，则在构造坐标之间的连接向量时考虑周期边界，即，对形成角度的向量应用最小图像约定。支持正交盒或三斜盒。

如果数据类型Numy数组 numpy.float64 有形状的 (n,) (为 n 坐标三元组)在中提供 result ，则填充该预分配的数组。这可以加快计算速度。

参数:

coords1 (numpy.ndarray or AtomGroup) -- 形状数组 (3,) 或 (n, 3) 包含单个或多个 n 角度(dtype是任意的，将被转换为 numpy.float32 内部)。还接受一个 AtomGroup 。
coords2 (numpy.ndarray or AtomGroup) -- 形状数组 (3,) 或 (n, 3) 包含单个或多个 n 角度(dtype是任意的，将被转换为 numpy.float32 内部)。还接受一个 AtomGroup 。
coords3 (numpy.ndarray or AtomGroup) -- 形状数组 (3,) 或 (n, 3) 包含单个或多个 n 角度(dtype是任意的，将被转换为 numpy.float32 内部)。还接受一个 AtomGroup 。
box (numpy.ndarray, optional) -- 系统的单位单元尺寸，可以是正交的或三斜的，并且必须以与返回的相同格式提供 MDAnalysis.coordinates.timestep.Timestep.dimensions ： [lx, ly, lz, alpha, beta, gamma] 。
result (numpy.ndarray, optional) -- 数据类型的预分配结果数组 numpy.float64 和形状 (n,) (为 n 坐标三元组)。避免在重复的函数调用中重新创建数组。
backend ({'serial', 'OpenMP'}, optional) -- 关键字选择加速类型。

返回:

角度 --包含每个三元组坐标之间的角度的数组。返回值以弧度(Rad)为单位。如果提供了三个单独的坐标，则以单个数字而不是数组的形式返回角度。

返回类型:

numpy.ndarray (dtype=numpy.float64 ， shape=(n,) )或umpy.flat64

在 0.8 版本加入.

在 0.9.0 版本发生变更: 添加了可选的框参数，以说明计算中的周期边界

在 0.13.0 版本发生变更: 已添加后端关键字。

在 0.19.0 版本发生变更: 将输入坐标的内部数据类型转换为 numpy.float32 。现在还接受单个坐标作为输入。

在 2.3.0 版本发生变更: 现在可以接受 AtomGroup 作为任意位置的参数，并使用类型提示检查输入。

MDAnalysis.lib.distances.calc_dihedrals(coords1: ndarray[Any, dtype[_ScalarType_co]] | AtomGroup, coords2: ndarray[Any, dtype[_ScalarType_co]] | AtomGroup, coords3: ndarray[Any, dtype[_ScalarType_co]] | AtomGroup, coords4: ndarray[Any, dtype[_ScalarType_co]] | AtomGroup, box: ndarray[Any, dtype[_ScalarType_co]] | None = None, result: ndarray[Any, dtype[_ScalarType_co]] | None = None, backend: str = 'serial') → ndarray[Any, dtype[_ScalarType_co]][源代码]

从四个坐标数组计算位置四元组之间形成的二面角 coords1 ， coords2 ， coords3 ，以及 coords4 ，它必须包含相同数量的坐标。

四元组位置(1，2，3，4)形成的二面角是围绕连接位置2和3的轴(即位置(1，2，3)和(2，3，4)跨越的平面之间的角度)计算的：

        4
        |
  2-----3
 /
1

如果所有坐标都位于同一平面上，则顺式构形对应于二面角零，反式构形对应于 \(\pi\) 弧度(180度)。未定义二面角的配置(例如，当所有坐标都位于同一条直线上时)会产生值 nan (不是一个数字)表示该二面体。

如果可选参数 box ，则在构造坐标之间的连接向量时考虑周期边界，即，对形成二面角的向量应用最小图像约定。支持正交盒或三斜盒。

如果数据类型Numy数组 numpy.float64 有形状的 (n,) (为 n 坐标四胞胎)在中提供 result 则填充该预分配的数组。这可以加快计算速度。

参数:

coords1 (numpy.ndarray or AtomGroup) -- 形状的坐标数组 (3,) 或 (n, 3) 包含二面体中的第一个位置(dtype为任意类型，将转换为 numpy.float32 内部)。还接受一个 AtomGroup 。
coords2 (numpy.ndarray or AtomGroup) -- 形状的坐标数组 (3,) 或 (n, 3) 包含二面体中的第二个位置(dtype是任意的，将被转换为 numpy.float32 内部)。还接受一个 AtomGroup 。
coords3 (numpy.ndarray or AtomGroup) -- 形状的坐标数组 (3,) 或 (n, 3) 包含二面体中的第三个位置(dtype为任意类型，将转换为 numpy.float32 内部)。还接受一个 AtomGroup 。
coords4 (numpy.ndarray or AtomGroup) -- 形状的坐标数组 (3,) 或 (n, 3) 包含二面体中的第4个位置(dtype为任意类型，将转换为 numpy.float32 内部)。还接受一个 AtomGroup 。
box (numpy.ndarray, optional) -- 系统的单位单元尺寸，可以是正交的或三斜的，并且必须以与返回的相同格式提供 MDAnalysis.coordinates.timestep.Timestep.dimensions ： [lx, ly, lz, alpha, beta, gamma] 。
result (numpy.ndarray, optional) -- 数据类型的预分配结果数组 numpy.float64 和形状 (n,) (为 n 坐标四胞胎)。避免在重复的函数调用中重新创建数组。
backend ({'serial', 'OpenMP'}, optional) -- 关键字选择加速类型。

返回:

dihedrals --包含每个四元组坐标形成的二面角的数组。返回值以弧度(Rad)为单位。如果提供了四个单一坐标，则以单个数字而不是数组的形式返回二面角。二面角的范围是 \((-\pi, \pi)\) 。

返回类型:

numpy.ndarray (dtype=numpy.float64 ， shape=(n,) )或umpy.flat64

在 0.8 版本加入.

在 0.9.0 版本发生变更: 添加了可选的框参数，以说明计算中的周期边界

在 0.11.0 版本发生变更: 已从calc_torsions重命名为calc_dihedrals

在 0.13.0 版本发生变更: 已添加后端关键字。

在 0.19.0 版本发生变更: 将输入坐标的内部数据类型转换为 numpy.float32 。现在还接受单个坐标作为输入。

在 2.3.0 版本发生变更: 现在可以接受 AtomGroup 作为任意位置的参数，并使用类型提示检查输入。

MDAnalysis.lib.distances.apply_PBC(coords: ndarray[Any, dtype[_ScalarType_co]] | AtomGroup, box: ndarray[Any, dtype[_ScalarType_co]] | None = None, backend: str = 'serial') → ndarray[Any, dtype[_ScalarType_co]][源代码]

将坐标移到主单位单元格中。

参数:

coords (numpy.ndarray or AtomGroup) -- 形状的坐标数组 (3,) 或 (n, 3) (数据类型是任意的，将被转换为 numpy.float32 内部)。还接受一个 AtomGroup 。
box (numpy.ndarray) -- 系统的单位单元尺寸，可以是正交的或三斜的，并且必须以与返回的相同格式提供 MDAnalysis.coordinates.timestep.Timestep.dimensions ： [lx, ly, lz, alpha, beta, gamma] 。
backend ({'serial', 'OpenMP'}, optional) -- 关键字选择加速类型。

返回:

新和弦 --包含坐标的数组，所有坐标都位于由定义的主单位单元格内 box 。

返回类型:

numpy.ndarray (dtype=numpy.float32 ， shape=coords.shape )

在 0.8 版本加入.

在 0.13.0 版本发生变更: 已添加后端关键字。

在 0.19.0 版本发生变更: 将输入坐标的内部数据类型转换为 numpy.float32 。现在还接受(并同样返回)单个坐标。

在 2.3.0 版本发生变更: 现在可以接受 AtomGroup 作为任意位置的参数，并使用类型提示检查输入。

MDAnalysis.lib.distances.transform_RtoS(coords, box, backend='serial')[源代码]

将一组坐标从实空间变换到S空间(也称为Lambda空间)

S空间表示该系统的单胞内的分数空间。

的倒数运算 transform_StoR() 。

参数:

coords (numpy.ndarray) -- A (3,) 或 (n, 3) 坐标数组(数据类型为任意类型，将转换为 numpy.float32 内部)。
box (numpy.ndarray) -- 系统的单位单元尺寸，可以是正交的或三斜的，并且必须以与返回的相同格式提供 MDAnalysis.coordinates.timestep.Timestep.dimensions ： [lx, ly, lz, alpha, beta, gamma] 。
backend ({'serial', 'OpenMP'}, optional) -- 关键字选择加速类型。

返回:

新和弦 --包含分数余弦的数组。

返回类型:

numpy.ndarray (dtype=numpy.float32 ， shape=coords.shape )

在 0.13.0 版本发生变更: 已添加后端关键字。

在 0.19.0 版本发生变更: 将输入坐标的内部数据类型转换为 numpy.float32 。现在还接受(并同样返回)单个坐标。

MDAnalysis.lib.distances.transform_StoR(coords, box, backend='serial')[源代码]

将一组坐标从S空间转换到实空间。

S空间表示该系统的单胞内的分数空间。

的倒数运算 transform_RtoS()

参数:

coords (numpy.ndarray) -- A (3,) 或 (n, 3) 坐标数组(数据类型为任意类型，将转换为 numpy.float32 内部)。
box (numpy.ndarray) -- 系统的单位单元尺寸，可以是正交的或三斜的，并且必须以与返回的相同格式提供 MDAnalysis.coordinates.timestep.Timestep.dimensions ： [lx, ly, lz, alpha, beta, gamma] 。
backend ({'serial', 'OpenMP'}, optional) -- 关键字选择加速类型。

返回:

新和弦 --包含实空间坐标的数组。

返回类型:

numpy.ndarray (dtype=numpy.float32 ， shape=coords.shape )

在 0.13.0 版本发生变更: 已添加后端关键字。

在 0.19.0 版本发生变更: 将输入坐标的内部数据类型转换为 numpy.float32 。现在还接受(并同样返回)单个坐标。

MDAnalysis.lib.distances.augment_coordinates(coordinates, box, r)

计算一定距离内的粒子的周期图像 r 从盒子的墙上。

该算法的工作原理是生成位于六个盒子壁中任何一个附近的原子的显式周期图像。生成图像所涉及的步骤包括评估倒数框向量，然后通过投影到倒数向量来计算原子到墙的距离。如果距离小于指定的截止距离，则使用框平移向量生成相关的周期图像 \(\vec{{t}}\) 使用

\[\vec{t}=l\cdot\vec{a}+m\cdot\vec{b}+n\cdot\vec{c}，，\]

哪里 \(l,\,m,\,n \in \{{-1,\,0,\,1\}}\) 中的相邻单元格索引 \(x\) -, \(y\) -、和 \(z\) -使用长方体向量相对于中心单元格的方向 \(\vec{{a}},\,\vec{{b}},\,\vec{{c}}\) 。

例如，一个靠近原子核的原子 \(xy\) -包含原点的平面将在中心像元外部生成周期图像，并靠近相反方向 \(xy\) -框的平面，即移位 \(\vec{{t}} = 0\cdot\vec{{a}}+0\cdot\vec{{b}}+1\cdot\vec{{c}}=\vec{{c}}\) 。

同样，如果粒子靠近多个长方体墙壁，也会生成沿对角线的图像：

                            x            x
+------------+                +------------+
|            |   augment      |            |
|            |   ------->     |            |
|          o |              x |          o |
+------------+                +------------+

参数:

coordinates (numpy.ndarray) -- 形状的输入坐标数组 (n, 3) 和数据类型 numpy.float32 用于在中央单元附近产生复制图像。所有坐标都必须在主单位单元格内。
box (numpy.ndarray) -- 形状的框尺寸 (6,) 和数据类型 numpy.float32 。提供的尺寸必须与返回的格式相同 MDAnalysis.coordinates.base.Timestep.dimensions ： [lx, ly, lz, alpha, beta, gamma]
r (float) -- 生成重复图像的截止区的厚度。

返回:

输出 ( numpy.ndarray )--重复(增强)粒子的坐标(dtype numpy.float32 )。
指数 ( numpy.ndarray )--增强坐标的原始索引(dtype numpy.int64 )。将增强粒子的索引映射到其原始粒子索引，以便 indices[augmented_index] = original_index 。

备注

输出不返回初始数组中的坐标。要将粒子与其各自的图像合并，在生成图像时需要执行以下操作：

images, mapping = augment_coordinates(coordinates, box, max_cutoff)
all_coords = numpy.concatenate([coordinates, images])

参见

undo_augment()

在 0.19.0 版本加入.

MDAnalysis.lib.distances.undo_augment(results, translation, nreal)

将增强的索引转换回原始索引。

参数:

results (numpy.ndarray) -- 数据类型数组 numpy.int64 包含坐标索引，包括“扩充”索引。
translation (numpy.ndarray) -- 数据类型的索引映射 numpy.int64 将所述增强的索引链接到所述原始粒子索引 translation[augmented_index] = original_index 。
nreal (int) -- 实坐标数，即中的索引 results 等于或大于该值需要映射到其真实的对应物。

返回:

结果 --修改后的输入 results 其中所有的扩充索引被转换为其对应的初始原始索引。

返回类型:

numpy.ndarray

备注

就地修改结果数组。

参见

augment_coordinates()

在 0.19.0 版本加入.

MDAnalysis.lib.distances.minimize_vectors(vectors, box)[源代码]

将最小图像约定应用于向量数组

此函数是计算两点之间的正确向量所必需的。幼稚的做法 ag1.positions - ag2.positions 不会提供粒子之间的最小向量，即使所有粒子都在主单位单元(长方体)内。

参数:

vectors (numpy.ndarray) -- 形状矢量数组 (n, 3) ，可以是Float32或Float64。它们表示许多向量(例如两个粒子之间)。
box (numpy.ndarray) -- 系统的单位单元尺寸，可以是正交的或三斜的，并且必须以与返回的相同格式提供 MDAnalysis.coordinates.timestep.Timestep.dimensions ： [lx, ly, lz, alpha, beta, gamma] 。

返回:

minimized_vectors --与输入相同的形状和数据类型。来自输入的向量，但根据长方体的大小最小化。

返回类型:

numpy.ndarray

在 2.1.0 版本加入.

13.2.2. 用于的低级模块 `MDAnalysis.lib.distances`

MDAnalysis.lib._distances 包含对串行中的MDAnalysis Cython函数 distances 。它们很少或根本没有对输入进行错误检查，因此应该谨慎使用。同样， MDAnalysis.lib._distances_openmp 包含启用OpenMP的函数。

13.2.1. 快速距离数组计算 MDAnalysis.lib.distances

13.2.1.1. 选择加速(“后台”)

13.2.1.2. Destopia类库的使用

13.2.1.3. 功能

13.2.2. 用于的低级模块 MDAnalysis.lib.distances

13.2.1. 快速距离数组计算 `MDAnalysis.lib.distances`

13.2.2. 用于的低级模块 `MDAnalysis.lib.distances`