XRD_GUI_lib.py 技術ドキュメント

プログラムの動作

XRD_GUI_lib.py は、X線回折（XRD）データの解析およびリファレンスパターン生成を支援するためのPythonライブラリです。主にGUIアプリケーションのバックエンドとして機能し、多様なデータ形式に対応するためのプラグイン機構を提供します。

目的

このライブラリの主な目的は、さまざまなソースからX線回折データを読み込み、標準化された形式で処理し、GUIアプリケーションなどの上位層に提供することです。具体的には、測定されたXRDパターンや結晶構造情報ファイル（CIFなど）から回折ピーク情報を抽出し、解析に必要なパラメータ（2θ範囲、X線波長など）を管理します。

主な機能

  • 動的プラグインロード: 環境変数 tkprog_X_path で指定されたパスの下にある xrd/filter ディレクトリから、データ読み込み・変換を行うPythonプラグインモジュールを動的にロードします。

  • XRD測定データ解析: 指定されたファイルパスからXRD測定データを読み込み、サンプル名、2θ角度の配列、および強度の配列として返します。対応するファイル形式はロードされたプラグインに依存します。

  • XRDリファレンスパターン生成: CIFファイルなどの結晶構造情報ファイルから、指定されたX線波長と2θ範囲に基づいて理論的な回折ピークの位置、強度、およびミラー指数（hkl）を計算して返します。

  • 解析パラメータ管理: 2θの最小・最大値、ステップ幅、X線波長、ピークの半値幅（FWHM）、ガウス関数とローレンツ関数の混合比率（Gfraction）、背景除去の次数などの多くの解析パラメータを tkApplication オブジェクトを通じて一元的に管理し、GUIからの設定変更に対応します。

  • ファイルフィルター生成: ロードされたすべてのプラグインが対応するファイル形式をリストアップし、GUIのファイルダイアログで使用できる形式のフィルター文字列を生成します。

解決する課題

  • 多様なデータフォーマットへの対応: XRD測定データや結晶構造情報のフォーマットが多岐にわたるため、プラグイン機構により柔軟に対応し、コードの拡張性を高めます。

  • 統一されたデータアクセスインターフェース: 異なるデータソースからの情報を、GUIアプリケーションが扱いやすい標準化されたPythonオブジェクト（NumPy配列など）として提供します。

  • 解析パラメータの一元管理: 複雑なXRD解析に必要な多数のパラメータを効率的に設定・管理し、ユーザーが容易に調整できるようにします。

原理

データ解析のフロー

XRD_GUI_lib.py は、XRDデータの解析およびリファレンスパターン生成において、主にプラグイン（フィルターモジュール）に処理を委譲するアーキテクチャを採用しています。

  1. プラグインのロード: プログラム起動時に、指定されたディレクトリからPythonスクリプトを読み込み、特定のインターフェース（例: check_file_type, read_data, convert メソッド）を持つものをデータ処理プラグインとして登録します。

  2. ファイルタイプの識別: parse_xrd や parse_reference 関数が呼び出されると、まずロードされた各プラグインの check_file_type メソッドを使って、入力ファイルの形式に対応するプラグインを特定します。

  3. データ読み込みと変換: 対応するプラグインが見つかると、そのプラグインの read_data メソッドが呼び出され、生データが読み込まれます。次に convert メソッドが呼び出され、読み込んだデータを本ライブラリが想定する標準的な辞書形式（例: {"data_list": [[2theta_values], [intensity_values]], "sample_name": "..."}）に変換します。

XRD回折ピーク計算の基礎

parse_reference 関数が結晶構造情報ファイル（例: CIF）からリファレンス回折パターンを生成する際には、X線回折の基本的な物理法則が利用されます。

  • ブラッグの法則: 結晶によるX線の回折は、ブラッグの法則によって記述されます。 $\( n\lambda = 2d_{hkl}\sin\theta \)$ ここで、

    • \(n\) は回折次数（通常は1）

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

    • \(d_{hkl}\) はミラー指数 \((hkl)\) で示される結晶面の間隔

    • \(\theta\) はブラッグ角（\(2\theta\) の半分） この法則に基づき、与えられた波長と結晶構造から、特定の \(hkl\) 面に対応する回折ピークの \(2\theta\) 位置が計算されます。

  • 回折強度: 各回折ピークの強度は、結晶構造因子 \(F_{hkl}\) の絶対値の二乗 \(|F_{hkl}|^2\) に比例します。構造因子は結晶の単位胞内の原子の種類と位置、および散乱因子によって決定されます。 $\( I_{hkl} \propto |F_{hkl}|^2 \)$ parse_reference 関数では、プラグインがこれらの結晶学的な計算を実行し、回折ピークの2θ位置と相対強度を提供します。生成された強度は、必要に応じて最大値が1になるように正規化されます。

HKL指数の表現

_to_hkl_str_and_raw 関数は、PyMatgenなどのライブラリが返すH K L指数のタプル（例: (h, k, l) または六方晶系での (h, k, i, l)）を、ユーザーフレンドリーな文字列（例: "(h k l)"）と、辞書形式の raw インデックス（例: {"h": h, "k": k, "l": l, "i": i_val}）に変換します。六方晶系の場合、\(i = -(h+k)\) の関係が利用されることがあります。

パラメータ管理

tkApplication クラスの cparams オブジェクトは、アプリケーション全体で共有される設定パラメータ（xmin, xmax, xstep, wavelength, fwhm など）を保持します。これらのパラメータは、set_two_theta_range や set_wavelength といった関数を通じて動的に変更され、XRDデータ解析やリファレンス生成の挙動に影響を与えます。

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

このプログラムの動作には、以下の非標準ライブラリが必要です。

  • numpy: 高度な数値計算（特に配列操作）に使用されます。

  • tklib: tkApplication クラスを提供するGUIアプリケーションフレームワークです。

インストール方法

numpy はPythonの標準的なパッケージインストーラ pip でインストールできます。

pip install numpy

tklib は一般的にPyPIには直接存在しないカスタムライブラリである可能性が高いです。もしそれが利用可能なパッケージである場合、同様に pip でインストールできます。

pip install tklib

tklib がカスタムライブラリである場合、そのインストール手順はプロジェクト固有のものであり、別途そのソースコードやドキュメントを参照する必要があります。

必要な入力ファイル

XRD_GUI_lib.py は、ロードされたプラグインモジュールによってサポートされる様々な形式の入力ファイルを処理できます。

  • XRD測定データファイル:

    • 形式: 主にテキストファイル（例: .txt）で、2θ角度と強度（カウント）のペアが格納されているもの。Excelファイル（例: .xlsx）など、プラグインが対応する任意の形式も利用可能です。

    • 内容: X線回折装置で測定された生データ。通常、2θ角度の列と、それに対応するX線強度の列で構成されます。

    • 例: 240219_AlScN_300_5h_oradw_25_Al100.txt (コード内の例)

  • 結晶構造情報ファイル:

    • 形式: CIF (Crystallographic Information File) が主要な形式です。その他、プラグインが対応する構造データファイル（例: .xlsx、.xyz など）も利用可能です。

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

    • 例: phase1.cif (コード内の例)

これらの入力ファイルは、環境変数 tkprog_X_path で指定されたルートディレクトリ以下の適切なパスに配置されているか、または直接ファイルパスが関数に渡される必要があります。プラグインは tkprog_X_path/xrd/filter ディレクトリに存在することが期待されます。

生成される出力ファイル

XRD_GUI_lib.py ライブラリは、自身の関数を実行しても直接ファイルを出力することはありません。その代わりに、以下に示すPythonオブジェクトを返り値として提供します。これらのデータは、GUIアプリケーションや他のスクリプトで利用されることを想定しています。

  • parse_xrd(path) の出力: XRD測定データを解析し、以下のタプルを返します。

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

    • xQ2_infile (numpy.ndarray): 測定された2θ角度（またはQ値）の配列。

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

  • parse_reference(path, ...) の出力: 結晶構造情報からリファレンス回折ピークを生成し、以下のタプルを返します。

    • reference_name (str): リファレンス名。通常、ファイル名から抽出されます。

    • positions (list of float): 計算された各回折ピークの2θ角度のリスト。

    • intensities (list of float): 計算された各回折ピークの相対強度のリスト（正規化済みの場合あり）。

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

    • raw_indices (list of dict): 各回折ピークに対応するミラー指数を辞書形式で表現したリスト（例: {"h": 1, "k": 0, "l": 0, "i": 0}）。

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

XRD_GUI_lib.py は、GUIアプリケーションのバックエンドとして設計されたライブラリであり、通常は他のPythonスクリプトからインポートして使用されます。直接コマンドラインから実行して具体的な解析結果を生成するようには作られていません。

このプログラムをライブラリとして利用する場合、Pythonスクリプト内で import XRD_GUI_lib と記述し、提供される関数（parse_xrd, parse_reference, set_two_theta_range など）を呼び出します。

基本的な実行コマンド:

このプログラムを単体で実行すると、内部のテストブロックが実行されます。

python XRD_GUI_lib.py

しかし、この実行はハードコードされたパスのファイルを読み込もうとするだけで、具体的な解析結果をコンソールに出力するようには設計されていません（内部の print デバッグメッセージは表示されます）。実用的な利用には、別途GUIアプリケーションやカスタムスクリプトから関数を呼び出す必要があります。

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

XRD_GUI_lib.py の if __name__ == "__main__": ブロックには、開発・テスト用の main() 関数が含まれています。この関数は、プログラムが直接実行された場合に一度だけ呼び出されます。

# main() 関数内のコード（コメントアウトされた部分も含む）
def main():
#    infile = "D:/git/tkProg/tkprog_COE/XRD/data/phase1.cif"
#    infile = "D:/git/tkProg/tkprog_COE/XRD/data/Bi_R-3m.xlsx"
    infile = "D:/git/tkProg/tkprog_COE/XRD/data/240219_AlScN_300_5h_oradw_25_Al100.txt"
    parse_xrd(infile)

#    infile = "D:/git/tkProg/tkprog_COE/XRD/data/phase1.cif"
#    parse_reference(infile)
    exit()

if __name__ == "__main__":
    main()

実行コマンド例

以下のコマンドを実行すると、XRD_GUI_lib.py が直接起動されます。

python XRD_GUI_lib.py

実行結果の説明

上記のコマンドを実行すると、main() 関数内のハードコードされた infile パス（例: "D:/git/tkProg/tkprog_COE/XRD/data/240219_AlScN_300_5h_oradw_25_Al100.txt"）を使用して parse_xrd 関数が呼び出されます。

プログラムはまず、以下のメッセージを出力します。

XRD_GUI_lib loaded

次に、環境変数 tkprog_X_path が設定されているかを確認し、filter_dir からプラグインモジュールをロードしようとします。ロードされるモジュールとその入出力タイプに関する情報が表示されます。

Load modules from D:\git\tkProg\tkprog_COE\xrd\filter
  text_parser: input_type={'file_type': 'text file (*.txt)'}  output_type={'file_type': 'text file (*.txt)'}
  excel_parser: input_type={'file_type': 'Excel file (*.xlsx)'}  output_type={'file_type': 'Excel file (*.xlsx)'}
  cif_parser: input_type={'file_type': 'CIF file (*.cif)'}  output_type={'file_type': 'CIF file (*.cif)'}

その後、parse_xrd 関数が実行され、指定された入力ファイルを読み込もうとします。各プラグインがファイルタイプをチェックする際に、デバッグメッセージが出力されます。

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 D:\git\tkProg\tkprog_COE\xrd\filter
try [text_parser] for [D:/git/tkProg/tkprog_COE/XRD/data/240219_AlScN_300_5h_oradw_25_Al100.txt]: file_type=text file (*.txt)
   type matched.

上記の例では、text_parser プラグインがファイルタイプに一致したことが示されています。実際にファイルが読み込まれ、内部で処理が行われますが、parse_xrd から返されるデータはコンソールには直接出力されません。main() 関数は parse_xrd 呼び出し後に exit() するため、プログラムは終了します。

もし tkprog_X_path 環境変数が設定されていない場合や、指定されたパスにファイルが存在しない、または対応するプラグインが見つからない場合は、エラーメッセージが出力され、プログラムは終了します。

#############################################
Error in XRD_GUI_lib: Environment variable tkprog_X_path must be specified
#############################################
Pree ENTER to terminate>>