Failing Calls to fetch_mp_reference_df() and fetch_structures()

[polarities]

Description

Current version of mp-api SummaryRester.search() does not support the thermo_types keyword. As a result, both fetch_structures and fetch_mp_reference_df fail.

The error raised is:

MPRestError: You have specified the following kwargs which are unknown to `search`, but may be known to `_search`: thermo_types

Steps to Reproduce

from amstools.thermodynamics import plot_convex_hull
from amstools.sources import fetch_structures, fetch_mp_reference_df

ref_df = fetch_mp_reference_df(
    ['Al','Li'],
    mp_api_key=MP_API,
    max_atoms=32,
    cache_dir="./cache_ref"
)

struct_dict=fetch_structures(
    ['Al','Li'],
    mp_api_key=MP_API,
    max_atoms=32,
    cache_dir="./cache_str"
)

Stack Trace

---------------------------------------------------------------------------
MPRestError                               Traceback (most recent call last)
Cell In[6], line 4
      1 from amstools.thermodynamics import plot_convex_hull
      2 from amstools.sources import fetch_structures, fetch_mp_reference_df
----> 4 ref_df = fetch_mp_reference_df(
      5     ['Al','Li'],
      6     mp_api_key=MP_API,
      7     max_atoms=32,
      8     cache_dir="./cache"
      9 )

File ~/PycharmProjects/amstools/amstools/sources/materials_project.py:469, in fetch_mp_reference_df(elements, e_above_hull, max_atoms, mp_api_key, cache_dir, force_redownload, thermo_types)
    466     search_kwargs["num_sites"] = (1, max_atoms)
    468 with MPRester(api_key) as mpr:
--> 469     docs = mpr.summary.search(**search_kwargs)
    471 # Group docs by chemsys
    472 by_chemsys: Dict[str, dict] = {
    473     cs: {"structs": {}, "meta": {}} for cs in to_download
    474 }

File ~/PycharmProjects/amstools/.venv/lib/python3.13/site-packages/mp_api/client/routes/materials/summary.py:276, in SummaryRester.search(self, band_gap, chemsys, crystal_system, density, deprecated, e_electronic, e_ionic, e_total, efermi, elastic_anisotropy, elements, energy_above_hull, equilibrium_reaction_energy, exclude_elements, formation_energy, formula, g_reuss, g_voigt, g_vrh, has_props, has_reconstructed, is_gap_direct, is_metal, is_stable, k_reuss, k_voigt, k_vrh, magnetic_ordering, material_ids, n, num_elements, num_sites, num_magnetic_sites, num_unique_magnetic_sites, piezoelectric_modulus, poisson_ratio, possible_species, shape_factor, spacegroup_number, spacegroup_symbol, surface_energy_anisotropy, theoretical, total_energy, total_magnetization, total_magnetization_normalized_formula_units, total_magnetization_normalized_vol, uncorrected_energy, volume, weighted_surface_energy, weighted_work_function, include_gnome, num_chunks, chunk_size, all_fields, fields, **kwargs)
    269 warn_ref_strs = [
    270     "Please see the documentation:",
    271     f"    {csrc('`search`: https://materialsproject.github.io/api/_autosummary/mp_api.client.routes.materials.summary.SummaryRester.html#mp_api.client.routes.materials.summary.SummaryRester.search')}",
    272     f"   {_csrc('`_search`: https://api.materialsproject.org/redoc#tag/Materials-Summary/operation/search_materials_summary__get')}",
    273 ]
    275 if exc_strs:
--> 276     raise MPRestError("\n".join([*warning_strs, *exc_strs, *warn_ref_strs]))
    277 if warn_ref_strs:
    278     warnings.warn(
    279         "\n".join([*warning_strs, *warn_ref_strs]), category=MPRestWarning
    280     )

MPRestError: You have specified the following kwargs which are unknown to `search`, but may be known to `_search`
    thermo_types
Please see the documentation:
    `search`: https://materialsproject.github.io/api/_autosummary/mp_api.client.routes.materials.summary.SummaryRester.html#mp_api.client.routes.materials.summary.SummaryRester.search
   `_search`: https://api.materialsproject.org/redoc#tag/Materials-Summary/operation/search_materials_summary__get

Proposed Fix

I propose specify the working mp-api version or replacing the mpr.summary.search() call with mpr.get_entries_in_chemsys(), which supports thermo_types via additional_criteria. However, this method does not support server-side filtering by system size; therefore, the maximum number of atoms must be filtered locally.

Example:

search_kwargs = dict(
    elements=to_download,
    additional_criteria={
        "energy_above_hull": (0, e_above_hull),
        "thermo_types": thermo_types,
    },
    property_data=[
        "material_id",
        "formula_pretty",
        "energy_per_atom",
        "energy_above_hull",
        "formation_energy_per_atom",
        "chemsys",
    ],
)

with MPRester(api_key) as mpr:
    docs = mpr.get_entries_in_chemsys(**search_kwargs)

[...logic add to filter by system size...]

[...logic update to remap data...]

I am happy to submit a PR implementing this change if the approach is acceptable.

Environment

• mp-api==0.46.0
• Python 3.13