CrystOD

The offline symmetry lab for crystals and molecules.

CrystOD answers questions like:

• "Which irreps do the Ti d orbitals belong to in SrTiO₃?"
• "What space groups can this imaginary phonon condense into?"
• "What symmetry-adapted spin bases does this magnetic structure have?"
• "Show me the MO diagram of this molecule from symmetry alone."

It replaces clicking through Bilbao / ISOTROPY / AMPLIMODES with a single pip-installable Python package and nine CLI commands — fully offline (apart from crystod-search, which fetches structures from the Materials Project), fully scriptable, and cross-validated against the reference servers.

Documentation: https://mochizuki-tus.github.io/CrystOD/

Top row: crystod --diagram -c 221_PPOSCAR_ScF3 --co-left Sc --co-right F3 and crystod-phonon --irreps -c 221_PPOSCAR_SrTiO3 --dim "4 4 4" (the labels drawn on a phonopy dispersion); bottom row: crystod-bz -c 221_PPOSCAR_ScF3 and crystod-mol --diagram --xyz XYZ_CH4.xyz. Every input is bundled with the package (see below).

Every irrep label follows one convention throughout — the ISO-IR (ISOTROPY, Miller–Love) tables, which ship inside the package — at the special k points and equally on symmetry lines, planes and general points.

The nine commands

Several of these are offline counterparts of the Bilbao Crystallographic Server and ISOTROPY tools (DIRPRO, ISOSUBGROUP, AMPLIMODES) and were cross-validated against them; see the documentation for the validation details.

Installation

pip install CrystOD

This installs the nine commands with everything needed for the symmetry analysis, the extended-Hückel crystal-orbital diagrams, the phonon irreps and the MO diagrams. Requires Python 3.10 or later. The dependencies (phonopy, spglib, spgrep, ase, seekpath, pymatgen, numpy, scipy, sympy, pandas, matplotlib, requests) are installed automatically. crystod-search also needs a free Materials Project API key, from https://next-gen.materialsproject.org/api: export MP_API_KEY=<your key>, or store it once with pmg config --add PMG_MAPI_KEY <your key>.

pip install "CrystOD[quantum]"

This adds PySCF for the quantitative engines — crystod --diagram/--band/--dos/--visualize --pyscf and crystod-mol --diagram --pyscf. PySCF is about 500 MB with its dependencies, which is why it is an extra; a --pyscf run without it stops with a one-line error that names this command.

To also get the worked examples and the full test suite, clone the repository instead:

conda create -n crystod python=3.11 && conda activate crystod

git clone https://github.com/ahntaeyoung1212/CrystOD.git && cd CrystOD && pip install -e ".[quantum]"

Quick start

With your own structure

# Your POSCAR -> crystal-orbital irreps of the Ti d orbitals
crystod -c POSCAR --element Ti --orbital d

# Your POSCAR + FORCE_SETS (phonopy, 2x2x2 supercell) -> phonon irrep labels
crystod-phonon --irreps -c POSCAR --dim "2 2 2"

# Space-group algebra (no structure file needed)
crystod-group --parent Pm-3m --irrep R4+

# No POSCAR yet? Search the Materials Project and download one
crystod-search Sr-Ti-O            # the Sr-Ti-O compounds; * = experimentally observed
crystod-search --get mp-5532      # -> POSCAR_Sr2TiO4_I4mmm_mp-5532

Try it without any input file

A few small inputs ship inside the package, so the first run needs nothing but the pip install:

crystod --example ScF3_d          # Sc 3d crystal-orbital irreps of ScF3
crystod-phonon --example SrTiO3   # phonon irrep labels of SrTiO3 (writes phonon_irreps.yaml)
crystod-mol --example CH4         # MO diagram of methane (writes MolOD_XYZ_CH4.html)
crystod-bz --example ScF3         # 3D Brillouin zone of ScF3 (writes BZ_221_PPOSCAR_ScF3.html)
crystod-xrd --example ScF3        # powder XRD pattern of ScF3 for Cu K-alpha (table + PDF)

--example NAME copies the input files of that example into the working directory, prints the equivalent ordinary command line (Running: crystod -c 221_PPOSCAR_ScF3 --element Sc --orbital d) and runs it, so the files are there to edit and re-run. --example alone lists the examples bundled with that command.

More

Which space groups the imaginary phonons of cubic SrTiO₃ can condense into — and the distorted structures themselves:

crystod-phonon --subgroup -c 221_PPOSCAR_SrTiO3 --dim "4 4 4" --qpoint R --modulate

Freeze a chosen mode combination into a structure (a unit cell plus FORCE_SETS is all you need):

crystod-phonon --modulation -c 221_PPOSCAR_ScF3 --qpoint 0.5 0.5 0.5 --mode 1 2 3 --amplitude 0.3

An MO diagram of a molecule from symmetry and overlap alone:

crystod-mol --diagram --xyz XYZ_CH4.xyz

Every command prints its own examples with --help, and the documentation shows the output of each one.

Python API

Every analysis is also a Python function, grouped into one module per command, so a part of CrystOD can be used inside another program:

import crystod

subgroups = crystod.group.isotropy_subgroups("Pm-3m", "R4+")
results = crystod.phonon.scan_imaginary_modes(phonon)   # a live phonopy object

crystod.salc, crystod.group, crystod.phonon, crystod.bz, crystod.mag, crystod.md, crystod.mol, crystod.xrd, crystod.search. Attribute access is lazy, so import crystod plus all nine domains costs ~0.09 s and pulls in nothing heavier than NumPy — phonopy, spgrep, PySCF and matplotlib load only when a function that needs them is called.

The API reference is at https://mochizuki-tus.github.io/CrystOD/api/. Three Jupyter notebooks in tutorials/ walk through one workflow each, on the bundled example inputs and with the Python API and the command line side by side: 01_phonon_irrep_labeling.ipynb, 02_isotropy_subgroup_search.ipynb and 03_mo_diagram.ipynb.

MCP server

crystod-mcp/ in this repository packages the same analyses as the tools of a Model Context Protocol server, so that an LLM client can run CrystOD on local structure files; see the crystod-mcp page of the documentation for the setup.

Testing

python testsuite.py

Runs the full regression suite (37 sections) against the data in example/; a section can be run alone with python testsuite.py 27. The --pyscf checks are skipped when PySCF is not installed. GitHub Actions runs the suite on every push (test.yml) and ruff (lint.yml).

Contributing

Bug reports, questions and pull requests are welcome; CONTRIBUTING.md describes the development setup, the code style and the pull-request process.

Data sources and acknowledgements

• Irrep tables: ISO-IR dataset of the ISOTROPY Software Suite, shipped as crystod/CIR_data.txt.gz — H. T. Stokes, B. J. Campbell and R. Cordes, Acta Cryst. A69, 388–395 (2013), https://iso.byu.edu.
• Isotropy subgroups validated against ISOSUBGROUP — H. T. Stokes, S. van Orden and B. J. Campbell, J. Appl. Cryst. 49, 1849–1853 (2016).
• Symmetry-mode analysis validated against AMPLIMODES — D. Orobengoa, C. Capillas, M. I. Aroyo and J. M. Perez-Mato, J. Appl. Cryst. 42, 820–833 (2009).
• Structures and properties of crystod-search: the Materials Project — A. Jain et al., APL Mater. 1, 011002 (2013), https://doi.org/10.1063/1.4812323; the data are licensed under CC BY 4.0.
• Built on phonopy, spglib, spgrep, ASE, seekpath and pymatgen, and optionally on PySCF.

Contributors

• Yasuhide Mochizuki — Tokyo University of Science (mochizuki@rs.tus.ac.jp)
• Hiroki Koiso — Institute of Science Tokyo

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

@article{CrystOD,
  title   = {Thermal expansion and phase stability of $B$F$_3$ ($B$ = Sc, Y, La, Al, Ga, In) from first principles},
  author  = {Koiso, Hiroki and Yoshida, Suguru and Nagai, Takayuki and Isobe, Toshihiro and Nakajima, Akira and Mochizuki, Yasuhide},
  journal = {Phys. Rev. B},
  volume  = {110},
  pages   = {064104},
  year    = {2024},
  doi     = {10.1103/PhysRevB.110.064104},
}

License

MIT License — see LICENSE.