openmaterials.ai / codes / pymatgen

pymatgen: structures, file formats and thermodynamic analysis for materials data

The Python library behind the Materials Project: core objects for structures and computed entries, parsers for electronic structure codes, and phase diagram and reaction analysis.

What it is and how it works

From energies to phase diagrams

ComputedEntry objects (composition plus energy) feed the phasediagram package, which builds compositional and grand canonical hulls. One DFT run plus Materials Project entries placed Li4SnS4 on the hull (Ong 2013).

Core objects

Element, Lattice, Site, PeriodicSite, Structure, Molecule and Composition live in the core package. Most objects serialize to JSON via to_dict and from_dict (Ong 2013).

Input and output

The io package reads CIF through PyCifRW, molecular formats through OpenBabel and VASP files through vaspio, and converts a Structure to an ASE Atoms object (Ong 2013).

Transformations and alchemy

SubstitutionTransformation, species removal, ordering of disordered cells, supercells. alchemy applies a sequence to many structures and keeps the history (Ong 2013).

Assimilation and compatibility

borg walks a directory tree and turns VASP runs into ComputedEntry objects in parallel. compatibility mixes GGA and GGA+U energies with fitted corrections (Ong 2013).

Materials API client

The matproj package queries the Materials Project REST API for structures, formation energies, calculation parameters and experimental thermochemistry (Ong 2013).

What people do with it

  • 1DFT run needed to place Li4SnS4 on the hullOng 2013
  • 1521semiconductors in the DFPT phonon databasePetretto 2018
  • 29,902ICSD phases pulled from the Materials ProjectSun 2016

DFPT phonons for 1521 inorganic solids

ABINIT phonon bands, Born charges and dielectric tensors for 1521 semiconductors, inputs and analysis through pymatgen and AbiPy. Gamma frequencies of 53 compounds: MARE 4.6% vs experiment. Petretto 2018

The thermodynamic scale of metastability

Materials Project energies for 29,902 ICSD phases, retrieved with pymatgen through the Materials API: 50.5% metastable, median 15 meV/atom above ground state, 90th percentile 67 meV/atom. Sun 2016

Amorphous limit of metastability

Melt-quench AIMD workflows on pymatgen, custodian, FireWorks and atomate set an upper energy bound for synthesizable polymorphs and classified more than 700 polymorphs in 41 systems. Aykol 2018

How it is used

  1. Read structures

    Structure from a CIF or POSCAR via the io package, or Materials Project data via matproj.

  2. Transform

    Substitute, order or make supercells with the transformations package.

  3. Write inputs and run

    vaspio_set writes VASP inputs with Materials Project parameters. Run the code.

  4. Assimilate

    borg collects runs into ComputedEntry objects, compatibility corrects the energies.

  5. Analyse

    phasediagram hulls, reaction_calculator energies, band structure and DOS plots.