0
# Command-line Tools
1

2
Comprehensive command-line interface providing phonopy calculations, plotting utilities, and file format conversions through specialized scripts. These tools enable complete phonopy workflows from the command line without requiring Python programming.
3

4
## Capabilities
5

6
### Main Phonopy Command
7

8
Primary command-line interface for phonopy calculations and analysis.
9

10
```python { .api }
11
def main():
12
    """
13
    Main phonopy command-line interface.
14
    
15
    Usage:
16
    phonopy [options] [unitcell_filename]
17
    
18
    Key Options:
19
    --dim="nx ny nz" : Supercell dimensions
20
    --pa="matrix" : Primitive matrix  
21
    --band="path" : Band structure calculation
22
    --mesh="nx ny nz" : Mesh sampling
23
    --dos : Calculate density of states
24
    --thermal : Calculate thermal properties
25
    --temperature="min max step" : Temperature range
26
    --save-params : Save parameters to phonopy.yaml
27
    --writefc : Write force constants
28
    --readfc : Read force constants
29
    --writedm : Write dynamical matrices
30
    --nac : Use non-analytical correction
31
    --q-direction : q-vector direction for NAC
32
    --factor : Frequency unit conversion factor
33
    --symprec : Symmetry precision
34
    --tolerance : Symmetry tolerance
35
    --calculator : Calculator interface
36
    --config : Configuration file
37
    """
38
```
39

40
**Common Usage Examples:**
41

42
```bash
43
# Basic phonopy run with supercell
44
phonopy --dim="2 2 2" POSCAR
45

46
# Calculate band structure
47
phonopy --dim="2 2 2" --band="band.conf" POSCAR
48

49
# Calculate density of states
50
phonopy --dim="2 2 2" --mesh="20 20 20" --dos POSCAR
51

52
# Calculate thermal properties
53
phonopy --dim="2 2 2" --mesh="20 20 20" --thermal POSCAR
54

55
# Use force constants file
56
phonopy --dim="2 2 2" --readfc --band="band.conf" POSCAR
57

58
# Save parameters for later use
59
phonopy --dim="2 2 2" --save-params POSCAR
60

61
# Use non-analytical correction
62
phonopy --dim="2 2 2" --nac --mesh="20 20 20" POSCAR
63
```
64

65
### Plotting Utilities
66

67
Specialized plotting tools for visualizing phonopy results.
68

69
```python { .api }
70
def phonopy_bandplot():
71
    """
72
    Plot phonon band structure from band.yaml file.
73
    
74
    Usage:
75
    phonopy-bandplot [options] [band.yaml]
76
    
77
    Options:
78
    --factor : Unit conversion factor
79
    --xlabel : X-axis label
80
    --ylabel : Y-axis label  
81
    --ymax : Maximum frequency
82
    --ymin : Minimum frequency
83
    --output : Output image file
84
    --title : Plot title
85
    --legend : Show legend
86
    """
87

88
def phonopy_pdosplot():
89
    """
90
    Plot projected density of states from projected_dos.dat.
91
    
92
    Usage:
93
    phonopy-pdosplot [options] [projected_dos.dat]
94
    
95
    Options:
96
    --factor : Unit conversion factor
97
    --xlabel : X-axis label
98
    --ylabel : Y-axis label
99
    --fmax : Maximum frequency
100
    --fmin : Minimum frequency
101
    --output : Output image file
102
    --title : Plot title
103
    --legend : Show legend
104
    --stack : Stacked plot
105
    """
106

107
def phonopy_propplot():
108
    """
109
    Plot thermal properties from thermal_properties.yaml.
110
    
111
    Usage:
112
    phonopy-propplot [options] [thermal_properties.yaml]
113
    
114
    Options:
115
    --factor : Unit conversion factor
116
    --xlabel : X-axis label
117
    --ylabel : Y-axis label
118
    --tmax : Maximum temperature
119
    --tmin : Minimum temperature
120
    --output : Output image file
121
    --title : Plot title
122
    """
123

124
def phonopy_tdplot():
125
    """
126
    Plot thermal displacements from thermal_displacements.yaml.
127
    
128
    Usage:
129
    phonopy-tdplot [options] [thermal_displacements.yaml]
130
    
131
    Options:
132
    --factor : Unit conversion factor
133
    --xlabel : X-axis label  
134
    --ylabel : Y-axis label
135
    --tmax : Maximum temperature
136
    --tmin : Minimum temperature
137
    --output : Output image file
138
    --title : Plot title
139
    """
140

141
def phonopy_gruneisenplot():
142
    """
143
    Plot Grüneisen parameters from gruneisen.yaml.
144
    
145
    Usage:
146
    phonopy-gruneisenplot [options] [gruneisen.yaml]
147
    
148
    Options:
149
    --factor : Unit conversion factor
150
    --xlabel : X-axis label
151
    --ylabel : Y-axis label
152
    --fmax : Maximum frequency
153
    --fmin : Minimum frequency  
154
    --output : Output image file
155
    --title : Plot title
156
    """
157
```
158

159
**Plotting Examples:**
160

161
```bash
162
# Plot band structure
163
phonopy-bandplot --output band_structure.png band.yaml
164

165
# Plot density of states with custom range
166
phonopy-pdosplot --fmax 30 --output dos.png projected_dos.dat
167

168
# Plot thermal properties
169
phonopy-propplot --tmax 1000 --output thermal.png thermal_properties.yaml
170

171
# Plot thermal displacements
172
phonopy-tdplot --output td.png thermal_displacements.yaml
173

174
# Plot Grüneisen parameters
175
phonopy-gruneisenplot --output gruneisen.png gruneisen.yaml
176
```
177

178
### Specialized Calculation Scripts
179

180
Dedicated scripts for advanced phonopy calculations.
181

182
```python { .api }
183
def phonopy_gruneisen():
184
    """
185
    Calculate mode Grüneisen parameters.
186
    
187
    Usage:
188
    phonopy-gruneisen [options] phonopy_V0.yaml phonopy_V+.yaml phonopy_V-.yaml
189
    
190
    Options:
191
    --band : Band structure path
192
    --mesh : Mesh sampling  
193
    --output-yaml : Output YAML file
194
    --output-hdf5 : Output HDF5 file
195
    --factor : Unit conversion factor
196
    --temperature : Temperature for average
197
    """
198

199
def phonopy_qha():
200
    """
201
    Quasi-harmonic approximation calculation.
202
    
203
    Usage:
204
    phonopy-qha [options] e-v.dat thermal_properties-V1.yaml [thermal_properties-V2.yaml ...]
205
    
206
    Options:
207
    --tmax : Maximum temperature
208
    --eos : Equation of state (vinet, murnaghan, etc.)
209
    --pressure : Applied pressure
210
    --sparse : Sparse temperature sampling
211
    --output : Output file prefix
212
    --plot : Generate plots
213
    """
214
```
215

216
**Advanced Calculation Examples:**
217

218
```bash
219
# Calculate Grüneisen parameters
220
phonopy-gruneisen --mesh="20 20 20" phonopy_V0.yaml phonopy_V+.yaml phonopy_V-.yaml
221

222
# Quasi-harmonic approximation
223
phonopy-qha --tmax 1000 --eos vinet e-v.dat thermal_properties-*.yaml
224

225
# QHA with plotting
226
phonopy-qha --plot --output qha_results e-v.dat thermal_properties-*.yaml
227
```
228

229
### File Format Conversion Utilities
230

231
Convert between different calculator formats and file types.
232

233
```python { .api }
234
def phonopy_calc_convert():
235
    """
236
    Convert between different calculator file formats.
237
    
238
    Usage:
239
    phonopy-calc-convert [options] input_file
240
    
241
    Options:
242
    --from : Input calculator format
243
    --to : Output calculator format  
244
    --output : Output filename
245
    --cell : Unit cell file
246
    --supercell : Supercell file
247
    """
248

249
def create_FORCE_SETS():
250
    """
251
    Create FORCE_SETS file from calculator output files.
252
    
253
    Usage:
254
    phonopy-create-force-sets [options] disp.yaml vasprun-{001,002,...}.xml
255
    
256
    Options:
257
    --calculator : Calculator type (vasp, qe, etc.)
258
    --prefix : File prefix for force files
259
    --suffix : File suffix for force files
260
    --zero : Include zero displacement calculation
261
    """
262
```
263

264
**Conversion Examples:**
265

266
```bash
267
# Convert VASP POSCAR to Quantum ESPRESSO
268
phonopy-calc-convert --from vasp --to qe --output pw.in POSCAR
269

270
# Create FORCE_SETS from VASP calculations
271
phonopy-create-force-sets --calculator vasp disp.yaml vasprun-*.xml
272

273
# Create FORCE_SETS from QE calculations
274
phonopy-create-force-sets --calculator qe disp.yaml *.out
275
```
276

277
### Born Effective Charge Utilities
278

279
Extract Born effective charges from calculator output files.
280

281
```python { .api }
282
def phonopy_vasp_born():
283
    """
284
    Extract Born effective charges from VASP output.
285
    
286
    Usage:
287
    phonopy-vasp-born [options] [vasprun.xml] [OUTCAR]
288
    
289
    Options:
290
    --factor : Unit conversion factor
291
    --symprec : Symmetry precision
292
    --output : Output BORN file
293
    """
294

295
def phonopy_qe_born():
296
    """
297
    Extract Born effective charges from Quantum ESPRESSO output.
298
    
299
    Usage:
300
    phonopy-qe-born [options] ph.out
301
    
302
    Options:
303
    --factor : Unit conversion factor
304
    --symprec : Symmetry precision
305
    --output : Output BORN file
306
    """
307

308
def phonopy_crystal_born():
309
    """
310
    Extract Born effective charges from CRYSTAL output.
311
    
312
    Usage:
313
    phonopy-crystal-born [options] crystal.out
314
    
315
    Options:
316
    --factor : Unit conversion factor
317
    --output : Output BORN file
318
    """
319
```
320

321
**Born Charge Examples:**
322

323
```bash
324
# Extract from VASP
325
phonopy-vasp-born --output BORN vasprun.xml OUTCAR
326

327
# Extract from Quantum ESPRESSO
328
phonopy-qe-born --output BORN ph.out
329

330
# Extract from CRYSTAL
331
phonopy-crystal-born --output BORN crystal.out
332
```
333

334
### Data Loading and Analysis
335

336
Load and analyze phonopy data from files.
337

338
```python { .api }
339
def phonopy_load():
340
    """
341
    Load phonopy data and perform basic analysis.
342
    
343
    Usage:
344
    phonopy-load [options] phonopy.yaml
345
    
346
    Options:
347
    --band : Calculate band structure
348
    --mesh : Calculate mesh
349
    --dos : Calculate density of states
350
    --thermal : Calculate thermal properties
351
    --temperature : Temperature range
352
    --output : Output prefix
353
    """
354
```
355

356
**Loading Examples:**
357

358
```bash
359
# Load and calculate band structure
360
phonopy-load --band band.conf phonopy.yaml
361

362
# Load and calculate thermal properties
363
phonopy-load --mesh="20 20 20" --thermal --temperature="0 1000 10" phonopy.yaml
364
```
365

366
### Force Constant Utilities
367

368
Handle force constants files and calculations.
369

370
```python { .api }
371
def phonopy_vasp_efe():
372
    """
373
    Extract effective force from VASP calculations.
374
    
375
    Usage:
376
    phonopy-vasp-efe [options] vasprun.xml
377
    
378
    Options:
379
    --forces : Output forces file
380
    --born : Include Born effective charges
381
    --epsilon : Include dielectric tensor
382
    """
383
```
384

385
## Complete Command-line Workflows
386

387
### Basic Phonopy Workflow
388

389
```bash
390
# 1. Generate displacement structures
391
phonopy --dim="2 2 2" -d POSCAR
392
# Creates: SPOSCAR, disp.yaml, and POSCAR-{001,002,...}
393

394
# 2. Run DFT calculations for each POSCAR-* file
395
# (External step using VASP, QE, etc.)
396

397
# 3. Create FORCE_SETS from DFT outputs
398
phonopy-create-force-sets --calculator vasp disp.yaml vasprun-*.xml
399

400
# 4. Calculate phonon properties
401
phonopy --dim="2 2 2" --mesh="20 20 20" --dos POSCAR
402
phonopy --dim="2 2 2" --band="band.conf" POSCAR
403
phonopy --dim="2 2 2" --mesh="20 20 20" --thermal POSCAR
404

405
# 5. Plot results
406
phonopy-bandplot band.yaml
407
phonopy-pdosplot projected_dos.dat
408
phonopy-propplot thermal_properties.yaml
409
```
410

411
### Advanced Analysis Workflow
412

413
```bash
414
# 1. Basic phonopy setup
415
phonopy --dim="2 2 2" --save-params POSCAR
416

417
# 2. Calculate with NAC (for polar materials)
418
phonopy-vasp-born vasprun.xml OUTCAR  # Extract Born charges
419
phonopy --dim="2 2 2" --nac --mesh="20 20 20" --dos POSCAR
420

421
# 3. Grüneisen parameter analysis
422
# (Requires calculations at multiple volumes)
423
phonopy-gruneisen --mesh="20 20 20" phonopy_V0.yaml phonopy_V+.yaml phonopy_V-.yaml
424
phonopy-gruneisenplot gruneisen.yaml
425

426
# 4. Quasi-harmonic approximation
427
phonopy-qha --tmax 1000 --plot e-v.dat thermal_properties-V*.yaml
428

429
# 5. Generate comprehensive plots
430
phonopy-bandplot --output band.png band.yaml
431
phonopy-pdosplot --output dos.png --stack projected_dos.dat
432
phonopy-propplot --output thermal.png thermal_properties.yaml
433
```
434

435
### Multi-Calculator Workflow
436

437
```bash
438
# 1. Convert structure between formats
439
phonopy-calc-convert --from vasp --to qe --output pw.in POSCAR
440

441
# 2. Generate displacements
442
phonopy --dim="2 2 2" -d --calculator qe pw.in
443

444
# 3. After QE calculations, create force sets
445
phonopy-create-force-sets --calculator qe disp.yaml *.out
446

447
# 4. Extract Born charges from QE
448
phonopy-qe-born --output BORN ph.out
449

450
# 5. Run phonopy analysis
451
phonopy --dim="2 2 2" --nac --mesh="20 20 20" --thermal pw.in
452
```
453

454
### Automation and Scripting
455

456
```bash
457
#!/bin/bash
458
# Complete phonopy automation script
459

460
STRUCTURE="POSCAR"
461
SUPERCELL="2 2 2"
462
MESH="20 20 20"
463

464
echo "Setting up phonopy calculation..."
465
phonopy --dim="$SUPERCELL" -d $STRUCTURE
466

467
echo "Running DFT calculations..."
468
# Loop through displacement structures
469
for i in POSCAR-*; do
470
    # Run your DFT calculation here
471
    echo "Processing $i"
472
done
473

474
echo "Creating FORCE_SETS..."
475
phonopy-create-force-sets --calculator vasp disp.yaml vasprun-*.xml
476

477
echo "Extracting Born charges..."
478
phonopy-vasp-born --output BORN vasprun.xml OUTCAR
479

480
echo "Running phonopy analysis..."
481
phonopy --dim="$SUPERCELL" --nac --mesh="$MESH" --dos --thermal $STRUCTURE
482
phonopy --dim="$SUPERCELL" --nac --band="band.conf" $STRUCTURE
483

484
echo "Generating plots..."
485
phonopy-bandplot --output band_structure.png band.yaml
486
phonopy-pdosplot --output dos.png projected_dos.dat
487
phonopy-propplot --output thermal_props.png thermal_properties.yaml
488

489
echo "Phonopy analysis complete!"
490
```
491

492
### Configuration Files
493

494
Most phonopy command-line tools support configuration files for complex setups:
495

496
**band.conf** (Band structure paths):
497
```
498
BAND = 0.0 0.0 0.0  0.5 0.0 0.5  0.5 0.25 0.75  0.0 0.0 0.0
499
BAND_LABELS = Gamma X W Gamma
500
```
501

502
**mesh.conf** (Mesh configuration):
503
```
504
MESH = 20 20 20
505
GAMMA_CENTER = .TRUE.
506
```
507

508
**phonopy.conf** (General configuration):
509
```
510
DIM = 2 2 2
511
PRIMITIVE_AXIS = AUTO
512
MESH = 20 20 20
513
DOS = .TRUE.
514
THERMAL = .TRUE.
515
TEMPERATURE = 0 1000 10
516
NAC = .TRUE.
517
```
518

519
Usage with configuration:
520
```bash
521
phonopy --config phonopy.conf POSCAR
522
```
523

524
## Error Handling and Troubleshooting
525

526
Common command-line issues and solutions:
527

528
```bash
529
# Check phonopy installation and version
530
phonopy --version
531

532
# Verbose output for debugging  
533
phonopy --verbose --dim="2 2 2" POSCAR
534

535
# Check symmetry detection
536
phonopy --dim="2 2 2" --symmetry POSCAR
537

538
# Validate force constants
539
phonopy --dim="2 2 2" --readfc --check-symmetry POSCAR
540

541
# Test different symmetry precision
542
phonopy --dim="2 2 2" --symprec=1e-3 POSCAR
543
```