tessl/pypi-phonopy

Comprehensive Python library for phonon calculations that enables lattice dynamics simulations and vibrational property analysis of crystalline materials.

—

Pending

Overview

Eval results

Files

Command-line Tools

Name: tessl/pypi-phonopy
Author: tessl

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.

Capabilities

Main Phonopy Command

Primary command-line interface for phonopy calculations and analysis.

def main():
    """
    Main phonopy command-line interface.
    
    Usage:
    phonopy [options] [unitcell_filename]
    
    Key Options:
    --dim="nx ny nz" : Supercell dimensions
    --pa="matrix" : Primitive matrix  
    --band="path" : Band structure calculation
    --mesh="nx ny nz" : Mesh sampling
    --dos : Calculate density of states
    --thermal : Calculate thermal properties
    --temperature="min max step" : Temperature range
    --save-params : Save parameters to phonopy.yaml
    --writefc : Write force constants
    --readfc : Read force constants
    --writedm : Write dynamical matrices
    --nac : Use non-analytical correction
    --q-direction : q-vector direction for NAC
    --factor : Frequency unit conversion factor
    --symprec : Symmetry precision
    --tolerance : Symmetry tolerance
    --calculator : Calculator interface
    --config : Configuration file
    """

Common Usage Examples:

# Basic phonopy run with supercell
phonopy --dim="2 2 2" POSCAR

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

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

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

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

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

# Use non-analytical correction
phonopy --dim="2 2 2" --nac --mesh="20 20 20" POSCAR

Plotting Utilities

Specialized plotting tools for visualizing phonopy results.

def phonopy_bandplot():
    """
    Plot phonon band structure from band.yaml file.
    
    Usage:
    phonopy-bandplot [options] [band.yaml]
    
    Options:
    --factor : Unit conversion factor
    --xlabel : X-axis label
    --ylabel : Y-axis label  
    --ymax : Maximum frequency
    --ymin : Minimum frequency
    --output : Output image file
    --title : Plot title
    --legend : Show legend
    """

def phonopy_pdosplot():
    """
    Plot projected density of states from projected_dos.dat.
    
    Usage:
    phonopy-pdosplot [options] [projected_dos.dat]
    
    Options:
    --factor : Unit conversion factor
    --xlabel : X-axis label
    --ylabel : Y-axis label
    --fmax : Maximum frequency
    --fmin : Minimum frequency
    --output : Output image file
    --title : Plot title
    --legend : Show legend
    --stack : Stacked plot
    """

def phonopy_propplot():
    """
    Plot thermal properties from thermal_properties.yaml.
    
    Usage:
    phonopy-propplot [options] [thermal_properties.yaml]
    
    Options:
    --factor : Unit conversion factor
    --xlabel : X-axis label
    --ylabel : Y-axis label
    --tmax : Maximum temperature
    --tmin : Minimum temperature
    --output : Output image file
    --title : Plot title
    """

def phonopy_tdplot():
    """
    Plot thermal displacements from thermal_displacements.yaml.
    
    Usage:
    phonopy-tdplot [options] [thermal_displacements.yaml]
    
    Options:
    --factor : Unit conversion factor
    --xlabel : X-axis label  
    --ylabel : Y-axis label
    --tmax : Maximum temperature
    --tmin : Minimum temperature
    --output : Output image file
    --title : Plot title
    """

def phonopy_gruneisenplot():
    """
    Plot Grüneisen parameters from gruneisen.yaml.
    
    Usage:
    phonopy-gruneisenplot [options] [gruneisen.yaml]
    
    Options:
    --factor : Unit conversion factor
    --xlabel : X-axis label
    --ylabel : Y-axis label
    --fmax : Maximum frequency
    --fmin : Minimum frequency  
    --output : Output image file
    --title : Plot title
    """

Plotting Examples:

# Plot band structure
phonopy-bandplot --output band_structure.png band.yaml

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

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

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

# Plot Grüneisen parameters
phonopy-gruneisenplot --output gruneisen.png gruneisen.yaml

Specialized Calculation Scripts

Dedicated scripts for advanced phonopy calculations.

def phonopy_gruneisen():
    """
    Calculate mode Grüneisen parameters.
    
    Usage:
    phonopy-gruneisen [options] phonopy_V0.yaml phonopy_V+.yaml phonopy_V-.yaml
    
    Options:
    --band : Band structure path
    --mesh : Mesh sampling  
    --output-yaml : Output YAML file
    --output-hdf5 : Output HDF5 file
    --factor : Unit conversion factor
    --temperature : Temperature for average
    """

def phonopy_qha():
    """
    Quasi-harmonic approximation calculation.
    
    Usage:
    phonopy-qha [options] e-v.dat thermal_properties-V1.yaml [thermal_properties-V2.yaml ...]
    
    Options:
    --tmax : Maximum temperature
    --eos : Equation of state (vinet, murnaghan, etc.)
    --pressure : Applied pressure
    --sparse : Sparse temperature sampling
    --output : Output file prefix
    --plot : Generate plots
    """

Advanced Calculation Examples:

# Calculate Grüneisen parameters
phonopy-gruneisen --mesh="20 20 20" phonopy_V0.yaml phonopy_V+.yaml phonopy_V-.yaml

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

# QHA with plotting
phonopy-qha --plot --output qha_results e-v.dat thermal_properties-*.yaml

File Format Conversion Utilities

Convert between different calculator formats and file types.

def phonopy_calc_convert():
    """
    Convert between different calculator file formats.
    
    Usage:
    phonopy-calc-convert [options] input_file
    
    Options:
    --from : Input calculator format
    --to : Output calculator format  
    --output : Output filename
    --cell : Unit cell file
    --supercell : Supercell file
    """

def create_FORCE_SETS():
    """
    Create FORCE_SETS file from calculator output files.
    
    Usage:
    phonopy-create-force-sets [options] disp.yaml vasprun-{001,002,...}.xml
    
    Options:
    --calculator : Calculator type (vasp, qe, etc.)
    --prefix : File prefix for force files
    --suffix : File suffix for force files
    --zero : Include zero displacement calculation
    """

Conversion Examples:

# Convert VASP POSCAR to Quantum ESPRESSO
phonopy-calc-convert --from vasp --to qe --output pw.in POSCAR

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

# Create FORCE_SETS from QE calculations
phonopy-create-force-sets --calculator qe disp.yaml *.out

Born Effective Charge Utilities

Extract Born effective charges from calculator output files.

def phonopy_vasp_born():
    """
    Extract Born effective charges from VASP output.
    
    Usage:
    phonopy-vasp-born [options] [vasprun.xml] [OUTCAR]
    
    Options:
    --factor : Unit conversion factor
    --symprec : Symmetry precision
    --output : Output BORN file
    """

def phonopy_qe_born():
    """
    Extract Born effective charges from Quantum ESPRESSO output.
    
    Usage:
    phonopy-qe-born [options] ph.out
    
    Options:
    --factor : Unit conversion factor
    --symprec : Symmetry precision
    --output : Output BORN file
    """

def phonopy_crystal_born():
    """
    Extract Born effective charges from CRYSTAL output.
    
    Usage:
    phonopy-crystal-born [options] crystal.out
    
    Options:
    --factor : Unit conversion factor
    --output : Output BORN file
    """

Born Charge Examples:

# Extract from VASP
phonopy-vasp-born --output BORN vasprun.xml OUTCAR

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

# Extract from CRYSTAL
phonopy-crystal-born --output BORN crystal.out

Data Loading and Analysis

Load and analyze phonopy data from files.

def phonopy_load():
    """
    Load phonopy data and perform basic analysis.
    
    Usage:
    phonopy-load [options] phonopy.yaml
    
    Options:
    --band : Calculate band structure
    --mesh : Calculate mesh
    --dos : Calculate density of states
    --thermal : Calculate thermal properties
    --temperature : Temperature range
    --output : Output prefix
    """

Loading Examples:

# Load and calculate band structure
phonopy-load --band band.conf phonopy.yaml

# Load and calculate thermal properties
phonopy-load --mesh="20 20 20" --thermal --temperature="0 1000 10" phonopy.yaml

Force Constant Utilities

Handle force constants files and calculations.

def phonopy_vasp_efe():
    """
    Extract effective force from VASP calculations.
    
    Usage:
    phonopy-vasp-efe [options] vasprun.xml
    
    Options:
    --forces : Output forces file
    --born : Include Born effective charges
    --epsilon : Include dielectric tensor
    """

Complete Command-line Workflows

Basic Phonopy Workflow

# 1. Generate displacement structures
phonopy --dim="2 2 2" -d POSCAR
# Creates: SPOSCAR, disp.yaml, and POSCAR-{001,002,...}

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

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

# 4. Calculate phonon properties
phonopy --dim="2 2 2" --mesh="20 20 20" --dos POSCAR
phonopy --dim="2 2 2" --band="band.conf" POSCAR
phonopy --dim="2 2 2" --mesh="20 20 20" --thermal POSCAR

# 5. Plot results
phonopy-bandplot band.yaml
phonopy-pdosplot projected_dos.dat
phonopy-propplot thermal_properties.yaml

Advanced Analysis Workflow

# 1. Basic phonopy setup
phonopy --dim="2 2 2" --save-params POSCAR

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

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

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

# 5. Generate comprehensive plots
phonopy-bandplot --output band.png band.yaml
phonopy-pdosplot --output dos.png --stack projected_dos.dat
phonopy-propplot --output thermal.png thermal_properties.yaml

Multi-Calculator Workflow

# 1. Convert structure between formats
phonopy-calc-convert --from vasp --to qe --output pw.in POSCAR

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

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

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

# 5. Run phonopy analysis
phonopy --dim="2 2 2" --nac --mesh="20 20 20" --thermal pw.in

Automation and Scripting

#!/bin/bash
# Complete phonopy automation script

STRUCTURE="POSCAR"
SUPERCELL="2 2 2"
MESH="20 20 20"

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

echo "Running DFT calculations..."
# Loop through displacement structures
for i in POSCAR-*; do
    # Run your DFT calculation here
    echo "Processing $i"
done

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

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

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

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

echo "Phonopy analysis complete!"

Configuration Files

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

band.conf (Band structure paths):

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
BAND_LABELS = Gamma X W Gamma

mesh.conf (Mesh configuration):

MESH = 20 20 20
GAMMA_CENTER = .TRUE.

phonopy.conf (General configuration):

DIM = 2 2 2
PRIMITIVE_AXIS = AUTO
MESH = 20 20 20
DOS = .TRUE.
THERMAL = .TRUE.
TEMPERATURE = 0 1000 10
NAC = .TRUE.

Usage with configuration:

phonopy --config phonopy.conf POSCAR

Error Handling and Troubleshooting

Common command-line issues and solutions:

# Check phonopy installation and version
phonopy --version

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

# Check symmetry detection
phonopy --dim="2 2 2" --symmetry POSCAR

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

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

Install with Tessl CLI