Pymatgen

Pymatgen is a community skill for computational materials science using the pymatgen Python library, covering crystal structure manipulation, phase diagram construction, electronic structure analysis, materials database queries, and symmetry operations for materials research.

What Is This?

Overview

Pymatgen provides tools for analyzing and manipulating crystal structures and materials properties through a comprehensive Python interface. It covers crystal structure manipulation that creates, transforms, and visualizes periodic atomic structures with lattice parameters and site coordinates, phase diagram construction that computes thermodynamic stability from formation energies across composition spaces, electronic structure analysis that processes band structures and density of states from first-principles calculations, materials database queries that access the Materials Project API for computed properties of known compounds, and symmetry operations that identify space groups and equivalent atomic sites. The skill enables researchers to perform computational materials analysis.

Who Should Use This

This skill serves materials scientists running computational screening studies, solid-state chemists analyzing crystal structures and phase stability, and researchers querying materials databases for property-driven materials discovery.

Why Use It?

Problems It Solves

Crystal structure file formats like CIF, POSCAR, and XYZ use different conventions requiring format-specific parsing code. Constructing phase diagrams from formation energy data requires convex hull computation across multi-component composition spaces. Analyzing electronic band structures from DFT outputs needs specialized parsing for each calculation code. Querying materials databases manually for hundreds of compounds is impractical for screening studies.

Core Highlights

Structure builder creates and transforms crystal structures with lattice and site data. Phase analyzer constructs thermodynamic phase diagrams from formation energies. Band processor parses electronic structure outputs from DFT codes. Database connector queries Materials Project for computed materials properties.

How to Use It?

Basic Usage

from pymatgen.core import (
  Structure, Lattice)
from pymatgen.symmetry\
  .analyzer import (
    SpacegroupAnalyzer)

lattice = Lattice.cubic(
  5.43)
si = Structure(
  lattice,
  ['Si', 'Si'],
  [[0, 0, 0],
   [0.25, 0.25, 0.25]])

print(
  f'Formula: '
  f'{si.formula}')
print(
  f'Volume: '
  f'{si.volume:.2f} A^3')
print(
  f'Density: '
  f'{si.density:.3f} '
  f'g/cm^3')

analyzer = (
  SpacegroupAnalyzer(si))
print(
  f'Space group: '
  f'{analyzer'
  f'.get_space_group_symbol()}')
print(
  f'Point group: '
  f'{analyzer'
  f'.get_point_group_symbol()}')

struct = Structure\
  .from_file(
    'POSCAR')
struct.to(
  filename='out.cif')

Real-World Examples

from pymatgen.ext.matproj\
  import MPRester
from pymatgen.analysis\
  .phase_diagram import (
    PhaseDiagram,
    PDPlotter)

class MaterialsScreener:
  def __init__(
    self, api_key: str
  ):
    self.mpr = MPRester(
      api_key)

  def get_stable(
    self,
    elements:
      list[str]
  ) -> list[dict]:
    entries = (
      self.mpr
        .get_entries_in_chemsys(
          elements))
    pd = PhaseDiagram(
      entries)
    stable = [
      {'formula': str(
        e.composition
          .reduced_formula),
       'energy':
        pd.get_form_energy_per_atom(
          e)}
      for e in
      pd.stable_entries]
    return sorted(
      stable,
      key=lambda x:
        x['energy'])

  def band_gap(
    self,
    formula: str
  ) -> float:
    results = (
      self.mpr.query(
        criteria={
          'pretty_formula':
            formula},
        properties=[
          'band_gap']))
    if results:
      return results[
        0]['band_gap']
    return -1.0

Advanced Tips

Use the structure matcher to compare crystal structures accounting for lattice distortions and site permutations when screening for duplicates. Build phase diagrams incrementally by adding computed entries to identify which compositions are thermodynamically stable. Cache Materials Project query results locally since repeated API calls for the same data consume quota unnecessarily.

When to Use It?

Use Cases

Screen a chemical system for thermodynamically stable phases by constructing phase diagrams from computed formation energies. Query the Materials Project database for band gaps and formation energies across hundreds of compounds for a screening study. Convert crystal structures between CIF, POSCAR, and other file formats for different simulation codes.

Related Topics

Pymatgen, materials science, crystal structures, phase diagrams, Materials Project, DFT, and computational chemistry.

Important Notes

Requirements

Pymatgen Python package with its scientific computing dependencies. Materials Project API key for database queries and property retrieval. NumPy and matplotlib for numerical operations and structure visualization.

Usage Recommendations

Do: validate crystal structures after transformations by checking bond lengths and coordination numbers. Use the symmetry analyzer to reduce redundant atomic sites before expensive calculations. Cache Materials Project queries locally to reduce API usage.

Don't: modify structure objects in place without copying since operations mutate the original. Trust database formation energies without checking the calculation methodology and convergence settings. Compare structures from different databases without accounting for different computational parameters.

Limitations

Materials Project API access has rate limits and query quotas that restrict bulk data retrieval. Phase diagram accuracy depends on the completeness of formation energy data for all competing phases. Some crystal structure transformations may produce physically unrealistic geometries requiring validation.