0
# Phonopy
1

2
A comprehensive Python library for phonon calculations that enables lattice dynamics simulations and vibrational property analysis of crystalline materials. Phonopy provides computational tools for phonon band structures, density of states, thermal properties, and advanced analyses including Grüneisen parameters and quasi-harmonic approximation calculations.
3

4
## Package Information
5

6
- **Package Name**: phonopy
7
- **Language**: Python
8
- **Installation**: `pip install phonopy`
9
- **Version Access**: `from phonopy import __version__`
10

11
## Core Imports
12

13
```python
14
import phonopy
15
from phonopy import Phonopy, PhonopyGruneisen, PhonopyQHA, load, __version__
16
```
17

18
For specific functionality:
19

20
```python
21
from phonopy.structure.atoms import PhonopyAtoms
22
from phonopy.interface.vasp import read_vasp
23
from phonopy.interface.phonopy_yaml import PhonopyYaml
24
```
25

26
## Basic Usage
27

28
```python
29
import numpy as np
30
from phonopy import Phonopy
31
from phonopy.structure.atoms import PhonopyAtoms
32

33
# Create unit cell structure
34
lattice = [[4.0, 0.0, 0.0],
35
           [0.0, 4.0, 0.0], 
36
           [0.0, 0.0, 4.0]]
37
positions = [[0.0, 0.0, 0.0],
38
             [0.5, 0.5, 0.5]]
39
numbers = [1, 1]
40

41
unitcell = PhonopyAtoms(cell=lattice, 
42
                        scaled_positions=positions,
43
                        numbers=numbers)
44

45
# Create Phonopy instance with 2x2x2 supercell
46
supercell_matrix = [[2, 0, 0], [0, 2, 0], [0, 0, 2]]
47
ph = Phonopy(unitcell, supercell_matrix)
48

49
# Generate displacements for force calculations
50
ph.generate_displacements(distance=0.01)
51
print(f"Number of displacements: {len(ph.displacements)}")
52

53
# Set force constants (after obtaining forces from ab initio calculations)
54
# ph.forces = forces_from_calculations
55
# ph.produce_force_constants()
56

57
# Calculate thermal properties
58
temperatures = np.arange(0, 1000, 10)
59
ph.run_thermal_properties(temperatures=temperatures)
60
thermal_props = ph.get_thermal_properties_dict()
61
```
62

63
## Architecture
64

65
Phonopy is built around a multi-layered architecture optimized for crystalline material analysis:
66

67
- **Core Engine**: The `Phonopy` class orchestrates all phonon calculations with 100+ methods
68
- **Structure Management**: `PhonopyAtoms`, `Supercell`, `Primitive` classes handle crystal structures 
69
- **Calculator Interfaces**: Support for 10+ ab initio codes (VASP, Quantum ESPRESSO, ABINIT, etc.)
70
- **Analysis Modules**: Specialized classes for band structures, DOS, thermal properties, group velocities
71
- **Advanced Features**: Grüneisen parameters, quasi-harmonic approximation, machine learning potentials
72
- **File I/O**: Comprehensive support for YAML, HDF5, and calculator-specific file formats
73

74
This modular design enables phonopy to serve as the foundation for phonon analysis workflows across the materials science community.
75

76
## Capabilities
77

78
### Core Phonopy API
79

80
Main Phonopy class providing comprehensive phonon calculation capabilities including displacement generation, force constant calculation, band structure analysis, density of states, and thermal property calculations.
81

82
```python { .api }
83
class Phonopy:
84
    def __init__(
85
        self,
86
        unitcell: PhonopyAtoms,
87
        supercell_matrix: ArrayLike = None,
88
        primitive_matrix: ArrayLike | str = None,
89
        nac_params: dict = None,
90
        factor: float = None,
91
        frequency_scale_factor: float = None,
92
        dynamical_matrix_decimals: int = None,
93
        force_constants_decimals: int = None,
94
        group_velocity_delta_q: float = None,
95
        symprec: float = 1e-5,
96
        is_symmetry: bool = True,
97
        store_dense_svecs: bool = True,
98
        use_SNF_supercell: bool = False,
99
        hermitianize_dynamical_matrix: bool = True,
100
        calculator: str = None,
101
        set_factor_by_calculator: bool = False,
102
        log_level: int = 0
103
    ): ...
104
    
105
    def generate_displacements(
106
        self,
107
        distance: float | None = None,
108
        is_plusminus: Literal["auto"] | bool = "auto",
109
        is_diagonal: bool = True,
110
        is_trigonal: bool = False,
111
        number_of_snapshots: int | Literal["auto"] | None = None,
112
        random_seed: int | None = None,
113
        temperature: float | None = None,
114
        cutoff_frequency: float | None = None,
115
        max_distance: float | None = None,
116
        number_estimation_factor: float | None = None
117
    ) -> None: ...
118
    
119
    def produce_force_constants(
120
        self,
121
        fc_calculator: str = "traditional",
122
        fc_calculator_options: str = None,
123
        show_log: bool = True
124
    ): ...
125
    
126
    def run_band_structure(
127
        self,
128
        paths: ArrayLike,
129
        with_eigenvectors: bool = False,
130
        with_group_velocities: bool = False,
131
        is_band_connection: bool = False,
132
        path_connections: ArrayLike = None,
133
        labels: list = None,
134
        is_legacy_plot: bool = False
135
    ): ...
136
    
137
    def run_mesh(
138
        self,
139
        mesh: ArrayLike,
140
        shift: ArrayLike = None,
141
        is_time_reversal: bool = True,
142
        is_mesh_symmetry: bool = True,
143
        with_eigenvectors: bool = False,
144
        with_group_velocities: bool = False,
145
        is_gamma_center: bool = False
146
    ): ...
147
    
148
    def run_thermal_properties(
149
        self,
150
        t_min: float = 0,
151
        t_max: float = 1000,
152
        t_step: float = 10,
153
        temperatures: ArrayLike = None,
154
        cutoff_frequency: float = None,
155
        pretend_real: bool = False,
156
        band_indices: ArrayLike = None,
157
        is_projection: bool = False,
158
        classical: bool = False
159
    ): ...
160
```
161

162
[Core Phonopy API](./core-phonopy.md)
163

164
### Grüneisen Parameters
165

166
Calculate mode Grüneisen parameters that quantify anharmonicity by measuring how phonon frequencies change with volume variations.
167

168
```python { .api }
169
class PhonopyGruneisen:
170
    def __init__(
171
        self,
172
        phonon: Phonopy,
173
        phonon_plus: Phonopy, 
174
        phonon_minus: Phonopy,
175
        delta_strain: float = None
176
    ): ...
177
    
178
    def set_mesh(
179
        self,
180
        mesh: ArrayLike,
181
        is_gamma_center: bool = False,
182
        shift: ArrayLike = None,
183
        is_time_reversal: bool = True,
184
        is_mesh_symmetry: bool = True
185
    ): ...
186
    
187
    def set_band_structure(self, bands: ArrayLike): ...
188
```
189

190
[Grüneisen Parameters](./gruneisen.md)
191

192
### Quasi-Harmonic Approximation
193

194
Perform quasi-harmonic approximation calculations to study temperature and pressure effects on material properties through phonon calculations at multiple volumes.
195

196
```python { .api }
197
class PhonopyQHA:
198
    def __init__(
199
        self,
200
        volumes: ArrayLike = None,
201
        electronic_energies: ArrayLike = None,
202
        temperatures: ArrayLike = None,
203
        free_energy: ArrayLike = None,
204
        cv: ArrayLike = None,
205
        entropy: ArrayLike = None,
206
        t_max: float = None,
207
        energy_plot_factor: float = None,
208
        pressure: float = None,
209
        eos: str = "vinet",
210
        verbose: bool = False
211
    ): ...
212
    
213
    def get_bulk_modulus(self): ...
214
    def get_helmholtz_volume(self): ...
215
    def get_volume_temperature(self): ...
216
    def get_thermal_expansion(self): ...
217
    def get_heat_capacity_P_numerical(self): ...
218
```
219

220
[Quasi-Harmonic Approximation](./qha.md)
221

222
### Crystal Structure Handling
223

224
Handle crystalline structure representations, transformations, and symmetry operations for phonon calculations.
225

226
```python { .api }
227
class PhonopyAtoms:
228
    def __init__(
229
        self,
230
        symbols: Optional[Sequence] = None,
231
        numbers: Optional[Union[Sequence, np.ndarray]] = None,
232
        masses: Optional[Union[Sequence, np.ndarray]] = None,
233
        magnetic_moments: Optional[Union[Sequence, np.ndarray]] = None,
234
        scaled_positions: Optional[Union[Sequence, np.ndarray]] = None,
235
        positions: Optional[Union[Sequence, np.ndarray]] = None,
236
        cell: Optional[Union[Sequence, np.ndarray]] = None,
237
        atoms: Optional["PhonopyAtoms"] = None,
238
        magmoms: Optional[Union[Sequence, np.ndarray]] = None,
239
        pbc: Optional[bool] = None
240
    ): ...
241
    
242
    def copy(self) -> PhonopyAtoms: ...
243
    def get_cell(self) -> ndarray: ...
244
    def get_positions(self) -> ndarray: ...
245
    def get_scaled_positions(self) -> ndarray: ...
246
    def get_masses(self) -> ndarray: ...
247
    def get_chemical_symbols(self) -> list: ...
248
    def get_atomic_numbers(self) -> ndarray: ...
249
```
250

251
[Crystal Structure Handling](./structure.md)
252

253
### Loading and File Operations
254

255
Load phonopy calculations from various file formats and manage input/output operations with different ab initio calculation codes.
256

257
```python { .api }
258
def load(
259
    phonopy_yaml: str | os.PathLike | io.IOBase | None = None,
260
    supercell_matrix: ArrayLike | None = None,
261
    primitive_matrix: ArrayLike | str | None = None,
262
    is_nac: bool = True,
263
    calculator: str | None = None,
264
    unitcell: PhonopyAtoms | None = None,
265
    supercell: PhonopyAtoms | None = None,
266
    nac_params: dict | None = None,
267
    unitcell_filename: os.PathLike | str | None = None,
268
    supercell_filename: os.PathLike | str | None = None,
269
    born_filename: os.PathLike | str | None = None,
270
    force_sets_filename: os.PathLike | str | None = None,
271
    force_constants_filename: os.PathLike | str | None = None,
272
    fc_calculator: Literal["traditional", "symfc", "alm"] | None = None,
273
    fc_calculator_options: str | None = None,
274
    factor: float | None = None,
275
    produce_fc: bool = True,
276
    is_symmetry: bool = True,
277
    symmetrize_fc: bool = True,
278
    is_compact_fc: bool = True,
279
    use_pypolymlp: bool = False,
280
    mlp_params: dict | None = None,
281
    store_dense_svecs: bool = True,
282
    use_SNF_supercell: bool = False,
283
    symprec: float = 1e-5,
284
    log_level: int = 0
285
) -> Phonopy: ...
286
```
287

288
[Loading and File Operations](./loading.md)
289

290
### Command-line Tools
291

292
Comprehensive command-line interface providing phonopy calculations, plotting utilities, and file format conversions through specialized scripts.
293

294
```python { .api }
295
# Main phonopy command-line interface
296
def main(): ...
297

298
# Plotting utilities  
299
def phonopy_bandplot(): ...
300
def phonopy_pdosplot(): ...
301
def phonopy_propplot(): ...
302
def phonopy_tdplot(): ...
303
def phonopy_gruneisenplot(): ...
304

305
# Calculation scripts
306
def phonopy_gruneisen(): ...
307
def phonopy_qha(): ...
308

309
# Utility scripts
310
def phonopy_calc_convert(): ...
311
def create_FORCE_SETS(): ...
312
```
313

314
[Command-line Tools](./cli-tools.md)
315

316
## Common Types
317

318
```python { .api }
319
# Standard library imports
320
import os
321
import io
322
from typing import Optional, Union, Sequence, Literal
323
from pathlib import Path
324

325
# NumPy imports
326
import numpy as np
327
from numpy import ndarray
328
from numpy.typing import ArrayLike
329

330
# Type aliases for common array-like inputs (following phonopy source)
331
ArrayLike = Union[list, tuple, Sequence, np.ndarray]
332

333
# File path types (explicit module references as in source)
334
PathLike = Union[str, os.PathLike, Path]
335
IOBase = io.IOBase
336

337
# Common calculator interfaces
338
Calculator = Literal[
339
    "vasp", "qe", "abinit", "aims", "castep", 
340
    "cp2k", "crystal", "wien2k", "siesta", "lammps"
341
]
342

343
# Force constants calculator types
344
ForceConstantsCalculator = Literal["traditional", "symfc", "alm"]
345
```