Changelog#

All notable changes to CrystOD, newest first.

Unreleased#

  • Changed: the space-group filter of crystod-search is --sg / --spacegroup / --space-group, as in crystod-group and crystod-bz; --spg, the spelling of v0.4.9, stays as an alias. crystod-search La2CuO4 --sg Cmce (or --spacegroup 64) lists the materials of that space group only, by number or by symbol as before; --spg 64 keeps working with the same result, so existing command lines need no change. All four spellings fill one value (args.space_group), checked as before (--spg 231 and --spg P7 are refused like --sg 231 and --sg P7, and --get with any of them is refused as a filter). The sort key --sort spg keeps its name. Documentation: crystod-search; tests in section 10-01 (the four spellings: the same rows, request and report; one namespace; the refusals).

  • Added: crystod-group -o FILE, the short form of --output that every other command with an output file already has. crystod-group --poscar2cif -c POSCAR -o out.cif is --output out.cif: one value (args.output), the same files (the CIF of --poscar2cif, the POSCAR of --cif2poscar, the page of --multiplet --visualize and of --graph) and the same refusals in the modes that write no file. As before, every token after --order-parameter up to the next --option is a component, so -o there is read as minus o (as -c is minus c); --output takes no part in the --order-parameter modes. Documentation: crystod-group; tests in section 02-18.

  • Added: crystod --unfold --trans-matrix T, an alias of --trans-mat, as in crystod-bz and crystod-phonon. The nine integers are read and checked as before (one value, args.trans_mat; the error messages name --trans-mat), and the unfolding is the same. The abbreviations --tr … --trans-ma, which argparse used to complete to --trans-mat, are now ambiguous (exit 2), as they already are in crystod-bz and crystod-phonon; --trans-mat itself is unchanged. Documentation: crystod; tests in sections 01-09 (the guards with the alias, the same .dat/.yaml of a synthetic 2x1x1 unfolding) and 01-10 (one namespace, --help).

v0.4.9#

Highlights (details in the entries below):

  • crystod-phonon --mode-resolved-fc: the force constant k = mu w and the effective mass of every phonon mode at the special q points, and the force-constant matrix restricted to the subspace of every irrep (the irrep-resolved Hessian), in mode-resolved-fc.yaml; testsuite section 04-12.

  • crystod-mag --qpoint at q != 0: both phases of a complex order parameter (the partners i w as comp<d+1> .. comp<2d>), every order-parameter direction of every basis in the magnetic cell with ISOTROPY’s label, magnetic isotropy subgroup, size and index (* Order-parameter directions *), and the one-parameter directions no component lay on as dir<k>; testsuite section 05-06.

  • crystod-mag --qpoint K --subgroup-poscar CHILD: the spin bases at q != 0 placed on a distorted structure whose cell is a magnetic cell of q, and every order-parameter direction aligned with its structural domain (the irrep of CHILD at GM its field becomes, its magnetic space group on CHILD, the angle from the exported component), with MAGMOM lines, VESTA files and a POSCAR in the cell of CHILD; testsuite section 05-07.

  • crystod-mag --qpoint ... --phonon-angular-momentum: the texture of the phonon angular momentum near Γ allowed by the magnetic point group of every component (lowest-degree q-polynomial of l_x, l_y, l_z, s- to j-wave, enforced nodal planes), with --classify-only a table that starts with the paramagnetic crystal; testsuite section 05-08.

  • crystod-mag --element A B --qpoint ...: spin bases on several elements at once (the decomposition per element and in total, the copies of one irrep checked to share the same matrices, one copy per element combined along every direction with the signs (+,+), (+,-)), and --superpose N ... --coefficients c ... for any listed bases; testsuite section 05-09.

  • crystod-mag --parent SG --irrep A B ...: magnetic isotropy subgroups of several coupled irreps (each irrep alone, then the coupled order parameters in which every irrep condenses), and --order-parameter for one direction; time-even irreps from Python (parities=); testsuite section 05-10.

  • crystod-mag -c POSCAR --element EL --irrep IR [IR2 ...]: every magnetic isotropy subgroup of --parent SG --irrep ... (several irreps: the coupled rows) placed on the sites of the element(s), with its magnetic space group identified again from the structure, spin listing, MAGMOM line, VESTA file and magnetic cell; testsuite section 05-01.

  • crystod-phonon -c POSCAR --element EL --irrep IR [IR2 ...] (no mode flag, no force data): every isotropy subgroup of crystod-group --parent SG --irrep ... (several irreps: the coupled rows) placed on the atoms of the element(s) as a symmetry-adapted displacement pattern, with the space group of the displaced structure identified again, displacement listing, VESTA arrows and the displaced structure; --qpoint K for every irrep at K; -c POSCAR --element EL alone for the irreps of the displacements at every special k point; testsuite section 04-01.

  • Commands whose result is a terminal report also save it, word for word, in a file named after the command (samm_*, saad_*, CORREL_*, salc_*, …); --no-files prints only and CRYSTOD_NO_REPORT=1 turns the saving off for every command.

  • The section numbers of testsuite.py, example/ and this manual are two-level, CC-NN, grouped by command; seven more example directories ship with the package (52 in all).

  • Changed: the section numbers are two-level, CC-NN: CC is the command group and NN the index inside it, shared by the example directory (example/CC-NN_name), the documentation heading (## CC-NN. Title) and the testsuite section (key "CC-NN", function test_CC_NN_name, header [CC-NN]). The groups are 01 crystod (01-01 the library core, 01-11 the Python API), 02 crystod-group, 03 crystod-bz, 04 crystod-phonon, 05 crystod-mag, 06 crystod-md, 07 crystod-mol, 08 crystod-xrd, 09 crystod-slab, 10 crystod-search and 11 crystod-example. The sections numbered at the end since v0.4.8 (58-66) now sit in their group: the displacement patterns of crystod-phonon -c POSCAR --element EL --irrep IR open the crystod-phonon group (04-01) and the magnetic arrangements of crystod-mag -c POSCAR --element EL --irrep IR the crystod-mag group (05-01), and their documentation sections moved to the front of their pages. A feature added later takes the next free NN of its group, so no number moves again. The sub-sections of a section are lettered CC-NN-A, CC-NN-B, … (02-01-A. Point-group irreps, formerly 02-01.1). python testsuite.py 05-01 04-02 runs those sections, python testsuite.py 05 the whole crystod-mag group, no argument everything in the new order; an old number is refused with its new one (ERROR: section 64 is an old number: it is 05-01 now). crystod-example takes the new number (crystod-example 02-10), the directory name or the name without the number (crystod-example isotropy_subgroup); an old number or name still finds the directory, with a NOTE (NOTE: 20 is now 02-10 ...), and crystod.examples.renamed_note gives that line in Python. The packaged copies in crystod/examples/ follow the new names (index.json format 2: the number of a directory is the text "CC-NN"). The renaming also repairs three stale paths: 32_phonon_irrep (renamed to 32_phonon_bandirrep in the tree but not in testsuite.py, example/PACKAGED, the docs and crystod-example) is 04-02_phonon_bandirrep everywhere; the Cr2O3 cell of 05-03_magnetic_group is Cr2O3/PPOSCAR_Cr2O3_R-3c in its README, the test and example/PACKAGED; and the YMnO3 cells of section 05-06 are read from its own directory 05-06_mag_directions. Released entries below keep the numbers of their release (their links point to the new headings).

    Old and new section numbers

    old

    new

    old example directory

    new directory or section

    1

    01-01

    01_wigner_d

    01-01_wigner_d

    2

    01-02

    02_salc

    01-02_salc

    3

    01-03

    03_hybridization

    01-03_hybridization

    4

    01-04

    04_selection_rules

    01-04_selection_rules

    5

    01-05

    05_star_of_k

    01-05_star_of_k

    6

    01-06

    06_visualized_basis

    01-06_visualized_basis

    7

    01-07

    07_check_symmetry

    01-07_check_symmetry

    8

    01-08

    (no example directory)

    crystod –extract-irrep

    9

    01-09

    09_band_unfold

    01-09_band_unfold

    10

    01-10

    (no example directory)

    crystod command-line regression

    52

    01-11

    52_python_api

    01-11_python_api

    11

    02-01

    11_direct_product

    02-01_direct_product

    12

    02-02

    12_symmetric_square

    02-02_symmetric_square

    13

    02-03

    13_decompose_irrep

    02-03_decompose_irrep

    14

    02-04

    14_ligand_field_split

    02-04_ligand_field_split

    15

    02-05

    15_basis_function

    02-05_basis_function

    16

    02-06

    16_tensor_form

    02-06_tensor_form

    17

    02-07

    17_generate_basis_function

    02-07_generate_basis_function

    18

    02-08

    18_show_coset

    02-08_show_coset

    19

    02-09

    19_correlate

    02-09_correlate

    20

    02-10

    20_isotropy_subgroup

    02-10_isotropy_subgroup

    21

    02-11

    21_invariants

    02-11_invariants

    22

    02-12

    22_child_lookup

    02-12_child_lookup

    23

    02-13

    23_subgroup_graph

    02-13_subgroup_graph

    24

    02-14

    24_multiplet

    02-14_multiplet

    25

    02-15

    25_poscar2cif

    02-15_poscar2cif

    26

    02-16

    26_symmetry_mode

    02-16_symmetry_mode

    27

    02-17

    27_correlate_double_group

    02-17_correlate_double_group

    28

    02-18

    (no example directory)

    crystod-group command-line regression

    29

    03-01

    29_brillouin_zone

    03-01_brillouin_zone

    30

    03-02

    30_bz_supercell

    03-02_bz_supercell

    31

    03-03

    (no example directory)

    crystod-bz command-line regression

    66

    04-01

    66_phonon_irrep

    04-01_phonon_irrep

    32

    04-02

    32_phonon_bandirrep

    04-02_phonon_bandirrep

    33

    04-03

    33_phonon_activity

    04-03_phonon_activity

    34

    04-04

    34_phonon_fatband

    04-04_phonon_fatband

    35

    04-05

    35_phonon_lt

    04-05_phonon_lt

    36

    04-06

    36_phonon_vector

    04-06_phonon_vector

    37

    04-07

    37_modulation

    04-07_modulation

    38

    04-08

    38_vibration

    04-08_vibration

    39

    04-09

    39_phonon_unfold

    04-09_phonon_unfold

    40

    04-10

    40_phonon_visualize

    04-10_phonon_visualize

    41

    04-11

    (no example directory)

    crystod-phonon –subgroup and command-line regression

    58

    04-12

    58_phonon_mode_fc

    04-12_phonon_mode_fc

    64

    05-01

    64_mag_irrep

    05-01_mag_irrep

    42

    05-02

    42_spin_basis

    05-02_spin_basis

    43

    05-03

    43_magnetic_group

    05-03_magnetic_group

    44

    05-04

    (no example directory)

    crystod-mag –parent

    45

    05-05

    (no example directory)

    crystod-mag command-line regression

    59

    05-06

    59_mag_directions

    05-06_mag_directions

    60

    05-07

    (no example directory)

    crystod-mag –subgroup-poscar

    61

    05-08

    61_phonon_angular_momentum

    05-08_phonon_angular_momentum

    62

    05-09

    62_multi_element

    05-09_multi_element

    63

    05-10

    63_mag_coupled

    05-10_mag_coupled

    65

    05-11

    (no example directory)

    crystod-mag magnetic space groups on non-invariant cells

    46

    06-01

    46_xdatcar2adp

    06-01_xdatcar2adp

    48

    06-02

    (no example directory)

    crystod-md –summary and command-line regression

    47

    06-03

    47_md_projection

    06-03_md_projection

    49

    07-01

    49_molecular_salc

    07-01_molecular_salc

    50

    07-02

    50_molod

    07-02_molod

    51

    07-03

    (no example directory)

    crystod-mol command-line regression

    53

    08-01

    53_xrd_pattern

    08-01_xrd_pattern

    54

    08-02

    54_xrd_superlattice

    08-02_xrd_superlattice

    56

    09-01

    56_slab

    09-01_slab

    55

    10-01

    55_mp_search

    10-01_mp_search

    57

    11-01

    (no example directory)

    crystod-example (packaged examples)

  • Changed: the examples of seven of the new features below ship with the package: 04-01_phonon_irrep, 04-12_phonon_mode_fc, 05-01_mag_irrep, 05-06_mag_directions, 05-08_phonon_angular_momentum, 05-09_multi_element and 05-10_mag_coupled (crystod-example 04-01, 04-12, 05-01, 05-06, 05-08, 05-09, 05-10). Their READMEs, input structures (for 04-12_phonon_mode_fc also the FORCE_SETS and the reference mode-resolved-fc.yaml files) and the samm_* reference reports the READMEs name are packaged. 52 of the 54 example directories now ship (all but 01-07_check_symmetry and 01-09_band_unfold): 291 files with the shared inputs, 8.46 MB (94.0 % of the 9,000,000-byte budget of example/PACKAGED), 2.96 MB compressed with zlib.

  • New: crystod-phonon -c POSCAR --element EL [EL2 ...] --irrep IR [IR2 ...] (no mode flag, no force data) gives the displacement pattern on the crystal of every isotropy subgroup of the irrep(s); --element EL --qpoint K does it for every irrep the displacements of EL contain at K, and -c POSCAR --element EL [EL2 ...] alone lists those irreps at every special k point. The displacement (polar-vector, time-even) counterpart of crystod-mag -c ... --irrep, with its machinery: for every row of the table of crystod-group --parent SG --irrep ... (one irrep: its table; several: the coupled table; the same rows, order, labels, groups, sizes and indices) displacement modes Psi of the atoms of the element(s) that transform with the table’s own matrices, O(g) Psi = Psi D(g) with (O(g) u)(g r) = R u(r) (no det(R), no time reversal; Gamma_disp = Gamma_perm x Gamma_vector), times the row’s order parameter, so that the stabilizer of the pattern in G is the row’s isotropy subgroup by construction. Every displaced structure is identified again with spglib as written (all atoms, the tolerance of --tolerance, default 1e-5 A): number, size from its primitive cell and index from its point group, in the column structure (63 Cmcm same) and a check (on the displaced structure as written): line with the numbers of elements of G/T_S fixing the displacements and the order parameter. La3Ni2O7 I4/mmm, O: --irrep X3- gives X3-(0;a) 63 Cmcm, X3-(a;a) 136 P4_2/mnm and X3-(a;b) 58 Pnnm, each on three copies (O(8g), O(4e), O(2a)); --irrep X3- X2+ the coupled rows 36 Cmc2_1, 62 Pnma, 38 Amm2, 26 Pmc2_1, 31 Pmn2_1 and 6 Pm. Every block lists the moving atoms (Cartesian displacements in Angstrom, the atoms at rest counted), the space and point group of the displaced structure and what the point group alone allows (electric polarization along an axis or in a plane, in Cartesian POSCAR axes, or none; inversion kept or broken; chiral), and a reproduce: --order-parameter "..." line. Copies, weights, --coefficients, --order-parameter, --copies, --classify-only, --conventional and --no-files as in crystod-mag --irrep (at q = 0 the copies of an orbit are split into the net shift of the orbit and the rest). These are symmetry-adapted displacement patterns, not eigenvectors of a dynamical matrix. Files: per row and copy POSCAR_<formula>_disp_<IR>[_<IR2>]_<NN>_<SG>_<symbol>[_c<copies>].vesta (arrows scaled to 1.5 A) and the displaced structure M<POSCAR name>_<IR>[_<IR2>]_<NN>_<SG>_<symbol>[_c<copies>] (largest displacement --amplitude, default 0.1 A), the supercell S<POSCAR name>_<IR>[_<IR2>] and the report saad_<formula>_<element(s)>_<IR>[_<IR2>] (_conv, _classify, _op; --qpoint K: S<POSCAR name>_<K>, saad_<formula>_<element(s)>_<K>). An irrep the displacements do not contain is an ERROR with the decomposition at its k point; the options of the force-data modes are refused, and --irrep together with a mode flag is refused (--irrep used to be accepted by argparse as an abbreviation of --irreps; it is now its own option). --element takes several values (still one with --fatband, where more is an error); every mode flag keeps its behaviour. The survey, -c POSCAR --element EL [EL2 ...] with no --irrep and no --qpoint (formerly a parser error), is the displacement counterpart of the crystod-mag -c POSCAR --element EL survey: the decomposition of the displacement (polar-vector) representation at every special k point of the tables, by the function and in the term order of the --irrep/--qpoint headers (several elements: per element and total), report saad_<formula>_<element(s)>_survey, no structures (--amplitude, --conventional, --classify-only, --order-parameter, --coefficients and --copies refused); every line equals the header of --qpoint K and, as a multiset, the one of crystod -c POSCAR --element EL --orbital p (p orbitals are polar vectors; a complex-conjugate pair at a time-reversal-invariant point stays one term under its pair label, A1A3(2) for A1(1) + A3(1), where crystod lists the members) (API phonon.displacement_irrep_survey, DisplacementSurvey). Validation: every irrep of every special point on 11 structures of the examples (Mn3GaN, AlNi3, SrTiO3, La2CuO4, La3Ni2O7 I4/mmm and Cmcm, NiO, Y2Ir2O7, Cr2O3, YMnO3 P6_3/mmc, LuFeO3), for one element and for all atoms, with and without --conventional (912 runs, 7060 rows, 14542 patterns), 17 coupled sets with and without --conventional (1194 patterns) and three primitive cells re-expressed with a’ = a + b (La2CuO4, NiO, YMnO3; 5756 patterns): spglib finds the row’s group, size and index on every displaced structure; the symmetry-mode analysis of crystod-group --supergroup-cif finds only the requested irreps in a sample of the displaced structures. Python: phonon.displacement_irrep_arrangements (DisplacementIrrepAnalysis, DisplacementArrangement); implementation in crystod/displacement_arrangements.py (the machinery of crystod/magnetic_arrangements.py, which gained parameters for polar vectors; its outputs are unchanged). See crystod-phonon, section 04-01, and the theory in Displacement patterns of the isotropy subgroups on a crystal. Example: example/04-01_phonon_irrep, three cells with a README of transcripts each: La3Ni2O7/ (I4/mmm, O), ScF3/ (Pm-3m, F) and SrTiO3/ (Pm-3m with Ti at the origin, O; in test_POSCARs/221_PPOSCAR_SrTiO3, with Sr at the origin, the same O displacements carry R5- and M2+ instead of R4+ and M3+); testsuite section 04-01.

  • New: crystod-mag -c POSCAR --element EL [EL2 ...] --irrep IR [IR2 ...] (no --parent, no --qpoint) gives the magnetic arrangement on the crystal of every magnetic isotropy subgroup of the irrep(s). For every row of the table of crystod-mag --parent SG --irrep ... (one irrep: its table; several: the coupled table, every irrep condensed; same rows, order, labels, groups, sizes and indices) the moments on the sites of the element(s) in a diagonal magnetic cell common to every arm of every star (Mn3GaN R4- M3-: 2x2x2). The arrangement is built from the table, not matched to it afterwards: spin modes Psi that transform with the table’s own matrices, O(g) Psi = Psi D(g) (projection of the axial-vector representation of the supercell, the ISO-IR setting mapped onto the POSCAR through the frame that names the irreps of every crystod-mag report), times the row’s order parameter, so that the stabilizer of the moments in G1’ is the row’s magnetic isotropy subgroup by construction. Every arrangement is nevertheless identified again with spglib on the moments exactly as written (4 decimals, moment tolerance 3e-4; column structure of the table and a check (on the written moments): line with the numbers of elements of G1’/T_S fixing the moments and the order parameter; a disagreement would be a NOTE on the row), and every block has a reproduce: --order-parameter "..." line whose numbers rebuild the same written moments. Copies of an irrep (on several elements, Wyckoff orbits, or twice on one orbit) give one arrangement per choice (c1, c2, …), split by element, orbit and, at q = 0, into the ferromagnetic combination and the antiferromagnetic ones named by multipole rank as --qpoint names them (Mn3GaN GM4+: Mn [FM, dipole], Mn [AFM, octupole]). Rows with several letters use generic values (printed, largest 1; the relative amplitudes are not fixed by symmetry), several irreps are scaled to largest moment 1 each and weighted by --coefficients (finite, nonzero, none below 1e-3 of the largest), by default per row the first of 1 : 1, 1 : 0.5, 1 : 0.75, … under which no moment cancels between the parts (Mn3GaN R4- M3-: rows 1, 5, 6, 13 at 1 : 0.5, the reason printed); more than 6 choices of copies per row export the first with a NOTE, --copies i j selects one; every block has a line on the moment sizes (equal on all 24 Mn sites, 2 distinct magnitudes ..., zero on 8 sites (no moment in R4-, M3-), cancelled on 8 sites by the weights), the magnetic space and point groups, UNI symbol, the responses allowed by symmetry, the collinear order, the spin listing and the MAGMOM line (--format qe: the Quantum ESPRESSO input). --classify-only prints the tables only, --order-parameter "0 0 a 0 0 b" builds one direction (numbers are amplitudes), names the row of its stratum and saves its report as ..._op. An irrep the spins do not carry is an ERROR with the decomposition at its k point (--irrep R4+ on Mn of Mn3GaN), every invalid irrep reported at once (so are bad --coefficients and a -c file that is not a POSCAR; on a structure whose irreps the survey cannot label at the tolerance, a NOTE says so and the copies come from the irrep matrices); --qpoint and the other options of the --qpoint report are refused. --conventional writes every arrangement in the conventional cell instead of the diagonal supercell (for I, F, C, A, R lattices): the cell --qpoint --conventional uses for the same POSCAR times the smallest multiples commensurate with every arm (La2CuO4 I4/mmm X3+: 2x2x1 conventional cells, a Display cell: line); the rows, weights and counts stay on the diagonal cell, the moments are re-tiled onto the conventional cell (exact, the arrangement being periodic under every T with k . T integral for every arm), and the check, spin listings, MAGMOM lines, site counts and files refer to the conventional cell; names get _conv (..._<BNS>[_c<copies>]_conv.vesta, S<POSCAR name>_<IR>_conv, report ..._conv, ..._conv_classify, ..._conv_op), the reproduce: line ends with --conventional, and a conventional cell above 12 cells along one axis or 256 primitive cells is refused with an ERROR that suggests running without it. Files: POSCAR_<formula>_spin_<IR>[_<IR2>]_<row>_<BNS>[_c<copies>].vesta per row, S<POSCAR name>_<IR>[_<IR2>] (atom order of the MAGMOM lines) and the report samm_<formula>_<element(s)>_<IR>[_<IR2>] (_classify with --classify-only; --no-files and CRYSTOD_NO_REPORT write none). Validation: every irrep of every special k point on 21 structure-element combinations of the examples (345 irreps, 2423 rows, 4340 arrangements) and 25 coupled sets over 10 structures (343 rows, 621 arrangements): spglib finds the table’s group on every arrangement, the tables equal those of --parent, the one-parameter rows have the groups of the --qpoint components (YMnO3 K3: 193.255 and 193.259), and the irrep content of every field is the requested irrep alone; with --conventional, every irrep of every special k point on La2CuO4, La3Ni2O7 (I4/mmm and Cmcm), NiO, Y2Ir2O7, Cr2O3, an A-centred Amm2 test structure and Mn3GaN (127 irreps, 1964 arrangements) and 10 coupled sets (231 arrangements): the same tables, weights and counts as without it, spglib finds the table’s group on all 2195 arrangements in the conventional cell, and every atom of it carries exactly the moment of the run without it at the same position. Before this change --irrep without --parent was an error; every other output is unchanged. Python: mag.magnetic_irrep_arrangements (MagneticIrrepAnalysis, MagneticArrangement, IrrepCopy); implementation in crystod/magnetic_arrangements.py. See crystod-mag, section 05-01, and the theory in Arrangements of the magnetic isotropy subgroups on a crystal. Example: example/05-01_mag_irrep (Mn3GaN); testsuite section 05-01.

  • New: crystod-mag --parent SG --irrep A B ... lists the magnetic isotropy subgroups of several coupled irreps, and --order-parameter gives the subgroup of one direction. An order condensing several irreps has its order parameter in the direct sum, and lowers the grey group G1’ to the stabilizer of that vector, time reversal acting as -D on every magnetic (time-odd) irrep. The report has the blocks of crystod-group --parent SG --irrep A B: * Coupled irreps *, the table of every irrep alone with its own letters (* Order parameter directions and isotropy subgroups (M3+ alone) *: M3+(0;0;d)), and * Order parameter directions and isotropy subgroups (coupled) *, one row per conjugacy class of stabilizers in G1’ in which every irrep has a nonzero amplitude, with the BNS number and symbol, size and index. Pm-3m R4+ M3+ gives 22 coupled rows, from R4+(0,0,a) M3+(0;0;d) 127.397 P_C4/mbm (size 4, index 12) and R4+(0,a,a) M3+(d;0;0) 62.454 P_Bnma (unitary Pnma, 24) to R4+(a,b,c) M3+(d;e;f) 2.4 P-1 (384). A coupled row with the group of a one-irrep row is a direction where one order parameter induces the other as a secondary one (8 of the 12 one-irrep directions of Pm-3m GM4+ GM5+). --order-parameter "0 a a d 0 0" (components irrep after irrep, parts may be zero; also with one irrep) prints * Magnetic isotropy subgroup * with the BNS group, type, UNI symbol, magnetic point group, unitary subgroup, size, index and sublattice basis. With one irrep and no --order-parameter the output is unchanged. Validation (no tabulated oracle exists): with one irrep the coupled engine reproduces the one-irrep table at every k point of the 230 space groups (16923 rows); with every irrep time-even it reproduces the coupled table of crystod-group as grey groups; every coupled direction of 23 cases (pairs and triples at GM, R, X, M, K, H, a complex pair, mixed parities) agrees with spglib on an explicit arrangement built from the irrep matrices (moments, and displacements for time-even irreps) in BNS number, size and index (758 comparisons); isotropy, containment, lift and non-conjugacy checks pass on 354 coupled rows. Python: mag.coupled_magnetic_isotropy_subgroups(parent, irreps, parities=None) (CoupledMagneticIsotropySubgroups of CoupledMagneticIsotropySubgroup rows), mag.coupled_magnetic_order_parameter (CoupledMagneticOrderParameter); parities=["even", "odd"] makes an irrep time-even (a distortion, theta acting as +D), printed then with ISOTROPY’s m on the time-odd ones; the command line does not take time-even irreps yet. Implementation in crystod/magnetic_isotropy_coupled.py. See crystod-mag, section 05-04, and the theory in Coupled magnetic order parameters. Example: example/05-10_mag_coupled (README transcript); testsuite section 05-10.

  • New: crystod-mag -c POSCAR --element Al Ni --qpoint GM takes two or more magnetic elements (two or more Wyckoff orbits) in one run. The spin representation is the direct sum over the elements; every element is analysed as its single-element run (the element-pure bases, the same outputs, VESTA names with the element: POSCAR_AlNi3_spin_Al_GM4+_dipole_z.vesta) and the decomposition is printed per element and in total (AlNi3: Al GM4+, Ni 2 x GM4+ + GM5+, total 3 x GM4+ + GM5+). The block * Copies of one irrep on several elements * compares the copies of every irrep found on two or more elements through the matrices of the operations on their basis rows (same matrices on the rows, or the intertwining map, e.g. rows mapped by (-x, y, z) for the Ni octupole copy of GM4+ in AlNi3, whose row x has the opposite sign convention) and states why the table of the single-element runs is complete: a superposition of copies along one order-parameter direction, with any nonzero amplitudes, has the magnetic space group of each copy alone, and the relative amplitudes are free parameters symmetry does not fix. For every such irrep and every direction of the first element’s copy (the components x, y, z, 110, 111, comp, dir of the listing), one copy per element is combined with the relative signs (+,+), (+,-) (2^(n-1) patterns), each copy with largest moment 1, and classified as any basis (magnetic space group, responses, class: parallel dipoles of AlNi3 a ferromagnet, antiparallel a ferrimagnet, both P4/mm’m’); 20 arrangements for AlNi3 at GM, 8 at X; VESTA files for at most 48. The table * Magnetic groups and collinear classes * gets the columns no. and element, --phonon-angular-momentum and --show-operations cover every row, and the reports are samm_<formula>_<A>-<B>_<q>[_classify] and samm_<formula>_<A>-<B>_survey (the survey gives the decomposition of every element and of the total at every special point). New option --superpose N [N ...] --coefficients c [c ...] (also with one element: the numbers are the rows of the table): any listed bases, of any irreps and elements, added with real coefficients, with their irrep content, moments, magnetic space group, responses, class, MAGMOM line and VESTA file. With one element and without --superpose every output is unchanged. Python: mag.analyze_multi_element (MultiElementAnalysis, CopyRelation, CombinedArrangement), mag.superpose_bases (Superposition), mag.multi_summary_rows, mag.format_multi_summary, mag.format_copy_relations, mag.component_magmoms; implementation in crystod/multi_element.py. See crystod-mag, section 05-09, and the theory in Spin bases on several elements. Example: example/05-09_multi_element (AlNi3, a Lieb lattice with Al/B and with Al/Al).

  • New: crystod-mag --qpoint ... --phonon-angular-momentum gives the texture of the phonon angular momentum near Γ that the magnetic point group of every component allows. The angular momentum l(q) of a phonon branch (L. Zhang and Q. Niu, Phys. Rev. Lett. 112, 085503 (2014)) is a time-odd axial vector, and an operation (R, t) demands l(A q) = B l(q) with A = s R, B = s det(R) R (s = -1 with time reversal). For each Cartesian component the lowest degree of an allowed q-polynomial (s, p, d, f, g, h, i, j for 0..7, searched up to 9), its polynomials and the nodal planes through Γ pinned by a single operation (a mirror without time reversal containing e_i, a 2’ along the normal when e_i is along it); the pinned planes can be fewer than the degree (4’ gives l_z ~ q_z with no plane), the other nodes then not fixed in position by symmetry; P T gives none (P T), degree 0 is the net magnetization. Every component block gets the line phonon angular momentum: l_x ~ q_y q_z (d-wave; zero on the planes perpendicular to [010], [001]); l_y ~ ...; l_z ~ q_x q_y (d-wave; zero on the planes perpendicular to [100], [010]) (rutile GM2+, 4’/mmm’) after collinear order:, and --classify-only the block * Phonon angular momentum allowed by symmetry * after the table, whose first row is the grey group of the crystal (what ordinary force constants give: none (P T) for rutile, the j-wave l_z with seven planes for YMnO3 P6_3cm); a reference line closes the report. Without the option every output is unchanged. Python: mag.phonon_angular_momentum (PhononAngularMomentum, AngularMomentumComponent; plane_normal= for a layer, with nodal lines), mag.phonon_angular_momentum_degrees (every allowed degree), mag.phonon_angular_momentum_rows, mag.format_phonon_angular_momentum and mag.paramagnetic_point_group. See crystod-mag, section 05-08, and the theory in Phonon angular momentum near Gamma. Example: example/05-08_phonon_angular_momentum (TiO2, YMnO3); testsuite section 05-08.

  • New: the line allowed by symmetry: of crystod-mag also says whether the magnetic point group allows a spontaneous electric polarization, right after the net magnetization: net magnetization none; electric polarization none; linear magnetoelectric effect 2 components; piezomagnetism none. The polarization is a time-even polar vector (Jahn V), so time reversal does not constrain it: it is allowed when the point group of the spatial parts of all operations is polar, and an MPG with -1' forbids it (Cr2O3, R-3’c’, MPG -3’m’: no polarization, no net magnetization, magnetoelectric tensor diag(alpha11, alpha11, alpha33)). The direction uses the words of the net magnetization (none, along z, in the xy plane, any direction) and is followed by (induced by the spin order) when the same structure without moments (same tolerance) allows no polarization, or by (the crystal without spins: along z) when it allows fewer components; TiO2 (P4_2/mnm) at q = (0,0,1/3) gives MPG 2’ with electric polarization along z (induced by the spin order), every order of polar LuFeO3 (P6_3cm) at GM along z without a note. format_magnetic_responses prints electric polarization: allowed by symmetry along z or forbidden by symmetry after the net magnetization. The summary table * Magnetic groups and collinear classes * and the other lines are unchanged. Python: MagneticResponses.polarization, .polarization_direction, .polarization_note and .n_polarization, MagneticGroupInfo.crystal_rotations (the point group of the structure without moments, filled by magnetic_space_group), and the keyword crystal_rotations of macroscopic_responses for explicit operations. See crystod-mag; tests in section 05-03.

  • New: crystod-phonon --mode-resolved-fc --dim N N N -c POSCAR gives the harmonic stiffness of every phonon mode and of every irrep subspace at the special q points of the space group (the points --irreps surveys). For every degenerate set, the force constant k = u^+ Phi(q) u^ = mu w of its displacement pattern u = M^-1/2 e normalized to 1 A over the primitive cell (eV/A^2 per primitive cell, the unit of phonopy’s force constants; k < 0 for an imaginary mode), the effective mass mu = 1 / sum_i |e_i|^2/m_i (amu) and k per formula unit (k / Z, Z of the primitive cell); at Γ also k with the uniform translation removed from the pattern, which a polar mode carries and which stores no energy. For every irrep, the force-constant matrix restricted to the subspace of all its modes, with its eigenvalues and trace (at Γ also with the three translations projected out): its lowest eigenvalue is the stability of the whole irrep subspace, and by Sylvester’s law of inertia it has as many negative eigenvalues as the irrep has imaginary modes (checked on every block). A set of an accidental degeneracy (the acoustic GM1 + GM5 set of BaTiO3 P4mm) is split into its irreps by the character projector. k does not change when the cell is enlarged, k per formula unit does; with the amplitude A of crystod-group --supergroup-cif measured over the same cell the harmonic energy is E_cell = k A^2 / 2. SrTiO3 (Pm-3m, 4x4x4): the polar GM4- sets of the Slater, Last and Axe patterns have mu = 20.0154, 56.6097 and 16.0173 amu and k = 0.580737, 5.148077 and 15.352475 eV/A^2 (Slater without the translation 0.826931), the GM4- block has the eigenvalues 0.825380, 5.799761 and 15.456418 (three times each) after the translations, and the R5- rotation has k = -0.077309 eV/A^2 (mu = m_O); Ca3Ti2O7 (I4/mmm, 2x2x2): at X the tilt X3- (k = -1.440908) and the rotation X2+ (k = -1.201008 eV/A^2), the pair of the hybrid improper ferroelectric Cmc2_1, are both unstable, and the six-dimensional X3- block goes down to -1.467490. --qpoint R (or three coordinates) computes one q point, --readfc reads FORCE_CONSTANTS, --nac reads BORN (at exactly Γ phonopy adds no non-analytical term, which a NOTE says), -o FILE names the YAML file, --tolerance sets the degeneracy tolerance. The YAML file mode-resolved-fc.yaml holds the header (space group, nac, Z, the units), every special point, and per computed q point the band_sets, the irrep_hessian blocks and the NOTE lines (notes). Python: crystod.phonon.mode_resolved_force_constants(ph, q), survey_mode_resolved_fc, the dataclasses ModeForceConstants, ModeForceConstantSet and IrrepHessianBlock, and write_mode_resolved_fc_yaml, read_mode_resolved_fc and format_mode_resolved_fc. See crystod-phonon, section 04-12, and the theory in Mode-resolved force constants and irrep-resolved Hessians. Example: example/04-12_phonon_mode_fc (SrTiO3, BaTiO3, Ca3Ti2O7; crystod-example 04-12).

  • New: every crystod-phonon mode that reads FORCE_SETS or FORCE_CONSTANTS (--irreps, --fatband, --lt, --vector, --modulation, --subgroup, --unfold for the child and the parent, --visualize, --mode-resolved-fc) prints a NOTE when the force data do not belong to the POSCAR. The raw (unsymmetrized) force constants are checked for the permutation symmetry Phi(a,b) = Phi(b,a)^T, which phonopy’s symmetrization would otherwise restore silently; above max(0.05 eV/A^2, 0.02 max |Phi|) the NOTE says that the force file probably does not match the POSCAR’s supercell order (atom order or wrapped coordinates) and that the results away from Γ are wrong, and adds, when the POSCAR has a coordinate within 1e-8 of 1, that such coordinates wrap differently in different programs. Calibrated on every force file under example/: clean data give at most 0.01 eV/A^2 (4.2e-4 max |Phi|; SrTiO3 3.6e-3, BaTiO3 1.4e-3), the Ca3Ti2O7 FORCE_SETS computed on a supercell with two Ca wrapped from z = 0.9999999999999999 to 0 gives 3.17 eV/A^2 (Γ right, X wrong). --mode-resolved-fc also writes the NOTE to a top-level notes list of mode-resolved-fc.yaml; a phonopy yaml (--yaml) is not checked. Python: crystod.phonon_irreps.permutation_symmetry_residual and check_force_constants_consistency. See crystod-phonon; testsuite section 04-12.

  • New: crystod-mag --conventional (with --qpoint, and with -c ... --irrep) prints a NOTE under the Display cell: line when the input primitive cell is not in the standard primitive setting of its centring, so that the cell written is a cell of the right number of primitive cells but not the conventional cell (the conventional matrix is applied to the primitive cell as given; the test compares that cell with spglib’s conventional cell, lattice and shape up to a relabelling of the axes; not on a P lattice). The NOTE says that the spin structures and their groups hold for the cell as written and to give the standard primitive cell to get the conventional cell. The cell written, names and checks are unchanged, and a standard primitive cell (the PPOSCAR of phonopy --symmetry) prints no new line. Python: SpinBasisAnalysis.conventional_note, MagneticIrrepAnalysis.conventional_note, crystod.spin_basis.conventional_cell_note; testsuite section 05-01.

  • Fixed: the magnetic space group of a spin arrangement given on a cell whose lattice is not invariant under the point group of the crystal could come out as a subgroup of the true one (spglib keeps only the operations whose rotation maps the lattice of the cell given onto itself). It happened in crystod-mag --qpoint whenever the magnetic cell has such a lattice: also on standard primitive cells, at q points whose diagonal magnetic supercell of an F lattice is not invariant (NiO at X: X3+ 58.404 instead of 128.410, X5+ 14.83 instead of 64.480; at W: 69.526 / 12.64 instead of 140.550 / 74.562; Y2Ir2O7 at X: 25.65, 34.164, 17.15, 19.30 instead of 115.290, 118.314, 95.142 / 91.110, 96.150 / 92.118, and at W 5.17 instead of 82.42; with --conventional, directions at W of Y2Ir2O7 that spglib did not identify), on primitive cells off the standard setting (La2CuO4 with a’ = a + b, --qpoint X --conventional: 2.7 three times instead of 64.480, 66.500, 64.480; NiO a’ = a + b at L; Cr2O3 a’ = a - b at GM), and for a user’s own magnetic supercell such as a 2x1x1 cell of a cubic ferromagnet; --subgroup-poscar, several elements and the direction tables go through the same function. magnetic_space_group now checks whether the lattice of the cell given is invariant under the point group of the crystal (from a primitive cell of the structure without moments); when it is not, it also identifies the structure in the cell of its translations without time reversal, whose lattice is invariant under every rotation of the group, and returns that group when the direct one is incomplete (when that cell cannot be built, MagneticGroupInfo.confirmed is False and a NOTE under the magnetic space group: line says that the group can be a subgroup of the true one): BNS and UNI symbols, type, magnetic point group, responses and collinear class are those of an invariant cell, the operations are those of the cell given (Cartesian rotations, translations in its fractional coordinates, counts per cell given) and the crystal point group of the polarization note is that of the primitive cell. Cells whose lattice is invariant (the PPOSCAR of phonopy --symmetry at Γ, conventional cells, and the magnetic supercells that are invariant, as at X of La2CuO4 or L of NiO) give the same output as before, byte for byte. The --irrep mode was right already (it identifies in the same reduced cell, now one shared implementation, crystod.magnetic_group.unitary_cell). Checked against the direct identification on the m x m x m supercell of the primitive cell that contains the magnetic cell (an invariant lattice) for 3,642 components (La2CuO4, La3Ni2O7 I4/mmm and Cmcm, NiO, Y2Ir2O7, Cr2O3, Mn3GaN; the standard cell and four unimodular re-expressions; every special point, with and without --conventional): no disagreement. Testsuite section 05-11.

  • Fixed: at a q that is not time-reversal invariant crystod-mag --qpoint exported only the real part of a complex order parameter, so one of its magnetic isotropy subgroups was missing, and nothing told which ISOTROPY direction a component was. The spin field of a d-dimensional copy at such a q is Re[eta w exp(2 pi i q.T)] with a complex eta, and the phase of eta is a physical degree of freedom; each copy now exports 2d components, the rows w (comp1 .. comp<d>, bit for bit the fields of before) and their partners i w (comp<d+1> .. comp<2d>, the phase turned by 90 degrees; the partner of a collinear row keeps its axis tag), with one global phase per copy and each partner signed along the crystal axes. For Mn of YMnO3 (P6_3/mmc) at K, K3 comp1 was the direction K3(a;0.974a) (193.255 P6_3/m’cm) and the direction K3(0.282a;a) (193.259 P6_3’/m’cm’) was never exported; it is now comp2, and K2 gives comp1 193.258 K2(0.282a;a) and comp2 193.261 K2(a;0.974a). The new block * Order-parameter directions * (after * Magnetic cell *, at every q != 0) lists the strata of every basis in the magnetic cell: the operations of the crystal that keep the star arm up to sign, the cell translations and time reversal act on the real span of the basis fields, and the strata are enumerated as crystod-mag --parent enumerates them. Each row gives ISOTROPY’s label at a special point (matched to the --parent table by BNS number, index, free parameters and size; a mirror-image representative with a note), the coefficients in the basis components, the magnetic isotropy subgroup, size, index (in the whole grey group) and the exported component on it; a one-parameter direction that no component or (a,a)-type combination lies on is exported as dir<k> with its VESTA file, MAGMOM line, group and class (K5 and K6 of YMnO3: three each, the Cmcm-type groups 63.457-63.465), a direction with more free parameters is listed as free, and a table row whose arms are not all in the magnetic cell as not in it. All 6 + 6 one-parameter rows of K5 and K6 and all rows of K2 and K3 are realized with the table’s size and index. Every component block has the line order-parameter direction: K3(a;0.974a), magnetic isotropy subgroup 193.255 P6_3/m'cm, and the sentence on the global phase under * Magnetic cell * is replaced. Copies of an irrep that occurs more than once at such a q are re-chosen so that the operations taking q to -q keep each copy (Mn of YMnO3 at (1/3,0,0): two copies each of SM2, SM3, SM4, each with its two one-parameter directions). Time-reversal-invariant points keep their components (AlNi3 R: R4+ and R5+ (0,0,a) / (0,a,a) / (a,a,a) are comp1 / aa0 / aaa, no dir), and the files written before are written byte for byte as before (checked for YMnO3 K, AlNi3 R/X/M, TiO2 Z/A/R and ZnO A; the re-chosen copies of a repeated irrep at a q that is not time-reversal invariant differ). Folded onto the P6_3cm phase, K3 comp1 is 0.25 GM1 + 0.75 GM4 and comp2 0.75 GM1 + 0.25 GM4 of the P6_3cm Mn bases. Python: SpinBasisAnalysis.directions (mag.OrderParameterDirection), SpinBasisComponent.direction_label, .direction_subgroup and .direction, mag.direction_table_rows and mag.format_direction_table. See crystod-mag, section 05-06, and the theory in Order-parameter directions of the spin bases. Example: example/05-06_mag_directions (YMnO3 at K, with the P6_3cm structure; crystod-example 05-06).

  • New: crystod-mag -c PARENT --element EL --qpoint K --subgroup-poscar CHILD places the spin bases at a q != 0 on a distorted structure of the same compound whose cell is a magnetic cell of q, and aligns every order-parameter direction with its structural domain. When the structural distortion and the magnetic order share their irrep, the magnetic space group of the distorted phase depends on the angle between the two order parameters; the exported components carry no reference to the structure (for YMnO3, K3 comp1 and comp2 of P6_3/mmc lie 60 degrees from the domains that P6_3cm singles out). CHILD is mapped onto the crystal as crystod-group --correlate --supergroup-poscar --subgroup-poscar maps it (x_parent = P x_child + p between the input cells, printed as * Transformation matrix (parent -> child) *), each of its magnetic atoms takes the spin of its site and cell of the magnetic cell, carried through the fractional components (S_parent = P S_child), and the fields of every basis are decomposed into the irreps of CHILD at GM (* Subgroup structure *: K2 -> GM2 + GM3, K3 -> GM1 + GM4, K5 and K6 -> GM5 + GM6 of P6_3cm, the K rows of --correlate). For every one-parameter direction of * Order-parameter directions *, the domains (images under the operations of the grey group) whose field is one irrep of CHILD are the aligned fields <component>_<irrep>, one per irrep and magnetic space group on CHILD, named after the nearest exported component of the direction. The block * Spin bases on the subgroup structure * lists every exported component as it is (its irreps of CHILD with weights, its magnetic space group on CHILD), every aligned field (irrep, group, angle from the component, coefficients in the comp basis), the directions with no domain in one irrep, and the generic fields; one block per basis (* K3(1) [AFM (q != 0)] on 185_PPOSCAR_YMnO3 *) gives the spins, groups and the MAGMOM line (or the Quantum ESPRESSO input) of every aligned field for the cell of CHILD, written also as POSCAR_YMnO3_spin_K3_K_comp2_GM4.vesta and S185_PPOSCAR_YMnO3_K (CHILD in the atom order of the MAGMOM lines). YMnO3 at K on its P6_3cm phase: the K3(a;0.974a)-type direction aligned with the structural domain is GM1, P6_3cm (185.197, type I); the K3(0.282a;a)-type direction at 90 degrees to it is GM4, P6_3’cm’ (185.200); the exported comp1 as is gives P3c1 (158.57); K2 gives GM2 P6_3c’m’ (185.201) and GM3 P6_3’c’m (185.199); the Cmcm-type directions of K5 and K6 give Cmc2_1, Cm’c’2_1 (GM5), Cm’c2_1’ and Cmc’2_1’ (GM6), and their P-62m-type directions have no domain in one irrep. Every aligned field lies in the span of the bases that crystod-mag -c CHILD --qpoint GM finds for its irrep and, in the magnetic cell of the parent, has the magnetic isotropy subgroup of its direction (checked for YMnO3 K and for AlNi3 R on an R-point I4/mmm child, a time-reversal-invariant q). The bases, files and groups of the parent cell are unchanged by the option. CHILD must be a primitive cell, q != 0 must fold onto its GM (an ERROR gives q . a’ otherwise), and the mapping and the groups on CHILD use 0.01 A or --tolerance when larger. Python: analyze_spin_basis(..., subgroup_poscar=CHILD) fills SpinBasisAnalysis.subgroup (mag.SubgroupAlignment with mag.SubgroupSpinField rows), mag.subgroup_table_rows and mag.format_subgroup_alignment. See crystod-mag, section 05-07. Example: example/05-06_mag_directions (the second command of its README; crystod-example 05-06).

  • New: crystod-group --correlate --supergroup-poscar P --subgroup-poscar C also saves its report, word for word what it prints, as CORREL_<formula>_<G>_<H> in the current directory (the reduced formula of the supergroup structure, as in sym_mode_<formula>, and the short symbols of G and H without _ and /: CORREL_YMnO3_P63mmc_P63cm, CORREL_SrTiO3_Pm-3m_I4mcm); --spinor runs append _spinor. A closing * Output files * block names the file; --output-dir DIR and --no-files act as for --supergroup-cif. crystod.group.subgroup_correlation and the MCP tool write no file; its result has the new field parent_formula.

  • New: a shared rule for terminal reports: a command whose result is a report printed on the terminal also saves it, word for word, in a file named by the command, closed by an * Output files * block with the line Report written to: FILE (this output); --no-files prints only, and the environment variable CRYSTOD_NO_REPORT (any value but empty or 0) turns the saving off for every command. The CORREL report of crystod-group --correlate --supergroup-poscar is the first to use it (unchanged byte for byte). Python: crystod.cli.common.SavedReport (a context manager over TeeStream) and crystod.cli.common.file_name_tag (P6_3/mmc -> P63mmc). The test suite runs every command with CRYSTOD_NO_REPORT=1 unless a check passes reports=True; section 02-09 checks the class.

  • Changed: the report of crystod-mag --qpoint is renamed from mag_salc_<formula>_<element>_<q> to samm_<formula>_<element>_<q> (samm = symmetry-adapted magnetic moments; samm_AlNi3_Ni_GM), and two more crystod-mag modes save their report, word for word what they print: the survey (no --qpoint) as samm_<formula>_<element>_survey (samm_AlNi3_Ni_survey) and --qpoint Q --classify-only (with or without --show-operations) as samm_<formula>_<element>_<q>_classify (samm_TiO2_Ti_GM_classify, _conv with --conventional). Both close with * Output files * / Report written to: ... (this output), as the --qpoint report does; they still write no VESTA file and no magnetic-cell POSCAR. The new --no-files prints only (accepted with the survey and --classify-only), CRYSTOD_NO_REPORT=1 too; --classify-only --subgroup-poscar, --parent and an ERROR exit write no file. Python: crystod.spin_basis.survey_report_file_name(formula, element) and classify_report_file_name(analysis); the MCP tools write nothing. Old mag_salc_* files are not renamed. Tests in sections 05-02, 05-03 and 05-06.

  • New: crystod-phonon --modulation, --subgroup, --vibration --qpoint and --unfold, and crystod-md --summary and --project, save their terminal report, word for word what they print. --modulation without --mode (mode table, star of q) as modulation_<formula>_<q> (modulation_ScF3_R), with --mode as modulation_<formula>_<tags> next to the structure, <tags> = the MPOSCAR name without MPOSCAR_ (modulation_ScF3_R_mode1+2+3_R4+_R-3c); --subgroup as SUBGROUP_<formula>_<q> (SUBGROUP_SrTiO3_R, _all without --qpoint), with the reproducing --modulation command lines of --modulate; --vibration --qpoint Q as vibration_<formula>_<q> and with --mode-index N as vibration_<formula>_<q>_space<N>[_comp<M>] (_comp<M> for a space of dimension 2 or more), and the displaced structure of --mode-index is now written by default to VPOSCAR_<formula>_<q>_space<N>[_comp<M>] when no --output is given (before, nothing was written); --unfold as phonon_unfold.txt (the -o prefix of the .pdf/.dat); crystod-md --summary as MDSUM_<formula> and --project as <prefix>_stats.txt (MDPROJ_ScF3_stats.txt, or -o PREFIX). A mode with its own * Output files * block lists the report there. --no-files (new in both commands) prints only; --vibration --list-qpoints, crystod-md --adp and the other crystod-phonon modes are unchanged. crystod-phonon --irreps --raman-tensor also writes the printed Raman tensors to phonon_irreps.yaml, under the new key raman_tensors (per Raman-active Γ irrep the label, Mulliken symbol, dimension, multiplicity, constants, the tensors as printed and their coefficients); the other keys are unchanged. Tests in sections 04-03, 04-07 to 04-09, 04-11, 06-02 and 06-03.

  • New: the crystod SALC, hybridization and star-of-k runs, crystod-mol --symmetry and its SALC runs, and the crystod-search table save their terminal report, word for word what they print. crystod -c POSCAR --element EL --orbital ORB (also with --show-irrep-table or --visualize) as salc_<formula>_<EL>_<ORB>[_<k>] (salc_ScF3_F_p, salc_SrTiO3_Ti_d_R), _spinor appended with --spinor, --axial as salc_<formula>_<EL>_axial[_<k>]; --atomic-orbital Sc_d F_p as hybrid_<formula>_Sc_d-F_p[_<k>][_spinor]; --star-of-k --kpoint K as star_of_k_<formula>_<k> (<formula> the reduced formula of the structure, <k> only for one requested k point: its special-point name, or its coordinates elsewhere, 0.25_0_0). crystod-mol as mol_sym_<formula> and mol_salc_<formula>_<EL>_<ORB> (the full molecular formula in Hill order: mol_salc_C6H6_C_p, mol_sym_H3N), crystod-search QUERY and --get as mp_search_<query>.txt (mp_search_Sr-Ti-O.txt, mp_search_mp-5532.txt; blanks, / and ? dropped, * written any). --visualize lists the report in its own * Output files * block. --no-files (new in the three commands) prints only; it is refused with the modes that save no report (--diagram, --band, --dos, the levels viewer, --check-symmetry, --unfold, crystod-mol --diagram), which are unchanged. crystod --extract-irrep without -o now writes its YAML as band_irreps_<formula>.yaml (the -o FILE writer, OVERWRITTEN when it was there, as --check-symmetry does with vasp_symmetry_<formula>.yaml); --no-files or CRYSTOD_NO_REPORT=1 write none. The MCP server runs its commands with CRYSTOD_NO_REPORT=1. Tests in sections 01-02, 01-03, 01-05, 01-06, 01-08, 07-01, 07-03 and 10-01.

  • New: crystod-group --tensor KIND -c POSCAR, --cif-axis -c FILE and crystod-slab save their terminal report, word for word what they print, and the sym_mode_<formula> file of crystod-group --supergroup-cif becomes the whole report. --tensor KIND -c POSCAR as TENSOR_<formula>_<kind> (TENSOR_ZnO_piezoelectric, TENSOR_ZnO_raman; a Jahn symbol with [ ] written - and { } written =: TENSOR_ZnO_V-V2-), --cif-axis -c FILE as CIFAXIS_<formula> (CIFAXIS_La3Ni2O7), both in the current directory and closed by * Output files * / Report written to: ... (this output); --no-files is now accepted with these two forms and prints only; --tensor --pg/--sg (a lookup) writes nothing, as before. crystod-slab as SLAB_<formula>_<selection> in --output-dir beside the slab POSCARs (SLAB_SrTiO3_100 for one --index 1 0 0, the plane family as in the POSCAR names; SLAB_SrTiO3_max1 for --max-index 1; SLAB_SrTiO3_list for --index-list or several --index; the dialogue names it after its equivalent command line and the file carries the questions and answers), with the Report written to: line inside its * Output files * block, whose none (no slab was generated) / none (every slab was skipped) then read no slab file (...); the report is overwritten on a rerun (--force concerns the POSCARs only), and --no-files, a quit of the dialogue and an ERROR exit write none. sym_mode_<formula> held only the transformation matrix and the decomposition table; it now holds everything the run prints (the structures, the cell relation, the atom pairings and displacements, the distortion amplitude, the transformation matrix, the table with its notes, the normalized mode components, the citation and the * Output files * block), and the line Decomposition table saved to sym_mode_<formula> of that block reads Report written to: sym_mode_<formula> (this output); --output-dir and --no-files act as before, and CRYSTOD_NO_REPORT=1 now leaves out sym_mode_<formula> while the VESTA files are still written. Nothing in the source tree read the old layout of sym_mode_<formula>. Tests in sections 02-06, 02-15, 02-16 and 09-01.

v0.4.8#

Highlights (details in the entries below):

  • crystod --check-symmetry: the Born effective charges, dielectric, piezoelectric, elastic and internal-strain tensors of a finished VASP run, each against the form the symmetry of its structure allows (raw and symmetrized components, residuals, relations), with the new tensor kind piezoelectric-e of crystod-group --tensor (VASP’s e, no factor 2).

  • crystod-group --correlate --supergroup-poscar P --subgroup-poscar C: the offline counterpart of DCORREL, the small irreps of the low-symmetry phase that every irrep of the parent becomes at every special k point, with --spinor also for the double-valued irreps; the compatibility relations along a line are now --correlate-kpath.

  • crystod-mag --qpoint also writes the magnetic cell as a POSCAR, its atoms in the order of the MAGMOM lines (atom by atom, as in phonopy’s SPOSCAR).

  • The shared section numbers of testsuite.py, example/ and this manual are regrouped by command and run from 1 to 57.

  • Changed: the copyright notice of LICENSE (also that of crystod-mcp) and of the documentation footer names Yasuhide Mochizuki alone. The article to cite and its authors, and the contributors listed in the README, are unchanged.

  • Changed: the section numbers. The features added since v0.4.4 had taken the next free numbers at the end (49, 49d, 51-56), away from their commands; they now sit inside their command groups, so the shared section numbers of testsuite.py, the example/ directories and the numbered sections of this manual run from 1 to 57, grouped by command: 1 library core, 2-10 crystod, 11-28 crystod-group, 29-31 crystod-bz, 32-41 crystod-phonon, 42-45 crystod-mag, 46-48 crystod-md, 49-51 crystod-mol, 52 Python API, 53-54 crystod-xrd, 55 crystod-search, 56 crystod-slab, 57 crystod-example. The order of the earlier sections is kept, and every later feature closes the group of its command, before that command’s regression section: 7 crystod --check-symmetry (provisionally 49d), 8 crystod --extract-irrep (was 49), 9 crystod --unfold (was 54), 27 crystod-group --correlate-double-group (was 55), 39 crystod-phonon --unfold (was 51), 40 crystod-phonon --visualize (was 52), 44 crystod-mag --parent (was 56), 56 crystod-slab (was 53) and 57 crystod-example (was 50). Sections 1-6 keep their numbers and the others move up: 7 -> 10, 8-23 -> 11-26, 24 -> 28, 25-27 -> 29-31, 28-34 -> 32-38, 35 -> 41, 36-37 -> 42-43, 38 -> 45, 39-41 -> 46-48, 42-44 -> 49-51, 45 -> 52, 46-48 -> 53-55; for example 28_phonon_irrep is now example/32_phonon_irrep (python testsuite.py 32, crystod-example 32) and 17_isotropy_subgroup is 20_isotropy_subgroup. The --subgroup section of the crystod-phonon page (now 41) moves after the phonon mode viewer (40). Scripts that call python testsuite.py N or crystod-example N, or read files below example/NN_*, need the new numbers. The commands and their options are unchanged. The entries of the released versions below keep the numbers of their release (their links lead to the renumbered sections).

  • New: crystod --check-symmetry FILE [--outcar OUTCAR] checks the response tensors of a finished VASP run against the symmetry of its structure. From the vasprun.xml (Born effective charges, the electronic and ionic dielectric tensors) and the OUTCAR (also the piezoelectric e, the elastic moduli and the internal-strain tensors), every tensor is projected onto its symmetry-allowed form by the group average (Z* and the internal-strain tensors over the site-symmetry group of their atom, made consistent over each orbit by the space group) and printed as its independent components, named and oriented as in crystod-group --tensor -c, raw and symmetrized, with the relative residual (Frobenius norm of the full Cartesian tensor), the largest deviating component and the relations; for Z* also the isotropic and antisymmetric parts and the acoustic sum rule (reported, not imposed). --only selects tensors, --tolerance sets spglib’s tolerance, and the YAML file vasp_symmetry_<formula>.yaml (-o FILE) adds the full matrices. On a DFPT run of SrTiO3 I4/mcm (ISYM = 2), Z* and the dielectric tensors are symmetric to 1e-15, while the ionic-relaxation elastic moduli break C44 = C55 (−14.3888 and −14.4631 kBar, relative residual 2.5e-4) and the shear components of the internal-strain tensors break the site symmetry (the apical O on 4a, 422: a forbidden component of 0.035 eV/Å). See crystod, section 7.

  • New: the tensor kind piezoelectric-e of crystod-group --tensor, the piezoelectric stress coefficients e_ijk that VASP and Quantum ESPRESSO print (e_iL = e_ijk, no factor 2). It has as many independent components as Nye’s d (piezoelectric, unchanged), with other relations in the trigonal and hexagonal classes (3m: e16 = −e22, d16 = −2 d22). A Jahn symbol V[V2] given to --tensor is now described as the symmetry type of both kinds.

  • New in Python: crystod.group.vasp_symmetry_report, VaspSymmetryReport, format_vasp_symmetry and symmetrize_tensor (the group average of any tensor, or of one tensor per atom, over a point group, a site-symmetry group or a space group), and the readers crystod.vasp_io.read_vasprun_response and read_outcar_response, which take the Born, dielectric, piezoelectric, elastic and internal-strain tensors, the ionic steps of a vasprun.xml and the magnetization tables of an OUTCAR by exact headings (pymatgen’s Outcar.read_piezo_tensor and read_elastic_tensor and phonopy’s get_born_OUTCAR fail on the output of VASP 6.5.1).

  • New: crystod-group --correlate --supergroup-poscar P --subgroup-poscar C lists, for every special k point of the space group G of the high-symmetry structure P, the small irreps of the space group H of the low-symmetry structure C that every irrep of G becomes, the offline counterpart of DCORREL of the Bilbao Crystallographic Server. The two structures are mapped as by --supergroup-cif (sublattice basis, origin, the operations of the subgroup file as parent operations; the transformation block is printed in DCORREL’s convention). Each parent star is split into the stars of H it falls onto, one block per pair, with the arm counts: SrTiO3 Pm-3m -> I4/mcm gives R4+(3) -> GM1+(1) [A1g] + GM5+(2) [Eg], GM4-(3) [T1u] -> GM3-(1) [A2u] + GM5-(2) [Eu], X (2 of 3 arms) -> X with X5+(2) -> X2+(1) + X3+(1) and X (1 arm) -> M with X1+(1) -> M3+(1). The special points of H that no special point of G reaches come from parent symmetry lines and are listed as well, with the number of merged arms: 2 x LD3(2) -> 2 N1(2) and 2 x Z3(1) -> P1P3(2) (I4/mcm), 2 x LD3(2) -> T1T2(4) (R-3c). The labels of H refer to the ISO-IR frame of the subgroup file, printed under * Subgroup *; Mulliken symbols are added at GM on both sides; small irreps that time reversal pairs are one term (P1P3). Checked against DCORREL for SrTiO3 I4/mcm, BaTiO3 P4mm and AlF3 R-3c (also with the parent origin on the A site, p = (1/2,1/2,1/2)): every row at the special points of Pm-3m and on the LD and Z lines that feed N, P, L and T is identical; DCORREL in addition omits the two M arms that fall onto X of I4/mcm, which this command lists (M5+ -> X1+ + X4+). Every row is checked (the character at the identity, the dimensions per arm and over all stars of H, the k name of every label, the same decomposition on every arm of a star of H); 4-6 s per pair. Python: crystod.group.subgroup_correlation(P, C, tolerance=0.01) returns a SubgroupCorrelation of KpointCorrelation blocks of IrrepCorrelation rows, printed by format_subgroup_correlation; MCP: crystod_correlate(supergroup_poscar=..., subgroup_poscar=...). Example: example/19_correlate (crystod-example 19).

  • Changed: the compatibility relations along a symmetry line are crystod-group --correlate-kpath --sg SG --kpoint K0 [K1] [--line L] (was --correlate --sg), with the same output and checks; --correlate --sg now stops with a one-line hint to the new name. The Python function compatibility_relations and the MCP form (space_group + kpoints) are unchanged.

  • Removed: crystod-group --correlate --parent SG --irrep IR --order-parameter ... [--irrep-list ...] (the subduction of parent irreps to the Gamma point of the isotropy subgroup of a direction), the option --irrep-list, and the Python names subduce_to_child, Subduction and format_subduction. It could not describe a subgroup reached by two irreps (Pnma = R4+ + M3+) of a real pair of structures and listed only the Gamma part of H. Its results are the GM rows of the new --correlate --supergroup-poscar P --subgroup-poscar C (SrTiO3 I4/mcm R4+ -> GM1+ [A1g] + GM5+ [Eg], R5+ -> GM4+ [B2g] + GM5+ [Eg]; AlF3 R-3c R4+ -> GM1+ [A1g] + GM3+ [Eg]), which replaces it together with subgroup_correlation; --correlate with --parent, --irrep or --order-parameter stops with a hint to that form. The MCP form parent + irreps + direction of crystod_correlate is replaced by supergroup_poscar + subgroup_poscar.

  • New: crystod-group --correlate --supergroup-poscar P --subgroup-poscar C --spinor adds the double-valued (spin-orbit) irreps to every block, the double-group half of DCORREL. After the unchanged single-valued rows, each block lists the double-valued small irreps of G at that k and those of H they become, named as crystod --spinor and --correlate-double-group name them (G exactly as --correlate-double-group --sg Pm-3m, H on the single-valued labels of its printed frame): SrTiO3 Pm-3m -> I4/mcm -R8+(4) -> -GM6+(2) + -GM7+(2), -X6+(2) -> -M6+(2) (the X arm along the fourfold axis), 2 x -LD6(2) -> -N2/-N2(4), 2 x -Z5(2) -> -P6/-P7(4); AlF3 R-3c -R8+(4) -> -GM4+/-GM5+(2) + -GM6+(2), 2 x -LD6(2) -> -T5/-T6(4). A time-reversal pair is one term A/B and an irrep doubled by time reversal A/A, with the pair dimension. Characters only: the arm characters of the double-valued small irreps of G (conjugated with the SU(2) sign of every operation) are decomposed into those of H, built in the same Cartesian frame so that every operation has the same SU(2) matrix in both groups (checked); every run also checks Res_H(Gamma x D(1/2)) = Res_H(Gamma) x D(1/2) for every single-valued irrep of G on every arm of H. Checked against DCORREL for the three pairs through the Bilbao numbering, established by the characters of the irrep package tables (by D x D(1/2) fingerprints for R-3c): all 27 + 28 + 24 double-valued rows agree (Pm-3m Γ6..Γ11 = -GM6+, -GM7+, -GM6-, -GM7-, -GM8+, -GM8-). Python: subgroup_correlation(..., spinor=True) (rows with double_valued=True, notes in spinor_notes); MCP: crystod_correlate(..., spinor=True).

  • New: every crystod-mag --qpoint run that writes files also writes the magnetic cell as a POSCAR, S<POSCAR name>_<q> in the current directory, in the atom order of the printed MAGMOM lines, so a MAGMOM line goes into the INCAR of a noncollinear VASP run on that file as it is: -c POSCAR_VO2_P42mnm --qpoint A (or 0.5 0.5 0.5) writes SPOSCAR_VO2_P42mnm_A, the 2x2x2 cell with V O / 16 32 and 48 MAGMOM triples; -c ../139_PPOSCAR_La3Ni2O7 --qpoint 0 0 0.5 --conventional writes S139_PPOSCAR_La3Ni2O7_X_conv; at q = 0 the file is the input cell (S221_PPOSCAR_AlNi3_GM) or its conventional cell. The name takes the basename of -c and the q part of the mag_salc_* report (GM for GAMMA, _conv with --conventional); the file is VASP 5 with direct coordinates and the same cell and atom order as the spin directions listings and the VESTA files. One new line under * Output files *, Supercell POSCAR written to: SPOSCAR_VO2_P42mnm_A (atom order of the MAGMOM lines); the survey, --classify-only and an ERROR exit write no file. Python: crystod.spin_basis.supercell_poscar_name(analysis, poscar) and write_supercell_poscar(analysis, path, poscar), and the new field SpinBasisAnalysis.supercell_cell_of_atom. Tests in section 42 (the SPOSCAR against the input cell at GM, against the STRUC and VECTR blocks of a VESTA file and the MAGMOM line at R, the basename rule, no file from the survey or --classify-only).

  • Changed: the atoms of the magnetic cell of crystod-mag are atom-major, as in the SPOSCAR of phonopy (each atom of the primitive cell followed by its images in the other cells); they were translation-major, which interleaved the species (VO2 2x2x2 at A: V V O O O O V V O O O O ..., now V x 16 then O x 32; AlNi3 at R: Al1..Al8 then Ni9..Ni32), so a POSCAR of that cell needed a POTCAR block for every species of every primitive cell (16 for VO2 at A). The order of the spin directions listings, the MAGMOM lines, the Quantum ESPRESSO input and the STRUC/VECTR blocks of the VESTA files changes for q != 0 and for --conventional; the spins, the groups, the classes and every other line are unchanged (checked atom by atom against the old output for VO2 at A, AlNi3 at R and La2CuO4 at X with --conventional), and at q = 0 without --conventional nothing changes. The READMEs of example/42_spin_basis and example/43_magnetic_group are regenerated.

v0.4.7#

Highlights (details in the entries below):

  • crystod --unfold: the electronic bands of a distorted phase unfolded onto the Brillouin zone of its high-symmetry parent, from the WAVECARs of two ordinary VASP band runs, with the parent eigenvalues drawn over them; --unfold-kpoints writes the child k points that cover the whole parent path.

  • crystod-group --correlate-double-group: the double-valued (spin-orbit) small irreps that each single-valued small irrep at a k point becomes, in any space group; crystod --spinor names the double-valued irreps (Bradley & Cracknell numbering).

  • crystod-mag --parent SG --qpoint K: the magnetic isotropy subgroups (BNS) of every magnetic irrep of a k point, the magnetic counterpart of crystod-group --parent, checked against ISOTROPY’s table.

  • crystod -c POSCAR --element EL --axial: the irreps of the spin configurations of an element’s sites, in the layout of the orbital SALC.

  • crystod-mag --qpoint: UNI symbols, the (a,a) / 110 directions where symmetry singles them out, --show-operations, and the report saved as mag_salc_*.

  • New: crystod-mag --parent SG --qpoint K (or --irrep IR) lists the magnetic isotropy subgroups of the paramagnetic grey group SG1’, the magnetic counterpart of crystod-group --parent SG --kpoint K. Every magnetic (time-odd) irrep of the k point is listed with every order-parameter direction, its BNS magnetic space group, the cell size and the index (the number of domains): Pm-3m GM4+ gives (0,0,a) 123.345 P4/mm'm' 6, (a,a,a) 166.101 R-3m' 8, (0,a,a) 65.486 Cmm'm' 12, plus the in-plane directions (0,a,b) P2'/m' and (a,a,b) C2'/m', which time reversal adds to the structural strata. R4+ gives the type IV groups I_c4/mcm, R_I-3c, and so on. No structure file is needed; mR4+ is accepted. In Python: mag.magnetic_isotropy_subgroups, mag.magnetic_isotropy_subgroups_at_kpoint, MagneticIsotropySubgroup, MagneticIsotropyAnalyzer. Validated against the magnetic isotropy subgroups tabulated by the ISOTROPY Software Suite: all 16721 subgroups of its 4777 irreps at every special k point of the 230 space groups (testsuite section 56; the data files are not in the repository).

  • Fixed: crystod-mag on Python 3.10. pymatgen 2025.10.7, the last release for Python 3.10, fails with a circular import when its maggroups module is imported before pymatgen.core, so every BNS symbol lookup (the magnetic space groups of --qpoint, --classify-only and --parent) stopped with an ImportError; pymatgen.core is now imported first.

  • Fixed: mag.magnetic_space_group (and with it crystod-mag --qpoint) checks spglib’s name of the group against the type and the unitary and family space groups of the operations. spglib 2.x names 37.184 C_ccc2 and 37.186 C_Acc2 as 36.177 and 36.179, and cannot name 37.185 C_acc2, because its database holds operations of type Cmc2_1 for two of them. These three are now named from their unitary and family groups. Any other contradiction leaves the group unidentified rather than misnamed; none occurs in the 16721 subgroups above.

  • New: crystod -c POSCAR --element EL --axial gives the irreps of the spin (magnetic) configurations of the element’s sites: one axial vector (Rx, Ry, Rz) per site in place of an orbital shell, at every special k point or at --kpoint. SrTiO3 with Ti on 1a: GM4+(3) at Γ, R4+(3) at R, X3+(1) + X5+(2) at X, M3+(1) + M5+(2) at M, printed under * Basis * / Rx, Ry, Rz in the layout of the orbital SALC. The character is det(R) times that of the p shell. At a time-reversal-invariant point a complex irrep and its conjugate are printed once under the pair label (2.0 [GM3+GM4+(2)]), exactly the terms of the crystod-mag survey. In Python: CrystalOrbital.irreducible_decomposition(k, EL, "axial"). Not with --spinor. Testsuite section 2 compares it with the explicit spin matrices of crystod-mag over 23 space groups, and over all 230 (4050 element/k-point cases) with CRYSTOD_AXIAL_SWEEP=1.

  • New: crystod-mag --qpoint prints the unified (UNI) magnetic space-group symbol of B. J. Campbell, H. T. Stokes, J. M. Perez-Mato and J. Rodriguez-Carvajal, Acta Cryst. A78, 99 (2022) next to the BNS symbol. Every component gets a line UNI symbol: P4/mnc.1'_I[I4/mmm]; point group 4/mmm.1' after its magnetic point group, and the * Magnetic groups and collinear classes * table a last column MSG (UNI) with a note line under it; the existing lines and columns are unchanged. The UNI symbol is the BNS symbol in the same standard BNS setting with the generator of {1, 1’} after a period (Pnma.1 type I, Pnma.1' type II, unchanged for type III); a type IV group carries its anti-translation on 1' and its family space group in brackets (P_I4/mnc -> P4/mnc.1'_I[I4/mmm], R_I-3c -> R-3c.1'_c[R-3m]), so the grey point group of a type IV group can be read from the symbol. The 1651 symbols are bundled as crystod/magnetic_unified.txt (from data_magnetic.txt of the ISOTROPY Software Suite, identical to Table S2 of the paper; source note in LICENSE; script/make_magnetic_unified.py rewrites it). Python: MagneticGroupInfo.uni_symbol and .uni_point_group, crystod.mag.unified_symbol(bns_number) and unified_point_group_symbol(mpg, type); uni_number stays spglib’s serial number. MCP crystod_mag_classify: the same column and line. Section 37 checks the table against pymatgen’s BNS symbols and the rules of the paper for all 1651 groups (types I-III, the type IV body, anti-translation subscripts S -> c / I and R_I -> c, the point group of the family group, the UNI point group) and the ten cases of Table 1 of the paper; the example README of section 37 and doc section 37 show the new column.

  • New: crystod-mag --qpoint ... --show-operations lists, for every component, the operations of the paramagnetic group G + theta G that the arrangement keeps and those it breaks, one per coset of the lattice translations, as Seitz symbols in the notation of Bradley and Cracknell: {C4z|0}, {IC2[1-10]|0}, {C4z|1/2,1/2,1/2} (P4_2/mnm), and {R|t}' = theta{R|t} with time reversal; t in the conventional cell, the axes x, y, z of an orthogonal conventional cell or [uvw]. For moments along c on the Cu site of La2CuO4 (I4/mmm, the Ce site of CeRu2Si2) the kept ones are {E|0}, {C4z|0}, {C2z|0}, {C4z^3|0}, {I|0}, {IC4z|0}, {IC2z|0}, {IC4z^3|0} and {C2x|0}’, {C2y|0}’, {C2[110]|0}’, {C2[1-10]|0}’ with their products by I, the kernel of the time-odd irrep mGM3+ (I4/mm’m’). The lines follow collinear order: in the listing; with --classify-only they form a block * Symmetry operations kept and broken * after the table; where q != 0 an operation kept both ways (with a magnetic-cell translation and with an anti-translation, type IV) gets a note line. Without the option nothing changes. The kept operations are those of the magnetic space group (spglib), each matched to the operation of the crystal with the same rotation and a translation that differs by a lattice vector: no operation was left unmatched over P4_2/mnm, Im-3m (H), Pm-3m (Γ, R), P6_3cm, R-3c, P2/m, Fm-3m (L) and I4/mmm (Γ, X). In Python, crystod.spin_basis.parent_operations(analysis, component) (ParentOperation: symbol, rotation, translation, kept, kept_primed) and format_parent_operations; SpinBasisAnalysis gains primitive_lattice, conventional_lattice, parent_rotations and parent_translations. Section 37 checks the I4/mmm lists against the kernel of mGM3+, the 4_2 screw of P4_2/mnm and the type IV note at H of bcc Fe.

  • New: crystod-mag --qpoint saves its whole report, exactly as printed, in mag_salc_<formula>_<element>_<q> in the current directory, next to the VESTA files (mag_salc_AlNi3_Ni_GM; mag_salc_AlNi3_Ni_R for --qpoint R or 0.5 0.5 0.5), so that > mag_salc_... is no longer needed. The formula is the reduced formula of the primitive cell, as in the VESTA names; the q point is named as in Selected q-point:, with GM for GAMMA; --conventional adds _conv. The * Output files * block ends with Report written to: mag_salc_AlNi3_Ni_GM (this output); a file of the same name is overwritten. The survey mode (no --qpoint), --classify-only and a run that stops with an ERROR write no report, and warnings on the standard error stream are not in it. In Python, crystod.spin_basis.report_file_name(analysis) gives the name. Section 36 checks the file against the standard output (Γ, R, --conventional) and that the survey, --classify-only and an ERROR exit write none.

  • New: crystod-mag --qpoint also exports the (a,a) / (a,a,0) direction of the order parameter of a two- or three-dimensional basis, wherever symmetry singles it out, next to its components (the (a,0) / (a,0,0) directions) and to 111 (x + y + z, the (a,a,a) direction, as before). The combination is the equal-weight sum of two components; it is exported when the operations that keep it (time reversal included) fix no other direction of the basis, so that it has an isotropy subgroup of its own (new _singled_out and _combined_components in crystod/spin_basis.py). It is named after the sum of the component directions when the components have direction tags, else in the order-parameter notation over the components in their order (aa, aa0, aaa); since the test does not depend on the tags, a cell rotated about c gives the same arrangements (rutile rotated by 30 degrees: aa for x). Examples: Ce of CeRu2Si2 (I4/mmm) at Γ, GM5+ dipole x, y (Im’m’m) and 110 (Fm’m’m, 69.524), the arrangement that was missing; Ti of TiO2 (P4_2/mnm), GM5+ dipole and octupole 1m10, 110 (Cmm’m’) and x (Pnn’m’, 58.398); Ni of AlNi3 (Pm-3m) at Γ, GM4+ and GM5+ x, y, z, 110 (Cmm’m’, 65.486) and 111, the GM5+ octupole allowing a net magnetization only in the 110 arrangement; at M, M5+ 110 (P_Bmna) and M5- aa (P_Bmma); at X, X5± 101 (C_cmcm); at R, R4+ and R5+ (comp<N> components) aa0 (I_bmma) and aaa; Ir of Y2Ir2O7 (Fd-3m), GM4+ and GM5+ octupoles (comp<N>) aa0 (Imm’a’, 74.559) and aaa (R-3m’, R-3m). Nothing is added where (a,a) is not special: the E irreps of hexagonal and trigonal crystals (Cr2O3, LuFeO3), whose x and y are already the two special directions, and the T irreps of the cubic groups m-3 and 23 (Pm-3, Pa-3, P23, I23 …), where the symmetry of x + y fixes the whole (a,b,0) plane and only 111 is added. The new components are printed and written like the others (POSCAR_CeSi2Ru2_spin_GM5+_dipole_110_conv.vesta) and are rows of the * Magnetic groups and collinear classes * table (and of --classify-only); no existing line or file changes. Where the components of a comp<N> basis are not the (a,0,0)-type partners fewer combinations come out, never a general direction; over the 228 structures of example/test_POSCARs at Γ, no error. The example READMEs of example/36_spin_basis and example/37_magnetic_group are rerun (only additions besides the UNI lines of the entry above in section 36), the 21 new VESTA files are added and the 110 existing ones are unchanged byte for byte; sections 36 and 37 check the new components (I4/mmm Eg, P4_2/mnm, Pm-3, R-3c, AlNi3 at M and R, the rotated rutile cell).

  • New: crystod-group --correlate-double-group --sg SG [--kpoint K] gives the double-valued (spin-orbit) small irreps that each single-valued small irrep at a k point becomes, Γ x D(1/2) = Σ_j m_j Δ_j, for every space group. --sg Pm-3m --kpoint R prints R1+(1) -> -R6+(2), R4+(3) -> -R6+(2) + -R8+(4), R4-(3) -> -R6-(2) + -R8-(4) (the j = 1/2 and j = 3/2 levels of the Pb 6p band of CsPbI3), …, the dimension after every label so that each line shows the doubling, under the * Space group * and * Compatibility relations * blocks of --correlate --sg. The single-valued labels are the ISO-IR labels of every other mode and the double-valued names those of crystod --spinor (Bradley & Cracknell’s numbering, with the NOTE: lines of --spinor where it differs: 32, 3m, -3m and the cyclic co-groups with complex pairs). --kpoint takes a special-point name or three coordinates (any arm, any k + G; off the special points, the relations on that line, plane or general point, e.g. --kpoint 0 1/4 0 gives DT1(1) -> -DT6(2) and DT5(2) -> -DT6(2) + -DT7(2)); without --kpoint, every special point of the group is listed, one block each. Every run checks the labels against the ISO-IR table at a special point (off the special points, that they all carry one k name), the dimensions of every row (2 dim Γ) and the reciprocity of every double-valued irrep (Σ_i m_ij dim Γ_i = 2 dim Δ_j). Run on all 230 space groups at every tabulated special point (1381 k points, 5408 relations: no failed check, no generic name), against the Koster tables (O_h at Γ and R, C1, Ci, D6h, C4v on Δ, Td at P of I-43m and its -k partner PA, the four X irreps of diamond onto -X5) and against crystod --spinor on real structures. In Python, crystod.group.spin_orbit_relations, SpinOrbitRelation and format_spin_orbit_relations. Documented in crystod-group; example example/55_correlate_double_group; tested in the new section 55 (CRYSTOD_DOUBLE_GROUP_SWEEP=1 adds the sweep over all 230 groups).

  • New: crystod -c POSCAR --element EL --orbital L --spinor and crystod --atomic-orbital ... --spinor name the double-valued (spinor) irreps — Ti 3d of SrTiO3 at Γ is 1.0 [-GM7+(2)] + 2.0 [-GM8+(4)], at R 1.0 [-R6-(2)] + 2.0 [-R8-(4)] — where they printed generic keys such as irrep_3(2), because the bundled ISO-IR tables hold single-valued irreps only. The names are those --extract-irrep and --diagram --vasp --vasp-engine overlap already gave spin-orbit runs, from the same namer, now public as crystod.wavecar_irreps.double_valued_names: a double-valued irrep D is fingerprinted by the decomposition of D x D(1/2) into the single-valued ISO-IR irreps at k and named -K<n><p> with the numbering of C. J. Bradley and A. P. Cracknell, The Mathematical Theory of Symmetry in Solids (Clarendon Press, Oxford, 1972), Table 6.5 (the Γ numbers of Koster, Dimmock, Wheeler and Statz, 1963): the overbar written as a leading -, an index that continues after the single-valued irreps, a parity suffix where the single-valued irreps carry one, the classes ordered by dimension and then by fingerprint, parity partners sharing the index, and a tied complex-conjugate pair (little co-groups 2, m, 2/m, 32, 3m, -3m) ordered +i first at the first operation where the two differ, in the SU(2) lift whose two-fold rotations turn by +pi about the ISO-IR frame axis, except that in 2, m and 2/m the unique axis turns by +pi about minus that axis, B&C’s C2z = (C4z-)^2, so that -GM3 is their (Koster’s) Γ3, the irrep with chi(2) = -i in the lift about +[uvw] (Double-valued irreps). At Γ the names agree with Table 6.5 for 26 of the 32 point groups. The two exceptions are deliberate: in 32, 3m and -3m the classes are ordered by dimension (Miller & Love, 1967), so the one-dimensional pair -GM4, -GM5 (B&C’s Γ5, Γ6) comes before the two-dimensional E1/2 -GM6 (B&C’s Γ4), as in CDML and at L of fcc; and in the cyclic co-groups 3, -3, 4, -4, 4/m, 6, -6 and 6/m the complex pairs follow the single-valued ISO-IR labels, because B&C number them inconsistently themselves (for 4, Table 6.5 has 1E1 = Γ6, 2E1 = Γ5 and Table 6.14 1E1 = Γ5, 2E1 = Γ8), which in 4, -4 and 4/m makes -GM7, -GM8 Table 6.5’s Γ8, Γ7. The names are not the Bilbao numbering (Pm-3m Γ: CrystOD -GM6- is BCS -GM8, -GM8+ is -GM10). Every --spinor run states the numbering in a three-line remark ((Double-valued irreps: overbar as a leading '-', index after the single-valued irreps, parity suffix; Bradley & Cracknell (1972) Table 6.5 (Koster) numbering, except that the 2-D irrep of 32, 3m, -3m is last (Miller & Love order) and complex pairs of cyclic co-groups follow ISO-IR labels; see the manual.); it replaces the earlier draft’s two-line remark on “CrystOD’s own convention”), and a NOTE: line under the irreps of a k point says where the names differ from B&C: NOTE: Bradley & Cracknell (1972) number the two-dimensional irrep GM4+- and the pair GM5+-, GM6+- (Table 6.5); here the pair is -GM4+-, -GM5+- and the two-dimensional irrep -GM6+- where the proper parts of the little co-group form 32 (Γ and T of R-3m, L of Fm-3m), NOTE: the complex-conjugate pairs are ordered after the single-valued ISO-IR labels; Bradley & Cracknell (1972) Tables 6.5 and 6.14 number them inconsistently where they form a cyclic group of order 3, 4 or 6 and a complex pair is present (Γ of P3 and P4); --show-irrep-table --spinor prints the double-valued character table with the names, and an irrep that cannot be named keeps its generic key with a NOTE: line giving the reason. The names are the same on every arm of a star and at k + G: they are fixed at the representative arm of the star (arm 0 of the ISO-IR family, new crystod.isoir.IsoIRLabeler.representative_k) and carried to the arm given by conjugation, D’(h) = D(g^-1 h g) (new crystod.wavecar_irreps.transport_double_valued_names; crystod.wavecar_irreps.little_group_data records it in the new LittleGroup.names_transported), the -k partners of a tabulated star (LE of LD, PA of P) taking the complex conjugates under the same index. Fixed with it: a tied pair used to be ordered by its characters at the arm given, so one irrep could carry two names on one star – at L of Fm-3m (NaCl) -L4± and -L5± were swapped between (1/2, 1/2, 1/2) and (1/2, 0, 0) or (0, 0, 1/2), and likewise on one arm of L of Fd-3m, of L and F of R-3m and of L of P6_3/mmc (two-dimensional ties), and on the symmetry lines with 2-, m- and 2/m-type little co-groups (over the special points and one point on each line of the 228 structures in example/test_POSCARs, 1798 of 5532 arm checks and 130 of 293 -k checks failed before, none after, nor any of 5976 k + G checks; the single-valued ISO-IR labels never depended on the arm). The spin factor of the orbital characters is now spgrep’s tr U_g, which equals the former 2 cos(alpha/2) to 4e-16 over every operation of the 215 space groups of the structures in example/test_POSCARs, so the multiplicities are unchanged. Checked for all 32 crystallographic point groups at Γ (sum of the squared dimensions, unique names, the first index, parity partners, and invariance under rigid rotations, primitive settings and supercells in the ISO-IR frame), against Bradley & Cracknell’s Table 6.5 at Γ, and against the literature at L of Fd-3m, L and X of F-43m, X, R and M of Pm-3m and K of P6_3/mmc. Tested in section 2 (38 new --spinor checks, 68 in all: the B&C order at Γ of P2, Pm and P2/m, star covariance through little_group_data and the SALC route, k + G at H and L of P6_3/mmc, names_transported, and the NOTE lines).

  • New: crystod --unfold --child-wavecar CHILD --parent-wavecar PARENT unfolds the electronic bands of a low-symmetry VASP run (the child) onto the Brillouin zone of its high-symmetry parent run, from the WAVECARs of two ordinary band calculations, without a new VASP run. Every child Bloch state at K is split over the N = det M parent wave vectors k = M^-1 K + g_i it unfolds onto, with the weights of its plane-wave coefficients in the N cosets of the child reciprocal lattice modulo the parent’s (V. Popescu and A. Zunger, Phys. Rev. B 85, 085201 (2012); the scheme of fold2Bloch, O. Rubel et al., Phys. Rev. B 90, 115202 (2014)): every band is normalised (the PAW one-centre part is neglected), spinor components are added, and the weights of a band add up to 1 (checked on every run). A degenerate level carries the level weight W_i = Re Tr(S^-1 P_i), which does not change under any mixing of its bands (mixing all 1070 degenerate levels of a 349 MB I4/mcm SrTiO3 run at random changes it by 2.7e-15, the weights of the single bands by up to 0.98). The setting is the one crystod-group --supergroup-cif finds for the two POSCARs, as in crystod-phonon --unfold (--trans-mat picks another equivalent setting); the k weights and the path labels come from each run’s KPOINTS (the ! K.n LABEL comments of an explicit list, line mode, Cartesian lists with the POSCAR scale; else the WAVECAR k list, with the weights of EIGENVAL or vasprun.xml and a NOTE). The report gives the setting and the parent images of the child Γ point, the child path with the images of every vertex, the coverage of the parent path (with the equivalent setting that covers the most), the levels at every child path vertex with their share on every image and the nearest parent level, and a summary with the sum rule, the agreement of repeated k points (K and K + G alike), the symmetry transport between equivalent path points, the mixed levels, the child-parent alignment (a diagnostic) and the energy above which the unfolded spectrum is incomplete. One energy zero, the child’s VBM (--zero efermi, raw or an energy in eV), applies to both runs, so the offsets between them are the raw ones; --separate-zero zeros each run at its own. The energy range of the figure and the tables follows the spectrum (the valence block at or below the zero and the complete range above it; --window EMIN EMAX sets it). Output: band_unfold.pdf (page 1: one panel per parent image along the child’s path, with the parent eigenvalues wherever the image is a parent k point; page 2: the parent bands along the parent’s path with the unfolded child at every point the child run samples, directly or through a child operation), band_unfold.dat (gnuplot datasets per image and for the parent path view) and band_unfold.yaml; -o PREFIX, --degeneracy-tol, --weight-min, --spin (ISPIN = 2 runs: tables and pages per channel, only K and -K relating k points), --all-kpoints, --tolerance. On two SrTiO3 band runs (I4/mcm, 10 atoms, a 349 MB WAVECAR, onto Pm-3m) the run takes about 6 s. Documented in crystod; example example/54_band_unfold (a small pair of real SrTiO3 runs, 4.1 MB of WAVECARs, not in the pip package); tested in the new section 54.

  • New: crystod --unfold-kpoints --child-wavecar CHILD --parent-wavecar PARENT writes a child KPOINTS whose band run covers the whole parent path (KPOINTS_unfold, -o FILE): the child’s weighted SCF points copied verbatim (from its KPOINTS, else its IBZKPT), then K = M k_p for every point of the parent’s labelled path (seekpath with --npoints points per leg when the parent KPOINTS has none) as zero-weight points whose ! K.n LABEL comments carry the parent labels. Only the POSCARs and KPOINTS files are read. crystod --unfold on a run made with it covers every parent leg.

  • New: crystod.vasp_io.read_kpoints(path, lattice=None, scale=1.0) reads a VASP KPOINTS file (KpointsFile): explicit lists in reciprocal or Cartesian coordinates (with the POSCAR scale), line mode expanded as VASP expands it (a leg that does not start where the previous one ended is a break), automatic meshes (no points), and the labels of ! K.n LABEL SEP comments, plain ! LABEL comments or labels after the numbers. Every spelling of Gamma becomes GM; a bare G only at an integer k, since G is a point of its own in the Hinuma paths, and the ! K.n G form keeps G.

  • New in Python: crystod.salc.unfold_bands, BandUnfolding, format_band_unfolding and unfold_kpoints (crystod --unfold and --unfold-kpoints; the result has to_dict(), write_dat, write_yaml and plot, and bad input raises ValueError with the command’s message); see Python API.

  • Changed: double-valued names of spin-orbit runs in --extract-irrep and --diagram --vasp --vasp-engine overlap where two irreps tie. The namer is shared, so in centrosymmetric groups parity partners now share the index (P2/m Γ: -GM3+, -GM5-, -GM4+, -GM6- -> -GM3+-, -GM4+-; P-3m1 Γ: -GM4+, -GM5+, -GM6-, -GM7-, -GM8+- -> -GM4+-, -GM5+-, -GM6+-; Fd-3m L: -L4+, -L5+, -L6-, -L7-, -L8+- -> -L4+-, -L5+-, -L6+-), and the members of a tied pair follow the tie-break above – B&C’s Γ3 first in 2, m and 2/m, fixed at the representative arm of the star and carried to the other arms by conjugation – instead of spgrep’s enumeration order at the k point of the run. Where no irreps tie nothing changes: the SrTiO3, CsPbI3 and InP fixtures (Pm-3m, F-43m) are labelled as before.

  • Changed: the keyword spior of crystod.salc.CrystalOrbital and of the --atomic-orbital class (crystod.orbital_hybridization_spgrep.CrystalOrbital) is renamed spinor. The misspelling spior= is still accepted, with a DeprecationWarning; the command-line flag --spinor is unchanged.

  • Changed: --zero of crystod also accepts fermi and none (for efermi and raw), and with --unfold an energy in eV; a non-finite value is refused. --extract-irrep takes vbm, efermi and raw as before (and the two aliases), and refuses a number. The options --zero, --spin, --degeneracy-tol and --all-kpoints without their mode now stop with X is only used with --extract-irrep or --unfold., and --window names --unfold among its modes.

  • Removed: the unreachable spinor matching code of the Bilbao-table era in crystod/crystal_orbital_spgrep.py (match_with_possible_conjugation, resolve_spinor_phase_convention_block and the conjugation and phase-convention passes that called them). The single-valued labelling is unchanged.

v0.4.6#

Highlights (details in the entries below):

  • crystod-phonon --unfold: the phonons of a distorted phase unfolded onto the Brillouin zone of its high-symmetry parent, with the transformation and the origin shift that crystod-group --supergroup-cif finds for the two structures, the parent irrep of every unfolded level, every arm of the stars of the path vertices, the average over the orientation domains, and the parent k and irreps the child Γ modes come from; crystod.phonon.unfold and its companions in Python. Test sections run 1-53 (51: --unfold, 52: --visualize, 53: crystod-slab).

  • crystod-phonon --visualize: an interactive 3D viewer of the phonon modes at the special points of the k path, grouped by irrep: one standalone HTML page with the dispersion, the mode table of every point with the ISO-IR labels (Mulliken symbol and IR/Raman activity at Γ, imaginary levels in red) and the displacement pattern of every mode as arrows and as an animation, next to band_vector.yaml, phonopy’s band.yaml with eigenvectors; crystod.phonon.phonon_viewer_data in Python. With --all-irreps, the pair of --irreps --all-irreps, the page (phonon_visualize_all.html) also shows the midpoint of every segment of the path with its line irreps.

  • crystod-phonon --irreps now also draws the phonon dispersion with the ISO-IR label of every level at the special points of the path (phonon_irreps.pdf, next to phonon_irreps.yaml; the README figure).

  • crystod-slab, a new command: surface slabs cut from a bulk structure, every termination of the given Miller indices (three- or four-index, one by one or from a list file) or of every index up to --max-index that is distinct under the crystal’s Laue group, each tested for a dipole (polar) and for two equivalent faces (symmetric) and written as a POSCAR, with --max-atoms, --no-polar and --symmetrize, and an interactive dialogue when no index is given; crystod.slab in Python. Please cite R. Kiribayashi et al., ACS Appl. Mater. Interfaces 17, 61872–61887 (2025) when you use it.

  • New: crystod-phonon --unfold --child-poscar CHILD --child-dim 2 2 2 --parent-poscar PARENT --parent-dim 2 2 2 unfolds the phonon bands of a distorted structure (the child) onto the Brillouin zone of its high-symmetry parent. Child mode J, computed at the child wave vector K = M k, is drawn at the parent k with the weight P_J(k) of its projection onto the Bloch states of the parent translations (Allen, Berlijn, Casavant and Soler, Phys. Rev. B 87, 085322 (2013)), with the eigenvectors converted from phonopy’s actual-position phase to the ideal sites (without that factor, as in phonopy’s Unfolding, the weights of a distorted child are off by up to 0.14 and depend on the supercell the force constants are written in); degenerate child modes are rotated so that their weights do not depend on the eigenvector basis, and the sum rule (the weights at every k add up to 3 n_parent) is checked on every run. The transformation is not an input: it is the setting that crystod-group --supergroup-cif PARENT --subgroup-cif CHILD finds for the two structures (SymmetryModeAnalysis), printed as crystod-group prints it (P and the origin shift p) and as the rows of M (A_child = M A_parent, k_child = M k_parent); --trans-mat (nine integers, the crystod-bz convention) chooses another of the equivalent settings (24 for Pnma CaTiO3 and for R-3c AlF3 on Pm-3m), the origin shift following from it, and refuses any other matrix with the list of the valid ones. The path is the parent’s seekpath path (or --band/--band-labels/--npoints in parent primitive coordinates); the run prints the child point every vertex lands on, every arm of the stars of the vertices with the arms that fold onto the child Γ point (the condensed distortions, such as the in-phase tilt M3+ of Pnma CaTiO3 on the M arm (1/2, 0, 1/2), which the default path does not pass) and the classes of arms that a child operation or time reversal relates, and the average over the orientation domains (6 for Pnma, 4 for R-3c). Every unfolded level gets its parent irrep from CrystOD’s projection operators (the ISO-IR labels --irreps gives the parent POSCAR, with the Mulliken symbol at Γ): the irrep holding at least 50 % of the weight of the degenerate group, else the smallest set the child symmetry cannot separate (SM1/SM2), else mixed; a time-reversal pair of a non-symmorphic parent is one unit (S1+S2). The child Γ modes are unfolded onto every parent k that folds onto them, with their child irreps and activities, and with --parent-dim the soft parent levels are followed into the child (the M3+ tilt of CaTiO3 at -5.44 THz mainly into the Ag mode at 4.37 THz). Output: phonon_unfold.pdf (page 1: parent bands, one domain, domain average and the star arms; page 2: the parent irreps), phonon_unfold.dat (two datasets, the path and the domain average), --export-npz FILE (every array), -o PREFIX; --child-readfc and --parent-readfc read FORCE_CONSTANTS, --no-irreps skips the labels and --weight-min sets the weight cut. Each force file is read next to its POSCAR, FORCE_SETS_<POSCAR name> (the name macer writes) before FORCE_SETS, so that the two POSCARs can share one directory, and phonopy runs in an empty directory, so that a FORCE_CONSTANTS lying in the working directory is never used in place of FORCE_SETS. --nac is refused. In Python: crystod.phonon.load_unfold_inputs, find_parent_mapping, parent_mapping_from_setting, make_parent_path, unfold, star_arms, domain_average, irrep_resolve and gamma_origin, with their dataclasses. Example: example/51_phonon_unfold (CaTiO3 Pnma and AlF3 R-3c onto Pm-3m, phonopy force sets from the MACE force field), which also ships with the package (crystod-example 51; 11 files, 242 kB); documented in section 51 of crystod-phonon. Tested in the new section 51.

  • New: crystod-phonon --irreps now also draws the phonon dispersion with the ISO-IR label of every level at the special points of the path (phonon_irreps.pdf, next to phonon_irreps.yaml; the figure of the README, which until now was drawn outside CrystOD). The bands run along the seekpath path of the primitive cell (or --band/--band-labels/--npoints; the vertices of a --band path are named by their ISO-IR k-vector type, so a vertex on a line such as DT is labeled too), and the labels are those phonon_irreps.yaml holds (GM4-(3), X3-, GM1 + GM5(2)), read at the vertex itself through the tabulated arm of its star, so every dot lies on the bands it labels (within 1e-7 THz for SrTiO3, ScF3, BaTiO3 and Si). Every point is labeled once, at its last place on the path that is not a break; the two equivalent points of a break with the same levels (U|K of fcc) get one set of labels, two different ones a set on either side; labels of close levels are moved apart (least-squares positions one line apart) and joined to their levels by leader lines; levels below --threshold (default -0.1 THz) are red. The figure is a PDF named after the YAML file (phonon_irreps.pdf, SrTiO3_irreps.pdf with -o SrTiO3_irreps.yaml, phonon_irreps_all.pdf with --all-irreps); the run prints the path and the labeled points in a * Band path * block, and with --nac a note that the Γ labels are those of the TO modes. The YAML file stays the result of the run: when the figure cannot be drawn, a NOTE: line in the * Band path * block gives the reason and the run still writes the YAML file and ends normally; a malformed --band, or a --band-labels count that does not fit it, stops the run with one line before the survey. The README image is now made by crystod-phonon --irreps -c 221_PPOSCAR_SrTiO3 --dim "4 4 4". Documented in section 28 of crystod-phonon; tested in section 28.

  • New: crystod-phonon --visualize --dim 4 4 4 -c POSCAR writes a phonon mode viewer: one standalone HTML page that shows every phonon mode at the special points of the k path, grouped by irrep, and band_vector.yaml, phonopy’s band.yaml with eigenvectors along the same path. The page holds the dispersion along the path of the --irreps figure (seekpath, or --band/--band-labels/--npoints) with a dot on every degenerate level of the labeled special points (red below --threshold, default -0.1 THz; a click selects the level), one button per special point (GM (0, 0, 0), X (0, 1/2, 0), …), the mode table of the selected point (band, frequency, the set label as phonon_irreps.yaml writes it, GM4-(3), X3-, GM1 + GM5(2), the component inside the set and, at Γ, the Mulliken symbol and the IR/Raman/silent/acoustic activity; imaginary rows in red) and a 3D scene in the style of the SALC viewer of crystod --visualize (VESTA colors, cell edges, the a/b/c compass, --bond EL1 EL2 MAX bonds and coordination polyhedra) with the displacement pattern of the selected mode as arrows on the smallest supercell commensurate with q (--conventional: the conventional cell), an amplitude slider (the largest displacement in Å; default 0.25 times the nearest-neighbor distance, 0.5 Å for ScF3 and SrTiO3), an animation of the vibration in which bonds and polyhedra follow the atoms, orthographic views down a, b and c, and a URL hash (phonon_visualize.html#q=R&mode=1&view=a) that opens a given point, band and view. The partners of a degenerate level are the symmetry-adapted eigenvectors of --vector (build_symmetry_adapted_modes); the page receives only the atomic-gauge vector of every primitive atom and the atom list (element, position, primitive atom, lattice translation T) and draws atom (a, T) displaced by Re[u_a exp(i(2 pi q.T - phi))], which reproduces phonopy’s modulation on the display cell to 1e-6 (checked by the test suite), so the page stays small (80 to 100 kB for ScF3 and SrTiO3; plotly 2.32.0 is loaded from its CDN, as for the other viewers). The terminal prints the structure, the band path and, per q point, the mode table and the display cell; a display cell of more than 1000 atoms (a general q) gets a NOTE. band_vector.yaml is phonopy’s own format (nqpoint, segment_nqpoint, labels with the ISO-IR vertex names, the primitive cell, and per q point the frequency and the eigenvector of every band, [re, im] per Cartesian component and atom); -o FILE renames the page only. Options: --qpoint (a label or coordinates: that point only), --band, --band-labels, --npoints, --threshold, --conventional, --bond (repeatable), --nac (TO patterns at Γ), --readfc, --tolerance, -o; --bond is refused outside --visualize. --all-irreps adds the midpoint of every segment of the path (DT, Z, SM, LD, S, T of Pm-3m; for --band the midpoints of its legs) as q points of their own, after the special points: the labels of phonon_irreps_all.yaml band by band, a display cell commensurate with the exact fractions of the midpoint (DT (0, 1/4, 0): 1 x 4 x 1 primitive cells), a dot in the middle of the leg, a Segment: line, and the page phonon_visualize_all.html (#q=DT(GM-X) or #q=5 open a midpoint); a midpoint whose cell would exceed 1000 atoms (the K-GM and X-U midpoints of fcc Si, 4096) is skipped with a NOTE naming the --qpoint that draws it, and --all-irreps with --qpoint is refused. In Python: crystod.phonon.phonon_viewer_data, write_phonon_viewer_html and write_band_vector_yaml, with the dataclasses PhononViewer, ViewerPoint and ViewerMode. The atom enumeration of the display cell and the bond search of the SALC viewer are now the helpers _display_cell_entries and _bond_pairs of crystod.visualize_basis, shared by both viewers (the bond search vectorized; the pages of crystod --visualize are byte for byte unchanged); compute_dispersion records the q of every labeled point (LabeledPoint.q). Example: example/52_phonon_visualize (ScF3 and SrTiO3 Pm-3m, the 4x4x4 FORCE_SETS of 28), which also ships with the package (crystod-example 52; 7 files, 161 kB); documented in section 52 of crystod-phonon. Tested in the new section 52.

  • New: crystod-slab -c POSCAR --max-index 1 cuts surface slabs from a bulk structure: every distinct termination of each Miller index, tested for a dipole and for two equivalent faces, and written as a POSCAR file. The Miller indices come from --index h k l (repeatable; h k i l of hexagonal axes with i = -(h + k) checked and dropped), --index-list FILE (one index per line, 1 0 0, 1,0,0 or 1 0 -1 0, # comments) or --max-index N: every index with |h|, |k|, |l| <= N that is distinct under the Laue group of the crystal (its rotations found by spglib at --tolerance, and the inversion that turns a slab over), in the axes of the cell used, in pymatgen’s order. This is not pymatgen’s get_symmetrically_distinct_miller_indices, which merges indices under the symmetry of the lattice and, for a trigonal crystal, of its hexagonal setting: on a primitive rhombohedral cell (R-3c AlF3, R-3m Bi) it lists one surface twice and leaves out another, and on a cell whose lattice has more symmetry than the crystal (P1, Pa-3 pyrite, P-3m1, a pseudo-cubic I4/mcm cell) it leaves out surfaces; the two lists agree for a crystal that is not trigonal and whose lattice has no more symmetry than the crystal (cubic SrTiO3 and NaCl, wurtzite ZnO, …). Exactly one index source may be given, and with none crystod-slab -c POSCAR asks for the indices, the minimum slab and vacuum height, the maximum number of atoms, whether polar slabs are allowed and whether to symmetrize them (Enter keeps the default in brackets, 4) quit exits with 0; the structure file and --oxidation are checked before the first question), then prints the * Equivalent command line * and runs it. For each index pymatgen’s SlabGenerator builds the oriented unit cell and stacks whole oriented cells until they reach --slab-size (default 10 Å; the atoms span that height less the gap at the cut, so the thickness in the table can be smaller) plus --vacuum-size of vacuum (default 15 Å; --in-unit-planes: both counted in d_hkl lattice planes of the cell), centers the slab (--no-center) and reduces the in-plane cell (--no-primitive); every termination is listed, t1, t2, ... in pymatgen’s order, with its shift, number of atoms, thickness (the extent of the atoms along the normal), vacuum, area and formula. polar is Slab.is_polar (a dipole per area along the normal above 1e-3 e/Å) on the slab decorated with the oxidation states, guessed from the bulk composition or given with --oxidation Sr=2 Ti=4 O=-2 (they must balance the bulk; all 0 means no ions), and ? without states (a metal); symmetric is Slab.is_symmetric at --tolerance (default 0.1 Å). --max-atoms N and --no-polar list the slabs they skip with the reason, --symmetrize asks for symmetric terminations (pymatgen’s get_slabs(symmetrize=True) with the faces compared at --tolerance; atoms are removed from one face, so the stoichiometry changes, and a slab left with a net formal charge gets a charge column and a NOTE, since “polar: no” then means no dipole, not a neutral slab), --conventional standardizes the input to the conventional standard cell first (the primitive fcc NaCl POSCAR gives (1 1 1) polar, (1 1 0) and (1 0 0) non-polar and symmetric only with it; without it a NOTE says that the indices refer to the cell as given), --orthogonal-c and --max-normal-search are passed on to pymatgen, --lll-reduce reduces the in-plane cell with a and b kept in the surface (pymatgen’s own lll_reduce LLL-reduces the whole slab cell and can tilt it out of the surface, as on SrTiO3 (3 3 2) with 5 Å of slab and vacuum), and --output-dir, --force and --no-files control the files POSCAR_slab_{formula}_{h}{k}{l}_t{n} (_s{n} for symmetrized slabs, _ between the components of an index of 10 or more; direct coordinates, one block per element in the order of the input POSCAR, the slab formula on the comment line); an identical file already there is kept, and a different one is refused unless --force. Every run that prints the table ends with the citations of R. Kiribayashi et al., ACS Appl. Mater. Interfaces 17, 61872–61887 (2025) (doi:10.1021/acsami.5c17978), the paper to cite when you use crystod-slab, and of pymatgen’s slab construction (W. Sun and G. Ceder, Surf. Sci. 617, 53 (2013); R. Tran et al., Sci. Data 3, 160080 (2016)). This is the former script/slabkit.py of Ryuju Kiribayashi (2024), without its banner; unlike the script, whose --index and list-file modes cut one termination per index (get_slab) unless they symmetrized, every termination is listed in every mode, and the polar test is pymatgen’s dipole test instead of a comparison of the atoms above and below the centre of the slab. In Python: the new API domain crystod.slab (load_structure, distinct_miller_indices, parse_miller_index, read_index_list, generate_slabs returning SlabSet / SlabRecord with charge, format_table, write_slab_poscar returning (path, status) as crystod.search.write_poscar does, slab_filename, SLAB_CITATION_LINES, …); importing it loads no pymatgen. crystod-slab --example SrTiO3 / --example ScF3 run on the bundled cells. Example: example/53_slab (SrTiO3 Pm-3m, NaCl Fm-3m from its primitive cell, La2CuO4 I4/mmm), which also ships with the package (crystod-example 53; 7 files, 34 kB; with 51-53 the package ships 44 example directories, 243 files, 7.80 MB); documented in crystod-slab. Tested in the new section 53. The MCP server gains the tool crystod_slab (the slab table of a POSCAR for one miller_index or for every distinct index up to max_index, with the slab and vacuum sizes, symmetrize, no_polar, max_atoms and oxidation_states of the command, and the slab POSCAR files only in an absolute output_dir the call names; it needs CrystOD 0.4.6).

  • Fixed: the direction column of crystod-group --supergroup-cif names each order parameter as crystod-group --parent does, by the ISOTROPY representative of its stratum, instead of by the direction the child file happens to sit on. The irreps are labelled with the ISO-IR tables of ISOTROPY, but the decomposition table wrote the direction of the input child, so a child in another orientation domain read differently from the --parent SG --irrep IR row of the same isotropy subgroup (reported on V2O3 R-3c -> C2/c: GM3+ (0.577a,-a) against the row GM3+(a,0) 15 C2/c; SrTiO3 Pm-3m -> I4/mcm printed R5- (a,0,0) since v0.4.1, against the row R5-(0,0,a)). The directions are now those of the domain-equivalent child in which the modes, in order of decreasing amplitude, sit on the simplest directions, one parent operation for all rows and chosen by the rule of the --parent tables (IsotropyAnalyzer.canonical_projector): the largest mode with domain-equivalent directions sits on its --parent row, and the rows together still describe one domain (the Pbnm perovskite prints R4+ (0,a,a) with M3+ (a;0;0), as in the coupled row R4+(0,a,a) M3+(d;0;0) of --parent Pm-3m --irrep R4+ M3+, although M3+ on its own is tabulated as (0;0;a)). A note under the table, in the terminal and in sym_mode_<formula>, names the mode that decides and its --parent command, the representatives of the other strata on their own, and the direction the child as given sits on when it differs: (direction: GM3+ sits on its ISOTROPY representative as listed by crystod-group --parent 167 --irrep GM3+; the input child as given sits on the domain-equivalent direction GM3+ (0.577a,-a)). Printed outputs that change: SrTiO3 R5- (a,0,0) -> (0,0,a), V2O3 GM3+ (0.577a,-a) -> (a,0), ZrO2 Fm-3m -> P4_2/nmc X2- (0;a;0) -> (0;0;a) and BaTiO3 Pm-3m -> P4mm GM4- (a,0,0) -> (0,0,a), each with the note; La3Ni2O7 I4/mmm -> Cmcm (X3- (0;a), the row of --parent I4/mmm --irrep X3-) is unchanged and has no note. Over 58 structure pairs (the inputs of section 23 and the bug reports), 54 of the 174 rows change their direction label; no other column changes. Unchanged: the sublattice setting (the cell relation, the transformation matrix P and p, the displacement table, the normalized mode components and the VESTA files keep following the input files), the irreps, amplitudes, numbers of modes and isotropy subgroups (those of the child as given; a child on the mirror-image domain of an enantiomorphic stratum keeps its own type, P4_32_12 where the direction shown is tabulated as P4_12_12, and the note names the partner), and the --parent tables. In Python, each entry of SymmetryModeAnalysis.modes gains domain_label (the direction of the child as given) and representative_label (the representative of its stratum on its own); label_info() keeps its (label, info, index) shape and returns the direction shown. Documented in section 23 of crystod-group. Tested in section 23.

v0.4.5#

Highlights (details in the entries below):

  • crystod --extract-irrep: the irreps of the electronic bands of one finished VASP run, read straight from its WAVECAR, at the special k points of the file or at every k point, for spin-polarized and spin-orbit runs as well; crystod.salc.extract_band_irreps in Python.

  • Worked examples with the package: all 41 example directories (README and inputs, without their large or unpublished data) ship in crystod/examples/, and the new command crystod-example lists them and copies them into a working directory, together with the shared structures and the other directories a README uses; crystod.examples gains the same functions. Every example README now runs inside its own directory.

  • crystod-group --parent: the pair labels of --kpoint are accepted by --irrep, --order-parameter reads sums of parameters exactly, and the direction tables print irrational ratios as decimals instead of small integers.

  • Compatibility: --spin of crystod (for --extract-irrep) no longer abbreviates --spinor. Test sections run 1-50 (50: the packaged examples).

  • New: crystod --extract-irrep [PATH] labels the electronic bands of one finished VASP run with the irreps of the little groups, straight from its WAVECAR — no crystal-orbital diagram, no sublattice runs, no PROCAR. PATH is the WAVECAR or the run directory (default: the current directory); the structure is the run’s POSCAR (-c FILE names another file of the same cell and origin). By default every ISO-IR special point of the space group that the file holds is analysed — found on any arm of its star and modulo reciprocal-lattice vectors, at its first occurrence when a band path passes it twice — and the levels are listed by energy: level number, band indices, energy (relative to the VBM, --zero efermi or raw), degeneracy, ISO-IR irrep (with the Mulliken symbol at Γ) and a note with what the labelling engine flags (an incomplete multiplet at the top of the band list, a numerically split level that was merged, symmetry leakage). Bands within the degeneracy window are always one level, also when the run returns them as pure states of different irreps; such an A/B level is classified by Wigner’s test of time reversal at k — a time-reversal pair (-L4/-L5 at L of zincblende with spin-orbit coupling, DT3/DT4 along Γ–X of zincblende without it), one irrep doubled by time reversal (Kramers pairs at a general point of a centrosymmetric spin-orbit run) or an accidental degeneracy, with the irrep of each band. --kpoint takes labels and/or coordinates, --all-kpoints labels every k point of the file (lines, planes and general points, named by the ISO-IR k label of the little group), --window EMIN EMAX limits the listed levels, --degeneracy-tol sets the level clustering (default 1 meV). ISPIN = 2 runs give one table per spin channel (--spin up|down|both); spin-orbit runs are recognised from the WAVECAR and carry the double-valued -R6+ names of the overlap engine. The report ends with the band edges of every analysed k point and the gap over the file; -o FILE writes the same content as YAML (the layout of phonon_irreps.yaml). Only the analysed k points are read, one at a time: the four special points of a 135 MB, 288-k-point SrTiO3 band-structure WAVECAR take under two seconds, those of a 3.2 GB spin-orbit CsPbI3 WAVECAR three. The labels agree with the SALC decompositions (crystod --element O --orbital p, --element Ti --orbital d: the nine O 2p and five Ti 3d bands at GM, X, M, R), with the 62 crystal levels of the anchor engine’s level table and with the 154 crystal levels of --diagram --vasp --vasp-engine overlap on the same runs. In Python: crystod.salc.extract_band_irreps(path, kpoints=None, zero="vbm", window=None, spin="both", symprec=1e-5, degeneracy_tol=None) returns a BandIrreps dataclass (format_band_irreps, write_band_irreps_yaml). The sublattice runs of --vasp-setup (Va point-charge species) are labelled too, with the labels the overlap engine gives the sublattice columns (308 levels). Inputs: four small real VASP runs in example/03_hybridization/vasp_wavecar — SrTiO3 (scalar, ISPIN = 2, spin-orbit) and InP with spin-orbit coupling (the time-reversal pairs); the scalar SrTiO3 and the InP runs also ship with the package (crystod-example 03), the ISPIN = 2 and spin-orbit SrTiO3 runs are not in the pip package (they stay in the CrystOD development tree). Tested in the new section 49 (and section 45 for the API).

  • Fixed: crystod.wavecar_irreps.irreps_at_kpoint at a general k point. A trivial little group has no generator, and the invariance test took the minimum of an empty array (ValueError). Only --extract-irrep --all-kpoints reaches such points; the special points of the overlap engine are unaffected. Tested in section 49.

  • Changed: crystod.vasp_wavecar.Wavecar reads both spin channels of an ISPIN = 2 WAVECAR when asked (allow_spin_polarized=True; Wavecar.bands(ik, isp), read_bands(path, k, spin=...)), and stops with one ERROR line on an empty or truncated WAVECAR instead of an IndexError or a short read. The overlap engine still refuses ISPIN = 2 with the same message. Tested in sections 3 and 49.

  • Note: --spin is now an option of crystod (for --extract-irrep), so it no longer abbreviates --spinor; write --spinor in full.

  • Fixed: crystod-group --parent SG --irrep takes the pair labels that --kpoint prints. --parent 176 --kpoint H lists H1H2, H3H6 and H4H5, but --irrep H1H2 H3H6 stopped with irrep "H1H2" is not tabulated; only the first member (--irrep H1 H3) was accepted. A pair label (H1H2, P1PA1, W1W2, M1+M4+, GM2+GM3+) is now an alias of its physically irreducible order parameter, built from the member listed first in the tables (the member the --kpoint table uses), in --irrep alone and with --order-parameter, --invariants, --secondary, --graph, --correlate and crystod.group.isotropy_subgroups; --irrep H1H2 H3H6 prints exactly what --irrep H1 H3 prints. Two tabulated irreps that are not a complex-conjugate pair are refused with the pair of the first one (H1H3: the order parameter of H1 is H1H2). All 743 pair labels of the --kpoint tables of the 230 space groups (146 groups) build under --irrep, and the 631 whose first member sits at the same k point give the rows of the --kpoint table exactly; a +-k pair listed at the -k point (P1PA1 at PA) is built from the member at +k, so at PA of I2_13 one decimal direction reads in the other member’s basis (same subgroups). Tested in section 17.

  • Fixed: crystod-group --order-parameter reads a sum of parameters as that sum. A component such as a+b-c-d was taken for one new, independent parameter, which made the direction more generic than the one printed and the subgroup too low: --parent 230 --irrep P1 --order-parameter 2a 2b 2c 2d a+b-c-d -a+b-c+d a+b+c+d a-b-c+d gave P1 (index 192) instead of C2 (No. 5, index 96). Integer and exact rational combinations (a+b-c-d, 2a-1/2b, a+a) are now read exactly, in the subgroup and in the restricted invariants of --invariants; a rounded decimal factor is refused inside a sum as it already was alone (-0.4g+0.917h: the factor 0.917 is not an exact fraction), and a sum with a number in it (a+1) is refused as unreadable. The representative vector of the direction is chosen by the genericity test of the tables’ own representatives (_generic_vector) instead of taking the first magnitude set untested. Over every printed direction of the --kpoint tables of the 230 groups (1381 k points, 15434 rows), 168 rows were accepted and read back to another subgroup (the decimal sums, the 230 P sum, the 214 P integers below); now 13849 read back to their own subgroup and the other 1585 are refused. Tested in section 17.

  • Fixed: the direction tables of crystod-group --parent print an irrational ratio as small integers no more. The integer form of a direction came from the SALC routine, whose tolerance (2e-3) is set for XYZ geometries, so 214 P printed P2(0,0;4a,3a) for (0, 0; 1, 0.7504); passed back to --order-parameter, 4 : 3 is another direction (C2, index 48, not the listed I2_12_12_1, index 24). The integers are now kept only when they reproduce the row to 1e-6, and a decimal is printed with as many digits as it takes not to read as an exact fraction it is not (0.7504, 0.3999, 0.8753 instead of 0.75, 0.4, 0.875; H3 of P6/mcc printed 1b for 0.9998b). 55 of the 15434 rows change: 214 P (6 rows; P2(0,0;a,0.7504a), and other domains of the same strata where the shorter label is now exact, P1(0,0;0.785a,a)), W5 of Fm-3m (44, 0.4 -> 0.3999), P5 of I4/mcm (2), and H3 of P-31m, P-31c and P6/mcc (one each, another domain of the same stratum); subgroups, sizes and indices are unchanged. Tested in section 17.

  • New: the worked examples ship with the package, and crystod-example copies them out. All 41 example/NN_name/ directories, each with its README and the input files its commands read but without their large or unpublished data, are installed under crystod/examples/ at the same relative paths, together with the shared test_POSCARs/ (18 structure files) and test_XYZs/ (5 molecules) that the READMEs read as ../test_POSCARs/...: 218 files, 7.36 MB, about 2.7 MB compressed in the wheel. crystod-example (or --list) lists the directories with their sizes and the directories each README uses; crystod-example NN [NN ...] [-o DIR] and crystod-example --all -o DIR copy them into ./example (or DIR), with the shared inputs and the directories a README uses (29 brings 28 and 30, 40 brings 33 and 39, 45 brings 28, 47 brings 23). A file already in place with the same content is kept; if one differs, nothing is written and one ERROR line names it (exit status 1). The same in Python: crystod.examples.list_example_dirs, get_example_dir, example_dir_path, resolve_example_dirs, copy_example_dirs and ExampleConflictError. The packaged files are byte-for-byte copies of example/, selected in example/PACKAGED and written, with index.json and a plain-text README, by script/sync_packaged_examples.py. Not in the pip package, because they are large or test-only (they stay in the CrystOD development tree): the full 41.7 MB NpT trajectory and every FORCE_CONSTANTS, the reference data of the test suite (the expected.json files, the two extra WAVECAR runs of vasp_wavecar, ISPIN = 2 and spin-orbit SrTiO3, the debugN_* fixtures of 23, the recorded answers of the offline section 48) and test_pyscf, as well as third-party and generated output. Unpublished, not distributed: the data of unpublished work (vasp_overlap and vasp_SrTiO3_LAK of 03, the CdF2 supercell of 06). LICENSE names the sources of the bundled structures that are not the authors’ own: four Materials Project structures of 23 (CC BY 4.0, two of them modified) and the PubChem geometries of benzene and O2. Documented on the new page crystod-example; tested in the new section 50.

  • Changed: every example README runs inside its own directory, in a clone as in a crystod-example copy. Paths are relative to the README (../test_POSCARs/..., ../28_phonon_irrep/...) instead of from the repository root, and private paths are gone. 22_poscar2cif works on its own copies of its inputs and no longer overwrites test_POSCARs/221_PPOSCAR_SrTiO3 and the test suite’s reference 221_PPOSCAR_ScF3.cif. 39_xdatcar2adp and 40_md_projection use XDATCAR_every10, every tenth frame of the equilibrated part of the NpT ScF3 run (301 frames, 3.1 MB, --start-step 0), with re-captured outputs; the ADPs agree with those of the full trajectory to 0.2 % (Ueq 0.005477 and 0.023486 Ų, against 0.005485 and 0.023521 Ų), and the full XDATCAR (not in the pip package) stays in the CrystOD development tree for sections 39-41. In 28_phonon_irrep, two phonopy lines write the FORCE_CONSTANTS that the --readfc lines read (phonopy-init -d -c POSCAR --dim 4 4 4, phonopy phonopy_disp.yaml --writefc --fc-calc traditional); they come after the FORCE_SETS lines, because phonopy.load prefers a FORCE_CONSTANTS in the working directory even when FORCE_SETS is named. 33_modulation/Sr3Ti2O7_I4mmm begins with the two phonopy lines that write its phonopy_params.yaml (phonopy-init -d -c 139_PPOSCAR_Sr3Ti2O7 --dim 4 4 4, phonopy phonopy_disp.yaml --sp; byte-identical to the file of the development tree with phonopy 4.3.0), which is not packaged. The ScF3 README runs the same two lines in a subdirectory phonopy4/, so that its packaged phonopy_params.yaml (the force constants that 40 reads) stays as it is and a later crystod-example 33 or 40 into the same directory still finds it unchanged, and checks there that --yaml with the new file writes the same structure byte for byte. 42_molecular_salc holds its own copies of XYZ_O2.xyz, XYZ_NH3.xyz and XYZ_CH4.xyz. 03_hybridization and 23_symmetry_mode mark the commands that need data not in the pip package; 23 gains the Materials Project attribution and an --output-dir for its second La3Ni2O7 pair, whose table would otherwise replace the first one’s sym_mode_La3Ni2O7.

  • Changed: packaging. pyproject.toml sets include-package-data = false, so only the package-data globs decide what ships (this also silences setuptools’ “Package would be ignored” for test_POSCARs/), adds the globs of the example directories and an exclude-package-data table (__pycache__, *.pyc, *.html, *.pdf, POTCAR*, .DS_Store), and the console script crystod-example. Package-data globs read the disk and ignore .gitignore, so a release is built from a git archive export of the release commit, never in the working tree, where python -m build --no-isolation would also let setuptools-scm put every tracked file into the sdist (CONTRIBUTING.md, Release process).

  • Note: the --example listing of crystod, crystod-phonon, crystod-mol, crystod-bz, crystod-xrd and crystod-search ends with a blank line and More examples, a directory per feature with its README and inputs: crystod-example; the lines above it are unchanged.

v0.4.4#

Highlights (details in the entries below):

  • crystod-md --project: the projection of an MD trajectory onto the symmetry-adapted displacement patterns of the parent cell (order-parameter statistics per irrep, single/double-peaked hint, histograms, sum rule) or, with --yaml, onto the phonon eigenvectors, with effective frequencies (--temperature) and every arm of the star (--star).

  • crystod-mag --qpoint and --classify-only: the magnetic space group (BNS) and point group, the responses allowed by symmetry and the collinear class (ferromagnet, ferrimagnet, conventional antiferromagnet, d/g/i-wave altermagnet) of every spin basis vector; complex-conjugate pairs merged into one real space, component numbers counted from 1; MCP tool crystod_mag_classify (17 tools).

  • crystod-xrd --parent PARENT -c CHILD: the superlattice reflections of a distorted phase indexed on the parent lattice and assigned to parent k points and irreps; --radiation neutron --wavelength W: powder neutron patterns.

  • crystod-group --cif-axis / --cif2poscar --spacegroup-set: every axis setting of the space group of a CIF or POSCAR, and the structure rewritten in one of them; --supergroup-cif prints and saves the transformation matrix from the parent to the child setting.

  • crystod --sigma / --xrange: the SCF Fermi smearing of --diagram --pyscf and --visualize --pyscf, the Gaussian broadening of --dos --pyscf and the energy range of the DOS plot; crystod-phonon --modulation --qpoint R: special-point labels in place of coordinates, as in --vector and --subgroup.

  • Every block header at column 0 as * Title *; phonon_irreps.yaml is valid YAML, read by crystod.phonon.read_phonon_irreps; fixes to the two-dimensional and complex irreps of crystod-mag. Test sections are renumbered 1-48.

  • crystod-mcp 0.3.0: 17 tools, requires CrystOD >= 0.4.4.

  • Fixes: the atomic gauge of the SALC viewer and species that are not contiguous in the POSCAR (crystod), the Bloch phases of crystod-group --basis --sg at k != 0, Brillouin zones of unreduced bases (crystod-bz), the site-symmetry constraints of crystod-md --adp, d and f shells in crystod-mol --diagram, the -k stars of crystod-xrd --parent, and the stdio stream of crystod-mcp.

  • Fixed: the SALC viewer of crystod --visualize --element X --orbital l draws the coefficients in the atomic gauge, so relative phases between sublattices are right at every k point. Each atom’s block is multiplied by exp(2 pi i k.x_a). Pages where that factor is one common phase, including every GM page, are unchanged. Tested in section 6.

  • Fixed: the conjugation-closure test of crystod --visualize --real-coefficient runs in the atomic gauge. Real-type irreps such as Si p X3/X4, FeS2 S p X and TiO2 O p X/A/R now get real bases, and complex-type irreps such as ZnO Zn d at A are reported as having none. Tested in section 6.

  • Changed: crystod --visualize names the gauge of the HTML page where it matters. The printed SALC coefficients are unchanged (site gauge). Where the gauge changes relative phases, one NOTE line states the convention the HTML page uses. Tested in section 6.

  • Fixed: the crystal-orbital (SALC) irreps of crystod -c POSCAR --element EL --orbital ORB when an element’s atoms are not contiguous in the POSCAR (repeated species blocks such as O Ti O Sr O). The permutation characters are now taken over the element’s atom indices, not over the index range from its first to its last atom, so the irreps no longer include atoms of other elements (O p at X of SrTiO3 is 9-dimensional again, not 15). Tested in sections 2 and 7.

  • Fixed: the atom count and the Wyckoff and site-symmetry letters printed by the SALC analysis for non-contiguous species. O (3) with ['c', 'c', 'c'] instead of O (5) with the letters of Ti and Sr. Tested in sections 2 and 7.

  • Fixed: crystod --atomic-orbital for non-contiguous species. The hybridization table no longer lists an orbital under irreps it does not span (O(p) under R5+ and M3- of SrTiO3 written as O Ti O Sr O). Tested in section 3.

  • Fixed: the inter-site Bloch overlaps of valence f shells (Ce, Sm, Gd, Yb, Lu 4f) in the extended-Hueckel crystal-orbital diagram are computed instead of being set to zero. They use the shared STO routine and a tail-probed lattice-sum cutoff, so crystod --diagram now shows f covalency (e.g. CeO2 S(Ce 4f, O 2p) = 0.016 at GM, GdN GM4- 4f with 16% N 2p). Tested in section 4.

  • Fixed: crystod --band/--dos/--visualize --pyscf accept --no-chk instead of stopping with ‘unrecognized arguments’. Those modes never use the automatic CHK_{formula}.chk cache, so the flag changes nothing there. Tested in section 7.

  • New: crystod --sigma and --xrange. --sigma sets the SCF Fermi smearing of --diagram --pyscf and --visualize --pyscf and the DOS broadening of --dos --pyscf, --xrange sets the DOS plot range; both are refused with a clear error where no engine uses them. Tested in section 7.

  • Fixed: crystod-group --basis/--generate-basis --sg at k != 0 of non-symmorphic space groups. The Bloch phases exp(-2 pi i k.t) are attached to the little-group action wherever they form a representation (complete decompositions, e.g. Fd-3m DT, P2_1 C). At zone-boundary points where they do not (e.g. M of P4_2/mnm, X of Pnma, X of Fd-3m), the command stops with an ERROR that names the obstruction instead of printing an incomplete decomposition; without --kpoint, such points are listed as skipped. Tested in sections 12 and 14.

  • Fixed: crystod-group --basis/--generate-basis --sg printed the conjugate partner’s function for complex-type irreps. The functions are now acted on with the active convention f(R^-1 r) used by --table and the SALC path (P4 GM3 is now x + i y, printed -Ix + y); multiplicities and point-group results are unchanged. Tested in sections 12 and 14.

  • Fixed: crystod-group --decompose refuses character vectors that are not the character of a representation. Non-integer or negative multiplicities, or characters the rounded decomposition does not reproduce, now give an ERROR instead of being rounded into a wrong decomposition. Tested in sections 10 and 24.

  • Fixed: crystod-group --multiplet --orbital g/h/i stops with a clean error (Coulomb multiplet energies exist for l <= 3 only) instead of a KeyError traceback. Only s, p, d, f are listed as valid --orbital shells. Tested in sections 21 and 24.

  • Fixed: crystod-bz drew a too-large Brillouin zone for unreduced bases (manual --band paths on oblique cells, sheared --trans-mat supercells). The Voronoi cell is built on the Selling-reduced reciprocal basis and its volume is checked against |det B|. Tested in sections 25 and 26.

  • Fixed: Brillouin-zone corners that coincide within a relative tolerance are merged, so lattice noise no longer splits faces. New keyword tolerance of get_brillouin_zone_3d (default 1e-5). Tested in section 25.

  • Fixed: crystod-bz --trans-mat folds the unit-cell q points to the true nearest image also for oblique unit-cell bases. Tested in section 26.

  • Fixed: crystod-bz --show-kpoint for non-standard setting symbols (Pbnm, Amam, Bbmm). The centring is taken from the ISO-IR standard setting of the table, the heading names that setting with a NOTE on the requested one, and the command no longer ends in a traceback. Tested in section 27.

  • Fixed: crystod-bz --trans-mat rejects non-integer matrices with an ERROR instead of printing meaningless folded points. Tested in section 26.

  • Fixed: crystod-phonon --vibration --mode-index refuses a q point that no supercell of at most 12 cells per axis holds, as --modulation does. q = (0.15, 0, 0) wrote a 6x1x1 structure whose modulation is not periodic. Denominators up to 12 are written exactly (1/8 used a 6x1x1 cell), and the error of both modes names the smallest commensurate supercell. Tested in sections 33 and 34.

  • Fixed: the POSCAR written by crystod-phonon --vibration has one block per species (Sc F / 8 24 instead of Sc F Sc F ...). Tested in section 34.

  • New: crystod-phonon --modulation --qpoint and --qpointN accept special-point labels (e.g. --qpoint R), resolved as in --vector and --subgroup. Tested in section 33.

  • Fixed: crystod-phonon --irreps honours -o: the YAML file is written to the given path instead of phonon_irreps.yaml. Tested in section 28.

  • Fixed: crystod-phonon --vibration rejects several --amplitude values with a one-line error (one mode-space component is written, so one value), instead of argparse’s ‘unrecognized arguments’. Tested in section 34.

  • New: keyword quiet of SymmetryOnlyVibrations, which suppresses the primitive-cell note on stdout. gamma_mode_activities and the crystod_phonon_activity MCP tool no longer print it (it went into the stdio protocol stream); the commands keep it. Tested in section 34 and in the crystod-mcp tests.

  • Fixed: crystod-mag uses --tolerance for the site matching of the spin representation and the collinear classification as well as for spglib, and builds the Bloch phases from the site positions symmetrized by the space group. A structure slightly off its ideal positions now decomposes and classifies like the ideal one instead of giving an empty decomposition. Tested in sections 36 and 37.

  • Fixed: crystod-mag refuses a q point that does not fit a magnetic supercell of at most 12 cells along each axis, with a one-line ERROR naming the smallest commensurate supercell, instead of building a cell that is not commensurate. q = (0, 0, 0.15) gave a 1x1x7 cell classified as a ferrimagnet; with --conventional the conventional magnetic cell is checked as well. Tested in sections 36 and 37.

  • Fixed: crystod-mag rejects a non-primitive input cell with the same one-line ERROR in survey mode and --qpoint mode (survey mode crashed with a ValueError traceback). doc/crystod-mag.md states the primitive-cell requirement. Tested in sections 37 and 38.

  • Fixed: crystod-mag lists a pair of multi-dimensional complex irreps at q != 0 under its pair label as one real space of twice the dimension (ZnO at A: A5A6(4): dim 4), matching the decomposition, instead of under the representative’s own label with complex partners. Tested in section 37.

  • Fixed: the site-symmetry constraints of crystod-md --adp in cells whose rotations mix axes of different reciprocal length (for example the primitive cell of a body-centred tetragonal or orthorhombic lattice). The projector now transforms the CIF U^ij with M = N*^-1 R N*, so an isotropic tensor stays isotropic; conventional cells and F-, C-centred, rhombohedral and bcc primitive cells give the same CIF as before. Tested in section 39.

  • Fixed: the constraint text of crystod-md --adp no longer claims relations the projector does not impose (for example U13=0 in a bct primitive cell, or U12=0 on a two-fold axis along a in a hexagonal cell). Sites constrained only by relations such as U12=U22/2 now read general linear constraints only. Tested in section 39.

  • Changed: crystod-md --adp uses --tolerance as a Cartesian distance in Angstrom, as spglib does, both when selecting site-symmetry operations and when mapping atoms onto their asymmetric-unit representative. get_site_symmetry_operations and build_symmetry_projector take an optional lattice= keyword for this. Tested in section 39.

  • Fixed: crystod-md --adp reports atoms that it cannot map onto their asymmetric-unit representative in a WARNING with their 1-based XDATCAR numbers, instead of dropping them from the ADP statistics silently. Tested in section 39.

  • Fixed: the site table of crystod-md --adp prints the Ueq of the tensor written to the CIF, so the two always agree. Tested in section 39.

  • Changed: the CIF written by crystod-md --adp opens with the comment line # generated using crystod-md --adp instead of the retired mode name crystod --xdatcar2adp. The lines below it are not affected: for the ScF3 example of section 39, the CIF written before this change differs from a fresh run in this first line only.

  • Fixed: the AO-parameter block of crystod-mol --diagram prints double-zeta d/f Slater exponents with their contraction coefficients, instead of crashing with a TypeError for transition-metal molecules such as TiCl4. Tested in section 43.

  • Fixed: the single-centre MO-diagram orbital sketches have d and f slots (s, p, then wigner_D_real-ordered d and f), so the HTML is written for molecules with d or f orbitals and d lobes are drawn, instead of raising IndexError. Tested in section 43.

  • Fixed: the single-centre MO numbering counts core shells by angular momentum, so d and f cores (Zn-Br, Rb onward) are no longer counted as p shells. For example, the first valence a1 of H2Se is now 8a1, as in the two-fragment engine. Tested in section 43.

  • Fixed: the crystod-mol --diagram report prints ligand SALCs of d and f ligand shells with d/f component names (3dxy, 3dz2, …). Tested in section 44.

  • Fixed: crystod-xrd --parent for parents with no operation taking k to -k: a complex-conjugate pair (GP1GQ1, LD1LE1, …) is now assigned to both the star of k and its separate -k star. The -k families, the Friedel partners of the k families, are first order instead of higher order; both summaries list the pair with its one amplitude, a note says so, and KPointSummary.shared names the other star. The symmetry-mode entry of such a pair now has partner_kname / partner_kvec. Tested in sections 23 and 47.

  • Fixed: crystod-xrd --parent and crystod-group --supergroup-cif refuse partially occupied or mixed-site CIFs with an ERROR naming the first disordered site, instead of an AttributeError traceback from site.specie. Tested in sections 23 and 46.

  • Fixed: crystod-mcp converts a SystemExit or KeyboardInterrupt raised in a tool body into an error result inside the worker thread, so that bad input such as crystod_irrep_product("Pm3m", ...) no longer escapes the event loop on Python 3.10/3.11 and leaves the stdio server without a reply. Tested in crystod-mcp/tests.

  • Fixed: crystod-mcp sends what tool bodies print to stderr instead of stdout, so progress lines such as the primitive-cell banner of crystod_phonon_activity no longer reach the stdio protocol stream. Tested in crystod-mcp/tests.

  • New: crystod-group --cif-axis -c FILE lists every axis setting of the space group of a CIF or POSCAR, and crystod-group --cif2poscar -c FILE --spacegroup-set SETTING writes the structure in one of them. The table has one row per Hall-symbol setting of the group, in the order of VESTA’s “Setting” list and the International Tables (Cmcm: Cmcm (a, b, c), Ccmm (b, a, -c), Amma (c, a, b), Amam (-c, b, a), Bbmm (b, c, a), Bmmb (a, -c, b); nine cell choices and unique axes for P2_1/c; origin choices; hexagonal and rhombohedral axes), each with the lengths and angles of the input cell in its axes (x_setting = P x_input + p; the monoclinic and orthorhombic settings follow from the first one with the axis permutations and cell-choice matrices of the International Tables, so the lengths follow the axes text), and marks the setting the file is in with <- input (a primitive cell or a supercell gets a note instead). Monoclinic symbols are read from the full symbol (P2_1/n, P2_1/a, …). --spacegroup-set takes the symbol, the No. of the table or spglib’s choice string (Amam, 4, -cba; b2, 2, R for symbols shared by several settings) and writes the conventional cell of that setting as <input without .cif>_<setting> (POSCAR_La3Ni2O7_Cmcm_Amam, 14_PPOSCAR_ZrO2_P21n_b2, 227_PPOSCAR_Si_Fd-3m_2). Python: crystod.group.list_space_group_settings, resolve_setting, transform_to_setting (SettingTable, SpaceGroupSetting). Tests in section 22 (La3Ni2O7 Cmcm, CaTiO3 Pnma, ZrO2 P2_1/c, Si Fd-3m, AlF3 R-3c, Sn4Pd Ccce, CaCuO2 P2_122_1, CaTiO3 Imma, primitive NaCl; every written file re-read in its setting).

  • New: crystod-group --supergroup-cif prints the transformation matrix from the parent to the child setting and saves it with the table. A block * Transformation matrix (parent -> child) * precedes the decomposition table, in the convention of AMPLIMODES and the International Tables: the columns of P are the child conventional basis vectors in units of the parent conventional basis, (a', b', c') = (a, b, c) P, and the last column is the child origin p in parent fractional coordinates, x_parent = P x_child + p, both in the conventional settings of the input files (spglib’s standard settings when it cannot relate an input cell to them; the block says which). The setting is the sublattice basis the analysis uses (the one closest to the orientation of the input files among the equivalent ones), so the matrix can differ from the AMPLIMODES one by a point operation of the parent: SrTiO3 Pm-3m -> I4/mcm gives exactly the AMPLIMODES [[1, 1, 0], [-1, 1, 0], [0, 0, 2]], origin (1/2, 1/2, 1/2); for CaTiO3 Pm-3m -> Pnma the Bilbao matrix is the same setting rotated. The saved sym_mode_<formula> now starts with this block, followed by the table as before. Python: SymmetryModeAnalysis.setting_transformation(frame="input" | "standard") returns a SettingTransformation (matrix, origin, frame). Tests in section 23 (the matrix maps every child atom of the input file onto a parent atom within the maximum displacement, also for a child file with a shifted origin and permuted axes).

  • New: magnetic space groups, magnetic point groups, responses allowed by symmetry and collinear classes in crystod-mag --qpoint, and --classify-only. Every exported component of a spin basis now gets four lines after its net moment: the magnetic space group of the arrangement from spglib (BNS symbol from the pymatgen table, BNS number, type I-IV, operations and primed operations in the magnetic cell), the magnetic point group (derived from the BNS symbol and checked against the operations; the derivation agrees with the operations for all 1651 groups), the responses its point group allows (net magnetization with its direction, the numbers of independent linear magnetoelectric and piezomagnetic components, from the time-odd tensor forms of --tensor), and the nonrelativistic class of a collinear arrangement from its sign pattern: ferromagnet, ferrimagnet, conventional antiferromagnet (a translation or the inversion exchanges the sublattices) or altermagnet with its d/g/i-wave type, the lowest-order form of the spin splitting allowed by symmetry and the spin-degenerate planes (L. Smejkal, J. Sinova and T. Jungwirth, Phys. Rev. X 12, 031042 (2022)). A final * Magnetic groups and collinear classes * table collects them; --classify-only prints the structure, the decomposition and that table only. The table names every component by the tag of its VESTA file (x_2 for a repeated x), and a note states the frames (MSG and MPG symbols in the standard BNS setting, directions in the Cartesian axes of the input cell). When spglib cannot identify a group in the cell given, the Niggli- and Delaunay-reduced and a few sheared bases of the same lattice are tried (bcc Fe at H, moments along x); if none is identified, the row keeps - in the MSG cells with the responses and class computed from the operations. At q = 0 every AFM basis vector is net-zero (see the entry on complex conjugate pairs and repeated irreps below), and the closing sentence on the AFM net moments is printed only when that holds. Rutile TiO2 with antiparallel Ti gives P4_2’/mnm’ (136.499), a d-wave altermagnet with a k_x k_y spin splitting allowed by symmetry; the Cr2O3 order gives R-3’c’ with alpha_11 = alpha_22, alpha_33; the hematite order R-3c, a g-wave altermagnet; the NiO-type order R_I-3c. The existing lines are kept; the component numbers and the files they name follow the comp<N> entry below. Python: crystod.mag.analyze_spin_basis, magnetic_space_group, macroscopic_responses, classify_collinear, magnetic_summary_rows; MCP tool crystod_mag_classify (17 tools). Test section 37; example example/37_magnetic_group; doc section 37.

  • Fixed: crystod-mag at q = 0 mixed up the copies of two-dimensional irreps that spgrep gives in a complex basis (the E irreps of trigonal and hexagonal crystals, GM5+ of rutile, also in a rotated cell): nan spins, “AFM” basis vectors with a nonzero net moment, partners along 45-degree mixtures of the symmetry directions (both partners of a copy tagged x), and magnetic groups of too low symmetry (P-1’ for the in-plane orders of Cr2O3, P2_1 for those of LuFeO3). When the copies made real one by one do not separate cleanly or their partners do not lie along directions symmetry fixes, the irrep is brought to a real form and every copy is projected with the same real matrices; the FM dipole and the AFM combinations are separated partner by partner, two or more AFM copies are fixed by their moments (the sites, the moments along the crystal axes, the products of the moments of neighbouring sites), and one common rotation turns the partners onto directions that a two-fold axis or a mirror fixes, as crystod-phonon --vibration does for displacements (for an in-plane E irrep the a axis of the input cell and the direction perpendicular to it, in the 321 and the 312 settings alike and whichever of the equivalent in-plane axes spglib calls a). Cr2O3 (Cr, GM): GM3+ gives the FM dipole along x, C2/c (15.85), and y, C2’/c’ (15.89), and the hematite-type g-wave octupoles; GM3- gives the in-plane orders + - + - and + + - -, P T antiferromagnets C2’/c (15.87) and C2/c’ (15.88). LuFeO3 (Fe, GM): GM6 gives the FM dipole along x, Cm’c2_1’ (36.174), and y, Cmc’2_1’ (36.175); GM5 the in-plane orders Cm’c’2_1 (36.176) / Cmc2_1 (36.172). Rutile rotated about z gives the groups and classes of the unrotated cell, the spin-splitting form rotated with it; rotated hexagonal and rhombohedral cells (LuFeO3, Cr2O3) give the partners along the rotated a axis and perpendicular to it. P3_112 RuCl3 (Ru) and P-31m BiI3 (I) give GM3 partners x and y, with the two-fold axis along y, instead of the [sqrt3 1 0] pair. Bases that were already real, aligned and along symmetry-fixed directions (in trigonal and hexagonal crystals: along the a axis and perpendicular to it) are kept exactly (the other examples, rutile included). Irreps that occur more than once in a single moment (monoclinic and triclinic crystals) and one-dimensional complex irreps are covered by the next entry. Tests in section 37.

  • Fixed: crystod-mag merges a one-dimensional complex irrep and its conjugate into one real two-dimensional space under the pair label (GM3+GM4+(2) at q = 0, Z3+Z4+(2) at Z), and separates the FM arrangements of an irrep that occurs more than once in a single moment; no row of the table is left unclassified. A complex irrep and its conjugate (little co-group 3, -3, 4, -4, 4/m, 6, -6, 6/m, 23 or m-3) carry the same real spin arrangements, which time reversal joins into one physically irreducible representation. They are now listed once, with the pair label that crystod-group --parent prints (GM3+GM4+, GM2GM3, GM4+GM6+), in the decomposition, the list of bases, the VESTA file names (POSCAR_Ti2Ga3_spin_GM3+GM4+_dipole_x.vesta) and the table, at q = 0, at the other time-reversal-invariant q points (P4/m Ti2Ga3: Z3+Z4+(2), A3-A4-(2); each member had been listed as a one-dimensional irrep with the same real vector, the other partner missing) and in the survey without --qpoint; every copy has two real partners, the real and imaginary parts of the complex basis vector (the real partners crystod-phonon --vibration gives the two members of the pair). No symmetry element fixes a direction in such a space (every operation acts on it as a rotation), so its global phase is a convention: the net moment of the first partner of the FM dipole copy lies along the conventional a axis and that of the second perpendicular to it, x and y of a standard cell in tetragonal, trigonal and hexagonal crystals alike (P3 HgBr GM2GM3, P6/m Nb7B8Ru6 GM4+GM6+; also for a rotated input cell), and the first partner of an AFM copy carries as much of its moments along the a axis as it can. The net moments are separated on the complex copies, so the pair has one FM dipole copy and net-zero AFM copies, each with its magnetic space group and class (P4/m Ti2Ga3, Ti 4k: the in-plane dipole along x and y, P2’/m’ (10.46), and the in-plane octupole, a d-wave altermagnet with the same group), and a note under the table names each merged pair; SpinBasisAnalysis.pair_labels lists them. An irrep that occurs more than once in a single moment (the moments perpendicular to the two-fold axis of a monoclinic crystal, any moment of a triclinic one) gets one FM row per allowed axis, the uniform moments along the axes of the partner frame (the Cartesian axes of a triclinic cell) projected onto the irrep, and net-zero AFM rows with their moments along one of those axes (P2/m MnO2: GM2+ FM along x and z, six AFM rows). The WARNING lines, the class basis not separated, SpinBasisComponent.unseparated, SpinBasisAnalysis.unseparated_labels and magnetic_group.CLASS_NOT_SEPARATED are gone with the failure they reported. Over the 228 POSCARs of example/test_POSCARs (--qpoint GM --classify-only, first element) the structures with a WARNING or an unclassified row go from 32 (16 monoclinic or triclinic, 16 with a complex pair) to 0; 134 outputs are byte-identical and 43 differ only in the component numbers (next entry); the other 51 are the 32 and 19 structures whose complex pairs were listed as two one-dimensional irreps, each with the real part of its complex basis vector only (P-3, P6_3/m, P23, Pa-3, I4/m, …), and in all of them the rows of the other irreps are unchanged. The E irreps of trigonal and hexagonal crystals and rutile GM5+ (previous entry) give the same output and VESTA files apart from the component numbers. Tests in section 37.

  • Fixed: crystod-mag at q != 0 builds the spin field of every basis vector with the Bloch factor of each site position, so every arrangement transforms like its irrep when the magnetic sites are at general positions. The basis vectors that spgrep’s projection gives carry the factor exp(2 pi i q.x_j) of the site position (the convention of phonopy’s eigenvectors), and the field over the magnetic cell was built with the factor exp(2 pi i q.T) of the cell alone, which is right only when exp(2 pi i q.x_j) is the same for all magnetic sites. The vectors are now taken in the lattice gauge w_j = v_j exp(2 pi i q.x_j), as in crystod-phonon --modulation, and the spin of site j in the cell at T is Re(w_j exp(2 pi i q.T)). P4/m Ti2Ga3 at A (Ti at general positions in the plane): the one-dimensional irreps give I_c4/m (87.80) with the four-fold axis instead of C_a2/m (12.64). At a time-reversal-invariant q the real irreps are now real in this gauge, so collinear arrangements get their direction tags in place of comp1 (La3Ni2O7 I4/mmm at (1/2, 1/2, 0): z, 1m10, 110, with the same groups; the VESTA files are renamed accordingly); AlNi3 at R and M keeps its groups, with some spins reversed or moved between equivalent sites. q = 0 is not affected. Tests in sections 36 and 37.

  • Changed: the component numbers comp<N> of crystod-mag count from 1, in the listing, the table and the VESTA file names (POSCAR_AlNi3_spin_R4+_R_comp1.vesta … _comp3.vesta), like the mode numbers of the other commands. comp<N> is the N-th basis vector of its space for a component without a single direction; the note under the table reads comp<N>: the N-th basis vector of its space. Compatibility: every _comp<N> file name moves up by one, so a script that opens ..._comp0.vesta must open ..._comp1.vesta instead. Tests in sections 36 and 37.

  • New: crystod-md --project -c PARENT --dim N1 N2 N3 [--qpoint Q ... | all] [--irrep IR ...] [--mean-lattice] [--npz] [--no-histogram], the projection of an MD trajectory onto the symmetry-adapted displacement patterns of the parent cell. Every XDATCAR frame is matched to the ideal supercell of the parent primitive cell (by element and nearest image of the time-averaged positions, independent of the atom order; composition, cell orientation within 10 % and one-to-one matching are checked), the mass-weighted centre-of-mass drift of every frame is removed, and the displacements are projected onto the bases of crystod-phonon --vibration (ISO-IR labels, mode-space and component numbers as there; the two real patterns of a complex row at a q that is not time-reversal invariant, q and -q once). Q = p_hat . u / sqrt(N) is the displacement norm per parent primitive cell, at a time-reversal invariant q the amplitude of crystod-phonon --modulation (the AMPLIMODES amplitude of an irrep in --supergroup-cif is sqrt(size) times the norm of its Q over all components and arms). Per q, a table of <Q>, sqrt<Q^2>, <|Q|>, the ratio <|Q|>/sqrt<Q^2> (0.798 for a Gaussian, 1 for two states), the excess kurtosis, the effective number of independent samples and a single/double-peaked hint, plus the components of each mode space pooled and the norm |Q|; a sum-rule block compares sum <Q^2> with <|u|^2>/N (exact with --qpoint all). Files: MDPROJ_<formula>_<q>.csv, MDPROJ_<formula>_hist.pdf, --npz. A synthetic R4+/M3+ trajectory is recovered to 1e-6 with every other component below 1e-9, the R4+ structure of --modulation --amplitude 0.3 projects to 0.3000 (AMPLIMODES 0.4243), and the 300 K NpT run of ScF3 gives single-peaked R4+ and M3+ distributions and 0.2266 A^2 per cell against 0.2281 A^2 from --adp. Python: crystod.md.project_trajectory (a TrajectoryProjection), format_projection, commensurate_qpoints. Test section 40; example example/40_md_projection.

  • New: crystod-md --project --yaml phonopy_params.yaml [--temperature T] [--star], the projection of an MD trajectory onto the phonon eigenvectors at each q, with effective frequencies. With force constants the basis at every q is the set of symmetry-adapted eigenvectors of crystod-phonon --modulation / --vector (same mode numbers): each column is the mass-weighted normal coordinate a(t) = p_hat . sqrt(m) u of the supercell (A sqrt(amu); A = a/sqrt(N) per cell), tabulated with the harmonic frequency, the statistics of the symmetry-only path, a pooled block per degenerate level and the exact sum rule sum <a^2> = <sum m |u|^2> over all commensurate q; CSV columns <mode>_<irrep> (1_R4+), default prefix MDPROJ_<formula>_phonon. The parent cell is the primitive cell of the yaml (-c is optional and must then be that cell). --temperature T adds nu_eff = sqrt(k_B T/<a^2>)/(2 pi), the frequency of the harmonic oscillator with the same mean-square normal coordinate (classical equipartition): for the 300 K NpT run of ScF3 the modes above 10 THz lie within 21 % of their harmonic frequencies, M3+ is harmonic (1.70 against 1.67 THz) and the R4+ tilts fluctuate more than the harmonic model predicts (0.74 against 1.42 THz; the run and the force constants do not share a reference, see the documentation). --star (both bases) projects every arm of the star of each requested q, one block and file per arm. The symmetry-only output of --project is unchanged. Testsuite section 40 gains 26 checks; documented in section 40 of crystod-md.

  • New: crystod-xrd --parent PARENT -c CHILD [--radiation xray|neutron] [--wavelength W], the superlattice reflections of a distorted structure indexed on the parent lattice and assigned to parent k points and irreps, and --radiation neutron --wavelength W, powder neutron patterns. The two structures (CIF or POSCAR) are paired by the symmetry-mode analysis of crystod-group --supergroup-cif; every reflection family of the child (orbit under its point group plus Friedel partners, never across parent k stars) is indexed on the conventional parent cell as exact fractions (h_conv = h_prim A^-T for a centred parent: the fundamentals of Fm-3m ZrO2 come out all even or all odd, its superlattice reflections at X), named by its parent k star (ISO-IR names of the analysis, GM for fundamentals) and, for a superlattice reflection, split among the irreps of that star by the structure factor of the parent plus each irrep’s projected displacements alone; a share of at least 95 % makes the reflection diagnostic for the irrep, and the families at which an irrep’s first-order structure factor vanishes are listed with the separating index condition when there is one. Fundamentals carry I_child and I_parent (the parent reference on the same per-cell scale). The structure factors use pymatgen’s scattering tables with no Debye-Waller factor; summed over the families at equal 2θ they reproduce XRDCalculator (SrTiO3 I4/mcm, CaTiO3 Pnma) and NDCalculator (ScF3) to 1e-6. SrTiO3 Pm-3m -> I4/mcm: 17 superlattice families, all (o o o)/2 at R, R5- 100 % (Sr-origin parent), extinct for |h| = |k|; CaTiO3 Pm-3m -> Pnma: R (R4+ / R5+, the (1 1 1)/2-type family R5+ 99 % because R4+ is extinct at first order for |h| = |k| = |l|), M (M3+ >= 99.9 %, extinct for |h| = |l|) and X (X5+), the Glazer and Woodward-Reaney classification. Output blocks * Structures *, * Radiation *, * Reflections *, * Superlattice reflections by k point *, * Output files *; files XRD_<child>_vs_<parent>_<xraytype>.txt/.pdf (ND_..._<W>A for neutrons), the PDF overlaying parent and child patterns with the superlattice ticks coloured by k star. The plain crystod-xrd -c POSCAR --radiation neutron --wavelength 1.5 runs pymatgen’s NDCalculator (nuclear scattering only) and writes ND_<cell>_1.5A.txt/.pdf; --xraytype with neutrons and --wavelength with X-rays are refused, the X-ray output is unchanged. Python: crystod.xrd.superlattice_reflections (a SuperlatticePattern of SuperlatticeReflection records with KPointSummary per star), format_superlattice_pattern, write_superlattice_table, plot_superlattice_pattern, radiation_lines, and compute_xrd_pattern(..., radiation="neutron", wavelength=W). Two stars with one name (DT (0,1/6,0) and DT (0,1/3,0) of a six-fold modulation) are kept apart (DT(0,1/3,0) in the k column); a star along which the child is not distorted reads higher order; --min-intensity trims the table only, never the k-point summary. Test section 47; example example/47_xrd_superlattice.

  • Changed: the section numbers from 37 on. The three features above take sections of their own, so the shared section numbers of testsuite.py, the example/ directories and the numbered sections of this manual run from 1 to 48 instead of 1 to 45, still grouped by command: 1 library core, 2-7 crystod, 8-24 crystod-group, 25-27 crystod-bz, 28-35 crystod-phonon, 36-38 crystod-mag, 39-41 crystod-md, 42-44 crystod-mol, 45 Python API, 46-47 crystod-xrd, 48 crystod-search. Sections 1-36 keep their numbers; for example example/38_xdatcar2adp is now example/39_xdatcar2adp, example/41_molod is example/43_molod (python testsuite.py 43) and example/45_mp_search is example/48_mp_search; scripts that call python testsuite.py N or read files below example/NN_* with N >= 37 need the new numbers. The commands and their options are unchanged.

  • Changed: phonon_irreps.yaml and phonon_irreps_all.yaml (crystod-phonon --irreps, --all-irreps) are valid YAML, and crystod.phonon.read_phonon_irreps reads them. The degenerate sets of a q point hung directly under its q_label mapping without a key, and their band indices and the special-point names were YAML comments, so yaml.safe_load and other YAML libraries rejected the file and the band indices could only be recovered from the comments. Every irreps entry now holds the sets in a band_sets list, each set starting with band_indices: [1, 2, 3] (1-based) in place of the - # 1 2 3 comment, and special_points and path_midpoints name their points with q_label (and segment) keys in place of the - # GM and - # DT (midpoint of GM-X) comments; all other keys and values (space_group, nac, the dielectric tensors, irrep_label, mulliken, frequency, activity, activity_summary, mode_effective_charge, dielectric_contribution, k_path) are written as before, and a k-path midpoint whose labeling fails gets band_sets: []. For SrTiO3, ScF3 (also with --nac), BaTiO3 P4mm and Si the new files carry the same band sets, labels, frequencies and activity lines as the files of v0.4.3. Compatibility: a script that parsed the comment lines of the old file has to read band_indices and q_label instead (or call read_phonon_irreps, which returns the file as a dictionary and raises ValueError for a file in the old layout); the shipped example files under example/28_phonon_irrep and example/32_phonon_vector/MoS2_P-6m2 are regenerated with the current code. Tests in sections 28, 29 and 35.

  • Changed: every block header of the terminal output starts at column 0 as * Title *, preceded by a blank line. The SALC listing and --atomic-orbital hybridization of crystod (* Space group *, * Crystal Orbitals *, * k point (primitive) *, * IrRep Table *, * Atomic Band Irreducible Representations *, * Result *), crystod --visualize with --element/--orbital, crystod --star-of-k, the crystal-orbital diagrams (--diagram with the extended-Hueckel, --pyscf and --vasp engines, including * k point <k> * and * Dipole selection rules at <k> *), --band --pyscf, --dos --pyscf, --chk-info, --vasp-setup, crystod-xrd and crystod-search printed their headers as * Title * with a leading space (and in places a trailing space); they now use the form of every other command. The title wording, the content lines and their indentation are unchanged. A blank line is added where a header followed its predecessor directly: * Ligand-field point charges (removed sublattice) * and * CAUTION: ... * of the extended-Hueckel diagram, * IrRep Table * of the --show-irrep-table survey, the two partial-charge blocks of --dos --pyscf (also in its TXT summary, which repeats the terminal report), and the first header of --band --pyscf, --dos --pyscf and --chk-info. A script that matched the old headers with their leading space has to drop it.

  • Changed: the modulated ScF3 structures of example/33_modulation/ScF3_Pm-3m (POSCAR_R-3c, POSCAR_I4mcm_{1,2,3}, POSCAR_Imma_{1,2,3}) are regenerated with the commands of its README, and the captured outputs of the other examples follow the current output. The shipped structures had been written with the mode numbering of v0.4.1. With the current numbering --mode 1, 2 and 3 of the R4+ triplet rotate the octahedra about a, b and c, so POSCAR_I4mcm_1 is now the rotation about a and POSCAR_I4mcm_3 the rotation about c (the old POSCAR_I4mcm_1 is the new POSCAR_I4mcm_3 byte for byte); the space groups are unchanged. Compatibility: a script that read POSCAR_I4mcm_1 as the rotation about c has to read POSCAR_I4mcm_3; example/40_md_projection and section 40 of the crystod-md manual use it. The captured output in the READMEs of examples 2, 4, 5, 19, 22, 23, 40 and 47, the VESTA files and mode tables of example/32_phonon_vector (BaTiO3, MoS2 at M, Sr3Ti2O7, and SrTiO3 with 1-based mode numbers in the file names and titles) and the sym_mode_* files of example/23_symmetry_mode are regenerated with the current code.

v0.4.3#

Highlights (details in the entries below):

  • crystod-group --parent --irrep --invariants / --secondary: Landau invariant polynomials, Landau and Lifshitz conditions, coupling terms and secondary order parameters.

  • crystod-group --parent --child [--coupled] and --graph: the irreps (or pairs of irreps) that give a subgroup, and the group-subgroup graph of the isotropy subgroups; a 10x faster stratum enumerator with a per-parent table cache.

  • crystod-group --correlate: point-group correlation tables, compatibility relations along symmetry lines, subduction of parent irreps to the Gamma point of an isotropy subgroup.

  • crystod-group --tensor: symmetry-allowed forms of property tensors (Nye matrices) for every point group.

  • crystod-group --product --symmetric/--antisymmetric and --jahn-teller: symmetrized squares, Jahn-Teller active modes and symmetry-allowed pseudo-Jahn-Teller couplings.

  • crystod --diagram: dipole selection rules between crystal-orbital levels, in the terminal and on the HTML page; the WAVECAR overlap engine for VASP.

  • crystod-phonon --irreps / --vibration --qpoint GM: IR / Raman / silent / acoustic activity, Mulliken symbols, Raman tensors, Born-charge dielectric response, Wyckoff-orbit breakdown; BORN is read only with --nac.

  • Terminal output of every command organised in titled * ... * blocks; ISO-IR k-point names with fraction coordinates in --vibration.

  • 16 MCP tools (crystod-mcp 0.2.0): six new tools for the features above.

  • Fixes: complex-conjugate pairs counted twice in the point-group reductions, hexagonal crystod-xrd, R-centred coset translations, and the label and k-point fixes listed below. Test sections are renumbered 1-45.

  • New: crystod-group --parent SG --irrep IR [IR2 ...] --invariants [--degree N], the invariant polynomials (Landau free-energy terms) of a space-group irrep or of a direct sum, the Landau and Lifshitz conditions, and --secondary, the secondary order parameters of a direction. The polynomials in the order-parameter components that are invariant under the parent group are listed degree by degree up to N (default 4), in the real basis of the direction patterns of --parent (Q1, Q2, ...), separated into products of lower-degree invariants and new ones (I<degree>_<n>), with exact coefficients where they exist; the number of invariants of every degree is checked against the Molien series. Pm-3m R4+ gives Q1^2 + Q2^2 + Q3^2, no cubic invariant and Q1^2*Q2^2 + Q1^2*Q3^2 + Q2^2*Q3^2; M1+ has the cubic invariant Q1*Q2*Q3. The Python API adds crystod.group.invariant_polynomials (an InvariantBasis) and crystod.group.landau_lifshitz (the numbers of cubic and Lifshitz invariants, a LandauLifshitz record); the engine crystod.invariants.invariants_of_matrices takes any finite real matrix group. Several --irrep labels give the invariants of the direct sum by multidegree (variables <label>_<n>, e.g. degree (1, 1, 1): 1 invariant) and name the lowest-order coupling term: I4/mmm X2+ X3- GM5- has the trilinear term of hybrid improper ferroelectrics, Pm-3m R4+ M3+ the biquadratic (2, 2) (crystod.group.coupling_terms, a CouplingTerm). With --order-parameter, --invariants also prints the free energy restricted to that direction (R4+ (a,b,0): a^2 + b^2, then a^4 + b^4; a^2*b^2). With --invariants, --order-parameter, --degree or --secondary, the * Irrep * block has the Landau line (cubic invariants), the Lifshitz line (Lifshitz invariants) and the verdict on a continuous transition; the plain enumeration --parent SG --irrep IR [IR2 ...] and the --parent SG --kpoint K table are unchanged. --parent SG --irrep IR [IR2 ...] --order-parameter DIR --secondary lists the irreps of Gamma and of the tabulated special k points with a component fixed by the isotropy subgroup, with the number of free parameters, the direction, the lowest coupling term Q^m eta that does not vanish on the fixed space of the subgroup, and the type (primary, polar, strain, other): Pm-3m R4+ (a,0,0) gives the GM1+ and GM3+ strains of I4/mcm, the hybrid improper Cmc2_1 of I4/mmm the polar GM5- through Q1^1 Q2^1 eta, and for the Pnma tilt system of Pm-3m (R4+ (0,a,a) + M3+ (d;0;0)) X5+, R5+ and M2+ (crystod.group.secondary_order_parameters, SecondaryOrderParameter records). The Molien counts use the traces of the matrix powers instead of eigenvalues (LAPACK’s eigenvalue solver failed to converge on matrices of the 12-component W irreps of Fm-3c), a degree whose largest linear problem has more than 20000 monomials is refused before the work (ERROR: ... lower --degree), and compound coefficients such as -1 + sqrt(3) (P4_332 R3) are printed as one parenthesized signed unit with the positive terms first ((sqrt(3) - 1)). The defensive origin-shift fallback of InducedRepresentation uses the same conjugate-and-wrap character rule as the label matching and warns when it needs a nonzero origin shift, and the real-type realification stops with a clear error instead of building a non-unitary basis (no output changes). The MCP server gains the tool crystod_invariants (the invariants, Landau and Lifshitz lines, coupling term and, for a direction, the restricted free energy and secondary order parameters, as Markdown). Tests in a new section 18.

  • New: crystod-group --parent G --child H [--size N] [--index N] [--kpoint K ...] [--coupled [--secondary]], the reverse lookup of isotropy subgroups, --parent SG --irrep IR [IR2 ...] --graph [--output FILE] [--graph-dot], the group-subgroup graph of the isotropy subgroups, and a faster --parent enumeration (2-10 times, most for large stars). --child lists every stratum of every irrep at the special k points of G whose isotropy subgroup has type H (symbol or number; in a parent with improper operations the enantiomorphic partner type counts, with a note:, in a Sohncke parent it does not; a complex-type pair spanning the k and the -k star is listed once), with the k point, direction, cell size, index and the conventional basis and origin of the subgroup: Pm-3m --child I4/mcm gives R4+ (0,0,a) among ten rows, --child R-3c gives R4+ (a,a,a), and --child Pnma --size 4 reports that no single irrep gives the tilt system (it names --coupled). The first run for a parent builds the table of all its strata and caches it as $CRYSTOD_CACHE_DIR/isotropy/<number>_<version>.json.gz (default ~/.cache/crystod); later runs read it, --no-cache rebuilds it, and a file built from other CrystOD sources is rebuilt. Python: crystod.group.find_isotropy_irreps (IsotropyMatch records) and crystod.group.isotropy_table (an IsotropyTable). The stratum enumeration of --parent (IsotropyAnalyzer.enumerate_directions) intersects new subspaces with the element fixed spaces only, with batched SVDs over cached element matrices, and replays the discovery order of the pairwise closure, so every table is unchanged (row order, direction labels and subgroups; 3506 exact + 28 enantiomorph against ISOSUBGROUP as before); --parent Fm-3m --kpoint W takes about 50 s instead of about 530 s. enumerate_directions(method="legacy") keeps the pairwise closure for comparison. --coupled searches the pairs of irreps (same k point first, then different k points) for coupled strata of type H that need both irreps, by intersecting the isotropy subgroups of the single strata of the cached table (only irreps with a stratum whose point-group order is a multiple of that of H take part), and lists them under * Coupled isotropy subgroups of type H * with both directions, size, index and setting: Pm-3m --child Pnma --size 4 --coupled gives the tilt system R4+ (0,a,a) + M3+ (d;0;0) among 32 rows (about 10 s), I4/mmm --child Cmc2_1 X2+ (0;a) + X3- (0;c), Cmcm --child Pna2_1 Y4+ + Y2-; --secondary adds the secondary order parameters of every row, and 50 seeded rows of the HIF survey are all recovered with their strata. --graph writes SUBGROUP_<SG>_<irreps>.html, an inline SVG of the parent, every stratum of the irreps and of their direct sum (including the single-irrep strata) and the kernel, layered by index, with the maximal-subgroup lines up to conjugacy (projector-orbit inclusion test, transitive reduction) and the setting of every node on hover; a line from the parent is dashed when the Landau or Lifshitz condition of its irrep fails (Pm-3m M1+), lines between strata are solid (their continuity is not tested); --graph-dot also writes a Graphviz .dot file. --parent Pm-3m --irrep R4+ M3+ --graph contains the 15 tilt systems of Howard and Stokes (Acta Cryst. B54, 782 (1998)) with the 25 group-subgroup relations among them (the relations their figure draws), plus the ten strata with in-phase and out-of-phase tilts about one axis. Python: crystod.group.find_coupled_isotropy_irreps (CoupledIsotropyMatch records; also find_isotropy_irreps(..., coupled=True)) and crystod.group.subgroup_graph (SubgroupGraph, GraphNode, GraphEdge). Tests in sections 19 and 20; examples in example/19_child_lookup and example/20_subgroup_graph. The MCP server gains the tools crystod_find_isotropy_irreps (the single-irrep and, with coupled=true, the coupled strata of type H as Markdown tables, from the same cached isotropy table) and crystod_subgroup_graph (the nodes by index layer and the solid or dashed edge list, as text).

  • New: crystod-group --correlate, the subduction of parent irreps to the Gamma point of an isotropy subgroup (--correlate --parent SG --irrep IR --order-parameter C... [--irrep-list IR ...]), the compatibility relations along a symmetry line (--correlate --sg SG --kpoint K0 K1 [--line L]) and point-group correlation tables (--correlate --pg G --subgroup H). The correlation table generates every subgroup of the point group G, groups those of type H into conjugacy classes under G and restricts the irreps of G to one representative per class, so each inequivalent orientation of H is one column (m-3m has three classes of mm2: the twofold axis along z with the axial or the diagonal mirrors, and along [110]; 4/mmm three of 2/m); the symbols are those of phonopy’s table of H with its classes placed as printed under * Subgroup * (both settings of -42m, 3m, -3m and -6m2 are tried, and the header names the setting when it is that of the axes of G). m-3m -> 4/mmm gives Eg -> A1g + B1g, T2g -> B2g + Eg, T1u -> A2u + Eu, m-3m -> -3m T2g -> A1g + Eg, -43m -> 3m T2 -> A1 + E; m-3m -> 4/mmm, -3m, 4mm, 3m and mmm (axial class) agree with the Altmann-Herzig tables, and 4/mmm -> mmm with the twofold axes along the diagonals gives their D4h -> D2h(C2’’) column; the dimensions add up for every irrep of all 32 point groups and all 222 (G, H) pairs (279 orientations), and m-3m has its 98 subgroups in 33 classes. The subduction averages every parent irrep over the translations of the isotropy subgroup H, decomposes the invariant part into the Gamma irreps of H with the ISO-IR labeler of H (Mulliken symbols in brackets) and counts the rest as components at non-Gamma k of H; the ISO-IR frame of H the labels refer to is printed as a basis and an origin in parent conventional units. Pm-3m R4+ (0,0,a) gives GM1+ [A1g] + GM5+ [Eg] of I4/mcm (SrTiO3), R4+ (a,a,a) GM1+ [A1g] + GM3+ [Eg] of R-3c, the Pnma tilt system R4+ (0,a,a) + M3+ (d;0;0) Ag + B1g + B2g from R4+ and Ag plus two non-Gamma components from M3+; the identity irrep occurs in a primary irrep once per free parameter of the direction (checked). The compatibility relations restrict the small irreps of both end points to the little group of a point of the line, with the translation phases corrected for the wave-vector difference, and decompose them into the ISO-IR line irreps: Pm-3m GM4- -> DT1 + DT5, GM5+ -> DT3 + DT5 (Delta1 + Delta5 and Delta2’ + Delta5), Si (Fd-3m) X1 -> DT1 + DT3; one --kpoint name lists every line from that point. The dimensions add up for every pair of special points of all 230 space groups. Python API: crystod.group.subduce_to_child (Subduction records), compatibility_relations (Compatibility records), format_subduction, format_compatibility, correlation_table (a CorrelationTable), format_correlation_table. Tests in a new section 16; example in example/16_correlate. The MCP server gains the tool crystod_correlate, which takes the arguments of exactly one of the three forms (point_group and subgroup; space_group and kpoints; parent, irreps and direction) and returns the result as Markdown tables.

  • New: crystod-group --product IR IR --symmetric / --antisymmetric, the symmetric and antisymmetric squares of a point-group or space-group irrep, and crystod-group --jahn-teller IR [IR2] --pg PG, the Jahn-Teller active modes and the symmetry-allowed pseudo-Jahn-Teller coupling modes. After the plain product, * Symmetric square * prints [T2g x T2g] = A1g + Eg + T2g and * Antisymmetric square * prints {T2g x T2g} = T1g (m-3m), with a dimension check; they agree with the singlet and triplet terms of --multiplet T2g2. With --sg the square of a full irrep is reduced from the characters (chi(g)^2 +- chi(g^2))/2 of the order-parameter matrices of --parent into the irreps at the stars of k_a + k_b, with ISO-IR labels: Pm-3m [R4+ x R4+] = GM1+ + GM3+ + GM5+, [X5+ x X5+] with terms at Gamma and M; a complex-type irrep is squared in its real form D + D* (P1P3 of I4/mcm, with a note: line); the identity irrep of the symmetric square equals the number of quadratic invariants of --invariants. --jahn-teller Eg --pg m-3m prints [Eg x Eg] = A1g + Eg and JT-active: Eg (T1u: Eg + T2g); two irreps give the symmetry-allowed pseudo-Jahn-Teller coupling modes of the plain product (Eg x T2g = T1g + T2g), printed with a note that this is a necessary condition only (the energy gap and the vibronic coupling strength decide whether the mixing destabilizes the structure), and for two identical labels the first-order Jahn-Teller modes of that level. Python API: crystod.group.symmetric_square, antisymmetric_square, jahn_teller_modes (a JahnTellerModes record) and SpaceGroupIrrepAlgebra.decompose_square (a SquareDecomposition). Tests in a new section 9.

  • New: crystod-group --tensor KIND --pg PG | --sg SG | -c POSCAR, the symmetry-allowed form of a property tensor (Neumann’s principle). KIND is dielectric, pyroelectric, piezoelectric, elastic, compliance, gyration, raman or any Jahn symbol (V[V2], [[V2]2], e[V2], a[V2], … up to rank 6). The output gives the point group with its axes and symmetry elements, the number and names of the independent components, the matrix form in Nye’s notation (d_iL with the factor 2, s_LM with the factors 2 and 4) and the relations (c66 = (c11-c12)/2, s66 = 2(s11-s12)); the counts reproduce Nye’s tables for all 32 point groups. --sg takes the point group of the default setting, -c that of spglib’s standard conventional cell, with the tensor axes printed in the input frame. --tensor raman lists the Raman tensor of every Raman-active irrep (Mulliken labels; with -c, the Γ phonon irreps with ISO-IR labels, as crystod-phonon --raman-tensor). A time-odd tensor vanishes in the grey group of a non-magnetic crystal, as stated in the output. API: crystod.group.tensor_form, TensorForm, format_tensor_form, raman_forms. The MCP server gains the tool crystod_tensor_form (kind and one of point_group, space_group, poscar; the independent components, matrix form and relations, or the Raman tensors per irrep, as Markdown).

  • New: dipole selection rules in the crystal-orbital diagrams (crystod --diagram, every engine). Each k point ends with a * Dipole selection rules at <k> * block: the VBM -> CBM transition is allowed (x, y, z), allowed (z) or forbidden (Γf* ⊗ ΓV ⊗ Γi ∋ Γ1 of the little group, resolved per Cartesian component with the representation matrices of the ISO-IR-labelled small irreps; vertical transitions), followed by the first allowed transition when the band edge is forbidden. The HTML page carries each crystal level’s irrep and a per-k table of allowed pairs: click one level and then another to see the verdict (empty space clears). SrTiO3 Γ: O 2p GM5- -> Ti 3d GM5+ allowed; Cu2O Γ: Cu 3d GM5+ -> Cu 4s GM1+ forbidden; Si Γ: GM5+ -> GM4- allowed. The polarizations refer to the Cartesian axes of the input POSCAR (the frame of the crystod-phonon --raman-tensor tensors); an allowed direction that is not a coordinate axis, in a rotated input cell or along a k arm such as M or L of a hexagonal cell, is printed as a vector in the input frame (allowed (0 1 -1), allowed (sqrt(3) 1 0)); the click-to-click verdict on the page shows the same text as the terminal. Python API: crystod.salc.dipole_selection_rules(diagram[, kpoint]) (every k point of a diagram), band_edge_selection_rules, little_group_dipole_table, format_dipole_selection_rules. Spin-orbit levels are not evaluated. Example: example/04_selection_rules. Tests in a new section 4.

  • New: crystod --diagram --vasp --vasp-engine overlap, crystal-orbital diagrams from the VASP wavefunctions with no energy alignment. The --vasp engine puts the sublattice columns on the crystal’s scale with one shift per site, fitted to the levels that symmetry forbids to mix; where a site has none — Ge 4s/4p in SrGeO3 and Pb 6s/6p in CsPbI3 at Γ, X, M and R — the fit absorbs the very bonding shift the diagram is meant to show. The new engine reads the three WAVECARs instead and computes the all-electron PAW overlaps between the Bloch states of the sublattice runs and those of the crystal (seconds per run; --vasp-cache FILE keeps them, and with no run directory the analysis runs from the cache alone), so it writes the crystal Kohn–Sham Hamiltonian in the basis of the sublattice orbitals and needs no alignment at all: the crystal levels up to VBM + 14 eV are reproduced exactly (--vasp-frozen-window, --vasp-frozen-qmin), the empty active orbitals above come from a projection-only disentanglement (the dotted effective levels), the fragment columns are the frozen-ion parent levels (occupied sublattice orbitals orthonormalized first, the empty ones projected off them), the colours the sign of the symmetric-Löwdin inter-sublattice COHP, the connectors the Löwdin populations, and every parent carries its energy ledger — bare ⟨φ|H|φ⟩ → Pauli shift → closed-shell or empty–empty mixing → covalent shift — with the covalency count of every k point. On SrTiO3 the Γ e_g–t₂g splitting of 2.22 eV is Pauli 1.91 + covalent 0.28 eV, and the CBM Γ5+ and the VBM R4+ come out exactly nonbonding. The active space is the minimal valence set (--vasp-shells, default the POTCAR valence shells plus one standard empty shell, printed), the irrep labels are computed from the plane waves (new crystod.wavecar_irreps, CrystOD’s ISO-IR labels in the crystal’s frame for all three runs), and spin-orbit (vasp_ncl) runs are read with their double-valued irreps (-R6+, drawn R̄6+ with one bar per Kramers pair; IrRep’s Bilbao names with --vasp-irrep-json; --vasp-scalar-reference lists the compatible scalar levels, Γ × D(1/2)). Outputs: CrystOD_<cell>_vasp_overlap.html, .json and .txt (_soc for spin-orbit runs), the report’s Key results also in the terminal. --vasp-setup --vasp-engine overlap writes LWAVE = .TRUE. and checks that the crystal bands reach VBM + 17 eV. On the SrTiO3, SrGeO3, CsPbI3 and CsPbI3 + SOC runs of example/03_hybridization/vasp_overlap every energy, population, COHP and ledger value agrees with the reference analysis; the default --vasp-engine anchor is unchanged.

  • New: IR / Raman / silent / acoustic activity of the Γ phonons in crystod-phonon --irreps and crystod-phonon --vibration --qpoint GM. A mode is IR active when its irrep occurs in the vector representation of the point group, Raman active when it occurs in its symmetric square, silent otherwise, and the three rigid translations are reported as acoustic. --irreps adds an activity: [...] line to every degenerate set at GM and an activity_summary: line to the GM block of phonon_irreps.yaml (all other lines unchanged), and prints the summary in a * Gamma-point activity * block, one irrep per line (GM4- [T1u] x4 (3 IR, 1 acoustic), GM5- [T2u] x1 (silent) for SrTiO3); --vibration --qpoint GM adds activity = ... to every mode space, the same summary (the acoustic count from the vector representation) and an activities array to --export-npz. SrTiO3 (4 T1u + T2u), Si (T2g Raman only) and BaTiO3 P4mm (A1, E IR and Raman, B1 = GM2 Raman only) agree with the Bilbao SAM tables. The Python API adds crystod.phonon.gamma_mode_activities (from a phonopy object or a structure), classify_gamma_irreps, format_activity_summary and the Activity record, and PhononMode gains an activity field (filled at Γ). A degenerate set that holds several irreps (more than one label) is split per irrep: its acoustic bands (the sum of the rigid-translation weights of its eigenvectors) go to the irreps of the vector representation and every other copy keeps its own activity, so a wide --tolerance no longer changes the summary. With --nac, --irreps also reports the mode effective charges, the contribution of every Γ set to the static dielectric tensor, eps_0, the acoustic sum rule of the Born charges and a Lyddane-Sachs-Teller check (ScF3: eps_0 = 7.59 from eps_inf = 2.28, LO/TO product 3.3240 = eps_0/eps_inf), on the terminal and as dielectric_electronic: / dielectric_static: header lines and mode_effective_charge: / dielectric_contribution: lines per Γ set in phonon_irreps.yaml; an imaginary optical mode with a dipole is flagged, since it makes eps_0 meaningless. The new --raman-tensor (with --irreps or --vibration --qpoint GM) prints the symmetry-allowed Raman tensors of the Raman-active Γ irreps in the Cartesian axes of the input cell (Si T2g, BaTiO3 A1/B1/E and ZnO A1/E1/E2 as in Loudon’s tables; a two-dimensional irrep that occurs twice, the E of the trigonal point groups, is printed per partner with constants shared across the partners, e.g. Bi Eg [[a, 0, 0], [0, -a, b], [0, b, 0]] and [[0, a, b], [a, 0, 0], [b, 0, 0]]), and --vibration --qpoint GM breaks the mode spaces down by Wyckoff orbit (SrTiO3: Sr 1a GM4-, Ti 1b GM4-, O 3c 2 GM4- + GM5-), as the Bilbao SAM program does. API: gamma_raman_tensors, raman_tensor_basis, format_raman_tensors, wyckoff_orbit_decomposition, format_wyckoff_orbits, mode_effective_charges, dielectric_response, format_dielectric_table and the records RamanTensors, WyckoffOrbit, DielectricResponse, DielectricSet. The MCP server gains the tool crystod_phonon_activity (the Γ activity table, Wyckoff-orbit breakdown and Raman tensors of a POSCAR, without force constants). Every Γ irrep label of --vibration (mode spaces, activity summary, Wyckoff orbits, Raman tensors) and of the --irreps terminal summary and Raman tensors is followed by its Mulliken symbol in square brackets (GM4- [T1u]), and phonon_irreps.yaml gains a mulliken: line after irrep_label: in every Γ set (A1 + E for a set holding two irreps); the symbols come from phonopy’s point-group character tables after the rotations are carried to the conventional standard setting as phonopy does it, so they agree with phonopy’s own labels (B1/B2 in its axis convention; a complex-conjugate pair gets the symbol of the physically irreducible pair, E of 3), API crystod.phonon.mulliken_symbols. The output of crystod-phonon --vibration is laid out in blocks with * ... * headers (* Q points (primitive) *, * Selected Q point *, * Irrep-grouped vibration spaces *, * Gamma-point activity * with one irrep per line, * Wyckoff-orbit breakdown (Gamma) *, * Raman tensors (Cartesian axes of the input cell) *, * Selected basis vector *), without the mode-space count line and the --mode-index hint; the q-point list is the set of ISO-IR special points that --irreps writes under special_points: (no seekpath names such as GAMMA or H_2), in the order of seekpath’s special-point table (GM, R, M, X for Pm-3m; GM, A, K, H, M, L for P6_3mc; phonon_irreps.yaml may list them in another order), with fraction coordinates ((1/3, 1/3, 1/2)), and --qpoint takes those names (the seekpath names and GAMMA/G/Γ are still accepted). Tests in a new section 29.

  • Changed: crystod-phonon reads the BORN file only with --nac. phonopy’s loader applies the non-analytical term correction by default and silently read a BORN file lying in the working directory (or the NAC parameters stored in a phonopy yaml) in --irreps, --vector, --modulation and --subgroup, and in the MCP phonon tools; near Γ this changed the LO frequencies (ScF3 at q = (0.1, 0, 0): 19.91 instead of 14.98 THz) without saying so. All crystod-phonon modes that read force data now take --nac, apply NAC only with it (BORN from the working directory, --modulation also next to the cell file, the yaml’s own NAC parameters first with --yaml), print where the charges came from, and stop with an error when --nac finds none; phonon_irreps.yaml records nac: true / nac: false in its header. Without --nac the results are those without NAC whatever files are present (the special-point labels and frequencies of --irreps are the same either way); the MCP tools never apply NAC, and SymmetryAdaptedModulation(yaml_path=...) loads the yaml without NAC (pass a phonon loaded with is_nac=True for it). --vibration rejects --nac. The error of --nac without a BORN file names every directory that was searched (for --modulation, the working directory and the directory of the cell file).

  • Fixed: crystod-group --product and --basis counted a complex-conjugate pair of point-group irreps twice. The character tables list such a pair as one real irrep (E of 3, 4, 6, -4, 4/m, Eg of m-3, …), whose character has norm 2, and the reduction divided by the group order only: --product E E --pg 3 gave 2(A) + 2(E) (dimension 6 for a 4-dimensional product) and --basis x y z --pg 4 gave 1.0 [A] + 2.0 [E]. The reduction now divides by the norm of each irrep character (2(A) + 1(E), 1.0 [A] + 1.0 [E]); groups without such pairs are unchanged. For -4 the class sizes were also taken in the wrong class order (--basis x y z --pg -4 gave 1.0 [E], now 1.0 [B] + 1.0 [E]), and point group 1 no longer crashes (--product A A --pg 1, --basis x y z --pg 1). Tested in section 9.

  • Fixed: crystod-group --decompose, --ligand-field and --multiplet counted a complex-conjugate pair of point-group irreps twice, and took the class sizes of -4 in the wrong order. The same reduction error as --product: these modes divided by the group order instead of the norm of each irrep character (2|G| for the real pairs E of 3, 4, -4, 23, E1/E2 of 6, Eg of m-3, …). --ligand-field d --pg 4 gave 1(A) + 2(B) + 2(E) (7 orbitals for a d shell), now 1(A) + 2(B) + 1(E); --decompose --pg 4 --characters 2 0 -2 gave 2(E), now 1(E); --multiplet E2 --pg 3 gave ^3A + ^1A + 2(^1E) with a state-count warning (8 states for C(4,2) = 6), now ^3A + ^1A + ^1E; and --multiplet Eg2 --pg m-3 --orbital d stopped with a projector-rank error, now it prints the (eg)^2 energies A - 8B, A + 8B + 4C, A + 2C. The class sizes are now looked up by class label, since the table of -4 lists them in another order than the characters: --ligand-field d --pg -4 printed 1S4: -1, 2C2: 1 and gave 2(A) + 2(B) + 2(E), now 2S4: -1, 1C2: 1 and 1(A) + 2(B) + 1(E) (the --decompose --pg -4 prompt had the same wrong sizes). --multiplet A2 --pg 1 (also with --orbital s --visualize) no longer stops with an IndexError. The same reduction gives the Gamma = line of crystod-mol --xyz ... --element ... --orbital ... (the H p orbitals of a C3 molecule with three H sites: 3(A) + 6(E), now 3(A) + 3(E)) and the results of the MCP tools crystod_decompose_representation and crystod_ligand_field; the note of crystod_ligand_field for these point groups now says that 1(E) is one doubly degenerate level (it said 2(E)), and the non-integer check of crystod_decompose_representation divides by the norm of each irrep, so characters that are no representation, such as [1, 0, -1] in point group 4 (half an E), get the WARNING they used to miss. The other point groups are unchanged. crystod.group.decompose takes the class sizes as an optional argument (by default from the table). Tested in sections 10, 11 and 21 over all 32 point groups.

  • Fixed: crystod --chk-info FILE stopped with KeyError: 'electrons' on every checkpoint --pyscf writes. The checkpoint stores the oxidation states but not the electron count (--electrons only fills the diagram’s levels, so it is deliberately not part of the stored conditions); --chk-info now prints the oxidation states and the SCF convergence settings, still prints the electron count of a file that has one, and leaves --oxidation out of the reuse string when none is stored. Tested in section 7.

  • Fixed: crystod-group --coset --pg G --subgroup H exited with code 0 when H is not a subgroup of G in the tabulated axes. It printed the * Groups * block and a multi-line ERROR: message; it now stops with one ERROR: ... line naming both groups and their orders and exit code 1 (--pg m-3m --subgroup 3m: the trigonal groups are tabulated in hexagonal axes). Tested in section 15.

  • Fixed: the primitive-basis translations behind crystod-group --coset --sg did not form a group for R3c and R-3c. The conventional fractional translations were carried to the primitive basis as a row vector (t M^-1) instead of a column vector (M^-1 t), which is the same only for a symmetric centring matrix; with the rhombohedral one, 12 of the 36 products of R3c (161) and 48 of the 144 of R-3c (167) fell outside the set modulo lattice translations. The printed cosets use the rotations only and are unchanged. Tested in section 15 (closure of all 230 space groups, and the R-3c cosets at Gamma and L).

  • Fixed: crystod --diagram --vasp read a spin-orbit run as a scalar one. A vasp_ncl run (LSORBIT, LNONCOLLINEAR) holds one Kramers partner per band, and the PROCAR engine counted every band as a doubly occupied level, so a CsPbI3 + SOC diagram came out with one-electron “R1+” levels and halved degeneracies, without a word. The run is now refused in one line that points to --vasp-engine overlap, which reads spinor runs.

  • Fixed: crystod --diagram --vasp could anchor the rigid alignment on an empty level instead of the semicore band. The PROCAR projection has one channel per (atom, l), so it cannot tell the Sr 4s semicore band of SrTiO3 from the empty Sr 5s-like level over 40 eV above it: at R, where no O state shares the irrep, both overlap the Sr 4s R2- fragment level at 1.000, and the anchor took whichever came out larger in the last digit. The PBE runs have the same tie and were right only because their two overlaps came out bit-identical and the first maximum was kept; on a METAGGA = LAK run the semicore overlap came out 4e-16 below 1 and the rigid cation-column shift — --vasp-align rigid, and the diagnostic, the RIGID alignment line of the default report — came out at +15.695 eV with a 45.779 eV spread over the four k points instead of +4.257 eV with 0.025 eV, and at +50.022 eV with --kpoint R. The crystal counterparts of the alignment anchors are now assigned one-to-one in energy order: the deepest fragment level of such a ladder goes with the deepest crystal level, the next with the next, which is all a radially blind projection can tell. The rigid shift also places the fragment levels against the anchor-window cut in the first pass of the default site-resolved fit, and it is the shift a column falls back to when none of its elements finds an anchor. On the four-k-point run neither decided anything, and every site-resolved number is unchanged (Sr +4.154, Ti +14.088, O +6.284 eV); with --kpoint R the +50 eV shift had pushed every Sr and Ti level out of the cut, the cation column took the fallback and vanished from the page, and it is now drawn with Sr +4.268 and Ti +16.519 eV. The PBE and CaF2 runs and the --pyscf engine (a genuine overlap, under which an inert counterpart is unique anyway) give the same numbers as before, now by construction. A trimmed copy of the LAK runs is the new test fixture example/03_hybridization/vasp_SrTiO3_LAK.

  • Fixed: a meta-GGA VASP run was labelled “PAW”. crystod --diagram --vasp read the functional from the GGA = line of the crystal run’s OUTCAR only, and a meta-GGA run writes none — its OUTCAR names the functional on a METAGGA = LAK line — so the report said functional PAW, the page chip VASP PAW/PAW and the level JSON "functional": "PAW". The METAGGA tag now wins (LAK, SCAN, R2SCAN, … as VASP spells it, in upper case) and the GGA tag is the fallback (PE is still shown as PBE); the METAGGA= F flag VASP 5 writes into every run is not taken for a functional. crystod.vasp_io.read_outcar also returns the two tags separately, as "metagga" and "gga".

  • Fixed: a POSCAR in Cartesian coordinates under a scale factor, or with a negative scale factor, was read as another crystal. VASP multiplies the lattice vectors and Cartesian coordinates alike by the factor of line 2; a negative factor is the cell volume (the factor is then (|s| / |det A|)^(1/3)), and the line may hold three factors, one per Cartesian axis. CrystOD read POSCARs with three parsers, and none of them did all of that. crystod.vasp_io.read_poscar (the run directories of crystod --diagram --vasp) scaled the lattice and left Cartesian coordinates as written. phonopy 4.3.0, which read every -c file and the unit cell of every crystod-phonon mode, does the same, takes a negative scale for a plain factor (the lattice comes out inverted and of the wrong size, for direct coordinates too) and stops on three factors. pymatgen (pymatgen-core 2026.5.18; crystod-xrd, crystod-group --poscar2cif and --supergroup-cif) multiplies Cartesian coordinates by the negative number itself. With scale 1, and with direct coordinates under a positive scale, all three agree with VASP, and all 404 POSCARs shipped with CrystOD are of that kind, so no test saw it. What it did: SrTiO3 written in Cartesian coordinates with scale 2 has every atom at half its fractional coordinates and was analysed as an R3m crystal (crystod-phonon --irreps wrote space_group: R3m with the points GM, F, L, T and exit status 0; --subgroup --qpoint R answered that the group has no point R); with Cartesian coordinates under a negative scale crystod-group --poscar2cif wrote an R3m CIF with a = 5.5793 for the cubic 3.9451 Å cell and crystod-xrd the pattern of “ScF3, R3m”, while the phonon modes ended in a traceback or an error, as did every file with three factors. crystod --diagram --vasp-setup on a Cartesian crystal POSCAR with scale 2 stopped with “the run’s lattice has the same lengths and angles but a rotated basis” for SrTiO3 (the misplaced copy is rhombohedral), as --vasp did; for a crystal without symmetry, whose misplaced copy keeps its primitive basis, it wrote the two sublattice POSCARs, and rewrote the crystal run’s own, with every atom at half its coordinates and exit status 0. There is now one rule, crystod.vasp_io.poscar_geometry, VASP’s own reading (one factor, a volume or three factors; Cartesian when the mode line starts with C, c, K or k, after an optional selective-dynamics line; the VASP 4 layout without a species line too), and every reader goes through it. read_poscar takes its cell from it, and the correction the WAVECAR-overlap engine applied on its own (crystod.vasp_wavecar) is gone. crystod.vasp_io.read_poscar_cell gives the phonopy cell behind every -c file and behind --irreps, --fatband, --lt, --vector, --subgroup and --modulation (which now hand the cell, not the file name, to phonopy.load): it keeps phonopy’s own cell where that is VASP’s and otherwise gives phonopy the same file in the plain spelling (scale 1, direct coordinates), so the chemical symbols remain phonopy’s. crystod.vasp_io.poscar_structure corrects the cell of the three pymatgen readers in the same way. A file in direct coordinates with a positive scale is handed on exactly as phonopy and pymatgen read it, so nothing changes for it: the page, the level table and the JSON of the SrTiO3 fixture are the same byte for byte. Three per-axis factors are read by the --vasp engines and the phonopy-based commands; crystod-xrd, --poscar2cif and --supergroup-cif still stop there with pymatgen’s message. The MCP tools that take a POSCAR (crystod_special_kpoints, crystod_crystal_orbital_irreps, crystod_phonon_irreps, crystod_imaginary_mode_subgroups) read it through the same reader with CrystOD 0.4.3 or later. In Python, crystod.vasp_io.read_poscar_cell(path) replaces phonopy’s read_vasp / read_crystal_structure for such files. Tests in section 3 (the three POSCARs of the SrTiO3 fixture in Cartesian coordinates with scale 2, 0.5 and -V, in direct coordinates with -V and with three factors, on the cubic and on a triclinic lattice, through the four readers, the anchor engine’s run mapping and --vasp-setup; a crystal without symmetry through --vasp-setup; a check that no module reads a POSCAR past the rule) and in crystod-mcp/tests.

  • New: crystod-group --parent SG --kpoint K lists the isotropy subgroups of every irrep of a k point in one table. crystod-group --parent Pm-3m --kpoint GM prints the ten irreps GM1+ … GM5- of Pm-3m with their order-parameter directions, subgroups, cell sizes and indices (29 rows) — the survey to start from when the irrep of a distortion is not known yet, where --irrep had to be run once per label. The output has the * Supergroup * block, a * Kpoint * block (the name, then the tabulated arm and the number of arms of the star) and a single table in the order of the ISO-IR tables; every irrep contributes the rows of its own --irrep table, and the enantiomorph note is collected under it. The k point is an ISO-IR name (GM, R, X, …; the case is ignored and G/Gamma mean GM) or three coordinates in the primitive reciprocal basis: any arm of the star and any q + G spelling resolve to the tabulated point (--kpoint 0.5 0.5 0.5, -1/2 1/2 1/2 and R give the same table; 0 0.5 0.5 is M). Decimals within 0.0005 of a special point are taken for it (0.333 is 1/3). An unknown name, or coordinates on a symmetry line or plane or at a general point, stop with an error that lists the k points of the space group with their coordinates, and so does --parent SG given neither --irrep nor --kpoint; an irrep label given to --kpoint is answered with its k point and the --irrep form; --kpoint is refused together with --irrep or --order-parameter. The two members of a complex-conjugate pair are listed once under their pair label (GM2+GM3+ of Pm-3): the block is the --irrep table of the first member, whose basis the order-parameter components refer to; whether two irreps are such a pair is decided from the representations themselves, not from their labels. An irrep whose enumeration fails no longer costs the whole table: the others are printed, the failed one is named in a note: LABEL: not enumerated (...) line, and the exit status is nonzero only if no irrep could be enumerated. In Python, crystod.group.isotropy_subgroups_at_kpoint(space_group, kpoint) (also in crystod.phonon and at the top level) returns the same table as a KpointIsotropySubgroups mapping from irrep label to IsotropySubgroup records, with the k-point name, its coordinates, the number of arms and the failed irreps (errors) as attributes; the command and the function share the k-point resolution and the loop over the irreps. The other space-group modes that take --kpoint (--table, --basis, --generate-basis, --coset) still require three coordinates and say so when given a name; all of them now also accept negative fractions (--kpoint -1/2 1/2 0), which argparse used to reject. Tested in testsuite sections 17 and 43.

  • Fixed: wrong complex-conjugate pair labels at 27 k points of 11 space groups. For a complex-type irrep crystod-group --parent SG --irrep IR (and crystod.group.isotropy_subgroups) names the physically irreducible order parameter by the irrep and its conjugate partner (P1P2, H1HA1). The partner was looked up from the characters of the coset representatives alone, which several irreps of one k point can share while they differ on the lattice translations; the first such irrep was taken. The 64 affected irreps are at P/PA of I-4 and I23, P of I4/mcm, H/K/HA/KA of P3, P3_1, P3_2 and P-6, H/HA of P31c and P-62c, and H of P6_3/m and P-6c2: --parent P3 --irrep K2 printed K2K3 for what is K2KA2, --parent I4/mcm --irrep P2 printed P1P2 for P2P4, --parent P6_3/m --irrep H4 printed H3H4 for H4H5. The partner is now the tabulated irrep with the same real form on every group element, translations included. All 1298 doubled irreps of the 230 space groups were re-checked against the matrices actually enumerated, and the pair label of every complex-type irrep is found in the IR column of the ISOSUBGROUP reference table of its k point wherever SUBGROUP/ has one (909 irreps). This fix changes only the pair labels: the subgroups, sizes, indices and direction strings of the 64 irreps are those of v0.4.2, and no other label moved with it (the special-point label fix below then gives some of these labels other tables: --parent I4/mcm --irrep P2 now lists Immm, Imma, I-4m2 and Imm2, the P2P4 table of ISOSUBGROUP, where v0.4.2 listed Ibam, Ibca, I-4c2 and Iba2). Tested in testsuite section 17.

  • Irrep labels: one frame per structure, the same in every command. An irrep label is defined only relative to a description of the crystal in the ISO-IR standard setting, and the setting leaves a choice (Sr or Ti at the origin of Pm-3m, Si on Wyckoff 8a or 8b of Fd-3m) that permutes the labels at zone-boundary points. Each command used to take the frame spglib returned for the cell it happened to work on (the input cell, phonopy’s primitive cell, the standardized primitive cell), so crystod, crystod-phonon --irreps, --vibration and crystod-mag could name one irrep of one structure differently. Every command now labels in one frame per structure, fixed by three rules: a cell already in the ISO-IR setting keeps its own axes and origin (the conventional cell, its primitive cell in the standard centring, and a diagonal n1 x n2 x n3 supercell of either, of any size); any other cell gets a canonical frame of the crystal (spglib’s frame composed with the lattice rotations and origin shifts of the Euclidean normalizer, the cell’s own origin preferred when it is the origin of a standard description, then the smallest sorted list of atomic positions, coordinates compared, and reduced into the unit cell, at 0.71, 0.071 and 0.0071 times the symmetry tolerance, so that coordinates typed with a few decimals cannot fall on a level (5-decimal LaFeAsO and Pmn2_1 cells used to change frame with the origin shift); along a polar axis the origin goes on an atom of the element with the smallest atomic number, centring copies included); a working cell derived from the input cell inherits its frame. Consequences: Si (Fd-3m) --vibration now lists L1+, L2-, L3+, L3- at L and W2, W2, W1 at W, and the SALC of Si p gives W1 + 2 W2 at W, in the frame of --irreps (L3+, L2-, L1+, L3- and W2, W1, W2, unchanged); v0.4.2 printed L2-, L1+, L3-, L3+, then W1, W1, W2 and 2 W1 + W2. --irreps --all-irreps labels the L-W line of Si in the frame of the points (Q1, Q2, Q2, Q1, Q2, Q1; v0.4.2: Q2, Q1, Q1, Q2, Q1, Q2), and crystod-mag on Y2Ir2O7 gives 2 L1- + L2+ + L2- + L3+ + 3 L3- at L and 3 W2 + 3 W1 at W (v0.4.2: 2 L2+ + L1- + L1+ + L3- + 3 L3+ and 3 W1 + 3 W2). An input in the ISO-IR setting is labelled relative to its own origin (SrTiO3 with Sr at the origin: R tilt R5-; with Ti at the origin: R4+); an input whose origin is a general point gets the canonical frame, the same for every shifted copy whatever its orientation, basis or cell size, so SrTiO3 shifted by (0.1234, 0.2345, 0.3456) now lists R1+, R3+, R4+, R4-, R5+ at R (tilt R4+, Ti at the origin) instead of the Sr-origin R2-, R3-, R4-, R5+, R5-, and crystod.phonon.label_phonon_modes labels its soft mode (v0.4.2 returned no label). An input with rotated or re-based axes whose origin is the origin of a standard description keeps that origin, so it and a shifted copy can name a mode differently (the unshifted sqrt2 x sqrt2 x 1 SrTiO3 cell: tilt R5-; shifted: R4+). A diagonal supercell (n1 x n2 x n3, of any size) of a cell in the ISO-IR setting keeps that cell’s axes and origin and is labelled like the cell (a 2x1x1 Si cell gave 2 W1 + W2 at W, now W1 + 2 W2 as the cell; 2x2x2 and 2x1x1 SrTiO3 cells keep R3- + R4- for Ti d at R); a non-diagonal supercell is labelled in the canonical frame and can get names that differ from the cell’s by a normalizer element (the sqrt2 x sqrt2 x 1 supercell of P4_2/mmc CuO: Cu p A1 + A2 + A3 at A, where the cell gives A1 + A2 + A4). The rules, examples and limits are in the manual, “Irrep labels and the frame of a structure”. Tests in sections 2, 28, 34 and 43.

  • Fixed: at 39 special points of 27 space groups an irrep label named another irrep. The tabulated ISO-IR characters (phase exp(+2 pi i k.t), exact translations) and spgrep’s (exp(-2 pi i k.t), translations reduced mod 1) describe the same small irrep when chi_spgrep = conj(chi_table) exp(2 pi i k.delta), delta being the wrapped-away lattice translation; the label was taken from a direct comparison chi_spgrep = chi_table first, and at 100 irreps that comparison picked a physically different irrep: P of I-4, I4cm, I-4m2, I4/mcm, I23 and I432, W of F-43m, H (and in eleven of them K) of sixteen trigonal and hexagonal groups from P3 to P6_3/mmc (P3, P3_1, P3_2, P312, P3_112, P3_212, P3m1, P3c1, P31c, P-31c, P-6, P6_3/m, P-6m2, P-6c2, P-62c, P6_3/mmc), T and Y of Ccce, X of I4_1/amd and I4_1/acd, N of Ia-3d. crystod-group --parent, --product and --kpoint now match through the conjugate comparison only, and the structure commands (crystod, --atomic-orbital, crystod-phonon, crystod-mag, crystod-group --table) take every label from the ISO-IR labeller, which compares in the same way in the ISO-IR frame; the old direct comparison is only a fallback where the labeller gives nothing. Every label now names the irrep of that name in the ISO-IR data, and --parent lists for it the subgroups ISOSUBGROUP lists under the same name: --parent I4/mcm --irrep P2 gives P2P4 with Immm, Imma, I-4m2 and Imm2 (v0.4.2: P1P2 with Ibam, Ibca, I-4c2 and Iba2), --parent Ia-3d --irrep N1 lists the N1 table of ISOSUBGROUP, which includes C222_1, P4_12_12, P-42_1c and R3c (v0.4.2 listed the N2 table). The note that blamed such differences on the ISO-IR data files (“crystod N1 = ISOTROPY N2”, printed at the ten k points that SUBGROUP/VALIDATION.md listed, also where the labels already agreed, as for Y of Cmce) is gone; script/validate_isosubgroup.py 62 230 gives 3506 exact matches and 28 up to the enantiomorphic partner among 3535 irreps, with no label differences, and no longer counts a label swap as a pass. Other outputs that change: crystod-group --product M1 P1 --sg I-42d gives PA1 (v0.4.2: PA2); MoS2 (P-6m2) phonons at K are K3, K6, K1, K4, K5, K2, K1, K6, K3 in order of frequency (v0.4.2 and the shipped files: K5, K4, K1, K6, K3, K2, K1, K4, K5; H likewise, and the VESTA files of the K modes are renamed); P4/n given in origin choice 1 (85_PPOSCAR_IN5) exchanges A1 and A2, M1 and M2; crystod-phonon --vibration names the P irreps of I4_1/a (88_PPOSCAR_ZrGeO4) P1 … P4, where v0.4.2 printed irrep_1 … irrep_4; crystod-mag on LuFeO3 (P6_3cm) gives A1 + 2 A2 + 2 A4 + A3 + 3 A5 + 3 A6 at A and L1, L2, L3, L4 at L (v0.4.2: A3, A4, A2, A1, A6, A5 and L3, L4, L1, L2). Tests in sections 8 and 17.

  • k points of a -k star are named and labelled. In a group without inversion the star of -k can differ from the star of k, and ISO-IR tabulates one of the two (P of I-4 at (1/4,1/4,1/4), not PA). A k point whose star is not tabulated but whose -k star is (PA of I-4, I-42m, I-42d, I23, I2_13, I-43m and I-43d; KA and HA of the trigonal and hexagonal groups without -k in the K and H stars, such as P3 and P-6; WA of I222 and I2_12_12_1) is now named with the ‘A’ suffix and labelled with the complex conjugates of the tabulated irreps (PA1 is the conjugate of P1) in every command, the names crystod-group --product (M1 x P1 = PA1) and --parent (P1PA1) use. v0.4.2 printed irrep_N labels and the name of a line through the point: crystod -c 82_PPOSCAR_AlPO4 --element Al --orbital p --kpoint -0.25 -0.25 -0.25 printed Q and irrep_2(1), …, and now prints PA and 1.0 [PA2(1)] + 1.0 [PA3(1)] + 1.0 [PA4(1)]; crystod-phonon --vibration at that q selects PA with the spaces PA1 … PA4; crystod-group --table --sg 82 --kpoint -0.25 -0.25 -0.25 prints the name PA and the rows PA1, PA4, PA2, PA3 (v0.4.2: an unnamed k point with irrep_N rows). The -k partners of lines, planes and the general point are named the same way (item after next). The k-point names follow the frame of the labels too (next item). Tests in sections 2, 24 and 34.

  • k-point names in the frame of the labels. The special points the structure commands list and survey (crystod and --atomic-orbital without --kpoint, --diagram, --visualize, crystod-phonon --irreps, --vector and --subgroup, crystod-mag) were taken from the ISO-IR tables through spglib’s standardized basis, while the labels refer to the ISO-IR frame of the input cell (item above); for an input outside the ISO-IR setting the two frames differ by a normalizer element, and a point could be printed P above PA1 + PA2 + PA3. The listed points are now named by the labeller of the labels, a point that is there the -k partner of a tabulated one being replaced by its -k (crystod.isoir.special_points_in_frame); a name given on the command line (--kpoint P, --qpoint P) is resolved in that list, and coordinates given on the command line are named by the labeller first. 82_PPOSCAR_AlPO4 shifted by (0.0731, 0.1593, 0.2417) lists P [-0.25, -0.25, -0.25] with Al p P1 + P2 + P3, --kpoint P analyzes that point, and --kpoint 0.25 0.25 0.25 prints PA above PA1 + PA2 + PA3 (before: P [0.25, 0.25, 0.25] above the PA labels, also for --kpoint P); crystod-phonon --vibration --qpoint P selects P = [-0.25, -0.25, -0.25] with P labels and --qpoint 0.25 0.25 0.25 selects PA (before: P above PA2). A 2x2x2 supercell of 143_PPOSCAR_HgBr with its atoms sorted by species, which spglib re-bases to (-b, -a, -c), lists H and K with H1 + H2 + H3 and K1 + K2 + K3 as the cell does (before: above HA and KA labels). The seekpath names of --vibration, crystod-mag --qpoint, --star-of-k and --visualize --kpoint are kept; a seekpath point is moved where the frame of the labels gives it another ISO-IR type than spglib’s frame, and the coordinates of a listed point are named as the list names them (H_2, not H); the endpoints of the --irreps --all-irreps k-path, which cannot move, are printed with their ISO-IR name there (k_path: GM-X-PA-N-... for the shifted AlPO4). For a triclinic cell seekpath’s letters denote other points than the ISO-IR names, as in v0.4.2: the seekpath Z of 1_PPOSCAR_RbBe2F5 is (-1/2, 0, 0), labelled X1, the ISO-IR Z of crystod --kpoint Z is (0, 0, 1/2). The MCP tools crystod_phonon_irreps and crystod_crystal_orbital_irreps name, survey and resolve their k points the same way (before: the table’s P (1/4, 1/4, 1/4) above PA labels, and kpoint="P" analyzed the table’s point); kpoint=NAME of the crystal-orbital tool now reports the arm crystod --kpoint NAME analyzes (X [-0.5, -0.5, 0.0] for GaP, where the table has (1/2, 0, 1/2)), with the same labels; with a CrystOD before 0.4.3 the phonon tool keeps the table’s list. In Python, crystod.salc.CrystalOrbital.get_special_points() returns the list in the frame of the labels (get_irt_special_points() stays the table’s own list, which the direct character comparison uses), crystod.phonon.resolve_qpoint names coordinates by the labeller first when given isoir_context, and PhononMode.qpoint_label of label_phonon_modes is the name of the star in the frame of the labels. Inputs whose frame is spglib’s, which includes the inputs in the ISO-IR setting as a rule, print what they printed. Tests in sections 2 and 34 and in crystod-mcp/tests.

  • -k partners of lines and planes: ISOTROPY’s names, the same in every command. On a line, a plane or the general point that no symmetry element reverses (LD of P2_1 and P4, DT of P6_3, the general point of every acentric group) the stars of k and -k differ, and the ISO-IR entry covers both signs of the parameter. The labelling commands printed the ISO-IR label at the negative parameter (DT2, DT1, DT4, DT3, DT6, DT5 at (0,0,7/12) of P6_3), while crystod-group --product and --supergroup-cif named the star of the smaller canonical representative through -k with an A suffix (DTA2, DTA1, DTA6, ... for the same irreps), so one irrep had two names, and the pair label of --supergroup-cif (GP1GPA1) was neither. Both now follow the ISOTROPY software, whose physically irreducible labels name the -k partner star (LD1LE1, DT6DU6, GP1GQ1, P1PA1): CrystOD gives the ISO-IR name to the star at the canonical parameter (the smallest, the positive one first; the name ISOTROPY gives for that parameter value, its parametrization being that of ISO-IR), and the other one is named LE for LD, DU for DT, SN for SM, GQ for GP, with the suffix A for the other letters and C where ISOTROPY uses it (P, B, C, D, E of P3, P3_1, P3_2; P and C of P31m and P31c; D of P3m1 and P3c1; B and E of P-6), with the complex conjugate irreps under the same numbers (LE1 = conj LD1, as ISOTROPY’s pair labels and their complex-conjugate data show). These names exist in ISOTROPY exactly for the k types whose -k lies outside the star (4141 types of the 230 groups checked). crystod-group --table --sg 173 --kpoint 0 0 7/12 prints DU with DU2, DU1, DU6, DU5, DU4, DU3, the conjugates of DT2, DT1, DT6, … at (0,0,5/12); --product P1 X1 --sg I4 gives LD1 + LD2 + LE1 + LE2 (before: LDA1 + LDA2); the -k partner of the line P (K-H) of P3 is PC (before: PA), while both signs of the parameter of P itself keep the name P; the general point of I-4m2 pairs as GP1GQ1 in --supergroup-cif (before: GP1GPA1). Over 1597 (group, type, parameter) cases of lines, planes and general points with a partner (138 groups) the names of --product equal those of the labeller, every partner irrep is the conjugate of the tabulated irrep with its number, and the names do not depend on the arm or on k + G. Tests in sections 8, 17, 23 and 24.

  • Negative fractions as k-point coordinates. crystod --kpoint -1/4 -1/4 -1/4, crystod-phonon --qpoint -1/3 -1/3 -1/2 (--vibration, --vector, --subgroup, --modulation) and crystod-mag --qpoint stopped with “expected at least one argument”: argparse takes -0.25 for a number but -1/4 for an option. The lists of special points print negative coordinates for inputs outside the ISO-IR setting, so a negative fraction after --kpoint or --qpoint (or an abbreviation argparse accepts, --kp) is now read as a coordinate (crystod-group --kpoint already did). Tests in sections 2 and 34.

  • Labels on symmetry lines and planes no longer depend on how k is written. On a line or plane the ISO-IR label depends on the value of the line parameter, and one k point has one value per arm of its star and per copy k + G. The label is now evaluated at the canonical value, the smallest parameter (the positive one when the two signs are equally small), the same for every arm and every k + G (DT of F-43m at the conventional (0,0,-1/2) is the arm (0,0,-a) at a = 1/2); IsoIrrep.match_k returns these parameters. Before, the label could depend on the arm or copy given: crystod-group --table --sg 216 --kpoint -0.25 -0.25 0 and --kpoint 3/4 3/4 0 printed DT3 for the row with the characters 1, -1, -1, 1, the label of +k, and now print DT4, the ISO-IR label at that point. The rhombohedral T point is recognized for every copy of k: --table --sg 166 --kpoint 3/2 3/2 3/2 printed unnamed irrep_N rows and now prints T with T1+, T1-, … . Tests in sections 24 and 43.

  • Fixed: crystod-group --parent 218 --irrep R4 (and R5) stopped with numpy.linalg.LinAlgError: Singular matrix. R4 and R5 of P-43n are a complex-conjugate pair of three-dimensional small irreps at R (1/2,1/2,1/2), so the order parameter is the six-dimensional physically irreducible real form that ISOSUBGROUP lists as R4R5. At a k point with 2k = 0 the small-irrep matrices are first tried for a real form, through the group-averaged antilinear intertwiner S between D and D*. For a complex-type irrep that intertwiner is zero (Schur), and what the average returned was round-off (about 1e-16 relative to its natural scale, against 0.3-0.4 for a real or pseudoreal irrep): the test “S S* is a positive multiple of the identity” had an absolute tolerance and was passed by the noise, the noise was normalized to an O(1) matrix, and the basis built from it was singular. Which input fails depends on last-bit rounding; R1R2 of the same group passed the same test on noise and was turned away only by a later check. The real-form attempt now answers “no real form” as soon as the averaged intertwiner vanishes relative to its scale, and refuses a basis that is not unitary; the pair then goes to the doubled real form like every other complex irrep. Both labels print the R4R5 table of ISOSUBGROUP (F222 and I-4 at index 12, R3 at 16, C2 at 24, P1 at 48, each on the doubled cell; script/validate_isosubgroup.py 218 218 passes all 16 tables of P-43n), and --parent 218 --kpoint R lists R1R2, R3 and R4R5 without a not enumerated note. This fix leaves the --irrep tables of all other 5406 irrep labels of the 230 space groups unchanged, byte for byte (the label fixes of this release, above, change some of them). Tests in section 17.

  • Fixed: the W point of Ibca (No. 73) and the W and WA points of I2_12_12_1 (No. 24) stopped with spgrep could not compute the small irreps at W: Given representation is not irreducible: indicator=2. This hit crystod-group --parent 73 --kpoint W (and --irrep W1), --parent 24 --kpoint W (no irrep at W could be enumerated) and every other command that takes small irreps from spgrep at these points, the SALC command included. spgrep 0.6.0 builds the correct two-dimensional small irrep at W = (1/4,1/4,1/4) and then checks it with a Frobenius-Schur sum over the coset representatives alone. That sum is the indicator only when 2k = 0; at W every 2_1 screw adds tr Γ(R)² e^(−4πi k·τ) = (−2)(−1) = +2, the sum comes out as 2, and spgrep raised. crystod.runtime_compat.get_spacegroup_irreps_from_primitive_symmetry now stands in for the spgrep function at all eleven call sites: on that error at a k point with 2k ≠ 0 it rebuilds the small irreps from spgrep’s own steps (little group, factor system, projective co-group irreps, translation phases) without the check (with the tolerance the caller gave spgrep), and keeps them only if they are irreducible, mutually inequivalent and complete; everywhere else it returns spgrep’s arrays unchanged. A sweep of the 230 space groups (all 1381 tabulated k points, and the 9980 star representatives of the 1/24 grid with 2k ≠ 0) finds exactly these three points failing in spgrep. --parent 73 --kpoint W now lists the six W1 rows of ISOSUBGROUP (P-1 twice and C2 three times at size 4 and index 16, P1 at index 32; SUBGROUP/SUBGROUP_SG73_W.txt), --parent 24 --kpoint W the four W1WA1 rows (C2 three times at index 8, P1 at 16; there is no ISOSUBGROUP table for No. 24, and the rows agree with a build from the ISO-IR matrices), and the SALC command reports W1(2) at W of both groups. Tests in section 17.

  • crystod-group --parent SG --irrep IR --order-parameter takes the directions as the tables print them. --order-parameter a -a 0 stopped with unrecognized arguments: -a 0, because argparse took -a for an option, so a direction such as M3+(a;-a;0) could not be passed back (the quoted "a -a 0" was one component and failed the length check). Every token after --order-parameter up to the next --option is now a component, in the command and in the isotropy module’s own parser: --order-parameter a -a 0 gives M3+(a;-a;0) -> I4/mmm (No. 139) for M3+ of Pm-3m, and so do one quoted string ("a -a 0"), the table spellings "a;-a;0", "a,-a,0" and "(a;-a;0)", and options placed after the components. A component may carry an exact factor (2a, -0.5a, 1/2a), which scales the parameter; before, 0.5a was silently read as a new, independent parameter. A rounded decimal factor (0.282a, as printed for irrational factors at K of P6_3/mmc) is refused with an error instead, because the rounded direction has a different subgroup — the rule crystod.group.isotropy_subgroups already applied. Tests in section 17.

  • Fixed: --order-parameter with more than eight free parameters gave a too-high subgroup. The values given to the parameter letters repeated after eight (i equalled a, j equalled b, …), so --parent 219 --irrep L3 --order-parameter a b c ... p (16 letters, the general direction) printed C2 (No. 5) at index 96 instead of P1 (No. 1) at index 192; crystod.group.isotropy_subgroups(..., order_parameter=...) shares the resolver and had the same error. Every letter now gets its own value; directions with up to eight letters resolve exactly as before. Tests in section 17.

  • Fixed: the representative vector of a coupled direction could have extra symmetry within one irrep. IsotropyAnalyzer.direction_label returns, with the label, a vector inside the stratum, built from fixed magnitudes on the orthonormal basis rows. Two of those magnitudes are related by sqrt(2) (0.4142/sqrt(2) = 0.2929), so rows (1,1,0)/sqrt(2) and (0,0,1) gave 0.2929 (1,1,1): for L1+(a;a;b) L1-(d;d;e) of P-31m the L1- part came out as (d;d;d), whose stabilizer within L1- is larger than that of the (d;d;e) subspace. The whole coupled vector was still generic, so no printed subgroup was wrong, but code that took the part of one irrep on its own (to find the subgroup of that irrep alone) got a too-high group. The vector is now checked: its stabilizer must equal the group fixing the whole subspace, and for coupled irreps the stabilizer of every irrep part must equal the group fixing that irrep’s share of the subspace; where the historical magnitudes pass they are kept, otherwise the next magnitude set (1/(1 + j/x) for transcendental x, without algebraic relations among its members) is taken, and an internal error is raised if none passes. Over 3562 coupled irrep pairs of 49 space groups (among them P-31m to R-3c, P622 to P6_322 and P-6m2 to P6_3/mmc, whose L and M stars carry the affected two-plus-two-parameter directions; the W points of the F-centred cubic groups aside) every one of the 22051 coupled directions now passes, 325 of them through the new magnitudes, and the stabilizer of the whole vector is unchanged in every one. A vector moves only where the historical one fails the test; the labels and the printed tables do not change (all single-irrep tables of the 230 space groups and 20 coupled tables compared byte for byte). Tests in section 17.

  • New: crystod-group --supergroup-cif ... --output-dir DIR and --no-files. The symmetry-mode analysis writes the decomposition table sym_mode_<formula> and one VESTA file per activated irrep, and wrote them into the current directory with no way to choose or suppress them, so a batch run left files wherever it was started. --output-dir DIR writes them into DIR (created if missing; the printed paths include it), and --no-files prints the analysis and writes nothing. Without either option the files go to the current directory as before. The options exclude each other and are refused outside --supergroup-cif; an --output-dir that names an existing file is refused before the analysis starts. crystod.group.SymmetryModeAnalysis writes no files and is unchanged. Tests in section 23.

  • Fixed: complex-type irreps never decomposed in crystod-group --supergroup-cif; they now appear as one line per conjugate pair. A complex-type irrep (Frobenius-Schur indicator 0, such as GM2+ and GM3+ of Pa-3, R1+ and R3+ of Pa-3, GM3+ and GM4+ of I4_1/a) and its conjugate form one physically irreducible real representation, whose dimension the irrep machinery reports doubled. The mode projector took that doubled dimension for the size of the complex irrep matrices, so the first complex-type irrep of any folding star stopped the analysis with a Python traceback (IndexError ... add.reduceat), whether the irrep was active or not: 178 structure pairs of a materials survey failed this way. The projector now uses the complex irrep for P_τ and adds its conjugate, P_τ + P_τ*; the pair is listed once, with both labels (GM2+GM3+, R1+R3+, B1BA1 when the conjugate lies on the -k star), the amplitude of the projection onto the pair and the number of independent modes of the pair. The partner is recognized from the conjugate characters, independently of the labels. A pseudoreal irrep keeps its single name (R2+). All 178 pairs now decompose (one of them, Pbam to C2, through the mapping fix below), the squared amplitudes add up to the squared total distortion (to 1e-15), and freezing the field of each pair into the parent gives the isotropy subgroup of its line (spglib at 1e-3 and 1e-4 Å, all 317 pair lines). No pair that decomposed before carries a complex-type irrep, so their modes, subgroups and amplitudes are unchanged. The irrep and direction columns of the printed table (and of the saved sym_mode_<formula>) now widen to the longest entry instead of letting it push the rest of its row out of line; that changes only the spacing, and only of tables with a direction string longer than 12 characters or an irrep label longer than 7 (158 of the 2938 survey tables, and 10 of the 45 shipped example pairs that decomposed before, among them GaN, PbZrO3 and CaTiO3). Tests in section 23 (pyrite-type FeS2, example/23_symmetry_mode/POSCAR_FeS2_Pa-3).

  • Fixed: crystod-group --supergroup-cif stopped with “the distortion is not fully captured by the listed modes; please report this case” or “cannot separate the surviving from the broken parent operations … try a different –tolerance” when the least-distortion atom mapping was not a group-subgroup setting. The cell relation (sublattice basis and origin) was chosen by the least total distortion alone. For a pseudo-symmetric parent a strained twin setting or a shifted origin can pair the atoms marginally better although some operation of the child is not a parent operation in it; the subgroup search then saw fewer exact operations than the child has and either gave up or took the lowest-mismatch pseudo-operations, and the projection left part of the field over. That mapping is now validated first (every child operation, carried over by the sublattice basis and the origin, an exact parent operation, and the displacement field invariant under them to machine precision; none of these checks depends on --tolerance) and, if it fails, redone among the sublattice settings that carry every child operation onto a parent operation: the origin is solved exactly from the translation parts of the child operations (free only along polar directions), the atoms are paired so that the field respects the child symmetry, and the least total distortion wins. A NOTE with the cell relation says when this happened. Where no such setting exists the run stops with one of four specific messages (no sublattice carries the child point group; the translation parts fit no origin; a Wyckoff conflict, with the operation and the site counts; no symmetric pairing within 1.8 Å), and the --tolerance advice is gone. On the survey, 25 of the 32 “not fully captured” pairs and 66 of the 106 “cannot separate” pairs now decompose, the reference plus the displacement field having exactly the child’s space group in each, and the other 7 and 40 stop with a specific message. None of the 2938 pairs that decomposed before, nor of the earlier section 23 inputs, takes the new route: their sublattice basis, displacements, mode tables and totals are those of v0.4.2, and so are their origins but one (next sentences). Also fixed: the printed origin shift could disagree with the displacement table by a uniform shift, in two places. When the last origin refinement of the least-distortion pairing was rejected, the origin kept the rejected step (0.45 Å in the mapping of LiCoPO4 P2_1 against Pnma, a pair that then stopped before printing it), and when the uniform part along the polar directions was taken out of the displacements of a polar child, the origin did not move with the atoms. The origin now always belongs to the positions in the table; of the 2938 survey pairs one prints a different origin because of this, a Pc child of a Pbcn parent whose origin moves by 0.187 Å in its polar plane (from (7/8, 1/2, 10/11) to (7/8, 1/2, 17/18)), the 0.187 Å by which the old one missed its atoms. The determinant filter of the sublattice enumeration and the per-operation mismatch search are vectorized, with the same candidates in the same order (checked on all 3254 survey pairs): the two slowest survey pairs, both failing, took 35 s and now take 6 s, and no survey pair takes more than about 20 s. Tests in section 23 (KGeCl3 P4/mmm to Cm, SeO2 Cmme to Pmc2_1).

  • Fixed: crystod-xrd stopped with ValueError: too many values to unpack on every hexagonal cell. pymatgen’s XRDCalculator indexes the reflections of a hexagonal lattice (hexagonal and trigonal crystals, rhombohedral ones in the hexagonal setting) with the four Miller-Bravais indices (h k i l), and the peak table expected three: wurtzite ZnO (186_PPOSCAR_ZnO) and AlF3 in the hexagonal cell of its CIF (R-3c) ended in a traceback after the header, with no table and no figure. crystod.xrd.Peak now stores (h k l), dropping the redundant i = -(h + k), for the reflection and for every merged family, so the printed table, the text file and the Python records keep their three-index form on every lattice (ZnO: (1 0 1) x12 at 35.7474° for CuKa1). Four indices with i != -(h + k) raise ValueError. Tests in section 44 (ZnO and the hexagonal AlF3 cell through the command, and Peak given Miller-Bravais indices).

  • Changed: the terminal output of crystod-bz (unit-cell and supercell Brillouin zones), crystod-xrd, crystod-search, crystod-mol --visualize, crystod --visualize (with --element/--orbital, and the level viewers without them and with --pyscf) and crystod-group (--product, --table, --basis, --generate-basis, --coset, --poscar2cif, --cif2poscar, --supergroup-cif, --decompose, --ligand-field, --multiplet) is laid out in blocks with * ... * headers. crystod-bz prints * Structure * (or * Band path * for a manual --band) and * Recommended k-path (seekpath) * with the Path: line inside it, and with --trans-mat * Transformation matrix (unit cell -> supercell) * (with the volume ratio), * Supercell lattice (rows) * and * Unit-cell q-points folding onto the supercell Gamma point (N) *; crystod-search lists the result table under * Materials * below the query block (--get MPID keeps it directly under the title); the written-file notices of crystod-bz, crystod-xrd, crystod-mol --visualize and crystod --visualize are collected in a final * Output files * block (one block for all pages when crystod --visualize scans every special k point). Every data line keeps its text and numbers (some move into their block with a two-space indent), and every output file is unchanged; the SALC listing, --atomic-orbital and --star-of-k modes of crystod and crystod-bz --show-kpoint already had this layout and are unchanged. The level viewers of crystod --visualize (extended Hückel without --element/--orbital, and --pyscf) print * Extended-Hueckel levels * (or * PySCF levels * and * Energy reference *) and list one GM: 5 levels (14 partners) -> page line per page in * Output files *, without the summary line of page names and without repeating the primitive-cell notice; with --pyscf the SCF saved to FILE.chk (...) notice is listed in * Output files * too, not inside * PySCF levels *. In crystod-group, every mode starts with a blank line before its first block (the point-group --product, --table and --basis did not); --product and --basis with --show-irrep-table print the * Point group * block once, --basis puts the * IrRep Table * after the group and k-point blocks, and --basis --sg without --kpoint names the special points in a * Special k points * block; --generate-basis prints the group blocks once and titles every block of an order with the order (* Decomposition: 2nd order (quadratic) *) instead of the ==== banners; --coset prints its headers without the leading space and without the blank lines inside the blocks; --poscar2cif and --cif2poscar print * Structure * and * Output files * (Bilbao-style CIF written to: ..., POSCAR written to: ..., with (existing file overwritten) in place of the NOTE: overwriting line); --supergroup-cif adds a * Distortion amplitude * header above the maximum-displacement lines and moves the Decomposition table saved to ... line and the VESTA file list into a final * Output files * block; the space-group --product prints the DIRPRO reference after the --symmetric/--antisymmetric blocks; --decompose and --ligand-field print the class characters directly under their * Reducible representation ... * header, --multiplet keeps the state-count check: line inside the * Term Symbols * block and moves the --visualize file notice into a final * Output files * block (with a two-space indent), and its HTML viewer is unchanged. The --example runs print no blank line of their own after Running: ..., since every command now opens with one, and crystod-phonon --vector, --modulation and crystod-mag title the q-point block * Selected Q point *, as --vibration does.

  • Changed: the terminal output of crystod-phonon (--irreps, --fatband, --lt, --vector, --modulation, --subgroup), crystod-mag and crystod-md (--adp, --summary) is organised in titled blocks with * ... * headers, as crystod-phonon --vibration and crystod-group --parent print it. --irreps prints * Gamma-point activity * (one label per line, as --vibration), * Gamma-point dielectric response (Born effective charges from BORN) * with --nac and * Raman tensors (Cartesian axes of the input cell) * with --raman-tensor; --fatband and --lt print * Structure *, * Band path * and * Projection * (with --projection-direction); --vector prints * Structure *, * Available high-symmetry q-points *, * Selected Q point * (the title --vibration uses), * Phonon modes at q = ... * and * Displacement patterns *; --modulation prints * Phonon source *, then * Selected Q point *, * Phonon modes at q = ... * and * Star of q (arms related by the space-group rotations) * for each q point, * Modulation * and * Symmetry of the generated structure *; --subgroup adds the * Order parameter directions and isotropy subgroups * header of crystod-group --parent above each table; crystod-mag prints * Structure *, * Selected Q point *, * Spin (axial-vector) representation *, * Symmetry-adapted spin bases *, * Magnetic cell * and one * <irrep> [<kind>] * block per basis (the survey without --qpoint lists every k point in one * Spin (axial-vector) Irreducible Representations of <El> sites * block); crystod-md --adp prints * Input *, * Supercell info *, * Time-averaged unit cell *, * ADP constraints per Wyckoff position *, * Trajectory unwrapping * and * Atomic displacement parameters *, and --summary * Input *, * Trajectory info * and * Time-averaged cell (mean +/- std) *. The written-file notices of every one of these modes are collected in a final * Output files * block (--subgroup --modulate names its files in the * Distorted structures * rows). Every data line keeps its numbers and, apart from the following, its text: the --irreps Gamma summary is split one label per line, the crystod-mag file notices read Spin basis written to: ..., its survey prints one k point (primitive): <name> <k> line per k point, and the Generating modulated structure... progress line of --modulation gives way to the * Modulation * header. Every output file (phonon_irreps.yaml, phonon_modes_*.txt, VESTA, MPOSCAR, PDF, CIF) is unchanged; crystod-md --adp no longer repeats the Asymmetric-unit sites: count after the file notice.

  • Changed: the section numbers. The features new in this release take sections of their own, so the shared section numbers of testsuite.py, the example/ directories and the numbered sections of this manual run from 1 to 45 instead of 1 to 37, still grouped by command: 1 library core, 2-7 crystod, 8-24 crystod-group, 25-27 crystod-bz, 28-35 crystod-phonon, 36-37 crystod-mag, 38-39 crystod-md, 40-42 crystod-mol, 43 Python API, 44 crystod-xrd, 45 crystod-search. For example example/13_isotropy_subgroup is now example/17_isotropy_subgroup (python testsuite.py 17), example/21_phonon_irrep is example/28_phonon_irrep and example/37_mp_search is example/45_mp_search; scripts that call python testsuite.py N or read files below example/NN_* need the new numbers. The commands and their options are unchanged.

v0.4.2#

  • New quantitative engine crystod --diagram --vasp: crystal-orbital diagrams from finished VASP runs. The third engine next to extended Hückel and PySCF, and the first one that computes nothing itself: crystod --diagram -c POSCAR --co-left SrTi --co-right O3 --vasp [ROOT] reads the crystal run in ROOT/BAND and the two sublattice runs in ROOT/BAND_sublattice* (DIR/band when it carries the PROCAR; gzipped files are accepted) and draws the same three columns from them. Which sublattice directory is the left and which the right column is decided from the real elements of its POSCAR, not from its name; --vasp-crystal/-left/-right DIR override the search. A sublattice run keeps one sublattice and replaces the other by Va<q><sign> point-charge species (Va2-, Va4+) of a modified VASP — a smeared Coulomb charge plus a short repulsive wall standing for the Pauli repulsion of the removed ion’s core; VASP is proprietary and is not distributed with CrystOD, the patch is available to VASP licensees on request, and --vasp itself needs only the output files. The companion crystod --diagram ... --vasp-setup [ROOT] writes those runs’ inputs — POSCAR with the crystal’s cell and atom order and the removed atoms renamed from the resolved oxidation states, POTCAR split out of the crystal run’s (or taken from --potcar-dir / PMG_VASP_PSP_DIR, with --potcar-map EL=NAME choosing a variant), INCAR with LORBIT = 12 and no NELECT, and one explicit KPOINTS holding the symmetry-reduced weighted mesh followed by the zero-weight special points, so one run per directory gives both the SCF and the special-point eigenvalues — and prints the three run commands without starting VASP. Levels, occupations and the complex LORBIT = 12 projections come from PROCAR; each band’s projection vector is treated as a vector in an AO-like (atom, l, m) basis and classified with the same representation matrices and character projectors CrystOD builds for a genuine AO basis, so every level carries a space-group irrep whose multiset reproduces the site-symmetry induced representation the report prints (32 of 34 manifolds of SrTiO3 exactly; a best irrep weight below 0.9 is warned about, and on SrTiO3 every level reaches 1.000). The three runs each pin their own G = 0 potential, so the crystal column is taken as the reference and every fragment level is raised onto it by a site-resolved shift: one constant per (column, element), fitted to the symmetry-forbidden probes (fragment levels whose irrep has no partner in the other sublattice at that k and which must therefore coincide with their crystal counterpart, weighted four times) and to the pure XPS-style counterparts. The shells of one atom move together, different sites do not: on SrTiO3 the Ti site, charged by covalent back-donation in the crystal, has all its levels raised 12.3 eV more than the ionic Sr site, which no single shift per column can describe. The energy zero of the page and the tables is --vasp-zero vbm|efermi|raw (default E − E_VBM); --vasp-align rigid falls back to one shift per column (its numbers are printed as a diagnostic in either mode), --vasp-anchor EL nl pins a column on a chosen shell and --no-align keeps the raw scales. An occupied-band trace sum rule that uses no projection cross-checks the result, and the bonding/antibonding colouring — which a plane-wave calculation must read from the aligned energies because it has no overlap matrix — is active for every crystal level whose parents sit on sites whose own anchors agree within 1 eV, and suppressed (neutral grey stroke) elsewhere rather than guessed. Output: CrystOD_{cell}_vasp.html through the usual writer, a CrystOD_{cell}_vasp_levels.txt with every number (per-level shift and the full anchor table included), a machine-readable CrystOD_{cell}_vasp_levels.json with the same content, and the terminal report of the other engines. Non-spin-polarized primitive cells only, and every share is a PAW-sphere projection, blind to the radial channel. New modules crystod/vasp_io.py and crystod/crystal_orbital_vasp.py; documentation: crystod. Tests in section 3, run offline against example/03_hybridization/vasp_SrTiO3 and example/03_hybridization/vasp_CaF2, trimmed copies of six real VASP runs restricted to the four special k points each, which reproduce every number of the untrimmed runs.

    The PROCAR projections are classified in the Bloch gauge CrystOD builds its permutation representation in, with no further conjugation. The engine first conjugated the representation with Lambda_a = exp(2 pi i k . tau_a), by analogy with the PySCF engine, whose AO coefficients really are in the atomic gauge. That conjugation is an exact no-op for every site on half-integer coordinates, so neither SrTiO3 nor ScF3 could test it. Fluorite CaF2 can — its F sites sit on (1/4,1/4,1/4) and (3/4,3/4,3/4) of the primitive basis — and it shows the conjugation is wrong: with it 21 of the 85 labelled levels fall below irrep purity 0.90 (minimum 0.000 at W, 12 failures at L), the fragment manifolds stop reproducing the SALC decomposition, the Ca shell spread is 6.58 eV and the F spread 2.31 eV so both sites fail the scale test, an F 2s anchor is paired with a crystal level 13.6 eV away, and the page carries 0 bonding and 0 antibonding levels. Without it every labelled level of CaF2 has purity 1.000 at GM, L, X and W, the manifolds match the group-theory decomposition exactly, and the page comes out 30 nonbonding / 6 antibonding / 5 bonding. The three half-integer-site systems are numerically unchanged, as the no-op argument predicts. CaF2 is now a test fixture of section 3, and it is also the ionic control of the site-resolved alignment: Ca +4.54 and F +4.43 eV move together to 0.1 eV, against 12.3 eV between Ti and Sr in SrTiO3.

    The point-charge wall is calibrated, and it is the default. --vasp-setup writes VACSIGMA 0.5, VACRWALL 0.45 and VACWALL = 2.5 q e^2 sqrt(2/pi)/sigma, one height per Va species so the charge scaling stays automatic; the new --vasp-sigma and --vasp-wall-factor change the first and the last, and --vasp-rwall defaults to 0.45 instead of 0.5. The same values are the defaults of the modified VASP, so a run made by hand and a run set up by CrystOD agree. A 72-point scan over (sigma, VACRWALL, height) on SrTiO3 and ScF3 organizes the whole family by one coordinate, the radius r10 = b sqrt(2 ln(A/10 eV)) at which the wall still repels by 10 eV: below 0.7 A the anion sublattice collapses into the bare -q/r well (occupied bands below the projection floor, negative gaps, metallic points), above 1.4 A the wall expels the anion valence shell (an O 2p manifold three times too wide, alignment shifts to +47 eV). The recommended setting sits at r10 = 0.99 A for q = +2 and 1.13 A for q = +4, the middle of the 0.85-1.25 A plateau, so ONE setting serves +2, +3 and +4; it is the joint minimum of the anchor-residual rms on both systems (SrTiO3 0.407 eV, ScF3 0.304 eV) and simultaneously the point where the anion p-manifold width matches the crystal best (-0.13 and +0.06 eV, against +0.49 and +0.40 eV before), and it transfers to CaF2 without retuning (rms 0.289 eV). What the wall chooses is the anion column’s position: across the scan the alignment shift ranges over 45 eV while the residual rms on the plateau moves by 0.1 eV. The shipped example/SrTiO3_Pm-3m and example/ScF3_Pm-3m sublattice runs were recomputed at the new default (the SrTiO3 anion shift moves from +5.144 to +6.147 eV).

    Two defects the fluorite study exposed are fixed with it. The anchor pool is cut per element, with that element’s own provisional shift, instead of once per column with a rigid pre-shift: with two sites 9 eV apart that one pre-shift is wrong for one of them and silently drops a whole shell’s anchors, so a site could report shell spread 0.20 eV -> shells agree when its own level table shows 1.56 eV. A shell that is drawn but contributed no anchor is now named in the report. And the parent energy a bond character is read against averages over all parents, with the deep semicore shells excluded (the criterion --valence-only uses for the other two engines) instead of everything below a 5 % connector weight: the old cut made both members of one three-level interaction antibonding with no bonding partner at all. The report also names, per k point, the fragment levels the drawn window cuts off the top — an empty cation d manifold can land a few hundredths of an eV above the default VBM + 10 eV and vanish at one k point out of four with no message.

    The forms of --vasp, the optional -c, and the setting the labels belong to. --vasp now takes no path (the current directory is the ROOT), one ROOT as before, or the three run directories in any order — --vasp ./BAND ./BAND_sublattice1 ./BAND_sublattice2, whatever they are named and wherever they live, the crystal run being the one whose POSCAR carries no Va species; two paths, or more than three, are refused in one line that shows the accepted forms (naming the three used to be an argparse “unrecognized arguments” error). -c is now optional with --vasp: without it the structure is the crystal run’s own POSCAR. With it, the analysis setting is the primitive cell of that file — so the irreps agree level for level with the extended-Hückel and PySCF diagrams and with crystod -c FILE --element ... --orbital ... of the same file — and every run is mapped onto it: the same lattice (the Cartesian matrices within a relative 1e-3), one global origin shift per run, a permutation of the atoms and lattice-vector wraps, with Va atoms mapping onto the removed ones. A -c file with Sr at the origin against runs written with Ti at the origin — the same crystal, the origin moved by (1/2,1/2,1/2) — used to stop with ERROR: ./BAND/POSCAR has Ti where the primitive cell has Sr (atom 1); it is now the same analysis, and every number of it (raw and aligned energies, site shifts, projected weights, purities, shares, connector weights) is identical to the analysis in the runs’ own setting to the last printed digit. What does differ is the irrep labels, which depend on the choice of origin (SrTiO3 at R: 1+ ↔ 2-, 3+ ↔ 3-, 4+ ↔ 5-; at X: 1+ ↔ 3-, 2+ ↔ 4-, 2- ↔ 4+, 5+ ↔ 5-; at M: 1+ ↔ 4+, 2+ ↔ 3+, 2- ↔ 3-), so the mapping is stated in the terminal report, in the level table, in the JSON ("setting") and as a chip on the page whenever it is not the identity. The transport needs no per-atom Bloch phase: the PROCAR projection vector is in VASP’s periodic gauge (the gauge the permutation representation is built in, section 2 of the engine report), where a coefficient belongs to an atom and not to one image of it, so the wraps cancel against the lattice sum and the origin shift contributes the one factor exp(−2πi k·s) to every atom alike. Proved on fluorite, whose quarter-coordinate F sites are the only fixture that can see the difference: transported with the atomic-gauge wrap factor exp(−2πi k·n_a) instead, 6 of 85 labelled levels fall below irrep purity 0.90 (minimum 0.249, three levels of one L manifold split 0.249/0.251/0.469), while the bare reordering gives the reference run’s 80 levels with purity 1.000 and identical energies. Names: without -c, or with a -c file that lives inside one of the run directories, the page is no longer named after the run directory (CrystOD_BAND_vasp.html) but after the compound and the space group — CrystOD_SrTiO3_Pm-3m_vasp.html, titled SrTiO3, Pm-3m; an ordinary -c file keeps the CrystOD_{cell}_vasp.html convention of the other engines. If the -c file and the crystal run are the same crystal in genuinely different bases the analysis falls back to the crystal run’s own setting and says so; if they are not the same crystal, the run stops with one line naming what differs and suggesting -c BAND/POSCAR. --vasp-setup follows the crystal run, not the -c file: -c is optional there too (without it the structure is ROOT/BAND/POSCAR), and the POSCARs it writes are now ROOT/BAND/POSCAR with one sublattice renamed to Va<q><sign> — its lattice, its origin and its ion order, line for line — with the -c file only naming the fragments and the formal charges; it used to write them in the -c setting, so a shifted -c silently produced fragment runs on another origin and on a lattice constant 3.2e-5 Å away from the crystal run they are compared with, which the new mapping then quietly repaired. A run directory that already holds a finished calculation (OUTCAR, PROCAR, vasprun.xml) is no longer overwritten without --force: rewriting it replaced the INCAR that was actually run. example/03_hybridization/vasp_SrTiO3 gained the Sr-origin POSCAR-finish of those runs and a README; tests in section 3.

  • New command crystod-xrd: powder X-ray diffraction patterns. crystod-xrd -c POSCAR prints the Bragg peaks of the structure (h k l, multiplicity, d, 2θ, relative intensity), writes them as a comma-separated table and draws the broadened pattern as a PDF with tick marks at the peak positions. The intensities come from pymatgen’s XRDCalculator. --xraytype selects the radiation: a Kα doublet (CuKa, the default, and MoKa, AgKa, CoKa, FeKa, CrKa) superposes the Kα1 and Kα2 patterns in the 2:1 ratio, a single line (CuKa1, CuKb, MoKa2, …) gives the monochromatic pattern, with the wavelengths of the RIETAN-FP manual. --peak-profile draws Lorentzian (default) or Gaussian peaks, both normalized to unit area so the two figures share one intensity scale; --width, --two-theta and --min-intensity adjust the figure and the window. Every reflection is kept by default, including the ones below pymatgen’s own 0.001 % cut-off. Families of planes that share a d spacing (cubic (3 0 0) and (2 2 1)) are listed together. This is the former script/xrd_pattern_poscar.py; on ScF3 the command reproduces all 36 peaks of that script to within 5×10⁻⁵ in 2θ and intensity. The Python form is the new API domain crystod.xrd (load_structure, compute_xrd_pattern, smear_pattern, write_peak_table, plot_xrd_pattern), and crystod-xrd --example ScF3 / --example SrTiO3 run on the bundled cells. Documentation: crystod-xrd. Tests in the new section 36 (section 46 since v0.4.4; 21 checks, including Bragg’s law for every peak and the unit area of both profiles); worked example in example/36_xrd_pattern (now example/46_xrd_pattern).

  • New command crystod-search: search the Materials Project and download POSCAR files. crystod-search SrTiO3 lists the matches the way the website’s table does (formula, space group, material ID, band gap, energy above hull, sites), sorted by the energy above the hull, with * after the ID of every experimentally observed material (mp-5229 *). The query is read like the website’s search box: a formula (SrTiO3, *TiO3), an anonymous formula (ABO3), a chemical system (Sr-Ti-O for the compounds of exactly these elements, Sr-* with a wildcard element), a list of elements (Sr,Ti,O, every material containing at least these) or material IDs (mp-5229,mp-5532). Server-side filters narrow the list: --experimental, --stable, --ehull, --band-gap, --sites, --spg, --exclude and --subsystems (a chemical system with all its subsystems), with --sort and --max (default 1000; a longer list, or --sort spg, which the server cannot sort on, is fetched in ID order and sorted locally, so no material is repeated or skipped at a page boundary). crystod-search --get mp-5532 writes POSCAR_Sr2TiO4_I4mmm_mp-5532 into the current directory, and a bare --get after a query downloads every listed material. The POSCAR holds the spglib-standardized conventional cell (14 atoms for Sr2TiO4), found at the tolerances the Materials Project assigns its space groups with (0.1 Å, 5°), so the file carries the listed space group exactly (the stored cell of Sr3Ti2O7, mp-3349, reads as C2/m at the default tolerance of crystod, the download as I4/mmm); --cell primitive writes the standardized primitive cell as PPOSCAR_Sr2TiO4_I4mmm_mp-5532 instead (7 atoms; the SALC analysis gives the same result for either file), so the two cells of one material never overwrite each other; --directory writes {formula}_{space group}_{ID}/POSCAR (PPOSCAR), -o names a single file, an identical existing file is kept and a different one is replaced only with --force. The API returns material IDs in its 8-letter alphabetical form (mp-aaaaahtd); they are shown as the website shows them (mp-5229, numbers up to mp-3347529, letters above), and both spellings are accepted. The client talks to the materials/summary endpoint of the Materials Project REST API with requests, now a dependency; the free API key is read from MP_API_KEY or from PMG_MAPI_KEY of the pymatgen settings file, and a missing, legacy or rejected key stops with a one-line ERROR: that says where to get one. The Python form is the new API domain crystod.search (search_materials, fetch_materials, write_poscar, normalize_material_id, …), and crystod-search --example SrTiO3 / Sr-Ti-O / mp-5229 run three ready-made searches. Documentation: crystod-search. Tests in the new section 37 (section 48 since v0.4.4; 95 checks, run offline against a local stand-in for the API that serves data recorded from the Materials Project; CRYSTOD_LIVE_MP=1 adds one live search); worked example in example/37_mp_search (now example/48_mp_search).

  • Fixed: crystod-phonon --modulation crashed at many q points and froze wrong structures at the others. Reported on a Cmcm structure (--qpoint 0.5 0.5 0 --mode 1 --amplitude 1.5, expected Pnma) and on I4/mmm SrLi2Nb2O7 (the two X arms --qpoint1 0 0 0.5 --mode1 1 --qpoint2 -0.5 0.5 0 --mode2 1, expected P4_2/mnm): both stopped with “RuntimeError: Coupled irrep spaces are not equivalent.” Three errors in the mode construction were behind it. spgrep’s irrep-projected rows were read as bras instead of kets; phonopy’s dynamical matrix, which already carries the phase convention the displacement representation acts on, was re-phased once more; and the symmetry analysis ran on an spglib re-standardized copy of the primitive cell (shifted by c/2 for the Cmcm structure, with three atoms wrapped by a lattice vector for the nickelate) while the dynamical matrix stayed on phonopy’s. Whether a q point crashed therefore depended on how it was written, not on which arm it was: on the shipped Sr3Ti2O7 example (0.5, 0.5, 0) ran and (-0.5, 0.5, 0), the same point, crashed; “Coupled irrep spaces with different dimensions” (ScF3 at (-0.5, 0.5, 0.5)) and “… is not scalar” were the other forms. Where it did not crash, the result was silently wrong for structures with atoms off the inversion centres: the frozen-in pattern was not the eigen-displacement of the chosen mode but a mixture of the levels of its irrep (overlap 0.31 with the correct pattern for Sr3Ti2O7 X3- mode 1), Sr3Ti2O7 X3- mode 1 at (0.5, 0.5, 0) printed Cmcm only because the space group is reported at 0.1 Å (Ama2 at 1e-5), and the two-arm direction X3-(a;a) came out Pnnm (Pnn2 at 1e-3) instead of P4_2/mnm. Structures with every atom at 0 or 1/2, such as the cubic perovskite examples, kept their space groups. One solver, crystod.symmetry_adapted_modes, now serves --modulation and --vector: it works on phonopy’s primitive cell as it is (nothing is re-standardized, so the output keeps the origin and orientation of the input) with the dynamical matrix exactly as phonopy returns it, reads the projected rows as kets, orthonormalizes repeated occurrences of one irrep (spgrep leaves them non-orthogonal; ScF3 in R32 and RuCl3 in P3_112 failed even at Γ), and checks every run against the phonopy spectrum, the eigenvalue equation of every vector and orthonormality. The two reported commands give Pnma and P4_2/mnm; every arm and every q + G spelling constructs, and q + G freezes the same structure as q.

  • Fixed: --modulation froze the mass-weighted eigenvector instead of the displacement, with an arbitrary phase. The frozen-in field is now the eigen-displacement e_j exp(2 pi i q.x_j) / sqrt(m_j) — for a non-degenerate mode at a time-reversal-invariant q, the pattern phonopy’s own MODULATION writes, up to its sign (the test suite compares the two); without the 1/sqrt(m), heavy atoms moved too much against light ones in every mode that moves several species (the Sc-F mode X3- 9 of ScF3: overlap 0.990 with the true pattern). --amplitude is now the norm of the displacement of one primitive cell, exactly so at a time-reversal-invariant q (2q a reciprocal lattice vector), where every mode vector is now real; the global phase used to be whatever the eigensolver returned, so only part of the requested amplitude was frozen in (70 % for Sr3Ti2O7 X3- mode 1 at (0.5, 0.5, 0)). At those q the partners of a degenerate level are real, orthonormal and chosen, and numbered, by the isotropy subgroups they freeze into (the most symmetric first), a rule that does not depend on the origin, orientation or lattice basis of the cell, equivalent partners listed along the crystal axes where those tell them apart (--mode 1 2 3 of the R4+ triplet of ScF3 rotate about a, b and c; the Si Γ triplets are x, y, z, and the Si --vector example files were regenerated) and by their displacement patterns where they do not (the two Pnma partners at X of Si, which used to swap with the origin of the input), and the partners of one level signed relative to each other, so single partners and equal-amplitude sums give order-parameter directions, the same domain for every origin (a complex irrep and its time-reversal partner form one real level, and the Degeneracy column shows twice the irrep dimension; its partners are fixed by the displacement patterns); at any other q the global phase is fixed by a convention only (independent of the orientation of the input) and is not physically controlled. The manual’s new “What is frozen in” section states the convention.

  • Fixed with it: --vector, --subgroup --modulate and the error paths. --vector shares the solver and no longer falls back to plain phonopy eigenvectors (with a warning) where the construction failed, e.g. at the reported Cmcm q point and at the P point of I4/mmm Sr3Ti2O7. --subgroup --modulate writes the X3-(a;a) P4_2/mnm and X3-(a;b) Pnnm structures of Sr3Ti2O7 that it reported as “no candidate reproduced”, and the Y2- (Pnma) and Y4- structures of the reported Cmcm case, which it skipped with “no structures generated”; it now also tries negative coefficients, after all positive ones, so directions such as N1+(a;-a;a;a) (I4_1/amd), (a;-a;b;b) (Imma) and (a;b;-a;b) (C2/c) of the SrLi2Nb2O7 case are generated too, and every printed reproduce command regenerates its file exactly (the amplitudes are generated with the ten significant digits the command shows; 0.3 x 0.5478 used to be printed as 0.16434 but frozen in as 0.16433999999999999). --subgroup no longer lists the acoustic modes at Γ (rigid translations) when --threshold lies above zero; their directions could only end as “no candidate reproduced” notes. A q that no supercell of at most 12 cells per axis holds is refused before any mode is computed (0.15 used to be frozen into a 7-cell supercell on which the modulation is not periodic); a phonopy object whose primitive cell is not primitive is refused with a message pointing to primitive_matrix="auto"; a construction that fails ends in one ERROR: line instead of a traceback. Frequencies use the phonopy object’s unit conversion factor instead of the VASP constant, and the “Inputed cell was converted into primitive cell” line is gone from --modulation. Python API: SymmetryAdaptedModulation.mode_vectors now holds the freezing vectors above (with 1/sqrt(m), normalized over the primitive cell), the new attribute eigenvectors the phonopy-convention eigenvectors; get_commensurate_supercell_sizes raises ValueError for an incommensurate q; crystod.symmetry_adapted_modes.NonPrimitiveCellError (a ValueError) is new.

  • Structures written by --modulation, --subgroup --modulate or --vector of v0.4.1 and earlier should be regenerated — for structures with atoms off the inversion centres they are wrong whatever space group was printed, and elsewhere the domain may differ. The shipped Sr3Ti2O7 structures in example/25_modulation were regenerated (same space groups; the old X3- pattern overlapped the correct one by 0.31), and the directory gained the (a;a)/(a;b) structures of --subgroup --modulate and the two-arm P4_2/mnm example. The ScF3 structures there are kept as written: every command gives the same space group, and the README says which ones now come out as another domain. Its Im-3 command, whose third arm repeated the first (--qpoint3 0 0.5 0.5, which gives Immm), now reads --qpoint3 0.5 0.5 0. Tests in sections 24, 25 (including a comparison with phonopy’s own modulation) and 27.

  • Fixed: crystod-phonon --vibration wrote structures of the wrong symmetry. The symmetry-only command froze the raw spgrep projected row as Re(row_j exp(2 pi i q.R)): the Bloch factor exp(2 pi i q.x_j) of each atom’s own position was missing, and the phase and, at a time-reversal-invariant q, the partner basis of the row were whatever the projection returned — the error fixed in --modulation above. Where the missing factors happened to be equal on all atoms of the pattern (ScF3 at R written 0.5 0.5 0.5) the structure came out right; elsewhere it could not be trusted. Sr3Ti2O7 X3- (--qpoint 0.5 0.5 0) froze into Ama2 in 4 of its 6 mode spaces, and at the same point written -0.5 0.5 0 one space gave Cmce, the subgroup of another irrep (X3- is Cmcm, crystod-group --parent I4/mmm --irrep X3-); in all, 54 of the 144 components of the X irreps at four spellings of the two X arms were not an isotropy subgroup of their irrep, 162 of 252 for SrLi2Nb2O7 at X and N (most N components Cm or Cc instead of C2/m or C2/c), 156 of 216 for the Y irreps of the reported Cmcm SrLi2Nb2O7 (8 of the 10 Y2- spaces Pna2_1 instead of Pnma), and 9 of 108 for ScF3 at Γ, R, M and X (R1+ gave I4/mmm at -0.5 0.5 0.5). A written component is now a genuine partner of its mode space, built by the solver of --modulation with no dynamical matrix (crystod.symmetry_adapted_modes.solve_symmetry_adapted_spaces; every mode space one level; the spaces of a repeated irrep an orthonormal basis of its patterns fixed by the structure — the atom orbit each lives on, then how the atoms move along the crystal axes, then the products of neighbouring displacements — instead of the copies spgrep’s projection returns, which depend on how q is written): at a time-reversal-invariant q real in the lattice gauge, along the directions, in the order and with the signs --modulation uses, with the Bloch factor taken from the cell the supercell is built on; at any other q a Bloch wave with the phase convention of --modulation. It is a unit-norm symmetry-adapted displacement pattern, not a normal mode (no masses, no force constants), and --amplitude is now the displacement norm of one primitive cell at such a q. Every component of those four test sets (720 in all) now freezes into the single-arm isotropy subgroup of its irrep at a tolerance of 1e-5 (X3- Cmcm, X4- Cmme, X2+ and X3+ Cmce, X1- Ccce, X1+ Cmmm, X2- Cmcm, X4+ Cccm; Y2- and Y2+ Pnma, Y4- Pmmn, Y4+ Pbcn, Y1+ Pmma, Y1- Pnna, Y3+ Pnnm, Y3- Pbcm; ScF3 R4+ I4/mcm for each partner), and so do the 15645 labelled components at the time-reversal-invariant special points of 58 test structures in 54 space groups, apart from the rigid translations at Γ; at those points q, q + G and -q write the same structure for the same irrep label, occurrence and component (the mode-space numbers follow the irrep order of the spelling used, as before; a complex irrep and its conjugate, which share one real space, hand out its partners in the order of their labels), an origin-shifted input gives the same space groups, and where an irrep occurs once the written pattern is the --modulation mode of that irrep (identical vectors on the same cell for ScF3 at Γ, R, M and X and for Sr3Ti2O7 and SrLi2Nb2O7 at Γ and M). The mode-space listing, labels and numbering are unchanged; the written structures, the --export-npz displacements and the printed displacement lines change. Python API: the new SymmetryOnlyVibrations.get_symmetry_adapted_spaces returns the partners in the order of describe_mode_spaces, and get_supercell_displacements now applies exp(2 pi i q.(R + x_j)), so a projected row given to it gets its per-atom factor as well. The shipped example/26_vibration files were regenerated (the same I4/mcm; component 1 of R4+ is now the rotation about a, the structure --modulation --mode 1 writes) and its README, which still showed the 0-based numbering, reproduced. Tests in section 26.

  • Fixed with it: partners chosen by round-off where symmetry leaves the basis open. At a time-reversal-invariant q, the real space of a complex irrep and its conjugate, and a pseudo-real level, get their partners from quadratic forms of the displacements (--modulation, --vector and --vibration alike). Where every atom of such a space moves on a circle, those forms were degenerate, and the eigensolver turned the basis by round-off, so the written pattern could change with how q was written (--vibration on P-4 MnZnGa4Se8 at Γ, spelled 0 -1 -1: a GM3 pattern rotated by 45°). The forms now include how each atom moves along the crystal axes, and a part that no form splits keeps its basis. The --modulation, --vector and --subgroup --modulate runs of the reported Cmcm and SrLi2Nb2O7 cases, Sr3Ti2O7, ScF3 and Si write the same files as before.

v0.4.1#

  • crystod-group --parent is now the primary spelling of the isotropy-subgroup command; --supergroup stays as an alias. --supergroup SG --irrep IR sat next to --supergroup-cif FILE --subgroup-cif FILE (the symmetry-mode analysis of section 16), and the two were easy to confuse when coming back to the tool after a while: one lists the subgroups an irrep of the parent group SG can produce, the other decomposes a distorted structure. The command is therefore crystod-group --parent Pm-3m --irrep R4+ [--order-parameter 0 0 a], named after the value it takes; --supergroup Pm-3m is accepted unchanged and gives byte-identical output, so existing scripts keep working. The help texts, error messages (--parent requires --irrep), the documentation (section 13, quick start, tutorials, MCP page), the example README and the test suite use the new spelling.

  • crystod-group --supergroup-cif: the sublattice setting follows the orientation of the input files (reported on PbTiO3 Pm-3m → P4mm: the polarization along c of the P4mm CIF came out along −b of the cubic parent in the displacement table and in the GM4- VESTA file — crystallographically equivalent, but not the structure the user supplied). 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, and the enumeration order used to pick one. Among the settings tied on the total distortion, the one whose child axes are rotated least against the parent axes is now chosen, both lattices taken as the input files orient them (recovered from spglib’s non-idealized standardization, which keeps the Cartesian frame of the file: a CIF sits with c along z and a in the xz plane, a POSCAR as written), so displacements and mode VESTA files follow the axes of the subgroup structure — a POSCAR whose polar axis lies along Cartesian y comes out along b. When no setting aligns the axes (standard settings that permute them, √2×√2 cells, a rhombohedral child in its hexagonal setting) the residual rotation is printed with the cell relation. Irreps, isotropy subgroups, dimensions and amplitudes of all 18 validated pairs are unchanged to the last digit; the direction labels of some pairs switch to a domain-equivalent form in the new setting (SrTiO3 R5- (a,0,0) instead of (0,0,a)), and the example VESTA files were regenerated. Tests in section 16 (PbTiO3 polarized along c and along Cartesian y).

v0.4.0#

  • PySCF is now an optional dependency (breaking change). pip install CrystOD no longer pulls in PySCF (about 500 MB with its dependencies); the quantitative engines — crystod --diagram/--band/--dos/--visualize --pyscf and crystod-mol --diagram --pyscf — need pip install "CrystOD[quantum]" once. Everything else (SALC irreps, extended-Hückel crystal-orbital and MO diagrams, group theory, phonon irreps, modulations, spin bases, Brillouin zones, molecular SALCs) runs without it. A --pyscf run in an environment without PySCF stops with one line that names the install command instead of a traceback, and the API classes crystod.salc.PySCFCrystalOrbitalDiagram / crystod.mol.PyscfDiagram raise ImportError with the same hint (crystod/_optional.py). The pyscf<2.14 cap moves into the extra. Verified by installing the built wheel into a fresh environment without PySCF: every command imports, the bundled examples run, and both --pyscf paths fail with the one-line message. New extras: quantum, doc, dev (= quantum + doc + ruff, nbconvert, ipykernel, build, twine) and all.

  • --example NAME: the quick start runs right after pip install. crystod, crystod-phonon, crystod-mol and crystod-bz gained --example. A few small inputs ship inside the package (crystod/examples/: the ScF3 and SrTiO3 cells, the 4×4×4 FORCE_SETS of SrTiO3, CH4 and NH3 — 108 kB in total), and --example NAME copies the files of that example into the working directory, prints the ordinary command line it stands for (Running: crystod -c 221_PPOSCAR_ScF3 --element Sc --orbital d) and runs it, so the files are there to edit and re-run. --example alone lists the names (ScF3_d, SrTiO3_d, ScF3_diagram; SrTiO3, SrTiO3_subgroup; CH4, NH3; ScF3). An existing identical file is left alone, a differing file of the same name is never overwritten, and further arguments pass through (crystod-phonon --example SrTiO3 --tolerance 1e-3). The registry (crystod.examples) is shared by the tutorials and the MCP server. Tests in sections 6, 20, 27 and 34.

  • --kpoint accepts a high-symmetry label in every mode of crystod. crystod -c POSCAR --atomic-orbital Sc-d F-p --kpoint R — the form the documentation had shown all along — was rejected in the SALC and hybridization modes (”–kpoint requires three coordinates”): labels were resolved only by --star-of-k, --visualize and --diagram. The label is now looked up in the ISO-IR special-point table the survey itself uses — the names crystod-bz --show-kpoint prints (GM, X, M, R; GM, Y, A, V, L, M for C2/m), resolved in the spglib primitive basis of the analysis — so --kpoint R, --kpoint Y and --kpoint GM (also GAMMA, G and Γ) work in every mode and print exactly what the coordinate form prints; an unknown label answers with the labels the space group has. Tests in section 6.

  • Fixed: seekpath labels were resolved in the wrong basis on base-centred monoclinic cells. crystod --star-of-k, crystod --visualize and the --qpoint labels of crystod-phonon --vibration/--vector/--modulation take their coordinates from seekpath, whose primitive cell differs from spglib’s by an integer change of basis for C-centred monoclinic lattices (VO2 C2/m: seekpath’s C was analyzed at [0.355, 0.355, 0], a different point, after a warning that the “coordinates might need a basis transformation”). The coordinates are now transformed into the spglib basis whenever the two cells are related by such a change of basis (C → [-0.355, 0.355, 0], the ISO-IR line LD), and the warning remains only for the case that cannot be transformed. Also fixed: the G alias of Gamma hid the genuine G point of body-centred tetragonal cells (--qpoint G on I4/mmm Sr3Ti2O7 now gives seekpath’s G = [1/2, 1/2, −0.018]). Tests in section 6.

  • crystod-phonon stops with one line when FORCE_SETS is missing. --irreps, --fatband, --lt, --vector and --subgroup read FORCE_SETS (FORCE_CONSTANTS with --readfc) from the working directory, as phonopy does; a run from another directory used to die in a phonopy FileNotFoundError traceback and now says where the file is expected (only --modulation also looks next to the cell file).

  • README and documentation for a first-time visitor. The README opens with the questions CrystOD answers, four output images (crystal-orbital diagram of ScF3, phonon dispersion of SrTiO3 with ISO-IR labels, 3D Brillouin zone, MO diagram of CH4), badges, the two-line installation and a quick start that needs no input file. The documentation site gained the same images, a “Try it” column in the question table, two Getting-Started pages (Your first analysis, CrystOD for phonopy users), a Tutorials page and a Contributing page.

  • API reference (Sphinx autodoc). Every symbol exported by crystod.salc, crystod.group, crystod.phonon, crystod.bz, crystod.mag, crystod.md and crystod.mol now carries a Google-style docstring (arguments, returns, raised errors, a runnable example) and is rendered at https://mochizuki-tus.github.io/CrystOD/api/ (doc/api/); the lazy namespaces work with autodoc unchanged. The docs workflow installs the package for the build; the -W build stays clean.

  • Three Jupyter tutorials in tutorials/ — phonon irrep labeling for phonopy users, isotropy-subgroup search from imaginary modes, MO diagrams of CH4 and NH3 — executed on the bundled inputs with their outputs saved, the Python API and the command line side by side.

  • crystod-mcp: a Model Context Protocol server. A separate package in crystod-mcp/ (pip install ./crystod-mcp; MCP Python SDK 2.x) exposes ten CrystOD analyses as tools — isotropy subgroups, irrep products, reducible-representation decomposition, ligand-field splitting, character tables, phonon irreps, imaginary-mode subgroups, crystal-orbital irreps, special k points, molecular symmetry — to Claude Desktop, Claude Code and other MCP clients. Every result carries the ISO-IR and CrystOD citations, each tool runs under a timeout (60 s, CRYSTOD_MCP_TIMEOUT), and 22 tests cover the tools and the protocol round trip. Not on PyPI yet.

  • Continuous integration. GitHub Actions now run the test suite on every push and pull request (Linux with Python 3.10/3.12/3.13, macOS with 3.12), ruff (rule set in ruff.toml), the docs build with warnings as errors (as before), and publish a tagged release v* to PyPI through Trusted Publishing after a manual approval (publish.yml; the one-time PyPI setup is described in the file). CONTRIBUTING.md describes the development setup, the section-number convention (feature N ↔ testsuite.py N ↔ example/N_* ↔ documentation section N) and the release recipe.

  • Housekeeping: *.bak and .DS_Store are ignored, the duplicated .gitignore block is gone, crystod --version is checked against the package version in the test suite, and the PyPI description says what the package does.

v0.3.8#

  • Package metadata now describes what the package can actually do. requires-python said >=3.9, which was untrue and already published: phonopy’s newest release carrying a CPython 3.9 wheel is 2.9.1 (2021), so pip back-solves to a phonopy sdist that fails to build, and pip install crystod cannot succeed on 3.9 at all — measured, with both pip and uv. The floor is now >=3.10, verified end to end by building throwaway environments on 3.10 through 3.14 and running the analyses in them (the source itself is 3.9-clean; the dependency stack is what sets the floor). Operating System :: OS Independent was likewise false: pyscf has never published a Windows wheel for any release and its own documentation directs Windows users to the Windows Subsystem for Linux, so the classifier is replaced by Linux and macOS, joined by the per-minor Python classifiers. Every one of the twelve dependencies now carries a lower bound traced to the specific API that sets it — phonopy>=2.9 for phonopy.phonon.character_table, sympy>=1.10 for hermite_normal_form, spgrep>=0.3.1 for the spinor irreps behind --spinor, ase>=3.21 because 3.20 silently writes a VASP 4 POSCAR with no element line, pymatgen>=2025.1.9 because older releases pull a monty whose zopen signature breaks Structure.from_file, and so on — and CITATION.cff gained the date-released, repository-code, url, abstract and keywords fields it needed for a citation with a year in it (validated with cffconvert).

  • pyscf is capped below 2.14.0, which cannot run a zero-electron cell. 2.14.0 rewrote pbc.scf.khf.get_occ as if 0 < nocc < nmo / elif nocc == nmo / else: raise, and a fragment that a GTH pseudopotential fully ionizes — Al³⁺ of AlN keeps no valence electrons — has nocc == 0, which matches neither branch and dies with Failed to assign mo_occ. Nocc (0) > Nmo (52), an inequality that is not even true. Isolated by crossing the two variables: the same structure passes on 2.13.1 under both Python 3.10 and 3.11 and fails on 2.14.0 under both, so it is the library version and not the interpreter. Only fragments that end up empty are affected — the crystal column of the same AlN run converges on 2.14.0. The cap is a stopgap; the durable fix is to skip the self-consistent cycle for a cell with no electrons.

  • A purely ferroelastic pair no longer aborts the symmetry-mode analysis (found while reproducing 27 saved AMPLIMODES runs; La3Ni2O7 I4/mmm → Fmmm died with “cannot separate the surviving from the broken parent operations”). How many parent operations survive in the child was derived from the child’s own space group, but that count is only a lower bound: mode amplitudes are measured in the strain-free parent-derived reference lattice, so an operation that the child’s metric breaks with no atomic counterpart still leaves the displacement field invariant and belongs in the analysis group. In La3Ni2O7 all 16 parent operations hold exactly while spglib reads the child as Fmmm (8), and cutting the mismatch spectrum in the middle of 16 exact zeros was impossible — correctly refused, but the wrong question. Whenever at least that many operations sit at the numerical-noise level they are now all kept, and the report says so (“8 parent operations that the child’s own metric breaks leave its atomic pattern exactly invariant … a spontaneous strain”). Reproduces the AMPLIMODES reference exactly: a single GM1+ mode, isotropy subgroup I4/mmm itself, dimension 4, 0.4666 Å, maximum displacement 0.2669 Å.

  • --poscar2cif warns when the CIF comes out more symmetric than the POSCAR. The CIF holds the spglib-standardized structure, so a displacement smaller than the tolerance is averaged away — silently turning a distorted structure into its own parent, after which a symmetry-mode analysis reports no distortion at all with nothing in the output to explain why. GaN F-43m → I-42d is the case that exposed it: its entire distortion is 0.0002 Å against the 0.01 Å default, and the child CIF came out byte-identical to the parent’s. The conversion now names both space groups and points at --tolerance; at --tolerance 0.0001 the pair reproduces AMPLIMODES exactly (W1 at (1/2,1/4,3/4) → I-42d, 0.0004 Å). Tests in sections 15 and 16.

  • crystod-group --supergroup-cif works for rhombohedral parents (reported on Ag3SI R32 → R3, which died with “could not fit the ISO-IR origin shift”). The centring translations used to match the ISO-IR origin against spglib’s conventional operations were generated from the rows of the primitive matrix, whose mod-1 lattice happens to coincide with the columns’ for every centring type except R — rows give (1/3, 1/3, 1/3) where the obverse setting needs (2/3, 1/3, 1/3), so no origin could ever fit an R-centred parent. Validated against ISODISTORT for Ag3SI: GM1 0.0741 Å matches exactly, and the polar GM2 amplitude agrees to five decimals (Ag in-plane 0.52161, I 0.16902, S 0.44628 Å) once the origin conventions are aligned — ISODISTORT pins the first orbit’s polar displacement to zero, while CrystOD keeps the AMPLIMODES minimum-distortion origin (the acoustic translation is removed, so the reported GM2 is 0.6512 Å instead of ISODISTORT’s origin-dependent 0.7070 Å). Tests in section 16, including the measured origin-convention equivalence.

  • --diagram --pyscf caches its SCFs by default, as CHK_{formula}.chk. A three-SCF periodic run is the expensive part of the page, and until now it was thrown away unless the user had thought to pass --chk beforehand. The densities are now saved under the compound’s reduced formula in conventional chemical order (rutile TiO2 → CHK_TiO2.chk, the same naming the symmetry-mode tables use), and the next run on that structure reads them and skips the SCFs (measured on TiO2 at Γ: 8 s instead of a full three-SCF run). The automatic file is a cache, so unlike an explicit --chk it never blocks a run and never costs one: options that do not match the stored ones (a different --xc, --kmesh, an --onsite file where fragment columns are wanted, a pre-electron-count-fix checkpoint), a checkpoint left by a same-formula polymorph (rocksalt and wurtzite AlN are both CHK_AlN.chk, with 2 and 4 atoms per cell — that comparison used to raise a raw numpy broadcast error), and a file that is not readable at all (an interrupted write, a foreign file that happens to match the name) each print one line and recompute. The checkpoint is written to a temporary file and renamed, so an interrupted write cannot leave a truncated one behind, and if it cannot be written at all (read-only or full working directory) the run says so and keeps going — losing a finished three-SCF calculation to a cache the user never asked for would be absurd. --no-chk turns the cache off entirely. --chk FILE keeps the strict contract — that file is the user’s, so a mismatch still aborts with the crystod --chk-info pointer instead of silently overwriting it. --electrons no longer invalidates a checkpoint (it fills the diagram’s arrows, it is not an SCF input), while the SCF’s own conv_tol/max_cycle, which do shape the density, are now part of the comparison. --chk FILE keeps the strict contract — that file is the user’s, so a mismatch still aborts with the crystod --chk-info pointer instead of silently overwriting it. Tests in section 3.

  • The extended-Hückel diagram now CAUTIONs that its level ORDER can be qualitatively wrong. Prompted by the rutile TiO2 case above: the model is non-self-consistent with fixed atomic parameters, so the symmetry labels, the state compositions and the bonding/antibonding pattern are reliable, but the energies carry no charge-transfer response and a whole band can land in the wrong place (TiO2’s artificial Ti 4p band inside the O 2p band, which costs the compound its insulating filling). The terminal report prints the caution once per run, the page footer carries it, and the --visualize levels viewer — which solves the identical Hamiltonian — prints it too. What the caution claims is deliberately narrow: the symmetry is rigorous (irrep labels, which states may mix, which stay nonbonding), the order can be wrong, and a wrong order takes the compositions with it (in the same TiO2 the bonding Γ₃⁺ comes out Ti-dominated and its antibonding partner O-dominated — the reverse of the heteropolar rule and of PySCF, verified against both engines). The prescribed --pyscf cross-check is qualified rather than absolute: it cannot run for the lanthanides, which no GTH basis covers, and there the caution says to read the diagram as a symmetry analysis instead. Test in section 3.

  • Fixed: the --diagram hover sketch could draw a 90%-s level as d lobes. Rutile TiO2’s Ti 4s Γ₁⁺ fragment level (Löwdin: Ti 4s 89.9%, Ti 3s 5.6%, Ti 3d 0.8%) rendered with drawn d:s amplitudes of 2.7:1 — the picture contradicted its own tooltip. The extended-Hückel sketch weighted raw eigenvector coefficients by the STO amplitude at a fixed 2-bohr radius, where the compact Ti 3d weighs ~4× the diffuse Ti 4s and the semicore 3s orthogonality tail cancels most of the s channel. The sketch now uses the recipe the PySCF sketches and the --visualize levels viewer already use: lobe sizes calibrated per (atom, l) channel to the Löwdin populations, with the probe radius chosen per channel (1.5/2.0/2.5/3.0 bohr, the one with the largest accumulated amplitude — away from semicore nodes). The TiO2 4s sphere now dominates its own sketch, and the drawn d amplitude² matches its 0.8% population. Level energies and occupations are untouched (verified identical across the full TiO2 page, 373 levels); the filtered --atomic-orbital sketch keeps the legacy fixed-radius amplitudes, since its channel populations include shells deliberately not drawn. Tests in section 3.

  • The extended-Hückel diagram discloses its two artifact modes for diffuse cation shells instead of silently mis-filling. Diagnosed on rutile TiO2, where the Γ-point HOMO (Γ₅⁻) showed 2 of 4 electrons although TiO2 is a band insulator. The electron count is correct everywhere (76 = 2×22 + 4×8; every column sums exactly); what breaks is the level ordering, twice: (1) the ζ = 0.675 Ti 4p STO engulfs the whole O²⁻ coordination cage, so the point-charge penetration term — a small correction for compact shells — shifts its on-site energy by −45.9 eV (to −51.3 eV, below Ti 3p); (2) its Bloch sums are all near-dependent (shell-block overlap eigenvalues ≤ 0.055); the doublet that survives the linear-dependency cut comes back as a first-order ~ estimate at ≈ h̄(1+(K−1)(ε−1)) ≈ −13 eV, right at the O 2p band top, and breaks the insulating filling — in the reporter’s phonopy-relaxed cell it lands inside the band, swallows 4 electrons and leaves the true O 2p top (Γ₅⁻) half-filled; in the slightly larger experimental cell shipped as the test structure it lands just above the band and is itself the half-filled HOMO, taking 2. (The deep Ti 4s Γ₁⁺ fragment level at −31.4 eV is the same physics from the other side: its in-phase Bloch sum has ε = 8.8, and the Wolfsberg–Helmholz energy h̄(K+(1−K)/ε) → K·h̄ overbinds large-overlap combinations — the classic EHT counterintuitive-overbinding artifact — to −36.7 eV pure; intra-sublattice mixing with the Ti 3s/3d Γ₁⁺ sums brings the fragment level back up to −31.4 eV. It miscounts nothing: in the crystal column the corresponding Ti 4s/O 2s bonding state at −36.6 eV simply occupies the O 2s Γ₁⁺ slot’s 2 electrons.) Now disclosed at every surface: the on-site report prints the decomposition (Ti 4p -51.32 [VSIP -5.44, field -45.88]) and WARNs when the point-charge shift exceeds 8 eV; the atomic-column tooltip carries the same warning; and an aufbau that runs out mid-level flags the partially filled level in the terminal and its tooltip (both engines — a genuinely metallic k point prints the same honest note). A column whose electron count is odd (a neutral open-shell sublattice: one level is necessarily half-filled at every k point) and a fractional --electrons request get their own matter-of-fact tooltip notes instead of the warning — parity and rounding are properties, not artifacts. Tests in section 3 (TiO2 at Γ).

  • Fixed: five two-shell --multiplet configurations aborted before printing the ground state (260828 bug report). (t2g)^2(eg)^2, (t2g)^3(eg)^{1,2,3} and (t2g)^4(eg)^2 of m-3m/d died with ERROR: multiplet-energy coefficient failed to snap to an exact fraction (8.66...) — exit 1, no Ground-state Term Symbol. The coupled-parent CI table recovered the off-diagonal coefficients as gram[pivot,q]/sqrt(gram[pivot,pivot]), and in these configurations they are genuinely irrational (2sqrt(2)B, 5sqrt(3)B, 4sqrt(3)B — the same square roots the printed Tanabe–Sugano matrices carry), so the rational-snap assumption could never hold. The Gram products c_p c_q themselves are basis-invariant and rational, so the off-diagonal is now snapped at the Gram level and factored exactly as sqrt(radicand) * (rational linear form) with a squarefree radicand: <1|H|2> = +-(5sqrt(3)B) prints where the run used to die, purely rational forms print byte-identically to before (+-(10B)), and a float reconstruction cross-check guards the factorization. Should a future block still have no such closed form, its table row says so in one line instead of killing the run — the term energies and the ground state never depended on it (they use the trace identity) — and a rank-1 consistency guard (the Gram diagonal must reproduce as radicand * c_q^2) protects the printed closed forms against any silent violation of the single-intertwiner assumption. All five configurations now complete with the physically correct ground states ((t2g)^3(eg)^2 → ^6A1g, the d⁵ high-spin sextet). Tests in section 14., so the choice is the user’s rather than a guess. --basis lists all 21 GTH basis sets PySCF ships grouped by element coverage — the decisive facts being that only gth-szv-molopt-sr and gth-dzvp-molopt-sr reach past Ar (71 elements: H–Rn minus the lanthanides) and that no GTH basis PySCF ships covers La–Lu at all, so --pyscf cannot run on a rare-earth compound (the extended-Hückel engine, which has its own La/Ce/Sm/Gd/Yb/Lu parameters, still can), while gth-tzvp/gth-qzv2p/gth-aug-*/gth-cc-* are main-group or light-element sets; --pseudo lists all 11 GTH pseudopotentials the same way (gth-pbe, gth-pade, gth-lda, gth-hfrev span H–Rn); --xc lists the LDA/GGA/meta-GGA/hybrid functionals verified (by running each of them) in this code path (lda, svwn, pbe, pbesol, revpbe, blyp, bp86, pw91, b97-d, scan, r2scan, tpss, revtpss, b3lyp, b3lyp5, pbe0, hse06, m06, m06-2x, wb97x, and hf), noting that hybrids want --ke-cutoff 150 or more; --orbital names the shells it accepts (s–i); --kpoint points at crystod-bz --show-kpoint for a space group’s labels. The lists are hard-coded so that --help stays import-free (no PySCF import for a help screen), and a testsuite check compares them against pyscf.pbc.gto.basis/pseudo.ALIAS so they cannot drift. Also fixed in the same pass: a basis or pseudopotential with no entry for one of the elements now fails with ERROR: the basis 'gth-qzv2p' has no entry for Sc. plus the list of sets that do cover the structure, instead of PySCF’s BasisNotFoundError from deep inside cell.build(); --xc is validated the same way, so an unknown name (pz, vwn — common shorthands libxc does not have) and a VV10 functional (wb97m-v, b97m-v, wb97x-v, which PySCF’s periodic code cannot evaluate — it has no nonlocal-correlation path, and the old failure was an AttributeError inside get_veff after all three cells were built) each end with one sentence naming the remedy; and the empty-shell caveat added earlier in this release recommended --basis gth-qzv2p unconditionally, which is impossible for anything past Ar — the recommendation now appears only when PySCF actually ships that set for every element, and says so plainly otherwise.

  • Removed the stale “pre-v0.3.0 flat modes” notice from crystod --help, the quickstart and the CLI docstrings: the flat spellings predate the first PyPI release (0.3.6), so no released version ever had them and the version numbers only dated the help text. A flag belonging to a sectioned command still gets the same helpful answer, now without the archaeology: ERROR: '--bz' is not a crystod option. The equivalent command is: crystod-bz.

  • Fixed: charged fragment cells converged with the wrong electron count on any k-mesh larger than 1×1×1 — every fragment column of the default (formal-charge) --diagram --pyscf mode was affected. PySCF subtracts cell.charge once from the Born–von Kármán supercell total (tot_electrons(nkpts) = ΣZ_val·nkpts − charge), not once per cell, so a fragment with formal charge q kept q·(nkpts−1)/nkpts spurious electrons per cell. Measured on the shipped ScF3 checkpoint (2×2×2 mesh): the Sc⁺³ sublattice carried 10.5 electrons per cell instead of 8, the F₃⁻³ sublattice 21.5 instead of 24, while the crystal (charge 0) was exact at 32. The fragment cells now pin their per-cell count explicitly (cell.nelectron), which makes tot_electrons(nkpts) exact on every mesh. Checkpoints written before this fix are refused when the bug could have bitten them — charged fragments on a k-mesh — with a message saying why; crystal-only (--onsite) and neutral-fragment checkpoints remain valid. Affected .chk files and the fragment columns of previously generated default-mode pages should be regenerated. Found by the adversarial review of the neutral-sublattice feature below, whose all-zero charges are immune (they were, until this fix, the only exactly counted fragment configuration).

  • --diagram --pyscf accepts neutral-atom sublattices (--oxidation Al=0 N=0) — the extended-Hückel engine’s convention, previously rejected with “the formal charges must make every fragment closed-shell”. Two things had to give: (1) a neutral sublattice usually has an odd electron count per cell (neutral Al: 3), which a spin-restricted driver with integer occupations cannot hold — pyscf’s aufbau would silently drop the unpaired electron (nocc = nelectron // 2). Such a cell is now solved with Fermi smearing automatically (fractional occupations; sigma 0.2 eV unless --sigma says otherwise, announced in the run report; which columns were smeared is recorded in the checkpoint) — the same smearing the convergence ladder already used as a fallback, so nothing downstream is new. (2) The isolated-atom columns must hit the right ground spin state: the old parity fallback (spin 0, else spin 1) would have computed neutral N as an excited spin-1 doublet. The ion/atom solver now scans the parity-consistent spins (up to 8 unpaired — Gd/Cm reach 4f⁷5d¹/5f⁷6d¹) and keeps the lowest converged energy, so neutral N comes out as the Hund ⁴S spin-3 atom, neutral Al as the ²P spin-1 atom, and closed-shell ions still win at spin 0 (sub-second atomic calculations; this also upgrades genuinely open-shell ions such as high-spin d⁵, which the old path forced to spin 1). A trial whose DIIS stalls is retried with second-order SCF (plain DIIS fails on neutral Ni’s near-degenerate 3d⁹4s¹ ground state, which would otherwise silently lose to a converged excited quintet 4.8 eV up), a failed trial is skipped with a note instead of killing the run, and if an unconverged spin state still undercuts the chosen one, a warning says the shown column may be an excited spin state. With all oxidation states 0 the point-charge lattice vanishes, so the fragments are bare neutral sublattices + ghost basis, exactly the EHT model. Verified on rocksalt AlN at X: Al column 3 electrons, N column 5, both smeared, Al^+0 (UKS PBE, 3 electrons, spin 1 (alpha levels)) / N^+0 (UKS PBE, 5 electrons, spin 3 (alpha levels)), and the Al 3p Bloch combination below Al 3s — the same intra-sublattice-overlap physics the EHT pages show. Test in section 3.

  • Empty ion shells in the PySCF atomic columns are now flagged as what they are — finite-basis virtuals, not Rydberg levels. In crystod --diagram --pyscf, the isolated-ion columns showed Al⁺³ 4p below 4s (and N⁻³ 3p below 3s), inverting the physical order. The cause is the default gth-dzvp-molopt-sr basis: optimized for condensed-phase valence states, it carries no diffuse functions, so any empty level beyond the lowest empty state of its l is merely the orthogonal remainder of the contraction — a compact, node-rich function pushed up by the kinetic energy of its enforced node (the repulsive GTH s-channel projector plausibly adds to this, though the experiment did not separate the two contributions). Verified against the NIST free-ion spectrum of Al⁺³ (Na-like Al III): with the production basis 4s is +7.1 eV off (4p only +1.5 eV, hence the inversion), while re-running the identical bare-ion problem in gth-qzv2p lands 4s/4p within 0.1 eV of experiment — the pseudopotential is innocent. For anions the defect is deeper: one more electron on a free anion is unbound, so every empty anion level is a discretized continuum state with no physical counterpart at any basis size (in the crystal the Madelung potential provides the binding). Both cases are now disclosed everywhere the levels appear: the tooltip of each affected level, the page footer, and the terminal report — each including the concrete remedy --basis gth-qzv2p when the run uses a molopt-family basis (with two honest caveats: diffuse-richer bases make the periodic SCF heavier and possibly ill-conditioned, and the 0.1 eV figure is the bare-ion validation — Kohn–Sham virtuals of ions that keep electrons retain the functional’s own eV-scale attachment error, which no basis removes). The lowest empty state of each l of a cation is left unflagged — occupied semicore shells below it do not consume the slot, so Na⁺ 3s (the first empty s above the 2s²2p⁶ core, basis-converged to 0.2 eV) is trusted while Na⁺ 4s is flagged — because those are genuine electron-affinity levels (Al⁺³ 3s/3p/3d match NIST to 0.2–1.2 eV even in the production basis); a formally neutral atom, whose Coulomb tail binds no attachment states, has all its empty shells flagged. Test in section 3 (NaCl: Na⁺ virtual notes, Cl⁻ continuum notes, and the recommendation string in the page).

  • The atomic-shell columns work in the PySCF engine too — as genuine isolated-ion calculations. crystod --diagram --pyscf now runs one additional PySCF calculation per element: the isolated ion at its formal charge (the same pymatgen-guessed/--oxidation charges the fragment sublattices already use), with the same basis, pseudopotential and functional as the periodic calculations — so the page tells the user’s three-stage story explicitly: charged atom → charged sublattice (+ point-charge lattice) → crystal. Closed-shell ions (Na⁺, Cl⁻, Sc³⁺, F⁻, N³⁻ …) are solved with RKS; a cation whose formal charge empties the pseudo-valence space entirely (Al³⁺ with GTH-q3) gets the bare-ion one-electron spectrum instead (its 3s eigenvalue, −27.9 eV, reproduces Al’s third ionization potential of 28.4 eV); odd-electron ions fall back to UKS with a tooltip flag. Because the molecular (vacuum) and periodic (G = 0) energy references share no common zero — and vacuum anion levels are unbound (F⁻ 2p at +3.5 eV) — each element’s ion column is rigidly shifted so its deepest shell sits at the degeneracy-weighted, all-k mean of the fragment levels that shell dominates (the band’s center of gravity, which is the tight-binding on-site energy in an orthogonal basis); the anchor, the shift and the raw vacuum levels are all printed and repeated in the tooltips. Splitting connector lines reuse the levels’ displayed Löwdin/Mulliken shell populations. --onsite pages are unchanged (the single-Hamiltonian mode has no atomic stage). Tests in section 3 (default-mode NaCl at X: ion report, anchoring, and the Cl 3p fragment→ion link).

  • crystod --diagram gained outermost atomic-shell columns — the crystal analogue of the MolOD ligand-ao column. With more than one atom of an element per primitive cell (wurtzite AlN: two Al), the fragment sublattice column alone can look puzzling — 26 electrons on the Al side, and Al-3p Bloch combinations below Al-3s at several k points, both genuine consequences of the intra-sublattice Al–Al overlap. The diagram now shows where that splitting comes from, exactly like the H₄ column of crystod-mol: the new outermost columns hold one level per (element, shell) at the k-independent on-site energy (VSIP + spherical part of the point-charge ligand field, e.g. 2Al 3s, 2Al 3p, no occupation arrows), and every sublattice level is connected to its parent shell(s) by correlation lines weighted with the same Löwdin shell populations as its tooltip — so “Al 3p GM4 at −16.35 eV sits below Al 3s GM4 at −6.50 eV” reads directly as the bonding/antibonding fan opened by the two equivalent atoms out of the atomic 3s (−16.80) and 3p (−11.00) levels. The terminal report prints the same on-site levels per fragment (“on-site atomic levels (VSIP + ligand field, eV): …”), and the page footer explains the columns. Layout grows from three to five columns (2Al AOs | Al | crystal orbitals | N | 2N AOs); engines that do not build the AO columns (--pyscf) keep the three-column page unchanged. Tests in section 3 (ScF3: Sc AOs/3F AOs headers and 3F 2p label; rocksalt AlN at X: the Al 3s fragment level linked to its parent Al 3s on-site level).

  • Fixed: crystod --diagram deleted physical levels in dense sublattices — rocksalt AlN had no Al 3s at the X point. The extended-Hückel solver excludes Bloch combinations whose overlap eigenvalue falls below 0.2, because their variational energies diverge as (1−K)·h/ε (the overlap catastrophe of diffuse shells). In a dense sublattice, however, a single shell’s own Bloch sum can fall below that floor — the fcc Al sublattice of rocksalt AlN (twelve neighbours at 2.86 Å) puts the one Al 3s X1+ combination at eigenvalue 0.15 — and deleting it removed a whole physical level: the Al column at X had no 3s state, so the aufbau filling put three electrons into 3p. Such modes are now kept as separate levels whose energies are estimated at first order in the Löwdin orthogonalization (H̃ = H − (S−1)(h̄ᵢ+h̄ⱼ)/2, the same correction the coupling tables use; for a single Bloch sum this gives the bounded E = h(1+(K−1)σ) instead of the divergent h(K+(1−K)/ε)). Estimated energies are marked ~ in the terminal and explained in the level’s tooltip (and carry "est": 1 in the page’s level JSON); only truly linearly dependent combinations (eigenvalue < 10⁻⁶, no physical content) are still removed, reported separately. The variational levels are bit-identical to before, and in the previously validated materials (ScF3, SrTiO3, BaTiO3, ZrO2) every restored level is empty, so no occupied manifold changed. AlN now shows Al 3s X1+ at X and Al 3p GM4- at Γ with the textbook 3s²3p¹ filling at Γ, and the crystal column gains the previously missing antibonding partners — the lowest empty state at X becomes X1+, matching the X-point conduction-band symmetry of rocksalt AlN in DFT. Regression tests in section 3 (the restored Sc 4s R1+ level of ScF3, and rocksalt AlN at X: the ~ estimate plus the 13-electron aufbau count of the Al column).

v0.3.7#

  • The SALC viewer shows the k point in both bases with --conventional: --kpoint is given in the primitive reciprocal basis throughout CrystOD, and the conventional-cell display now lists both — X [0.0, 0.0, 0.5] (primitive) and X [0.5, 0.5, 0.0] (conventional) for I4/mmm La3Ni2O7 — so the shape of the commensurate display supercell (2 × 2 × 1 conventional cells at X) is evident at a glance. The conversion uses the same primitive-to-conventional matrix as the displayed cell (fcc Si X: [0,1/2,1/2] → [1,0,0]); pages without --conventional are unchanged. Tests in section 6 (the –visualize extras block).

  • The symmetry-mode decomposition table is saved as sym_mode_{formula} (e.g. sym_mode_K2SeO4) next to the VESTA files of every --supergroup-cif run, named by the parent composition. The formula follows the conventional chemical order — cations before anions, the cation on the most special Wyckoff site (letter closest to a) first, then increasing valence (SrTiO3, KNbO3, PbZrO3; La3Ni2O7 keeps La first because the site rule beats Ni’s lower valence) — computed from the structure itself (oxidation-state guesses, electronegativity fallback), so POSCAR inputs work the same as CIFs. The same formula is written into every --poscar2cif output as the IUCr _chemical_formula_sum field ("K2 Se O4"). Second non-special-k reference case added: the K2SeO4 lock-in ferroelectric Pnma → Pna2₁ (3× along a, SM = (1/3,0,0)) reproduces AMPLIMODES entry by entry — GM1+ 0.9467, polar GM4- 0.4230, SM2 1.2885, SM3 0.1727 Å, total 1.6629 Å. Tests in sections 15 and 16.

  • Fixed: the one-sentence rejection of a wrong --dim in crystod-phonon --modulation depended on the phonopy version — older phonopy raises ValueError for a supercell that does not match the force data, phonopy 4 an IndexError from the site-symmetry lookup, which escaped as a raw traceback. Both are caught now.

  • crystod-group --supergroup-cif supports order parameters at non-special k points (symmetry lines, planes and general points on the 1/24 grid). The reference case is the PbZrO3 antiferroelectric, Pm-3m → Pbam at 8× the cubic primitive cell, whose distortion condenses the Σ point (1/4,1/4,0) and the S point (1/4,1/2,1/4) on top of R/X/M modes — previously rejected with “some folding k-points are not tabulated special points”. Small irreps at such points are computed with spgrep at the exact k, named through the bundled ISO-IR tables (SM2, S4, …), and the full induced representations are built from the ISO-IR full-star matrices themselves (tabulated arm order, deterministic across spgrep versions; the spgrep-basis induction is the automatic fallback). Every AMPLIMODES reference number is reproduced — SM2 1.2871 Å → Pbam, R4+ 1.5232 Å → Imma, S4 0.4470 Å → Cmce, R5+ 0.0810 Å, X3- 0.0374 Å, M5- 0.0473 Å, total 2.0462 Å — and each mode’s isotropy subgroup is additionally verified by freezing that single mode’s displacement field and re-measuring its space group with spglib. Because the phase gauge that fixes the ISOTROPY web tables’ order-parameter axes is not part of the bundled data, the direction pattern of a line mode may differ from ISOSUBGROUP’s (a printed note says so); subgroup, dimension and amplitude are gauge-independent. Internals: the mode projectors are now assembled per k star in a Fourier-block basis (star arms × parent atoms) instead of dense displacement matrices on the invariant-core supercell — the old route would have needed ~22 GB at PbZrO3’s 4×4×4 invariant core (320 atoms), the new one runs the whole analysis in ~18 s; outputs of all previously validated cases (SrTiO3, ZrO2, CaTiO3, BaTiO3, AlF3, La3Ni2O7, SrLi2Nb2O7 ×2) are unchanged to the last printed digit. Tests in section 16, including the frozen-field re-measurement.

v0.3.6#

  • Python API: every analysis is now reachable as a Python function, grouped into one module per command — crystod.salc, crystod.group, crystod.phonon, crystod.bz, crystod.mag, crystod.md, crystod.mol — so that a part of CrystOD can be used inside another program without going through the command line (full guide: the Python API page of the documentation). The domain modules are a curated view over the implementation modules, which keep their own names: from crystod.phonon_irreps import get_irrep_labels, from crystod.operations import wigner_D_real and every other pre-0.3.6 import path works unchanged, and the command line is untouched apart from the new --subgroup mode below. Attribute access is lazy (PEP 562), so import crystod plus all seven domains costs ~0.09 s and pulls in nothing heavier than NumPy — phonopy, spgrep, spglib, PySCF and matplotlib load only when a function that needs them is actually called. New in the API layer: crystod.group.isotropy_subgroups(space_group, irrep[, order_parameter]) returns the crystod-group --supergroup table as IsotropySubgroup records (irrep, direction, space-group number/symbol, cell size, index, free-parameter count, and the conventional basis/origin in the parent convention); crystod.phonon.label_phonon_modes(phonon, qpoint) labels the modes of a live phonopy object with ISO-IR irreps (star arms mapped onto the tabulated arm automatically), returning PhononMode records with 1-based band indices; crystod.phonon.imaginary_mode_subgroups(phonon, qpoint) and scan_imaginary_modes(phonon) combine the two into the symmetry-lowering step of a structure search. Bad input raises ValueError rather than exiting: the implementation modules report errors the way a command line wants them (raise SystemExit), which would tear down a program that merely called the function — the API layer translates that at its boundary. This matters for the labels of symmetry lines and planes (DT5, LD3, …), which are legitimate mode labels with no isotropy subgroups in the tables; imaginary_mode_subgroups/scan_imaginary_modes record such a level in errors with an empty subgroups and carry on. Tested in the new testsuite section 35 (31 checks: import hygiene, backward compatibility, API-vs-CLI agreement on every order-parameter direction — including the arm grouping of multi-arm stars such as M3+(0;0;a) — the error contract, and the SrTiO3 R-point soft mode).

  • Fixed: the documentation site always displayed version 0.3.3. doc/conf.py read the version through importlib.metadata("CrystOD") and fell back to a hard-coded string, but the docs workflow installs only Sphinx and never CrystOD itself, so every published build took the fallback. The version is now read straight out of pyproject.toml when the package is not installed.

  • crystod-phonon --modulation runs from the files you already have. A unit cell plus FORCE_SETS (or FORCE_CONSTANTS with --readfc) is enough — crystod-phonon --modulation -c 221_PPOSCAR_ScF3 --qpoint 0.5 0.5 0.5 --mode 1 2 3 --amplitude 0.3 produces the byte-identical structure that the --yaml phonopy_params.yaml form does, so no phonopy yaml has to be generated first. The supercell of the force calculation is read from phonopy_disp.yaml when present and otherwise inferred from the atom count of the force file (respecting the axis equivalence of the lattice: a cell with |a| = |b| never gets unequal multipliers); which route was taken is printed, and --dim overrides it. A supercell that does not match the force data now aborts with one sentence instead of a phonopy traceback. --yaml still works and still wins when both are given. Fixed in the same pass: --tolerance/--symprec reached the symmetry-adapted mode construction but never the space group reported for the generated structure, which was hard-coded at 0.1 Å — a tolerance comparable to the modulation amplitude itself, so the printed label depended on the absolute amplitude scale (--mode 1 2 3 --amplitude 0.3 0.15 0.075, the direction (a,b,c), printed C2/c instead of P-1). One --tolerance now sets both.

  • crystod-phonon --subgroup --modulate: the distorted structure of every enumerated order-parameter direction, generated in the same run — one POSCAR per direction plus the --modulation command that reproduces it, so the candidate structures of a structure search come straight out of the instability analysis (cubic SrTiO3 R5-: six structures, I4/mcm, R-3c, Imma, C2/m, C2/c, P-1). Which combination of the degenerate modes realizes which direction is not fixed by any convention CrystOD could assume, so it is measured rather than assumed: candidate combinations are generated, the space group, primitive-cell multiplication and index of each generated structure are determined with spglib, and the triple is matched against the enumerated table — a direction no candidate reproduces is reported as not generated instead of guessed at. When two directions of one irrep share that triple — R5+ of Pm-3m puts both (0,a,b) and (a,a,b) at C2/m, size 2, index 24 — the conventional cell metric separates them, so a domain of one is never written under the other’s name, and the pattern of zero and equal components decides which label a structure takes; every enumerated row ends up either as a file or as an explicit note. Multi-arm stars go through the multi-q form of --modulation automatically (M3+ of a perovskite: one arm for (0;0;a), two for (0;a;a), three for (a;a;a)). --amplitude scales the set (default 0.3 Å). Tests in section 27, including an independent re-measurement of every written structure and an execution of every printed reproduce command.

  • crystod-group --parent is accepted as an alias of --supergroup: the flag names the parent group but returns its subgroups, which reads backwards, so the option is now also available under the name of the value it takes. Both spellings produce byte-identical output.

  • crystod-phonon --subgroup: the command-line form of the same analysis — every imaginary phonon level is labeled with its irrep and each order-parameter direction resolved to the space group it condenses into (cubic SrTiO3, R5- triplet: I4/mcm, R-3c, Imma, C2/m, C2/c, P-1), scanning every q point commensurate with the supercell when no --qpoint is given. --threshold sets what counts as imaginary (default -0.1 THz); --yaml phonopy_params.yaml replaces --dim/-c. Freezing in a single eigenvector explores only one direction of a degenerate level, so this is the enumeration a structure search needs before it can claim a ground state. Tests in section 27.

v0.3.5#

  • All irreducible-representation tables unified on the bundled ISO-IR data; the irreptables and irrep package dependencies are removed. Every table lookup — crystal orbitals, hybridization, SALC/basis functions, phonon irreps/vibrations/modulations, spin bases, direct products, isotropy subgroups, little-group character tables, and special-k listings — now reads the ISO-IR dataset shipped in the package (crystod/CIR_data.txt.gz; ISOTROPY Software Suite: H. T. Stokes, B. J. Campbell and R. Cordes, Acta Cryst. A69, 388-395 (2013)). Labels follow the ISO-IR (ISOTROPY, Miller-Love) convention uniformly at special points and on symmetry lines/planes; at the maximal k points they coincide with the previously used Bilbao-convention labels for all 230 space groups (verified programmatically: operator sets, representative star arms, characters, and label strings all agree). Line terms formerly named from a DIRPRO-fitted map follow ISO-IR now (S of the P6₃/mmc family → Q, T → LD, V of I4/mmm → LD; the DT numbering of Fm-3m/Ia-3d is permuted). The non-self-conjugate P/N/W points of the centred nonsymmorphic groups (P of I-4̄2d/Ia-3̄d, N of I4₁32, W of Fd-3̄m, …) are resolved by one exact rule — complex conjugation combined with the wrapped-lattice translation phase — replacing the previous per-case gauge fixes and fitted-name substitutions (chirality-sensitive results such as I4₁32 N1 → P4₁22 are reproduced). The provenance notes (“absent from the … tables”, “[…; ISO-IR labels]”) are gone from the outputs since there is only one convention now. Verified by the full testsuite (639 checks) and by a feature-by-feature side-by-side comparison against the previous pipeline (61 command runs: no physical differences — decompositions, frequencies, subgroup tables, and exported files agree).

  • License changed to MIT (possible now that the GPL table packages are no longer used).

  • Rare-earth support: archived neutral-atom reference levels (reference/atomic_level_*) added for Y and La–Lu (def2-SVP for Y/La, Stuttgart RSC 1997 / ECP28MWB for Ce–Yb, CRENBL for Lu — the 4f shell stays in the valence space), and extended-Hückel parameters for La, Ce, Sm, Gd, Yb, Lu (YAeHMOP tables) together with new f-orbital STO overlaps (σ/π/δ/φ channels, validated against independent grid integration). crystod --diagram now works for e.g. CeO₂, with the 4f crystal-field splitting labeled (GM4⁻/GM5⁻/GM2⁻ at Γ of Fm-3̄m).

  • crystod --visualize without --kpoint now visualizes the SALCs at every special k point of the space group (one HTML per point, SALC_{POSCAR}_{element}_{orbital}_{kpoint}.html), mirroring the --diagram behaviour.

  • The citation notice is printed at the end of every subcommand’s --help.

  • Documentation front page gained an interactive “molecule → crystal” band-formation demo and embedded MO/crystal-orbital diagrams.

  • Cd parameterized for every extended-Hückel mode (--diagram, the new levels viewer, crystod-mol): the YAeHMOP table entry (5s −11.80 eV / ζ 1.640, 5p −8.20 eV / ζ 1.600; the filled 4d¹⁰ stays inactive there, exactly as for Zn — it enters the full-electron basis as a semicore shell instead) plus the archived neutral-atom reference calculation (reference/atomic_level_Cd, RHF/def2-svp + def2 ECP-28 — def2-svp does cover Cd; the 4d sits at −19.6 eV). CdF₂ at Γ comes out textbook: the ligand-field-split Cd 4d¹⁰ semicore (6e + 4e), the F 2p valence band, and the Cd 5s conduction level as the LUMO. script/collect_atomic_levels.py now takes element arguments (… Cd) to regenerate ONLY those entries — a full re-collection re-runs every archived atom and can trip the 1e-4 hartree cross-check on unrelated elements when the BLAS environment differs from the original archive’s.

  • Extended-Hückel eigen-levels in the SALC viewer (bare crystod --visualize -c POSCAR, crystod/visualize_eht.py): the extended-Hückel counterpart of --visualize --pyscf — without --element/--orbital the viewer now shows the eigen-levels of the --diagram engine instead of the SALC basis: one page per special k point, Mode | Irrep | Comp. | Energy (eV) rows for every level inside the energy window (HOMO−15 .. LUMO+10 eV by default; --window opens the deep shells), the clicked row rendering the eigenvector’s wave function with lobe sizes calibrated to the Löwdin populations (per-channel best probe radius among 1.5/2.0/2.5/3.0 bohr, so semicore orthogonalization nodes don’t flip drawn signs — same recipe as the PySCF viewer). No SCF and no options required: STO basis, atomic levels and point charges are tabulated (ScF₃’s four k-point pages appear in seconds, levels identical to the --diagram crystal column). --sublattice Sc shows the pre-bonding sublattice block of the shared Hamiltonian instead of the crystal — all views on ONE energy reference by construction. --kpoint/--window/--diagonalize/--valence-only/--bond/--conventional/--electrons/--oxidation work as in the PySCF version (--real-coefficient is accepted but inert on the level pages — the degenerate partners are always realified and the drawn field is Re[ψ], which the sidebar now states honestly on the PySCF pages too); PySCF-only flags (--chk, --basis, --kmesh, …) are rejected with a pointer to --visualize --pyscf, and --element without --orbital still directs to the basis viewer. Tests in section 5.

  • Fixed: a missing structure file crashed with an AttributeError traceback ('NoneType' object has no attribute 'totuple') in most modes — phonopy’s read_crystal_structure returns None instead of raising. Every POSCAR-reading entry point (--diagram both engines, --dos, --band, --visualize --pyscf, the SALC analysis, --product hybridization, crystod-phonon --qpoint) now goes through the shared read_poscar_or_exit helper (previously only the SALC viewer/BZ/star-of-k/mag paths used it) and prints ERROR: No POSCAR named 225_PPOSCAR_ZrO2! — the unified message across all modes.

  • --diagram --conventional: conventional-cell orbital sketches (both engines): the Level-details hover sketch draws the wave function on the primitive k-commensurate supercell by default — at Γ of an fcc crystal that is the 3-atom rhombohedral primitive cell, hard to relate to the textbook conventional picture. --conventional (same flag as the SALC viewer) wraps every atom into the conventional cell of the detected centring (times the diagonal multiples that keep the Bloch phase exactly commensurate: ZrO₂ Fm-3m draws the full 12-atom fluorite cube at Γ and X, 2×1×1 cubes at W, 2×2×2 at L), each atom carrying the exact phase of its own primitive-lattice translation — verified against exp(2πi k_conv·r) sign patterns at X for both engines. The sketch caption names the displayed cell (orbital sketch (conventional cell (F centring), 1 x 1 x 1)), the page footer says which cell the sketches use, and the flag is display-only: the diagram, the populations and any --chk are untouched (a checkpoint written without it is reused as-is). Default-mode pages are unchanged apart from the new caption (the rewritten supercell enumeration was verified bit-identical). --visualize --pyscf gained the same flag (it was silently dropped there before — the PySCF SALC-viewer pages now honor --conventional like the classic viewer always did). Adversarial review fixes in passing: the primitive→conventional matrix was transposed for non-symmetric centrings — phonopy’s M acts on column-vector lattices, so the row matrix is inv(M)ᵀ, not inv(M); the two coincide for P/F/I (why every cubic example was right) but R-centred structures drew an oblique det-3 supercell instead of the hexagonal cell, and A/C got axis-swapped cells — a pre-existing bug shared by the SALC viewer’s --conventional, crystod-phonon --vector --conventional and crystod-mag’s display cell, all fixed at the source (GeTe R3m now frames the true 4.23/4.23/10.89 Å γ=120° hexagonal cell); --dos now rejects being combined with --diagram/--visualize (it silently swallowed them and their flags); the --bond/--conventional guards run before every mode branch (--star-of-k --conventional used to be silently ignored). Regression tests: the conventional NaCl frame must be the cubic cell (orthogonal, equal edges) and the Na 2s Bloch signs at X must follow exp(2πi k_conv·r); the NH3 1e/2e sketch-phase check was rewritten to the gauge-invariant bond-directed product Σ_H s_H (p_N·r_NH) — the old max-|s| pick broke on the mirror-hydrogen tie whenever the degenerate-partner canonicalization landed on the other gauge (a BLAS-environment effect, the sketches themselves were correct).

  • Added two-fragment extended-Hückel MO diagrams (crystod-mol --diagram --xyz FILE.xyz --ao-left FORMULA --ao-right FORMULA, no --pyscf): the molecule is split into two arbitrary submolecules by chemical formula (benzene H6/C6, CH3OH H4/CO, O2 O/O) and drawn as the three-column diagram (left fragment MOs | molecule MOs | right fragment MOs) with the same symmetry + overlap machinery as the single-center mode — all three columns solved in the one molecular AO space (the fragment’s (H, S) sub-block is the isolated fragment in extended Hückel), molecular MOs projected onto the fragment MOs through the shared overlap matrix, COOP bonding colors, VESTA fragment-line colors, orbital sketches, and irrep labels assigned from the MO characters after solving with core shells counted in the numbering (benzene: (2a1g)^2 … (1e1g)^4 with the Hückel π ladder 1a2u < 1e1g < 1e2u < 1b1g, label-compatible with --pyscf). A fragment keeping a higher symmetry than the molecule (the exactly degenerate CO π pair of CH3OH under Cs) is decomposed with the irrep projectors; non-invariant fragments and linear molecules fall back to unlabeled levels. Tests in section 33.

  • Fixed (2026-08-01/02): the --pyscf MolOD orbital sketches drew CORE levels from their valence orthogonalization tails — the r0 = 2 bohr radial weighting of the 2026-07-28 phase fix, taken alone, kills the contracted 1s functions (dead at r0), so e.g. the C 1s combinations of benzene’s C6 fragment rendered as 2p-like lobes. Each (atom, l) sketch channel is now rescaled to its Löwdin population (signs/orientation still from the r0 amplitudes; the same two-step recipe as the crystal engine’s sketches), the r0 amplitudes gained the missing per-primitive gto_norm normalization (verified to reproduce eval_gto to 8 digits; without it the per-shell weights were off by 0.28–7.7× and could flip a channel’s relative sign), and non-degenerate levels get a deterministic dominant-lobe-positive phase. Core levels are drawn as the pure s spheres they are (Löwdin p admixture of the benzene C-1s a1g state: 0.22%, honestly drawn at √0.002 ≈ 4% of the s lobes); the NH3 1e/2e phase regression test still passes and the example diagrams were regenerated. — the --chk restart files are binary (compressed npz, for size and load speed), so the calculation conditions they lock in were invisible until a parameter-mismatch error spelled one of them out. --chk-info prints everything the file stores — structure, method (XC/basis/pseudo/ke_cutoff/k-mesh/max_l/smearing), electron count and oxidation states, fragment split, which densities it holds (full three-SCF run vs an --onsite crystal-only checkpoint) on how many k points × AOs, the SCF energies — plus a ready-to-paste reuse with: --co-left … --kmesh … --chk FILE option string that reproduces the stored conditions exactly (with --onsite appended automatically for crystal-only files). The parameter-mismatch error now points to it.

  • crystod --band --pyscf: electronic band structure and fatbands from the recorded density matrix (crystod/band_pyscf.py): the whole-band-structure companion to --dos — read the full dispersion first, then zoom into the special k points with the crystal-orbital diagram. VASP-style two-step: the SCF (or a --chk restart, including the crystal-only checkpoints of --onsite runs via --onsite) provides the density matrix, get_bands diagonalizes it non-self-consistently along the automatic seekpath high-symmetry path (--band-points per leg, default 41); E_F/VBM/CBM come from a zero-temperature filling of the uniform SCF mesh (metal-safe), plots are VBM-referenced (--align absolute to disable) and the terminal names the band-edge k points (ScF3: VBM at R, CBM at Γ, gap 5.199 eV — matching the --dos mesh gap exactly). --fatband adds the same per-AO projections the DOS and the diagram compositions use (--projection Löwdin default): one overview page with every element in its VESTA color, plus one page per element with the s/p/d/f breakdown (total | s | p | d panels, weights as dot sizes). Outputs: BAND_<structure>.pdf (+ _fatband.pdf, _fatband_<El>.pdf), a long-format CSV of every band energy (and every (element, l) weight), and a TXT summary. The chk parameter guard applies as usual — a --max-l 2 checkpoint needs --max-l 2 here too, and the mismatch message names the offending option.

  • Fragment-column levels show their composition too (--diagram, both engines): a repeated fragment label (F 2p GM4-#1/#2, or a fragment-SCF eigenstate whose label only names its dominant shell) used to be opaque — the Level-details bars and hover tooltip now show every fragment/onsite level’s per-shell AO populations in the same --projection measure as the crystal levels, listing the level’s own sublattice shells only: a fragment level is a sublattice state, and per-shell entries of the other element read as contamination (user feedback on SrTiO3 — “O states inside a Ti-only level”). The weight that does sit beyond the own shells — the counterpoise ghost tail in the fragment-SCF mode, and in every mode the Löwdin attribution of the overlap density (the state’s coefficients stay on its own side) — is aggregated into one closing note, e.g. Loewdin: O 2p 78.1%, O 3p 16.7% (+5.2% on the removed sublattice's basis: ghost tail + Loewdin attribution). The full cross-side breakdown of an early draft of this display is what exposed the --onsite block pathology below (a “Ti 3d GM3+” whose bars read Ti 3d 39.5 / Ti 4d 27.6 / O 2s+3s 28%).

  • --onsite: the single-Hamiltonian crystal-orbital diagram (--diagram --pyscf): the default mode draws each fragment column from its own SCF (formal-charge ions + point charges + ghosts), so a crystal level’s vertical offset against its parent mixes the bonding shift with a site-dependent environment error that no rigid alignment can remove — quantified on SrTiO3 at R with the on-site decomposition d = ⟨φ_frag|F_crystal|φ_frag⟩: the chemically inert Sr 4s column sat 1.59 eV too deep (pure reference error, zero bonding), making the weakly bonding Sr 4p crystal level (P=+0.031, true bonding shift −0.06 eV) appear risen by +1.5 eV — a bonding state that looked antibonding. --onsite removes the problem structurally: only the crystal SCF runs, and the fragment columns are the per-(element, shell) on-site multiplets of its converged Fock — F(k) diagonalized within each shell’s own symmetry-adapted Bloch orbitals (the tight-binding on-site energies ⟨φ|F|φ⟩; one level per induced irrep, matching the site-symmetry table exactly; no cross-shell mixing). Whole-sublattice blocks were tried and rejected on user scrutiny: with this diffuse basis the raw AO block lets cation functions fall variationally into the removed side’s potential wells (a “Ti 3d GM3+” at O-2p depth with 28% Löwdin weight on O — a disguised anion state, the ghost/BSSE pathology in new clothes), while Löwdin- or projection-orthogonalized blocks load strongly-overlapped shells with huge orthogonalization penalties (the O 2s on-site swung −6.9 → +0.5 → +12.6 eV across the three block conventions; compact shells agreed throughout) — the per-shell Rayleigh quotient has no variational freedom to abuse, and it is the d = ⟨φ|F_crystal|φ⟩ reference of the decomposition analysis above, so the parent→crystal offset is the orbital interaction by construction. (The extended-Hückel engine’s whole-side block stays safe because its minimal STO basis offers no diffuse escape routes.) One operator for every column means no fragment SCF, no point charges, no reference alignment: on SrTiO3 at R the Sr 4p parent (−5.44) now sits above its weakly bonding crystal level (−5.54), the inert Ti 3s column coincides with its crystal counterpart to 0.2 eV, the O 2s band’s genuine +0.43 eV closed-shell push-up by the Ti 3p semicore below it (upper member of a filled–filled pair; its COOP stays bonding-positive through the valence-channel donation into the empty Ti 4p — energy shift and overlap population are different observables) is displayed honestly instead of being masked by the alignment, and on ScF3 at R the diagram finally reads like the textbook: bonding R3+ below its F 2p parent, the antibonding t2g LUMO above its Sc 3d parent (t2g 3.82 / eg 4.01 bare splitting — the large crystal eg–t2g gap emerges from the hybridization, not the bare ligand field). A full-run --chk is reused (only the crystal density is read; --no-ghost differences are ignored there, being numerically inert); an --onsite-written chk holds only the crystal density and a full-mode run against it aborts with a clear message. crystod --dos --pyscf accepts --onsite too — the DOS never needs the fragment densities, so it runs on a single SCF and on the crystal-only chk files. Column occupations remain the formal ionic counts (a display convention, stated in the page footer). Also fixed in passing: the PySCF diagram pages carried the extended-Hückel footer (“VSIP … Wolfsberg-Helmholz”) and a “(full-electron basis)” chip — each engine now writes its own footer/chips.

  • One displayed composition per crystal level — the PySCF AO populations everywhere (--diagram, extended-Hückel and --pyscf): the Level-details bars used to quote the Löwdin fragment-level projection (“Sc 3d R5+ — 69.7%”) while the hover tooltip quoted the per-(element, shell) AO populations (“Loewdin: Sc 3d 76.0%”) — two genuinely different measures of the same state shown side by side with no way to tell which to trust (the fragment eigenstate “Sc 3d R5+” itself mixes 3d and 4d AO character, so the numbers must disagree — Sc 4d read 19.3% vs 8.9% on the ScF3 t2g LUMO). The panel bars, the tooltip and the terminal now all quote one identical list: the per-(element, shell) AO populations of the PySCF eigenvector in the --projection measure (Löwdin default — non-negative, summing to exactly 100%), i.e. the same partial-charge machinery as crystod --dos --pyscf, with symmetry doing the orbital selection (a state of irrep Γ only picks up the Γ-adapted combination of each shell; forbidden shells project to ~0) — every entry is labeled with the crystal irrep (Sc 3d R5+ 76.0%  F 2p R5+ 9.5%  Sc 4d R5+ 8.9%  F 3p R5+ 5.7%). The extended-Hückel --diagram gets the same treatment (Löwdin over the Bloch-STO overlaps), so both engines read identically. The fragment projection is demoted to an internal quantity — it still positions the correlation lines and feeds the deep-level alignment anchors (bit-identical before/after), but its weights are no longer displayed as percentages. Verified panel==tooltip==terminal over every crystal level of ScF3 (140 PySCF levels × Löwdin and Mulliken, 81 EHT levels) and SrTiO3 (87 EHT levels).

  • Testsuite section 3 caught up with the whole --diagram series (an adversarial review found every regression): the two test commands dropped the removed --atomic-orbital flag, the terminal regexes follow the #N labels and one-decimal percentages, the multi-shell sketch probe parses the current VARIANTS JSON (its physics assertions — bonding Sc 3p lobe in phase with F 2s at X, antibonding opposite — pass unchanged), the “sketches not embedded” expectations flipped to always-embedded, and the --diagram requires---co-left/--co-right error message no longer advertises the removed --atomic-orbital option. 41/41 pass.

  • crystod --dos --pyscf: DOS/PDOS and partial charges from the recorded density matrix (crystod/dos_pyscf.py): the --chk file already stores the converged density matrices — everything the band step needs — so crystod --dos --pyscf -c POSCAR --chk FILE [--dos-kmesh 8 8 8] diagonalizes them non-self-consistently on a dense mesh (VASP-style two-step; ~40 s for ScF3 on 8×8×8 with zero new SCF) and writes, in the calc_pyscf_dos.py style: a Gaussian-broadened total DOS + element×angular PDOS plot (VESTA colors, PDF), a CSV of every curve, and a text summary with the gap (VBM/CBM/E_F from zero-temperature filling of the whole mesh, metal-safe). Partial charges are reported in both conventions side by side — with the diffuse molopt basis they disagree spectacularly (ScF3: Löwdin Sc +0.004 because the diffuse Sc 5s/4d claim the density sitting on the F sites, vs Mulliken Sc +1.57/F −0.52 with the semicore 3s²3p⁶ intact and the covalent d occupation 1.06) — an atomic partition of a continuous density is a convention, and both sums reproduce the electron count to 32.0000 as a built-in sanity check. Unlike the diagram’s composition lists, the PDOS weights live directly in the AO basis (no fragment-state projection), so the fragment double-counting issue cannot occur; --projection lowdin|mulliken picks the PDOS measure.

  • Löwdin-orthogonalized composition lists (--diagram, both engines): the composition panel used to show renormalized plain projections |⟨φ_fragment|S|ψ⟩|² — but the fragment eigenstates of the two columns are mutually non-orthogonal (⟨Sc 4p|S|F 2s⟩ = 0.69 in ScF3), so the projections double-count shared density: the occupied F 2s R4- band state summed to 144% before renormalization and displayed as “Sc 4p 34%”, diffuse virtuals (F 3s at +48 eV) appeared at 9% inside the semicore bands, and the t2g LUMO showed a spurious “F 3d 0.9%”. The compositions are now computed in the Löwdin-orthogonalized fragment-level basis (weights |G^{−1/2}Φ†Sψ|², G = Φ†SΦ — the orthonormal set closest to the original fragment states, so the labels keep their meaning; the weights sum to the span completeness ≤ 100%): the same states become F 2s 76.5 / Sc 4p 15.8 / Sc 3p 7.5, Sc 3p 87.6 with F 3s down to 3.4, and Sc 3d 99.8 with the F 3d admixture gone. The deep-level alignment anchors intentionally keep the raw projections (their purity criteria were validated on them; anchors and shifts are bit-identical before/after). Note the composition percentages are CrystOD’s decomposition of the PySCF eigenvectors, not a PySCF charge analysis — the per-(element, shell) Löwdin/Mulliken row in the tooltip is the population-style companion number.

  • Resonance-based semicore rule in the bonding-character classifier (--diagram, both engines): one filled semicore shell acts in two distinct ways, and the classifier now distinguishes them per level. Resonant filled–filled pairing (Sc 3p × F 2s of ScF3, 6 eV apart) is genuine He₂-like closed-shell physics — its occupied partners now show as the bonding/antibonding pair they are (R4-/X3- #1 blue with P ≈ +0.05, #2 red with P ≈ −0.03..−0.05). Far off-resonant orthogonality tails of the same shell (Sc 3p inside the F 2p band, 23 eV above) are excluded — previously they flipped the sign of donation-bonding states: the occupied M3- of ScF3 at −4.18 eV read “antibonding −0.045” although its Sc 4p × F 2p channel is bonding +0.058, because the 1.5% Sc 3p tail contributed −0.102 (and Sc 3p escaped the old per-fragment-HOMO semicore flag, being the HOMO of Sc³⁺ itself). Semicore shells are now flagged against the crystal VBM using reference-consistent Hamiltonian expectations ⟨φ|F|φ⟩, and excluded from a level’s P only when the level lies more than 10 eV from that shell’s band top. ScF3 outcome: M3- #2 → bonding +0.059, GM4- #2 sharpens from +0.013 to +0.111, R1+ #2 → +0.112, symmetry-nonbonding states stay exactly 0, and the R4-/X3- closed-shell pairs keep their textbook blue/red split. The molecular engines keep the legacy per-fragment-HOMO rule (adequate there; the pathology needs a highly charged cation whose fragment HOMO is the semicore).

  • Löwdin-corrected coupling table (--diagram --pyscf): the fragment levels of the two columns are not mutually orthogonal, so the bare matrix element ⟨φ_L|F(k)|φ_R⟩ carries an unphysical overlap-times-mean-energy part |S|·(e_L+e_R)/2 — a compact semicore level against a diffuse virtual showed |H| of 5–15 eV without any real resonance (Sc 3s × F 2p read 12.5 eV, Sc 4p × F 2s 14.7 eV). The reported strength is now the first-order Löwdin-orthogonalized coupling |H̃| = |⟨φ_L|F|φ_R⟩ − S·(e_L+e_R)/2| with e_X = ⟨φ_X|F|φ_X⟩ (invariant under the G=0 reference), and _coupling.txt gains |S| and |H|raw columns so the overlap contamination is visible (ScF3 R point: Sc 3p × F 2s 4.3 → 1.7 eV, Sc 3s × F 2p 12.5 → 5.7, Sc 4p × F 2s 14.7 → 7.1). Couplings against the very diffuse F 3s/3p/3d fragment virtuals legitimately stay at the eV scale — a state with ⟨r⟩ ≳ 1.1 Å (plus its counterpoise ghost tail) has large Fock elements with everything; the physically suppressing factor is ΔE, i.e. the mix column the table is sorted by. Reminder that ⟨i|H|j⟩ itself does not vanish for large ΔE — the mixing |H|/ΔE and the 2nd-order energy |H|²/ΔE do.

  • Bonding-character colors in every diagram + VESTA element colors for the fragment columns: the COOP classification below now runs in all four diagram commands — crystod --diagram (extended-Hückel and --pyscf) and crystod-mol --diagram (both engines), through one shared classifier (crystal_orbital_diagram.assign_bond_characters); NH₃ verifies the molecular case (σ bonding blue, σ* red, the N 1s core black, valence MOs carrying the “(semicore N 1s excluded)” note). The fragment/sublattice columns are no longer occupied-blue/empty-gray: every fragment level is drawn in the VESTA color of its dominant element (Sc levels purple, F levels light blue-violet, Sr/Ti/O each their own), so a composite sublattice like SrTi reads at a glance; occupation stays visible through the electron arrows.

  • Bonding-character colors in the crystal-orbital diagram (--diagram --pyscf): crystal-orbital lines are now colored blue = bonding / black = nonbonding / red = antibonding, classified by the COOP-style left–right overlap population P = 2 Re[c_L† S_LR c_R] of each eigenstate (P > 0: charge accumulates between the sublattices; P < 0: internuclear node; exactly 0 for symmetry-nonbonding states such as the GM5- of ScF3 — the value is shown in every level’s tooltip, and the footer carries the legend). Two rejected alternatives, for the record: a plain energy comparison with the parent fragment levels fails because point-charge-vs-crystal environment shifts (~0.5 eV) drown the ionic splittings, and an (F − E·S) energy partition is unusable in this non-orthogonal basis (diffuse-shell Mulliken cross terms dominate — the ScF3 σ level came out “antibonding +2.45 eV”). Semicore orthogonality tails are excluded from P (shells whose own bands lie ≥ 10 eV below their fragment column’s HOMO, unless the level is that semicore band): with the Sc 3s tail included the bonding σ R1+ of ScF3 reads P = −0.015, without it P = +0.112 — the same semicore-node story as the sketches, now in the classification. Note the generic COOP asymmetry: |P| of antibonding partners is systematically larger than of their bonding counterparts (0.5–6 vs 0.01–0.2 here).

  • PySCF eigen-levels in the SALC viewer (crystod --visualize --pyscf): the SALC viewer shows the symmetry-adapted basis — the states before any Hamiltonian; it can now show the actual PySCF eigenstates in the same interactive page. crystod --visualize --pyscf -c POSCAR [--sublattice Sc|F3] --bond Sc F 3 --real-coefficient: without --sublattice the full crystal’s levels (the states after bonding), with it one fragment sublattice’s pre-bonding levels (formal-charge ions + ghost basis + point-charge Madelung field — exactly the --diagram --pyscf columns). The SALC-basis table becomes Mode | Irrep | Comp. | Energy (eV) — one row per degenerate partner, labels in the diagram convention (GM4- #2, Sc 3d R3+), energies on the shared deep-level-aligned scale so the Sc page, the F3 page and the crystal page are directly comparable — and clicking a row renders the eigenvector’s wave function (every element, all shells s..f, population-calibrated lobe sizes with a per-level shared normalization) on the k-commensurate display cell with the usual bonds/polyhedra. The special k points are enumerated automatically from the space group (one page per k; --kpoint GM restricts). All --diagram --pyscf options apply (--basis/--xc/--kmesh/--ke-cutoff/--max-l/--projection/--no-align/...), including --chk: the three ScF3 commands above share one SCF through one checkpoint file (~5 s per page set after the first run). --window LO HI overrides the default energy window (HOMO−15 .. LUMO+10 eV of the displayed column), which keeps the page sizes manageable. --diagonalize canonicalizes degenerate partners (RREF): the SCF’s arbitrary unitary mixture — which draws e.g. a tilted d_z² — becomes axis-aligned components (the R5+ t2g triplet of ScF3 turns into pure d_xy/d_yz/d_xz) with unchanged energies; each channel’s drawn sign is probed at the 1.5–3 bohr radius where its amplitude is largest, so a semicore orthogonalization node at one radius cannot flip it (note that a valence σ level can faithfully look “antibonding” near a semicore-carrying atom — the ScF3 R1+ case carries the real orthogonality node against the −50 eV Sc 3s band, verified against real-space pbc_eval_gto). --valence-only drops such semicore shells (⟨r⟩(Sc 3s) = 0.77 Å vs the 2.03 Å bond; auto-detected as occupied fragment bands > 12 eV below the crystal VBM and printed — Sc 3s/3p and F 2s here) from the drawn wave functions, so the σ level shows its bonding Sc 4s component; levels a semicore shell dominates (the semicore bands themselves) keep it.

  • VESTA-style periodic boundary in the orbital sketches (--diagram, extended-Hückel and --pyscf): the hover wave-function sketch used to draw only the bare atom list of the k-commensurate supercell; it now draws the crystal the way VESTA does — atoms on the supercell boundary appear at every translationally equivalent position (a corner atom at all eight corners, an edge atom on all parallel edges), each carrying the wave function, and the supercell outline is drawn as a dashed frame. The boundary images carry identical lobes by construction: within the k-commensurate supercell the Bloch function is exactly periodic (e^{ik·T_super} = 1), which is precisely why that supercell is the drawing unit — at R the frame is the 2×2×2 cell and the sign alternation between primitive cells stays visible inside it. Bonds across the boundary now appear too. Molecular (crystod-mol) sketches are unchanged.

  • Extended-Hückel --diagram fragment columns now number repeated (element, shell, irrep) labels — e.g. the two F 2p GM4- combinations of ScF3 at GM become F 2p GM4-#1/F 2p GM4-#2 in the terminal, the HTML, and the crystal composition lists — the same convention --diagram --pyscf already used.

  • --chk (WAVECAR-style restart), --projection, saved coupling tables, #N crystal labels (--diagram --pyscf): --chk FILE writes the three converged density matrices (all the band step needs) plus the defining parameters after the SCFs, and a rerun with the file present skips all three SCFs entirely — the parameters (basis, functional, k-mesh, cutoff, fragments, structure, …) are verified first and a mismatch aborts with the offending names. --projection lowdin|mulliken selects the population measure used for the sketch lobe sizes and the per-(element, shell) rows (default: Löwdin; mulliken restores Mulliken gross populations — note the two disagree strongly on diffuse empty levels, where atomic attribution is inherently convention-dependent). The full same-irrep resonance-integral tables <φ_left|F(k)|φ_right> (all pairs with |H|, ΔE, and the two-level mixing fraction, per k point, on the aligned scale) are now written to <output-stem>_coupling.txt next to the HTML — the terminal keeps showing the top 8. Crystal-column levels are labeled GM4- #2 (second GM4- multiplet from the bottom, the same #N convention as the fragment columns) instead of GM4-(2), which read like a degeneracy count; the extended-Hückel --diagram uses the same format now.

  • Population-true sketch lobes and a Löwdin row in the Level details (--diagram --pyscf): a crystal GM4- level of ScF3 (--max-l 2) drew a p lobe on the Sc site at 83% of the largest F lobe while its composition list read as pure F — misleading in opposite directions, because the state genuinely carries ~8% Sc p weight (mostly diffuse 4p + semicore 3p: the symmetry-allowed T1u ligand-to-metal donation; every basis function is atom-centred, so nothing sits in the interstitial voids). (i) The sketch used to scale lobes by the wave-function amplitude at r0 = 2 bohr, where the diffuse gth-dzvp Sc 4p is 5.4x an F 2p — a 2–3x exaggeration over any population measure; lobe sizes now follow the per-(atom, l) Löwdin population — |coefficient|² in the symmetrically orthogonalized basis, the orthonormal set closest to the atomic orbitals, i.e. the intuitive “squared LCAO weight” made rigorous for a non-orthogonal basis (non-negative and summing to 100%, where Mulliken’s overlap cross terms go negative or overshoot on diffuse empty levels) — with signs and orientation still taken from the r0 amplitudes so semicore orthogonalization tails keep their inverted phases. (ii) The composition list projects onto the surviving fragment levels only — under --max-l 2 the empty Sc 4p GM4- fragment level is removed by the ghost filter, its 4.5% absolute projection silently vanished and the renormalization inflated the F entries to 92.3%; every crystal level’s detail tooltip and terminal row now add the full per-(element, shell) Löwdin populations and state the fragment-projection coverage whenever it falls below 98%.

  • Exact degeneracies via Fock group-averaging; --max-l (--diagram --pyscf): the PySCF SCF carries no point-group constraint, so the FFT grid breaks degeneracies numerically — negligibly for semilocal functionals (<1 meV for PBE/ScF3), but by 0.4–0.8 eV for grid-evaluated exact exchange (B3LYP at ke_cutoff 80), which tore a GM5- triplet into a doublet plus an unlabeled level. The displayed levels are now re-diagonalized from the group-averaged Fock F̄ = (1/|G|) Σ_g D(g)† F D(g) built with the verified AO representation, so every degeneracy is exact by construction; the raw symmetry-breaking magnitude is printed per k point (--no-symmetrize shows the raw spectrum), and a NOTE recommends ke_cutoff ≥ 150 for hybrid energetics. The new --max-l L drops basis shells above l = L (e.g. --max-l 2 removes the f polarization functions, whose tails otherwise show up as small Sc-4f/Ti-4f weights in the O-2p/F-2p valence compositions — a basis-decomposition effect absent from VASP’s atomic-sphere projections).

  • Ghost-aware fragment sketches and --no-ghost (--diagram --pyscf): a fragment level can legitimately carry weight on the ghost basis of the removed sublattice (symmetry-allowed variational tail toward the point charges, the counterpoise design), but the sketch drew that as an atom-centred orbital on the empty site — and the coefficient-based drawing exaggerated diffuse ghost functions far beyond their density share (an F 2p R1+ level with 10% Mulliken ghost weight drew its peak on the empty Sc site). Fragment sketches now draw only the fragment’s own sublattice components, the ghost weight of every level is printed in the terminal report and shown in the Level-details panel, and the new --no-ghost option applies the hard constraint instead: the removed sublattice’s basis functions are excluded from the fragment variational space entirely (measured BSSE on ScF3: ~2 mHa per fragment), with the small-basis fragment states zero-padded back into the shared AO space for the projections.

  • Frontier-centered default view, always-on wave-function sketches, faster --pyscf (crystal-orbital diagrams): the interactive energy window now opens on ±8 eV around the HOMO/LUMO midpoint (the VBM/CBM region) instead of a fixed −20..10 eV; --diagram no longer takes --atomic-orbital — every level (extended-Hückel and --pyscf) embeds the hover wave-function sketch of all its atomic-orbital components (the old filter could render a level by its minority admixture, e.g. Sr 5s drawn as its Ti 4s tail; same-l shells accumulate with radial weights at r0 = 2 bohr, contracted-GTO weights in the PySCF case); the --pyscf SCF now solves only the irreducible wedge of the k-mesh (symmetry-reduced, expanded with to_khf, point-charge Hamiltonian re-attached) and starts each fragment from the crystal density restricted to its own sublattice AO block, which both speeds it up and fixes the SrTi(6+)/BaTi(6+) convergence failures; a non-converging SCF escalates through a Fermi-smearing / virtual-level-shift ladder automatically. Deep-level (XPS-style) column alignment added in the same series: each of the three calculations pins its own G = 0 average potential, so the raw columns are offset by one rigid k-independent constant each — the deepest chemically inert fragment level (absolute counterpart purity ≥ 80%, near-purest anchor pairs only) keeps its pre-bonding energy (--no-align to disable).

  • Added quantitative crystal-orbital diagrams via PySCF PBC (crystod --diagram --pyscf -c POSCAR --co-left Sc --co-right F3 [--basis ...] [--pseudo ...] [--xc ...] [--kmesh N N N] [--ke-cutoff E] [--sigma S] [--oxidation El=Q ...] [--no-align]), the crystalline counterpart of crystod-mol --diagram --pyscf (crystod/crystal_orbital_pyscf.py): three periodic KRKS/KRHF calculations sharing one AO space — each fragment keeps its sublattice as real formal-charge ions plus the removed sublattice as ghost basis functions (counterpoise-consistent) and its formal-charge point lattice (jellium-referenced FFT potential, validated against point_charge_field.ewald_site_potential to 2e-6 eV for neutral arrays; every cell is neutral, electron counts even and additive). The diagram is built at the special k points only (SCF mesh defaults to round(8 Å/|a_i|)), every level is labeled with its little-group irrep by crystod’s own machinery evaluated directly in the PySCF AO basis — the periodic-vs-atomic Bloch-gauge conjugation Λ D Λ⁻¹ (essential for non-half-integer sites, e.g. fluorite X/L/W) and the l=3 real-orbital reordering are handled, and the representation is verified against PySCF’s overlap (D†SD = S, residual printed) at every k point. Degenerate levels are clustered adaptively (groups merged until the irrep multiplicities are integral, since the FFT grid splits symmetry-degenerate levels by 1e-4..1e-1 eV depending on the system). The three columns are put on one energy scale by deep-level (XPS-style) alignment — each calculation pins its own G=0 average potential, so the raw columns carry one rigid k-independent offset each; the deepest chemically inert fragment level (counterpart purity ≥ 80%) keeps its pre-bonding energy, using only the near-purest anchor pairs (--no-align to disable) — and the report adds the site-symmetry induced representation of every (element, shell) block plus the same-irrep coupling <φ_left|F(k)|φ_right> of the converged crystal Fock operator with the two-level mixing fraction (same irrep does not imply mixing). Non-converging SCFs escalate through a Fermi-smearing ladder automatically. Examples: ScF3, ZrO2 (fluorite), SrTiO3, BaTiO3 (polar P4mm) in example/03_hybridization.

  • Added two standalone PySCF PBC example scripts in example/test_pyscf/: pyscf_band_structure.py (VASP-style two-step band structure — SCF on a regular mesh, then non-SCF diagonalization on the zero-weight k path; reads VASP KPOINTS band paths, overlays VASP EIGENVAL aligned at the VBM, element-projected Mulliken fatbands, DOS, --save-mo crystal-orbital export; reproduces the SrTiO3 VASP reference gap to 0.04 eV) and pyscf_band_localized.py (the same solid solved with molecular-chemistry machinery — Gaussian density fitting, Becke grids, all-electron bases — with a --benchmark mode; measured conclusion: the localized-basis solid is cheapest with the uniform-grid FFT Coulomb, and the molecular GDF route is orders of magnitude slower for periodic systems).

v0.3.4#

ISO-IR fallback labeling: irreducible representations at NON-special k/q points (symmetry lines, planes, and general points) are now labeled everywhere.

  • Added crystod/isoir.py, a parser and labeler for the ISO-IR dataset of the ISOTROPY Software Suite [H. T. Stokes, B. J. Campbell and R. Cordes, Acta Cryst. A 69, 388-395 (2013); iso.byu.edu/irtables.php]. The complex-irrep table (CIR_data.txt.gz, 1.1 MB gzip) ships inside the package, holds the full space-group representation matrices for every k-vector type (points, lines, planes, general point), and is evaluated at arbitrary k with free parameters. A k point absent from the irreptables (BCS) tables — where previous versions fell back to generic irrep_N names, custom, or - — now gets Miller-Love / ISOTROPY irrep labels (T1, DT5, LD3, GP1, …) and its k-vector-type letter as the k-point name, across crystod (SALC, with a provenance note in the output), crystod --atomic-orbital, crystod-mag, and crystod-phonon --vibration/--vector/--modulation (phonopy band sets are decomposed against the ISO-IR irreps, so accidental degeneracy is handled). Tabulated k points keep their Bilbao-convention labels unchanged; --spinor is unaffected (the ISO-IR dataset has no double-group irreps). Conventions handled explicitly: ISO-IR uses the exp(+2 pi i k.t) translation phase (spgrep/irreptables use exp(-2 pi i k.t)), so spgrep characters are matched against the complex conjugate of the ISO-IR characters — for complex-type irreps the two conventions genuinely swap labels (e.g. Pnma R point: Bilbao R1 = ISOTROPY R2) — and the structure is transformed into the ISOTROPY standard setting (origin choice 2 etc.) via the spglib Hall number, verified for two-origin groups such as Fd-3m. Validated against the ISOSUBGROUP-derived label crosswalk (SG 141/142 X, 230 N) and by gauge-free isotropy-subgroup construction (SG 68 T).

  • crystod-phonon --vector/--modulation: output files of a non-special q are named with the ISO-IR k-vector-type letter (phonon_modes_MoS2_U.txt, POSCAR_MoS2_U_mode1_U2_conv.vesta, MPOSCAR_DT_mode1_DT3_Cmcm). Since every q on one symmetry line shares that letter, --keep-q-coords keeps the coordinate-based q label (q_0.5_0_0.2) so line scans do not overwrite each other (the irrep tag stays).

  • crystod-phonon --irreps --all-irreps: writes phonon_irreps_all.yaml, which additionally lists the phonon irreps at the midpoints of the seekpath k-path segments (the symmetry lines DT, Z, SM, LD, S, T, … connecting the special points), labeled via the ISO-IR tables, together with the seekpath path string (k_path:) and the midpoint list (path_midpoints:). The default run stays the fast special-points-only survey and keeps writing phonon_irreps.yaml, so the two files coexist; the output file name is now printed at the end of the run.

  • crystod --atomic-orbital: the element/orbital tokens accept a hyphen as well as an underscore (Ti-d O-p == Ti_d O_p); a token without a separator is now rejected with an explicit message instead of a bare ValueError traceback.

  • crystod-group --supergroup-cif (symmetry-mode analysis): every run now also writes one VESTA file per activated irrep, {supergroup_file}_{irrep}.vesta, visualizing that irrep’s displacement pattern as arrows on the parent-derived reference structure (invariant-core cell, largest arrow scaled to 1.5 Å) — e.g. the five frozen modes of Pnma CaTiO3 (X5+, M2+, M3+, R4+, R5+) as separate files. --conventional switches the files to the parent conventional basis (_conv suffix).

  • crystod-group --table --space-group SG --kpoint ...: displays the character table of the little group of k — the space-group analogue of the point-group --table — with irreptables (BCS) irrep labels at tabulated k points and ISO-IR (Miller-Love) labels on symmetry lines/planes, Seitz-symbol column headers, and the little-group symbol.

  • crystod-group --basis / --generate-basis with --space-group --kpoint: non-special k points are labeled via the ISO-IR tables as well (e.g. --basis x y z --sg Pm-3m --kpoint 0 0 0.1 gives DT [0, 0, 0.1] with DT1(1) + DT5(2) instead of generic irrep_N names), including centred lattices (C/F/I/R). Fixed in the same change: the conventional-to-primitive translation conversion of the --basis space-group path mixed row/column conventions, which silently broke the symmetry-operation group for the rhombohedral (R) centring — R-group --basis runs now label correctly at special points too. The misleading “No irreps … in irreptables!” warning is no longer printed when the ISO-IR fallback succeeds.

  • crystod-group --product --sg: product terms landing on symmetry lines outside both the CDML tables and the DIRPRO-fitted name map — previously shown with positional names like (1/8,1/8,0)(2) — are now named from the ISO-IR tables and marked [non-tabulated; ISO-IR labels] with a citation note (e.g. N1 x P1 = DT1 + DT4 + DT2 + DT3 in I4_132). The DIRPRO-fitted CDML names keep precedence, since the two conventions genuinely differ at some lines (CDML V of I4/mmm = ISOTROPY LD, T/S of the hexagonal groups = ISOTROPY LD/Q, and the DT numbering of Fm-3m/Ia-3d is permuted — recorded in crystod/dirpro_line_names.py). Distinct +k/-k line stars of acentric groups are disambiguated with the CDML “A” suffix (P1 x X1 = LD1 + LD2 + LDA1 + LDA2 in I4), matching the PA-point convention; -k line stars themselves are labeled through the complex conjugates of the tabulated +k irreps. Sweep-validated over 43 centred/polar space groups (all pairwise k-star products): every line term is named, dimension bookkeeping closes throughout.

  • Fixed crystod-group --product --sg 122: every product involving a P or PA irrep of I-42d aborted with “the irreptables characters of P1 … do not correspond to any allowed small representation”. The shipped irreptables P entry of SG 122 is tabulated in the conjugate gauge (its characters are those of the -k partners, matching no allowed small irrep at P itself), so fitted CDML names for P/PA were added to crystod/dirpro_line_names.py through the name-preserving conjugate correspondence — in agreement with the ISO-IR labels at this point and the ISOSUBGROUP P1PA1/P2PA2 conjugate pairing (P1 x PA1 = GM1 + GM4 + GM5, M1 x P1 = PA2, P1 x X1 = LD1 + LD2 + LD3 + LD4).

v0.3.3#

crystod-group grows into a full Bilbao-style representation-theory toolbox: space-group irrep direct products (DIRPRO), isotropy subgroups (ISOSUBGROUP), multi-electron term symbols with exact Racah multiplet energies, POSCAR <-> Bilbao-style CIF conversion, and AMPLIMODES-style symmetry-mode analysis - each validated against its Bilbao counterpart. crystod-mol gains molecular-orbital diagrams from symmetry + overlap alone. The shared section numbers are regrouped strictly by command.

  • Section renumbering: the shared section numbers of testsuite.py, the example/ directories, and the documentation are regrouped strictly by command — 1 library core, 2-6 crystod, 7-17 crystod-group (the v0.3.3 additions now sit inside the group block: 13 --supergroup, 14 --multiplet, 15 --poscar2cif/--cif2poscar, 16 --supergroup-cif, 17 CLI regression), 18-20 crystod-bz, 21-27 crystod-phonon, 28-29 crystod-mag, 30-31 crystod-md, 32-34 crystod-mol. The example directories were renamed accordingly (e.g. example/30_isotropy_subgroup -> example/13_isotropy_subgroup, example/17_phonon_irrep -> example/21_phonon_irrep).

  • Added space-group irrep direct products: crystod-group --product R4- R5+ --sg Pm-3m decomposes the direct product of full space-group irreps (induced over the whole star of each k point) into full space-group irreps with CDML labels — the offline counterpart of the Bilbao Crystallographic Server DIRPRO [M. I. Aroyo et al., Acta Cryst. A62, 115-128 (2006)]. The wavevector selection rules over the star arms are applied exactly (translation sums carried out analytically over the finite factor group), the star-size x small-dimension bookkeeping always closes, and any number of factors is supported. Products landing on symmetry lines outside the tabulated special points (DT, SM, V, T, S, …) are decomposed with on-the-fly spgrep small irreps and named from a reference-fitted CDML table; missing -k stars of polar groups (CDML “A” points such as PA of I-43m) are synthesized as conjugate irreps; the shipped irreptables characters are refined against exact spgrep values (and the broken P-point entry of SG 230 is substituted). Cross-validated line by line against the 9007-product DIRPRO reference set in DIRPRO/ (20 space groups, all Bravais classes): 96.8% exact; every remaining difference was traced — with dimension-count and label-bijection impossibility proofs — to inconsistencies in the reference notes themselves (see example/07_direct_product/README).

  • Added isotropy subgroups (crystod-group --supergroup Pm-3m --irrep GM4- [--order-parameter 0 0 a]): computes which space group survives when a distortion with the given irrep condenses along an order-parameter direction, or enumerates all direction types (strata) with their subgroups, cell sizes, indices, and (single-direction mode) the conventional basis/origin of the subgroup. Full-star treatment of zone-boundary irreps (cell enlargement detected from the order parameter’s translation stabilizer), real (physically) irreducible forms, arbitrary space groups. Several irreps at once (--irrep X3- X2+) enumerate the coupled-order-parameter isotropy subgroups on the direct sum of the irreps (single-irrep tables printed first, then the coupled directions with every irrep nonzero; every irrep keeps its own free-parameter letters) — I4/mmm X3- + X2+ gives the hybrid-improper-ferroelectric X3-(0;a) X2+(0;c) -> Cmc2_1 (= A2_1am, Ca3Ti2O7) for same-arm rotation + tilt, and Pm-3m R4+ + M3+ the Howard-Stokes mixed perovskite tilt systems (a-a-c+ -> Pnma). Complex- and pseudoreal-type irreps (Frobenius-Schur indicator) are analyzed in the physically irreducible doubled real form with ISOTROPY-style pair labels (Ia-3d P2 -> P1P2, +-k pairs I-42d P1 -> P1PA1), with automatic handling of conjugate-gauge and origin-choice tabulations and a fitted-name recovery for broken irreptables entries (N of I4_132); the subgroup types are identified through a generic-orbit structure standardized by spglib (robust for subgroup axes along sublattice-cell diagonals), and the real irrep basis is canonicalized so the direction labels stay clean signed patterns. Offline counterpart of ISOSUBGROUP (ISOTROPY Software Suite, https://iso.byu.edu); validated exhaustively against the 910 ISOSUBGROUP reference tables in SUBGROUP/ (SG 16-230, all parameter-free k points, 3535 irreps, script/validate_isosubgroup.py): 3533/3535 exact in the full (subgroup, size, index) multiset (25 up to the enantiomorphic partner, 44 up to a verified label swap), the only exceptions being W of Ibca (a spgrep limitation) and the untabulated rhombohedral L star of R-3m.

  • Added multi-electron term symbols (crystod-group --multiplet T2g2 --pg m-3m [--orbital d]): the Pauli-allowed many-electron states of an electron configuration over point-group irrep shells, with spin multiplicities sorted Hund-first — (t2g)^2 = ^3T1g + ^1A1g + ^1Eg + ^1T2g. The antisymmetrization is exact (symmetrized powers / Schur functors via the Frobenius formula, Murnaghan-Nakayama symmetric-group characters, class power maps of the point group); several inequivalent shells couple by spatial direct products and spin angular-momentum addition (T2g2 Eg1); shell tokens accept both T2g^2 and the quoting-free T2g2 (an unquoted ^ is a glob character in zsh); --orbital d prints the ligand-field splitting of the parent orbital and validates the occupied shells against it; every result closes with a state-count check (product of C(2 dim, n)). Hole equivalence and closed shells come out automatically ((t2g)^4 = (t2g)^2 terms, (t2g)^6 = ^1A1g). Validated against the standard crystal-field term tables (t2g^n, eg^n, t2g^2 eg^1 in Oh; e^2 in Td/C3v). 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) from exact Gaunt-coefficient two-electron integrals + Slater determinants + spin/point-group projectors on the determinant space — (t2g)^3 gives the Tanabe-Sugano table ^4A2g = 3A - 15B, ^2Eg = ^2T1g = 3A - 6B + 3C, ^2T2g = 3A + 5C — with closed-form configuration-interaction eigenvalues for doubly-occurring terms (e.g. 3A - 3B + 3C +- 3sqrt(2)B in (t2g)^2(eg)^1), a built-in trace-identity check, and the energy-determined ground state (“lowest for any B, C > 0” when provable). The free-ion limit is reproduced exactly ((T1u)^2 –orbital p: ^3P = F0 - 5F2, ^1D = F0 + F2, ^1S = F0 + 10F2). --visualize additionally writes the exact term eigenstates as an interactive HTML page: every term’s full Slater-determinant expansion drawn as orbital box diagrams (up/down arrows over the symmetry-identified real orbitals) with exact coefficients, degenerate partners and CI states switchable.

  • Added POSCAR <-> Bilbao-style CIF (crystod-group --poscar2cif -c POSCAR [--tolerance 0.01] and the inverse --cif2poscar -c FILE.cif [--conventional]): --poscar2cif writes <POSCAR>.cif in the layout of the Bilbao Crystallographic Server files — spglib-standardized ITA conventional cell and origin, aligned CIF keys with the quoted Hermann-Mauguin symbol and 4-decimal cell parameters, the full conventional-cell operator list as compact unquoted x+1/2,-y,z strings (proper block first, centring translations included), and one representative site per Wyckoff orbit with 5-decimal coordinates — unlike the pymatgen CifWriter layout (script/poscar2cif.py keeps producing the pymatgen flavour as <POSCAR>_pmg.cif). --cif2poscar reads any CIF (Bilbao or pymatgen flavour), expands the symmetry operations, and writes the spglib-standardized primitive cell (or, with --conventional, the conventional cell) as a POSCAR in the crystod test-file style to the input path without .cif. Validated against a Bilbao reference CIF (identical operator set; also used directly as --cif2poscar input), the ITA Pnma general positions, and structure-matching round trips (SrTiO3, ScF3, F-centred NaCl).

  • Added symmetry-mode analysis (crystod-group --supergroup-cif HIGH.cif --subgroup-cif LOW.cif): the displacive distortion between a high-symmetry and a low-symmetry structure (CIF or POSCAR) is decomposed into symmetry-adapted modes of the parent space group — for every parent irrep the k-vector, order-parameter direction, isotropy subgroup, number of independent modes, and mode amplitude in Angstrom (AMPLIMODES normalization: within the primitive cell of the distorted structure, strain-free parent-derived reference lattice), plus the automatically determined cell relation (strain-tolerant lattice matching + atom pairing), the displacement table, and normalized polarization vectors. The direction and isotropy-subgroup columns are computed with the full induced-irrep/isotropy machinery of section 13; non-invariant subgroup lattices are handled by enlarging to the largest parent-invariant sublattice (complete k stars) with exact amplitude rescaling; polar subgroups get the minimum-distortion origin (acoustic component removed); the lattice matching uses principal strains (20% tolerance, atom-count-based index), so strongly relaxed pairs work; and every run is closed by a projector-completeness check. Offline counterpart of AMPLIMODES [D. Orobengoa et al., J. Appl. Cryst. 42, 820-833 (2009)]; validated against its output for SrTiO3 Pm-3m -> I4/mcm (R5-, 0.3303 A, entry by entry) and the F-centred ZrO2 Fm-3m -> P4_2/nmc (X2-, 0.5773 A), plus ferroelectric BaTiO3 -> P4mm (GM4-) and large-tilt AlF3 -> R-3c (R4+, ~14% lattice strain), and cross-validated against the section-25 modulation structures (ScF3 R-3c/Im-3/P4mbm/Imma/I4mmm/Pbnm; frozen amplitudes recovered exactly, including the multi-irrep Pbnm case R4+ + M3+ with inactive secondaries X5+/M2+/R5+). f shells are fully supported (--orbital f, reduced F0/F2/F4/F6 output; hydrogenic 4f ratios F4/F2 = 0.138, F6/F2 = 0.0151 as the reference for CI blocks and the ground state) — e.g. (T1u)^3 = ^4A1u + ^2Eu + ^2T1u + ^2T2u with ^4A1u = 3F0 - (105/4)F2 - (189/2)F4 - (3705/4)F6.

  • Added molecular-orbital diagrams (crystod-mol --diagram --xyz FILE.xyz): the MO diagram of a single-center molecule (NH3, CH4, SF6, …) from symmetry and overlap alone — ligand SALCs + central-atom orbitals combined per irrep with the Wolfsberg-Helmholz approximation H_ij = K S_ij (H_ii + H_jj)/2 over exact single-zeta-STO overlap integrals (prolate-spheroidal quadrature; ligand-ligand overlap included), i.e. symmetry-adapted extended Hückel [M. Wolfsberg and L. Helmholz, J. Chem. Phys. 20, 837 (1952); R. Hoffmann, J. Chem. Phys. 39, 1397 (1963)]. Writes an interactive HTML/SVG diagram by default (ligand AOs | ligand SALCs | MOs | central AOs, correlation lines weighted by composition, electron arrows, HOMO/LUMO markers, per-level composition panel, adjustable energy window) and prints the SALCs, the inter-fragment overlap integrals, and the full MO table. The MO numbering counts core shells as in photoelectron spectroscopy: CH4 (2a1)^2 (1t2)^6, NH3 (2a1)^2 (1e)^4 (3a1)^2 (3a1 lone-pair HOMO), SF6 filled to the nonbonding F 2p block. Elements H-Cl. With --pyscf the diagram becomes quantitative: three PySCF SCF calculations in one AO space (fragments with ghost basis on the removed atoms, counterpoise-consistent; spin/spherically averaged by fractional occupations) give the pre-bonding fragment columns and the exact projection of every molecular MO onto them, with crystod-convention irrep labels assigned from the MO characters on the PySCF AO basis (σ/π labels for linear molecules); --ao-left/--ao-right select any fragment partition by formula (O2 O/O, CH3OH H4/CO, benzene H6/C6), and --basis/--theory/--xc/--charge/--spin follow script/calc_pyscf.py [Q. Sun et al., WIREs Comput. Mol. Sci. 8, e1340 (2018)]. Every level of both diagram flavours carries a drag-rotatable orbital sketch in the hover panel (molecule + VESTA-style +/− lobes from the actual eigenvector, degenerate partners switchable), and the energy window of the page is interactive (input boxes / Ctrl+scroll zoom / drag pan; with all-electron core levels below -40 eV the default window is clamped to [-40, 15] eV and a Show-all-energy-levels button restores the full range). Fixed (2026-07-28): the --pyscf sketches compressed each atom’s contracted s/p functions by a bare coefficient sum, which can invert the far-field lobe sign (tight and diffuse contracted functions enter one MO with opposite signs) — the bonding 1e of NH3 was drawn with an inverted N-2p lobe and looked identical to the antibonding 2e; every contracted function is now weighted by its radial amplitude at r0 = 2 bohr before summing, so the drawn phases are the real wave-function phases (verified against real-space psi evaluation; regression test in section 33), and the example + binary pyscf diagrams were regenerated.

  • CLI polish: --space-group/--point-group gained the no-hyphen aliases --spacegroup/--pointgroup everywhere (in addition to --sg/--pg), crystod-bz --show-kpoint also accepts --sg/--spacegroup, and space groups can be given by number (1-230) as well as by symbol in all --sg modes (crystod-bz --show-kpoint --sg 221, crystod-group --basis x y z --spacegroup 221 ...).

  • SALC viewer pages are now ~40-190x smaller (e.g. the R-point PySCF eigen-level page of ScF3: 19.5 MB -> 180 kB; SALC_F_p_R: 17 MB -> 116 kB): the orbital-lobe surface grids — previously ~97-99% of the HTML — are no longer embedded. Each lobe’s angular function Re[sum_m c_m X_lm] is a homogeneous degree-l polynomial on the unit sphere, so the page now ships only the exact polynomial coefficients per lobe (fit residual < 1e-6, asserted) plus one shared lobe-builder JavaScript that reconstructs the identical surface grids client-side at load. Appearance, mode switching, depth fade, opacity and compass behaviour are unchanged; the classic, molecular, and PySCF eigen-level viewers all share the writer and shrink alike.

  • Added crystal-orbital diagrams (crystod --diagram -c POSCAR --co-left SrTi --co-right O3 [--atomic-orbital Ti-3d Ti-4s O-2p] [--oxidation Sr=+2 Ti=+4 O=-2]): the analysis CrystOD is named after — the crystalline analogue of the crystod-mol --ao-left/--ao-right MO diagram. --co-left/--co-right split the crystal into two fragment sublattices by chemical formula, each treated with its full-electron basis (WIEN2k-style: every core and valence shell; valence with the extended-Hueckel parameters, cores with Slater-rule exponents and the archived neutral-atom PySCF Hartree-Fock/def2-svp levels — one calculation per element in reference/atomic_level_*, generated with the user-standard script/calc_pyscf.py driver via script/generate_atomic_levels.py, collected into crystod/atomic_levels.py with angular-momentum shell assignment and an archive cross-check; beyond Kr the def2 ECP freezes the deep cores, which are omitted exactly as in pseudopotential DFT), and each fragment feels the removed sublattice as a point-charge lattice with the formal oxidation states (pymatgen-guessed or --oxidation) — the Madelung ligand field of the pre-bonding states, entering as exact same-site STO matrix elements (real-spherical-harmonics Laplace expansion in the wigner_D_real convention, closed-form radial integrals, Loewdin-consistent with the on-site metric, near shells explicit + Ewald long-range tail; validated against the NaCl Madelung constant and the exact 6Dq/-4Dq octahedral ratio), so the fragment d states carry the true electrostatic t2g/eg splittings; the background-dependent monopole of the charged sublattice array is omitted (it cancels against the intra-atomic charging energy absent from EHT VSIPs; the jellium-referenced values are printed). At every special k point the Bloch orbitals are symmetry-adapted per little-group irrep, all overlaps are evaluated exactly as Bloch lattice sums of STO integrals (double-zeta d shells, generic sigma/pi/delta Slater-Koster assembly via exact real Wigner-D rotations, validated to machine precision; per-shell-pair cutoffs probed from the actual STO tails — diffuse cation shells reach 30+ bohr), and the Wolfsberg-Helmholz generalized eigenproblem (diagonal carrying the same-orbital neighbour-cell Bloch sums; ligand-field blocks added identically to fragment and crystal Hamiltonians, symmetry invariance of S and H self-checked per k point) implements the COD mixing rule (same irrep -> bonding/antibonding, no partner -> rigorously nonbonding); near-linearly-dependent Bloch combinations of the diffuse cation shells (overlap eigenvalue < 0.2, the extended-Hueckel overlap catastrophe) are removed by canonical orthogonalization and counted in the report. Output: per-k terminal tables (fragment levels labeled by their dominant element+shell) and an interactive HTML with one diagram per k point (k-point buttons, composition-weighted correlation lines, electron arrows, HOMO/LUMO, full-electron filling with --electrons override, energy window opening on -20 .. 10 eV with a Show-all button for the core levels, and — with the optional --atomic-orbital sketch filter — a hover wave-function sketch: Re[psi] of exactly the selected components on the k-commensurate supercell with s/p/d lobes, drag-rotatable with switchable degenerate partners). The extended-Hueckel parameter tables were extended to H-Bi (3d/4d metals with the standard double-zeta d contractions). ScF3 (Sc | F3, 48 electrons) and SrTiO3 (SrTi | O3, 56 electrons with the ECP-28-frozen Sr core) reproduce the symmetry-resolved perovskite bonding picture: flat core levels at the archived atomic energies, fragment t2g below eg in the octahedral anion field, F-2s/Sc-3d(eg) sigma bonds at GM with the t2g GM5+ rigorously nonbonding, and sigma/sigma* eg + pi/pi* t2g splittings with nonbonding R4+/R5- at R. Fixed (2026-07-28): the --atomic-orbital sketches wrote same-l shells of one atom into the same s/p/d slots by plain assignment, so a multi-shell filter (e.g. Sc-p = 2p+3p+4p) drew only the last shell’s raw STO coefficients — a semicore level like Sc 3p came out as the tiny sign-inverted 4p orthogonalization tail, the crystal analogue of the contracted-GTO compression bug in the crystod-mol --pyscf sketches; the shells now accumulate, each weighted by its STO radial amplitude at r0 = 2 bohr, so the drawn lobe phases are the real wave-function phases (regression test in section 3: the X-point Sc-3p/F-2s bonding/antibonding pair of ScF3), and the example diagrams were regenerated.

v0.3.2#

  • Added crystod-mol, a new sectioned command for molecules (XYZ files): --symmetry detects the molecular point group with pymatgen (Schoenflies + Hermann-Mauguin symbols and the symmetry operations by class — the molecular analogue of phonopy --symmetry), and --element EL --orbital s|p|d|f builds molecular SALCs: the site-permutation characters are multiplied by the orbital characters, decomposed into point-group irreps (same character tables and labels as crystod-group), and the explicit SALCs are projected out (via the permutation x real-orbital Wigner-D representation, so p/d/f orbital components mix correctly). --align rotates the molecule into the standard point-group orientation for textbook axis conventions, --show-matrix prints the site-permutation matrices, and --tolerance controls the symmetry detection. --visualize writes the SALCs as the same standalone interactive 3D HTML viewer as crystod --visualize (molecule in a vacuum box at Gamma; no cell edges, x/y/z compass; --output and --bond EL1 EL2 MAX supported). The detected symmetry operations are snapped onto the exact character-table matrices, so the SALC coefficients are clean small integers whenever possible. Adds pymatgen as a dependency.

  • Added crystod-bz --show-kpoint --space-group SG: prints the special (high-symmetry) k points of a space group with their CDML labels (from irreptables, the same k-point definition as the SALC/irrep analyses) in the primitive reciprocal basis, and additionally in the conventional reciprocal basis for centred lattices (F, I, C, A, B, R) such as Fm-3m, where the two definitions differ.

  • testsuite.py gained the crystod-mol sections (32 and 34 in the current numbering) with the molecule files in example/test_XYZs (O2, H2O, NH3, CH4).

  • Fixed: the SALC viewer (crystod --visualize and crystod-mol --visualize) squeezed the structure into the left half of the viewport and opened too zoomed-in, clipping part of the structure. Cause: with the compass added as a second plotly scene, the main scene had no explicit domain and was grid-split to half the width. The main scene now claims the full plot area and the initial camera starts further out, so the whole structure is visible on load (the stored example/05_visualized_basis pages were regenerated accordingly).

v0.3.1#

crystod-phonon --modulation workflow overhaul — corrected frequencies, CDML irrep labels, a mode-table preview, and informative default file names — plus star-arm-aware k-point/irrep labeling across all commands.

  • crystod-phonon --modulation can now be run with --qpoint only (no --mode): it prints the mode table (mode number, frequency, irrep, degeneracy) and the star of q, then exits without generating a structure — useful for inspecting the modes at a q point before choosing which to apply.

  • Fixed: the frequencies in the --modulation mode table were wrong whenever an irrep occurs more than once at the q point (each irrep-projected block was diagonalized on its own, dropping the coupling between blocks carrying equivalent irreps — e.g. every X-point mode of Sr3Ti2O7 except the singly-occurring X1-/X2+ irreps). The dynamical matrix is now block-diagonalized with the same equivalent-irrep clustering as crystod-phonon --vector, the mode vectors are true eigenvectors, and every run is verified internally against the plain phonopy spectrum. Mode numbers at affected q points differ from v0.3.0 accordingly; the frequencies now agree with crystod-phonon --irreps (phonon_irreps.yaml).

  • The --modulation mode table now shows CDML irrep labels (X3-(1), GM5-(2), …) from irreptables — the same labeling as crystod-phonon --vector/--irreps — instead of internal block indices (the column header changed from Irrep Block to Irrep; labels fall back to - when irreptables labeling is unavailable, e.g. at non-special q points).

  • Irrep and k-point labeling now works at EVERY arm of a special-point star, not only at the single arm tabulated in irreptables/seekpath — across ALL label lookups: the SALC analysis (crystod -c ... --element/--orbital), --atomic-orbital hybridization, --visualize, --star-of-k (the header now shows e.g. X [0.0, 0.5, 0.5] instead of custom), crystod-mag, crystod-phonon --vibration, --vector (q label in the report and VESTA file names), and --modulation. E.g. all three X arms (1/2,0,0)/(0,1/2,0)/(0,0,1/2) of Pm-3m, and both X arms (0,0,1/2)/(1/2,1/2,0) of the I4/mmm primitive cell, now get X labels; previously only the tabulated arm was labeled (the SALC decomposition fell back to generic irrep_N names). For the phonon commands the k point is mapped onto the tabulated arm (star-arm spectra are identical band by band); for the SALC/orbital analyses, which compare little-group characters operation by operation, the characters are transported by the conjugation isomorphism h -> g^-1 h g between the little groups, including the Bloch phase from lattice-translation offsets (verified at the X and W stars of nonsymmorphic Fd-3m Si).

  • Fixed: special k points with 1/3-type coordinates (K/H of hexagonal groups, …) were rounded to 0.333333 in the table-derived k-point lists, which silently broke the little-group detection — e.g. the crystod-mag survey printed a wrong decomposition with generic irrep_N labels at K/H. Table-derived coordinates are now snapped to exact fractions, and k/q-point input across the commands accepts fractions (--qpoint 1/3 1/3 0) while near-fraction decimals are snapped (0.333333 -> 1/3).

  • Fixed: crystod-mag exported the SAME spin structure twice (e.g. ..._GM5+_dipole_x_conv.vesta and an identical ..._x_conv_2.vesta) when a 2-dim irrep space came out of the projection in the circular complex basis (x + iy, x - iy): taking the real part folded both partners onto the same vector. Such spaces are now recombined unitarily into a real orthonormal basis (possible whenever the space is closed under complex conjugation), so the two components export as orthogonal partners (..._dipole_x and ..._dipole_y), matching the 2-dim order parameter (found for the in-plane Ni dipoles/quadrupoles of I4/mmm La3Ni2O7).

  • The --modulation default output name is now MPOSCAR_{q}_{mode}_{irrep}_{subgroup} (e.g. MPOSCAR_R_mode1+2+3_R4+_R-3c; one {q}_{mode}_{irrep} group per term in multi-q runs) instead of POSCAR_modulated; --output still overrides it.

  • testsuite.py sections are renumbered by command group (1 library core, 2-6 crystod, 7-13 crystod-group, 14-16 crystod-bz, 17-23 crystod-phonon, 24-25 crystod-mag, 26-27 crystod-md; each group closes with that command’s CLI regression section), and every example/ directory is prefixed with its section number (example/24_phonon_vector <-> python testsuite.py 24). New example directories with captured output were added for the previously undocumented features: 01_wigner_d (library demo), 04_star_of_k, 07_direct_product, 10_basis_function, 11_generate_basis_function, 12_show_coset, and 19_bz_supercell. See example/README for the full map.

v0.3.0#

CrystOD has been restructured into sectioned commands (phonopy style: one main crystod command plus per-domain crystod-* commands), with phonopy-aligned option names (-c/--cell for the structure file, with --poscar kept as an alias). The old crystod --<mode> flat forms were removed; invoking one prints an error with the equivalent sectioned command.

  • Mode numbering is now 1-based across ALL commands and outputs: crystod-phonon --vector --mode, --modulation --mode/--modeN, --vibration --mode-index/--component-index (the component default is now 1), crystod --visualize --mode-index, and every printed mode table / Mode Space / component listing. A 0 or out-of-range number is rejected with a clear 1-based message.

  • crystod --visualize HTML redesigned as an interactive viewer modeled after Henrique Miranda’s phonon website (BSD-3-Clause; design imitated, no code copied): sidebar with structure summary, irreducible decomposition, a clickable SALC-basis table replacing the dropdown, lobe-opacity / cell / atom display controls, and a credit link in the page. New --conventional displays the SALC in the conventional cell (primitive-to-conventional matrix from the detected centring, as in crystod-phonon --vector). New --bond EL1 EL2 MAX (repeatable) draws bonds within the cutoff and VESTA-style translucent coordination polyhedra around the EL1 atoms, with boundary atoms completed so polyhedra at the cell edge are not cut off.

  • crystod --visualize now always writes the interactive 3D HTML, auto-named SALC_{element}_{orbital}_{kpoint}.html when --output is omitted (previously nothing was written without --output).

  • crystod-phonon --vector usability update: mode numbering is now 1-based, matching the printed table (--mode 0 is rejected with a clear message); the q-point mode table (space group, q-points, frequencies, irreps) is automatically saved as phonon_modes_<formula>_<qlabel>.txt; and omitting --mode now exports ALL modes as individual VESTA files (--mode still selects specific modes, summed into one file). VESTA file names now carry the irrep label and zero-padded mode numbers (POSCAR_<formula>_<qlabel>_mode<NN>_<irrep>.vesta) so that ls lists them in order.

  • Redesigned the main crystod command: the flagship SALC analysis runs without a mode flag (crystod -c POSCAR --element Ti --orbital d; hybridization via --atomic-orbital), --visualize merges the former --visualize-basis, and --star-of-k stays as the symmetry-information option. --kpoint now also accepts high-symmetry labels (GM/X/M/R) in --star-of-k/--visualize mode — the documented --kpoint M form previously failed to parse. Added --version; crystod --help lists all sectioned commands.

  • Added crystod-bz (first sectioned command), merging --bz and --bz-supercell: with the default identity --trans-mat it plots the unit-cell BZ with an automatic (seekpath) or manual (--band/--band-labels) k-path; with any non-identity --trans-mat it plots the unit-cell BZ together with the folded BZ of the transformed (super)lattice.

  • Added crystod-md (MD section) with two modes: --adp (replacing --xdatcar2adp) writes atomic displacement parameters as a CIF; --summary (based on script/md_summary.py) reports time-averaged lattice parameters and cell volume with standard deviations over a step range (--start-step/--end-step). --dim now also accepts a nine-value diagonal matrix (quoted or unquoted); --format selects the trajectory format (vasp; LAMMPS planned). A missing trajectory file is reported cleanly instead of a traceback.

  • Added crystod-phonon (phonon section), merging the six flat phonon modes as --irreps (old --phonon-irrep, renamed to match phonopy), --fatband, --lt, --vector, --modulation, and --vibration (force-data-free). --dim accepts three values or a nine-value diagonal matrix, quoted or unquoted; --band-labels is the primary spelling (--label kept as alias); numbered --qpoint1/--mode1/... arguments still work in --modulation.

  • Added crystod-group (representation-theory section) for point AND space groups, merging six flat modes: --product (old --direct-product), --table (character-table display, formerly --direct-product --show-irrep-table without irreps), --decompose (old --decompose-irrep), --ligand-field ORBITAL (old --ligand-field-split --orbital), --basis (old --basis-function), --generate-basis (old --generate-basis-function), and --coset (old --show-coset). --pg/--sg are provided as short aliases of --point-group/--space-group; labels starting with a minus sign (-43m, -1, …) are handled.

  • crystod-mag --conventional exports the symmetry-adapted spin structures in the conventional cell (primitive-to-conventional matrix from the detected centring; _conv-suffixed VESTA files).

  • Added crystod-mag (magnetism section), replacing --spin-basis: symmetry-adapted spin bases as the default action, with per-atom spin directions and the noncollinear magnetization input printed by default (no --show-spin-direction needed). New --format vasp|qe selects the printed input: a VASP MAGMOM line, or the Quantum ESPRESSO &SYSTEM counterpart (noncolin, per-type starting_magnetization/angle1/angle2, with the magnetic element split into one type per spin direction).

  • Removed the old flat forms of all sectioned modes — --salc, --visualize-basis, --bz, --bz-supercell, --xdatcar2adp, --spin-basis, --phonon-irrep, --phonon-fatband, --phonon-lt, --phonon-vector, --modulation, --vibration, --direct-product, --decompose-irrep, --ligand-field-split, --basis-function, --generate-basis-function, and --show-coset. Invoking one prints an error naming the sectioned replacement.

v0.2.3#

  • Added --phonon-vector: phonon-eigenvector visualization as VESTA files with displacement arrows, from the same POSCAR + FORCE_SETS/FORCE_CONSTANTS inputs as --phonon-irrep. Modes are listed with frequencies and irrep labels; the commensurate supercell and Bloch phase factors are applied automatically for fractional q-points. Degenerate modes are exported as symmetry-adapted eigenvectors (aligned along symmetry-dictated directions, as in --modulation) rather than arbitrary eigensolver combinations. --conventional switches the output from the primitive to the conventional cell.

  • Added --decompose-irrep: interactive decomposition of a reducible representation into point-group irreps from user-entered characters (based on script/decomose_to_irreps.py by Hiroki Koiso), with a non-interactive --characters option.

  • Added --ligand-field-split: ligand-field splitting of an atomic orbital (s-i) into point-group irreps (based on script/ligand_field_spliting.py by Hiroki Koiso).

  • Added --xdatcar2adp: time-averaged structure and symmetry-constrained ADPs (U_ij) from an MD XDATCAR trajectory as a CIF (based on script/xdatcar_to_adp.py by Ko Sato), with a fast built-in XDATCAR parser instead of pymatgen.

  • Added --phonon-fatband: element-projected phonon fatbands (PDF per element) along an automatic seekpath k-path, computed directly from POSCAR + FORCE_SETS/FORCE_CONSTANTS via the phonopy API. Colored with VESTA default element colors; --nac applies the non-analytical term correction (LO/TO splitting) from a BORN file.

  • Added --bz-supercell: interactive 3D plot of the unit-cell BZ together with the BZ of a transformed (super)lattice, tiled at the |det T| folded supercell reciprocal-lattice points (based on script/supercell_BZ.py by Hiroki Koiso).

  • Added --phonon-lt: phonon bands colored by longitudinal/transverse character with an optional --nac correction (based on script/LT_phonon_band.py, after Qijing Zheng), using the exact eigenvector projection onto the propagation direction so that diagonal path segments are also colored correctly.

  • Added --spin-basis: symmetry-adapted spin bases (cluster multipoles / SAMM, after M.-T. Suzuki et al.) with FM/AFM separation, multipole-rank naming, per-atom spin directions with a VASP MAGMOM line (--show-spin-direction), VESTA export, and automatic magnetic supercells for q != 0. Omitting --qpoint lists the spin-multipole irreps at all special k points (as in the crystod SALC survey).

  • --basis-function now supports the axial-vector components Rx, Ry, Rz (transforming with det(R) R, like magnetic moments), including mixed polar-axial products such as the toroidal x*Ry - y*Rx. In space-group mode, omitting --kpoint now analyzes all special k points automatically (as in the crystod SALC survey).

  • Fixed point-group labels starting with a minus sign (-43m, -42m, -6m2, -1, …) being rejected by the argument parser in all --point-group/--subgroup modes; both --point-group -43m and --point-group="-43m" now work.

  • --dim now also accepts unquoted values (--dim 4 4 4) in all modes.

  • Fixed --phonon-irrep with phonopy >= 2.21, where the removed IrReps.frequencies property caused an AttributeError.

v0.2.2#

  • Added --bz: interactive 3D Brillouin-zone plot (HTML) with automatic space-group detection and a seekpath-generated high-symmetry k-path, or a manual path via --band/--label. Based on script/brillouin_zone_plot.py by Hiroki Koiso.

  • Added seekpath and scipy to the package dependencies.

v0.2.1#

  • Added --visualize-basis: SALC coefficients and interactive 3D HTML visualization, with the --real-coefficient option for real-type degenerate irreps.

  • Added --star-of-k as a standalone command, and automatic star-of-q display in --modulation.

  • Added --show-coset: left-coset decomposition G = sum g_i H (point groups) and right-coset decomposition G = sum G_k g_i (space groups, one coset per star arm).

  • Added --generate-basis-function: automatic 1st-3rd order polynomial basis functions classified by irrep.

  • Rewrote the Wigner-D routines in operations.py with pure NumPy (no sympy) and fixed several bugs: the parity factor for improper operations (det vs det^l), the beta = pi Euler-angle branch, the p_y row sign in the complex-to-real transform, and a float-determinant perturbation that broke the Euler-angle extraction.

  • Fixed numerical-noise blowup in space-group basis-function coefficients (--basis-function / --generate-basis-function).

  • Improved compatibility with recent phonopy PhonopyAtoms (removed remaining ASE-style getter calls).