Source code for crystod.phonon_unfold_irreps

"""Parent-irrep labels of unfolded phonon levels (``crystod-phonon --unfold``).

The unfolded vectors u_J(k) of :mod:`crystod.phonon_unfold` (child mode J
projected onto the Bloch states of the parent at the parent k) are decomposed
into the irreps of the little group of k of the parent with CrystOD's own
machinery: :class:`crystod.vibration_modes.SymmetryOnlyVibrations` on the
parent primitive cell as it is (``standardize=False``, ISO-IR frame of the
parent file) gives the spgrep small irreps and the displacement
representation Gamma(g) of the little co-group, ``get_irrep_labels`` their
ISO-IR names, and :func:`crystod.phonon_activity.mulliken_symbols` the
Mulliken symbols at GM.  The labels are those of ``crystod-phonon --irreps``
on the parent POSCAR (with Ti at the origin of CaTiO3 the tilts are R4+ and
M3+).

For every irrep i present in the displacement representation the isotypic
projector is ``Pi_i = (d_i / |G0|) sum_g conj(chi_i(g)) Gamma(g)`` (checked:
complete, idempotent, Hermitian, mutually orthogonal, commuting with the
masses).  A pair of complex irreps that time reversal makes degenerate
(Wigner's case (c), :func:`crystod.extract_irrep._time_reversal`) is one unit
with the projector ``Pi_a + Pi_b`` and the name ``S1+S2``.  The weight of unit
u in child mode J is ``P_J^(u)(k) = || Pi_u R u_J(k) ||^2`` (R: the rigid
rotation from the child to the parent Cartesian frame); ``sum_u P_J^(u) =
P_J``.

Labels belong to degenerate groups g of child modes (``|df| <= 1e-4`` THz): with
``P_g = sum_{J in g} P_J`` and ``f_u = sum_{J in g} P_J^(u) / P_g`` the group
gets the unit with ``f_u >= 0.5``; otherwise the smallest set of units that
the child symmetry cannot separate with a summed fraction >= 0.5, written
``Z1/Z3``; otherwise ``mixed``; ``-`` when ``P_g`` is below the weight cut.
Units u and v cannot be separated when one child level can hold weight in
both: an irrep of H(k) (the child operations that fix k) in u and one in v
occur together in one irrep of the child little group of K = M k, or in its
time-reversal partner.  By Mackey's theorem this is a non-zero multiplicity
``<Res_H Ind_H^G(K) u, v>_H`` (plus the same with the induced representation
conjugated by a child operation that takes K to -K): the child operations of
the little group of K that take k to another arm folding onto K, and time
reversal, join the partners of a degenerate child level that carry different
irreps of H(k) (DT1 and DT5 at k = (0, 1/4, 0) of Pnma CaTiO3, which folds
onto the child Y point).

Along a straight run of path points with the same little group the ISO-IR
names are computed at the first point and copied to the others by matching
the characters stripped of their Bloch phase (``chi(g) exp(+2 pi i k.t_g)``,
constant along a line), and checked again at the last point of the run.

Conventions: those of :mod:`crystod.phonon_unfold` (rows = lattice vectors,
``A_child = M @ A_parent``, ``k_child = M @ k_parent``, THz, imaginary
negative).  CPU only (numpy): the projectors are at most a few tens square.
"""

from __future__ import annotations

import re
import time
import warnings
from dataclasses import dataclass, field
from types import SimpleNamespace

import numpy as np

from .spglib_compat import ensure_spglib_compat

ensure_spglib_compat()

from .phonon_unfold import (  # noqa: E402
    CHUNK,
    DEGENERACY_TOLERANCE,
    FRACTION_MIN,
    PROJECTOR_TOLERANCE,
    SYMPREC,
    WEIGHT_MIN,
    _cell_tuple,
    _check_child_cell,
    _operations,
    _run_qpoints,
    _vec,
    degenerate_groups,
    rotate_unfolded_vectors,
)

_LABEL_RE = re.compile(r"^(?P<name>.*?)\((?P<dim>\d+)\)$")
_STRIPPED_TOLERANCE = 1e-6  # characters of one irrep at two points of a straight run


def split_label(label: str):
    """``'R4+(3)'`` -> ``('R4+', 3)``; a label without the dimension suffix -> ``(label, None)``."""
    m = _LABEL_RE.match(label.strip())
    if m is None:
        return label.strip(), None
    return m.group("name"), int(m.group("dim"))


def kname_of(name: str):
    """k-vector type of an ISO-IR irrep name: ``'GM4-'`` -> ``'GM'``, ``'irrep_2'`` -> None."""
    m = re.match(r"^([A-Z]+)\d", name)
    return m.group(1) if m else None


def irrep_sort_key(name: str):
    """Natural order of the irreps of one k type: index, then '+' before '-' (GM1+, GM1-, ...)."""
    m = re.match(r"^([A-Z]+)(\d+)([+-]?)", name)
    if m is None:
        return (1, name, 0, 0)
    return (0, m.group(1), int(m.group(2)), {"+": 0, "": 1, "-": 2}[m.group(3)])


@dataclass
class IrrepProjectorSet:
    """The isotypic projectors of the parent displacement representation at one k.

    Attributes:
        k: (3,) parent fractional k.
        little_ops: (``|G0|``,) indices of the little co-group operations in the
            operations of :class:`ParentIrrepBasis`.
        order: ``|G0|``.
        irreps: The spgrep small irreps at k (all of them).
        characters: (n_irrep, ``|G0|``) their characters.
        stripped: (n_irrep, ``|G0|``) characters times ``exp(+2 pi i k.t_g)``.
        present: Indices of the irreps that occur in the displacement representation.
        projectors: (n_present, 3 n, 3 n) orthogonal projectors (parent atom
            order, Cartesian components of the parent frame, tau phase).
        dims, multiplicities: (n_present,) d_i and n_i (trace = d_i n_i).
        checks: Largest deviations of the projector identities.
        names: ISO-IR names of all irreps (no ``(dim)``); None before labeling.
        kname: ISO-IR k-vector type of k.
        labeled_directly: The names come from ``get_irrep_labels`` at this k
            (not copied along a run).
        units: Names of the units (an irrep, or a time-reversal pair ``S1+S2``),
            natural order; ``unit_members`` their positions in ``present``;
            ``unit_characters`` (n_units, ``|G0|``); ``unit_traces`` (n_units,).
        tr_pairs: The time-reversal pairs that form units.
        tr_failed: Wigner's test could not be made at k.
        classes: Units the child symmetry cannot separate (tuples of unit
            positions, classes of more than one unit), set by
            :func:`_inseparable_classes`; ``class_deviation`` the largest
            distance of the multiplicities behind them from integers.
    """

    k: np.ndarray
    little_ops: np.ndarray
    order: int
    irreps: list
    characters: np.ndarray
    stripped: np.ndarray
    present: np.ndarray
    projectors: np.ndarray
    dims: np.ndarray
    multiplicities: np.ndarray
    checks: dict
    names: list | None = None
    kname: str | None = None
    labeled_directly: bool = False
    units: list | None = None
    unit_members: list | None = None
    unit_characters: np.ndarray | None = None
    unit_traces: np.ndarray | None = None
    tr_pairs: list = field(default_factory=list)
    tr_failed: bool = False
    classes: list | None = None
    class_deviation: float = 0.0

    @property
    def present_names(self) -> list:
        return [self.names[i] for i in self.present]


class ParentIrrepBasis:
    """CrystOD irrep projectors of the parent primitive cell, cached per k.

    Args:
        cell: The parent primitive cell of the unfolding (PhonopyAtoms; it
            must be primitive as given).
        input_cell: The cell of the parent file, whose ISO-IR frame names the
            irreps (default ``cell``).
        symprec: spglib tolerance.

    Attributes:
        vib: The :class:`crystod.vibration_modes.SymmetryOnlyVibrations`.
        rotations, translations: Space-group operations of ``cell`` (spglib order).
        mulliken: ``{GM irrep: Mulliken symbol}``; empty when unavailable.
        notes: NOTE lines (Mulliken symbols missing, warnings of the tables).
        child_ops: Indices of the operations that are child operations (set by
            :func:`irrep_resolve`).
        child_affine: The child operations in the parent setting with their
            conjugation table (:func:`_child_affine_operations`, set by
            :func:`irrep_resolve`).
    """

    def __init__(self, cell, input_cell=None, symprec: float = SYMPREC):
        from .phonon_activity import mulliken_symbols
        from .vibration_modes import SymmetryOnlyVibrations

        with warnings.catch_warnings():
            warnings.simplefilter("ignore", DeprecationWarning)
            self.vib = SymmetryOnlyVibrations(
                cell, symprec=symprec, standardize=False, input_cell=input_cell, quiet=True
            )
        primitive = self.vib.primitive_cell
        if (
            len(primitive) != len(cell)
            or np.abs(np.array(primitive.cell) - np.array(cell.cell)).max() > 1e-10
            or np.abs(np.array(primitive.scaled_positions) - np.array(cell.scaled_positions)).max()
            > 1e-10
        ):
            raise SystemExit(
                "ERROR: internal error: the irrep analysis changed the parent primitive cell."
            )
        self.cell = cell
        self.input_cell = cell if input_cell is None else input_cell
        self.lattice, self.frac, self.numbers = _cell_tuple(cell)
        self.masses = np.array(cell.masses, dtype=float)
        self.n_atoms = len(cell)
        self.symprec = symprec
        self.rotations = np.asarray(self.vib.rotations, dtype=np.int64)
        self.translations = np.asarray(self.vib.translations, dtype=float)
        self.space_group_number = int(self.vib.spglib_dataset["number"])
        self.notes: list = []
        self.child_ops = None
        self.child_affine = None
        self._sets: dict = {}
        self.label_time = 0.0
        try:
            with warnings.catch_warnings(record=True) as caught:
                warnings.simplefilter("always")
                self.mulliken = mulliken_symbols(self.vib)
            for warning in caught:
                if not issubclass(warning.category, DeprecationWarning):
                    self.notes.append("NOTE: " + " ".join(str(warning.message).split()))
        except Exception as exc:  # the brackets are an annotation: say why they are missing
            self.mulliken = {}
            self.notes.append(
                "NOTE: no Mulliken symbols: " + (" ".join(str(exc).split()) or type(exc).__name__)
            )

    # -- projectors --------------------------------------------------------
    def build(self, k):
        """``(projector set at k (cached), displacement representation (|G0|, 3n, 3n))``."""
        from .runtime_compat import get_character

        k = np.asarray(k, dtype=float).reshape(3)
        key = tuple(np.round(k, 10) + 0.0)
        with warnings.catch_warnings():
            warnings.simplefilter("ignore", DeprecationWarning)
            irreps, rep, ops = self.vib.get_vibration_rep([float(v) for v in k])
        ops = np.asarray(ops, dtype=np.int64)
        pset = self._sets.get(key)
        if pset is not None:
            return pset, rep
        order = len(rep)
        n3 = rep.shape[1]
        characters = np.array([np.asarray(get_character(ir), dtype=complex) for ir in irreps])
        stripped = characters * np.exp(2j * np.pi * (self.translations[ops] @ k))[None, :]
        present, projectors, dims, mults = [], [], [], []
        for i, ir in enumerate(irreps):
            d = int(ir.shape[1])
            P = (d / order) * np.einsum("g,gij->ij", characters[i].conj(), rep)
            trace = float(np.real(np.trace(P)))
            if trace < 0.5:  # irrep absent from the displacement representation
                continue
            n_i = trace / d
            if abs(n_i - round(n_i)) > 1e-6:
                raise SystemExit(
                    f"ERROR: internal error: non-integer multiplicity {n_i:.6f} of an irrep at k = "
                    f"{_vec(k)}."
                )
            present.append(i)
            projectors.append(P)
            dims.append(d)
            mults.append(int(round(n_i)))
        projectors = np.array(projectors)
        mass3 = np.repeat(self.masses, 3)
        cross = 0.0
        for a in range(len(projectors)):
            for b in range(a + 1, len(projectors)):
                cross = max(cross, float(np.abs(projectors[a] @ projectors[b]).max()))
        checks = {
            "completeness": float(np.abs(projectors.sum(axis=0) - np.eye(n3)).max()),
            "idempotency": float(max(np.abs(P @ P - P).max() for P in projectors)),
            "hermiticity": float(max(np.abs(P - P.conj().T).max() for P in projectors)),
            "orthogonality": cross,
            "mass_commutator": float(
                max(np.abs(P * mass3[None, :] - mass3[:, None] * P).max() for P in projectors)
            ),
        }
        worst = max(checks, key=checks.get)
        if checks[worst] > PROJECTOR_TOLERANCE:
            raise SystemExit(
                f"ERROR: internal error: the irrep projectors at k = {_vec(k)} fail the {worst} "
                f"check ({checks[worst]:.1e})."
            )
        pset = IrrepProjectorSet(
            k=k.copy(),
            little_ops=ops,
            order=order,
            irreps=list(irreps),
            characters=characters,
            stripped=stripped,
            present=np.array(present, dtype=np.int64),
            projectors=projectors,
            dims=np.array(dims, dtype=np.int64),
            multiplicities=np.array(mults, dtype=np.int64),
            checks=checks,
        )
        self._sets[key] = pset
        return pset, rep

    def projector_set(self, k) -> IrrepProjectorSet:
        """The projector set at k, labeled and with its time-reversal units."""
        pset, _rep = self.build(k)
        if pset.names is None:
            self.label_directly(pset)
        if pset.units is None:
            self.make_units(pset)
        return pset

    # -- names ---------------------------------------------------------------
    def direct_labels(self, pset: IrrepProjectorSet):
        """``(names of all irreps, k type)`` from ``get_irrep_labels`` at the point of ``pset``."""
        t0 = time.perf_counter()
        with warnings.catch_warnings():
            warnings.simplefilter("ignore", DeprecationWarning)
            labels = self.vib.get_irrep_labels(
                [float(v) for v in pset.k], pset.irreps, pset.little_ops
            )
        names = [split_label(label)[0] for label in labels]
        kname = (
            getattr(self.vib, "isoir_qpoint_name", None)
            if getattr(self.vib, "labels_from_isoir", False)
            else None
        )
        knames = {kname_of(names[i]) for i in pset.present} - {None}
        if kname is None or kname not in knames:
            kname = sorted(knames)[0] if knames else "k"
        self.label_time += time.perf_counter() - t0
        return names, kname

    def label_directly(self, pset: IrrepProjectorSet) -> None:
        pset.names, pset.kname = self.direct_labels(pset)
        pset.labeled_directly = True
        pset.units = None

    def make_units(self, pset: IrrepProjectorSet) -> None:
        """Group the present irreps into units; time-reversal pairs (Wigner's case (c)) are one."""
        from .extract_irrep import _time_reversal

        group = SimpleNamespace(
            kpoint=pset.k,
            rotations=self.rotations[pset.little_ops],
            translations=self.translations[pset.little_ops],
            characters=pset.characters,
            names=list(pset.names),
            order=pset.order,
            spin_rotations=None,
        )
        reversal = _time_reversal(group, self.lattice, self.frac, self.numbers, self.symprec)
        present_names = pset.present_names
        position = {name: a for a, name in enumerate(present_names)}
        units, members, pairs, done = [], [], [], set()
        for a, name in enumerate(present_names):
            if a in done:
                continue
            partner = None
            if reversal and name in reversal and reversal[name][0] == "c":
                other = reversal[name][1]
                if other != name and other in position and position[other] not in done:
                    partner = other
            if partner is None:
                units.append(name)
                members.append((a,))
                done.add(a)
            else:
                pair = tuple(sorted((name, partner), key=irrep_sort_key))
                units.append("+".join(pair))
                members.append(tuple(position[x] for x in pair))
                pairs.append(pair)
                done |= {a, position[partner]}
        order = sorted(range(len(units)), key=lambda i: irrep_sort_key(units[i]))
        pset.units = [units[i] for i in order]
        pset.unit_members = [members[i] for i in order]
        chars = pset.characters[pset.present]
        pset.unit_characters = np.array([chars[list(m)].sum(axis=0) for m in pset.unit_members])
        pset.unit_traces = np.array(
            [int(sum(pset.dims[j] * pset.multiplicities[j] for j in m)) for m in pset.unit_members]
        )
        pset.tr_pairs = pairs
        pset.tr_failed = reversal is None


# ---------------------------------------------------------------------------
# helpers
# ---------------------------------------------------------------------------
def irrep_weights(vectors, projectors) -> np.ndarray:
    """``||Pi_i v||^2`` for the rows v of ``vectors`` (n_vec, 3n): shape (n_vec, n_projector)."""
    v = np.atleast_2d(np.asarray(vectors, dtype=complex))
    pv = np.einsum("iab,nb->nia", np.asarray(projectors), v)
    return np.sum(np.abs(pv) ** 2, axis=-1)


def _unit_weights(pset: IrrepProjectorSet, irrep_w) -> np.ndarray:
    """Weights per unit (sum over the members of each unit), shape (n_vec, n_units)."""
    return np.stack([irrep_w[:, list(m)].sum(axis=1) for m in pset.unit_members], axis=1)


def child_operations_in_parent(mapping, basis: ParentIrrepBasis, symprec: float = SYMPREC):
    """The space-group operations of the child, written in the parent setting.

    A child operation (W_c, w_c) becomes, with ``x_parent = M.T x_child + p``,
    ``W_p = M.T W_c inv(M.T)`` and ``w_p = M.T w_c + p - W_p p``; each must be
    an operation of the parent (same rotation, translation equal modulo the
    parent lattice).

    Returns:
        ``(sorted indices of those parent operations, number of child
        operations, largest translation mismatch)``.
    """
    rotations, translations = _operations(mapping.child_cell, symprec)
    MT = mapping.M.T.astype(float)
    MT_inv = np.linalg.inv(MT)
    p = np.asarray(mapping.origin_shift, dtype=float)
    found, worst = set(), 0.0
    for Wc, wc in zip(rotations, translations):
        Wp = MT @ Wc @ MT_inv
        Wi = np.rint(Wp).astype(np.int64)
        best = None
        if np.abs(Wp - Wi).max() < 1e-8:
            wp = MT @ wc + p - Wi @ p
            for j in np.where(np.all(basis.rotations == Wi[None], axis=(1, 2)))[0]:
                dt = basis.translations[j] - wp
                dev = float(np.abs(dt - np.rint(dt)).max())
                if dev < 1e-3 and (best is None or dev < best[1]):
                    best = (int(j), dev)
        if best is None:
            raise SystemExit(
                "ERROR: internal error: a child operation is not a parent operation in this "
                "setting."
            )
        found.add(best[0])
        worst = max(worst, best[1])
    return sorted(found), len(rotations), worst


def _child_positions(pset: IrrepProjectorSet, child_ops) -> list:
    """Positions (in the little co-group of k) of the child operations that belong to it: H(k)."""
    position = {int(j): a for a, j in enumerate(pset.little_ops)}
    return [position[j] for j in child_ops if j in position]


def _child_affine_operations(mapping, basis: ParentIrrepBasis, symprec: float = SYMPREC):
    """The child operations in the parent setting, with their conjugation table.

    A child operation (W_c, w_c) is ``W = M.T W_c inv(M.T)``, ``w = M.T w_c + p
    - W p`` in parent fractional coordinates (the coset representatives of the
    child modulo its own lattice).  For every pair (x, h) the table holds the
    child coset of ``y = x^-1 h x`` and the parent lattice vector ``t`` with
    ``y = (W_j, w_j + t)``, (W_j, w_j) the parent operation of that coset, so
    that the character of y at k is ``chi(j) exp(-2 pi i k.t)`` (the
    convention of the spgrep small representations: ``D((E, t) g) = exp(-2 pi
    i k.t) D(g)``).

    Returns:
        A namespace with ``rotations`` (n_c, 3, 3) int64, ``translations``
        (n_c, 3), ``parent_index`` (n_c,) (the parent operation of each
        child operation), ``lattice`` (n_c, 3) (``w - w_j``, integers),
        ``conj_index`` (n_c, n_c) and ``conj_lattice`` (n_c, n_c, 3) (``[x, h]``
        for ``x^-1 h x``).
    """
    rotations, translations = _operations(mapping.child_cell, symprec)
    MT = mapping.M.T.astype(float)
    MT_inv = np.linalg.inv(MT)
    p = np.asarray(mapping.origin_shift, dtype=float)
    W = np.array([np.rint(MT @ Wc @ MT_inv) for Wc in rotations], dtype=np.int64)
    w = np.array([MT @ wc + p - Wp @ p for Wp, wc in zip(W, translations)], dtype=float)
    parent_index = np.empty(len(W), dtype=np.int64)
    for c, Wp in enumerate(W):
        match = np.flatnonzero(np.all(basis.rotations == Wp[None], axis=(1, 2)))
        if len(match) != 1:
            raise SystemExit(
                "ERROR: internal error: a child operation is not a parent operation in this "
                "setting."
            )
        parent_index[c] = match[0]
    lattice = w - basis.translations[parent_index]
    by_rotation = {W[c].tobytes(): c for c in range(len(W))}
    n = len(W)
    conj_index = np.empty((n, n), dtype=np.int64)
    conj_lattice = np.empty((n, n, 3), dtype=float)
    worst = float(np.abs(lattice - np.rint(lattice)).max()) if n else 0.0
    for x in range(n):
        Wx_inv = np.rint(np.linalg.inv(W[x])).astype(np.int64)
        for h in range(n):
            Wy = Wx_inv @ W[h] @ W[x]
            wy = Wx_inv @ (W[h] @ w[x] + w[h] - w[x])
            c = by_rotation.get(Wy.tobytes())
            if c is None:
                raise SystemExit(
                    "ERROR: internal error: the child operations do not close under conjugation."
                )
            t = wy - basis.translations[parent_index[c]]
            worst = max(worst, float(np.abs(t - np.rint(t)).max()))
            conj_index[x, h] = c
            conj_lattice[x, h] = np.rint(t)
    if worst > 1e-3:
        raise SystemExit(
            "ERROR: internal error: a child operation is not a parent operation in this setting "
            f"(translation off by {worst:.1e})."
        )
    return SimpleNamespace(
        rotations=W,
        translations=w,
        parent_index=parent_index,
        lattice=np.rint(lattice),
        conj_index=conj_index,
        conj_lattice=conj_lattice,
    )


def _inseparable_classes(pset: IrrepProjectorSet, basis: ParentIrrepBasis, mapping) -> list:
    """Units the child symmetry cannot separate; classes of more than one unit.

    Units u and v are linked when an irrep of H(k) (the child operations that
    fix k) in u and one in v occur together in one irrep of the child little
    group G(K) of K = M k, or in its time-reversal partner, i.e. when one
    child level can hold weight in both.  With Mackey's theorem the test is
    ``<Res_H Ind_H^G u, v>_H + <Res_H (Ind_H^G u)', v>_H > 0``, where the
    prime is the conjugation by an antiunitary operation (time reversal times
    a child operation A that takes K to -K): ``chi'(h) = conj(chi(A^-1 h A))``.
    Both multiplicities are non-negative integers (checked: the largest
    distance from integers is kept in ``pset.class_deviation``).  Without the
    induction (u and v sharing an irrep of H(k) only) the partners of a
    degenerate child level that carry different irreps of H(k) would be
    called separable.  Classes are the connected components of the links.

    Returns a list of tuples of unit positions (natural order); cached on ``pset``.
    """
    if pset.classes is not None:
        return pset.classes
    if basis.child_affine is None:
        basis.child_affine = _child_affine_operations(mapping, basis, basis.symprec)
    ops = basis.child_affine
    n_units = len(pset.units)
    if n_units < 2:
        pset.classes, pset.class_deviation = [], 0.0
        return pset.classes
    k = np.asarray(pset.k, dtype=float)
    M = np.asarray(mapping.M, dtype=float)
    rotated = np.einsum("cji,j->ci", ops.rotations, k)  # W^T k

    def integer(v):
        return np.all(np.abs(v - np.rint(v)) < 1e-8, axis=-1)

    in_H = integer(rotated - k)
    H = np.flatnonzero(in_H)
    G = np.flatnonzero(integer((rotated - k) @ M.T))
    A = np.flatnonzero(integer((rotated + k) @ M.T))
    position = np.full(len(basis.rotations), -1, dtype=np.int64)
    position[np.asarray(pset.little_ops, dtype=np.int64)] = np.arange(len(pset.little_ops))
    chars = np.asarray(pset.unit_characters, dtype=complex)

    def characters(cosets, lattice):
        """Characters (n_units, *shape) of the elements (coset, parent lattice translation)."""
        cols = position[ops.parent_index[cosets]]
        phase = np.exp(-2j * np.pi * (lattice @ k))
        return chars[:, np.where(cols >= 0, cols, 0)] * np.where(cols >= 0, phase, 0.0)

    order = len(H)
    chi_H = characters(H, ops.lattice[H])  # (n_units, |H|)

    def induced(X):
        """(1/|H|) sum_{x in X, x^-1 h x in H} chi_u(x^-1 h x) for every h in H: (n_units, |H|)."""
        if len(X) == 0:
            return np.zeros((n_units, order), dtype=complex)
        cosets = ops.conj_index[np.ix_(X, H)]  # (|X|, |H|)
        lattice = ops.conj_lattice[np.ix_(X, H)]  # (|X|, |H|, 3)
        values = characters(cosets, lattice) * in_H[cosets][None]
        return values.sum(axis=1) / order

    L = induced(G) @ chi_H.conj().T / order + induced(A).conj() @ chi_H.conj().T / order
    deviation = float(max(np.abs(L.imag).max(), np.abs(L.real - np.rint(L.real)).max()))
    link = np.rint(L.real) >= 1
    link = link | link.T
    classes, seen = [], set()
    for i in range(n_units):
        if i in seen:
            continue
        stack, component = [i], set()
        while stack:
            a = stack.pop()
            if a in component:
                continue
            component.add(a)
            stack.extend(int(b) for b in np.flatnonzero(link[a]) if b not in component)
        seen |= component
        if len(component) > 1:
            classes.append(tuple(sorted(component, key=lambda u: irrep_sort_key(pset.units[u]))))
    pset.classes, pset.class_deviation = classes, deviation
    return classes


def _unit_member_names(unit: str, pset: IrrepProjectorSet) -> tuple:
    index = pset.units.index(unit)
    names = pset.present_names
    return tuple(names[j] for j in pset.unit_members[index])


def _group_labels(
    pset: IrrepProjectorSet, classes, unit_w, freqs, P, weight_min: float, tol: float
):
    """The label rule on the degenerate groups of child modes at one k.

    Fractions are compared after rounding to 1e-9, and ties go by the natural
    order of the irreps (:func:`irrep_sort_key`; ``pset.units`` is in that
    order): of two irreps with 50 % each the first is the label (the fractions
    column lists both), of two sets with the same number of irreps and the same
    share the one whose sorted names come first.  The rule therefore does not
    depend on round-off.

    Returns per mode: label (str), members (tuple of irrep names), fraction;
    and the list of groups ``(indices, label, members, fraction, P_g, f (n_units,))``.
    """
    n_band = len(freqs)
    labels = ["-"] * n_band
    members = [()] * n_band
    fractions = np.zeros(n_band)
    groups = []
    for g in degenerate_groups(freqs, tol):
        Pg = float(P[g].sum())
        f = unit_w[g].sum(axis=0) / Pg if Pg > 0 else np.zeros(len(pset.units))
        fr = np.round(f, 9)  # the fractions the rule compares
        if Pg < weight_min:
            label, mem, frac = "-", (), 0.0
        else:
            best = float(fr.max())
            if best >= FRACTION_MIN:
                u = int(np.flatnonzero(fr == best)[0])  # ties: natural order
                label, chosen = pset.units[u], [u]
            else:
                candidates = []
                for cls in classes:
                    ranked = sorted(cls, key=lambda u: (-fr[u], irrep_sort_key(pset.units[u])))
                    chosen, total = [], 0.0
                    for u in ranked:
                        chosen.append(u)
                        total = round(total + float(fr[u]), 9)
                        if total >= FRACTION_MIN:
                            break
                    if total >= FRACTION_MIN:
                        names = sorted((pset.units[u] for u in chosen), key=irrep_sort_key)
                        candidates.append(
                            (len(chosen), -total, [irrep_sort_key(n) for n in names], chosen)
                        )
                if candidates:
                    chosen = min(candidates, key=lambda c: c[:3])[3]
                    label = "/".join(sorted((pset.units[u] for u in chosen), key=irrep_sort_key))
                else:
                    label, chosen = "mixed", []
            mem = tuple(
                name
                for u in sorted(chosen, key=lambda u: irrep_sort_key(pset.units[u]))
                for name in _unit_member_names(pset.units[u], pset)
            )
            frac = float(sum(f[u] for u in chosen)) if chosen else 0.0
        for J in g:
            labels[J], members[J], fractions[J] = label, mem, frac
        groups.append((g, label, mem, frac, Pg, f))
    return labels, members, fractions, groups


def _selection_rules(rep_H, chi_H, vectors, freqs, P, irrep_w, weight_min: float, tol: float):
    """Selection rules of the child symmetry H on the degenerate groups of child modes at one k.

    The unfolded vectors of a group g (canonical: mutually orthogonal, with
    norms ``P_J``) span a subspace that H maps onto itself; its character
    ``chi_g(h) = Tr(Q^H Gamma(h) Q)`` (Q an orthonormal basis of the vectors
    with ``P_J > 1e-10``) contains the irreps of H the group carries, and the
    group's weight can lie only in parent irreps that share one of them.  For
    a non-degenerate mode ``chi_g`` is the one-dimensional character of H on
    its vector.  ``rep_H`` and ``chi_H`` are taken at the same parent coset
    representatives, so the lattice-translation phases cancel.  Returns
    ``(largest weight fraction of a group in forbidden irreps, largest
    residual ||(1 - Q Q^H) Gamma(h) Q|| of the subspaces, groups checked)``.
    """
    if len(rep_H) == 0:
        return 0.0, 0.0, 0
    forbidden = residual = 0.0
    checked = 0
    for g in degenerate_groups(freqs, tol):
        Pg = float(P[g].sum())
        if Pg < weight_min:
            continue
        keep = [int(J) for J in g if P[J] > 1e-10]
        Q, _r = np.linalg.qr(np.asarray(vectors[keep]).T)
        image = np.einsum("hab,bj->haj", rep_H, Q)
        block = np.einsum("ai,haj->hij", Q.conj(), image)
        residual = max(
            residual,
            float(np.abs(image - np.einsum("ai,hij->haj", Q, block)).max()),
        )
        chi_g = np.einsum("hii->h", block)
        m = np.real(chi_H @ chi_g.conj()) / len(rep_H)
        bad = m < 0.5
        forbidden = max(forbidden, float(irrep_w[g][:, bad].sum() / Pg))
        checked += 1
    return forbidden, residual, checked


def _match_stripped(reference, stripped):
    """Permutation ``perm`` with ``stripped[i] == reference[perm[i]]`` (one to one), or None."""
    if len(reference) != len(stripped):
        return None
    perm, used = [], set()
    for row in stripped:
        hits = [
            j
            for j in range(len(reference))
            if j not in used and np.abs(row - reference[j]).max() <= _STRIPPED_TOLERANCE
        ]
        if len(hits) != 1:
            return None
        perm.append(hits[0])
        used.add(hits[0])
    return perm


def _label_points(basis: ParentIrrepBasis, psets: list, path) -> dict:
    """Name the irreps of every projector set; along straight runs of the path copy the names.

    A run is a maximal set of consecutive interior points of one leg with the
    same little-group operations (points of one open line segment with the same
    little group are of one k type).  The end points of the legs (the vertices)
    never join a run: two different special points can share their little
    group and their phase-stripped characters (GM and R of a symmorphic cubic
    group), so they are always labeled directly.  The first point of a run is
    labeled directly, the others by matching phase-stripped characters; the
    last point of a run of three or more points is labeled directly as a
    check.  A failed match or a check that disagrees labels the whole run point
    by point (counted as a mismatch).
    """
    stats = {"runs": 0, "labeled_directly": 0, "copied": 0, "mismatches": 0}
    if path is None:
        for pset in psets:
            if pset.names is None:
                basis.label_directly(pset)
    else:
        runs = []
        segment = np.asarray(path.segment_index)
        n_k = len(psets)
        for ik, pset in enumerate(psets):
            end = (
                ik == 0
                or segment[ik] != segment[ik - 1]
                or ik == n_k - 1
                or segment[ik] != segment[ik + 1]
            )
            key = (int(segment[ik]), tuple(int(j) for j in pset.little_ops), ik if end else -1)
            if runs and runs[-1][0] == key and not end:
                runs[-1][1].append(ik)
            else:
                runs.append((key, [ik]))
        for _key, members in runs:
            first = psets[members[0]]
            if first.names is None:
                basis.label_directly(first)
            todo = [psets[ik] for ik in members[1:] if psets[ik].names is None]
            if not todo:
                continue
            stats["runs"] += 1
            consistent = True
            for pset in todo:
                perm = _match_stripped(first.stripped, pset.stripped)
                if perm is None:
                    consistent = False
                    break
                pset.names = [first.names[j] for j in perm]
                pset.kname = first.kname
                pset.labeled_directly = False
            last = psets[members[-1]]
            if consistent and len(members) >= 3 and not last.labeled_directly:
                names, _kname = basis.direct_labels(last)
                if names == last.names:
                    last.labeled_directly = True
                else:
                    consistent = False
            if not consistent:
                stats["mismatches"] += 1
                for ik in members:
                    if not psets[ik].labeled_directly:
                        basis.label_directly(psets[ik])
    unique = {id(p): p for p in psets}.values()
    stats["labeled_directly"] = sum(1 for p in unique if p.labeled_directly)
    stats["copied"] = sum(1 for p in unique if not p.labeled_directly)
    return stats


def _ordered_units(psets: list) -> list:
    """Every unit met, grouped by k type in order of appearance, natural order inside a type."""
    by_type: dict = {}
    for pset in psets:
        bucket = by_type.setdefault(pset.kname, [])
        for unit in pset.units:
            if unit not in bucket:
                bucket.append(unit)
    out = []
    for units in by_type.values():
        out.extend(sorted(units, key=irrep_sort_key))
    return list(dict.fromkeys(out))


# ---------------------------------------------------------------------------
# the result
# ---------------------------------------------------------------------------
[docs] @dataclass class UnfoldedIrreps: """Parent-irrep resolution of unfolded bands (:func:`irrep_resolve`). Attributes: units: Every irrep unit met along the k points (``'GM4-'``, ``'S1+S2'``, ...), grouped by k type, natural order inside a type. kname: ISO-IR k type of every k (``'GM'``, ``'DT'``, ``'X'``, ...). weights: (n_k, n_band, n_units) P_J^(u)(k) per mode (canonical basis); 0 where a unit does not occur. group_label: (n_k, n_band) str, the label of the mode's degenerate group (``'R4+'``, ``'Z1/Z3'``, ``'S1+S2'``, ``'mixed'``, ``'-'``). group_members: ``[k][mode]`` -> tuple of the irrep names of the label (``('U2+', 'U3+')``, ``('Z1', 'Z3')``; ``()`` for mixed and -). group_fraction: (n_k, n_band) summed share of P_g held by the label's units (0 for mixed and -). inseparable: ``[k]`` -> tuples of units the child symmetry cannot separate. tr_units: ``[k]`` -> the time-reversal pairs present at k. parent_labels: (n_k, 3 n_parent) str, unit of every parent band (with parent phonons), else None; ``parent_frequencies`` likewise (THz). mulliken: ``{parent GM unit: Mulliken symbol}``. checks: Largest deviations: projector identities ('completeness', 'idempotency', 'hermiticity', 'orthogonality', 'mass_commutator'), 'sum_over_irreps' (sum_u P_J^(u) - P_J), 'per_irrep_sum_rule' (sum_J P_J^(u) - trace), 'parent_purity' (distance of the unit weights of every parent level from whole numbers of bands), 'forbidden_weight' (largest share of a degenerate group in parent irreps its irreps of H(k) forbid), 'selection_residual' (largest residual of the H(k)-invariance of the groups' subspaces), 'selection_groups' (groups checked), 'class_multiplicity' (distance from integers of the multiplicities behind the inseparable sets), 'translation_mismatch'. cache: ``{'runs', 'labeled_directly', 'copied', 'mismatches'}`` of the line-label cache. basis: The :class:`ParentIrrepBasis` (reused by :func:`crystod.phonon_unfold.gamma_origin`). notes: NOTE lines (time-reversal test failed, Mulliken symbols, checks above 1e-6). timings: CPU wall times of the steps. """ units: list kname: list weights: np.ndarray group_label: np.ndarray group_members: list group_fraction: np.ndarray inseparable: list tr_units: list parent_labels: np.ndarray | None parent_frequencies: np.ndarray | None mulliken: dict checks: dict cache: dict basis: object notes: list = field(default_factory=list) timings: dict = field(default_factory=dict)
def _parent_eigen(parent_phonon, mapping, kpoints): """Parent frequencies (n_k, 3n) and eigenvectors as rows (n_k, 3n bands, 3n) at the parent k.""" _check_parent_cell(parent_phonon, mapping) freqs, vecs = [], [] for start in range(0, len(kpoints), CHUNK): result = _run_qpoints(parent_phonon, kpoints[start : start + CHUNK], with_eigenvectors=True) freqs.append(np.array(result.frequencies, dtype=float)) vecs.append(np.transpose(np.array(result.eigenvectors), (0, 2, 1))) return np.concatenate(freqs), np.concatenate(vecs) def _check_parent_cell(parent_phonon, mapping) -> None: try: _check_child_cell(parent_phonon.primitive, mapping.parent_cell) except ValueError: raise ValueError( "the primitive cell of parent_phonon is not the parent cell of the mapping" ) from None
[docs] def irrep_resolve( bands, mapping, *, path=None, parent_phonon=None, weight_min: float = WEIGHT_MIN, degeneracy_tolerance: float = DEGENERACY_TOLERANCE, symprec: float = SYMPREC, ) -> UnfoldedIrreps: """Resolve unfolded bands by the irreps of the parent; label every degenerate group. Args: bands: :class:`crystod.phonon_unfold.UnfoldedBands`. mapping: The :class:`crystod.phonon_unfold.ParentMapping`. path: The :class:`crystod.phonon_unfold.ParentPath` of ``bands`` (its straight runs reuse the ISO-IR names); None labels every k directly. parent_phonon: ``phonopy.Phonopy`` of the parent (primitive cell = ``mapping.parent_cell``) for the parent levels, or None. weight_min: Groups with ``P_g`` below it get the label ``'-'``. degeneracy_tolerance: THz, degenerate groups of child (and parent) modes. symprec: spglib tolerance of the symmetry analysis. Returns: :class:`UnfoldedIrreps`. Raises: SystemExit: A projector identity fails (an internal error). """ timings = {} t0 = time.perf_counter() basis = ParentIrrepBasis( mapping.parent_cell, input_cell=mapping.parent_unitcell, symprec=symprec ) child_ops, _n_child_ops, mismatch = child_operations_in_parent(mapping, basis, symprec) basis.child_ops = child_ops basis.child_affine = _child_affine_operations(mapping, basis, symprec) timings["basis_s"] = time.perf_counter() - t0 kpoints = np.atleast_2d(np.asarray(bands.k_parent, dtype=float)) n_k, n_band = bands.frequencies.shape if path is not None and ( len(path.kpoints) != n_k or np.abs(path.kpoints - kpoints).max() > 1e-12 ): raise ValueError("path does not hold the k points of bands") vectors = rotate_unfolded_vectors(bands.vectors, mapping.frame_rotation) freqs, P = bands.frequencies, bands.weights_canonical parent_freqs = parent_vecs = None if parent_phonon is not None: parent_freqs, parent_vecs = _parent_eigen(parent_phonon, mapping, kpoints) # pass 1: projectors, irrep weights, selection rules t1 = time.perf_counter() psets, w_irrep, w_parent = [], [], [] forbidden = residual = 0.0 n_checked = 0 for ik in range(n_k): pset, rep = basis.build(kpoints[ik]) psets.append(pset) w = irrep_weights(vectors[ik], pset.projectors) w_irrep.append(w) if parent_vecs is not None: w_parent.append(irrep_weights(parent_vecs[ik], pset.projectors)) H = _child_positions(pset, child_ops) f_dev, e_dev, n = _selection_rules( rep[H], pset.characters[pset.present][:, H], vectors[ik], freqs[ik], P[ik], w, weight_min, degeneracy_tolerance, ) forbidden, residual, n_checked = max(forbidden, f_dev), max(residual, e_dev), n_checked + n timings["projectors_s"] = time.perf_counter() - t1 # pass 2: ISO-IR names (line cache), time-reversal units t2 = time.perf_counter() basis.label_time = 0.0 cache = _label_points(basis, psets, path) for pset in {id(p): p for p in psets}.values(): if pset.units is None: basis.make_units(pset) timings["labels_s"] = time.perf_counter() - t2 # pass 3: unit weights, inseparable classes, group labels t3 = time.perf_counter() units = _ordered_units(psets) index = {u: i for i, u in enumerate(units)} weights = np.zeros((n_k, n_band, len(units))) group_label = np.empty((n_k, n_band), dtype=object) group_members = [] group_fraction = np.zeros((n_k, n_band)) inseparable, tr_units = [], [] per_irrep = sum_over = class_dev = 0.0 notes = list(basis.notes) tr_failed = [] for ik in range(n_k): pset = psets[ik] unit_w = _unit_weights(pset, w_irrep[ik]) weights[ik][:, [index[u] for u in pset.units]] = unit_w per_irrep = max( per_irrep, float(np.abs(w_irrep[ik].sum(axis=0) - pset.dims * pset.multiplicities).max()), ) sum_over = max( sum_over, float(np.abs(w_irrep[ik].sum(axis=1) - np.sum(np.abs(vectors[ik]) ** 2, axis=1)).max()), ) classes = _inseparable_classes(pset, basis, mapping) class_dev = max(class_dev, pset.class_deviation) inseparable.append([tuple(pset.units[u] for u in c) for c in classes]) tr_units.append(list(pset.tr_pairs)) if pset.tr_failed and not any(np.allclose(pset.k, k_) for k_ in tr_failed): tr_failed.append(pset.k) labels, members, fractions, _groups = _group_labels( pset, classes, unit_w, freqs[ik], P[ik], weight_min, degeneracy_tolerance ) group_label[ik] = labels group_members.append(members) group_fraction[ik] = fractions for k_ in tr_failed: notes.append( f"NOTE: Wigner's time-reversal test failed at k = {_vec(k_)}; levels there are " "labeled per irrep." ) # pass 4: parent levels parent_labels = None purity = 0.0 if parent_vecs is not None: parent_labels = np.empty(parent_freqs.shape, dtype=object) for ik in range(n_k): pset = psets[ik] unit_w = _unit_weights(pset, w_parent[ik]) parent_labels[ik] = [pset.units[u] for u in np.argmax(unit_w, axis=1)] # every unit holds a whole number of bands of each level (also where two # irreps happen to be degenerate within the tolerance) for level in degenerate_groups(parent_freqs[ik], degeneracy_tolerance): total = unit_w[level].sum(axis=0) purity = max(purity, float(np.abs(total - np.rint(total)).max())) parent_labels = parent_labels.astype(str) timings["weights_and_labels_s"] = time.perf_counter() - t3 unique = list({id(p): p for p in psets}.values()) checks = {key: max(p.checks[key] for p in unique) for key in unique[0].checks} if unique else {} checks.update( { "sum_over_irreps": sum_over, "per_irrep_sum_rule": per_irrep, "parent_purity": purity, "forbidden_weight": forbidden, "selection_residual": residual, "selection_groups": float(n_checked), "class_multiplicity": class_dev, "translation_mismatch": mismatch, } ) if forbidden > 1e-6: notes.append( f"NOTE: weight forbidden by the child symmetry reaches {forbidden:.1e} (child levels " "in parent irreps that share no irrep of the child operations fixing k with them)." ) if class_dev > 1e-6: notes.append( f"NOTE: the multiplicities behind the sets the child symmetry cannot separate are off " f"integers by {class_dev:.1e}; the sets may be wrong." ) if purity > 1e-6: notes.append( f"NOTE: a parent level does not hold whole bands of its irrep units ({purity:.1e}); " "the parent labels there are those of the largest unit." ) if cache["mismatches"]: runs = "run" if cache["mismatches"] == 1 else "runs" notes.append( f"NOTE: {cache['mismatches']} {runs} of labels recomputed point by point (the copied " "labels differed at its last point)." ) timings["total_s"] = time.perf_counter() - t0 return UnfoldedIrreps( units=units, kname=[p.kname for p in psets], weights=weights, group_label=group_label.astype(str), group_members=group_members, group_fraction=group_fraction, inseparable=inseparable, tr_units=tr_units, parent_labels=parent_labels, parent_frequencies=parent_freqs, mulliken=dict(basis.mulliken), checks=checks, cache=cache, basis=basis, notes=notes, timings=timings, )
def resolve_point( basis: ParentIrrepBasis, mapping, k, vectors, freqs, weights, *, weight_min: float = WEIGHT_MIN, degeneracy_tolerance: float = DEGENERACY_TOLERANCE, ): """Irrep weights and group labels of given unfolded vectors at one parent k. Args: basis: The :class:`ParentIrrepBasis` (with ``child_ops`` set). mapping: The :class:`crystod.phonon_unfold.ParentMapping`. k: (3,) parent fractional k. vectors: (n_band, 3 n_parent) unfolded vectors (child frame, parent origin). freqs, weights: (n_band,) frequencies (THz) and weights P_J(k). Returns: A namespace with ``pset``, ``unit_weights`` (n_band, n_units), ``labels``, ``members``, ``fractions`` per mode, ``groups`` and ``classes``. """ pset = basis.projector_set(k) if basis.child_ops is None: basis.child_ops = child_operations_in_parent(mapping, basis)[0] u = rotate_unfolded_vectors(np.asarray(vectors), mapping.frame_rotation) unit_w = _unit_weights(pset, irrep_weights(u, pset.projectors)) classes = _inseparable_classes(pset, basis, mapping) labels, members, fractions, groups = _group_labels( pset, classes, unit_w, np.asarray(freqs), np.asarray(weights), weight_min, degeneracy_tolerance, ) return SimpleNamespace( pset=pset, unit_weights=unit_w, labels=labels, members=members, fractions=fractions, groups=groups, classes=classes, ) def format_label(label: str, members: tuple, kname: str, mulliken: dict) -> str: """A group label for the terminal: at GM with the Mulliken symbols of its members in brackets. ``'GM4- [T1u]'``, ``'GM4-/GM5- [T1u/T2u]'``; a time-reversal unit ``'GM3+GM4 [E]'`` (repeated symbols are written once); away from GM, and for ``mixed`` and ``-``, the label unchanged. """ if kname != "GM" or label in ("mixed", "-") or not mulliken or not members: return label parts = [] for unit in label.split("/"): if unit in members: names = [unit] else: # a time-reversal unit 'a+b' of two members names = next( ([a, b] for a in members for b in members if a != b and f"{a}+{b}" == unit), [] ) symbols = [mulliken.get(n) for n in names] if not names or any(s is None for s in symbols): return label parts.append("+".join(dict.fromkeys(symbols))) return f"{label} [{'/'.join(parts)}]"