analyze_symmetry.py ドキュメント
本ドキュメントは、Pythonスクリプト analyze_symmetry.py の機能と使用方法について説明します。
ファイル概要
本スクリプトは、JSONファイルから配位子の構造データを読み込み、点群対称性を自動検出します。 検出された点群に基づいて、配位子の対称性を既約表現に分解し、 中心金属のd軌道とのハイブリダイゼーションの可否を評価します。 さらに、各既約表現に対応する対称適合線形結合 (SALC) を抽出し、その結果を出力します。
非標準ライブラリ
本スクリプトが依存する非標準ライブラリは以下の通りです。
numpytkpg
関数ドキュメント
load_structure_json(path: str) -> dict
指定されたJSONファイルから構造設定を読み込みます。
詳細説明: ファイルパスを引数として受け取り、配位子の位置、d軌道タイプ、解析モード、 許容誤差などの設定を辞書形式で抽出して返します。 欠損しているキーにはデフォルト値が適用されます。
引数:
path(str): 構造設定を含むJSONファイルのパス。
戻り値:
dict: 読み込まれた設定値を含む辞書。 主なキーとしてligands_pos(numpy.ndarray),d_orbital(str),mode(str),tol_match_geom(float),tol_match_D(float),salc_eig_tol(float),coeff_tol(float),print_coeffs(bool),print_salc_thr(float),max_salc_per_irrep(int | None),autodetect(dict) などが含まれます。
center_positions(ligands_pos: numpy.ndarray) -> numpy.ndarray
配位子の位置を重心が原点に来るように移動します。
詳細説明: 与えられた配位子の三次元座標群の重心を計算し、各座標から重心を引くことで、 重心を原点に移動した新しい座標群を生成します。
引数:
ligands_pos(numpy.ndarray): shapeが(N, 3)の配位子座標配列。
戻り値:
numpy.ndarray: 重心が原点に移動された配位子座標配列。
choose_point_group(plugins: list[dict], ligands_pos: numpy.ndarray, tol_match_geom: float, autodetect_cfg: dict | None) -> tuple[dict, list[dict]]
複数の点群プラグインを評価し、最も適切な点群を自動選択します。
詳細説明:
各プラグインが提供するalign_guessとsymmetry_hit_rateの結果を評価し、
以下のルールに基づいて最適な点群を選択します:
min_rate_strict設定で定義された閾値strict_okを満たすプラグインを優先します。残りの候補の中から、ヒット数 (
hits) が最大であるものを選択します。次に、群の位数 (
Gorder) が最大であるものを選択します。最後に、ヒット率 (
rate) が最大であるものを選択します。
引数:
plugins(list[dict]): 点群プラグインのリスト。 各プラグインは辞書形式で、name(str),align_guess(callable),build_group(callable),d_irreps(dict),irreps(callable),irrep_dim(callable),irrep_char(callable) などの情報を含む。ligands_pos(numpy.ndarray): shapeが(N, 3)の配位子座標配列。tol_match_geom(float): 幾何学的な一致を判定するための許容誤差。autodetect_cfg(dict | None): 自動検出設定を含む辞書。min_rate_strict(dict) などのキーを含むことができる。
戻り値:
tuple[dict, list[dict]]:dict: 選択された最適な点群プラグインと評価結果を含む辞書。 キーとしてplugin(dict),ok_align(bool),R_align(numpy.ndarray),pos_aligned(numpy.ndarray),hits(int),rate(float),Gorder(int),strict_thr(float),strict_ok(bool) を含む。list[dict]: 評価された全ての点群プラグインの結果リスト。 各要素は上記のdictと同じ構造を持つ。
main() 関数
スクリプトの実行方法
本スクリプトは、Pythonインタープリタを使用して直接実行できます。
python analyze_symmetry.py --infile <input_file.json>
コマンドライン引数
--infile: 構造設定を含むJSONファイルのパスを指定します。 デフォルト値はstructure.jsonです。
入出力仕様
入力
コマンドライン引数 --infile で指定されたJSONファイルから構造設定を読み込みます。
JSONファイルは以下のキーと値を持ちます。
ligands_pos(必須): 配位子の3次元座標のリスト。例:[[0.0, 0.0, 1.0], [0.0, 0.0, -1.0]]d_orbital(オプション): 中心金属のd軌道のタイプ。デフォルトは"d_xy"。指定可能な値は点群プラグインによって異なりますが、"d_xy","d_yz","d_zx","d_x2-y2","d_z2"などが考えられます。mode(オプション): 解析モード。デフォルトは"full"。コードからは確認できませんが、"full"以外のモードも存在し得ます。tolerances(オプション): 許容誤差を定義する辞書。tol_match_geom(オプション): 幾何学的な一致判定の許容誤差。デフォルトは5e-3。tol_match_D(オプション): 可約表現構築時の許容誤差。デフォルトは5e-3。
salc(オプション): SALC抽出に関する設定を定義する辞書。salc_eig_tol(オプション): SALC抽出時の固有値の許容誤差。デフォルトは1e-6。coeff_tol(オプション): 係数の表示閾値。デフォルトは1e-6。print_coeffs(オプション): 可約表現の分解係数を出力するかどうか。デフォルトはTrue。print_salc_thr(オプション): SALC係数の表示閾値。デフォルトは1e-3。max_salc_per_irrep(オプション): 各既約表現で表示するSALCの最大数。デフォルトはNone(制限なし)。
autodetect(オプション): 自動検出に関する設定を定義する辞書。min_rate_strict(オプション): 点群ごとの厳格なヒット率閾値を定義する辞書。例:{"Oh":0.70, "C4v":0.80}
出力
解析結果は標準出力に出力されます。内容は以下の通りです。
自動検出された点群情報: 検出された点群の名前、ヒット数、群の位数、ヒット率。
候補となる点群のリスト: 評価されたすべての点群候補について、点群名、ヒット数、群の位数、ヒット率、アライメントの成功可否、厳格な閾値のクリア状況、およびその閾値。
中心金属d軌道情報: 設定されたd軌道名と、そのd軌道が属する既約表現。
配位子可約表現の分解結果: 配位子の可約表現が各既約表現に分解された際の係数（
print_coeffsがTrueの場合）。ハイブリダイゼーションチェック: 中心金属のd軌道が配位子の可約表現に含まれるかどうかによる、ハイブリダイゼーションの対称性による可否判定。
配位子SALCs: 各既約表現に対応する対称適合線形結合 (SALC) の係数。 係数が
print_salc_thrより大きい成分のみ表示されます。max_salc_per_irrepで表示数が制限されることがあります。
主要処理フロー
analyze_symmetry.py の main() 関数は以下の順序で処理を実行します。
コマンドライン引数の解析:
argparseを使用して、入力JSONファイルのパス (--infile) を取得します。設定の読み込み:
load_structure_json()を呼び出し、指定されたJSONファイルから構造設定と解析オプションを読み込みます。配位子位置の正規化:
center_positions()を使用して、配位子の重心が原点に来るように座標を移動します。点群の自動検出:
tkpg.load_plugins()で利用可能な点群プラグインを読み込み、choose_point_group()を呼び出して最適な点群を自動選択します。点群情報の表示: 自動検出された点群の詳細と、評価されたすべての候補点群の結果を標準出力に表示します。
中心金属d軌道の既約表現確認: 設定されたd軌道が、選択された点群においてどの既約表現に属するかを特定し、表示します。
基底の構築:
core.compute_local_frames()およびcore.build_ligand_basis()を使用して、配位子の局所フレームと基底を構築します。可約表現の構築と分解:
core.build_reducible_characters()を使用して、配位子の可約表現 (Gamma) の指標を計算します。core.decompose_generic()を使用して、Gammaを選択された点群の既約表現に分解し、その係数 (coeffs) を取得します。print_coeffsがTrueの場合、分解係数を表示します。
ハイブリダイゼーションチェック: 中心金属のd軌道の既約表現が配位子の分解された可約表現に含まれるかを確認し、ハイブリダイゼーションの可否を判定結果を表示します。
SALCの抽出と表示:
各既約表現について、
core.extract_salc()を使用して対称適合線形結合 (SALC) を抽出します。core.print_salc()を使用して、抽出されたSALCの係数を標準出力に表示します。表示はprint_salc_thrとmax_salc_per_irrepの設定に従います。SALCが一つも抽出されなかった場合、その旨のメッセージが表示されます。