symphon

A simple wrapper of the phonopy irreps module for finding irreducible representations of phonon modes in ABINIT's anaddb output.

Features

• Automatic high-symmetry analysis: Analyzes all high-symmetry k-points (GM, X, M, R, etc.) automatically
• Dual-label display at Gamma: Shows both Mulliken (T1u, Eg, etc.) and BCS (GM4-, GM5+, etc.) notation side-by-side
• Spectroscopic activity: Identifies IR- and Raman-active modes at Γ point
• Multiple input formats: Supports both anaddb PHBST NetCDF files and phonopy params/YAML files
• Dual backend support:
  • phonopy backend: Γ-point analysis with IR/Raman activity (used automatically at Gamma)
  • irrep backend: Non-Gamma point analysis using the irrep package (used automatically for other points)
• CLI and Python API: Flexible usage through command-line tools or Python functions
• Complete symmetry information: Reports both space group and point group for the crystal

Installation

Basic Installation

Install from PyPI:

pip install symphon

Optional Dependencies

For non-Gamma phonons (k-points other than Γ), install with the irrep backend:

pip install "symphon[irrep]"

For ABINIT support (reading PHBST NetCDF files), install with the abipy optional dependency:

pip install "symphon[abipy]"

To install all optional dependencies:

pip install "symphon[irrep,abipy]"

Documentation

• Usage Guide: Complete API and CLI reference with examples for all features
• Irreducible Representation Labeling Guide: Mathematical foundations, Mulliken notation, and tutorial for non-Gamma phonons (e.g., X and M points in BaTiO3)
• IR and Raman Activity Methodology: Scientific guide to the group-theoretical method used to identify spectroscopic activity, with TmFeO3 case study

Quick Start

Python API

from symphon import print_irreps_phonopy

# Analyze any q-point (backend auto-selected)
print_irreps_phonopy("phonopy_params.yaml", qpoint=[0, 0, 0])  # Gamma
print_irreps_phonopy("phonopy_params.yaml", qpoint=[0.5, 0.5, 0])  # M point

Command Line

Unified CLI (symphon)

All functionality is available through the unified symphon CLI:

# Phonon irreps from phonopy (auto-discovers all high-symmetry k-points)
symphon phonopy-irreps --params phonopy_params.yaml

# Phonon irreps from anaddb (auto-discovers high-symmetry q-points)
symphon anaddb-irreps --phbst run_PHBST.nc

# With chiral transition analysis
symphon phonopy-irreps --params phonopy_params.yaml --chiral

# Find chiral phase transitions from space groups
symphon find-chiral-transition --sg 136

# Magnetic chirality analysis
symphon magnetic-chiral --structure POSCAR --qpoint 0 0 0.5 --mag-sites 0,1
symphon abstract-magnetic --spg 221 --qpoint 0 0 0
symphon msg 18.16

phonopy-irreps (Auto-discovery mode)

# Analyze all high-symmetry k-points automatically
symphon phonopy-irreps --params phonopy_params.yaml

# Output shows all high-symmetry points:
# - GM point: dual labels (Mulliken + BCS) + IR/Raman activity
# - Other points (M, R, X, etc.): BCS labels

anaddb-irreps (Auto-discovery or manual mode)

# Auto-discover all high-symmetry q-points (using standalone command)
anaddb-irreps --phbst run_PHBST.nc

# Or using unified CLI
symphon anaddb-irreps --phbst run_PHBST.nc

# Or analyze specific q-point (0-based index)
symphon anaddb-irreps --phbst run_PHBST.nc --q-index 0

Output Examples

Automatic high-symmetry analysis (phonopy-irreps)

When you run phonopy-irreps --params phonopy_params.yaml, it automatically:

1. Discovers all high-symmetry k-points from the space group
2. Shows dual labels (Mulliken + BCS) at Gamma point with IR/Raman activity
3. Shows BCS labels for other high-symmetry points

Space group: Pm-3m
Found 4 high-symmetry points:
  GM: k=(0.0, 0.0, 0.0)
  M: k=(0.5, 0.5, 0.0)
  R: k=(0.5, 0.5, 0.5)
  X: k=(0.0, 0.5, 0.0)

# GM point (k=(0.0, 0.0, 0.0))
============================================================
q-point: [0.0000, 0.0000, 0.0000]
Space group: Pm-3m
Point group: m-3m

# qx      qy      qz      band  freq(THz)   freq(cm-1)   label(M)   label(BCS)  IR  Raman
 0.0000  0.0000  0.0000     0     -6.0487      -201.76  T1u         GM4-         Y    .  
 0.0000  0.0000  0.0000     9      8.5335       284.65  T2u         GM5-         .    .  

# X point (k=(0.0, 0.5, 0.0))
============================================================
q-point: [0.0000, 0.5000, 0.0000]
Space group: Pm-3m
Point group: m-3m

# qx      qy      qz      band  freq(THz)   freq(cm-1)   label
 0.0000  0.5000  0.0000     0     -4.8804      -162.79  X5+
 0.0000  0.5000  0.0000     2      3.3171       110.65  X5-

Examples

See examples/MoS2_1T/ for a complete working example with MoS2 1T structure using anaddb output.

See docs/irreps_guide.md for BaTiO3 examples demonstrating both Gamma and non-Gamma point analysis.

Technical Notes

K-point Coordinate Systems

The irrep backend requires careful handling of k-point coordinates:

• irreptables package: Provides k-points in reference unit cell coordinates
• irrep package: Expects k-points in primitive unit cell coordinates

For certain space groups, a coordinate transformation is required. Currently implemented:

• Pnma (space group 62): Cyclic permutation k_prim = (k_z, k_x, k_y)
  • Transformation matrix: [[0,0,1], [1,0,0], [0,1,0]]
  • Verified with TmFeO3 structure (all 8 high-symmetry points work correctly)

Symmetry Precision

The symprec parameter controls tolerance for symmetry detection and atom mapping:

• Default: 1e-5 (standard phonopy default)
• Both phonopy and irrep backends now use the same symprec value consistently
• For low-symmetry or distorted structures, increase symprec (e.g., 1e-2 or 1e-3)

License

BSD-2-clause