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
- 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 | >=0.20.26 | 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 mdapy
One 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 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.
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.zip
If you want to build mannual locally, you can install the dependencies:
pip install Sphinx nbsphinx sphinx-rtd-theme
conda install pandoc
Then changing to ./doc dir:
make html
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}
}
- Improve the performance for split_dump and split_xyz method.
- Add minimizer with FIRE method.
- Add an example to compute Vacancy Formation energy.
- Fix a bug for cell_opt class.
- Fix a bug for neighbor class.
- Add new feature to calculate the Atomic Shear Strain.
- Fix a bug for RDF with partial interaction.
- Fix a bug for reading cp2k output file with OT method.
- Fix a bug for create_polycrystalline module.
- Fix a bug for reading xyz.
- Refactor the code about generating box, supporting all triclinic box now. The previous version only support lammps style triclinic box.
- Add the farthest point sampling method to select the configuration by descriptor.
- Add stress_max parameter for DFT2NEPXYZ class.
- Fix a bug for obtaining descriptor in NEP interface.
- Fix a bug for reading xyz.
- Refactor code of unwraping position.
- Let read/write xyz containing the global information, such as energy, virial and stress.
- Add cutoff_radius and displacement parameter in Phonon class.
- Rewrite the plot_dispersion function to make users custom figures easily.
- Reading POSCAR dose not need to rotate the box.
- Add MANIFEST.in file.
- Let tqdm as a dependency package.
- Fix frame counter in DFT2NEPXYZ.
- Fix a bug for NEP potential with triclinic box.
- Add write_cp2k method.
- Fix a bug when reading xyz.
- Fix a bug when writing cif.
- Fix a bug for phonon calculation.
- Add phonon calculation feature based on the phonopy, supporting any kind of potential format.
- Add atomic virial computation for eam/alloy potential.
- Fix a bug for NEP interface.
- Fix a bug for read_data.
- Add feature of cell_opt, using lammps as calculation backend.
- Add phonopy and lammps as optional package.
- Add force_max and mode parameter for DFT2NEPXYZ class.
- Support taichi>=1.7.1.
- Support polars>=0.20.22.
- Update readme.
- Fix a typo bug in DFT2NEPXYZ class.
- Refactor the code structure. Delete calculator file. Remove timer into tool_function file.
- Support NEP model to evaluate the energy, force and virial.
- Add feature for generating initial geometry model with perturbation, which is helpful to prepare the initial database for deep learning. The function is similar to init_bulk and init_surf in dpgen.
- Add feature for converge cp2k output to xyz format for NEP trainning.
- Add feature to split dump/xyz containing multi frames into seperate frames.
- Optimize timer decorators.
- Fix bug when writing cif and POSCAR.
- Fix bug for create_polycrystalline when input wrong box, and optimize the performance of deleting overlap atoms.
- Make mdapy support polars>=0.20.19.
- Add feature for plotting phonon dispersion based on the data generated by phonopy.
- Fix bug for writing xyz.
- Make mdapy support polars>=0.20.15
- Fix bug when read/write POSCAR with reduced positions.
- Fix bug when read data file with multi space.
- Fix bug when read dump with reduced positions.
- Add support for write data with type name list.
- Support read/write simple Crystallographic Information File cif format.
- Significantly optimize the performance of Neighbor class.
- Add label for colorbar while visualizing in jupyter.
- Provide a GUI interface based on the polyscope.
- Provide a GUI software for Windows platform.
- Fix a bug when generating System from array with velocity.
- Modify repr of System to print entire DataFrame.
- Fix a bug in pair_distribution class.
- Fix a bug when loading dump file.
- Fix a bug in PTM module.
- Update polars version to 0.20.0
- Updated README.
- Make mdapy support polars>=0.19.17
- Make mdapy support taichi>=1.7.0
- Fix a bug in void_distribution class
- Fix a bug when system with small size
- Change the display when system pos changed
- Rewrite the pltset and add a set_figure feature, which makes plotting easier.
- We can use elemental list to calculate the atomic temperature now.
- Fix a bug when loading xyz file.
- Update support for Polars>=0.19.14.
- Prepared to support Python 3.12.
- Remove the SciencePlots and pyfnntw as optional dependency for concise.
- Update support for Polars>=0.19.13
- Support clustering with multi cutoff distance for different elemental pairs.
- Add species clustering feature.
- Let k3d be an optional dependency. One can install it only if you need visualize the System in Jupyter environment.
- Experimentally support Visualizing System (only in Jupyter environment).
- Add k3d as a dependency.
- Add jupyter as a dependency.
- One can explicitly assign the type number when writing to data file.
- Support load/save POSCAR format.
- Support load/save XYZ format.
- Fix the documentations.
- Add a dynamic logo.
- Improve the memory use for System class.
- Improve the README.
- Add plot for 3D spatial binning.
- Remove dependency for Pandas and Pyarrow. mdapy uses Polars to be the newer DataFrame structure.
- Updated Documentation.
- Improve the importing speed.
- Minor improvement on compilation speed.
- Support generating special crystalline orientations for FCC and BCC lattice.
- Fix bug for warpping positions.
- Fix bug for write dump.
- Fix bug for generate System class from np.ndarray.
- Update an example to calculate the Generalized Stacking Fault Energy (GSFE).
- Fix capacity of cross-platform.
- Updated doc.
- Add Polars as dependency package. Now we still use pandas, but mdapy maybe move to polars in the future.
- Optimize the performance of reading and saving Dump and Data file.
- Support loading/saving compressed Dump file (such as sample.dump.gz).
- Support the lowest python version to 3.8.0.
- Add pyproject.toml.
- Support triclinic box now!!!
- Add Select feature.
- Rewrite the load and save module.
- Make many method suitable for small system.
- Fix some bugs.
- Fix installation in python 3.11.5.
- Fix memory leak in SpatialBinning class, not the correct issue.
- Fix bug in SteinhardtBondOrientation class.
- Fix bug in read data.
- Fix bug in spatial_binning.
- Updated the IdentifySFTBinFCC class to identify the twinning and extrinsic stacking fault.
- Updated Taichi to 1.6.0, which decreases the import time and supports Python 3.11.
- Fix bug in read data.
- Updated mdapy citation. We are pleased that our article for mdapy has been accepted by Computer Physics Communications.
- Add repr for System class.
- Add Replicate class.
- Improve the performance of reading/writing DATA file with pyarrow.
- Improve the performance of building Voronoi diagram with new version voro++.
- Compile it on MAC OS with M1. Now mdapy is fully cross-platform.
- Obviously improve the performance of reading/writing DUMP with pyarrow.
- Add pyarrow as a dependency package.
- Fix bug of create_polycrystalline module. One can give box with any number, the old version only works for positive float.
- Fix bug of spatial_binning module for empty region.
- Let tqdm as an Optional dependency.
- Optimize Pair Distribution module.
- Optimize Neighbor module.
- Update many Benchmark cases.
- Make Polyhedral Template Mathing parallel.
- Fix bugs of unwrap positions.
- Fix a typo error in msd.
- Add Steinhardt Bondorder Parameter method, which can be used to identify the lattice structure and distinguish the solid/liquid phase during melting process.
- Add Polyhedral Template Mathing method.
- Add IdentifySFsTBs method to identify the stacking faults (SFs) and twinning boundary (TBs) in FCC lattice.
- Add Ackland Jones Analysis (AJA) method.
- Add Common Neighbor Parameter (CNP) method.
- Update the nearest neighbor search in CSP method.
- Fix bug of create_polycrystalline module in Linux.
- Update TaiChi version to 1.4.0.
- Set SciencePlots as a optional package.
- Fix bug in create_polycrystalline.