# Spin bases on several magnetic elements (crystod-mag --element A B, --superpose)
# Example directory: example/05-09_multi_element (testsuite section 05-09)
#
# With two or more elements (two or more Wyckoff orbits) the spin space is the
# direct sum of the spin spaces of the elements. crystod-mag --element A B
# analyses every element as its single-element run does (the element-pure
# bases, numbered [1], [2], ... in the order of the table), prints the
# decomposition per element and in total, and then compares the copies of one
# irrep that occur on different elements: the matrices of the operations on the
# basis rows of every copy, and the map that takes the rows of the first copy
# to those of another (the identity when they share the same matrices). Because
# all copies transform with the same irrep matrices, a superposition of copies
# along the SAME order-parameter direction, with any nonzero real amplitudes,
# has the magnetic space group of each copy alone: the table "irrep x
# direction -> magnetic space group" of the single-element runs is complete as
# far as symmetry goes, and the relative amplitudes of the copies are free
# parameters that symmetry does not fix. The run then lists, for every irrep
# found on two or more elements and every direction of the first element's
# copy, the arrangements with one copy per element and the relative signs
# (+,+) and (+,-) (2^(n-1) patterns for n elements), each copy with largest
# moment 1 and signed as its listed component, with their magnetic space
# groups, responses and classes (and VESTA files in a full run, at most 48).
#
# 1) AlNi3 (Pm-3m): Al alone gives GM4+, Ni alone 2 x GM4+ + GM5+.
#
#   crystod-mag -c 221_PPOSCAR_AlNi3 --element Al Ni --qpoint GM --classify-only
#
#   * Spin (axial-vector) representation *
#     Spin (axial-vector) representation on Al, Ni sites: 12 dimensions
#     Decomposition (Al, 3 dimensions): GM4+(3)
#     Decomposition (Ni, 9 dimensions): 2 x GM4+(3) + GM5+(3)
#     Decomposition (total): 3 x GM4+(3) + GM5+(3)
#   ...
#   * Copies of one irrep on several elements *
#     GM4+(3): reference Al GM4+(3) [FM, dipole]
#       Ni GM4+(3) [FM, dipole]: same matrices on the rows
#       Ni GM4+(3) [AFM, octupole]: rows mapped by (-x, y, z)
#
# The octupole copy of Ni has its x row with the opposite sign convention: its
# exported component 111 is the domain [11-1] of the same group R-3m', not the
# direction 111 of the dipoles. The combined arrangements follow the direction
# through that map. 20 of them: GM4+ along z, x, y, 110 and 111, Al with either
# Ni copy, (+,+) and (+,-). Their groups are those of the single copies
# (P4/mm'm', Cmm'm', R-3m'); the class tells parallel from antiparallel:
#
#   -    Al+Ni    GM4+(3) [Al FM, dipole + Ni FM, dipole]     z (+,+)    P4/mm'm' (123.345)  III   4/mm'm'  along z            ferromagnet                          P4/mm'm'
#   -    Al+Ni    GM4+(3) [Al FM, dipole + Ni FM, dipole]     z (+,-)    P4/mm'm' (123.345)  III   4/mm'm'  along z            ferrimagnet                          P4/mm'm'
#
# 2) A Lieb lattice with two different elements on the edge sites (Cu at
#    (0,0,1/2), Al at (0,1/2,1/2), B at (1/2,0,1/2); a = 3, c = 20 A; Pmmm):
#
#   crystod-mag -c POSCAR_Lieb_CuAlB --element Al B --qpoint GM --classify-only --phonon-angular-momentum
#
#   -    Al+B     GM2+(1) [Al FM, dipole + B FM, dipole]  z (+,+)    Pm'm'm (47.252)  III   m'm'm  along z            ferromagnet                          Pm'm'm
#   -    Al+B     GM2+(1) [Al FM, dipole + B FM, dipole]  z (+,-)    Pm'm'm (47.252)  III   m'm'm  along z            compensated (unrelated sublattices)  Pm'm'm
#
# Al up and B down has the group of Al up and B up, and l_z of its phonons is
# s-wave (a net magnetization is allowed along z). The same picture with Al on
# both sites (P4/mmm) is a d-wave altermagnet:
#
#   crystod-mag -c POSCAR_Lieb_CuAl2 --element Al --qpoint GM --classify-only --phonon-angular-momentum
#
#   GM4+(1) [AFM, octupole]  z          P4'/mm'm (123.342)  III   4'/mm'm  none               altermagnet (d-wave)  P4'/mm'm
#   GM4+(1) [AFM, octupole]  z          4'/mm'm  d    q_x q_z     2       d    q_y q_z     2       d    q_x^2 - q_y^2    2
#
# Two different elements are never exchanged by an operation of the crystal,
# so the two-element description cannot have the C4 that relates the two edge
# sites: the "same" up-down pattern is a different magnetic group.
#
# 3) Any listed bases, of any irreps and elements, superposed with given
#    coefficients (the model is crystod-phonon --modulation --mode ... --amplitude):
#
#   crystod-mag -c 221_PPOSCAR_AlNi3 --element Al Ni --qpoint GM --classify-only --superpose 1 16 --coefficients 1 0.5 --no-files
#
#   * Superposition *
#     [1] Al GM4+(3) [FM, dipole] z: coefficient 1
#     [16] Ni GM5+(3) [AFM, octupole] z: coefficient 0.5
#     irrep content (squared weights): Al GM4+(3) [FM, dipole] 0.667 + Ni GM5+(3) [AFM, octupole] 0.333
#       Al1: S = [ 0.0000,  0.0000,  1.0000]
#       Ni1: S = [ 0.0000,  0.0000,  0.0000]
#       Ni2: S = [ 0.0000,  0.0000,  0.5000]
#       Ni3: S = [ 0.0000,  0.0000, -0.5000]
#       net moment over the magnetic cell: [0.0, 0.0, 1.0]
#       magnetic space group: Pm'm'm (BNS 47.252, type III), 8 operations, 4 with time reversal
#       ...
#       collinear order: ferrimagnet
#
# Without --classify-only the superposition also gets its MAGMOM line and the
# VESTA file POSCAR_AlNi3_spin_superposition_1_16_GM.vesta; with one element the
# numbers are the rows of its table of magnetic groups, counted from 1.
#
# Files:
#   221_PPOSCAR_AlNi3               AlNi3, primitive cell (as example/test_POSCARs)
#   POSCAR_Lieb_CuAlB               Lieb lattice, Al and B on the edge sites (Pmmm)
#   POSCAR_Lieb_CuAl2               the same with Al on both edge sites (P4/mmm)
#   samm_AlNi3_Al-Ni_GM_classify    report of the first command
#   samm_CuAlB_Al-B_GM_classify     report of the second command
#   samm_CuAl2_Al_GM_classify       report of the third command
