--- myst: html_meta: "description lang=en": "CrystOD (Crystal Orbital Diagram) is a command-line and Python toolkit for the symmetry analysis of crystals and molecules: LCAO crystal-orbital diagrams, SALC and space-group irreducible representations, isotropy subgroups, phonon irreps and symmetry-adapted modulations." "keywords": "CrystOD, crystal orbital diagram, SALC, symmetry-adapted linear combination, space group, irreducible representation, isotropy subgroup, phonon irreps, phonon modulation, crystallography software" "og:title": "CrystOD - Crystal Orbital Diagram" "og:description": "LCAO orbital diagrams for crystals, with full space-group symmetry labels: SALC and crystal-orbital irreps, isotropy subgroups, phonon irreps and symmetry-adapted modulations." "og:url": "https://mochizuki-tus.github.io/CrystOD/" "og:type": "website" --- # 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. ```{list-table} :widths: 50 50 :align: center * - [![Crystal-orbital diagram of ScF3 at the R point, with irrep labels and the orbital sketch of the selected level](images/hero_crystal_orbital.png)](crystod.md#3-crystal-orbital-diagrams) - [![Phonon dispersion of cubic SrTiO3 with the ISO-IR irrep label of every level at the special k points](images/hero_phonon_irrep.png)](crystod-phonon.md#21-phonon-irreps---irreps) * - [![Interactive 3D Brillouin zone of ScF3 with the special k points and the seekpath k path](images/hero_brillouin_zone.png)](crystod-bz.md#18-brillouin-zone-plot) - [![MO diagram of CH4 from symmetry and overlap, with the 1t2 HOMO selected](images/hero_mo_diagram.png)](crystod-mol.md#33-molecular-orbital-diagrams---diagram) ``` 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 a 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. ## 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`, `--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/_*`. ## 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](crystod.md#2-irreps-of-salc) | | Which orbitals are allowed to hybridize here? | `crystod -c POSCAR --atomic-orbital Sc-d F-p --kpoint R` | | [3](crystod.md#3-crystal-orbital-diagrams) | | 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](crystod.md#3-crystal-orbital-diagrams) | | ... and its band structure and DOS? | `crystod --band --pyscf -c POSCAR --chk FILE`, then the same with `--dos` | | [3](crystod.md#band-structure-fatbands-and-dos---band---dos) | | What do these SALCs look like in 3D? | `crystod --visualize -c POSCAR --element Sc --orbital d` | | [5](crystod.md#5-salc-basis-visualization---visualize) | | What is `T2g x T2g x T1u` in m-3m? | `crystod-group --product T2g T2g T1u --pg m-3m` | | [7](crystod-group.md#7-direct-products---product) | | Which space group does this distortion give? | `crystod-group --parent Pm-3m --irrep R4+` | | [13](crystod-group.md#13-isotropy-subgroups---parent) | | What are the multi-electron terms of (t2g)³? | `crystod-group --multiplet T2g3 --pg m-3m --orbital d` | | [14](crystod-group.md#14-multi-electron-terms---multiplet) | | How does the observed structure differ from its parent? | `crystod-group --supergroup-cif HIGH.cif --subgroup-cif LOW.cif` | | [16](crystod-group.md#16-symmetry-mode-analysis---supergroup-cif) | | What does this Brillouin zone look like? | `crystod-bz -c POSCAR` | `crystod-bz --example ScF3` | [18](crystod-bz.md#18-brillouin-zone-plot) | | Which irrep is each phonon mode? | `crystod-phonon --irreps --dim 4 4 4 -c POSCAR` | `crystod-phonon --example SrTiO3` | [21](crystod-phonon.md#21-phonon-irreps---irreps) | | Which phases can this unstable phonon reach? | `crystod-phonon --subgroup --dim 4 4 4 -c POSCAR` | `crystod-phonon --example SrTiO3_subgroup` | [27](crystod-phonon.md#27-subgroups-from-imaginary-modes---subgroup) | | Which magnetic orders are symmetry-allowed? | `crystod-mag -c POSCAR --element Ni` | | [28](crystod-mag.md#28-symmetry-adapted-spin-bases) | | What are the ADPs of my MD run? | `crystod-md --adp --dim 4 4 4 --xdatcar XDATCAR` | | [30](crystod-md.md#30-adps-from-an-md-trajectory---adp) | | What is the MO diagram of this molecule? | `crystod-mol --diagram --xyz FILE.xyz` | `crystod-mol --example CH4` | [33](crystod-mol.md#33-molecular-orbital-diagrams---diagram) | | What powder XRD pattern does this structure give? | `crystod-xrd -c POSCAR` | `crystod-xrd --example ScF3` | [36](crystod-xrd.md#36-powder-x-ray-diffraction-patterns) | | Where do I get a POSCAR of this compound? | `crystod-search SrTiO3`, then `crystod-search --get mp-5229` | `crystod-search --example SrTiO3` | [37](crystod-search.md#37-searching-the-materials-project) | | Can I call all of this from Python? | `from crystod.phonon import imaginary_mode_subgroups` | | [35](python-api.md), [API reference](api/index.md) | | Can an LLM assistant run these analyses for me? | `crystod-mcp` (Model Context Protocol server) | | [MCP server](crystod-mcp.md) | ```{toctree} :maxdepth: 1 :titlesonly: true :caption: Getting started install quickstart first-analysis for-phonopy-users ``` ```{toctree} :maxdepth: 1 :titlesonly: true :caption: Tutorials tutorials ``` ```{toctree} :maxdepth: 2 :caption: Commands crystod crystod-group crystod-bz crystod-phonon crystod-mag crystod-md crystod-mol crystod-xrd crystod-search ``` ```{toctree} :maxdepth: 2 :caption: Theory theory-representations theory-orbital-diagrams theory-isotropy-subgroups ``` ```{toctree} :maxdepth: 2 :caption: Python API python-api api/index ``` ```{toctree} :maxdepth: 1 :titlesonly: true :caption: Integrations crystod-mcp ``` ```{toctree} :maxdepth: 1 :titlesonly: true :caption: Reference citation changelog contributing ``` ## 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)](https://doi.org/10.1103/PhysRevB.110.064104). ## Contributors - **Yasuhide Mochizuki** — Tokyo University of Science - **Hiroki Koiso** — Institute of Science Tokyo ## License MIT License