Source code for crystod.vibration_modes

"""
Symmetry-only vibration basis workflow for crystod.
"""

from __future__ import annotations

import re
from argparse import ArgumentDefaultsHelpFormatter, ArgumentParser, RawDescriptionHelpFormatter, RawTextHelpFormatter
from fractions import Fraction
from pathlib import Path

import numpy as np
import spglib
from ase import Atoms
from ase.io import write as ase_write
from numpy.typing import NDArray

from phonopy.structure.cells import get_primitive_matrix_by_centring

from .irreptables_compat import load_irreptables
from .operations import conjugated_little_group_map, find_star_arm, parse_qpoint_token, snap_qpoint
from .runtime_compat import (
    SymmetryDatasetAdapter,
    get_character,
    get_chemical_symbols,
    get_little_group,
    get_scaled_positions,
)
from .spglib_compat import ensure_spglib_compat

ensure_spglib_compat()

from phonopy.interface.calculator import read_crystal_structure
from phonopy.structure.atoms import PhonopyAtoms
from .runtime_compat import get_spacegroup_irreps_from_primitive_symmetry
from spgrep.representation import project_to_irrep

IrrepTable, Irrep = load_irreptables()


def _snap_if_rational(vector) -> list[float]:
    """``snap_qpoint`` for the coordinates within 1e-6 of a simple fraction,
    the value itself for the others: a seekpath point whose coordinates
    depend on the lattice parameters is not shifted along its line."""
    return [parse_qpoint_token(float(value)) for value in vector]


class MyHelpFormatter(
    RawTextHelpFormatter,
    RawDescriptionHelpFormatter,
    ArgumentDefaultsHelpFormatter,
):
    pass


desc = """
Construct symmetry-allowed vibration basis vectors without phonon force data.

# Command Examples:
crystod-phonon --vibration -c example/test_POSCARs/221_PPOSCAR_ScF3 --qpoint 0.5 0.5 0.5
crystod-phonon --vibration -c example/test_POSCARs/221_PPOSCAR_ScF3 --qpoint R --mode-index 3 --component-index 1 --output POSCAR_vibration
"""


def build_parser() -> ArgumentParser:
    parser = ArgumentParser(description=desc, formatter_class=MyHelpFormatter)
    parser.add_argument(
        "--poscar",
        default="POSCAR",
        help="POSCAR path.",
    )
    parser.add_argument(
        "--qpoint",
        nargs="+",
        default=None,
        help="Either an ISO-IR special-point name such as GM/X/M/R or three primitive\n"
        "reciprocal coordinates.",
    )
    parser.add_argument(
        "--tolerance",
        type=float,
        default=1e-5,
        help="Symmetry tolerance.",
    )
    parser.add_argument(
        "--list-qpoints",
        action="store_true",
        help="Only list the ISO-IR special q points (primitive coordinates) and exit.",
    )
    parser.add_argument(
        "--raman-tensor",
        dest="raman_tensor",
        action="store_true",
        help="At Gamma, print the symmetry-allowed Raman tensors of the Raman-active\n"
        "irreps (Cartesian axes of the input cell).",
    )
    parser.add_argument(
        "--mode-index",
        type=int,
        default=None,
        help="Irrep-grouped mode-space number to inspect (1-based).",
    )
    parser.add_argument(
        "--component-index",
        type=int,
        default=1,
        help="Component number inside the selected degenerate mode space (1-based).",
    )
    parser.add_argument(
        "--amplitude",
        nargs="+",
        type=float,
        default=[0.3],
        help="Amplitude in Angstroms of the written displacement: one value per selected\n"
        "mode, i.e. one value (a single mode-space component is written).",
    )
    parser.add_argument(
        "--output",
        default=None,
        help="Output POSCAR path for the selected mode/component (default:\n"
        "VPOSCAR_<formula>_<q>_space<N>[_comp<M>], _comp<M> for a space of dimension >= 2).",
    )
    parser.add_argument(
        "--export-npz",
        default=None,
        help="Optional .npz path to save positions, displacements, symbols, and lattice.",
    )
    parser.add_argument(
        "--no-files",
        dest="no_files",
        action="store_true",
        help="Print the report only: do not save it as vibration_<formula>_<q>[_space<N>...].",
    )
    return parser


# The note printed when the input cell is reduced to the spglib primitive
# cell (crystod.visualize_pyscf filters this exact text; keep them in sync).
PRIMITIVE_CELL_NOTICE = "### Inputed cell was converted into primitive cell. ###"

# The largest supercell multiplicity per axis a modulation at q is frozen
# into (--vibration and --modulation share it).
MAX_SUPERCELL_DENOMINATOR = 12


def _note(message: str, quiet: bool = False) -> None:
    """Print a note of this module where the commands show it (stdout),
    unless ``quiet`` (library use, MCP tools)."""
    if not quiet:
        print(message)


def _format_size(sizes) -> str:
    return "x".join(str(int(size)) for size in sizes)


def commensurate_supercell_sizes(
    qpoint, max_denominator: int = MAX_SUPERCELL_DENOMINATOR
) -> tuple[int, int, int]:
    """Supercell multiplicities along a, b, c commensurate with q.

    The smallest diagonal supercell on which the modulation at q is periodic:
    1 for an integer component, else the denominator of the component. The
    check of ``crystod-phonon --vibration`` and ``--modulation``.

    Args:
        qpoint: Fractional coordinates of q in the primitive reciprocal basis.
        max_denominator: The largest multiplicity accepted per axis.

    Returns:
        ``(n1, n2, n3)``.

    Raises:
        ValueError: If a component is not a fraction with a denominator of at
            most ``max_denominator`` (within 1e-4, e.g. 0.15 = 3/20): freezing
            the modulation into a smaller supercell would build a structure
            that is not periodic. The message names the smallest commensurate
            supercell when one with at most 1000 cells per axis exists.
    """
    sizes = []
    offending = None
    for component in qpoint:
        value = float(component)
        if abs(value - round(value)) < 1e-10:
            sizes.append(1)
            continue
        fraction = Fraction(value).limit_denominator(max_denominator)
        if abs(value - float(fraction)) > 1e-4:
            if offending is None:
                offending = value
            sizes.append(None)
            continue
        sizes.append(fraction.denominator)
    if offending is None:
        return tuple(sizes)
    smallest = []
    for component, size in zip(qpoint, sizes):
        value = float(component)
        fraction = Fraction(value).limit_denominator(1000)
        if size is None and abs(value - float(fraction)) < 1e-6:
            size = fraction.denominator
        smallest.append(size)
    if all(size is not None for size in smallest):
        where = f"the smallest commensurate supercell is {_format_size(smallest)}"
    else:
        where = "no supercell of at most 1000 cells per axis is commensurate with it"
    raise ValueError(
        f"q = {[float(v) for v in qpoint]} is not commensurate with a supercell of "
        f"at most {max_denominator} cells per axis (component {offending:g}; {where}); "
        f"give q as fractions with a denominator of at most {max_denominator}, e.g. 1/3."
    )


def _approximate_supercell_sizes(qpoint, max_denominator: int = 6) -> tuple[int, int, int]:
    """The multiplicities :meth:`SymmetryOnlyVibrations.get_supercell_size`
    returned before it checked commensurability: 1 for a zero component, else
    the denominator of the component limited to ``max_denominator``, never an
    error. Kept for the display cell of the SALC viewer (``crystod
    --visualize``), which draws a k point it cannot hold periodically too."""
    sizes = []
    for component in qpoint:
        if abs(component) < 1e-10:
            sizes.append(1)
        else:
            sizes.append(Fraction(float(component)).limit_denominator(max_denominator).denominator)
    return tuple(sizes)


class _CoreRepresentation:
    def __init__(
        self,
        cell: PhonopyAtoms,
        symprec: float = 1e-5,
        standardize: bool = True,
        input_cell: PhonopyAtoms | None = None,
        quiet: bool = False,
    ):
        # the cell as given: the ISO-IR frame of the irrep labels is taken
        # from it, not from the standardized cell derived below
        self.input_cell = cell if input_cell is None else input_cell
        if standardize:
            primitive_lattice, primitive_pos, primitive_numbers = spglib.standardize_cell(
                cell.totuple(),
                to_primitive=True,
                symprec=symprec,
            )
            self.primitive_cell = PhonopyAtoms(
                numbers=primitive_numbers,
                scaled_positions=primitive_pos,
                cell=primitive_lattice,
            )
            _note(f"\n {PRIMITIVE_CELL_NOTICE}", quiet=quiet)
        else:
            # Keep the input cell as-is (it must already be primitive). This
            # preserves the caller's atom positions so that phase conventions
            # stay consistent with an externally built dynamical matrix.
            self.primitive_cell = cell

        dataset = SymmetryDatasetAdapter(
            spglib.get_symmetry_dataset(self.primitive_cell.totuple(), symprec=symprec)
        )
        self.spglib_dataset = dataset
        self.rotations = dataset.rotations
        self.translations = dataset.translations
        self.symprec = symprec

    def _get_isoir_label_list(
        self,
        qpoint: list[float],
        irreps,
        mapping_little_group,
    ) -> list[str] | None:
        """ISO-IR (Miller-Love) labels for spgrep irreps at a non-tabulated q,
        or None when the ISO-IR data are unavailable or matching fails.
        """
        from .isoir import get_isoir_label_map

        self.labels_from_isoir = False
        matched = get_isoir_label_map(
            self.spglib_dataset["number"],
            self.primitive_cell.totuple(),
            self.symprec,
            qpoint,
            [self.rotations[index] for index in mapping_little_group],
            [self.translations[index] for index in mapping_little_group],
            [get_character(irrep) for irrep in irreps],
            input_cell=self.input_cell.totuple(),
        )
        if matched is None:
            return None
        label_map, qpoint_name = matched
        self.labels_from_isoir = True
        self.isoir_qpoint_name = qpoint_name
        return [
            f"{label_map[index]}({irrep.shape[1]})"
            for index, irrep in enumerate(irreps)
        ]

    def _get_isoir_labeler(self):
        """The ISO-IR labeller of the labels (that of
        :meth:`_get_isoir_label_list`), or None."""
        from .isoir import get_cached_labeler

        return get_cached_labeler(
            self.spglib_dataset["number"], self.primitive_cell.totuple(),
            self.symprec, input_cell=self.input_cell.totuple(),
        )

    def _special_points_in_label_frame(self, names, points):
        """A list of tabulated special points named in the frame of the
        labels (``crystod.isoir.special_points_in_frame``): the list a
        survey loops over and shows."""
        from .isoir import special_points_in_frame

        return special_points_in_frame(
            names, points, self._get_isoir_labeler(), canonical=snap_qpoint
        )

    def _spglib_frame_labeler(self):
        """An ISO-IR labeller in spglib's own frame of the primitive cell,
        the frame seekpath and the special-point tables name their points
        in, or None."""
        if not hasattr(self, "_spglib_labeler"):
            from .isoir import IsoIRLabeler

            try:
                self._spglib_labeler = IsoIRLabeler(
                    self.spglib_dataset["number"], cell=self.primitive_cell.totuple(),
                    symprec=self.symprec,
                )
            except Exception:
                self._spglib_labeler = None
        return self._spglib_labeler

    def _renamed_by_frame(self, qpoint) -> str | None:
        """The ISO-IR name of q in the frame of the labels when spglib's
        frame names q differently (an input outside the ISO-IR setting,
        where the point seekpath calls P can be the PA of the labels), else
        None."""
        labeler, spglib_frame = self._get_isoir_labeler(), self._spglib_frame_labeler()
        if labeler is None or spglib_frame is None:
            return None
        try:
            name = labeler.kpoint_name(qpoint)
            if name is not None and name != spglib_frame.kpoint_name(qpoint):
                return name
        except Exception:
            pass
        return None

    def get_modified_permutation_rep(
        self,
        rotation: NDArray[np.int_],
        translation: NDArray[np.float64],
        kpoint: list[float],
    ) -> NDArray[np.complex128]:
        """Atom-permutation matrix of one operation at q, with Bloch phases."""
        positions = get_scaled_positions(self.primitive_cell)
        num_atom = len(positions)
        matrix = np.zeros((num_atom, num_atom), dtype=complex)
        for i, pos_in in enumerate(positions):
            pos_rot = np.dot(rotation, pos_in) + translation
            for j, pos_out in enumerate(positions):
                diff = pos_rot - pos_out
                if (abs(diff - np.rint(diff)) < 1e-5).all():
                    phase_factor = np.dot(
                        kpoint,
                        np.dot(np.linalg.inv(rotation), pos_out - translation) - pos_out,
                    )
                    matrix[j, i] = np.exp(2j * np.pi * phase_factor)
        return matrix

    def get_permutation_reps_at_k(
        self,
        little_rotations: NDArray[np.int_],
        little_translations: NDArray[np.float64],
        kpoint: list[float],
    ) -> NDArray[np.complex128]:
        """Permutation matrices of the little-group operations at q."""
        return np.array(
            [
                self.get_modified_permutation_rep(rotation, translation, kpoint)
                for rotation, translation in zip(little_rotations, little_translations)
            ],
            dtype=np.complex128,
        )

    def get_little_group(self, kpoint: list[float]):
        """Little-group operations of q (see ``runtime_compat.get_little_group``)."""
        return get_little_group(
            rotations=self.rotations,
            translations=self.translations,
            kpoint=kpoint,
        )


[docs] class SymmetryOnlyVibrations(_CoreRepresentation): """Symmetry-allowed vibration bases of a crystal, without force data. The engine of ``crystod-phonon --vibration``: at a q point, the displacement representation of the little group of q (the permutation representation of the atoms times the Cartesian rotation, with Bloch phases) is projected onto the spgrep irreps, giving one basis of symmetry-adapted displacement patterns per irrep occurrence. The spaces are labeled with ISO-IR irrep names, and any component can be written out as a displaced structure on the commensurate supercell: the partner of :meth:`get_symmetry_adapted_spaces` -- fixed by the conventions of ``--modulation``, real with the Bloch phase of every atom at a time-reversal-invariant q, so that it freezes into an isotropy subgroup of its irrep -- a unit-norm symmetry-adapted displacement pattern, not a normal mode. :func:`crystod.symmetry_adapted_modes.solve_symmetry_adapted_modes` (behind ``crystod-phonon --modulation`` and ``--vector``) uses the same basis, on phonopy's primitive cell as it is (``standardize=False``), to block-diagonalize a dynamical matrix. Args: cell: The crystal structure as a ``phonopy.structure.atoms.PhonopyAtoms`` object, e.g. from ``phonopy.interface.calculator.read_crystal_structure``. symprec: Symmetry tolerance of the spglib analysis. standardize: Reduce ``cell`` to the spglib primitive cell first (the default; a note is printed on stdout unless ``quiet``). ``False`` keeps the input cell as it is, which must then already be primitive; this preserves the caller's atom positions so that phase conventions stay consistent with an externally built dynamical matrix. Either way the analysis, the Bloch phases and the written supercells all use ``primitive_cell``. input_cell: The cell whose ISO-IR frame names the irreps, when it is not ``cell`` itself (e.g. the unit cell a phonopy primitive cell was built from); default ``cell``. quiet: Do not print the note ``### Inputed cell was converted into primitive cell. ###`` that ``standardize`` prints on stdout (the commands keep it); for library use and the MCP server, whose stdout is the protocol stream. Attributes: primitive_cell: The primitive cell the analysis runs on. spglib_dataset: Its spglib symmetry dataset (``["number"]``, ``["international"]``, ...). rotations: Rotation parts of the space-group operations in the primitive basis, shape ``(n_ops, 3, 3)``. translations: The corresponding translation parts, shape ``(n_ops, 3)``. rotations_cartesian: The rotations in Cartesian coordinates. symprec: The symmetry tolerance. labels_from_isoir: ``True`` when the last :meth:`get_irrep_labels` call took its labels from the general ISO-IR k-vector lookup rather than from the special-point table. Example: List the vibration spaces of cubic ScF3 at the R point:: from phonopy.interface.calculator import read_crystal_structure from crystod import phonon from crystod.examples import example_path cell, _ = read_crystal_structure( example_path("221_PPOSCAR_ScF3"), interface_mode="vasp") vibrations = phonon.SymmetryOnlyVibrations(cell) label, qpoint = vibrations.resolve_qpoint(["R"]) irreps, spaces, labels = vibrations.describe_mode_spaces(qpoint) labels # ['R1+(1)', 'R3+(2)', 'R4+(3)', ...] [space.shape for space in spaces] # [(1, 12), (2, 12), (3, 12), ...] """ def __init__( self, cell: PhonopyAtoms, symprec: float = 1e-5, standardize: bool = True, input_cell: PhonopyAtoms | None = None, quiet: bool = False, ): super().__init__( cell=cell, symprec=symprec, standardize=standardize, input_cell=input_cell, quiet=quiet, ) lattice_t = np.transpose(self.primitive_cell.cell) lattice_t_inv = np.linalg.inv(lattice_t) self.rotations_cartesian = np.array( [lattice_t @ rotation @ lattice_t_inv for rotation in self.rotations], dtype=np.complex128, )
[docs] def get_high_symmetry_qpoints(self) -> dict[str, list[float]]: """High-symmetry q points of the primitive cell, from seekpath. ``crystod-phonon --vibration --list-qpoints`` prints this map. The coordinates are expressed in the reciprocal basis of *this* object's (spglib) primitive cell: seekpath's own primitive cell can differ from it by an integer change of basis (base-centred monoclinic cells, for instance), and the tabulated coordinates are transformed accordingly. A warning is issued only when the two cells are not related by such a change of basis, in which case the coordinates are returned as seekpath gives them. seekpath names its points in spglib's standardized frame, while the irrep labels refer to the ISO-IR frame of the input cell; for an input outside the ISO-IR setting the two differ by an element of the normalizer, which can turn seekpath's P into the PA of the labels. A point whose ISO-IR type differs between the two frames is therefore moved to the point that carries its type in the frame of the labels (-k for the -k partner of a tabulated type, else its image under the change of frame), so that ``--qpoint P`` is the point the labels call P. The names stay seekpath's: for a triclinic cell seekpath's letters X, Y, Z, R, T, U, V denote other points than the ISO-IR names of the labels (seekpath's Z of ``1_PPOSCAR_RbBe2F5`` carries ``X1``). Returns: Dict mapping seekpath labels (``"GAMMA"``, ``"R"``, ``"X"``, ...) to fractional coordinates in the primitive reciprocal basis. """ import seekpath import warnings structure = ( self.primitive_cell.cell, self.primitive_cell.scaled_positions, self.primitive_cell.numbers, ) path_data = seekpath.get_path(structure, symprec=1e-5) point_coords = path_data["point_coords"] own_lattice = np.asarray(self.primitive_cell.cell, dtype=float) seekpath_lattice = np.asarray(path_data["primitive_lattice"], dtype=float) if not np.allclose(own_lattice, seekpath_lattice, atol=1e-4): # rows of the seekpath cell as integer combinations of our rows: # P_seek = M P_own; a k point with fractional coordinates k_seek # in seekpath's reciprocal basis is k_own = k_seek inv(M)^T here change = seekpath_lattice @ np.linalg.inv(own_lattice) rounded = np.rint(change) if (np.allclose(change, rounded, atol=1e-6) and abs(round(np.linalg.det(rounded))) == 1): to_own = np.linalg.inv(rounded).T point_coords = { label: (np.asarray(coords, dtype=float) @ to_own).tolist() for label, coords in point_coords.items() } else: warnings.warn( "The primitive cell from seekpath does not match the spglib " "primitive cell. The q-point coordinates might need a basis " "transformation.", stacklevel=2, ) # the labels whose point carries seekpath's ISO-IR type in the frame # of the labels (all of them unless a move below fails): the ones # resolve_qpoint may name coordinates by self._labels_in_frame = set(point_coords) labeler, spglib_frame = self._get_isoir_labeler(), self._spglib_frame_labeler() if labeler is None or spglib_frame is None: return point_coords # k_label = k_spglib Pinv_spglib P_label carries a point onto the one # with the same ISO-IR conventional coordinates in the label frame change = spglib_frame.Pinv @ labeler.P in_frame = {} for label, coords in point_coords.items(): in_frame[label] = coords try: wanted = spglib_frame.kpoint_name(coords) if wanted is None or labeler.kpoint_name(coords) == wanted: continue self._labels_in_frame.discard(label) vector = np.asarray(coords, dtype=float) for candidate in (_snap_if_rational(-vector), _snap_if_rational(vector @ change)): if labeler.kpoint_name(candidate) == wanted: in_frame[label] = candidate self._labels_in_frame.add(label) break except Exception: continue return in_frame
[docs] def resolve_qpoint(self, raw_qpoint: list[str]) -> tuple[str, list[float]]: """Resolve ``--qpoint`` tokens into a label and coordinates. One token is a seekpath label (``GM``, ``G`` and the Greek capital gamma are accepted for ``GAMMA``) of :meth:`get_high_symmetry_qpoints`; three tokens are coordinates in the primitive reciprocal basis, fractions such as ``1/3`` allowed. Coordinates of a point of :meth:`get_high_symmetry_qpoints` are labeled with its name there. Other coordinates get, where the frame of the labels names q differently from spglib's frame (an input outside the ISO-IR setting), the ISO-IR name in the frame of the labels (``PA`` above PA labels); else the name of the star arm the space-group rotations map them onto, else the ISO-IR k-vector type of q, else ``"custom"``. Args: raw_qpoint: The tokens, one label or three coordinate strings. Returns: ``(label, qpoint)`` with ``qpoint`` a list of three floats. Raises: ValueError: For an unknown label, or a token count other than one or three. """ qpoint_map = self.get_high_symmetry_qpoints() alias_map = { "GM": "GAMMA", "G": "GAMMA", "Γ": "GAMMA", } if len(raw_qpoint) == 1: requested = raw_qpoint[0].strip().upper() # the aliases stand in for GAMMA only where the cell has no # special point of that name (body-centred tetragonal cells have # a genuine G) if requested not in qpoint_map: requested = alias_map.get(requested, requested) if requested in qpoint_map: return requested, list(qpoint_map[requested]) available = ", ".join(sorted(qpoint_map)) raise ValueError( f"Unknown q-point label '{raw_qpoint[0]}'. Available labels: {available}" ) if len(raw_qpoint) != 3: raise ValueError("--qpoint must be either one label or three coordinates.") qpoint = [parse_qpoint_token(value) for value in raw_qpoint] # a listed point is named as the list names it: its point carries # the ISO-IR type of seekpath's name in the frame of the labels in_frame = getattr(self, "_labels_in_frame", set(qpoint_map)) matched_label = None for label, coords in qpoint_map.items(): if label in in_frame and np.allclose(qpoint, coords, atol=1e-8): matched_label = label break # else the frame of the labels first where spglib's frame, in which # seekpath names its points, would give q another name if matched_label is None: matched_label = self._renamed_by_frame(qpoint) if matched_label is None: for label, coords in qpoint_map.items(): if np.allclose(qpoint, coords, atol=1e-8): matched_label = label break if matched_label is None: # q may be a non-tabulated arm of a special-point star: label it # with the name of the arm the space-group rotations map it onto. arm = find_star_arm(qpoint, self.rotations, list(qpoint_map.values())) if arm is not None: for label, coords in qpoint_map.items(): if np.allclose(arm[1], coords, atol=1e-8): matched_label = label break if matched_label is None: # q outside the special-point list (a line, plane or generic q, # or a -k star such as PA): the ISO-IR k-vector type label from .isoir import get_isoir_kpoint_name matched_label = get_isoir_kpoint_name( self.spglib_dataset["number"], self.primitive_cell.totuple(), self.symprec, qpoint, input_cell=self.input_cell.totuple(), ) return matched_label or "custom", qpoint
[docs] def get_special_qpoints(self) -> dict[str, list[float]]: """The ISO-IR special q points of the space group, in the frame of the labels. ``crystod-phonon --vibration`` lists these points (``--list-qpoints``) and resolves ``--qpoint NAME`` through them: one entry per special point of the ISO-IR tables, named as the irrep labels at it are named (the frame of the labels, ``crystod.isoir.special_points_in_frame``; a point tabulated only through its -k partner is listed at the tabulated point), the set of points ``crystod-phonon --irreps`` writes under ``special_points:`` for the same structure. The -k partners (``PA``) and seekpath's extra points (``H_2``) are not listed. The command prints them in the order of seekpath's path (``GM, A, K, H, M, L`` for P6_3mc); this method keeps the table order. Returns: Dict mapping ISO-IR names (``"GM"``, ``"A"``, ``"K"``, ...), in the order of the tables, to fractional coordinates in the reciprocal basis of :attr:`primitive_cell`; empty when the tables do not cover the space group. """ cached = getattr(self, "_special_qpoints", None) if cached is None: from .phonon_irreps import get_irt_special_points cached = {} try: table = IrrepTable(self.spglib_dataset["number"], spinor=False) primitive_matrix = get_primitive_matrix_by_centring( self.spglib_dataset["international"][0] ) names, points = self._special_points_in_label_frame( *get_irt_special_points(table, primitive_matrix) ) cached = { name: [float(value) + 0.0 for value in point] for name, point in zip(names, points) } except Exception: cached = {} self._special_qpoints = cached return {name: list(point) for name, point in cached.items()}
[docs] def name_qpoint(self, qpoint) -> str: """The name ``crystod-phonon --vibration`` gives to q point coordinates. The ISO-IR name of a point of :meth:`get_special_qpoints`; for another arm of its star (or ``q + G``) the name of the arm the space-group rotations map q onto; else the ISO-IR k-vector type of q in the frame of the labels (``T`` for a symmetry line, ``PA`` for the -k partner of a tabulated point, ``GP`` for a general point); else ``"custom"``. Args: qpoint: Fractional coordinates in the primitive reciprocal basis. Returns: The name. """ points = self.get_special_qpoints() for name, coords in points.items(): if np.allclose(qpoint, coords, atol=1e-8): return name arm = find_star_arm(qpoint, self.rotations, list(points.values())) if arm is not None: for name, coords in points.items(): if np.allclose(arm[1], coords, atol=1e-8): return name from .isoir import get_isoir_kpoint_name try: name = get_isoir_kpoint_name( self.spglib_dataset["number"], self.primitive_cell.totuple(), self.symprec, list(qpoint), input_cell=self.input_cell.totuple(), ) except Exception: name = None return name or "custom"
[docs] def resolve_special_qpoint(self, raw_qpoint: list[str]) -> tuple[str, list[float]]: """Resolve ``--qpoint`` tokens of ``crystod-phonon --vibration``. One token is an ISO-IR name of :meth:`get_special_qpoints` (any case); ``GAMMA``, ``G`` and the Greek capital gamma stand for ``GM``, and a seekpath name of :meth:`get_high_symmetry_qpoints` that is not an ISO-IR name of the list (``H_2``) is accepted as an alias of its point. Three tokens are coordinates in the primitive reciprocal basis (fractions such as ``1/3`` allowed), named by :meth:`name_qpoint`. :meth:`resolve_qpoint` keeps the seekpath names for the other commands. Args: raw_qpoint: The tokens, one name or three coordinate strings. Returns: ``(name, qpoint)`` with ``qpoint`` a list of three floats. Raises: ValueError: For an unknown name, or a token count other than one or three. """ if len(raw_qpoint) == 1: token = raw_qpoint[0].strip() requested = token.upper() points = self.get_special_qpoints() if requested in points: return requested, list(points[requested]) if requested in ("GAMMA", "G", "Γ") and "GM" in points: return "GM", list(points["GM"]) try: seekpath_points = self.get_high_symmetry_qpoints() except Exception: seekpath_points = {} if requested in seekpath_points: qpoint = [float(value) for value in seekpath_points[requested]] return self.name_qpoint(qpoint), qpoint available = ", ".join(points) or ", ".join(seekpath_points) raise ValueError( f"Unknown q-point label '{token}'. Available labels: {available}" ) if len(raw_qpoint) != 3: raise ValueError("--qpoint must be either one label or three coordinates.") qpoint = [parse_qpoint_token(value) for value in raw_qpoint] return self.name_qpoint(qpoint), qpoint
[docs] def get_vibration_rep(self, kpoint: list[float]): """Displacement representation of the little group of q. Args: kpoint: Fractional coordinates of q in the primitive reciprocal basis. Returns: ``(irreps, vibration_rep, mapping_little_group)``: the spgrep irreps of the little group of q; the representation matrices of the little-group operations on the ``3 * n_atoms`` displacement space, shape ``(n_little, 3 * n_atoms, 3 * n_atoms)``; and the indices of the little-group operations within ``rotations``. """ irreps, mapping_little_group = get_spacegroup_irreps_from_primitive_symmetry( rotations=self.rotations, translations=self.translations, kpoint=kpoint, ) little_rotations = self.rotations[mapping_little_group] little_translations = self.translations[mapping_little_group] permutation_matrices = self.get_permutation_reps_at_k( little_rotations=little_rotations, little_translations=little_translations, kpoint=kpoint, ) cartesian_rep = self.rotations_cartesian[mapping_little_group] vibration_rep = np.array( [ np.kron(permutation_matrix, cartesian_rotation) for permutation_matrix, cartesian_rotation in zip(permutation_matrices, cartesian_rep) ], dtype=np.complex128, ) return irreps, vibration_rep, mapping_little_group
[docs] def get_vibration_basis( self, irreps, vibration_rep, irrep_labels: list[str] | None = None, ) -> tuple[list[NDArray[np.complex128]], list[str]]: """Project the displacement representation onto each irrep. Args: irreps: The spgrep irreps from :meth:`get_vibration_rep`. vibration_rep: The representation matrices from :meth:`get_vibration_rep`. irrep_labels: One label per irrep, e.g. from :meth:`get_irrep_labels`; generic ``irrep_N(dim)`` labels are used when omitted. Returns: ``(basis_vectors, basis_labels)``: one ``(dim, 3 * n_atoms)`` array per occurrence of an irrep in the displacement representation, and the label of each space. The rows are the symmetry-adapted displacement patterns as kets: for one array ``B`` and the irrep matrices ``d``, ``vibration_rep[g] @ B.T == B.T @ d[g]``. They are in the atom-position phase convention of phonopy's eigenvectors (Bloch factor ``exp(2 pi i q . x_j)`` of each atom not included). Repeated occurrences of one irrep transform with the same matrices but are not orthogonal to each other. """ basis_vectors: list[NDArray[np.complex128]] = [] basis_labels: list[str] = [] fallback_labels = irrep_labels or [f"irrep_{index + 1}({irrep.shape[1]})" for index, irrep in enumerate(irreps)] for irrep, irrep_label in zip(irreps, fallback_labels): projected_spaces = project_to_irrep(vibration_rep, irrep) basis_vectors.extend(projected_spaces) basis_labels.extend([irrep_label] * len(projected_spaces)) return basis_vectors, basis_labels
def _get_irt_irreps_at_q(self, qpoint: list[float], irt_table, prim_mat) -> list[Irrep]: irreps_at_q = [] prim_inv = np.linalg.inv(prim_mat) conventional_q = np.array(qpoint) @ prim_inv for irrep_at_q in irt_table.irreps: if np.allclose(irrep_at_q.k, conventional_q): irreps_at_q.append(irrep_at_q) return irreps_at_q def _get_mapping_to_irt( self, irt_little_rotations: NDArray[np.int_], found_little_rotations: NDArray[np.int_], prim_mat: NDArray[np.float64], ) -> list[int]: conventional_little_rotations = prim_mat @ found_little_rotations @ np.linalg.inv(prim_mat) mapping_to_irt = [] for irt_rotation in irt_little_rotations: for index, rotation in enumerate(conventional_little_rotations): if np.allclose(irt_rotation, rotation): mapping_to_irt.append(index) break return mapping_to_irt
[docs] def get_irrep_labels( self, qpoint: list[float], irreps, mapping_little_group: NDArray[np.int_], ) -> list[str]: """ISO-IR labels of the spgrep irreps at q. The ISO-IR labeller (``crystod.isoir``) names the spgrep irreps at any q -- a special point, any arm of its star or copy q + G, a symmetry line, plane or generic q (Miller-Love labels) -- in the ISO-IR frame of the input cell; a q point tabulated only through its -k partner gets the 'A' names of the conjugate irreps (``PA1``). Only where the labeller gives nothing are the characters compared directly with the special-point table (at a tabulated point, or by conjugation onto the tabulated arm for another arm of its star). An irrep neither route names keeps its generic ``irrep_N(dim)`` label. Args: qpoint: Fractional coordinates of q in the primitive reciprocal basis. irreps: The spgrep irreps from :meth:`get_vibration_rep`. mapping_little_group: The little-group indices from :meth:`get_vibration_rep`. Returns: One label per irrep, e.g. ``"R4+(3)"`` (the irrep name with its dimension). """ generic_labels = [f"irrep_{index + 1}({irrep.shape[1]})" for index, irrep in enumerate(irreps)] # The ISO-IR labeller is the label authority at every q: it compares # in the ISO-IR setting, at the exact translations and with the # conjugate phase convention. The direct special-point comparison # further down ignores all three and names a physically different # irrep at some points (H/K of the hexagonal groups, P of I4/mcm, # Y/T of Ccce, ...); it is kept only as a fallback. isoir_labels = self._get_isoir_label_list(qpoint, irreps, mapping_little_group) try: irt_table = IrrepTable(self.spglib_dataset["number"], spinor=False) except Exception: return isoir_labels or generic_labels prim_mat = get_primitive_matrix_by_centring(self.spglib_dataset["international"][0]) irt_irreps = self._get_irt_irreps_at_q(qpoint, irt_table, prim_mat) conjugated = None if not irt_irreps: # q may be a non-tabulated arm of a special-point star: map it onto # the tabulated arm and transport the characters by conjugation. special_points: list[list[float]] = [] for irrep_at_q in irt_table.irreps: primitive_q = snap_qpoint(np.array(irrep_at_q.k) @ prim_mat) if primitive_q not in special_points: special_points.append(primitive_q) arm = find_star_arm(qpoint, self.rotations, special_points) if arm is not None: candidate_irreps = self._get_irt_irreps_at_q(arm[1], irt_table, prim_mat) transported = conjugated_little_group_map( self.rotations, self.translations, arm[0], arm[1], mapping_little_group ) if candidate_irreps and transported is not None: irt_irreps = candidate_irreps conjugated = transported if not irt_irreps: # Not tabulated as a special point (e.g. a symmetry line/plane or # generic q): only the general ISO-IR (ISOTROPY) k-vector lookup # covers it. Labels then follow the Miller-Love convention. return isoir_labels or generic_labels if isoir_labels is not None: # a special point (or another arm of its star): same labeller, # but the flag keeps its meaning "q is not a tabulated point" self.labels_from_isoir = False return isoir_labels irt_little_rotations = np.array( [irt_table.symmetries[index - 1].R for index in irt_irreps[0].characters.keys()] ) found_little_rotations = self.rotations[mapping_little_group] if conjugated is None: mapping_to_irt = self._get_mapping_to_irt(irt_little_rotations, found_little_rotations, prim_mat) character_phases = np.ones(len(irt_little_rotations), dtype=complex) else: # mapping_to_irt[m] = position (within the little group of q) of the # operation h whose conjugate g^-1 h g is the m-th tabulated # operation; the transported character picks up the Bloch phase. conj_indices, conj_phases = conjugated prim_mat_inv = np.linalg.inv(prim_mat) mapping_to_irt = [] phases: list[complex] = [] for irt_rotation in irt_little_rotations: rotation_prim = np.rint(prim_mat_inv @ irt_rotation @ prim_mat).astype(int) table_op_index = None for j, rotation in enumerate(self.rotations): if (rotation == rotation_prim).all(): table_op_index = j break if table_op_index is None or table_op_index not in conj_indices: break position = conj_indices.index(table_op_index) mapping_to_irt.append(position) phases.append(conj_phases[position]) character_phases = np.array(phases, dtype=complex) if len(mapping_to_irt) != len(irt_little_rotations): return generic_labels resolved_labels: list[str] = [] used_irt_labels: set[str] = set() for generic_label, irrep in zip(generic_labels, irreps): spgrep_character = np.array(get_character(irrep), dtype=complex)[mapping_to_irt] best_label = generic_label best_overlap = -1.0 for irt_irrep in irt_irreps: irt_label = f"{irt_irrep.name}({irt_irrep.dim})" irt_character = ( np.array(list(irt_irrep.characters.values()), dtype=complex) * character_phases ) overlap = np.abs( np.dot(spgrep_character, np.conjugate(irt_character)) / irt_irrep.nsym ) if overlap > best_overlap: best_label = irt_label best_overlap = float(overlap) if best_overlap < 0.9: best_label = generic_label elif best_label in used_irt_labels: best_label = f"{best_label} [{generic_label}]" used_irt_labels.add(best_label) resolved_labels.append(best_label) return resolved_labels
[docs] def describe_mode_spaces( self, qpoint: list[float], ) -> tuple[object, list[NDArray[np.complex128]], list[str]]: """Irreps, projected vibration spaces and their labels at q. The one-call form of :meth:`get_vibration_rep`, :meth:`get_irrep_labels` and :meth:`get_vibration_basis`, as ``crystod-phonon --vibration`` prints them (one "Mode Space" line per irrep occurrence, with its label and dimension). Args: qpoint: Fractional coordinates of q in the primitive reciprocal basis. Returns: ``(irreps, basis_spaces, basis_space_labels)``: the spgrep irreps, one ``(dim, 3 * n_atoms)`` array per irrep occurrence, and the ISO-IR label of each space. The mode-space numbers of the command are 1-based positions in ``basis_spaces``. These are spgrep's raw projected spaces; the partners the command writes out are those of :meth:`get_symmetry_adapted_spaces`. """ irreps, vibration_rep, mapping_little_group = self.get_vibration_rep(qpoint) irrep_labels = self.get_irrep_labels(qpoint, irreps, mapping_little_group) basis_spaces, basis_space_labels = self.get_vibration_basis(irreps, vibration_rep, irrep_labels) return irreps, basis_spaces, basis_space_labels
[docs] def get_symmetry_adapted_spaces(self, qpoint: list[float]) -> list[NDArray[np.complex128]]: """Symmetry-adapted partners of every mode space, as ``--vibration`` freezes them. The spaces of :meth:`describe_mode_spaces` (same order, same dimensions) with their partners fixed by the conventions of ``crystod-phonon --modulation`` (:func:`crystod.symmetry_adapted_modes.solve_symmetry_adapted_spaces`, the mode solver with no dynamical matrix): the spaces of a repeated irrep are an orthonormal basis of its isotypic space fixed by the displacements (the atom orbit each lives on, then how the atoms move along the crystal axes, then the products of the displacements of neighbouring atoms), not the copies spgrep's projection happens to return; at a time-reversal-invariant q (``2q`` a reciprocal lattice vector) every partner is, with the Bloch factor ``exp(2 pi i q . x_j)`` of each atom, a real displacement pattern along a direction symmetry operations fix up to sign -- a single partner freezes into an isotropy subgroup of its irrep, whatever the origin; at any other q each space is a complex Bloch wave whose global phase is a convention. A complex irrep and its conjugate, which time reversal joins into one real space at such a q, share its real partners: the first half belongs to the irrep whose label sorts first. At a time-reversal-invariant q the k-th space of a given label thus holds the same partners however q is written (q, q + G or -q); the position of a label in the list follows spgrep's irrep order at the q given and can differ between those spellings. (At any other q the relative phases of the partners of a larger irrep follow the irrep matrices spgrep builds at the q given.) The rows are unit-norm symmetry-adapted displacement patterns, not normal modes: there are no force constants to select a combination of the spaces of a repeated irrep, and no masses. Args: qpoint: Fractional coordinates of q in the primitive reciprocal basis. Returns: One ``(dim, 3 * n_atoms)`` array per mode space, rows in the atom-position phase convention of :meth:`get_vibration_basis` (the Bloch factor of each atom not included), ready for :meth:`get_supercell_displacements`. """ from .symmetry_adapted_modes import solve_symmetry_adapted_spaces irreps, _, mapping_little_group = self.get_vibration_rep(qpoint) labels = self.get_irrep_labels(qpoint, irreps, mapping_little_group) # natural order of the labels (T2 before T10), independent of spgrep's # irrep order at the q given keys = [ tuple(int(part) if part.isdigit() else part for part in re.split(r"(\d+)", label)) for label in labels ] phase = np.repeat( np.exp(2j * np.pi * (np.asarray(self.primitive_cell.scaled_positions, dtype=float)
[docs] @ np.asarray(qpoint, dtype=float))), 3, ) return [ rows * phase.conj()[None, :] for rows in solve_symmetry_adapted_spaces(self, qpoint, irrep_keys=keys) ]
def get_supercell_size(self, qpoint: list[float]) -> tuple[int, int, int]: """Supercell multiplicities along a, b, c commensurate with q. Args: qpoint: Fractional coordinates of q in the primitive reciprocal basis. Returns: ``(n1, n2, n3)``: 1 for an integer component, else the denominator of the component (:func:`commensurate_supercell_sizes`, the check ``--modulation`` makes). Raises: ValueError: If a component is not a fraction with a denominator of at most 12 (e.g. 0.15 = 3/20): no such supercell holds the modulation; the message names the smallest one that does. """ return commensurate_supercell_sizes(qpoint)
[docs] def get_supercell_displacements( self, qpoint: list[float], mode_vector: NDArray[np.complex128], supercell_size: tuple[int, int, int], ): """Displacement pattern of one basis vector on a supercell. Atom j of the primitive cell at lattice translation R is displaced by ``Re(mode_j * exp(2 pi i q . (R + x_j)))`` (unit amplitude), with ``x_j`` the scaled position of atom j in ``primitive_cell``, the cell the supercell is built from: the Bloch wave the ket ``mode`` describes in the atom-position phase convention. For a row of :meth:`get_symmetry_adapted_spaces` at a time-reversal-invariant q the displacement of every primitive cell has unit norm. Args: qpoint: Fractional coordinates of q in the primitive reciprocal basis. mode_vector: One row of :meth:`get_symmetry_adapted_spaces` (what ``--vibration`` writes) or of a projected space of :meth:`describe_mode_spaces` (whose global phase, and at a time-reversal-invariant q its partner basis, spgrep leaves arbitrary), ``3 * n_atoms`` complex components. supercell_size: ``(n1, n2, n3)`` multiplicities, e.g. from :meth:`get_supercell_size`. Returns: ``(positions, displacements, symbols, supercell_lattice)``: Cartesian positions and displacements of the supercell atoms, shape ``(n1 * n2 * n3 * n_atoms, 3)``, their chemical symbols, and the supercell lattice vectors as rows. """ primitive = self.primitive_cell n_atoms = len(primitive.scaled_positions) lattice = primitive.cell frac_pos = primitive.scaled_positions symbols_prim = get_chemical_symbols(primitive) mode = mode_vector.reshape((-1, 3)) n1, n2, n3 = supercell_size all_positions = [] all_displacements = [] all_symbols = [] for i1 in range(n1): for i2 in range(n2): for i3 in range(n3): translation_frac = np.array([i1, i2, i3]) for atom_index in range(n_atoms): pos_frac = frac_pos[atom_index] + translation_frac pos_cart = pos_frac @ lattice all_positions.append(pos_cart) # the Bloch factor of the atom's own position, not # only of its cell phase = np.exp(2j * np.pi * np.dot(qpoint, pos_frac)) displacement = np.real(mode[atom_index] * phase) all_displacements.append(displacement) all_symbols.append(symbols_prim[atom_index]) supercell_lattice = lattice.copy() supercell_lattice[0] *= n1 supercell_lattice[1] *= n2 supercell_lattice[2] *= n3 return ( np.array(all_positions), np.array(all_displacements), all_symbols, supercell_lattice, )
[docs] def write_displaced_structure( self, positions: NDArray[np.float64], displacements: NDArray[np.float64], symbols: list[str], supercell_lattice: NDArray[np.float64], amplitude: float, output_path: str, ) -> None: """Write ``positions + amplitude * displacements`` as a POSCAR. The atoms are grouped by species, in the order the species first appear in ``symbols`` (one block per element, ``Sc F`` / ``8 24``, as ``--modulation`` writes them); within a species they keep their order. Args: positions: Cartesian positions from :meth:`get_supercell_displacements`. displacements: The unit-amplitude displacements from the same call. symbols: Chemical symbols of the atoms. supercell_lattice: Supercell lattice vectors as rows. amplitude: Displacement amplitude in Angstroms. output_path: Output file path (VASP format, direct coordinates). """ first_seen: dict[str, int] = {} for symbol in symbols: first_seen.setdefault(symbol, len(first_seen)) order = sorted(range(len(symbols)), key=lambda index: first_seen[symbols[index]]) displaced = np.asarray(positions) + amplitude * np.asarray(displacements) atoms = Atoms( symbols=[symbols[index] for index in order], positions=displaced[order], cell=supercell_lattice, pbc=True, ) ase_write(output_path, atoms, format="vasp", direct=True)
def format_fraction_vector(qpoint) -> str: """Coordinates as ``(0, 0, 1/2)``: each component as a fraction of denominator at most 24 where it is one (``1/3``, ``-1/2``), else with four decimals. Args: qpoint: Three fractional coordinates. Returns: The text, e.g. ``"(1/3, 1/3, 0)"``. """ parts = [] for value in qpoint: value = float(value) fraction = Fraction(value).limit_denominator(24) if abs(float(fraction) - value) < 1e-6: parts.append(str(fraction)) else: parts.append(f"{value + 0.0:.4f}") return "(" + ", ".join(parts) + ")" def _in_seekpath_order( vibrations: "SymmetryOnlyVibrations", qpoints: dict[str, list[float]] ) -> dict[str, list[float]]: """The special q points in the order seekpath lists its points. The set, names and coordinates are those of :meth:`SymmetryOnlyVibrations.get_special_qpoints`; only the display order follows seekpath (``GM, A, K, H, M, L`` for P6_3mc). A point that matches no seekpath point (mod G) keeps its table position after the matched ones; the table order is kept when seekpath fails. """ import warnings try: with warnings.catch_warnings(): warnings.simplefilter("ignore") seek_points = list(vibrations.get_high_symmetry_qpoints().values()) except Exception: return qpoints def rank(item: tuple[int, tuple[str, list[float]]]) -> tuple[int, int]: table_index, (_, coords) = item for seek_index, seek in enumerate(seek_points): delta = np.asarray(coords, dtype=float) - np.asarray(seek, dtype=float) if np.allclose(delta, np.rint(delta), atol=1e-6): return seek_index, table_index return len(seek_points), table_index ordered = sorted(enumerate(qpoints.items()), key=rank) return {label: coords for _, (label, coords) in ordered} def _print_qpoint_block(title: str, qpoints: dict[str, list[float]]) -> None: print(f"\n* {title} *") for label, coords in qpoints.items(): print(f" {label:8s} {format_fraction_vector(coords)}") def _print_mode_spaces( basis_spaces: list[NDArray[np.complex128]], irrep_labels: list[str], activities: list | None = None, mulliken: dict[str, str] | None = None, ) -> None: from .phonon_activity import _with_mulliken print("\n* Irrep-grouped vibration spaces *") for mode_index, (space, irrep_label) in enumerate(zip(basis_spaces, irrep_labels), start=1): dim = space.shape[0] activity = "" if activities is not None: activity = f", activity = {'+'.join(activities[mode_index - 1].activity)}" print( f" Mode Space {mode_index:2d}: irrep = {_with_mulliken(irrep_label, mulliken)}, " f"dimension = {dim}, component numbers = 1..{dim}{activity}" ) if activities is not None: from .phonon_activity import _activity_summary_parts print("\n* Gamma-point activity *") for part in _activity_summary_parts(activities, True, mulliken): print(part) print(" (acoustic: one set per occurrence of the irrep in the vector representation;") print(" without force constants the mode spaces are symmetry-adapted patterns,") print(" not normal modes)") def _print_gamma_extras(vibrations, cell, irrep_labels, args, mulliken=None) -> None: """The Wyckoff-orbit breakdown at Gamma and, with ``--raman-tensor``, the Raman tensors in the axes of the input cell.""" from .phonon_activity import ( _gamma_irreps, _input_axes_vibrations, _raman_records, format_raman_tensors, format_wyckoff_orbits, wyckoff_orbit_decomposition, ) lines = format_wyckoff_orbits( wyckoff_orbit_decomposition(vibrations), irrep_labels, mulliken=mulliken ) print("\n* Wyckoff-orbit breakdown (Gamma) *") print("\n".join(lines[1:])) if args.raman_tensor: table = _gamma_irreps(_input_axes_vibrations(cell, args.tolerance)) lines = format_raman_tensors(_raman_records(table), mulliken=mulliken) print("\n* Raman tensors (Cartesian axes of the input cell) *") print("\n".join(lines[1:])) def _gamma_space_activities(vibrations, qpoint, basis_spaces, irrep_labels) -> list | None: """The activity of every mode space when q is Gamma, else None; None too when the spaces cannot be matched one to one (never expected).""" from .phonon_activity import _is_gamma, mode_space_activities if not _is_gamma(qpoint): return None activities = mode_space_activities(vibrations, qpoint) expected = [(re.sub(r"\(\d+\)$", "", label), space.shape[0]) for label, space in zip(irrep_labels, basis_spaces)] found = [(record.labels[0], record.dimension) for record in activities] return activities if found == expected else None def _gamma_mulliken(vibrations, qpoint) -> dict[str, str]: """The Mulliken symbols of the Gamma irreps when q is Gamma, else {}.""" from .phonon_activity import _is_gamma, mulliken_symbols if not _is_gamma(qpoint): return {} try: return mulliken_symbols(vibrations) except Exception as exc: # the bracket is an annotation; never fail on it import warnings warnings.warn(f"no Mulliken symbols: {exc}", stacklevel=2) return {} def main(argv: list[str] | None = None) -> None: """``crystod-phonon --vibration``: the run; with ``--qpoint`` its report is saved as ``vibration_<formula>_<q>`` (with ``--mode-index`` N: ``..._space<N>[_comp<M>]``) unless ``--no-files`` or ``CRYSTOD_NO_REPORT``; ``--list-qpoints`` alone saves nothing.""" from .cli.common import SavedReport args = build_parser().parse_args(argv) with SavedReport(enabled=not args.no_files) as report: _run(args, report) def _run(args, report) -> None: from .phonon_vector import reduced_formula from .star_of_k import read_poscar_or_exit # one mode-space component is written, so one amplitude (per selected mode) if len(args.amplitude) != 1: raise SystemExit( f"ERROR: --vibration writes one mode-space component (--mode-index, " f"--component-index), so --amplitude takes one value; got " f"{len(args.amplitude)} ({' '.join(f'{value:g}' for value in args.amplitude)})." ) amplitude = args.amplitude[0] cell = read_poscar_or_exit(args.poscar) vibrations = SymmetryOnlyVibrations(cell=cell, symprec=args.tolerance) _print_qpoint_block( "Q points (primitive)", _in_seekpath_order(vibrations, vibrations.get_special_qpoints()), ) if args.list_qpoints: return if not args.qpoint: raise ValueError("--qpoint is required unless --list-qpoints is used.") try: qpoint_label, qpoint = vibrations.resolve_special_qpoint(args.qpoint) except ValueError as exc: raise SystemExit(f"ERROR: {exc}") from None if args.raman_tensor and not np.allclose(qpoint, np.rint(qpoint), atol=1e-8): raise SystemExit( f"ERROR: --raman-tensor is defined at Gamma only (--qpoint GM); got " f"{qpoint_label} = {format_fraction_vector(qpoint)}." ) _print_qpoint_block("Selected Q point", {qpoint_label: qpoint}) if args.mode_index is not None: # the written structure must be periodic: a q that no supercell of at # most 12 cells per axis holds is refused before any space is computed # (as --modulation does); the spaces can still be listed without # --mode-index try: vibrations.get_supercell_size(qpoint) except ValueError as exc: raise SystemExit(f"ERROR: {exc}") from None irreps, basis_spaces, irrep_labels = vibrations.describe_mode_spaces(qpoint) activities = _gamma_space_activities(vibrations, qpoint, basis_spaces, irrep_labels) mulliken = _gamma_mulliken(vibrations, qpoint) _print_mode_spaces(basis_spaces, irrep_labels, activities, mulliken) if activities is not None: _print_gamma_extras(vibrations, cell, irrep_labels, args, mulliken) stem = f"{reduced_formula(list(cell.symbols))}_{qpoint_label}" if args.mode_index is None: report.name = f"vibration_{stem}" return if args.mode_index < 1 or args.mode_index > len(basis_spaces): raise SystemExit( f"ERROR: mode-space number {args.mode_index} is out of range " f"[1, {len(basis_spaces)}] (numbering is 1-based)." ) selected_space = basis_spaces[args.mode_index - 1] if args.component_index < 1 or args.component_index > selected_space.shape[0]: raise SystemExit( f"ERROR: component number {args.component_index} is out of range " f"[1, {selected_space.shape[0]}] (numbering is 1-based)." ) # the symmetry-adapted partner, not the raw projected row: its Bloch phase # and, at a time-reversal-invariant q, its partner basis are fixed so that # the component freezes into an isotropy subgroup of its irrep adapted_spaces = vibrations.get_symmetry_adapted_spaces(qpoint) if [space.shape for space in adapted_spaces] != [space.shape for space in basis_spaces]: raise RuntimeError("The symmetry-adapted spaces do not match the projected spaces.") mode_vector = adapted_spaces[args.mode_index - 1][args.component_index - 1] supercell_size = vibrations.get_supercell_size(qpoint) print("\n* Selected basis vector *") print(f"Selected mode space: {args.mode_index}") print(f"Selected irrep : {irrep_labels[args.mode_index - 1]}") print(f"Selected component : {args.component_index}") print(f"Commensurate supercell size: {supercell_size}") positions, displacements, symbols, supercell_lattice = vibrations.get_supercell_displacements( qpoint=qpoint, mode_vector=mode_vector, supercell_size=supercell_size, ) norms = np.linalg.norm(displacements, axis=1) print(f"Supercell atom count: {len(symbols)}") print(f"Displacement norm range (unit amplitude): min={norms.min():.6f}, max={norms.max():.6f}") print("First 5 displacement vectors:") for index in range(min(5, len(displacements))): print( f" {index:2d} {symbols[index]:2s} " f"pos={np.round(positions[index], 6).tolist()} " f"disp={np.round(displacements[index], 6).tolist()}" ) if args.export_npz: extra = {} if activities is not None: extra["activities"] = np.array( ["+".join(record.activity) for record in activities], dtype=object ) np.savez( args.export_npz, **extra, positions=positions, displacements=displacements, symbols=np.array(symbols, dtype=object), supercell_lattice=supercell_lattice, qpoint=np.array(qpoint, dtype=float), qpoint_label=np.array(qpoint_label, dtype=object), mode_index=np.array(args.mode_index), component_index=np.array(args.component_index), irrep_labels=np.array(irrep_labels, dtype=object), selected_irrep_label=np.array(irrep_labels[args.mode_index - 1], dtype=object), mode_space_dimensions=np.array([space.shape[0] for space in basis_spaces], dtype=int), selected_mode_dimension=np.array(selected_space.shape[0], dtype=int), amplitude=np.array(amplitude, dtype=float), ) print(f"Saved mode data to: {args.export_npz}") tags = f"{stem}_space{args.mode_index}" if selected_space.shape[0] > 1: tags += f"_comp{args.component_index}" output_path = args.output or f"VPOSCAR_{tags}" vibrations.write_displaced_structure( positions=positions, displacements=displacements, symbols=symbols, supercell_lattice=supercell_lattice, amplitude=amplitude, output_path=output_path, ) print(f"Saved displaced structure to: {output_path}") report.name = f"vibration_{tags}" if __name__ == "__main__": main()