Source code for crystod.isoir

"""ISO-IR (ISOTROPY Software Suite) irreducible-representation tables.

Parses the ISO-IR data files of Stokes & Campbell (2011 version)

    CIR_data.txt : complex irreducible representations
    PIR_data.txt : physically irreducible representations

and evaluates small-representation (little-group) characters at arbitrary
k points, including non-special k vectors (symmetry lines, planes and the
general point) that carry free parameters alpha/beta/gamma.

The tables store, for every irrep, the FULL space-group representation
matrices (all arms of the star) for the coset representatives in the
standard conventional setting used by ISOTROPY (orthorhombic axes abc,
monoclinic axes a(b)c cell choice 1, origin choice 2, hexagonal axes).
The small representation at one arm is the diagonal block of that arm,
multiplied by the translation phase exp(+2*pi*i k.t) [ISO-IR convention;
note spgrep uses exp(-2*pi*i k.t), so spgrep characters are matched
against the COMPLEX CONJUGATE of the ISO-IR characters].

Every irrep label CrystOD prints comes from these tables (special points,
lines, planes and the general point).  The labels follow the Miller-Love /
ISOTROPY convention (e.g. T1..T5, DT5, LD3, GP1); a k point whose star is
the -k partner of a tabulated one (PA of I-4; the star at the negative
parameter of a polar line) is named as the ISOTROPY software names it, with
the complex conjugate irreps (PA1 = conj P1, LE1 = conj LD1; see
``minus_k_type``).

Data location: the gzip-compressed table ``CIR_data.txt.gz`` is bundled
inside the crystod package directory itself.  The lookup order is the
environment variable ``CRYSTOD_ISOIR_PATH`` first, then the package
directory, then ``<repository root>/ISOTROPY`` (the original ISO-IR
download layout with ``CIR_data/CIR_data.txt``).

File format (from CIR_data.f / PIR_data.f):
  header line:
      irnum sgnum "sgsymbol" "irlabel" irdim irtype kcount pmkcount opcount
  k vectors (CIR: kcount arms, PIR: pmkcount arms), 16 ints per arm,
  column-major kvec(4,4):
      col 1     = (x, y, z, denominator) constant part
      cols 2..4 = alpha/beta/gamma coefficient columns (x, y, z, denom)
  per operator (opcount of them):
      16 ints: 4x4 augmented operator matrix, ROW-major, common
               denominator at [3][3]
      [only if k is non-special] 4 ints: IR-translation (x, y, z, denom)
      irdim^2 IR-matrix entries, row-major
          CIR: complex tokens "(re,im)"
          PIR: bare real tokens
"""
from __future__ import annotations

import gzip
import os
import re
from dataclasses import dataclass, field
from pathlib import Path
from typing import Optional

import numpy as np

_HEADER_RE = re.compile(
    r'^\s*(\d+)\s+(\d+)\s+"([^"]*)"\s+"([^"]*)"'
    r"\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s*$"
)

# centering translations (conventional basis) by first letter of the HM symbol
_CENTERING_TRANSLATIONS = {
    "P": [],
    "A": [(0.0, 0.5, 0.5)],
    "B": [(0.5, 0.0, 0.5)],
    "C": [(0.5, 0.5, 0.0)],
    "F": [(0.0, 0.5, 0.5), (0.5, 0.0, 0.5), (0.5, 0.5, 0.0)],
    "I": [(0.5, 0.5, 0.5)],
    "R": [(2 / 3, 1 / 3, 1 / 3), (1 / 3, 2 / 3, 2 / 3)],
}

_KTYPE_RE = re.compile(r"^([A-Z]+)")


# In a group without inversion the star of -k can differ from the star of k.
# ISO-IR tabulates one of the two; the ISOTROPY software names the other by
# its own letters in the physically irreducible labels (LD1LE1, DT6DU6,
# GP1GQ1, P1PA1, P1PC1 in its data file data_little.txt): the next letter
# for LD, DT, SM and GP, the suffix A otherwise, and the suffix C for the
# types below.  Over all 230 groups these names exist exactly for the k
# types whose -k lies outside the star (4141 types checked).
_MINUS_K_LETTERS = {"LD": "LE", "DT": "DU", "SM": "SN", "GP": "GQ"}
_MINUS_K_EXCEPTIONS = {
    143: {"P": "PC", "B": "BC", "C": "CC", "D": "DC", "E": "EC"},
    144: {"P": "PC", "B": "BC", "C": "CC", "D": "DC", "E": "EC"},
    145: {"P": "PC", "B": "BC", "C": "CC", "D": "DC", "E": "EC"},
    156: {"D": "DC"},
    157: {"P": "PC", "C": "CC"},
    158: {"D": "DC"},
    159: {"P": "PC", "C": "CC"},
    174: {"B": "BC", "E": "EC"},
}


def minus_k_type(ktype: str, sgnum: Optional[int] = None) -> str:
    """ISOTROPY's name of the -k partner of a k-vector type (``P`` ->
    ``PA``, ``LD`` -> ``LE``, ``P`` -> ``PC`` in P3).

    Meaningful only for a type whose -k lies outside its star; for another
    type the name returned may be a tabulated type of its own (``ZA`` of
    P23), and the callers never ask for it."""
    if sgnum is not None:
        special = _MINUS_K_EXCEPTIONS.get(int(sgnum), {}).get(ktype)
        if special is not None:
            return special
    return _MINUS_K_LETTERS.get(ktype, ktype + "A")


def minus_k_label(label: str, sgnum: Optional[int] = None) -> str:
    """Name of the -k partner of a k-vector type or irrep: ISOTROPY's
    partner letters on the type (``P1`` -> ``PA1``, ``DT6`` -> ``DU6``).
    The partner irrep with that name is the complex conjugate of the
    tabulated one."""
    return _KTYPE_RE.sub(lambda match: minus_k_type(match.group(1), sgnum), label)


def minus_k_base(label: str, sgnum: int) -> Optional[str]:
    """The tabulated label whose -k partner ``label`` names (``LE1`` ->
    ``LD1``), or None when ``label`` is not such a name in this group."""
    match = _KTYPE_RE.match(label)
    if match is None:
        return None
    prefix = match.group(1)
    types = {ir.ktype for ir in load_isoir_irreps(int(sgnum), "cir")}
    if prefix in types:
        return None
    for ktype in sorted(types):
        if minus_k_type(ktype, sgnum) == prefix:
            return ktype + label[len(prefix):]
    return None


def _parameter_key(params) -> tuple:
    """Order of line or plane parameters: the canonical value is the
    smallest, the positive one first among values of equal size."""
    q = np.round(np.asarray(params, dtype=float), 7) + 0.0
    return (round(float(q @ q), 12), tuple(-q))


@dataclass
class IsoIrrep:
    """One irrep block of an ISO-IR data file."""

    irnum: int
    sgnum: int
    sgsymbol: str
    label: str
    dim: int
    irtype: int
    kcount: int
    pmkcount: int
    opcount: int
    kvecs: np.ndarray = field(repr=False, default=None)  # (narms, 4, 4) int
    special: bool = True
    rotations: np.ndarray = field(repr=False, default=None)  # (nop, 3, 3) int
    translations: np.ndarray = field(repr=False, default=None)  # (nop, 3)
    irtrans: np.ndarray = field(repr=False, default=None)  # (nop, 3)
    matrices: np.ndarray = field(repr=False, default=None)  # (nop, dim, dim)

    @property
    def centering(self) -> str:
        return self.sgsymbol[0]

    @property
    def narms(self) -> int:
        return len(self.kvecs)

    @property
    def small_dim(self) -> int:
        return self.dim // self.narms

    @property
    def ktype(self) -> str:
        """k-vector type label, e.g. 'T' for 'T5', 'GM' for 'GM1+'."""
        return _KTYPE_RE.match(self.label).group(1)

    @property
    def num_free_params(self) -> int:
        used = 0
        for p in range(3):
            col = self.kvecs[0][p + 1]
            if col[3] != 0 and any(col[j] != 0 for j in range(3)):
                used += 1
        return used

    def arm_k(self, arm: int, params) -> np.ndarray:
        """k vector of an arm (conventional reciprocal basis) at parameters."""
        kv = self.kvecs[arm]
        k = np.array([kv[0][j] / kv[0][3] for j in range(3)], dtype=float)
        for p in range(3):  # alpha, beta, gamma
            col = kv[p + 1]
            if col[3] != 0:
                k = k + params[p] * np.array(
                    [col[j] / col[3] for j in range(3)], dtype=float
                )
        return k

    def _arm_parametrization(self, arm: int):
        """``(const, parameter indices, A, pinv(A))`` of an arm, with
        ``arm_k(arm, params) = const + A @ params[indices]``; ``A`` is None
        for a special point."""
        cache = self.__dict__.setdefault("_arm_cache", {})
        if arm not in cache:
            kv = self.kvecs[arm]
            const = np.array([kv[0][j] / kv[0][3] for j in range(3)], dtype=float)
            index, columns = [], []
            for p in range(3):
                c = kv[p + 1]
                if c[3] != 0 and any(c[j] != 0 for j in range(3)):
                    index.append(p)
                    columns.append([c[j] / c[3] for j in range(3)])
            if columns:
                A = np.array(columns, dtype=float).T
                cache[arm] = (const, index, A, np.linalg.pinv(A))
            else:
                cache[arm] = (const, index, None, None)
        return cache[arm]

    def match_k(self, k, atol: float = 1e-6) -> Optional[tuple[int, np.ndarray]]:
        """Find (arm, params) with arm_k(arm, params) == k modulo the
        reciprocal lattice of the (possibly centered) crystal lattice.

        `k` is in conventional fractional reciprocal coordinates.

        On a line or plane the same k is reached with several parameter
        values: through another arm (``(0,-1/2,0)`` is the arm ``(0,a,0)`` at
        ``a = -1/2`` and the arm ``(0,-a,0)`` at ``a = 1/2``) and through a
        reciprocal lattice vector.  The irrep an ISO-IR label names depends
        on the parameter value (DT3 at ``-a`` is DT4 at ``a`` in F-43m), so
        one value has to be singled out.  The parameters returned are the
        smallest ones, and among those of equal size the positive ones
        (the largest in lexicographic order).  The choice is a property of
        the star: every arm of one star gets the same parameters, and k and
        k + G do as well, so that a label does not depend on which arm or
        which copy of k the caller works with.
        """
        k = np.asarray(k, dtype=float)
        best = None
        for arm in range(self.narms):
            const, index, A, A_pinv = self._arm_parametrization(arm)
            d = k - const
            if A is None:
                n = np.rint(d)
                if np.all(np.abs(d - n) <= atol) and _is_reciprocal_lattice_vector(
                    n, self.centering
                ):
                    return arm, np.zeros(3)
                continue
            # A p = d + G for a reciprocal lattice vector G near -d
            offsets = _reciprocal_offsets_near(self.centering, -np.rint(d))
            rhs = d + offsets
            sols = rhs @ A_pinv.T
            hits = np.all(np.abs(sols @ A.T - rhs) <= atol, axis=1)
            for sol in sols[hits]:
                params = np.zeros(3)
                params[index] = sol
                key = _parameter_key(params)
                if best is None or key < best[0]:
                    best = (key, arm, params)
        if best is None:
            return None
        return best[1], best[2]

    def find_operator(self, rotation) -> Optional[int]:
        index = self.__dict__.get("_operator_index")
        if index is None:
            index = {}
            for i in range(self.opcount):
                index.setdefault(
                    tuple(int(v) for v in np.asarray(self.rotations[i]).ravel()), i
                )
            self.__dict__["_operator_index"] = index
        rotation = np.asarray(rotation)
        if rotation.shape != (3, 3):
            return None
        try:
            return index.get(tuple(int(v) for v in rotation.ravel()))
        except (TypeError, ValueError):
            return None

    def small_character(self, rotation, translation, arm: int, params) -> complex:
        """Character of the small representation at the given arm/params for
        the conventional-setting operator {rotation|translation}, in the
        ISO-IR phase convention exp(+2*pi*i k.t).
        """
        i = self.find_operator(rotation)
        if i is None:
            raise LookupError(f"operator not found in ISO-IR {self.label}")
        dt = np.asarray(translation, dtype=float) - self.translations[i]
        if not _is_lattice_translation(dt, self.centering):
            raise LookupError(
                f"translation mismatch for ISO-IR {self.label}: {dt}"
            )
        tph = dt + (self.irtrans[i] if not self.special else 0.0)
        kk = self.arm_k(arm, params)
        phase = np.exp(2j * np.pi * np.dot(kk, tph))
        nb = self.small_dim
        block = self.matrices[i][
            arm * nb : (arm + 1) * nb, arm * nb : (arm + 1) * nb
        ]
        return phase * np.trace(block)

    def in_little_group(self, rotation, arm: int, params) -> bool:
        """Is {rotation|*} in the little group of the arm's k?  (R^-T k = k
        modulo the reciprocal lattice of the centered crystal lattice.)
        """
        kk = self.arm_k(arm, params)
        kp = np.linalg.inv(np.asarray(rotation, dtype=float).T) @ kk
        d = kp - kk
        di = np.rint(d)
        if not np.allclose(d, di, atol=1e-6):
            return False
        return _is_reciprocal_lattice_vector(di, self.centering)


_INTEGER_BOX = np.array(
    [(gx, gy, gz) for gx in range(-3, 4) for gy in range(-3, 4) for gz in range(-3, 4)],
    dtype=float,
)


def _reciprocal_offsets_near(centering: str, base) -> np.ndarray:
    """Reciprocal lattice vectors of the centered lattice (conventional
    reciprocal basis) within three units of the integer vector ``base``."""
    offsets = np.asarray(base, dtype=float) + _INTEGER_BOX
    keep = np.ones(len(offsets), dtype=bool)
    for t in _CENTERING_TRANSLATIONS[centering]:
        s = offsets @ np.asarray(t, dtype=float)
        keep &= np.abs(s - np.rint(s)) < 1e-9
    return offsets[keep]


def _is_reciprocal_lattice_vector(G, centering: str) -> bool:
    """Is the integer vector G (conventional reciprocal basis) a reciprocal
    lattice vector of the centered crystal lattice?  True iff G.t is an
    integer for every centering translation t.
    """
    for t in _CENTERING_TRANSLATIONS[centering]:
        s = float(np.dot(G, t))
        if not np.isclose(s - round(s), 0.0, atol=1e-9):
            return False
    return True


def _is_lattice_translation(t, centering: str, atol: float = 1e-6) -> bool:
    """Is t (conventional basis) a translation of the centered lattice?"""
    for c in [np.zeros(3)] + [np.array(v) for v in _CENTERING_TRANSLATIONS[centering]]:
        d = np.asarray(t) - c
        if np.allclose(d - np.rint(d), 0, atol=atol):
            return True
    return False


_COMPLEX_TOKEN_RE = re.compile(r"\(([^,]+),([^)]+)\)")


def _parse_complex_token(token: str) -> complex:
    m = _COMPLEX_TOKEN_RE.fullmatch(token)
    if not m:
        raise ValueError(f"bad complex token in ISO-IR data: {token!r}")
    return complex(float(m.group(1)), float(m.group(2)))


class _TokenStream:
    """Whitespace-token stream over the lines following a header line."""

    def __init__(self, line_iter):
        self._lines = line_iter
        self._buf: list[str] = []
        self._pos = 0

    def next_tokens(self, n: int) -> list[str]:
        out: list[str] = []
        while len(out) < n:
            if self._pos >= len(self._buf):
                self._buf = next(self._lines).split()
                self._pos = 0
                continue
            out.append(self._buf[self._pos])
            self._pos += 1
        return out


def _isoir_data_file(data_dir: Path, kind: str) -> Optional[Path]:
    """Path of the (possibly gzip-compressed) data file of one kind.

    Two layouts are accepted: the flat package layout (``CIR_data.txt.gz``
    directly inside ``data_dir``, as bundled with the crystod package) and
    the original ISO-IR distribution layout (``CIR_data/CIR_data.txt``).
    """
    name = f"{kind.upper()}_data.txt"
    for base in (data_dir / name, data_dir / f"{kind.upper()}_data" / name):
        for path in (base, base.parent / (base.name + ".gz")):
            if path.is_file():
                return path
    return None


def find_isoir_data_dir() -> Optional[Path]:
    """Locate the ISO-IR data directory.

    Search order: the ``CRYSTOD_ISOIR_PATH`` environment variable, the
    crystod package directory itself (bundled ``CIR_data.txt.gz``), then
    ``<repository root>/ISOTROPY`` (original ISO-IR download layout).
    """
    env = os.environ.get("CRYSTOD_ISOIR_PATH")
    candidates = []
    if env:
        candidates.append(Path(env))
    package_dir = Path(__file__).resolve().parent
    candidates.append(package_dir)
    candidates.append(package_dir.parent / "ISOTROPY")
    for cand in candidates:
        if _isoir_data_file(cand, "cir") is not None:
            return cand
    return None


_CACHE: dict[tuple[str, int, str], list[IsoIrrep]] = {}


[docs] def load_isoir_irreps(sgnum: int, kind: str = "cir", data_dir: Optional[Path] = None) -> list[IsoIrrep]: """Parse all irreps of one space group from an ISO-IR data file. Direct access to the tables behind every ISO-IR label that CrystOD prints: for each irrep the full space-group matrices over the coset representatives of the ISOTROPY standard setting, the (parametrized) k vectors of every star arm, and the operator translations. Results are cached per (file, space group). Args: sgnum: Space-group number (1-230). kind: ``"cir"`` for the complex irreps (``CIR_data``, bundled with the package) or ``"pir"`` for the physically irreducible ones (``PIR_data``, not bundled). data_dir: Directory holding the data file; by default the lookup order of ``find_isoir_data_dir`` (``CRYSTOD_ISOIR_PATH``, the package directory, ``<repository root>/ISOTROPY``). Returns: One ``IsoIrrep`` record per irrep, in table order, with ``label`` (``"GM4-"``, ``"DT5"``, ...), ``dim`` (full dimension), ``narms``, ``small_dim``, ``ktype``, ``num_free_params``, the arrays ``kvecs``, ``rotations``, ``translations``, ``irtrans`` and ``matrices``, and the methods ``arm_k``, ``match_k``, ``small_character`` and ``in_little_group``. Raises: ValueError: ``kind`` is neither ``"cir"`` nor ``"pir"``, or the file is malformed. FileNotFoundError: No data directory or data file found. Example: >>> from crystod import group >>> irreps = group.load_isoir_irreps(221) >>> len(irreps) 72 >>> [ir.label for ir in irreps if ir.ktype == "R"] ['R1+', 'R2+', 'R3+', 'R4+', 'R5+', 'R1-', 'R2-', 'R3-', 'R4-', 'R5-'] """ if kind not in ("cir", "pir"): raise ValueError(f"kind must be 'cir' or 'pir', got {kind!r}") if data_dir is None: data_dir = find_isoir_data_dir() if data_dir is None: raise FileNotFoundError( "ISO-IR data directory not found (set CRYSTOD_ISOIR_PATH or place " "the ISOTROPY directory next to the crystod package)" ) path = _isoir_data_file(data_dir, kind) if path is None: raise FileNotFoundError( f"ISO-IR {kind.upper()} data file not found under {data_dir}" ) key = (str(path), sgnum, kind) if key in _CACHE: return _CACHE[key] opener = gzip.open if path.suffix == ".gz" else open irreps: list[IsoIrrep] = [] with opener(path, "rt") as f: lines = iter(f) for line in lines: if '"' not in line: continue m = _HEADER_RE.match(line) if not m: continue sg = int(m.group(2)) if sg > sgnum: break if sg != sgnum: continue irnum = int(m.group(1)) sgsym = m.group(3).strip() irlabel = m.group(4).strip() dim = int(m.group(5)) irtype = int(m.group(6)) kcount = int(m.group(7)) pmkcount = int(m.group(8)) nop = int(m.group(9)) # CIR stores the full star of k, PIR only the star of +/-k narms = kcount if kind == "cir" else pmkcount ts = _TokenStream(lines) kints = [int(t) for t in ts.next_tokens(16 * narms)] kvecs = np.array(kints, dtype=int).reshape(narms, 4, 4) special = True for arm in range(narms): for col in (1, 2, 3): if any(kvecs[arm][col][j] != 0 for j in range(3)): special = False rotations = np.zeros((nop, 3, 3), dtype=int) translations = np.zeros((nop, 3), dtype=float) irtrans = np.zeros((nop, 3), dtype=float) matrices = np.zeros((nop, dim, dim), dtype=complex) for i in range(nop): a = np.array( [int(t) for t in ts.next_tokens(16)], dtype=int ).reshape(4, 4) denom = a[3][3] rotations[i] = a[:3, :3] // denom if not np.array_equal(rotations[i] * denom, a[:3, :3]): raise ValueError( f"non-integer rotation in ISO-IR irrep {irnum}" ) translations[i] = a[:3, 3] / denom if not special: v = [int(t) for t in ts.next_tokens(4)] irtrans[i] = np.array(v[:3], dtype=float) / v[3] tokens = ts.next_tokens(dim * dim) if kind == "cir": values = [_parse_complex_token(t) for t in tokens] else: values = [float(t) for t in tokens] matrices[i] = np.array(values, dtype=complex).reshape(dim, dim) irreps.append( IsoIrrep( irnum, sg, sgsym, irlabel, dim, irtype, kcount, pmkcount, nop, kvecs, special, rotations, translations, irtrans, matrices, ) ) _CACHE[key] = irreps return irreps
def isoir_available() -> bool: return find_isoir_data_dir() is not None _ISO_HALL_CACHE: dict[int, int] = {} def iso_hall_number(sgnum: int) -> int: """spglib Hall number of the ISO-IR standard setting of a space group. ISOTROPY's preferences: origin choice 2, orthorhombic axes abc, monoclinic axes a(b)c cell choice 1, hexagonal axes. In terms of the spglib `choice` strings this means, in order of preference: '2' (origin choice 2), '' (unique standard setting), 'b1' (monoclinic), 'H' (rhombohedral on hexagonal axes), '1' (origin choice 1 only). """ if not _ISO_HALL_CACHE: import spglib by_sg: dict[int, list[tuple[int, str]]] = {} for hall in range(1, 531): t = spglib.get_spacegroup_type(hall) number = t['number'] if isinstance(t, dict) else t.number choice = t['choice'] if isinstance(t, dict) else t.choice by_sg.setdefault(number, []).append((hall, choice)) for number, entries in by_sg.items(): chosen = entries[0][0] for preferred in ("2", "", "b1", "H", "1"): hits = [h for h, c in entries if c == preferred] if hits: chosen = hits[0] break _ISO_HALL_CACHE[number] = chosen return _ISO_HALL_CACHE[sgnum]
[docs] class IsoIRLabeler: """Label spgrep small representations with ISO-IR (Miller-Love) labels. The labeling engine shared by every CrystOD command (crystal orbitals, phonons, spin bases, ``crystod-group --table --sg``): spgrep computes the small irreps of the little group of k in the primitive basis of the user's cell, and this class matches their characters against the ISO-IR tables in the ISOTROPY standard setting (origin choice 2, orthorhombic axes abc, monoclinic axes a(b)c cell choice 1, hexagonal axes), at tabulated k points as well as on symmetry lines, planes and the general point. Because ISO-IR uses the phase convention ``exp(+2 pi i k.t)`` and spgrep ``exp(-2 pi i k.t)``, spgrep characters are compared with the complex conjugate of the ISO-IR characters. Args: sgnum: Space-group number (1-230). transformation_matrix: spglib-style transformation ``P`` into the ISO-IR setting (``x_conventional = P x_primitive + origin_shift``); give it together with ``origin_shift`` when ``cell`` is omitted. origin_shift: The origin shift of that transformation. cell: Alternatively, the primitive cell ``(lattice, scaled_positions, numbers)`` whose operations feed spgrep; the transformation is then computed with spglib for the Hall number of the ISO-IR setting. symprec: Symmetry tolerance for spglib when ``cell`` is given. Attributes: sgnum: The space-group number. P: The transformation matrix into the ISO-IR setting; ``Pinv`` its inverse and ``origin_shift`` the accompanying shift. irreps: The ``IsoIrrep`` records of the space group, from ``load_isoir_irreps``. Raises: ValueError: spglib could not standardize ``cell`` to the ISO-IR setting. FileNotFoundError: The ISO-IR data file is not available. Example: >>> import numpy as np >>> from crystod import group >>> labeler = group.IsoIRLabeler(221, transformation_matrix=np.eye(3), ... origin_shift=np.zeros(3)) >>> labeler.kpoint_name([0.5, 0.5, 0.4]), labeler.kpoint_name([0, 0, 0]) ('T', 'GM') """ def __init__(self, sgnum: int, transformation_matrix=None, origin_shift=None, cell=None, symprec: float = 1e-5): self.sgnum = sgnum if cell is not None: import spglib try: dataset = spglib.get_symmetry_dataset( cell, symprec=symprec, hall_number=iso_hall_number(sgnum) ) except Exception as exc: # spglib raises its own SpglibError family raise ValueError( "spglib standardization to the ISO-IR setting failed" ) from exc if dataset is None: raise ValueError( "spglib standardization to the ISO-IR setting failed" ) number = ( dataset['number'] if isinstance(dataset, dict) else dataset.number ) if number != sgnum: raise ValueError( "spglib standardization to the ISO-IR setting failed" ) transformation_matrix = ( dataset['transformation_matrix'] if isinstance(dataset, dict) else dataset.transformation_matrix ) origin_shift = ( dataset['origin_shift'] if isinstance(dataset, dict) else dataset.origin_shift ) self.P = np.asarray(transformation_matrix, dtype=float) self.Pinv = np.linalg.inv(self.P) self.origin_shift = np.asarray(origin_shift, dtype=float) self.irreps = load_isoir_irreps(sgnum, "cir") # -- setting conversion --------------------------------------------------
[docs] def conventional_k(self, k_primitive) -> np.ndarray: """k vector in the ISO-IR conventional reciprocal basis. Args: k_primitive: k vector in the primitive reciprocal basis. Returns: ``k_primitive @ P^-1`` as a float array. """ return np.asarray(k_primitive, dtype=float) @ self.Pinv
[docs] def conventional_operations(self, rotations, translations): """Map primitive-basis operations into the ISO-IR conventional setting. Args: rotations: Integer rotation matrices in the primitive basis. translations: Their fractional translations. Returns: ``[(R_c, t_c), ...]`` with ``R_c = P R P^-1`` and ``t_c = P t + (1 - R_c) origin_shift``. """ conv = [] for R_p, t_p in zip(rotations, translations): R_c = np.rint(self.P @ R_p @ self.Pinv).astype(int) t_c = self.P @ np.asarray(t_p, dtype=float) + ( np.eye(3) - R_c ) @ self.origin_shift conv.append((R_c, t_c)) return conv
[docs] def kpoint_name(self, k_primitive, minus_k: bool = True) -> Optional[str]: """Most specific ISO-IR k-vector type label containing a k point. Args: k_primitive: k vector in the primitive reciprocal basis. minus_k: Name a point whose -k partner is tabulated more specifically by the partner's name (``"PA"``, see ``minus_k_type``). Returns: The type label with the fewest free parameters, e.g. ``"T"`` for ``(1/2, 1/2, 0.4)`` in Pm-3m; ``None`` when no entry matches. """ k_conv = self.conventional_k(k_primitive) best = self._most_specific_type(k_conv) if minus_k: # a point of a -k star that is not tabulated (PA of I-4) lies on # a tabulated line; the point itself is the partner of the # tabulated one partner = self._most_specific_type(-k_conv) if partner is not None and (best is None or partner[0] < best[0]): return minus_k_type(partner[1], self.sgnum) return best[1] if best is not None else None
def _most_specific_type(self, k_conv): """``(number of free parameters, k-type)`` of the most specific tabulated k-vector type containing k (the partner name on the -k side of a line or plane, see ``_minus_side``), or None.""" families = self._matched_families(k_conv) if not families: return None ktype, family = families[0] if self._minus_side(ktype, family, k_conv) is not None: ktype = minus_k_type(ktype, self.sgnum) return family[0][0].num_free_params, ktype def _minus_side(self, ktype, family, k_conv): """The family at -k when k is the -k partner of the star there. On a line, a plane or the general point whose -k lies outside the star (a polar line such as LD of P4), k and -k are both on the tabulated type, at parameters p and -p. The star with the canonical parameter (``_parameter_key``: the positive one) keeps the tabulated name; the other one is its -k partner, named as ISOTROPY names it (LE for LD, DU for DT; ``minus_k_type``) with the complex conjugates of the tabulated irreps. Returns None when k is on the tabulated side or -k is in the star of k. """ if family[0][0].num_free_params == 0: return None minus = dict(self._matched_families(-np.asarray(k_conv, dtype=float))) minus_family = minus.get(ktype) if minus_family is None or len(minus_family) != len(family): return None if not _parameter_key(minus_family[0][2]) < _parameter_key(family[0][2]): return None return minus_family # -- labeling ------------------------------------------------------------
[docs] def label_characters( self, k_primitive, little_rotations, little_translations, spgrep_characters, atol: float = 1e-5, minus_k: bool = True, ) -> Optional[tuple[dict[int, str], str]]: """Match spgrep small-irrep characters against the ISO-IR tables. Args: k_primitive: k vector in the primitive reciprocal basis. little_rotations: Rotations of the little group of k in the primitive basis. little_translations: Their fractional translations. spgrep_characters: One character vector per spgrep irrep, aligned with the little-group operations and computed with the spgrep phase convention ``exp(-2 pi i k.t)``. atol: Tolerance of the character comparison. minus_k: When k has no assignment, label it through -k: the small irreps at k are the complex conjugates of those at -k, and only one star of such a pair is tabulated (P of I-4, not PA). The labels then carry ISOTROPY's partner name (``"PA1"`` is the conjugate of ``"P1"``). The -k partner of a line, plane or general point is named that way in any case (``"LE1"`` for the conjugate of ``"LD1"``; ``_minus_side``). Returns: ``({spgrep irrep index: ISO-IR label}, k-type label)``, e.g. ``({0: "R1+", ...}, "R")``, or ``None`` when no consistent assignment exists. """ matched = self._match_family( k_primitive, little_rotations, little_translations, spgrep_characters, atol, minus_k, ) if matched is None: return None label_map, ktype, _family, _conjugate = matched return label_map, ktype
[docs] def representative_k( self, k_primitive, little_rotations, little_translations, spgrep_characters, atol: float = 1e-5, minus_k: bool = True, ) -> Optional[tuple[np.ndarray, bool]]: """The representative arm of the tabulated star whose irreps name k. The search is that of :meth:`label_characters` (same families in the same order, same -k branches and checks); instead of the labels it returns the k vector of arm 0 of the family that matched, at the matched parameters -- the arm the ISO-IR table lists first. k lies in the star of that vector, or, when the labels came from the complex conjugates of the tabulated irreps (the -k partner of a line, plane or general point, ``_minus_side``, and a star tabulated only through -k), in the star of its negative; the irreps at -k0 are then the complex conjugates of those at k0, under the same index. A name that has to be the same on every arm of a star (the double-valued names of ``crystod.wavecar_irreps``) is fixed at this vector and carried to k by conjugation. Args: k_primitive: k vector in the primitive reciprocal basis. little_rotations: Rotations of the little group of k in the primitive basis. little_translations: Their fractional translations. spgrep_characters: One character vector per spgrep irrep, aligned with the little-group operations (phase convention ``exp(-2 pi i k.t)``). atol: Tolerance of the character comparison. minus_k: As in :meth:`label_characters`. Returns: ``(k0_primitive, conjugate)``: arm 0 of the matched family in the primitive reciprocal basis (``arm_k(0, params) @ P``), and whether k lies in the star of -k0 (the labels are conjugates); ``None`` where :meth:`label_characters` returns ``None``. """ matched = self._match_family( k_primitive, little_rotations, little_translations, spgrep_characters, atol, minus_k, ) if matched is None: return None _label_map, _ktype, family, conjugate = matched ir, _arm, params = family[0] k0_conventional = ir.arm_k(0, params) return np.asarray(k0_conventional, dtype=float) @ self.P + 0.0, conjugate
def _match_family(self, k_primitive, little_rotations, little_translations, spgrep_characters, atol, minus_k): """The search behind :meth:`label_characters` and :meth:`representative_k`: ``(label_map, k-type, family, conjugate)`` of the first family whose characters match, ``conjugate`` telling whether the characters were matched as complex conjugates (the -k branches), or None.""" k_conv = self.conventional_k(k_primitive) conv_ops = self.conventional_operations( little_rotations, little_translations ) conjugates = [np.conj(chi) for chi in spgrep_characters] for ktype, family in self._matched_families(k_conv): minus_family = self._minus_side(ktype, family, k_conv) if minus_family is not None: # the -k partner of the star at -k (LE of LD) result = self._try_family(minus_family, conv_ops, conjugates, atol) if result is not None: return ( {m: minus_k_label(name, self.sgnum) for m, name in result.items()}, minus_k_type(ktype, self.sgnum), minus_family, True, ) continue result = self._try_family(family, conv_ops, spgrep_characters, atol) if result is not None: return result, ktype, family, False if minus_k: for ktype, family in self._matched_families(-k_conv): result = self._try_family(family, conv_ops, conjugates, atol) if result is not None: return ( {m: minus_k_label(name, self.sgnum) for m, name in result.items()}, minus_k_type(ktype, self.sgnum), family, True, ) return None
[docs] def decompose_characters( self, k_primitive, little_rotations, little_translations, reducible_characters, atol: float = 1e-3, ) -> Optional[tuple[list[tuple[str, int, int]], str]]: """Decompose a reducible character vector into ISO-IR irreps. Used for phonopy band sets, whose characters can be reducible under accidental degeneracy. As in ``label_characters``, the -k partner of a tabulated star gets ISOTROPY's partner names (PA1, LE1). Args: k_primitive: k vector in the primitive reciprocal basis. little_rotations: Rotations of the little group of k in the primitive basis. little_translations: Their fractional translations. reducible_characters: The character vector, aligned with the little-group operations, in the spgrep/phonopy phase convention ``exp(-2 pi i k.t)``. atol: Tolerance of the multiplicity check. Returns: ``([(label, multiplicity, small_dim), ...], k-type label)``, or ``None`` when no consistent decomposition exists. """ results = self.decompose_characters_many( k_primitive, little_rotations, little_translations, [reducible_characters], atol=atol, ) return results[0]
[docs] def decompose_characters_many( self, k_primitive, little_rotations, little_translations, character_vectors, atol: float = 1e-3, ) -> list[Optional[tuple[list[tuple[str, int, int]], str]]]: """Decompose several reducible character vectors at one k point. Same as ``decompose_characters``, but the candidate-family search (the expensive part) is done once and shared by all vectors; use this for phonopy band sets, which all live at the same q. Args: k_primitive: k vector in the primitive reciprocal basis. little_rotations: Rotations of the little group of k in the primitive basis. little_translations: Their fractional translations. character_vectors: The reducible character vectors, each aligned with the little-group operations (phase convention ``exp(-2 pi i k.t)``). atol: Tolerance of the multiplicity check. Returns: One entry per input vector, each ``([(label, multiplicity, small_dim), ...], k-type label)`` or ``None`` when no consistent decomposition exists. """ n_vectors = len(character_vectors) k_conv = self.conventional_k(k_primitive) conv_ops = self.conventional_operations( little_rotations, little_translations ) e_index = None for j, (R_c, t_c) in enumerate(conv_ops): if np.array_equal(R_c, np.eye(3, dtype=int)) and np.allclose( np.asarray(t_c) - np.rint(t_c), 0, atol=1e-6 ): e_index = j break if e_index is None: return [None] * n_vectors # k itself (the -k partner of the star at -k on a line, see # label_characters), then -k with the conjugate characters candidates = [] for ktype, family in self._matched_families(k_conv): minus_family = self._minus_side(ktype, family, k_conv) if minus_family is None: candidates.append((ktype, family, False)) else: candidates.append((ktype, minus_family, True)) candidates += [ (ktype, family, True) for ktype, family in self._matched_families(-k_conv) ] for ktype, family, conjugate in candidates: iso_chars = self._family_characters_checked(family, conv_ops) if iso_chars is None: continue name = minus_k_type(ktype, self.sgnum) if conjugate else ktype results: list[Optional[tuple[list[tuple[str, int, int]], str]]] = [] for reducible in character_vectors: red = np.asarray(reducible, dtype=complex) counts = self._decompose_against( family, iso_chars, np.conj(red) if conjugate else red, e_index, len(conv_ops), atol, ) if counts is not None and conjugate: counts = [ (minus_k_label(label, self.sgnum), n, dim) for label, n, dim in counts ] results.append((counts, name) if counts is not None else None) # the family validity checks are vector-independent, so # per-vector failures here are numerical; keep them as None if any(result is not None for result in results): return results return [None] * n_vectors
@staticmethod def _decompose_against(family, iso_chars, red, e_index, n_ops, atol): """Multiplicities of one reducible character vector in a family, or None when they are not consistent non-negative integers. The multiplicity of the irrep with characters conj(chi_iso) in red is n = (1/|G|) sum_g conj(conj(chi_iso(g))) red(g). """ total_dim = int(round(red[e_index].real)) counts: list[tuple[str, int, int]] = [] dim_sum = 0 for (ir, _, _), chi in zip(family, iso_chars): n = complex(np.dot(chi, red)) / n_ops ni = int(round(n.real)) if abs(n - ni) > atol or ni < 0: return None if ni: counts.append((ir.label, ni, ir.small_dim)) dim_sum += ni * ir.small_dim if dim_sum != total_dim: return None return counts def _matched_families(self, k_conv): """Candidate irreps whose star contains k, grouped by k-type and sorted most specific k type (fewest free parameters) first.""" # the search depends on the tables and on k only, and every band of # every atom asks for the same few k points key = (self.sgnum,) + tuple(np.round(np.asarray(k_conv, dtype=float), 10)) if key not in _FAMILY_CACHE: if len(_FAMILY_CACHE) >= 4096: _FAMILY_CACHE.clear() families: dict[str, list[tuple[IsoIrrep, int, np.ndarray]]] = {} by_type: dict = {} # the irreps of one k type share their k vectors for ir in self.irreps: if ir.ktype not in by_type: by_type[ir.ktype] = (ir.kvecs, ir.match_k(k_conv)) kvecs, matched = by_type[ir.ktype] if kvecs is not ir.kvecs and not np.array_equal(kvecs, ir.kvecs): matched = ir.match_k(k_conv) if matched is not None: families.setdefault(ir.ktype, []).append( (ir, matched[0], matched[1]) ) _FAMILY_CACHE[key] = sorted( families.items(), key=lambda item: item[1][0][0].num_free_params ) return _FAMILY_CACHE[key] def _family_characters_checked(self, family, conv_ops): """ISO-IR character vectors of a family, or None when the family does not describe the little group of these operations.""" # all little-group operations must belong to the family's little group for ir, arm, params in family: for R_c, _ in conv_ops: if not ir.in_little_group(R_c, arm, params): return None # the family must exhaust the little group if sum(ir.small_dim**2 for ir, _, _ in family) != len(conv_ops): return None try: return self._family_characters(family, conv_ops) except LookupError: # setting mismatch (operator or translation not found): the # transformation into the ISO-IR setting is wrong -- fail safe return None def _try_family(self, family, conv_ops, spgrep_characters, atol): iso_chars = self._family_characters_checked(family, conv_ops) if iso_chars is None: return None label_map: dict[int, str] = {} used: set[str] = set() for m, chi in enumerate(spgrep_characters): hits = [ ir.label for (ir, _, _), chi_iso in zip(family, iso_chars) if ir.label not in used and np.allclose(chi, np.conj(chi_iso), atol=atol) ] if len(hits) != 1: return None label_map[m] = hits[0] used.add(hits[0]) return label_map @staticmethod def _family_characters(family, conv_ops): iso_chars = [] for ir, arm, params in family: iso_chars.append( np.array( [ ir.small_character(R_c, t_c, arm, params) for R_c, t_c in conv_ops ] ) ) return iso_chars
# --------------------------------------------------------------- shared helpers _LABELER_CACHE: dict = {} _FAMILY_CACHE: dict = {} _NORMALIZER_CACHE: dict = {} _OPERATIONS_CACHE: dict = {} # ------------------------------------------------- the ISO-IR frame of a cell # # An irrep label is only defined relative to a description of the crystal in # the ISO-IR standard setting. The setting leaves a choice: translating the # origin by an element of the Euclidean normalizer (Si on Wyckoff 8a or 8b of # Fd-3m, Sr or Ti at the origin of Pm-3m) is again a standard setting, and it # permutes labels at zone-boundary points (L1+ <-> L2-, R4+ <-> R5-). spglib # returns one of these frames, and which one depends on the cell it is given, # so two commands working on different cells of one structure (phonopy's # primitive cell, the spglib-standardized primitive cell) would name one # irrep differently. The frame is therefore fixed by these rules: # # 1. a cell that is already in the ISO-IR setting keeps its own axes and # origin (the user's choice of setting is respected, including the sense # of a polar axis); so does an n1 x n2 x n3 supercell of such a cell # of any size (a non-diagonal supercell falls to rule 2); # 2. otherwise the frame is a property of the structure, not of the cell it # came from. The candidates are spglib's frame and its images under the # Euclidean normalizer: a proper rotation W of the lattice that maps the # group onto itself (the sixfold axis for P-6m2, the twofold axis that # reverses the polar axis of P4), followed by a normalizer translation. # Frames that keep the cell's own origin are preferred when there are # any; among the candidates the one with the lexicographically smallest # list of atomic positions is taken (coordinates compared by their # cluster rank at 0.71, 0.071 and 0.0071 times the symmetry tolerance, # _smallest_structure). Along a polar axis the origin is free and carries # no information; it is put on an atom of the species with the smallest # atomic number, again by the smallest list; # 3. a working cell derived from an input cell (primitive reduction, # standardization) inherits the frame of the input cell through the affine # map between the two. def _dataset_item(dataset, name): return dataset[name] if isinstance(dataset, dict) else getattr(dataset, name) def _iso_table_entry(sgnum: int) -> IsoIrrep: """The ISO-IR block listing every coset representative of the group.""" return max(load_isoir_irreps(sgnum, "cir"), key=lambda ir: ir.opcount) def _frame_is_valid(entry: IsoIrrep, rotations, translations, P, origin, atol: float) -> bool: """Do the operations of a cell become the tabulated ISO-IR operations under x_iso = P x + origin?""" P = np.asarray(P, dtype=float) try: P_inv = np.linalg.inv(P) except np.linalg.LinAlgError: return False found = set() for R, t in zip(rotations, translations): R_c = P @ np.asarray(R, dtype=float) @ P_inv R_int = np.rint(R_c) if not np.allclose(R_c, R_int, atol=1e-6): return False j = entry.find_operator(R_int.astype(int)) if j is None: return False t_c = P @ np.asarray(t, dtype=float) + (np.eye(3) - R_int) @ origin if not _is_lattice_translation( t_c - entry.translations[j], entry.centering, atol ): return False found.add(j) return len(found) == entry.opcount def _polar_axes(entry: IsoIrrep) -> np.ndarray: """Conventional axes along which the origin is free: e_i is kept by every rotation of the group (z of P4, x and z of Pm, all of P1).""" identity = np.eye(3, dtype=int) return np.array([ all(np.array_equal(np.asarray(R)[:, i], identity[:, i]) for R in entry.rotations) for i in range(3) ]) def _normalizer_translations(sgnum: int, W=None) -> np.ndarray: """Translations w (on the 1/24 grid, zero along the polar axes) for which x -> W x + w maps the ISO-IR setting of a space group onto itself. ``W`` is a rotation in the conventional basis (default: the identity, which gives the origin shifts of the setting). The result is empty when W is not the linear part of a normalizer element.""" W = np.eye(3) if W is None else np.asarray(W, dtype=float) key = (int(sgnum), np.round(W, 6).tobytes()) if key not in _NORMALIZER_CACHE: entry = _iso_table_entry(sgnum) polar = _polar_axes(entry) axes = [np.zeros(1) if polar[i] else np.arange(24) / 24.0 for i in range(3)] grid = np.array(np.meshgrid(*axes, indexing="ij")).reshape(3, -1).T centerings = [np.zeros(3)] + [ np.array(v) for v in _CENTERING_TRANSLATIONS[entry.centering] ] W_inv = np.linalg.inv(W) keep = np.ones(len(grid), dtype=bool) for R, tau in zip(entry.rotations, entry.translations): # {W|w} {R|tau} {W|w}^-1 = {W R W^-1 | W tau + (1 - W R W^-1) w} image_R = W @ np.asarray(R, dtype=float) @ W_inv image_int = np.rint(image_R) j = ( entry.find_operator(image_int.astype(int)) if np.allclose(image_R, image_int, atol=1e-6) else None ) if j is None: keep[:] = False break image = ( W @ np.asarray(tau, dtype=float) + grid @ (np.eye(3) - image_int).T - entry.translations[j] ) lattice = np.zeros(len(grid), dtype=bool) for c in centerings: d = image - c lattice |= np.all(np.abs(d - np.rint(d)) < 1e-9, axis=1) keep &= lattice _NORMALIZER_CACHE[key] = grid[keep] return _NORMALIZER_CACHE[key] def _lattice_rotations(P, lattice, centering: str, symprec: float) -> list: """Proper rotations of the crystal lattice, in the conventional basis of the frame ``x_iso = P x + o`` of a cell with the given lattice.""" import spglib conventional = np.linalg.inv(np.asarray(P, dtype=float)).T @ np.asarray( lattice, dtype=float ) points = [np.zeros(3)] + [np.array(v) for v in _CENTERING_TRANSLATIONS[centering]] symmetry = spglib.get_symmetry( (conventional, points, [1] * len(points)), symprec=symprec ) if symmetry is None: return [np.eye(3)] seen, result = set(), [] for R in _dataset_item(symmetry, "rotations"): R = np.asarray(R, dtype=int) if round(float(np.linalg.det(R))) != 1 or R.tobytes() in seen: continue seen.add(R.tobytes()) result.append(R.astype(float)) return result or [np.eye(3)] def _smallest_structure(frames, positions, numbers, centering: str, tolerance: float) -> int: """Index of the frame in which the sorted list of atomic positions of the conventional cell is the smallest (atoms of the species with the smallest type number on the origin, then on low fractions; the type numbers are atomic numbers in the CrystOD commands). Coordinates closer than the tolerance count as equal: a coordinate is replaced by the rank of its cluster among the coordinates of all frames, so that the comparison does not depend on how a value such as 0.07465 happens to round. Frames that tie are compared again at one tenth and one hundredth of the level; frames that still tie describe the structure identically within that tolerance. The levels are 0.71 times powers of ten of the tolerance: coordinates typed with a few decimals differ by multiples of 1e-5, 1e-6, ..., and a level equal to such a gap would leave the decision to floating-point noise.""" centerings = [np.zeros(3)] + [ np.array(v) for v in _CENTERING_TRANSLATIONS[centering] ] positions = np.asarray(positions, dtype=float) species = np.tile(np.asarray(numbers, dtype=np.int64), len(centerings)) coordinates = [] for P, origin in frames: x = positions @ np.asarray(P, dtype=float).T + origin x = np.concatenate([x + c for c in centerings]) # the wrap at 1 uses the first level too: a gap of exactly one # decimal unit between two atoms must not straddle it coordinates.append(x - np.floor(x + 0.71 * tolerance)) alive = list(range(len(frames))) for level in (0.71 * tolerance, 0.071 * tolerance, 0.0071 * tolerance): if len(alive) == 1: break values = np.sort(np.concatenate([coordinates[i].ravel() for i in alive])) rank = np.concatenate( [[0], np.cumsum(np.diff(values) > level * (1.0 + 1e-9))] ) keys = [] for i in alive: index = rank[np.searchsorted(values, coordinates[i])] rows = np.unique(np.column_stack([species, index]), axis=0) keys.append(rows.ravel().tolist()) smallest = min(keys) alive = [i for i, key in zip(alive, keys) if key == smallest] return alive[0] def _cell_operations(sgnum: int, cell, symprec: float): """``(rotations, translations, P, origin)``: every operation of the crystal in the basis of the given cell, and spglib's frame ``x_iso = P x + origin`` of the cell; None when spglib and the ISO-IR table do not describe the same group. spglib lists only the operations that keep the lattice of the cell, so a supercell loses some (a 2x1x1 cell of a cubic crystal keeps 16 of the 48 rotations) and gains pure translations. The list returned here is the ISO-IR table carried back through spglib's frame instead; a rotation need not be an integer matrix in the basis of a supercell. The lattice translations of the crystal come last, as operations with the identity rotation, so that a frame is valid only when it also has the lattice of the crystal.""" key = (int(sgnum), float(symprec)) + _cell_key(cell) if key not in _OPERATIONS_CACHE: if len(_OPERATIONS_CACHE) >= 64: _OPERATIONS_CACHE.clear() _OPERATIONS_CACHE[key] = _cell_operations_uncached(sgnum, cell, symprec) return _OPERATIONS_CACHE[key] def _cell_operations_uncached(sgnum: int, cell, symprec: float): import spglib try: dataset = spglib.get_symmetry_dataset( cell, symprec=symprec, hall_number=iso_hall_number(sgnum) ) symmetry = spglib.get_symmetry(cell, symprec=symprec) except Exception: # spglib raises its own SpglibError family return None if ( dataset is None or symmetry is None or _dataset_item(dataset, "number") != sgnum ): return None P = np.asarray(_dataset_item(dataset, "transformation_matrix"), dtype=float) origin = np.asarray(_dataset_item(dataset, "origin_shift"), dtype=float) entry = _iso_table_entry(sgnum) atol = max(1e-4, 10.0 * float(symprec)) P_inv = np.linalg.inv(P) # the operations spglib lists for the cell must be tabulated ones for R, t in zip( _dataset_item(symmetry, "rotations"), _dataset_item(symmetry, "translations") ): R_c = P @ np.asarray(R, dtype=float) @ P_inv R_int = np.rint(R_c) j = ( entry.find_operator(R_int.astype(int)) if np.allclose(R_c, R_int, atol=1e-6) else None ) if j is None: return None t_c = P @ np.asarray(t, dtype=float) + (np.eye(3) - R_int) @ origin if not _is_lattice_translation( t_c - entry.translations[j], entry.centering, atol ): return None rotations, translations = [], [] for R, t in zip(entry.rotations, entry.translations): R = np.asarray(R, dtype=float) rotations.append(P_inv @ R @ P) translations.append(P_inv @ (R @ origin + np.asarray(t, dtype=float) - origin)) lattice_vectors = list(np.eye(3)) + [ np.array(v) for v in _CENTERING_TRANSLATIONS[entry.centering] ] for v in lattice_vectors: rotations.append(np.eye(3)) translations.append(P_inv @ v) return rotations, translations, P, origin def _frame_matches(entry: IsoIrrep, operations, P, origin, atol: float) -> bool: """Is ``x_iso = P x + origin`` an ISO-IR frame of the crystal: the tabulated operations on the lattice of the crystal (not a sublattice or a superlattice of it)?""" rotations, translations, P_spglib, _ = operations try: volume = abs(np.linalg.det(np.asarray(P, dtype=float) @ np.linalg.inv(P_spglib))) except np.linalg.LinAlgError: return False if abs(volume - 1.0) > 1e-6: return False return _frame_is_valid(entry, rotations, translations, P, origin, atol) def canonical_iso_frame(sgnum: int, cell, symprec: float = 1e-5): """The ISO-IR frame ``(P, origin_shift)`` of a cell, by rules 1 and 2. Args: sgnum: Space-group number (1-230). cell: spglib tuple ``(lattice, scaled_positions, numbers)``. symprec: Symmetry tolerance for spglib. Returns: ``(P, origin_shift)`` with ``x_iso = P x + origin_shift``, or ``None`` when spglib or the ISO-IR data cannot provide a frame. """ lattice, positions, numbers = cell operations = _cell_operations(sgnum, cell, symprec) if operations is None: return None P, origin = operations[2], operations[3] entry = _iso_table_entry(sgnum) atol = max(1e-4, 10.0 * float(symprec)) zero = np.zeros(3) # rule 1: the cell's own axes and origin, for a conventional cell, its # primitive cell in the standard centring, or an n1 x n2 x n3 supercell # of either. n_i is read from the lattice: the i-th cell vector is n_i # times a primitive lattice vector (the edges of both unit cells are # primitive). units = [np.eye(3)] if entry.centering != "P": from phonopy.structure.cells import get_primitive_matrix_by_centring units.append( np.array(get_primitive_matrix_by_centring(entry.centering), dtype=float) ) content = np.linalg.inv(units[-1]) @ P # columns: cell vectors, primitive basis if np.allclose(content, np.rint(content), atol=1e-5): multiples = np.gcd.reduce(np.abs(np.rint(content).astype(np.int64)), axis=0) if np.all(multiples >= 1): for unit in units: P0 = unit @ np.diag(multiples.astype(float)) if _frame_matches(entry, operations, P0, zero, atol): return P0, zero # rule 2: the images of spglib's frame under the Euclidean normalizer lattice_rotations = _lattice_rotations(P, lattice, entry.centering, symprec) candidates = [ (W @ P, zero) for W in lattice_rotations if _frame_matches(entry, operations, W @ P, zero, atol) ] if not candidates: # no frame keeps the cell's own origin; a rotation of the group # itself gives an equivalent frame, so one W per coset is enough group = { tuple(int(v) for v in np.asarray(R).ravel()) for R in entry.rotations } cosets = [] for W in lattice_rotations: if any( tuple(int(v) for v in np.rint(W @ np.linalg.inv(V)).ravel()) in group for V in cosets ): continue shifts = _normalizer_translations(sgnum, W) if len(shifts) == 0: continue cosets.append(W) candidates.extend((W @ P, W @ origin + shift) for shift in shifts) polar = _polar_axes(entry) if polar.any(): # the free origin along the polar axes: on an atom of the species # with the smallest type number (the atomic number in the CrystOD # commands; any of its copies under the centring translations) numbers = np.asarray(numbers) lightest = np.asarray(positions, dtype=float)[numbers == numbers.min()] centerings = [np.zeros(3)] + [ np.array(v) for v in _CENTERING_TRANSLATIONS[entry.centering] ] anchored = [] for P_c, origin_c in candidates: seen = set() # the atoms of a supercell repeat the same positions for x in lightest @ P_c.T + origin_c: for c in centerings: offset = (x + c)[polar] reduced = np.round(offset - np.floor(offset + 1e-7), 6) key = tuple(np.where(reduced >= 1.0, 0.0, reduced)) if key in seen: continue seen.add(key) shifted = np.array(origin_c, dtype=float) shifted[polar] -= offset anchored.append((P_c, shifted)) candidates = anchored if candidates: P_c, origin_c = candidates[_smallest_structure( candidates, positions, numbers, entry.centering, float(symprec) )] if _frame_matches(entry, operations, P_c, origin_c, atol): return P_c, origin_c - np.floor(origin_c + 1e-9) return P, origin def _affine_map_between_cells(input_cell, work_cell, symprec: float): """``(A, b)`` with ``x_input = A x_work + b`` for two cells of one structure, or None. Two relations are recognized: the working cell shares the Cartesian frame and origin of the input cell (phonopy's primitive cell), or it is the spglib standardization of the input cell (idealized frame, origin shift). The map is accepted only when it sends every atom of the working cell onto an atom of the same species of the input cell.""" import spglib L_in, X_in, Z_in = (np.asarray(a) for a in input_cell) L_w, X_w, Z_w = (np.asarray(a) for a in work_cell) L_in = L_in.astype(float) L_w = L_w.astype(float) tolerance = max(1e-3, 10.0 * float(symprec)) # Angstrom def maps_onto(A, b) -> bool: if not np.isfinite(A).all() or abs(np.linalg.det(A)) < 1e-8: return False for x, z in zip(X_w, Z_w): image = A @ np.asarray(x, dtype=float) + b same = X_in[Z_in == z] if len(same) == 0: return False d = image - same d = d - np.rint(d) if np.min(np.linalg.norm(d @ L_in, axis=1)) > tolerance: return False return True candidates = [((L_w @ np.linalg.inv(L_in)).T, np.zeros(3))] try: dataset = spglib.get_symmetry_dataset(input_cell, symprec=symprec) T = np.asarray(_dataset_item(dataset, "transformation_matrix"), dtype=float) shift = np.asarray(_dataset_item(dataset, "origin_shift"), dtype=float) L_std = np.asarray(_dataset_item(dataset, "std_lattice"), dtype=float) T_inv = np.linalg.inv(T) candidates.append((T_inv @ (L_w @ np.linalg.inv(L_std)).T, -T_inv @ shift)) except Exception: pass for A, b in candidates: if maps_onto(A, b): return A, b return None def iso_frame_for_derived_cell(sgnum: int, input_cell, work_cell, symprec: float = 1e-5): """ISO-IR frame of a working cell inherited from its input cell (rule 3). Returns ``(P, origin_shift)`` for the working cell, or ``None`` when the relation between the two cells cannot be established or the inherited frame does not reproduce the tabulated operations. """ frame = canonical_iso_frame(sgnum, input_cell, symprec) relation = _affine_map_between_cells(input_cell, work_cell, symprec) if frame is None or relation is None: return None P_in, origin_in = frame A, b = relation P = P_in @ A origin = P_in @ b + origin_in operations = _cell_operations(sgnum, work_cell, symprec) if operations is None or not _frame_matches( _iso_table_entry(sgnum), operations, P, origin, max(1e-4, 10.0 * float(symprec)), ): return None return P, origin def _cell_key(cell) -> tuple: lattice, positions, numbers = cell return ( np.asarray(lattice, dtype=float).round(10).tobytes(), np.asarray(positions, dtype=float).round(10).tobytes(), np.asarray(numbers, dtype=int).tobytes(), ) def get_cached_labeler(sgnum: int, cell, symprec: float = 1e-5, input_cell=None): """Cached IsoIRLabeler for a primitive cell, or None when unavailable. ``cell`` is a spglib tuple (lattice, scaled_positions, numbers) of the primitive cell whose symmetry operations feed spgrep. ``input_cell`` is the cell the user gave when ``cell`` was derived from it (primitive reduction or standardization): the labels then refer to the ISO-IR frame of the input cell, so every command names an irrep of one structure the same way whatever cell it works on. Returns None when the ISO-IR data files are missing or standardization fails, so callers can fall through to their existing generic labels. """ key = (int(sgnum), float(symprec)) + _cell_key(cell) if input_cell is not None: key += _cell_key(input_cell) if key not in _LABELER_CACHE: try: frame = None if input_cell is not None: frame = iso_frame_for_derived_cell(sgnum, input_cell, cell, symprec) if frame is None: frame = canonical_iso_frame(sgnum, cell, symprec) if frame is None: labeler = IsoIRLabeler(sgnum, cell=cell, symprec=symprec) else: labeler = IsoIRLabeler( sgnum, transformation_matrix=frame[0], origin_shift=frame[1] ) _LABELER_CACHE[key] = labeler except Exception: _LABELER_CACHE[key] = None return _LABELER_CACHE[key]
[docs] def get_isoir_label_map( sgnum: int, cell, symprec: float, kpoint, little_rotations, little_translations, spgrep_characters, input_cell=None, minus_k: bool = True, ) -> Optional[tuple[dict[int, str], str]]: """Label spgrep small irreps at a k point with ISO-IR labels. One-stop entry point shared by every labeling path of CrystOD (crystal orbitals, orbital hybridization, spin bases, phonons): builds (and caches) the ``IsoIRLabeler`` of the cell and calls its ``label_characters``. Never raises: any failure yields ``None`` so that callers can fall back to generic labels. Args: sgnum: Space-group number (1-230). cell: Primitive cell as an spglib tuple ``(lattice, scaled_positions, numbers)`` whose operations feed spgrep. symprec: Symmetry tolerance for spglib. kpoint: k vector in the primitive reciprocal basis. little_rotations: Rotations of the little group of k in the primitive basis. little_translations: Their fractional translations. spgrep_characters: One character vector per spgrep irrep, aligned with the little-group operations (phase convention ``exp(-2 pi i k.t)``). input_cell: The cell the user gave, when ``cell`` was derived from it; the labels then refer to the ISO-IR frame of that cell (see ``get_cached_labeler``). minus_k: Label a k point without a tabulated star through its -k partner, with ISOTROPY's partner names (see ``IsoIRLabeler.label_characters``). Returns: ``({spgrep irrep index: label}, k-type label)`` such as ``({0: "Q1"}, "Q")``, or ``None`` when the ISO-IR data are unavailable or no consistent assignment exists. """ labeler = get_cached_labeler(sgnum, cell, symprec, input_cell) if labeler is None: return None try: return labeler.label_characters( kpoint, little_rotations, little_translations, spgrep_characters, minus_k=minus_k, ) except Exception: return None
def get_isoir_kpoint_name(sgnum: int, cell, symprec: float, kpoint, input_cell=None, minus_k: bool = True) -> Optional[str]: """Most specific ISO-IR k-vector type label for a k point, or None. With ``minus_k``, a point whose -k partner is the tabulated one is named by ISOTROPY's partner name (``"PA"``; ``minus_k_type``).""" labeler = get_cached_labeler(sgnum, cell, symprec, input_cell) if labeler is None: return None try: return labeler.kpoint_name(kpoint, minus_k=minus_k) except Exception: return None def special_points_in_frame(names, kpoints, labeler, canonical=None): """The tabulated special points of a list, named in the frame of the labels. The lists of special points are built from the tables through spglib's standardized basis, while the labels refer to the ISO-IR frame of the input cell (``get_cached_labeler``). The two differ by an element of the normalizer when the input is not in the ISO-IR setting, and that element can turn the tabulated point H into the -k partner of H or into another tabulated point. This returns the same list with every point named by the labeller, and with a point that is the 'A' partner of a tabulated type replaced by the tabulated point itself (-k), so that the names in the list are the letters of the labels printed at each point. Args: names: k-point names of the list. kpoints: Their coordinates in the primitive reciprocal basis. labeler: The ``IsoIRLabeler`` of the cell, or ``None``. canonical: Function applied to the coordinates of a replaced point (the snapping convention of the caller); default: none. Returns: ``(names, kpoints)``; the input lists themselves when there is no labeller or the renaming is not one-to-one. """ if labeler is None: return names, kpoints tabulated = list(names) new_names, new_points = [], [] for name, k in zip(names, kpoints): try: found = labeler.kpoint_name(k) except Exception: found = None point = k if found is None: found = name elif found not in tabulated: partners = [ t for t in tabulated if minus_k_label(t, labeler.sgnum) == found ] if not partners: return names, kpoints found = partners[0] point = [-float(v) + 0.0 for v in k] if canonical is not None: point = canonical(point) new_names.append(found) new_points.append(point) if len(set(new_names)) != len(new_names): return names, kpoints return new_names, new_points def get_isoir_band_decomposition( sgnum: int, cell, symprec: float, kpoint, little_rotations, little_translations, reducible_characters, input_cell=None, ) -> Optional[tuple[list[tuple[str, int, int]], str]]: """Decompose one reducible character vector into ISO-IR irreps. The labelling route of phonopy band sets (whose characters can be reducible under accidental degeneracy); a k point tabulated only through its -k partner gets 'A' labels, as in ``label_characters``. Returns ([(label, multiplicity, dim), ...], k-type label) or None. Never raises. """ labeler = get_cached_labeler(sgnum, cell, symprec, input_cell) if labeler is None: return None try: return labeler.decompose_characters( kpoint, little_rotations, little_translations, reducible_characters ) except Exception: return None def get_isoir_band_decompositions( sgnum: int, cell, symprec: float, kpoint, little_rotations, little_translations, character_vectors, input_cell=None, ) -> list[Optional[tuple[list[tuple[str, int, int]], str]]]: """Decompose several reducible character vectors at one k point. Batch version of get_isoir_band_decomposition: the candidate-family search is done once for all vectors (phonopy band sets share the q); 'A' labels at a k point tabulated only through -k as there. Returns one entry per vector. Never raises. """ labeler = get_cached_labeler(sgnum, cell, symprec, input_cell) if labeler is None: return [None] * len(character_vectors) try: return labeler.decompose_characters_many( kpoint, little_rotations, little_translations, character_vectors ) except Exception: return [None] * len(character_vectors)