0
# Pymatgen
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: pymatgen
7
- **Language**: Python
8
- **Installation**: `pip install pymatgen`
9
- **Version**: 2025.6.14+
10
- **License**: MIT
11

12
## Core Imports
13

14
Standard imports for basic functionality:
15

16
```python
17
from pymatgen.core import Structure, Composition, Lattice, Element, Species
18
from pymatgen.core.sites import Site, PeriodicSite
19
from pymatgen.core.units import FloatWithUnit, ArrayWithUnit
20
```
21

22
Common imports for file I/O:
23

24
```python
25
from pymatgen.io.vasp import Poscar, Vasprun, Incar, Kpoints
26
from pymatgen.io.cif import CifParser, CifWriter
27
from pymatgen.io.xyz import XYZ
28
```
29

30
Analysis and processing imports:
31

32
```python
33
from pymatgen.analysis.structure_matcher import StructureMatcher
34
from pymatgen.analysis.local_env import VoronoiNN
35
from pymatgen.analysis.phase_diagram import PhaseDiagram
36
from pymatgen.transformations.standard_transformations import SupercellTransformation
37
```
38

39
## Basic Usage
40

41
```python
42
import pymatgen as mg
43
from pymatgen.core import Structure, Composition, Lattice, Element
44
from pymatgen.io.vasp import Poscar
45

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

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

55
# Basic structure operations
56
primitive = structure.get_primitive_structure()
57
supercell = structure * (2, 2, 2)
58
composition = structure.composition
59

60
# Structure analysis
61
neighbors = structure.get_neighbors(structure[0], 3.0)
62
volume = structure.volume
63
density = structure.density
64

65
# Composition analysis
66
comp = Composition("Fe2O3")
67
formula = comp.formula
68
elements = comp.elements
69
weight = comp.weight
70

71
# File I/O
72
poscar = Poscar(structure)
73
poscar.write_file("POSCAR_output")
74

75
# Parse computational results
76
vasprun = Vasprun("vasprun.xml")
77
final_structure = vasprun.final_structure
78
band_structure = vasprun.get_band_structure()
79
```
80

81
## Architecture
82

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

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

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

96
## Capabilities
97

98
### Core Materials Representation
99

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

102
```python { .api }
103
class Structure:
104
    def __init__(self, lattice, species, coords, **kwargs): ...
105
    def get_primitive_structure(self): ...
106
    def get_neighbors(self, site, r, include_index=False): ...
107
    @property
108
    def volume(self): ...
109
    @property
110
    def density(self): ...
111

112
class Composition:
113
    def __init__(self, data): ...
114
    @property
115
    def formula(self): ...
116
    @property
117
    def elements(self): ...
118
    def get_atomic_fraction(self, el): ...
119

120
class Lattice:
121
    def __init__(self, matrix): ...
122
    def get_points_in_sphere(self, frac_points, center, r): ...
123
    @property
124
    def reciprocal_lattice(self): ...
125
```
126

127
[Core Materials Representation](./core-materials.md)
128

129
### Structure Analysis & Manipulation
130

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

133
```python { .api }
134
class StructureMatcher:
135
    def __init__(self, **kwargs): ...
136
    def fit(self, struct1, struct2): ...
137
    def get_rms_dist(self, struct1, struct2): ...
138

139
class VoronoiNN:
140
    def get_nn_info(self, structure, n): ...
141
    def get_cn(self, structure, n): ...
142

143
def get_bond_length(sp1, sp2): ...
144
def obtain_all_bond_lengths(structure): ...
145
```
146

147
[Structure Analysis & Manipulation](./structure-analysis.md)
148

149
### Electronic Structure Analysis
150

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

153
```python { .api }
154
class BandStructure:
155
    def __init__(self, kpoints, eigenvals, lattice, **kwargs): ...
156
    def get_band_gap(self): ...
157
    def get_cbm(self): ...
158
    def get_vbm(self): ...
159

160
class Dos:
161
    def __init__(self, efermi, energies, densities): ...
162
    def get_interpolated_gap(self): ...
163
    def get_cbm_vbm(self): ...
164

165
class BSPlotter:
166
    def get_plot(self, **kwargs): ...
167
    def show(self, **kwargs): ...
168
```
169

170
[Electronic Structure Analysis](./electronic-structure.md)
171

172
### File I/O & Format Support
173

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

176
```python { .api }
177
class Poscar:
178
    def __init__(self, structure, **kwargs): ...
179
    def write_file(self, filename): ...
180
    @classmethod
181
    def from_file(cls, filename): ...
182

183
class Vasprun:
184
    def __init__(self, filename, **kwargs): ...
185
    def get_band_structure(self): ...
186
    def get_dos(self): ...
187
    @property
188
    def final_structure(self): ...
189

190
class CifParser:
191
    def __init__(self, filename): ...
192
    def get_structures(self): ...
193
```
194

195
[File I/O & Format Support](./io-formats.md)
196

197
### Phase Diagrams & Thermodynamics
198

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

201
```python { .api }
202
class PhaseDiagram:
203
    def __init__(self, entries, elements=None): ...
204
    def get_hull_energy(self, composition): ...
205
    def get_equilibrium_reaction_energy(self, entry): ...
206

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

211
class PDPlotter:
212
    def get_plot(self, **kwargs): ...
213
    def show(self): ...
214
```
215

216
[Phase Diagrams & Thermodynamics](./phase-diagrams.md)
217

218
### Crystallographic Transformations
219

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

222
```python { .api }
223
class SupercellTransformation:
224
    def __init__(self, scaling_matrix): ...
225
    def apply_transformation(self, structure): ...
226

227
class SubstitutionTransformation:
228
    def __init__(self, species_map): ...
229
    def apply_transformation(self, structure): ...
230

231
class SlabTransformation:
232
    def __init__(self, miller_index, min_slab_size, **kwargs): ...
233
    def apply_transformation(self, structure): ...
234
```
235

236
[Crystallographic Transformations](./transformations.md)
237

238
### Symmetry & Crystallography
239

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

242
```python { .api }
243
class SpacegroupAnalyzer:
244
    def __init__(self, structure, **kwargs): ...
245
    def get_space_group_number(self): ...
246
    def get_point_group_symbol(self): ...
247
    def get_primitive_standard_structure(self): ...
248

249
class HighSymmKpath:
250
    def __init__(self, structure, **kwargs): ...
251
    @property
252
    def kpath(self): ...
253
    @property
254
    def kpoints(self): ...
255
```
256

257
[Symmetry & Crystallography](./symmetry.md)