CrystOD#

CrystOD draws crystal-orbital diagrams: it takes a crystal structure and shows how the atomic orbitals combine — with full space-group symmetry labels — into the crystal orbitals at each k point, exactly the way a molecular-orbital diagram explains a molecule. Around this core it provides a complete symmetry toolbox: Symmetry-Adapted Linear Combinations (SALCs), basis functions, phonon irreducible representations, symmetry-adapted vibrations/modulations, magnetic (spin) multipole bases, direct products, isotropy subgroups, and group representation theory.

Crystal-orbital diagram of ScF3 at the R point, with irrep labels and the orbital sketch of the selected level

Phonon dispersion of cubic SrTiO3 with the ISO-IR irrep label of every level at the special k points

Interactive 3D Brillouin zone of ScF3 with the special k points and the seekpath k path

MO diagram of CH4 from symmetry and overlap, with the 1t2 HOMO selected

Four outputs, each linked to its section. Top row: the crystal-orbital diagram of ScF3 (crystod --diagram -c 221_PPOSCAR_ScF3 --co-left Sc --co-right F3) and the phonon irreps of SrTiO3 drawn on the phonopy dispersion (crystod-phonon --irreps -c 221_PPOSCAR_SrTiO3 --dim "4 4 4"); bottom row: the Brillouin zone of ScF3 (crystod-bz -c 221_PPOSCAR_ScF3) and the MO diagram of CH4 (crystod-mol --diagram --xyz XYZ_CH4.xyz). Every one of these inputs is bundled with the package, so each runs right after pip install CrystOD — see the “Try it” column below.

New in v0.4.9#

One line per feature: the command, what it gives, and the section that shows its output.

  • crystod-phonon -c POSCAR --element EL --irrep IR [IR2 ...] (no force data): every isotropy subgroup of the irrep(s) placed on the atoms of the element(s) as a symmetry-adapted displacement pattern, with the space group of the displaced structure identified again, VESTA arrows and the displaced structure; --qpoint K for every irrep at K (04-01).

  • crystod-mag -c POSCAR --element EL --irrep IR [IR2 ...]: every magnetic isotropy subgroup of the irrep(s) placed on the sites of the element(s), with its magnetic space group identified again, the MAGMOM line, a VESTA file and the magnetic cell (05-01); crystod-mag --parent SG --irrep A B ... gives the magnetic isotropy subgroups of coupled irreps (05-04).

  • crystod-phonon --mode-resolved-fc: the force constant and the effective mass of every phonon mode at the special q points, and the force-constant matrix of every irrep subspace (04-12).

  • crystod-mag --qpoint at q != 0: both phases of a complex order parameter and every order-parameter direction with ISOTROPY’s label and its magnetic isotropy subgroup (05-06); --subgroup-poscar CHILD aligns the directions with the domains of a distorted structure (05-07).

  • crystod-mag --qpoint ... --phonon-angular-momentum: the texture of the phonon angular momentum near Γ that the magnetic point group allows (05-08); --element A B analyses several magnetic elements in one run (05-09).

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

In v0.4.9 the section numbers became two-level numbers CC-NN, CC the command group and NN the index inside it (for example 01-09 is crystod --unfold, 02-17 crystod-group --correlate-double-group, 04-09 and 04-10 crystod-phonon --unfold and --visualize, 05-04 crystod-mag --parent), so the example directories carry new names (Quick start has the table, the changelog the old and new numbers). The full list of changes and fixes, and the features of v0.4.8 (crystod --check-symmetry, crystod-group --correlate --supergroup-poscar P --subgroup-poscar C and the magnetic-cell POSCAR of crystod-mag --qpoint), is in the changelog.

CrystOD at a glance#

Not sure what an “orbital diagram for a crystal” means? Play with the toy model first, then look at the real outputs below — everything shown is generated by CrystOD itself.

1. The idea — from a molecule to a crystal (interactive toy model):

Open the simulator full-screen

2. A real molecule — the NH3 molecular-orbital diagram (crystod-mol --diagram --xyz XYZ_NH3.xyz); the only thing you need is XYZ file! Hover the levels for the orbital sketches:

Open the NH3 MO diagram full-screen

3. A real crystal — the same construction for ScF3 (crystod --diagram -c 221_PPOSCAR_ScF3 --co-left Sc --co-right F3, or crystod --example ScF3_diagram): Sc and F3 sublattice orbitals on the sides, the crystal orbitals with their irreducible-representation labels in the middle, one page per special k point:

Open the ScF3 crystal-orbital diagram full-screen

Commands#

The package is organized phonopy-style: one main command plus one sectioned command per research domain.

Command

Domain

crystod

crystal-orbital SALC analysis (main command), --diagram (with dipole selection rules), --band/--dos, --visualize, --star-of-k, --extract-irrep (band irreps of a VASP run from its WAVECAR), --unfold (electronic band unfolding of two VASP runs onto the parent zone)

crystod-group

point/space-group representation-theory calculator (products, correlation tables, property tensors, isotropy subgroups, Landau invariants)

crystod-bz

Brillouin-zone plots (unit cell and supercell folding), special-k-point tables

crystod-phonon

phonon analyses (irreps, IR / Raman activity, fatband, LT bands, eigenvectors, modulation, vibration, subgroups of imaginary modes, band unfolding onto the parent zone, interactive 3D viewer of the modes by irrep)

crystod-mag

symmetry-adapted spin bases (cluster multipoles / SAMM); magnetic space groups, allowed responses and altermagnet classification

crystod-md

MD-trajectory analyses (ADPs, lattice summary, projection onto symmetry-adapted modes)

crystod-mol

molecular point groups, molecular SALCs, and MO diagrams (XYZ files)

crystod-xrd

powder X-ray and neutron diffraction patterns (Bragg peak list and broadened pattern); superlattice reflections of a distorted phase indexed on the parent, with k points and irreps

crystod-slab

surface slabs: every termination of given or of all distinct Miller indices, polar and symmetric tests, POSCAR files

crystod-search

Materials Project search (formula, chemical system, elements, ID) and POSCAR download

crystod-example

the packaged worked examples: lists the example directories and copies them into a working directory

Every feature carries a shared section number used consistently across this documentation, testsuite.py, and the example/ directories of the repository: feature CC-NN (CC the command group, NN the index inside it) is tested by python testsuite.py CC-NN (in a clone of the repository) and demonstrated in example/CC-NN_*, which ships with the package: crystod-example CC-NN copies it into ./example (crystod-example) (all but 01-07_check_symmetry and 01-09_band_unfold, whose VASP runs are not distributed).

What you can ask CrystOD#

Every command prints its answer to the terminal; the ones that draw something also write an HTML page, a PDF, or a VESTA file. A POSCAR (or an XYZ, or nothing at all) is the only input, and crystod-search fetches the POSCAR of any compound of the Materials Project. Every calculation runs offline, and crystod-search is the only command that goes online. The 3D viewers of crystod --visualize, crystod-phonon --visualize, crystod-bz and crystod-mol --visualize load plotly.js from cdn.plot.ly when they are opened, so the browser needs a network connection to display them; the crystal-orbital and MO diagram pages are self-contained. The “Try it” column holds the bundled example closest to each question: --example NAME copies the input files into the working directory, prints the equivalent ordinary command line and runs it (--example alone lists the names); crystod-example CC-NN copies a whole example directory, whose README holds the commands to run (11-01).

Question

Command

Try it

Section

Which irreps does this shell span at each k point?

crystod -c POSCAR --element Ti --orbital d

crystod --example SrTiO3_d

01-02

Which orbitals are allowed to hybridize here?

crystod -c POSCAR --atomic-orbital Sc-d F-p --kpoint R

01-03

What does the orbital diagram of this crystal look like?

crystod --diagram -c POSCAR --co-left Sc --co-right F3

crystod --example ScF3_diagram

01-03

… and its band structure and DOS?

crystod --band --pyscf -c POSCAR --chk FILE, then the same with --dos

01-03

Is the band-edge transition dipole-allowed, and for which polarization?

crystod --diagram -c POSCAR --co-left SrTi --co-right O3

01-04

What do these SALCs look like in 3D?

crystod --visualize -c POSCAR --element Sc --orbital d

01-06

What is T2g x T2g x T1u in m-3m?

crystod-group --product T2g T2g T1u --pg m-3m

02-01

Which components of a piezoelectric (elastic, Raman, …) tensor are allowed?

crystod-group --tensor piezoelectric --pg 4mm

02-06

Which irreps of the low-symmetry phase does every irrep of the parent become (DCORREL)?

crystod-group --correlate --supergroup-poscar POSCAR_SrTiO3_Pm-3m --subgroup-poscar POSCAR_SrTiO3_I4mcm

crystod-example 02-09

02-09

What does each band irrep become with spin-orbit coupling?

crystod-group --correlate-double-group --sg Pm-3m --kpoint R

crystod-example 02-17

02-17

Which space group does this distortion give?

crystod-group --parent Pm-3m --irrep R4+

02-10

Which subgroups can the distortions at this k point give?

crystod-group --parent Pm-3m --kpoint GM

02-10

Which Landau free-energy terms, coupling terms and secondary order parameters does this irrep allow?

crystod-group --parent Pm-3m --irrep R4+ --invariants (--order-parameter a 0 0 --secondary)

02-11

Which distortions give the subgroup I observe?

crystod-group --parent Pm-3m --child I4/mcm

02-12

What are the multi-electron terms of (t2g)³?

crystod-group --multiplet T2g3 --pg m-3m --orbital d

02-14

Which axis setting is my CIF in, and how do I rewrite it in another?

crystod-group --cif-axis -c FILE.cif, then crystod-group --cif2poscar -c FILE.cif --spacegroup-set Amam

02-15

How does the observed structure differ from its parent, and what is the parent-to-child transformation?

crystod-group --supergroup-cif HIGH.cif --subgroup-cif LOW.cif

02-16

What does this Brillouin zone look like?

crystod-bz -c POSCAR

crystod-bz --example ScF3

03-01

Which irrep is each phonon mode?

crystod-phonon --irreps --dim 4 4 4 -c POSCAR

crystod-phonon --example SrTiO3

04-02

Which Gamma phonons are IR or Raman active?

crystod-phonon --irreps --dim 4 4 4 -c POSCAR

crystod-phonon --example SrTiO3

04-03

Which phases can this unstable phonon reach?

crystod-phonon --subgroup --dim 4 4 4 -c POSCAR

crystod-phonon --example SrTiO3_subgroup

04-11

How do the phonons of a distorted phase look in the zone of its parent?

crystod-phonon --unfold --child-poscar POSCAR_child --child-dim 2 2 2 --parent-poscar POSCAR_parent --parent-dim 2 2 2

crystod-example 04-09

04-09

How do the electronic bands of a distorted phase look in the zone of its parent?

crystod --unfold --child-wavecar CHILD/BAND --parent-wavecar PARENT/BAND

01-09

How do the modes move?

crystod-phonon --visualize --dim 4 4 4 -c POSCAR

crystod-example 04-10

04-10

How stiff is each phonon mode, and is the whole subspace of an irrep stable?

crystod-phonon --mode-resolved-fc --dim 4 4 4 -c POSCAR

crystod-example 04-12

04-12

Which irreps do the spin configurations of a site span at each k point?

crystod -c POSCAR --element Ti --axial

01-02

Which magnetic orders are symmetry-allowed?

crystod-mag -c POSCAR --element Ni

05-02

Which magnetic space groups can the magnetic orders of a k point give (no structure file)?

crystod-mag --parent Pm-3m --qpoint GM

05-04

Which magnetic space group does each order have, which responses does it allow, and is it an altermagnet?

crystod-mag -c POSCAR --element Ti --qpoint GM --classify-only

05-03

What are the ADPs of my MD run?

crystod-md --adp --dim 4 4 4 --xdatcar XDATCAR

06-01

How large are the R4+ / M3+ fluctuations in my MD run, and are they single- or double-peaked?

crystod-md --project -c POSCAR --dim 4 4 4 --qpoint R M

06-03

How far does each phonon of my MD run deviate from the harmonic model (effective frequencies)?

crystod-md --project --yaml phonopy_params.yaml --dim 4 4 4 --qpoint R M GM --temperature 300

06-03

What is the MO diagram of this molecule?

crystod-mol --diagram --xyz FILE.xyz

crystod-mol --example CH4

07-02

What powder XRD pattern does this structure give?

crystod-xrd -c POSCAR

crystod-xrd --example ScF3

08-01

Which superlattice reflections of my distorted phase come from which k point and irrep (X-ray or neutron)?

crystod-xrd --parent PARENT.cif -c CHILD.cif

08-02

Which surface slabs can I cut from this structure, and which are polar?

crystod-slab -c POSCAR --max-index 1

crystod-slab --example SrTiO3

09-01

Where do I get a POSCAR of this compound?

crystod-search SrTiO3, then crystod-search --get mp-5229

crystod-search --example SrTiO3

10-01

Where is the worked example of a feature, with its inputs and captured output?

crystod-example CC-NN (copies example/CC-NN_* into ./example)

crystod-example (the list)

11-01

Can I call all of this from Python?

from crystod.phonon import imaginary_mode_subgroups

01-11, API reference

Can an LLM assistant run these analyses for me?

crystod-mcp (Model Context Protocol server)

MCP server

Tutorials

Citation#

If you use CrystOD in your research, please cite:

H. Koiso, S. Yoshida, T. Nagai, T. Isobe, A. Nakajima, and Y. Mochizuki, “Thermal expansion and phase stability of BF3 (B = Sc, Y, La, Al, Ga, In) from first principles”, Physical Review B 110, 064104 (2024).

crystod-slab: please also cite R. Kiribayashi et al., ACS Appl. Mater. Interfaces 17, 61872–61887 (2025).

Contributors#

  • Yasuhide Mochizuki — Tokyo University of Science

  • Hiroki Koiso — Institute of Science Tokyo

  • Ryuju Kiribayashi — Institute of Science Tokyo

License#

MIT License