Installation¶

Method 1 — pip install (recommended)¶

pip install mdapy

Note

GPU-accelerated ray-tracing (NVIDIA OptiX 7)

Pre-compiled wheels with GPU rendering support are published for Linux x86_64 and Windows x86_64. The GPU wheel is selected automatically by pip on supported platforms:

Linux (glibc ≥ 2.28, e.g. Ubuntu 20.04+): pip automatically installs the GPU-capable wheel. Older Linux systems receive the CPU-only wheel.
Windows: the published wheel always includes GPU support.
macOS: CPU-only (Apple Silicon does not support CUDA).

The GPU wheel works on CPU-only machines too — backend='gpu' will raise a RuntimeError if no suitable GPU is found, while backend='cpu' and all other features continue to work normally.

Runtime requirements (GPU features only):

NVIDIA GPU with CUDA Compute Capability 6.0+ (Pascal or newer)
NVIDIA display driver ≥ 520 (ships with OptiX 7 support)
No CUDA Toolkit installation needed — the runtime is statically linked

Check GPU availability at runtime:

from mdapy import render
print(render.is_gpu_available())   # True if GPU backend is usable

Method 2 — install with optional extras¶

pip install mdapy[plot]      # + matplotlib
pip install mdapy[k3d]       # + k3d 3-D widget
pip install mdapy[all]       # + matplotlib, k3d, pyfftw, phonopy

LAMMPS is not an extra — install it via your preferred channel (conda-forge, system package manager, or build from source).

Method 3 — build from the PyPI source distribution¶

If no pre-built wheel fits your platform, or you want to compile with your own compiler flags, install from the sdist also published to PyPI. The sdist contains only the C++ sources, Python package and build configuration (no git history, no docs, no test input files), and pip downloads it automatically:

pip install --no-binary mdapy mdapy

The --no-binary mdapy flag skips the wheel for mdapy only — numpy and polars still install as wheels.

Method 4 — install from a git clone (for development)¶

git clone https://github.com/mushroomfire/mdapy.git
cd mdapy
pip install .          # regular install
# or:
pip install -e .       # editable, picks up source changes without reinstall

Use this if you intend to modify the source, run the tests, or build the documentation.

Method 5 — install directly from GitHub¶

pip install https://github.com/mushroomfire/mdapy/archive/master.zip

System requirements for Methods 3 – 5¶

All three compile mdapy’s C++ extensions locally and therefore need:

Python 3.9+
C++17-capable compiler
OpenMP support
Tested platforms: Windows 10 (MSVC), Ubuntu (GCC), macOS Apple Silicon (Clang)

Verify the installation¶

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

Interoperability with PyTorch / OVITO / freud / scikit-learn¶

mdapy, PyTorch, OVITO, freud and scikit-learn all use OpenMP for internal parallelism. Because each project ships its own pre-built binaries, a single Python process can end up with more than one copy of the OpenMP runtime, which LLVM libomp detects and aborts with:

OMP Error #15: Initializing libomp.dylib, but found libomp.dylib already initialized.

mdapy handles this in two ways depending on how it was installed:

From a PyPI wheel (pip install mdapy) the wheel bundles its own OpenMP runtime so it works in a fresh environment. If you then import it alongside another package that bundles its own copy (commonly PyTorch) and hit the error above, set the flag yourself before importing any of the affected libraries:

import os
os.environ["KMP_DUPLICATE_LIB_OK"] = "TRUE"

or at the shell level:

export KMP_DUPLICATE_LIB_OK=TRUE

From source inside a conda env (pip install . with CONDA_PREFIX set) mdapy’s build system detects the conda env and links against the OpenMP runtime that already lives there — the same one that conda-installed OVITO / PyTorch / freud are using — so only a single libomp ends up in the process and the conflict never arises. This is the recommended setup for development and for any environment that mixes these libraries heavily.

On macOS arm64 specifically, OVITO and freud both bundle voro++ and TBB, and importing both in one Python process crashes inside freud.locality.Voronoi.compute (or the equivalent OVITO modifier). This is an upstream incompatibility — not something mdapy can fix. Run mdapy’s own test suite with ./run_tests.sh (one subprocess per test file) to sidestep it.