Fast building, analysis, simulation and visualization of atomistic systems, in Python.

Documentation · Quick tour · Lessons · Examples · Install · Tests · Cite

MDAPY 2.0 is a complete rewrite and is not compatible with MDAPY 1.x. It brings many more features, and we recommend upgrading. The code of 1.x stays on the branch 1.x.

If you like MDAPY, please give it a ⭐ star.

💡 Why MDAPY

• Light. NumPy and polars are its only requirements. Packages such as matplotlib or ASE are optional, and it carries no other third-party code.
• Robust. Tests cover more than 99 % of the code and compare each feature with analytic results and with mature software. All of them run automatically on Linux, macOS and Windows. Results are the same for any number of threads, and damaged files or impossible inputs give a clear error, not a crash.
• Fast. The heavy parts run in C++, on a parallel engine of MDAPY's own. See the benchmarks.
• Predictable. Names say what the code does: minimize, elastic_constants, CommonNeighborAnalysis. A System never changes in place, every analysis has the form compute(system) and returns NumPy arrays, and one unit system, Å, eV and ps, runs through everything.
• Integrated. One package and one System, from the first structure to the last picture. It converts systems to and from ASE, OVITO, pymatgen and freud, takes any ASE calculator or LAMMPS interaction, shares a process with PyTorch, and works as one step of high-throughput calculations.
• Documented. Every feature has its own page, with an example, its parameters, its results and its references, and lessons lead from the first structure on.

🧰 What it does

Area	What is in it
Build	Crystals, polycrystals, alloys, defects and dislocations
Analyze	More than 40 analyses of structure, local order, defects and dynamics
Simulate	Native EAM and NEP, interfaces to LAMMPS and ASE; relaxation and dynamics; elastic constants, phonons, free energies, melting points and phase diagrams
MLIP	Training sets from VASP, descriptors, errors of a model, the frames worth computing
Visualize	Ray-traced pictures on the processor or the graphics card, movies and plots
Exchange	Eight file formats, and systems shared with ASE, OVITO, pymatgen and freud

🎨 Examples

One copper polycrystal, from nothing to a movie.

Build	Grains, 81,734 atoms
import mdapy as mp from mdapy.build import build_crystal, build_polycrystal from mdapy.visualization import render copper = build_crystal("fcc", 3.615, elements="Cu") grains = build_polycrystal(copper, mp.Box(100.0), 8, seed=1) render(grains, "grains.png", color="grain")
Analyze	The atoms that are not fcc
from mdapy.identify import CommonNeighborAnalysis structures = CommonNeighborAnalysis().compute(grains) structures.counts() # {'other': 21043, 'fcc': 60682, ...} boundaries = structures.structure != 1 # not fcc render(grains, "boundaries.png", atoms=boundaries, color=structures)
Simulate	Phonons of copper
from mdapy.calculators import EAM from mdapy.lattice_dynamics import phonons, primitive_cell from mdapy.simulation import minimize from mdapy.visualization import plot eam = EAM.zhou(["Cu"]) relaxed = minimize(copper, eam, cell="full", max_stress=1e-4) cell = primitive_cell(relaxed.system) bands = phonons(cell, eam).band_structure("fcc") with plot.style(): fig, ax = plot.figure() plot.band_structure(bands, ax=ax) plot.save(fig, "phonons", formats=("png",))
MLIP	The 20 frames most worth a DFT calculation
from mdapy import mlip crystal = build_crystal("fcc", 3.615, elements="Cu", repeat=(3, 3, 3)) frames = mlip.perturb(crystal, 200, displacement=0.1, seed=1) points = mlip.structure_descriptors(frames, mlip.SOAP(["Cu"])) chosen = mlip.farthest_point_sampling(points, 20) xy = mlip.principal_components(points).transform(points) with plot.style(): fig, ax = plot.figure() ax.scatter(*xy.T, s=4, color="0.7", label="all frames") ax.scatter(*xy[chosen].T, s=12, label="chosen") ax.set_xlabel("principal component 1") ax.set_ylabel("principal component 2") ax.legend() plot.save(fig, "frames", formats=("png",))

Make a movie

See A movie that flies through a crystal for the whole script.

📦 Install

pip install --pre mdapy

The first release of 2.0 is a preview, and --pre asks pip for it: without it, pip installs 1.x. MDAPY needs Python 3.11 or newer. Installation describes the other ways to install it, from a source archive or from git, what those need, and the optional packages.

🧪 Tests

git clone https://github.com/mushroomfire/mdapy.git
cd mdapy
pip install -e ".[dev]"
pytest

Tests that need another program are skipped where it is missing. Contributing lists what a complete run needs.

📖 Citing MDAPY

If MDAPY contributes to a publication, please cite:

Yong-Chao Wu and Jian-Li Shao, mdapy: A flexible and efficient analysis software for molecular dynamics simulations, Computer Physics Communications 290, 108764 (2023). doi:10.1016/j.cpc.2023.108764

📄 License

Mozilla Public License 2.0, see LICENSE: MDAPY may be used in any software, open or closed, and changes to its own files are shared under the same license.

📜 Code history

MDAPY has been written three times.

Series	Years	How it was built	Code
0.x	2022–2025	Python, with Taichi for the kernels	Branch mdapy_old, last release 0.11.5
1.x	2025–2026	Rewritten with every kernel in C++, and with NumPy and polars as its only requirements	Branch 1.x, last release 1.0.10, documentation
2.x	2026–	Rewritten again from scratch, for the reasons below	This branch

Taichi was no longer updated, which also limited the versions of Python that 0.x could run on. 1.x was rewritten to be easy to update and maintain, and it needs only NumPy and polars, no longer SciPy and Taichi.

2.x goes further: it is easier to maintain, more stable and more consistent, lighter without external code, with many more features and a clearer organization. In particular:

• OpenMP. The OpenMP runtime of 1.x could clash with those of other packages. 2.x runs a thread pool of its own, so it shares a process with PyTorch and LAMMPS.
• Third-party code. 1.x carried ten third-party codes to build and keep working. 2.x carries none.
• The API. In 1.x an analysis was a method that changed the system. In 2.x a System never changes and every analysis is a class with one form.
• Tests. Tests cover more than 99 % of the code and compare each feature with analytic results and with mature software, which makes 2.x more stable.
• Many small calculations. The threads can be limited for each process, so thousands of small calculations side by side do not fight for cores.
• Graphical interfaces. Long computations report their progress, can be cancelled and leave Python running, so a graphical interface is easy to build on 2.x.