以下にtkpointgroup.pyのSphinx対応Markdownドキュメントを作成します。

# tkpointgroup モジュールリファレンス

`tkpointgroup.py` は、NumPyを使用して点群に関連する様々なユーティリティを提供するPythonモジュールです。

```rst
.. py:module:: tkpointgroup
   :synopsis: Pure NumPy point-group utilities

このモジュールは、NumPyを使用して点群に関連する様々なユーティリティを提供します。主な機能として、Herman–Mauguin記号とSchoenflies記号の相互変換、群記号からの生成元と全要素の取得、生成元からの閉包計算、点の軌道や独立代表点の取得、および回転、鏡映、反転などの基本的な幾何学操作が含まれます。また、点群の指標表、クラスへの分類、振動モードの既約表現分解など、群論解析のための機能も提供します。

詳細は tkpointgroup_usage ガイドを参照してください。

提供機能（再利用向けAPI）

Herman–Mauguin (国際) と Schoenflies の相互変換
群記号から generator と全要素（重複なし）を取得
generator から閉包を取り、全要素のラベルと行列を取得
点の軌道・独立代表点（重複削除）を取得
各種ユーティリティ（回転・鏡映・反転、スナップ、直交化など）
点群の指標表の取得と操作の分類
振動モードの既約表現分解

依存

numpy

基本ユーティリティ

.. py:function:: _norm(v: numpy.ndarray) -> numpy.ndarray

ベクトルを正規化します。

概要: 入力ベクトルを正規化し、単位ベクトルを返します。詳細説明: ベクトルのL2ノルムが0の場合はValueErrorを発生させます。 :param v: 正規化する入力ベクトル。 :type v: numpy.ndarray :returns: 正規化された単位ベクトル。 :rtype: numpy.ndarray :raises ValueError: 入力ベクトルの長さがゼロの場合。

.. py:function:: rot(axis: numpy.ndarray, angle_deg: float) -> numpy.ndarray

指定された軸を中心とした回転行列を生成します。

概要: 与えられた軸と角度に基づいて3x3の回転行列を計算します。詳細説明: ロドリゲスの回転公式を使用して回転行列を構築します。角度は度数で指定します。 :param axis: 回転軸を示すベクトル。 :type axis: numpy.ndarray :param angle_deg: 回転角度（度数）。 :type angle_deg: float :returns: 3x3の回転行列。 :rtype: numpy.ndarray

.. py:function:: mirror(normal: numpy.ndarray) -> numpy.ndarray

指定された法線ベクトルを持つ平面での鏡映行列を生成します。

概要: 与えられた法線ベクトルに垂直な平面に関する3x3の鏡映行列を計算します。詳細説明: 鏡映行列は I - 2*(n @ n.T) で計算されます。ここで I は単位行列、n は正規化された法線ベクトルです。 :param normal: 鏡映平面の法線ベクトル。 :type normal: numpy.ndarray :returns: 3x3の鏡映行列。 :rtype: numpy.ndarray

.. py:function:: inversion() -> numpy.ndarray

反転操作の行列を生成します。

概要: 原点に対する反転操作を表す3x3の行列を返します。詳細説明: これは -I（マイナス単位行列）と等価です。 :returns: 3x3の反転行列。 :rtype: numpy.ndarray

.. py:data:: _SNAP_VALUES: List[float]

行列要素のスナップに使用される代表値のリスト。

.. py:function:: _closest(x: float) -> float

与えられた浮動小数点数を、定義済みの代表値リストから最も近い値にスナップします。

概要: 浮動小数点数を物理的に意味のある代表値（0, 0.5, 1/√2, √3/2, 1など）に丸めます。詳細説明: _SNAP_VALUES リスト内の値と入力値との絶対差が最小となる値を返します。スナップの閾値は5e-8です。 :param x: スナップする浮動小数点数。 :type x: float :returns: 最も近い代表値。 :rtype: float

.. py:function:: snap_matrix(M: numpy.ndarray) -> numpy.ndarray

行列要素を代表値へスナップし、直交性/ det=±1 を保証します。

概要: 入力された3x3行列の各要素を事前に定義された代表的な浮動小数点数にスナップし、さらにその行列が直交性を満たし、かつ行列式が±1であることを保証します。詳細説明: まず、各要素を _closest 関数でスナップします。次に、スナップ後の行列が厳密に直交行列でない場合、SVD (特異値分解) を用いて最も近い直交行列に変換し、再度要素をスナップします。最後に、行列式が±1でない場合、SVDを用いて行列式を±1に修正します。これにより、数値誤差によって生じるわずかなずれを修正し、物理的に正しい対称操作行列を保証します。 :param M: スナップ処理を行う3x3の浮動小数点行列。 :type M: numpy.ndarray :returns: スナップされ、直交性および行列式の条件を満たす3x3行列。 :rtype: numpy.ndarray

.. py:function:: mat_key(M: numpy.ndarray) -> tuple

行列の一意な識別キーを生成します。

概要: NumPy配列を行列の同一性チェックに使用できるハッシュ可能なタプルに変換します。詳細説明: 行列を1次元に平坦化し、各要素を小数点以下10桁で丸めてタプルに変換します。これにより、浮動小数点誤差に強いキーとして、辞書のキーや集合の要素として利用可能になります。 :param M: キーを生成する入力行列。 :type M: numpy.ndarray :returns: 行列の要素を丸めたタプルのキー。 :rtype: tuple

.. py:function:: unique_closure(generators: List[numpy.ndarray]) -> List[numpy.ndarray]

生成元のリストから有限群の閉包を構成します（重複なし）。

概要: 与えられた生成元行列のセットから、それらによって生成される全てのユニークな群要素（行列）を計算します。詳細説明: 生成元と既存の群要素の積を計算し、新しいユニークな要素が見つかるたびにキューに追加していく幅優先探索（またはダイクストラ法に似た）アプローチを使用します。全ての要素は snap_matrix で正規化され、mat_key で重複がチェックされます。入力が空の場合、単位行列のみを含むリストを返します。 :param generators: 群の生成元であるNumPy行列のリスト。 :type generators: List[numpy.ndarray] :returns: 生成元から構成される点群の全てのユニークな要素行列のリスト。 :rtype: List[numpy.ndarray]

.. py:data:: ex: numpy.ndarray
.. py:data:: ey: numpy.ndarray
.. py:data:: ez: numpy.ndarray

標準軸ベクトル (x, y, z)。

.. py:function:: vertical_plane(phi_deg: float) -> numpy.ndarray

z軸に垂直な平面（xz平面またはyz平面を含む）に垂直な、xy平面内の法線ベクトルを生成します。

概要: 与えられた角度を持つ垂直面の法線ベクトル（xy平面内）を計算します。詳細説明: phi_deg が 0 の場合、y軸に沿ったベクトル ([0, -1, 0]) となり、これはxz平面 (y=0) に垂直です。 phi_deg が 90 の場合、x軸に沿ったベクトル ([-1, 0, 0]) となり、これはyz平面 (x=0) に垂直です。 :param phi_deg: xy平面内での角度（度数）。 :type phi_deg: float :returns: 垂直面の法線ベクトル。 :rtype: numpy.ndarray

.. py:function:: diagonal_plane(phi_deg: float) -> numpy.ndarray

対角面（z軸に対して45度の角度を持つ面）の法線ベクトルを生成します。

概要: 指定された角度に対する対角面の法線ベクトルを計算します。詳細説明: vertical_plane 関数を呼び出し、角度に90度を加えることで、 xy平面内で45度の傾きを持つ（例: (1,1,0) や (1,-1,0) 方向を法線に持つ）面を表現します。 :param phi_deg: xy平面内での角度（度数）。 :type phi_deg: float :returns: 対角面の法線ベクトル。 :rtype: numpy.ndarray

群ビルダー

.. py:function:: build_Cn(n: int) -> List[numpy.ndarray]

n回軸 (Cn) 点群の全ての対称操作行列を構築します。

概要: n回回転軸のみから構成される点群の全要素行列を返します。詳細説明: z軸周りの360/n度の回転を生成元とし、それらの閉包を計算します。 :param n: 回転軸の次数。 :type n: int :returns: Cn点群の対称操作行列のリスト。 :rtype: List[numpy.ndarray]

.. py:function:: build_Cnv(n: int) -> List[numpy.ndarray]

Cnv点群の全ての対称操作行列を構築します。

概要: n回回転軸とそれに含まれる複数の鉛直鏡映面から構成される点群の全要素行列を返します。詳細説明: z軸周りの360/n度の回転と、z軸を含む垂直面（phi=0）での鏡映を生成元とし、それらの閉包を計算します。 :param n: 回転軸の次数。 :type n: int :returns: Cnv点群の対称操作行列のリスト。 :rtype: List[numpy.ndarray]

.. py:function:: build_Cnh(n: int) -> List[numpy.ndarray]

Cnh点群の全ての対称操作行列を構築します。

概要: n回回転軸とそれに垂直な水平鏡映面から構成される点群の全要素行列を返します。詳細説明: z軸周りの360/n度の回転と、z軸に垂直な水平面（ez）での鏡映を生成元とし、それらの閉包を計算します。 :param n: 回転軸の次数。 :type n: int :returns: Cnh点群の対称操作行列のリスト。 :rtype: List[numpy.ndarray]

.. py:function:: build_Sn(n: int) -> List[numpy.ndarray]

Sn点群の全ての対称操作行列を構築します。

概要: n回回映軸 (improper rotation axis) から構成される点群の全要素行列を返します。詳細説明: z軸に垂直な鏡映とz軸周りの360/n度の回転の積（回映操作）を生成元とし、その閉包を計算します。 :param n: 回映軸の次数。 :type n: int :returns: Sn点群の対称操作行列のリスト。 :rtype: List[numpy.ndarray]

.. py:function:: build_Dn(n: int) -> List[numpy.ndarray]

Dn点群の全ての対称操作行列を構築します。

概要: n回回転軸とそれに垂直な2回回転軸（n個）から構成される点群の全要素行列を返します。詳細説明: z軸周りの360/n度の回転と、x軸周りの180度回転を生成元とし、それらの閉包を計算します。 :param n: 主回転軸の次数。 :type n: int :returns: Dn点群の対称操作行列のリスト。 :rtype: List[numpy.ndarray]

.. py:function:: build_Dnh(n: int) -> List[numpy.ndarray]

Dnh点群の全ての対称操作行列を構築します。

概要: Dn点群に水平鏡映面が加わった点群の全要素行列を返します。詳細説明: z軸周りの360/n度の回転、x軸周りの180度回転、およびz軸に垂直な水平鏡映を生成元とし、それらの閉包を計算します。 :param n: 主回転軸の次数。 :type n: int :returns: Dnh点群の対称操作行列のリスト。 :rtype: List[numpy.ndarray]

.. py:function:: build_Dnd(n: int) -> List[numpy.ndarray]

Dnd点群の全ての対称操作行列を構築します。

概要: Dn点群に、2回回転軸の間の対角鏡映面が加わった点群の全要素行列を返します。詳細説明: z軸周りの360/n度の回転、x軸周りの180度回転、および2回回転軸の間の対角鏡映面（phi=0）を生成元とし、それらの閉包を計算します。 :param n: 主回転軸の次数。 :type n: int :returns: Dnd点群の対称操作行列のリスト。 :rtype: List[numpy.ndarray]

.. py:function:: build_T() -> List[numpy.ndarray]

T (四面体) 点群の全ての対称操作行列を構築します。

概要: 正四面体の対称性を持つ点群の全要素行列を返します。詳細説明: [1,1,1]軸周りの120度回転と、x軸周りの180度回転を生成元とし、それらの閉包を計算します。 :returns: T点群の対称操作行列のリスト。 :rtype: List[numpy.ndarray]

.. py:function:: build_Th() -> List[numpy.ndarray]

Th (全四面体) 点群の全ての対称操作行列を構築します。

概要: T点群に反転中心が加わった点群の全要素行列を返します。詳細説明: T点群の生成元に反転操作を追加し、それらの閉包を計算します。 :returns: Th点群の対称操作行列のリスト。 :rtype: List[numpy.ndarray]

.. py:function:: build_Td() -> List[numpy.ndarray]

Td (正四面体) 点群の全ての対称操作行列を構築します。

概要: 正四面体の対称性を持つ点群の全要素行列を返します。詳細説明: [1,1,1]軸周りの120度回転、x軸周りの180度回転、およびz軸周りのS4回映操作を生成元とし、それらの閉包を計算します。 :returns: Td点群の対称操作行列のリスト。 :rtype: List[numpy.ndarray]

.. py:function:: build_O() -> List[numpy.ndarray]

O (八面体) 点群の全ての対称操作行列を構築します。

概要: 正八面体または立方体の対称性を持つ点群の全要素行列を返します。詳細説明: 3次元空間における軸の順列と符号の組み合わせにより、立方体の回転対称操作を直接列挙します。行列式が1の操作のみを含めます。 :returns: O点群の対称操作行列のリスト。 :rtype: List[numpy.ndarray]

.. py:function:: build_Oh() -> List[numpy.ndarray]

Oh (全八面体) 点群の全ての対称操作行列を構築します。

概要: O点群に反転中心が加わった点群の全要素行列を返します。詳細説明: O点群の全ての操作に反転操作を適用したものを加え、ユニークな要素を抽出します。 :returns: Oh点群の対称操作行列のリスト。 :rtype: List[numpy.ndarray]

記号の正規化と相互変換

.. py:function:: normalize_symbol(s: str) -> str

点群シンボル文字列を正規化します。

概要: 入力された点群シンボル文字列から空白、ハイフン、アンダースコアを除去し、標準形式に変換します。詳細説明: 異なる形式で入力されうるハイフン文字（U+2212, U+2013, U+2014）も標準のASCIIハイフンに統一します。 :param s: 正規化する点群シンボル文字列。 :type s: str :returns: 正規化された点群シンボル文字列。 :rtype: str

.. py:data:: _S_to_H: Dict[str, str]

Schoenflies記号からHerman–Mauguin記号への代表的な変換マップです。曖昧さがある場合は代表形に丸められます。

.. py:data:: _H_to_S: Dict[str, str]

Herman–Mauguin記号からSchoenflies記号への代表的な逆変換マップです。値の代表形を採用し、一部はbuild_group側の代表入力に合わせた近似対応を含みます。

.. py:function:: schoenflies_to_hm(s: str) -> str

Schoenflies点群記号をHerman–Mauguin (国際) 記号に変換します。

概要: 与えられたSchoenflies記号を対応するHerman–Mauguin記号に変換します。詳細説明: 変換マップ _S_to_H を使用します。マップにない記号はそのまま返されます。変換前に normalize_symbol でシンボルを正規化します。 :param s: Schoenflies点群記号。 :type s: str :returns: 対応するHerman–Mauguin点群記号。 :rtype: str

.. py:function:: hm_to_schoenflies(h: str) -> str

Herman–Mauguin (国際) 点群記号をSchoenflies記号に変換します。

概要: 与えられたHerman–Mauguin記号を対応するSchoenflies記号に変換します。詳細説明: 変換マップ _H_to_S を使用します。マップにない記号はそのまま返されます。変換前に normalize_symbol でシンボルを正規化します。 :param h: Herman–Mauguin点群記号。 :type h: str :returns: 対応するSchoenflies点群記号。 :rtype: str

サポート一覧 / 構築エントリ

.. py:data:: SUPPORTED: List[str]

このモジュールで構築可能な点群シンボルの一覧。 Schoenfliesファミリーと代表的な国際記号が含まれます。

.. py:function:: supported_symbols() -> List[str]

このモジュールで構築可能な点群シンボルの一覧を返します。

概要: 現在サポートされている点群シンボルのリストを返します。詳細説明: Schoenflies記号と、それに対応する代表的なHerman–Mauguin記号が含まれます。 :returns: サポートされている点群シンボルのリスト。 :rtype: List[str]

.. py:function:: build_group(symbol: str) -> List[numpy.ndarray]

指定された点群シンボルに対応する全ての対称操作行列を構築します。

概要: 点群シンボル（SchoenfliesまたはHerman–Mauguin）に基づいて、その点群の全ての対称操作行列をリストで返します。詳細説明: 入力シンボルを正規化し、対応する build_C* や build_D* などの関数を呼び出します。サポートされていないシンボルの場合は ValueError を発生させます。 :param symbol: 構築する点群のシンボル（例: "C2v", "mmm"）。 :type symbol: str :returns: 点群の全ての対称操作行列のリスト。 :rtype: List[numpy.ndarray] :raises ValueError: サポートされていない点群シンボルが指定された場合。

ラベリング（簡易）

.. py:function:: classify_label(M: numpy.ndarray) -> str

対称操作行列を簡易的なラベル（例: "E", "i", "σ_h", "C(z,90)"）に分類します。

概要: 与えられた3x3の対称操作行列を行列式とトレースに基づいて分類し、対応する文字列ラベルを返します。詳細説明: 単位行列は "E"、反転行列は "i" となります。行列式が-1の操作で自乗すると単位行列になるものは鏡映（σ）と判断し、法線ベクトルの方向によって σ_h, σ_v などを割り当てます。行列式が1の操作は回転 (C)、行列式が-1の操作で鏡映でないものは回映 (S) と判断し、回転軸と角度に基づいてラベルを生成します。 :param M: 分類する3x3の対称操作行列。 :type M: numpy.ndarray :returns: 分類された操作を示す文字列ラベル。 :rtype: str

.. py:function:: label_elements(mats: List[numpy.ndarray]) -> List[Tuple[str, numpy.ndarray]]

対称操作行列のリストをラベル付きのリストに変換します。

概要: 各対称操作行列に対して classify_label 関数を適用し、(ラベル, 行列) のペアのリストを生成します。 :param mats: 対称操作行列のリスト。 :type mats: List[numpy.ndarray] :returns: ラベルとそれに対応する行列のペアのリスト。 :rtype: List[Tuple[str, numpy.ndarray]]

.. py:function:: generators_for(symbol: str) -> List[Tuple[str, numpy.ndarray]]

指定された点群シンボルに対応する規約な生成元を返します（ラベル付き）。

概要: 特定の点群シンボルに対して、その群を生成するための最小限の操作行列のリストをラベル付きで提供します。詳細説明: ほとんどのSchoenflies記号に対して定義済みの生成元を返します。国際記号など、生成元が明確に定義されていない場合は空のリストを返します。返される全ての生成元は snap_matrix で正規化されています。 :param symbol: 点群シンボル。 :type symbol: str :returns: ラベルと生成元行列のペアのリスト。生成元が定義されていない場合は空リスト。 :rtype: List[Tuple[str, numpy.ndarray]]

軌道・独立代表点（重複削除）

.. py:function:: point_key(p: numpy.ndarray, tol: float = 1e-8) -> tuple

点の同一性判定用キーを生成します（トレランスつき）。

概要: 与えられた3D点のNumPy配列を、浮動小数点誤差を考慮したハッシュ可能なタプルキーに変換します。詳細説明: 点を指定された許容誤差 (tol) でスケールし、最も近い整数に丸めます。これにより、非常に近い点が同じキーを持つようになり、集合や辞書での重複排除に利用できます。 :param p: 3次元の点座標。 :type p: numpy.ndarray :param tol: 点の比較に用いる許容誤差。 :type tol: float :returns: 点のハッシュ可能なタプルキー。 :rtype: tuple

.. py:function:: orbit_for_point(ops: List[numpy.ndarray], p: numpy.ndarray, tol: float = 1e-8) -> List[Tuple[numpy.ndarray, List[int]]]

一点から生成される軌道上の全ての等価点と、それらを生成する操作のインデックスを返します。

概要: 与えられた点pに、点群の全ての操作を適用して生成される軌道上のユニークな点をリストアップします。詳細説明: 各操作 M に対して M @ p を計算し、point_key を使用してユニークな点を識別します。結果は、(等価点, [その点を生成する操作のインデックスのリスト]) のタプルのリストとして返されます。 :param ops: 点群の対称操作行列のリスト。 :type ops: List[numpy.ndarray] :param p: 軌道を計算する開始点。 :type p: numpy.ndarray :param tol: 点の比較に用いる許容誤差。 :type tol: float :returns: 軌道上の各ユニークな点と、それを生成する操作インデックスのリストのタプル。 :rtype: List[Tuple[numpy.ndarray, List[int]]]

.. py:function:: dedup_points(orbits: List[Tuple[numpy.ndarray, List[int]]], tol: float = 1e-8) -> List[Tuple[numpy.ndarray, List[int]]]

(点, 操作IDリスト) のリストからユニークな点を抽出します。

概要: orbit_for_point の結果から、座標が同じ点をまとめ、それらに対応する操作IDを結合します。詳細説明: point_key を使用して点の重複を検出し、重複する点が見つかった場合は、対応する操作IDのセットを結合します。最終的に、ユニークな点とその点を生成する全ての操作ID（ソート済みリスト）のペアを返します。 :param orbits: orbit_for_point から返される (点, 操作IDリスト) のリスト。 :type orbits: List[Tuple[numpy.ndarray, List[int]]] :param tol: 点の比較に用いる許容誤差。 :type tol: float :returns: 重複排除された (ユニークな点, その点を生成する操作IDのリスト) のペアのリスト。 :rtype: List[Tuple[numpy.ndarray, List[int]]]

.. py:function:: unique_orbit_points(ops: List[numpy.ndarray], p: numpy.ndarray, tol: float = 1e-8) -> List[Tuple[numpy.ndarray, List[int]]]

対称操作行列と開始点を受け取り、重複排除された軌道上の独立点とその生成操作のインデックスを返します。

概要: 与えられた点pに点群の全ての操作を適用し、結果として得られる軌道上の重複しない点を抽出します。詳細説明: orbit_for_point と dedup_points を内部的に使用して、最終的な独立代表点と、それらを作成する全ての対称操作のインデックスをまとめます。 :param ops: 点群の対称操作行列のリスト。 :type ops: List[numpy.ndarray] :param p: 軌道を計算する開始点。 :type p: numpy.ndarray :param tol: 点の比較に用いる許容誤差。 :type tol: float :returns: 軌道上のユニークな各点と、それを生成する操作インデックスのリストのタプル。 :rtype: List[Tuple[numpy.ndarray, List[int]]]

高レベルAPI

.. py:function:: get_all_operations(symbol: str) -> List[Tuple[str, numpy.ndarray]]

点群シンボルから全要素（ラベル付き、重複なし）を返します。

概要: 指定された点群シンボルに対応する全ての対称操作行列と、それぞれの簡易ラベルのペアのリストを返します。詳細説明: build_group を使用して行列を構築し、label_elements でラベル付けを行います。 :param symbol: 点群シンボル。 :type symbol: str :returns: ラベルと操作行列のペアのリスト。 :rtype: List[Tuple[str, numpy.ndarray]] :raises ValueError: サポートされていない点群シンボルが指定された場合。

.. py:function:: get_generators(symbol: str) -> List[Tuple[str, numpy.ndarray]]

点群シンボルから生成元（ラベル付き）を返します。

概要: 指定された点群シンボルに対応する生成元の操作行列と、それぞれの簡易ラベルのペアのリストを返します。詳細説明: generators_for を使用して定義済みの生成元を取得します。もし generators_for が生成元を返さない場合（国際記号など）、get_all_operations にフォールバックし、全ての群要素を生成元と見なして返します。 :param symbol: 点群シンボル。 :type symbol: str :returns: ラベルと生成元行列のペアのリスト。 :rtype: List[Tuple[str, numpy.ndarray]] :raises ValueError: サポートされていない点群シンボルが指定された場合（build_group経由）。

.. py:function:: elements_from_generators(generators: List[numpy.ndarray]) -> List[Tuple[str, numpy.ndarray]]

生成元行列のリストから閉包をとり、ラベル付きの全要素を返します。

概要: 与えられた生成元行列のリストから、それらによって生成される全てのユニークな群要素を計算し、それぞれの操作に簡易ラベルを付けて返します。詳細説明: unique_closure を使用して生成元から全ての群要素行列を計算し、 label_elements で各行列にラベルを付けます。 :param generators: 群の生成元であるNumPy行列のリスト。 :type generators: List[numpy.ndarray] :returns: ラベルと群要素行列のペアのリスト。 :rtype: List[Tuple[str, numpy.ndarray]]

指標表と群論解析

.. py:data:: PG_CHAR_TABLES: Dict[str, Dict[str, Dict[str, complex]]]

主要な点群の指標表を格納する辞書です。キーは点群シンボル、値はクラス名と既約表現ごとの指標を持つ辞書です。非結晶性点群（I, Ih, C3h）やC4hなど、計算で生成される表も含まれます。

.. py:function:: character_table(pg: str) -> Dict[str, Dict[str, complex]]

指定された点群の指標表（classes, irreps）を返します。

概要: 与えられた点群シンボルに対応する指標表を検索し、そのクラスと既約表現の指標を返します。詳細説明: PG_CHAR_TABLES 辞書から対応する指標表を取得します。サポートされていない点群の場合は ValueError を発生させます。シンボルは normalize_symbol で正規化されます。 :param pg: 点群シンボル。 :type pg: str :returns: 指標表を含む辞書。キーは 'classes' (クラス名のリスト) と 'irreps' (既約表現ごとの指標の辞書)。 :rtype: Dict[str, Dict[str, complex]] :raises ValueError: 指定された点群の指標表が利用できない場合。

.. py:data:: ABSTRACT_CLASS_SIZES: Dict[str, Dict[str, int]]

pymatgen/builder で直接構築できない抽象群のクラスサイズを定義する辞書。例: C3h, I, Ih。

.. py:function:: _unit(v: numpy.ndarray) -> numpy.ndarray

ベクトルを単位化します。

概要: 入力ベクトルを単位ベクトルに変換します。詳細説明: ベクトルのノルムが非常に小さい場合でもゼロ除算を避けるために小さな値を加えます。 :param v: 単位化するベクトル。 :type v: numpy.ndarray :returns: 単位ベクトル。 :rtype: numpy.ndarray

.. py:function:: _close_to(v: numpy.ndarray, cands: List[numpy.ndarray], tol: float = 0.1) -> bool

ベクトルが候補ベクトルのいずれかに近似しているかを判定します。

概要: 与えられた単位ベクトルが、候補リスト内のいずれかの単位ベクトルに指定されたトレランス内で近似するかどうかをチェックします。詳細説明: 入力ベクトルと各候補ベクトルの内積の絶対値を計算し、それが 1 - tol より大きい場合に近似と見なします。 :param v: 比較する単位ベクトル。 :type v: numpy.ndarray :param cands: 比較対象の候補ベクトルリスト。 :type cands: List[numpy.ndarray] :param tol: 近似を判定する許容誤差。 :type tol: float :returns: ベクトルが候補群に近似していればTrue、そうでなければFalse。 :rtype: bool

.. py:function:: _orth_keep_det(R: numpy.ndarray) -> numpy.ndarray

行列を直交化し、行列式の符号を維持します。

概要: 入力行列を最も近い直交行列に変換し、元の行列式の符号が正であれば新しい行列式も正に、負であれば負になるように調整します。詳細説明: 特異値分解 (SVD) を使用して行列を直交化します。もし直交化後の行列式が元の符号と異なる場合、SVDのU行列の最後の列の符号を反転させて調整します。 :param R: 直交化する行列。 :type R: numpy.ndarray :returns: 直交化され、行列式の符号が維持された行列。 :rtype: numpy.ndarray

.. py:function:: _rot_axis(R: numpy.ndarray) -> Optional[numpy.ndarray]

回転行列の回転軸を抽出します。

概要: 与えられた回転行列の固定軸（回転軸）を実固有ベクトルとして特定し、正規化されたベクトルを返します。詳細説明: 回転行列の固有値を計算し、固有値1に対応する実固有ベクトルを回転軸と見なします。もし固有値1に対応する固有ベクトルが見つからない場合や、実数部が1に近似しない場合はNoneを返します。 :param R: 回転行列。 :type R: numpy.ndarray :returns: 回転軸を示す単位ベクトル、またはNone。 :rtype: Optional[numpy.ndarray]

.. py:function:: _angle_from_trace(R: numpy.ndarray) -> float

回転行列のトレースから回転角度を計算します。

概要: 回転行列のトレース情報を使用して、その回転が表す角度（ラジアン）を計算します。詳細説明: 回転行列Rのトレース tr(R) は 1 + 2*cos(theta) の関係があります。この式を逆算して theta = arccos((tr(R)-1)/2) を求めます。数値誤差を考慮して (tr(R)-1)/2 の値は [-1, 1] にクリップされます。 :param R: 回転行列。 :type R: numpy.ndarray :returns: 回転角度（ラジアン）。 :rtype: float

.. py:function:: classify_op_for_table(pg: str, R: numpy.ndarray, tol: float = 1e-6) -> str

回転行列を、指定された点群の指標表中のクラス名に対応づけて分類します。

概要: 与えられた対称操作行列を、点群のコンテキストに基づいて標準的なクラスラベル（例: "C2", "C2(x)", "σh"）に分類します。詳細説明: まず行列を直交化し、行列式を±1に修正します。その後、行列式、トレース、固有ベクトル、そして特定の点群（例: D2h, D4h）の軸の方向に基づいて操作を分類します。例えば、C2操作は点群によって "C2(x)", "C2(y)", "C2(z)"、または単に "C2" とラベル付けされます。 :param pg: 点群シンボル (例: "C2v", "D2h")。 :type pg: str :param R: 分類する3x3の対称操作行列。 :type R: numpy.ndarray :param tol: 浮動小数点比較の許容誤差。 :type tol: float :returns: 指標表のクラス名に対応する文字列ラベル。 :rtype: str

.. py:function:: class_aggregation(pg: str, raw_labels: List[str]) -> Tuple[List[str], Dict[str, str]]

生の操作ラベルを、指定された点群の指標表のクラス名に集約します。

概要: classify_op_for_table によって生成された詳細な操作ラベルを、点群の指標表で定義されているクラス名にマッピングし、集約します。詳細説明: 点群の指標表からクラスのリストを取得し、入力された生のラベルをこれらのクラス名に対応付ける辞書を構築します。例えば、"σ_v(φ=0)" や "σ_v(φ=90)" のような複数のσv面が単一の "σv" クラスに集約されます。 :param pg: 点群シンボル。 :type pg: str :param raw_labels: 各対称操作に対する生の文字列ラベルのリスト。 :type raw_labels: List[str] :returns: (指標表のクラス名のリスト, 生ラベルからクラス名へのマッピング辞書) のタプル。 :rtype: Tuple[List[str], Dict[str, str]]

.. py:function:: _parse_power(label: str, default_n: Optional[int] = None) -> Tuple[str, Optional[int], int]

操作ラベルから回転軸の次数と指数を解析します。

概要: "C3^2" のような操作ラベルを解析し、操作の種類 ('C'/'S')、次数 (3)、指数 (2) を抽出します。詳細説明: ラベルに "^" が含まれる場合、ベースと指数に分割します。ベース部分から操作の種類（C, Sなど）と次数を抽出します。次数が数値でない場合は default_n を使用します。 :param label: 解析する操作ラベル。 :type label: str :param default_n: 次数が解析できない場合のデフォルト値。 :type default_n: Optional[int] :returns: (操作の種類, 次数, 指数) のタプル。 :rtype: Tuple[str, Optional[int], int]

.. py:function:: polar_trace_from_label(lab: str) -> float

操作ラベルから、3次元の直交変換行列のトレースを計算します。

概要: 与えられた対称操作のラベルに基づいて、その操作の3x3行列のトレース（対角成分の和）を返します。詳細説明: 'E' は3、'i' は-3。鏡映操作 ('σ') は1。回転操作 ('C') は 1 + 2*cos(theta) を計算します。回映操作 ('S') は 2*cos(theta) - 1 を計算します。角度 theta はラベルから解析される次数 n と指数 p に基づきます (2*pi*p/n)。 :param lab: 対称操作のラベル。 :type lab: str :returns: その操作の3x3行列のトレース。 :rtype: float

.. py:function:: det_from_label(lab: str) -> int

操作ラベルから、その操作の行列式を返します。

概要: 与えられた対称操作のラベルに基づいて、その操作の行列式 (1または-1) を返します。詳細説明: 'E' や 'C' (純粋回転) 操作は行列式が1です。 'i' (反転)、'σ' (鏡映)、'S' (回映) 操作は行列式が-1です。 :param lab: 対称操作のラベル。 :type lab: str :returns: 行列式 (1または-1)。 :rtype: int

.. py:function:: gamma_3N_characters(coords: numpy.ndarray, op_mats: List[numpy.ndarray], labels: List[str], tol: float = 1e-5) -> Dict[str, float]

分子の全並進振動モード (Γ_3N) の指標を計算します。

概要: 与えられた原子座標、対称操作行列、およびそれらのラベルを使用して、分子の全振動モードの可約表現の指標を計算します。詳細説明: 各対称操作Rに対して、その操作によって移動しない原子を特定します。移動しない原子については、Rのトレースが指標に貢献します。全ての操作についてこれを合計し、各ラベルに対応する総指標を算出します。 :param coords: 原子座標のNumPy配列 (N, 3)。 :type coords: numpy.ndarray :param op_mats: 対称操作行列のリスト。 :type op_mats: List[numpy.ndarray] :param labels: 各操作行列に対応するラベルのリスト。 :type labels: List[str] :param tol: 原子位置の比較に用いる許容誤差。 :type tol: float :returns: 各操作ラベルに対するΓ_3Nの指標値の辞書。 :rtype: Dict[str, float]

.. py:function:: gamma_trans_characters(labels: List[str], class_map: Dict[str, str]) -> Dict[str, float]

分子の並進振動モード (Γ_T) の指標を計算します。

概要: 対称操作のラベルとクラスマップを使用して、分子の並進モードの可約表現の指標を計算します。詳細説明: 各操作ラベルについて、その操作の3x3行列のトレースを polar_trace_from_label を用いて計算します。これらのトレース値をクラスマップに従って集約し、各クラスのΓ_T指標を求めます。 :param labels: 各対称操作のラベルのリスト。 :type labels: List[str] :param class_map: 生ラベルから指標表クラス名へのマッピング辞書。 :type class_map: Dict[str, str] :returns: 各クラスに対するΓ_Tの指標値の辞書。 :rtype: Dict[str, float]

.. py:function:: gamma_rot_characters(labels: List[str], class_map: Dict[str, str]) -> Dict[str, float]

分子の回転振動モード (Γ_R) の指標を計算します。

概要: 対称操作のラベルとクラスマップを使用して、分子の回転モードの可約表現の指標を計算します。詳細説明: 各操作ラベルについて、その操作の3x3行列のトレースにその行列式 (det_from_label) を乗じた値を計算します。これは、回転操作 (det=1) にはトレースそのままを、回転-反転操作 (det=-1) にはトレースに-1を乗じた値を意味します。これらの値をクラスマップに従って集約し、各クラスのΓ_R指標を求めます。 :param labels: 各対称操作のラベルのリスト。 :type labels: List[str] :param class_map: 生ラベルから指標表クラス名へのマッピング辞書。 :type class_map: Dict[str, str] :returns: 各クラスに対するΓ_Rの指標値の辞書。 :rtype: Dict[str, float]

.. py:function:: reduce_to_classes(vec_by_label: Dict[str, float], classes: List[str], class_map: Dict[str, str]) -> Dict[str, float]

ラベルごとの指標ベクトルを指標表のクラスに集約します。

概要: 詳細な操作ラベルに対応する指標値を、点群の指標表で定義されたクラス名に対応する指標値に集約します。詳細説明: class_map を使用して、各ラベルの指標値を対応するクラスに加算します。最終結果は、指標表の全てのクラス名を含む辞書として返され、対応する指標値がないクラスには0が割り当てられます。 :param vec_by_label: 各操作ラベルに対する指標値の辞書。 :type vec_by_label: Dict[str, float] :param classes: 指標表で定義されたクラス名のリスト。 :type classes: List[str] :param class_map: 生ラベルから指標表クラス名へのマッピング辞書。 :type class_map: Dict[str, str] :returns: 各クラスに対する集約された指標値の辞書。 :rtype: Dict[str, float]

.. py:function:: group_order(symbol: str) -> int

点群の位数を返します。

概要: 指定された点群シンボルに対応する群の位数（要素数）を返します。詳細説明: build_group で構築可能な群については、実際に構築された操作の数を返します。 ABSTRACT_CLASS_SIZES に定義されている抽象群については、その合計クラスサイズを返します。どちらにも対応しない場合は ValueError を発生させます。 :param symbol: 点群シンボル。 :type symbol: str :returns: 点群の位数。 :rtype: int :raises ValueError: サポートされていない、または抽象定義されていない点群シンボルが指定された場合。

.. py:function:: group_ops(symbol: str) -> List[numpy.ndarray]

点群の全ての対称操作（3x3行列）を返します。

概要: 指定された点群シンボルに対応する全ての対称操作行列のリストを返します。詳細説明: build_group 関数を呼び出して操作行列を構築し、snap_matrix で正規化します。 build_group で対応していない抽象群の場合は、ValueError が発生します。 :param symbol: 点群シンボル。 :type symbol: str :returns: 点群の全ての対称操作行列のリスト。 :rtype: List[numpy.ndarray] :raises ValueError: 抽象群など、build_group で操作行列を構築できない場合。

.. py:function:: decompose_irreps(chars_by_class: Dict[str, float], pg: str, class_sizes_override: Optional[Dict[str, int]] = None, order_override: Optional[int] = None) -> Dict[str, int]

クラスごとの指標ベクトルを既約表現へ直交分解します。

概要: 与えられた可約表現の指標ベクトルを、指定された点群の既約表現に分解し、各既約表現の多重度を計算します。詳細説明: 群論の直交性定理 (m_i = (1/h) * sum(chi_reducible(R) * chi_irreducible(R)* * N_R)) を使用します。 h は群の位数、N_R はクラスRの要素数、chi(R) はクラスRの指標です。クラスサイズと群の位数は、class_sizes_override や order_override で明示的に指定できます。指定がない場合、group_order と classify_op_for_table を用いて自動的に計算されます。 :param chars_by_class: 各クラスに対する可約表現の指標値の辞書。 :type chars_by_class: Dict[str, float] :param pg: 点群シンボル。 :type pg: str :param class_sizes_override: クラスサイズを明示的に指定する辞書（クラス名: サイズ）。 :type class_sizes_override: Optional[Dict[str, int]] :param order_override: 群の位数を明示的に指定する整数。 :type order_override: Optional[int] :returns: 各既約表現名とその多重度（整数）の辞書。 :rtype: Dict[str, int] :raises ValueError: 指定された点群の指標表が利用できない場合、または群の位数を特定できない場合。

.. py:function:: pretty_irreps(pg: str, mults: Dict[str, int]) -> str

既約表現の多重度を見やすい和の形式で整形します。

概要: 既約表現の多重度を示す辞書を受け取り、それを "A1 + 2E + T2" のような人間が読みやすい文字列形式に変換します。詳細説明: 一般的な点群の既約表現には標準的な並び順があります。この関数では、order_map を使用して、指定された点群の既約表現をその慣習的な順序で並べ替えます。多重度が1より大きい場合は 2E のように係数を付け、1の場合は A1 のように表現名を直接使用します。多重度が0の表現は省略されます。 :param pg: 点群シンボル。 :type pg: str :param mults: 各既約表現名とその多重度（整数）の辞書。 :type mults: Dict[str, int] :returns: 整形された既約表現の和の文字列。 :rtype: str