以下は、Python プログラム find_point_group.py の解析に基づくドキュメントです。

# 1) プログラムの動作概要

- 入力として XYZ 形式の分子データを読み込み、点群解析を通じて対称操作を推定します。
- オプションにより以下を行います
  - 質量中心への平行移動（center）
  - 慣性主軸整列（align）
  - 直交化前後の回転操作行列の表示（dump-ops）
  - 整列後の XYZ の出力（write-aligned）
- pymatgen の Molecule から点群の推定を行い、PointGroupAnalyzer を用いて Schoenflies 記号の点群を推定します。
- 直交化（SVD）とスナップショット化は共通ライブラリ tkpointgroup (as pg) を用いて行います。
- 回転行列 R から回転軸・回転角の推定、鏡映の法線ベクトルの検出を行い、ファミリー別のラベリング関数を用いて対称操作をラベル付けします。対象となるファミリーには以下が含まれます:
  - Cnv, Dn, T, Th, Td, O, Oh など
  - 及び特定のサブカテゴリ（例: C2v, C3v, C4v, …）
- ラベリングはファミリーに応じて label_c2v, label_cnv, label_dn, label_t, label_th, label_td, label_o, label_oh, などの関数を用いて決定します。
- 推定された点群とラベル付き回転操作列を出力します。
- 出力には、整列前後の統計情報、推定記号、ファミリー、回転操作の一覧（ canonicalized & labeled operations ）が含まれます。
- 失敗時のフォールバックとして tkpointgroup.classify_label(R) を利用可能です。

補足
- “tkpointgroup” は共通ライブラリとして同梱されている前提で、snap_matrix、normalize_symbol、classify_label などの機能を活用します。
- 実行例に示されている通り、非標準ライブラリ pymatgen のインストールが必要です。

# 2) 必要な非標準ライブラリとインストール方法

- 必須ライブラリ
  - pymatgen
  - tkpointgroup (サンプルコードでは import tkpointgroup as pg として使用)
- インストール方法（推奨コマンド例）
  - pip の使用例:
    - pip install pymatgen
    - pip install tkpointgroup  (もし PyPI に tkpointgroup がある場合。無い場合はソースから導入する必要があります)
- 補足
  - Python 環境（Python 3.7 以降が想定されますが、コード自体は特に古い仕様には依存していません）
  - 依存関係の解決には仮想環境の利用を推奨します（例: python3 -m venv venv; source venv/bin/activate; pip install ...）。

注意
- tkpointgroup は本コードの中で pg.snap_matrix、pg.normalize_symbol、pg.classify_label を提供することを前提としています。もしローカルにない場合は、 tkpointgroup の対応ファイルを入手・配置してください。

# 3) 必要な入力ファイル

- XYZ 形式の分子データファイル
  - ファイル名例: h2o.xyz, nh3.xyz, ch4.xyz, SF6.xyz, C6H6.xyz など
  - 内容は各原子の元素種と座標が記述された標準的な XYZ 形式
- 输入ファイルの最低要件
  - 有効な分子構造データであること
  - 原子の座標系が適切に記述されていること
- 実行時のコマンド例は以下の通り（XYZファイルを指定して実行します）
  - python find_point_group.py --xyz h2o.xyz --center --align --dump-ops --write-aligned h2o_aligned.xyz
  - python find_point_group.py --xyz nh3.xyz --center --align --symprec 2e-3 --angle-tol 8
  - python find_point_group.py --xyz ch4.xyz --center --align --dump-ops
  - python find_point_group.py --xyz h2o.xyz --center --align
  - python find_point_group.py --xyz SF6.xyz --center --align
  - python find_point_group.py --xyz C6H6.xyz --center --align

- 注釈
  - 入力 XYZ ファイルは pymatgen の Molecule.from_file で読み込める形式であることが前提です。

# 4) 実行後に生成される出力ファイル

- 標準出力（ターミナル）に表示される内容
  - 入力ファイル名
  - 原子数
  - 推定された点群記号（Guessed PG）
  - ファミリー仮定（Assume family）
  - 回転操作の総数（Group order）
  - dump-ops を指定した場合は「Raw rotation matrices (from analyzer)」セクションとして未整列の回転操作行列を表示
  - canonicalized & labeled operations の一覧
    - 各操作について、名前（例: E, C3, σd, …）と対応する 3x3 回転行列が表示
- 任意で書き出す整列後 XYZ ファイル
  - --write-aligned オプションを指定した場合、整列後の XYZ が指定されたパスに保存される
  - コメントには「aligned; PG≈<推定記号>; family=<ファミリー>」が含まれる
- 追加出力
  - もし --dump-ops を使えば、raw rotation matrices の表示が追加されます

# 5) コマンドラインでの使用例（Usage）

- 必須: 入力 XYZ ファイルを指定して実行します
  - 基本的な実行例（中心配置・慣性主軸整列を適用、結果を整列後 XYZ へ保存）：
    - python find_point_group.py --xyz h2o.xyz --center --align --dump-ops --write-aligned h2o_aligned.xyz
- 精密なパラメータを用いた実行例：
  - python find_point_group.py --xyz nh3.xyz --center --align --symprec 2e-3 --angle-tol 8
- 対称操作をダンプせずに実行（簡易出力）：
  - python find_point_group.py --xyz ch4.xyz --center --align --dump-ops
- 基本的な実行（整列のみ、中心移動なし）：
  - python find_point_group.py --xyz h2o.xyz --center --align
- 推奨の実行例（オプションは初期値のままでも可）：
  - python find_point_group.py --xyz SF6.xyz --center --align
  - python find_point_group.py --xyz C6H6.xyz --center --align

補足
- オプションの意味
  - --xyz: 入力 XYZ ファイルのパス（必須）
  - --tolerance: 点群対称性推定時の許容差（デフォルト 0.03 Å）
  - --eigen-tol: 固有値縮退の許容（デフォルト 1e-2）
  - --center: 質量中心へ平行移動
  - --align: 慣性主軸整列
  - --dump-ops: 直交化前の行列も表示
  - --write-aligned: 整列後 XYZ の出力ファイルパス
  - --assume: ファミリーを手動指定（例: C2v, C3v, C4v, C6v, D3, D4, D6, T, Th, Td, O, Oh）
- 出力の解釈
  - 推定された GA: Guessed PG は分子の対称性の推定結果（例: Td, Oh, T など）
  - Assume family: 自動推