.. _DeePMDHDF5MixedFormat:

deepmd/hdf5/mixed format
========================

Class: :class:`DeePMDHDF5MixedFormat <dpdata.plugins.deepmd.DeePMDHDF5MixedFormat>`


Mixed type HDF5 format for DeePMD-kit.

Mixed type data stores frames with the same atom count in one dataset even
when their formulas differ. The placeholder ``type.raw`` contains only the
mixed token type, while ``set.*/real_atom_types.npy`` stores the real atom
type layout for each frame. Loading reconstructs regular Systems by
splitting frames with different ``real_atom_types`` rows.

The HDF5 layout mirrors ``deepmd/npy/mixed`` inside HDF5 groups. For
:class:`dpdata.MultiSystems`, each top-level mixed group is keyed by the
number of atoms after optional padding, such as ``"4"`` or ``"8"``. A
string path may include ``"#group/path"`` to read or write mixed data under
a nested HDF5 group.














.. rubric:: Examples

Dump a :class:`dpdata.MultiSystems` object to a mixed HDF5 file:

>>> systems.to_deepmd_hdf5_mixed("mixed.hdf5")

Dump with atom-count padding:

>>> systems.to_deepmd_hdf5_mixed("mixed.hdf5", atom_numb_pad=8)

Load a mixed HDF5 file into :class:`dpdata.MultiSystems`:

>>> dpdata.MultiSystems().from_deepmd_hdf5_mixed("mixed.hdf5")


Conversions
-----------

.. _DeePMDHDF5MixedFormat_to_system:

Convert from System to this format
``````````````````````````````````

.. py:function:: dpdata.System.to(fmt: Literal['deepmd/hdf5/mixed'], file_name, set_size: 'int' = 2000, prec=<class 'numpy.float64'>, comp_prec=None)
   :noindex:
.. py:function:: dpdata.System.to_deepmd_hdf5_mixed(file_name, set_size: 'int' = 2000, prec=<class 'numpy.float64'>, comp_prec=None)
   :noindex:

   
Dump a System data dict in mixed HDF5 format.


:Parameters:

    **file_name** : str or h5py.Group or h5py.File
        HDF5 file, HDF5 group, or string in ``"file.hdf5#group"`` form.
        Strings open the target file in write mode. HDF5 objects are written
        in place.

    **set_size** : int, default=2000
        Maximum number of frames per ``set.*`` group.

    **prec** : numpy.dtype, default=numpy.float64
        Floating point precision for dumped frame data. Kept for
        consistency with ``deepmd/npy/mixed``.

    **comp_prec** : numpy.dtype, optional
        Explicit floating point precision. When provided, this overrides
        ``prec``.







:Raises:

    TypeError
        If ``file_name`` is not a string, HDF5 group, or HDF5 file.











.. _DeePMDHDF5MixedFormat_to_labeled_system:

Convert from LabeledSystem to this format
`````````````````````````````````````````

.. py:function:: dpdata.LabeledSystem.to(fmt: Literal['deepmd/hdf5/mixed'], file_name, set_size: 'int' = 2000, prec=<class 'numpy.float64'>, comp_prec=None)
   :noindex:
.. py:function:: dpdata.LabeledSystem.to_deepmd_hdf5_mixed(file_name, set_size: 'int' = 2000, prec=<class 'numpy.float64'>, comp_prec=None)
   :noindex:

   
Dump a System data dict in mixed HDF5 format.


:Parameters:

    **file_name** : str or h5py.Group or h5py.File
        HDF5 file, HDF5 group, or string in ``"file.hdf5#group"`` form.
        Strings open the target file in write mode. HDF5 objects are written
        in place.

    **set_size** : int, default=2000
        Maximum number of frames per ``set.*`` group.

    **prec** : numpy.dtype, default=numpy.float64
        Floating point precision for dumped frame data. Kept for
        consistency with ``deepmd/npy/mixed``.

    **comp_prec** : numpy.dtype, optional
        Explicit floating point precision. When provided, this overrides
        ``prec``.







:Raises:

    TypeError
        If ``file_name`` is not a string, HDF5 group, or HDF5 file.











.. _DeePMDHDF5MixedFormat_from_multi_systems:

Convert from this format to MultiSystems
````````````````````````````````````````

.. py:function:: dpdata.MultiSystems.from_deepmd_hdf5_mixed(directory) -> dpdata.system.MultiSystems
   :noindex:

   
Generate mixed HDF5 groups for MultiSystems loading.


:Parameters:

    **directory** : str or h5py.Group or h5py.File
        HDF5 file, HDF5 group, or string in ``"file.hdf5#group"`` form. The
        selected object may be either one mixed system group or a container
        of mixed groups.



:Returns:

    MultiSystems
        converted system




:Raises:

    TypeError
        If ``directory`` is not a string, HDF5 group, or HDF5 file.











.. _DeePMDHDF5MixedFormat_to_multi_systems:

Convert from MultiSystems to this format
````````````````````````````````````````

.. py:function:: dpdata.MultiSystems.to(fmt: Literal['deepmd/hdf5/mixed'], directory) -> dpdata.system.MultiSystems
   :noindex:
.. py:function:: dpdata.MultiSystems.to_deepmd_hdf5_mixed(directory) -> dpdata.system.MultiSystems
   :noindex:

   
Generate HDF5 groups for MultiSystems mixed dumping.


:Parameters:

    **directory** : str or h5py.Group or h5py.File
        HDF5 file, HDF5 group, or string in ``"file.hdf5#group"`` form.
        Strings open the target file in write mode.



:Returns:

    MultiSystems
        this system




:Raises:

    TypeError
        If ``directory`` is not a string, HDF5 group, or HDF5 file.