This notebook demostrates the core functionality of pymatgen, including the core objects representing Elements, Species, Lattices, and Structures.

Written using:

By convention, we import pymatgen as mg.

Basic Element, Specie and Composition objects

Pymatgen contains a set of core classes to represent an Element, Specie and Composition. These objects contains useful properties such as atomic mass, ionic radii, etc. These core classes are loaded by default with pymatgen. An Element can be created as follows:

You can see that units are printed for atomic masses and ionic radii. Pymatgen comes with a complete system of managing units in pymatgen.core.unit. A Unit is a subclass of float that attaches units and handles conversions. For example,

Please refer to the Units example for more information on units. Species are like Elements, except they have an explicit oxidation state. They can be used wherever Element is used for the most part.

A Composition is essentially an immutable mapping of Elements/Species with amounts, and useful properties like molecular weight, get_atomic_fraction, etc. Note that you can conveniently either use an Element/Specie object or a string as keys (this is a feature).

Lattice & Structure objects

A Lattice represents a Bravais lattice. Convenience static functions are provided for the creation of common lattice types from a minimum number of arguments.

A Structure object represents a crystal structure (lattice + basis). A Structure is essentially a list of PeriodicSites with the same Lattice. Let us now create a CsCl structure.

The Structure object contains many useful manipulation functions. Since Structure is essentially a list, it contains a simple pythonic API for manipulation its sites. Some examples are given below. Please note that there is an immutable version of Structure known as IStructure, for the use case where you really need to enforce that the structure does not change. Conversion between these forms of Structure can be performed using from_sites().

Basic analyses

Pymatgen provides many analyses functions for Structures. Some common ones are given below.

We also have an extremely powerful structure matching tool.


Pymatgen also provides IO support for various file formats in the package. A convenient set of read_structure and write_structure functions are also provided which auto-detects several well-known formats.

The vaspio_set module provides a means o obtain a complete set of VASP input files for performing calculations. Several useful presets based on the parameters used in the Materials Project are provided.

This concludes this pymatgen tutorial. Please explore the usage pages on for more information.