materials-project

name	materials-project
description	Query Materials Project data for crystal structures, stability, electronic properties, phase diagrams.

Materials Project Skill

This skill provides guidance for using the Materials Project API in Agent workflows. It is intended for querying known inorganic materials, retrieving crystal structures, checking thermodynamic stability, comparing generated candidates with known database entries.

The API key can be obtained from the MP_API_KEY environment variable or provided directly by the user.

Search Materials Project for materials matching the given criteria

Search Materials Project for materials matching the given criteria.

Parameters: api_key: Materials Project API key. search_criteria: A dictionary of search criteria. Supported keys include: - material_id: str, Materials Project material ID, e.g. "mp-1234". - formula: str, chemical formula, e.g. "TiO2". - elements: List[str], list of required elements, e.g. ["Ti", "O"]. - exclude_elements: List[str], list of elements to exclude. - band_gap: Tuple[float, float], band gap range (min, max) in eV, e.g. (1.0, 3.0). - energy_above_hull: Tuple[float, float], energy above hull range (min, max) in eV/atom. - num_sites: Tuple[int, int], number of atomic sites range (min, max). - spacegroup_number: int, space group number. - crystal_system: str, crystal system. One of "Triclinic", "Monoclinic", "Orthorhombic", "Tetragonal", "Trigonal", "Hexagonal", or "Cubic". - is_gap_direct: bool, whether the material has a direct band gap. download_path: Download path. If provided, the returned structure files will be saved. limit: Maximum number of returned results.

Returns: A dictionary containing the search results and download status.

from typing import Dict, Any, Optional
import os
import traceback

from mp_api.client import MPRester
from pymatgen.core import Structure

def search_materials_project(
    api_key: str,
    search_criteria: Dict[str, Any],
    download_path: Optional[str] = None,
    limit: int = 10
) -> Dict[str, Any]:
    
    try:
        # 构建搜索条件
        search_params = {}
        
        # 化学式搜索
        if "formula" in search_criteria:
            search_params["formula"] = search_criteria["formula"]
        
        # 元素组成搜索
        if "elements" in search_criteria:
            elements = search_criteria["elements"]
            if isinstance(elements, list):
                search_params["elements"] = elements
        
        # 排除元素
        if "exclude_elements" in search_criteria:
            exclude_elements = search_criteria["exclude_elements"]
            if isinstance(exclude_elements, list):
                search_params["exclude_elements"] = exclude_elements
        
        # 带隙范围
        if "band_gap" in search_criteria:
            band_gap_range = search_criteria["band_gap"]
            if isinstance(band_gap_range, (tuple, list)) and len(band_gap_range) == 2:
                min_bg, max_bg = band_gap_range
                search_params["band_gap"] = (min_bg, max_bg)
            elif isinstance(band_gap_range, (int, float)):
                # 单值视为下限
                search_params["band_gap"] = (band_gap_range, None)
        
        # 形成能范围
        if "energy_above_hull" in search_criteria:
            energy_range = search_criteria["energy_above_hull"]
            if isinstance(energy_range,  (tuple, list)) and len(energy_range) == 2:
                search_params["energy_above_hull"] = tuple(energy_range)
        
        # 原子数范围
        if "num_sites" in search_criteria:
            nsites_range = search_criteria["num_sites"]
            if isinstance(nsites_range, (tuple, list)) and len(nsites_range) == 2:
                search_params["num_sites"] = tuple(nsites_range)
        
        # 空间群编号
        if "spacegroup_number" in search_criteria:
            search_params["spacegroup_number"] = search_criteria["spacegroup_number"]
        
        # 晶系
        if "crystal_system" in search_criteria:
            search_params["crystal_system"] = search_criteria["crystal_system"]
        
        # 直接带隙
        if "is_gap_direct" in search_criteria:
            search_params["is_gap_direct"] = search_criteria["is_gap_direct"]
        
        search_params["num_chunks"] = 1
        search_params["chunk_size"] = limit
        # 执行搜索
        try:
            with MPRester(api_key) as mpr:
                materials_data = mpr.materials.summary.search(
                    **search_params
                )
        except Exception as query_error:
            return {
                "success": False,
                "error": f"搜索Materials Project时出错: {str(query_error)}\n{traceback.format_exc()}",
                "materials": [],
                "count": 0,
                "search_criteria": search_criteria
            }
        # 限制结果数量
        if isinstance(materials_data, list):
            materials_data = materials_data[:limit]
        else:
            materials_data = [materials_data]
        
        if not materials_data:
            return {
                "success": False,
                "error": "未找到符合条件的材料",
                "materials": [],
                "count": 0,
                "search_criteria": search_criteria
            }

        # 处理搜索结果
        materials_list = []
        for material_data in materials_data:
            try:
                
                structure: Structure = material_data.structure
                if structure is None:
                    continue
                
                material_info = {
                    "material_id": material_data.material_id,
                    "formula": structure.composition.reduced_formula,
                    "band_gap": material_data.band_gap,
                    "energy_above_hull": material_data.energy_above_hull,
                    "is_gap_direct": material_data.is_gap_direct,
                }
                
                # 如果提供了下载路径，保存结构文件
                if download_path:
                    os.makedirs(download_path, exist_ok=True)
                    filename = f"{material_data.material_id}_{structure.composition.reduced_formula}.vasp"
                    filepath = os.path.join(download_path, filename)
                    structure.to(filename=filepath, fmt="poscar")
                    material_info["downloaded_file"] = filepath
                
                materials_list.append(material_info)
                
            except Exception as material_error:
                print(f"处理材料 {material_data.material_id} 时出错: {str(material_error)}")
                continue
        
        return {
            "success": True,
            "error": None,
            "materials": materials_list,
        }
        
    except Exception as e:
        return {
            "success": False,
            "error": f"搜索Materials Project时出错: {str(e)}\n{traceback.format_exc()}",
            "materials": [],
            "search_criteria": search_criteria
        }

Query electronic structure data by Materials Project ID

Query electronic structure data by Materials Project ID, including band structure and density of states.

For implementation details and example code, refer to electronic-structure.md.

Query charge density

Use this when the task requires charge density data from Materials Project, such as charge-density visualization, bonding analysis, or comparison with local DFT results.

Example: retrieve charge density for silicon mp-149.

from mp_api.client import MPRester

mp_id = "mp-149"  # silicon

with MPRester() as mpr:
    chgcar = mpr.get_charge_density_from_material_id(mp_id)

chgcar.write_file("CHGCAR")

Query phase diagram

Use this when the task requires thermodynamic phase stability information, competing phases, or phase-diagram-based analysis.

Example: retrieve a phase diagram for a chemical system.

from mp_api.client import MPRester
from emmet.core.thermo import ThermoType

chemsys = "Li-Fe-O"

with MPRester() as mpr:
    phase_diagram = mpr.materials.thermo.get_phase_diagram_from_chemsys(
        chemsys=chemsys,
        thermo_type=ThermoType.GGA_GGA_U_R2SCAN,
    )

for entry in phase_diagram.stable_entries:
    print(entry.composition.reduced_formula, entry.energy_per_atom)