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 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, POSCAR format in VASP, universal XYZ format and CIF format. Besides, all data in mdapy is stored in NDARRAY format in NumPy, which enables easy integration with the scientific ecosystem in python and facilitates collaboration with other post-progressing tools such as OVITO and freud.

Resources

• Homepage: https://github.com/mushroomfire/mdapy

• Documentation: https://mdapy.readthedocs.io/

• Issue Tracker: https://github.com/mushroomfire/mdapy/issues

• Tutorial: https://github.com/mushroomfire/mdapy-tutorial

Dependencies

• python (3.8-3.11)

• taichi>=1.7.1

• numpy

• scipy

• polars>=0.20.22

• matplotlib

• polyscope

Optional Dependencies

• k3d (Visualizing the 3D atoms)

• tqdm (Show progress bar when reading/saving multi files)

• pyfftw (Fast FFT)

• phonopy (Do phonon calculation)

• lammps (Compute atomic energy, force and virial using lammps supported potential)

Citation

If you find mdapy useful, you can star it! If you use mdapy in your scientific publications, please cite the paper:

@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}
   }

Getting Started

• Installation
  • Install from pip (recommended).
  • Install from source code.
• QuicklyStart
  • This is a quick start guide to show users what mdapy can do and how it should be implemented, for more specific information check out the API in the documentation.
    • Import corresponding packages
    • Generate a System class from a dump file, which can be found in example folder and come from the Supplementary materials of this paper.
    • Check the data of System.
    • Calculate the average entropy fingerprint.
    • Calculate the CSP.
    • Calculate the CNA pattern.
    • Calculate the Voronoi volume.
    • Check the calculated results.
    • Check the cutoff distance now.
    • Neighbor atom index of atom 0 withing the cutoff distance.
    • Corresponding distance from atom 0 to its neighbor atoms.
    • Validate the distance between atom 0 and atom 896.
    • Save the results to the disk.
    • Do the spatial binning of entropy along xy plane.
    • Binning coordinations.
    • Plot the binning results.
    • Calculate the WCP to reveal the short-range order in alloy.
    • Results show high SRO degree.
    • Calculate the radiul distribution function (RDF).
    • Plot the RDF results.
    • Plot the partial RDF results.
    • One can save the figure easily.
    • Analyze the atomic trajectories
    • Generate a random walk trajectories.
    • Calculate the mean squared displacement (MSD).
    • Check the MSD results.
    • Plot the MSD results.
    • Calculate the Lindemann index.
    • Plot the Lindemann index results.
    • Analyze EAM potential.
    • Generate an average EAM potential is simple.
    • Read this average potential file.
    • Plot the results. A is the virtual element.
• Examples
  • 1. Structure analysis
  • 2. Mean squared displacement and Lindemann index
  • 3. Calculate WCP matrix in high-entropy alloy
  • 4. Create polycrystalline with graphene boundary
  • 5. Calculate the EOS curve
  • 1. Collaborative use with Ovito
  • 7. Identify stacking faults (SFs) and twin boundaries (TBs) in Ovito
• Calculate GSFE
  • This script will use mdapy to calculate the generalized stacking fault energy directly
  • Generate a FCC lattice with orientation x[11-2], y[1-10] and z[111]
  • Change boundary condition to free along z axis
  • Calculate the initial potential energy
  • Calculate the GSFE along [112] direction
  • Plot the results
• Phonon Calculation
  • This script will show how to use mdapy to calculate phonon dispersion.
    • One should install Phonopy by one of the following ways:
  • We use graphene as an example.
  • NEP potential
  • Computer dos
  • Compute pdos
  • Compute thermal properties
  • Airebo potential
  • ReaxFF potential
• User-defined potential
• Visualize Atoms
  • This script will use mdapy (>=0.9.7) to visualize the 3D atoms model.
  • Build a polycrystalline as an example
  • Build a system
  • Display the configurations
  • Colored by the grain id
  • Colored by the structure type
• Use mdapy efficiently
  • The key point is re-using the neighborlist information.
  • Build a FCC lattice with 4,000,000 atoms.
  • Generate a system class.
  • Check the system information.
  • Direct calculation.
  • Re-use neighborlist information.
• Precautions
  • Here we discuss some precautions when using mdapy.
  • Check the position information
• Read and Save file
  • mdapy can read/save file very efficiently. Including Dump, Data and Dump.gz formats.
  • The performance of mdapy is around 2-7 times higher than ovito.
  • Prepare a Data, Dump, Dump.gz files
  • Read a dump file in mdapy
  • Read a dump file in OVITO
  • Read a data file in mdapy
  • Read a data file in ovito
  • Read a dump.gz file in mdapy
  • Read a dump.gz file in ovito
  • Save a dump file in mdapy
  • Save a dump file in OVITO
  • Save a data file in mdapy
  • Save a data file in ovito
  • Save a dump.gz file in mdapy
  • Save a dump.gz file in ovito
• Benchmark
  • Benchmark for NeighborSearch in mdapy and freud.
• Main Features

Mdapy Python API

• mdapy