以下は、Python プログラム point_group.py の解析結果を、利用マニュアル形式でまとめたものです。

---

# 1. プログラムの動作

- 目的
  - 32 種の結晶点群（Hermann–Mauguin 表記）の情報を扱い、以下の機能を提供します。
    - 点群の対称操作の情報表示
    - ステレオ投影による投影図の描画（鏡映面、回転軸、展開方向を表示）
    - 指定した方向ベクトルの点群作用による展開方向の数値リスト出力

- 主な機能と流れ
  - PG_HM に 32 種の Hermann–Mauguin 表記の点群を格納
  - display_pg_info(symbol=None)
    - symbol=None の場合、全 32 点群の一覧を表示
    - symbol が与えられた場合、その点群の対称操作を取得して、総数と各操作の種類・回転行列を表示
  -ワンショットの数学処理
    - orthogonalize(R): 行列 R を最も近い直交行列へ射影（SVD）し、det の符号を整える
    - unique_dirs(vs, ...): 入力方向ベクトル集合の重複を除去（ hemisphere=True の場合 z>=0 に揃え、±同一視を排除）
    - classify_symop_pg(R): 直交化済み行列 R から点群操作の種別を推定（恒等、反転、回転、鏡映、回転対反転などの分類）
  - stereo 投影と可視化
    - stereo_project(v): 単位球上の点 v をステレオ投影（南極から z=0 平面）し、上半球を単位円内へ写す
    - plot_pg_projection(symbol, seed_vec=None, annotate=True)
      - 指定点群 symbol の対称要素から、回転軸、鏡映面（大円）、seed_vec から展開した方向を取得・描画
      - 展開方向は hemisphere=True の重複排除後の集合としてプロット
      - 図にはレジェンド、タイトル、座標軸は非表示（等倍長さの正方形表示）
      - 最後に標準出力へ展開方向の座標一覧を出力
  - 展開方向の数値展開
    - expand_direction(symbol, vec)
      - 指定点群の全対称操作を作用させ、 vec から得られる像方向の集合を unique_dirs で整理して返す

- 入出力の扱い
  - 標準入力は使用せず、CLI からの引数で動作を切り替え
  - 出力は主に標準出力（テキスト表示）と、matplotlib によるポップアップウィンドウのプロット
  - プログラム終了時に自動でファイルを出力する挙動はなく、必要に応じて画面表示・標準出力のみ

---

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

このプログラムは以下の外部ライブラリに依存しています。

- numpy
- matplotlib
- pymatgen

推奨環境は Python 3.8 以降（実行時は Python3）。以下のコマンドでインストールできます。

- pip でのインストール例
  - pip install numpy matplotlib pymatgen

- conda 環境を使う場合
  - conda create -n pg_env python=3.x
  - conda activate pg_env
  - conda install numpy matplotlib pymatgen

注意点
- pymatgen は対称群データを提供するために必要です。インストール後、ネットワーク越しにパッケージの依存関係が解決されます。
- matplotlib は GUI 画面を開く描画を行います。リモート環境やヘッドレス環境では X サーバや適切なバックエンド設定が必要になる場合があります。

---

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

- 物理的なファイルは不要です。コード内に 32 種の点群（Hermann–Mauguin 表記）のリスト
  - PG_HM = ["1", "-1", "2", "m", "2/m", ... "m-3m"]
- CLI から操作を選択して入力を与えます。

入力として利用するデータは以下のとおりです（CLI 引数で提供します）。
- --mode の選択
  - list: 32 点群の一覧表示
  - pg: 指定点群の対称操作情報表示
  - stereo: 指定点群のステレオ投影図の描画
  - expand: 指定点群の方向展開を数値で出力
- --pg: 対象の H–M 表記（例: 4mm, -3m, m-3m など）
- --vec: seed ベクトルの座標（例: "0.8,0.1,0.05"）
- --no-anno: 展開方向の番号付けラベルを非表示にするオプション

---

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

- 標準出力
  - list 時: 32 点群の一覧と各点群の情報（番号、表記）
  - pg 時: 指定点群の総数と各対称操作の分類および回転行列
  - stereo 時: 
    - シーンの説明テキスト
    - 展開方向の座標リスト
- 図（ポップアップウィンドウ）
  - ステレオ投影図（円と大円・点・三角マーク・番号付き）
  - ウィンドウを閉じると処理が終了
- expand 時:
  - 指定ベクトルから展開された方向の座標一覧を標準出力へ表示

- 実行中の補足
  - stereo のプロットは Matplotlib ウィンドウを開いて表示するため、環境によっては画面表示が必要です（特に GUI がない環境ではバックエンド設定が必要）。

---

# 5. コマンドラインでの使用例 (Usage)

- 1) 32 点群の一覧表示
  - python point_group.py list

- 2) 指定点群の対称操作情報表示
  - python point_group.py pg --pg 4mm
  - python point_group.py pg -p "-3m"

- 3) 指定点群のステレオ投影図を描画
  - python point_group.py stereo --pg 4mm --vec "0.8,0.1,0.05"
  -  seed ベクトルを変更したい場合は --vec に x,y,z をカンマ区切りで指定
  - 展開方向の番号付けを表示したくない場合は --no-anno を使用
  例:
  - python point_group.py stereo -p "4mm" -v "0.5,0.2,0.3"  (注意: 上記は --vec が正しく解釈されるよう --vec の仕様に合わせてください)

- 4) 指定点群の方向展開を数値として表示
  - python point_group.py expand --pg "-3m" --vec "0.9,0.1,0.4"

- 共通の注意
  - --pg または -p の値は PG_HM に含まれる 32 種の表記のいずれかである必要があります（例: 4mm, -3m, m-3m など）。
  - seed ベクトルは非ゼロ、かつ正規化してから使用されます。0 ベクトル