# point_group_inf.py のドキュメント

このプログラムは、純粋な NumPy ベースの点群対称性演算と軌道の計算ツールです。tkpointgroup（別名 tkpointgroup というライブラリ）を内部で利用して、シンメトリ操作の列挙、生成子の表示、与えられた点の等価クラス（軌道）、独立代表点の抽出などを行います。

以下では、動作の概要、必要ライブラリとインストール方法、入力ファイルの要件、生成される出力、CLI の使用例を整理します。

---

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

- 入力シンボルの解釈
  - Schoenflies 記法（例: C3v, D4h, Td, Oh, 4/mmm, -3m, m-3m など）または Hermán– Mauguin 記法への変換・利用をサポートします。
  - 内部では tkpointgroup によるグループ生成・操作行列の取得を行います。

- 動作モード
  - 基本モード（--p が指定されていない場合）
    - --generators が指定された場合: 指定シンボルの生成子だけを表示
    - 指定がない場合: 指定シンボルの全操作（行列）を表示
    - --json/--csv が付随すると、それぞれ JSON/CSV 形式で出力
  - 軌道/代表点モード（--p が指定された場合）
    - 指定された点に対して対称性による軌道を計算
    - --independent-only を指定すると、独立代表点のみを抽出
    - 出力は JSON/CSV/人間が読みやすいテキストのいずれかで提供

- 出力形式の柔軟性
  - 人間可読テキスト
  - JSON（機械可読）
  - CSV（表計算ソフトでの取り込みを想定）
  - 角度の丸め（表示精度の設定 --round）

- 補助機能
  - 記法の相互変換（--to-hm: Schoenflies から Herman–Mauguin、--to-s: Herman–Mauguin から Schoenflies）
  - --list でサポート対象の点群記号一覧を表示

- 実行後の終了動作
  - 最後に input("\nPress ENTER to terminate>>\n") が走るため、終了前に ENTER を押す必要があります。

---

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

このスクリプトは以下の外部ライブラリに依存します。

- NumPy
  - インストール: `pip install numpy`
- tkpointgroup（モジュール名: tkpointgroup、エイリアスとして pg）
  - インストール: `pip install tkpointgroup`
  - 注意: tkpointgroup は点群対称性のグループ・操作に関する機能を提供します。プロジェクトの名称や配布元により、パッケージ名が異なる場合があります。公式リポジトリの案内に従ってください。

推奨環境
- Python 3.7 以上
- 仮想環境（venv, conda など）を利用することを推奨

インストールコマンドの例
- 仮想環境作成とアクティベーション
  - python -m venv venv
  - source venv/bin/activate  (Unix/macOS)
  - venv\Scripts\activate  (Windows)
- 依存ライブラリのインストール
  - pip install numpy tkpointgroup

補足
- tkpointgroup の API は本スクリプト内で pg という名前でインポートされています。公式のドキュメントに従って、対応バージョンを使用してください。

---

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

本プログラムは基本的にはコマンドラインから直接シンボルと点の情報を受け取り、入出力を行います。従って特別な外部「入力ファイル」を必須としません。

- 典型的な入力の提供元
  - シンボルだけを与える場合: python point_group_inf.py C3v
  - 点群データを与える場合: --p オプションで x,y,z を複数回指定（例: --p 1,0,0 --p 0.2,0.3,0.4）
  - JSON/CSV での外部ツール連携を想定する場合のデータは、プログラム自身が標準出力（stdout）に出力します（--json, --csv 指定時）。

- 特記事項
  - --independent-only を使う場合、同一軸・対称操作のもとでの独立代表点のみが抽出されます。
  - --tol で点の同値判定の許容誤差を調整可能（デフォルト 1e-8）。
  - 入力点は x,y,z の文字列表現をコンマ区切りで渡します。

---

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

実行時のオプションに応じて、標準出力へ以下の形式で出力されます。

- テキスト（デフォルト）
  - 指定シンボルの全操作または生成子のリスト
  - それぞれの操作に対応する 3x3 行列の表示
  - 点軌道モード時は、各入力点の軌道の点と適用可能な対称操作の一覧を表示

- JSON（--json 指定時）
  - 全体構造の例
    - symbol: 対称群記号
    - count: 操作の総数
    - operations: 各操作のラベルと行列
  - 軌道モード時は、inputs 配下に各入力点の orbit または representatives が含まれる構造
  - independent_only を指定している場合、representatives のみの情報を含む構造

- CSV（--csv 指定時）
  - テキストより機械的に取り込みやすい階層のフラット形式
  - テーブルの列名はモードに応じて異なる
  - テンポラリとして、各操作のラベルと 3x3 行列、または各点とその代表点・対応する操作インデックスをCSV に展開

- 追加的な出力規則
  - --round で表示の小数点以下の桁数を変更可能
  - print_matrix(M, prec) により、表示は指定桁数で整形されます

- 最後の待機
  - プログラム終了時に「Press ENTER to terminate>>」を要求する入力待ちが入ります。

---

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

以下に、スクリプト内に示された代表的な使用例を整理します。実行環境は同じディレクトリか、スクリプトのパスが通っている状態を想定します。

- サポート中のシンボル一覧を表示
  - python point_group_inf.py --list

- C3v の全操作を表示（デフォルトはテキスト）
  - python point_group_inf.py C3v

- D4h の生成子のみ表示
  - python point_group_inf.py D4h --generators

- Td の全操作を JSON 形式で取得
  - python point_group_inf.py Td --json > Td_ops.json

- 4/mmm の全操作を CSV 形式で取得
  - python point_group