General Property Units

Units Reference for Atomistic Simulations

Goal

Provide a single authoritative reference for units of energy, forces, and stress across all MLIPs, DFT codes, and simulation tools used in this project, including the conversions applied internally.

Project Standard

All internal representations follow the ASE (Atomic Simulation Environment) convention:

MLIP Model Units

Prediction (Inference)

The raw torch model and the ASE calculator do not return the same stress units. Most calculators apply a unit conversion on the way out; two do not. Read the stress column for the layer you are actually calling.

Energy is eV and forces are eV/Å everywhere, at both layers. Only stress varies:

Measured on one compressed Si cell (xx component), 2026-08-25:

Every ratio above is exactly 160.21766208, i.e. GPa per eV/ų.

[!IMPORTANT] matgl.ext.ase.PESCalculator takes stress_unit: Literal["eV/A3", "GPa"] = "GPa", so using it as a drop-in ASE calculator gives GPa, not ASE units — it prints a runtime warning saying so. Calling Potential.forward directly also returns GPa. Pass PESCalculator(potential=model, stress_unit="eV/A3"), or divide by 160.21766208. Mixing this up is a 160x error, not a sign error.

[!NOTE] All of the above are in the ASE sign convention: positive = tensile, compression negative. A compressed cell therefore gives negative diagonal stress at both layers. DFT codes may differ — see VASP below.

Training Input Labels

Training labels in training_data.json are stored in ASE standard units (eV, eV/Å, eV/ų). Conversions to trainer-specific units are handled automatically inside each wrapper:

[!IMPORTANT] MatGL is the only trainer that requires stress conversion. The conversion from eV/ų → GPa is performed automatically inside MATGLWrapper._prepare_training_data(). Users should always provide stress labels in eV/ų.

Training Output (Saved Metrics)

Each MLIP trainer natively reports MAE in eV. All wrappers apply a ×1000 conversion to save MAE values in meV to training_history.json and plot axes in training_history.png, for human readability and consistent cross-model comparison:

The training_history.json keys and their units:

[!NOTE] For MatGL stress: the trainer computes MAE in GPa internally. The wrapper converts back to eV/ų first, then multiplies by 1000 to get meV/ų, matching the other wrappers.

DFT Code Units

VASP

[!NOTE] VASP stores stress internally in kB (kilo-Bar). The vasprun.xml parser in pymatgen returns stress in kB. The Atomate2 MCP tool applies the conversion kB → eV/ų automatically when convert_units=True (default).

Sign Convention

VASP reports stress with the opposite sign to the physics and ASE convention:

• VASP: positive = compressive (pressure-like)
• ASE/Physics/MLIPs: positive = tensile

The sign flip is handled during VASP output parsing (e.g. in the atomate2 MCP tool, VASP stress is multiplied by -1 in addition to the unit conversion).

Common Conversion Factors

Quick Reference: Python Conversions

# Env: base-agent
from ase import units

# Stress conversions
stress_GPa = stress_eV_per_A3 / units.GPa        # eV/ų → GPa
stress_eV_per_A3 = stress_GPa * units.GPa         # GPa → eV/ų
stress_eV_per_A3 = stress_kB * 0.1 * units.GPa    # kB → eV/ų

# Energy conversions
energy_kJ_per_mol = energy_eV * units.kJ / units.mol
energy_kcal_per_mol = energy_eV * units.kcal / units.mol

Constraints

• Never mix unit systems within a single workflow.
• Always verify stress units when comparing MLIP predictions to DFT references.
• Training data JSON files must use eV/ų for stress — wrapper-internal conversion handles the rest.
• When reporting MAE in papers/docs, specify the unit explicitly (e.g., "Force MAE: 50 meV/Å").

Author: Bowen Deng Contact: GitHub @learningmatter-mit