Materials Project Emmet

2024.5.17 · active · verified Fri Apr 17

Emmet is a builder framework developed by the Materials Project to manage and process scientific data, primarily related to materials science. It provides tools to extract, transform, and load data into a standardized database schema, facilitating advanced materials discovery and analysis. The library is actively maintained with frequent updates, with the current stable version being 2024.5.17, available as 'mp-emmet' on PyPI.

Common errors

```
ModuleNotFoundError: No module named 'emmet'
```
cause You attempted to import from 'emmet' after installing 'mp-emmet', or you installed the outdated 'emmet' package by mistake.

fix If you installed 'mp-emmet', imports should begin with `from emmet...` as 'mp-emmet' installs into the 'emmet' namespace. If you installed the old 'emmet' package, uninstall it (`pip uninstall emmet`) and install the correct one (`pip install mp-emmet`).
```
pydantic.v1.error_wrappers.ValidationError: 1 validation error for TaskDoc...
```
cause This usually indicates an incompatibility between your `pydantic` version and the `mp-emmet` library, or that data you are attempting to process does not conform to the expected Emmet schema.

fix Check the `mp-emmet` `pyproject.toml` or `setup.cfg` for its required `pydantic` version and ensure yours matches. If manually creating documents, verify they adhere to the `emmet.core` schema definitions.
```
pymatgen.ext.matproj.MPRestError: No MP_API_KEY found in the environment. Please set the MP_API_KEY environment variable.
```
cause The Materials Project API client (`MPRester`) could not find your API key in the environment variables or as a direct argument.

fix Obtain your API key from `materialsproject.org/dashboard` and set it in your environment: `export MP_API_KEY="YOUR_KEY_HERE"` or pass it directly when initializing `MPRester(api_key="YOUR_KEY")`.
```
AttributeError: 'MPRester' object has no attribute 'get_task_doc'
```
cause You are likely using an outdated version of `pymatgen` or `mp-emmet` where the `MPRester` method signatures or available methods for Emmet data have changed or were not yet implemented.

fix Update both `pymatgen` and `mp-emmet` to their latest stable versions: `pip install --upgrade pymatgen mp-emmet`. Consult the official documentation for the current API methods.

Warnings

breaking The official package name for the Materials Project's Emmet library on PyPI is `mp-emmet`, not `emmet`. Installing `emmet` will fetch an old, unrelated package (version 2018.6.7) that does not correspond to the current Materials Project framework. Always use `pip install mp-emmet` to get the correct library.
Fix: Uninstall the old package (`pip uninstall emmet`) and install the correct one (`pip install mp-emmet`).
gotcha Emmet relies heavily on `pydantic` for defining data schemas. Incompatible versions of `pydantic` (e.g., v1 vs v2) can lead to `ValidationError` or unexpected behavior. Check Emmet's `install_requires` for the specific `pydantic` version range.
Fix: Ensure `pydantic` version is compatible with `mp-emmet`'s requirements. Consider using a virtual environment or `pip install 'mp-emmet[full]'` to install a complete set of compatible dependencies.
gotcha The Emmet project is under active development, and API methods or document schemas can change between minor releases, especially in `emmet.core` definitions. Always refer to the official documentation for the specific version you are using to avoid unexpected behavior.
Fix: Consult the changelog or official documentation at `mp-emmet.materialsproject.org` before upgrading and adapt your code as necessary.
gotcha Interacting with the Materials Project database via `MPRester` requires an API key. This key must be obtained from the Materials Project website and typically set as the `MP_API_KEY` environment variable. Without it, API calls will fail.
Fix: Obtain an API key from `materialsproject.org/dashboard` and set it as an environment variable: `export MP_API_KEY="YOUR_KEY_HERE"` or pass it directly to the `MPRester` constructor: `MPRester(api_key="YOUR_KEY")`.

Install

pip install mp-emmet Install mp-emmet

Imports

TaskDoc
```
from emmet.core.tasks import TaskDoc
```

MaterialsBuilder

from emmet.builders.materials.materials import MaterialsBuilder

MPRester
```
from pymatgen.ext.matproj import MPRester
```
MPRester is from pymatgen, but it is the primary and recommended way for users to interact with Emmet-structured data from the Materials Project API.

Quickstart

This quickstart demonstrates how to fetch materials data, specifically a TaskDoc, from the Materials Project database. Emmet defines the underlying schema for these documents. The `MPRester` from `pymatgen` is the standard client for interacting with the Materials Project API, which serves Emmet-structured data. Ensure your `MP_API_KEY` environment variable is set for successful API calls.

import os
from pymatgen.ext.matproj import MPRester

# Set your Materials Project API key as an environment variable (MP_API_KEY)
# Get your API key from https://materialsproject.org/dashboard
api_key = os.environ.get("MP_API_KEY", "")

if not api_key:
    print("Warning: MP_API_KEY environment variable not set. API calls will likely fail.")
    print("Using a placeholder API key for demonstration purposes.")
    api_key = "YOUR_API_KEY_HERE_IF_NOT_SET_IN_ENV"

try:
    with MPRester(api_key=api_key) as mpr:
        # Fetch the TaskDoc for a specific Materials Project task_id
        # Example Task ID for LiCoO2 calculation
        task_id = "mp-149"
        task_doc = mpr.get_task_doc(task_id)

        print(f"\nSuccessfully fetched TaskDoc for ID: {task_id}")
        print(f"Pretty Formula: {task_doc.formula_pretty}")
        print(f"Energy per atom: {task_doc.energy_per_atom:.3f} eV/atom")

except Exception as e:
    print(f"\nAn error occurred during data retrieval: {e}")
    print("Please ensure your MP_API_KEY is correctly set and valid.")

view raw JSON →