Changelog#
All notable changes to CrystOD, newest first.
Unreleased#
Changed: the space-group filter of
crystod-searchis--sg/--spacegroup/--space-group, as incrystod-groupandcrystod-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 64keeps 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 231and--spg P7are refused like--sg 231and--sg P7, and--getwith any of them is refused as a filter). The sort key--sort spgkeeps 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--outputthat every other command with an output file already has.crystod-group --poscar2cif -c POSCAR -o out.cifis--output out.cif: one value (args.output), the same files (the CIF of--poscar2cif, the POSCAR of--cif2poscar, the page of--multiplet --visualizeand of--graph) and the same refusals in the modes that write no file. As before, every token after--order-parameterup to the next--optionis a component, so-othere is read as minus o (as-cis minus c);--outputtakes no part in the--order-parametermodes. Documentation: crystod-group; tests in section 02-18.Added:
crystod --unfold --trans-matrix T, an alias of--trans-mat, as incrystod-bzandcrystod-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 incrystod-bzandcrystod-phonon;--trans-matitself 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), inmode-resolved-fc.yaml; testsuite section 04-12.crystod-mag --qpointat q != 0: both phases of a complex order parameter (the partners i w ascomp<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 asdir<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-onlya 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-parameterfor 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 ofcrystod-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 Kfor every irrep at K;-c POSCAR --element ELalone 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-filesprints only andCRYSTOD_NO_REPORT=1turns 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", functiontest_CC_NN_name, header[CC-NN]). The groups are 01crystod(01-01 the library core, 01-11 the Python API), 02crystod-group, 03crystod-bz, 04crystod-phonon, 05crystod-mag, 06crystod-md, 07crystod-mol, 08crystod-xrd, 09crystod-slab, 10crystod-searchand 11crystod-example. The sections numbered at the end since v0.4.8 (58-66) now sit in their group: the displacement patterns ofcrystod-phonon -c POSCAR --element EL --irrep IRopen thecrystod-phonongroup (04-01) and the magnetic arrangements ofcrystod-mag -c POSCAR --element EL --irrep IRthecrystod-maggroup (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 letteredCC-NN-A,CC-NN-B, … (02-01-A. Point-group irreps, formerly02-01.1).python testsuite.py 05-01 04-02runs those sections,python testsuite.py 05the wholecrystod-maggroup, 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-exampletakes 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 ...), andcrystod.examples.renamed_notegives that line in Python. The packaged copies incrystod/examples/follow the new names (index.jsonformat 2: thenumberof a directory is the text"CC-NN"). The renaming also repairs three stale paths:32_phonon_irrep(renamed to32_phonon_bandirrepin the tree but not intestsuite.py,example/PACKAGED, the docs andcrystod-example) is04-02_phonon_bandirrepeverywhere; the Cr2O3 cell of05-03_magnetic_groupisCr2O3/PPOSCAR_Cr2O3_R-3cin its README, the test andexample/PACKAGED; and the YMnO3 cells of section 05-06 are read from its own directory05-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_d01-01_wigner_d2
01-02
02_salc01-02_salc3
01-03
03_hybridization01-03_hybridization4
01-04
04_selection_rules01-04_selection_rules5
01-05
05_star_of_k01-05_star_of_k6
01-06
06_visualized_basis01-06_visualized_basis7
01-07
07_check_symmetry01-07_check_symmetry8
01-08
(no example directory)
crystod –extract-irrep
9
01-09
09_band_unfold01-09_band_unfold10
01-10
(no example directory)
crystod command-line regression
52
01-11
52_python_api01-11_python_api11
02-01
11_direct_product02-01_direct_product12
02-02
12_symmetric_square02-02_symmetric_square13
02-03
13_decompose_irrep02-03_decompose_irrep14
02-04
14_ligand_field_split02-04_ligand_field_split15
02-05
15_basis_function02-05_basis_function16
02-06
16_tensor_form02-06_tensor_form17
02-07
17_generate_basis_function02-07_generate_basis_function18
02-08
18_show_coset02-08_show_coset19
02-09
19_correlate02-09_correlate20
02-10
20_isotropy_subgroup02-10_isotropy_subgroup21
02-11
21_invariants02-11_invariants22
02-12
22_child_lookup02-12_child_lookup23
02-13
23_subgroup_graph02-13_subgroup_graph24
02-14
24_multiplet02-14_multiplet25
02-15
25_poscar2cif02-15_poscar2cif26
02-16
26_symmetry_mode02-16_symmetry_mode27
02-17
27_correlate_double_group02-17_correlate_double_group28
02-18
(no example directory)
crystod-group command-line regression
29
03-01
29_brillouin_zone03-01_brillouin_zone30
03-02
30_bz_supercell03-02_bz_supercell31
03-03
(no example directory)
crystod-bz command-line regression
66
04-01
66_phonon_irrep04-01_phonon_irrep32
04-02
32_phonon_bandirrep04-02_phonon_bandirrep33
04-03
33_phonon_activity04-03_phonon_activity34
04-04
34_phonon_fatband04-04_phonon_fatband35
04-05
35_phonon_lt04-05_phonon_lt36
04-06
36_phonon_vector04-06_phonon_vector37
04-07
37_modulation04-07_modulation38
04-08
38_vibration04-08_vibration39
04-09
39_phonon_unfold04-09_phonon_unfold40
04-10
40_phonon_visualize04-10_phonon_visualize41
04-11
(no example directory)
crystod-phonon –subgroup and command-line regression
58
04-12
58_phonon_mode_fc04-12_phonon_mode_fc64
05-01
64_mag_irrep05-01_mag_irrep42
05-02
42_spin_basis05-02_spin_basis43
05-03
43_magnetic_group05-03_magnetic_group44
05-04
(no example directory)
crystod-mag –parent
45
05-05
(no example directory)
crystod-mag command-line regression
59
05-06
59_mag_directions05-06_mag_directions60
05-07
(no example directory)
crystod-mag –subgroup-poscar
61
05-08
61_phonon_angular_momentum05-08_phonon_angular_momentum62
05-09
62_multi_element05-09_multi_element63
05-10
63_mag_coupled05-10_mag_coupled65
05-11
(no example directory)
crystod-mag magnetic space groups on non-invariant cells
46
06-01
46_xdatcar2adp06-01_xdatcar2adp48
06-02
(no example directory)
crystod-md –summary and command-line regression
47
06-03
47_md_projection06-03_md_projection49
07-01
49_molecular_salc07-01_molecular_salc50
07-02
50_molod07-02_molod51
07-03
(no example directory)
crystod-mol command-line regression
53
08-01
53_xrd_pattern08-01_xrd_pattern54
08-02
54_xrd_superlattice08-02_xrd_superlattice56
09-01
56_slab09-01_slab55
10-01
55_mp_search10-01_mp_search57
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_elementand05-10_mag_coupled(crystod-example 04-01,04-12,05-01,05-06,05-08,05-09,05-10). Their READMEs, input structures (for04-12_phonon_mode_fcalso theFORCE_SETSand the referencemode-resolved-fc.yamlfiles) and thesamm_*reference reports the READMEs name are packaged. 52 of the 54 example directories now ship (all but01-07_check_symmetryand01-09_band_unfold): 291 files with the shared inputs, 8.46 MB (94.0 % of the 9,000,000-byte budget ofexample/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 Kdoes 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 ofcrystod-mag -c ... --irrep, with its machinery: for every row of the table ofcrystod-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 columnstructure(63 Cmcm same) and acheck (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 areproduce: --order-parameter "..."line. Copies, weights,--coefficients,--order-parameter,--copies,--classify-only,--conventionaland--no-filesas incrystod-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 copyPOSCAR_<formula>_disp_<IR>[_<IR2>]_<NN>_<SG>_<symbol>[_c<copies>].vesta(arrows scaled to 1.5 A) and the displaced structureM<POSCAR name>_<IR>[_<IR2>]_<NN>_<SG>_<symbol>[_c<copies>](largest displacement--amplitude, default 0.1 A), the supercellS<POSCAR name>_<IR>[_<IR2>]and the reportsaad_<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--irreptogether with a mode flag is refused (--irrepused to be accepted by argparse as an abbreviation of--irreps; it is now its own option).--elementtakes 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--irrepand no--qpoint(formerly a parser error), is the displacement counterpart of thecrystod-mag -c POSCAR --element ELsurvey: 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/--qpointheaders (several elements: per element and total), reportsaad_<formula>_<element(s)>_survey, no structures (--amplitude,--conventional,--classify-only,--order-parameter,--coefficientsand--copiesrefused); every line equals the header of--qpoint Kand, as a multiset, the one ofcrystod -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)forA1(1)+A3(1), wherecrystodlists the members) (APIphonon.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 ofcrystod-group --supergroup-ciffinds only the requested irreps in a sample of the displaced structures. Python:phonon.displacement_irrep_arrangements(DisplacementIrrepAnalysis,DisplacementArrangement); implementation incrystod/displacement_arrangements.py(the machinery ofcrystod/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) andSrTiO3/(Pm-3m with Ti at the origin, O; intest_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 ofcrystod-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; columnstructureof the table and acheck (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 areproduce: --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--qpointnames 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 jselects 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 theMAGMOMline (--format qe: the Quantum ESPRESSO input).--classify-onlyprints 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--coefficientsand a-cfile 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);--qpointand the other options of the--qpointreport are refused.--conventionalwrites every arrangement in the conventional cell instead of the diagonal supercell (for I, F, C, A, R lattices): the cell--qpoint --conventionaluses for the same POSCAR times the smallest multiples commensurate with every arm (La2CuO4 I4/mmm X3+: 2x2x1 conventional cells, aDisplay 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,MAGMOMlines, 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), thereproduce: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>].vestaper row,S<POSCAR name>_<IR>[_<IR2>](atom order of the MAGMOM lines) and the reportsamm_<formula>_<element(s)>_<IR>[_<IR2>](_classifywith--classify-only;--no-filesandCRYSTOD_NO_REPORTwrite 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--qpointcomponents (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--irrepwithout--parentwas an error; every other output is unchanged. Python:mag.magnetic_irrep_arrangements(MagneticIrrepAnalysis,MagneticArrangement,IrrepCopy); implementation incrystod/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-parametergives 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 ofcrystod-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, fromR4+(0,0,a) M3+(0;0;d)127.397 P_C4/mbm (size 4, index 12) andR4+(0,a,a) M3+(d;0;0)62.454 P_Bnma (unitary Pnma, 24) toR4+(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-parameterthe 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 ofcrystod-groupas 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)(CoupledMagneticIsotropySubgroupsofCoupledMagneticIsotropySubgrouprows),mag.coupled_magnetic_order_parameter(CoupledMagneticOrderParameter);parities=["even", "odd"]makes an irrep time-even (a distortion, theta acting as +D), printed then with ISOTROPY’smon the time-odd ones; the command line does not take time-even irreps yet. Implementation incrystod/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 GMtakes 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 columnsno.andelement,--phonon-angular-momentumand--show-operationscover every row, and the reports aresamm_<formula>_<A>-<B>_<q>[_classify]andsamm_<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--superposeevery 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 incrystod/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-momentumgives 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 givesnone (P T), degree 0 is the net magnetization. Every component block gets the linephonon 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’) aftercollinear order:, and--classify-onlythe 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_momentumandmag.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:ofcrystod-magalso 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 (JahnV), 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’ withelectric polarization along z (induced by the spin order), every order of polar LuFeO3 (P6_3cm) at GMalong zwithout a note.format_magnetic_responsesprintselectric polarization: allowed by symmetry along zorforbidden by symmetryafter the net magnetization. The summary table* Magnetic groups and collinear classes *and the other lines are unchanged. Python:MagneticResponses.polarization,.polarization_direction,.polarization_noteand.n_polarization,MagneticGroupInfo.crystal_rotations(the point group of the structure without moments, filled bymagnetic_space_group), and the keywordcrystal_rotationsofmacroscopic_responsesfor explicit operations. See crystod-mag; tests in section 05-03.New:
crystod-phonon --mode-resolved-fc --dim N N N -c POSCARgives the harmonic stiffness of every phonon mode and of every irrep subspace at the special q points of the space group (the points--irrepssurveys). 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 ofcrystod-group --supergroup-cifmeasured 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,--readfcreadsFORCE_CONSTANTS,--nacreadsBORN(at exactly Γ phonopy adds no non-analytical term, which a NOTE says),-o FILEnames the YAML file,--tolerancesets the degeneracy tolerance. The YAML filemode-resolved-fc.yamlholds the header (space group,nac, Z, the units), every special point, and per computed q point theband_sets, theirrep_hessianblocks and the NOTE lines (notes). Python:crystod.phonon.mode_resolved_force_constants(ph, q),survey_mode_resolved_fc, the dataclassesModeForceConstants,ModeForceConstantSetandIrrepHessianBlock, andwrite_mode_resolved_fc_yaml,read_mode_resolved_fcandformat_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-phononmode that readsFORCE_SETSorFORCE_CONSTANTS(--irreps,--fatband,--lt,--vector,--modulation,--subgroup,--unfoldfor 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 underexample/: clean data give at most 0.01 eV/A^2 (4.2e-4 max |Phi|; SrTiO3 3.6e-3, BaTiO3 1.4e-3), the Ca3Ti2O7FORCE_SETScomputed on a supercell with two Ca wrapped from z = 0.9999999999999999 to 0 gives 3.17 eV/A^2 (Γ right, X wrong).--mode-resolved-fcalso writes the NOTE to a top-levelnoteslist ofmode-resolved-fc.yaml; a phonopy yaml (--yaml) is not checked. Python:crystod.phonon_irreps.permutation_symmetry_residualandcheck_force_constants_consistency. See crystod-phonon; testsuite section 04-12.New:
crystod-mag --conventional(with--qpoint, and with-c ... --irrep) prints a NOTE under theDisplay 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 ofphonopy --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 --qpointwhenever 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_groupnow 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.confirmedis False and a NOTE under themagnetic 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 ofphonopy --symmetryat Γ, 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--irrepmode 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 --qpointexported 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, K3comp1was 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 nowcomp2, and K2 givescomp1193.258 K2(0.282a;a) andcomp2193.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 ascrystod-mag --parentenumerates them. Each row gives ISOTROPY’s label at a special point (matched to the--parenttable 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 asdir<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 lineorder-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) arecomp1/aa0/aaa, nodir), 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, K3comp1is 0.25 GM1 + 0.75 GM4 andcomp20.75 GM1 + 0.25 GM4 of the P6_3cm Mn bases. Python:SpinBasisAnalysis.directions(mag.OrderParameterDirection),SpinBasisComponent.direction_label,.direction_subgroupand.direction,mag.direction_table_rowsandmag.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 CHILDplaces 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, K3comp1andcomp2of P6_3/mmc lie 60 degrees from the domains that P6_3cm singles out). CHILD is mapped onto the crystal ascrystod-group --correlate --supergroup-poscar --subgroup-poscarmaps 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 asPOSCAR_YMnO3_spin_K3_K_comp2_GM4.vestaandS185_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 exportedcomp1as 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 thatcrystod-mag -c CHILD --qpoint GMfinds 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--tolerancewhen larger. Python:analyze_spin_basis(..., subgroup_poscar=CHILD)fillsSpinBasisAnalysis.subgroup(mag.SubgroupAlignmentwithmag.SubgroupSpinFieldrows),mag.subgroup_table_rowsandmag.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 Calso saves its report, word for word what it prints, asCORREL_<formula>_<G>_<H>in the current directory (the reduced formula of the supergroup structure, as insym_mode_<formula>, and the short symbols of G and H without_and/:CORREL_YMnO3_P63mmc_P63cm,CORREL_SrTiO3_Pm-3m_I4mcm);--spinorruns append_spinor. A closing* Output files *block names the file;--output-dir DIRand--no-filesact as for--supergroup-cif.crystod.group.subgroup_correlationand the MCP tool write no file; its result has the new fieldparent_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 lineReport written to: FILE (this output);--no-filesprints only, and the environment variableCRYSTOD_NO_REPORT(any value but empty or0) turns the saving off for every command. The CORREL report ofcrystod-group --correlate --supergroup-poscaris the first to use it (unchanged byte for byte). Python:crystod.cli.common.SavedReport(a context manager overTeeStream) andcrystod.cli.common.file_name_tag(P6_3/mmc->P63mmc). The test suite runs every command withCRYSTOD_NO_REPORT=1unless a check passesreports=True; section 02-09 checks the class.Changed: the report of
crystod-mag --qpointis renamed frommag_salc_<formula>_<element>_<q>tosamm_<formula>_<element>_<q>(samm = symmetry-adapted magnetic moments;samm_AlNi3_Ni_GM), and two morecrystod-magmodes save their report, word for word what they print: the survey (no--qpoint) assamm_<formula>_<element>_survey(samm_AlNi3_Ni_survey) and--qpoint Q --classify-only(with or without--show-operations) assamm_<formula>_<element>_<q>_classify(samm_TiO2_Ti_GM_classify,_convwith--conventional). Both close with* Output files */Report written to: ... (this output), as the--qpointreport does; they still write no VESTA file and no magnetic-cell POSCAR. The new--no-filesprints only (accepted with the survey and--classify-only),CRYSTOD_NO_REPORT=1too;--classify-only --subgroup-poscar,--parentand anERRORexit write no file. Python:crystod.spin_basis.survey_report_file_name(formula, element)andclassify_report_file_name(analysis); the MCP tools write nothing. Oldmag_salc_*files are not renamed. Tests in sections 05-02, 05-03 and 05-06.New:
crystod-phonon --modulation,--subgroup,--vibration --qpointand--unfold, andcrystod-md --summaryand--project, save their terminal report, word for word what they print.--modulationwithout--mode(mode table, star of q) asmodulation_<formula>_<q>(modulation_ScF3_R), with--modeasmodulation_<formula>_<tags>next to the structure,<tags>= the MPOSCAR name withoutMPOSCAR_(modulation_ScF3_R_mode1+2+3_R4+_R-3c);--subgroupasSUBGROUP_<formula>_<q>(SUBGROUP_SrTiO3_R,_allwithout--qpoint), with the reproducing--modulationcommand lines of--modulate;--vibration --qpoint Qasvibration_<formula>_<q>and with--mode-index Nasvibration_<formula>_<q>_space<N>[_comp<M>](_comp<M>for a space of dimension 2 or more), and the displaced structure of--mode-indexis now written by default toVPOSCAR_<formula>_<q>_space<N>[_comp<M>]when no--outputis given (before, nothing was written);--unfoldasphonon_unfold.txt(the-oprefix of the .pdf/.dat);crystod-md --summaryasMDSUM_<formula>and--projectas<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 --adpand the othercrystod-phononmodes are unchanged.crystod-phonon --irreps --raman-tensoralso writes the printed Raman tensors tophonon_irreps.yaml, under the new keyraman_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
crystodSALC, hybridization and star-of-k runs,crystod-mol --symmetryand its SALC runs, and thecrystod-searchtable save their terminal report, word for word what they print.crystod -c POSCAR --element EL --orbital ORB(also with--show-irrep-tableor--visualize) assalc_<formula>_<EL>_<ORB>[_<k>](salc_ScF3_F_p,salc_SrTiO3_Ti_d_R),_spinorappended with--spinor,--axialassalc_<formula>_<EL>_axial[_<k>];--atomic-orbital Sc_d F_pashybrid_<formula>_Sc_d-F_p[_<k>][_spinor];--star-of-k --kpoint Kasstar_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-molasmol_sym_<formula>andmol_salc_<formula>_<EL>_<ORB>(the full molecular formula in Hill order:mol_salc_C6H6_C_p,mol_sym_H3N),crystod-search QUERYand--getasmp_search_<query>.txt(mp_search_Sr-Ti-O.txt,mp_search_mp-5532.txt; blanks,/and?dropped,*writtenany).--visualizelists 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-irrepwithout-onow writes its YAML asband_irreps_<formula>.yaml(the-o FILEwriter,OVERWRITTENwhen it was there, as--check-symmetrydoes withvasp_symmetry_<formula>.yaml);--no-filesorCRYSTOD_NO_REPORT=1write none. The MCP server runs its commands withCRYSTOD_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 FILEandcrystod-slabsave their terminal report, word for word what they print, and thesym_mode_<formula>file ofcrystod-group --supergroup-cifbecomes the whole report.--tensor KIND -c POSCARasTENSOR_<formula>_<kind>(TENSOR_ZnO_piezoelectric,TENSOR_ZnO_raman; a Jahn symbol with[ ]written-and{ }written=:TENSOR_ZnO_V-V2-),--cif-axis -c FILEasCIFAXIS_<formula>(CIFAXIS_La3Ni2O7), both in the current directory and closed by* Output files */Report written to: ... (this output);--no-filesis now accepted with these two forms and prints only;--tensor --pg/--sg(a lookup) writes nothing, as before.crystod-slabasSLAB_<formula>_<selection>in--output-dirbeside the slab POSCARs (SLAB_SrTiO3_100for one--index 1 0 0, the plane family as in the POSCAR names;SLAB_SrTiO3_max1for--max-index 1;SLAB_SrTiO3_listfor--index-listor several--index; the dialogue names it after its equivalent command line and the file carries the questions and answers), with theReport written to:line inside its* Output files *block, whosenone (no slab was generated)/none (every slab was skipped)then readno slab file (...); the report is overwritten on a rerun (--forceconcerns the POSCARs only), and--no-files, a quit of the dialogue and anERRORexit 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 lineDecomposition table saved to sym_mode_<formula>of that block readsReport written to: sym_mode_<formula> (this output);--output-dirand--no-filesact as before, andCRYSTOD_NO_REPORT=1now leaves outsym_mode_<formula>while the VESTA files are still written. Nothing in the source tree read the old layout ofsym_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 kindpiezoelectric-eofcrystod-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--spinoralso for the double-valued irreps; the compatibility relations along a line are now--correlate-kpath.crystod-mag --qpointalso writes the magnetic cell as a POSCAR, its atoms in the order of the MAGMOM lines (atom by atom, as in phonopy’sSPOSCAR).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 ofcrystod-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, theexample/directories and the numbered sections of this manual run from 1 to 57, grouped by command: 1 library core, 2-10crystod, 11-28crystod-group, 29-31crystod-bz, 32-41crystod-phonon, 42-45crystod-mag, 46-48crystod-md, 49-51crystod-mol, 52 Python API, 53-54crystod-xrd, 55crystod-search, 56crystod-slab, 57crystod-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: 7crystod --check-symmetry(provisionally 49d), 8crystod --extract-irrep(was 49), 9crystod --unfold(was 54), 27crystod-group --correlate-double-group(was 55), 39crystod-phonon --unfold(was 51), 40crystod-phonon --visualize(was 52), 44crystod-mag --parent(was 56), 56crystod-slab(was 53) and 57crystod-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 example28_phonon_irrepis nowexample/32_phonon_irrep(python testsuite.py 32,crystod-example 32) and17_isotropy_subgroupis20_isotropy_subgroup. The--subgroupsection of thecrystod-phononpage (now 41) moves after the phonon mode viewer (40). Scripts that callpython testsuite.py Norcrystod-example N, or read files belowexample/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 thevasprun.xml(Born effective charges, the electronic and ionic dielectric tensors) and theOUTCAR(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 incrystod-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).--onlyselects tensors,--tolerancesets spglib’s tolerance, and the YAML filevasp_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-eofcrystod-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 symbolV[V2]given to--tensoris now described as the symmetry type of both kinds.New in Python:
crystod.group.vasp_symmetry_report,VaspSymmetryReport,format_vasp_symmetryandsymmetrize_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 readerscrystod.vasp_io.read_vasprun_responseandread_outcar_response, which take the Born, dielectric, piezoelectric, elastic and internal-strain tensors, the ionic steps of avasprun.xmland the magnetization tables of anOUTCARby exact headings (pymatgen’sOutcar.read_piezo_tensorandread_elastic_tensorand phonopy’sget_born_OUTCARfail on the output of VASP 6.5.1).New:
crystod-group --correlate --supergroup-poscar P --subgroup-poscar Clists, 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 givesR4+(3) -> GM1+(1) [A1g] + GM5+(2) [Eg],GM4-(3) [T1u] -> GM3-(1) [A2u] + GM5-(2) [Eu], X (2 of 3 arms) -> X withX5+(2) -> X2+(1) + X3+(1)and X (1 arm) -> M withX1+(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)and2 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 aSubgroupCorrelationofKpointCorrelationblocks ofIrrepCorrelationrows, printed byformat_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 --sgnow stops with a one-line hint to the new name. The Python functioncompatibility_relationsand 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 namessubduce_to_child,Subductionandformat_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/mcmR4+ -> GM1+ [A1g] + GM5+ [Eg],R5+ -> GM4+ [B2g] + GM5+ [Eg]; AlF3 R-3cR4+ -> GM1+ [A1g] + GM3+ [Eg]), which replaces it together withsubgroup_correlation;--correlatewith--parent,--irrepor--order-parameterstops with a hint to that form. The MCP formparent+irreps+directionofcrystod_correlateis replaced bysupergroup_poscar+subgroup_poscar.New:
crystod-group --correlate --supergroup-poscar P --subgroup-poscar C --spinoradds 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 ascrystod --spinorand--correlate-double-groupname 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 termA/Band an irrep doubled by time reversalA/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 theirreppackage 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 withdouble_valued=True, notes inspinor_notes); MCP:crystod_correlate(..., spinor=True).New: every
crystod-mag --qpointrun 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(or0.5 0.5 0.5) writesSPOSCAR_VO2_P42mnm_A, the 2x2x2 cell withV O/16 32and 48 MAGMOM triples;-c ../139_PPOSCAR_La3Ni2O7 --qpoint 0 0 0.5 --conventionalwritesS139_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-cand the q part of themag_salc_*report (GMfor GAMMA,_convwith--conventional); the file is VASP 5 with direct coordinates and the same cell and atom order as thespin directionslistings 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-onlyand an ERROR exit write no file. Python:crystod.spin_basis.supercell_poscar_name(analysis, poscar)andwrite_supercell_poscar(analysis, path, poscar), and the new fieldSpinBasisAnalysis.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-magare atom-major, as in theSPOSCARof 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 ..., nowVx 16 thenOx 32; AlNi3 at R:Al1..Al8thenNi9..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 thespin directionslistings, 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--conventionalnothing changes. The READMEs ofexample/42_spin_basisandexample/43_magnetic_groupare 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-kpointswrites 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 --spinornames 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 ofcrystod-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 asmag_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 ofcrystod-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 groupsI_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-magon Python 3.10. pymatgen 2025.10.7, the last release for Python 3.10, fails with a circular import when itsmaggroupsmodule is imported beforepymatgen.core, so every BNS symbol lookup (the magnetic space groups of--qpoint,--classify-onlyand--parent) stopped with anImportError;pymatgen.coreis now imported first.Fixed:
mag.magnetic_space_group(and with itcrystod-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.184C_ccc2and 37.186C_Acc2as 36.177 and 36.179, and cannot name 37.185C_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 --axialgives 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, Rzin 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 thecrystod-magsurvey. In Python:CrystalOrbital.irreducible_decomposition(k, EL, "axial"). Not with--spinor. Testsuite section 2 compares it with the explicit spin matrices ofcrystod-magover 23 space groups, and over all 230 (4050 element/k-point cases) withCRYSTOD_AXIAL_SWEEP=1.New:
crystod-mag --qpointprints 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 lineUNI 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 columnMSG (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.1type I,Pnma.1'type II, unchanged for type III); a type IV group carries its anti-translation on1'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 ascrystod/magnetic_unified.txt(fromdata_magnetic.txtof the ISOTROPY Software Suite, identical to Table S2 of the paper; source note in LICENSE;script/make_magnetic_unified.pyrewrites it). Python:MagneticGroupInfo.uni_symboland.uni_point_group,crystod.mag.unified_symbol(bns_number)andunified_point_group_symbol(mpg, type);uni_numberstays spglib’s serial number. MCPcrystod_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-operationslists, 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 followcollinear order:in the listing; with--classify-onlythey 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) andformat_parent_operations;SpinBasisAnalysisgainsprimitive_lattice,conventional_lattice,parent_rotationsandparent_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 --qpointsaves its whole report, exactly as printed, inmag_salc_<formula>_<element>_<q>in the current directory, next to the VESTA files (mag_salc_AlNi3_Ni_GM;mag_salc_AlNi3_Ni_Rfor--qpoint Ror0.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 inSelected q-point:, withGMfor GAMMA;--conventionaladds_conv. The* Output files *block ends withReport written to: mag_salc_AlNi3_Ni_GM (this output); a file of the same name is overwritten. The survey mode (no--qpoint),--classify-onlyand a run that stops with anERRORwrite 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-onlyand anERRORexit write none.New:
crystod-mag --qpointalso 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 to111(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_outand_combined_componentsincrystod/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:aaforx). Examples: Ce of CeRu2Si2 (I4/mmm) at Γ, GM5+ dipolex,y(Im’m’m) and110(Fm’m’m, 69.524), the arrangement that was missing; Ti of TiO2 (P4_2/mnm), GM5+ dipole and octupole1m10,110(Cmm’m’) andx(Pnn’m’, 58.398); Ni of AlNi3 (Pm-3m) at Γ, GM4+ and GM5+x,y,z,110(Cmm’m’, 65.486) and111, the GM5+ octupole allowing a net magnetization only in the110arrangement; 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) andaaa; Ir of Y2Ir2O7 (Fd-3m), GM4+ and GM5+ octupoles (comp<N>)aa0(Imm’a’, 74.559) andaaa(R-3m’, R-3m). Nothing is added where (a,a) is not special: the E irreps of hexagonal and trigonal crystals (Cr2O3, LuFeO3), whosexandyare 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 only111is 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 acomp<N>basis are not the (a,0,0)-type partners fewer combinations come out, never a general direction; over the 228 structures ofexample/test_POSCARsat Γ, no error. The example READMEs ofexample/36_spin_basisandexample/37_magnetic_groupare 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 RprintsR1+(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 ofcrystod --spinor(Bradley & Cracknell’s numbering, with theNOTE:lines of--spinorwhere it differs: 32, 3m, -3m and the cyclic co-groups with complex pairs).--kpointtakes 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 0givesDT1(1) -> -DT6(2)andDT5(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 againstcrystod --spinoron real structures. In Python,crystod.group.spin_orbit_relations,SpinOrbitRelationandformat_spin_orbit_relations. Documented in crystod-group; exampleexample/55_correlate_double_group; tested in the new section 55 (CRYSTOD_DOUBLE_GROUP_SWEEP=1adds the sweep over all 230 groups).New:
crystod -c POSCAR --element EL --orbital L --spinorandcrystod --atomic-orbital ... --spinorname the double-valued (spinor) irreps — Ti 3d of SrTiO3 at Γ is1.0 [-GM7+(2)] + 2.0 [-GM8+(4)], at R1.0 [-R6-(2)] + 2.0 [-R8-(4)]— where they printed generic keys such asirrep_3(2), because the bundled ISO-IR tables hold single-valued irreps only. The names are those--extract-irrepand--diagram --vasp --vasp-engine overlapalready gave spin-orbit runs, from the same namer, now public ascrystod.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-GM3is 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,-GM8Table 6.5’s Γ8, Γ7. The names are not the Bilbao numbering (Pm-3m Γ: CrystOD-GM6-is BCS-GM8,-GM8+is-GM10). Every--spinorrun 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 aNOTE: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 inconsistentlywhere they form a cyclic group of order 3, 4 or 6 and a complex pair is present (Γ of P3 and P4);--show-irrep-table --spinorprints the double-valued character table with the names, and an irrep that cannot be named keeps its generic key with aNOTE: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, newcrystod.isoir.IsoIRLabeler.representative_k) and carried to the arm given by conjugation, D’(h) = D(g^-1 h g) (newcrystod.wavecar_irreps.transport_double_valued_names;crystod.wavecar_irreps.little_group_datarecords it in the newLittleGroup.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 inexample/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 inexample/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--spinorchecks, 68 in all: the B&C order at Γ of P2, Pm and P2/m, star covariance throughlittle_group_dataand 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 PARENTunfolds 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 onecrystod-group --supergroup-ciffinds for the two POSCARs, as incrystod-phonon --unfold(--trans-matpicks another equivalent setting); the k weights and the path labels come from each run’s KPOINTS (the! K.n LABELcomments 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,rawor an energy in eV), applies to both runs, so the offsets between them are the raw ones;--separate-zerozeros 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 EMAXsets 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) andband_unfold.yaml;-o PREFIX,--degeneracy-tol,--weight-min,--spin(ISPIN = 2runs: 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; exampleexample/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 PARENTwrites 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--npointspoints per leg when the parent KPOINTS has none) as zero-weight points whose! K.n LABELcomments carry the parent labels. Only the POSCARs and KPOINTS files are read.crystod --unfoldon 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 SEPcomments, plain! LABELcomments or labels after the numbers. Every spelling of Gamma becomesGM; a bareGonly at an integer k, sinceGis a point of its own in the Hinuma paths, and the! K.n Gform keepsG.New in Python:
crystod.salc.unfold_bands,BandUnfolding,format_band_unfoldingandunfold_kpoints(crystod --unfoldand--unfold-kpoints; the result hasto_dict(),write_dat,write_yamlandplot, and bad input raisesValueErrorwith the command’s message); see Python API.Changed: double-valued names of spin-orbit runs in
--extract-irrepand--diagram --vasp --vasp-engine overlapwhere 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
spiorofcrystod.salc.CrystalOrbitaland of the--atomic-orbitalclass (crystod.orbital_hybridization_spgrep.CrystalOrbital) is renamedspinor. The misspellingspior=is still accepted, with aDeprecationWarning; the command-line flag--spinoris unchanged.Changed:
--zeroofcrystodalso acceptsfermiandnone(forefermiandraw), and with--unfoldan energy in eV; a non-finite value is refused.--extract-irreptakesvbm,efermiandrawas before (and the two aliases), and refuses a number. The options--zero,--spin,--degeneracy-toland--all-kpointswithout their mode now stop withX is only used with --extract-irrep or --unfold., and--windownames--unfoldamong 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_blockand 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 thatcrystod-group --supergroup-ciffinds 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.unfoldand 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 toband_vector.yaml, phonopy’sband.yamlwith eigenvectors;crystod.phonon.phonon_viewer_datain 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 --irrepsnow also draws the phonon dispersion with the ISO-IR label of every level at the special points of the path (phonon_irreps.pdf, next tophonon_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-indexthat 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-polarand--symmetrize, and an interactive dialogue when no index is given;crystod.slabin 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 2unfolds 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’sUnfolding, 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 thatcrystod-group --supergroup-cif PARENT --subgroup-cif CHILDfinds 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/--npointsin 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--irrepsgives 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), elsemixed; 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-dimthe 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-readfcand--parent-readfcreadFORCE_CONSTANTS,--no-irrepsskips the labels and--weight-minsets the weight cut. Each force file is read next to its POSCAR,FORCE_SETS_<POSCAR name>(the name macer writes) beforeFORCE_SETS, so that the two POSCARs can share one directory, and phonopy runs in an empty directory, so that aFORCE_CONSTANTSlying in the working directory is never used in place ofFORCE_SETS.--nacis refused. In Python:crystod.phonon.load_unfold_inputs,find_parent_mapping,parent_mapping_from_setting,make_parent_path,unfold,star_arms,domain_average,irrep_resolveandgamma_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 --irrepsnow also draws the phonon dispersion with the ISO-IR label of every level at the special points of the path (phonon_irreps.pdf, next tophonon_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--bandpath 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 thosephonon_irreps.yamlholds (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.pdfwith-o SrTiO3_irreps.yaml,phonon_irreps_all.pdfwith--all-irreps); the run prints the path and the labeled points in a* Band path *block, and with--naca 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, aNOTE: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-labelscount that does not fit it, stops the run with one line before the survey. The README image is now made bycrystod-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 POSCARwrites a phonon mode viewer: one standalone HTML page that shows every phonon mode at the special points of the k path, grouped by irrep, andband_vector.yaml, phonopy’sband.yamlwith eigenvectors along the same path. The page holds the dispersion along the path of the--irrepsfigure (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 asphonon_irreps.yamlwrites 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 ofcrystod --visualize(VESTA colors, cell edges, the a/b/c compass,--bond EL1 EL2 MAXbonds 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.yamlis phonopy’s own format (nqpoint,segment_nqpoint,labelswith the ISO-IR vertex names, the primitive cell, and per q point the frequency and theeigenvectorof every band,[re, im]per Cartesian component and atom);-o FILErenames 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;--bondis refused outside--visualize.--all-irrepsadds the midpoint of every segment of the path (DT, Z, SM, LD, S, T of Pm-3m; for--bandthe midpoints of its legs) as q points of their own, after the special points: the labels ofphonon_irreps_all.yamlband 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, aSegment:line, and the pagephonon_visualize_all.html(#q=DT(GM-X)or#q=5open 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--qpointthat draws it, and--all-irrepswith--qpointis refused. In Python:crystod.phonon.phonon_viewer_data,write_phonon_viewer_htmlandwrite_band_vector_yaml, with the dataclassesPhononViewer,ViewerPointandViewerMode. The atom enumeration of the display cell and the bond search of the SALC viewer are now the helpers_display_cell_entriesand_bond_pairsofcrystod.visualize_basis, shared by both viewers (the bond search vectorized; the pages ofcrystod --visualizeare byte for byte unchanged);compute_dispersionrecords 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 1cuts 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 lof hexagonal axes withi = -(h + k)checked and dropped),--index-list FILE(one index per line,1 0 0,1,0,0or1 0 -1 0,#comments) or--max-index N: every index with|h|, |k|, |l| <= Nthat 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’sget_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 nonecrystod-slab -c POSCARasks 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) quitexits with 0; the structure file and--oxidationare checked before the first question), then prints the* Equivalent command line *and runs it. For each index pymatgen’sSlabGeneratorbuilds 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-sizeof vacuum (default 15 Å;--in-unit-planes: both counted ind_hkllattice 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 isSlab.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 isSlab.is_symmetricat--tolerance(default 0.1 Å).--max-atoms Nand--no-polarlist the slabs they skip with the reason,--symmetrizeasks for symmetric terminations (pymatgen’sget_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),--conventionalstandardizes 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-cand--max-normal-searchare passed on to pymatgen,--lll-reducereduces the in-plane cell withaandbkept in the surface (pymatgen’s ownlll_reduceLLL-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,--forceand--no-filescontrol the filesPOSCAR_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 usecrystod-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 formerscript/slabkit.pyof Ryuju Kiribayashi (2024), without its banner; unlike the script, whose--indexand 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 domaincrystod.slab(load_structure,distinct_miller_indices,parse_miller_index,read_index_list,generate_slabsreturningSlabSet/SlabRecordwithcharge,format_table,write_slab_poscarreturning(path, status)ascrystod.search.write_poscardoes,slab_filename,SLAB_CITATION_LINES, …); importing it loads no pymatgen.crystod-slab --example SrTiO3/--example ScF3run 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 toolcrystod_slab(the slab table of a POSCAR for onemiller_indexor for every distinct index up tomax_index, with the slab and vacuum sizes,symmetrize,no_polar,max_atomsandoxidation_statesof the command, and the slab POSCAR files only in an absoluteoutput_dirthe call names; it needs CrystOD 0.4.6).Fixed: the direction column of
crystod-group --supergroup-cifnames each order parameter ascrystod-group --parentdoes, 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 IRrow of the same isotropy subgroup (reported on V2O3 R-3c -> C2/c:GM3+ (0.577a,-a)against the rowGM3+(a,0) 15 C2/c; SrTiO3 Pm-3m -> I4/mcm printedR5- (a,0,0)since v0.4.1, against the rowR5-(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--parenttables (IsotropyAnalyzer.canonical_projector): the largest mode with domain-equivalent directions sits on its--parentrow, and the rows together still describe one domain (the Pbnm perovskite printsR4+ (0,a,a)withM3+ (a;0;0), as in the coupled rowR4+(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 insym_mode_<formula>, names the mode that decides and its--parentcommand, 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: SrTiO3R5- (a,0,0)->(0,0,a), V2O3GM3+ (0.577a,-a)->(a,0), ZrO2 Fm-3m -> P4_2/nmcX2- (0;a;0)->(0;0;a)and BaTiO3 Pm-3m -> P4mmGM4- (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--parenttables. In Python, each entry ofSymmetryModeAnalysis.modesgainsdomain_label(the direction of the child as given) andrepresentative_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_irrepsin 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 commandcrystod-examplelists them and copies them into a working directory, together with the shared structures and the other directories a README uses;crystod.examplesgains the same functions. Every example README now runs inside its own directory.crystod-group --parent: the pair labels of--kpointare accepted by--irrep,--order-parameterreads sums of parameters exactly, and the direction tables print irrational ratios as decimals instead of small integers.Compatibility:
--spinofcrystod(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 FILEnames 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 efermiorraw), 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 anA/Blevel is classified by Wigner’s test of time reversal at k — a time-reversal pair (-L4/-L5at L of zincblende with spin-orbit coupling,DT3/DT4along Γ–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.--kpointtakes labels and/or coordinates,--all-kpointslabels every k point of the file (lines, planes and general points, named by the ISO-IR k label of the little group),--window EMIN EMAXlimits the listed levels,--degeneracy-tolsets the level clustering (default 1 meV).ISPIN = 2runs 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 FILEwrites the same content as YAML (the layout ofphonon_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 overlapon 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 aBandIrrepsdataclass (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 inexample/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), theISPIN = 2and 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_kpointat 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-kpointsreaches such points; the special points of the overlap engine are unaffected. Tested in section 49.Changed:
crystod.vasp_wavecar.Wavecarreads both spin channels of anISPIN = 2WAVECAR 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 refusesISPIN = 2with the same message. Tested in sections 3 and 49.Note:
--spinis now an option ofcrystod(for--extract-irrep), so it no longer abbreviates--spinor; write--spinorin full.Fixed:
crystod-group --parent SG --irreptakes the pair labels that--kpointprints.--parent 176 --kpoint HlistsH1H2,H3H6andH4H5, but--irrep H1H2 H3H6stopped withirrep "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--kpointtable uses), in--irrepalone and with--order-parameter,--invariants,--secondary,--graph,--correlateandcrystod.group.isotropy_subgroups;--irrep H1H2 H3H6prints exactly what--irrep H1 H3prints. 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--kpointtables 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--kpointtable exactly; a +-k pair listed at the -k point (P1PA1at 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-parameterreads a sum of parameters as that sum. A component such asa+b-c-dwas 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+dgave 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--kpointtables 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 --parentprint 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 printedP2(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.8753instead of0.75,0.4,0.875; H3 of P6/mcc printed1bfor 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-examplecopies them out. All 41example/NN_name/directories, each with its README and the input files its commands read but without their large or unpublished data, are installed undercrystod/examples/at the same relative paths, together with the sharedtest_POSCARs/(18 structure files) andtest_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]andcrystod-example --all -o DIRcopy them into./example(orDIR), 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 oneERRORline 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_dirsandExampleConflictError. The packaged files are byte-for-byte copies ofexample/, selected inexample/PACKAGEDand written, withindex.jsonand a plain-textREADME, byscript/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 everyFORCE_CONSTANTS, the reference data of the test suite (theexpected.jsonfiles, the two extra WAVECAR runs ofvasp_wavecar,ISPIN = 2and spin-orbit SrTiO3, thedebugN_*fixtures of 23, the recorded answers of the offline section 48) andtest_pyscf, as well as third-party and generated output. Unpublished, not distributed: the data of unpublished work (vasp_overlapandvasp_SrTiO3_LAKof 03, the CdF2 supercell of 06).LICENSEnames 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-examplecopy. Paths are relative to the README (../test_POSCARs/...,../28_phonon_irrep/...) instead of from the repository root, and private paths are gone.22_poscar2cifworks on its own copies of its inputs and no longer overwritestest_POSCARs/221_PPOSCAR_SrTiO3and the test suite’s reference221_PPOSCAR_ScF3.cif.39_xdatcar2adpand40_md_projectionuseXDATCAR_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 % (Ueq0.005477 and 0.023486 Ų, against 0.005485 and 0.023521 Ų), and the fullXDATCAR(not in the pip package) stays in the CrystOD development tree for sections 39-41. In28_phonon_irrep, two phonopy lines write theFORCE_CONSTANTSthat the--readfclines read (phonopy-init -d -c POSCAR --dim 4 4 4,phonopy phonopy_disp.yaml --writefc --fc-calc traditional); they come after theFORCE_SETSlines, becausephonopy.loadprefers aFORCE_CONSTANTSin the working directory even whenFORCE_SETSis named.33_modulation/Sr3Ti2O7_I4mmmbegins with the two phonopy lines that write itsphonopy_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 subdirectoryphonopy4/, so that its packagedphonopy_params.yaml(the force constants that 40 reads) stays as it is and a latercrystod-example 33or40into the same directory still finds it unchanged, and checks there that--yamlwith the new file writes the same structure byte for byte.42_molecular_salcholds its own copies ofXYZ_O2.xyz,XYZ_NH3.xyzandXYZ_CH4.xyz.03_hybridizationand23_symmetry_modemark the commands that need data not in the pip package; 23 gains the Materials Project attribution and an--output-dirfor its second La3Ni2O7 pair, whose table would otherwise replace the first one’ssym_mode_La3Ni2O7.Changed: packaging.
pyproject.tomlsetsinclude-package-data = false, so only the package-data globs decide what ships (this also silences setuptools’ “Package would be ignored” fortest_POSCARs/), adds the globs of the example directories and anexclude-package-datatable (__pycache__,*.pyc,*.html,*.pdf,POTCAR*,.DS_Store), and the console scriptcrystod-example. Package-data globs read the disk and ignore.gitignore, so a release is built from agit archiveexport of the release commit, never in the working tree, wherepython -m build --no-isolationwould also letsetuptools-scmput every tracked file into the sdist (CONTRIBUTING.md, Release process).Note: the
--examplelisting ofcrystod,crystod-phonon,crystod-mol,crystod-bz,crystod-xrdandcrystod-searchends with a blank line andMore 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 --qpointand--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 toolcrystod_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-cifprints and saves the transformation matrix from the parent to the child setting.crystod --sigma/--xrange: the SCF Fermi smearing of--diagram --pyscfand--visualize --pyscf, the Gaussian broadening of--dos --pyscfand the energy range of the DOS plot;crystod-phonon --modulation --qpoint R: special-point labels in place of coordinates, as in--vectorand--subgroup.Every block header at column 0 as
* Title *;phonon_irreps.yamlis valid YAML, read bycrystod.phonon.read_phonon_irreps; fixes to the two-dimensional and complex irreps ofcrystod-mag. Test sections are renumbered 1-48.crystod-mcp0.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 ofcrystod-group --basis --sgat k != 0, Brillouin zones of unreduced bases (crystod-bz), the site-symmetry constraints ofcrystod-md --adp, d and f shells incrystod-mol --diagram, the -k stars ofcrystod-xrd --parent, and the stdio stream ofcrystod-mcp.Fixed: the SALC viewer of
crystod --visualize --element X --orbital ldraws the coefficients in the atomic gauge, so relative phases between sublattices are right at every k point. Each atom’s block is multiplied byexp(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-coefficientruns 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 --visualizenames 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 ORBwhen an element’s atoms are not contiguous in the POSCAR (repeated species blocks such asO 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 ofO (5)with the letters of Ti and Sr. Tested in sections 2 and 7.Fixed:
crystod --atomic-orbitalfor 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 asO 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 --diagramnow 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 --pyscfaccept--no-chkinstead of stopping with ‘unrecognized arguments’. Those modes never use the automaticCHK_{formula}.chkcache, so the flag changes nothing there. Tested in section 7.New:
crystod --sigmaand--xrange.--sigmasets the SCF Fermi smearing of--diagram --pyscfand--visualize --pyscfand the DOS broadening of--dos --pyscf,--xrangesets 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 --sgat k != 0 of non-symmorphic space groups. The Bloch phasesexp(-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 --sgprinted 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--tableand 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 --decomposerefuses 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/istops 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--orbitalshells. Tested in sections 21 and 24.Fixed:
crystod-bzdrew a too-large Brillouin zone for unreduced bases (manual--bandpaths on oblique cells, sheared--trans-matsupercells). 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
toleranceofget_brillouin_zone_3d(default 1e-5). Tested in section 25.Fixed:
crystod-bz --trans-matfolds the unit-cell q points to the true nearest image also for oblique unit-cell bases. Tested in section 26.Fixed:
crystod-bz --show-kpointfor 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-matrejects non-integer matrices with an ERROR instead of printing meaningless folded points. Tested in section 26.Fixed:
crystod-phonon --vibration --mode-indexrefuses a q point that no supercell of at most 12 cells per axis holds, as--modulationdoes. 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 --vibrationhas one block per species (Sc F/8 24instead ofSc F Sc F ...). Tested in section 34.New:
crystod-phonon --modulation --qpointand--qpointNaccept special-point labels (e.g.--qpoint R), resolved as in--vectorand--subgroup. Tested in section 33.Fixed:
crystod-phonon --irrepshonours-o: the YAML file is written to the given path instead ofphonon_irreps.yaml. Tested in section 28.Fixed:
crystod-phonon --vibrationrejects several--amplitudevalues 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
quietofSymmetryOnlyVibrations, which suppresses the primitive-cell note on stdout.gamma_mode_activitiesand thecrystod_phonon_activityMCP 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-maguses--tolerancefor 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-magrefuses 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--conventionalthe conventional magnetic cell is checked as well. Tested in sections 36 and 37.Fixed:
crystod-magrejects a non-primitive input cell with the same one-line ERROR in survey mode and--qpointmode (survey mode crashed with a ValueError traceback). doc/crystod-mag.md states the primitive-cell requirement. Tested in sections 37 and 38.Fixed:
crystod-maglists 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 --adpin 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 CIFU^ijwithM = 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 --adpno longer claims relations the projector does not impose (for exampleU13=0in a bct primitive cell, orU12=0on a two-fold axis along a in a hexagonal cell). Sites constrained only by relations such asU12=U22/2now readgeneral linear constraints only. Tested in section 39.Changed:
crystod-md --adpuses--toleranceas 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_operationsandbuild_symmetry_projectortake an optionallattice=keyword for this. Tested in section 39.Fixed:
crystod-md --adpreports 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 --adpprints theUeqof the tensor written to the CIF, so the two always agree. Tested in section 39.Changed: the CIF written by
crystod-md --adpopens with the comment line# generated using crystod-md --adpinstead of the retired mode namecrystod --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 --diagramprints 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 --diagramreport prints ligand SALCs of d and f ligand shells with d/f component names (3dxy, 3dz2, …). Tested in section 44.Fixed:
crystod-xrd --parentfor 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 ofhigher order; both summaries list the pair with its one amplitude, a note says so, andKPointSummary.sharednames the other star. The symmetry-mode entry of such a pair now haspartner_kname/partner_kvec. Tested in sections 23 and 47.Fixed:
crystod-xrd --parentandcrystod-group --supergroup-cifrefuse partially occupied or mixed-site CIFs with an ERROR naming the first disordered site, instead of an AttributeError traceback fromsite.specie. Tested in sections 23 and 46.Fixed: crystod-mcp converts a
SystemExitorKeyboardInterruptraised in a tool body into an error result inside the worker thread, so that bad input such ascrystod_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_activityno longer reach the stdio protocol stream. Tested in crystod-mcp/tests.New:
crystod-group --cif-axis -c FILElists every axis setting of the space group of a CIF or POSCAR, andcrystod-group --cif2poscar -c FILE --spacegroup-set SETTINGwrites 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-settakes the symbol, the No. of the table or spglib’s choice string (Amam,4,-cba;b2,2,Rfor 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-cifprints 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 ofPare 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 originpin 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 savedsym_mode_<formula>now starts with this block, followed by the table as before. Python:SymmetryModeAnalysis.setting_transformation(frame="input" | "standard")returns aSettingTransformation(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-onlyprints the structure, the decomposition and that table only. The table names every component by the tag of its VESTA file (x_2for a repeatedx), 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 ak_x k_yspin splitting allowed by symmetry; the Cr2O3 order gives R-3’c’ withalpha_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 thecomp<N>entry below. Python:crystod.mag.analyze_spin_basis,magnetic_space_group,macroscopic_responses,classify_collinear,magnetic_summary_rows; MCP toolcrystod_mag_classify(17 tools). Test section 37; exampleexample/37_magnetic_group; doc section 37.Fixed:
crystod-magat 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):nanspins, “AFM” basis vectors with a nonzero net moment, partners along 45-degree mixtures of the symmetry directions (both partners of a copy taggedx), 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, ascrystod-phonon --vibrationdoes 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-magmerges 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 thatcrystod-group --parentprints (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 partnerscrystod-phonon --vibrationgives 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,xandyof a standard cell in tetragonal, trigonal and hexagonal crystals alike (P3 HgBrGM2GM3, P6/m Nb7B8Ru6GM4+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_labelslists 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). TheWARNINGlines, the classbasis not separated,SpinBasisComponent.unseparated,SpinBasisAnalysis.unseparated_labelsandmagnetic_group.CLASS_NOT_SEPARATEDare gone with the failure they reported. Over the 228 POSCARs ofexample/test_POSCARs(--qpoint GM --classify-only, first element) the structures with aWARNINGor 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-magat 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 factorexp(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 factorexp(2 pi i q.T)of the cell alone, which is right only whenexp(2 pi i q.x_j)is the same for all magnetic sites. The vectors are now taken in the lattice gaugew_j = v_j exp(2 pi i q.x_j), as incrystod-phonon --modulation, and the spin of site j in the cell at T isRe(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 ofcomp1(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>ofcrystod-magcount 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 readscomp<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.vestamust open..._comp1.vestainstead. 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 ofcrystod-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 ofcrystod-phonon --modulation(the AMPLIMODES amplitude of an irrep in--supergroup-cifissqrt(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 comparessum <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.3projects 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(aTrajectoryProjection),format_projection,commensurate_qpoints. Test section 40; exampleexample/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 ofcrystod-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 prefixMDPROJ_<formula>_phonon. The parent cell is the primitive cell of the yaml (-cis optional and must then be that cell).--temperature Tadds 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--projectis unchanged. Testsuite section 40 gains 26 checks; documented in section 40 ofcrystod-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 ofcrystod-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^-Tfor 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,GMfor 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 carryI_childandI_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 reproduceXRDCalculator(SrTiO3 I4/mcm, CaTiO3 Pnma) andNDCalculator(ScF3) to 1e-6. SrTiO3 Pm-3m -> I4/mcm: 17 superlattice families, all(o o o)/2at 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 *; filesXRD_<child>_vs_<parent>_<xraytype>.txt/.pdf(ND_..._<W>Afor neutrons), the PDF overlaying parent and child patterns with the superlattice ticks coloured by k star. The plaincrystod-xrd -c POSCAR --radiation neutron --wavelength 1.5runs pymatgen’sNDCalculator(nuclear scattering only) and writesND_<cell>_1.5A.txt/.pdf;--xraytypewith neutrons and--wavelengthwith X-rays are refused, the X-ray output is unchanged. Python:crystod.xrd.superlattice_reflections(aSuperlatticePatternofSuperlatticeReflectionrecords withKPointSummaryper star),format_superlattice_pattern,write_superlattice_table,plot_superlattice_pattern,radiation_lines, andcompute_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 readshigher order;--min-intensitytrims the table only, never the k-point summary. Test section 47; exampleexample/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, theexample/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-7crystod, 8-24crystod-group, 25-27crystod-bz, 28-35crystod-phonon, 36-38crystod-mag, 39-41crystod-md, 42-44crystod-mol, 45 Python API, 46-47crystod-xrd, 48crystod-search. Sections 1-36 keep their numbers; for exampleexample/38_xdatcar2adpis nowexample/39_xdatcar2adp,example/41_molodisexample/43_molod(python testsuite.py 43) andexample/45_mp_searchisexample/48_mp_search; scripts that callpython testsuite.py Nor read files belowexample/NN_*with N >= 37 need the new numbers. The commands and their options are unchanged.Changed:
phonon_irreps.yamlandphonon_irreps_all.yaml(crystod-phonon --irreps,--all-irreps) are valid YAML, andcrystod.phonon.read_phonon_irrepsreads them. The degenerate sets of a q point hung directly under itsq_labelmapping without a key, and their band indices and the special-point names were YAML comments, soyaml.safe_loadand other YAML libraries rejected the file and the band indices could only be recovered from the comments. Everyirrepsentry now holds the sets in aband_setslist, each set starting withband_indices: [1, 2, 3](1-based) in place of the- # 1 2 3comment, andspecial_pointsandpath_midpointsname their points withq_label(andsegment) keys in place of the- # GMand- # 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 getsband_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 readband_indicesandq_labelinstead (or callread_phonon_irreps, which returns the file as a dictionary and raisesValueErrorfor a file in the old layout); the shipped example files underexample/28_phonon_irrepandexample/32_phonon_vector/MoS2_P-6m2are 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-orbitalhybridization ofcrystod(* Space group *,* Crystal Orbitals *,* k point (primitive) *,* IrRep Table *,* Atomic Band Irreducible Representations *,* Result *),crystod --visualizewith--element/--orbital,crystod --star-of-k, the crystal-orbital diagrams (--diagramwith the extended-Hueckel,--pyscfand--vaspengines, including* k point <k> *and* Dipole selection rules at <k> *),--band --pyscf,--dos --pyscf,--chk-info,--vasp-setup,crystod-xrdandcrystod-searchprinted 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-tablesurvey, 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 --pyscfand--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,2and3of the R4+ triplet rotate the octahedra about a, b and c, soPOSCAR_I4mcm_1is now the rotation about a andPOSCAR_I4mcm_3the rotation about c (the oldPOSCAR_I4mcm_1is the newPOSCAR_I4mcm_3byte for byte); the space groups are unchanged. Compatibility: a script that readPOSCAR_I4mcm_1as the rotation about c has to readPOSCAR_I4mcm_3;example/40_md_projectionand section 40 of thecrystod-mdmanual 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 ofexample/32_phonon_vector(BaTiO3, MoS2 at M, Sr3Ti2O7, and SrTiO3 with 1-based mode numbers in the file names and titles) and thesym_mode_*files ofexample/23_symmetry_modeare 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/--antisymmetricand--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-mcp0.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+ givesQ1^2 + Q2^2 + Q3^2, no cubic invariant andQ1^2*Q2^2 + Q1^2*Q3^2 + Q2^2*Q3^2; M1+ has the cubic invariantQ1*Q2*Q3. The Python API addscrystod.group.invariant_polynomials(anInvariantBasis) andcrystod.group.landau_lifshitz(the numbers of cubic and Lifshitz invariants, aLandauLifshitzrecord); the enginecrystod.invariants.invariants_of_matricestakes any finite real matrix group. Several--irreplabels 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/mmmX2+ X3- GM5-has the trilinear term of hybrid improper ferroelectrics, Pm-3mR4+ M3+the biquadratic(2, 2)(crystod.group.coupling_terms, aCouplingTerm). With--order-parameter,--invariantsalso prints the free energy restricted to that direction (R4+(a,b,0):a^2 + b^2, thena^4 + b^4; a^2*b^2). With--invariants,--order-parameter,--degreeor--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 Ktable are unchanged.--parent SG --irrep IR [IR2 ...] --order-parameter DIR --secondarylists 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 termQ^m etathat 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- throughQ1^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,SecondaryOrderParameterrecords). 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 ofInducedRepresentationuses 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 toolcrystod_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--parentenumeration (2-10 times, most for large stars).--childlists 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 anote:, 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/mcmgivesR4+ (0,0,a)among ten rows,--child R-3cgivesR4+ (a,a,a), and--child Pnma --size 4reports 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-cacherebuilds it, and a file built from other CrystOD sources is rebuilt. Python:crystod.group.find_isotropy_irreps(IsotropyMatchrecords) andcrystod.group.isotropy_table(anIsotropyTable). 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 Wtakes about 50 s instead of about 530 s.enumerate_directions(method="legacy")keeps the pairwise closure for comparison.--coupledsearches 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 --coupledgives the tilt systemR4+ (0,a,a)+M3+ (d;0;0)among 32 rows (about 10 s), I4/mmm--child Cmc2_1X2+ (0;a)+X3- (0;c), Cmcm--child Pna2_1Y4++Y2-;--secondaryadds the secondary order parameters of every row, and 50 seeded rows of the HIF survey are all recovered with their strata.--graphwritesSUBGROUP_<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-dotalso writes a Graphviz.dotfile.--parent Pm-3m --irrep R4+ M3+ --graphcontains 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(CoupledIsotropyMatchrecords; alsofind_isotropy_irreps(..., coupled=True)) andcrystod.group.subgroup_graph(SubgroupGraph,GraphNode,GraphEdge). Tests in sections 19 and 20; examples inexample/19_child_lookupandexample/20_subgroup_graph. The MCP server gains the toolscrystod_find_isotropy_irreps(the single-irrep and, withcoupled=true, the coupled strata of type H as Markdown tables, from the same cached isotropy table) andcrystod_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)givesGM1+ [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 + B2gfrom R4+ andAgplus 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--kpointname 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(Subductionrecords),compatibility_relations(Compatibilityrecords),format_subduction,format_compatibility,correlation_table(aCorrelationTable),format_correlation_table. Tests in a new section 16; example inexample/16_correlate. The MCP server gains the toolcrystod_correlate, which takes the arguments of exactly one of the three forms (point_groupandsubgroup;space_groupandkpoints;parent,irrepsanddirection) 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, andcrystod-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 + T2gand* 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--sgthe square of a full irrep is reduced from the characters(chi(g)^2 +- chi(g^2))/2of the order-parameter matrices of--parentinto the irreps at the stars ofk_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 formD + D*(P1P3of I4/mcm, with anote:line); the identity irrep of the symmetric square equals the number of quadratic invariants of--invariants.--jahn-teller Eg --pg m-3mprints[Eg x Eg] = A1g + EgandJT-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(aJahnTellerModesrecord) andSpaceGroupIrrepAlgebra.decompose_square(aSquareDecomposition). 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 isdielectric,pyroelectric,piezoelectric,elastic,compliance,gyration,ramanor 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_iLwith the factor 2,s_LMwith 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.--sgtakes the point group of the default setting,-cthat of spglib’s standard conventional cell, with the tensor axes printed in the input frame.--tensor ramanlists the Raman tensor of every Raman-active irrep (Mulliken labels; with-c, the Γ phonon irreps with ISO-IR labels, ascrystod-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 toolcrystod_tensor_form(kindand one ofpoint_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 isallowed (x, y, z),allowed (z)orforbidden(Γ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 thecrystod-phonon --raman-tensortensors); 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--vaspengine 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 FILEkeeps 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 (newcrystod.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-referencelists the compatible scalar levels, Γ × D(1/2)). Outputs:CrystOD_<cell>_vasp_overlap.html,.jsonand.txt(_socfor spin-orbit runs), the report’s Key results also in the terminal.--vasp-setup --vasp-engine overlapwritesLWAVE = .TRUE.and checks that the crystal bands reach VBM + 17 eV. On the SrTiO3, SrGeO3, CsPbI3 and CsPbI3 + SOC runs ofexample/03_hybridization/vasp_overlapevery energy, population, COHP and ledger value agrees with the reference analysis; the default--vasp-engine anchoris unchanged.New: IR / Raman / silent / acoustic activity of the Γ phonons in
crystod-phonon --irrepsandcrystod-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.--irrepsadds anactivity: [...]line to every degenerate set at GM and anactivity_summary:line to the GM block ofphonon_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 GMaddsactivity = ...to every mode space, the same summary (the acoustic count from the vector representation) and anactivitiesarray 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 addscrystod.phonon.gamma_mode_activities(from a phonopy object or a structure),classify_gamma_irreps,format_activity_summaryand theActivityrecord, andPhononModegains anactivityfield (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--toleranceno longer changes the summary. With--nac,--irrepsalso 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 asdielectric_electronic:/dielectric_static:header lines andmode_effective_charge:/dielectric_contribution:lines per Γ set inphonon_irreps.yaml; an imaginary optical mode with a dipole is flagged, since it makes eps_0 meaningless. The new--raman-tensor(with--irrepsor--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 GMbreaks 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_tableand the recordsRamanTensors,WyckoffOrbit,DielectricResponse,DielectricSet. The MCP server gains the toolcrystod_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--irrepsterminal summary and Raman tensors is followed by its Mulliken symbol in square brackets (GM4- [T1u]), andphonon_irreps.yamlgains amulliken:line afterirrep_label:in every Γ set (A1 + Efor 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,Eof 3), APIcrystod.phonon.mulliken_symbols. The output ofcrystod-phonon --vibrationis 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-indexhint; the q-point list is the set of ISO-IR special points that--irrepswrites underspecial_points:(no seekpath names such asGAMMAorH_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.yamlmay list them in another order), with fraction coordinates ((1/3, 1/3, 1/2)), and--qpointtakes those names (the seekpath names andGAMMA/G/Γare still accepted). Tests in a new section 29.Changed:
crystod-phononreads the BORN file only with--nac. phonopy’s loader applies the non-analytical term correction by default and silently read aBORNfile lying in the working directory (or the NAC parameters stored in a phonopy yaml) in--irreps,--vector,--modulationand--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. Allcrystod-phononmodes that read force data now take--nac, apply NAC only with it (BORN from the working directory,--modulationalso 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--nacfinds none;phonon_irreps.yamlrecordsnac: true/nac: falsein its header. Without--nacthe results are those without NAC whatever files are present (the special-point labels and frequencies of--irrepsare the same either way); the MCP tools never apply NAC, andSymmetryAdaptedModulation(yaml_path=...)loads the yaml without NAC (pass aphononloaded withis_nac=Truefor it).--vibrationrejects--nac. The error of--nacwithout a BORN file names every directory that was searched (for--modulation, the working directory and the directory of the cell file).Fixed:
crystod-group --productand--basiscounted a complex-conjugate pair of point-group irreps twice. The character tables list such a pair as one real irrep (Eof 3, 4, 6, -4, 4/m,Egof m-3, …), whose character has norm 2, and the reduction divided by the group order only:--product E E --pg 3gave2(A) + 2(E)(dimension 6 for a 4-dimensional product) and--basis x y z --pg 4gave1.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 -4gave1.0 [E], now1.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-fieldand--multipletcounted 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 pairsEof 3, 4, -4, 23,E1/E2of 6,Egof m-3, …).--ligand-field d --pg 4gave1(A) + 2(B) + 2(E)(7 orbitals for a d shell), now1(A) + 2(B) + 1(E);--decompose --pg 4 --characters 2 0 -2gave2(E), now1(E);--multiplet E2 --pg 3gave^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 dstopped 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 -4printed1S4: -1,2C2: 1and gave2(A) + 2(B) + 2(E), now2S4: -1,1C2: 1and1(A) + 2(B) + 1(E)(the--decompose --pg -4prompt had the same wrong sizes).--multiplet A2 --pg 1(also with--orbital s --visualize) no longer stops with anIndexError. The same reduction gives theGamma =line ofcrystod-mol --xyz ... --element ... --orbital ...(the H p orbitals of a C3 molecule with three H sites:3(A) + 6(E), now3(A) + 3(E)) and the results of the MCP toolscrystod_decompose_representationandcrystod_ligand_field; the note ofcrystod_ligand_fieldfor these point groups now says that1(E)is one doubly degenerate level (it said2(E)), and the non-integer check ofcrystod_decompose_representationdivides 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.decomposetakes 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 FILEstopped withKeyError: 'electrons'on every checkpoint--pyscfwrites. The checkpoint stores the oxidation states but not the electron count (--electronsonly fills the diagram’s levels, so it is deliberately not part of the stored conditions);--chk-infonow prints the oxidation states and the SCF convergence settings, still prints the electron count of a file that has one, and leaves--oxidationout of the reuse string when none is stored. Tested in section 7.Fixed:
crystod-group --coset --pg G --subgroup Hexited with code 0 when H is not a subgroup of G in the tabulated axes. It printed the* Groups *block and a multi-lineERROR:message; it now stops with oneERROR: ...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 --sgdid 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 --vaspread a spin-orbit run as a scalar one. Avasp_nclrun (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 --vaspcould 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 aMETAGGA = LAKrun the semicore overlap came out 4e-16 below 1 and the rigid cation-column shift —--vasp-align rigid, and thediagnostic, the RIGID alignmentline 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 Rthe +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--pyscfengine (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 fixtureexample/03_hybridization/vasp_SrTiO3_LAK.Fixed: a meta-GGA VASP run was labelled “PAW”.
crystod --diagram --vaspread the functional from theGGA =line of the crystal run’s OUTCAR only, and a meta-GGA run writes none — its OUTCAR names the functional on aMETAGGA = LAKline — so the report saidfunctional PAW, the page chipVASP PAW/PAWand the level JSON"functional": "PAW". TheMETAGGAtag now wins (LAK,SCAN,R2SCAN, … as VASP spells it, in upper case) and theGGAtag is the fallback (PEis still shown as PBE); theMETAGGA= Fflag VASP 5 writes into every run is not taken for a functional.crystod.vasp_io.read_outcaralso 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 ofcrystod --diagram --vasp) scaled the lattice and left Cartesian coordinates as written. phonopy 4.3.0, which read every-cfile and the unit cell of everycrystod-phononmode, 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 --poscar2cifand--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 --irrepswrotespace_group: R3mwith the points GM, F, L, T and exit status 0;--subgroup --qpoint Ranswered that the group has no point R); with Cartesian coordinates under a negative scalecrystod-group --poscar2cifwrote an R3m CIF with a = 5.5793 for the cubic 3.9451 Å cell andcrystod-xrdthe 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-setupon 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--vaspdid; 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_poscartakes 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_cellgives the phonopy cell behind every-cfile and behind--irreps,--fatband,--lt,--vector,--subgroupand--modulation(which now hand the cell, not the file name, tophonopy.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_structurecorrects 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--vaspengines and the phonopy-based commands;crystod-xrd,--poscar2cifand--supergroup-cifstill 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’sread_vasp/read_crystal_structurefor 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 incrystod-mcp/tests.New:
crystod-group --parent SG --kpoint Klists the isotropy subgroups of every irrep of a k point in one table.crystod-group --parent Pm-3m --kpoint GMprints 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--irrephad 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--irreptable, and the enantiomorph note is collected under it. The k point is an ISO-IR name (GM,R,X, …; the case is ignored andG/GammameanGM) or three coordinates in the primitive reciprocal basis: any arm of the star and anyq + Gspelling resolve to the tabulated point (--kpoint 0.5 0.5 0.5,-1/2 1/2 1/2andRgive the same table;0 0.5 0.5is M). Decimals within 0.0005 of a special point are taken for it (0.333is 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 SGgiven neither--irrepnor--kpoint; an irrep label given to--kpointis answered with its k point and the--irrepform;--kpointis refused together with--irrepor--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--irreptable 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 anote: 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 incrystod.phononand at the top level) returns the same table as aKpointIsotropySubgroupsmapping from irrep label toIsotropySubgrouprecords, 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(andcrystod.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 K2printedK2K3for what isK2KA2,--parent I4/mcm --irrep P2printedP1P2forP2P4,--parent P6_3/m --irrep H4printedH3H4forH4H5. 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 theIRcolumn of the ISOSUBGROUP reference table of its k point whereverSUBGROUP/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 P2now 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,--vibrationandcrystod-magcould 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)--vibrationnow 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-irrepslabels 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), andcrystod-magon 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-, andcrystod.phonon.label_phonon_modeslabels 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,--productand--kpointnow 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--parentlists for it the subgroups ISOSUBGROUP lists under the same name:--parent I4/mcm --irrep P2gives P2P4 with Immm, Imma, I-4m2 and Imm2 (v0.4.2: P1P2 with Ibam, Ibca, I-4c2 and Iba2),--parent Ia-3d --irrep N1lists 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 thatSUBGROUP/VALIDATION.mdlisted, also where the labels already agreed, as for Y of Cmce) is gone;script/validate_isosubgroup.py 62 230gives 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-42dgivesPA1(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 --vibrationnames the P irreps of I4_1/a (88_PPOSCAR_ZrGeO4) P1 … P4, where v0.4.2 printedirrep_1…irrep_4;crystod-magon 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 (
PA1is the conjugate ofP1) in every command, the namescrystod-group --product(M1 x P1 = PA1) and--parent(P1PA1) use. v0.4.2 printedirrep_Nlabels and the name of a line through the point:crystod -c 82_PPOSCAR_AlPO4 --element Al --orbital p --kpoint -0.25 -0.25 -0.25printedQandirrep_2(1), …, and now printsPAand1.0 [PA2(1)] + 1.0 [PA3(1)] + 1.0 [PA4(1)];crystod-phonon --vibrationat that q selectsPAwith the spaces PA1 … PA4;crystod-group --table --sg 82 --kpoint -0.25 -0.25 -0.25prints the namePAand the rows PA1, PA4, PA2, PA3 (v0.4.2: an unnamed k point withirrep_Nrows). 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 (
crystodand--atomic-orbitalwithout--kpoint,--diagram,--visualize,crystod-phonon --irreps,--vectorand--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 printedPabovePA1 + 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_AlPO4shifted by (0.0731, 0.1593, 0.2417) listsP [-0.25, -0.25, -0.25]with Al pP1 + P2 + P3,--kpoint Panalyzes that point, and--kpoint 0.25 0.25 0.25printsPAabovePA1 + PA2 + PA3(before:P [0.25, 0.25, 0.25]above the PA labels, also for--kpoint P);crystod-phonon --vibration --qpoint PselectsP = [-0.25, -0.25, -0.25]with P labels and--qpoint 0.25 0.25 0.25selectsPA(before:PabovePA2). A 2x2x2 supercell of143_PPOSCAR_HgBrwith its atoms sorted by species, which spglib re-bases to (-b, -a, -c), listsHandKwithH1 + H2 + H3andK1 + K2 + K3as the cell does (before: aboveHAandKAlabels). The seekpath names of--vibration,crystod-mag --qpoint,--star-of-kand--visualize --kpointare 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, notH); the endpoints of the--irreps --all-irrepsk-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 seekpathZof1_PPOSCAR_RbBe2F5is (-1/2, 0, 0), labelledX1, the ISO-IR Z ofcrystod --kpoint Zis (0, 0, 1/2). The MCP toolscrystod_phonon_irrepsandcrystod_crystal_orbital_irrepsname, survey and resolve their k points the same way (before: the table’sP (1/4, 1/4, 1/4)abovePAlabels, andkpoint="P"analyzed the table’s point);kpoint=NAMEof the crystal-orbital tool now reports the armcrystod --kpoint NAMEanalyzes (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_qpointnames coordinates by the labeller first when givenisoir_context, andPhononMode.qpoint_labeloflabel_phonon_modesis 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 incrystod-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, DT5at (0,0,7/12) of P6_3), whilecrystod-group --productand--supergroup-cifnamed the star of the smaller canonical representative through -k with anAsuffix (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= conjLD1, 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/12printsDUwithDU2, DU1, DU6, DU5, DU4, DU3, the conjugates of DT2, DT1, DT6, … at (0,0,5/12);--product P1 X1 --sg I4givesLD1 + LD2 + LE1 + LE2(before:LDA1 + LDA2); the -k partner of the line P (K-H) of P3 isPC(before:PA), while both signs of the parameter of P itself keep the name P; the general point of I-4m2 pairs asGP1GQ1in--supergroup-cif(before:GP1GPA1). Over 1597 (group, type, parameter) cases of lines, planes and general points with a partner (138 groups) the names of--productequal 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) andcrystod-mag --qpointstopped with “expected at least one argument”: argparse takes-0.25for a number but-1/4for an option. The lists of special points print negative coordinates for inputs outside the ISO-IR setting, so a negative fraction after--kpointor--qpoint(or an abbreviation argparse accepts,--kp) is now read as a coordinate (crystod-group --kpointalready 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_kreturns these parameters. Before, the label could depend on the arm or copy given:crystod-group --table --sg 216 --kpoint -0.25 -0.25 0and--kpoint 3/4 3/4 0printed 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/2printed unnamedirrep_Nrows and now prints T with T1+, T1-, … . Tests in sections 24 and 43.Fixed:
crystod-group --parent 218 --irrep R4(andR5) stopped withnumpy.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 218passes all 16 tables of P-43n), and--parent 218 --kpoint Rlists R1R2, R3 and R4R5 without anot enumeratednote. This fix leaves the--irreptables 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 hitcrystod-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_symmetrynow 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 Wnow 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 Wthe 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 reportsW1(2)at W of both groups. Tests in section 17.crystod-group --parent SG --irrep IR --order-parametertakes the directions as the tables print them.--order-parameter a -a 0stopped withunrecognized arguments: -a 0, because argparse took-afor an option, so a direction such asM3+(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-parameterup to the next--optionis now a component, in the command and in the isotropy module’s own parser:--order-parameter a -a 0givesM3+(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.5awas 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 rulecrystod.group.isotropy_subgroupsalready applied. Tests in section 17.Fixed:
--order-parameterwith more than eight free parameters gave a too-high subgroup. The values given to the parameter letters repeated after eight (iequalleda,jequalledb, …), 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_labelreturns, 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)gave0.2929 (1,1,1): forL1+(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 DIRand--no-files. The symmetry-mode analysis writes the decomposition tablesym_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 DIRwrites them intoDIR(created if missing; the printed paths include it), and--no-filesprints 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-dirthat names an existing file is refused before the analysis starts.crystod.group.SymmetryModeAnalysiswrites 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+,B1BA1when 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 savedsym_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-cifstopped 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. ANOTEwith 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--toleranceadvice 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-xrdstopped withValueError: too many values to unpackon every hexagonal cell. pymatgen’sXRDCalculatorindexes 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.Peaknow 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) raiseValueError. Tests in section 44 (ZnO and the hexagonal AlF3 cell through the command, andPeakgiven 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) andcrystod-group(--product,--table,--basis,--generate-basis,--coset,--poscar2cif,--cif2poscar,--supergroup-cif,--decompose,--ligand-field,--multiplet) is laid out in blocks with* ... *headers.crystod-bzprints* Structure *(or* Band path *for a manual--band) and* Recommended k-path (seekpath) *with thePath: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-searchlists the result table under* Materials *below the query block (--get MPIDkeeps it directly under the title); the written-file notices ofcrystod-bz,crystod-xrd,crystod-mol --visualizeandcrystod --visualizeare collected in a final* Output files *block (one block for all pages whencrystod --visualizescans 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-orbitaland--star-of-kmodes ofcrystodandcrystod-bz --show-kpointalready had this layout and are unchanged. The level viewers ofcrystod --visualize(extended Hückel without--element/--orbital, and--pyscf) print* Extended-Hueckel levels *(or* PySCF levels *and* Energy reference *) and list oneGM: 5 levels (14 partners) -> pageline per page in* Output files *, without the summary line of page names and without repeating the primitive-cell notice; with--pyscftheSCF saved to FILE.chk (...)notice is listed in* Output files *too, not inside* PySCF levels *. Incrystod-group, every mode starts with a blank line before its first block (the point-group--product,--tableand--basisdid not);--productand--basiswith--show-irrep-tableprint the* Point group *block once,--basisputs the* IrRep Table *after the group and k-point blocks, and--basis --sgwithout--kpointnames the special points in a* Special k points *block;--generate-basisprints the group blocks once and titles every block of an order with the order (* Decomposition: 2nd order (quadratic) *) instead of the====banners;--cosetprints its headers without the leading space and without the blank lines inside the blocks;--poscar2cifand--cif2poscarprint* Structure *and* Output files *(Bilbao-style CIF written to: ...,POSCAR written to: ..., with(existing file overwritten)in place of theNOTE: overwritingline);--supergroup-cifadds a* Distortion amplitude *header above the maximum-displacement lines and moves theDecomposition table saved to ...line and the VESTA file list into a final* Output files *block; the space-group--productprints the DIRPRO reference after the--symmetric/--antisymmetricblocks;--decomposeand--ligand-fieldprint the class characters directly under their* Reducible representation ... *header,--multipletkeeps the state-countcheck:line inside the* Term Symbols *block and moves the--visualizefile notice into a final* Output files *block (with a two-space indent), and its HTML viewer is unchanged. The--exampleruns print no blank line of their own afterRunning: ..., since every command now opens with one, andcrystod-phonon --vector,--modulationandcrystod-magtitle the q-point block* Selected Q point *, as--vibrationdoes.Changed: the terminal output of
crystod-phonon(--irreps,--fatband,--lt,--vector,--modulation,--subgroup),crystod-magandcrystod-md(--adp,--summary) is organised in titled blocks with* ... *headers, ascrystod-phonon --vibrationandcrystod-group --parentprint it.--irrepsprints* Gamma-point activity *(one label per line, as--vibration),* Gamma-point dielectric response (Born effective charges from BORN) *with--nacand* Raman tensors (Cartesian axes of the input cell) *with--raman-tensor;--fatbandand--ltprint* Structure *,* Band path *and* Projection *(with--projection-direction);--vectorprints* Structure *,* Available high-symmetry q-points *,* Selected Q point *(the title--vibrationuses),* Phonon modes at q = ... *and* Displacement patterns *;--modulationprints* 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 *;--subgroupadds the* Order parameter directions and isotropy subgroups *header ofcrystod-group --parentabove each table;crystod-magprints* Structure *,* Selected Q point *,* Spin (axial-vector) representation *,* Symmetry-adapted spin bases *,* Magnetic cell *and one* <irrep> [<kind>] *block per basis (the survey without--qpointlists every k point in one* Spin (axial-vector) Irreducible Representations of <El> sites *block);crystod-md --adpprints* 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 --modulatenames its files in the* Distorted structures *rows). Every data line keeps its numbers and, apart from the following, its text: the--irrepsGamma summary is split one label per line, thecrystod-magfile notices readSpin basis written to: ..., its survey prints onek point (primitive): <name> <k>line per k point, and theGenerating modulated structure...progress line of--modulationgives way to the* Modulation *header. Every output file (phonon_irreps.yaml,phonon_modes_*.txt, VESTA, MPOSCAR, PDF, CIF) is unchanged;crystod-md --adpno longer repeats theAsymmetric-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, theexample/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-7crystod, 8-24crystod-group, 25-27crystod-bz, 28-35crystod-phonon, 36-37crystod-mag, 38-39crystod-md, 40-42crystod-mol, 43 Python API, 44crystod-xrd, 45crystod-search. For exampleexample/13_isotropy_subgroupis nowexample/17_isotropy_subgroup(python testsuite.py 17),example/21_phonon_irrepisexample/28_phonon_irrepandexample/37_mp_searchisexample/45_mp_search; scripts that callpython testsuite.py Nor read files belowexample/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 inROOT/BANDand the two sublattice runs inROOT/BAND_sublattice*(DIR/bandwhen it carries thePROCAR; 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 DIRoverride the search. A sublattice run keeps one sublattice and replaces the other byVa<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--vaspitself needs only the output files. The companioncrystod --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=NAMEchoosing a variant), INCAR withLORBIT = 12and noNELECT, 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 complexLORBIT = 12projections come fromPROCAR; 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(defaultE − E_VBM);--vasp-align rigidfalls back to one shift per column (its numbers are printed as a diagnostic in either mode),--vasp-anchor EL nlpins a column on a chosen shell and--no-alignkeeps 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.htmlthrough the usual writer, aCrystOD_{cell}_vasp_levels.txtwith every number (per-level shift and the full anchor table included), a machine-readableCrystOD_{cell}_vasp_levels.jsonwith 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 modulescrystod/vasp_io.pyandcrystod/crystal_orbital_vasp.py; documentation: crystod. Tests in section 3, run offline againstexample/03_hybridization/vasp_SrTiO3andexample/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-setupwritesVACSIGMA 0.5,VACRWALL 0.45andVACWALL = 2.5 q e^2 sqrt(2/pi)/sigma, one height perVaspecies so the charge scaling stays automatic; the new--vasp-sigmaand--vasp-wall-factorchange the first and the last, and--vasp-rwalldefaults 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 radiusr10 = 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/rwell (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 atr10 = 0.99 Aforq = +2and 1.13 A forq = +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 shippedexample/SrTiO3_Pm-3mandexample/ScF3_Pm-3msublattice 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 agreewhen 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-onlyuses 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 defaultVBM + 10 eVand 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.--vaspnow 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 noVaspecies; 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).-cis 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 withcrystod -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, withVaatoms mapping onto the removed ones. A-cfile 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 withERROR: ./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-cfile 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, titledSrTiO3, Pm-3m; an ordinary-cfile keeps theCrystOD_{cell}_vasp.htmlconvention of the other engines. If the-cfile 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-setupfollows the crystal run, not the-cfile:-cis optional there too (without it the structure isROOT/BAND/POSCAR), and the POSCARs it writes are nowROOT/BAND/POSCARwith one sublattice renamed toVa<q><sign>— its lattice, its origin and its ion order, line for line — with the-cfile only naming the fragments and the formal charges; it used to write them in the-csetting, so a shifted-csilently 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 theINCARthat was actually run.example/03_hybridization/vasp_SrTiO3gained the Sr-originPOSCAR-finishof those runs and a README; tests in section 3.New command
crystod-xrd: powder X-ray diffraction patterns.crystod-xrd -c POSCARprints 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’sXRDCalculator.--xraytypeselects the radiation: a Kα doublet (CuKa, the default, andMoKa,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-profiledraws Lorentzian (default) or Gaussian peaks, both normalized to unit area so the two figures share one intensity scale;--width,--two-thetaand--min-intensityadjust 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 formerscript/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 domaincrystod.xrd(load_structure,compute_xrd_pattern,smear_pattern,write_peak_table,plot_xrd_pattern), andcrystod-xrd --example ScF3/--example SrTiO3run 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 inexample/36_xrd_pattern(nowexample/46_xrd_pattern).New command
crystod-search: search the Materials Project and download POSCAR files.crystod-search SrTiO3lists 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-Ofor 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,--excludeand--subsystems(a chemical system with all its subsystems), with--sortand--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-5532writesPOSCAR_Sr2TiO4_I4mmm_mp-5532into the current directory, and a bare--getafter 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 ofcrystod, the download as I4/mmm);--cell primitivewrites the standardized primitive cell asPPOSCAR_Sr2TiO4_I4mmm_mp-5532instead (7 atoms; the SALC analysis gives the same result for either file), so the two cells of one material never overwrite each other;--directorywrites{formula}_{space group}_{ID}/POSCAR(PPOSCAR),-onames 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 tomp-3347529, letters above), and both spellings are accepted. The client talks to thematerials/summaryendpoint of the Materials Project REST API withrequests, now a dependency; the free API key is read fromMP_API_KEYor fromPMG_MAPI_KEYof the pymatgen settings file, and a missing, legacy or rejected key stops with a one-lineERROR:that says where to get one. The Python form is the new API domaincrystod.search(search_materials,fetch_materials,write_poscar,normalize_material_id, …), andcrystod-search --example SrTiO3/Sr-Ti-O/mp-5229run 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=1adds one live search); worked example inexample/37_mp_search(nowexample/48_mp_search).Fixed:
crystod-phonon --modulationcrashed 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--modulationand--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 everyq + Gspelling constructs, andq + Gfreezes the same structure asq.Fixed:
--modulationfroze the mass-weighted eigenvector instead of the displacement, with an arbitrary phase. The frozen-in field is now the eigen-displacemente_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 ownMODULATIONwrites, 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).--amplitudeis 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 3of the R4+ triplet of ScF3 rotate about a, b and c; the Si Γ triplets are x, y, z, and the Si--vectorexample 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 --modulateand the error paths.--vectorshares 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 --modulatewrites 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).--subgroupno longer lists the acoustic modes at Γ (rigid translations) when--thresholdlies 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 toprimitive_matrix="auto"; a construction that fails ends in oneERROR: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_vectorsnow holds the freezing vectors above (with 1/sqrt(m), normalized over the primitive cell), the new attributeeigenvectorsthe phonopy-convention eigenvectors;get_commensurate_supercell_sizesraisesValueErrorfor an incommensurate q;crystod.symmetry_adapted_modes.NonPrimitiveCellError(aValueError) is new.Structures written by
--modulation,--subgroup --modulateor--vectorof 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 inexample/25_modulationwere 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 --modulateand 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. ItsIm-3command, 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 --vibrationwrote structures of the wrong symmetry. The symmetry-only command froze the raw spgrep projected row asRe(row_j exp(2 pi i q.R)): the Bloch factorexp(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--modulationabove. Where the missing factors happened to be equal on all atoms of the pattern (ScF3 at R written0.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 0one 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--modulationwith 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--modulationuses, 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--amplitudeis 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 pointsq,q + Gand-qwrite 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--modulationmode 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-npzdisplacements and the printed displacement lines change. Python API: the newSymmetryOnlyVibrations.get_symmetry_adapted_spacesreturns the partners in the order ofdescribe_mode_spaces, andget_supercell_displacementsnow appliesexp(2 pi i q.(R + x_j)), so a projected row given to it gets its per-atom factor as well. The shippedexample/26_vibrationfiles were regenerated (the same I4/mcm; component 1 of R4+ is now the rotation about a, the structure--modulation --mode 1writes) 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,--vectorand--vibrationalike). 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 (--vibrationon P-4 MnZnGa4Se8 at Γ, spelled0 -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,--vectorand--subgroup --modulateruns of the reported Cmcm and SrLi2Nb2O7 cases, Sr3Ti2O7, ScF3 and Si write the same files as before.
v0.4.1#
crystod-group --parentis now the primary spelling of the isotropy-subgroup command;--supergroupstays as an alias.--supergroup SG --irrep IRsat 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 thereforecrystod-group --parent Pm-3m --irrep R4+ [--order-parameter 0 0 a], named after the value it takes;--supergroup Pm-3mis 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 theGM4-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 CrystODno longer pulls in PySCF (about 500 MB with its dependencies); the quantitative engines —crystod --diagram/--band/--dos/--visualize --pyscfandcrystod-mol --diagram --pyscf— needpip 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--pyscfrun in an environment without PySCF stops with one line that names the install command instead of a traceback, and the API classescrystod.salc.PySCFCrystalOrbitalDiagram/crystod.mol.PyscfDiagramraiseImportErrorwith the same hint (crystod/_optional.py). Thepyscf<2.14cap 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--pyscfpaths fail with the one-line message. New extras:quantum,doc,dev(= quantum + doc + ruff, nbconvert, ipykernel, build, twine) andall.--example NAME: the quick start runs right afterpip install.crystod,crystod-phonon,crystod-molandcrystod-bzgained--example. A few small inputs ship inside the package (crystod/examples/: the ScF3 and SrTiO3 cells, the 4×4×4FORCE_SETSof SrTiO3, CH4 and NH3 — 108 kB in total), and--example NAMEcopies 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.--examplealone 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.--kpointaccepts a high-symmetry label in every mode ofcrystod.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,--visualizeand--diagram. The label is now looked up in the ISO-IR special-point table the survey itself uses — the namescrystod-bz --show-kpointprints (GM,X,M,R;GM,Y,A,V,L,Mfor C2/m), resolved in the spglib primitive basis of the analysis — so--kpoint R,--kpoint Yand--kpoint GM(alsoGAMMA,GandΓ) 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 --visualizeand the--qpointlabels ofcrystod-phonon --vibration/--vector/--modulationtake 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’sCwas 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: theGalias of Gamma hid the genuineGpoint of body-centred tetragonal cells (--qpoint Gon I4/mmm Sr3Ti2O7 now gives seekpath’sG = [1/2, 1/2, −0.018]). Tests in section 6.crystod-phononstops with one line whenFORCE_SETSis missing.--irreps,--fatband,--lt,--vectorand--subgroupreadFORCE_SETS(FORCE_CONSTANTSwith--readfc) from the working directory, as phonopy does; a run from another directory used to die in a phonopyFileNotFoundErrortraceback and now says where the file is expected (only--modulationalso 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.mdandcrystod.molnow 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-Wbuild 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 incrystod-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 inruff.toml), the docs build with warnings as errors (as before), and publish a tagged releasev*to PyPI through Trusted Publishing after a manual approval (publish.yml; the one-time PyPI setup is described in the file).CONTRIBUTING.mddescribes the development setup, the section-number convention (feature N ↔testsuite.py N↔example/N_*↔ documentation section N) and the release recipe.Housekeeping:
*.bakand.DS_Storeare ignored, the duplicated.gitignoreblock is gone,crystod --versionis 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-pythonsaid>=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, andpip install crystodcannot 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 Independentwas 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.9forphonopy.phonon.character_table,sympy>=1.10forhermite_normal_form,spgrep>=0.3.1for the spinor irreps behind--spinor,ase>=3.21because 3.20 silently writes a VASP 4 POSCAR with no element line,pymatgen>=2025.1.9because older releases pull a monty whosezopensignature breaksStructure.from_file, and so on — andCITATION.cffgained thedate-released,repository-code,url,abstractandkeywordsfields it needed for a citation with a year in it (validated with cffconvert).pyscfis capped below 2.14.0, which cannot run a zero-electron cell. 2.14.0 rewrotepbc.scf.khf.get_occasif 0 < nocc < nmo / elif nocc == nmo / else: raise, and a fragment that a GTH pseudopotential fully ionizes — Al³⁺ of AlN keeps no valence electrons — hasnocc == 0, which matches neither branch and dies withFailed 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 Å.
--poscar2cifwarns 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.0001the 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-cifworks 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 --pyscfcaches its SCFs by default, asCHK_{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--chkbeforehand. 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--chkit never blocks a run and never costs one: options that do not match the stored ones (a different--xc,--kmesh, an--onsitefile where fragment columns are wanted, a pre-electron-count-fix checkpoint), a checkpoint left by a same-formula polymorph (rocksalt and wurtzite AlN are bothCHK_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-chkturns the cache off entirely.--chk FILEkeeps the strict contract — that file is the user’s, so a mismatch still aborts with thecrystod --chk-infopointer instead of silently overwriting it.--electronsno longer invalidates a checkpoint (it fills the diagram’s arrows, it is not an SCF input), while the SCF’s ownconv_tol/max_cycle, which do shape the density, are now part of the comparison.--chk FILEkeeps the strict contract — that file is the user’s, so a mismatch still aborts with thecrystod --chk-infopointer 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
--visualizelevels 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--pyscfcross-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
--diagramhover 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--visualizelevels 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-orbitalsketch 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--electronsrequest 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
--multipletconfigurations aborted before printing the ground state (260828 bug report).(t2g)^2(eg)^2,(t2g)^3(eg)^{1,2,3}and(t2g)^4(eg)^2of m-3m/d died withERROR: multiplet-energy coefficient failed to snap to an exact fraction (8.66...)— exit 1, noGround-state Term Symbol. The coupled-parent CI table recovered the off-diagonal coefficients asgram[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 productsc_p c_qthemselves are basis-invariant and rational, so the off-diagonal is now snapped at the Gram level and factored exactly assqrt(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 asradicand * 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.--basislists all 21 GTH basis sets PySCF ships grouped by element coverage — the decisive facts being that onlygth-szv-molopt-srandgth-dzvp-molopt-srreach past Ar (71 elements: H–Rn minus the lanthanides) and that no GTH basis PySCF ships covers La–Lu at all, so--pyscfcannot run on a rare-earth compound (the extended-Hückel engine, which has its own La/Ce/Sm/Gd/Yb/Lu parameters, still can), whilegth-tzvp/gth-qzv2p/gth-aug-*/gth-cc-*are main-group or light-element sets;--pseudolists all 11 GTH pseudopotentials the same way (gth-pbe,gth-pade,gth-lda,gth-hfrevspan H–Rn);--xclists 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, andhf), noting that hybrids want--ke-cutoff 150or more;--orbitalnames the shells it accepts (s–i);--kpointpoints atcrystod-bz --show-kpointfor a space group’s labels. The lists are hard-coded so that--helpstays import-free (no PySCF import for a help screen), and a testsuite check compares them againstpyscf.pbc.gto.basis/pseudo.ALIASso they cannot drift. Also fixed in the same pass: a basis or pseudopotential with no entry for one of the elements now fails withERROR: the basis 'gth-qzv2p' has no entry for Sc.plus the list of sets that do cover the structure, instead of PySCF’sBasisNotFoundErrorfrom deep insidecell.build();--xcis 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 anAttributeErrorinsideget_veffafter 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-qzv2punconditionally, 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 --pyscfmode was affected. PySCF subtractscell.chargeonce 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 makestot_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.chkfiles 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 --pyscfaccepts 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--sigmasays 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 defaultgth-dzvp-molopt-srbasis: 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 ingth-qzv2plands 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-qzv2pwhen 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 --pyscfnow runs one additional PySCF calculation per element: the isolated ion at its formal charge (the same pymatgen-guessed/--oxidationcharges 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.--onsitepages 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 --diagramgained outermost atomic-shell columns — the crystal analogue of the MolODligand-aocolumn. 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 ofcrystod-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 AOsheaders and3F 2plabel; rocksalt AlN at X: the Al 3s fragment level linked to its parentAl 3son-site level).Fixed:
crystod --diagramdeleted 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": 1in 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:--kpointis given in the primitive reciprocal basis throughout CrystOD, and the conventional-cell display now lists both —X [0.0, 0.0, 0.5] (primitive)andX [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--conventionalare 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-cifrun, 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--poscar2cifoutput as the IUCr_chemical_formula_sumfield ("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
--dimincrystod-phonon --modulationdepended on the phonopy version — older phonopy raisesValueErrorfor a supercell that does not match the force data, phonopy 4 anIndexErrorfrom the site-symmetry lookup, which escaped as a raw traceback. Both are caught now.crystod-group --supergroup-cifsupports 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_realand every other pre-0.3.6 import path works unchanged, and the command line is untouched apart from the new--subgroupmode below. Attribute access is lazy (PEP 562), soimport crystodplus 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 thecrystod-group --supergrouptable asIsotropySubgrouprecords (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), returningPhononModerecords with 1-based band indices;crystod.phonon.imaginary_mode_subgroups(phonon, qpoint)andscan_imaginary_modes(phonon)combine the two into the symmetry-lowering step of a structure search. Bad input raisesValueErrorrather 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_modesrecord such a level inerrorswith an emptysubgroupsand 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.pyread the version throughimportlib.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 ofpyproject.tomlwhen the package is not installed.crystod-phonon --modulationruns from the files you already have. A unit cell plusFORCE_SETS(orFORCE_CONSTANTSwith--readfc) is enough —crystod-phonon --modulation -c 221_PPOSCAR_ScF3 --qpoint 0.5 0.5 0.5 --mode 1 2 3 --amplitude 0.3produces the byte-identical structure that the--yaml phonopy_params.yamlform does, so no phonopy yaml has to be generated first. The supercell of the force calculation is read fromphonopy_disp.yamlwhen 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--dimoverrides it. A supercell that does not match the force data now aborts with one sentence instead of a phonopy traceback.--yamlstill works and still wins when both are given. Fixed in the same pass:--tolerance/--symprecreached 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), printedC2/cinstead ofP-1). One--tolerancenow 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--modulationcommand 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--modulationautomatically (M3+ of a perovskite: one arm for(0;0;a), two for(0;a;a), three for(a;a;a)).--amplitudescales 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 --parentis 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--qpointis given.--thresholdsets what counts as imaginary (default -0.1 THz);--yaml phonopy_params.yamlreplaces--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
irreptablesandirreppackage 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 --diagramnow works for e.g. CeO₂, with the 4f crystal-field splitting labeled (GM4⁻/GM5⁻/GM2⁻ at Γ of Fm-3̄m).crystod --visualizewithout--kpointnow visualizes the SALCs at every special k point of the space group (one HTML per point,SALC_{POSCAR}_{element}_{orbital}_{kpoint}.html), mirroring the--diagrambehaviour.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.pynow 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/--orbitalthe viewer now shows the eigen-levels of the--diagramengine 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;--windowopens 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--diagramcrystal column).--sublattice Scshows 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/--oxidationwork as in the PySCF version (--real-coefficientis 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--elementwithout--orbitalstill directs to the basis viewer. Tests in section 5.Fixed: a missing structure file crashed with an
AttributeErrortraceback ('NoneType' object has no attribute 'totuple') in most modes — phonopy’sread_crystal_structurereturnsNoneinstead of raising. Every POSCAR-reading entry point (--diagramboth engines,--dos,--band,--visualize --pyscf, the SALC analysis,--producthybridization,crystod-phonon --qpoint) now goes through the sharedread_poscar_or_exithelper (previously only the SALC viewer/BZ/star-of-k/mag paths used it) and printsERROR: 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--chkare 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 --pyscfgained the same flag (it was silently dropped there before — the PySCF SALC-viewer pages now honor--conventionallike the classic viewer always did). Adversarial review fixes in passing: the primitive→conventional matrix was transposed for non-symmetric centrings — phonopy’sMacts on column-vector lattices, so the row matrix isinv(M)ᵀ, notinv(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 --conventionalandcrystod-mag’s display cell, all fixed at the source (GeTe R3m now frames the true 4.23/4.23/10.89 Å γ=120° hexagonal cell);--dosnow rejects being combined with--diagram/--visualize(it silently swallowed them and their flags); the--bond/--conventionalguards run before every mode branch (--star-of-k --conventionalused 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 (benzeneH6/C6, CH3OHH4/CO, O2O/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)^4with 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
--pyscfMolOD 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-primitivegto_normnormalization (verified to reproduceeval_gtoto 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--chkrestart 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-infoprints 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--onsitecrystal-only checkpoint) on how many k points × AOs, the SCF energies — plus a ready-to-pastereuse with: --co-left … --kmesh … --chk FILEoption string that reproduces the stored conditions exactly (with--onsiteappended 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--chkrestart, including the crystal-only checkpoints of--onsiteruns via--onsite) provides the density matrix,get_bandsdiagonalizes it non-self-consistently along the automatic seekpath high-symmetry path (--band-pointsper 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 absoluteto disable) and the terminal names the band-edge k points (ScF3: VBM at R, CBM at Γ, gap 5.199 eV — matching the--dosmesh gap exactly).--fatbandadds the same per-AO projections the DOS and the diagram compositions use (--projectionLö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 2checkpoint needs--max-l 2here 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--projectionmeasure 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--onsiteblock 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.--onsiteremoves 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--chkis reused (only the crystal density is read;--no-ghostdifferences 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 --pyscfaccepts--onsitetoo — 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--projectionmeasure (Löwdin default — non-negative, summing to exactly 100%), i.e. the same partial-charge machinery ascrystod --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--diagramgets 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
--diagramseries (an adversarial review found every regression): the two test commands dropped the removed--atomic-orbitalflag, the terminal regexes follow the#Nlabels and one-decimal percentages, the multi-shell sketch probe parses the currentVARIANTSJSON (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--diagramrequires---co-left/--co-righterror message no longer advertises the removed--atomic-orbitaloption. 41/41 pass.crystod --dos --pyscf: DOS/PDOS and partial charges from the recorded density matrix (crystod/dos_pyscf.py): the--chkfile already stores the converged density matrices — everything the band step needs — socrystod --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 thecalc_pyscf_dos.pystyle: 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|mullikenpicks 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.txtgains |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. themixcolumn 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) andcrystod-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--sublatticethe 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 --pyscfcolumns). 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 GMrestricts). All--diagram --pyscfoptions 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 HIoverrides the default energy window (HOMO−15 .. LUMO+10 eV of the displayed column), which keeps the page sizes manageable.--diagonalizecanonicalizes 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-onlydrops 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
--diagramfragment columns now number repeated (element, shell, irrep) labels — e.g. the two F 2p GM4- combinations of ScF3 at GM becomeF 2p GM4-#1/F 2p GM4-#2in the terminal, the HTML, and the crystal composition lists — the same convention--diagram --pyscfalready used.--chk(WAVECAR-style restart),--projection, saved coupling tables,#Ncrystal labels (--diagram --pyscf):--chk FILEwrites 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|mullikenselects the population measure used for the sketch lobe sizes and the per-(element, shell) rows (default: Löwdin;mullikenrestores 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.txtnext to the HTML — the terminal keeps showing the top 8. Crystal-column levels are labeledGM4- #2(second GM4- multiplet from the bottom, the same#Nconvention as the fragment columns) instead ofGM4-(2), which read like a degeneracy count; the extended-Hückel--diagramuses 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 2the 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-symmetrizeshows the raw spectrum), and a NOTE recommends ke_cutoff ≥ 150 for hybrid energetics. The new--max-l Ldrops basis shells above l = L (e.g.--max-l 2removes 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-ghostoption 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;--diagramno 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--pyscfSCF now solves only the irreducible wedge of the k-mesh (symmetry-reduced, expanded withto_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-alignto 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 ofcrystod-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 againstpoint_charge_field.ewald_site_potentialto 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 toround(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-alignto 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) inexample/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-mocrystal-orbital export; reproduces the SrTiO3 VASP reference gap to 0.04 eV) andpyscf_band_localized.py(the same solid solved with molecular-chemistry machinery — Gaussian density fitting, Becke grids, all-electron bases — with a--benchmarkmode; 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 genericirrep_Nnames,custom, or-— now gets Miller-Love / ISOTROPY irrep labels (T1,DT5,LD3,GP1, …) and its k-vector-type letter as the k-point name, acrosscrystod(SALC, with a provenance note in the output),crystod --atomic-orbital,crystod-mag, andcrystod-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;--spinoris 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-coordskeeps 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: writesphonon_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 writingphonon_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 bareValueErrortraceback.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.--conventionalswitches the files to the parent conventional basis (_convsuffix).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-basiswith--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.1givesDT [0, 0, 0.1]withDT1(1) + DT5(2)instead of genericirrep_Nnames), including centred lattices (C/F/I/R). Fixed in the same change: the conventional-to-primitive translation conversion of the--basisspace-group path mixed row/column conventions, which silently broke the symmetry-operation group for the rhombohedral (R) centring — R-group--basisruns 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 + DT3in 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 incrystod/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 + LDA2in 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 tocrystod/dirpro_line_names.pythrough 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, theexample/directories, and the documentation are regrouped strictly by command — 1 library core, 2-6crystod, 7-17crystod-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-20crystod-bz, 21-27crystod-phonon, 28-29crystod-mag, 30-31crystod-md, 32-34crystod-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-3mdecomposes 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-flyspgrepsmall 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 shippedirreptablescharacters are refined against exactspgrepvalues (and the broken P-point entry of SG 230 is substituted). Cross-validated line by line against the 9007-product DIRPRO reference set inDIRPRO/(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 (seeexample/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-ferroelectricX3-(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 inSUBGROUP/(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 bothT2g^2and the quoting-freeT2g2(an unquoted^is a glob character in zsh);--orbital dprints 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).--visualizeadditionally 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]):--poscar2cifwrites<POSCAR>.cifin 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 unquotedx+1/2,-y,zstrings (proper block first, centring translations included), and one representative site per Wyckoff orbit with 5-decimal coordinates — unlike the pymatgen CifWriter layout (script/poscar2cif.pykeeps producing the pymatgen flavour as<POSCAR>_pmg.cif).--cif2poscarreads 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--cif2poscarinput), 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--pyscfthe 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-rightselect any fragment partition by formula (O2O/O, CH3OHH4/CO, benzeneH6/C6), and--basis/--theory/--xc/--charge/--spinfollow 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--pyscfsketches 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-groupgained the no-hyphen aliases--spacegroup/--pointgroupeverywhere (in addition to--sg/--pg),crystod-bz --show-kpointalso accepts--sg/--spacegroup, and space groups can be given by number (1-230) as well as by symbol in all--sgmodes (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 thecrystod-mol --ao-left/--ao-rightMO diagram.--co-left/--co-rightsplit 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 inreference/atomic_level_*, generated with the user-standardscript/calc_pyscf.pydriver viascript/generate_atomic_levels.py, collected intocrystod/atomic_levels.pywith 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--electronsoverride, energy window opening on -20 .. 10 eV with a Show-all button for the core levels, and — with the optional--atomic-orbitalsketch 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-orbitalsketches 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 thecrystod-mol --pyscfsketches; 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):--symmetrydetects the molecular point group with pymatgen (Schoenflies + Hermann-Mauguin symbols and the symmetry operations by class — the molecular analogue ofphonopy --symmetry), and--element EL --orbital s|p|d|fbuilds molecular SALCs: the site-permutation characters are multiplied by the orbital characters, decomposed into point-group irreps (same character tables and labels ascrystod-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).--alignrotates the molecule into the standard point-group orientation for textbook axis conventions,--show-matrixprints the site-permutation matrices, and--tolerancecontrols the symmetry detection.--visualizewrites the SALCs as the same standalone interactive 3D HTML viewer ascrystod --visualize(molecule in a vacuum box at Gamma; no cell edges, x/y/z compass;--outputand--bond EL1 EL2 MAXsupported). The detected symmetry operations are snapped onto the exact character-table matrices, so the SALC coefficients are clean small integers whenever possible. Addspymatgenas 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 (fromirreptables, 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.pygained thecrystod-molsections (32 and 34 in the current numbering) with the molecule files inexample/test_XYZs(O2, H2O, NH3, CH4).Fixed: the SALC viewer (
crystod --visualizeandcrystod-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 explicitdomainand 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 storedexample/05_visualized_basispages 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 --modulationcan now be run with--qpointonly (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
--modulationmode 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 ascrystod-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 withcrystod-phonon --irreps(phonon_irreps.yaml).The
--modulationmode table now shows CDML irrep labels (X3-(1),GM5-(2), …) from irreptables — the same labeling ascrystod-phonon --vector/--irreps— instead of internal block indices (the column header changed fromIrrep BlocktoIrrep; 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-orbitalhybridization,--visualize,--star-of-k(the header now shows e.g.X [0.0, 0.5, 0.5]instead ofcustom),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 genericirrep_Nnames). 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 isomorphismh -> g^-1 h gbetween 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-magsurvey printed a wrong decomposition with genericirrep_Nlabels 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-magexported the SAME spin structure twice (e.g...._GM5+_dipole_x_conv.vestaand 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_xand..._dipole_y), matching the 2-dim order parameter (found for the in-plane Ni dipoles/quadrupoles of I4/mmm La3Ni2O7).The
--modulationdefault output name is nowMPOSCAR_{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 ofPOSCAR_modulated;--outputstill overrides it.testsuite.pysections are renumbered by command group (1 library core, 2-6crystod, 7-13crystod-group, 14-16crystod-bz, 17-23crystod-phonon, 24-25crystod-mag, 26-27crystod-md; each group closes with that command’s CLI regression section), and everyexample/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, and19_bz_supercell. Seeexample/READMEfor 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. A0or out-of-range number is rejected with a clear 1-based message.crystod --visualizeHTML 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--conventionaldisplays the SALC in the conventional cell (primitive-to-conventional matrix from the detected centring, as incrystod-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 --visualizenow always writes the interactive 3D HTML, auto-namedSALC_{element}_{orbital}_{kpoint}.htmlwhen--outputis omitted (previously nothing was written without--output).crystod-phonon --vectorusability update: mode numbering is now 1-based, matching the printed table (--mode 0is rejected with a clear message); the q-point mode table (space group, q-points, frequencies, irreps) is automatically saved asphonon_modes_<formula>_<qlabel>.txt; and omitting--modenow exports ALL modes as individual VESTA files (--modestill 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 thatlslists them in order.Redesigned the main
crystodcommand: the flagship SALC analysis runs without a mode flag (crystod -c POSCAR --element Ti --orbital d; hybridization via--atomic-orbital),--visualizemerges the former--visualize-basis, and--star-of-kstays as the symmetry-information option.--kpointnow also accepts high-symmetry labels (GM/X/M/R) in--star-of-k/--visualizemode — the documented--kpoint Mform previously failed to parse. Added--version;crystod --helplists all sectioned commands.Added
crystod-bz(first sectioned command), merging--bzand--bz-supercell: with the default identity--trans-matit plots the unit-cell BZ with an automatic (seekpath) or manual (--band/--band-labels) k-path; with any non-identity--trans-matit 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 onscript/md_summary.py) reports time-averaged lattice parameters and cell volume with standard deviations over a step range (--start-step/--end-step).--dimnow also accepts a nine-value diagonal matrix (quoted or unquoted);--formatselects 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).--dimaccepts three values or a nine-value diagonal matrix, quoted or unquoted;--band-labelsis the primary spelling (--labelkept 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-tablewithout 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/--sgare provided as short aliases of--point-group/--space-group; labels starting with a minus sign (-43m,-1, …) are handled.crystod-mag --conventionalexports 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-directionneeded). New--format vasp|qeselects the printed input: a VASPMAGMOMline, or the Quantum ESPRESSO&SYSTEMcounterpart (noncolin, per-typestarting_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.--conventionalswitches 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 onscript/decomose_to_irreps.pyby Hiroki Koiso), with a non-interactive--charactersoption.Added
--ligand-field-split: ligand-field splitting of an atomic orbital (s-i) into point-group irreps (based onscript/ligand_field_spliting.pyby Hiroki Koiso).Added
--xdatcar2adp: time-averaged structure and symmetry-constrained ADPs (U_ij) from an MD XDATCAR trajectory as a CIF (based onscript/xdatcar_to_adp.pyby 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;--nacapplies the non-analytical term correction (LO/TO splitting) from aBORNfile.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 onscript/supercell_BZ.pyby Hiroki Koiso).Added
--phonon-lt: phonon bands colored by longitudinal/transverse character with an optional--naccorrection (based onscript/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--qpointlists the spin-multipole irreps at all special k points (as in thecrystodSALC survey).--basis-functionnow supports the axial-vector componentsRx,Ry,Rz(transforming with det(R) R, like magnetic moments), including mixed polar-axial products such as the toroidalx*Ry - y*Rx. In space-group mode, omitting--kpointnow analyzes all special k points automatically (as in thecrystodSALC survey).Fixed point-group labels starting with a minus sign (
-43m,-42m,-6m2,-1, …) being rejected by the argument parser in all--point-group/--subgroupmodes; both--point-group -43mand--point-group="-43m"now work.--dimnow also accepts unquoted values (--dim 4 4 4) in all modes.Fixed
--phonon-irrepwith phonopy >= 2.21, where the removedIrReps.frequenciesproperty caused anAttributeError.
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 onscript/brillouin_zone_plot.pyby Hiroki Koiso.Added
seekpathandscipyto the package dependencies.
v0.2.1#
Added
--visualize-basis: SALC coefficients and interactive 3D HTML visualization, with the--real-coefficientoption for real-type degenerate irreps.Added
--star-of-kas 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.pywith 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).