Metadata-Version: 2.1
Name: dpdata
Version: 0.0.2
Summary: Manipulating DeePMD-kit, VASP and LAMMPS data formats
Home-page: https://github.com/deepmodeling/dpdata
Author: Han Wang
Author-email: wang_han@iapcm.ac.cn
License: UNKNOWN
Description: 
        **dpdata** is a python package for manipulating DeePMD-kit, VASP, LAMMPS data formats.
        dpdata only works with python 3.x.
        
        Installation
        ============
        
        One can download the source code of dpdata by 
        
        .. code-block:: bash
        
           git clone https://github.com/deepmodeling/dpdata.git dpdata
        
        then use ``setup.py`` to install the module
        
        .. code-block:: bash
        
           cd dpdata
           python setup.py install
        
        ``dpdata`` can also by install via pip
        
        .. code-block:: bash
        
           pip3 install dpdata
        
        Quick start
        ===========
        
        This section gives some examples on how dpdata works. Firstly one needs to import the module in a python 3.x compatible code.
        
        .. code-block:: python
        
           import dpdata
        
        The typicall workflow of ``dpdata`` is 
        
        
        #. Load data from vasp or lammps or deepmd-kit data files.
        #. Manipulate data 
        #. Dump data to in a desired format
        
        Load data
        ---------
        
        .. code-block:: python
        
           d_poscar = dpdata.System('POSCAR', fmt = 'vasp/poscar')
        
        or let dpdata infer the format (\ ``vasp/poscar``\ ) of the file from the file name extension
        
        .. code-block:: python
        
           d_poscar = dpdata.System('my.POSCAR')
        
        The number of atoms, atom types, coordinates are loaded from the ``POSCAR`` and stored to a data ``System`` called ``d_poscar``.
        A data ``System`` (a concept used by `deepmd-kit <https://github.com/deepmodeling/deepmd-kit>`_\ ) contains frames that has the same number of atoms of the same type. The order of the atoms should be consistent among the frames in one ``System``. 
        It is noted that ``POSCAR`` only contains one frame.
        If the multiple frames stored in, for example, a ``OUTCAR`` is wanted, 
        
        .. code-block:: python
        
           d_outcar = dpdata.LabeledSystem('OUTCAR')
        
        The labels provided in the ``OUTCAR``\ , i.e. energies, forces and virials (if any), are loaded by ``LabeledSystem``. It is noted that the forces of atoms are always assumed to exist. ``LabeledSystem`` is a derived class of ``System``.
        
        The ``System`` or ``LabeledSystem`` can be constructed from the following file formats with the ``format key`` in the table passed to argument ``fmt``\ :
        
        .. list-table::
           :header-rows: 1
        
           * - Software
             - format
             - multi frames
             - labeled
             - class
             - format key
           * - vasp
             - poscar
             - False
             - False
             - System
             - 'vasp/poscar'
           * - vasp
             - outcar
             - True
             - True
             - LabeledSystem
             - 'vasp/outcar'
           * - vasp
             - xml
             - True
             - True
             - LabeledSystem
             - 'vasp/xml'
           * - lammps
             - lmp
             - False
             - False
             - System
             - 'lammps/lmp'
           * - lammps
             - dump
             - True
             - False
             - System
             - 'lammps/dump'
           * - deepmd
             - raw
             - True
             - True
             - LabeledSystem
             - 'deepmd/raw'
        
        
        Access data
        -----------
        
        These properties stored in ``System`` and ``LabeledSystem`` can be accessed by operator ``[]`` with the key of the property supplied, for example
        
        .. code-block:: python
        
           coords = d_outcar['coords']
        
        Available properties are (nframe: number of frames in the system, natoms: total number of atoms in the system)
        
        .. list-table::
           :header-rows: 1
        
           * - key
             - type
             - dimension
             - are labels
             - description 
           * - 'atom_names'
             - list of str
             - ntypes
             - False
             - The name of each atom type
           * - 'atom_numbs'
             - list of int
             - ntypes
             - False
             - The number of atoms of each atom type
           * - 'atom_types'
             - np.ndarray
             - natoms
             - False
             - Array assigning type to each atom
           * - 'cells'
             - np.ndarray
             - nframes x 3 x 3
             - False
             - The cell tensor of each frame
           * - 'coords'
             - np.ndarray
             - nframes x natoms x 3
             - False
             - The atom coordinates
           * - 'energies'
             - np.ndarray
             - nframes
             - True
             - The frame energies
           * - 'forces'
             - np.ndarray
             - nframes x natoms x 3
             - True
             - The atom forces
           * - 'virials'
             - np.ndarray
             - nframes x 3 x 3
             - True
             - The virial tensor of each frame
        
        
        Dump data
        ---------
        
        The data stored in ``System`` or ``LabeledSystem`` can be dumped in 'lammps/lmp' or 'vasp/poscar' format, for example:
        
        .. code-block:: python
        
           d_outcar.to_lammps_lmp('conf.lmp', frame_idx=0)
        
        The first frames of ``d_outcar`` will be dumped to 'conf.lmp'
        
        .. code-block:: python
        
           d_outcar.to_vasp_poscar('POSCAR', frame_idx=-1)
        
        The last frames of ``d_outcar`` will be dumped to 'POSCAR'.
        
        The data stored in ``LabeledSystem`` can be dumped to deepmd-kit raw format, for example
        
        .. code-block:: python
        
           d_outcar.to_deepmd_raw('dpmd_raw')
        
        Or a simpler command:
        
        .. code-block:: python
        
           dpdata.LabeledSystem('OUTCAR').to_deepmd_raw('dpmd_raw')
        
        Frame selection can be implemented by
        
        .. code-block:: python
        
           dpdata.LabeledSystem('OUTCAR').sub_system([0,-1]).to_deepmd_raw('dpmd_raw')
        
        by which only the first and last frames are dumped to ``dpmd_raw``.
        
Keywords: lammps vasp deepmd-kit
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3.6
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Description-Content-Type: text/markdown
