tkpointgroup.py 技術ドキュメント
このドキュメントは、Pythonライブラリ tkpointgroup.py の技術的な側面を詳細に記述します。
ライブラリの機能や目的
tkpointgroup.py は、分子や結晶の点群対称性に関するユーティリティ機能を提供する純粋なNumPyベースのライブラリです。主に以下の目的と機能を持っています。
Herman–Mauguin (国際記号) と Schoenflies (シェーンフリース記号) の相互変換: 点群の記号体系間の変換をサポートします。
点群要素の生成と管理: 指定された点群記号から、その群に含まれるすべての対称操作行列（重複なし）を取得したり、生成元（ジェネレーター）を特定したりします。生成元から群全体を構成する機能も提供します。
幾何学的操作のユーティリティ: 回転、鏡映、反転といった基本的な3次元幾何学操作のための行列を生成します。また、数値的な誤差を許容しつつ行列要素を代表値にスナップし、直交性や決定因子を保証する機能も持ちます。
点の軌道と独立代表点の計算: 与えられた点と群の対称操作セットに対して、その点によって生成される軌道上のすべての等価な点、および重複を除去した独立代表点を特定します。
点群指標表と既約表現の分解: 主要な点群の指標表（キャラクターテーブル）を提供し、任意のレデューシブル表現（例えば分子の振動モードの表現）を既約表現に分解する機能を提供します。
このライブラリは、計算化学、物性物理、材料科学などの分野で、分子や結晶の対称性を扱う際の基盤となるツールとして利用されることを想定しています。
importする方法
tkpointgroup.py ライブラリを他のPythonプログラムから利用するには、通常のPythonモジュールと同様に import ステートメントを使用します。
ライブラリ全体をインポートする場合:
import tkpointgroup
特定の関数や変数を直接インポートする場合:
from tkpointgroup import build_group, get_all_operations, character_table
必要な非標準ライブラリとインストール方法
このライブラリは numpy に依存しています。numpy は科学技術計算で広く使用される非標準ライブラリです。
numpy がシステムにインストールされていない場合、以下の pip コマンドでインストールできます。
pip install numpy
importできる変数と関数
以下に tkpointgroup.py から import できる主要な変数と関数、およびその説明を記述します。
グローバル変数
ex:numpy.array([1, 0, 0.])x軸方向の単位ベクトル。
ey:numpy.array([0, 1, 0.])y軸方向の単位ベクトル。
ez:numpy.array([0, 0, 1.])z軸方向の単位ベクトル。
_SNAP_VALUES:listsnap_matrix関数が行列要素をスナップする際に参照する代表的な浮動小数点値のリスト。0.0,0.5,-0.5,1.0/sqrt(2),sqrt(3)/2,1.0,-1.0などが含まれます。
_S_to_H:dictSchoenflies記号からHerman–Mauguin記号への変換マップ。一部は代表的な対応に丸められます。
_H_to_S:dictHerman–Mauguin記号からSchoenflies記号への変換マップ。値は代表的なSchoenflies記号が採用されます。
SUPPORTED:listこのライブラリが
build_group関数でサポートする点群シンボルのリスト。Schoenflies記号と国際記号の両方が含まれます。
PG_CHAR_TABLES:dict主要な点群の指標表（キャラクターテーブル）を格納する辞書。キーは点群シンボル、値はその群のクラスと既約表現ごとの指標を示す辞書です。
ABSTRACT_CLASS_SIZES:dictbuild_group関数では直接操作行列を生成できない抽象的な点群（例: 正二十面体群 I, Ih, C3h）に対して、その群の各クラスのサイズ（要素数）を定義する辞書。
関数
基本ユーティリティ
rot(axis: numpy.ndarray, angle_deg: float) -> numpy.ndarray指定された軸を中心に指定された角度（度数法）だけ回転する3x3回転行列を生成します。
引数:
axis(numpy.ndarray): 回転軸を表す3要素のベクトル。angle_deg(float): 回転角度（度数法）。
戻り値:
numpy.ndarray: 回転行列。
数式: ロドリゲスの回転公式に基づいて回転行列 \(R\) を計算します。単位ベクトル \(\mathbf{a} = (x, y, z)\) と回転角度 \(\theta\) (ラジアン) に対して、 $\(R = \begin{pmatrix} c + x^2(1-c) & xy(1-c) - zs & xz(1-c) + ys \\ yx(1-c) + zs & c + y^2(1-c) & yz(1-c) - xs \\ zx(1-c) - ys & zy(1-c) + xs & c + z^2(1-c) \end{pmatrix}\)\( ここで \)c = \cos\theta\(, \)s = \sin\theta$ です。
mirror(normal: numpy.ndarray) -> numpy.ndarray指定された法線ベクトルを持つ平面に対する鏡映（ミラー）操作の3x3行列を生成します。
引数:
normal(numpy.ndarray): 鏡映面の法線ベクトル。
戻り値:
numpy.ndarray: 鏡映行列。
数式: 単位法線ベクトル \(\mathbf{n}\) に対する鏡映行列 \(M\) は、単位行列 \(I\) と外積 \(\mathbf{n}\mathbf{n}^T\) を用いて次のように表されます。 $\(M = I - 2 \mathbf{n}\mathbf{n}^T\)$
inversion() -> numpy.ndarray原点に対する反転（inversion）操作の3x3行列を生成します。
引数: なし。
戻り値:
numpy.ndarray: 反転行列（対角要素が全て -1 の3x3行列）。
snap_matrix(M: numpy.ndarray) -> numpy.ndarray入力行列の要素を、定義済みの代表値 (
_SNAP_VALUES) に最も近い値にスナップします。さらに、直交性（\(M^T M = I\)）と決定因子が \(\pm 1\) であることを保証します。引数:
M(numpy.ndarray): スナップ処理を行う3x3行列。
戻り値:
numpy.ndarray: 修正・スナップされた行列。
動作:
各要素を
_SNAP_VALUESにスナップできるかチェックし、可能であればスナップ。行列が直交でない場合、特異値分解（SVD）を用いて直交行列に変換します。変換は \(X = U V^T\) で行われます。
決定因子が \(\pm 1\) でない場合、再度SVDを利用し、特異値の符号を調整することで決定因子を \(\pm 1\) に修正します。
mat_key(M: numpy.ndarray) -> tuple行列の要素を丸めて一意なタプルキーを生成し、辞書で重複を判定するなどの用途に利用します。
引数:
M(numpy.ndarray): 3x3行列。
戻り値:
tuple: 行列の要素を10桁の精度で丸めたフラットなタプル。
unique_closure(generators: List[numpy.ndarray]) -> List[numpy.ndarray]与えられた生成元行列のリストから、それらによって生成される有限群の全ての要素（操作行列）を重複なく取得します。
引数:
generators(List[numpy.ndarray]): 群の生成元となる行列のリスト。
戻り値:
List[numpy.ndarray]: 生成された全てのユニークな行列のリスト。
動作: 単位行列から開始し、キューイングと既知の要素の組み合わせを繰り返すことで群の閉包を構築します。
snap_matrixとmat_keyを利用して数値的な誤差に対応し、重複を排除します。
vertical_plane(phi_deg: float) -> numpy.ndarrayz軸に垂直な面に対する垂直鏡映面を定義する法線ベクトルを生成します。
引数:
phi_deg(float): XY平面内での法線ベクトルの角度（度数法）。
戻り値:
numpy.ndarray: 鏡映面の法線ベクトル。
diagonal_plane(phi_deg: float) -> numpy.ndarrayz軸に垂直な平面上で、
vertical_planeで定義される面から45度傾いた（対角的な）鏡映面を定義する法線ベクトルを生成します。引数:
phi_deg(float): XY平面内での基準となる角度（度数法）。
戻り値:
numpy.ndarray: 鏡映面の法線ベクトル。
群ビルダー
build_Cn から build_Oh までの関数群は、各点群シンボルに対応する生成元から unique_closure を呼び出し、その点群の全要素行列を構築します。
build_Cn(n: int) -> List[numpy.ndarray]\(C_n\) 群の全操作行列を生成します。
build_Cnv(n: int) -> List[numpy.ndarray]\(C_{nv}\) 群の全操作行列を生成します。
build_Cnh(n: int) -> List[numpy.ndarray]\(C_{nh}\) 群の全操作行列を生成します。
build_Sn(n: int) -> List[numpy.ndarray]\(S_n\) 群の全操作行列を生成します。
build_Dn(n: int) -> List[numpy.ndarray]\(D_n\) 群の全操作行列を生成します。
build_Dnh(n: int) -> List[numpy.ndarray]\(D_{nh}\) 群の全操作行列を生成します。
build_Dnd(n: int) -> List[numpy.ndarray]\(D_{nd}\) 群の全操作行列を生成します。
build_T() -> List[numpy.ndarray]\(T\) (四面体) 群の全操作行列を生成します。
build_Th() -> List[numpy.ndarray]\(T_h\) (正八面体群の部分群) 群の全操作行列を生成します。
build_Td() -> List[numpy.ndarray]\(T_d\) (完全四面体) 群の全操作行列を生成します。
build_O() -> List[numpy.ndarray]\(O\) (正八面体) 群の全操作行列を生成します。
build_Oh() -> List[numpy.ndarray]\(O_h\) (完全八面体) 群の全操作行列を生成します。
記号の正規化と相互変換
normalize_symbol(s: str) -> str入力された点群シンボル文字列から、スペース、ハイフン、アンダースコアなどの不要な文字を除去し、正規化します。
引数:
s(str): 点群シンボル文字列。
戻り値:
str: 正規化されたシンボル文字列。
schoenflies_to_hm(s: str) -> strSchoenflies記号をHerman–Mauguin記号に変換します。
引数:
s(str): Schoenflies記号。
戻り値:
str: 対応するHerman–Mauguin記号。変換マップにない場合は入力された記号をそのまま返します。
hm_to_schoenflies(h: str) -> strHerman–Mauguin記号をSchoenflies記号に変換します。
引数:
h(str): Herman–Mauguin記号。
戻り値:
str: 対応するSchoenflies記号。変換マップにない場合は入力された記号をそのまま返します。
サポート一覧 / 構築エントリ
supported_symbols() -> List[str]このライブラリが
build_groupで直接操作行列を生成できる点群シンボルの一覧を返します。引数: なし。
戻り値:
List[str]: サポートされている点群シンボル名のリスト。
build_group(symbol: str) -> List[numpy.ndarray]与えられた点群シンボルに基づいて、その点群の全ての対称操作行列を生成し、リストとして返します。
引数:
symbol(str): 点群シンボル（SchoenfliesまたはHerman–Mauguin記号）。
戻り値:
List[numpy.ndarray]: 点群の全操作行列のリスト。
例外:
ValueError: サポートされていない点群シンボルが指定された場合。
ラベリング
classify_label(M: numpy.ndarray) -> str与えられた対称操作行列を、その種類（例: "E" (恒等), "i" (反転), "σ_h" (水平鏡映), "C(z,120)" (z軸周り120度回転)）に基づいて分類し、対応するラベルを返します。
引数:
M(numpy.ndarray): 対称操作行列。
戻り値:
str: 分類された操作のラベル。
label_elements(mats: List[numpy.ndarray]) -> List[Tuple[str, numpy.ndarray]]対称操作行列のリストを受け取り、それぞれの行列に
classify_labelで生成されたラベルを付与したタプルのリストを返します。引数:
mats(List[numpy.ndarray]): 対称操作行列のリスト。
戻り値:
List[Tuple[str, numpy.ndarray]]:(ラベル, 行列)のタプルのリスト。
generators_for(symbol: str) -> List[Tuple[str, numpy.ndarray]]指定された点群シンボルに対する「標準的な」生成元（ラベル付き）を返します。標準的な生成元が定義されていない国際記号などの場合は、空のリストを返すか、
get_all_operationsにフォールバックします。引数:
symbol(str): 点群シンボル。
戻り値:
List[Tuple[str, numpy.ndarray]]:(ラベル, 生成元行列)のタプルのリスト。
軌道・独立代表点（重複削除）
point_key(p: numpy.ndarray, tol=1e-8) -> tuple与えられた点（座標ベクトル）から、浮動小数点誤差を考慮した一意なキーを生成します。点の同一性判定に利用されます。
引数:
p(numpy.ndarray): 3要素の座標ベクトル。tol(float): 比較の許容誤差。
戻り値:
tuple: 点の丸められた座標に基づくタプルキー。
orbit_for_point(ops: List[numpy.ndarray], p: numpy.ndarray, tol=1e-8) -> List[Tuple[numpy.ndarray, List[int]]]一点
pに群の全ての操作opsを適用して得られる軌道を計算します。軌道上の各点に対して、その点と、それを生成した操作のインデックスのリストを返します。引数:
ops(List[numpy.ndarray]): 対称操作行列のリスト。p(numpy.ndarray): 3要素の座標ベクトル。tol(float): 座標比較の許容誤差。
戻り値:
List[Tuple[numpy.ndarray, List[int]]]:(軌道上の点, その点を生成した操作のインデックスリスト)のタプルのリスト。
dedup_points(orbits: List[Tuple[numpy.ndarray, List[int]]], tol=1e-8) -> List[Tuple[numpy.ndarray, List[int]]]orbit_for_pointから得られた軌道点のリストから、重複する点を削除し、各ユニークな点に対してそれを生成する全ての操作のインデックスをまとめます。引数:
orbits(List[Tuple[numpy.ndarray, List[int]]]):(点, 操作インデックスリスト)のリスト。tol(float): 座標比較の許容誤差。
戻り値:
List[Tuple[numpy.ndarray, List[int]]]:(ユニークな点, その点を生成した全ての操作のソート済みインデックスリスト)のタプルのリスト。
unique_orbit_points(ops: List[numpy.ndarray], p: numpy.ndarray, tol=1e-8) -> List[Tuple[numpy.ndarray, List[int]]]orbit_for_pointとdedup_pointsを組み合わせた高レベル関数。指定された点pと操作opsに対して、重複のない独立な軌道点と、それらを生成した操作のインデックスを返します。引数:
ops(List[numpy.ndarray]): 対称操作行列のリスト。p(numpy.ndarray): 3要素の座標ベクトル。tol(float): 座標比較の許容誤差。
戻り値:
List[Tuple[numpy.ndarray, List[int]]]:(ユニークな点, その点を生成した全ての操作のソート済みインデックスリスト)のタプルのリスト。
高レベルAPI
get_all_operations(symbol: str) -> List[Tuple[str, numpy.ndarray]]点群シンボルから、その群に含まれる全ての対称操作（ラベル付き）のリストを返します。
引数:
symbol(str): 点群シンボル。
戻り値:
List[Tuple[str, numpy.ndarray]]:(ラベル, 行列)のタプルのリスト。
get_generators(symbol: str) -> List[Tuple[str, numpy.ndarray]]点群シンボルから、その群の生成元（ラベル付き）のリストを返します。生成元が明確に定義されていない群（国際記号など）の場合は、全ての操作を返す
get_all_operationsにフォールバックします。引数:
symbol(str): 点群シンボル。
戻り値:
List[Tuple[str, numpy.ndarray]]:(ラベル, 行列)のタプルのリスト。
elements_from_generators(generators: List[numpy.ndarray]) -> List[Tuple[str, numpy.ndarray]]生成元行列のリストから、群の閉包を計算し、全ての要素（ラベル付き）を返します。
引数:
generators(List[numpy.ndarray]): 生成元行列のリスト。
戻り値:
List[Tuple[str, numpy.ndarray]]:(ラベル, 行列)のタプルのリスト。
点群指標表と既約表現の分解
character_table(pg: str) -> Dict[str, Dict[str, complex]]指定された点群の指標表（キャラクターテーブル）を返します。指標表には、クラスの順序 (
classes) と既約表現ごとの指標 (irreps) が含まれます。引数:
pg(str): 点群シンボル。
戻り値:
Dict[str, Dict[str, complex]]: 指標表を表す辞書。キーは "classes" と "irreps"。
例外:
ValueError: 指定された点群の指標表が利用できない場合。
classify_op_for_table(pg: str, R: numpy.ndarray, tol=1e-6) -> str対称操作行列
Rを、指定された点群pgの指標表で使用されるクラス名に対応付けて分類します。classify_labelよりも指標表の慣例に合わせた詳細な分類を行います（例: \(C_2(x)\), \(\sigma_h\) など）。引数:
pg(str): 点群シンボル。R(numpy.ndarray): 対称操作行列。tol(float): 比較の許容誤差。
戻り値:
str: 指標表のクラス名に対応する操作ラベル。
class_aggregation(pg: str, raw_labels: List[str]) -> Tuple[List[str], Dict[str, str]]classify_op_for_tableで得られた詳細な操作ラベルを、指定された点群pgの指標表で定義されているクラス名に集約します。引数:
pg(str): 点群シンボル。raw_labels(List[str]):classify_op_for_tableから得られた操作ラベルのリスト。
戻り値:
Tuple[List[str], Dict[str, str]]:(指標表のクラス名のリスト, 生ラベルからクラス名へのマッピング辞書)のタプル。
polar_trace_from_label(lab: str) -> float操作ラベルに基づいて、その操作の3x3行列のトレース（対角成分の和）を計算します。これは並進表現の指標
$\chi_T$の計算に用いられます。引数:
lab(str): 操作ラベル（例: "E", "C2", "sigma_h"）。
戻り値:
float: 操作行列のトレース。
数式: 回転操作 \(C_n^p\) の場合、トレースは \(1 + 2 \cos(2\pi p/n)\)。 回映操作 \(S_n^p\) の場合、トレースは \(2 \cos(2\pi p/n) - 1\)。 恒等操作 \(E\) は \(3.0\)、反転操作 \(i\) は \(-3.0\)、鏡映操作 \(\sigma\) は \(1.0\)。
det_from_label(lab: str) -> int操作ラベルに基づいて、その操作の行列の決定因子を計算します。これは回転表現の指標
$\chi_R$の計算に用いられます。引数:
lab(str): 操作ラベル。
戻り値:
int: 行列の決定因子（1または-1）。
gamma_3N_characters(coords: numpy.ndarray, op_mats: List[numpy.ndarray], labels: List[str], tol=1e-5) -> Dict[str, float]原子座標のセット
coordsと対称操作op_matsから、3N次元表現 \(\Gamma_{3N}\) の指標を計算します。原子が移動しない（固定されている）場合にのみ、その原子に作用する操作のトレースが寄与します。引数:
coords(numpy.ndarray): 原子座標（\(N \times 3\) の配列）。op_mats(List[numpy.ndarray]): 対称操作行列のリスト。labels(List[str]):op_matsに対応する操作ラベルのリスト。tol(float): 原子が固定されているとみなす許容誤差。
戻り値:
Dict[str, float]: 操作ラベルごとの \(\Gamma_{3N}\) の指標。
数式: 各操作 \(R\) に対して、\(\Gamma_{3N}(R)\) の指標 \(\chi_{3N}(R)\) は、その操作によって固定される原子 \(j\) の数と、その原子に作用する操作行列のトレースの和で与えられます。 $\(\chi_{3N}(R) = \sum_{j \text{ (fixed)}} \mathrm{Tr}(R_j)\)\( ここで \)R_j\( は原子 \)j\( に作用する \)R\( の部分行列ですが、通常は点群操作全体と同じ \)R$ を使用できます。
gamma_trans_characters(labels: List[str], class_map: Dict[str, str]) -> Dict[str, float]並進表現 \(\Gamma_T\) の指標を計算します。
引数:
labels(List[str]): 操作ラベルのリスト。class_map(Dict[str, str]): 生ラベルからクラス名へのマッピング。
戻り値:
Dict[str, float]: クラス名ごとの \(\Gamma_T\) の指標。
gamma_rot_characters(labels: List[str], class_map: Dict[str, str]) -> Dict[str, float]回転表現 \(\Gamma_R\) の指標を計算します。
引数:
labels(List[str]): 操作ラベルのリスト。class_map(Dict[str, str]): 生ラベルからクラス名へのマッピング。
戻り値:
Dict[str, float]: クラス名ごとの \(\Gamma_R\) の指標。
reduce_to_classes(vec_by_label: Dict[str, float], classes: List[str], class_map: Dict[str, str]) -> Dict[str, float]操作ラベルごとに計算された指標ベクトルを、指標表で定義されたクラスごとに集約します。
引数:
vec_by_label(Dict[str, float]): 操作ラベルごとの指標値の辞書。classes(List[str]): 指標表のクラス名のリスト。class_map(Dict[str, str]): 生ラベルからクラス名へのマッピング。
戻り値:
Dict[str, float]: クラス名ごとの集約された指標値の辞書。
group_order(symbol: str) -> int指定された点群の位数（群の要素数）を返します。
build_groupで構築可能な場合は実際の要素数、抽象群の場合はABSTRACT_CLASS_SIZESから計算されます。引数:
symbol(str): 点群シンボル。
戻り値:
int: 群の位数。
例外:
ValueError: サポートされていない抽象群の場合。
group_ops(symbol: str) -> List[numpy.ndarray]点群シンボルから、その群の全ての操作行列（3x3）を返します。
build_groupが利用できない抽象群の場合は例外を発生させます。引数:
symbol(str): 点群シンボル。
戻り値:
List[numpy.ndarray]: 全操作行列のリスト。
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]クラスごとの指標ベクトル（レデューシブル表現の指標）を、指定された点群
pgの既約表現に直交分解します。引数:
chars_by_class(Dict[str, float]): クラス名ごとのレデューシブル表現の指標値。pg(str): 点群シンボル。class_sizes_override(Optional[Dict[str, int]]): クラスサイズを明示的に指定する場合の辞書。order_override(Optional[int]): 群の位数を明示的に指定する場合。
戻り値:
Dict[str, int]: 各既約表現の重複度（その既約表現がレデューシブル表現に何回含まれるか）を示す辞書。
数式: 既約表現 \(i\) の重複度 \(a_i\) は、群の位数 \(h\)、各クラスの要素数 \(g_k\)、レデューシブル表現の指標 \(\chi_{red}(R_k)\)、既約表現 \(i\) の指標 \(\chi_i(R_k)\) を用いて、次の直交性定理によって計算されます。 $\(a_i = \frac{1}{h} \sum_k g_k \cdot \chi_{red}(R_k) \cdot \chi_i(R_k)^*\)\( ここで \)R_k\( はクラス \)k\( に属する任意の操作、\)\chi_i(R_k)^*\( は \)\chi_i(R_k)$ の複素共役です。
pretty_irreps(pg: str, mults: Dict[str, int]) -> strdecompose_irrepsの結果（各既約表現の重複度）を、人間が読みやすい形式の文字列で整形して返します（例: "A1 + B1 + 2E")。引数:
pg(str): 点群シンボル。表示順序のヒントとして使用されます。mults(Dict[str, int]): 既約表現の重複度を示す辞書。
戻り値:
str: 整形された既約表現の和の文字列。
main scriptとして実行したときの動作
tkpointgroup.py のソースコードには、if __name__ == "__main__": ブロックが存在しません。
したがって、このライブラリファイルを直接Pythonインタープリタで実行しても、特別な処理は行われません。
このライブラリは、他のプログラムから import されて利用されることを目的として設計されています。