Add formal_chempots option to ChemicalPotentialDiagram to plot the formal chemical potentials rather than the DFT energies

[kavanase]

The ChemicalPotentialDiagram object for which the (very useful! 🙌) pymatgen.analysis.chempot_diagram module is written, plots the chemical potential diagram using the absolute DFT energies, rather than the actual (formal) chemical potentials (aka. reference potentials) of the elements, which are the meaningful values that can be compared to experiment.

This is essentially the difference between absolute DFT energies (which on their own are essentially meaningless and differ substantially between different functional choices, input parameter/grid settings, vdW corrections, DFT codes etc) and formation energies (i.e. energies relative to the elemental energies) which are meaningful, and far more robust with respect to input parameter choice.
Moreover, the axis labels for these plots in the output of ChemicalPotentialDiagram.get_plot() (which is also used on the Materials Project website for the chemical potential diagram plots) are given as μ_X - μ_X^0, which means it should refer to the formal chemical potentials, but in fact it's the absolute DFT energies that are shown (i.e. μ_X(DFT)).

This PR adds an optional parameter formal_chempots = True to ChemicalPotentialDiagram which renormalises the entry energies and plots the formal chemical potentials.

    formal_chempots (bool): Whether to plot the formal ('reference') chemical potentials
        (i.e. μ_X - μ_X^0) or the absolute DFT reference energies (i.e. μ_X(DFT)).
        Default is True (i.e. plot formal chemical potentials).                

Example changes:

The chemical potential diagram of the Y-Ti-O-S phase space on the Materials Project (using the old code):

You can see the energies of the elemental reference states are not zero as they should be (i.e. not corresponding to their μ_X - μ_X^0 axis labels). – Might need to click into the image to see this clearly.

With the updated code we get the expected/desired behaviour:

Further examples can be generated using the test data in test_chempot_diagram.py.

I've added docstrings for these additions and also added a full set of tests to test_chempot_diagram.py for this option.

[janosh]

Thanks @kavanase for the clear explanation and screenshots. Very helpful!

[kavanase]

No problem @janosh, thanks for the speedy merge!

[mkhorton]

Just wanted to second, this was a great change. Thanks @kavanase!

[kavanase]

No problem @mkhorton! 😃
Just curious, do you know if/when this will be reflected in the Phase Diagram Explorer app on the MP website? I guess it's (currently) fixed to a specific pymatgen version, but can't find this anywhere in the docs.

[janosh]

@kavanase The web client is currently set to pymatgen==2023.3.23. This fix came just after that release and the next release wasn't until 2 days ago. We'll probably make a another web deployment next week (maybe even this Fri).

[kavanase]

Ok cool! Thanks very much for the info @janosh! 🙌

[janosh]

Just pinging @tschaume and @yang-ruoxi to make sure we bump pymatgen for the next web deployment to publish this fix.

[kavanase]

@janosh had a browse through, looks great! 😃
Thanks very much all for the speedy update and deployment! 🙌

The elemental forms now arise when μ_X = 0 as expected, and the chemical potential values are physically meaningful (relative rather than absolute DFT energies):

[mattmcdermott]

Looks good to me as well. Thanks for making this change @kavanase. I should have fixed this a long time ago ;)

[janosh]

Thanks for confirming the fix @kavanase @mattmcdermott.