A phase diagram viewer that explains itself

Last year we launched the energy-above-hull endpoint. It gave you a number and a Plotly chart. The number was the useful part, but the chart didn't say much about what it meant. Phase diagrams now have their own viewer on Ouro, built so the thermodynamics are something you read rather than decode.

Here's a live one. I ran the route on TiPdBi, a half-Heusler candidate, against 55 Materials Project references relaxed with Orb v3:

What's new

Hover anywhere, not just on points. Move over an empty patch of the triangle and the viewer shades the stable phases that region breaks down into, draws tie lines to them, and lists how much of each you'd get. The empty space in a phase diagram is where most of the information is; now you can point at it.

The decomposition, written as a reaction. Select an unstable entry and you get the balanced reaction it would undergo. For our example, roughly: TiPdBi → Ti₂Pd₃ + Ti₈Bi₉ + Bi. Next to it is the energy the reaction releases, so "127.9 meV/atom above the hull" turns into a concrete statement about what happens to the material.

Colours that mean something. Points are shaded by distance from the hull, in four plain-language bands:

• Stable: on the hull.

• Near hull: within 25 meV/atom, often reachable in practice.

• Metastable: 25 to 100 meV/atom, possibly synthesizable with care.

• Unlikely: more than 100 meV/atom above.

A meter from 0 to 200 meV shows where the selected entry falls, so you don't have to remember the thresholds.

Straight-line cuts. Choose any two compositions and the viewer plots formation energy along the line between them, with the hull as a line that bends wherever the cut crosses into a new region. This is the most readable view for pseudo-binary questions ("what happens if I swap Pd for Ni?"). It's also how we display systems with five or more elements, which older charts couldn't draw at all.

The 3D energy surface and the quaternary tetrahedron from before are still there. Every entry links to its Materials Project page or its Ouro structure asset.

Try it on your structure

The endpoint now returns a .phasediagram file next to the hull distance, so every run gets the new viewer:

GGen's exploration routes produce the same file for the systems they explore.

For developers

The format is open JSON and documented here. It carries pymatgen's own hull facets, so the viewer draws exactly the hull your numbers were measured against. If you have a pymatgen PhaseDiagram, ouro-py 0.11.19+ can write one directly:

import json
from ouro import Ouro
from ouro.utils.phase_diagram import PHASE_DIAGRAM_EXTENSION, phase_diagram_to_dict

ouro = Ouro()
data = phase_diagram_to_dict(pd, max_e_above_hull=0.2, highlight=my_entry)
ouro.files.create(
    name="Fe-Co-Bi phase diagram",
    visibility="public",
    file_content=json.dumps(data).encode(),
    file_name=f"Fe-Co-Bi.{PHASE_DIAGRAM_EXTENSION}",
)

Files written by any other tool render the same way, as long as they follow the format.

Caveats

The 25 and 100 meV/atom boundaries are rules of thumb, not guarantees. Plenty of made materials sit above 100 meV, and some near-hull ones never form. The energies come from Orb v3, which is internally consistent but isn't DFT, so treat small differences between neighbouring entries with some scepticism.

If you find a system where the viewer confuses rather than clarifies, leave a comment. That's the feedback we most want.