.. image:: https://img.pterclub.com/images/2023/01/06/logo.png
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>
.
https://github.com/mushroomfire/mdapy <https://github.com/mushroomfire/mdapy>
_https://mdapy.readthedocs.io/ <https://mdapy.readthedocs.io/>
_https://github.com/mushroomfire/mdapy/issues <https://github.com/mushroomfire/mdapy/issues>
_https://github.com/mushroomfire/mdapy-tutorial <https://github.com/mushroomfire/mdapy-tutorial>
_.. image:: doc/source/images/GUI.gif
.. 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
Structure Analysis
Ackland Jones Analysis <https://mdapy.readthedocs.io/en/latest/mdapy.html#module-mdapy.ackland_jones_analysis>
_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>
_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>
_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>
_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>
_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>
_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>
_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>
_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>
_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>
_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/>`_
- >=0.20.26
- 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.
.. 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.
Install from pip (recommended). ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: bash
pip install mdapy
One can install optional dependencies. For example:
.. code-block:: bash
pip install mdapy[k3d]
.. code-block:: bash
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>
_.
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)"
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 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
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} }
V0.11.1 (Under development) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
V0.11.0 (June 22, 2024) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
V0.10.9 (June 20, 2024) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
V0.10.8 (May 17, 2024) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
V0.10.7 (April 25, 2024) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
V0.10.6 (April 13, 2024) ^^^^^^^^^^^^^^^^^^^^^^^^^
V0.10.5 (April 12, 2024) ^^^^^^^^^^^^^^^^^^^^^^^^^
NEP <https://gpumd.org/potentials/nep.html>
_ model to evaluate the energy, force and virial.init_bulk
and init_surf
in dpgen <https://github.com/deepmodeling/dpgen>
_.NEP <https://gpumd.org/potentials/nep.html>
_ trainning.V0.10.4 (March 12, 2024) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
phonopy <https://phonopy.github.io/phonopy/>
_.V0.10.3 (January 30, 2024) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Crystallographic Information File cif <https://www.iucr.org/resources/cif/spec/version1.1/cifsyntax>
_ format.V0.10.2 (January 8, 2024) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
V0.10.1 (December 18, 2023) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
V0.10.0 (November 28, 2023) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
V0.9.9 (November 21, 2023) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
V0.9.8 (November 13, 2023) ^^^^^^^^^^^^^^^^^^^^^^^^^^^
k3d <https://matplotlib.org/>
_ be an optional dependency. One can install it only if you need visualize the System in Jupyter environment.V0.9.7 (11/5/2023) ^^^^^^^^^^^^^^^^^^^^^^^^^^^
k3d <https://matplotlib.org/>
_ as a dependency.jupyter <https://jupyter.org/>
_ as a dependency.V0.9.6 (11/2/2023) ^^^^^^^^^^^^^^^^^^^^^^^^^^
V0.9.5 (10/24/2023) ^^^^^^^^^^^^^^^^^^^^^^^^^^^
logo <https://mdapy.readthedocs.io/en/latest/>
_.V0.9.4 (10/20/2023) ^^^^^^^^^^^^^^^^^^^^^^^^^^
V0.9.3 (10/19/2023) ^^^^^^^^^^^^^^^^^^^^^
V0.9.2 (10/12/2023) ^^^^^^^^^^^^^^^^^^^^^^
V0.9.1 (10/11/2023) ^^^^^^^^^^^^^^^^^^^^^^^^^^
V0.9.0 (9/23/2023) ^^^^^^^^^^^^^^^^^^^^^^^^^^^
V0.8.9 (9/5/2023) ^^^^^^^^^^^^^^^^^^^^^^^^^^^
V0.8.8 (8/24/2023) ^^^^^^^^^^^^^^^^^^^^^^^^^^
V0.8.7 (5/25/2023) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
V0.8.6 (4/22/2023) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
V0.8.5 (4/9/2023) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
V0.8.4 (3/30/2023) ^^^^^^^^^^^^^^^^^^^
V0.8.3 (3/20/2023) ^^^^^^^^^^^^^^^^^^^
V0.8.2 ^^^^^^^^^
V0.8.1 ^^^^^^^
V0.8.0 ^^^^^^^
V0.7.9 ^^^^^^^
V0.7.8 ^^^^^^^