or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-materials.mdelectronic-structure.mdindex.mdio-formats.mdphase-diagrams.mdstructure-analysis.mdsymmetry.mdtransformations.md
tile.json

tessl/pypi-pymatgen

Comprehensive materials science analysis library for crystal structures, molecules, and materials data with extensive computational chemistry integration.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pymatgen@2025.6.x

To install, run

npx @tessl/cli install tessl/pypi-pymatgen@2025.6.0

index.mddocs/

Pymatgen

A comprehensive Python library for materials analysis that provides robust core object representations for structures and molecules with extensive support for electronic structure codes. Pymatgen is the foundation of the Materials Project and offers a complete materials science analysis ecosystem including structure manipulation, property analysis, phase diagrams, and I/O for major computational chemistry codes.

Package Information

  • Package Name: pymatgen
  • Language: Python
  • Installation: pip install pymatgen
  • Version: 2025.6.14+
  • License: MIT

Core Imports

Standard imports for basic functionality:

from pymatgen.core import Structure, Composition, Lattice, Element, Species
from pymatgen.core.sites import Site, PeriodicSite
from pymatgen.core.units import FloatWithUnit, ArrayWithUnit

Common imports for file I/O:

from pymatgen.io.vasp import Poscar, Vasprun, Incar, Kpoints
from pymatgen.io.cif import CifParser, CifWriter
from pymatgen.io.xyz import XYZ

Analysis and processing imports:

from pymatgen.analysis.structure_matcher import StructureMatcher
from pymatgen.analysis.local_env import VoronoiNN
from pymatgen.analysis.phase_diagram import PhaseDiagram
from pymatgen.transformations.standard_transformations import SupercellTransformation

Basic Usage

import pymatgen as mg
from pymatgen.core import Structure, Composition, Lattice, Element
from pymatgen.io.vasp import Poscar

# Create a simple cubic lattice
lattice = Lattice.cubic(4.0)
species = ["Li", "Cl"]
coords = [[0, 0, 0], [0.5, 0.5, 0.5]]
structure = Structure(lattice, species, coords)

# Load structure from file
structure = Structure.from_file("POSCAR")

# Basic structure operations
primitive = structure.get_primitive_structure()
supercell = structure * (2, 2, 2)
composition = structure.composition

# Structure analysis
neighbors = structure.get_neighbors(structure[0], 3.0)
volume = structure.volume
density = structure.density

# Composition analysis
comp = Composition("Fe2O3")
formula = comp.formula
elements = comp.elements
weight = comp.weight

# File I/O
poscar = Poscar(structure)
poscar.write_file("POSCAR_output")

# Parse computational results
vasprun = Vasprun("vasprun.xml")
final_structure = vasprun.final_structure
band_structure = vasprun.get_band_structure()

Architecture

Pymatgen's architecture is built around several fundamental concepts that enable comprehensive materials analysis:

  • Structure & Composition: Core representations for crystal structures (Structure, IStructure) and chemical compositions (Composition) with rich manipulation and query capabilities
  • Lattice: Crystal lattice representation with vector operations, reciprocal lattice calculations, and crystallographic transformations
  • Sites & Species: Atomic sites (Site, PeriodicSite) and chemical species (Element, Species, Ion) with oxidation states and properties
  • Units & Tensors: Physical unit handling (FloatWithUnit, ArrayWithUnit) and tensor operations for materials properties
  • Entry System: Unified representation of computed and experimental data (ComputedEntry) with energy corrections and compatibility schemes
  • Analysis Framework: Modular analysis tools for structure comparison, local environments, phase diagrams, and electronic properties
  • Transformation System: Systematic structure modifications through composable transformations with full provenance tracking
  • I/O Ecosystem: Comprehensive file format support for major electronic structure codes (VASP, Quantum ESPRESSO, Gaussian, etc.)

This design provides a unified interface for materials science workflows while maintaining flexibility for specialized applications and integration with other computational tools.

Capabilities

Core Materials Representation

Fundamental classes for representing crystal structures, molecules, compositions, and lattices with rich manipulation capabilities and property calculations.

class Structure:
    def __init__(self, lattice, species, coords, **kwargs): ...
    def get_primitive_structure(self): ...
    def get_neighbors(self, site, r, include_index=False): ...
    @property
    def volume(self): ...
    @property
    def density(self): ...

class Composition:
    def __init__(self, data): ...
    @property
    def formula(self): ...
    @property
    def elements(self): ...
    def get_atomic_fraction(self, el): ...

class Lattice:
    def __init__(self, matrix): ...
    def get_points_in_sphere(self, frac_points, center, r): ...
    @property
    def reciprocal_lattice(self): ...

Core Materials Representation

Structure Analysis & Manipulation

Comprehensive tools for structure comparison, local environment analysis, Voronoi tessellation, bond analysis, and advanced structural characterization methods.

class StructureMatcher:
    def __init__(self, **kwargs): ...
    def fit(self, struct1, struct2): ...
    def get_rms_dist(self, struct1, struct2): ...

class VoronoiNN:
    def get_nn_info(self, structure, n): ...
    def get_cn(self, structure, n): ...

def get_bond_length(sp1, sp2): ...
def obtain_all_bond_lengths(structure): ...

Structure Analysis & Manipulation

Electronic Structure Analysis

Band structure analysis, density of states processing, transport properties calculation via BoltzTraP, and COHP analysis for chemical bonding insights.

class BandStructure:
    def __init__(self, kpoints, eigenvals, lattice, **kwargs): ...
    def get_band_gap(self): ...
    def get_cbm(self): ...
    def get_vbm(self): ...

class Dos:
    def __init__(self, efermi, energies, densities): ...
    def get_interpolated_gap(self): ...
    def get_cbm_vbm(self): ...

class BSPlotter:
    def get_plot(self, **kwargs): ...
    def show(self, **kwargs): ...

Electronic Structure Analysis

File I/O & Format Support

Extensive I/O support for electronic structure codes (VASP, Quantum ESPRESSO, Gaussian, etc.), structure formats (CIF, XYZ, POSCAR), and materials databases.

class Poscar:
    def __init__(self, structure, **kwargs): ...
    def write_file(self, filename): ...
    @classmethod
    def from_file(cls, filename): ...

class Vasprun:
    def __init__(self, filename, **kwargs): ...
    def get_band_structure(self): ...
    def get_dos(self): ...
    @property
    def final_structure(self): ...

class CifParser:
    def __init__(self, filename): ...
    def get_structures(self): ...

File I/O & Format Support

Phase Diagrams & Thermodynamics

Phase diagram construction and analysis, Pourbaix diagrams, chemical potential diagrams, and thermodynamic property calculations.

class PhaseDiagram:
    def __init__(self, entries, elements=None): ...
    def get_hull_energy(self, composition): ...
    def get_equilibrium_reaction_energy(self, entry): ...

class PourbaixDiagram:
    def __init__(self, entries, **kwargs): ...
    def get_stable_entry(self, pH, V): ...

class PDPlotter:
    def get_plot(self, **kwargs): ...
    def show(self): ...

Phase Diagrams & Thermodynamics

Crystallographic Transformations

Systematic structure modifications including supercells, substitutions, defect creation, surface generation, and magnetic ordering enumeration.

class SupercellTransformation:
    def __init__(self, scaling_matrix): ...
    def apply_transformation(self, structure): ...

class SubstitutionTransformation:
    def __init__(self, species_map): ...
    def apply_transformation(self, structure): ...

class SlabTransformation:
    def __init__(self, miller_index, min_slab_size, **kwargs): ...
    def apply_transformation(self, structure): ...

Crystallographic Transformations

Symmetry & Crystallography

Space group analysis, point group operations, crystallographic symmetry detection, and high-symmetry k-point path generation for band structures.

class SpacegroupAnalyzer:
    def __init__(self, structure, **kwargs): ...
    def get_space_group_number(self): ...
    def get_point_group_symbol(self): ...
    def get_primitive_standard_structure(self): ...

class HighSymmKpath:
    def __init__(self, structure, **kwargs): ...
    @property
    def kpath(self): ...
    @property
    def kpoints(self): ...

Symmetry & Crystallography