"""Invariant polynomials of space-group irreps (crystod-group --invariants).
The Landau free energy of a distortion that transforms as a space-group irrep
D is a polynomial in the order-parameter components that is invariant under
every operation of the parent group, ``f(D(g) Q) = f(Q)``. This module
lists a basis of those invariant polynomials degree by degree, the offline
counterpart of the INVARIANTS program of the ISOTROPY Software Suite
(https://iso.byu.edu; D. M. Hatch and H. T. Stokes, J. Appl. Cryst. 36,
951-952 (2003)).
How it works:
- The representation is given as a list of real orthogonal matrices, one per
element of the finite group ``G / T_N`` (``InducedRepresentation.elements``
for a space-group irrep), together with the dimensions of its blocks
("parts": one part for a single irrep, several for a direct sum).
- For every (multi)degree the invariance condition is linear in the
coefficients of the monomial basis. It is evaluated at random points on
the unit sphere, one generator of the group at a time, and solved as a
nullspace (SVD, threshold relative to the largest singular value); the
symmetric power of D is never built explicitly.
- The dimension found is checked against the Molien series, computed from
the power sums ``tr D(g)^k`` with Newton's identities, averaged over all
elements.
- The basis is brought to reduced row-echelon form in graded lexicographic
monomial order (``Q1^n`` first), the coefficients are rationalized where
possible (fractions, square roots of 2 and 3), and the invariants that are
products of lower-degree invariants are separated from the new ones.
The order-parameter components refer to the real irrep basis of
``InducedRepresentation`` (the basis of the direction patterns printed by
``crystod-group --parent``). ISOTROPY uses a different real basis, related
by an orthogonal transformation, so its polynomials can look different while
spanning the same space; the numbers of invariants agree.
Example:
>>> from crystod import group
>>> basis = group.invariant_polynomials("Pm-3m", ["R4+"], degree=4)
>>> basis.counts
{1: 0, 2: 1, 3: 0, 4: 2}
>>> [term.expression for term in basis.polynomials[2]]
['Q1^2 + Q2^2 + Q3^2']
"""
from __future__ import annotations
import itertools
import math
import re
import warnings
from dataclasses import dataclass, field
from fractions import Fraction
import numpy as np
# warn above this many monomials in one (multi)degree (SVD cost grows as n^3)
MONOMIAL_WARNING = 5000
# refuse above this many: the dense point matrix alone would need gigabytes
MONOMIAL_LIMIT = 20000
# an exact coefficient printed as a 6-decimal float (no exact form found)
_DECIMAL = re.compile(r"-?\d+\.\d+")
INVARIANTS_CITATION = (
"Conventions and validation: ISOTROPY INVARIANTS (https://iso.byu.edu):\n"
"D. M. Hatch and H. T. Stokes, J. Appl. Cryst. 36, 951-952 (2003)."
)
# ------------------------------------------------------------------ data types
@dataclass
class InvariantPolynomial:
"""One invariant polynomial of the canonical basis.
Attributes:
name: ``I<degree>_<n>`` for a new invariant of one irrep,
``I(<multidegree>)_<n>`` for a direct sum (``I(2,0)_1``), or the
product written in the names of lower-degree invariants
(``I2_1^2``).
degree: Total degree.
multidegree: Degree in the variables of every part.
exponents: Monomial exponents, shape ``(n_monomials, n_variables)``,
in graded lexicographic order (``Q1^n`` first).
coefficients: Coefficient of every monomial (floats, full
precision).
exact: The coefficients as rationalized strings (``"3/2"``,
``"sqrt(3)/2"``, ``"-1 + sqrt(3)"``), or a 6-decimal float when
no exact form fits. The decimals are display values: they
occur when the real basis of the irrep (the arbitrary real form
chosen by ``InducedRepresentation``, e.g. at the W points of
Fm-3m) makes the coefficients irrational, so they depend on that
basis and are not exact; ``sympy()`` uses ``coefficients`` for
them.
expression: The polynomial as text, e.g. ``"Q1^2 + Q2^2 + Q3^2"``.
"""
name: str
degree: int
multidegree: tuple
exponents: np.ndarray
coefficients: np.ndarray
exact: list = field(default_factory=list)
expression: str = ""
def sympy(self, variables: list[str]):
"""The polynomial as a sympy expression.
Exact coefficients are used where they exist; a coefficient shown
as a 6-decimal float enters with its full floating-point value.
Args:
variables: Variable names, e.g. ``InvariantBasis.variables``
(names such as ``R4+_1`` are turned into valid symbols by
``sympy.Symbol``).
Returns:
A ``sympy.Expr``.
"""
import sympy
symbols = [sympy.Symbol(name) for name in variables]
total = 0
for row, text, value in zip(self.exponents, self.exact, self.coefficients):
if text == "0":
continue
if _DECIMAL.fullmatch(text):
term = sympy.Float(float(value), 17)
else:
term = sympy.sympify(text.replace("^", "**"))
for symbol, power in zip(symbols, row):
term *= symbol ** int(power)
total += term
return sympy.expand(total)
[docs]
@dataclass
class InvariantBasis:
"""Invariant polynomials of a representation, degree by degree.
Attributes:
variables: Names of the order-parameter components (``Q1``, ...
for one irrep; ``<label>_<n>`` for a direct sum).
parts: Dimension of every block of the representation.
degrees: The total degrees computed (1 .. the requested degree).
counts: Number of linearly independent invariants of every total
degree (the Molien count, equal to the nullspace dimension).
polynomials: For every total degree, the new invariants (not
products of lower-degree ones) as ``InvariantPolynomial``.
products: For every total degree, the independent products of
lower-degree invariants that complete the basis.
labels: Irrep label of every part (empty for a bare matrix group).
arm_chunks: Components per star arm of every part (for the
direction-pattern letters).
multidegree_counts: Molien count of every multidegree.
"""
variables: list
parts: list
degrees: list
counts: dict
polynomials: dict
products: dict
labels: list = field(default_factory=list)
arm_chunks: list = field(default_factory=list)
multidegree_counts: dict = field(default_factory=dict)
[docs]
@dataclass
class LandauLifshitz:
"""Landau and Lifshitz conditions of an irrep.
Attributes:
n_cubic: Number of cubic invariants (Landau condition: zero).
n_lifshitz: Multiplicity of the identity in the antisymmetric square
of D times the polar-vector representation (Lifshitz condition:
zero).
continuous_allowed: ``True`` when both conditions hold, so a
continuous (second-order) transition is allowed by symmetry.
"""
n_cubic: int
n_lifshitz: int
continuous_allowed: bool
[docs]
@dataclass
class CouplingTerm:
"""Lowest-order coupling term of a direct sum of irreps.
A coupling term is an invariant whose multidegree has every entry at
least 1, i.e. one that involves the components of every part.
Attributes:
multidegree: Degree in the variables of every part, e.g.
``(1, 1, 1)`` for a trilinear term.
polynomials: Every invariant of that multidegree (products of
lower-degree invariants first, then the new ones), as
``InvariantPolynomial`` records; their number is the Molien
count of the multidegree.
trilinear: ``True`` when the multidegree is ``(1, 1, ..., 1)``
(for three parts, the hybrid-improper term ``Q1 Q2 P``).
"""
multidegree: tuple
polynomials: list
trilinear: bool = False
# ------------------------------------------------------------- group helpers
def _key(matrix: np.ndarray) -> bytes:
return (np.round(np.asarray(matrix, dtype=float), 5) + 0.0).tobytes()
def _unique_with_counts(matrices) -> list[tuple[np.ndarray, int]]:
unique: dict[bytes, list] = {}
for matrix in matrices:
key = _key(matrix)
if key in unique:
unique[key][1] += 1
else:
unique[key] = [np.asarray(matrix, dtype=float), 1]
return [(m, c) for m, c in unique.values()]
def _generating_subset(candidates, group_keys: set) -> list[np.ndarray]:
"""A subset of ``candidates`` that generates the matrix group whose
elements have the keys ``group_keys`` (greedy closure). Falls back to
all distinct candidates when they do not generate the whole group."""
chosen: list[np.ndarray] = []
n = np.asarray(candidates[0]).shape[0] if candidates else 0
closure = {_key(np.eye(n)): np.eye(n)}
for candidate in candidates:
if len(closure) >= len(group_keys):
break
if _key(candidate) in closure:
continue
chosen.append(np.asarray(candidate, dtype=float))
frontier = list(closure.values())
while frontier:
new = []
for element in frontier:
for generator in chosen:
product = generator @ element
key = _key(product)
if key not in closure:
closure[key] = product
new.append(product)
frontier = new
if len(closure) > 4 * len(group_keys) + 8:
break # not the expected group: keep every candidate
if len(closure) != len(group_keys) or set(closure) != group_keys:
distinct = {}
for candidate in candidates:
distinct.setdefault(_key(candidate), np.asarray(candidate, dtype=float))
return list(distinct.values())
return chosen
# --------------------------------------------------------------- Molien series
def _complete_homogeneous(matrix: np.ndarray, degree: int) -> np.ndarray:
"""h_0..h_degree of the eigenvalues of ``matrix`` (Newton's identities).
The power sums are the traces ``tr M^k``; no eigendecomposition is
needed (LAPACK's eigenvalue solver can fail to converge on the
permutation-like matrices of large induced irreps)."""
p = [float(matrix.shape[0])]
power = np.eye(matrix.shape[0])
for _ in range(degree):
power = power @ matrix
p.append(float(np.trace(power)))
h = [1.0]
for n in range(1, degree + 1):
h.append(sum(p[k] * h[n - k] for k in range(1, n + 1)) / n)
return np.array(h)
def _round_count(value: complex, what: str) -> int:
count = int(round(value.real))
if abs(value - count) > 1e-6:
raise RuntimeError(
f"the Molien average for {what} is not an integer ({value:.8f})."
)
return count
def molien_counts(matrices, parts, degrees) -> dict:
"""Number of linearly independent invariants of given (multi)degrees.
Args:
matrices: The real matrices of every group element (one per element
of the finite group; repeated matrices count with multiplicity).
parts: Block dimensions of the (block-diagonal) matrices.
degrees: Total degrees (ints; summed over all multidegrees) and/or
multidegrees (tuples with one entry per part).
Returns:
A dict from every requested degree to the number of invariants.
Raises:
RuntimeError: The group average is not an integer (the matrices do
not form a group, or the parts are wrong).
Example:
>>> import numpy as np
>>> mirror = [np.eye(1), -np.eye(1)]
>>> molien_counts(mirror, [1], [1, 2, 3, 4])
{1: 0, 2: 1, 3: 0, 4: 1}
"""
parts = [int(p) for p in parts]
degrees = list(degrees)
max_degree = 0
for degree in degrees:
max_degree = max(max_degree, sum(degree) if isinstance(degree, tuple) else int(degree))
offsets = np.cumsum([0] + parts)
unique = _unique_with_counts(matrices)
order = sum(count for _, count in unique)
# h_n of every part (and of the whole matrix) for every unique matrix
per_part, whole = [], []
for matrix, count in unique:
per_part.append([
_complete_homogeneous(
matrix[offsets[j]:offsets[j + 1], offsets[j]:offsets[j + 1]],
max_degree,
)
for j in range(len(parts))
])
whole.append(_complete_homogeneous(matrix, max_degree))
weights = np.array([count for _, count in unique], dtype=float)
result = {}
for degree in degrees:
if isinstance(degree, tuple):
values = np.array([
np.prod([h[j][n] for j, n in enumerate(degree)]) for h in per_part
])
else:
values = np.array([h[int(degree)] for h in whole])
result[degree] = _round_count(np.sum(weights * values) / order, f"degree {degree}")
return result
# ------------------------------------------------------------------ monomials
def _compositions(total: int, length: int):
"""Exponent tuples of the given total, lexicographically descending."""
if length == 1:
yield (total,)
return
for first in range(total, -1, -1):
for rest in _compositions(total - first, length - 1):
yield (first,) + rest
def monomial_exponents(parts, multidegree) -> np.ndarray:
"""Monomial basis of a multidegree in graded lexicographic order.
Args:
parts: Block dimensions.
multidegree: Degree in the variables of every part.
Returns:
Integer array ``(n_monomials, sum(parts))``; the first row is
``Q1^n`` (of the first part with nonzero degree).
"""
per_part = [list(_compositions(int(n), int(d))) for d, n in zip(parts, multidegree)]
rows = [sum(combo, ()) for combo in itertools.product(*per_part)]
rows.sort(reverse=True)
return np.array(rows, dtype=np.int64).reshape(len(rows), sum(int(p) for p in parts))
def _evaluate(points: np.ndarray, exponents: np.ndarray) -> np.ndarray:
"""Monomial values, shape ``(n_points, n_monomials)``."""
max_power = int(exponents.max()) if exponents.size else 0
powers = np.ones((max_power + 1,) + points.shape)
for k in range(1, max_power + 1):
powers[k] = powers[k - 1] * points
values = np.ones((exponents.shape[0], points.shape[0]))
for v in range(points.shape[1]):
column = exponents[:, v]
if np.any(column):
values *= powers[column, :, v]
return values.T
def _nullspace(matrix: np.ndarray, reference: float) -> np.ndarray:
"""Orthonormal nullspace basis (columns).
The singular-value threshold is relative: ``1e-8`` times the largest
singular value, or times ``reference`` (the scale of the monomial
values) when the matrix vanishes numerically (a generator that fixes
every monomial of the degree)."""
if matrix.shape[1] == 0:
return np.zeros((0, 0))
_, sing, Vh = np.linalg.svd(matrix, full_matrices=True)
largest = float(sing[0]) if sing.size else 0.0
rank = int(np.sum(sing > 1e-8 * max(largest, reference)))
return Vh[rank:].T
def _invariant_space(generators, exponents, n_vars, expected, rng_seed) -> np.ndarray:
"""Nullspace of the invariance conditions (columns = invariants)."""
n_mono = exponents.shape[0]
n_pts = 2 * n_mono + 10
found = None
for attempt in range(4):
rng = np.random.default_rng(rng_seed + attempt)
points = rng.normal(size=(n_pts, n_vars))
points /= np.linalg.norm(points, axis=1)[:, None]
base = _evaluate(points, exponents)
reference = float(np.linalg.norm(base, 2))
B = np.eye(n_mono)
for generator in generators:
moved = _evaluate(points @ np.asarray(generator).T, exponents)
A = (moved - base) @ B
B = B @ _nullspace(A, reference)
if B.shape[1] == 0:
break
found = B.shape[1]
if found == expected:
# orthonormalize the columns (products of orthonormal bases are
# orthonormal, but keep it exact)
if found:
B, _ = np.linalg.qr(B)
return B
n_pts *= 2
raise RuntimeError(
f"the invariant nullspace has dimension {found}, but the Molien series "
f"gives {expected} (monomials {n_mono})."
)
# ------------------------------------------------------- canonical form, text
def _rref(rows: np.ndarray, tol: float = 1e-7) -> tuple[np.ndarray, list[int]]:
"""Reduced row-echelon form (partial pivoting along the columns)."""
A = np.array(rows, dtype=float, copy=True)
if A.size == 0:
return A.reshape(0, rows.shape[1] if rows.ndim == 2 else 0), []
scale = max(1.0, float(np.max(np.abs(A))))
pivots: list[int] = []
r = 0
n_rows, n_cols = A.shape
for c in range(n_cols):
if r >= n_rows:
break
p = r + int(np.argmax(np.abs(A[r:, c])))
if abs(A[p, c]) <= tol * scale:
continue
A[[r, p]] = A[[p, r]]
A[r] /= A[r, c]
for other in range(n_rows):
if other != r and A[other, c] != 0:
A[other] -= A[other, c] * A[r]
A[r, np.abs(A[r]) < 1e-12] = 0.0
pivots.append(c)
r += 1
return A[:r], pivots
# Tolerance of the exact forms. The nullspace coefficients are accurate to
# ~1e-13; a looser tolerance (1e-6) would let limit_denominator(1000) "find"
# a fraction for most irrational numbers (the fractions with denominators up
# to 1000 are spaced ~3e-6 apart), e.g. 818/259 for 3.15830076.
_EXACT_TOLERANCE = 1e-9
def _rationalize(value: float) -> str:
"""Exact text of a coefficient: a fraction, a fraction times sqrt(2),
sqrt(3) or sqrt(6), a short surd found by ``sympy.nsimplify``, or a
6-decimal float."""
if abs(value) < 1e-9:
return "0"
frac = Fraction(value).limit_denominator(1000)
if abs(value - float(frac)) < _EXACT_TOLERANCE:
return str(frac)
for radicand in (2, 3, 6):
root = float(np.sqrt(radicand))
frac = Fraction(value / root).limit_denominator(1000)
if abs(value - float(frac) * root) < _EXACT_TOLERANCE:
sign = "-" if frac < 0 else ""
frac = abs(frac)
text = f"sqrt({radicand})"
if frac.numerator != 1:
text = f"{frac.numerator}*{text}"
if frac.denominator != 1:
text = f"{text}/{frac.denominator}"
return sign + text
import sympy
try:
guess = sympy.nsimplify(
value, [sympy.sqrt(2), sympy.sqrt(3)], tolerance=_EXACT_TOLERANCE
)
if (
not guess.is_Float
and abs(float(guess) - value) < _EXACT_TOLERANCE
and sympy.count_ops(guess) <= 6
):
return str(guess).replace("**", "^")
except (TypeError, ValueError, ZeroDivisionError):
pass
return f"{value:.6f}"
def _monomial_text(row, variables) -> str:
factors = []
for name, power in zip(variables, row):
if power == 1:
factors.append(name)
elif power > 1:
factors.append(f"{name}^{int(power)}")
return "*".join(factors) if factors else "1"
def _signed_magnitude(coefficient: str) -> tuple[bool, str]:
"""Sign and printed magnitude of an exact coefficient.
A compound coefficient (a sum such as ``-1 + sqrt(3)``) is one signed
unit: its sign is the sign of its value, and the magnitude is the
parenthesized expression, never the text with the first ``-`` cut off.
"""
negative = coefficient.startswith("-")
magnitude = coefficient[1:] if negative else coefficient
if any(op in magnitude for op in "+-"):
import sympy
expr = sympy.sympify(coefficient.replace("^", "**"))
negative = bool(float(expr) < 0)
magnitude = f"({_positive_first(sympy.expand(-expr if negative else expr))})"
return negative, magnitude
def _positive_first(expr) -> str:
"""A sum as text with its positive terms first, rational terms first
within each sign (``2*sqrt(3) - 3``, not sympy's ``-3 + 2*sqrt(3)``;
``6 + 2*sqrt(3)``); ``^`` powers."""
import sympy
terms = sorted(
sympy.Add.make_args(expr),
key=lambda term: (term.could_extract_minus_sign(), not term.is_Number, str(term)),
)
text = ""
for term in terms:
negative = term.could_extract_minus_sign()
body = str(-term if negative else term).replace("**", "^")
if not text:
text = f"-{body}" if negative else body
else:
text += f" - {body}" if negative else f" + {body}"
return text
def _polynomial_text(exact: list[str], exponents: np.ndarray, variables) -> str:
"""The polynomial ``sum exact[j] * monomial[j]`` as text (``^`` powers,
``*`` products, compound coefficients in parentheses)."""
text = ""
for coefficient, row in zip(exact, exponents):
if coefficient == "0":
continue
negative, magnitude = _signed_magnitude(coefficient)
monomial = _monomial_text(row, variables)
term = monomial if magnitude == "1" else f"{magnitude}*{monomial}"
if not text:
text = f"-{term}" if negative else term
else:
text += f" - {term}" if negative else f" + {term}"
return text or "0"
def _multiply(a: dict, b: dict) -> dict:
out: dict = {}
for ea, ca in a.items():
for eb, cb in b.items():
key = tuple(x + y for x, y in zip(ea, eb))
out[key] = out.get(key, 0.0) + ca * cb
return out
def _as_dict(poly: InvariantPolynomial) -> dict:
return {
tuple(int(x) for x in row): float(c)
for row, c in zip(poly.exponents, poly.coefficients)
if c != 0
}
def _product_name(factors: list[InvariantPolynomial]) -> str:
names, counts = [], {}
for factor in factors:
if factor.name not in counts:
names.append(factor.name)
counts[factor.name] = counts.get(factor.name, 0) + 1
return "*".join(name if counts[name] == 1 else f"{name}^{counts[name]}" for name in names)
def _multidegrees(n_parts: int, total: int):
return list(_compositions(total, n_parts))
def monomial_count(parts, degree: int) -> int:
"""Largest number of monomials in one multidegree of total ``degree``.
This is the size of the largest linear problem the engine solves for
that degree (the monomials of one part number
``comb(d + n - 1, n)``).
Args:
parts: Block dimensions.
degree: Total degree.
Returns:
The largest monomial count over the multidegrees of total
``degree``.
Example:
>>> monomial_count([12], 6)
12376
"""
parts = [int(p) for p in parts]
return max(
math.prod(math.comb(d + n - 1, n) for d, n in zip(parts, multidegree))
for multidegree in _multidegrees(len(parts), int(degree))
)
def check_monomial_count(parts, degree: int) -> int:
"""Refuse a degree whose linear problems are too large.
Args:
parts: Block dimensions.
degree: Highest total degree requested.
Returns:
The largest monomial count (see ``monomial_count``).
Raises:
ValueError: More than ``MONOMIAL_LIMIT`` monomials in one
multidegree (the message names the count and the degree).
"""
count = max(monomial_count(parts, n) for n in range(1, int(degree) + 1))
if count > MONOMIAL_LIMIT:
raise ValueError(
f"degree {degree} needs {count} monomials of {sum(parts)} components "
f"in one (multi)degree, more than the limit of {MONOMIAL_LIMIT}; "
"lower the degree."
)
return count
def _invariant_name(multidegree: tuple, serial: int) -> str:
if len(multidegree) == 1:
return f"I{multidegree[0]}_{serial}"
return f"I({','.join(str(n) for n in multidegree)})_{serial}"
def invariant_space(matrices, parts, multidegree, generators, rng_seed: int = 0):
"""Invariants of one multidegree as coefficient vectors.
The low-level step of ``invariants_of_matrices``, for callers that need
a single multidegree (coupling terms, secondary order parameters).
Args:
matrices: Real matrices of every group element (with multiplicity).
parts: Block dimensions.
multidegree: Degree in the variables of every part.
generators: Matrices that generate the group (used as given).
rng_seed: Seed of the random evaluation points.
Returns:
``(exponents, space)``: the monomial exponents of the multidegree
and an orthonormal basis of the invariant coefficient vectors as
columns (``(n_monomials, count)``; ``count`` is the Molien count).
Raises:
ValueError: Too many monomials (``MONOMIAL_LIMIT``).
RuntimeError: The nullspace disagrees with the Molien series.
"""
parts = [int(p) for p in parts]
multidegree = tuple(int(n) for n in multidegree)
exponents = monomial_exponents(parts, multidegree)
if exponents.shape[0] > MONOMIAL_LIMIT:
raise ValueError(
f"multidegree {multidegree} needs {exponents.shape[0]} monomials, "
f"more than the limit of {MONOMIAL_LIMIT}; lower the degree."
)
expected = molien_counts(matrices, parts, [multidegree])[multidegree]
if expected == 0:
return exponents, np.zeros((exponents.shape[0], 0))
space = _invariant_space(
[np.asarray(g, dtype=float) for g in generators],
exponents, sum(parts), expected, rng_seed,
)
return exponents, space
# ------------------------------------------------------------------- engine
def invariants_of_matrices(
matrices,
parts,
degree: int,
generators=None,
rng_seed: int = 0,
variables: list[str] | None = None,
) -> InvariantBasis:
"""Invariant polynomials of a finite real matrix group.
Args:
matrices: Real orthogonal matrices, one per group element (they
must form a group; repeated matrices are allowed).
parts: Block dimensions of the block-diagonal matrices (``[d]`` for
an irreducible representation).
degree: Highest total degree to compute.
generators: Matrices generating the group; by default a generating
subset of ``matrices`` is chosen.
rng_seed: Seed of the random evaluation points.
variables: Variable names (default ``Q1``, ``Q2``, ...).
Returns:
An ``InvariantBasis`` with the degrees 1 .. ``degree``.
Raises:
RuntimeError: The nullspace dimension disagrees with the Molien
series even after enlarging the point set (the generators do
not generate the group, or the problem is ill conditioned).
ValueError: ``degree`` is smaller than 1, the parts do not add up
to the matrix size, or one multidegree has more than
``MONOMIAL_LIMIT`` monomials (checked before any work).
Warns:
UserWarning: More than ``MONOMIAL_WARNING`` monomials in one
multidegree (the computation may take long).
Example:
>>> import numpy as np
>>> c4 = np.array([[0.0, -1.0], [1.0, 0.0]])
>>> group = [np.linalg.matrix_power(c4, k) for k in range(4)]
>>> basis = invariants_of_matrices(group, [2], 4)
>>> basis.counts
{1: 0, 2: 1, 3: 0, 4: 3}
"""
parts = [int(p) for p in parts]
n_vars = sum(parts)
if degree < 1:
raise ValueError("the degree must be at least 1.")
largest = check_monomial_count(parts, degree)
if largest > MONOMIAL_WARNING:
warnings.warn(
f"{largest} monomials in one (multi)degree at degree <= {degree}; "
"the computation may take long.",
stacklevel=2,
)
matrices = [np.asarray(m, dtype=float) for m in matrices]
if not matrices or matrices[0].shape != (n_vars, n_vars):
raise ValueError("the parts do not add up to the matrix dimension.")
if variables is None:
variables = [f"Q{n + 1}" for n in range(n_vars)]
group_keys = {_key(m) for m in matrices}
if generators is None:
generators = _generating_subset(matrices, group_keys)
else:
generators = _generating_subset([np.asarray(g, dtype=float) for g in generators],
group_keys)
degrees = list(range(1, degree + 1))
all_multidegrees = [m for n in degrees for m in _multidegrees(len(parts), n)]
multidegree_counts = molien_counts(matrices, parts, all_multidegrees)
counts: dict[int, int] = {}
polynomials: dict[int, list] = {}
products: dict[int, list] = {}
new_by_multidegree: dict[tuple, list] = {}
for n in degrees:
counts[n] = 0
polynomials[n] = []
products[n] = []
serial = 0
for multidegree in _multidegrees(len(parts), n):
expected = multidegree_counts[multidegree]
counts[n] += expected
if expected == 0:
new_by_multidegree[multidegree] = []
continue
if len(parts) > 1:
serial = 0 # direct sums: I(2,0)_1, numbered per multidegree
exponents = monomial_exponents(parts, multidegree)
space = _invariant_space(generators, exponents, n_vars, expected, rng_seed)
column = {tuple(int(x) for x in row): j for j, row in enumerate(exponents)}
# products of lower-degree new invariants with this multidegree
product_rows, product_names = [], []
for factors in _factorizations(multidegree, new_by_multidegree):
poly = _as_dict(factors[0])
for factor in factors[1:]:
poly = _multiply(poly, _as_dict(factor))
vector = np.zeros(exponents.shape[0])
for key, value in poly.items():
vector[column[key]] += value
product_rows.append(vector)
product_names.append(_product_name(factors))
accepted, accepted_rows = [], []
basis_q = np.zeros((exponents.shape[0], 0))
for name, vector in zip(product_names, product_rows):
residual = vector - basis_q @ (basis_q.T @ vector)
if np.linalg.norm(residual) > 1e-6 * max(1.0, np.linalg.norm(vector)):
basis_q = np.column_stack([basis_q, residual / np.linalg.norm(residual)])
accepted.append(name)
accepted_rows.append(vector)
# the new invariants: the invariant space reduced modulo the products
rows, _ = _rref(space.T)
if accepted_rows:
p_rows, p_pivots = _rref(np.array(accepted_rows))
for r in range(rows.shape[0]):
for p_row, pivot in zip(p_rows, p_pivots):
rows[r] -= rows[r, pivot] * p_row
rows, _ = _rref(rows)
n_new = expected - len(accepted)
if rows.shape[0] != n_new:
raise RuntimeError(
f"degree {n}: {expected} invariants, {len(accepted)} products, "
f"but {rows.shape[0]} new ones after the reduction."
)
for name, vector in zip(accepted, accepted_rows):
exact = [_rationalize(v) for v in vector]
products[n].append(InvariantPolynomial(
name=name, degree=n, multidegree=multidegree,
exponents=exponents, coefficients=vector, exact=exact,
expression=_polynomial_text(exact, exponents, variables),
))
new = []
for row in rows:
serial += 1
exact = [_rationalize(v) for v in row]
new.append(InvariantPolynomial(
name=_invariant_name(multidegree, serial), degree=n,
multidegree=multidegree,
exponents=exponents, coefficients=row, exact=exact,
expression=_polynomial_text(exact, exponents, variables),
))
new_by_multidegree[multidegree] = new
polynomials[n].extend(new)
return InvariantBasis(
variables=list(variables),
parts=parts,
degrees=degrees,
counts=counts,
polynomials=polynomials,
products=products,
multidegree_counts=multidegree_counts,
)
def _factorizations(multidegree: tuple, new_by_multidegree: dict):
"""Multisets of (at least two) lower-degree new invariants whose
multidegrees add up to ``multidegree``, in the order of the generator
list (degree, then serial number)."""
generators = [
poly
for md in sorted(new_by_multidegree, key=lambda m: (sum(m), tuple(-x for x in m)))
for poly in new_by_multidegree[md]
]
target = tuple(multidegree)
found = []
def extend(start: int, remaining: tuple, chosen: list):
if not any(remaining):
if len(chosen) >= 2:
found.append(list(chosen))
return
for index in range(start, len(generators)):
poly = generators[index]
md = poly.multidegree
if all(r >= m for r, m in zip(remaining, md)) and sum(md) < sum(target):
chosen.append(poly)
extend(index, tuple(r - m for r, m in zip(remaining, md)), chosen)
chosen.pop()
extend(0, target, [])
return found
# ------------------------------------------------------------ space groups
def _representation(space_group, irreps):
from .isotropy_subgroup import CoupledRepresentation, InducedRepresentation
from .spacegroup_product import SpaceGroupIrrepAlgebra
if isinstance(irreps, str):
irreps = [irreps]
irreps = list(irreps)
if not irreps:
raise SystemExit("ERROR: give at least one irrep label.")
algebra = SpaceGroupIrrepAlgebra(str(space_group))
if len(irreps) == 1:
representation = InducedRepresentation(algebra, irreps[0])
parts = [representation]
else:
representation = CoupledRepresentation(algebra, irreps)
parts = representation.parts
return algebra, representation, parts
def _generator_candidates(algebra, representation) -> list[np.ndarray]:
"""The generators (id, e_j) and (i, 0) of G / T_N, translations first."""
identity = algebra._rotation_index[algebra._key(np.eye(3))]
lookup = {
(i, tuple(int(x) for x in t)): matrix for i, t, matrix in representation.elements
}
candidates = []
if representation.grid_n > 1:
for e in ((1, 0, 0), (0, 1, 0), (0, 0, 1)):
candidates.append(lookup[(identity, e)])
candidates += [matrix for i, t, matrix in representation.elements if not np.any(t)]
return candidates
[docs]
def invariant_polynomials(space_group, irreps, degree: int = 4) -> InvariantBasis:
"""Invariant polynomials of one space-group irrep or of a direct sum.
Args:
space_group: Space-group number or international symbol
(``"Pm-3m"``, ``221``).
irreps: ISO-IR label(s): one label (``"R4+"``) or a list; several
labels give the invariants of the direct sum, with variables
``<label>_<n>``.
degree: Highest total degree (default 4).
Returns:
An ``InvariantBasis``. For one irrep the variables ``Q1 .. Qd``
follow the real basis of ``InducedRepresentation`` (arm by arm;
doubled complex-type irreps: real rows, then imaginary rows of each
arm), the order of the direction patterns of ``--parent``.
Raises:
SystemExit: Unknown space group or irrep (``ValueError`` through
``crystod.group``).
RuntimeError: The nullspace disagrees with the Molien series.
Example:
>>> from crystod import group
>>> basis = group.invariant_polynomials("Pm-3m", "M1+", degree=3)
>>> basis.polynomials[3][0].expression
'Q1*Q2*Q3'
"""
algebra, representation, parts = _representation(space_group, irreps)
return invariants_of_representation(algebra, representation, degree)
def invariants_of_representation(algebra, representation, degree: int = 4) -> InvariantBasis:
"""Invariant polynomials of an already-built space-group representation.
Args:
algebra: The ``SpaceGroupIrrepAlgebra`` the representation was built
from.
representation: An ``InducedRepresentation`` or a
``CoupledRepresentation``.
degree: Highest total degree.
Returns:
An ``InvariantBasis`` (see ``invariant_polynomials``).
Raises:
RuntimeError: The nullspace disagrees with the Molien series.
"""
parts = getattr(representation, "parts", None) or [representation]
if len(parts) == 1:
variables = [f"Q{n + 1}" for n in range(representation.dimension)]
else:
variables = [
f"{part.label}_{n + 1}" for part in parts for n in range(part.dimension)
]
matrices = [matrix for _, _, matrix in representation.elements]
basis = invariants_of_matrices(
matrices,
[part.dimension for part in parts],
degree,
generators=_generator_candidates(algebra, representation),
variables=variables,
)
basis.labels = [part.label for part in parts]
basis.arm_chunks = [list(part.arm_chunks) for part in parts]
return basis
def landau_lifshitz_of_elements(elements, rotations) -> LandauLifshitz:
"""Landau and Lifshitz counts from the group elements.
Args:
elements: ``(i, t, matrix)`` triples of the (physically irreducible,
real) representation, one per element of ``G / T_N``.
rotations: Rotation matrices of the coset representatives
(``algebra.rotations``); only their traces are used.
Returns:
A ``LandauLifshitz`` record.
"""
traces_w = [float(np.trace(rotations[i])) for i in range(len(rotations))]
cubic_sum = 0.0 + 0j
lifshitz_sum = 0.0
seen: dict[tuple, tuple] = {}
for i, _, matrix in elements:
key = (int(i), _key(matrix))
if key not in seen:
chi = float(np.trace(matrix))
chi2 = float(np.trace(matrix @ matrix))
h3 = _complete_homogeneous(matrix, 3)[3]
seen[key] = (h3, (chi * chi - chi2) / 2.0)
h3, antisym = seen[key]
cubic_sum += h3
lifshitz_sum += antisym * traces_w[int(i)]
order = len(elements)
n_cubic = _round_count(cubic_sum / order, "the cubic invariants")
n_lifshitz = _round_count(complex(lifshitz_sum / order), "the Lifshitz invariants")
return LandauLifshitz(n_cubic, n_lifshitz, n_cubic == 0 and n_lifshitz == 0)
[docs]
def landau_lifshitz(space_group, irrep: str) -> LandauLifshitz:
"""Landau (no cubic invariant) and Lifshitz conditions of an irrep.
Args:
space_group: Space-group number or international symbol.
irrep: ISO-IR irrep label (the physically irreducible, possibly
doubled real representation is used).
Returns:
A ``LandauLifshitz`` record; ``continuous_allowed`` is ``True`` when
neither a cubic nor a Lifshitz invariant exists.
Example:
>>> from crystod import group
>>> group.landau_lifshitz("Pm-3m", "R4+")
LandauLifshitz(n_cubic=0, n_lifshitz=0, continuous_allowed=True)
"""
algebra, representation, _ = _representation(space_group, [irrep])
return landau_lifshitz_of_elements(representation.elements, algebra.rotations)
def lowest_coupling_terms(basis: InvariantBasis) -> list[CouplingTerm]:
"""Coupling terms of the lowest total degree of a direct sum.
Args:
basis: An ``InvariantBasis`` of a direct sum (two or more parts).
Returns:
One ``CouplingTerm`` per multidegree with every entry >= 1 and a
nonzero count at the lowest such total degree, in the printed order
(descending lexicographic); an empty list when there is none up to
the computed degree or the basis has a single part.
"""
if len(basis.parts) < 2:
return []
trilinear = (1,) * len(basis.parts)
for n in basis.degrees:
found = []
for multidegree in _multidegrees(len(basis.parts), n):
if min(multidegree) < 1 or basis.multidegree_counts.get(multidegree, 0) == 0:
continue
polys = [
poly
for poly in basis.products[n] + basis.polynomials[n]
if tuple(poly.multidegree) == multidegree
]
found.append(CouplingTerm(multidegree, polys, multidegree == trilinear))
if found:
return found
return []
[docs]
def coupling_terms(space_group, irreps, max_degree: int = 4) -> CouplingTerm | None:
"""Lowest-order coupling term of a direct sum of irreps.
The invariants of the direct sum are computed up to total degree
``max_degree`` and the first multidegree with every entry at least 1
(lowest total degree, then descending lexicographic order) is
returned. For the hybrid improper mechanism, give two order
parameters and a polar Gamma irrep: a trilinear term ``Q1 Q2 P`` has
the multidegree ``(1, 1, 1)``.
Args:
space_group: Space-group number or international symbol.
irreps: Two or more ISO-IR labels, e.g. ``["X2+", "X3-", "GM5-"]``.
max_degree: Highest total degree searched (default 4).
Returns:
A ``CouplingTerm``, or ``None`` when no coupling term exists up to
``max_degree``.
Raises:
SystemExit: Fewer than two labels, or an unknown space group or
irrep (``ValueError`` through ``crystod.group``).
Example:
>>> from crystod import group
>>> term = group.coupling_terms("I4/mmm", ["X2+", "X3-", "GM5-"], 3)
>>> term.multidegree, len(term.polynomials), term.trilinear
((1, 1, 1), 1, True)
"""
if isinstance(irreps, str) or len(list(irreps)) < 2:
raise SystemExit("ERROR: a coupling term needs at least two irreps.")
basis = invariant_polynomials(space_group, list(irreps), max_degree)
terms = lowest_coupling_terms(basis)
return terms[0] if terms else None
def gamma_tensor_multiplicities(elements, rotations) -> tuple[int, int]:
"""Multiplicities of a Gamma irrep in the polar vector and in the strain.
The polar-vector representation has the character ``tr W``, the strain
(symmetric second-rank tensor) ``((tr W)^2 + tr W^2) / 2``. A doubled
(physically irreducible) form counts once per real copy.
Args:
elements: ``(i, t, matrix)`` triples of a Gamma-point
representation (one matrix per coset representative ``i``; the
translations act trivially).
rotations: Rotation matrices of the coset representatives
(``algebra.rotations``).
Returns:
``(n_polar, n_strain)``.
"""
by_i: dict[int, np.ndarray] = {}
for i, _, matrix in elements:
by_i.setdefault(int(i), matrix)
n_ops = len(rotations)
chi = np.array([np.trace(by_i[i]) for i in range(n_ops)])
traces = np.array([np.trace(w) for w in rotations], dtype=float)
traces2 = np.array([np.trace(w @ w) for w in rotations], dtype=float)
norm = float(chi @ chi) / n_ops # 1 for a real irrep, 2 for a doubled one
polar = float(chi @ traces) / n_ops / norm
strain = float(chi @ ((traces ** 2 + traces2) / 2.0)) / n_ops / norm
return int(round(polar)), int(round(strain))
def _plural(count: int, noun: str) -> str:
return f"{count} {noun}" if count == 1 else f"{count} {noun}s"
def landau_lifshitz_lines(record: LandauLifshitz) -> list[str]:
"""The Landau, Lifshitz and verdict lines of the ``* Irrep *`` block.
Args:
record: A ``LandauLifshitz`` record.
Returns:
Three lines, e.g. ``Landau condition: satisfied (no cubic
invariant)``, ``Lifshitz condition: satisfied (no Lifshitz
invariant)`` and ``-> a continuous transition is allowed``.
"""
landau = (
"satisfied (no cubic invariant)" if record.n_cubic == 0
else f"violated ({_plural(record.n_cubic, 'cubic invariant')})"
)
lifshitz = (
"satisfied (no Lifshitz invariant)" if record.n_lifshitz == 0
else f"violated ({_plural(record.n_lifshitz, 'Lifshitz invariant')})"
)
reasons = [
name for name, count in (("Landau", record.n_cubic), ("Lifshitz", record.n_lifshitz))
if count
]
verdict = (
"-> a continuous transition is allowed" if not reasons
else f"-> a continuous transition is forbidden ({' and '.join(reasons)})"
)
return [f"Landau condition: {landau}", f"Lifshitz condition: {lifshitz}", verdict]
def landau_lifshitz_note(label: str, record: LandauLifshitz) -> str:
"""The one-line form used under the ``--kpoint`` table (after ``note: ``).
Args:
label: Irrep label.
record: Its ``LandauLifshitz`` record.
Returns:
E.g. ``R4+: Landau condition satisfied, Lifshitz condition satisfied
(continuous transition allowed)``.
"""
landau = (
"Landau condition satisfied" if record.n_cubic == 0
else f"Landau condition violated ({_plural(record.n_cubic, 'cubic invariant')})"
)
lifshitz = (
"Lifshitz condition satisfied" if record.n_lifshitz == 0
else "Lifshitz condition violated "
f"({_plural(record.n_lifshitz, 'Lifshitz invariant')})"
)
verdict = "allowed" if record.continuous_allowed else "forbidden"
return f"{label}: {landau}, {lifshitz} (continuous transition {verdict})"
# ------------------------------------------------- restriction to a direction
def _component_expressions(tokens: list[str]):
"""sympy expressions of ``--order-parameter`` tokens (``a``, ``-a``,
``2a``, ``1/2a``, ``a+b-c-d``, ``0``, ``1/2``), read by the rules of
``IsotropyAnalyzer.resolve_direction``, and the parameter symbols in
order of appearance."""
import sympy
from .isotropy_subgroup import _component_terms
expressions, symbols = [], {}
for token in tokens:
value, terms = _component_terms(token)
if value is not None:
expressions.append(sympy.Rational(value.numerator, value.denominator))
continue
expression = sympy.Integer(0)
for name, factor in terms.items():
if name not in symbols:
symbols[name] = sympy.Symbol(name)
expression += sympy.Rational(factor.numerator, factor.denominator) * symbols[name]
expressions.append(expression)
return expressions, list(symbols.values())
def restricted_invariants(basis: InvariantBasis, tokens: list[str]) -> dict:
"""The invariants restricted to an order-parameter direction.
Every invariant (products of lower-degree invariants included) is
evaluated on the direction pattern, e.g. ``(a, a, 0)``; per degree the
restricted polynomials that vanish or are linearly dependent are
dropped, and the rest is brought to reduced row-echelon form in the
monomials of the parameters (so ``(a, b, 0)`` of R4+ gives
``a^4 + b^4`` and ``a^2*b^2`` at degree 4).
Args:
basis: An ``InvariantBasis`` (one irrep or a direct sum).
tokens: One ``--order-parameter`` token per component, in the order
of ``basis.variables`` (letters are parameters; ``-a``, ``2a``,
``1/2a``, sums such as ``a+b-c-d`` and numbers are accepted).
Returns:
A dict from every degree with a surviving invariant to the list of
independent restricted polynomials as text (``"a^2 + b^2"``).
Raises:
SystemExit: The number of tokens differs from the number of
components, a parameter factor is a rounded decimal
(``0.282a``), or a component cannot be read.
Example:
>>> from crystod import group
>>> basis = group.invariant_polynomials("Pm-3m", "R4+", 4)
>>> restricted_invariants(basis, ["a", "a", "a"])
{2: ['a^2'], 4: ['a^4']}
"""
import sympy
if len(tokens) != len(basis.variables):
raise SystemExit(
f"ERROR: the direction needs {len(basis.variables)} components "
f"(got {len(tokens)})."
)
expressions, parameters = _component_expressions(tokens)
names = [str(p) for p in parameters]
variables = [sympy.Symbol(name) for name in basis.variables]
substitution = dict(zip(variables, expressions))
result: dict[int, list[str]] = {}
for n in basis.degrees:
rows: list[dict] = []
for poly in basis.products[n] + basis.polynomials[n]:
restricted = sympy.expand(poly.sympy(basis.variables).subs(substitution))
if restricted == 0:
continue
if parameters:
terms = sympy.Poly(restricted, *parameters).terms()
else:
terms = [((), restricted)]
rows.append({tuple(int(e) for e in mono): float(coeff) for mono, coeff in terms})
if not rows:
continue
monomials = sorted({m for row in rows for m in row}, reverse=True)
matrix = np.array([[row.get(m, 0.0) for m in monomials] for row in rows])
reduced, _ = _rref(matrix)
texts = []
exponents = np.array(monomials, dtype=np.int64).reshape(len(monomials), len(names))
for row in reduced:
if np.max(np.abs(row)) < 1e-9:
continue
exact = [_rationalize(v) for v in row]
texts.append(_polynomial_text(exact, exponents, names))
if texts:
result[n] = texts
return result
# ------------------------------------------------------------------ printing
def _components_line(basis: InvariantBasis) -> str:
from .isotropy_subgroup import _PARAMETER_NAMES
variables = ", ".join(basis.variables)
if not basis.arm_chunks or len(basis.variables) > len(_PARAMETER_NAMES):
return f"Order-parameter components: ({variables})"
letters, start = [], 0
for chunks in basis.arm_chunks:
arms = []
for size in chunks:
arms.append(", ".join(_PARAMETER_NAMES[start:start + size]))
start += size
letters.append("; ".join(arms))
return (
f"Order-parameter components: ({variables}), in the order of the "
f"direction patterns ({' | '.join(letters)})"
)
def _count_line(head: str, count: int, n_products: int) -> str:
if count == 0:
return f"{head}: none"
noun = _plural(count, "invariant")
if n_products:
return f"{head}: {noun} ({n_products} from lower degrees, {count - n_products} new)"
return f"{head}: {noun}"
def format_invariants(basis: InvariantBasis) -> str:
"""The ``--invariants`` block as text.
One irrep is listed by total degree (``degree 2: 1 invariant``); a
direct sum by multidegree, in the order of total degree and then
descending lexicographic order (``degree (2, 0): 1 invariant``,
``degree (1, 1): none``, ...), followed by the lowest-order coupling
term (a multidegree with every entry >= 1).
Args:
basis: The result of ``invariant_polynomials`` or
``invariants_of_matrices``.
Returns:
The text block, starting with the ``* Invariant polynomials *``
header and ending with the Molien-check line (no trailing newline).
"""
top = max(basis.degrees)
lines = [f"* Invariant polynomials (degree <= {top}) *", _components_line(basis)]
multi = len(basis.parts) > 1
for n in basis.degrees:
if not multi:
count = basis.counts[n]
if n == 1 and count == 0:
continue
lines.append(_count_line(f"degree {n}", count, len(basis.products[n])))
for product in basis.products[n]:
lines.append(f" {product.name}")
for poly in basis.polynomials[n]:
lines.append(f" {poly.name} = {poly.expression}")
continue
for multidegree in _multidegrees(len(basis.parts), n):
count = basis.multidegree_counts.get(multidegree, 0)
if n == 1 and count == 0:
continue
products = [p for p in basis.products[n] if tuple(p.multidegree) == multidegree]
news = [p for p in basis.polynomials[n] if tuple(p.multidegree) == multidegree]
head = f"degree ({', '.join(str(x) for x in multidegree)})"
lines.append(_count_line(head, count, len(products)))
for product in products:
lines.append(f" {product.name}")
for poly in news:
lines.append(f" {poly.name} = {poly.expression}")
if multi:
terms = lowest_coupling_terms(basis)
if terms:
described = [
f"degree ({', '.join(str(x) for x in term.multidegree)}), "
f"{_plural(len(term.polynomials), 'invariant')}"
for term in terms
]
text = f"Lowest-order coupling term: {described[0]}"
if len(described) > 1:
text += f" (also {'; '.join(described[1:])})"
lines.append(text)
else:
lines.append(f"No coupling term up to total degree {top}")
lines.append("Numbers of invariants checked against the Molien series.")
return "\n".join(lines)
def format_restricted(restricted: dict, header: str) -> str:
"""The restricted free energy block printed after the invariants.
Args:
restricted: The result of ``restricted_invariants``.
header: The direction and subgroup, e.g. ``(a,0,0) [I4/mcm (140)]``.
Returns:
``Restricted to <header>:`` followed by one ``degree n: ...`` line
per surviving degree (independent polynomials separated by ``; ``).
"""
lines = [f"Restricted to {header}:"]
if not restricted:
lines.append(" no invariant survives on this direction")
for n, texts in restricted.items():
lines.append(f"degree {n}: {'; '.join(texts)}")
return "\n".join(lines)