CrystOD

Crystal Orbital Diagram — a Python package and command-line toolset for the symmetry analysis of crystals and molecules: crystal-orbital and SALC irreducible representations, space-group irrep direct products, isotropy subgroups, phonon irreps, symmetry-adapted phonon modulations, molecular point groups and MO diagrams.

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

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 seven 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

Requires Python 3.9 or later. The main dependencies (phonopy, spglib, spgrep, ase, seekpath, pymatgen, pyscf, numpy, scipy, sympy, pandas, matplotlib) are installed automatically.

To also get the worked examples and the 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 .

Quick start

Irreps of the Sc 3d crystal orbitals of ScF₃ at every special k point:

crystod -c 221_PPOSCAR_ScF3 --element Sc --orbital d

Which space groups can the imaginary phonons of cubic SrTiO₃ 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

Which subgroup a distortion of a given irrep and order-parameter direction leaves behind:

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

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. Attribute access is lazy, so import crystod plus all seven 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.

Testing

python testsuite.py

Runs the full regression suite (35 sections) against the data in example/; a section can be run alone with python testsuite.py 27.

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).
• Built on phonopy, spglib, spgrep, ASE, seekpath, pymatgen and 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.