This page contains answers to common questions about the Materials Project.

See also our "Glossary of Terms" page which defines common terms in use by Materials Project.

How do I sign in to the Materials Project?

You can login to the Materials Project either using an existing social identity provider (currently GitHub, Google, Facebook, Microsoft or Amazon) or via an email link.

Here are some issues people have encountered when trying to sign in the Materials Project website, and their solutions:

• I want to log in with my social identity provider (GitHub/Google/Facebook/Microsoft/Amazon), but I can’t.

  Ensure that your password for your provider is correct (go to their site and log in there), ensure that you have a full name set on that account, and ensure that you allow Materials Project to see your basic profile info (name and email address).

  You also may be behind a firewall that doesn’t allow GitHub/Google/Facebook/Microsoft/Amazon. In that case, use our email based option instead.

• I appear to sign in OK (the popup goes away), but then I remain on the sign-in screen.

  It may take a few seconds, depending on your connection, to actually get logged in. This is because we have an external identity provider verify your email address so that we don’t have to store any passwords on our servers.

  You may also have an older browser that won’t work well with our website at all. The latest version of Mozilla Firefox, Google Chrome, or Microsoft Edge will work well. Older versions of Internet Explorer will not work.

• I tried using the email option several times but haven’t received a login link.

  We currently don’t do any validation of your email addresses, so if it “looks right”, i.e. you mistype myname@gmail.com as myname@gmali.com, we will still try to send to the wrong address. Also check your "Spam" or "Junk" folder in case the login email has been flagged.

  There is a known issue with Tencent @qq.com addresses, where Tencent throttles delivery and you might not get an email within a reasonable amount of time. Please consider using an alternative to your @qq.com address for login.

How do I cite Materials Project?

Citations are appropriate wherever Materials Project data, methods or output are used. See this page on the Materials Project website for more information:

There is a canonical Materials Project citation, and additional citations for specific properties or tools. See also the Database Versions page for information on how to cite a specific database version.

Where do the material properties shown on Materials Project come from?

The Materials Project core data is all calculated in-house by the Materials Project team using a variety of simulation methods. To understand the quality of these predictions, it is crucial to read the peer-reviewed publications from the Materials Project where each property is benchmarked as much as possible against known experimental values: this will give an estimate of typical error and, importantly, any systematic error that may be present.

Why are the lattice parameters different to what I expect?

The same crystal structure can have multiple, equivalent sets of lattice parameters depending on what crystallographic "setting" is used.

Typically, there are two sets of lattice parameters reported. Lattice parameters can be defined for the primitive cell, which is a definition of the crystal with the fewest number of atoms and therefore convenient for simulations and other uses, and the conventional cell, which is typically easier to visualize and more like you will see in textbooks.

If the lattice parameters are very different to what you expect, check the setting first!

Some systematic errors are also present. These will typically be an over-estimation of 1–3% for most crystals. Layered crystals will also typically have significant error in the interlayer distances since van der Waals interactions are not well-described by the simulation methods (PBE) used by Materials Project. These systematic errors will be improved as Materials Project switches to user newer simulation methods (r2SCAN). See Calculation Details for more information

How can I get CIF Files of structures from Materials Project?

If you search for compounds using our Materials Explorer, for example by chemical formula or by choosing a set of elements, it will generate a table of all possible computed structures matching the criteria in MP. Clicking on each entry in the table of results will open a detail page for that compound, and from that page, there is a button link to export the structure in multiple formats like CIF, JSON, POSCAR or as a VASP Input Set (MPRelaxSet). There are also options to choose between a conventional or a primitive lattice.

Why is the band gap different to what I expect?

Electronic band gaps are difficult to calculate reliably from first principles, especially using methods that scale well to hundreds of thousands of materials. The method used by the Materials Project (PBE) systematically underestimates band gaps.

While it would be possible to provide higher quality calculations for a select number of materials, with more accurate band gaps, it is noted that for materials discovery purposes it is useful to have a dataset that has the same systematic error. See Electronic Structure for more information.

Why has a value changed on Materials Project?

The Materials Project presents the data it generates in two ways:

1. As individual calculations. These are always the same, and as far as possible Materials Project tries to ensure all historical calculations remain available. Typically, only advanced users will access information about individual calculations.

2. As aggregated information. This is information generated from a combination of individual calculations. This information is what is presented on the public "material details" pages, and is what most users will access. As new, improved calculations are performed, this aggregated information can change.

The Materials Project periodically updates this aggregated information in the form of new database releases. See Database Versions for information on the latest database releases.

What is a "task_id" and what is a "material_id" and how do they differ?

Every database needs a unique key which can be used to distinguish one entry from another. In the Materials Project, each unique material is given a material_id (also referred to in various places as mp-id, mpid, MPID). This allows a specific polymorph of a given material to be referenced. For example, wurtzite GaN is assigned the material_id of mp-804, while zinc blende GaN is assigned a material_id of mp-830.

How does a "material_id" get assigned?

The Materials Project is a computational resource. All of the information on a given material details page is actually a combination of data generated from many individual calculations or "tasks". It is also important that these tasks also have unique identifiers.

When a task is added to the Materials Project database, it will get an identifier assigned with the format mp-[0-9] ("mp-" with numbers after it). These identifiers are assigned sequentially, so smaller numbers usually refer to older calculations. An identifier referring to an individual calculation task are known as a task_id.

When the Materials Project database is built, a unique material will then have a collection of multiple different task_ids associated with it. The numerically smallest task_id will then become the material_id. This ensures that, as new, additional calculations are associated with the same material, its material_id should not change.

In the past, I have seen material_ids that start with "mvc", what are these?

Some calculation tasks were associated with a search for multivalent cathode materials. These tasks were given the prefix mvc- instead of mp- and thus some materials also had the prefix mvc-. However, this caused confusion and this approach has been retired. Tasks with the prefix mvc- still exist since the task_id cannot change, but a material_id will now always start with an mp- prefix by convention provided that at least one task associated with that material has the mp- prefix.

Do material_ids ever change? Do task_ids ever change?

A task_id will never change. It will always refer to the same, individual calculation task.

A material_id might change in rare instances, such as the removal of the mvc- prefix, although this is avoided wherever possible.

If a material_id does change, we ensure a redirect on the website is always in place, and the new material_id can also be found programmatically with the API using the get_material_id_from_task_id() function. This way, any publications or research that reference an older material_id are still valid, and the relevant data can still be retrieved.

What does ______ mean?

Consult our glossary here:

If a term is used in Materials Project but is not listed, let us know and we will add it.

This is public documentation for the Materials Project (MP). The Materials Project is a decade-long effort from the Department of Energy to pre-compute properties of "materials" and make this data publicly available, with the intent of accelerating the process of materials discovery. In this context, a material can mean either an inorganic crystal (like silicon), or a molecule (like ethylene). Possible applications are vast, but might include better batteries, solar energy, water splitting, optoelectronics, catalysts and more (see here for a list of publications).

Builder. A builder is a little script written in the Python programming language that helps create new database collection(s) from input database collection(s). It's typically used to allow common analysis tasks to be repeated automatically, for example the calculation of "energies above hull" when new calculations are added to the database. Builders are an essential step in the Materials Project database release process and are formalized with the emmet code.

Chemical system. On Materials Project, a chemical system is a set of materials whose members all contain the same elements. It is usually noted with as dash-delimited list of elements. For example, the "Ga-In-N" chemical system would contain all materials containing Ga, In or N or combinations of these elements (Ga, In, N2, GaN, InGaN, etc.).

Correction scheme. The Materials Project performs calculations using a simulation technique with known systematic errors. A correction scheme is employed to adjust energies based on the elements present in a material to address these systematic errors. Only elements for which sufficient experimental data is available can be corrected.

Energy above hull. A measure of a material's thermodynamic stability. This value refers to a mathematical construction that can be calculated from a set of formation energies and compositions known as a convex hull, and often referred to here as a "phase diagram." However, unlike most phase diagrams, convex hulls are usually given without a temperature axis since the simulation technique used (DFT) gives predictions at zero temperature. A material which lies "on the convex hull" is predicted to be thermodynamically stable, while off the hull is predicted to be metastable or unstable. Values above 200 meV/atom are considered very large and suggest an unstable material that might not be synthesizable, however this ceiling differs significantly by chemistry. Energies above hull are given as a guide and subject to both limits of calculation precision (several meV) and also of calculation accuracy due to limitations of the simulation technique used, where errors can be significant in certain chemistries.

The Materials Project documentation is a collaborative effort between Materials Project staff, contributors, and researchers including graduate students, postdocs and members of the Materials Project community.

A recent list of contributors can be found here:

See also the "Documentation Authors" sections on individual documentation pages.

The Materials Project is an active, academic research project. Changes are common as new research methods become available, and the quality and kind of data we present changes, and also as a result of organizational needs. This page summarizes major changes in different aspects of the Materials Project.

Upcoming Changes

This documentation will continue to be improved. New documentation is currently being written for each of the Materials Project "apps". Some pages may be blank until this is completed.

Previous Changes

Database

The Materials Project database is constantly evolving as new and better calculations become available, both as a result of new features and better methods, and also as errors or problems are identified and fixed.

See the following documentation page for a list of changes to the Materials Project database:

API

The Materials Project API has recently undergone a significant modernization effort. The new Materials Project website is exclusively powered by this API.

See the following documentation page for more information:

Website

The Materials Project has recently undergone a major change in its website architecture. More information on this can be seen in the release announcement.

It is recommended that the URL https://materialsproject.org is used as the primary location of the Materials Project website, however a specific website version can be visited via the following links:

• https://next-gen.materialsproject.org will always take visitors to the latest Materials Project website with the newest database version available.

• https://legacy.materialsproject.org will take visitors to a frozen snapshot of the older Materials Project website. This is powered by an older version of the database with known issues. The legacy website is being left online for some time as we fully transition to the next-gen website, and to allow users time to make any adjustments as necessary for features that may only be available on the legacy website, however the legacy website will be taken offline in due course.

See the website changelog for a detailed list of recent changes:

Documentation

The Materials Project documentation has gone through several iterations, powered previously by MediaWiki and MkDocs software. The current version is powered by GitBook. This switch was made to allow more easy and rapid changes to the documentation, in the hopes of ensuring documentation is maintained at a consistent, high quality.

The current documentation is also available via GitHub at https://github.com/materialsproject/public-docs. Edits and improvements from external users are very welcome, please submit a "pull request" with any suggest change or use the "Edit in GitHub" button on the relevant page.

The previous MkDocs documentation is still available for the historical record, and the older MediaWiki documentation are currently offline but available on request. However, the current version of the documentation should contain all necessary information including historical information. An effort has been made to ensure URLs remain the same during the transition from the previous MkDocs-powered documentation to the new GitBook-powered documentation.

2022-12-16 (7ca3bcd3)

• Better integration between MPRester and MPContribs API python clients.

  • Users of the new API should upgrade to mp-api>=0.30.5 and mpcontribs-client>=5.0.4

2022-12-02 (13f229ed)

• Fix an incorrect unit label for elasticity data on the new website. Thank you to Serge Maalouf for reporting.

  • Data returned from the API was correct and unaffected by this error.

• Fix for insufficient precision in reporting atomic co-ordinates of some materials. Kindly reported by Branton Campbell for the entry mp-1106336.

  • Data returned from the API was correct and unaffected by this error.

• An issue with displaying "task detail" pages is resolved.

2022-08-09 (f2aa3e0a)

• Resolved a bug with "MOF Explorer" detail pages not loading.

• We are investigating an issue with the "Crystal Toolkit" app.

  • This was resolved.

2022-07-28 (e7527896)

• Added "Alloy Systems" section to the material details pages.

  • This is a preview of a new feature and is not yet peer-reviewed.

2022-07-12 (5d802243)

• • The data returned by the API was correct and unaffected by this error

• Fixed an issue with swapped labels in the Battery Explorer, kindly reported by 施荣鑫 via email

  • The data returned by the API was correct and unaffected by this error

The Materials Project welcomes collaborations and strives to maintain an environment where people are encouraged to share their findings as well as their analysis methods.

If you are interested in collaborating with others or are seeking ways to actively contribute:

• Join the weekly infrastructure update Zoom call and listen to decisions being made to improve the Materials Project or bring up a specific item to discuss. To request to attend, email us with the subject line "Request to Join MP Update Call" and a brief introduction as well as the specific item you would like to discuss. Depending on the topic proposed, it might be referred for discussion on the Materials Project forum instead.

• Materials Project hosts annual meetings for discussions among Materials Project Principal Investigators, their research groups, and the infrastructure team. If you have a suggestion for an item to be discussed in this context, please also send us an email. If you are a new member of the Materials Project collaboration, reach out to us so that you can get involved in these meetings directly.

• Reach out to people who are heavily involved in the Materials Project, especially if you are already contributing to code on GitHub (for example, pymatgen) and would like to get in work with people who maintain/review these repositories. You can read more about their involvement, field of expertise, current projects and see if their goals align with yours to propose areas of collaboration.

The Materials Project would not be the resource it is today without the sustained efforts of many individual contributors who have helped make the Materials Project better. The Materials Project is a free, academic resource, with only a small team of core maintainers: any help received is always appreciated, and means we can make the Materials Project better for everyone!

There are several ways to get involved:

• If you are a software developer, please refer to the Contributor Guide.

• If you are a domain expert, you can join the discussion and help answer questions of less experienced users in our forum at https://matsci.org/materials-project.

• If you are a domain expert, you can also notify us of errors, either in our public forum or via email at feedback@materialsproject.org. Please check our FAQ first to ensure that this error is not already known; some common issues arise from a misunderstanding of the data that Materials Project offers.

• If you generate data, either experimental or computational, you can use our contribution platform MPContribs to upload and link your data to the relevant material on Materials Project. This helps us by being able to offer a more complete and helpful resource, and also helps improve the discoverability of your own research by making it available to a wider audience. All uploaded data is credited to the original authors, and will have links to the appropriate publications.

• If you are an advanced user of Materials Project data or codes, you can help us improve documentation and tutorials.

• If you have discovered or know about a new crystal structure that is not present in the Materials Project database, you can submit it to us for calculation to help us offer a more complete database. If you are an advanced user, we may be able to receive calculations directly, but this typically requires prior communication and planning.

Any help is gratefully received, and we work hard to try to give back to the community ourselves wherever possible!

Purpose of this Guide

This guide aims to facilitate the process of contributing to any Materials Project (MP) open source repositories. It offers high-level instructions and guidelines for those who wish to contribute to MP, regardless of the size of the contribution. Whether you're fixing a bug, improving docs, or proposing a new feature, this guide is for you. All contributions are welcome and appreciated!

This guide is a work in progress and will be updated as necessary to reflect changes in MP's practices. If you have any suggestions, don't hesitate to open an issue or a pull request!

Happy contributing!

The Materials Project Software Ecosystem

MP consists of several interconnected parts, each serving a specific purpose that together enable high-throughput computations.

Official Materials Project Codes

The primary codes that most users are likely to interact with and contribute to are:

• pymatgen [docs][repo]: A large Python library for various materials analysis, manipulation and IO between different codes. Can be used on its own for analysis and setting up calculations to be executed manually, or together with the other codes below for a higher level of automation, error correction, and databasing of results.

• atomate2 [docs][repo]: A library of automated computational workflows for various properties, such as structural relaxations, bandgaps, etc.

The following lower-level codes provide additional critical functions, but most users will likely make contributions to pymatgen or atomate2.

• custodian [docs][repo]: Just in time (JIT) job management software that provides automated, on the fly error correction to calculations as they are running. Many workflows (particularly VASP and Q-Chem) are designed to work closely with custodian, although use of custodian is not required.

• jobflow [docs][repo]: A library for writing and executing workflows. Jobflow defines the base Job, Flow, and Maker classes that are used in atomate2 to define computational workflow steps.

• fireworks [docs][repo]: A software for managing execution of computational workflows, particularly suited for high-performance computing (HPC) environments with queueing systems. Instructions for setting up FireWorks for use with atomate2 can be found here. atomate2 workflows can also be run without FireWorks.

• emmet [docs][repo]: Defines structured schemas for storing outputs of different types of calculations performed by the Materials Project team. These comprise both code-specific schemas (e.g., for a VASP relaxation) and code-agnostic schemas (e.g., for any periodic solid material). emmet also uses maggma's Builder to define data processing pipelines that build the Materials Project database.

• maggma [docs][repo]: A framework for building modular data pipelines. maggma's Store and Builder classes provide a unified interface for accessing and transforming data. atomate2 uses Store to save workflow results into a database or file, and emmet uses Builder to define the pipelines for processing Materials Project data.

• crystaltoolkit [docs][repo]: A web app framework that makes it easy for developers to create interactive web apps for materials science data, based on plot.ly dash.

Because official MP codes are highly interdependent, their development is coordinated by the MP Software Foundation. This group of developers meets regularly to establish policies regarding the scope of different packages, coding standards, etc.

External Tools and Third-Party Codes

Many external or third-party developed codes are built to interoperate with the official MP codes above. An overview of these is available on the Software Ecosystem page.

How to Contribute

This section provides general guidelines for how to make contributions to the MP software ecosystem. If you are brand new to contributing to a software project, we encourage you to first read Questions and Answers for new Contributors.

Note that detailed instructions for setting up a development environment or installing the necessary packages and dependencies for a particular project are not found here. Because they are repository-specific, please consult the documentation of the respective repositories (linked above) for that.

Types of Contributions

We welcome many types of contributions, some of which require little to no coding experience. Contributions may include:

• Reporting a problem via a GitHub issue

• Testing a new feature

• Proposing a new feature

• Writing documenation

• Writing examples

• Developing graphics, slides, or Jupyter notebooks that aid in training and documentation

• Fixing a bug and submitting a GitHub pull request

• Writing a new feature and submitting a GitHub pull request

Communication

As you work on a contribution, the best ways to communicate with project maintainers and fellow users are:

• GitHub Issues: If you've found a problem or want to propose an idea, open an issue in the relevant repo. This is the first place to go if you need help with something. Please don't submit how-to and support questions via issues, use GitHub Discussions instead (see below).

• Pull Request Comments: If you want to discuss a specific change proposed in a pull request, use the PR's comments. This allows all discussions about a change to be kept in one place which is easily referenced later.

• GitHub Discussions: For more general discussions, use GitHub Discussions. This can be a great place to announce your intent to develop a new feature, ask for feedback on a proposal, discuss a new out-there idea, or get help with a problem.

Remember, it's okay to ask for help and feedback! We all started somewhere, and the MP community is there to help.

Code of Conduct

Official Materials Project codes implement the Contributor Covenant code of conduct, which applies to project maintainers as well as all interactions with and among contributors. The overarching principle is to maintain a respectful and inclusive environment. Please read and adhere to these guidelines to ensure a positive and welcoming atmosphere for all contributors.

TODO - need a link over "these guidelines" (need new PR to implement this)

## Contribution Workflow

Materials Project codes are hosted on GitHub and generally follow the GitHub Flow development model. If you're unfamiliar with this process, refer to GitHub docs for more information. Briefly, the steps are:

1. Read this guide: It provides an important orientation to the overall MP software ecosystem and expectations of code quality, etc.

2. Check the Discussion boards: Visit the GitHub discussion board for the project you want to contribute to to see whether anyone is working on something similar. You might find some free help!

3. Describe your plans: It's a good idea to post something on the discussion board to register your intentions (especially if you are developing a significant new feature or tutorial). This helps prevent duplication of effort.

4. Fork and Clone: Fork the repository you wish to contribute to, then clone it to your local machine.

5. Create a New Branch: Always create a new branch for your changes. This keeps your fork's main branch clean and makes it easier to open new pull requests in the future.

6. Commit Your Changes: Make your changes and commit them to your local repository.

7. Push to Your Fork: Push your changes to your fork.

8. Open a Pull Request (PR): Open a PR against the upstream repo you're contributing to. We encourage you to do so EARLY - well before your code is highly developed or even working. You can use the Draft status to show that your PR is not ready for review yet, but having it open allows you to receive feedback from project maintainers and other community stakeholders. You can always mark it as ready for review later.

## Code Quality Guidelines

Each Materials Project repository adheres to similar code format, testing, and documentation requirements. Although the specifics may vary slightly from repository to repository, the general requirements are as follows:

1. Code Style: All code should adhere to black formatting and ruff linting rules, use snake_case for variable naming, PascalCase for classes, CONSTANT_CASE for globals.

2. Testing: All new features and bug fixes need tests. These should be implemented using pytest, with a new unit test for each bug fix (that fails without the fix and passes with it) and functional tests for each new feature.

3. Documentation: Good docs are crucial. Function docstrings should follow the Google docstring format and describe every argument and keyword argument in concise terms, including appropriate units for the input (where applicable). Package documentation should be written in active and concise language, with small, ready-to-run code snippets that allow users to quickly try out new features. Relevant links should be included to allow users to easily find additional context or details e.g. in docs or GitHub issues/pull requests.

Questions and Answers for new Contributors

How much experience do I need to contribute?

None! We routinely have new contributors who have not previously been involved in software development, or who are currently learning it as part of their graduate training. We do not have the resources to provide individual mentorship, but we will do what we can to support new contributors.

How do I get started?

Reading this guide is the first step! After that, we suggest you visit the Discussion board of the GitHub repository for the project you want to contribute to. You can see what people are working on and even make a post to describe what you'd like to contribute to gather feedback.

If you prefer to discuss your plans more privately, don't be shy about reaching out to the package maintainers or other expert users directly.

Where can I find help?

GitHub Issues for bugs and Discussions for Q&A (see Communication) are a great place to start. For scientific and troubleshooting questions, you can also post on the MatSci forums. Finally, reach out to your colleagues, other expert users, or project maintainers.

How do I add a new workflow? (link to atomate)

See this tutorial in the atomate2 documentation! Note that all new workflows should go into atomate2 rather than the legacy version of atomate (a.k.a., atomate 1).

TODO - add link to atomate2 workflow tutorial

How do I support a new code in pymatgen?

See this tutorial in the pymatgendocumentation. You can also draw inspiration from similar PRs. The most recent new code support was parsing AIRSS (ab-initio random structure search) results implemented in pymatgen#2625.

TODO develop tutorial and add link to pymatgen

How do I make a web app to share my data?

We suggest using crystaltoolkit , which we built to make it easy to create web apps for materials science. We have a growing list of example apps on GitHub like this simple starter for rendering an interactive 3d crystal structure. You can find a simple tutorial here.

TODO - link to crystaltoolkit tutorial

How do I know who maintains XXX code?

Check the README file, which is displayed on the main page of each GitHub repository. We do our best to list the currently active maintainers of each repository there

TODO - can/should we make this a policy?

Getting Credit for your Work

We value community contributions and want to do our best to provide appropriate credit. Some of the ways you can get visible credit for your work include

• Submit a PR to be added to the lists of contributors for a specific code. For example, see

• All MP codes support duecredit, which provides function decorators to associate publications with specific functions, classes and modules. You are welcome to include these decorators in your contributions where applicable (e.g. when you re-implement code from a paper, or use parameters from a paper, or contribute code you've created and published about). If in doubt, better to add citations than to not have them.

• For pymatgen add-ons, submit a PR to be added to the addons page

Past MP Workshop Materials

To increase open access for the scientific the community, recordings and materials from the Materials Project Workshops are released publicly.

Overview

Many individuals both affiliated and unaffiliated with MP have published software that directly builds upon core MP resources. This page seeks to highlight such efforts so their hard work can be recognized and so you can learn about new tools that might benefit your own research.

The MP Community Software Ecosystem

The Materials Project does not have a unified code of conduct at present since it is a joint, collaborative effort, and different aspects of the Materials Project, such as its different open-source codes, are led and maintained by different individuals at different institutions.

Our Pledge

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

Our Standards

Examples of behavior that contributes to a positive environment for our community include:

• Demonstrating empathy and kindness toward other people

• Being respectful of differing opinions, viewpoints, and experiences

• Giving and gracefully accepting constructive feedback

• Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience

• Focusing on what is best not just for us as individuals, but for the overall community

Examples of unacceptable behavior include:

• The use of sexualized language or imagery, and sexual attention or advances of any kind

• Trolling, insulting or derogatory comments, and personal or political attacks

• Public or private harassment

• Publishing others’ private information, such as a physical or email address, without their explicit permission

• Other conduct which could reasonably be considered inappropriate in a professional setting

This page contains a summary of major changes for each version of the Materials Project database.

We are aware of a community need for more detailed change logs, and hope to improve our reporting for future database versions.

v2025.02.12.post1

This version went live on March 21st, 2025 at about 12:00pm Pacific.

This is a patch release addressing localized data issues.

Property Origins field

Elasticity Collection Updates

Further sanity checks were applied to deprecate additional documents (290 new deprecations) with unreasonable elastic moduli:

• Any documents with elastic moduli (bulk or shear) values outside the range of -100 GPa to 800 GPa were deprecated

• Any documents that failed either of the following elastic modulus requirements were also deprecated:

  • KR <= KVRH <= KV

  • GR <= GVRH <= GV

A backlog issue regarding inconsistencies in how deprecated elasticity documents were displayed in the Materials Explorer interface was also addressed

• Deprecated elasticity documents will no longer appear in the Materials Explorer search interface

• The deprecated documents can still be retrieved via the mp_api client

v2025.02.12.post

This version went live on February 28th, 2025 at about 6:30pm Pacific.

This is a patch release addressing localized data issues.

Elasticity Collection Updates

• Resolved tensor fitting failures for 2,484 compounds (approximately 28% increase in valid tensors)

v2025.02.12

This version went live on February 12th, 2025 at about 4pm Pacific.

New Content

• Added 1,073 ytterbium (Yb) materials recalculated using the Yb_3 pseudo-potential and re-relaxed with r2SCAN

• Added ~30 new hybrid inorganic/organic formate perovskites

Electronic Structure Data Updates

• Improved consistency of magnetic ordering assignment for structures in the electronic structure and summary collections

Battery Explorer/Electrode Collection Updates

• Resolved upstream builder dependencies that caused the initial data loss

v2024.12.18

This version went live on December 20th, 2024 at about 11pm Pacific.

Major updates include the addition of r2SCAN calculations and improvements to thermodynamic data handling.

New Content:

• Added 15,483 GNoME-originated materials calculated using r2SCAN. We remind our users that the GNoME structures are licensed BY-NC (non-commerical purposes). Explicitly accepting theBY-NC license is now required to access the GNoME dataset in the Materials/GNoME explorers and the API. A further release of an additional ~100k GNoME materials is in preparation.

Core Changes:

• • Previously: A material was required to have at least one GGA(+U)calculation

  • Now: MP accepts materials with only r2SCAN calculations, as going forward MP will be prioritizing r2SCAN workflows

  • This change restored 736 previously deprecated materials

Thermodynamic Data Updates:

• New hierarchy for thermodata presentation:

  • Affects Materials Explorer and MPRester().summary endpoint

  • These values were not passed through to the summary endpoint as a strict thermo_typeof GGA_GGA+U_R2SCANwas required

  • New preference order for thermo_type: GGA_GGA+U_R2SCAN> r2SCAN> GGA_GGA+U

  • The thermo_typefor a material can be found on the material's Material Detail Page under Properties in the Thermodynamic Stability tab

v2024.11.14

This version went live on December 12th, 2024 around noon Pacific.

• Transition in document schemas for the tasks collection:

  • Part of forward-looking transition from atomate to atomate2workflow orchestration package

  • Previous: emmet.core.vasp.task_valid.TaskDocument

  • Current: emmet.core.tasks.TaskDoc

  • Accessing fields is slightly different with TaskDoc (ex: each Calculation in calcs_reversed is no longer accessed like a dict, but as a Calculation object), but TaskDoc should be fully backwards compatible with operations on TaskDocument.

  • TaskDoc has some advantages over TaskDocument, such as dynamically updating task_type, run_type, and calc_type. This would avoid long-term errors such as noted below for certain NSCF calculations, or noted issues with incorrectly parsing r²SCAN meta-GGA calcs as (PBE) GGA

• 21,144 tasks were incorrectly assigned a task_type of NSCF Uniform when they were really NSCF Line. NSCF Uniform tasks are used to calculate DOSes, NSCF Linetasks are used to generate band structure scans. These and associated properties in materials/summary (band gaps, DOS, etc.) have been corrected.

• 39,374 materials were mistakenly assigned a DOS from a deprecated NSCF Uniform task. These have been corrected and removed

• The current set of 2,047 GNoME-originated materials has been deprecated in preparation for a release of about 120,000 GNoME materials

• While the XAS data has not changed, be sure to update to the newest version of pymatgen to avoid issues parsing certain XAS tasks

v2023.11.1

• Improved and expanded set of elasticity data. Note that there are schema changes with how it is accessed in SummaryDoc and ElasticityDoc.

• Conversion electrode data added alongside existing insertion electrode data.

• ~10k new materials added, with ~5k deprecated. This includes a temporary deprecation of all compounds containing Yb while they are being re-run. This is in response to pseudopotential issues identified which were providing incorrect energies.

v2022.10.28

This database build incorporates Materials Project’s (R2)SCAN calculations as pre-release data. The default fields returned by the website and API will remain unchanged from the previous release at the GGA(+U) level of theory, but the (R2)SCAN data is now available for advanced users. Either see the “Pre-release Data” section of a relevant material details page, generate an R2(SCAN) phase diagram with the Phase Diagram app, or access the data via the thermo API endpoint. This database release also incorporates several new perovskite materials from a collaboration with Zachary Bare, University of Colorado.

v2021.11.10

This will be the first release with our new website and API. It does not contain any new data but is built using our new database building methods and is largely consistent with the previous database release. Some changes exist to the previous release due to improvements to detection of multi-anion systems leading to changes in the applied formation energy corrections.

v2021.05.13

This release updates the energy correction scheme we use to generate phase diagrams and compute formation energies. As with any new database release, formation energies for many compounds have changed; however in this case the change is due only to our new energy correction scheme and not to any new data. We are proud to report that the new correction scheme has reduced the overall error in formation energy in our database by 7% compared to experiment.

You can see details of each correction that has been applied by inspecting the energy_adjustments attribute of a ComputedEntry retrieved via the API. In addition, the new correction scheme is available for manual use via the MaterialsProject2020Compatibility class in pymatgen.

1. Refitted corrections for legacy species Corrections applied to oxygen compounds, diatomic gases, and transition metal oxides and fluorides have been refit using more up to date DFT calculations and a larger compilation of computed and experimental formation enthalpy data.

2. Corrections for additional species We have added corrections for Br, I, Se, Si, Sb, and Te, which did not previously have energy corrections. As a result, formation energies for materials containing these species will generally be lower than they were previously.

3. Diatomic gas corrections moved to compounds Previously, corrections for H, F, Cl, and N were applied to the elements. One consequence of this was that polymorphs of H2, N2, Cl2 and F2 were alwaysassigned a zero energy above hull, even if some polymorphs were higher in energy. This made interpretation of these values confusing. With this release, energy corrections are applied to the material (e.g., LiH) and not the element. This also means that unstable polymorphs of diatomic gases will now have non-zero e_above_hull

4. Oxidation state based corrections Our build process now estimates the likely oxidation states of each species in a material, and uses this information to intelligently apply corrections to anionic species only when their estimated oxidation state is negative. For example, in the compound MoCl3O, estimated oxidation states for both Cl and O are negative, so both anions receive corrections.

Our algorithms are not always successful in predicting the oxidation state. When this occurs, we apply anion corrections to only the most electronegative element in the material. As a result, some ternary or higher compounds in the database may be destabilized in this release because their oxidation states could not be determined. This is the case for MoCl5O (mp-1196724) for example, which does not receive a Cl correction because O is more electronegative.

If this affects your work, you can manually assign oxidation states by populating the oxidation_states key of the .data attribute of any ComputedEntry and then reprocessing the data using MaterialsProject2020Compatibility.

A Note for API and MPRester Users

For API users, if you are retrieving formation energies directly via the API, you will get the correct, latest formation energies from the current database release. However, if you are using get_entries or get_pourbaix_entries which apply the correction scheme on-the-fly, make sure to update to the latest version of pymatgen (v2022.0.8 or later) to get the correct values. If you are using pymatgen v2021 or earlier, this will use the old correction scheme by default when using get_entries and get_pourbaix_entries.

v2021.03.22

This release updates some older materials with new calculations, and adjusts our rules for deprecating older calculations. It does not contain any new materials. Thanks to the new calculations many materials that were previously deprecated are now accessible again. This release is in preparation for a switch to our new compatibility scheme which will improve our predictions of formation energy.

v2021.02.08

We had a small new database release today, this introduces new higher-quality calculations for around 30,000 materials. It also deprecates 78 materials since we currently do not have calculations for these materials that match our current quality standards; we hope to restore these 78 materials in a subsequent release. For an exact list, please see the attached file.

As a reminder, all historical calculation tasks remain available via our API and the task detail pages, and information on deprecated materials also remain available via the API. More information on our deprecation policy is in our documentation. We continue our work on better ways communicate database diffs and to more easily provide access to historical information, so stay tuned for future announcements here.

v2020.09.08

This releases addresses issues noticed in the previous release with formation energies and updates the energies of approximately 6k materials where this error was greatest. We are planning a further supplemental release.

We’re also looking at ways to put in place a process to be more transparent with database changes and updates to share more specifically what has changed, as well as providing means to access historical versions of the database, since we know this is a common requirement.

Note that, wherever possible, we continue to keep individual historical calculation data available via its task_id even in cases where the aggregated information (such as that presented on the materials detail page) might change.

V2020.08.20 Released

v2020.06

In this database release, we have added several thousand materials and many magnetic ground states, improved the quality of our energetics, and fixed many bugs. This database release is part of on-going efforts in 2020 to improve database reliability and quality, following the introduction of our deprecation process last year. There are still known issues with this release which we are working to address, please let us know if you encounter any in our forum.

v2019.12.05

The issue mentioned in 2019-12-04 has now been addressed, however approximately 7% of materials saw errors in their reported energies above hull of greater than 0.05 eV/atom. Values calculated via pymatgen or via the phase diagram app on the website during this time were correct, while values reported on the materials details page and via the e_above_hull API key were incorrect.

We encourage users who accessed convex hulls from the website between the latest database release and 2019-12-05 to re-check any values obtained from the website.

We apologize for the error, and will be incorporating additional checks into our automated testing to prevent similar errors in the future.

v2019.12.04

We are aware of an on-going issue with the reported energies above hull on the materials detail pages. We will update this thread when a fix has been fully implemented and with further details.

Until this issue is fully resolved, correct energies above hull can be retrieved using pymatgen as follows:

If you have not previously used pymatgen, it is a Python code and can be installed using pip install pymatgen or conda install --channel conda-forge pymatgen.

Note: the above information for v2019-12-04 is now out of date.

v2019.11.21

During deployment of the new v2019.11 database, there was temporary issue with generating interactive phase diagrams leading to incorrect formation enthalpies for a small number of chemical systems. This has now been fixed. Data presented on the materials detail pages was unaffected by this issue.

v2019.11

• Introduced 3,971 new materials

• Amorphous materials added with amorphous tag

• Added theoretical which is True when the material matches no known experimental structure from ICSD

• Fixed several inconsistency bugs for band_gap, piezo tensors, elastic warnings, and total magnetic moment.

v2019.05

• Introduced a new deprecated field to materials. By default the website and API only search for materials that are not deprecated: {“deprecated”: false}.

• Deprecated 15,000 and added 3,600 new materials. We will be recomputing the deprecated materials to fill these spaces back up. Some of these new relaxations may end up matching current materials, so the total number of materials is not guaranteed to be the same as in V2019.02. This also affects downstream properties. Most notably, ~3k elastic tensors associated with the deprecated materials have been removed from the database and are no longer accessible.

• Fixed an issue with sandboxes not properly building the whole hull. Previously, only the sandboxed chemical systems were being recalculated for energy_above_hull searches

v2019.02

• Added over 47,000 new materials from orderings of disordered ICSD as well as compounds from the Pauling File

• Finalized enforcing symmetry on piezo tensors

• Moved third order elastic data to elasticity_third_order so that people are not swamped by the mountain of information associated with it.

v2018.12

• Adjusted the mp-id naming scheme to fix “mvc” ids taking over old mp-ids.

• Fixed piezoeletric max_direction to be a miller index rather than a unit vector.

v2018.11

• Changed the grouping of magnetic materials to aggregate all magnetic orderings of a given material into a single material-id, and report the lowest energy ordering

• Fixed incorrect calculation and display of polycrystalline dielectric constants

• Fixed labeling of all materials as high-pressure. Note we’re parsing ICSD tags for this labeling so while some materials may not conventionally be considered high-pressure, a single matching ICSD entry can tag a material as such. We would love to hear comments on how we could better tag high-pressure materials

• Begun enforcing the symmetry of the structure on piezo tensors. In general, this reduces the expected piezo value.

Concepts

Each MPContribs deployment is organized into projects. The MP account creating the project becomes its owner. An owner can ask for the MP accounts of their collaborators to be given access to their project. A collaborator assumes the same level of permissions within a project as the owner.

A project contains a list of contributions to existing MP materials (or alternatively to formulas and chemical systems). It's in the owner's purview to decide what exactly constitutes a project. Often this will simply be an umbrella for a dataset containing contributions to MP materials that are comparable in their scientific context and thus are consistent in their data schema.

By default, projects are set to private, i.e. only visible to owners and their collaborators. Each individual contribution in a project is set to public by default and thus automatically released to the public when the project is published. Since the public/private flag can be controlled for each contribution individually, some contributions in a project can be kept private even if the project is public. The public/private state of a project and its contributions can be changed/reverted at any time.

Materials Science Community Forum at matsci.org

Contact

This section provides a list of methodologies used in computational materials science to calculate properties of materials.

What is a material?

The term materials is used quite loosely, and has become more inclusive as the materials science community branches out to do more research in various areas of physics and chemistry. The conventional textbook definition of materials is divided, by chemical composition, into three classes: metals, ceramics and polymers.

Metallic materials are composed of, as the name suggests, metals. This class of materials is commonly seen in applications where structural integrity is important; jet engines, for example, has to use an alloy of up to 15 types of metals to withstand the high temperature generated by the combustion while still being able to stay structurally intact.

Ceramic materials are mostly oxides of metals, for the purpose of materials science. Some staple ceramic materials include Lead Zirconate Titanate (PZT) and CoO2. The former is the most commonly used piezoelectric (this type of materials converts mechanical work into electrical work) while the latter is the most commonly used Lithium ion battery cathode.

Polymer materials are results of polymerization of organic monomer molecules. As a relatively new member of the materials class, polymers have received much attention in the research space thanks to their versatility. Everyday plastic items, ranging from plastic bags, take out containers and Tupperware to water bottles, toys and Legos, are all polymers. Furthermore, polymer research in materials science also branch out to biological areas like drug delivery and tissue regeneration.

Another way to classify materials is by its usage case; in this scenario materials are classified into structural and functional materials. Structural materials, as the name suggests, serves to protect the structural integrity of something. A car frame, for example, would be a structural material. Functional materials, on the other hand, serves some kind of function (other than supporting weight, that is). The majority of modern-day materials science research lives in this functional materials space, ranging from semiconductors in computer chips, battery electrodes and OLEDs to piezoelectrics and MRI machines.

In short, materials science focuses on the joint of physics and chemistry and works on coming up with designs that satisfy a particular need in our real world.

What kind of properties do we care about?

Depending on the intended usage of our calculated data, there are different sets of properties that we care about.

For example, a materials scientist might be working on coming up with a semiconducting material that serves a certain purpose. They will be interested in looking at the electronic structure behavior of materials, such as band structure. Someone else might be interested in looking at piezoelectric properties, while others are interested in the migration behavior of a battery material. In short, depending on the interest, there is a range of properties we care about and calculate.

How do we calculate/predict these properties?

In computational materials science, we use Ab Initio (from first principle) methods to simulate the behavior of particles in the systems we're interested in. For materials data on the Materials Project, the majority of our work is done using Vienna Ab Initio Simulation Package (VASP), which implements Density Functional Theory (DFT) to calculate all kinds of properties from first principle.

Calculation Parameters

Total energy convergence

As mentioned, we currently employ a k-point mesh of 1000 per reciprocal atom (pra). However, we have performed a convergence test of total energy with respect to k-point density and convergence energy difference for a subset of chemically diverse compounds for a previous parameter set, which employed a smaller k-point mesh of 500 pra. Using a 500 pra k-point mesh, the numerical convergence for most compounds tested was within 5 meV/atom, and 96% of compounds tested were converged to within 15 meV/atom. Results for the new parameter set will be better due to the denser k-point mesh employed. Convergence will depend on chemical system; for example, oxides were generally converged to less than 1 meV/atom. [2]

Structure convergence

The energy difference for ionic convergence is set to 0.0005 * natoms in the cell. Data on expected accuracy on cell volumes can be found in a previous paper. [1] We have found these parameters to yield well-converged structures in most instances; however, if the structures are to be used for further calculations that require strictly converged atomic positions and cell parameters (e.g. elastic constants, phonon modes, etc.), we recommend that users re-optimize the structures with tighter cutoffs or in force convergence mode.

Authors

1. Shyue Ping Ong

References

[1]: A. Jain, G. Hautier, C. Moore, S.P. Ong, C.C. Fischer, T. Mueller, K.A. Persson, G. Ceder., A High-Throughput Infrastructure for Density Functional Theory Calculations, Computational Materials Science. vol. 50 (2011) 2295-2310.

[2]: L. Wang, T. Maxisch, G. Ceder, Oxidation energies of transition metal oxides within the GGA+U framework, Physical Review B. 73 (2006) 1-6.

We use DFT as implemented in the Vienna Ab Initio Simulation Package (VASP) software [1] to evaluate the total energy of compounds. For the exchange-correlational functional, we employ a mix of Generalized Gradient Approximation (GGA) and GGA+U, or a mix of GGA, GGA+U, and r2SCAN. Both mixing schemes are described here. All calculations are performed at 0 K and 0 atm. All computations are performed with spin polarization on and with magnetic ions in a high-spin ferromagnetic initialization (the system can of course relax to a low spin state during the DFT relaxation). For a select number of materials, alternate spin states are searched for. Details on this can be found in the Magnetic Properties section.

Input structures are sourced from many different places, including the Inorganic Crystal Structure Database (ICSD). [2] We relax all cell and atomic positions in our calculation two times in consecutive runs. When multiple crystal structures are present for a single chemical composition, we attempt to evaluate all unique structures as determined by an affine mapping technique. [3]

More detailed information on the GGA/GGA+U and r2SCAN calculations run by the Materials Project can be found in the following two subsections:

References

[1]: Kresse, G. & Furthmuller, J., 1996. Efficient iterative schemes for ab initio total-energy calculations using a plane-wave basis set. Physical Review B, 54, pp.11169-11186.

[2]: G. Bergerhoff, The inorganic crystal-structure data-base, Journal Of Chemical Information and Computer Sciences. 23 (1983) 66-69.

[3]: R. Hundt, J.C. Schön, M. Jansen, CMPZ - an algorithm for the efficient comparison of periodic structures, Journal Of Applied Crystallography. 39 (2006) 6-16.

Hubbard U Values

It is well-known that first principles calculations within the local density approximation (LDA) or generalized gradient approximation (GGA) lead to considerable error in calculated redox reaction energies of many transition metal compounds. This error arises from the self-interaction error in LDA and GGA, which is not canceled out in redox reactions where an electron is transferred between significantly different environments, such as between a metal and a transition metal or between a transition metal and oxygen or fluorine. Extensive discussion of this issue can be found in the following works. [1-4]

In the Materials Project, for an oxide or fluoride material with a transition element listed previously, with the VASP input settings constructed according to the logic defined in pymatgen.

Calibration and Values

3. We find the U value that minimizes the sum of square Error / Redox.

The full list of U values used is described in the table below. For oxides and fluorides containing any of the elements, only GGA+U calculations are performed.

Caveats

The U values are calibrated for phase stability analyses, and should be used with care if applied to obtain other properties such as band structures. Also, the U values depend on the pseudopotential used. Further, typically, U values should be site specific, however in our approach, U values were applied to all sites with an element listed above, and only to the d-orbitals. A discussion of the pseudopotentials used in the Materials Project can be found here.

References

[1]: F. Zhou, M. Cococcioni, C. A. Marianetti, D. Morgan and G. Ceder. First-principles prediction of redox potentials in transition-metal compounds with LDA+U. Physical Review B, 2004, 70, 235121. doi:10.1103/PhysRevB.70.235121

[2]: M. Cococcioni, S. de Gironcoli, Linear response approach to the calculation of the effective interaction parameters in the LDA+U method. Physical Review B, 2005, 71, 035105. doi:10.1103/PhysRevB.71.035105

[3]: L. Wang, T. Maxisch, & G. Ceder. Oxidation energies of transition metal oxides within the GGA+U framework. Physical Review B. 2006, 73, 195107, doi:10.1103/PhysRevB.73.195107

[4]: A. Jain, G. Hautier, S. P. Ong, C. Moore, C. Fischer, K. A. Persson, & G. Ceder. Formation enthalpies by mixing GGA and GGA + U calculations. Physical Review B, 2011, 84(4), 045115. doi:10.1103/PhysRevB.84.045115

[5]: M. Wang, A. Navrotsky Enthalpy of formation of LiNiO2, LiCoO2 and their solid solution, LiNi1-xCoxO2, Solid State Ionics, vol. 166, no. 1-2, pp. 167-173, Jan. 2004.

Information regarding calculation parameters, convergence, and pseudopotential choices can also be found in the following subsections:

References

[1] R. Kingsbury, A. S. Gupta, C. J. Bartel, J. M. Munro, S. Dwaraknath, M. Horton, and K. A. Persson Phys. Rev. Materials 6, 013801 (2022)

Calculation Parameters

Convergence

References

[1] P. Wisesa, K. A. McGill, and T. Mueller, Efficient generation of generalized Monkhorst-Pack grids through the use of informatics, Phys. Rev. B 93, 1 (2016).

[2] R. Kingsbury, A. S. Gupta, C. J. Bartel, J. M. Munro, S. Dwaraknath, M. Horton, and K. A. Persson Phys. Rev. Materials 6, 013801 (2022)

All calculations used pseudopotentials from the "PBE PAW datasets version 54" set released in September 2015; a list of the specific POTCAR symbols used for each element is provided below. Although these pseudopotentials were developed for use with the PBE functional, their use with SCAN is common practice because no SCAN-specific pseudopotentials are available for use in VASP.

References

[1] R. Kingsbury, A. S. Gupta, C. J. Bartel, J. M. Munro, S. Dwaraknath, M. Horton, and K. A. Persson Phys. Rev. Materials 6, 013801 (2022)

To better model energies across diverse chemical spaces, we apply several adjustments to the total calculated energy of each material. These adjustments fall into two different sets, each of which is described in a different subsection. One set, consisting of anion and GGA/GGA+U mixing scheme corrections, and another consisting of only GGA/GGA+U/r2SCAN mixing scheme corrections. The former is used in the in the current and legacy data, while the latter is only present in releases after the addition of r2SCAN calculations (post v2022.10.28). Both of them are used to produce ComputedStructureEntry objects, and mixed phase diagrams.

Mixing Rules

The two rules used to construct mixed GGA/GGA+U/r2SCAN phase diagrams are as follows:

References

Methodology

1) Anion corrections

2) GGA / GGA+U Mixing Corrections

Some compounds are better modeled with a U correction term to the density functional theory Hamiltonian while others are better modeled without (i.e., regular GGA). Energies from calculations with the +U correction are not directly comparable to those without. To obtain better accuracy across chemical systems, we use GGA+U when appropriate, GGA otherwise, and mix energies from the two calculation methodologies by adding an energy correction term to the GGA+U calculations to make them comparable to the GGA calculations.

Accuracy of Total Energies

To estimate the accuracy of our total energy calculations, we compute reaction data and compare against experimental data. Note that this data set was compiled using a lower k-point mesh and pseudopotentials with fewer electrons than the current Materials Project parameter set.

Estimating errors in calculated reaction energies

Figure 1: Errors in Calculated Formation Energies for 413 binaries in the Kubaschewski Tables. Energies are normalized to per mol atom.

Sources of error

GGA errors on reaction energies between chemically similar compounds

The main conclusions are:

• The error in reaction energies for the binary oxide to ternary oxides reaction energies are an order of magnitude lower than for the more often reported formation energies from the element. An error intrinsic to GGA (+U) is estimated to follow a normal distribution centered in zero (no systematic underestimation or overestimation) and with a standard deviation around 24 meV/at.

• When looking at phase stability (and for instance assessing if a phase is stable or not), the relevant reaction energies are most of the time not the formation energies from the elements but reaction energies from chemically similar compounds (e.g., two oxides forming a third oxide). Large cancellation of errors explain this observation.

• The +U is necessary for accurate description of the energetics even when reactions do not involve change in formal oxidation states

Citations

To cite the calculation methodology, please reference the following works:

References

[2]: A. Jain, G. Hautier, S.P. Ong, C. Moore, C.C. Fischer, K.A. Persson, G. Ceder, Formation Enthalpies by Mixing GGA and GGA+U calculations, Physical Review B, vol. 84 (2011), 045115.

[3]: J.B. Foresman, A.E. Frisch, Exploring Chemistry With Electronic Structure Methods: A Guide to Using Gaussian, Gaussian. (1996).

[4]: A. Jain, S.-a Seyed-Reihani, C.C. Fischer, D.J. Couling, G. Ceder, W.H. Green, Ab initio screening of metal sorbents for elemental mercury capture in syngas streams, Chemical Engineering Science. 65 (2010) 3025-3033.

[5]: S. Lany, Semiconductor thermochemistry in density functional calculations, Physical Review B. 78 (2008) 1-8.

[6]: G. Hautier, S.P. Ong, A. Jain, C. J. Moore, G. Ceder, Accuracy of density functional theory in predicting formation energies of ternary oxides from binary oxides and its implication on phase stability, Physical Review B, 85 (2012), 155208

Acknowledgments

Thank you to the original authors of this page:

1. Anubhav Jain

2. Shyue Ping Ong

3. Geoffroy Hautier

4. Charles Moore

Background

Methodology

Citations

References

Introduction

A phonon is a collective excitation of a set of atoms in condensed matter. These excitations can be decomposed into different modes, each being associated with an energy that corresponds to the frequency of the vibration. The different energies associated with each vibrational mode constitute the phonon vibrational spectra (or phonon band structure). The vibrational spectra of materials play an important role in physical phenomena such as thermal conductivity, superconductivity, ferroelectricity and carrier thermalization.

There are different methods to calculate the vibrational spectra from first-principles using the density functional theory formalism (DFT). It can be obtained from the Fourier transform of the trajectories of the atoms on a molecular dynamics run, from finite-differences of the total energy with respect to atomic displacements or directly from density functional perturbation theory (DFPT). The latter method is the one used in the calculations on the Materials project page.

Formalism

In the density functional perturbation theory formalism the derivatives of the total energy with respect to a perturbation are directly obtained from the self-consistency loop [1] For a generic point q in the Brillouin zone the phonon frequencies $\omega_{\mathbf{q},m}$ and eigenvectors $U_m(\mathbf{q}\kappa'\beta)$ are obtained by solving of the generalized eigenvalue problem

where $\kappa$ labels the atoms in the cell, $\alpha$ and $\beta$ are cartesian coordinates and $\widetilde{C}_{\kappa\alpha,\kappa'\beta}(\mathbf{q})$ are the interatomic force constants in reciprocal space, which are related to the second derivatives of the energy with respect to atomic displacements. These values have been obtained by performing a Fourier interpolation of those calculated on a regular grid of q-points obtained with DFPT.

Thermodynamic properties

The vibrational density of states $g(\omega)$ is obtained from an integration over the full Brillouin zone

where $n$ is the number of atoms per unit cell and $N$ is the number of unit cells. The expressions for the Helmholtz free energy $\Delta F$, the phonon contribution to the internal energy $\Delta E_{\text{ph}}$, the constant-volume specific heat $C_v$ and the entropy $S$ can be obtained in the harmonic approximation [2]

where $k_B$ is the Boltzmann constant and $\omega_L$ is the largest phonon frequency.

Calculation details

All the DFT and DFPT calculations are performed with the ABINIT software package [3,4].

The PBEsol [5] semilocal generalized gradient approximation exchange-correlation functional (XC) is used for the calculations. This functional is proven to provide accurate phonon frequencies compared to experimental data [6]. The pseudopotentials are norm-conserving [7] and taken from the pseudopotentials table Pseudo-dojo version 0.3 [8].

The plane wave cutoff is chosen based on the hardest element for each compound, according to the values suggested in the Pseudo-dojo table. The Brillouin zone is sampled using equivalent k-point and q-point grids that respect the symmetries of the crystal with a density of approximately 1500 points per reciprocal atom and the q-point grid is always $\Gamma$-centered [^9].

All the structures are relaxed with strict convergence criteria, i.e. until all the forces on the atoms are below $10^{-6}$ Ha/Bohr and the stresses are below $10^{-4}$ Ha/Bohr$^3$.

The primitive cells and the band structures are defined according to the conventions of Setyawan and Curtarolo [10].

Citation

Guido Petretto, Shyam Dwaraknath, Henrique P. C. Miranda, Donald Winston, Matteo Giantomassi, Michiel J. van Setten, Xavier Gonze, Kristin A. Persson, Geoffroy Hautier, Gian-Marco Rignanese, High-throughput density functional perturbation theory phonons for inorganic materials, Scientific Data, 5, 180065 (2018). doi:10.1038/sdata.2018.65

References

[1]: Gonze, X. & Lee, C. Dynamical matrices, Born effective charges, dielectric permittivity tensors, and interatomic force constants from density functional perturbation theory. Phys. Rev. B 55, 10355–10368 (1997)

[2]: C. Lee & X. Gonze, Ab initio calculation of the thermodynamic properties and atomic temperature factors of SiO2 α-quartz and stishovite. Phys. Rev. B 51, 8610 (1995)

[3]: Gonze, X. et al. First-principles computation of material properties: the Abinit software project. Computational Materials Science 25, 478 – 492 (2002)

[4]: Gonze, X. et al. ABINIT: First-principles approach to material and nanosystem properties. Computer Physics Communications 180, 2582 – 2615 (2009)

[5]: Perdew, J. P. et al. Restoring the density-gradient expansion for exchange in solids and surfaces. Phys. Rev. Lett. 100, 136406 (2008)

[6]: He, L. et al. Accuracy of generalized gradient approximation functionals for density-functional perturbation theory calculations. Phys. Rev. B 89, 064305 (2014)

[7]: Hamann, D. R. Optimized norm-conserving Vanderbilt pseudopotentials. Phys. Rev. B 88, 085117 (2013)

[8]: van Setten, M., Giantomassi, M., Bousquet, E., Verstraete, M.J., Hamann, D.R., Gonze, X. & Rignanese, G.-M., et al. The PseudoDojo: Training and grading a 85 element optimized norm-conserving pseudopotential table (2018). Computer Physics Communications 226, 39.

[9]: Petretto, G., Gonze, X., Hautier, G. & Rignanese, G.-M. Convergence and pitfalls of density functional perturbation theory phonons calculations from a high-throughput perspective. Computational Materials Science 144, 331 – 337 (2018)

[10]: Setyawan, W. & Curtarolo, S. High-throughput electronic band structure calculations: Challenges and tools. Computational Materials Science 49, 299 – 312 (2010)

Introduction

Diffraction occurs when waves (electrons, x-rays, neutrons) scattering from obstructions act as secondary sources of propagation. In the case of crystal structures, atoms in periodic lattices act as scattering sites from which constructive and destructive interference can occur. Line spectra of scattering intensity as a function incident angle can give powerful information into the planar spacing and symmetries of a crystalline material.

X-ray Diffraction Formalism

The calculation of x-ray diffraction patterns (XRD) in the Materials Project relies on the diffraction condition in reciprocal space[1]:

where $\bold{k}$ is the wave vector of the incident x-ray, $\bold{k'}$ is the wave​vector is the scattered x-ray and $\bold{g_{hkl}}$is the reciprocal lattice vector of the parallel set of diffracting planes with miller indices hkl. The length of reciprocal lattice plane vector $\bold{g_{hkl}}$ is given by:

where $\lambda$ is the wavelength of the x-ray. Therefore, the maximum diffraction plane condition which is searched is $|\bold{g_{hkl}}| =\frac{2}{\lambda}$. Once all of the relevant diffraction planes with reciprocal lattice vectors within this limit are selected, the diffraction condition for each of these planes can be calculated:

where $d_{hkl}$ is the is the spacing of the hkl plane. The structure factor for each of these diffraction conditions is calculated as:

where $j$ is the index for the $N$ atoms in the unit cell, $\bold{r}$​ is the basis vector for the atoms in the unit cell. The atomic scattering factor $f$​ is given by:

where $s = \frac{\sin(\theta)}{\lambda}$, $a_{i}$ and $b_{i}$ are parameters fitted to individual elements. ​The intensity of each diffraction condition is given by the squared modulus of the structure factor.

Finally the Lorentz-polarization factor is applied to correct for the change in x-ray amplitude due to scattering angle and geometry of the experimental conditions:

Electron Diffraction

The Transmission Electron Microscopy (TEM) pattern for multiple Laue zones is calculated similarly to the XRD diffraction patterns and is available through the diffraction properties tab in the materials explorer.

References

[1]: De Graef, Marc, and Michael E. McHenry. Structure of materials: an introduction to crystallography, diffraction and symmetry. Cambridge University Press, 2012.

Introduction

The chemical potential diagram is the mathematical dual to the compositional phase diagram. To create the diagram, convex minimization is performed in energy (E) vs. chemical potential (μ) space by taking the lower convex envelope of hyperplanes. Accordingly, “points” on the compositional phase diagram become N-dimensional convex polytopes (domains) in chemical potential space.

For more information on this specific implementation of the algorithm, please cite/reference the paper below:

Methodology

Constructing hyperplanes

Calculating lower convex envelope (halfspace intersection)

Visualizing the chemical potential diagram

Relationship to predominance diagrams

Citations

References

[1] Yokokawa, H. “Generalized chemical potential diagram and its applications to chemical reactions at interfaces between dissimilar materials.” JPE 20, 258 (1999). https://doi.org/10.1361/105497199770335794

[1] Todd, P. K., McDermott, M. J., Rom, C. L., Corrao, A. A., Denney, J. J., Dwaraknath, S. S., Khalifah, P. G., Persson, K. A., & Neilson, J. R. (2021). Selectivity in Yttrium Manganese Oxide Synthesis via Local Chemical Potentials in Hyperdimensional Phase Space. Journal of the American Chemical Society, 143(37), 15185-15194. https://doi.org/10.1021/jacs.1c06229

Introduction

A phase diagram is a calculation of the thermodynamic phase equilibria of multicomponent systems. It is an important tool in materials science for revealing 1) thermodynamic stability of compounds, 2) predicted equilibrium chemical reactions, and 3) processing conditions for synthesizing materials. However, the experimental determination of a phase diagram is an extremely time-consuming process, requiring careful synthesis and characterization of all phases in a chemical system.

Computational modeling tools, such as the density functional theory (DFT) methods used by the Materials Project, can accelerate compositional phase diagram construction significantly. By calculating the energies of all known compounds in a given chemical system (e.g. the lithium/iron/oxygen chemical system, Li-Fe-O), we can determine the phase diagram for that system at a temperature of $T=0$ K and pressure of $P=0$ atm. Furthermore, for systems comprised of predominantly solid phases open with respect to a gaseous element, approximations can be made as to the finite temperature and pressure phase diagrams.

In this section, we will describe the theory/methodology behind the calculation of compositional phase diagrams.

Methodology

This section will discuss how to construct phase diagrams from DFT-calculated energies. This is exact process done by the Materials Project (MP) for computing formation energies, thermodynamic stability, and phase diagrams. This methodology has been implemented in Python within the pymatgen package. Please see Code (pymatgen)for brief examples of how to build phase diagrams on your own.

Calculating formation energy

The formation energy, $\Delta E_f$, is the energy change upon reacting to form a phase of interest from its constituent components. The components typically used are the constituent elements. For a phase composed of $N$ components indexed by $i$, the formation energy can be calculated as follows:

$\Delta E_f = E - \sum_i^N{n_i\mu_i}$

where $E$ is the total energy of the phase of interest, $n_i$is the total number of moles of component $i$, and $\mu_i$ is the total energy of component $i$. Note that $\mu_i$is often referred to as the chemical potential of the component, however, this is only rigorously true when working with Gibbs free energies, $G$.

Typically, formation energies are normalized on a per-atom basis by dividing by the number of atoms in 1 mole of formula. For example, for BaTiO$_3$, the normalized per-atom formation energy would be calculated by dividing the $E_f$ above by 5 atoms.

Constructing the compositional phase diagram

The convex hull approach

To construct a phase diagram, one needs to compare the relative thermodynamic stability of phases belonging to the system using an appropriate free energy model. For an isothermal, isobaric, closed system, the relevant thermodynamic potential is the Gibbs free energy, $G$, which can be expressed as a Legendre transform of the enthalpy, $H$, and internal energy, $E$, as follows:

where $T$ is the temperature of the system, $S$ is the entropy of the system, $P$ is the pressure of the system, $V$ is the volume of the system, and $N_i$ is the number of atoms of species $i$ in the system.

For systems comprising primarily of condensed phases, the $PV$ term can be neglected and at 0K, the expression for $G$ simplifies to just $E$. Normalizing $E$ with respect to the total number of particles in the system, we obtain $\bar{E}(0,P,x_{Li},x_{Fe},x_O)$. By taking the convex hull [2] of $E$ for all phases belonging to the M-component system and projecting the stable nodes into the $(M-1)$- dimension composition space, one can obtain the 0 K phase diagram for the closed system at constant pressure. The convex hull of a set of points is the smallest convex set containing the points. For instance, to construct a 0 K, closed $Li-Fe-O$ system phase diagram, the convex hull is taken on the set of points in $(\bar{E},x_{Li},x_{Fe})$ space with $x_O$ being related to the other composition variables by $x_O = 1 - x_{Li} - x_{Fe}$.

Evaluating thermodynamic stability

Figure 2 is an example of a calculated binary A-X phase diagram at 0 K and 0 atm. Binary phase diagrams show the complete convex hull for the system, where the y-axis is the formation energy per atom and the x-axis is the composition.

The blue lines show the convex hull construction, which connects stable phases (circles). Unstable phases will always appear above the convex hull line (squares); one measure of the thermodynamic stability of an arbitrary compound is its distance from the convex hull line ($\Delta E_d$), which predicts the decomposition energy of that phase into the most stable phases.

Accuracy of Calculated Phase Diagrams

In general, we can expect that compositional phase diagrams comprising of predominantly solid phases to be reproduced fairly well by our calculations. However, it should be noted that there are inherent limitations in accuracy in the DFT calculated energies. Furthermore, our calculated phase diagrams are at 0 K and 0 atm, and differences with non-zero temperature phase diagrams are to be expected.

For grand potential phase diagrams, further approximations are made as to the entropic contributions [2]. They are therefore expected to be less accurate, but nonetheless provide useful insights on general trends.

Code (pymatgen)

GGA/GGA+U

Constructing mixed GGA/GGA+U phase diagrams can be done directly with the corrected ComputedStructureEntry objects from the API.

from mp_api.client import MPRester
from pymatgen.analysis.phase_diagram import PhaseDiagram, PDPlotter

with MPRester("your_api_key") as mpr:

    # Obtain only corrected GGA and GGA+U ComputedStructureEntry objects
    entries = mpr.get_entries_in_chemsys(elements=["Li", "Fe", "O"], 
                                         additional_criteria={"thermo_types": ["GGA_GGA+U"]}) 
    # Construct phase diagram
    pd = PhaseDiagram(entries)
    
    # Plot phase diagram
    PDPlotter(pd).get_plot()

GGA/GGA+U/R2SCAN

Constructing a mixed GGA/GGA+U/R2SCAN phase diagram requires corrections to be reapplied locally. This is because the corrected ComputedStructureEntry object obtained from the thermodynamic data endpoint of the API for a given material is from its home chemical system phase diagram (i.e. Si-O for SiO2, or Li-Fe-O for Li2FeO3).

Unlike the previous GGA/GGA+U only mixing scheme, the updated scheme does not guarantee the same correction to an entry in phase diagrams of different chemical systems. In other words, the energy correction applied to the entry for silicon (mp-149) in the Si-O phase diagram is not guaranteed to be the same for the one in the Si-O-P phase diagram.

For more details on the correction scheme and its logic, see the Energy Corrections section or the original publication [4].

from mp_api.client import MPRester
from pymatgen.analysis.phase_diagram import PhaseDiagram, PDPlotter
from pymatgen.entries.mixing_scheme import MaterialsProjectDFTMixingScheme

with MPRester("your_api_key") as mpr:

    # Obtain GGA, GGA+U, and r2SCAN ComputedStructureEntry objects
    entries = mpr.get_entries_in_chemsys(elements=["Li", "Fe", "O"], 
                                         additional_criteria={"thermo_types": ["GGA_GGA+U", "R2SCAN"]}) 
    
    # Apply corrections locally with the mixing scheme
    scheme = MaterialsProjectDFTMixingScheme()
    corrected_entries = scheme.process_entries(entries)
    
    # Construct phase diagram
    pd = PhaseDiagram(corrected_entries)
    
    # Plot phase diagram
    PDPlotter(pd).get_plot()

Citations

References

[1] Bartel, C.J. Review of computational approaches to predict the thermodynamic stability of inorganic solids. J Mater Sci 57, 10475–10498 (2022). https://doi.org/10.1007/s10853-022-06915-4

[2] V. Raghavan, Fe-Li-O Phase Diagram, ASM Alloy Phase Diagrams Center, P. Villars, editor-in-chief; H. Okamoto and K. Cenzual, section editors; http://www1.asminternational.org/AsmEnterprise/APD, ASM International, Materials Park, OH, 2006.

[3]: https://dx.doi.org/10.1145/235815.235821

[4] Kingsbury, R.S., Rosen, A.S., Gupta, A.S. et al. A flexible and scalable scheme for mixing computed formation energies from different levels of theory. npj Comput Mater 8, 195 (2022). https://doi.org/10.1038/s41524-022-00881-w

Calculation Details

A relaxed structure associated with the canonical data in the entries field of a material data entry is used to run both uniform and line-mode NSCF calculations with the same functional (and U if any). Currently, only GGA (PBE) and GGA+U DOS and band structures are available from the database.

We first run a static (SCF) calculation with a uniform (Monkhorst Pack or $\Gamma$-centered for hexagonal systems) k-point grid determined by the standard MPStaticSet input set in pymatgen. The charge density is extracted from this and used for the subsequent uniform and line-mode NSCF calculations. The parameters for both of these are determined by the MPNonSCFSet input set in pymatgen. For more details, see the band structure workflow in atomate.

Line-mode Band Structure

The line-mode NSCF calculation is run with k-points chosen along high-symmetry lines within the Brillouin zone of the material. Currently, three conventions for choosing this k-path are used, and follow the methodologies by Curtarolo et al. [1], Hinuma et al. [2], and Munro et al. [3] Code for generating the k-paths can be found within pymatgen.