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.

Four outputs, each linked to its section. Top row: the crystal-orbital diagram of ScF₃ (crystod --diagram -c 221_PPOSCAR_ScF3 --co-left Sc --co-right F3) and the phonon irreps of SrTiO₃ drawn on a phonopy dispersion (crystod-phonon --irreps -c 221_PPOSCAR_SrTiO3 --dim "4 4 4"); bottom row: the Brillouin zone of ScF₃ (crystod-bz -c 221_PPOSCAR_ScF3) and the MO diagram of CH₄ (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.

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 NH₃ 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 ScF₃ (crystod --diagram -c 221_PPOSCAR_ScF3 --co-left Sc --co-right F3, or crystod --example ScF3_diagram): Sc and F₃ 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`, `--band`/`--dos`, `--visualize`, `--star-of-k`
`crystod-group`	point/space-group representation-theory calculator
`crystod-bz`	Brillouin-zone plots (unit cell and supercell folding), special-k-point tables
`crystod-phonon`	phonon analyses (irreps, fatband, LT bands, eigenvectors, modulation, vibration, subgroups of imaginary modes)
`crystod-mag`	symmetry-adapted spin bases (cluster multipoles / SAMM)
`crystod-md`	MD-trajectory analyses (ADPs, lattice summary)
`crystod-mol`	molecular point groups, molecular SALCs, and MO diagrams (XYZ files)
`crystod-xrd`	powder X-ray diffraction patterns (Bragg peak list and broadened pattern)
`crystod-search`	Materials Project search (formula, chemical system, elements, ID) and POSCAR download

Every feature carries a shared section number used consistently across this documentation, testsuite.py, and the example/ directories of the repository: feature N is tested by python testsuite.py N and demonstrated in example/<N>_*.

What you can ask CrystOD#

Every command prints its answer to the terminal; the ones that draw something also write a standalone 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. 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).

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`	2
Which orbitals are allowed to hybridize here?	`crystod -c POSCAR --atomic-orbital Sc-d F-p --kpoint R`		3
What does the orbital diagram of this crystal look like?	`crystod --diagram -c POSCAR --co-left Sc --co-right F3`	`crystod --example ScF3_diagram`	3
… and its band structure and DOS?	`crystod --band --pyscf -c POSCAR --chk FILE`, then the same with `--dos`		3
What do these SALCs look like in 3D?	`crystod --visualize -c POSCAR --element Sc --orbital d`		5
What is `T2g x T2g x T1u` in m-3m?	`crystod-group --product T2g T2g T1u --pg m-3m`		7
Which space group does this distortion give?	`crystod-group --parent Pm-3m --irrep R4+`		13
What are the multi-electron terms of (t2g)³?	`crystod-group --multiplet T2g3 --pg m-3m --orbital d`		14
How does the observed structure differ from its parent?	`crystod-group --supergroup-cif HIGH.cif --subgroup-cif LOW.cif`		16
What does this Brillouin zone look like?	`crystod-bz -c POSCAR`	`crystod-bz --example ScF3`	18
Which irrep is each phonon mode?	`crystod-phonon --irreps --dim 4 4 4 -c POSCAR`	`crystod-phonon --example SrTiO3`	21
Which phases can this unstable phonon reach?	`crystod-phonon --subgroup --dim 4 4 4 -c POSCAR`	`crystod-phonon --example SrTiO3_subgroup`	27
Which magnetic orders are symmetry-allowed?	`crystod-mag -c POSCAR --element Ni`		28
What are the ADPs of my MD run?	`crystod-md --adp --dim 4 4 4 --xdatcar XDATCAR`		30
What is the MO diagram of this molecule?	`crystod-mol --diagram --xyz FILE.xyz`	`crystod-mol --example CH4`	33
What powder XRD pattern does this structure give?	`crystod-xrd -c POSCAR`	`crystod-xrd --example ScF3`	36
Where do I get a POSCAR of this compound?	`crystod-search SrTiO3`, then `crystod-search --get mp-5229`	`crystod-search --example SrTiO3`	37
Can I call all of this from Python?	`from crystod.phonon import imaginary_mode_subgroups`		35, API reference
Can an LLM assistant run these analyses for me?	`crystod-mcp` (Model Context Protocol server)		MCP server

Getting started

Tutorials

Tutorials

Commands

Theory

Python API

Integrations

MCP server (crystod-mcp)

Reference

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).

Contributors#

Yasuhide Mochizuki — Tokyo University of Science
Hiroki Koiso — Institute of Science Tokyo

License#

MIT License

CrystOD

Contents