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.
- 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
- 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.
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.
- Structure Analysis
- Ackland Jones Analysis
- Atomic Shear Strain
- CentroSymmetry Parameter
- Common Neighbor Analysis
- Common Neighbor Parameter
- Atomic Structure Entropy
- Steinhardt Bondorder
- Radiul Distribution Function
- Polyhedral Template Matching
- Identify stacking faults (SFs) and twinning boundary (TBs)
- Identify Diamond structure
- Bond Analysis
- Potential Analysis
- Phonon Calculation
- Melting Analysis
- Deep Learning Potential Database Preparing
- Geometry Structure Creation
- Neighbor Search
- I/O
- Other
Dependencies (Support Python 3.8-3.11)
| Package Name | Version | Features |
| taichi | >=1.7.1 | Do parallel computing. |
| numpy | <2.0 | Data structure. |
| scipy | latest | Build kdtree, do FFT, spline interpolation. |
| polars | >=1.8.0 | Fast read/save file. Data structure to represent the particles information. |
| matplotlib | latest | Plot the results. |
| polyscope | latest | Provide GUI interface. |
| tqdm | latest | Show progress bar. |
| Package Name | Version | Features |
| k3d | latest | Visualize the 3D atoms in Jupyter. |
| pyfftw | latest | Faster FFT. |
| phonopy | latest | Do phonon calculation. |
| lammps | latest | Compute atomic energy, force and virial using lammps supported potential. |
pip install mdapyOne can install optional dependencies. For example:
# This will also install the k3d package.
pip install mdapy[k3d]# 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:
conda install -c conda-forge phonopyIf 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. A simple installation way can be found here.
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.
git clone https://github.com/mushroomfire/mdapy.git cd mdapy pip install .
python -c "import mdapy as mp; mp.init(); print('mdapy version is:', mp.__version__)"If you encounter ImportError in Linux:
version 'GLIBCXX_X.X.X' not found.You can install mdapy from source.
pip install https://github.com/mushroomfire/mdapy/archive/master.zipIf you encounter GUI problem:
GLFW emitted error...You can solve it by enableing GPU direct passthrough, see issue.
If you want to build mannual locally, you can install the dependencies:
pip install Sphinx nbsphinx sphinx-rtd-theme
conda install pandocThen changing to ./doc dir:
make htmlIf 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}
}