.. image:: https://img.pterclub.com/images/2023/01/06/logo.png

mdapy : Molecular Dynamics Analysis with Python

Overview

The mdapy python library provides an array of powerful, flexible, and straightforward tools to analyze atomic trajectories generated from Molecular Dynamics (MD) simulations. The library is fully cross-platform, making it accessible to users in Windows, Linux, and Mac OS. Benefited by the TaiChi <https://github.com/taichi-dev/taichi>_ project, we can effectively accelerate the pure python code, bringing it closer to the speed of code written in C++. Furthermore, mdapy is highly parallelized, allowing users to leverage the resources of both multicore CPU and GPU. mdapy can directly handle the DUMP and DATA formats in LAMMPS <https://www.lammps.org/>, POSCAR format in VASP <https://www.vasp.at/wiki/index.php/The_VASP_Manual>, universal XYZ format and CIF format. Besides, all data in mdapy is stored in NDARRAY format in NumPy <https://numpy.org/>, which enables easy integration with the scientific ecosystem in python and facilitates collaboration with other post-progressing tools such as OVITO <https://www.ovito.org/> and freud <https://github.com/glotzerlab/freud>_.

Resources

• Homepage: https://github.com/mushroomfire/mdapy <https://github.com/mushroomfire/mdapy>_
• Documentation: https://mdapy.readthedocs.io/ <https://mdapy.readthedocs.io/>_
• Issue Tracker: https://github.com/mushroomfire/mdapy/issues <https://github.com/mushroomfire/mdapy/issues>_
• Tutorial: https://github.com/mushroomfire/mdapy-tutorial <https://github.com/mushroomfire/mdapy-tutorial>_

GUI Mode

• After installing mdapy, type mdapy at CMD can start the GUI mode. Note that this mode only runs on Windows platform now.
• A standalone version can be found in release page.

.. image:: doc/source/images/GUI.gif

Script Mode

.. code-block:: bash

In [1]: import mdapy as mp [Taichi] version 1.6.0, llvm 15.0.1, commit f1c6fbbd, win, python 3.8.0

In [2]: mp.init('cpu') # Use cpu, mp.init('gpu') will use gpu to compute. [Taichi] Starting on arch=x64

In [3]: system=mp.System('CoCuFeNiPd-4M.dump') # Load a Dump file generated by LAMMPS.

In [4]: print(system) # Check the particle information. Filename: CoCuFeNiPd-4M.dump Atom Number: 8788 Simulation Box: [[47.36159615 0. 0. ] [ 0. 47.46541884 0. ] [ 0. 0. 47.46849764] [-1.18079807 -1.23270942 -1.23424882]] TimeStep: 0 Boundary: [1, 1, 1] Particle Information: shape: (8_788, 5) ┌──────┬──────┬───────────┬───────────┬───────────┐ │ id ┆ type ┆ x ┆ y ┆ z │ │ --- ┆ --- ┆ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ f64 ┆ f64 ┆ f64 │ ╞══════╪══════╪═══════════╪═══════════╪═══════════╡ │ 1 ┆ 2 ┆ 0.006118 ┆ -0.310917 ┆ -0.345241 │ │ 2 ┆ 4 ┆ 1.9019 ┆ -0.292456 ┆ 1.48488 │ │ 3 ┆ 3 ┆ -0.015641 ┆ 1.58432 ┆ 1.43129 │ │ 4 ┆ 5 ┆ 1.86237 ┆ 1.51117 ┆ -0.372278 │ │ … ┆ … ┆ … ┆ … ┆ … │ │ 8785 ┆ 4 ┆ 43.4575 ┆ 43.7371 ┆ 43.6083 │ │ 8786 ┆ 4 ┆ 45.3771 ┆ 43.7577 ┆ 45.2727 │ │ 8787 ┆ 4 ┆ 43.4552 ┆ 45.4854 ┆ 45.2825 │ │ 8788 ┆ 1 ┆ 45.3919 ┆ 45.4009 ┆ 43.4999 │ └──────┴──────┴───────────┴───────────┴───────────┘

In [5]: system.cal_voronoi_volume() # Calculate Voronoi volume in parallel.

In [6]: system.cal_polyhedral_template_matching() # Lattice structure identification by PTM algorithm in parallel.

In [7]: print(system.data.head()) # Check the calculation results. shape: (5, 9) ┌─────┬──────┬───────────┬───────────┬───┬────────────────┬────────────────┬───────────────┬─────────────────┐ │ id ┆ type ┆ x ┆ y ┆ … ┆ voronoi_volume ┆ voronoi_number ┆ cavity_radius ┆ structure_types │ │ --- ┆ --- ┆ --- ┆ --- ┆ ┆ --- ┆ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ f64 ┆ f64 ┆ ┆ f64 ┆ i32 ┆ f64 ┆ i32 │ ╞═════╪══════╪═══════════╪═══════════╪═══╪════════════════╪════════════════╪═══════════════╪═════════════════╡ │ 1 ┆ 2 ┆ 0.006118 ┆ -0.310917 ┆ … ┆ 12.68101 ┆ 15 ┆ 3.675684 ┆ 1 │ │ 2 ┆ 4 ┆ 1.9019 ┆ -0.292456 ┆ … ┆ 12.012947 ┆ 14 ┆ 3.581766 ┆ 1 │ │ 3 ┆ 3 ┆ -0.015641 ┆ 1.58432 ┆ … ┆ 12.197214 ┆ 12 ┆ 3.674408 ┆ 1 │ │ 4 ┆ 5 ┆ 1.86237 ┆ 1.51117 ┆ … ┆ 12.900968 ┆ 15 ┆ 3.713117 ┆ 1 │ │ 5 ┆ 5 ┆ 3.79257 ┆ -0.331891 ┆ … ┆ 12.400861 ┆ 14 ┆ 3.645415 ┆ 1 │ └─────┴──────┴───────────┴───────────┴───┴────────────────┴────────────────┴───────────────┴─────────────────┘

In [8]: system.write_dump() # Save results to a Dump file.

Visualize Configurations in Jupyter <https://mdapy.readthedocs.io/en/latest/gettingstarted/visualizing_atoms.html>_

.. image:: doc/source/images/visualize.gif

Main Features

1. Structure Analysis

   • Ackland Jones Analysis <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.ackland_jones_analysis>_
   • Atomic Shear Strain <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.atomic_strain>_
   • CentroSymmetry Parameter <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.centro_symmetry_parameter>_
   • Common Neighbor Analysis <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.common_neighbor_analysis>_
   • Common Neighbor Parameter <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.common_neighbor_parameter>_
   • Atomic Structure Entropy <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.entropy>_
   • Steinhardt Bondorder <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.steinhardt_bond_orientation>_
   • Radiul Distribution Function <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.pair_distribution>_
   • Polyhedral Template Matching <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.polyhedral_template_matching>_
   • Identify stacking faults (SFs) and twinning boundary (TBs) <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.identify_SFs_TBs>_
   • Identify Diamond structure <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.identify_diamond_structure>_
   • Bond Analysis <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.bond_analysis>_

2. Potential Analysis

   • Generate EAM/alloy Potential <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.eam_generate>_
   • Read EAM/alloy Potential <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.potential>_
   • Average EAM/alloy Potential <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.eam_average>_
   • Calculate Atomic Force and Energy by EAM/alloy <https://mdapy.readthedocs.io/en/latest/mdapy.html#mdapy.potential.EAM>_

3. Phonon Calculation

   • Cell optimization <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.cell_opt>_
   • Calculate phonon dispersion, dos and thermal properties, supporting any kind of potential formats <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.phonon>_

4. Melting Analysis

   • Mean Squared Displacement <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.mean_squared_displacement>_
   • Lindemann Parameter <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.lindemann_parameter>_
   • Identify Solid/Liquid Phase <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.steinhardt_bond_orientation>_

5. Deep Learning Potential Database Preparing

   • Generate perturbation models <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.perturb_model>_
   • Extract DFT data to XYZ format for NEP training <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.dft2nepxyz>_
   • Calculate Atomic Force and Energy by NEP <https://mdapy.readthedocs.io/en/latest/mdapy.html#mdapy.potential.NEP>_

6. Geometry Structure Creation

   • Generate Standard Lattice Structure <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.lattice_maker>_
   • Generate Polycrystal <https://mdapy.readthedocs.io/en/latest/mdapy.html#mdapy.create_polycrystalline.CreatePolycrystalline>_

7. Neighbor Search

   • Neighbor Atoms within Fixed Distance <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.neighbor>_
   • Neighbor Atoms within Fixed Number <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.nearest_neighbor>_

8. I/O

   • Load Dump, Data, POSCAR, XYZ, cif format <https://mdapy.readthedocs.io/en/latest/mdapy.html#mdapy.system.System>_
   • Export Dump, Data, POSCAR, XYZ, cif format <https://mdapy.readthedocs.io/en/latest/mdapy.html#mdapy.system.System>_

9. Other

   • Void Distribution <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.void_distribution>_
   • Cluster Analysis <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.cluser_analysis>_
   • Replication <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.replicate>_
   • Warren Cowley Parameter <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.warren_cowley_parameter>_
   • Identify species <https://mdapy.readthedocs.io/en/latest/mdapy.html#mdapy.system.System>_
   • Average Atomic Temperature <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.temperature>_
   • Atomic Voronoi Volume <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.voronoi_analysis>_
   • Multi-dimensional Spatial Binning <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.spatial_binning>_
   • Parallelly Compress file to .gz format <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.pigz>_
   • Split xyz/dump trajectories into seperate xyz/dump files <https://mdapy.readthedocs.io/en/latest/mdapy.html#mdapy.tool_function.split_dump>_
   • Minimization <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.minimizer>_
   • OrthogonalBox <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.orthogonal_box>_

Dependencies (Support Python <https://www.python.org/>_ 3.8-3.11)

.. list-table::

*   -   **Package Name**
    -   **Version**
    -   **Features**
*   -   `taichi <https://github.com/taichi-dev/taichi>`_
    -   >=1.7.1
    -   Do parallel computing.
*   -   `numpy <https://numpy.org/>`_
    -   <2.0
    -   Data structure.
*   -   `scipy <https://scipy.org/>`_
    -   latest
    -   Build kdtree, do FFT, spline interpolation.
*   -   `polars <https://pola-rs.github.io/polars/>`_
    -   >=1.8.0
    -   Fast read/save file. Data structure to represent the particles information.
*   -   `matplotlib <https://matplotlib.org/>`_
    -   latest
    -   Plot the results.
*   -   `polyscope <https://polyscope.run/py/>`_
    -   latest
    -   Provide GUI interface.
*   -   `tqdm <https://github.com/tqdm/tqdm>`_
    -   latest
    -   Show progress bar.

Optional Dependencies

.. list-table::

*   -   **Package Name**
    -   **Version**
    -   **Features**
*   -   `k3d <https://github.com/K3D-tools/K3D-jupyter>`_
    -   latest
    -   Visualize the 3D atoms in Jupyter.
*   -   `pyfftw <https://github.com/pyFFTW/pyFFTW>`_
    -   latest
    -   Faster FFT.
*   -   `phonopy <https://github.com/phonopy/phonopy>`_
    -   latest
    -   Do phonon calculation.
*   -   `lammps <https://github.com/lammps/lammps>`_ 
    -   latest
    -   Compute atomic energy, force and virial using lammps supported potential.

Installation

Install from pip (recommended). ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

pip install mdapy

One can install optional dependencies. For example:

.. code-block:: bash

This will also install the k3d package.

pip install mdapy[k3d]

.. code-block:: bash

This will install all optional packages (k3d, pyfftw) except phonopy and lammps.

pip install mdapy[all]

If one wants to install phonopy, the best way is:

.. code-block:: bash

conda install -c conda-forge phonopy

If one wants to use lammps supported potential to calculate atomic force and phonon properties, one can install the lammps-python interface referring to the official guide <https://docs.lammps.org/Python_install.html>. A simple installation way can be found here <https://github.com/mushroomfire/lammps_nep>.

Install from source code. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

• You should have a C++ compilation environment (-std=c++11 or newer) and openmp supports. Tested by MSVC in Windows 10, GCC in Ubuntu, Clang in MAC OS M1.

• Download the source code and installation.

  .. code-block:: bash

  git clone https://github.com/mushroomfire/mdapy.git
  cd mdapy 
  pip install .
  

Check Installation ^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

python -c "import mdapy as mp; mp.init(); print('mdapy version is:', mp.version)"

Trouble Shoot

If you encounter ImportError in Linux:

.. code-block:: bash

version 'GLIBCXX_X.X.X' not found.

You can install mdapy from source.

.. code-block:: bash

pip install https://github.com/mushroomfire/mdapy/archive/master.zip

If you encounter GUI problem:

.. code-block:: bash

GLFW emitted error...

You can solve it by enableing GPU direct passthrough, see issue <https://github.com/mushroomfire/mdapy/issues/2#issuecomment-2033441993>_.

Build the doc

If you want to build mannual locally, you can install the dependencies:

.. code-block:: bash

pip install Sphinx nbsphinx sphinx-rtd-theme conda install pandoc

Then changing to ./doc dir:

.. code-block:: bash

make html

Citation

If you find mdapy useful, you can star it! <https://github.com/mushroomfire/mdapy>_ If you use mdapy in your scientific publications, please cite the paper: <https://doi.org/10.1016/j.cpc.2023.108764>_

.. code-block:: bibtex

@article{mdapy2023, title = {mdapy: A flexible and efficient analysis software for molecular dynamics simulations}, journal = {Computer Physics Communications}, pages = {108764}, year = {2023}, issn = {0010-4655}, doi = {https://doi.org/10.1016/j.cpc.2023.108764}, url = {https://www.sciencedirect.com/science/article/pii/S0010465523001091}, author = {Yong-Chao Wu and Jian-Li Shao}, keywords = {Simulation analysis, Molecular dynamics, Polycrystal, TaiChi, Parallel computing} }