crystod-group#
The point/space-group representation-theory calculator. One mode flag per task:
--product, --table, --decompose, --ligand-field, --basis,
--generate-basis, --coset, --parent, --multiplet, --poscar2cif,
--cif2poscar, --supergroup-cif.
Point groups are selected with --pg/--pointgroup/--point-group and
space groups with --sg/--spacegroup/--space-group, by symbol or by
number (labels starting with -, such as -43m, are accepted). No structure
file is needed.
I want to … |
command |
|---|---|
multiply irreps |
|
see a character table |
|
split an orbital in a crystal field |
|
classify basis functions |
|
know which subgroup a distortion gives |
|
get the term symbols of a configuration |
|
convert POSCAR <-> CIF |
|
decompose an observed distortion |
|
7. Direct products (--product)#
Example directory: example/07_direct_product (testsuite section 7)
7.1 Point-group irreps (--pg/--point-group)#
crystod-group --product T2g T2g T1u --point-group m-3m
* Point group *
m-3m
* Direct product *
T2g*T2g*T1u
* Result *
1(A1u) + 1(A2u) + 2(Eu) + 4(T1u) + 3(T2u)
(--product T2g T2g alone gives 1(A1g) + 1(Eg) + 1(T1g) + 1(T2g) — the
symmetric/antisymmetric split of this square is what --multiplet performs in
section 14.)
7.2 Space-group irreps (--sg/--space-group)#
Decompose the direct product of full space-group irreps (the irreps at high-symmetry k points, induced over their whole star) into full space-group irreps with ISO-IR (ISOTROPY, Miller-Love) labels:
crystod-group --product R4- R5+ --sg Pm-3m
* Direct product (full space-group irreps) *
R4- x R5+ = GM2- + GM3- + GM4- + GM5-
* Dimension check (star size x small dim) *
3 x 3 = 9 -> 1 + 2 + 3 + 3 = 9
The k points of the factors may differ and three or more factors are accepted.
The wavevector selection rule k1 + k2 = k3 (mod reciprocal lattice) over the
star arms decides which stars appear, and the dimension check under the result
verifies the reduction. Products landing on symmetry lines outside the
tabulated special points (DT, SM, LD, …) are decomposed with on-the-fly
spgrep small irreps and marked [non-tabulated]; distinct +k/-k stars of
acentric groups take an “A” suffix (P1 x X1 = LD1 + LD2 + LDA1 + LDA2 in I4).
This is the offline counterpart of the DIRPRO program of the Bilbao
Crystallographic Server, cross-validated against it line by line (9007
products, 20 space groups covering all Bravais classes; see
example/07_direct_product/README). If you use this feature in a
publication, please cite M. I. Aroyo, A. Kirov, C. Capillas, J. M. Perez-Mato
and H. Wondratschek, Acta Cryst. A62, 115-128 (2006), and the ISO-IR
tables: H. T. Stokes, B. J. Campbell and R. Cordes, Acta Cryst. A69,
388-395 (2013).
7.3 Character tables for point groups (--table --point-group)#
crystod-group --table --point-group 3m
* IrRep Table *
table:
irrep E(1) C3(2) sgv(3)
A1 1 1 1
A2 1 1 -1
E 2 -1 0
The columns are the conjugacy classes with their sizes in parentheses. The
same table is printed alongside a decomposition with --show-irrep-table:
crystod-group --product T2g T2g T1u --point-group m-3m --show-irrep-table
7.4 Character tables for space groups (--table --space-group)#
With --space-group and a --kpoint, the characters of the small irreps of
the little group at that k point are tabulated — the space-group counterpart
of the point-group table above:
crystod-group --table --space-group Pm-3m --kpoint 0 0.5 0.5
* Space group *
Pm-3m (221)
* k-point (primitive) *
M [0.0, 0.5, 0.5]
* IrRep Table *
little group: P4/mmm (123)
table:
irrep 1 2_100 2_010 2_001 4^+_100 4^-_100 2_011 2_01-1 -1 m_100 m_010 m_001 -4^+_100 -4^-_100 m_011 m_01-1
irrep_1(1) = M1+(1) 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
irrep_2(1) = M1-(1) 1 1 1 1 1 1 1 1 -1 -1 -1 -1 -1 -1 -1 -1
irrep_3(1) = M3+(1) 1 1 -1 -1 1 1 -1 -1 1 1 -1 -1 1 1 -1 -1
irrep_4(1) = M3-(1) 1 1 -1 -1 1 1 -1 -1 -1 -1 1 1 -1 -1 1 1
irrep_5(2) = M5+(2) 2 -2 0 0 0 0 0 0 2 -2 0 0 0 0 0 0
irrep_6(2) = M5-(2) 2 -2 0 0 0 0 0 0 -2 2 0 0 0 0 0 0
irrep_7(1) = M2+(1) 1 1 1 1 -1 -1 -1 -1 1 1 1 1 -1 -1 -1 -1
irrep_8(1) = M2-(1) 1 1 1 1 -1 -1 -1 -1 -1 -1 -1 -1 1 1 1 1
irrep_9(1) = M4+(1) 1 1 -1 -1 -1 -1 1 1 1 1 -1 -1 -1 -1 1 1
irrep_10(1) = M4-(1) 1 1 -1 -1 -1 -1 1 1 -1 -1 1 1 1 1 -1 -1
Note that (0, 1/2, 1/2) is a non-representative arm of the M star: the
header names it M and the rows carry the ISO-IR labels transported from the
tabulated arm (irrep_N is the internal spgrep name, MN+/- the physical
label). Unlike a point-group table the columns are individual symmetry
operations in Seitz notation, not classes, because at a general k point the
Bloch phases of a class need not coincide. These are exactly the characters
against which the SALC, phonon, and spin analyses are reduced.
8. Representation decomposition (--decompose)#
Example directory: example/08_decompose_irrep (testsuite section 8)
Decompose a reducible representation into the irreps of a point group by entering
its characters class by class (educational / hand-analysis companion to --product):
crystod-group --decompose --point-group 3m
* Reducible representation *
1E: 3
2C3: 0
3sgv: 1
* Result *
1(A1) + 1(E)
The characters can also be given at once for non-interactive use:
crystod-group --decompose --point-group 3m --characters 3 0 1
The class order and multiplicities follow the prompt (e.g. 1E, 2C3, 3sgv for
3m); the character table can be checked with crystod-group --table.
Based on script/decomose_to_irreps.py by Hiroki Koiso.
9. Ligand-field splitting (--ligand-field)#
Example directory: example/09_ligand_field_split (testsuite section 9)
Decompose an atomic orbital (s, p, d, f, g, h, i) into the irreps of a point group — the crystal-field / ligand-field splitting of the orbital in the given point-symmetric environment:
crystod-group --ligand-field d --point-group m-3m
* Reducible representation of the d orbital in the m-3m field *
1E: 5
8C3: -1
6C2: 1
6C4: -1
3C4^2: 1
1i: 5
6S4: -1
8S6: -1
3sgh: 1
6sgd: 1
* Result *
1(Eg) + 1(T2g)
— the t2g/eg splitting of an octahedral field, with the characters it was
reduced from. Any shell up to i works, in any of the 32 point groups
(--ligand-field f --point-group 4/mmm gives 1(A2u) + 1(B1u) + 1(B2u) + 2(Eu)).
The characters of the (2l+1)-dimensional orbital representation are generated
from the standard angular-momentum formulas
(chi(C(a)) = sin((l+1/2)a)/sin(a/2), chi(S(a)) = cos((l+1/2)a)/cos(a/2)) and
decomposed with the same reduction engine as --decompose.
Based on script/ligand_field_spliting.py by Hiroki Koiso.
10. Basis functions (--basis)#
Example directory: example/10_basis_function (testsuite section 10)
crystod-group --basis x y z --point-group m-3m
crystod-group --basis x y z --space-group Pm-3m --kpoint 0 0 0
crystod-group --basis xyz --space-group Pm-3m --kpoint 0.5 0.3 0 --show-irrep-table
crystod-group --basis "x(y^2-z^2)" --point-group="m-3m"
crystod-group --basis "x^2-y^2" "2z^2-x^2-y^2" xy yz zx --space-group="Pm-3m" --kpoint 0 0 0
The input functions are automatically closed under the selected point group or
the little group of the selected space-group k point, then decomposed into
irreps. The irreps carry ISO-IR labels at every k point — special points and
generic lines alike (GM4-(3) at GM; Z2(1) in the third example above).
Besides the polar coordinates x, y, z, the axial-vector components
Rx, Ry, Rz (rotations, angular momenta, magnetic moments) are supported;
they transform with det(R) R and therefore land in the parity partners of the
polar bases:
crystod-group --basis Rx Ry Rz --point-group m-3m # -> T1g (x y z gives T1u)
crystod-group --basis Rx Ry Rz --space-group Pm-3m --kpoint 0 0 0 # -> GM4+
crystod-group --basis "x*Ry - y*Rx" --point-group m-3m # toroidal component -> T1u
The axial run shows the sign pattern responsible for the parity flip — the rotation classes keep the polar characters, while every improper class (i, S4, S6, sgh, sgd) changes sign relative to (x, y, z):
* Input basis functions *
Rx, Ry, Rz
* Reducible characters *
E: 3
C3: 0
C2: -1
C4: 1
C4^2: -1
i: 3
S4: 1
S6: 0
sgh: -1
sgd: -1
* Decomposition *
1.0 [T1g]
* Irreducible representations for basis functions *
T1g: [Rx, Ry, Rz]
This makes the magnetic (spin) irreps directly comparable with the
crystod-mag labels (e.g. the GM4+ cluster dipole of AlNi3).
When --kpoint is omitted in space-group mode, all special k points of the
space group are analyzed automatically (as in the crystod SALC survey):
crystod-group --basis Rx Ry Rz --space-group Pm-3m
# -> GM4+(3), R4+(3), M3+(1) + M5+(2), X3+(1) + X5+(2)
11. Basis-function generation (--generate-basis)#
Example directory: example/11_generate_basis_function (testsuite section 11)
Automatically generate 1st-3rd order polynomial basis functions
(x, y, z / x^2, ..., zx / x^3, ..., xyz) classified by irreducible representation:
crystod-group --generate-basis --point-group m-3m
crystod-group --generate-basis --point-group m-3m --order 2
crystod-group --generate-basis --space-group Pm-3m --kpoint 0 0 0
crystod-group --generate-basis --space-group Pm-3m --kpoint 0 0 0 --order 2 3 --show-irrep-table
This is the automated counterpart of --basis: for each requested order, all
monomials of that degree are decomposed into the irreps of the point group, or
of the little group of the selected space-group k point. The second-order run
at GM of Pm-3m, for example, ends with
* Decomposition *
1.0 [GM1+(1)] + 1.0 [GM3+(2)] + 1.0 [GM5+(3)]
* Irreducible representations for basis functions *
GM1+(1): [x^2 + y^2 + z^2]
GM3+(2): [-2 x^2 + y^2 + z^2, x^2 - 2 y^2 + z^2]
GM5+(3): [xy, yz, xz]
— the quadratic polynomials sorted into the breathing mode, the Eg pair, and the T2g triple (see also the projection-operator walk-through in the theoretical background).
12. Coset decomposition (--coset)#
Example directory: example/12_show_coset (testsuite section 12)
Point-group mode decomposes G into left cosets g H of a subgroup H:
crystod-group --coset --point-group m-3m --subgroup 4/mmm
* Groups *
G = m-3m (order 48)
H = 4/mmm (order 16)
* Coset decomposition G = sum_i g_i H *
index [G:H] = 3
coset 1 (representative: E):
{ E, C4#1, C4#2, C4^2#1, C4^2#2, C4^2#3, C2#1, C2#4, i, S4#1, S4#2, sgh#1, sgh#2, sgh#3, sgd#4, sgd#1 }
coset 2 (representative: C3#1):
{ C3#1, C2#3, C4#5, C3#7, C3#3, C3#5, C4#6, C2#6, S6#1, sgd#3, S4#5, S6#7, S6#3, S6#5, sgd#6, S4#6 }
coset 3 (representative: C3#2):
{ C3#2, C4#4, C2#2, C3#8, C3#4, C3#6, C4#3, C2#5, S6#2, S4#4, sgd#2, S6#8, S6#4, S6#6, sgd#5, S4#3 }
Space-group mode decomposes the rotation group of G into right cosets G_k g of the little co-group of a k point — one coset per arm of the star of k:
crystod-group --coset --space-group Pm-3m --kpoint 0.5 0.5 0
* Little co-group G_k *
order |G_k| = 16 (|G| = 48)
{ 1, 2_100, 2_010, 2_001, 4^+_001, 4^-_001, 2_110, 2_-110, -1, m_100, m_010, m_001, -4^+_001, -4^-_001, m_110, m_-110 }
* Coset decomposition G = sum_i G_k g_i (one coset per arm of the star) *
index [G:G_k] = |star of k| = 3
coset 1 (representative: 1, k arm = [+0.5, +0.5, +0]):
{ 1, 2_100, 2_010, 2_001, 4^+_001, 4^-_001, 2_110, 2_-110, -1, m_100, m_010, m_001, -4^+_001, -4^-_001, m_110, m_-110 }
coset 2 (representative: 3^+_111, k arm = [+0.5, +0, +0.5]):
{ 3^+_111, 3^+_1-1-1, 3^+_-11-1, 3^+_-1-11, 4^+_100, 4^-_100, 2_011, 2_01-1, ... }
coset 3 (representative: 3^-_111, k arm = [+0, +0.5, +0.5]):
{ 3^-_111, 3^-_1-1-1, 3^-_-11-1, 3^-_-1-11, 4^+_010, 4^-_010, 2_101, 2_-101, ... }
Each coset carries the k arm it generates, so this is the operation-level view
of the star printed by crystod --star-of-k. For the point-group mode, H must
be expressed in the same axes convention as G; a clear error message is printed
otherwise.
13. Isotropy subgroups (--parent)#
Example directory: example/13_isotropy_subgroup (testsuite section 13)
When a distortion transforming as an irrep condenses, the symmetry drops from
the parent group to the isotropy subgroup H(eta) = {g : D(g) eta = eta},
which depends on the order-parameter direction eta. The value the flag takes is
the parent group; --supergroup SG is kept as an alias of --parent SG
(backward compatibility) and should not be confused with --supergroup-cif,
the symmetry-mode analysis of section 16.
Omit --order-parameter to enumerate every direction type:
crystod-group --parent Pm-3m --irrep R4+
* Irrep *
R4+: order parameter dimension 3
* Order parameter directions and isotropy subgroups *
irrep subgroup size index
R4+(0,0,a) 140 I4/mcm 2 6
R4+(a,a,a) 167 R-3c 2 8
R4+(0,a,a) 74 Imma 2 12
R4+(0,a,b) 12 C2/m 2 24
R4+(a,a,b) 15 C2/c 2 24
R4+(a,b,c) 2 P-1 2 48
— the complete Howard-Stokes octahedral-tilt classification of perovskites, in one command. Give a direction to get that subgroup in full, with the cell relation you need to build it:
crystod-group --parent Pm-3m --irrep GM4- --order-parameter 0 0 a
* Irrep *
GM4-: order parameter dimension 3
* Isotropy subgroup *
GM4-(0,0,a) -> P4mm (No. 99)
cell size 1, index 6
sublattice basis (parent primitive units): (1,0,0), (0,1,0), (0,0,1)
conventional basis (parent conventional units): (0,0,1), (1,0,0), (0,1,0)
origin: (0,0,0)
Zone-boundary irreps carry their full star (order-parameter dimension =
arms x small dimension) and the cell enlargement is detected automatically.
Letters in --order-parameter are free parameters.
Following ISOTROPY, the order-parameter components are grouped arm by arm:
; separates the star arms and , the components within one arm (R4+ of
Pm-3m: one arm x small dim 3 -> (a,a,b); M3+: three arms x small dim 1 ->
(a;b;c); X5+: three arms x small dim 2 -> (a,b;0,0;0,0)).
When the induced irrep is of complex or pseudoreal type (Frobenius-Schur
indicator 0 or -1), the real order parameter transforms as the physically
irreducible doubled real form: the order-parameter dimension doubles and
the irrep is reported under an ISOTROPY-style pair label
(crystod-group --parent Ia-3d --irrep P2 prints P1P2, order-parameter
dimension 8). Separately tabulated +k/-k stars pair across the stars in the
same way (P1 of I-42d -> P1PA1, H1 of P3 -> H1HA1).
See also
Theory: Complex- and pseudoreal-type irreps — the realification of D + D*, and the conjugate-gauge and origin matching behind these pair labels.
Coupled order parameters (several irreps)#
Giving --irrep several labels enumerates the isotropy subgroups of the
coupled order parameters — the stabilizers on the direct sum of the
irreps, i.e. the space groups reached when several distortions condense
simultaneously:
crystod-group --parent I4/mmm --irrep X3- X2+
* Order parameter directions and isotropy subgroups (X3- alone) *
irrep subgroup size index
X3-(0;a) 63 Cmcm 2 4
X3-(a;a) 136 P4_2/mnm 4 4
X3-(a;b) 58 Pnnm 4 8
* Order parameter directions and isotropy subgroups (X2+ alone) *
irrep subgroup size index
X2+(0;c) 64 Cmce 2 4
X2+(c;c) 127 P4/mbm 4 4
X2+(c;d) 55 Pbam 4 8
* Order parameter directions and isotropy subgroups (coupled) *
irrep subgroup size index
X3-(0;a) X2+(0;c) 36 Cmc2_1 2 8
X3-(0;a) X2+(c;0) 62 Pnma 4 8
X3-(a;a) X2+(c;c) 38 Amm2 4 16
X3-(0;a) X2+(c;d) 26 Pmc2_1 4 16
X3-(a;b) X2+(0;c) 31 Pmn2_1 4 16
X3-(a;b) X2+(c;d) 6 Pm 4 32
The single-irrep tables of every given irrep are printed first, then the
coupled table. Its first column groups the components irrep by irrep, and
every irrep keeps its own free-parameter letters (X3-: a, b; X2+: c, d –
the amplitudes of different irreps are always independent); every coupled
direction condenses all the irreps with nonzero amplitude (a zero irrep
would just reproduce the single-irrep tables above). The arm combinations
matter: for
the n = 2 Ruddlesden-Popper structure above, condensing the octahedral
rotation (X2+) and tilt (X3-) at the same X arm gives the polar
hybrid-improper ferroelectric ground state Cmc2_1 (= A2_1am, as in
Ca3Ti2O7), while crossed arms give nonpolar Pnma. --order-parameter
then takes the concatenated components (--order-parameter 0 a 0 c above
resolves to Cmc2_1), and --parent Pm-3m --irrep R4+ M3+ reproduces the
full Howard-Stokes table of mixed perovskite tilt systems (a-a-c+ =
R4+(0,a,a) M3+(a;0;0) -> Pnma, a+a+c- -> P4_2/nmc, a0b-c+ -> Cmcm, …).
--parent is the offline counterpart of ISOSUBGROUP of the ISOTROPY
Software Suite (https://iso.byu.edu) and reproduces its published strata
tables. Where crystod’s ISO-IR data or a stratum’s enantiomorphic partner
differs from the ISOTROPY software, a note is printed under the output.
See also
Theory: Validation against ISOSUBGROUP — the exhaustive validation sweep, the known exceptions, and the citation to give if you use this feature.
14. Multi-electron terms (--multiplet)#
Example directory: example/14_multiplet (testsuite section 14)
The Pauli-allowed many-electron states (spin multiplicity 2S+1 + spatial irrep) of an electron configuration over point-group irrep shells, sorted by descending spin multiplicity (Hund-rule ground term first):
crystod-group --multiplet T2g2 --pg m-3m --orbital d
# -> (T2g)^2 = ^3T1g + ^1A1g + ^1Eg + ^1T2g (15 states = C(6,2))
crystod-group --multiplet T2g2 Eg1 --pg m-3m
# -> ^4T1g + ^4T2g + ^2A1g + ^2A2g + 2(^2Eg) + 2(^2T1g) + 2(^2T2g)
Shell tokens are written T2g2 or T2g^2 (equivalent; the ^-free form
needs no quoting in shells where ^ is a glob character, e.g. zsh).
The ground-state term symbol is always printed (Hund’s rules); with
--orbital, the exact Coulomb multiplet energies of every term are
computed in Racah parameters (A, B, C for d shells; reduced Slater-Condon
F_k otherwise) and the ground state is determined by energy:
crystod-group --multiplet T2g3 --pg m-3m --orbital d
* Multiplet Energies (Racah parameters A, B, C; Coulomb part only) *
^4A2g: 3A - 15B
^2Eg : 3A - 6B + 3C
^2T1g: 3A - 6B + 3C
^2T2g: 3A + 5C
* Ground-state Term Symbol (within this configuration) *
^4A2g (lowest for any B > 0, C > 0)
— the Tanabe-Sugano strong-field table of (t2g)^3. The energies come from the Coulomb Hamiltonian over the Slater determinants of the configuration, each term isolated by S^2 and point-group projectors; doubly-occurring terms mix (configuration interaction) and their two energies are printed in closed form (e.g. 3A - 3B + 3C +- 3sqrt(2)B in (t2g)^2(eg)^1).
See also
Theory: How the multiplet energies are computed — the Gaunt coefficients, the Racah / Slater-Condon reduction, the CI matrices, and the internal consistency checks.
f shells are fully supported (--orbital f; A2u + T1u + T2u shells in
m-3m), with energies in the reduced Slater-Condon parameters F0, F2, F4,
F6 — e.g. --multiplet T1u3 --pg m-3m --orbital f gives
^4A1u = 3F0 - (105/4)F2 - (189/2)F4 - (3705/4)F6 as the ground state (the
f analogue of (t2g)^3 -> ^4A2g); numeric CI blocks and the ground-state
selection use the hydrogenic 4f ratios F4/F2 = 0.138, F6/F2 = 0.0151.
Several tokens denote inequivalent shells, coupled by spatial direct
products and spin angular-momentum addition; the optional
--orbital s|p|d|f|... prints the ligand-field splitting of the parent
atomic orbital (section 9) and verifies the occupied shells occur in it.
Every result closes with a state-count check (product of C(2 dim, n)).
--multiplet applies the Pauli principle exactly: of the plain product
T2g x T2g (section 7) only the antisymmetric square pairs with the spin
triplet, so hole equivalence and closed shells come out automatically
((t2g)^4 gives the (t2g)^2 terms, (t2g)^6 gives ^1A1g).
See also
Theory: The Pauli principle and the CI matrices — the antisymmetrization, the CI matrices in the coupled-parent basis of the Tanabe-Sugano / Griffith strong-field tables, and the validation against the standard crystal-field term tables.
Visualizing the term eigenstates (--visualize)#
With --orbital, --visualize writes the exact eigenstates of every term as an interactive HTML page (Multiplet_{pg}_{config}.html): the term list in a sidebar (Hund/energy ground state marked), and for the selected term the full Slater-determinant expansion — every determinant drawn as an orbital box diagram (t2g: dxy, dyz, dxz | eg: dz2, dx2-y2, identified from the parent orbital) with up/down arrows and the exact expansion coefficient (1, ±1/2, ±1/√2, ±√3/2, …):
crystod-group --multiplet "T2g^2" --pg m-3m --orbital d --visualize
The page below is the live output of that command — the four terms of
(t2g)^2 (^3T1g + ^1A1g + ^1Eg + ^1T2g, the Hund ground term ^3T1g marked)
in the sidebar; pick one to see its Slater-determinant expansion as orbital
box diagrams and the drag-rotatable charge/spin-density surface of that
eigenstate:
Open the (t2g)2 multiplet viewer full-screen
A term eigenstate is in general a superposition of determinants, not a single box configuration: the ^4A2g of (t2g)^3 is the single determinant |dxy↑ dyz↑ dxz↑⟩ (coefficient 1), while a ^4T1g partner of (t2g)^2(eg)^1 is √3/2 |dx2-y2↑; dxy↑ dyz↑⟩ + 1/2 |dz2↑; dxy↑ dyz↑⟩. What the page shows:
states at the highest spin projection Ms = S, with degenerate spatial partners switchable (canonicalized, so any orthogonal mixture is equivalent);
one tab per state for configuration-mixed terms (the CI pairs, e.g. the two ^2T1g), each with its Coulomb energy at the reference parameters;
a drag-rotatable 3D surface of the charge and spin density (angular part) of every state, computed from the one-particle reduced density matrix of the term eigenstate and colored by the local spin polarization — the real-space picture behind orbital ordering and Jahn-Teller physics. The (t2g)^3 ^4A2g shows the cubic-symmetric t2g flower, fully spin-polarized; the ^2Eg partners keep the cubic charge density but carry an anisotropic spin density.
--output selects the file name. For f shells, symmetry-mixed basis functions
(e.g. the t1u combination of fx(x2-3y2) and fxz2) get short symbols t1u(1),
… in the boxes, expanded in an Orbital basis functions legend on the page.
15. POSCAR <-> CIF (--poscar2cif / --cif2poscar)#
Example directory: example/15_poscar2cif (testsuite section 15)
Convert a POSCAR into a CIF laid out like the files of the Bilbao Crystallographic Server, and back:
crystod-group --poscar2cif -c 221_PPOSCAR_SrTiO3 [--tolerance 0.01]
* POSCAR -> Bilbao-style CIF *
input : 221_PPOSCAR_SrTiO3
output : 221_PPOSCAR_SrTiO3.cif
space group: Pm-3m (No. 221), tolerance 0.01
48 symmetry operations, 3 independent sites
data_221_PPOSCAR_SrTiO3
_chemical_formula_sum "Sr Ti O3"
_symmetry_Int_Tables_number 221
_symmetry_space_group_name_H-M "Pm-3m"
_cell_length_a 3.9451
...
loop_
_symmetry_equiv_pos_site_id
_symmetry_equiv_pos_as_xyz
1 x,y,z
...
O1 O 0.50000 0.00000 0.50000 1.0000
Sr1 Sr 0.00000 0.00000 0.00000 1.0000
Ti1 Ti 0.50000 0.50000 0.50000 1.0000
and back:
crystod-group --cif2poscar -c 221_PPOSCAR_SrTiO3.cif [--conventional]
# -> 221_PPOSCAR_SrTiO3 (primitive cell; --conventional for the conventional cell)
The structure is brought to the spglib-standardized conventional cell (the
ITA setting and origin, as used by Bilbao); the CIF lists the space-group
number, the quoted Hermann-Mauguin symbol, 4-decimal cell parameters, the
full conventional-cell symmetry operations as compact x+1/2,-y,z strings
(proper operations first, centring translations included — 192 for Fm-3m),
and one representative site per Wyckoff orbit (5-decimal coordinates,
occupancy 1.0000). This differs from the pymatgen CifWriter layout;
--output overrides the default <POSCAR>.cif path. Validated against a
Bilbao reference file (identical operator set), the ITA Pnma general
positions, and pymatgen round-trip re-reading.
The _chemical_formula_sum
field carries the reduced formula in the conventional chemical order —
cations before anions; among the cations, the element on the most special
Wyckoff site (the letter closest to a) first, then increasing valence.
That is what makes SrTiO3, KNbO3 and PbZrO3 come out in the familiar
order (site tie broken by valence — electronegativity alone would write
ZrPbO3), and La3Ni2O7 keep La first (the 2-fold site beats Ni’s 4-fold
one even though Ni carries the lower valence). Valences are
oxidation-state guesses; electronegativity is the fallback.
--cif2poscar accepts any CIF flavour (Bilbao or pymatgen), expands the
symmetry operations, and writes the spglib-standardized primitive cell —
the working format of the other crystod commands — as a POSCAR in the
crystod test-file style (6-decimal direct coordinates with element tags)
to the input path without .cif. Round trips reproduce the original
primitive structure exactly (SrTiO3, ScF3, F-centred NaCl: 2-atom
primitive by default, 8-atom conventional with --conventional).
16. Symmetry-mode analysis (--supergroup-cif)#
Example directory: example/16_symmetry_mode (testsuite section 16)
Decompose the distortion between a high-symmetry and a low-symmetry structure of the same compound into symmetry-adapted modes of the parent space group — the offline counterpart of AMPLIMODES of the Bilbao Crystallographic Server:
crystod-group --supergroup-cif 221_PPOSCAR_SrTiO3.cif --subgroup-cif 140_PPOSCAR_SrTiO3.cif
* Symmetry-mode decomposition *
k-vector irrep direction isotropy subgroup dim amplitude (A)
(1/2,1/2,1/2) R5- (a,0,0) 140 I4/mcm 1 0.3303
A second example, the n = 2 Ruddlesden-Popper nickelate La3Ni2O7
(I4/mmm -> Cmcm), with --conventional:
crystod-group --supergroup-cif 139_PPOSCAR_La3Ni2O7.cif --subgroup-cif 63_PPOSCAR_La3Ni2O7.cif --conventional
* Supergroup (parent) structure *
I4/mmm (No. 139)
* Subgroup (distorted) structure *
Cmcm (No. 63)
* Cell relation *
child primitive basis in parent primitive units (rows):
(0, 0, -1)
(1, 1, 1)
(1, -1, 0)
origin shift (parent primitive fractional): (1/2, 0, 1/2)
primitive cell multiplication: 2
(setting: of 8 equivalent sublattice bases the one closest to the orientation of the
input files; the child axes are rotated 98.4 deg against the parent axes)
maximum atomic displacement: 0.4097 A
total distortion amplitude : 1.1489 A
(normalized within the primitive cell of the distorted structure)
* Symmetry-mode decomposition *
k-vector irrep direction isotropy subgroup dim amplitude (A)
(0,0,0) GM1+ (a) 139 I4/mmm 4 0.1313
(0,0,1/2) X3- (0;a) 63 Cmcm 6 1.1413
* Mode displacement VESTA files (parent conventional basis) *
display cell in parent primitive units (rows):
(0, 2, 2)
(2, 0, 2)
(1, 1, 0)
139_PPOSCAR_La3Ni2O7_GM1+_conv.vesta (amplitude 0.1313 A)
139_PPOSCAR_La3Ni2O7_X3-_conv.vesta (amplitude 1.1413 A)
The distortion is dominated by the zone-boundary octahedral-tilt mode
X3-(a;0), whose isotropy subgroup is exactly the observed Cmcm — the same
entry as in the single-irrep table of section 13 — while the totally
symmetric GM1+ is only a small secondary relaxation of the free
coordinates within I4/mmm. --conventional writes the per-mode displacement
VESTA files in the parent conventional basis (the _conv suffix; the
body-centred I lattice makes the conventional cell twice the primitive one,
hence the printed display-cell rows), so the arrows can be inspected in the
familiar tetragonal setting instead of the primitive one.
The output also contains the automatically determined cell relation
(sublattice basis + origin shift), the atom-by-atom displacement table
(maximum displacement, total distortion), the number of independent modes
per irrep, and the normalized polarization vectors; inputs may be CIFs or
POSCARs. Amplitudes follow the AMPLIMODES normalization (within the
primitive cell of the distorted structure). Multi-irrep distortions
decompose completely — the Pbnm perovskite gives R4+ -> Imma and
M3+ -> P4/mbm plus the inactive secondaries X5+/M2+/R5+. The direction and
isotropy-subgroup columns are computed with the same induced-irrep machinery
as --parent (section 13).
Which of the equivalent settings is reported? A symmetric parent leaves
the sublattice basis degenerate: every basis S·W (W a point operation of the
parent) pairs the atoms equally well and merely presents the same
distortion in a rotated setting — 24 of them for a cubic parent. CrystOD
picks the one whose child axes are rotated least against the parent axes,
both lattices taken as the input files orient them (a CIF is placed with c
along z and a in the xz plane; a POSCAR keeps its lattice vectors as
written), so the displacement table and the per-irrep VESTA files follow the
axes of the subgroup file: PbTiO3 P4mm polarized along c is shown
polarized along c of the cubic cell, not along b, and a POSCAR whose
polar axis lies along Cartesian y comes out along b. When no setting
aligns the axes — standard settings that permute them, a √2×√2 cell, a
rhombohedral child in its hexagonal setting — the residual rotation is
printed with the cell relation, as in the La3Ni2O7 example above (Cmcm puts
the long axis first: 90° plus the 45° in-plane rotation of the √2 cell). The
direction label of each irrep is written in the ISO-IR order-parameter basis
of that setting, so a domain-equivalent form can appear — (a,0,0) rather
than (0,0,a) for the I4/mcm tilt above; irrep, isotropy subgroup, number
of modes and amplitude do not depend on the setting.
Order parameters at non-special k points#
A few materials condense modes at k points that are not special points of the parent — points on symmetry lines with a fractional free parameter. The classic case is the PbZrO3 antiferroelectric, whose Pbam ground state (8x the cubic primitive cell) involves the Sigma point (1/4,1/4,0) and the S point (1/4,1/2,1/4):
crystod-group --supergroup-cif POSCAR_PbZrO3_Pm-3m.cif --subgroup-cif POSCAR_PbZrO3_Pbam.cif
* Symmetry-mode decomposition *
k-vector irrep direction isotropy subgroup dim amplitude (A)
(0,1/2,0) X3- (a;0;0) 123 P4/mmm 2 0.0374
(1/4,1/4,0) SM2 (0;0;0;0;0;0;a;0.332a;0;0;0;0) 55 Pbam 5 1.2871
(1/2,1/2,0) M5- (0,0;0,0;a,-a) 51 Pmma 3 0.0473
(1/4,1/2,1/4) S4 (0;0;a;0.332a;0;0;0;0;0;0;0;0) 64 Cmce 3 0.4470
(1/2,1/2,1/2) R4+ (a,a,0) 74 Imma 1 1.5232
(1/2,1/2,1/2) R5+ (a,-a,0) 74 Imma 2 0.0810
Every number agrees with the Bilbao AMPLIMODES reference — the dominant
antipolar Pb mode SM2 (1.2871 Å) and the octahedral tilt R4+
(1.5232 Å), with the secondary S4, R5+, X3- and M5- — including
each mode’s isotropy subgroup, which is verified internally by freezing the
single-mode displacement field and re-measuring its space group with
spglib. Small irreps at such points are computed with spgrep at the exact
k and named/represented through the bundled ISO-IR tables (SM2, S4, …);
since the ISOTROPY web tables fix their order-parameter axes with a phase
gauge that is not part of the bundled data, the direction pattern of a
line mode may differ from ISOSUBGROUP’s while the subgroup, dimension and
amplitude — gauge-independent quantities — always agree.
A second line-point case, the K2SeO4 lock-in ferroelectric (Pnma -> Pna2₁ at 3x the cell along a, SM = (1/3,0,0)):
crystod-group --supergroup-cif POSCAR_K2SeO4_Pnma.cif --subgroup-cif POSCAR_K2SeO4_Pna21.cif
* Symmetry-mode decomposition *
k-vector irrep direction isotropy subgroup dim amplitude (A)
(0,0,0) GM1+ (a) 62 Pnma 13 0.9467
(0,0,0) GM4- (a) 33 Pna2_1 8 0.4230
(1/3,0,0) SM2 (0.254a;-a) 33 Pna2_1 16 1.2885
(1/3,0,0) SM3 (0.254a;-a) 62 Pnma 26 0.1727
Decomposition table saved to sym_mode_K2SeO4
again matching AMPLIMODES entry by entry (including the polar GM4- that
carries the spontaneous polarization of the lock-in phase). The
decomposition table of every run is also saved as a text file,
sym_mode_{formula}, named by the parent composition in the conventional
chemical order of the _chemical_formula_sum rule of section 15
(sym_mode_K2SeO4, sym_mode_SrTiO3, sym_mode_La3Ni2O7, …), so a
batch of analyses leaves one table per compound.
Comparing with the Bilbao and ISOTROPY web tools#
The physically meaningful columns — which irreps are active, their k-vectors, isotropy subgroups, dimensions and amplitudes — reproduce AMPLIMODES and ISODISTORT case for case. Four things can legitimately read differently, and none of them is a disagreement about the distortion:
The origin of a polar subgroup is free, so the amplitude of a polar irrep depends on where it is pinned. CrystOD places it at the minimum of the total distortion (the AMPLIMODES convention) and prints a
note: the subgroup is polarline when it does. ISODISTORT pins the first orbit instead, which typically leaves its polar amplitude larger by exactly the removed rigid translation: the two differ by that translation and nothing else, so every other irrep is untouched.Parity superscripts of a k ≠ 0 irrep depend on the parent’s origin. Two descriptions of the same crystal related by a translation that is in the Euclidean normalizer but not in the space group (rutile VO₂ with the metal at 2a rather than 2b) give the same subgroup and the same amplitude, but swap
R1+andR1-.The k-vector is printed in the parent’s primitive basis, while Bilbao quotes the conventional one. For a C-centred monoclinic parent the M point reads
(1/2,1/2,1/2)here and(0,1,1/2)there — the same point.Order-parameter direction labels use whatever basis the bundled ISO-IR tables fix for that irrep, so the letter pattern can differ (
(a,-a,-a)against(a,a,a)) while naming the same stratum; the isotropy subgroup column, which is basis-independent, is the one to compare.
Two differences are not conventions and mean the input needs attention. If
the reported distortion is far larger than expected, check that the reference
cell the other program used really is the strain-free parent supercell — a
transformation matrix that misplaces it by a fraction of a cell dumps the
whole rigid offset into the fully symmetric mode. And if the analysis reports
no distortion at all, the child was probably symmetrized away during
--poscar2cif: displacements below the tolerance are averaged out (the
conversion warns about this), so pass a smaller --tolerance.
A symmetry lowering can also be purely a spontaneous strain: in La₃Ni₂O₇ I4/mmm → Fmmm the atoms keep every parent operation exactly and only the orthorhombic metric breaks the four-fold axis. The displacive decomposition then holds a single fully symmetric mode, and the report says which part of the symmetry lowering it is not carrying.
See also
Theory: Symmetry-mode analysis internals — the lattice and origin handling, the completeness checks, the validation against Bilbao AMPLIMODES, and the citation to give if you use this feature.