0
# Core Phonopy API
1

2
The main Phonopy class provides comprehensive phonon calculation capabilities including displacement generation, force constant calculation, band structure analysis, density of states, and thermal property calculations. This class serves as the primary interface for most phonopy operations.
3

4
## Capabilities
5

6
### Initialization and Setup
7

8
Create and configure Phonopy instances with crystal structure and calculation parameters.
9

10
```python { .api }
11
class Phonopy:
12
    def __init__(
13
        self,
14
        unitcell: PhonopyAtoms,
15
        supercell_matrix: ArrayLike = None,
16
        primitive_matrix: ArrayLike | str = None,
17
        nac_params: dict = None,
18
        factor: float = None,
19
        frequency_scale_factor: float = None,
20
        dynamical_matrix_decimals: int = None,
21
        force_constants_decimals: int = None,
22
        group_velocity_delta_q: float = None,
23
        symprec: float = 1e-5,
24
        is_symmetry: bool = True,
25
        store_dense_svecs: bool = True,
26
        use_SNF_supercell: bool = False,
27
        hermitianize_dynamical_matrix: bool = True,
28
        calculator: str = None,
29
        set_factor_by_calculator: bool = False,
30
        log_level: int = 0
31
    ):
32
        """
33
        Initialize Phonopy instance for phonon calculations.
34
        
35
        Parameters:
36
        - unitcell: Unit cell structure as PhonopyAtoms object
37
        - supercell_matrix: 3x3 array defining supercell transformation
38
        - primitive_matrix: 3x3 array or string ('auto', 'F', 'I', 'A', 'C', 'P', 'R') 
39
        - nac_params: Non-analytical correction parameters dictionary (deprecated)
40
        - factor: Unit conversion factor (deprecated)
41
        - frequency_scale_factor: Frequency scaling factor (deprecated)
42
        - dynamical_matrix_decimals: Decimal places for dynamical matrix (deprecated)
43
        - force_constants_decimals: Decimal places for force constants (deprecated)
44
        - group_velocity_delta_q: Delta-q distance for group velocity calculation
45
        - symprec: Symmetry search precision (default: 1e-5)
46
        - is_symmetry: Whether to search supercell symmetry (default: True)
47
        - store_dense_svecs: Store shortest vectors in dense format (default: True)
48
        - use_SNF_supercell: Use SNF algorithm for supercell building (default: False)
49
        - hermitianize_dynamical_matrix: Force-hermitianize dynamical matrix (default: True)
50
        - calculator: Calculator interface ('vasp', 'qe', 'abinit', etc.)
51
        - set_factor_by_calculator: Set unit factor by calculator (default: False)
52
        - log_level: Logging verbosity (0=quiet, 1=normal, 2=verbose)
53
        """
54
```
55

56
**Example:**
57

58
```python
59
from phonopy import Phonopy
60
from phonopy.structure.atoms import PhonopyAtoms
61

62
# Create unit cell
63
lattice = [[3.17, 0, 0], [0, 3.17, 0], [0, 0, 5.13]]
64
positions = [[0.33, 0.67, 0], [0.67, 0.33, 0.5]]
65
numbers = [13, 13]  # Aluminum
66

67
unitcell = PhonopyAtoms(cell=lattice, 
68
                        scaled_positions=positions,
69
                        numbers=numbers)
70

71
# Create Phonopy instance with 3x3x2 supercell  
72
supercell_matrix = [[3, 0, 0], [0, 3, 0], [0, 0, 2]]
73
ph = Phonopy(unitcell, supercell_matrix, primitive_matrix='auto')
74
```
75

76
### Displacement Generation
77

78
Generate atomic displacements for force constant calculations using finite displacement method.
79

80
```python { .api }
81
def generate_displacements(
82
    self,
83
    distance: float | None = None,
84
    is_plusminus: Literal["auto"] | bool = "auto",
85
    is_diagonal: bool = True,
86
    is_trigonal: bool = False,
87
    number_of_snapshots: int | Literal["auto"] | None = None,
88
    random_seed: int | None = None,
89
    temperature: float | None = None,
90
    cutoff_frequency: float | None = None,
91
    max_distance: float | None = None,
92
    number_estimation_factor: float | None = None
93
) -> None:
94
    """
95
    Generate displacement patterns for force calculations.
96
    
97
    Parameters:
98
    - distance: Displacement distance in Angstrom (default: 0.01 if None)
99
    - is_plusminus: Generate both positive and negative displacements ("auto", True, or False)
100
    - is_diagonal: Use diagonal displacement matrix  
101
    - is_trigonal: Generate trigonal displacement patterns
102
    - number_of_snapshots: Number of random displacement snapshots (int or "auto")
103
    - random_seed: Seed for random number generator
104
    - temperature: Temperature for random displacements (K)
105
    - cutoff_frequency: Frequency cutoff for random displacements (THz)
106
    - max_distance: Maximum distance between displaced atom and others
107
    - number_estimation_factor: Factor for estimating number of random displacements
108
    """
109

110
def get_displacements(self) -> ndarray:
111
    """Get generated displacement vectors."""
112

113
def get_supercells_with_displacements(self) -> list:
114
    """Get supercell structures with applied displacements."""
115
```
116

117
**Example:**
118

119
```python
120
# Generate standard finite displacements
121
ph.generate_displacements(distance=0.01, is_plusminus=True)
122
print(f"Generated {len(ph.displacements)} displacements")
123

124
# Generate random displacements at finite temperature
125
ph.generate_displacements(
126
    number_of_snapshots=100,
127
    temperature=300,
128
    random_seed=42
129
)
130
```
131

132
### Force Constants Calculation
133

134
Calculate interatomic force constants from forces obtained through ab initio calculations.
135

136
```python { .api }
137
def produce_force_constants(
138
    self,
139
    fc_calculator: str = "traditional",
140
    fc_calculator_options: str = None,
141
    show_log: bool = True
142
):
143
    """
144
    Calculate force constants from forces using specified method.
145
    
146
    Parameters:
147
    - fc_calculator: Method ('traditional', 'symfc', 'alm')
148
    - fc_calculator_options: Additional options string for calculator
149
    - show_log: Display calculation progress and information
150
    """
151

152
def set_forces(self, forces: ArrayLike):
153
    """Set forces on atoms in displaced supercells."""
154

155
def get_force_constants(self) -> ndarray:
156
    """Get calculated second-order force constants matrix."""
157

158
def set_force_constants(self, force_constants: ArrayLike):
159
    """Directly set force constants matrix."""
160
```
161

162
**Example:**
163

164
```python
165
# After obtaining forces from ab initio calculations
166
forces = [force_array_1, force_array_2, ...]  # From DFT calculations
167
ph.forces = forces
168

169
# Calculate force constants using symmetry
170
ph.produce_force_constants(fc_calculator='symfc', show_log=True)
171

172
# Or set force constants directly
173
ph.set_force_constants(force_constants_matrix)
174
```
175

176
### Phonon Band Structure
177

178
Calculate and analyze phonon band structures along high-symmetry paths in the Brillouin zone.
179

180
```python { .api }
181
def run_band_structure(
182
    self,
183
    paths: ArrayLike,
184
    with_eigenvectors: bool = False,
185
    with_group_velocities: bool = False,
186
    is_band_connection: bool = False,
187
    path_connections: ArrayLike = None,
188
    labels: list = None,
189
    is_legacy_plot: bool = False
190
):
191
    """
192
    Calculate phonon band structure along specified k-point paths.
193
    
194
    Parameters:
195
    - paths: k-point paths as list of segments or 2D array
196
    - with_eigenvectors: Calculate eigenvectors (mode vectors)
197
    - with_group_velocities: Calculate phonon group velocities
198
    - is_band_connection: Connect bands across path segments
199
    - path_connections: Specify which path segments to connect
200
    - labels: Labels for special k-points
201
    - is_legacy_plot: Use legacy plotting format
202
    """
203

204
def get_band_structure(self):
205
    """Get BandStructure object with frequencies and k-points."""
206

207
def get_band_structure_dict(self) -> dict:
208
    """Get band structure data as dictionary."""
209

210
def write_yaml_band_structure(self, filename: str = "band.yaml"):
211
    """Write band structure to YAML file."""
212

213
def auto_band_structure(
214
    self,
215
    npoints: int = 101,
216
    with_eigenvectors: bool = False,
217
    with_group_velocities: bool = False
218
) -> dict:
219
    """
220
    Automatically generate and calculate band structure using seekpath.
221
    
222
    Parameters:
223
    - npoints: Number of points along each path segment
224
    - with_eigenvectors: Include eigenvectors in calculation
225
    - with_group_velocities: Include group velocities
226
    
227
    Returns:
228
    Dictionary with band structure data and path information
229
    """
230
```
231

232
**Example:**
233

234
```python
235
# Manual band structure with custom path
236
paths = [[[0.0, 0.0, 0.0],    # Gamma
237
          [0.5, 0.0, 0.5]],   # X
238
         [[0.5, 0.0, 0.5],    # X  
239
          [0.5, 0.25, 0.75]], # W
240
         [[0.5, 0.25, 0.75],  # W
241
          [0.0, 0.0, 0.0]]]   # Gamma
242

243
ph.run_band_structure(paths, with_eigenvectors=True)
244
bs = ph.get_band_structure_dict()
245

246
# Automatic band structure using seekpath
247
bs_auto = ph.auto_band_structure(npoints=101, with_group_velocities=True)
248
```
249

250
### Phonon Mesh Calculations
251

252
Perform phonon calculations on regular q-point meshes for integration over the Brillouin zone.
253

254
```python { .api }
255
def run_mesh(
256
    self,
257
    mesh: ArrayLike,
258
    shift: ArrayLike = None,
259
    is_time_reversal: bool = True,
260
    is_mesh_symmetry: bool = True,
261
    with_eigenvectors: bool = False,
262
    with_group_velocities: bool = False,
263
    is_gamma_center: bool = False
264
):
265
    """
266
    Calculate phonons on regular q-point mesh.
267
    
268
    Parameters:
269
    - mesh: Mesh dimensions [nx, ny, nz]
270
    - shift: Mesh shift from origin [sx, sy, sz]  
271
    - is_time_reversal: Apply time-reversal symmetry
272
    - is_mesh_symmetry: Use crystal symmetry to reduce q-points
273
    - with_eigenvectors: Calculate eigenvectors at each q-point
274
    - with_group_velocities: Calculate group velocities
275
    - is_gamma_center: Center mesh on gamma point
276
    """
277

278
def get_mesh_dict(self) -> dict:
279
    """Get mesh calculation results as dictionary."""
280

281
def write_hdf5_mesh(self, filename: str = "mesh.hdf5"):
282
    """Write mesh data to HDF5 file."""
283

284
def write_yaml_mesh(self, filename: str = "mesh.yaml"):
285
    """Write mesh data to YAML file."""
286
```
287

288
### Density of States
289

290
Calculate total and projected phonon density of states from mesh calculations.
291

292
```python { .api }
293
def run_total_dos(
294
    self,
295
    sigma: float = None,
296
    freq_min: float = None,
297
    freq_max: float = None,
298
    freq_pitch: float = None,
299
    use_tetrahedron_method: bool = True
300
):
301
    """
302
    Calculate total phonon density of states.
303
    
304
    Parameters:
305
    - sigma: Smearing width for Gaussian method (THz)
306
    - freq_min: Minimum frequency for DOS calculation (THz)
307
    - freq_max: Maximum frequency for DOS calculation (THz)
308
    - freq_pitch: Frequency step size (THz)
309
    - use_tetrahedron_method: Use tetrahedron method (more accurate)
310
    """
311

312
def run_projected_dos(
313
    self,
314
    sigma: float = None,
315
    freq_min: float = None,
316
    freq_max: float = None,
317
    freq_pitch: float = None,
318
    use_tetrahedron_method: bool = True,
319
    direction: ArrayLike = None,
320
    xyz_projection: bool = False
321
):
322
    """
323
    Calculate projected phonon density of states.
324
    
325
    Parameters:
326
    - sigma: Smearing width for Gaussian method (THz)  
327
    - freq_min: Minimum frequency for DOS calculation (THz)
328
    - freq_max: Maximum frequency for DOS calculation (THz)
329
    - freq_pitch: Frequency step size (THz)
330
    - use_tetrahedron_method: Use tetrahedron method
331
    - direction: Projection direction vector
332
    - xyz_projection: Project onto x, y, z directions
333
    """
334

335
def get_total_dos_dict(self) -> dict:
336
    """Get total DOS data as dictionary."""
337

338
def get_projected_dos_dict(self) -> dict:
339
    """Get projected DOS data as dictionary."""
340

341
def write_total_dos(self, filename: str = "total_dos.dat"):
342
    """Write total DOS to text file."""
343

344
def write_projected_dos(self, filename: str = "projected_dos.dat"):
345
    """Write projected DOS to text file."""
346
```
347

348
### Thermal Properties
349

350
Calculate thermodynamic properties including heat capacity, entropy, and free energy.
351

352
```python { .api }
353
def run_thermal_properties(
354
    self,
355
    t_min: float = 0,
356
    t_max: float = 1000,
357
    t_step: float = 10,
358
    temperatures: ArrayLike = None,
359
    cutoff_frequency: float = None,
360
    pretend_real: bool = False,
361
    band_indices: ArrayLike = None,
362
    is_projection: bool = False,
363
    classical: bool = False
364
):
365
    """
366
    Calculate thermal properties from phonon frequencies.
367
    
368
    Parameters:
369
    - t_min: Minimum temperature (K, default: 0)
370
    - t_max: Maximum temperature (K, default: 1000)
371
    - t_step: Temperature step (K, default: 10)
372
    - temperatures: Custom temperature array (overrides t_min/t_max/t_step)
373
    - cutoff_frequency: Ignore frequencies below cutoff (THz)
374
    - pretend_real: Treat imaginary frequencies as real
375
    - band_indices: Specific phonon bands to include
376
    - is_projection: Calculate mode-by-mode contributions
377
    - classical: Use classical statistics instead of quantum
378
    """
379

380
def get_thermal_properties_dict(self) -> dict:
381
    """
382
    Get thermal properties as dictionary.
383
    
384
    Returns:
385
    Dictionary with keys: 'temperatures', 'free_energy', 'entropy', 
386
    'heat_capacity', and temperature-dependent values
387
    """
388

389
def write_yaml_thermal_properties(
390
    self, 
391
    filename: str = "thermal_properties.yaml"
392
):
393
    """Write thermal properties to YAML file."""
394

395
def run_thermal_displacements(
396
    self,
397
    temperatures: ArrayLike = None,
398
    direction: ArrayLike = None,
399
    freq_min: float = None,
400
    freq_max: float = None
401
):
402
    """
403
    Calculate mean square thermal displacements.
404
    
405
    Parameters:
406
    - temperatures: Temperature range for calculation (K)
407
    - direction: Displacement direction vector
408
    - freq_min: Minimum frequency to include (THz)
409
    - freq_max: Maximum frequency to include (THz)
410
    """
411

412
def get_thermal_displacements_dict(self) -> dict:
413
    """Get thermal displacement data as dictionary."""
414
```
415

416
### Q-point Calculations
417

418
Calculate phonon properties at specific q-points.
419

420
```python { .api }
421
def run_qpoints(
422
    self,
423
    q_points: ArrayLike,
424
    with_eigenvectors: bool = False,
425
    with_dynamical_matrices: bool = False,
426
    with_group_velocities: bool = False,
427
    nac_q_direction: ArrayLike = None
428
):
429
    """
430
    Calculate phonons at specific q-points.
431
    
432
    Parameters:
433
    - q_points: List of q-point coordinates in reciprocal space
434
    - with_eigenvectors: Calculate phonon eigenvectors
435
    - with_dynamical_matrices: Store dynamical matrices
436
    - with_group_velocities: Calculate group velocities
437
    - nac_q_direction: Direction for non-analytical correction at Gamma
438
    """
439

440
def get_qpoints_dict(self) -> dict:
441
    """Get q-point calculation results as dictionary."""
442

443
def get_frequencies(self, q: ArrayLike) -> ndarray:
444
    """
445
    Get phonon frequencies at single q-point.
446
    
447
    Parameters:
448
    - q: q-point coordinates [qx, qy, qz]
449
    
450
    Returns:
451
    Array of phonon frequencies (THz)
452
    """
453

454
def get_frequencies_with_eigenvectors(self, q: ArrayLike) -> tuple:
455
    """
456
    Get frequencies and eigenvectors at single q-point.
457
    
458
    Parameters:
459
    - q: q-point coordinates [qx, qy, qz]
460
    
461
    Returns:
462
    Tuple of (frequencies, eigenvectors)
463
    """
464
```
465

466
### File I/O and Serialization
467

468
Save and load phonopy calculations and results.
469

470
```python { .api }
471
def save(
472
    self,
473
    filename: str = "phonopy_params.yaml",
474
    settings: dict = None
475
):
476
    """
477
    Save Phonopy instance parameters to YAML file.
478
    
479
    Parameters:
480
    - filename: Output file name
481
    - settings: Additional settings to save
482
    """
483

484
def copy(self) -> Phonopy:
485
    """Create deep copy of Phonopy instance."""
486

487
def write_animation(
488
    self,
489
    q_point: ArrayLike = None,
490
    anime_type: str = "v_sim",
491
    band_index: int = None,
492
    amplitude: float = 1,
493
    num_div: int = 20,
494
    shift: ArrayLike = None,
495
    filename: str = None
496
):
497
    """
498
    Write phonon mode animation files.
499
    
500
    Parameters:
501
    - q_point: q-point for mode visualization [qx, qy, qz]
502
    - anime_type: Animation format ('v_sim', 'arc', 'xyz', 'jmol', 'poscar')
503
    - band_index: Phonon band index to animate
504
    - amplitude: Animation amplitude scaling
505
    - num_div: Number of animation frames
506
    - shift: Phase shift for animation
507
    - filename: Output file name
508
    """
509
```
510

511
### Properties and Attributes
512

513
Key properties accessible on Phonopy instances.
514

515
```python { .api }
516
# Structure properties
517
@property
518
def unitcell(self) -> PhonopyAtoms: ...
519

520
@property  
521
def primitive(self) -> PhonopyAtoms: ...
522

523
@property
524
def supercell(self) -> PhonopyAtoms: ...
525

526
@property
527
def supercell_matrix(self) -> ndarray: ...
528

529
@property
530
def primitive_matrix(self) -> ndarray: ...
531

532
# Calculation data
533
@property
534
def dataset(self) -> dict: ...
535

536
@property
537
def displacements(self) -> ndarray: ...
538

539
@property  
540
def forces(self) -> ndarray: ...
541

542
@property
543
def force_constants(self) -> ndarray: ...
544

545
# Symmetry and analysis
546
@property
547
def symmetry(self): ...
548

549
@property
550
def primitive_symmetry(self): ...
551

552
@property
553
def dynamical_matrix(self): ...
554

555
@property
556
def nac_params(self) -> dict: ...
557

558
# Results
559
@property
560
def mesh(self): ...
561

562
@property
563
def band_structure(self): ...
564

565
@property
566
def thermal_properties(self): ...
567

568
@property
569
def total_dos(self): ...
570

571
@property
572
def projected_dos(self): ...
573
```
574

575
**Example Usage:**
576

577
```python
578
# Access calculated results
579
temps = ph.thermal_properties.temperatures
580
free_energy = ph.thermal_properties.free_energy
581
heat_capacity = ph.thermal_properties.heat_capacity
582

583
# Get structure information
584
print(f"Unit cell volume: {ph.unitcell.volume}")
585
print(f"Supercell dimensions: {ph.supercell_matrix}")
586
print(f"Number of atoms: {ph.supercell.get_number_of_atoms()}")
587
```
588

589
## Common Workflow Example
590

591
```python
592
from phonopy import Phonopy
593
from phonopy.structure.atoms import PhonopyAtoms
594
import numpy as np
595

596
# 1. Setup structure and Phonopy instance
597
unitcell = PhonopyAtoms(...)  # Create from structure data
598
ph = Phonopy(unitcell, [[2,0,0],[0,2,0],[0,0,2]])
599

600
# 2. Generate displacements and calculate forces (external DFT step)
601
ph.generate_displacements(distance=0.01)
602
# ... run DFT calculations for each displaced structure ...
603
ph.forces = forces_from_dft  # Set forces from DFT
604

605
# 3. Calculate force constants
606
ph.produce_force_constants()
607

608
# 4. Phonon analysis
609
# Band structure
610
ph.auto_band_structure(npoints=101)
611
band_dict = ph.get_band_structure_dict()
612

613
# Density of states
614
ph.run_mesh([20, 20, 20])
615
ph.run_total_dos()
616
dos_dict = ph.get_total_dos_dict()
617

618
# Thermal properties
619
temperatures = np.arange(0, 1000, 10)
620
ph.run_thermal_properties(temperatures)
621
thermal_dict = ph.get_thermal_properties_dict()
622

623
# 5. Save results
624
ph.save("phonopy_params.yaml")
625
ph.write_yaml_band_structure("band.yaml")
626
ph.write_yaml_thermal_properties("thermal.yaml")
627
```