.. _DeePMDRawFormat:

deepmd/raw format
=================

Aliases
-------

``deepmd``, ``deepmd/raw``

Implementation: :class:`DeePMDRawFormat <dpdata.plugins.deepmd.DeePMDRawFormat>`

Overview
--------


DeePMD-kit raw text dataset directory.

`DeePMD-kit <https://github.com/deepmodeling/deepmd-kit>`_ is a deep
learning package for training interatomic potentials. A raw dataset stores
atom types in ``type.raw`` and frame properties in text files such as
``coord.raw``, ``box.raw``, ``energy.raw``, and ``force.raw``. It is
human-readable and convenient for inspection, but ``deepmd/npy`` is
usually smaller and faster for training.
















Quick examples
--------------

The examples use the preferred alias ``deepmd/raw``; any alias listed above is equivalent.

.. code-block:: python

   import dpdata
   
   # Geometry-only data
   system = dpdata.System("input_file", fmt="deepmd/raw")
   
   # Data with energies and forces
   labeled_system = dpdata.LabeledSystem("input_file", fmt="deepmd/raw")
   
   # Multiple compositions or calculation directories
   systems = dpdata.MultiSystems.from_file("input_directory", fmt="deepmd/raw")
   
   # Write geometry-only data
   system.to("deepmd/raw", "output_path")
   
   # Write multiple systems
   systems.to("deepmd/raw", "output_path")

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

.. _DeePMDRawFormat_from_system:

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

.. py:function:: dpdata.System(file_name, type_map=None, fmt: Literal['deepmd'] = None, **kwargs) -> dpdata.system.System
   :noindex:
.. py:function:: dpdata.System(file_name, type_map=None, fmt: Literal['deepmd/raw'] = None, **kwargs) -> dpdata.system.System
   :noindex:
.. py:function:: dpdata.System.from_deepmd(file_name, type_map=None, **kwargs) -> dpdata.system.System
   :noindex:
.. py:function:: dpdata.System.from_deepmd_raw(file_name, type_map=None, **kwargs) -> dpdata.system.System
   :noindex:

   
Load an unlabeled DeePMD raw dataset.


:Parameters:

    **file_name** : str or os.PathLike
        DeePMD raw dataset directory.

    **type_map** : list[str], optional
        Element names used when ``type_map.raw`` is absent, or a requested
        ordering used to remap the stored atom types.

    **\*\*kwargs** : dict
        Additional format arguments accepted for API compatibility.



:Returns:

    System
        converted system















.. _DeePMDRawFormat_to_system:

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

.. py:function:: dpdata.System.to(fmt: Literal['deepmd'], file_name, **kwargs)
   :noindex:
.. py:function:: dpdata.System.to(fmt: Literal['deepmd/raw'], file_name, **kwargs)
   :noindex:
.. py:function:: dpdata.System.to_deepmd(file_name, **kwargs)
   :noindex:
.. py:function:: dpdata.System.to_deepmd_raw(file_name, **kwargs)
   :noindex:

   
Write a System or LabeledSystem as DeePMD raw text files.


:Parameters:

    **file_name** : str or os.PathLike
        Destination dataset directory.

    **\*\*kwargs** : dict
        Additional format arguments accepted for API compatibility.


















.. _DeePMDRawFormat_to_labeled_system:

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

.. py:function:: dpdata.LabeledSystem.to(fmt: Literal['deepmd'], file_name, **kwargs)
   :noindex:
.. py:function:: dpdata.LabeledSystem.to(fmt: Literal['deepmd/raw'], file_name, **kwargs)
   :noindex:
.. py:function:: dpdata.LabeledSystem.to_deepmd(file_name, **kwargs)
   :noindex:
.. py:function:: dpdata.LabeledSystem.to_deepmd_raw(file_name, **kwargs)
   :noindex:

   
Write a System or LabeledSystem as DeePMD raw text files.


:Parameters:

    **file_name** : str or os.PathLike
        Destination dataset directory.

    **\*\*kwargs** : dict
        Additional format arguments accepted for API compatibility.


















.. _DeePMDRawFormat_from_labeled_system:

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

.. py:function:: dpdata.LabeledSystem(file_name, type_map=None, fmt: Literal['deepmd'] = None, **kwargs) -> dpdata.system.LabeledSystem
   :noindex:
.. py:function:: dpdata.LabeledSystem(file_name, type_map=None, fmt: Literal['deepmd/raw'] = None, **kwargs) -> dpdata.system.LabeledSystem
   :noindex:
.. py:function:: dpdata.LabeledSystem.from_deepmd(file_name, type_map=None, **kwargs) -> dpdata.system.LabeledSystem
   :noindex:
.. py:function:: dpdata.LabeledSystem.from_deepmd_raw(file_name, type_map=None, **kwargs) -> dpdata.system.LabeledSystem
   :noindex:

   
Load a labeled DeePMD raw dataset.


:Parameters:

    **file_name** : str or os.PathLike
        DeePMD raw dataset directory.

    **type_map** : list[str], optional
        Element names or requested type ordering used while loading.

    **\*\*kwargs** : dict
        Additional format arguments accepted for API compatibility.



:Returns:

    LabeledSystem
        converted system















.. _DeePMDRawFormat_from_multi_systems:

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

.. py:function:: dpdata.MultiSystems.from_deepmd(directory, **kwargs) -> dpdata.system.MultiSystems
   :noindex:
.. py:function:: dpdata.MultiSystems.from_deepmd_raw(directory, **kwargs) -> dpdata.system.MultiSystems
   :noindex:

   
Convert this format to :class:`MultiSystems`.


:Parameters:

    **directory** : str
        directory of systems



:Returns:

    MultiSystems
        converted system















.. _DeePMDRawFormat_to_multi_systems:

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

.. py:function:: dpdata.MultiSystems.to(fmt: Literal['deepmd'], directory, **kwargs) -> dpdata.system.MultiSystems
   :noindex:
.. py:function:: dpdata.MultiSystems.to(fmt: Literal['deepmd/raw'], directory, **kwargs) -> dpdata.system.MultiSystems
   :noindex:
.. py:function:: dpdata.MultiSystems.to_deepmd(directory, **kwargs) -> dpdata.system.MultiSystems
   :noindex:
.. py:function:: dpdata.MultiSystems.to_deepmd_raw(directory, **kwargs) -> dpdata.system.MultiSystems
   :noindex:

   
Convert :class:`MultiSystems` to this format.


:Parameters:

    **directory** : str
        directory to save systems



:Returns:

    MultiSystems
        this system