XRD_GUI_lib.py 技術ドキュメント

プログラムの動作

XRD_GUI_lib.py は、X線回折（XRD）データおよび結晶構造ファイルからの参照回折パターンを解析し、GUIアプリケーションで利用可能な形式でデータを提供するPythonライブラリです。主に、様々なデータフォーマットに対応するためのプラグイン機構をバックエンドに持ち、GUIのデータ読み込み部分の柔軟性と拡張性を高めることを目的としています。

主な機能は以下の通りです。

  • プラグインの動的ロード: 特定のディレクトリ (xrd/filter) から、データ解析と変換を行うPythonモジュール（プラグイン）を動的にロードします。これにより、多種多様なX線回折データフォーマットや結晶構造ファイル形式に対応できます。

  • X線回折データ解析: 指定されたパスのX線回折生データファイルを解析し、サンプル名、2θ（またはQ値）、および強度データとして抽出します。適切なプラグインを自動的に選択してデータ処理を行います。

  • 参照回折パターン生成: CIF (Crystallographic Information File) などの結晶構造ファイルから、理論的なX線回折ピークの位置、強度、およびミラー指数（hkl）を計算し、参照パターンとして提供します。

  • 回折条件の設定: 2θ測定範囲（xmin, xmax, xstep）や使用X線波長（wavelength）といったXRD条件をGUI側から設定・変更するためのインターフェースを提供します。

  • ファイルフィルターの生成: ロードされたプラグインがサポートするファイル形式に基づいて、GUIのファイル選択ダイアログで使用するためのフィルター文字列を生成します。

本ライブラリは、単体で実行されるよりも、GUIアプリケーションの一部としてインポートされ、そのバックエンド処理を担うことが意図されています。

原理

XRD_GUI_lib.py は、X線回折の物理的な原理に基づいた計算を直接行うのではなく、tklib ライブラリのフレームワーク内でロードされるプラグインモジュールを介してデータ解析や参照パターンの生成を行います。しかし、その動作の背後には以下のX線回折に関する物理的・数理的原理が存在します。

X線回折の基本原理

結晶性物質にX線を照射すると、特定の方向にX線が強く回折される現象が起こります。これはブラッグの法則によって説明されます。

\[n\lambda = 2d \sin\theta\]

ここで、

  • \(n\) は回折次数（整数）

  • \(\lambda\) はX線の波長

  • \(d\) は結晶面間隔

  • \(\theta\) はX線入射角（ブラッグ角）

この法則により、結晶面間隔が既知であれば、特定の波長を持つX線がどの角度で回折されるか（ピーク位置）を予測できます。

回折ピーク強度

回折ピークの強度は、結晶中の原子の種類、位置、そして各原子の散乱能に依存します。これは構造因子 \(F_{hkl}\) の絶対値の二乗 \(|F_{hkl}|^2\) に比例します。

\[I_{hkl} \propto |F_{hkl}|^2\]

構造因子は、ミラー指数 \((hkl)\) で示される結晶面に対して、単位胞内の全ての原子からの散乱波を足し合わせたものです。

\[F_{hkl} = \sum_{j=1}^{N} f_j \exp\left[2\pi i (hx_j + ky_j + lz_j)\right]\]

ここで、

  • \(N\) は単位胞内の原子数

  • \(f_j\) は \(j\) 番目の原子の原子散乱因子

  • \((x_j, y_j, z_j)\) は \(j\) 番目の原子の単位胞内分数座標

parse_reference 関数は、CIFファイルからこれらの結晶構造情報を読み込み、プラグインがこれらの原理に基づいて計算した回折ピークの位置と強度を利用します。プログラム内で設定される cparams.fwhm や cparams.Gfraction といったパラメータは、回折ピークの形状（半値幅、ガウス成分とローレンツ成分の比率）をシミュレートする際に使用されますが、本ライブラリ自体が直接これらのピーク形状を生成するわけではありません。

プラグイン機構

XRD_GUI_lib.py の中心的な原理は、tklib.tkapplication の提供するプラグイン（またはフィルター）機構です。これは以下のステップで動作します。

  1. モジュールのロード: 指定されたディレクトリ (filter_dir) 内のPythonスクリプトを動的にインポートします。

  2. インターフェースチェック: ロードされたモジュールが、check_file_type, read_data, convert, get_input_type, get_output_type といった特定の関数を持っているかを内部的に確認します。

  3. ファイルタイプの判定とデータ処理: parse_xrd や parse_reference の実行時、入力ファイルに対して各プラグインの check_file_type を呼び出し、どのプラグインがそのファイルを処理できるかを判定します。

  4. データ変換: 適切なプラグインが見つかると、その read_data メソッドで生データを読み込み、convert メソッドでGUIアプリケーションが利用しやすい標準的なデータ構造に変換します。

このプラグイン機構により、新たなファイル形式やデータ処理ロジックが追加された場合でも、filter ディレクトリに新しいモジュールを追加するだけで容易に機能拡張が可能です。

必要な非標準ライブラリとインストール方法

XRD_GUI_lib.py を実行するには、以下の非標準ライブラリが必要です。

  • numpy: 高性能な数値計算をPythonで行うための基本ライブラリ。主に数値配列の操作に使用されます。

    pip install numpy

  • tklib: TkinterをベースとしたGUIアプリケーションフレームワーク。本プログラムは tklib.tkapplication モジュールを利用しています。このライブラリは tklib_coe という名前でPyPIに登録されているか、カスタムビルドされたものである可能性があります。一般的なインストール方法は以下の通りです。

    pip install tklib_coe

    もし上記のコマンドでインストールできない場合は、開発元から提供される特定の指示に従ってください。

  • pymatgen (間接的な依存): _to_hkl_str_and_raw 関数のドキュメントに「pymatgenのhkl」と記載されていることから、参照パターン生成において pymatgen ライブラリが出力するデータ構造を想定している可能性があります。直接的なインポートはありませんが、関連するプラグインが依存している場合があります。

    pip install pymatgen

必要な入力ファイル

XRD_GUI_lib.py は、以下の種類のファイルを入力として想定しています。

  1. X線回折生データファイル:

    • 形式: 主にテキストファイル (.txt) やスプレッドシートファイル (.xlsx、.csv など、プラグインの対応状況による)。

    • 内容: 一般的に、X線回折角度（2θまたはQ値）とX線強度のデータペアが含まれます。複数の列を持つ場合もありますが、通常は最初の2列が角度と強度に対応します。

    • 例: 2カラムのテキストデータ

      20.000  1500
20.020  1520
20.040  1550
...

  2. 結晶構造ファイル (参照パターン生成用):

    • 形式: 主にCIF (Crystallographic Information File) 形式 (.cif)。

    • 内容: 結晶の空間群、単位胞パラメータ、原子の種類と位置などの結晶構造情報が含まれます。これらの情報に基づいて理論的なX線回折パターンが計算されます。

  3. プラグインモジュールファイル:

    • 形式: Pythonスクリプト (.py)。

    • 内容: tkprog_X_path 環境変数で指定されたルートディレクトリ内の xrd/filter サブディレクトリに配置されるべきファイルです。これらのファイルは、特定のデータ形式の読み込み、ファイルタイプの判定、およびデータの標準形式への変換ロジックを実装します。各プラグインは、check_file_type, read_data, convert, get_input_type, get_output_type などの特定の関数またはメソッドを提供する必要があります。

生成される出力ファイル

XRD_GUI_lib.py は、主にGUIアプリケーションのバックエンドとして動作することを意図しており、ディスク上に直接ファイルを出力することはありません。代わりに、解析されたデータをメモリ上でPythonのデータ構造として返します。

各関数の主な返り値は以下の通りです。

  • parse_xrd(path):

    • 入力されたXRDデータファイルから抽出された情報を返します。

    • 返り値: (sample_name, xQ2_infile, yobs_infile)

      • sample_name (str): サンプル名。通常、入力ファイル名から抽出されます。

      • xQ2_infile (numpy.ndarray): 2θまたはQ値の配列。

      • yobs_infile (numpy.ndarray): 観測されたX線強度の配列。

  • parse_reference(path, ...):

    • 入力された結晶構造ファイルから生成された理論的な参照回折パターン情報を返します。

    • 返り値: (reference_name, positions, intensities, hkls, raw_indices)

      • reference_name (str): 参照パターン名。通常、入力ファイル名から抽出されます。

      • positions (list of float): 理論的な回折ピークの2θ（またはQ）位置のリスト。

      • intensities (list of float): 各ピークの強度（0〜1に正規化される場合あり）のリスト。

      • hkls (list of str): 各ピークに対応するミラー指数 (h k l) の文字列リスト。

      • raw_indices (list of dict): 各ピークに対応するミラー指数 {"h": h, "k": k, "l": l, "i": i} の辞書リスト。

  • get_supported_file_filters():

    • ロードされたプラグインがサポートするファイル形式を、GUIのファイル選択ダイアログに適したフィルター文字列として返します。

    • 返り値: str。例: "CIFファイル (*.cif);;テキストファイル (*.txt);;全てのファイル (*.*)"

コマンドラインでの使用例 (Usage)

XRD_GUI_lib.py は主にライブラリとして他のPythonスクリプトからインポートされて使用されることを想定しています。しかし、スクリプトの最後にある if __name__ == "__main__": ブロックにより、直接コマンドラインから実行してテストすることが可能です。

実行するには、まず tkprog_X_path 環境変数を設定する必要があります。この環境変数は、XRD関連のデータ処理プラグインが格納されているルートディレクトリを指します。具体的には、このパスの下に xrd/filter というディレクトリが存在し、その中にプラグインファイルが格納されている必要があります。

基本的な実行コマンドは以下の通りです。

python XRD_GUI_lib.py

引数は受け付けず、スクリプト内部にハードコードされたファイルパス（main() 関数内）またはデフォルト設定に基づいて処理を試みます。

コマンドラインでの具体的な使用例

XRD_GUI_lib.py をコマンドラインから実行する具体的な手順と、その出力の例を以下に示します。

まず、tkprog_X_path 環境変数を設定します。この例では、Windows環境とLinux/macOS環境の両方で設定方法を示します。

Windowsの場合 (コマンドプロンプト):

set tkprog_X_path="C:\path\to\tkprog_COE"

Linux/macOSの場合 (Bash/Zsh):

export tkprog_X_path="/path/to/tkprog_COE"

上記の C:\path\to\tkprog_COE または /path/to/tkprog_COE は、実際の tkprog_X_path のルートディレクトリに置き換えてください。例えば、XRD_GUI_lib.py が tkprog_COE/XRD/lib/XRD_GUI_lib.py にある場合、tkprog_X_path は tkprog_COE を指すべきです。そして、そのパスの下に xrd/filter ディレクトリが存在し、中にプラグイン（例えば txt_filter.py, cif_filter.py など）が含まれている必要があります。

環境変数を設定した後、XRD_GUI_lib.py を実行します。

python XRD_GUI_lib.py

実行結果の説明:

スクリプトはまず、tkprog_X_path が設定されているかを確認します。設定されていなければエラーメッセージを出力し終了します。 環境変数が正しく設定されていれば、filter_dir からプラグインモジュールをロードし、その情報を標準出力に表示します。

現在の main() 関数は、ハードコードされたパス D:/git/tkProg/tkprog_COE/XRD/data/240219_AlScN_300_5h_oradw_25_Al100.txt を使用して parse_xrd を呼び出します（コメントアウトされたCIFファイルやExcelファイルのパスもあります）。このファイルが指定されたパスに存在し、対応するプラグインが filter_dir にあれば、ファイルが正常に読み込まれます。

以下は、一般的な実行時の出力例です。

XRD_GUI_lib loaded

Load modules from /path/to/tkprog_COE/xrd/filter
Loaded module: tklib.plugins.xrd.filter.cif_filter
  cif_filter: input_type={'description': 'Crystallographic Information File', 'extension': '*.cif', 'file_type': 'CIF File (*.cif)'}  output_type={'file_type': 'XRD Pattern'}
Loaded module: tklib.plugins.xrd.filter.txt_filter
  txt_filter: input_type={'description': 'XRD Data File', 'extension': '*.txt', 'file_type': 'XRD Data File (*.txt)'}  output_type={'file_type': 'XRD Pattern'}
Loaded module: tklib.plugins.xrd.filter.xlsx_filter
  xlsx_filter: input_type={'description': 'Excel XRD Data File', 'extension': '*.xlsx', 'file_type': 'Excel XRD Data File (*.xlsx)'}  output_type={'file_type': 'XRD Pattern'}
Read D:/git/tkProg/tkprog_COE/XRD/data/240219_AlScN_300_5h_oradw_25_Al100.txt in XRD_GUI_lib.parse_xrd() using filters in /path/to/tkprog_COE/xrd/filter
try [cif_filter] for [D:/git/tkProg/tkprog_COE/XRD/data/240219_AlScN_300_5h_oradw_25_Al100.txt]: file_type=None
try [txt_filter] for [D:/git/tkProg/tkprog_COE/XRD/data/240219_AlScN_300_5h_oradw_25_Al100.txt]: file_type=TXT
   type matched.

もし、tkprog_X_path が設定されていない場合や、指定されたファイルが見つからない、または対応するプラグインがない場合は、以下のようなエラーメッセージが出力されます。

tkprog_X_path が未設定の場合:

#############################################
Error in XRD_GUI_lib: Environment variable tkprog_X_path must be specified
#############################################

Pree ENTER to terminate>>

ファイルが見つからない、またはプラグインが対応しない場合: （parse_xrd の中で ValueError が発生する）

... (プラグインロードの出力) ...
Read /invalid/path/to/file.txt in XRD_GUI_lib.parse_xrd() using filters in /path/to/tkprog_COE/xrd/filter
try [cif_filter] for [/invalid/path/to/file.txt]: file_type=None
try [txt_filter] for [/invalid/path/to/file.txt]: file_type=None
... (他のプラグインも同様に None) ...
Traceback (most recent call last):
  File "XRD_GUI_lib.py", line 223, in <module>
    main()
  File "XRD_GUI_lib.py", line 214, in main
    parse_xrd(infile)
  File "XRD_GUI_lib.py", line 87, in parse_xrd
    raise ValueError(f"Failed to find modules in {filter_dir}")
ValueError: Failed to find modules in /path/to/tkprog_COE/xrd/filter