pymatgen

Pymatgen - Materials Genomics Toolkit

Capabilities Overview

Pymatgen is a comprehensive materials science Python toolkit for creating, analyzing, and manipulating crystal structures and molecules, calculating phase diagrams and thermodynamic properties, analyzing electronic structure (band structures, density of states), and accessing the Materials Project database.

Use Cases

1. Crystal Structure and Molecule Manipulation

Read and write 100+ structure file formats (CIF, POSCAR, XYZ, etc.), analyze space group symmetry, compute coordination environments, generate supercells and primitive cells, perform element substitutions and structure transformations.

2. Electronic Structure Analysis and Visualization

Extract band structures and density of states from outputs of computational codes like VASP and Gaussian, compute band gaps, identify metals/insulators/semiconductors, and produce publication-quality visualizations.

3. Phase Diagram and Thermodynamic Calculations

Construct binary, ternary, and multicomponent phase diagrams, compute the energy above the convex hull, analyze thermodynamic stability, predict decomposition products, and assess metastable materials.

4. Materials Project Database Access

Access the Materials Project computational materials database via API to search material properties and retrieve crystal structures, band structures, phase transition temperatures, etc., supporting high-throughput materials screening.

5. Computational Workflow Automation

Generate standard input files for VASP, Quantum ESPRESSO, Gaussian, etc., set up common workflows like relaxations, static calculations, and band structure runs, and track structure transformation history.

Core Features

1. Structure File Format Conversion

Supports automatic detection and conversion of 100+ crystal structure and molecular file formats, including CIF, POSCAR, VASP, XYZ, Gaussian, Quantum ESPRESSO, and other major computational formats.

2. Symmetry and Coordination Environment Analysis

Use spglib for space group identification, obtain conventional and primitive cells, analyze coordination environments (CrystalNN, Voronoi, etc.), and compute bond lengths, bond angles and other structural parameters.

3. Surface and Interface Analysis

Generate surface slabs, calculate surface energies, construct Wulff shapes, find adsorption sites, analyze surface reconstructions, supporting surface science and catalysis research.

4. Phase Diagram Constructor

Build phase diagrams from Materials Project or custom data, compute convex hulls, analyze stability, predict decomposition pathways, supporting thermodynamic studies and phase diagram calculations.

5. Band Structure and Density of States Analysis

Read outputs like VASP vasprun.xml to extract band structures and density of states, compute band gaps (direct/indirect), analyze orbital projections, and generate customizable plots.

Frequently Asked Questions

What is pymatgen used for?

Pymatgen (Python Materials Genomics) is a comprehensive library for materials analysis used to create, analyze, and manipulate crystal structures and molecules. It supports file format conversion, symmetry analysis, phase diagram construction, electronic structure analysis, surface generation, and provides programmatic access to the Materials Project database.

How do I convert CIF to POSCAR in pymatgen?

Use automatic format detection with Structure.from_file() and to() methods:

from pymatgen.core import Structure
struct = Structure.from_file("structure.cif")
struct.to(filename="POSCAR")

Or use the bundled script: python scripts/structure_converter.py structure.cif POSCAR

How to connect to Materials Project API?

Get API key from https://next-gen-materialsproject.org/

Set environment variable: export MP_API_KEY="your_key"

Use MPRester context manager:

from mp_api.client import MPRester
with MPRester() as mpr:
    struct = mpr.get_structure_by_material_id("mp-149")

What file formats does pymatgen support?

Pymatgen supports 100+ file formats including CIF, POSCAR/CONTCAR (VASP), XYZ, CSSR, JSON, pymatgen's JSON serialization, Gaussian input/output, Quantum ESPRESSO PW input, and many more. Use Structure.from_file() for automatic format detection.

How to analyze crystal symmetry with pymatgen?

from pymatgen.symmetry.analyzer import SpacegroupAnalyzer
sga = SpacegroupAnalyzer(struct)
print(f"Space group: {sga.get_space_group_symbol()}")
print(f"Number: {sga.get_space_group_number()}")

Is pymatgen free to use?

Yes, pymatgen is free and open-source under the MIT license. The Materials Project API is also free for academic use with registration. Commercial use requires separate licensing.

How to calculate band structure from VASP output?

from pymatgen.io.vasp import Vasprun
from pymatgen.electronic_structure.plotter import BSPlotter
vasprun = Vasprun("vasprun.xml")
bs = vasprun.get_band_structure()
print(f"Band gap: {bs.get_band_gap()['energy']:.3f} eV")
plotter = BSPlotter(bs)
plotter.save_plot("band_structure.png")

How to generate slab surfaces?

from pymatgen.core.surface import SlabGenerator
slabgen = SlabGenerator(struct, miller_index=(1,1,1),
                        min_slab_size=10.0, min_vacuum_size=10.0)
slabs = slabgen.get_slabs()

Technical Requirements

Python 3.10+

pymatgen >= 2023.x

mp-api (for Materials Project access)

Optional: spglib (symmetry), matplotlib (plotting), scipy (analysis)

License

MIT License - Free for academic and commercial use