mdapy logo

PyPI version Python versions PyPI downloads License Documentation Tests GitHub stars

mdapy (Molecular Dynamics Analysis in Python) is a fast, full-featured Python library for analyzing Molecular Dynamics (MD) simulation data — from structural characterization and machine-learning potential workflows to built-in ray-tracing visualization, all in a clean Pythonic API.

pip install mdapy

Why mdapy?

⚡

Blazing Fast

C++ core (via Nanobind) with full OpenMP parallelism. Analyses that take minutes elsewhere finish in seconds.

🐍

Pythonic by Design

One-liner analyses. All data lives in a Polars DataFrame and interops natively with NumPy.

🪶

Minimal Dependencies

The core package depends only on NumPy and Polars, keeping installation lightweight and easy to reproduce across environments.

🌍

Truly Cross-Platform

Pre-built wheels for Windows, Linux, and macOS (including Apple Silicon). No compiler needed for standard installs.

🎨

Built-in Ray-Tracing

Tachyon-powered CPU and GPU (NVIDIA OptiX) renderer baked right in — no third-party renderer required.

🤝

Ecosystem Friendly

First-class interop with OVITO, ASE, freud, phonopy, LAMMPS and GPUMD.

📖

Thoroughly Documented

Full API reference, tutorials, and Jupyter notebooks on ReadTheDocs.

🔄

Actively Maintained

Regular releases, responsive issue tracker, and a growing feature set.

Feature Overview

Structural Analysis

  • Structure identification — Polyhedral Template Matching (PTM), Common Neighbor Analysis (CNA), Ackland-Jones Analysis, Common Neighbor Parameter, Identify Diamond Structure

  • Defect characterization — Centro-Symmetry Parameter (CSP), Identify FCC Planar Faults (ISF / TB / ESF), Atomic Strain, Wigner-Seitz defect analysis

  • Order parameters — Steinhardt Bond Orientation (q₂…q₁₂, averaged), Structure Entropy, Warren-Cowley SRO parameter

  • Distributions — Radial Distribution Function, Structure Factor (total + partial + X-ray weighted), Angular Distribution Function, Bond Analysis

Model Building

  • Single-crystal lattices (FCC, BCC, HCP, diamond, and more)

  • Large-scale polycrystalline structures via Voronoi tessellation

  • High-entropy alloy (HEA) configurations

Machine-Learning Potential Workflows

  • NEP / qNEP potential evaluation (energy, forces, stress, virials)

  • ASE-compatible NEP4ASE calculator

  • Elastic constant tensor calculation

  • Equation-of-state (EOS) fitting

  • Stacking-fault energy curves

  • Phonon dispersion via phonopy

  • Dataset extraction, PCA, FPS, display Train/Thermo results, etc.

Visualization

  • TachyonRender — CPU or NVIDIA OptiX GPU ray-tracing, renders any System to a PNG/JPEG with one method call

  • Per-element colors and radii, transparent background, anti-aliasing, ambient occlusion, shadows — all configurable

Utilities

  • EAM potential generation and averaging

  • Mean Squared Displacement (FFT-accelerated or direct)

  • Lindemann parameter, Void analysis, Cluster analysis

  • Spatial binning (multi-dimensional)

  • Atomic temperature averaging

  • Parallel .gz compression

  • Multi-frame XYZ trajectory reader / splitter

Installation

pip install mdapy

Pre-built wheels cover Windows / Linux / macOS (Apple Silicon included). For optional extras, source builds, GPU-renderer details, and interoperability notes with PyTorch / OVITO / freud / scikit-learn, see the full Installation guide.

Verify:

python -c "import mdapy as mp; print('mdapy', mp.__version__, '— ready!')"

Quick Examples

Load & analyse in three lines:

import mdapy as mp

sys = mp.System("fcc.dump")
sys.cal_polyhedral_template_matching()   # adds 'ptm' column
sys.cal_centro_symmetry_parameter(N=12)  # CSP for FCC
print(sys.data)                          # Polars DataFrame

Radial distribution function:

rdf = sys.cal_radial_distribution_function(rc=6.0)
rdf.plot()           # matplotlib figure — one line

Machine-learning potential workflow:

from mdapy import get_elastic_constant
calc = mp.NEP('nep.txt')
C = get_elastic_constant(sys, calc)
C.print()   # 6×6 elastic tensor in GPa

Ray-tracing render:

from mdapy.render import TachyonRender

ren = TachyonRender(backend="auto")          # GPU if available, else CPU
ren.render_system(sys, width=1920, height=1080,
                  output_figure="structure.png")

Build a polycrystal:

unit = mp.build_crystal("Al", "fcc", 4.05)
poly = mp.CreatePolycrystal(unit, box=100, seed_number=10, metal_overlap_dis=2.0)
system = poly.compute()
system.write_xyz("polycrystal.xyz")

Supported File Formats

Format

Read / Write

LAMMPS DUMP

✅ / ✅

LAMMPS DATA

✅ / ✅

VASP POSCAR/CONTCAR

✅ / ✅

XYZ (extended)

✅ / ✅

MP (mdapy native)

✅ / ✅

ASE Atoms

✅ (import / export)

OVITO DataCollection

✅ (import / export)

Documentation & Resources

📖 Full documentation

https://mdapy.readthedocs.io

🏠 Source code

https://github.com/mushroomfire/mdapy

🐛 Issue tracker

https://github.com/mushroomfire/mdapy/issues

Dependencies

Required:

  • numpy — array engine

  • polars — fast DataFrame backend

Optional:

  • matplotlib — plotting (pip install mdapy[plot])

  • k3d — interactive 3-D notebook viewer (pip install mdapy[k3d])

  • pyfftw — faster FFT for MSD calculations

  • phonopy — phonon dispersion

  • lammps — LAMMPS-based potential calculations

Running the Tests

pip install pytest
pip install .
cd tests && pytest -q

Citation

If mdapy contributes to a scientific publication, please cite:

@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     = {10.1016/j.cpc.2023.108764},
  url     = {https://www.sciencedirect.com/science/article/pii/S0010465523001091},
  author  = {Yong-Chao Wu and Jian-Li Shao},
}

Version Notice

mdapy 1.0 is a ground-up rewrite with a new, cleaner API. The legacy release (≤ 0.11.5) is preserved on the mdapy_old branch.

Contributing

Bug reports, feature requests, and pull requests are all very welcome! Please open an issue or submit a PR on GitHub.

License

BSD 3-Clause — see LICENSE for details.

Contact

If mdapy helps your research, a ⭐ on GitHub is always appreciated!