Energy Above Hull Calculator

App slug: e-above-hull Category: Composition / Formula / Structure Check

The Energy Above Hull Calculator estimates the thermodynamic stability of a material relative to the Materials Project convex hull. It can use a user-provided formation energy, a CIF plus user-provided total energy, or an approximate MACE-predicted energy from a CIF file.

This app is useful for quick stability screening, comparing candidate structures, and checking whether a computed structure is predicted to be stable, near-hull, metastable, or unstable.

What The App Does

The app builds a Materials Project phase diagram for the chemical system of the submitted material and inserts the user-provided or model-predicted entry into that phase diagram.

It reports:

• energy above hull in eV/atom
• energy above hull in meV/atom
• stability label
• number of Materials Project entries used
• decomposition products when the material is above hull
• same-formula Materials Project reference information for CIF-based modes
• method warnings for approximate MLIP calculations

Calculation Modes

1. Formula + Formation Energy

Use this mode when you already have a formation energy per atom.

Example:

formula=LiFeO2
formation_energy=-1.55

The app converts the formation energy into a total energy using Materials Project elemental references, then inserts the entry into a Materials Project phase diagram.

Required input:

• formula
• formation_energy or formation_energy_per_atom

2. CIF + Computed Energy

Use this mode when you have a structure file and a DFT-computed energy.

With energy per atom:

energy_per_atom=-5.2

With total cell energy:

total_energy=-62.4

Required input:

• one uploaded .cif file
• either energy_per_atom or total_energy

Use the CIF energy input dropdown to tell the app whether the provided energy is per atom or total cell energy.

3. CIF + MACE Approximate Energy

Use this mode when you want a quick approximate MLIP energy from a CIF file.

Example options:

mace_model=medium-mpa-0
fmax=0.05
max_steps=200

Required input:

• one uploaded .cif file

Optional settings:

The app can optionally relax the structure before evaluating the energy.

Important: MACE mode is an approximate mixed-scale diagnostic. It is not an official Materials Project energy above hull.

Inputs

Formula / Energy Text Box

The text box accepts key-value input.

Formula mode:

formula=LiFeO2
formation_energy=-1.55

CIF energy mode:

energy_per_atom=-5.2

or:

total_energy=-62.4

MACE mode:

mace_model=medium-mpa-0
fmax=0.05
max_steps=200

CIF Structure File

Upload a CIF file for CIF-based modes.

The CIF is parsed using pymatgen. Oxidation states, if present, are removed before constructing the phase-diagram entry.

Materials Project API Key

The backend must have a Materials Project API key configured. The app uses this key to retrieve entries for the submitted chemical system.

Supported backend environment variables:

MTOOLBOX_MP_API_KEY
MP_API_KEY

Algorithm Summary

The app uses pymatgen and mp-api to compute energy above hull.

The workflow is:

1. Parse user input. 2. Determine the chemical system from the formula or CIF composition. 3. Query Materials Project entries for that chemical system. 4. Build a pymatgen PhaseDiagram. 5. Convert the submitted material into a ComputedEntry or ComputedStructureEntry. 6. Add the submitted entry to the phase diagram. 7. Compute energy above hull. 8. If the material is above hull, compute the decomposition phases. 9. Return a CSV result and structured JSON data.

For formula mode, the app converts formation energy to total energy per atom using Materials Project elemental references:

total_energy_per_atom = formation_energy_per_atom + elemental_reference_energy_per_atom

For CIF energy mode, the app uses the uploaded structure and user-provided total energy.

For MACE mode, the app uses MACE-MP to predict a raw MLIP total energy, then inserts that energy into the Materials Project phase diagram.

Output File

The app generates:

The job result also stores structured data for the frontend and permanent result URL.

Result Columns

Typical output columns include:

Stability Labels

The app uses these labels:

These thresholds are practical screening labels, not universal synthesis guarantees.

How To Interpret Results

An energy above hull of 0 means the submitted material lies on the convex hull for the retrieved Materials Project chemical system.

A small positive value, such as below 25 meV/atom, often indicates a near-hull phase that may be experimentally accessible, depending on temperature, entropy, synthesis route, kinetics, and uncertainty in the input energy.

A large positive value means the material is predicted to decompose into lower-energy phases.

The decomposition field lists phases that define the competing lower-energy combination.

Important Warning About MACE Mode

MACE mode uses a raw machine-learning interatomic potential energy and compares it against Materials Project DFT entries. These energies are not guaranteed to be on the same thermodynamic scale.

Therefore:

• MACE mode is good for fast triage and ranking.
• MACE mode is not an official Materials Project energy above hull.
• MACE mode can give misleading absolute hull values.
• For publication-quality results, use consistent DFT calculations and corrections.

For example, a Materials Project structure with known near-zero hull energy can receive a nonzero mixed-scale MACE hull value if the raw MACE energy differs from the MP DFT energy scale.

Recommended Workflows

Quick Screening From Formation Energy

Use this when you have a formation energy from another model or DFT workflow.

formula=LiFeO2
formation_energy=-1.55

DFT Structure Stability Check

Use this when you have a relaxed CIF and DFT total energy.

total_energy=-62.4

Select:

• Calculation mode: CIF + computed energy
• CIF energy input: Total cell energy

Approximate MLIP Triage

Use this for fast preliminary checks.

mace_model=medium-mpa-0
fmax=0.05
max_steps=200

Select:

• Calculation mode: CIF + MACE approximate energy
• Relax before MLIP energy: optional
• MLIP device: CPU or CUDA

Troubleshooting

No Materials Project entries found

This can happen if:

• the formula or CIF composition is malformed
• Materials Project has no entries for that chemical system
• the MP API request failed
• the backend API key is missing or invalid

Check the formula and confirm the backend has MTOOLBOX_MP_API_KEY or MP_API_KEY.

MACE result differs from Materials Project

This is expected. MACE mode uses raw MLIP energy, while Materials Project hulls use corrected DFT entries. Treat the MACE hull value as an approximate diagnostic.

CIF energy mode gives strange hull values

Check that:

• the energy is in eV
• energy_per_atom is really per atom
• total_energy is really the total energy for the uploaded CIF cell
• the structure and energy correspond to the same number of atoms
• the calculation used compatible DFT settings and corrections

Formula mode requires formation energy

Formula mode needs a formation energy per atom, not a total energy.

Use:

formula=LiFeO2
formation_energy=-1.55

Limitations

Current limitations include:

• depends on Materials Project data availability
• does not apply custom correction schemes to user DFT energies
• does not automatically normalize energies from arbitrary DFT workflows
• MACE mode is approximate and mixed-scale
• no finite-temperature free energy or entropy correction
• no uncertainty estimate for model-derived energies
• no automatic chemical potential diagram for open systems

Acknowledgements

This app uses pymatgen and mp-api for Materials Project phase-diagram construction and convex-hull analysis. CIF parsing is handled through pymatgen. Optional approximate energy prediction uses MACE-MP when available in the backend worker environment.

Users should cite Materials Project, pymatgen, mp-api, and MACE-MP where appropriate when using results in scientific reports or publications.