.. _ASEStructureFormat:

ase/structure format
====================

Class: :class:`ASEStructureFormat <dpdata.plugins.ase.ASEStructureFormat>`


Format for the `Atomic Simulation Environment <https://wiki.fysik.dtu.dk/ase/>`_ (ase).

ASE supports parsing a few dozen of data formats. As described in i
`the documentation <ihttps://wiki.fysik.dtu.dk/ase/ase/io/io.html>`_,
many of these formats can be determined automatically.
Use the `ase_fmt` keyword argument to supply the format if
automatic detection fails.
















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

.. _ASEStructureFormat_from_system:

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

.. py:function:: dpdata.System(atoms: 'ase.Atoms', fmt: Literal['ase/structure'] = None) -> dpdata.system.System
   :noindex:
.. py:function:: dpdata.System.from_ase_structure(atoms: 'ase.Atoms') -> dpdata.system.System
   :noindex:

   
Convert ase.Atoms to a System.


:Parameters:

    **atoms** : ase.Atoms
        an ASE Atoms, containing a structure



:Returns:

    System
        converted system















.. _ASEStructureFormat_to_system:

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

.. py:function:: dpdata.System.to(fmt: Literal['ase/structure']) -> 'list[ase.Atoms]'
   :noindex:
.. py:function:: dpdata.System.to_ase_structure() -> 'list[ase.Atoms]'
   :noindex:

   
Convert System to ASE Atom obj.




















.. _ASEStructureFormat_to_labeled_system:

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

.. py:function:: dpdata.LabeledSystem.to(fmt: Literal['ase/structure']) -> 'list[ase.Atoms]'
   :noindex:
.. py:function:: dpdata.LabeledSystem.to_ase_structure() -> 'list[ase.Atoms]'
   :noindex:

   
Convert System to ASE Atoms object.




















.. _ASEStructureFormat_from_labeled_system:

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

.. py:function:: dpdata.LabeledSystem(atoms: 'ase.Atoms', fmt: Literal['ase/structure'] = None) -> dpdata.system.LabeledSystem
   :noindex:
.. py:function:: dpdata.LabeledSystem.from_ase_structure(atoms: 'ase.Atoms') -> dpdata.system.LabeledSystem
   :noindex:

   
Convert ase.Atoms to a LabeledSystem. Energies and forces
are calculated by the calculator.

Note that this method will try to load virials from either virial field or converted from stress tensor.

:Parameters:

    **atoms** : ase.Atoms
        an ASE Atoms, containing a structure



:Returns:

    LabeledSystem
        converted system




:Raises:

    RuntimeError
        ASE will raise RuntimeError if the atoms does not
        have a calculator











.. _ASEStructureFormat_from_multi_systems:

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

.. py:function:: dpdata.MultiSystems.from_ase_structure(file_name: 'str', begin: 'int | None' = None, end: 'int | None' = None, step: 'int | None' = None, ase_fmt: 'str | None' = None) -> dpdata.system.MultiSystems
   :noindex:

   
Convert a ASE supported file to ASE Atoms.

It will finally be converted to MultiSystems.

:Parameters:

    **file_name** : str
        path to file

    **begin** : int, optional
        begin frame index

    **end** : int, optional
        end frame index

    **step** : int, optional
        frame index step

    **ase_fmt** : str, optional
        ASE format. See the ASE documentation about supported formats



:Returns:

    MultiSystems
        converted system