6.9. H5MD轨迹 `MDAnalysis.coordinates.H5MD`

这个 H5MD 基于通用、高性能的轨迹文件格式 HDF5 文件格式。HDF5文件是自我记录的，可以使用 h5py 类库。HDF5可以通过HDF5库的MPI-IO接口利用并行文件系统功能来改进并行读写。

HDF5库和 h5py 必须安装；否则，MDAnalysis无法读取H5MD文件。如果 h5py 未安装，则为 RuntimeError 都被养大了。

6.9.1. 单位

H5MD文件非常灵活，可以在广泛的物理单元中存储数据。这个 H5MDReader 将尝试匹配单位，以便将所有数据转换为标准MDAnalysis单位(请参见 MDAnalysis.units )。

从H5MD文件提供的位置、速度、力和时间数据集的属性中读取单位。单位字符串的翻译自 H5MD notation 至 MDAnalysis notation 。如果MDAnalysis无法识别该单位(可能是因为该单位字符串未在中定义 MDAnalysis.units )，但须提供 RuntimeError 都被养大了。如果未提供单位，则MDAnalysis将存储值 None 对于每个单元。如果H5MD文件不包含单元和 convert_units=True ，MDAnalysis将引发一个 ValueError 。要从未定义单位的H5MD文件加载语义层，请设置 convert_units=False 。

H5MDWriter 检测父轨迹的本机单位，并使用这些单位写入轨迹，除非 timeunit, lengthunit, velocityunit, forceunit arugments are supplied. In this case, the writer will write the corresponding dataset with the selected unit only if it is recognized by MDAnalysis units 。

6.9.2. 示例：加载H5MD模拟

从H5MD轨迹数据文件加载H5MD模拟(使用 H5MDReader )，将拓扑和轨迹文件传递到 Universe ：：

import MDAnalysis as mda
u = mda.Universe("topology.tpr", "trajectory.h5md")

也可以通过一个公开的 h5py.File 进入读取器的文件流：：

import MDAnalysis as mda
with h5py.File("trajectory.h5md", 'r') as f:
     u = mda.Universe("topology.tpr", f)

备注

直接使用 h5py.File does not work yet. See issue #2884 。

6.9.3. 示例：编写H5MD文件

要从加载了MDAnalysis的轨迹写入H5MD文件，请执行以下操作：

import MDAnalysis as mda
u = mda.Universe("topology.tpr", "trajectory.h5md")
with mda.Writer("output.h5md", n_atoms=u.trajectory.n_atoms) as W:
    for ts in u.trajectory:
        W.write(u)

要写入具有连续数据集的H5MD文件，必须指定要写入和设置的帧的数量 chunks=False ：

with mda.Writer("output_contigous.h5md", n_atoms=u.trajectory.n_atoms,
                n_frames=3, chunks=False) as W:
    for ts in u.trajectory[:3]:
        W.write(u)

编写器还支持直接从 AtomGroup ：：

ag = u.select_atoms("protein and name CA")
ag.write("alpha_carbons.h5md", frames='all')

6.9.4. 示例：并行打开H5MD文件

可以通过h5py访问HDF5的并行功能(请参见 parallel h5py docs 有关更多详细信息)，请使用 mpi4py 带有HDF5的并行构建的Python包。要使用并行HDF5加载H5MD模拟，请通过 driver 和 comm 争论到 Universe ：：

import MDAnalysis as mda
from mpi4py import MPI
u = mda.Universe("topology.tpr", "trajectory.h5md",
                 driver="mpio", comm=MPI.COMM_WORLD)

备注

h5py 构建时必须在并行HDF5构建的基础上启用并行功能，并且HDF5和 mpi4py 必须与工作的MPI实现构建。请参阅下面的说明。

6.9.4.1. 在Linux上构建并行的h5py和hdf5

构建一个可以工作的并行HDF5/h5py/mpi4py环境可能具有挑战性，而且通常特定于您的本地计算资源，例如，您运行的超级计算机通常已经安装了其首选的MPI。作为起点，我们提供了在特定的、相当通用的环境中工作的说明。

这些指令成功地构建了并行HDF5/h5py OpenMPI 4.0.4 ， HDF5 1.10.6 ， H5py 2.9.0 ，以及 Mpi4py 3.0.3 在……上面 Ubuntu 16.0.6 。您可能需要尝试不同的h5py/hdf5版本组合才能得到一个可以工作的并行构建。

Build MPI from sources
Build HDF5 from sources 启用并行设置时：
./configure --enable-parallel --enable-shared
make
make install
Install mpi4py _，一定要指向 mpicc 到您安装MPI实现的位置：
env MPICC=/path/to/mpicc pip install mpi4py
Build h5py from sources _，确保启用MPI并指向您的HDF5并行构建：
export HDF5_PATH=path-to-parallel-hdf5
python setup.py clean --all
python setup.py configure -r --hdf5-version=X.Y.Z --mpi --hdf5=$HDF5_PATH
export gcc=gcc
CC=mpicc HDF5_DIR=$HDF5_PATH python setup.py build
python setup.py install

如果您有问题或想分享您是如何构建并行hdf5/h5py/mpi4py的，请在 MDAnalysis forums 。

6.9.5. 班级

class MDAnalysis.coordinates.H5MD.H5MDReader(filename, convert_units=True, driver=None, comm=None, **kwargs)[源代码]

H5MD格式的读卡器。

看见 h5md documentation 以获取H5MD文件格式的详细概述。

读取器尝试将轨迹文件中的单位转换为标准MDAnalysis单位 (MDAnalysis.units )如果 convert_units 设置为 True 。

中的其他数据 observables 组的H5MD文件被加载到 Timestep.data 字典。

仅支持3D周期框或无周期性；对于无周期性， Timestep.dimensions 会回来的 None 。

尽管H5MD可以存储例如由GCMC模拟产生的每个时间步长不同数量的粒子，但MDAnalysis目前每步只能处理固定数量的粒子。如果粒子的数量改变为 ValueError 都被养大了。

这个 H5MDReader 读取具有以下HDF5层次结构的.h5md文件：

Notation:
(name) is an HDF5 group that the reader recognizes
{name} is an HDF5 group with arbitrary name
[variable] is an HDF5 dataset
<dtype> is dataset datatype
+-- is an attribute of a group or dataset

H5MD root
 \-- (h5md)
    +-- version <int>
    \-- author
        +-- name <str>, author's name
        +-- email <str>, optional email address
    \-- creator
        +-- name <str>, file that created .h5md file
        +-- version
 \-- (particles)
    \-- {group1}
        \-- (box)
            +-- dimension : <int>, number of spatial dimensions
            +-- boundary : <str>, boundary conditions of unit cell
            \-- (edges)
                \-- [step] <int>, gives frame
                \-- [value] <float>, gives box dimensions
                    +-- unit <str>
        \-- (position)
            \-- [step] <int>, gives frame
            \-- [time] <float>, gives time
                +-- unit <str>
            \-- [value] <float>, gives numpy arrary of positions
                                 with shape (n_atoms, 3)
                +-- unit <str>
        \-- (velocity)
            \-- [step] <int>, gives frame
            \-- [time] <float>, gives time
                +-- unit <str>
            \-- [value] <float>, gives numpy arrary of velocities
                                 with shape (n_atoms, 3)
                +-- unit <str>
        \-- (force)
            \-- [step] <int>, gives frame
            \-- [time] <float>, gives time
                +-- unit <str>
            \-- [value] <float>, gives numpy arrary of forces
                                 with shape (n_atoms, 3)
                +-- unit <str>
 \-- (observables)
    \-- (lambda)
        \-- [step] <int>, gives frame
        \-- [time] <float>, gives time
        \-- [value] <float>
    \-- (step)
        \-- [step] <int>, gives frame
        \-- [time] <float>, gives time
        \-- [value] <int>, gives integration step

备注

读取器当前不读取质量或电荷数据。

备注

如果 driver and comm arguments were used to open the hdf5 file (specifically, driver="mpio") then the :meth:`_ ReOpen`方法可以 not 像大多数阅读器一样关闭和打开文件，因为有关MPI通信器的信息将丢失；相反，它会将轨迹倒回到第一个时间步。

在 2.0.0 版本加入.

在 2.1.0 版本发生变更: 加法 parse_n_atoms() 对象的形状直接从轨迹获得原子数。 position ， velocity ，或 force 组。

在 2.5.0 版本发生变更: 添加对简单长方体的正确处理

参数:

filename (str or h5py.File) -- 轨迹文件名或打开h5py文件
convert_units (bool (optional)) -- 将单位转换为MDAnalysis单位
driver (str (optional)) -- 用于打开H5MD文件的H5PY文件驱动程序
comm (MPI.Comm (optional)) -- 用于打开H5MD文件的MPI通信器必须与 'mpio' 文件驱动程序
**kwargs (dict) -- 读者的一般论点。

抛出:

RuntimeError -- 什么时候 H5PY 未安装
RuntimeError -- 当MDAnalysis无法识别单位时
ValueError -- 什么时候 n_atoms 在时间步长之间更改值
ValueError -- 什么时候 convert_units=True 但H5MD文件不包含任何部件
ValueError -- 当单元格的尺寸不是3时
ValueError -- 当将MPI通信器对象传递给读取器时 driver != 'mpio'
NoDataError -- 当H5MD文件没有‘位置’、‘速度’或‘力’组时

_reopen()[源代码]: 重新打开轨迹

备注

如果 driver 和 comm 参数用于打开HDF5文件(具体地说， driver="mpio" )，则此方法会 not 像大多数阅读器一样关闭和打开文件，因为有关MPI通信器的信息将丢失；相反，它会将轨迹倒回到第一个timStep。

OtherWriter(filename, **kwargs)

返回适用于的编写器 文件名 。

设置默认关键字开始， step 和 dt (如果可用)。 n_atoms 始终设置为 Reader.n_atoms 。

参见

Reader.Writer()

Writer(filename, n_atoms=None, **kwargs)[源代码]

用于轨迹格式的返回写入器

备注

输入文件的块形状不会复制到输出文件，因为 H5MDWriter 使用块形状 (1, n_atoms, 3) 默认情况下。若要使用自定义区块形状，必须指定 chunks 争论。如果要从数据集中复制现有块格式(位置、速度或力)，请执行以下操作：

chunks = u.trajectory._particle_group['position/value'].chunks

请注意，编写器将为所有粒子组设置相同的布局。

参见

H5MDWriter

在 2.0.0 版本加入.

add_auxiliary(aux_spec: str | Dict[str, str] = None, auxdata: str | AuxReader = None, format: str = None, **kwargs) → None

添加要与轨迹一起读取的辅助数据。

辅助数据可以是除了由轨迹读取器读入的轨迹之外的来自轨迹的任何数据时间序列。 辅助数据 可以是一个 AuxReader 实例，或数据本身作为文件名；在后一种情况下，适当的 AuxReader 是从数据/文件格式中猜测出来的。一种适当的 format 也可以直接作为关键字参数提供。

添加时，AuxReader最初与轨迹的当前时间步长匹配，并将在轨迹时步更改时更新(通过调用 next() 或者跳跃时间步长 trajectory[i] )。

每个时间步长的辅助数据的代表值(S)(由 AuxReader )存储在 ts.aux 下的命名空间 aux_spec ；例如，要添加存储在Pull-force.xvg中的其他拉力数据：：

u = MDAnalysis.Universe(PDB, XTC)
u.trajectory.add_auxiliary('pull', 'pull-force.xvg')

然后，当前时间步长的代表值可以被访问为 u.trajectory.ts.aux.pull 或 u.trajectory.ts.aux['pull'] 。

以下内容适用于能源读者，如 EDRReader 。

可以通过省略来添加(能源)文件中存在的所有数据 aux_spec 像这样：：

u.trajectory.add_auxiliary(auxdata="ener.edr")

aux_spec 属性中映射所需属性名称的字典。 ts.aux 命名空间设置为要添加的精确数据，该数据由 data_selector **

term_dict = {"temp": "Temperature", "epot": "Potential"}
u.trajectory.add_auxiliary(term_dict, "ener.edr")

例如，添加此数据对于基于非坐标数据(如每个时间步长的势能)过滤轨迹帧可能很有用。轨迹切片允许处理帧的子集：

selected_frames = np.array([ts.frame for ts in u.trajectory
                            if ts.aux.epot < some_threshold])
subset = u.trajectory[selected_frames]

参见

remove_auxiliary()

备注

假设辅助数据是按时间排序的，没有重复。请参阅辅助API 。

add_transformations(*transformations)

添加要应用于轨迹的所有变换。

此函数将转换列表作为参数。这些转换是将由Reader调用的函数，并为其提供 Timestep 对象作为参数，它将被转换并返回给读取器。这些转换可以是 transformations 模块，或由用户创建，并以列表形式存储 transformations 。此列表只能修改一次，进一步调用此函数将引发异常。

u = MDAnalysis.Universe(topology, coordinates)
workflow = [some_transform, another_transform, this_transform]
u.trajectory.add_transformations(*workflow)

将按照列表中给出的顺序应用转换 transformations 即，第一个转换是要应用于 Timestep 。上面的示例等同于

for ts in u.trajectory:
   ts = this_transform(another_transform(some_transform(ts)))

参数:: transform_list (list) -- 将按列表中给定的顺序应用于坐标的所有变换的列表

参见

MDAnalysis.transformations

property aux_list: 列出新增辅助数据的名称。

check_slice_indices(start, stop, step)

检查帧索引是否有效，并剪裁以适合轨迹。

该用法遵循以下标准的Python约定 range() 但请参阅下面的警告。

参数:

start (int or None) -- 起始帧索引(含)。 None 对应于缺省值0，即初始帧。
stop (int or None) -- 最后一帧索引(独占)。 None 对应于默认的n帧，即它包括轨迹的最后一帧。
step (int or None) -- 切片的步长大小， None 对应于缺省值1，即包括范围中的每一帧 start ， stop 。

返回:

开始、停止、步进 --表示切片的整数

返回类型:

tuple (int, int, int)

警告

返回值 start ， stop 和 step 传入时给出预期结果 range() ，但在传入 slice 什么时候 stop=None 和 step=-1

对于此方法的输出的下游处理来说，这可能是一个问题。例如，轨迹切片是通过传递 check_slice_indices() 至 range() ：：

range(start, stop, step)

并将其作为随机寻求的指标。另一方面，在 MDAnalysis.analysis.base.AnalysisBase 由返回的值 check_slice_indices() 用于拼接轨迹，方法是创建 slice 实例：：

slice(start, stop, step)

这会造成差异，因为这两行不相等：：

range(10, -1, -1)             # [10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0]
range(10)[slice(10, -1, -1)]  # []

close()[源代码]: 近距离阅读

convert_forces_from_native(force, inplace=True)

力阵的换算力从原生单位到基本单位

参数:

force (array_like) -- 转型的力量
inplace (bool (optional)) -- 是否就地修改数组，覆盖以前的数据

备注

默认情况下，输入力被就地修改并也被返回。就地操作提高了性能，因为避免了分配新阵列。

在 0.7.7 版本加入.

convert_forces_to_native(force, inplace=True)

力阵的换算力从基本单位到原生单位。

参数:

force (array_like) -- 转型的力量
inplace (bool (optional)) -- 是否就地修改数组，覆盖以前的数据

备注

默认情况下，输入 force 被就地修改并也被返回。就地操作提高了性能，因为避免了分配新阵列。

在 0.7.7 版本加入.

convert_pos_from_native(x, inplace=True)

坐标数组x从原生单位到基本单位的转换。

参数:

x (array_like) -- 要转型的职位
inplace (bool (optional)) -- 是否就地修改数组，覆盖以前的数据

备注

默认情况下，输入 x 被就地修改并也被返回。就地操作提高了性能，因为避免了分配新阵列。

在 0.7.5 版本发生变更: 关键字 inplace 可以设置为 False 以便返回修改后的副本除非不会发生转换，在这种情况下，对未修改的 x 返回。

convert_pos_to_native(x, inplace=True)

坐标数组的转换 x 从基本单位到本地单位。

参数:

x (array_like) -- 要转型的职位
inplace (bool (optional)) -- 是否就地修改数组，覆盖以前的数据

备注

默认情况下，输入 x 被就地修改并也被返回。就地操作提高了性能，因为避免了分配新阵列。

在 0.7.5 版本发生变更: 关键字 inplace 可以设置为 False 以便返回修改后的副本除非不会发生转换，在这种情况下，对未修改的 x 返回。

convert_time_from_native(t, inplace=True)

转换时间 t 从原生单位到基本单位。

参数:

t (array_like) -- 要转换的时间值
inplace (bool (optional)) -- 是否就地修改数组，覆盖以前的数据

备注

默认情况下，输入 t 被就地修改并返回(尽管请注意标量值 t 在Python中通过值传递，因此就地修改对调用方没有任何影响。)就地操作提高了性能，因为避免了分配新阵列。

在 0.7.5 版本发生变更: 关键字 inplace 可以设置为 False 以便返回修改后的副本除非不会发生转换，在这种情况下，对未修改的 x 返回。

convert_time_to_native(t, inplace=True)

转换时间 t 从基本单位到本地单位。

参数:

t (array_like) -- 要转换的时间值
inplace (bool, optional) -- 是否就地修改数组，覆盖以前的数据

备注

默认情况下，输入 t 被就地修改并也被返回。(另请注意，标量值 t 在Python中通过值传递，因此就地修改对调用方没有任何影响。)

在 0.7.5 版本发生变更: 关键字在位可以设置为 False 以便返回修改后的副本除非不会发生转换，在这种情况下，对未修改的 x 返回。

convert_velocities_from_native(v, inplace=True)

速度阵的换算 v 从原生单位到基本单位

参数:

v (array_like) -- 转型的速度
inplace (bool (optional)) -- 是否就地修改数组，覆盖以前的数据

备注

默认情况下，输入 v 被就地修改并也被返回。就地操作提高了性能，因为避免了分配新阵列。

在 0.7.5 版本加入.

convert_velocities_to_native(v, inplace=True)

坐标数组的转换 v 从基本单位到原生单位

参数:

v (array_like) -- 转型的速度
inplace (bool (optional)) -- 是否就地修改数组，覆盖以前的数据

备注

默认情况下，输入 v 被就地修改并也被返回。就地操作提高了性能，因为避免了分配新阵列。

在 0.7.5 版本加入.

copy()

退还本阅读器的独立副本。

新的阅读器将有自己的文件句柄，可以独立于原始阅读器进行查找/迭代。

还将复制原始读取器中保存的时间步长的当前状态。

在 2.2.0 版本发生变更: 用于构造读取器的参数被正确捕获并传递给新类的创建。以前是唯一的 n_atoms 被传递给类副本，导致使用默认参数创建的类可能与原始类不同。

property dt: float: 两个轨迹帧之间的时间，以皮秒为单位。

property frame: int

当前时间步长的帧编号。

这是一条简单的捷径 Timestep.frame 。

get_aux_attribute(auxname, attrname)

获取的价值 属性名称 从辅助器 辅助名称

参数:

auxname (str) -- 要获取其值的辅助设备的名称
attrname (str) -- 辅助读取器中的gettable属性的名称

参见

set_aux_attribute()

get_aux_descriptions(auxnames=None)

获取描述以允许重新加载指定的辅助项。

如果未提供辅助名称，则默认为添加的辅助名称的完整列表。

将生成的描述传递给 add_auxiliary() 将允许辅助人员的娱乐活动。例如，将所有辅助词复制到第二个轨迹中：

descriptions = trajectory_1.get_aux_descriptions()
for aux in descriptions:
    trajectory_2.add_auxiliary(**aux)

返回:: 描述每个辅助词的args/kwargs词典列表。
返回类型:: list

参见

MDAnalysis.auxiliary.base.AuxReader.get_description()

property has_forces: True 如果‘力量’小组在轨道上。

property has_positions: True 如果‘位置’组在轨道上。

property has_velocities: True 如果“速度”组在轨道上。

iter_as_aux(auxname): 迭代至少有一个来自辅助步骤的分配步骤的时间步长 辅助名称 中指定的截止范围内 辅助名称 。

参见

next_as_aux(), iter_auxiliary()

iter_auxiliary(auxname, start=None, stop=None, step=None, selected=None)

遍历辅助词 辅助名称 与弹道无关。

将迭代辅助的指定步骤(默认为所有步骤)。允许访问辅助对象中的所有值，包括轨迹时间范围之外的值，而不必同时迭代轨迹。

迭代后，辅助器将重新定位在当前步骤。

参数:

auxname (str) -- 要迭代的辅助对象的名称。
(start (optional) -- 用于在辅助对象的切片上迭代的选项。
stop (optional) -- 用于在辅助对象的切片上迭代的选项。
step) (optional) -- 用于在辅助对象的切片上迭代的选项。
selected (lst | ndarray, optional) -- 要迭代的步骤列表。

生成器:

AuxStep 对象

参见

iter_as_aux()

property n_frames: 轨迹中的帧数

next() → Timestep: 前进一步到下一帧。

next_as_aux(auxname)

移动到辅助时间步长至少有一个步长的下一个时间步长 辅助名称 中指定的截止范围内 辅助名称 。

这允许在轨迹中前进，而不会遇到 NaN 代表值(除非这些值特别是辅助数据的一部分)。

如果未设置辅助截止，则辅助步骤较少 (auxiliary.dt > trajectory.dt )，这允许以辅助步调(四舍五入到最接近的时间步长)前进；而如果辅助步长更频繁，这将与调用 next() 。

请参阅辅助API 。

参见

iter_as_aux()

open_trajectory()[源代码]: 使用h5py库打开轨迹文件

static parse_n_atoms(filename)[源代码]

读取坐标文件并推算出原子数

返回:: n_atoms --坐标文件中的原子数
返回类型:: int
抛出:: NotImplementedError -- 当原子的数量无法推断时

remove_auxiliary(auxname): 清除数据并关闭 AuxReader 对于辅助者 辅助名称 。

参见

add_auxiliary()

rename_aux(auxname, new)

更改辅助设备的名称 辅助名称 至 new 。

假设还没有名为 new ，辅助名称将在t.aux名称空间、轨迹的添加辅助项列表以及辅助阅读器本身中更改。

参数:

auxname (str) -- 要重命名的辅助设备的名称
new (str) -- 要尝试设置的新名称

抛出:

ValueError -- 如果该名称 new 已被现有的辅助设备使用。

rewind() → Timestep: 轨迹起始处的位置

set_aux_attribute(auxname, attrname, new)

设置的值 属性名称 在辅助词中 辅助名称 。

参数:

auxname (str) -- 要更改的辅助设备的名称
attrname (str) -- 辅助读取器中的可设置属性的名称
new -- 要尝试设置的新值 属性名称 至

参见

get_aux_attribute(), rename_aux()

property time

当前帧的时间，以MDAnalysis时间单位表示(通常为ps)。

这要么直接从TimeStep读取，要么计算为time= Timestep.frame * Timestep.dt

返回原子组的坐标数据子集

参数:

asel (AtomGroup (optional)) -- 这个 AtomGroup 从…读取坐标。默认为 None 在这种情况下，将返回完整的坐标数据集。
start (int (optional)) -- 从帧索引处开始读取轨迹 start (其中0是轨迹中第一帧的索引)；默认设置 None 从头开始。
stop (int (optional)) -- 在帧索引处结束读取轨迹 stop -1，即， stop 被排除在外。轨迹将使用默认设置读取到末尾 None 。
step (int (optional)) -- 读取步长；默认设置 None 等于1，表示读取每一帧。
order (str (optional)) -- 对应于(A)tom、(F)rame、(C)坐标的返回数据数组的顺序/形状允许所有六个‘a’、‘f’、‘c’的组合，即“fac”-其中形状为(帧、原子数、坐标)的返回数组

参见

MDAnalysis.coordinates.memory

在 2.4.0 版本加入.

property totaltime: float

轨迹的总长度

时间的计算方式为 (n_frames - 1) * dt 也就是说，我们假设第一帧没有经过时间。因此，具有两个帧的轨迹将被视为具有单个时间步的长度 dt 并且具有单帧的“轨迹”将被报告为长度0。

property transformations: 返回转换列表

units = {'length': None, 'time': None, 'velocity': None}: 带有以下单位的词典 time 和长度 (及速度，力 ..用于支持它的格式)

class MDAnalysis.coordinates.H5MD.H5MDWriter(filename, n_atoms, n_frames=None, driver=None, convert_units=True, chunks=None, compression=None, compression_opts=None, positions=True, velocities=True, forces=True, timeunit=None, lengthunit=None, velocityunit=None, forceunit=None, author='N/A', author_email=None, creator='MDAnalysis', creator_version='2.6.1', **kwargs)[源代码]

撰稿人 H5MD 格式(1.1版)。

H5MD轨迹由文件扩展名“.h5md”自动识别。

来自输入的所有数据 Timestep 默认情况下是写入的。以获取有关如何 H5MDWriter 处理单位、压缩和分块，请参阅下面的注释部分。

备注

使用MPI通信器和 'mpio' 当前不支持HDF5驱动程序。

备注

NoDataError 如果在输入轨迹中找不到位置、速度或力，则引发。虽然H5MD标准允许这种情况， H5MDReader 如果没有这三个组中的至少一个，当前无法读取文件。

备注

使用奇特的轨迹切片编写H5MD文件，其中时间步长不会单调增加，例如 u.trajectory[[2,1,0]] 或 u.trajectory[[0,1,2,0,1,2]] 引发了一个 ValueError 因为这违反了H5MD标准中的STEP数据集的规则。

参数:

filename (str or h5py.File) -- 轨迹文件名或打开h5py文件
n_atoms (int) -- 轨迹中的原子数
n_frames (int (optional)) -- 要在轨迹中写入的帧数
driver (str (optional)) -- 用于打开H5MD文件的H5PY文件驱动程序。看见 H5PY drivers 有关可用驱动程序的列表。
convert_units (bool (optional)) -- 将单位从MDAnalysis转换为所需单位
chunks (tuple (optional)) -- 要应用于位置、速度和力数据集的自定义块布局。默认情况下，这些数据集被分成块 (1, n_atoms, 3) 块
compression (str or int (optional)) -- 要应用于位置、速度和力数据集的HDF5数据集压缩设置。允许的设置为‘gzip’、‘szip’、‘lzf’。如果是范围(10)内的整数，则表示gzip压缩级别。否则，整数表示动态加载的压缩过滤器的编号。
compression_opts (int or tup (optional)) -- 压缩设置。这是一个整数，表示gZip，2元组表示szip，依此类推。如果指定动态加载的压缩筛选器号，则这必须是值的元组。对于gzip，1表示最低压缩级别，9表示最大压缩。
positions (bool (optional)) -- 将位置写入轨迹 [True]
velocities (bool (optional)) -- 将速度写入轨迹 [True]
forces (bool (optional)) -- 将力写入轨迹 [True]
timeunit (str (optional)) -- 用于将‘Time’数据集中的值转换为自定义单位的选项，必须可由MDAnalysis识别
lengthunit (str (optional)) -- 将‘Position/Value’数据集中的值转换为自定义单位的选项必须可被MDAnalysis识别
velocityunit (str (optional)) -- 将‘速度/值’数据集中的值转换为自定义单位的选项必须可被MDAnalysis识别
forceunit (str (optional)) -- 用于将‘force/Value’数据集中的值转换为自定义单位的选项必须可被MDAnalysis识别
author (str (optional)) -- 文件作者的姓名
author_email (str (optional)) -- 文件作者的电子邮件
creator (str (optional)) -- 写入该文件的软件 [MDAnalysis]
creator_version (str (optional)) -- 写入文件的软件版本 [MDAnalysis.__version__]

抛出:

RuntimeError -- 什么时候 H5PY 未安装
ValueError -- 什么时候 n_atoms 是0
ValueError -- 什么时候 chunks=False 但用户没有指定 n_frames
ValueError -- 什么时候 positions ， velocities ，以及 forces 都设置为 False
TypeError -- 当输入对象不是 Universe 或 AtomGroup
IOError -- 什么时候 n_atoms 的 Universe 或 AtomGroup 正在写入的内容不匹配 n_atoms 作为参数传递给编写者
ValueError -- 当任何可选的 timeunit ， lengthunit ， velocityunit ，或 forceunit MDAnalysis无法识别关键字参数

备注

默认情况下，如果在输入中检测到，写入器将写入所有可用数据(位置、速度和力 Timestep 。此外，的设置 compression 和 compression_opts 将从第一组可用的位置、速度或力中读取并用作默认值。要在没有这些数据集的情况下写入文件，请设置 positions ， velocities ，或 forces 至 False 。

单位

H5MD格式在单位方面非常灵活，因为该格式没有标准定义的单位。因为这个原因， H5MDWriter 不强制执行任何单位。可以使用关键字参数显式设置所写轨迹的单位 lengthunit ， velocityunit ，以及 forceunit 。如果未明确指定单位，则将它们设置为作为坐标源的轨迹的原生单位。例如，如果一个人转换一个DCD轨迹，那么位置就用Akma单位来写，而位置就用Akma单位来写。GROMACS XTC将以nm和ps写成。单位存储在H5MD文件的元数据中，因此当MDAnalysis加载H5MD轨迹时，单位将自动正确设置。

压缩

HDF5本身就支持各种压缩模式。要使用压缩的数据集写入轨迹，请设置 compression='gzip' ， compression='lzf' 等。请参阅 H5PY compression options 适用于所有支持的压缩模式。另一个论点是， compression_opts ，可用于微调压缩级别。例如，对于GZIP压缩， compression_opts 对于最小压缩可以设置为1，对于最大压缩可以设置为9。

HDF5分块

HDF5数据集可以分块这意味着数据集可以被分割成大小相等的片段，并存储在磁盘上不同的、不连续的位置。如果HDF5尝试从分块的数据集中读取元素，全必须读取数据集，因此考虑不周的分块方案可能会极大地影响文件I/O性能。在所有MDAnalysis编写器的情况下，通常，编写器事先不知道正在写入的帧的数量，因此HDF5必须是可扩展的。但是，磁盘空间的分配是在创建数据集时定义的，因此可以扩展HDF5数据集 must 被分块，以便允许在磁盘上动态存储任何传入写入器的数据。在这种情况下，分块不是由用户明确定义的，H5PY通过一种算法自动选择块形状，该算法试图在1 KiB-1 MiB之间生成大部分正方形的块，但这可能会导致次优的I/O性能。 H5MDWriter 使用默认的块形状 (1, n_atoms, 3) 从而通过MDAnalysis模拟轨迹的典型访问模式。在我们的测试中 ([Jakupovic2021]) ，与H5PY的自动分块形状相比，这种块形状的加速比约为10倍。用户可以使用设置自定义块形状 chunks 争论。此外，通过设置，文件中的数据集可以使用连续布局写入 chunks=False 但是，这必须伴随着设置 n_frames 等于正在写入的帧的数量，因为在创建数据集时，HDF5必须知道要在磁盘上分配多少空间。

在 2.0.0 版本加入.

H5MD_VERSION = (1, 1): 当前编写的文件格式版本

close(): 关闭轨迹文件。

convert_dimensions_to_unitcell(ts, inplace=True)

从TimeStep读取维度 ts 并返回相应的单元格。

默认情况下，返回 [A,B,C,alpha,beta,gamma] ；如果这不合适，则必须重写此方法。

convert_forces_from_native(force, inplace=True)

力阵的换算力从原生单位到基本单位

参数:

force (array_like) -- 转型的力量
inplace (bool (optional)) -- 是否就地修改数组，覆盖以前的数据

备注

默认情况下，输入力被就地修改并也被返回。就地操作提高了性能，因为避免了分配新阵列。

在 0.7.7 版本加入.

convert_forces_to_native(force, inplace=True)

力阵的换算力从基本单位到原生单位。

参数:

force (array_like) -- 转型的力量
inplace (bool (optional)) -- 是否就地修改数组，覆盖以前的数据

备注

默认情况下，输入 force 被就地修改并也被返回。就地操作提高了性能，因为避免了分配新阵列。

在 0.7.7 版本加入.

convert_pos_from_native(x, inplace=True)

坐标数组x从原生单位到基本单位的转换。

参数:

x (array_like) -- 要转型的职位
inplace (bool (optional)) -- 是否就地修改数组，覆盖以前的数据

备注

默认情况下，输入 x 被就地修改并也被返回。就地操作提高了性能，因为避免了分配新阵列。

在 0.7.5 版本发生变更: 关键字 inplace 可以设置为 False 以便返回修改后的副本除非不会发生转换，在这种情况下，对未修改的 x 返回。

convert_pos_to_native(x, inplace=True)

坐标数组的转换 x 从基本单位到本地单位。

参数:

x (array_like) -- 要转型的职位
inplace (bool (optional)) -- 是否就地修改数组，覆盖以前的数据

备注

默认情况下，输入 x 被就地修改并也被返回。就地操作提高了性能，因为避免了分配新阵列。

在 0.7.5 版本发生变更: 关键字 inplace 可以设置为 False 以便返回修改后的副本除非不会发生转换，在这种情况下，对未修改的 x 返回。

convert_time_from_native(t, inplace=True)

转换时间 t 从原生单位到基本单位。

参数:

t (array_like) -- 要转换的时间值
inplace (bool (optional)) -- 是否就地修改数组，覆盖以前的数据

备注

默认情况下，输入 t 被就地修改并返回(尽管请注意标量值 t 在Python中通过值传递，因此就地修改对调用方没有任何影响。)就地操作提高了性能，因为避免了分配新阵列。

在 0.7.5 版本发生变更: 关键字 inplace 可以设置为 False 以便返回修改后的副本除非不会发生转换，在这种情况下，对未修改的 x 返回。

convert_time_to_native(t, inplace=True)

转换时间 t 从基本单位到本地单位。

参数:

t (array_like) -- 要转换的时间值
inplace (bool, optional) -- 是否就地修改数组，覆盖以前的数据

备注

默认情况下，输入 t 被就地修改并也被返回。(另请注意，标量值 t 在Python中通过值传递，因此就地修改对调用方没有任何影响。)

在 0.7.5 版本发生变更: 关键字在位可以设置为 False 以便返回修改后的副本除非不会发生转换，在这种情况下，对未修改的 x 返回。

convert_velocities_from_native(v, inplace=True)

速度阵的换算 v 从原生单位到基本单位

参数:

v (array_like) -- 转型的速度
inplace (bool (optional)) -- 是否就地修改数组，覆盖以前的数据

备注

默认情况下，输入 v 被就地修改并也被返回。就地操作提高了性能，因为避免了分配新阵列。

在 0.7.5 版本加入.

convert_velocities_to_native(v, inplace=True)

坐标数组的转换 v 从基本单位到原生单位

参数:

v (array_like) -- 转型的速度
inplace (bool (optional)) -- 是否就地修改数组，覆盖以前的数据

备注

默认情况下，输入 v 被就地修改并也被返回。就地操作提高了性能，因为避免了分配新阵列。

在 0.7.5 版本加入.

data_blacklist = ['step', 'time', 'dt']: 这些变量不是从 Timestep.data H5MD文件中可观测对象组的字典

property has_forces: True 如果作者正在写来自TimeStep的力量。

property has_positions: True 如果编写器正在写入TimeStep中的位置。

has_valid_coordinates(criteria, x)

退货 True 如果所有值都在其格式的限制值内。

由于四舍五入，测试是不对称的(和 min 应该是负面的)：

最小<x<=最大

参数:

criteria (dict) -- 包含 max 和 min 以本地单位表示的值
x (numpy.ndarray) -- (x, y, z) 选定要写出的原子的坐标

返回类型:

bool

property has_velocities: True 如果编写器正在写入TimeStep的速度。

units = {'length': None, 'time': None, 'velocity': None}: 带有以下单位的词典 time 和长度 (及速度，力 ..用于支持它的格式)

write(obj)

写入当前时间步长，使用提供的 obj 。

参数:: obj (AtomGroup or Universe) -- 写入与以下项关联的坐标信息 obj

备注

的大小 obj 必须与设置轨迹时提供的原子数相同。

在 2.0.0 版本发生变更: 不推荐使用的写入TimeStep参数的支持现已删除。取而代之的是使用原子组或宇宙作为输入。

class MDAnalysis.coordinates.H5MD.H5PYPicklable(name, mode='r', driver=None, libver=None, userblock_size=None, swmr=False, rdcc_nslots=None, rdcc_nbytes=None, rdcc_w0=None, track_order=None, fs_strategy=None, fs_persist=False, fs_threshold=1, fs_page_size=None, page_buf_size=None, min_meta_keep=0, min_raw_keep=0, locking=None, alignment_threshold=1, alignment_interval=1, meta_block_size=None, **kwds)[源代码]

H5PY可酸洗的文件对象(只读)。

此类提供了一个类似文件的对象(由 h5py.File )，与标准的Python文件对象不同，它可以进行酸洗。仅支持读取模式。

当文件被浸泡时，文件名、模式、驱动程序和通信 h5py.File 保存在文件中。在取消酸洗时，按文件名、模式、驱动程序打开文件。这意味着要成功地取消选取，原始文件仍然必须可以使用其文件名进行访问。

参数:

filename (str or file-like) -- 给定文本或字节字符串的文件名。
driver (str (optional)) -- 用于打开H5MD文件的H5PY文件驱动程序

示例

f = H5PYPicklable('filename', 'r')
print(f['particles/trajectory/position/value'][0])
f.close()

还可以用作上下文管理器：：

with H5PYPicklable('filename', 'r'):
    print(f['particles/trajectory/position/value'][0])

备注

酸奶的腌制 h5py.File 打开时为 driver="mpio" 并且当前不支持MPI通信器

参见

MDAnalysis.lib.picklable_file_io.FileIOPicklable, MDAnalysis.lib.picklable_file_io.BufferIOPicklable, MDAnalysis.lib.picklable_file_io.TextIOPicklable, MDAnalysis.lib.picklable_file_io.GzipPicklable, MDAnalysis.lib.picklable_file_io.BZ2Picklable

在 2.0.0 版本加入.

创建新的文件对象。

有关这些选项的详细说明，请参阅h5py用户指南。

名字

磁盘上的文件或类似文件的对象的名称。注意：对于使用‘core’驱动程序创建的文件，HDF5仍然要求它是非空的。

模式

R只读，文件必须存在(默认)r+读/写，文件必须存在w创建文件，如果存在则截断w-或x创建文件，如果存在则失败如果存在则读/写，否则创建

司机

要使用的驱动程序的名称。合法值为None(默认，推荐)、‘core’、‘sec2’、‘Direct’、‘stdio’、‘mpio’、‘ros3’。

利伯弗

库版本限制。支持的值：‘最早’、‘v108’、‘v110’、‘v112’、‘最新’。‘v108’、‘v110’和‘v112’选项只能与HDF5 1.10.2库或更高版本一起指定。

userblock_size

所需的用户块大小。仅在创建新文件时允许(模式为w、w-或x)。

Swmr

在SWMR读取模式下打开文件。仅在模式=‘r’时使用。

rdcc_nbytes

数据集区块缓存的总大小(字节)。每个数据集的默认大小为1024**2(1 MiB)。适用于所有数据集，除非单独更改。

rdcc_w0

所有数据集的区块抢占策略。它必须介于0和1之间(含0和1)，并指示在确定要从缓存中刷新哪些块时，根据哪些块的权重对已完全读取或写入的块进行惩罚。值0表示完全读取或写入的区块与其他区块没有区别(抢占严格地说是LRU)，而值1意味着完全读取或写入的区块总是在其他区块之前被抢占。如果您的应用程序只读取或写入数据一次，则可以安全地将其设置为1。否则，应根据您重新读取或重新写入相同数据的频率将其设置得更低。默认值为0.75。适用于所有数据集，除非单独更改。

rdcc_nslots

此文件的原始数据区块缓存中的区块槽数。增加此值会减少缓存冲突的次数，但会略微增加所使用的内存。由于散列策略，该值理想情况下应该是质数。根据经验，该值应该至少是rdcc_n字节中可以容纳的区块数量的10倍。为了获得最佳性能，应该将此值设置为区块数量的大约100倍。默认值为521。适用于所有数据集，除非单独更改。

track_order

如果为True，则跟踪根组下的数据集/组/属性创建顺序。如果没有，则使用全局默认的h5.get_config().Track_Order。

fs_strategy

要使用的文件空间处理策略。仅在创建新文件时允许(模式为w、w-或x)。定义为：“FSM”FSM、聚合器、VFD“PAGE”分页FSM、VFD“Aggregate”聚合器、VFD“None”VFD(如果没有使用HDF5缺省值)。

fs_page_size

文件空间页面大小，以字节为单位。仅当fs_Strategy=“page”时使用。如果没有，则使用HDF5默认值(4096字节)。

fs_persist

一个布尔值，用于指示可用空间是否应该是持久的。仅在创建新文件时允许。默认值为FALSE。

fs_threshold

可用空间管理器将跟踪的最小可用空间节大小。仅在创建新文件时允许。默认值为1。

page_buf_size

页面缓冲区大小，以字节为单位。仅允许使用fs_Strategy=“page”创建的HDF5文件。必须是2的幂，且大于或等于创建文件时的文件空间页面大小。默认情况下不使用它。

min_meta_keep

允许逐出包含元数据的页面之前保留在页面缓冲区中的元数据的最小百分比。仅在设置了PAGE_BUF_SIZE时适用。默认值为零。

min_raw_keep

允许收回包含原始数据的页面之前保留在页面缓冲区中的原始数据的最小百分比。仅在设置了PAGE_BUF_SIZE时适用。默认值为零。

锁紧

文件锁定行为。定义为：

False(或“False”)--禁用文件锁定
True(或“True”)--启用文件锁定
“尽力而为”--启用文件锁定，但忽略一些错误
无--使用HDF5默认设置

警告

HDF5_USE_FILE_LOCKING环境变量可以覆盖此参数。

仅在HDF5>=1.12.1或1.10.x>=1.10.7时可用。

alignment_threshold

与.一起 alignment_interval ，此属性确保任何大小大于或等于对齐阈值(以字节为单位)的文件对象都将在是对齐间隔倍数的地址上对齐。

alignment_interval

此属性应与一起使用 alignment_threshold 。请参阅上面的描述。欲了解更多详情，请访问https://portal.hdfgroup.org/display/HDF5/H5P_SET_ALIGNMENT

meta_block_size

设置新元数据块分配的当前最小大小(以字节为单位)。请参阅https://portal.hdfgroup.org/display/HDF5/H5P_SET_META_BLOCK_SIZE

其他关键字

传递给选定的文件驱动程序。

6.9. H5MD轨迹 MDAnalysis.coordinates.H5MD

6.9.1. 单位

6.9.2. 示例：加载H5MD模拟

6.9.3. 示例：编写H5MD文件

6.9.4. 示例：并行打开H5MD文件

6.9.4.1. 在Linux上构建并行的h5py和hdf5

6.9.5. 班级

6.9. H5MD轨迹 `MDAnalysis.coordinates.H5MD`