0
# Grüneisen Parameters
1

2
Calculate mode Grüneisen parameters that quantify anharmonicity by measuring how phonon frequencies change with volume variations. Grüneisen parameters are crucial for understanding thermal expansion, pressure effects, and anharmonic properties of materials.
3

4
## Capabilities
5

6
### Grüneisen Parameter Calculation
7

8
Initialize and perform Grüneisen parameter calculations using three Phonopy instances at different volumes.
9

10
```python { .api }
11
class PhonopyGruneisen:
12
    def __init__(
13
        self,
14
        phonon: Phonopy,
15
        phonon_plus: Phonopy,
16
        phonon_minus: Phonopy,
17
        delta_strain: float = None
18
    ):
19
        """
20
        Initialize Grüneisen parameter calculation.
21
        
22
        Parameters:
23
        - phonon: Reference Phonopy instance at equilibrium volume
24
        - phonon_plus: Phonopy instance at expanded volume (V + ΔV)
25
        - phonon_minus: Phonopy instance at compressed volume (V - ΔV)  
26
        - delta_strain: Volume strain used for finite difference (optional)
27
        """
28

29
    def get_phonon(self) -> Phonopy:
30
        """Get reference phonon object."""
31
```
32

33
**Example:**
34

35
```python
36
from phonopy import Phonopy, PhonopyGruneisen
37
from phonopy.structure.atoms import PhonopyAtoms
38
import numpy as np
39

40
# Create three Phonopy instances at different volumes
41
# Reference volume (equilibrium)
42
ph0 = Phonopy(unitcell_eq, supercell_matrix)
43
ph0.force_constants = fc_eq
44

45
# Expanded volume (+2% strain)
46
unitcell_plus = unitcell_eq.copy()  
47
unitcell_plus.cell = unitcell_eq.cell * 1.02**(1/3)
48
ph_plus = Phonopy(unitcell_plus, supercell_matrix)
49
ph_plus.force_constants = fc_plus
50

51
# Compressed volume (-2% strain) 
52
unitcell_minus = unitcell_eq.copy()
53
unitcell_minus.cell = unitcell_eq.cell * 0.98**(1/3)
54
ph_minus = Phonopy(unitcell_minus, supercell_matrix)
55
ph_minus.force_constants = fc_minus
56

57
# Calculate Grüneisen parameters
58
gruneisen = PhonopyGruneisen(ph0, ph_plus, ph_minus)
59
```
60

61
### Mesh Calculations
62

63
Calculate Grüneisen parameters on regular q-point meshes for Brillouin zone integration.
64

65
```python { .api }
66
def set_mesh(
67
    self,
68
    mesh: ArrayLike,
69
    is_gamma_center: bool = False,
70
    shift: ArrayLike = None,
71
    is_time_reversal: bool = True,
72
    is_mesh_symmetry: bool = True
73
):
74
    """
75
    Set q-point mesh for Grüneisen parameter calculation.
76
    
77
    Parameters:
78
    - mesh: Mesh dimensions [nx, ny, nz]
79
    - is_gamma_center: Center mesh on Gamma point
80
    - shift: Mesh shift from origin [sx, sy, sz]
81
    - is_time_reversal: Apply time-reversal symmetry
82
    - is_mesh_symmetry: Use crystal symmetry to reduce q-points
83
    """
84

85
def get_mesh(self):
86
    """
87
    Get GruneisenMesh object with calculated parameters.
88
    
89
    Returns:
90
    GruneisenMesh object containing frequencies, Grüneisen parameters,
91
    and integration weights for each q-point
92
    """
93

94
def write_yaml_mesh(self, filename: str = "gruneisen_mesh.yaml"):
95
    """
96
    Write mesh Grüneisen parameters to YAML file.
97
    
98
    Parameters:
99
    - filename: Output YAML file name
100
    """
101

102
def write_hdf5_mesh(self, filename: str = "gruneisen_mesh.hdf5"):
103
    """
104
    Write mesh Grüneisen parameters to HDF5 file.
105
    
106
    Parameters:
107
    - filename: Output HDF5 file name
108
    """
109
```
110

111
**Example:**
112

113
```python
114
# Calculate Grüneisen parameters on 20x20x20 mesh
115
gruneisen.set_mesh([20, 20, 20], is_gamma_center=True)
116
mesh = gruneisen.get_mesh()
117

118
# Access mesh data
119
frequencies = mesh.frequencies  # Shape: (nq, nbands)
120
gruneisen_params = mesh.gruneisen  # Shape: (nq, nbands)
121
weights = mesh.weights  # Integration weights
122

123
# Save results
124
gruneisen.write_yaml_mesh("gruneisen_mesh.yaml")
125
gruneisen.write_hdf5_mesh("gruneisen_mesh.hdf5")
126
```
127

128
### Band Structure Analysis
129

130
Calculate Grüneisen parameters along high-symmetry paths in the Brillouin zone.
131

132
```python { .api }
133
def set_band_structure(self, bands: ArrayLike):
134
    """
135
    Set band structure path for Grüneisen parameter calculation.
136
    
137
    Parameters:
138
    - bands: k-point paths as list of segments or 2D array
139
    """
140

141
def get_band_structure(self):
142
    """
143
    Get GruneisenBandStructure object with calculated parameters.
144
    
145
    Returns:
146
    GruneisenBandStructure object containing frequencies, Grüneisen 
147
    parameters, and q-point paths
148
    """
149

150
def write_yaml_band_structure(
151
    self, 
152
    filename: str = "gruneisen_band.yaml"
153
):
154
    """
155
    Write band structure Grüneisen parameters to YAML file.
156
    
157
    Parameters:
158
    - filename: Output YAML file name
159
    """
160
```
161

162
**Example:**
163

164
```python
165
# Define high-symmetry path
166
bands = [[[0.0, 0.0, 0.0],    # Gamma
167
          [0.5, 0.0, 0.5]],   # X
168
         [[0.5, 0.0, 0.5],    # X
169
          [0.5, 0.25, 0.75]], # W
170
         [[0.5, 0.25, 0.75],  # W
171
          [0.0, 0.0, 0.0]]]   # Gamma
172

173
# Calculate Grüneisen parameters along path
174
gruneisen.set_band_structure(bands)
175
band_structure = gruneisen.get_band_structure()
176

177
# Access band structure data
178
distances = band_structure.distances
179
frequencies = band_structure.frequencies  # Shape: (nq, nbands)
180
gruneisen_params = band_structure.gruneisen  # Shape: (nq, nbands)
181

182
# Save results
183
gruneisen.write_yaml_band_structure("gruneisen_band.yaml")
184
```
185

186
### Plotting and Visualization
187

188
Generate plots of Grüneisen parameters versus frequency and along band structure paths.
189

190
```python { .api }
191
def plot_mesh(
192
    self,
193
    cutoff_frequency: float = None,
194
    color_scheme: str = None,
195
    marker: str = 'o',
196
    markersize: float = None,
197
    xlabel: str = None,
198
    ylabel: str = None,
199
    drawing_area: ArrayLike = None,
200
    aspect: str = 'auto'
201
):
202
    """
203
    Plot Grüneisen parameters vs frequency from mesh calculation.
204
    
205
    Parameters:
206
    - cutoff_frequency: Exclude frequencies below cutoff (THz)
207
    - color_scheme: Color scheme for plotting
208
    - marker: Matplotlib marker style
209
    - markersize: Size of plot markers
210
    - xlabel: X-axis label
211
    - ylabel: Y-axis label  
212
    - drawing_area: Plot area bounds [xmin, xmax, ymin, ymax]
213
    - aspect: Axes aspect ratio
214
    """
215

216
def plot_band_structure(
217
    self,
218
    epsilon: float = 1e-4,
219
    color_scheme: str = None,
220
    marker: str = 'o',
221
    markersize: float = None,
222
    xlabel: str = None,
223
    ylabel: str = None,
224
    drawing_area: ArrayLike = None,
225
    aspect: str = 'auto'
226
):
227
    """
228
    Plot Grüneisen parameters along band structure path.
229
    
230
    Parameters:
231
    - epsilon: Threshold for avoiding small frequencies
232
    - color_scheme: Color scheme for plotting
233
    - marker: Matplotlib marker style
234
    - markersize: Size of plot markers
235
    - xlabel: X-axis label
236
    - ylabel: Y-axis label
237
    - drawing_area: Plot area bounds [xmin, xmax, ymin, ymax]
238
    - aspect: Axes aspect ratio
239
    """
240
```
241

242
**Example:**
243

244
```python
245
import matplotlib.pyplot as plt
246

247
# Plot Grüneisen parameters vs frequency from mesh
248
gruneisen.plot_mesh(cutoff_frequency=1.0)
249
plt.title("Grüneisen Parameters vs Frequency")
250
plt.show()
251

252
# Plot Grüneisen parameters along band structure
253
gruneisen.plot_band_structure(epsilon=1e-3)
254
plt.title("Grüneisen Parameters Band Structure")
255
plt.show()
256
```
257

258
## Supporting Classes
259

260
### GruneisenMesh
261

262
Mesh-based Grüneisen parameter calculation results.
263

264
```python { .api }
265
class GruneisenMesh:
266
    @property
267
    def frequencies(self) -> ndarray:
268
        """Phonon frequencies at mesh q-points (THz)."""
269
    
270
    @property
271
    def gruneisen(self) -> ndarray:
272
        """Grüneisen parameters at mesh q-points."""
273
    
274
    @property
275
    def weights(self) -> ndarray:
276
        """Integration weights for mesh q-points."""
277
    
278
    @property
279
    def qpoints(self) -> ndarray:
280
        """q-point coordinates in reciprocal space."""
281
        
282
    def get_average_gruneisen_parameter(
283
        self, 
284
        t: float = None,
285
        cutoff_frequency: float = None
286
    ) -> float:
287
        """
288
        Get average Grüneisen parameter.
289
        
290
        Parameters:
291
        - t: Temperature for thermal weighting (K)
292
        - cutoff_frequency: Exclude frequencies below cutoff (THz)
293
        
294
        Returns:
295
        Average Grüneisen parameter
296
        """
297
```
298

299
### GruneisenBandStructure  
300

301
Band structure Grüneisen parameter calculation results.
302

303
```python { .api }
304
class GruneisenBandStructure:
305
    @property
306
    def distances(self) -> ndarray:
307
        """Distances along band structure path."""
308
    
309
    @property
310
    def frequencies(self) -> ndarray:
311
        """Phonon frequencies along path (THz)."""
312
    
313
    @property
314
    def gruneisen(self) -> ndarray:
315
        """Grüneisen parameters along path."""
316
    
317
    @property
318
    def qpoints(self) -> ndarray:
319
        """q-point coordinates along path."""
320
        
321
    @property
322
    def labels(self) -> list:
323
        """High-symmetry point labels."""
324
```
325

326
## Complete Workflow Example
327

328
```python
329
from phonopy import Phonopy, PhonopyGruneisen
330
from phonopy.structure.atoms import PhonopyAtoms
331
import numpy as np
332
import matplotlib.pyplot as plt
333

334
# 1. Create structures at three volumes
335
strain = 0.02  # 2% volume strain
336

337
# Equilibrium structure
338
unitcell_eq = PhonopyAtoms(...)  # Your equilibrium structure
339
supercell_matrix = [[2, 0, 0], [0, 2, 0], [0, 0, 2]]
340

341
# Expanded structure (+strain)
342
unitcell_plus = unitcell_eq.copy()
343
scale_plus = (1 + strain)**(1/3)
344
unitcell_plus.cell = unitcell_eq.cell * scale_plus
345

346
# Compressed structure (-strain)  
347
unitcell_minus = unitcell_eq.copy()
348
scale_minus = (1 - strain)**(1/3)
349
unitcell_minus.cell = unitcell_eq.cell * scale_minus
350

351
# 2. Calculate force constants for each volume
352
# (This requires separate DFT calculations at each volume)
353
ph0 = Phonopy(unitcell_eq, supercell_matrix)
354
ph_plus = Phonopy(unitcell_plus, supercell_matrix) 
355
ph_minus = Phonopy(unitcell_minus, supercell_matrix)
356

357
# Set force constants from DFT calculations
358
ph0.force_constants = fc_equilibrium
359
ph_plus.force_constants = fc_expanded
360
ph_minus.force_constants = fc_compressed
361

362
# 3. Calculate Grüneisen parameters
363
gruneisen = PhonopyGruneisen(ph0, ph_plus, ph_minus)
364

365
# 4. Mesh calculation
366
gruneisen.set_mesh([20, 20, 20])
367
mesh = gruneisen.get_mesh()
368

369
# Get average Grüneisen parameter
370
avg_gruneisen = mesh.get_average_gruneisen_parameter(t=300)
371
print(f"Average Grüneisen parameter at 300K: {avg_gruneisen:.3f}")
372

373
# 5. Band structure calculation
374
bands = [[[0.0, 0.0, 0.0], [0.5, 0.0, 0.5]],  # Gamma-X
375
         [[0.5, 0.0, 0.5], [0.5, 0.5, 0.0]],  # X-M
376
         [[0.5, 0.5, 0.0], [0.0, 0.0, 0.0]]]  # M-Gamma
377

378
gruneisen.set_band_structure(bands)
379
band_structure = gruneisen.get_band_structure()
380

381
# 6. Plotting and analysis
382
# Plot frequency vs Grüneisen parameter
383
gruneisen.plot_mesh(cutoff_frequency=1.0)
384
plt.xlabel("Frequency (THz)")
385
plt.ylabel("Grüneisen Parameter")
386
plt.title("Grüneisen Parameters vs Frequency")
387
plt.grid(True)
388
plt.show()
389

390
# Plot band structure
391
gruneisen.plot_band_structure()
392
plt.xlabel("Wave Vector")
393
plt.ylabel("Grüneisen Parameter") 
394
plt.title("Grüneisen Parameters Band Structure")
395
plt.show()
396

397
# 7. Save results
398
gruneisen.write_yaml_mesh("gruneisen_mesh.yaml")
399
gruneisen.write_yaml_band_structure("gruneisen_band.yaml")
400
```
401

402
## Physical Interpretation
403

404
Grüneisen parameters γ are defined as:
405

406
γ = -(V/ω)(∂ω/∂V)
407

408
Where:
409
- V is the crystal volume
410
- ω is the phonon frequency
411
- ∂ω/∂V is the frequency change with volume
412

413
**Interpretation:**
414
- γ > 0: Frequency decreases with expansion (typical for most modes)
415
- γ < 0: Frequency increases with expansion (rare, indicates unusual bonding)
416
- |γ| large: Mode is sensitive to volume changes (anharmonic)
417
- |γ| small: Mode is relatively harmonic
418

419
Grüneisen parameters are essential for understanding:
420
- Thermal expansion coefficients
421
- Pressure dependence of phonon frequencies  
422
- Mode anharmonicity and coupling
423
- Thermodynamic properties under pressure