mdapy 2.0.0

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: From MDAPY 1.x gives the 2.0 way of each common call. 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.
• Stable. From 2.0.0 on, code that works keeps working: the API changes only with 3.0, a replaced name warns long before it goes, and a result changes only to fix a bug, named in the release notes. See Compatibility.
• 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

🎨 Examples

Click a picture for its example, with the whole code.

Fly through a crystal

Polycrystals	Gradient grains	Graphene grains
Ice polycrystal	Quasirandom alloys	Dislocations
Structure types	Voronoi cells	Point groups
Atomic strain	Rings	Clusters
Ice and water	Atom paths	Polyhedra
Gamma surfaces	NEP against DFT	Phase diagrams
Surface meshes	Model uncertainty	High throughput

More in the documentation, from the quick tour on.

📦 Install

pip install mdapy

MDAPY needs Python 3.11 or newer. Code written for 1.x keeps working with pip install "mdapy<2", or moves to 2.0 as this guide shows. 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

Papers citing MDAPY lists, by year, the work done with it.

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

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.