MAGMATOMIX/UMD is a free, open-source package for the analysis of molecular dynamics simulations, ab initio and classical: structure, chemical speciation, transport and thermodynamics, with error bars on every statistical result. It is written in Python, with C for the heavy parts, and runs on a laptop.
Current version: 3.2 (November 2026). Source code, releases and documentation: github.com/rcaracas/MAGMATOMIX-UMD_package
License: GNU GPL v3 and CeCILL v2.
Please cite: R. Caracas, A. Kobsch, N. V. Solomatova, Z. Li, F. Soubiran, J.-A. Hernandez, Analyzing melts and fluids from ab initio molecular dynamics simulations with the UMD package, J. Vis. Exp. 175, e61534 (2021), doi:10.3791/61534. A paper on version 3 is in preparation.
What it does

- Input and output: parsers for VASP (also on-the-fly machine-learning runs), ABINIT, CP2K and LAMMPS write the UMD file; conversion of UMD files to extended XYZ, POSCAR, LAMMPS data and dump files, and DeepMD training sets; construction of new structures (supercells, insertion of molecules, vacuum slabs, substitutions).
- Quality checks: 14 checks of a run before any analysis (times, unwrapping, energy drift, time step, momentum, equilibration, temperature, stress, core overlap, charge balance).
- Structure: pair distribution functions and coordination numbers; bond lengths found automatically; bonds; chemical species and their lifetimes; polymerization; angles; liquid and vapor; orientations of molecules (water, ammonia, methane, sulfate…) and their correlations.
- Transport: diffusion coefficients (also of molecules, and the anisotropic diffusion tensor), viscosity by Green–Kubo.
- Thermodynamics: averages with errors, heat capacity, vibrational spectra, quantum corrections, entropy of liquids (two-phase thermodynamic model, including molecular rotation), free energy by thermodynamic integration.
- Workflow: one command runs all analyses for a run and gathers the results in a single table; on rerun, it redoes only what changed.
Any cell shape, constant volume or constant pressure. Every script is checked by a validation suite on reference runs and on synthetic runs with exact answers.
The UMD file
All the scripts read one format, the UMD file (<name>.umd.dat): plain text, one line per quantity, a keyword followed by its value(s) and unit (Temperature 2999.5 K, Pressure 1.29 GPa, StressTensor, acell, rprim…), then one line per atom in each snapshot, with 17 columns:
| Columns | Quantity | Unit |
|---|---|---|
| 1–3 | reduced coordinates | – |
| 4–6 | Cartesian coordinates | Å |
| 7–9 | unwrapped Cartesian coordinates (followed across the faces of the cell, for diffusion) | Å |
| 10–12 | velocities | Å/fs |
| 13–15 | forces | eV/Å |
| 16 | charge | e |
| 17 | local magnetic moment | μB |
A parser writes the UMD file once; the analyses never read the outputs of the simulation codes again.
Installation
You need Python 3 with numpy, scipy and matplotlib, and a C compiler for four small libraries.
macOS
xcode-select --install # the C compiler, once
python3 -m pip install numpy scipy matplotlib
git clone https://github.com/rcaracas/MAGMATOMIX-UMD_package.git
cd MAGMATOMIX-UMD_package/src
gcc -O2 -dynamiclib -o c_UMDprocess.dylib c_UMDprocess.c
gcc -dynamiclib -o c_bonds_full.dylib c_bonds_full.c
gcc -dynamiclib -o c_clusters.dylib c_clusters.c
gcc -O2 -dynamiclib -o c_gofr.dylib c_gofr.c
Linux
sudo apt install git gcc python3-pip # Ubuntu, Debian; or your distribution's packages
python3 -m pip install numpy scipy matplotlib
git clone https://github.com/rcaracas/MAGMATOMIX-UMD_package.git
cd MAGMATOMIX-UMD_package/src
for lib in c_UMDprocess c_bonds_full c_clusters c_gofr; do gcc -O2 -fPIC -shared -o $lib.so $lib.c; done
Windows
A native Windows version is in preparation. Until then, use the Windows Subsystem for Linux (WSL, Windows 10 and 11): in a PowerShell opened as administrator, type wsl --install, restart, open Ubuntu from the Start menu, and follow the Linux instructions above. Your Windows files are under /mnt/c/.
Without git, download the code as a zip file from the latest release.
Tutorial
Download the example run, a pyrolite melt at 3000 K (153 atoms, 3 ps of ab initio molecular dynamics, 24 MB): pyrolite.a13.T3000K.umd.zip. Unzip it in a folder work next to the package, and run the scripts from there; each takes a second or two.
cd work
python3 ../MAGMATOMIX-UMD_package/src/check_umd.py -f pyrolite.a13.T3000K.umd.dat
Quality checks of the run. One warning here: the conserved energy jumps 22 times, at electronic steps that did not converge.
python3 ../MAGMATOMIX-UMD_package/src/averages.py -a -i 500 -f pyrolite.a13.T3000K.umd.dat
Density, pressure, temperature, energy and heat capacity, with their errors, skipping the first 500 snapshots: P = 1.29 ± 0.16 GPa, T = 2999.5 ± 16 K.
python3 ../MAGMATOMIX-UMD_package/src/gofr_umd.py -f pyrolite.a13.T3000K.umd.dat
python3 ../MAGMATOMIX-UMD_package/src/analyze_gofr.py -f pyrolite.a13.T3000K.gofr.dat
Pair distribution functions; then, for each pair of elements, the bond length (first minimum) and the coordination number: Si–O 4.00, Al–O 4.09, Mg–O 4.93. The bond lengths are written to pyrolite.a13.T3000K.maximum_bonds.inp; add -v to check them in a plot and correct them by clicking.
python3 ../MAGMATOMIX-UMD_package/src/bonding_umd.py -f pyrolite.a13.T3000K.umd.dat -c pyrolite.a13.T3000K.maximum_bonds.inp
python3 ../MAGMATOMIX-UMD_package/src/speciation_and_angles.py -f pyrolite.a13.T3000K.umd.dat -b pyrolite.a13.T3000K.bonding.dat -c Si,Al -a O -r 1 -t 1
The bonds of every snapshot, then the chemical species around Si and Al with their lifetimes and angles: SiO4 tetrahedra 69% of the time, then AlO4, SiO5 and SiO3 (file pyrolite.a13.T3000K.r1.stat.dat).
python3 ../MAGMATOMIX-UMD_package/src/msd_umd.py -f pyrolite.a13.T3000K.umd.dat
Mean square displacements and diffusion coefficients with errors: D(Si) = 6.3 ± 0.6 × 10−9 m²/s, D(O) = 10.6 ± 0.9 × 10−9 m²/s.
python3 ../MAGMATOMIX-UMD_package/src/umd2out.py -f pyrolite.a13.T3000K.umd.dat -r xyz -s 10
Every tenth snapshot as an extended XYZ trajectory, to watch the melt in OVITO or VMD.
python3 ../MAGMATOMIX-UMD_package/src/umd_workflow.py -f pyrolite.a13.T3000K.umd.dat
Or everything at once: checks, structure, speciation, diffusion, viscosity, vibrations and thermodynamics in about 15 seconds, summarized in umd_workflow.summary.dat.
Every script lists its options with -h. The quick help (two pages, PDF) has one card per script with a typical command and its outputs.