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

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.

Script Mode

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

Main Features

Structure Analysis
Potential Analysis
Phonon Calculation
- Cell optimization
- Calculate phonon dispersion, dos and thermal properties, supporting any kind of potential formats
Melting Analysis
Deep Learning Potential Database Preparing
Geometry Structure Creation
- Generate Standard Lattice Structure
- Generate Polycrystal
Neighbor Search
- Neighbor Atoms within Fixed Distance
- Neighbor Atoms within Fixed Number
I/O
- Load Dump, Data, POSCAR, XYZ, cif format
- Export Dump, Data, POSCAR, XYZ, cif format
Other

Dependencies (Support Python 3.8-3.11)

Package Name	Version	Features
taichi	>=1.7.1	Do parallel computing.
numpy	latest	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.

Optional Dependencies

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.

Installation

Install from pip (recommended).

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.

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.

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

Check Installation

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

Trouble Shoot

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

Build the doc

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

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

Release Notes

V0.10.8 (May 17, 2024)

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.

V0.10.7 (April 25, 2024)

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.

V0.10.6 (April 13, 2024)

Fix a typo bug in DFT2NEPXYZ class.

V0.10.5 (April 12, 2024)

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.

V0.10.4 (March 12, 2024)

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

V0.10.3 (January 30, 2024)

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.

V0.10.2 (January 8, 2024)

Significantly optimize the performance of Neighbor class.
Add label for colorbar while visualizing in jupyter.

V0.10.1 (December 18, 2023)

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.

V0.10.0 (November 28, 2023)

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

V0.9.9 (November 21, 2023)

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.

V0.9.8 (November 13, 2023)

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.

V0.9.7 (11/5/2023)

Experimentally support Visualizing System (only in Jupyter environment).
Add k3d as a dependency.
Add jupyter as a dependency.

V0.9.6 (11/2/2023)

One can explicitly assign the type number when writing to data file.
Support load/save POSCAR format.
Support load/save XYZ format.

V0.9.5 (10/24/2023)

Fix the documentations.
Add a dynamic logo.
Improve the memory use for System class.
Improve the README.
Add plot for 3D spatial binning.

V0.9.4 (10/20/2023)

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.

V0.9.3 (10/19/2023)

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).

V0.9.2 (10/12/2023)

Fix capacity of cross-platform.
Updated doc.

V0.9.1 (10/11/2023)

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.

V0.9.0 (9/23/2023)

Support triclinic box now!!!
Add Select feature.
Rewrite the load and save module.
Make many method suitable for small system.
Fix some bugs.

V0.8.9 (9/5/2023)

Fix installation in python 3.11.5.

V0.8.8 (8/24/2023)

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.

V0.8.7 (5/25/2023)

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.

V0.8.6 (4/22/2023)

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++.

V0.8.5 (4/9/2023)

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.

V0.8.4 (3/30/2023)

Optimize Pair Distribution module.
Optimize Neighbor module.
Update many Benchmark cases.

V0.8.3 (3/20/2023)

Make Polyhedral Template Mathing parallel.

V0.8.2

Fix bugs of unwrap positions.
Fix a typo error in msd.

V0.8.1

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.

V0.8.0

Add Ackland Jones Analysis (AJA) method.
Add Common Neighbor Parameter (CNP) method.
Update the nearest neighbor search in CSP method.

V0.7.9

Fix bug of create_polycrystalline module in Linux.

V0.7.8

Update TaiChi version to 1.4.0.
Set SciencePlots as a optional package.
Fix bug in create_polycrystalline.

mushroomfire / mdapy Goto Github PK

mdapy's Introduction