pg_generators プログラム仕様
点群の生成元とそれらの語表現を計算するスクリプト。
詳細説明: このスクリプトは、Pymatgenライブラリを用いて特定の点群（H–M記法）の対称操作を取得し、 その操作集合から最小限の生成元セットを特定します。 さらに、点群内の各操作を、見つけられた生成元とそれらのべき乗の積（語表現）として表現します。 数値的な丸め誤差による問題を避けるため、対称操作の直交化やスナップ処理が組み込まれています。 また、生成元には優先順位を付けて抽出され、ユーザーが任意のラベルを付けることも可能です。 計算結果は、標準出力またはJSON形式で出力されます。
- crystal.pg_generators.axis_label(v)[ソース]
ベクトルを軸ラベル（x, y, z）または座標文字列に変換します。
詳細説明: 与えられたベクトルが主要な結晶学的軸（x, y, z）のいずれかに ほぼ平行である場合、対応する文字ラベルを返します。 そうでない場合は、ベクトルの丸められた座標値を文字列として返します。
- パラメータ:
v (numpy.ndarray or None) -- ラベル化するベクトル。
- 戻り値:
軸ラベルまたは座標文字列。
- 戻り値の型:
- crystal.pg_generators.build_snapper(known_ops)[ソース]
既知の対称操作集合に任意の操作を「スナップ」させる関数を構築します。
詳細説明: 浮動小数点数演算に起因する微小な誤差を吸収するため、 与えられた既知の操作集合の中で、最も近い操作に任意の行列を「スナップ」させる クロージャ関数を返します。これにより、グループ閉包の計算中に 同一の操作が異なる浮動小数点値で表現されることを防ぎます。
- パラメータ:
known_ops (list[numpy.ndarray]) -- 既知の対称操作行列のリスト。
- 戻り値:
snap(R) -> (numpy.ndarray, tuple) というシグネチャを持つ関数。 R はスナップ対象の行列、戻り値はスナップされた行列と、その正規化されたタプル形式のキー。
- 戻り値の型:
callable
- crystal.pg_generators.canon(R, ndigits=12)[ソース]
行列を正規化し、比較可能なタプル形式に変換します。
詳細説明: まず orthogonalize_preserving_det を用いて行列を直交化し、 その結果の要素を丸めて1次元のタプルに変換します。 これにより、浮動小数点数の誤差による比較の問題を避け、行列の同一性を 効率的に判定できるようになります。
- crystal.pg_generators.classify_and_geometry(R)[ソース]
3x3対称操作行列の種類と幾何学的情報を分類します。
詳細説明: 与えられた対称操作行列を恒等操作(I)、反転操作(Inv)、純粋回転(Rot)、 鏡映操作(Mir)、回反操作(Rinv)のいずれかに分類し、それぞれの幾何学的情報 （回転次数、回転軸、面法線）を返します。 行列式の符号や行列のべき乗の振る舞いを検査することで分類を行います。
- パラメータ:
R (numpy.ndarray) -- 分類する3x3対称操作行列。
- 戻り値:
(種類 (str), 次数 (int), 軸または法線 (numpy.ndarray or None))。 kind は 'I', 'Inv', 'Rot', 'Mir', 'Rinv', 'Unknown' のいずれか。 order は RotまたはRinvの場合の回転次数。 axis_or_normal は Rotの場合は回転軸、Mirの場合は面法線ベクトル。
- 戻り値の型:
- crystal.pg_generators.closure_with_words(generators, target_size, snap)[ソース]
生成元からグループの閉包を計算し、各要素の語表現を追跡します。
詳細説明: 幅優先探索（BFS）を使用して、与えられた生成元セットから到達可能な すべての対称操作（グループの閉包）を計算します。 各到達可能な操作について、それが恒等元からどのように生成されたかの「語」 （生成元のインデックス列）を記録します。snap 関数を使用して 数値的な安定性を確保します。
- crystal.pg_generators.compare_sets(setA, setB)[ソース]
2つの対称操作行列のセットが同一であるかを比較します。
詳細説明: 浮動小数点数の誤差を考慮して、2つの行列のリストが本質的に同じ要素の セットを構成しているかを判断します。 各行列を canon 関数で正規化されたタプルに変換し、集合として比較します。
- crystal.pg_generators.compute_generators_with_words(symbol, user_gen_labels=None)[ソース]
指定された点群の生成元とその語表現を計算します。
詳細説明: Pymatgenを使用して指定された点群のすべての対称操作を取得し、重複を排除します。 次に、find_generators を呼び出して生成元を見つけ、estimate_orders で位数を推定します。 最後に、closure_with_words で各操作の語表現を計算し、format_word で整形します。 ユーザーが生成元にカスタムラベルを割り当てることも可能です。
- パラメータ:
- 戻り値:
(gens, gen_labels, gen_orders, all_ops, elems, ok)。 gens: 抽出された生成元行列のリスト。 gen_labels: 各生成元のラベル（自動生成またはユーザー指定）。 gen_orders: 各生成元の位数のリスト。 all_ops: 点群のすべてのユニークな対称操作行列のリスト。 elems: (操作行列, 語表現文字列, 分類ラベル) のタプルのリスト（恒等元を除く）。 ok: 生成元からの閉包が点群全体と一致したかを示すブール値。
- 戻り値の型:
tuple[list[numpy.ndarray], list[str], list[int or None], list[numpy.ndarray], list[tuple[numpy.ndarray, str, str]], bool]
- crystal.pg_generators.default_label_of(R)[ソース]
対称操作行列のデフォルトの記号ラベルを生成します。
詳細説明: classify_and_geometry 関数で分類された情報に基づいて、 対称操作の標準的な記号ラベル（例: "E", "i", "C3(z)", "m(⊥x)", "S6"）を生成します。
- パラメータ:
R (numpy.ndarray) -- ラベルを生成する3x3対称操作行列。
- 戻り値:
対称操作の記号ラベル。
- 戻り値の型:
- crystal.pg_generators.eigvec_for_value(R, val, atol=1e-06)[ソース]
指定された固有値に対応する実固有ベクトルを抽出します。
詳細説明: 与えられた行列の固有値と固有ベクトルを計算し、指定された固有値に 数値的に近い実部を持つ固有値に対応する固有ベクトルを返します。 見つからない場合はNoneを返します。主に回転軸（固有値1）や鏡映面法線 （固有値-1）を求めるのに使用されます。
- crystal.pg_generators.estimate_orders(generators, snap)[ソース]
各生成元の位数を推定します。
詳細説明: 各生成元について、その操作を繰り返し適用し、恒等操作に戻るまでの 最小回数（位数）を計算します。 snap 関数を使用して、累積的な浮動小数点誤差による判定のずれを防ぎます。 結晶点群の文脈では、位数は通常小さいため、最大12回までの繰り返しで探索します。
- crystal.pg_generators.find_generators(all_ops)[ソース]
与えられたすべての操作から、点群の最小生成元セットを特定します。
詳細説明: symmetry_priority_score に基づいて操作をソートし、貪欲法を用いて 生成元のセットを構築します。 まず、操作を優先順位で並べ、空の生成元セットから始めて、 まだ生成されていない操作を一つずつ追加していきます。 追加した生成元で構成される閉包が、以前の閉包よりも多くのユニークな操作を 生成する場合にのみ、その操作を生成元に採用します。 最後に、冗長な生成元を削除し、慣習的な順序に並べ替えます。
- crystal.pg_generators.format_word(words_idx, gen_labels, gen_orders)[ソース]
生成元のインデックス列（語）を人間が読める文字列形式に整形します。
詳細説明: 生成元のインデックスリストを、記号ラベルと指数を用いた簡潔な文字列 （例: "C6 * m", "C6^2"）に変換します。 連続する同一の生成元はべき乗として圧縮されます。 生成元の位数が既知の場合、指数は位数で割った剰余に正規化され、 常に正の指数が使用されます。
- crystal.pg_generators.main()[ソース]
スクリプトのエントリポイント。コマンドライン引数を解析し、点群の生成元と要素を出力します。
詳細説明: argparse を使用してコマンドライン引数（点群の記号、カスタム生成元ラベル、JSON出力オプション）を解析します。 compute_generators_with_words を呼び出して点群情報を計算し、その結果を整形して標準出力に表示します。 JSONオプションが指定されている場合は、追加でJSON形式の出力も行います。
- Param:
なし
- 戻り値:
なし。スクリプトの実行結果を標準出力に出力します。
- 戻り値の型:
None
- crystal.pg_generators.orthogonalize_preserving_det(R)[ソース]
行列を直交化し、元の行列の行列式の符号を保存します。
詳細説明: 特異値分解（SVD）を用いて行列Rを直交化します。直交化後の行列の行列式の符号が 元のRの符号と異なる場合、最後の特異ベクトルに-1を乗算して符号を一致させます。 これは回転行列や鏡映行列の分類において、行列式の符号が重要であるためです。
- パラメータ:
R (numpy.ndarray) -- 直交化する3x3行列。
- 戻り値:
行列式の符号を保存して直交化された3x3行列。
- 戻り値の型:
numpy.ndarray
- crystal.pg_generators.parse_gen_labels(s)[ソース]
コマンドライン引数から生成元ラベルの辞書を解析します。
詳細説明: "g1=C6(z),g2=m(⊥z)" のような文字列を受け取り、 生成元のインデックス（0から始まる）をキー、指定されたラベルを値とする辞書に変換します。 これにより、ユーザーがコマンドラインから生成元にカスタムラベルを適用できるようになります。
- crystal.pg_generators.rotation_order(R)[ソース]
回転行列の回転次数を計算します。
詳細説明: 3x3回転行列の回転次数（最小の正整数nでR^n = Iとなるn）を計算します。 行列のトレースから回転角を求め、2πを回転角で割ることで次数を推定します。 微小な回転角（ほぼ恒等変換）の場合は1を返します。
- パラメータ:
R (numpy.ndarray) -- 回転行列。
- 戻り値:
回転次数。
- 戻り値の型: