📊 Plot Scripts
The plotting module contains Python scripts for visualizing data generated by GPUMD, NEP, and GPUMDkit calculators. All plots can be displayed interactively or saved as high-resolution PNG files.
Script Location: Scripts/plt_scripts/
Quick Access
gpumdkit.sh -plt # Show all plotting options
gpumdkit.sh -plt <type> # Generate a plot
gpumdkit.sh -plt <type> save # Save plot as PNG
gpumdkit.sh -plt -h # List available plot types
Running gpumdkit.sh -plt prints the plotting command menu:
+-----------------------------------------------------------------------------------------------+
| GPUMDkit <version> PLOT & VISUALIZATION TOOLS |
+-----------------------------------------------------------------------------------------------+
| Usage: gpumdkit.sh -plt <type> Plot list: gpumdkit.sh -plt -h |
+-----------------------------------------------------------------------------------------------+
| NEP Training & Evaluation |
+-----------------------------------------------------------------------------------------------+
| train - NEP training results prediction - NEP prediction results |
| train_test - NEP train and test results parity_density - Parity density plot |
| train_density - Training results density plot restart - Parameters in nep.restart |
| charge - Charge distribution born_charge - Born effective charges |
| dimer - Dimer energy/force curve force_errors - Force errors |
| des - Descriptors lr - Learning rate for gnep |
+-----------------------------------------------------------------------------------------------+
| Diffusion & Transport |
+-----------------------------------------------------------------------------------------------+
| msd - Mean square displacement msd_conv - MSD convergence |
| msd_all - MSD for all species sdc - Self diffusion coefficient |
| msd_sdc - MSD and SDC together sigma - Arrhenius ionic conductivity|
| D - Arrhenius diffusivity sigma_xyz - Directional Arrhenius sigma |
| D_xyz - Directional Arrhenius D |
| doas - Density of atomistic states |
+-----------------------------------------------------------------------------------------------+
| MD & Structural Analysis |
+-----------------------------------------------------------------------------------------------+
| thermo - thermo info in thermo.out thermo2/3 - Thermo in different styles |
| rdf - Radial distribution function rdf_pmf - Potential of mean force |
| vac - Velocity autocorrelation cohesive - Cohesive energy curve |
| net_force - Net force distribution plane-grid - Displacement plane grid |
| xrd - X-ray diffraction |
+-----------------------------------------------------------------------------------------------+
| Heat Transport |
+-----------------------------------------------------------------------------------------------+
| emd - EMD results emd2 - EMD all directions |
| nemd - NEMD results hnemd - HNEMD results |
| viscosity - Viscosity |
+-----------------------------------------------------------------------------------------------+
| Phonons |
+-----------------------------------------------------------------------------------------------+
| pdos - VAC and PDOS |
+-----------------------------------------------------------------------------------------------+
A reliable plotting workflow
Use the following sequence instead of trying plot names at random:
- List the available types with
gpumdkit.sh -plt -h. - Identify the file already present in your working directory.
- Find the matching entry below, then run its exact command signature.
- Add
saveonly where that entry shows it; the argument position is not identical for every plot.
| If you have... | Start with... | What to inspect first |
|---|---|---|
loss.out, energy_train.out, and force_train.out |
gpumdkit.sh -plt train |
loss trend and energy/force parity |
energy_test.out and force_test.out |
gpumdkit.sh -plt prediction |
generalization on the test set |
thermo.out |
gpumdkit.sh -plt thermo |
equilibration and thermodynamic evolution |
msd.out |
gpumdkit.sh -plt msd or gpumdkit.sh -plt sdc |
diffusion regime before interpreting a fit |
rdf.out |
gpumdkit.sh -plt rdf |
selected pair column and peak positions |
xrd.out |
gpumdkit.sh -plt xrd |
angle in column 2 and intensity in column 4 |
For example, a saved training plot is requested as:
The Gallery image below is an example of the figure layout, not a universal quality threshold. Whether a loss curve, parity scatter, or transport fit is acceptable depends on the model, data, and simulation protocol; do not infer a scientific conclusion from the image alone.
Why not use
gpumdkit.sh -plt train -h? Plot scripts do not share a uniform per-plot-hinterface. Usegpumdkit.sh -plt -hfor the list, then use the exact signature and input-file notes in the matching section below.
NEP Training and Prediction
The train, prediction, train_density, and parity_density plots also
print a terminal table containing R^2, MAE, and RMSE for energy, force, and
stress. If no valid stress rows are available, the stress entries are N/A.
plt_train.py
Visualizes NEP training progress including loss curves, RMSE evolution, and parity plots comparing DFT vs NEP predictions for energy, forces, and stresses.
Input Files: loss.out, energy_train.out, force_train.out, virial_train.out
plt_prediction.py
Visualizes NEP prediction results on the test set.
Input Files: energy_test.out, force_test.out, virial_test.out
plt_train_test.py
Creates combined parity plots for both training and testing datasets.
Input Files: energy_train.out, force_train.out, virial_train.out, energy_test.out, force_test.out, virial_test.out
plt_parity_density.py
Generates density-based parity plots for energies, forces, and stresses. Useful for large datasets where scatter plots become unreadable.
Input Files: energy_train.out, force_train.out, virial_train.out
plt_force_errors.py
Plots force error evaluation metrics as proposed by Liu et al..
Input File: force_train.out
Metrics Displayed: - Force magnitude errors (delta_F) - Force angle errors (delta_theta) - Distribution of errors
plt_learning_rate.py
Visualizes learning rate during gnep training.
Input File: loss.out
Note: Only for the gnep training process.
plt_nep_restart.py
Visualizes parameters stored in the nep.restart file.
Input File: nep.restart
plt_charge.py
Plots charge distribution from qNEP model.
Input File: charge_train.out
Important: Ensure consistency between training set and charge output atom ordering. Use full batch training or run prediction step first.
plt_born_charge.py
Creates parity plots for Born effective charges (BEC) on training and testing datasets. Structures with all-zero reference BEC are filtered out.
Input Files: bec_train.out, bec_test.out
Thermodynamic Properties
plt_thermo.py
Primary script for comprehensive thermodynamic property visualization.
Input File: thermo.out
plt_thermo2.py & plt_thermo3.py
Alternative thermodynamic visualization with different styles.
Input File: thermo.out
Diffusion and Ionic Transport
plt_msd.py
Plots mean square displacement (MSD) for all directions.
Input File: msd.out
plt_msd_all.py
Plots MSD for all atomic species separately when using all_groups in GPUMD.
Input File: msd.out (computed with all_groups option)
Requirements: Must use all_groups in the compute_msd command in run.in.
plt_msd_convergence_check.py
Checks convergence of MSD calculations across different time windows.
Input File: msd_step*.out (computed with save_every option)
Requirements: Use save_every in the compute_msd command.
Purpose: Verify MSD has converged sufficiently for accurate diffusion coefficient calculation.
plt_sdc.py
Plots self-diffusion coefficient (SDC) vs time.
Input File: msd.out
plt_arrhenius_d.py
Creates Arrhenius plot for diffusivity (log10 D vs 1000/T).
Input Files: *K/msd.out files (each temperature subdirectory should contain an msd.out)
Output example:
T: 300K, D_total: 1.001e-07 cm2/s
T: 350K, D_total: 4.184e-07 cm2/s
T: 400K, D_total: 1.027e-06 cm2/s
Ea: 0.230 eV
plt_arrhenius_sigma.py
Creates Arrhenius plot for ionic conductivity (ln(σ·T) vs 1000/T).
Input Files: *K/{model.xyz, run.in, thermo.out, msd.out} (each temperature subdirectory)
Heat Transport
plt_emd.py
Analyzes and plots thermal conductivity from equilibrium molecular dynamics (EMD).
Input Files: EMD output files from GPUMD
plt_emd2.py
Plots heat-current correlation and total EMD thermal conductivity in the x, y,
and z directions in one figure. It uses the same run.in and hac.out files
and averaging rule as plt_emd.py.
Input Files: EMD output files from GPUMD
gpumdkit.sh -plt emd2 # Display all directional results
gpumdkit.sh -plt emd2 save # Save as emd2.png
The HAC panels use a logarithmic correlation-time axis and retain the signed HAC values on the y-axis. A physically zero direction is shown as a zero curve. The reported uncertainty follows the legacy half-window spread divided by the square root of the number of HAC repeats; it is not an independent- trajectory standard error.
plt_nemd.py
Visualizes non-equilibrium molecular dynamics (NEMD) thermal transport properties.
Input Files: NEMD output files from GPUMD
Parameters:
| Parameter | Description |
|---|---|
real_length |
Real length of heat transfer zone in nm (set to Auto for auto-calculation) |
scale_eff_size |
Scale factor for effective cross-sectional area (default: 1). For 3D bulk: use 1. For low-dimensional systems with vacuum: S_box / S_eff |
cutoff_freq |
Cutoff frequency for SHC calculation in THz (default: 60) |
save |
Optional, save the plot as nemd.png |
Note: If no SHC data, set scale_eff_size and cutoff_freq to any number as placeholders when using save.
plt_hnemd.py
Plots homogeneous non-equilibrium molecular dynamics (HNEMD) results.
Input Files: HNEMD output files from GPUMD
Parameters:
| Parameter | Description |
|---|---|
scale_eff_size |
Scale factor for effective cross-sectional area (default: 1) |
cutoff_freq |
Cutoff frequency for SHC calculation in THz (default: 60) |
save |
Optional, save the plot as hnemd.png |
Note: If no SHC data, set scale_eff_size and cutoff_freq to any number as placeholders when using save.
Structural Analysis
plt_rdf.py
Plots radial distribution function (RDF) showing pair correlations.
Input File: rdf.out
Full RDF output:
Single pair RDF:
plt_xrd.py
Plots the X-ray diffraction (XRD) output generated by calculator 413.
Input File: xrd.out by default; an alternative XRD output path can be
passed as the first argument.
The plotter reads the second numeric column (column index 1) as the angle and
the fourth numeric column (column index 3) as the intensity. Lines beginning
with # are ignored, and the values are plotted without smoothing or
renormalization.
The reader validates the calculator 413 header and four-column data layout. If
the format is not recognized, it stops and asks you to regenerate the file
with gpumdkit.sh -> 4 -> 413.
With save, the figure is written to xrd.png in the current working
directory.
Example:
This Gallery example is generated separately at 100 DPI. The production script uses 150 DPI for display and at least 300 DPI when saving.
plt_rdf_pmf.py
Plots RDF combined with potential of mean force (PMF).
Input File: rdf.out
plt_vac.py
Plots velocity autocorrelation function (VAC). Useful for analyzing phonon properties and atomic dynamics.
Input File: sdc.out (the VAC columns are read from this file by the plotting script)
Output: Interactive plot or vac.png (with save option)
plt_cohesive.py
Plots cohesive energy curve from cohesive.out. Useful for analyzing lattice stability and equilibrium lattice constants.
Input File: cohesive.out (isotropic scaling factor vs cohesive energy)
Output: Interactive plot or cohesive.png (with save option)
plt_net_force.py
Plots distribution of net forces on structures, useful for identifying problematic configurations.
Input File: train.xyz (extxyz format)
Reference: arXiv:2510.19774
Phonons
plt_phonon.py
Plots a phonon band structure generated by calculator 414. The plotter reads
the q-point path and high-symmetry labels directly from a line-mode QPOINTS
file, so the path does not need to be repeated in the plotting script.
Input Files: phonon_NEP.dat and QPOINTS
The calculation step is interactive:
The Python prompts accept a primitive-cell structure (default PRIMCELL.vasp),
a NEP model (default nep.txt), a line-mode path (default QPOINTS), the
supercell, the displacement amplitude, and the output name (default
phonon_NEP.dat). The calculation requires phonopy in addition to the
usual GPUMDkit/Calorine dependencies.
Plot the result with:
Each disconnected q-path segment is drawn separately. Boundary labels such as
S|S₀ are combined at one horizontal position, and labels stay at one height
with lateral alignment used when neighboring labels are crowded.
plt_phonon_comp.py
Compares two or more phonon band-structure files. The legend is inferred from
the filename: phonon_NEP.dat becomes NEP, phonon_DFT.dat becomes DFT,
and phonon_MACE.dat becomes MACE.
gpumdkit.sh -plt phonon_comp phonon_DFT.dat phonon_NEP.dat save
gpumdkit.sh -plt phonon_comp phonon_DFT.dat phonon_NEP.dat phonon_MACE.dat \
--qpoints QPOINTS save
The default path file is QPOINTS; use --qpoints FILE for another path
definition. For two-file DFT/NEP comparisons, DFT is gray and solid while NEP
is firebrick and dashed. Additional models use the comparison palette and
distinct line styles.
plt_pdos.py
Calculates and plots normalized VAC, PDOS, and Heat Capacity (Cv).
Input Files: model.xyz, run.in, dos.out, mvac.out
Heat capacity output:
Descriptor, Dimer, and Extra Analysis
plt_descriptors.py
Visualizes high-dimensional NEP descriptors using dimensionality reduction (PCA or UMAP).
Input File: descriptors.npy (generated by gpumdkit.sh -calc des)
Methods:
- pca — Principal Component Analysis
- umap — Uniform Manifold Approximation and Projection
# First generate descriptors
gpumdkit.sh -calc des train.xyz descriptors.npy nep.txt Li
# Then visualize
gpumdkit.sh -plt des pca
gpumdkit.sh -plt des umap
plt_dimer.py
Plots dimer interaction curves. Two atoms are placed in a cubic box (30 Å) and the potential energy and force are calculated as a function of dimer distance using a NEP model.
Input File: nep.txt
Reference: J. Chem. Inf. Model. 2026, 66, 3, 1406-1413
plt_doas.py
Plots density of atomistic states (DOAS) proposed by Wang et al..
Input File: doas.out (calculated by gpumdkit.sh -calc doas)
Plane-Grid Plot for Polar Materials
This workflow maps displacement or polarization data onto a grid and plots selected plane profiles. For detailed usage and real-world examples, see Polar Material Analysis.
Dependency:
Typical upstream steps:
gpumdkit.sh -calc nlist -i model.xyz -c 4 -n 12 -C Pb Sr -E O
gpumdkit.sh -calc disp -i movie.xyz -n nl-Pb_Sr-O.dat -o displacements.dat
gpumdkit.sh -calc avg-struct -i movie.xyz -l 0.2 -o averaged_structure.xyz
Usage:
gpumdkit.sh -plt plane-grid -i averaged_structure.xyz -d displacements.dat -e Pb Sr
gpumdkit.sh -plt plane-grid -i averaged_structure.xyz -d displacements.dat -e Pb Sr --select-xy 0 1
Quick Reference Table
| Command | Input File(s) | Description |
|---|---|---|
train |
loss.out, *_train.out |
NEP training plots |
prediction / test |
*_test.out |
NEP prediction plots |
train_test |
*_train.out, *_test.out |
Combined parity plots |
parity_density |
*_train.out |
Density-based parity plots |
force_errors |
force_train.out |
Force error metrics |
lr |
loss.out (gnep) |
Learning rate |
restart |
nep.restart |
Restart file parameters |
charge |
charge_train.out |
Charge distribution |
born_charge / bec |
bec_train.out, bec_test.out |
Born effective charges |
thermo |
thermo.out |
Thermodynamic properties |
msd |
msd.out |
Mean square displacement |
msd_all |
msd.out (all_groups) |
MSD for all species |
msd_conv |
msd_step*.out |
MSD convergence check |
sdc |
msd.out |
Self-diffusion coefficient |
arrhenius_d / D |
*K/msd.out |
Arrhenius diffusivity |
arrhenius_sigma / sigma |
*K/{model.xyz, run.in, thermo.out, msd.out} |
Arrhenius ionic conductivity |
rdf |
rdf.out |
Radial distribution function |
rdf_pmf |
rdf.out |
RDF + potential of mean force |
xrd |
xrd.out |
X-ray diffraction intensity |
vac |
sdc.out |
Velocity autocorrelation |
cohesive |
cohesive.out |
Cohesive energy curve |
net_force |
train.xyz |
Net force distribution |
doas |
doas.out |
Density of atomistic states |
des |
descriptors.npy |
Descriptor PCA/UMAP |
dimer |
nep.txt |
Dimer energy/force curve |
pdos |
model.xyz, run.in, dos.out, mvac.out |
VAC and PDOS |
emd |
EMD outputs | EMD thermal conductivity in one direction |
emd2 |
EMD outputs | EMD thermal conductivity in all directions |
nemd |
NEMD outputs | NEMD thermal transport |
hnemd |
HNEMD outputs | HNEMD thermal transport |
viscosity |
Viscosity outputs | Viscosity |