Emmet Core

0.86.3 · active · verified Mon Apr 13

Emmet Core is the foundational Python library for the Materials Project data ecosystem. It provides Pydantic models and serializers for representing diverse materials science data, including crystallographic structures, VASP calculations, and associated metadata. This library ensures data standardization and interoperability within the materials science domain. It is currently at version 0.86.3, with an active development cycle often releasing pre-release versions.

Warnings

breaking Emmet-core requires Python 3.11 or newer. Attempting to install or run with older Python versions will result in dependency resolution failures or runtime errors.
Fix: Upgrade your Python environment to 3.11 or later.
breaking Emmet-core relies exclusively on Pydantic V2 for its data models. If your project uses Pydantic V1, you will encounter compatibility issues, as Pydantic V1 and V2 are not backward-compatible.
Fix: Ensure your project's dependencies are compatible with Pydantic V2, or isolate emmet-core in a separate environment if V1 is strictly required elsewhere.
gotcha As a data modeling library for a large scientific project, emmet-core's schemas can evolve. While efforts are made for stability, schema changes may occur, especially in minor or pre-release versions, potentially breaking backward compatibility for stored data.
Fix: Always review the changelog when upgrading, particularly for changes in data model fields or types, and validate existing data against new schemas.
gotcha Emmet-core provides Pydantic models for data structuring. For functionality like data building, API interactions, or database integration (e.g., MongoDB), you typically need to install the broader 'emmet' library or 'emmet-builder', not just 'emmet-core'.
Fix: If you need more than just the data models, install `pip install emmet` or `pip install emmet-builder` depending on your use case.

Install

pip install emmet-core Install stable version

Imports

MaterialsDoc

from emmet_core.models.materials import MaterialsDoc

TaskDocument

from emmet_core.models.vasp.calculation import TaskDocument

RunType

from emmet_core.models.vasp.calculation import RunType

MPProperties

from emmet_core.mp_properties import MPProperties

Quickstart

This example demonstrates how to create a basic `MaterialsDoc` instance by first generating a `pymatgen` structure and then populating the Pydantic model with required and some optional fields. This showcases the core data modeling capabilities of `emmet-core`.

from datetime import datetime
from pymatgen.core import Structure, Lattice, Species
from emmet_core.models.materials import MaterialsDoc

# Create a simple structure using pymatgen
lattice = Lattice.cubic(4)
species = [Species("Fe"), Species("O")]
coords = [[0, 0, 0], [0.5, 0.5, 0.5]]
structure = Structure(lattice, species, coords)

# Create a MaterialsDoc instance
material_doc = MaterialsDoc(
    material_id="mp-12345",
    structure=structure,
    formula_pretty="FeO",
    last_updated=datetime.utcnow(),
    # Many other fields exist but are optional for a basic doc
    nsites=len(structure),
    volume=structure.volume,
    density=structure.density,
    nelements=len(structure.composition.elements),
    elements=[str(el) for el in structure.composition.elements],
    composition=structure.composition.as_dict(),
    chemsys="Fe-O",
    symmetry={"space_group_number": 225, "point_group": "m-3m"}
)

print(f"Created MaterialsDoc for {material_doc.formula_pretty} with ID: {material_doc.material_id}")
print(f"Structure volume: {material_doc.volume:.2f} Å^3")

view raw JSON →