Skip to content

[Bug]: get_pourbaix_entries with an r2SCAN user entry silently discards every r2SCAN entry, including the user's #1143

Open

Description

@kavanase

Code snippet

from collections import Counter

from mp_api.client import MPRester
from pymatgen.analysis.pourbaix_diagram import PourbaixDiagram
from pymatgen.entries.computed_entries import ComputedStructureEntry


def my_entry(mpr, formula, thermo_type):
    """MP's lowest-energy `formula` entry of `thermo_type`, as a user calculation 50 meV/atom lower in energy."""
    mp = min(
        mpr.get_entries(formula, additional_criteria={"thermo_types": [thermo_type]}),
        key=lambda e: e.energy_per_atom,
    )
    return ComputedStructureEntry(
        mp.structure,
        mp.uncorrected_energy - 0.05 * len(mp.structure),
        parameters=dict(mp.parameters),
        entry_id=f"my-{formula}-{mp.parameters['run_type']}",
    )


with MPRester() as mpr:
    print("MP database:", mpr.db_version)
    for formula, chemsys in (("TiO2", "O-Ti"), ("Fe2O3", "Fe-O")):
        for arg in (chemsys, [my_entry(mpr, formula, "GGA_GGA+U")], [my_entry(mpr, formula, "R2SCAN")]):
            pbx = mpr.get_pourbaix_entries(arg)
            ids = {str(e.entry_id) for e in pbx}
            solids = Counter(str(e.entry_id).rsplit("-", 1)[1] for e in pbx if e.phase_type == "Solid")
            stable = [(e.name, str(e.entry_id)) for e in PourbaixDiagram(pbx).stable_entries if e.phase_type == "Solid"]
            user = f"user entry {arg[0].entry_id}" if isinstance(arg, list) else "no user entries"
            returned = f" (returned: {arg[0].entry_id in ids})" if isinstance(arg, list) else ""
            print(f"{chemsys}, {user}{returned}: solids {dict(sorted(solids.items()))}")
            print(f"  Pourbaix-stable solids: {sorted(stable)}")

    # `solid_compat=None` keeps all entries, but leaves the user's raw r2SCAN energy off MP's mixed scale:
    pbx = mpr.get_pourbaix_entries([my_entry(mpr, "TiO2", "R2SCAN")], solid_compat=None)
    tio2 = sorted((round(e.entry.energy_per_atom, 3), str(e.entry_id)) for e in pbx if e.name == "TiO2(s)")
    print(f"O-Ti, solid_compat=None: lowest TiO2(s) formation energies (eV/atom): {tio2[:2]}")

What happened?

Since #990 (first released in v0.45.9), get_pourbaix_entries accepts user entries. If any of them is r2SCAN, it switches to the mixed GGA_GGA+U_R2SCAN thermo type:

user_run_types = {
entry.parameters.get("run_type", "unknown").lower()
for entry in user_entries
}
if any("r2scan" in rt for rt in user_run_types):
thermo_types = ["GGA_GGA+U_R2SCAN"]

I expect the desired behaviour is that each r2SCAN entry is placed on MP's mixed GGA(+U)/r2SCAN energy scale and included. Instead, however, every r2SCAN entry is silently discarded (MP's and the user's own). The diagram is then built from whatever GGA(+U) entries are left in MP's mixed hull. That leftover set has no entry at all for any material MP represents by its r2SCAN calculation.

Example of the issue from Claude:
Each user entry in the snippet below is a copy of MP's own lowest-energy entry, 50 meV/atom lower:

  • The r2SCAN user entry is not returned (returned: False). The GGA(+U) one is.
  • The reference solids get worse. Ti–O drops from 158 to 92 solids and Fe–O from 202 to 188, and higher-energy GGA(+U) polymorphs take the place of the ground states:
    • TiH2(s) becomes mp-1077353 (+219 meV/atom above the GGA(+U) hull);
    • TiO2(s) becomes mp-34688 (+8);
    • Fe(s) becomes mp-1271068 (+17).
  • The diagram is wrong. For Fe, the Pourbaix-stable solids change from Fe + Fe2O3 + FeO to Fe + Fe3O4 + FeHO2 + FeO. So an r2SCAN Fe2O3 entry that should stabilise Fe2O3 removes its domain instead. On a grid of pH 0–14 (step 0.5) × −2 to 2 V (step 0.1), the stable phase differs from the no-user-entry diagram at 431 of 1189 points for Fe–O, and at 25 for Ti–O.
  • No warning is raised. There are only INFO log lines (see Log output).

Origin: in the r2SCAN branch, get_pourbaix_entries fetches MP's pre-built mixed entries for the ion-reference system and appends the user's. The GGA(+U) entries carry MP2020 corrections; the r2SCAN entries carry MP GGA(+U)/r2SCAN mixing adjustments:

ion_ref_entries: Sequence[
ComputedEntry | ComputedStructureEntry | GibbsComputedStructureEntry
] = (
self.get_entries_in_chemsys(
list([str(e) for e in ion_ref_elts] + ["O", "H"]),
additional_criteria={"thermo_types": thermo_types},
# use_gibbs=use_gibbs
)
+ user_entries
)

It then applies MaterialsProjectAqueousCompatibility(solid_compat=MaterialsProject2020Compatibility()):

api/mp_api/client/mprester.py

Lines 987 to 1001 in f107e6d

compat = MaterialsProjectAqueousCompatibility(solid_compat=solid_compat)
# suppress the warning about missing oxidation states
n = len(ion_ref_entries)
with warnings.catch_warnings():
warnings.filterwarnings(
"ignore", message="Failed to guess oxidation states.*"
)
ion_ref_entries = apply_corrections(
compat,
ion_ref_entries,
description="Applying aqueous corrections",
log=f"Applying aqueous corrections to {n:,} ion reference entries",
summary=f"Applied aqueous corrections to {n:,} entries ({{kept:,}} kept)",
enabled=not self.mute_progress_bars,
)

That first re-applies solid_compat.process_entries(entries, clean=True) (pymatgen L1611-L1615), which strips the mixing adjustments. MP2020 then rejects every run type but GGA/GGA+U (L1084-L1088), and on_error="ignore" swallows the CompatibilityError (L633-L638).

For H–O–Ti, 225 entries go in (MP's 118 GGA and 106 r2SCAN entries, plus the user's) and 118 come out. test_get_pourbaix_entries only passes chemical systems, so the user-entries path is untested.

This is unchanged by the currently-open PRs or materialsproject/pymatgen#4754.

Suggested fix: in the r2SCAN branch, do what get_stability does, and re-mix MP's un-mixed GGA(+U) and r2SCAN entries together with the user's:

api/mp_api/client/mprester.py

Lines 1977 to 1986 in f107e6d

joint_entries: Sequence[ComputedEntry | ComputedStructureEntry | PDEntry] = [
*entries,
*(
self._get_unmixed_entries(_all_subchemsyses(str(el) for el in chemsys))
if thermo_type_valid_str == ThermoType.GGA_GGA_U_R2SCAN.value
else pd.all_entries
), # `pd.all_entries` for a mixed hull hold one already-mixed entry per material,
] # which the mixing scheme cannot re-process (needs the GGA(+U) and r2SCAN entries
# side by side), and silently drops every entry it cannot pair up -- so we fetch
# separately in the mixed case

Then don't re-apply MP2020, because the mixing scheme's compat_1 has already applied it:

ion_ref_elements = [str(e) for e in ion_ref_elts] + ["O", "H"]
if thermo_types == ["GGA_GGA+U_R2SCAN"]:
    MaterialsProjectDFTMixingScheme = mixing_scheme_class()
    ion_ref_entries = apply_corrections(
        MaterialsProjectDFTMixingScheme(run_type_2="r2SCAN", fuzzy_matching=False),  # as MP builds its hulls
        self._get_unmixed_entries(_all_subchemsyses(ion_ref_elements)) + user_entries,
        ...,
    )
    solid_compat = None  # MP2020 already applied (the scheme's compat_1); re-applying it drops r2SCAN
else:
    ion_ref_entries = self.get_entries_in_chemsys(
        ion_ref_elements, additional_criteria={"thermo_types": thermo_types}
    ) + user_entries

From testing, this fixes these issues.
However, there are some points that should probably be decided before implementing a PR (hence I'm raising an issue rather than PR here):

  • H2O reference: MaterialsProjectAqueousCompatibility infers h2o_energy and h2o_adjustments from the lowest-energy H2O entry (L1636-L1640).
    • In the re-mixed set, that entry is mp-697111-r2SCAN. Its only adjustment is its mixing adjustment (+0.151 eV/atom), against −0.229 eV/atom for the MP2020-corrected mp-697111-GGA.
    • As a result, the MP Aqueous hydrate adjustment (L1557) becomes +2.004 instead of +3.145 eV per H2O.
    • This makes no difference to the Ti or Fe diagrams here. Still, the fix should probably pass both values explicitly, since pymatgen only infers them when neither is given.
  • Other solid_compat values. Users can combine r2SCAN entries with a non-MP2020 solid_compat, including None, which has been valid since [Bug]: get_pourbaix_entries does not support solid_compat=None #1060/Allow solid_compat to be None in get_pourbaix_entries #1061. The mixing scheme is built on MP2020, so this combination should probably warn or raise? Separately, a user's own MP2020 instance would need passing on as compat_1.
  • Dropped user entries. A warning for user entries the corrections drop would also catch the same silent drop on the GGA(+U) path, e.g. for a ComputedEntry without parameters["run_type"]. get_stability: no hull energy for entries the corrections drop #1142 adds such a warning to get_stability.

Version

mp-api 0.47.0, pymatgen 2026.9.24, pymatgen-core 2026.10.16, emmet-core 0.88.0, Python 3.13.1; MP database 2026.09.28

Which OS?

  • MacOS
  • Windows
  • Linux

Log output

MP database: 2026.09.28
O-Ti, no user entries: solids {'GGA': 158}
  Pourbaix-stable solids: [('TiH2(s)', 'mp-24726-GGA'), ('TiO2(s)', 'mp-554278-GGA')]
O-Ti, user entry my-TiO2-GGA (returned: True): solids {'GGA': 159}
  Pourbaix-stable solids: [('TiH2(s)', 'mp-24726-GGA'), ('TiO2(s)', 'my-TiO2-GGA')]
O-Ti, user entry my-TiO2-r2SCAN (returned: False): solids {'GGA': 92}
  Pourbaix-stable solids: [('TiH2(s)', 'mp-1077353-GGA'), ('TiO2(s)', 'mp-34688-GGA')]
Fe-O, no user entries: solids {'GGA': 16, 'GGA+U': 186}
  Pourbaix-stable solids: [('Fe(s)', 'mp-13-GGA'), ('Fe2O3(s)', 'mp-19770-GGA+U'), ('FeO(s)', 'mp-1274279-GGA+U')]
Fe-O, user entry my-Fe2O3-GGA+U (returned: True): solids {'GGA': 16, 'GGA+U': 187}
  Pourbaix-stable solids: [('Fe(s)', 'mp-13-GGA'), ('Fe2O3(s)', 'my-Fe2O3-GGA+U'), ('FeO(s)', 'mp-1274279-GGA+U')]
Fe-O, user entry my-Fe2O3-r2SCAN (returned: False): solids {'GGA': 11, 'GGA+U': 177}
  Pourbaix-stable solids: [('Fe(s)', 'mp-1271068-GGA'), ('Fe3O4(s)', 'mp-31770-GGA+U'), ('FeHO2(s)', 'mp-696580-GGA+U'), ('FeO(s)', 'mp-1274279-GGA+U')]
O-Ti, solid_compat=None: lowest TiO2(s) formation energies (eV/atom): [(-5.517, 'my-TiO2-r2SCAN'), (-3.297, 'mp-390-r2SCAN')]

# the only other output for the O-Ti r2SCAN-user-entry call (in a terminal, the progress summary reads
# "Applied aqueous corrections to 225 entries (118 kept)"):
mp_api.client - INFO - Fetching the GGA_GGA+U_R2SCAN phase diagram for H-O-Ti...
mp_api.client - INFO - Applying aqueous corrections to 225 ion reference entries
# the reason, swallowed by `on_error="ignore"`:
>>> MaterialsProject2020Compatibility().get_adjustments(my_entry(mpr, "TiO2", "R2SCAN"))
CompatibilityError: Entry my-TiO2-r2SCAN has invalid run type r2SCAN. Must be GGA or GGA+U. Discarding.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions