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 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 Kfor 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 --qpointat 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 CHILDaligns 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 Banalyses 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-filesorCRYSTOD_NO_REPORT=1turn 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:
Commands#
The package is organized phonopy-style: one main command plus one sectioned command per research domain.
Command |
Domain |
|---|---|
|
crystal-orbital SALC analysis (main command), |
|
point/space-group representation-theory calculator (products, correlation tables, property tensors, isotropy subgroups, Landau invariants) |
|
Brillouin-zone plots (unit cell and supercell folding), special-k-point tables |
|
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) |
|
symmetry-adapted spin bases (cluster multipoles / SAMM); magnetic space groups, allowed responses and altermagnet classification |
|
MD-trajectory analyses (ADPs, lattice summary, projection onto symmetry-adapted modes) |
|
molecular point groups, molecular SALCs, and MO diagrams (XYZ files) |
|
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 |
|
surface slabs: every termination of given or of all distinct Miller indices, polar and symmetric tests, POSCAR files |
|
Materials Project search (formula, chemical system, elements, ID) and POSCAR download |
|
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? |
|
|
|
Which orbitals are allowed to hybridize here? |
|
||
What does the orbital diagram of this crystal look like? |
|
|
|
… and its band structure and DOS? |
|
||
Is the band-edge transition dipole-allowed, and for which polarization? |
|
||
What do these SALCs look like in 3D? |
|
||
What is |
|
||
Which components of a piezoelectric (elastic, Raman, …) tensor are allowed? |
|
||
Which irreps of the low-symmetry phase does every irrep of the parent become (DCORREL)? |
|
|
|
What does each band irrep become with spin-orbit coupling? |
|
|
|
Which space group does this distortion give? |
|
||
Which subgroups can the distortions at this k point give? |
|
||
Which Landau free-energy terms, coupling terms and secondary order parameters does this irrep allow? |
|
||
Which distortions give the subgroup I observe? |
|
||
What are the multi-electron terms of (t2g)³? |
|
||
Which axis setting is my CIF in, and how do I rewrite it in another? |
|
||
How does the observed structure differ from its parent, and what is the parent-to-child transformation? |
|
||
What does this Brillouin zone look like? |
|
|
|
Which irrep is each phonon mode? |
|
|
|
Which Gamma phonons are IR or Raman active? |
|
|
|
Which phases can this unstable phonon reach? |
|
|
|
How do the phonons of a distorted phase look in the zone of its parent? |
|
|
|
How do the electronic bands of a distorted phase look in the zone of its parent? |
|
||
How do the modes move? |
|
|
|
How stiff is each phonon mode, and is the whole subspace of an irrep stable? |
|
|
|
Which irreps do the spin configurations of a site span at each k point? |
|
||
Which magnetic orders are symmetry-allowed? |
|
||
Which magnetic space groups can the magnetic orders of a k point give (no structure file)? |
|
||
Which magnetic space group does each order have, which responses does it allow, and is it an altermagnet? |
|
||
What are the ADPs of my MD run? |
|
||
How large are the R4+ / M3+ fluctuations in my MD run, and are they single- or double-peaked? |
|
||
How far does each phonon of my MD run deviate from the harmonic model (effective frequencies)? |
|
||
What is the MO diagram of this molecule? |
|
|
|
What powder XRD pattern does this structure give? |
|
|
|
Which superlattice reflections of my distorted phase come from which k point and irrep (X-ray or neutron)? |
|
||
Which surface slabs can I cut from this structure, and which are polar? |
|
|
|
Where do I get a POSCAR of this compound? |
|
|
|
Where is the worked example of a feature, with its inputs and captured output? |
|
|
|
Can I call all of this from Python? |
|
||
Can an LLM assistant run these analyses for me? |
|
Getting started
Tutorials
Commands
Theory
Python API
Integrations
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).
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



