官方

材料研究入门组合

使用 Materials Project Python API 查询小型材料摘要，保留材料标识、来源与单位，区分计算性质和实验依据。

难度: 中等费用: 免费与付费混合隐私: 取决于配置 ~30 分钟

开始安装

关注

公开链接：https://chemaiatlas.com/zh/recipes/materials-research-starter/

你将能够

按指定 Materials Project 材料标识查询限定字段。
保留来源、物理单位及缺失值。

你将构建什么

范围与访问

使用 Python 3.11 与 mp-api 0.46.5，包要求 >=3.11。需要 Materials Project 账号及当前 API Key，使用 mp_api.client.MPRester 而不是旧 API 客户端。查询访问带认证的外部服务，并非完全离线。此入门流程获取带标识的材料摘要并提供人工核对 Prompt，不自动检索所有材料文献，也不预测实验测量值。

科学解释

参考材料采用官方示例中的硅 mp-149，带隙单位 eV，凸包以上能量单位 eV/atom。数值依赖计算方法与数据库更新，不保证特定带隙或实验一致性；保留缺失值、日期与材料 ID。stable 标签属于数据库分类，不证明实际样品可以合成。

材料数据检索服务

Materials Project API

组合组件

Materials Project API

材料数据检索服务 · mp-api==0.46.5 / current MP API

需要私有 Materials Project API Key，数据及依赖方法的数值可能变化。

费用与许可请核对上游及客户端、服务账号条款。

查看资源

兼容环境

客户端	操作系统	架构	版本要求
Python	macOS	不限	>= 3.11
Python	Windows	不限	>= 3.11
Python	Linux	不限	>= 3.11

安装与测试

1. 准备账号与 Python 环境

全部平台

安装 Python 3.11，从 Materials Project 账号 dashboard 获取自己的 API Key，确认当前 API 访问可用；不要把密钥写入源码、截图或共享日志。

官方来源

预期结果

账号有可用密钥，并私下保存。

2. 安装独立 Python 依赖

macOS

在新的工作目录执行。此命令适用于 macOS/Linux，Windows 使用单独步骤。

python3.11 -m venv .venv
.venv/bin/python -m pip install mp-api==0.46.5
.venv/bin/python -m pip freeze

官方来源

预期结果

依赖安装完成，记录实际解析版本。

3. 安装独立 Python 依赖

Linux

在新的工作目录执行。此命令适用于 macOS/Linux，Windows 使用单独步骤。

python3.11 -m venv .venv
.venv/bin/python -m pip install mp-api==0.46.5
.venv/bin/python -m pip freeze

官方来源

预期结果

依赖安装完成，记录实际解析版本。

4. 在 Windows 安装 Python 依赖

Windows

使用 PowerShell，直接调用虚拟环境解释器。

py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install mp-api==0.46.5
.\.venv\Scripts\python.exe -m pip freeze

官方来源

预期结果

依赖安装完成，记录实际解析版本。

5. 在 macOS/Linux 私下设置密钥

macOS

该 bash 命令隐藏输入，避免将密钥值放在命令文本中。在同一 shell 执行查询，结束后清除变量。使用 zsh 时先运行 bash；查询也在该 bash 会话中执行。

read -r -s -p "Materials Project API key: " MP_API_KEY
export MP_API_KEY

官方来源

预期结果

查询 shell 设置了 MP_API_KEY，未打印其值。

6. 在 Linux 私下设置密钥

Linux

在 bash 中执行，同一个 shell 查询。使用 zsh 时先运行 bash；查询也在该 bash 会话中执行。

read -r -s -p "Materials Project API key: " MP_API_KEY
export MP_API_KEY

官方来源

预期结果

环境变量已设置，未打印。

7. 在 Windows 私下设置密钥

Windows

在 PowerShell 执行，密钥会供进程环境使用，查询结束后清除。

$atlasMpCredential = Read-Host "Materials Project API key" -AsSecureString
$env:MP_API_KEY = [System.Net.NetworkCredential]::new("", $atlasMpCredential).Password

官方来源

预期结果

查询进程可读取 MP_API_KEY，未显示其值。

8. 保存小型摘要查询脚本

全部平台

保存为 materials_summary.py，只查询一个指定材料并写入新文件，输出不记录密钥。

"""Fetch a small, identified Materials Project summary using a private API key.

Sources: https://docs.materialsproject.org/downloading-data/using-the-api/getting-started
         https://docs.materialsproject.org/downloading-data/using-the-api/examples
Source-reviewed example; not executed.
"""
import argparse
import json
import os
from datetime import datetime, timezone
from importlib.metadata import version
from pathlib import Path

from mp_api.client import MPRester


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--material-id", default="mp-149")
    parser.add_argument("--output", type=Path, default=Path("materials-summary.json"))
    args = parser.parse_args()
    api_key = os.environ.get("MP_API_KEY", "").strip()
    if not api_key:
        parser.error("Set MP_API_KEY privately; no request was sent.")
    if args.output.exists():
        parser.error("Choose a new output path; existing output will not be overwritten.")
    try:
        with MPRester(api_key) as mpr:
            docs = mpr.materials.summary.search(
                material_ids=[args.material_id],
                fields=["material_id", "formula_pretty", "band_gap", "energy_above_hull", "is_stable"],
                num_chunks=1,
                chunk_size=1,
            )
    except Exception:
        # Avoid including credential-bearing request details in shared output.
        parser.exit(1, "Materials Project request failed. Check key/account, network, rate limits and installed client version privately.\n")
    payload = {
        "retrieved_at": datetime.now(timezone.utc).isoformat(),
        "mp_api_version": version("mp-api"),
        "requested_material_id": args.material_id,
        "records": [
            {
                "material_id": str(doc.material_id),
                "formula": doc.formula_pretty,
                "band_gap_eV": doc.band_gap,
                "energy_above_hull_eV_per_atom": doc.energy_above_hull,
                "is_stable": doc.is_stable,
                "source_url": "https://materialsproject.org/materials/" + str(doc.material_id),
            }
            for doc in docs
        ],
    }
    with args.output.open("x", encoding="utf-8") as target:
        json.dump(payload, target, ensure_ascii=False, indent=2)
        target.write("\n")
    print("Saved", len(payload["records"]), "record(s) to", args.output)


if __name__ == "__main__":
    main()

官方来源

预期结果

脚本与 .venv 位于同一工作目录。

9. 获取硅材料示例

全部平台

在设置私有密钥的 shell 中执行，Windows 使用 ..venv\Scripts\python.exe；选择新的输出文件名。

.venv/bin/python materials_summary.py --material-id mp-149 --output silicon-summary.json

官方来源

预期结果

实际 JSON 标识 mp-149、分子式 Si，包含时间戳与客户端版本，缺失字段保持 null。数值来自 API，不要求固定带隙；没有记录时如实说明，检查当前访问，不编造数据。

10. 核对材料依据

全部平台

作为人工核对清单，或仅提供不含私密信息的返回数据给可选助手；绝不附 API Key。

检查提供的 mp-149 硅摘要，保留标识、时间戳、带隙 eV 与凸包以上能量 eV/atom 单位。区分数据库计算、稳定性分类与实验测量或合成结论，保留 null 为不可用，引用来源链接。

官方来源

预期结果

核对说明与返回数据及来源一致。

11. 查询后清除私有密钥

Windows

bash 使用 unset MP_API_KEY；PowerShell 使用下方命令。

Remove-Item Env:MP_API_KEY
Remove-Variable atlasMpCredential

官方来源

预期结果

临时 shell 密钥已清除。

故障排除

缺密钥：在运行脚本的同一个终端设置 MP_API_KEY。
401/403：私下核对当前账号密钥和权限，不将凭据贴进对话。
客户端或 schema 冲突：使用独立 mp-api 0.46.5 与当前 MPRester 文档。
网络或限流：减少查询，退避重试并保留已有结果。
无条目：核对材料 ID 与数据库版本。
输出已存在：选择新路径。
带隙与文献不同：检查计算方法，不将 DFT 值与实测值直接等同。

仍无法运行

替代方案

可在 Materials Project 网站查看相同 ID，或使用官方文档中的直接 API。与文献比较应作为独立且带引用的审核步骤。