CrystOD 0.3.6__tar.gz

crystod-0.3.6/CrystOD.egg-info/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: CrystOD
+Version: 0.3.6
+Summary: Symmetry analysis toolkit for crystal orbital diagrams (SALC), space-group irreps, phonon irreps and modulations.
+Author: Yasuhide Mochizuki, Hiroki Koiso
+Maintainer-email: Yasuhide Mochizuki <mochizuki@rs.tus.ac.jp>
+License-Expression: MIT
+Project-URL: Homepage, https://mochizuki-tus.github.io/CrystOD/
+Project-URL: Documentation, https://mochizuki-tus.github.io/CrystOD/
+Project-URL: Repository, https://github.com/ahntaeyoung1212/CrystOD
+Project-URL: Issues, https://github.com/ahntaeyoung1212/CrystOD/issues
+Keywords: crystallography,space group,irreducible representation,phonon,SALC,crystal orbital,symmetry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: phonopy
+Requires-Dist: spglib
+Requires-Dist: spgrep
+Requires-Dist: ase
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: sympy
+Requires-Dist: pandas
+Requires-Dist: matplotlib
+Requires-Dist: seekpath
+Requires-Dist: pymatgen
+Requires-Dist: pyscf
+Provides-Extra: doc
+Requires-Dist: sphinx; extra == "doc"
+Requires-Dist: myst-parser; extra == "doc"
+Requires-Dist: sphinx-book-theme; extra == "doc"
+Requires-Dist: sphinx-copybutton; extra == "doc"
+Dynamic: license-file
+
+# CrystOD
+
+**Cryst**al **O**rbital **D**iagram — 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
+
+| command | what it gives you |
+|---|---|
+| `crystod` | crystal-orbital / SALC irreps from atomic orbitals, orbital hybridization, crystal-orbital diagrams (extended Hückel or PySCF), band structure, DOS, 3D SALC viewers |
+| `crystod-group` | direct products of point- and space-group irreps, reducible-representation decomposition, ligand-field splitting, polynomial basis functions, coset decompositions, isotropy subgroups, multi-electron terms, POSCAR ↔ CIF, symmetry-mode (AMPLIMODES-style) analysis |
+| `crystod-bz` | interactive 3D Brillouin zones, automatic or manual k-paths, supercell (folded) BZs, special k points of any space group |
+| `crystod-phonon` | phonon irrep labeling, element-projected fatbands, longitudinal/transverse bands, eigenvector VESTA export, symmetry-adapted modulations, symmetry-only vibration bases, isotropy subgroups of imaginary modes |
+| `crystod-mag` | symmetry-adapted spin bases (cluster multipoles / SAMM) with ready-to-paste VASP `MAGMOM` or Quantum ESPRESSO input |
+| `crystod-md` | atomic displacement parameters (ADPs) and time-averaged cells from an MD trajectory |
+| `crystod-mol` | molecular point groups, molecular SALCs, and MO diagrams from symmetry + overlap (or PySCF) |
+
+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
+
+```bash
+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:
+
+```bash
+conda create -n crystod python=3.11 && conda activate crystod
+```
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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):
+
+```bash
+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:
+
+```bash
+crystod-group --parent Pm-3m --irrep R4+
+```
+
+An MO diagram of a molecule from symmetry and overlap alone:
+
+```bash
+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:
+
+```python
+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
+
+```bash
+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](mailto: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)](https://doi.org/10.1103/PhysRevB.110.064104).
+
+```bibtex
+@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](LICENSE).

crystod-0.3.6/CrystOD.egg-info/SOURCES.txt

@@ -0,0 +1,79 @@
+LICENSE
+README.md
+pyproject.toml
+CrystOD.egg-info/PKG-INFO
+CrystOD.egg-info/SOURCES.txt
+CrystOD.egg-info/dependency_links.txt
+CrystOD.egg-info/entry_points.txt
+CrystOD.egg-info/requires.txt
+CrystOD.egg-info/top_level.txt
+crystod/CIR_data.txt.gz
+crystod/__init__.py
+crystod/__main__.py
+crystod/_api.py
+crystod/atomic_levels.py
+crystod/band_pyscf.py
+crystod/basis_function.py
+crystod/brillouin_zone.py
+crystod/bz.py
+crystod/bz_supercell.py
+crystod/coset.py
+crystod/crystal_orbital_diagram.py
+crystod/crystal_orbital_pyscf.py
+crystod/crystal_orbital_spgrep.py
+crystod/decompose_irrep.py
+crystod/direct_product.py
+crystod/dirpro_line_names.py
+crystod/dos_pyscf.py
+crystod/generate_basis_function.py
+crystod/group.py
+crystod/irreptables_compat.py
+crystod/isoir.py
+crystod/isotropy_subgroup.py
+crystod/ligand_field.py
+crystod/mag.py
+crystod/md.py
+crystod/md_summary.py
+crystod/mo_diagram.py
+crystod/mo_diagram_fragment.py
+crystod/mo_diagram_pyscf.py
+crystod/modulation.py
+crystod/mol.py
+crystod/molecular_salc.py
+crystod/multiplet.py
+crystod/multiplet_energy.py
+crystod/multiplet_visualize.py
+crystod/operations.py
+crystod/orbital_hybridization_spgrep.py
+crystod/phonon.py
+crystod/phonon_fatband.py
+crystod/phonon_irreps.py
+crystod/phonon_lt.py
+crystod/phonon_subgroups.py
+crystod/phonon_vector.py
+crystod/point_charge_field.py
+crystod/poscar2cif.py
+crystod/runtime_compat.py
+crystod/salc.py
+crystod/show_kpoints.py
+crystod/spacegroup_product.py
+crystod/spglib_compat.py
+crystod/spin_basis.py
+crystod/star_of_k.py
+crystod/symmetry_mode.py
+crystod/vesta_element_rgb.json
+crystod/vibration_modes.py
+crystod/vibration_viewer.py
+crystod/visualize_basis.py
+crystod/visualize_eht.py
+crystod/visualize_pyscf.py
+crystod/xdatcar_adp.py
+crystod/cli/__init__.py
+crystod/cli/bz.py
+crystod/cli/common.py
+crystod/cli/group.py
+crystod/cli/mag.py
+crystod/cli/main.py
+crystod/cli/md.py
+crystod/cli/mol.py
+crystod/cli/phonon.py

crystod-0.3.6/CrystOD.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

crystod-0.3.6/CrystOD.egg-info/entry_points.txt

@@ -0,0 +1,8 @@
+[console_scripts]
+crystod = crystod.cli:main
+crystod-bz = crystod.cli.bz:main
+crystod-group = crystod.cli.group:main
+crystod-mag = crystod.cli.mag:main
+crystod-md = crystod.cli.md:main
+crystod-mol = crystod.cli.mol:main
+crystod-phonon = crystod.cli.phonon:main

crystod-0.3.6/CrystOD.egg-info/requires.txt

@@ -0,0 +1,18 @@
+phonopy
+spglib
+spgrep
+ase
+numpy
+scipy
+sympy
+pandas
+matplotlib
+seekpath
+pymatgen
+pyscf
+
+[doc]
+sphinx
+myst-parser
+sphinx-book-theme
+sphinx-copybutton

crystod-0.3.6/CrystOD.egg-info/top_level.txt

@@ -0,0 +1 @@
+crystod

crystod-0.3.6/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2024-2026 Yasuhide Mochizuki and Hiroki Koiso
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+----------------------------------------------------------------------
+
+Bundled data: crystod/CIR_data.txt.gz contains the ISO-IR tables of the
+ISOTROPY Software Suite (H. T. Stokes, B. J. Campbell and R. Cordes,
+"Tabulated irreducible representations of the crystallographic space
+groups", Acta Cryst. A69, 388-395 (2013); iso.byu.edu/irtables.php).
+Please cite that work when the irreducible-representation tables are used
+in published research.

crystod-0.3.6/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: CrystOD
+Version: 0.3.6
+Summary: Symmetry analysis toolkit for crystal orbital diagrams (SALC), space-group irreps, phonon irreps and modulations.
+Author: Yasuhide Mochizuki, Hiroki Koiso
+Maintainer-email: Yasuhide Mochizuki <mochizuki@rs.tus.ac.jp>
+License-Expression: MIT
+Project-URL: Homepage, https://mochizuki-tus.github.io/CrystOD/
+Project-URL: Documentation, https://mochizuki-tus.github.io/CrystOD/
+Project-URL: Repository, https://github.com/ahntaeyoung1212/CrystOD
+Project-URL: Issues, https://github.com/ahntaeyoung1212/CrystOD/issues
+Keywords: crystallography,space group,irreducible representation,phonon,SALC,crystal orbital,symmetry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: phonopy
+Requires-Dist: spglib
+Requires-Dist: spgrep
+Requires-Dist: ase
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: sympy
+Requires-Dist: pandas
+Requires-Dist: matplotlib
+Requires-Dist: seekpath
+Requires-Dist: pymatgen
+Requires-Dist: pyscf
+Provides-Extra: doc
+Requires-Dist: sphinx; extra == "doc"
+Requires-Dist: myst-parser; extra == "doc"
+Requires-Dist: sphinx-book-theme; extra == "doc"
+Requires-Dist: sphinx-copybutton; extra == "doc"
+Dynamic: license-file
+
+# CrystOD
+
+**Cryst**al **O**rbital **D**iagram — 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
+
+| command | what it gives you |
+|---|---|
+| `crystod` | crystal-orbital / SALC irreps from atomic orbitals, orbital hybridization, crystal-orbital diagrams (extended Hückel or PySCF), band structure, DOS, 3D SALC viewers |
+| `crystod-group` | direct products of point- and space-group irreps, reducible-representation decomposition, ligand-field splitting, polynomial basis functions, coset decompositions, isotropy subgroups, multi-electron terms, POSCAR ↔ CIF, symmetry-mode (AMPLIMODES-style) analysis |
+| `crystod-bz` | interactive 3D Brillouin zones, automatic or manual k-paths, supercell (folded) BZs, special k points of any space group |
+| `crystod-phonon` | phonon irrep labeling, element-projected fatbands, longitudinal/transverse bands, eigenvector VESTA export, symmetry-adapted modulations, symmetry-only vibration bases, isotropy subgroups of imaginary modes |
+| `crystod-mag` | symmetry-adapted spin bases (cluster multipoles / SAMM) with ready-to-paste VASP `MAGMOM` or Quantum ESPRESSO input |
+| `crystod-md` | atomic displacement parameters (ADPs) and time-averaged cells from an MD trajectory |
+| `crystod-mol` | molecular point groups, molecular SALCs, and MO diagrams from symmetry + overlap (or PySCF) |
+
+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
+
+```bash
+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:
+
+```bash
+conda create -n crystod python=3.11 && conda activate crystod
+```
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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):
+
+```bash
+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:
+
+```bash
+crystod-group --parent Pm-3m --irrep R4+
+```
+
+An MO diagram of a molecule from symmetry and overlap alone:
+
+```bash
+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:
+
+```python
+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
+
+```bash
+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](mailto: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)](https://doi.org/10.1103/PhysRevB.110.064104).
+
+```bibtex
+@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](LICENSE).

crystod-0.3.6/README.md

@@ -0,0 +1,151 @@
+# CrystOD
+
+**Cryst**al **O**rbital **D**iagram — 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
+
+| command | what it gives you |
+|---|---|
+| `crystod` | crystal-orbital / SALC irreps from atomic orbitals, orbital hybridization, crystal-orbital diagrams (extended Hückel or PySCF), band structure, DOS, 3D SALC viewers |
+| `crystod-group` | direct products of point- and space-group irreps, reducible-representation decomposition, ligand-field splitting, polynomial basis functions, coset decompositions, isotropy subgroups, multi-electron terms, POSCAR ↔ CIF, symmetry-mode (AMPLIMODES-style) analysis |
+| `crystod-bz` | interactive 3D Brillouin zones, automatic or manual k-paths, supercell (folded) BZs, special k points of any space group |
+| `crystod-phonon` | phonon irrep labeling, element-projected fatbands, longitudinal/transverse bands, eigenvector VESTA export, symmetry-adapted modulations, symmetry-only vibration bases, isotropy subgroups of imaginary modes |
+| `crystod-mag` | symmetry-adapted spin bases (cluster multipoles / SAMM) with ready-to-paste VASP `MAGMOM` or Quantum ESPRESSO input |
+| `crystod-md` | atomic displacement parameters (ADPs) and time-averaged cells from an MD trajectory |
+| `crystod-mol` | molecular point groups, molecular SALCs, and MO diagrams from symmetry + overlap (or PySCF) |
+
+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
+
+```bash
+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:
+
+```bash
+conda create -n crystod python=3.11 && conda activate crystod
+```
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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):
+
+```bash
+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:
+
+```bash
+crystod-group --parent Pm-3m --irrep R4+
+```
+
+An MO diagram of a molecule from symmetry and overlap alone:
+
+```bash
+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:
+
+```python
+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
+
+```bash
+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](mailto: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)](https://doi.org/10.1103/PhysRevB.110.064104).
+
+```bibtex
+@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](LICENSE).