MDAPY, short for Molecular Dynamics Analysis in Python, builds, analyzes, simulates and visualizes atomistic systems.

MDAPY 2.0 is a complete rewrite

It 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, each concept has one name (Glossary), and one unit system, Å, eV, ps, amu, K, and GPa for stress, runs through everything (Units and conventions).
• 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, reads and writes the files of LAMMPS, VASP and GPUMD, takes any ASE calculator or LAMMPS interaction as a calculator (Interoperability), shares a process with PyTorch (Parallelism), and works as one step of high-throughput calculations.
• Documented. Every feature has its own page on how to use it and, for analyses, what it computes and which papers it follows, and lessons lead from the first structure on.

🧰 What it does

Structures come from files or are built, live in a System, and its neighbors feed the analyses and the calculators.

flowchart TB
    files[("<b>Files</b><br/>extended XYZ · LAMMPS · POSCAR<br/>OUTCAR · CIF · PDB · MDAPY")]
    build["<b>Structure builder</b><br/>crystals · alloys · defects<br/>dislocations · polycrystals"]
    system(["<b>System</b><br/>box · topology · trajectory"])
    neighbors(["<b>Neighbor lists</b>"])
    visual["<b>Visualization</b><br/>rendering · movies · plots"]
    mlip["<b>MLIP</b><br/>VASP training sets · descriptors<br/>choosing frames · errors · uncertainty"]
    analysis["<b>Analysis</b><br/>structures · local order · defects · dynamics"]
    calculators["<b>Calculators</b><br/>native EAM · NEP<br/>interfaces to LAMMPS · ASE · VASP"]
    minimization["<b>Relaxation and dynamics</b><br/>minimization · molecular dynamics<br/>defect energies"]
    lattice["<b>Lattice dynamics</b><br/>elastic constants · phonons<br/>sheets · finite temperature"]
    thermodynamics["<b>Thermodynamics</b><br/>free energy · melting points · phase diagrams<br/>stacking faults with temperature"]
    packages["<b>Interoperability</b><br/>ASE · OVITO · pymatgen · freud<br/>LAMMPS · VASP · GPUMD"]

    files <--> system
    build --> system
    packages <--> system
    packages <--> calculators
    system --> neighbors
    system --> visual
    files --> mlip
    calculators --> mlip
    neighbors --> analysis
    neighbors --> calculators
    calculators --> minimization
    minimization --> lattice
    minimization --> thermodynamics

    classDef core fill:#2563eb40,stroke:#2563eb,stroke-width:4px
    classDef data fill:#3b82f61f,stroke:#3b82f6,stroke-width:2px
    classDef analysis fill:#ea580c26,stroke:#ea580c,stroke-width:2px
    classDef simulation fill:#9333ea26,stroke:#9333ea,stroke-width:2px
    classDef build fill:#16a34a26,stroke:#16a34a,stroke-width:2px
    classDef visual fill:#db277726,stroke:#db2777,stroke-width:2px
    classDef mlip fill:#0d948826,stroke:#0d9488,stroke-width:2px
    class system,neighbors core
    class files,packages data
    class analysis analysis
    class calculators,minimization,lattice,thermodynamics simulation
    class build build
    class visual visual
    class mlip mlip

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

Installation describes the other ways to install it, what those need, and the optional packages.

🧪 Tests

More than 99 % of the code is tested. Contributing says how to run the tests and what a complete run needs.

📖 Citing MDAPY

If MDAPY contributes to a publication, please cite Wu and Shao (2023), and the papers that the pages of the features you use ask to cite.

See the release notes for what each development version contains.