Updates to Identifier Systems in the Materials Project

Materials Project
1

a bit of an overdue post, but will temporarily pin this topic as well as the previous topic I posted about the latest database release for increased visibility

As stated in the release notes for database version v2026.04.13 MP has been updating the way in which we represent the IDs for our data products (material_ids, task_ids, etc.), see: Identifier Systems.

The most immediate changes you might encounter as a user are that 1) material_ids are stored in an alphabetical format, and 2) task_ids no longer have an mp- prefix (and are also alphabetical). Other changes are listed in the release notes linked above.

There is a class in emmet-core (emmet.core.mpid.AlphaID, similar to the MPID class) that handles all the necessary conversions that you can use (or is used on your behalf in mp-api). Some examples:

>>> from emmet.core.mpid import AlphaID, MPID
>>> # looking at mp-149
>>> "mp-149", AlphaID("mp-149"), AlphaID("mp-149", padlen=8), MPID("mp-149")
('mp-149', AlphaID(mp-ft), AlphaID(mp-aaaaaaft), MPID(mp-149))
>>> # equality comparisons
>>> "mp-149" == AlphaID("mp-149") == AlphaID("mp-149", padlen=8) == MPID("mp-149")
True

The primary driver for this being improving the disambiguation* between ‘material’s and ‘tasks’ in the contexts of static datasets that were loosely associated with a ‘material’ by a material_id**, rather than being a property derived from a ‘material’.

Preamble out of the way, what does this practically mean for you as an MP user? Our hope is nothing (or as close to nothing as possible), and you can continue to use MP in all the same ways as before. Use the same queries, link to the same URLs, reference the same material_ids/DOIs in papers, etc. You may just get some kwarg deprecation warnings when using the mp-api Python client, but most existing queries should just work.

We put a lot of effort into ensuring this change was as backwards and forwards compatible as we could such that:

  1. The mp-api client will handle deprecated kwargs for you without breaking your existing queries,
  2. The REST API server will still accept all ID formats (even if you mix them!), regardless of if you use mp-api or not (with an option for you to request how IDs are formatted in request responses from the REST API***)
  3. The website will render IDs based on the format you choose via a new setting in your user dashboard.

Translating the comparisons above into URLs/queries:

>>> mpr.materials.summary.search(material_ids=["mp-149"])[0].material_id
MPID(mp-149)
>>> mpr.materials.summary.search(material_ids=["mp-aaaaaaft"])[0].material_id
MPID(mp-149)
>>> mpr.materials.summary.search(material_ids=["mp-ft"])[0].material_id
MPID(mp-149)
  • And finally the REST API:
> # as numeric mpid: mp-149
> curl "https://api.materialsproject.org/materials/summary/?material_ids=mp-149&_fields=material_id" \
  -H "accept: application/json" \
  -H "X-API-KEY: ${MP_API_KEY}"
{"data":[{"material_id":"mp-aaaaaaft"}], ...
> # as short alpha mpid: mp-ft
> curl "https://api.materialsproject.org/materials/summary/?material_ids=mp-ft&_fields=material_id" \
  -H "accept: application/json" \
   -H "X-API-KEY: ${MP_API_KEY}"
{"data":[{"material_id":"mp-aaaaaaft"}], ...

For #3 in the list above, the Materials Project website has two options that allow you to modify the way IDs are rendered. The first is in your user dashboard (‘Edit Information’ → ‘Identifier Format’). This option applies across the website to switch ID rendering everywhere possible and will persist across browsers, sessions, etc. The second is in the Calculations page for each material, where the ‘Identifier Format’ toggle will just temporarily flip the formats of the task_ids of the calculations for that material only. This setting does not persist in any fashion and is primarily meant to be used for quick comparisons between the two formats.

–

*An incidental boon is that sorting datasets based on identifiers is now logically correct. task_ids (and therefore material_ids) are assigned incrementally, so you would be correct in assuming that mp-2 was created before mp-110 chronologically.

But since the IDs are stored as strings, attempting to sort this list [”mp-1”, “mp-2”, “mp-110”] would of course result in:

>>> sorted(["mp-1", "mp-2", "mp-110"])
['mp-1', 'mp-110', 'mp-2']

The alphabetical representation of material_ids fixes this:

>>> from emmet.core.mpid import AlphaID
>>> [AlphaID("mp-1"), AlphaID("mp-2"), AlphaID("mp-110")] # as alpha id
[AlphaID(mp-b), AlphaID(mp-c), AlphaID(mp-eg)]
>>> sorted([AlphaID("mp-1"), AlphaID("mp-2"), AlphaID("mp-110")])
[AlphaID(mp-b), AlphaID(mp-c), AlphaID(mp-eg)]

**The XAS collection was a particularly bad offender in this regard, having a material_id field which actually corresponded to task_ids, this post highlights some of the confusion: Downloading Site-Specific XAS Spectra (FEFF) with Structures and Full Properties

Assigning a material_id to a static dataset like the XAS collection led to drift overtime since material_ids are assigned based on the results of structure matching tasks (see also: How does a “material_id” get assigned?). And since symmetry determination libraries/tolerances change over time that drift is somewhat inevitable, then more material_id associations will break over time, etc., etc.

You can repeat this mental exercise with the EOS, phonon, and other (psuedo)static datasets and imagine the confusion.

***The REST API accepts an additional parameter (id_format) that you can append to your query string to format the id fields directly in the server response. Example for the summary endpoint which will transform both the material_id and task_ids fields:

> # standard response
> > curl "https://api.materialsproject.org/materials/summary/?material_ids=mp-149&_fields=material_id%2Ctask_ids" \
  -H "accept: application/json" \
  -H "X-API-KEY: ${MP_API_KEY}"
{"data":[{"material_id":"mp-aaaaaaft","task_ids":["aaaftppd","aaaenmim", ...
> # id_format=legacy response
> curl "https://api.materialsproject.org/materials/summary/?material_ids=mp-149&_fields=material_id%2Ctask_ids&id_format=legacy" \
  -H "accept: application/json" \
  -H "X-API-KEY: ${MP_API_KEY}"
{"data":[{"material_id":"mp-149","task_ids":["mp-2629357","mp-2064724","
2 Likes
Task ID returned from the API has changed?