phononkit 0.1.0__py3-none-any.whl

phononkit/__init__.py

@@ -0,0 +1,169 @@
+"""phononkit - A clean, modular Python library for phonon analysis.
+
+This package provides tools for:
+- Phonon mode representation and analysis
+- Displacement generation and projections
+- Supercell operations with commensurate q-points
+- Structure analysis and symmetry
+- Data I/O (MCIF export, phonopy integration)
+
+The package is organized into domain-driven modules:
+- core: Type definitions and constants
+- qpoints: Q-point mathematics and grids
+- modes: Phonon mode representation
+- displacements: Displacement generation
+- projections: Mass-weighted projections
+- supercells: Supercell operations
+- analysis: Structure analysis and symmetry
+- io: Data import/export
+
+All modules follow single responsibility principle (< 500 lines per file)
+and strict layering with no circular dependencies.
+"""
+
+__version__ = "0.1.0"
+
+from typing import Optional, List
+
+from phononkit.modes import PhononMode, PhononModeCollection
+from phononkit.displacements import (
+    generate_displacement,
+    generate_displaced_structure,
+    generate_mode_displacement,
+    generate_thermal_displacement,
+    generate_thermal_structure,
+)
+from phononkit.io import (
+    load_from_phonopy_yaml,
+    create_mode_from_phonopy_data,
+    export_to_mcif,
+    save_mcif_file,
+)
+from phononkit.supercells import (
+    build_supercell,
+    build_supercell_for_qpoint,
+    create_supercell_mode,
+)
+from phononkit.qpoints import (
+    is_commensurate_qpoint,
+    find_commensurate_qpoints,
+    validate_supercell_commensurability,
+)
+
+
+def generate_structure_for_mode(
+    yaml_path: str,
+    qpoint: List,
+    mode_index: int,
+    amplitude: float = 1.0,
+    supercell: Optional[List] = None,
+):
+    """Generate displaced structure for a specific phonon mode.
+
+    Simple one-function API to load phonon data and generate a displaced
+    structure for a specific mode at a given q-point, optionally in a supercell.
+
+    Parameters:
+        yaml_path: Path to phonopy YAML file
+        qpoint: Q-point coordinates [qx, qy, qz] (e.g., [0, 0, 0] for Gamma)
+        mode_index: Index of the mode at that q-point (0-based)
+        amplitude: Displacement amplitude in Angstroms (default: 1.0)
+        supercell: Supercell specification (optional):
+            - 3-vector [n1, n2, n3] for diagonal matrix (e.g., [2, 2, 2])
+            - Full 3x3 matrix [[n1, 0, 0], [0, n2, 0], [0, 0, n3]]
+            If None, uses primitive cell
+
+    Returns:
+        ASE Atoms object with displacements applied
+
+    Examples:
+        >>> # Primitive cell - 3rd mode at Gamma with 0.5 Å amplitude
+        >>> structure = generate_structure_for_mode(
+        ...     'phonopy_params.yaml',
+        ...     qpoint=[0, 0, 0],
+        ...     mode_index=2,
+        ...     amplitude=0.5
+        ... )
+
+        >>> # 2x2x2 Supercell using diagonal notation
+        >>> structure = generate_structure_for_mode(
+        ...     'phonopy_params.yaml',
+        ...     qpoint=[0, 0, 0],
+        ...     mode_index=2,
+        ...     amplitude=0.5,
+        ...     supercell=[2, 2, 2]
+        ... )
+
+        >>> # Save to file
+        >>> from ase.io import write
+        >>> write('displaced.vasp', structure)
+    """
+    import numpy as np
+
+    # Load phonon data
+    primitive_structure, modes = load_from_phonopy_yaml(yaml_path)
+
+    # Filter modes by q-point
+    qpoint_array = np.array(qpoint)
+    qpoint_modes = modes.filter_by_qpoint(qpoint_array)
+
+    # Check if mode_index is valid
+    if mode_index >= qpoint_modes.n_modes:
+        raise ValueError(
+            f"Mode index {mode_index} out of range. "
+            f"Only {qpoint_modes.n_modes} modes at q-point {qpoint}."
+        )
+
+    # Select the mode
+    selected_mode = qpoint_modes[mode_index]
+
+    # Handle supercell
+    if supercell is not None:
+        supercell_array = np.array(supercell)
+
+        # Convert 3-vector to 3x3 diagonal matrix
+        if supercell_array.ndim == 1 and len(supercell_array) == 3:
+            supercell_matrix = np.diag(supercell_array)
+        elif supercell_array.shape == (3, 3):
+            supercell_matrix = supercell_array
+        else:
+            raise ValueError(
+                f"Invalid supercell format. "
+                f"Expected 3-vector [n1,n2,n3] or 3x3 matrix, got {supercell}"
+            )
+
+        # Create supercell mode (handles tiling and phase factors)
+        from phononkit.supercells import create_supercell_mode
+
+        supercell_mode = create_supercell_mode(selected_mode, supercell_matrix)
+
+        # Generate displacement for supercell mode
+        displaced_structure = generate_mode_displacement(supercell_mode, amplitude)
+    else:
+        # Use primitive mode directly
+        displaced_structure = generate_mode_displacement(selected_mode, amplitude)
+
+    return displaced_structure
+
+
+__all__ = [
+    "__version__",
+    "PhononMode",
+    "PhononModeCollection",
+    "generate_structure_for_mode",  # Simple API
+    "generate_displacement",
+    "generate_displaced_structure",
+    "generate_mode_displacement",
+    "generate_thermal_displacement",
+    "generate_thermal_structure",
+    "load_from_phonopy_yaml",
+    "create_mode_from_phonopy_data",
+    "export_to_mcif",
+    "save_mcif_file",
+    "build_supercell",
+    "build_supercell_for_qpoint",
+    "create_supercell_mode",
+    "is_commensurate_qpoint",
+    "find_commensurate_qpoints",
+    "validate_supercell_commensurability",
+]

phononkit/analysis/__init__.py

@@ -0,0 +1,37 @@
+"""Structure analysis, species substitution, and symmetry.
+
+This module provides:
+- Atomic correspondence between structures
+- Species substitution handling
+- Symmetry analysis and irreducible representations
+"""
+
+from phononkit.analysis.structure import (
+    find_atomic_correspondence,
+    apply_atomic_mapping,
+)
+from phononkit.analysis.substitution import (
+    create_substitution_map,
+    validate_substitution,
+)
+from phononkit.analysis.symmetry import (
+    find_degenerate_modes,
+    classify_mode_symmetry,
+    generate_mode_summary,
+)
+from phononkit.analysis.irreps import (
+    analyze_irreps,
+    IrRepsEigen,
+)
+
+__all__ = [
+    "find_atomic_correspondence",
+    "apply_atomic_mapping",
+    "create_substitution_map",
+    "validate_substitution",
+    "find_degenerate_modes",
+    "classify_mode_symmetry",
+    "generate_mode_summary",
+    "analyze_irreps",
+    "IrRepsEigen",
+]

phononkit/analysis/irreps.py

@@ -0,0 +1,399 @@
+"""Irreducible representations (irreps) analysis for phonon modes.
+
+This module provides functionality for identifying symmetry labels (irreps)
+for phonon modes, adapted from the better implementation in anaddb_irreps.
+"""
+
+import contextlib
+import numpy as np
+from io import StringIO
+from typing import List, Optional, Tuple, Dict, Any
+
+from ase import Atoms
+from phonopy.phonon.irreps import IrReps, IrRepLabels
+from phonopy.structure.symmetry import Symmetry
+from phonopy.phonon.character_table import character_table
+from phonopy.phonon.degeneracy import degenerate_sets as get_degenerate_sets
+from phonopy.structure.cells import is_primitive_cell
+from phonopy import load as phonopy_load
+
+
+class IrRepsEigen(IrReps, IrRepLabels):
+    """Irreducible representations analysis from provided eigenvalues/vectors.
+
+    This class extends phonopy's IrReps and IrRepLabels to work with
+    already calculated frequencies and eigenvectors.
+    """
+
+    def __init__(
+        self,
+        primitive_atoms,
+        qpoint,
+        freqs,
+        eigvecs,
+        is_little_cogroup: bool = False,
+        symprec: float = 1e-5,
+        degeneracy_tolerance: float = 1e-5,
+        log_level: int = 0,
+    ) -> None:
+        """Initialize IrRepsEigen.
+
+        Parameters:
+            primitive_atoms: Phonopy Atoms object (primitive cell)
+            qpoint: Q-point in reduced coordinates
+            freqs: Frequencies at this q-point (THz)
+            eigvecs: Eigenvectors at this q-point
+            is_little_cogroup: Whether to use little co-group
+            symprec: Symmetry precision
+            degeneracy_tolerance: Tolerance for degeneracy detection
+            log_level: Verbosity level
+        """
+        self._is_little_cogroup = is_little_cogroup
+        self._log_level = log_level
+
+        self._qpoint = np.array(qpoint)
+        self._degeneracy_tolerance = degeneracy_tolerance
+        self._symprec = symprec
+        self._primitive = primitive_atoms
+        self._freqs, self._eig_vecs = freqs, eigvecs
+        self._character_table = None
+        self._verbose = False
+
+    def run(self) -> bool:
+        """Run the irreps analysis."""
+        self._symmetry_dataset = Symmetry(
+            self._primitive, symprec=self._symprec
+        ).dataset
+
+        if not is_primitive_cell(self._symmetry_dataset.rotations):
+            raise RuntimeError(
+                "Non-primitive cell is used. Your unit cell may be transformed to "
+                "a primitive cell by PRIMITIVE_AXIS tag."
+            )
+
+        (self._rotations_at_q, self._translations_at_q) = self._get_rotations_at_q()
+
+        self._g = len(self._rotations_at_q)
+
+        self._pointgroup_symbol = self._symmetry_dataset.pointgroup
+
+        (
+            self._transformation_matrix,
+            self._conventional_rotations,
+        ) = self._get_conventional_rotations()
+
+        self._ground_matrices = self._get_ground_matrix()
+        self._degenerate_sets = self._get_degenerate_sets()
+        self._irreps = self._get_irreps()
+        self._characters, self._irrep_dims = self._get_characters()
+
+        self._ir_labels = None
+
+        if (
+            self._pointgroup_symbol in character_table.keys()
+            and character_table[self._pointgroup_symbol] is not None
+        ):
+            (
+                self._rotation_symbols,
+                character_table_of_ptg,
+            ) = self._get_rotation_symbols(self._pointgroup_symbol)
+            self._character_table = character_table_of_ptg
+
+            if (abs(self._qpoint) < self._symprec).all() and self._rotation_symbols:
+                self._ir_labels = self._get_irrep_labels(character_table_of_ptg)
+                self._RamanIR_labels = self._get_infrared_raman()
+        else:
+            self._rotation_symbols = None
+
+        return True
+
+    def _get_degenerate_sets(self):
+        deg_sets = get_degenerate_sets(self._freqs, cutoff=self._degeneracy_tolerance)
+        return deg_sets
+
+    def _get_infrared_raman(self):
+        """Compute IR- and Raman-active irreps using symmetry operations."""
+        # make symops in cartesian space
+        rprim = self._primitive.cell
+        gprim = np.linalg.inv(rprim).T
+
+        # make cartesian symop matrices for each operation in each class
+        nclass = len(self._character_table["rotation_list"])
+        self._cartesian_rotations_at_q = np.zeros([nclass, 96, 3, 3])
+        degenclass = np.zeros(nclass)
+        characters_xyz = np.zeros(nclass)
+        chardegen_xyz = np.zeros(nclass)
+        characters_x2 = np.zeros(nclass)
+        chardegen_x2 = np.zeros(nclass)
+        iclass = 0
+        for opclass in self._character_table["mapping_table"].keys():
+            degenclass[iclass] = len(self._character_table["mapping_table"][opclass])
+            iop = 0
+            for symop in np.array(self._character_table["mapping_table"][opclass][:]):
+                self._cartesian_rotations_at_q[iclass][iop] = np.dot(
+                    rprim, np.dot(symop, gprim.T)
+                )
+                iop += 1
+
+            m = self._cartesian_rotations_at_q[iclass][0]
+            # get representation characters for x,y,z functions
+            characters_xyz[iclass] = np.matrix.trace(m)
+
+            # get representation characters for quadratic functions
+            bigmat = np.zeros([6, 6])
+            ibig = 0
+            for ixyz in range(3):
+                for ixyz_prime in range(ixyz + 1):
+                    outprod = np.ndarray.flatten(np.outer(m[:, ixyz], m[:, ixyz_prime]))
+                    bigmat[ibig, :] = [
+                        outprod[0],
+                        outprod[1] + outprod[3],
+                        outprod[4],
+                        outprod[2] + outprod[6],
+                        outprod[5] + outprod[7],
+                        outprod[8],
+                    ]
+                    ibig += 1
+
+            characters_x2[iclass] = np.matrix.trace(bigmat)
+            chardegen_xyz[iclass] = characters_xyz[iclass] * degenclass[iclass]
+            chardegen_x2[iclass] = characters_x2[iclass] * degenclass[iclass]
+            iclass += 1
+
+        xyzlabels = ["x", "y", "z"]
+        x2labels = ["x^2", "xy", "y^2", "xz", "yz", "z^2"]
+        IR_dict = {"x": None, "y": None, "z": None}
+        Raman_dict = {"x^2": [], "xy": [], "y^2": [], "xz": [], "yz": [], "z^2": []}
+
+        # loop over irreducible representations
+        for irreplabel in self._character_table["character_table"].keys():
+            irr_char = self._character_table["character_table"][irreplabel]
+            len_irr = irr_char[0]
+            n_ir = int(np.round(np.dot(irr_char, chardegen_xyz) / self._g))
+            n_ram = int(np.round(np.dot(irr_char, chardegen_x2) / self._g))
+
+            for ixyz in range(3):
+                xyzvec = np.zeros(3)
+                for iclass in range(len(self._character_table["mapping_table"].keys())):
+                    opclass = list(self._character_table["mapping_table"].keys())[
+                        iclass
+                    ]
+                    degenclass_val = len(
+                        self._character_table["mapping_table"][opclass][:]
+                    )
+                    for iop in range(degenclass_val):
+                        xyzvec += (
+                            irr_char[iclass]
+                            * self._cartesian_rotations_at_q[iclass][iop][ixyz, :]
+                        )
+                xyzvec *= len_irr / self._g
+                if np.linalg.norm(xyzvec) > 1.0e-6:
+                    IR_dict[xyzlabels[ixyz]] = irreplabel
+
+            ibig = 0
+            for ixyz in range(3):
+                for ixyz_prime in range(ixyz + 1):
+                    x2vec = np.zeros(6)
+                    for iclass in range(
+                        len(self._character_table["mapping_table"].keys())
+                    ):
+                        opclass = list(self._character_table["mapping_table"].keys())[
+                            iclass
+                        ]
+                        degenclass_val = len(
+                            self._character_table["mapping_table"][opclass][:]
+                        )
+                        for iop in range(degenclass_val):
+                            m = self._cartesian_rotations_at_q[iclass][iop]
+                            outprod = np.ndarray.flatten(
+                                np.outer(m[:, ixyz], m[:, ixyz_prime])
+                            )
+                            bigvec = np.array(
+                                [
+                                    outprod[0],
+                                    outprod[1] + outprod[3],
+                                    outprod[4],
+                                    outprod[2] + outprod[6],
+                                    outprod[5] + outprod[7],
+                                    outprod[8],
+                                ]
+                            )
+                            x2vec += irr_char[iclass] * bigvec
+
+                    x2vec *= len_irr / self._g
+                    if np.linalg.norm(x2vec) > 1.0e-6:
+                        Raman_dict[x2labels[ibig]].append(irreplabel)
+                    ibig += 1
+
+        return IR_dict, Raman_dict
+
+    def get_summary_table(self) -> List[Dict[str, Any]]:
+        """Return core mode information as list of dicts."""
+        if not hasattr(self, "_freqs"):
+            raise RuntimeError("run() must be called before get_summary_table().")
+
+        q = tuple(float(x) for x in self._qpoint)
+        freqs_thz = self._freqs
+        conv = 33.35641  # 1 THz -> cm^-1
+        n_modes = len(freqs_thz)
+
+        irreps = getattr(self, "_irreps", None)
+
+        ir_active_map: Dict[str, bool] = {}
+        raman_active_map: Dict[str, bool] = {}
+
+        raman_ir = getattr(self, "_RamanIR_labels", None)
+        if raman_ir is not None:
+            ir_dict, raman_dict = raman_ir
+            for lbl in ir_dict.values():
+                if lbl:
+                    ir_active_map[lbl] = True
+            for labels in raman_dict.values():
+                for lbl in labels:
+                    if lbl:
+                        raman_active_map[lbl] = True
+
+        raw_labels = [None] * n_modes
+        ir_labels_seq = getattr(self, "_ir_labels", None)
+        deg_sets = getattr(self, "_degenerate_sets", None)
+
+        mode_to_degset = {}
+        if deg_sets is not None:
+            for set_idx, deg_set in enumerate(deg_sets):
+                for mode_idx in deg_set:
+                    mode_to_degset[mode_idx] = set_idx
+
+        for band_index in range(n_modes):
+            label = None
+            if irreps is not None and band_index < len(irreps):
+                ir = irreps[band_index]
+                if hasattr(ir, "label"):
+                    label = ir.label
+                elif isinstance(ir, dict) and "label" in ir:
+                    label = ir["label"]
+
+            if label is None and ir_labels_seq is not None:
+                set_idx = mode_to_degset.get(band_index)
+                if set_idx is not None and set_idx < len(ir_labels_seq):
+                    cand = ir_labels_seq[set_idx]
+                    if isinstance(cand, (tuple, list)) and cand:
+                        label = cand[0]
+                    elif isinstance(cand, str):
+                        label = cand
+            raw_labels[band_index] = label
+
+        if deg_sets is not None:
+            for deg_set in deg_sets:
+                labels_in_set = {raw_labels[i] for i in deg_set if raw_labels[i]}
+                if len(labels_in_set) == 1:
+                    lbl = labels_in_set.pop()
+                    for i in deg_set:
+                        raw_labels[i] = lbl
+
+        summary = []
+        for band_index, f_thz in enumerate(freqs_thz):
+            freq_thz = float(f_thz)
+            freq_cm1 = freq_thz * conv
+            label = raw_labels[band_index]
+            is_ir_active = bool(label and ir_active_map.get(label, False))
+            is_raman_active = bool(label and raman_active_map.get(label, False))
+
+            summary.append(
+                {
+                    "qpoint": q,
+                    "band_index": band_index,
+                    "frequency_thz": freq_thz,
+                    "frequency_cm1": freq_cm1,
+                    "label": label,
+                    "is_ir_active": is_ir_active,
+                    "is_raman_active": is_raman_active,
+                }
+            )
+        return summary
+
+    def format_summary_table(self, include_header: bool = True) -> str:
+        """Format the summary table as a human-readable string."""
+        summary = self.get_summary_table()
+        lines = []
+
+        if summary:
+            qx, qy, qz = summary[0]["qpoint"]
+            lines.append(f"q-point: [{qx:.4f}, {qy:.4f}, {qz:.4f}]")
+
+        point_group = getattr(self, "_pointgroup_symbol", None)
+        if point_group:
+            lines.append(f"Point group: {point_group}")
+
+        if lines:
+            lines.append("")
+
+        if include_header:
+            header = "# qx      qy      qz      band  freq(THz)   freq(cm-1)   label        IR  Raman"
+            lines.append(header)
+
+        for row in summary:
+            qx, qy, qz = row["qpoint"]
+            bi = row["band_index"]
+            f_thz = row["frequency_thz"]
+            f_cm1 = row["frequency_cm1"]
+            label = row["label"] or "-"
+            ir_flag = "Y" if row["is_ir_active"] else "."
+            raman_flag = "Y" if row["is_raman_active"] else "."
+
+            line = (
+                f"{qx:7.4f} {qy:7.4f} {qz:7.4f}  {bi:4d}  "
+                f"{f_thz:10.4f}  {f_cm1:11.2f}  {label:10s}  {ir_flag:^3s} {raman_flag:^5s}"
+            )
+            lines.append(line)
+
+        return "\n".join(lines)
+
+    def get_verbose_output(self) -> str:
+        """Get verbose phonopy-style irreps output."""
+        buf = StringIO()
+        with contextlib.redirect_stdout(buf):
+            show_method = getattr(self, "_show", None) or getattr(self, "show", None)
+            if show_method is None:
+                print(repr(self))
+            else:
+                try:
+                    show_method(True)
+                except TypeError:
+                    show_method()
+        return buf.getvalue()
+
+
+def analyze_irreps(
+    primitive_atoms,
+    qpoint,
+    freqs,
+    eigvecs,
+    symprec: float = 1e-5,
+    degeneracy_tolerance: float = 1e-5,
+    log_level: int = 0,
+) -> IrRepsEigen:
+    """Analyze irreps for a single q-point.
+
+    Parameters:
+        primitive_atoms: Phonopy Atoms object
+        qpoint: Q-point
+        freqs: Frequencies
+        eigvecs: Eigenvectors
+        symprec: Symmetry precision
+        degeneracy_tolerance: Degeneracy tolerance
+        log_level: Log level
+
+    Returns:
+        IrRepsEigen object
+    """
+    irr = IrRepsEigen(
+        primitive_atoms,
+        qpoint,
+        freqs,
+        eigvecs,
+        symprec=symprec,
+        degeneracy_tolerance=degeneracy_tolerance,
+        log_level=log_level,
+    )
+    irr.run()
+    return irr