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¶

Neighbor Search¶

Fixed-radius cutoff	Efficient cell-list algorithm
k-Nearest neighbors	Exact kNN via aabb tree
Voronoi neighbors	Topology-based, powered by Voro++

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¶

Set up a dedicated environment with the reference libraries mdapy compares against:

conda create -n mda python=3.13
conda activate mda
conda install --strict-channel-priority -c https://conda.ovito.org -c conda-forge ovito
conda install -c conda-forge freud scipy scikit-learn pyfftw pymatgen ase
pip install pytest
pip install git+https://github.com/bigd4/PyNEP.git
pip install .
# also install LAMMPS via your preferred method

Then run the suite:

bash run_tests.sh

run_tests.sh invokes pytest once per test file. This is required on macOS because ovito and freud both ship voro++ + TBB and cannot coexist in a single Python process — an upstream incompatibility, not mdapy’s.

To run a subset:

./run_tests.sh test_centro_symmetry_parameter.py test_voronoi.py

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¶

Issues / feature requests: https://github.com/mushroomfire/mdapy/issues
Email: 934313174@qq.com

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