Code

pymatgen

Python Materials Genomics, the structure and analysis library behind the Materials Project.

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.

What pymatgen is, how it works and what it is used for, from the papers listed as sources. Every number links to its paper.Poster pageDownload the poster (PNG, 1920 x 1080)

What pymatgen is

pymatgen is the Python library behind the Materials Project. It handles structures and symmetry, reads and writes the input and output formats of many codes, and provides analysis for phase diagrams, electronic structure and diffraction. On the map it serves the structural and derived quantities it computes.

WebsiteOn the mapAll codesLicense: MIT

In more detail

Objects, tests and serialization

pymatgen is object oriented and test driven, and every non-trivial class and method has a unit test. The core package defines Element, Lattice, Site, PeriodicSite, Structure, Molecule and Composition. The entries package wraps a composition and an energy into a ComputedEntry that is independent of whether the energy came from VASP, ABINIT or another code, and ExpEntry holds experimental thermochemistry. Most objects implement to_dict and from_dict, so they round-trip through JSON files or a MongoDB database such as the one behind the Materials Project (Ong 2013).

Thermodynamic analysis

entries.compatibility adjusts GGA+U energies with experimental binary formation enthalpies so they mix with GGA energies, and corrects the overbinding of O2 and N2. MaterialsProjectCompatibility and MITCompatibility carry the two parameter sets. analysis.reaction_calculator balances reactions and computes their energies. The phasediagram package builds compositional and grand canonical hulls. In the Li4SnS4 example one VASP ground-state run plus Materials Project entries gave the Li-Sn-S diagram and a chemical potential map with stability only over a narrow range of Li chemical potential, where a standalone study needs more than 30 structures (Ong 2013).

Interfaces and use in other studies

The io package supports CIF via PyCifRW, molecular formats via OpenBabel, VASP input and output via vaspio with Materials Project parameter sets in vaspio_set, limited Gaussian input, and an aseio adaptor to ASE Atoms. The matproj package talks to the Materials API, a RESTful interface returning JSON for each material (Ong 2013). The DFPT phonon database of Petretto 2018 used pymatgen with AbiPy to generate ABINIT inputs and analyze the results under FireWorks. Sun 2016 retrieved its 29,902 phases from the Materials Project with pymatgen, and Aykol 2018 built its melt-quench workflow on pymatgen, custodian, FireWorks and atomate.

What it computes on the map

22 quantities, drawn by tier with the data flow between them. Dashed boxes are intermediate quantities. Select one for its formula and the other codes that compute it.

SourcesHarmonicMolecular dynamicsGround stateMechanicsStabilityDiffusionBorn charges: BornChargesBorn chargesZ*Dielectric tensor: DielectricTensorDielectric tensorε∞Atomic structure: StructureAtomic structure𝒮Force constants (2): ForceConstants[order=2]Force constants (2)Φ(2)Phonon frequencies: FrequencyPhonon frequenciesωPhonon density of states: PhononDOSPhonon density of statesg(ω)Mean squared displacement: MeanSquaredDisplacementMean squared displacement⟨u2⟩Magnetic moment: MagneticMomentMagnetic momentmspinTotal energy: TotalEnergyTotal energyEtotStress: StressStressσElastic constants: ElasticConstantsElastic constantsCBulk modulus: BulkModulusBulk modulusKShear modulus: ShearModulusShear modulusGPoisson ratio: PoissonRatioPoisson ratioνYoung's modulus: YoungsModulusYoung's modulusEYFormation energy: FormationEnergyFormation energyΔHfGrain boundary energy: GrainBoundaryEnergyGrain boundary energyGrainBoundaryEnergySurface energy: SurfaceEnergySurface energyγsurfVoltage: VoltageVoltageVavgEnergy above hull: EnergyAboveHullEnergy above hullEhullDiffusivity: DiffusivityDiffusivityDActivation energy: ActivationEnergyActivation energyEa
Open the full mapShare this submap
Embed this submap
<iframe src="https://openmaterials.ai/m/c56731602651/2c800040001001b0ede4000018?embed=1" title="pymatgen on the OpenMaterials map" width="100%" height="480" loading="lazy" style="border:1px solid #EBEBEB;border-radius:6px"></iframe>

Each quantity with the interface the representation records.

  • ActivationEnergypymatgen.analysis.diffusion.analyzer fit_arrhenius / get_arrhenius_plot over D(T), eVev
  • BornChargespymatgen.io.vasp.outputs.Outcar.born (shape (n_atoms, 3, 3)), units of edimensionless
  • BulkModuluspymatgen ElasticTensor.k_vrh (= 0.5*(k_voigt + k_reuss)), eV/A^3eV_per_A3
  • DielectricTensorpymatgen.io.vasp.outputs.Outcar.dielectric_tensor (3x3), dimensionlessdimensionless
  • Diffusivitypymatgen.analysis.diffusion.analyzer.DiffusionAnalyzer.diffusivity, cm^2/s (add-on distribution)cm^2/s
  • ElasticConstantspymatgen.analysis.elasticity.elastic.ElasticTensor (.voigt 6x6), eV/A^3eV_per_A3
  • EnergyAboveHullpymatgen PhaseDiagram.get_e_above_hull / get_decomp_and_e_above_hull, eV/atom (skills report meV/atom)ev_per_atom
  • ForceConstants[order=2]MP field ph_force_constants via mpr.materials.phonon.get_data_by_id; pymatgen MontyEncoder serialization, eV/A^2eV_per_A2
  • FormationEnergypymatgen PhaseDiagram.get_form_energy_per_atom / ComputedEntry.formation_energy_per_atom, eV/atomev_per_atom
  • Frequencypymatgen.phonon.bandstructure.PhononBandStructureSymmLine (mp_api retrieval), linear THzlinear_THz
  • GrainBoundaryEnergypymatgen.analysis.gb.grain.GrainBoundaryGenerator CSL slabs; in-skill gamma_GB = (E_GB - N E_bulk)/(2A), J/m^2J_per_m2
  • MagneticMomentsite moments parsed from calculator output; pymatgen.analysis.magnetism Ordering / CollinearMagneticStructureAnalyzer, mu_Bmu_B
  • MeanSquaredDisplacementpymatgen DiffusionAnalyzer.msd (A^2) against .dt (fs; skill divides by 1000 for ps)A^2
  • PhononDOSpymatgen.phonon.dos.PhononDos (mp_api retrieval), densities against a linear-THz axis
  • PoissonRatiopymatgen ElasticTensor.homogeneous_poisson, dimensionlessdimensionless
  • ShearModuluspymatgen ElasticTensor.g_vrh (= 0.5*(g_voigt + g_reuss)), eV/A^3eV_per_A3
  • Stressstresses consumed by ElasticTensor.from_independent_strains (ASE/MLIP Voigt, eV/A^3)eV_per_A3
  • Structurepymatgen.core.Structure (from_file / from_str; AseAtomsAdaptor bridge)
  • SurfaceEnergypymatgen SlabGenerator slabs; in-skill gamma = (E_slab - N E_bulk)/(2A), J/m^2; WulffShape aggregationJ_per_m2
  • TotalEnergypymatgen.entries.computed_entries.ComputedEntry.energy (per cell), eVev
  • Voltagein-skill V = -(E_full - E_empty - n mu_metal)/n over pymatgen Structure.remove_species cells (monovalent working ion), voltsvolt
  • YoungsModuluspymatgen ElasticTensor.y_mod (= 9.0e9 * k_vrh*g_vrh/(3k+g)), SI PaPa

References

The code

The papers that describe the code; cite them when you use it.

  1. S. P. Ong, W. D. Richards, A. Jain et al., Python Materials Genomics (pymatgen): A robust, open-source python library for materials analysis, Computational Materials Science, 2013. doi.org/10.1016/j.commatsci.2012.10.028

Applications

Highly cited studies that cite the code, with a few picked by hand.

  1. W. Sun, S. T. Dacek, S. P. Ong et al., The thermodynamic scale of inorganic crystalline metastability, Science Advances, 2016. doi.org/10.1126/sciadv.1600225
  2. G. Petretto, S. Dwaraknath, H. P.C. Miranda et al., High-throughput density-functional perturbation theory phonons for inorganic materials, Scientific Data, 2018. doi.org/10.1038/sdata.2018.65
  3. M. Aykol, S. S. Dwaraknath, W. Sun et al., Thermodynamic limit for synthesis of metastable inorganic materials, Science Advances, 2018. doi.org/10.1126/sciadv.aaq0148

How to cite

S. P. Ong, W. D. Richards, A. Jain, et al., Python Materials Genomics (pymatgen): A robust, open-source python library for materials analysis, Comput. Mater. Sci. 68, 314 (2013)

doi.org/10.1016/j.commatsci.2012.10.028