"""Isotropy-subgroup tables of a parent space group and the reverse lookup.
``crystod-group --parent SG --irrep IR`` answers "which subgroups does this
irrep give?". This module answers the reverse question: given the parent G
and a subgroup type H, which irreps (and which order-parameter directions)
give an isotropy subgroup of type H? It is the offline counterpart of the
reverse search of the ISOSUBGROUP tool of the ISOTROPY Software Suite
(https://iso.byu.edu).
How it works:
- ``isotropy_table(parent)`` enumerates, once per parent, every stratum of
every irrep at every special k point of the ISO-IR tables (the irreps of
``crystod-group --parent SG --kpoint K`` for every K), with the direction
pattern, the subgroup type, the cell size, the index, the conventional
basis and origin of the subgroup in the parent setting, a generic
order-parameter vector and the projector onto the stratum.
- The table is written to ``<cache>/isotropy/<number>_<version>.json.gz``,
where ``<cache>`` is ``$CRYSTOD_CACHE_DIR`` or ``~/.cache/crystod`` and
``<version>`` is ``crystod.__version__`` (the labels and settings follow
the conventions of the installed version, so no data is shipped with the
package). Later lookups read the file instead of recomputing.
- ``find_isotropy_irreps(parent, child)`` filters the table by subgroup type
(by number; in a parent with improper operations the enantiomorphic
partner type of ``ENANTIOMORPHIC_PAIRS`` counts as a match, since an
improper operation of the parent maps the order parameter to another one
of the same stratum whose stabilizer is the partner; in a Sohncke parent
the two types come from different strata and are kept apart), and
optionally by cell size, index and k point.
- A complex-type pair whose partner sits at the -k star (``K1KA1`` of P3)
is listed once, at the first of the two stars; ``--kpoint`` with the
other star selects the same rows.
Several rows of the same type are several embeddings of H in G (different
orientations or origins of the subgroup cell); their conventional basis and
origin tell them apart. Only single-irrep order parameters at the special
k points are tabulated. A subgroup that needs two coupled irreps (Pnma
with cell size 4 from the R4+ + M3+ tilts of Pm-3m) is found by
``find_coupled_isotropy_irreps`` (``--child H --coupled``): it searches the
pairs of irreps, first two irreps at the same k point, then pairs at
different k points, and builds the coupled strata of a pair by intersecting
the isotropy subgroups of the single strata of the table (every coupled
isotropy subgroup is ``S1 & S2'`` with ``S1`` an isotropy subgroup of the
first irrep and ``S2'`` any conjugate of one of the second). Only irreps
with a single stratum whose point group has an order divisible by that of
H (and, with ``--size`` and ``--index``, whose size and index divide the
requested ones) can take part, which prunes most pairs.
If you use this feature, please cite: H. T. Stokes, S. van Orden and
B. J. Campbell, "Tool for Generating Isotropy Subgroups of Crystallographic
Space Groups", J. Appl. Cryst. 49, 1849-1853 (2016).
"""
from __future__ import annotations
import gzip
import json
import os
import sys
from dataclasses import dataclass, field
import numpy as np
CACHE_ENV = "CRYSTOD_CACHE_DIR"
_FORMAT = 2
# sources whose changes can change the table (labels, settings, strata)
_FINGERPRINT_FILES = ("isotropy_subgroup.py", "isotropy_table.py", "isoir.py",
"spacegroup_product.py", "CIR_data.txt.gz")
# point groups without improper operations (the 65 Sohncke space groups)
_SOHNCKE_POINT_GROUPS = frozenset(
{"1", "2", "222", "4", "422", "3", "32", "6", "622", "23", "432"}
)
# ---------------------------------------------------------------- data model
@dataclass(frozen=True)
class IsotropyStratum:
"""One stratum (order-parameter direction type) of one irrep.
A row of the ``crystod-group --parent SG --kpoint K`` table with the
setting and the order parameter behind it.
Attributes:
label: ISO-IR label of the irrep, e.g. ``"R4+"`` (the pair label
such as ``"GM2+GM3+"`` for a complex-type pair).
kname: Name of its special k point, e.g. ``"R"``.
dimension: Dimension of the order parameter of the irrep.
direction: Direction pattern, e.g. ``"(0,0,a)"`` (``;`` between
star arms).
n_free: Number of free order-parameter parameters.
number: Space-group number of the isotropy subgroup.
symbol: Its international short symbol.
size: Primitive-cell multiplication relative to the parent.
index: Index of the subgroup in the parent.
basis: Rows of the conventional cell of the subgroup in parent
conventional units (as ``--order-parameter`` prints them), or
``None`` when the setting could not be standardized.
origin: Origin of that cell in parent conventional coordinates, or
``None``.
vector: A generic order-parameter vector of the stratum (its
stabilizer is the isotropy subgroup).
projector: The orthogonal projector onto the stratum subspace.
"""
label: str
kname: str
dimension: int
direction: str
n_free: int
number: int
symbol: str
size: int
index: int
basis: np.ndarray | None = field(default=None, compare=False)
origin: np.ndarray | None = field(default=None, compare=False)
vector: np.ndarray | None = field(default=None, compare=False)
projector: np.ndarray | None = field(default=None, compare=False)
[docs]
@dataclass(frozen=True)
class IsotropyMatch:
"""One answer of the reverse lookup: an irrep stratum giving type H.
Attributes:
label: ISO-IR label of the irrep, e.g. ``"R4+"``.
kname: Its special k point, e.g. ``"R"``.
direction: Order-parameter direction, e.g. ``"(0,0,a)"``.
number: Space-group number of the isotropy subgroup (H, or its
enantiomorphic partner).
symbol: International short symbol of the subgroup.
size: Primitive-cell multiplication relative to the parent.
index: Index of the subgroup in the parent.
basis: Conventional basis of the subgroup (rows, parent conventional
units), or ``None``.
origin: Origin of the subgroup cell (parent conventional
coordinates), or ``None``.
"""
label: str
kname: str
direction: str
number: int
symbol: str
size: int
index: int
basis: np.ndarray | None = field(default=None, compare=False)
origin: np.ndarray | None = field(default=None, compare=False)
def __str__(self) -> str:
return (
f"{self.label}{self.direction} ({self.kname}) -> {self.symbol} "
f"(No. {self.number}), size {self.size}, index {self.index}"
)
[docs]
@dataclass
class IsotropyTable:
"""Every single-irrep stratum of a parent space group.
Returned by :func:`isotropy_table`.
Attributes:
space_group: International short symbol of the parent.
number: Its number.
version: The CrystOD version that built the table.
kpoints: Maps every special k-point name, in table order, to a dict
with ``coordinates`` (the tabulated arm, primitive reciprocal
basis), ``arms`` (all arms), ``n_arms`` and ``listed_at`` (the
k points under which its irreps are listed: itself, or the
first star of a pair that spans both the k and the -k star).
irreps: ``(label, kname, dimension)`` of every analyzed irrep, in
table order.
strata: Every :class:`IsotropyStratum`, irrep by irrep, each irrep
in the order of the ``--parent`` table.
errors: Maps the label of an irrep that could not be enumerated to
the reason.
sohncke: ``True`` when the parent has no improper operation (then
an enantiomorphic partner type is not a match).
fingerprint: Hash of the sources the table was built with; a
cached table with another fingerprint is rebuilt.
cache_path: The cache file read or written, or ``None``.
from_cache: ``True`` when the table was read from ``cache_path``.
"""
space_group: str
number: int
version: str
kpoints: dict
irreps: list
strata: list
errors: dict
sohncke: bool = False
fingerprint: str = ""
cache_path: str | None = None
from_cache: bool = False
[docs]
def select(self, numbers=None, size=None, index=None, kpoints=None) -> list:
"""The strata passing every given filter.
Args:
numbers: Subgroup numbers to keep (any iterable), or ``None``.
size: Cell size to keep, or ``None``.
index: Index to keep, or ``None``.
kpoints: k-point names to keep, or ``None``.
Returns:
The matching :class:`IsotropyStratum` records, in table order.
"""
numbers = None if numbers is None else set(int(n) for n in numbers)
knames = None if kpoints is None else set(kpoints)
return [
s for s in self.strata
if (numbers is None or s.number in numbers)
and (size is None or s.size == size)
and (index is None or s.index == index)
and (knames is None or s.kname in knames)
]
[docs]
def to_dict(self) -> dict:
"""The JSON form written to the cache file."""
def array(value, digits):
if value is None:
return None
return (np.round(np.asarray(value, dtype=float), digits) + 0.0).tolist()
return {
"format": _FORMAT,
"crystod_version": self.version,
"fingerprint": self.fingerprint,
"sohncke": self.sohncke,
"space_group": self.space_group,
"number": self.number,
"kpoints": self.kpoints,
"irreps": [list(entry) for entry in self.irreps],
"errors": self.errors,
"strata": [
{
"label": s.label, "kname": s.kname, "dimension": s.dimension,
"direction": s.direction, "n_free": s.n_free,
"number": s.number, "symbol": s.symbol,
"size": s.size, "index": s.index,
"basis": array(s.basis, 6), "origin": array(s.origin, 6),
"vector": array(s.vector, 10),
"projector": array(s.projector, 10),
}
for s in self.strata
],
}
[docs]
@classmethod
def from_dict(cls, data: dict) -> IsotropyTable:
"""Inverse of :meth:`to_dict`.
Raises:
ValueError: The data is not a table of the current format or was
built from other sources.
"""
if data.get("format") != _FORMAT:
raise ValueError("unknown isotropy-table format")
if data.get("fingerprint") != _fingerprint():
raise ValueError("isotropy table built from other sources")
def array(value):
return None if value is None else np.array(value, dtype=float)
strata = [
IsotropyStratum(
label=row["label"], kname=row["kname"], dimension=int(row["dimension"]),
direction=row["direction"], n_free=int(row["n_free"]),
number=int(row["number"]), symbol=row["symbol"],
size=int(row["size"]), index=int(row["index"]),
basis=array(row["basis"]), origin=array(row["origin"]),
vector=array(row["vector"]), projector=array(row["projector"]),
)
for row in data["strata"]
]
return cls(
space_group=data["space_group"], number=int(data["number"]),
version=data["crystod_version"], kpoints=data["kpoints"],
irreps=[tuple(entry) for entry in data["irreps"]],
strata=strata, errors=dict(data["errors"]),
sohncke=bool(data["sohncke"]), fingerprint=data["fingerprint"],
)
# ---------------------------------------------------------------- building
def cache_directory() -> str:
"""The directory of the isotropy-table cache files.
Returns:
``$CRYSTOD_CACHE_DIR/isotropy`` when the variable is set, otherwise
``~/.cache/crystod/isotropy``.
"""
root = os.environ.get(CACHE_ENV) or os.path.join(
os.path.expanduser("~"), ".cache", "crystod"
)
return os.path.join(root, "isotropy")
def cache_path(number: int) -> str:
"""The cache file of one parent space group (by number)."""
from . import __version__
return os.path.join(cache_directory(), f"{int(number)}_{__version__}.json.gz")
_FINGERPRINT: list = []
def _fingerprint() -> str:
"""Short hash of the sources behind the table (computed once).
Keys the cache beyond the version string, so that a change of the
label, setting or enumeration code within one version (an editable
install, an unreleased version) rebuilds the cached tables.
"""
if not _FINGERPRINT:
import hashlib
digest = hashlib.sha1()
directory = os.path.dirname(os.path.abspath(__file__))
for name in _FINGERPRINT_FILES:
digest.update(name.encode())
try:
with open(os.path.join(directory, name), "rb") as handle:
digest.update(handle.read())
except OSError:
digest.update(b"missing")
_FINGERPRINT.append(digest.hexdigest()[:16])
return _FINGERPRINT[0]
def is_sohncke(parent) -> bool:
"""``True`` when the space group has no improper operation.
In such a (Sohncke) parent the two members of an enantiomorphic pair of
subgroup types are not conjugate and come from different strata.
"""
return str(_resolve(parent).pointgroup_international) in _SOHNCKE_POINT_GROUPS
def _resolve(space_group):
"""spglib type info of a space group given by symbol or number."""
from .spacegroup_product import _resolve_space_group
if isinstance(space_group, (int, np.integer)):
space_group = str(int(space_group))
return _resolve_space_group(str(space_group))
def _progress_to_stderr(message: str) -> None:
print(message, file=sys.stderr, flush=True)
def build_isotropy_table(parent, progress=_progress_to_stderr) -> IsotropyTable:
"""Enumerate every stratum of every special-point irrep (no cache).
Args:
parent: Symbol or number of the parent space group.
progress: Called with one line per k point before it is enumerated
(``"building the isotropy table of Fm-3m: W (4 of 4) ..."``);
``None`` for silence.
Returns:
The :class:`IsotropyTable` (``cache_path`` unset).
Raises:
SystemExit: Unknown space group.
"""
from . import __version__
from .isotropy_subgroup import _direction_records, kpoint_irrep_tables
from .spacegroup_product import DEN, SpaceGroupIrrepAlgebra
algebra = SpaceGroupIrrepAlgebra(str(parent))
symbol = str(algebra.sg_type.international_short)
knames = list(algebra.k_by_kname) # the tabulated special points only
kpoints: dict = {}
irreps: list = []
strata: list = []
errors: dict = {}
first_kname: dict = {} # irrep label -> the k point it is listed at
for position, kname in enumerate(knames, start=1):
if progress is not None:
progress(f"building the isotropy table of {symbol}: {kname} "
f"({position} of {len(knames)}) ...")
arms, _ = algebra.star(kname)
kpoints[kname] = {
"coordinates": [int(v) / DEN for v in algebra.k_by_kname[kname]],
"arms": [[int(v) / DEN for v in arm] for arm in arms],
"n_arms": len(arms),
"listed_at": [],
}
def rows_of(analyzer, kname=kname):
representation = analyzer.representation
label = representation.label
rows = []
for index, n_free, full_label, info, size, extra in _direction_records(analyzer):
_, _, _, B, rotations, translations, lattice = extra["subgroup"]
try:
setting = analyzer.conventional_setting(
B, rotations, translations, lattice, info
)
except Exception:
setting = None
basis, origin = (
(setting[0] + 0.0, setting[1] + 0.0) if setting is not None
else (None, None)
)
rows.append(IsotropyStratum(
label=label, kname=kname, dimension=int(representation.dimension),
direction=full_label[len(label):], n_free=int(n_free),
number=int(info.number), symbol=str(info.international_short),
size=int(size), index=int(index), basis=basis, origin=origin,
vector=np.asarray(extra["generic"], dtype=float),
projector=np.real(np.asarray(extra["projector"])),
))
return int(representation.dimension), rows
tables, failed = kpoint_irrep_tables(algebra, kname, rows_of)
listed_at = kpoints[kname]["listed_at"]
for label, (dimension, rows) in tables.items():
# a pair spanning the k and the -k star (H1HA1 at H and at HA)
# is one order parameter: keep it at the first star only
home = first_kname.setdefault(label, kname)
if home not in listed_at:
listed_at.append(home)
if home != kname:
continue
irreps.append((label, kname, dimension))
strata.extend(rows)
for label, reason in failed.items():
home = first_kname.setdefault(label, kname)
if home not in listed_at:
listed_at.append(home)
errors.setdefault(label, reason)
if not listed_at:
listed_at.append(kname)
return IsotropyTable(
space_group=symbol, number=int(algebra.sg_type.number), version=__version__,
kpoints=kpoints, irreps=irreps, strata=strata, errors=errors,
sohncke=str(algebra.sg_type.pointgroup_international) in _SOHNCKE_POINT_GROUPS,
fingerprint=_fingerprint(),
)
def _read_cache(path: str) -> IsotropyTable | None:
try:
with gzip.open(path, "rt", encoding="utf-8") as handle:
table = IsotropyTable.from_dict(json.load(handle))
except (OSError, ValueError, KeyError, TypeError, EOFError):
return None # missing or unreadable: rebuild
table.cache_path = path
table.from_cache = True
return table
def _write_cache(table: IsotropyTable, path: str) -> bool:
directory = os.path.dirname(path)
temporary = f"{path}.{os.getpid()}.tmp"
try:
os.makedirs(directory, exist_ok=True)
with gzip.open(temporary, "wt", encoding="utf-8") as handle:
json.dump(table.to_dict(), handle, separators=(",", ":"))
os.replace(temporary, path)
except OSError as exc:
try:
os.remove(temporary)
except OSError:
pass
print(f"WARNING: the isotropy table could not be cached at {path} ({exc}).",
file=sys.stderr)
return False
return True
def _isotropy_table(parent, *, use_cache=True, write_cache=True,
progress=_progress_to_stderr) -> IsotropyTable:
info = _resolve(parent)
path = cache_path(info.number)
if use_cache:
table = _read_cache(path)
if table is not None:
return table
table = build_isotropy_table(str(info.number), progress=progress)
if write_cache and _write_cache(table, path):
table.cache_path = path
return table
[docs]
def isotropy_table(parent, *, use_cache: bool = True, write_cache: bool = True,
progress: bool = True) -> IsotropyTable:
"""The isotropy table of a parent space group, cached on disk.
Every stratum of every irrep at every special k point of the ISO-IR
tables, as ``crystod-group --parent SG --kpoint K`` lists them for all
K, with the conventional settings of the subgroups. The first call for
a parent builds the table (seconds for most groups, minutes for the
large stars of the face-centred cubic groups) and writes it to
:func:`cache_path`; later calls read the file.
Args:
parent: Symbol (``"Pm-3m"``) or number (``221``) of the parent.
use_cache: Read the cache file when it exists (``False`` rebuilds
the table; the file is still written).
write_cache: Write the table to the cache file after building it.
progress: Print one line per k point to stderr while building.
Returns:
An :class:`IsotropyTable`.
Raises:
ValueError: Unknown space group.
Example:
>>> from crystod import group
>>> table = group.isotropy_table("Pm-3m")
>>> [(s.label, s.direction, s.symbol) for s in table.select([167], size=2)]
[('R4+', '(a,a,a)', 'R-3c'), ('R5-', '(a,a,a)', 'R-3c')]
"""
try:
return _isotropy_table(
parent, use_cache=use_cache, write_cache=write_cache,
progress=_progress_to_stderr if progress else None,
)
except SystemExit as exc:
message = " ".join(str(exc).split())
raise ValueError(message.removeprefix("ERROR: ") or "invalid input") from None
# ---------------------------------------------------------------- lookup
def resolve_child(child):
"""Number and symbol of the subgroup type given by symbol or number.
Raises:
SystemExit: Not a space-group symbol or number.
"""
text = str(child).strip()
if text.isdigit() and not 1 <= int(text) <= 230:
raise SystemExit(f'ERROR: "{child}" is not a space-group number (1-230).')
info = _resolve(text)
return int(info.number), str(info.international_short)
def child_numbers(number: int, include_partner: bool = True) -> list[int]:
"""The subgroup numbers that count as type ``number``.
Args:
number: Space-group number of the subgroup type H.
include_partner: Also count the enantiomorphic partner type of H
(right for a parent with improper operations, wrong for a
Sohncke parent, see :func:`is_sohncke`).
Returns:
``[number]``, followed by the partner number when it is counted.
"""
from .isotropy_subgroup import ENANTIOMORPHIC_PAIRS
partner = ENANTIOMORPHIC_PAIRS.get(int(number)) if include_partner else None
return [int(number)] + ([partner] if partner is not None else [])
def resolve_kpoints(table: IsotropyTable, tokens) -> list[str]:
"""k-point names of the table from ``--kpoint`` values.
Args:
table: The :class:`IsotropyTable`.
tokens: k-point names (case ignored, ``G``/``GAMMA`` for ``GM``),
or three coordinates of one special point in the primitive
basis (any arm, modulo reciprocal lattice vectors).
Returns:
The names under which the selected irreps are listed, in the
order given (the -k star of a pair spanning both stars maps to the
first star).
Raises:
SystemExit: A name or a point that is not a special point of the
table.
"""
from fractions import Fraction
from .isotropy_subgroup import _GAMMA_ALIASES
tokens = [piece for token in tokens for piece in str(token).replace(",", " ").split()]
available = ", ".join(table.kpoints)
numeric = all(token[:1].isdigit() or token[:1] in "+-." for token in tokens)
if numeric and len(tokens) == 3:
try:
k = np.array([float(Fraction(token)) for token in tokens])
except (ValueError, ZeroDivisionError):
raise SystemExit(f"ERROR: invalid k point {' '.join(tokens)}.") from None
for kname, entry in table.kpoints.items():
for arm in entry["arms"]:
d = k - np.asarray(arm)
if np.allclose(d, np.rint(d), atol=5e-4):
return list(entry.get("listed_at") or [kname])
raise SystemExit(
f"ERROR: k = ({', '.join(tokens)}) is not a special k point of "
f"{table.space_group} (No. {table.number}); special points: {available}."
)
by_upper = {kname.upper(): kname for kname in table.kpoints}
names = []
for token in tokens:
requested = token.upper()
if requested not in by_upper and requested in _GAMMA_ALIASES:
requested = "GM"
if requested not in by_upper:
raise SystemExit(
f'ERROR: "{token}" is not a special k point of {table.space_group} '
f"(No. {table.number}); special points: {available}."
)
kname = by_upper[requested]
for name in table.kpoints[kname].get("listed_at") or [kname]:
if name not in names:
names.append(name)
return names
def _match(stratum: IsotropyStratum) -> IsotropyMatch:
return IsotropyMatch(
label=stratum.label, kname=stratum.kname, direction=stratum.direction,
number=stratum.number, symbol=stratum.symbol, size=stratum.size,
index=stratum.index, basis=stratum.basis, origin=stratum.origin,
)
[docs]
def find_isotropy_irreps(parent, child, size=None, index=None, kpoints=None,
*, coupled: bool = False, use_cache: bool = True) -> list:
"""Irreps and directions whose isotropy subgroup is of a given type.
The reverse lookup of ``crystod-group --parent G --child H``: every
stratum of every special-point irrep of G whose isotropy subgroup is of
type H, read from the cached :func:`isotropy_table`. When G has an
improper operation, a stratum listed with the enantiomorphic partner
type of H is a match too (an improper operation of G maps its order
parameter to one of the same stratum with a stabilizer of type H); in a
Sohncke parent the two types are different strata and only H counts.
Args:
parent: Symbol or number of the parent space group G.
child: Symbol (``"I4/mcm"``) or number (``140``) of the subgroup
type H.
size: Keep only this primitive-cell multiplication.
index: Keep only this index [G:H].
kpoints: Keep only these special k points (names, or one point as
three coordinates).
coupled: Also search the pairs of irreps (``--coupled``) and append
the :class:`CoupledIsotropyMatch` records of
:func:`find_coupled_isotropy_irreps` after the single-irrep ones.
use_cache: Read the cached table when it exists.
Returns:
A list of :class:`IsotropyMatch`, in table order (k point, irrep,
then the order of the ``--parent`` table); several rows of one type
are distinct embeddings (conventional basis and origin). Empty when
no single irrep gives type H: the subgroup may need coupled irreps
(``coupled=True``).
Raises:
ValueError: Unknown parent or child, or a k point that is not a
special point of the parent.
Example:
>>> from crystod import group
>>> for match in group.find_isotropy_irreps("Pm-3m", "R-3c", size=2):
... print(match)
R4+(a,a,a) (R) -> R-3c (No. 167), size 2, index 8
R5-(a,a,a) (R) -> R-3c (No. 167), size 2, index 8
"""
try:
number, _ = resolve_child(child)
table = _isotropy_table(parent, use_cache=use_cache, progress=None)
knames = None if kpoints is None else resolve_kpoints(
table, [kpoints] if isinstance(kpoints, str) else kpoints
)
except SystemExit as exc:
message = " ".join(str(exc).split())
raise ValueError(message.removeprefix("ERROR: ") or "invalid input") from None
matches = [
_match(s)
for s in table.select(child_numbers(number, not table.sohncke),
size=size, index=index, kpoints=knames)
]
if coupled:
matches += coupled_search(table, number, size=size, index=index,
knames=knames).matches
return matches
# ---------------------------------------------------------------- coupled lookup
# order of every crystallographic point group (spglib's international symbols)
_POINT_GROUP_ORDER = {
"1": 1, "-1": 2, "2": 2, "m": 2, "2/m": 4, "222": 4, "mm2": 4, "mmm": 8,
"4": 4, "-4": 4, "4/m": 8, "422": 8, "4mm": 8, "-42m": 8, "-4m2": 8,
"4/mmm": 16, "3": 3, "-3": 6, "32": 6, "3m": 6, "-3m": 12, "6": 6, "-6": 6,
"6/m": 12, "622": 12, "6mm": 12, "-6m2": 12, "-62m": 12, "6/mmm": 24,
"23": 12, "m-3": 24, "432": 24, "-43m": 24, "m-3m": 48,
}
_PG_ORDER_BY_NUMBER: dict = {}
def point_group_order(number: int) -> int:
"""Order of the point group of the space-group type ``number``."""
if not _PG_ORDER_BY_NUMBER:
import spglib
from .runtime_compat import get_spacegroup_type
for hall_number in range(1, 531):
info = get_spacegroup_type(spglib.get_spacegroup_type(hall_number))
_PG_ORDER_BY_NUMBER.setdefault(
int(info.number), _POINT_GROUP_ORDER[str(info.pointgroup_international)]
)
return _PG_ORDER_BY_NUMBER[int(number)]
[docs]
@dataclass(frozen=True)
class CoupledIsotropyMatch:
"""One answer of the coupled reverse lookup: two irreps giving type H.
A coupled stratum of the direct sum of two irreps (both amplitudes
nonzero) whose isotropy subgroup has type H, where neither irrep alone
(with the other one as a secondary order parameter) has that isotropy
subgroup.
Attributes:
label1: ISO-IR label of the first irrep (table order), e.g. ``"R4+"``.
kname1: Its special k point.
direction1: Its part of the direction, e.g. ``"(0,a,a)"``.
label2: Label of the second irrep, e.g. ``"M3+"``.
kname2: Its special k point.
direction2: Its part of the direction, e.g. ``"(d;0;0)"`` (the
letters continue after those of the first irrep, as in
``crystod-group --parent SG --irrep IR1 IR2``).
number: Space-group number of the isotropy subgroup (H, or its
enantiomorphic partner).
symbol: Its international short symbol.
size: Primitive-cell multiplication relative to the parent.
index: Index of the subgroup in the parent.
basis: Conventional basis of the subgroup (rows, parent conventional
units), or ``None``.
origin: Origin of the subgroup cell (parent conventional
coordinates), or ``None``.
vector: A generic order-parameter vector of the stratum (the first
irrep's components, then the second's).
projector: The orthogonal projector onto the stratum subspace in
the direct sum.
"""
label1: str
kname1: str
direction1: str
label2: str
kname2: str
direction2: str
number: int
symbol: str
size: int
index: int
basis: np.ndarray | None = field(default=None, compare=False)
origin: np.ndarray | None = field(default=None, compare=False)
vector: np.ndarray | None = field(default=None, compare=False)
projector: np.ndarray | None = field(default=None, compare=False)
@property
def direction(self) -> str:
"""The coupled direction, e.g. ``"R4+(0,a,a) M3+(d;0;0)"``."""
return f"{self.label1}{self.direction1} {self.label2}{self.direction2}"
@property
def same_k(self) -> bool:
"""``True`` when both irreps belong to the same special k point."""
return self.kname1 == self.kname2
def __str__(self) -> str:
return (
f"{self.direction} -> {self.symbol} (No. {self.number}), "
f"size {self.size}, index {self.index}"
)
@dataclass
class CoupledSearch:
"""The result of a coupled reverse lookup with its search statistics.
Attributes:
matches: The :class:`CoupledIsotropyMatch` records, sorted by index,
then size, then the order of the irrep pairs.
n_irreps: Number of irreps that passed the point-group filter.
n_pairs_same_k: Number of irrep pairs searched at the same k point.
n_pairs_cross_k: Number of irrep pairs searched at different k points.
errors: Maps an irrep pair (``"X1 + X2"``) that could not be
analyzed to the reason.
data: Per match (same order), the objects behind it: the
``algebra``, the coupled ``representation``, the stabilizer
``members`` and the sublattice basis ``B`` (for the secondary
order parameters).
"""
matches: list
n_irreps: int = 0
n_pairs_same_k: int = 0
n_pairs_cross_k: int = 0
errors: dict = field(default_factory=dict)
data: list = field(default_factory=list, repr=False)
def _fixing_mask(blocks: np.ndarray, basis: np.ndarray) -> np.ndarray:
"""Mask of the matrices of ``blocks`` (``(G, n, n)``) fixing every
column of ``basis`` (tolerance 1e-6, as ``_RepCache.fixes``)."""
D = np.matmul(blocks, basis) - basis[None]
return np.max(np.abs(D), axis=(1, 2)) < 1e-6
def _orbit(cache, projector: np.ndarray) -> dict:
"""``_RepCache.orbit`` with the keys of all images rounded at once (the
same keys as ``_projector_key``)."""
images = np.matmul(np.matmul(cache.Ed, projector), cache.Ed.transpose(0, 2, 1))
rounded = np.round(images, 6) + 0.0
orbit: dict = {}
for image, key_array in zip(images, rounded):
orbit.setdefault(key_array.tobytes(), image)
return orbit
_OWN_MASKS: dict = {}
def _stratum_masks(representation, strata, with_orbit: bool) -> np.ndarray:
"""Distinct stabilizer masks, over the elements of ``representation``
itself, of the given strata (``with_orbit``: of every orbit image).
Kept per representation and stratum list: every pair that contains the
irrep needs them.
"""
from .isotropy_subgroup import _orth_basis, _rep_cache
cache = _rep_cache(representation)
key = (id(cache), tuple(id(s) for s in strata), with_orbit)
entry = _OWN_MASKS.get(key)
if entry is not None and entry[0] is cache:
return entry[1]
bases = []
for stratum in strata:
if with_orbit:
bases.extend(_orth_basis(image)
for image in _orbit(cache, stratum.projector).values())
else:
bases.append(_orth_basis(stratum.projector))
masks: dict = {}
by_rank: dict = {}
for basis in bases:
by_rank.setdefault(basis.shape[1], []).append(basis)
for group in by_rank.values():
for start in range(0, len(group), 32):
B = np.array(group[start:start + 32]) # (m, n, r)
D = np.matmul(cache.E[None], B[:, None]) - B[:, None]
for mask in np.max(np.abs(D), axis=(2, 3)) < 1e-6:
masks.setdefault(np.packbits(mask).tobytes(), mask)
result = np.array(list(masks.values())) if masks else np.zeros((0, len(cache.E)), bool)
if len(_OWN_MASKS) > 512:
_OWN_MASKS.clear()
_OWN_MASKS[key] = (cache, result)
return result
def _element_map(representation, coupled) -> np.ndarray:
"""For every element of ``coupled``, the index of the element of
``representation`` (one of its parts) with the same matrix block."""
lookup = {
(int(i), tuple(int(x) for x in t)): g
for g, (i, t, _) in enumerate(representation.elements)
}
grid = int(representation.grid_n)
return np.array([
lookup[(int(i), tuple(int(x) % grid for x in t))] for i, t, _ in coupled.elements
])
def _split_coupled_label(label: str, label1: str, label2: str) -> tuple[str, str]:
"""``"R4+(0,a,a) M3+(d;0;0)"`` -> ``("(0,a,a)", "(d;0;0)")``."""
first, second = label.split(" ", 1)
return first[len(label1):], second[len(label2):]
def coupled_search(table: IsotropyTable, number: int, size=None, index=None,
knames=None, progress=None, keep_data: bool = False) -> CoupledSearch:
"""Search the irrep pairs of a parent for coupled strata of type H.
The engine of ``--child H --coupled`` and of
:func:`find_coupled_isotropy_irreps`. Every isotropy subgroup of the
direct sum ``D1 + D2`` with both parts nonzero is ``S1 & S2'``, with
``S1`` the isotropy subgroup of a single stratum of ``D1`` (a
representative of the table) and ``S2'`` any conjugate of one of
``D2``; its isotropy subspace is ``Fix_1 + Fix_2`` (group-average
projectors). The strata are the parent orbits of these subspaces, with
the representative and the direction label that ``crystod-group
--parent G --irrep D1 D2`` prints.
Args:
table: The :class:`IsotropyTable` of the parent (the single strata
of every irrep are the candidates).
number: Space-group number of the subgroup type H (the
enantiomorphic partner counts in a parent with improper
operations, see :func:`child_numbers`).
size: Keep only this cell size.
index: Keep only this index.
knames: Use only the irreps of these k points (names of the table),
or ``None`` for every k point.
progress: Called with one line per pair of k points once the search
has run for more than three seconds; ``None`` for silence.
keep_data: Keep the representation, the stabilizer and the
sublattice of every match in ``data``.
Returns:
A :class:`CoupledSearch`.
"""
import time
from .isotropy_subgroup import _failure_reason, _label_rank, kpoint_irrep_tables
from .spacegroup_product import SpaceGroupIrrepAlgebra
start = time.time()
numbers = set(child_numbers(number, not table.sohncke))
target = point_group_order(number)
def candidate(stratum) -> bool:
return (point_group_order(stratum.number) % target == 0
and (size is None or size % stratum.size == 0)
and (index is None or index % stratum.index == 0))
strata_by_label: dict = {}
for stratum in table.strata:
if candidate(stratum):
strata_by_label.setdefault(stratum.label, []).append(stratum)
allowed = None if knames is None else set(knames)
irreps = [
(label, kname) for label, kname, _ in table.irreps
if label in strata_by_label and (allowed is None or kname in allowed)
]
result = CoupledSearch(matches=[], n_irreps=len(irreps))
if len(irreps) < 2:
return result
knames_order = list(dict.fromkeys(kname for _, kname in irreps))
groups = [(k, k) for k in knames_order] + [
(k1, k2) for i, k1 in enumerate(knames_order) for k2 in knames_order[i + 1:]
]
algebra = SpaceGroupIrrepAlgebra(str(table.number))
identity = algebra._rotation_index[algebra._key(np.eye(3))]
representations: dict = {}
def representation_of(label: str, kname: str):
if kname not in representations:
tables, _ = kpoint_irrep_tables(
algebra, kname, lambda analyzer: analyzer.representation
)
representations[kname] = tables
return representations[kname].get(label)
found = []
position = 0
for group_number, (k1, k2) in enumerate(groups, start=1):
if progress is not None and time.time() - start > 3.0:
progress(f"searching the coupled irrep pairs of {table.space_group}: "
f"{k1} + {k2} ({group_number} of {len(groups)}) ...")
labels1 = [label for label, kname in irreps if kname == k1]
labels2 = [label for label, kname in irreps if kname == k2]
if k1 == k2:
pairs = [(a, b) for i, a in enumerate(labels1) for b in labels1[i + 1:]]
result.n_pairs_same_k += len(pairs)
else:
pairs = [(a, b) for a in labels1 for b in labels2]
result.n_pairs_cross_k += len(pairs)
for label1, label2 in pairs:
position += 1
try:
rep1 = representation_of(label1, k1)
rep2 = representation_of(label2, k2)
if rep1 is None or rep2 is None:
raise RuntimeError("representation not available")
for match, extra in _coupled_pair(
algebra, identity, rep1, rep2, k1, k2,
strata_by_label[label1], strata_by_label[label2],
numbers, target, size, index, keep_data,
):
found.append((match.index, match.size, position,
_label_rank(match.direction), match, extra))
except (SystemExit, Exception) as exc: # noqa: BLE001 - reported
result.errors[f"{label1} + {label2}"] = _failure_reason(exc)
found.sort(key=lambda item: item[:4])
result.matches = [item[4] for item in found]
result.data = [item[5] for item in found] if keep_data else []
return result
def _coupled_pair(algebra, identity, rep1, rep2, k1, k2, strata1, strata2, numbers,
target, size, index, keep_data):
"""The coupled strata of type H of one irrep pair (generator of
``(CoupledIsotropyMatch, data)``)."""
from .isotropy_subgroup import (
CoupledRepresentation,
IsotropyAnalyzer,
_label_rank,
_orth_basis,
_projector_key,
_rep_cache,
)
coupled = CoupledRepresentation.from_parts(algebra, [rep1, rep2])
cache = _rep_cache(coupled)
n1 = rep1.dimension
E1 = cache.E[:, :n1, :n1]
E2 = cache.E[:, n1:, n1:]
own1 = _stratum_masks(rep1, strata1, with_orbit=False)
own2 = _stratum_masks(rep2, strata2, with_orbit=True)
if not len(own1) or not len(own2):
return
masks1 = own1[:, _element_map(rep1, coupled)]
masks2 = own2[:, _element_map(rep2, coupled)]
elements = coupled.elements
grid_volume = int(coupled.grid_n) ** 3
pure = np.array([i == identity for i, _, _ in elements])
rotation_index = np.array([i for i, _, _ in elements])
one_hot = np.zeros((len(elements), algebra.n_ops), dtype=np.float32)
one_hot[np.arange(len(elements)), rotation_index] = 1.0
# the isotropy subgroup of Fix(h) contains h: an h with more rotations
# than H (or a smaller cell than --size) cannot give H
intersections: dict = {}
for mask1 in masks1:
H = masks2 & mask1[None, :]
n_rot = np.count_nonzero(H.astype(np.float32) @ one_hot, axis=1)
keep = n_rot <= target
if size is not None:
keep &= np.count_nonzero(H & pure[None, :], axis=1) <= grid_volume // size
for h, packed in zip(H[keep], np.packbits(H[keep], axis=1)):
intersections.setdefault(packed.tobytes(), h)
used: set = set()
analyzer = None
for h in intersections.values():
basis1 = _orth_basis(E1[h].mean(axis=0))
basis2 = _orth_basis(E2[h].mean(axis=0))
if basis1.shape[1] == 0 or basis2.shape[1] == 0:
continue
W = np.zeros((coupled.dimension, basis1.shape[1] + basis2.shape[1]))
W[:n1, :basis1.shape[1]] = basis1
W[n1:, basis1.shape[1]:] = basis2
projector = W @ W.T
key = _projector_key(projector)
if key in used:
continue
# every test below is a property of the conjugacy class, so a
# rejected subspace needs no orbit
full = _fixing_mask(cache.E, W)
# one irrep alone already has this isotropy subgroup (the other one
# is a secondary order parameter of it): not a coupled answer
count = int(full.sum())
if (int(_fixing_mask(E1, basis1).sum()) == count
or int(_fixing_mask(E2, basis2).sum()) == count):
continue
# cheap type filters before the spglib identification
n_point = len(set(rotation_index[full].tolist()))
if n_point != target:
continue
n_pure = int(np.sum(full & pure))
cell = grid_volume // max(n_pure, 1)
if size is not None and cell != size:
continue
if index is not None and algebra.n_ops * cell // n_point != index:
continue
orbit = _orbit(cache, projector)
used.update(orbit)
if analyzer is None:
analyzer = IsotropyAnalyzer.from_representation(algebra, coupled)
# the type is a property of the class: identify it before choosing
# the representative (the label search over the orbit is the
# expensive part)
info = analyzer.subgroup_of(
[(elements[g][0], elements[g][1]) for g in np.nonzero(full)[0]]
)[0]
if int(info.number) not in numbers:
continue
best = min(orbit.values(),
key=lambda Q: _label_rank(analyzer._direction_pattern(Q)[0]))
label, generic = analyzer.direction_label(best)
members = [
(elements[g][0], elements[g][1])
for g in np.nonzero(cache.vector_stabilizer_mask(generic))[0]
]
info, cell_size, subgroup_index, B, rotations, translations, lattice = (
analyzer.subgroup_of(members)
)
if int(info.number) not in numbers:
continue
if size is not None and cell_size != size:
continue
if index is not None and subgroup_index != index:
continue
try:
setting = analyzer.conventional_setting(
B, rotations, translations, lattice, info
)
except Exception: # noqa: BLE001 - the setting is optional
setting = None
direction1, direction2 = _split_coupled_label(label, rep1.label, rep2.label)
match = CoupledIsotropyMatch(
label1=rep1.label, kname1=k1, direction1=direction1,
label2=rep2.label, kname2=k2, direction2=direction2,
number=int(info.number), symbol=str(info.international_short),
size=int(cell_size), index=int(subgroup_index),
basis=None if setting is None else setting[0] + 0.0,
origin=None if setting is None else setting[1] + 0.0,
vector=np.asarray(generic, dtype=float), projector=np.real(best),
)
extra = ({"algebra": algebra, "representation": coupled,
"members": members, "B": B} if keep_data else None)
yield match, extra
[docs]
def find_coupled_isotropy_irreps(parent, child, size=None, index=None, kpoints=None,
*, use_cache: bool = True) -> list:
"""Irrep pairs and directions whose coupled isotropy subgroup has type H.
The coupled reverse lookup of ``crystod-group --parent G --child H
--coupled``: every stratum of the direct sum of two special-point
irreps of G, with both amplitudes nonzero, whose isotropy subgroup has
type H while neither irrep alone has it. The pairs are searched at the
same k point first, then at different k points; the single strata of
the cached :func:`isotropy_table` are the candidates.
Args:
parent: Symbol or number of the parent space group G.
child: Symbol or number of the subgroup type H.
size: Keep only this primitive-cell multiplication.
index: Keep only this index [G:H].
kpoints: Use only the irreps of these special k points.
use_cache: Read the cached table when it exists.
Returns:
A list of :class:`CoupledIsotropyMatch`, sorted by index, then by
size, then in the order of the irrep pairs.
Raises:
ValueError: Unknown parent or child, or a k point that is not a
special point of the parent.
Example:
>>> from crystod import group
>>> for match in group.find_coupled_isotropy_irreps("Pm-3m", "Pnma", size=4):
... print(match)
R4+(0,a,a) M3+(d;0;0) -> Pnma (No. 62), size 4, index 24
"""
try:
number, _ = resolve_child(child)
table = _isotropy_table(parent, use_cache=use_cache, progress=None)
knames = None if kpoints is None else resolve_kpoints(
table, [kpoints] if isinstance(kpoints, str) else kpoints
)
except SystemExit as exc:
message = " ".join(str(exc).split())
raise ValueError(message.removeprefix("ERROR: ") or "invalid input") from None
return coupled_search(table, number, size=size, index=index, knames=knames).matches
# ---------------------------------------------------------------- report
def _setting_text(values) -> str:
from .isotropy_subgroup import _format_setting_value
if values is None:
return "-"
array = np.asarray(values, dtype=float)
if array.ndim == 1:
return "(" + ",".join(_format_setting_value(x) for x in array) + ")"
return ",".join(_setting_text(row) for row in array)
def _origin_text(values) -> str:
"""The origin reduced into [0,1) modulo parent lattice translations.
Integer conventional translations are lattice translations of every
parent, so the reduced origin gives a G-conjugate member of the same
stratum and makes rows comparable by eye.
"""
if values is None:
return "-"
reduced = np.mod(np.round(np.asarray(values, dtype=float), 6), 1.0)
reduced[np.isclose(reduced, 1.0, atol=1e-6)] = 0.0
return _setting_text(reduced + 0.0)
def _home_relative(path: str) -> str:
home = os.path.expanduser("~")
if path == home or path.startswith(home + os.sep):
return "~" + path[len(home):]
return path
def _filter_text(size, index, knames) -> str:
parts = []
if size is not None:
parts.append(f"size {size}")
if index is not None:
parts.append(f"index {index}")
if knames:
parts.append(("k point " if len(knames) == 1 else "k points ") + ", ".join(knames))
return ", ".join(parts)
def _table_lines(header: list, cells: list) -> list:
"""Left-aligned columns separated by two spaces (header first)."""
widths = [max(len(header[c]), *(len(row[c]) for row in cells))
for c in range(len(header))]
return [" ".join(text.ljust(width) for text, width in zip(row, widths)).rstrip()
for row in [header] + cells]
def _partner_note(number: int, symbol: str, partner_rows: list, listed: str) -> list:
import textwrap
from .isotropy_subgroup import ENANTIOMORPHIC_PAIRS
partner = ENANTIOMORPHIC_PAIRS.get(number)
partner_symbol = partner_rows[0].symbol
return [line.replace("\u00a0", " ") for line in textwrap.wrap(
f"note: {number} <-> {partner} ({symbol} <-> {partner_symbol}) are "
"enantiomorphic partner types: an improper operation of the parent maps "
"the order parameter of such a stratum to another one of the same "
f"stratum whose stabilizer is the partner. The rows {listed} are listed with a "
f"stabilizer of type {partner_symbol} (No.\u00a0{partner}).",
width=78, break_on_hyphens=False,
)]
def format_coupled_block(search: CoupledSearch, number: int, symbol: str,
filters: str = "") -> str:
"""The ``* Coupled isotropy subgroups of type H *`` block as text.
Args:
search: The :class:`CoupledSearch` of :func:`coupled_search`.
number: Number of the subgroup type H.
symbol: Its symbol.
filters: The filter text (``"size 4"``), or ``""``.
Returns:
The block (no leading or trailing blank line).
"""
n_pairs = search.n_pairs_same_k + search.n_pairs_cross_k
lines = [
f"* Coupled isotropy subgroups of type {symbol} *",
f"{search.n_irreps} irreps pass the point-group filter; {n_pairs} pairs searched",
f"({search.n_pairs_same_k} at the same k point, "
f"{search.n_pairs_cross_k} at different k points)",
]
if not search.matches:
where = f" with {filters}" if filters else ""
lines.append(f"no coupled stratum of type {symbol} (No. {number}){where}")
else:
header = ["irrep1", "dir1", "irrep2", "dir2", "size", "index",
"conventional basis", "origin"]
cells = [
[m.label1, m.direction1, m.label2, m.direction2, str(m.size), str(m.index),
_setting_text(m.basis), _origin_text(m.origin)]
for m in search.matches
]
lines.extend(_table_lines(header, cells))
lines.append("every row needs both irreps: neither irrep alone has this "
"isotropy subgroup")
partner_rows = [m for m in search.matches if m.number != number]
if partner_rows:
listed = ", ".join(m.direction.replace(" ", "\u00a0") for m in partner_rows)
lines.append("")
lines.extend(_partner_note(number, symbol, partner_rows, listed))
for pair, reason in search.errors.items():
lines.append(f"note: {pair}: not analyzed ({reason})")
return "\n".join(lines)
def format_child_report(table: IsotropyTable, number: int, symbol: str,
size=None, index=None, knames=None, coupled=None,
secondary=None) -> str:
"""The ``crystod-group --parent G --child H`` report as text.
Args:
table: The :class:`IsotropyTable` of the parent.
number: Number of the subgroup type H.
symbol: Its symbol.
size: The ``--size`` filter, or ``None``.
index: The ``--index`` filter, or ``None``.
knames: The resolved ``--kpoint`` names, or ``None``.
coupled: The :class:`CoupledSearch` of ``--coupled``, or ``None``.
secondary: Text blocks of ``--secondary`` (one per coupled match),
or ``None``.
Returns:
The report, ``* ... *`` blocks separated by blank lines.
"""
numbers = child_numbers(number, not table.sohncke)
rows = table.select(numbers, size=size, index=index, kpoints=knames)
lines = ["", "* Supergroup *", f"{table.space_group} (No. {table.number})",
"", "* Subgroup *", f"{symbol} (No. {number})", "",
"* Isotropy table *"]
knames_all = ", ".join(table.kpoints)
lines.append(f"{len(table.irreps)} irreps at the special k points {knames_all}; "
f"{len(table.strata)} strata")
if table.cache_path is not None:
state = "read" if table.from_cache else "written"
lines.append(f"cache: {_home_relative(table.cache_path)} ({state})")
filters = _filter_text(size, index, knames)
if filters:
lines.append(f"selected: {filters}")
lines.append("")
lines.append(f"* Isotropy subgroups of type {symbol} *")
if not rows:
where = f" with {filters}" if filters else ""
lines.append(f"no single-irrep stratum of type {symbol} (No. {number}){where};")
if coupled is None:
lines.append("the subgroup may need two coupled irreps (--coupled)")
else:
lines.append("the subgroup may need two coupled irreps (see below)")
else:
header = ["irrep", "k", "direction", "size", "index", "conventional basis", "origin"]
cells = [
[s.label, s.kname, s.direction, str(s.size), str(s.index),
_setting_text(s.basis), _origin_text(s.origin)]
for s in rows
]
lines.extend(_table_lines(header, cells))
partner_rows = [s for s in rows if s.number != number]
if partner_rows:
listed = ", ".join(f"{s.label}{s.direction}\u00a0at\u00a0{s.kname}"
for s in partner_rows)
lines.append("")
lines.extend(_partner_note(number, symbol, partner_rows, listed))
if coupled is not None:
lines.append("")
lines.append(format_coupled_block(coupled, number, symbol, filters))
for block in secondary or []:
lines.append("")
lines.append(block)
if table.errors:
lines.append("")
for label, reason in table.errors.items():
lines.append(f"note: {label}: not enumerated ({reason})")
lines.append("")
lines.append("Conventions and validation: ISOSUBGROUP (https://iso.byu.edu):")
lines.append('H. T. Stokes, S. van Orden and B. J. Campbell, "Tool for Generating')
lines.append('Isotropy Subgroups of Crystallographic Space Groups",')
lines.append("J. Appl. Cryst. 49, 1849-1853 (2016).")
return "\n".join(lines)
def _secondary_blocks(search: CoupledSearch, max_degree: int) -> list:
"""The ``--secondary`` block of every coupled match."""
import warnings
from .secondary_order_parameter import analyze_secondary, format_secondary
blocks = []
for match, data in zip(search.matches, search.data):
header = (f"H = {match.symbol} ({match.number}), index {match.index}: "
f"{match.direction}")
try:
with warnings.catch_warnings(record=True) as caught:
warnings.simplefilter("always", UserWarning)
result = analyze_secondary(
data["algebra"], data["representation"], data["members"],
data["B"], max_degree,
)
block = format_secondary(result, header, max_degree)
for warning in caught:
block += f"\nWARNING: {warning.message}"
except (ValueError, RuntimeError) as exc:
block = (f"* Secondary order parameters *\n{header}\n"
f"not analyzed ({exc})")
blocks.append(block)
return blocks
def main(argv: list[str] | None = None) -> None:
"""``crystod-group --parent G --child H`` (dispatched by cli/group.py)."""
import argparse
parser = argparse.ArgumentParser(
description="Reverse lookup: the irreps whose isotropy subgroup has a given type."
)
parser.add_argument("--parent", required=True)
parser.add_argument("--child", required=True)
parser.add_argument("--size", type=int, default=None)
parser.add_argument("--index", type=int, default=None)
parser.add_argument("--kpoint", nargs="+", default=None)
parser.add_argument("--no-cache", dest="no_cache", action="store_true")
parser.add_argument("--coupled", action="store_true")
parser.add_argument("--secondary", action="store_true")
parser.add_argument("--degree", type=int, default=None)
if argv is None:
argv = sys.argv[1:]
args = parser.parse_args(list(argv))
if args.secondary and not args.coupled:
parser.error("--secondary with --child needs --coupled (the secondary order "
"parameters of every coupled answer).")
if args.degree is not None and not args.secondary:
parser.error("--degree is only used with --invariants or --secondary.")
degree = 4 if args.degree is None else args.degree
if args.secondary and not 2 <= degree <= 12:
parser.error("--secondary needs --degree between 2 and 12.")
number, symbol = resolve_child(args.child)
parent_info = _resolve(args.parent)
table = _isotropy_table(str(parent_info.number), use_cache=not args.no_cache)
knames = resolve_kpoints(table, args.kpoint) if args.kpoint else None
coupled = secondary = None
if args.coupled:
coupled = coupled_search(
table, number, size=args.size, index=args.index, knames=knames,
progress=_progress_to_stderr, keep_data=args.secondary,
)
if args.secondary:
secondary = _secondary_blocks(coupled, degree)
print(format_child_report(table, number, symbol, args.size, args.index, knames,
coupled=coupled, secondary=secondary))