qmof-thermo

A toolkit for calculating thermodynamic stability (i.e. formation energy, energy above hull) of metal–organic frameworks (MOFs) using machine-learned interatomic potentials (MLIPs).

Note: For the QMOF-Thermo Database, please refer to the data available on Figshare.

Reference: B. Dallmann, A. Saha, A.S. Rosen, "Predicting the Thermodynamic Limits of Metal–Organic Framework Metastability", J. Am. Chem. Soc., 19, 19487--19501 (2026). DOI: https://doi.org/10.1021/jacs.5c20253

Overview

This package provides a streamlined workflow to calculate the formation energy and energy above hull for MOFs. In order to utilize the energy-above-hull calculation method, one must follow the Setup Instructions directions.

This repository also includes scripts to reproduce key figures in the manuscript. To reproduce the manuscript figures, one can simply clone the repository and follow Figure Reproducability directions denoted below.

Usage

Energy Above Hull Calculation

If you plan to calculate the energy of your MOF with VASP, first set up quacc and then run the following:

from ase.io import read
from qmof_thermo import set_log_level, get_energy_above_hull
from quacc.recipes.vasp.core import relax_job

# Set logging level
set_log_level("INFO")

# Load your structure
atoms = read("mof.cif")

# Relax the structure with QMOF settings and get the energy
output = relax_job(atoms, preset="QMOFSet", relax_cell=True)
energy = output["results"]["energy"]

# Calculate energy above hull
e_above_hull = get_energy_above_hull(atoms, energy, energy_type="DFT")
print(f"Energy above hull: {e_above_hull} eV/atom")

If you plan to calculate the energy of your MOF with an ODAC-trained MLIP, first set up the MLIP and then run the following:

from ase.io import read
from qmof_thermo import set_log_level, relax_mof, get_energy_above_hull

# Set logging level
set_log_level("INFO")

# Load your structure
atoms = read("mof.cif")

# Relax the structure with an ODAC-trained MLIP and get the energy
energy = relax_mof(atoms, model="uma-s-1p1.pt", fmax=0.05, label="mymof")

# Calculate energy above hull
e_above_hull = get_energy_above_hull(atoms, energy, energy_type="ODAC_MLIP")
print(f"Energy above hull: {e_above_hull} eV/atom")

Setup Instructions

1. Install the Package

pip install git+https://github.com/Quantum-Accelerators/qmof_thermo.git

2. Optional: MLIP Setup

Refer to FairChem's documentation for detailed instructions on using their models.

UMA-ODAC

You have two options:

1. Local checkpoint: Download the UMA model checkpoint directly.

2. HuggingFace: Log in with your HuggingFace credentials to download the model automatically:

   hf auth login

   Enter your HuggingFace token when prompted. If using this method, do not include the .pt extension in the model keyword argument.

eSEN-ODAC

Local checkpoint: Download the eSEN-ODAC model checkpoint directly.

Advanced: Phase Diagram Reconstruction

While we provide the phase diagram data with the package, to re-construct it (e.g. to add new phases), you can do so as follows:

from qmof_thermo import setup_phase_diagrams

structures_path = "reference_thermo_structures.json"  # from QMOF-Thermo figshare
thermo_path = "reference_thermo.json"  # from QMOF-Thermo figshare
output_dir = "phase_diagrams"  # directory to store patched_phase_diagram.json

setup_phase_diagrams(structures_path, thermo_path, output_dir=output_dir)

The resulting phase_diagrams/patched_phase_diagram.json can then be passed to the serialized_phase_diagram keyword argument of qmof_thermo.get_energy_above_hull(). Note that the added data must be compatible with the QMOF-Thermo Database phase diagram data.

Figure Reproducibility

Scripts to reproduce the figures in the manuscript are also included in this repository and can be run as follows:

1. Clone and Install the Repository

git clone https://github.com/Quantum-Accelerators/qmof_thermo.git
cd qmof_thermo

2. Construct Figures

Run the corresponding Python scripts:

python figures/figure_<N>.py

FAQ

1. Can I use an MLIP not trained on ODAC to relax my MOF when using the qmof_thermo package?

Not without some work. It is critical that the energy for the MOFs and the structures that compose the convex hull are all at the same level of theory, including functional, pseudopotentials, and so on. The DFT-computed energies of both the materials composing the hull and the MOFs in our work are obtained using QMOF settings, which is at the PBE-D3(BJ) level of theory. This is the same functional as UMA-ODAC and eSEN-ODAC, after filtering out elements with incompatible pseudopotentials between QMOF and ODAC. If you would like to use a completely different MLIP, you will need to to ensure internal consistency between all materials composing the convex hull diagram.

You can potentially use an MLIP that is compatible with the Materials Project (e.g. any foundation MLIP labeled OAM) to obtain the energy of your MOF, but you would then need to construct the convex hull using Pymatgen and the Materials Project data available via the MP API. Our package would not be needed in that scenario. Refer to the Materials Project Thermodynamic Stability documentation for details about constructing the convex hull using Materials Project-compatible data. Specific care is needed with regards to the empirical anion corrections. You may also be able to use an r2SCAN MLIP if it is compatible with the Materials Project settings.

An MLIP that is not compatible with ODAC or the Materials Project would require recomputing the energies of all the materials composing the convex hull as well as the MOF(s) of interest, which is not recommended.