{"id":9723,"library":"mp-emmet","title":"Materials Project Emmet","description":"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.","status":"active","version":"2024.5.17","language":"en","source_language":"en","source_url":"https://github.com/materialsproject/emmet","tags":["materials science","data engineering","database","API","Materials Project","Pymatgen","scientific computing"],"install":[{"cmd":"pip install mp-emmet","lang":"bash","label":"Install mp-emmet"}],"dependencies":[{"reason":"Database interaction with MongoDB for storing and retrieving Emmet documents.","package":"pymongo","optional":false},{"reason":"Data validation and settings management, essential for Emmet's schema definitions.","package":"pydantic","optional":false},{"reason":"Materials Project's common utilities for scientific data objects and general helpers.","package":"monty","optional":false}],"imports":[{"symbol":"TaskDoc","correct":"from emmet.core.tasks import TaskDoc"},{"symbol":"MaterialsBuilder","correct":"from emmet.builders.materials.materials import MaterialsBuilder"},{"note":"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.","symbol":"MPRester","correct":"from pymatgen.ext.matproj import MPRester"}],"quickstart":{"code":"import os\nfrom pymatgen.ext.matproj import MPRester\n\n# Set your Materials Project API key as an environment variable (MP_API_KEY)\n# Get your API key from https://materialsproject.org/dashboard\napi_key = os.environ.get(\"MP_API_KEY\", \"\")\n\nif not api_key:\n    print(\"Warning: MP_API_KEY environment variable not set. API calls will likely fail.\")\n    print(\"Using a placeholder API key for demonstration purposes.\")\n    api_key = \"YOUR_API_KEY_HERE_IF_NOT_SET_IN_ENV\"\n\ntry:\n    with MPRester(api_key=api_key) as mpr:\n        # Fetch the TaskDoc for a specific Materials Project task_id\n        # Example Task ID for LiCoO2 calculation\n        task_id = \"mp-149\"\n        task_doc = mpr.get_task_doc(task_id)\n\n        print(f\"\\nSuccessfully fetched TaskDoc for ID: {task_id}\")\n        print(f\"Pretty Formula: {task_doc.formula_pretty}\")\n        print(f\"Energy per atom: {task_doc.energy_per_atom:.3f} eV/atom\")\n\nexcept Exception as e:\n    print(f\"\\nAn error occurred during data retrieval: {e}\")\n    print(\"Please ensure your MP_API_KEY is correctly set and valid.\")","lang":"python","description":"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."},"warnings":[{"fix":"Uninstall the old package (`pip uninstall emmet`) and install the correct one (`pip install mp-emmet`).","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult the changelog or official documentation at `mp-emmet.materialsproject.org` before upgrading and adapt your code as necessary.","message":"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.","severity":"gotcha","affected_versions":"All versions, particularly between minor updates (e.x. 2024.5.17 to 2024.6.x)"},{"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\")`.","message":"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.","severity":"gotcha","affected_versions":"All versions using MPRester"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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`).","cause":"You attempted to import from 'emmet' after installing 'mp-emmet', or you installed the outdated 'emmet' package by mistake.","error":"ModuleNotFoundError: No module named 'emmet'"},{"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.","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.","error":"pydantic.v1.error_wrappers.ValidationError: 1 validation error for TaskDoc..."},{"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\")`.","cause":"The Materials Project API client (`MPRester`) could not find your API key in the environment variables or as a direct argument.","error":"pymatgen.ext.matproj.MPRestError: No MP_API_KEY found in the environment. Please set the MP_API_KEY environment variable."},{"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.","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.","error":"AttributeError: 'MPRester' object has no attribute 'get_task_doc'"}]}