analyze_symmetry_k.py のドキュメント

このドキュメントは、Pythonプログラム analyze_symmetry_k.py の機能、使用方法、および内部構造について説明します。

概要

analyze_symmetry_k.py は、結晶構造の対称性を解析し、特に中心金属のd軌道と配位子の対称適応型線形結合 (SALC) のk点における互換性を評価するモジュールです。

このプログラムは、ユーザーが指定した構造JSONファイルから情報を読み込み、点群の自動検出、SALCの計算、およびk点におけるSALCの振る舞いを解析します。

コードのdocstringにある関連リンク :doc:analyze_symmetry_k_usage はSphinx/reStructuredText固有の記法であり、MySTのMarkdownでは直接利用できないため、このドキュメントでは言及しません。

インストール

このプログラムは以下の非標準ライブラリに依存しています。

numpy: 数値計算を行うためのPythonライブラリです。
tkpg: 点群対称性の操作やプラグインを提供するライブラリです。

これらのライブラリは、Pythonのパッケージマネージャー pip を使用してインストールできます。

pip install numpy tkpg

tkpg はこのプログラムの主要な依存関係であり、点群対称性操作の提供に使用されます。

使用方法

コマンドライン引数

analyze_symmetry_k.py は、コマンドラインから以下の引数を受け付けます。

--infile (デフォルト: structure_k.json): 構造設定が記述されたJSONファイルへのパスを指定します。

例:

特定のJSONファイルを指定してプログラムを実行する場合:

python analyze_symmetry_k.py --infile my_custom_structure.json

デフォルトのファイル名 structure_k.json を使用する場合は、引数を省略できます。

python analyze_symmetry_k.py

入力データ形式 (JSON)

プログラムは、構造設定を定義するJSONファイルを読み込みます。このファイルは、格子情報、配位子座標、d軌道情報、解析モード、許容誤差、SALC設定などを含みます。

必須キー:

ligands_frac (list[list[float]]): 配位子の分数座標 (格子ベクトル単位)。
または ligands_pos (list[list[float]]): 配位子のデカルト座標。

これらのキーのいずれか一つが必須です。両方存在する場合は ligands_frac が優先されます。どちらも存在しない場合、ValueError が発生します。

オプションキー:

lattice (list[list[float]]): 3x3の格子ベクトルを表す行列。デフォルトは単位行列 ([[1.0, 0.0, 0.0], [0.0, 1.0, 0.0], [0.0, 0.0, 1.0]]) です。
d_orbital (str): 中心金属のd軌道タイプ (例: d_xy, d_z2)。デフォルトは d_xy です。
mode (str): SALC計算モード (例: full)。デフォルトは full です。
center_ligands (bool): 配位子座標を原点にセンタリングするかどうか。デフォルトは False です。周期的な解析には推奨されません。
tolerances (dict): 様々な許容誤差設定を含む辞書。
- tol_match_geom (float): 幾何学的なマッチングに使用する許容誤差。デフォルトは 5e-3 です。
- tol_match_D (float): 対称性操作のマッチング許容誤差。デフォルトは 5e-3 です。
- tol_frac_site (float): 周期的なサイトクラスタリングのための分数座標の許容誤差。デフォルトは 1e-6 です。
salc (dict): SALC計算に関する設定を含む辞書。
- salc_eig_tol (float): SALC抽出のための固有値の許容誤差。デフォルトは 1e-6 です。
- coeff_tol (float): 既約表現の係数を表示するための閾値。デフォルトは 1e-6 です。
- print_coeffs (bool): 既約表現の係数を表示するかどうか。デフォルトは True です。
- print_salc_thr (float): SALCの係数を表示するための閾値。デフォルトは 1e-3 です。
- max_salc_per_irrep (int or null): 各既約表現で表示するSALCの最大数。デフォルトは null (無制限) です。
autodetect (dict): 点群自動検出に関する追加設定を含む辞書。
- min_rate_strict (dict): 特定の点群名に対する厳密なヒット率の閾値を含む辞書。
- tie_eps (float): 自動検出でタイブレークに使用する許容誤差。デフォルトは 1e-12 です。
kpoints_frac (list[list[float]]): 解析するk点の分数座標のリスト。デフォルトはガンマ点 ([[0.0, 0.0, 0.0]]) です。
k_tol (float): k点互換性フィルターの許容誤差。デフォルトは 1e-6 です。

JSONファイルの例:

{
  "lattice": [
    [3.0, 0.0, 0.0],
    [0.0, 3.0, 0.0],
    [0.0, 0.0, 3.0]
  ],
  "ligands_frac": [
    [0.0, 0.0, 0.5],
    [0.0, 0.5, 0.0],
    [0.5, 0.0, 0.0],
    [0.0, 0.0, -0.5],
    [0.0, -0.5, 0.0],
    [-0.5, 0.0, 0.0]
  ],
  "d_orbital": "d_z2",
  "mode": "full",
  "center_ligands": false,
  "tolerances": {
    "tol_match_geom": 0.005
  },
  "salc": {
    "salc_eig_tol": 1e-6,
    "print_salc_thr": 0.001
  },
  "kpoints_frac": [
    [0.0, 0.0, 0.0],
    [0.5, 0.0, 0.0]
  ]
}

出力

プログラムは標準出力に解析結果をテキスト形式で出力します。出力には以下の情報が含まれます。

自動検出された点群情報: 最適な点群の名前、ヒット数、ヒット率、および厳密な受け入れ基準が適用された場合のタグ。
候補点群のリスト: 自動検出プロセスで評価されたすべての点群候補とその評価詳細。
中心金属d軌道情報: 指定されたd軌道の名前とその点群における既約表現。
配位子可約表現分解: 配位子基底が点群の既約表現にどのように分解されるかの係数 (print_coeffs が True の場合)。
ハイブリダイゼーションチェック: 中心金属のd軌道の既約表現が配位子の可約表現に含まれるかどうかの対称性のみによる判定。
k点互換性SALC: 各指定k点について、Bloch位相を考慮してフィルターされたSALCのリスト。各SALCは、その既約表現、タイプ、および配位子原子上の係数で記述されます。

出力例 (一部):

[Auto-detected point group]  Oh   (hits=48/48, hit_rate=1.000)
[Candidates]
  Oh : hits=48/48  rate=1.000  ok_align=True
  O  : hits=24/24  rate=1.000  ok_align=True
  Td : hits=24/24  rate=1.000  ok_align=True
...
[Central metal d orbital]
  Orbital : d_z2
  Irrep   : Eg

[Ligand reducible rep decomposition (Oh)]
  A1g: 1.000000
  Eg: 1.000000
  T1u: 2.000000

[Hybridization check (symmetry-only)]
  ✔ Allowed by point-group symmetry: ligand contains Eg

[All ligand SALCs with Bloch phase]  point_group=Oh  mode=full

[k-compatibility] irrep=A1g  k_frac=(0.000,0.000,0.000)  compatible=1/1
# SALC  irrep=A1g  type=sigma (1)  k=(0.000,0.000,0.000)
#     Ligands: frac=[0.000,0.000,0.500], id=0, T=[0,0,0] : (sigma_z)  0.408248
#     Ligands: frac=[0.000,0.500,0.000], id=1, T=[0,0,0] : (sigma_y)  0.408248
#     Ligands: frac=[0.500,0.000,0.000], id=2, T=[0,0,0] : (sigma_x)  0.408248
#     Ligands: frac=[0.000,0.000,-0.500], id=3, T=[0,0,0] : (sigma_z) -0.408248
#     Ligands: frac=[0.000,-0.500,0.000], id=4, T=[0,0,0] : (sigma_y) -0.408248
#     Ligands: frac=[-0.500,0.000,0.000], id=5, T=[0,0,0] : (sigma_x) -0.408248
...

主要関数

`load_structure_json(path)`

説明: 構造設定をJSONファイルから読み込み、設定辞書を構築します。ligands_frac (分数座標) または ligands_pos (デカルト座標) のいずれかが必須です。
引数:
- path (str): 設定を読み込むJSONファイルへのパス。
戻り値:
- dict: 読み込んだ設定情報を含む辞書。
発生する例外:
- ValueError: JSONファイルに ligands_frac または ligands_pos のいずれも含まれていない場合。

`choose_point_group(plugins, ligands_pos, tol_match_geom, autodetect_cfg)`

説明: 複数の点群プラグインを評価し、配位子の配置に最も適切な点群を自動検出します。各プラグインの align_guess と symmetry_hit_rate を利用して適合度を計算し、ヒット率、ヒット数、群の位数、名前の順でソートして最良のものを選択します。autodetect_cfg に min_rate_strict が指定されている場合、特定の点群に対して厳密なヒット率の閾値が適用されます。
引数:
- plugins (list[dict]): 評価する tkpg プラグインのリスト。各プラグインは、点群の名前、 align_guess メソッド、 build_group メソッドなどを含む辞書である必要があります。
- ligands_pos (numpy.ndarray): 配位子の座標 (デカルト座標) のNumPy配列。形状は (N, 3) です。
- tol_match_geom (float): 幾何学的なマッチングに使用する許容誤差。
- autodetect_cfg (dict or None): 自動検出に関する追加設定を含む辞書。min_rate_strict (点群名と閾値の辞書) や tie_eps (タイブレークの許容誤差) などのキーを含めることができます。None の場合、デフォルト値が使用されます。
戻り値:
- tuple[tuple[dict, float, int, numpy.ndarray, numpy.ndarray, str], list[tuple]]: 以下の2つの要素を含むタプルを返します。
  - 最良の点群に関する情報。以下の要素を含むタプルです。
    - plugin: 最良と判断された点群プラグイン辞書。
    - rate: 最良点群のヒット率。
    - hits: 最良点群のヒット数。
    - R_align: 配位子を標準的な軸にアラインメントするための回転行列。
    - pos_aligned: アラインメント後の配位子座標。
    - strict_tag: 厳密な受け入れ基準が適用された場合のタグ文字列。
  - 評価された全プラグインの情報（整形済み文字列含む）のリスト。各要素は (rate, hits, ok, p, R, pos, tag) のタプルです。

`main()`

説明: コマンドライン引数からJSONファイルを読み込み、配位子SALCのk点互換性解析を実行します。この関数は、構造の読み込み、点群の自動検出、中心金属d軌道の既約表現特定、配位子SALCの計算、およびk点におけるSALCの互換性フィルター処理を行います。
引数: なし。この関数はコマンドライン引数 (--infile) を直接解析します。
戻り値: なし。結果は標準出力に直接表示されます。
発生する例外:
- RuntimeError: tkpg プラグインが見つからない場合。
- ValueError: 指定された d_orbital が検出された点群で定義されていない場合。