Skip to content

README.rst

Latest commit

 

History

History
358 lines (258 loc) · 10.5 KB

README.rst

File metadata and controls

358 lines (258 loc) · 10.5 KB
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

Neighbor Search

Fixed-radius cutoff Efficient cell-list algorithm
k-Nearest neighbors Exact kNN via kd-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

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!