# Mode-resolved force constants (crystod-phonon --mode-resolved-fc)
# Example directory: example/04-12_phonon_mode_fc (testsuite section 04-12)
#
# At the special q points of the space group (the points crystod-phonon --irreps
# surveys) the run gives, from POSCAR + FORCE_SETS (or FORCE_CONSTANTS with
# --readfc), the harmonic stiffness of every phonon level and of every irrep
# subspace, and writes mode-resolved-fc.yaml:
#   band_sets      per degenerate set: the ISO-IR label, the frequency, the
#                  effective mass mu = 1 / sum_i |e_i|^2/m_i (amu) and the force
#                  constant k = u^+ Phi(q) u^ = mu w (eV/A^2), with the pattern
#                  u = M^-1/2 e normalized to |u^| = 1 A over the primitive cell;
#                  k < 0 for an imaginary (unstable) mode. k is per primitive cell
#                  and does not change when the cell is enlarged; k/fu divides by
#                  the formula units Z of the primitive cell. At GM also
#                  k(-transl.): the uniform translation that a polar pattern
#                  carries is projected out and the rest renormalized.
#   irrep_hessian  per irrep: the force-constant matrix Phi(q) restricted to the
#                  subspace of all modes with that label (dim = multiplicity x
#                  irrep dimension), its eigenvalues and trace (eV/A^2); at GM
#                  also with the three uniform translations removed.
# With the amplitude A of crystod-group --supergroup-cif (AMPLIMODES type)
# measured over the same cell, the harmonic energy is E_cell = k A^2 / 2.
# crystod.phonon.read_mode_resolved_fc reads the file; the same numbers come
# from crystod.phonon.mode_resolved_force_constants (one q point) and
# survey_mode_resolved_fc (all special points) in Python.
#
# Three cases, each with a POSCAR and the FORCE_SETS of the supercell:
#   SrTiO3_Pm-3m/    221_PPOSCAR_SrTiO3, FORCE_SETS (4x4x4)    cubic perovskite
#   BaTiO3_P4mm/     99_PPOSCAR_BaTiO3, FORCE_SETS (4x4x4)     tetragonal ferroelectric
#   Ca3Ti2O7_I4mmm/  139_PPOSCAR_Ca3Ti2O7, FORCE_SETS (2x2x2)  Ruddlesden-Popper n = 2
# Run the command of each README inside its directory, e.g.
#   cd SrTiO3_Pm-3m
#   crystod-phonon --mode-resolved-fc -c 221_PPOSCAR_SrTiO3 --dim 4 4 4
# A run takes 2 to 4 s and writes mode-resolved-fc.yaml (-o FILE renames it).
#
# What to look at:
#   SrTiO3    the three polar GM4- optical sets have the effective masses of
#             the Slater (2.66 THz, mu = 20 amu), Last (4.71 THz, 57 amu) and
#             Axe (15.31 THz, 16 amu) patterns; R5-, the antiphase octahedral
#             rotation, has k = -0.077 eV/A^2 (unstable).
#   BaTiO3    the polar GM5 set at GM is unstable, k = -0.812 eV/A^2; the
#             acoustic set is an accidental GM1 + GM5 degeneracy, split into
#             its two irreps by the character projector.
#   Ca3Ti2O7  at X both the tilt X3- (k = -1.441 eV/A^2) and the rotation X2+
#             (k = -1.201 eV/A^2) are unstable: the pair whose trilinear
#             coupling with the polar mode gives the hybrid improper
#             ferroelectricity of Cmc2_1.
#
# Variants:
#   --qpoint R           only that q point (a label or three coordinates in the
#                        primitive reciprocal basis); special_points still lists
#                        every point
#   --readfc             FORCE_CONSTANTS instead of FORCE_SETS
#   --nac                with BORN; at exactly GM phonopy adds no NAC term, so the
#                        GM values are the analytic (TO) ones
#   --tolerance T        degeneracy tolerance of the sets in THz (default 1e-3)
