以下は、提供されたPythonコード find_point_group.py を解析し、Sphinx（MyST）でビルド可能なMarkdownドキュメントとして記述したものです。

# ``find_point_group.py`` ドキュメント

## 1. 概要

``find_point_group.py`` は、XYZ形式の分子ファイルから点群を推定し、対称操作を直交化、整列、そして特定のSchoenflies記号（C3v/C4v/C6v/C2v/Dn/T/Td/Th/O/Oh）でラベル付けして表示するPythonスクリプトです。

主要な機能は以下の通りです。

*   XYZ ファイルの読み込み（``pymatgen`` ライブラリを使用）。
*   オプションで質量中心への平行移動と、慣性主軸に基づく分子の整列。
*   検出された最大次数の Cn 回転軸を自動的に z 軸に整列。
*   ``pymatgen.symmetry.analyzer.PointGroupAnalyzer`` を用いた点群の推定とSchoenflies記号の取得。
*   対称操作（回転行列）を特異値分解（SVD）で直交化し、``tkpointgroup.snap_matrix()`` で代表化。
*   Cnv (n=3,4,6) の ``σv``/``σd`` の区別、C2v の ``σv(xz)``/``σv'(yz)`` の区別、Dn (n=3,4,6) の ``C2'(x系)`` の分類。
*   T/Th/Td/O/Oh 点群における対称操作のラベリング。

このスクリプトは、共通ライブラリである ``tkpointgroup`` の機能（``tkpointgroup.snap_matrix()``, ``tkpointgroup.normalize_symbol()``, ``tkpointgroup.classify_label()``）を活用することで、コードの重複を削減し、堅牢性を向上させています。

## 2. インストール

このプログラムを実行するには、以下の非標準ライブラリが必要です。

*   ``pymatgen``

``pymatgen`` は ``pip`` を使用してインストールできます。

```bash
pip install pymatgen

プログラムが依存する共通ライブラリ tkpointgroup については、このドキュメントの対象外ですが、このプログラムと同じ環境、または適切な方法で利用可能にしてください。コードからはインストールの詳細を確認できません。

3. 使用方法

3.1. コマンドライン引数

find_point_group.py は以下のコマンドライン引数を受け付けます。

  • --xyz:

    • 説明: 入力 XYZ ファイルのパス（必須）。

    • データ型: 文字列。

  • --tolerance:

    • 説明: 座標許容差 [Å]。

    • データ型: 浮動小数点数。

    • デフォルト値: 0.03。

  • --eigen-tol:

    • 説明: 固有値縮退の許容（無次元）。

    • データ型: 浮動小数点数。

    • デフォルト値: 1e-2。

  • --center:

    • 説明: 分子を質量中心へ平行移動します。

    • データ型: フラグ（存在すれば True）。

  • --align:

    • 説明: 分子を慣性主軸に沿って整列します。

    • データ型: フラグ（存在すれば True）。

  • --dump-ops:

    • 説明: 直交化前の対称操作行列も表示します。

    • データ型: フラグ（存在すれば True）。

  • --write-aligned:

    • 説明: 整列後の分子を XYZ 形式で指定されたパスに保存します。

    • データ型: 文字列（出力ファイルパス）。

    • メタ変数: OUT_XYZ。

  • --assume:

    • 説明: 対称操作の分類に使用する点群ファミリーを明示的に指定します。未指定の場合、推定された記号に基づいて自動的に選択されます。

    • データ型: 文字列。

    • 選択肢: C2v, C3v, C4v, C6v, D3, D4, D6, T, Th, Td, O, Oh。

3.2. 使用例

# H2O 分子の点群を推定し、質量中心へ移動、慣性主軸で整列
python find_point_group.py --xyz h2o.xyz --center --align

# NH3 分子の点群を推定し、質量中心へ移動、慣性主軸で整列、許容差を設定
python find_point_group.py --xyz nh3.xyz --center --align --symprec 2e-3 --angle-tol 8

# CH4 分子の点群を推定し、質量中心へ移動、慣性主軸で整列、直交化前の行列も表示
python find_point_group.py --xyz ch4.xyz --center --align --dump-ops

# 整列後の H2O 分子を新しい XYZ ファイルに保存
python find_point_group.py --xyz h2o.xyz --center --align --write-aligned h2o_aligned.xyz

# SF6 分子と C6H6 分子の点群を推定
python find_point_group.py --xyz SF6.xyz --center --align
python find_point_group.py --xyz C6H6.xyz --center --align

# 推奨されるデフォルトの許容差 (eigen-tol=1e-2, matrix-tol=1e-1) をそのまま使用

4. プログラム解説

4.1. 主要モジュール

このプログラムは以下のPythonモジュールを利用しています。

標準ライブラリ

  • argparse: コマンドライン引数を解析するために使用されます。

  • numpy: 数値計算、特に行列演算に使用されます。

  • pathlib.Path: ファイルパスをオブジェクトとして扱い、ファイルシステム操作を容易にします。

  • typing.List, typing.Tuple, typing.Optional: 型ヒントを提供し、コードの可読性と保守性を高めます。

非標準ライブラリ

  • pymatgen.core.Molecule: 分子構造を表現するためのクラスです。

  • pymatgen.core.periodic_table.Element: 周期表の元素情報を提供します。

  • pymatgen.symmetry.analyzer.PointGroupAnalyzer: 分子の点群を解析し、対称操作を検出するために使用されます。

  • tkpointgroup as pg: 共通ライブラリであり、対称操作行列のスナップ、Schoenflies記号の正規化、およびフォールバックの対称操作ラベリングに使用されます。

4.2. 主要関数およびグローバル変数

プログラム内の主要な関数とその役割は以下の通りです。

数値ユーティリティ

  • _orth_preserve_det(R: np.ndarray) -> np.ndarray:

    • 入力された行列 R を SVD で直交化し、元の行列式の符号を保持した上で、tkpointgroup.snap_matrix() を使用して代表的な値にスナップします。

  • _vec_to_unit(v):

    • ベクトル v を正規化し、単位ベクトルを返します。ノルムが非常に小さい場合は、元のベクトルをそのまま返します。

  • rot_axis_angle(R: np.ndarray) -> Tuple[Optional[np.ndarray], float]:

    • 回転行列 R の回転軸（存在しない場合は None）と回転角（0から π の範囲）を返します。

  • mirror_normal(R: np.ndarray) -> Optional[np.ndarray]:

    • 入力された行列 R が鏡映操作を表す場合、その鏡映面の法線ベクトルを返します。鏡映でない場合は None を返します。

  • pretty_matrix(R: np.ndarray) -> str:

    • 行列 R を整形して文字列として返します。微小な値は 0.0 とし、表示を小数点以下6桁に丸めます。

  • U100, U110, U111:

    • それぞれ [±1,0,0], [±1,±1,0] など、特定の対称性の方向を表す正規化されたベクトルリストです。

  • align_score(axis: np.ndarray, fam: List[np.ndarray]) -> float:

    • 与えられた軸 axis と方向のファミリー fam の間で、最大の内積の絶対値を計算し、軸がファミリーのいずれかの方向にどれだけ近いかを示すスコアを返します。

幾何前処理

  • center_of_mass(mol: Molecule) -> np.ndarray:

    • Molecule オブジェクトの質量中心を計算し、その座標を numpy 配列で返します。

  • inertia_align_matrix(mol: Molecule) -> np.ndarray:

    • Molecule オブジェクトの慣性テンソルを計算し、その固有ベクトルに基づいて慣性主軸に整列するための回転行列を返します。

  • apply_rigid_transform(mol: Molecule, R: np.ndarray, t: np.ndarray) -> Molecule:

    • Molecule オブジェクトに対して、指定された回転行列 R と並進ベクトル t を適用し、変換された新しい Molecule オブジェクトを返します。

  • write_xyz(mol: Molecule, path: Path, comment: str = ""):

    • Molecule オブジェクトの内容を XYZ 形式で指定されたファイルパスに書き込みます。

点群推定

  • guess_point_group(mol: Molecule, tolerance=0.03, eigen_tolerance=1e-2):

    • pymatgen.symmetry.analyzer.PointGroupAnalyzer を使用して、分子のSchoenflies記号と検出された対称操作のリストを返します。

ラベル付け（各ファミリー）

  • label_c2v(R: np.ndarray) -> str:

    • C2v 点群に特有の対称操作（E, C2(z), σv(xz), σv'(yz)）にラベルを付けます。

  • label_cnv(n: int, R: np.ndarray) -> str:

    • Cnv (n=3,4,6) 点群に特有の対称操作（E, Cn^k(z), C2(z), σv, σd）にラベルを付けます。

  • label_dn(n: int, R: np.ndarray) -> str:

    • Dn (n=3,4,6) 点群に特有の対称操作（E, Cn^k(z), C2(z), C2'(xy)）にラベルを付けます。

  • label_t(R: np.ndarray) -> str:

    • T 点群に特有の対称操作（E, C3, C3^2, C2）にラベルを付けます。

  • label_th(R: np.ndarray) -> str:

    • Th 点群に特有の対称操作（Tの操作に加え、i, S6, S6^5, σh）にラベルを付けます。

  • label_td(R: np.ndarray) -> str:

    • Td 点群に特有の対称操作（Tの操作に加え、S4, S4^3, σd）にラベルを付けます。

  • label_o(R: np.ndarray) -> str:

    • O 点群に特有の対称操作（E, C3, C3^2, C4, C4^3, C2(⟨100⟩), C2(⟨110⟩)）にラベルを付けます。

  • label_oh(R: np.ndarray) -> str:

    • Oh 点群に特有の対称操作（Oの操作に加え、i, S4, S4^3, S6, S6^5）にラベルを付けます。

メイン処理

  • main():

    • プログラムのエントリポイントです。コマンドライン引数の解析、分子の読み込み、前処理、点群推定、対称操作のラベリング、および結果の出力を行います。

  • order_key:

    • 対称操作のラベルを出力時にソートするための優先順位を定義する辞書です。

4.3. 処理フロー

find_point_group.py の主な処理フローは以下の通りです。

  1. コマンドライン引数の解析: argparse を使用して、入力ファイルパス、許容差、前処理オプションなどが解析されます。

  2. 分子データの読み込み: 指定された XYZ ファイルから pymatgen.core.Molecule オブジェクトを読み込みます。

  3. 幾何学的前処理:

    • --center オプションが指定されている場合、分子を質量中心に平行移動します。

    • --align オプションが指定されている場合、慣性主軸に沿って分子を整列します。

  4. 点群の推定:

    • pymatgen.symmetry.analyzer.PointGroupAnalyzer を使用して、分子のSchoenflies記号と、pymatgenが検出した対称操作のリストを取得します。

  5. 対称操作の直交化と代表化:

    • pymatgen から得られた各対称操作行列に対して、_orth_preserve_det() 関数を適用し、SVDによる直交化と tkpointgroup.snap_matrix() による代表化を行います。

  6. 点群ファミリーの自動選択または明示指定:

    • --assume オプションが指定されていれば、そのファミリー（例: C2v, Td）が使用されます。

    • 指定がない場合、pymatgen が推定したSchoenflies記号に基づいて、適切なラベリングファミリーが自動的に選択されます。

  7. 対称操作のラベリング:

    • 選択された点群ファミリー（例: label_td(), label_cnv() など）に応じた関数を使用して、各直交化された対称操作行列に具体的なラベル（例: C3, σd）を割り当てます。

    • ラベリングに失敗した場合（ラベルが ? の場合）、tkpointgroup.classify_label() を使用して基本的な分類を試みます。

  8. 結果の出力:

    • 入力ファイル名、原子数、推定されたSchoenflies記号、使用されたファミリー、操作の総数が標準出力に表示されます。

    • --dump-ops オプションが指定されている場合、直交化前の生の状態の対称操作行列も表示されます。

    • 直交化されラベル付けされた対称操作は、order_key に基づいてソートされ、そのラベルと整形された行列が標準出力に表示されます。

  9. 整列済み XYZ の保存:

    • --write-aligned オプションが指定されている場合、前処理（質量中心移動、慣性主軸整列）が適用された後の分子構造が、指定されたファイルパスに XYZ 形式で保存されます。

4.4. 入出力データ形式

入力

  • XYZ ファイル: --xyz オプションで指定される入力ファイルは、標準的な XYZ 形式である必要があります。これは pymatgen.core.Molecule.from_file() メソッドで読み込める形式です。

出力

  • 標準出力:

    • プログラムの実行結果は標準出力に出力されます。これには、ファイル情報、原子数、推定された点群のSchoenflies記号、使用された点群ファミリー、検出された対称操作の総数が含まれます。

    • 各対称操作に対して、その直交化され代表化された行列と、割り当てられたラベルが表示されます。

    • --dump-ops オプションが指定された場合、pymatgen から直接取得された直交化前の対称操作行列も表示されます。

  • XYZ ファイル (オプション):

    • --write-aligned オプションが使用された場合、質量中心へ平行移動され、慣性主軸に整列された後の分子構造が、指定されたファイルパスに XYZ 形式で書き出されます。

5. ライセンス情報

コードからはライセンス情報を確認できません。

6. 開発者情報

コードからは開発者情報を確認できません。