以下は、tkpointgroup.py の機能整理と使い方をまとめたドキュメントです。

Markdown 形式で記述します。

---

# tkpointgroup.py の概要

- 点群の群論（特に Schoenflies 系と Hermann–Mauguin 国際記号の相互変換）と、3×3 行列による点群操作の生成・閉包計算を Pure NumPy で実装したライブラリ
- 主な機能
  - 相互変換: Schoenflies 表記と HM 表記の相互変換
  - 群の生成元と全要素の取得（重複なし、行列は snap して正規化）
  - generator から群を閉包化し、全要素のラベル付きリストを取得
  - 点の軌道計算（対称操作による点の同値点集合）および独立代表点の抽出
  - ユーティリティ（回転、鏡映、反転、スナップ、直交化など）
  - いくつかの高レベル API（使いやすい公開インターフェース）
  - 主要な群のカタログ（C, D, T, O, I 系、Oh/Ih などの代表的な群、I/Ih などの抽象モードも含む）
- 依存: numpy

---

# 1. 主な機能・目的

- 点群の集合を、Schoenflies 表記と Hermann–Mauguin 表記に対応させて扱えるようにする
- 国際表記とその派生（例: Cn, Cnv, Cnh, Dn, Dnh, Dnd, T, Th, Td, O, Oh, I, Ih など）の「全要素」および「生成元」を計算・返却できるAPIを提供
- 生成元から群の閉包を作成し、元の生成元とは異なる重複のない全要素を取得する機能
- ラベリング機能: 各要素を対称操作のクラス名に基づくラベルに分類
- GPL 風の高レベル API
  - get_all_operations(symbol): 指定された点群シンボルから全要素をラベル付きで取得
  - get_generators(symbol): 指定されたシンボルの generators をラベル付きで取得（対応が無ければ全要素へフォールバック）
  - elements_from_generators(generators): 指定の生成元リストから群の全要素を閉包してラベル付きで取得
- ユーティリティ系
  - rot(axis, angle_deg): 与えられた軸周りの回転行列を返す
  - mirror(normal): 指定法線方向の鏡映変換
  - inversion(): 原点中心の反転（-I）
  - snap_matrix(M): 行列要素を代表値へスナップし、直交性と det=±1 を保つ正規化処理
  - unique_closure(generators): 生成元の集合から有限群の閉包を構成（重複なし）
  - classify_label(M): 行列をラベル（E/ i / σ / Cn / Sn など）へ分類
  - point/orbit/duplicates 関連: orbit_for_point, dedup_points, unique_orbit_points など
- 文字・記号の正規化と相互変換
  - normalize_symbol(s)
  - schoenflies_to_hm(s), hm_to_schoenflies(h)
- 文字表（character tables）と群のデータ構造
  - PG_CHAR_TABLES: 主要な点群のキャラクター表データを提供
  - ABSTRACT_CLASS_SIZES: 抽象モードのクラスサイズ情報
  - ほか、細かな補助データと計算用関数

---

# 2. 他のプログラムから import する方法

- 前提: NumPy がインストール済みであること

- 基本的な import の例

  - 全機能を利用する場合
    - import tkinterpointgroup as tpg
    - 以後、tpg.get_all_operations("C2v") などの API を利用

  - 必要な関数だけを取り出して使う場合
    - from tkpointgroup import get_all_operations, get_generators, generators_for, classify_label
    - 例:
      - ops = get_all_operations("Cnv(4)") など
      - gens = get_generators("C2v")
      - label_list = [(lab, M) for lab, M in get_all_operations("C2v")]
  - 実装はモジュール内に公開 API が複数あり、目的に応じて必要な関数を import して使います

- 注意
  - このファイルは主に関数型の API を提供します。呼び出し側は generate_group の symbol の書式を正規化して扱う必要があります。

---

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

- 非標準ライブラリ
  - numpy

- インストール方法
  - Python 環境に numpy を追加するには pip を用います:
    - pip install numpy
  - または conda 環境を使っている場合:
    - conda install numpy

- バージョンの目安
  - numpy はほとんどの Python バージョンで動作しますが、本コードは 3.6+ 以降の構文・型ヒントを想定しています。特に 3.x 系を推奨。

---

# 4. import できる変数・関数一覧と説明

以下、公開 API と主要な補助変数を整理します。コメントとして日本語の説明を付けています。

- 公開変数
  - SUPPORTED: List[str]
    - 説明: サポートされている点群シンボルのリスト。Schoenflies 表記と一部の国際表記が含まれます。
  - PG_CHAR_TABLES: Dict[str, Dict[str, Dict[str, complex]]]
    - 説明: 点群キャラクター表のデータ構造。各点群名に対して「classes」と「irreps」を含む辞書を提供。
  - ABSTRACT_CLASS_SIZES: Dict[str, Dict[str, int]]
    - 説明: 抽象モードのクラスサイズ。具体的な群の要素数が未実装の場合に参照される情報。
- 公開関数（機能説明つき）
  - normalize_symbol(s: str) -> str
    - 目的: 入力文字列の空白・特殊文字を除去・統一した表記へ変換する
    - 引数: s - 正規化したいシンボル文字列
    - 戻り値: 正規化済みの文字列
  - schoenflies_to_hm(s: str) -> str
    - 目的: Schoenflies 表記を Hermann–Mauguin 表記へ変換
    - 引数: s - Schoenflies 表記の文字列
    - 戻り値: HM 表記の文字列
  - hm_to_schoenflies(h: str) -> str
    - 目的: HM 表記を Schoenflies 表記へ変換
    - 引数: h - HM 表記の文字列
    - 戻り値: Schoenflies 表記の文字列
  - build_group(symbol: str) -> List[np.ndarray]
    - 目的: 指定シンボルに対応する群の要素（行列のリスト）を返す
    - 引数: symbol - 点群シンボル（例: "Cnv