以下のMarkdownドキュメントは、提供されたPythonプログラム xrd_fit_xrayutilities.py をSphinx (MyST) で問題なくビルドできるように作成されています。

# ``xrd_fit_xrayutilities.py`` ドキュメント

## プログラム概要

``xrd_fit_xrayutilities.py`` は、X線回折 (XRD) シミュレーションおよびフィッティングツールです。
このモジュールは、``xrayutilities`` ライブラリを使用して動的理論に基づいたXRDシミュレーションを実行し、実験データに対して構造パラメータ（組成 ``x``、緩和度 ``relax``、膜厚 ``thick``）を最適化します。また、フリンジ解析による膜厚の自動推定機能も備えています。

関連情報については、``xrd_fit_usage`` ドキュメントを参照してください。

## 非標準ライブラリ

このプログラムは、以下の非標準ライブラリを使用しています。

*   ``numpy``
*   ``matplotlib``
*   ``xrayutilities``
*   ``scipy``

## インストール

必要なライブラリは ``pip`` を使用してインストールできます。

```bash
pip install numpy matplotlib scipy xrayutilities

コマンドライン引数

xrd_fit_xrayutilities.py は argparse モジュールを使用してコマンドライン引数を解析します。

build_parser()

コマンドライン引数を解析するためのパーサーを構築します。

この関数は argparse モジュールを使用して、XRDシミュレーション、フィッティング、および膜厚推定ツールが受け入れるコマンドライン引数を定義します。各引数にはデフォルト値、選択肢、ヘルプメッセージが含まれます。

戻り値:

  • 設定済みの argparse.ArgumentParser オブジェクト。

定義されている引数:

  • --mode

    • 説明: 実行モード。

    • デフォルト: sim

    • 選択肢: sim (シミュレーション), read (読込), fit (最適化), guess (膜厚推定)

  • --method

    • 説明: 最適化手法。 fit モード時に有効。

    • デフォルト: pso

    • 選択肢: random, nelder-mead, bfgs, cg, pso

  • --infile

    • 説明: 2theta-intensityデータを含むテキストファイルへのパス。

    • デフォルト: "" (空文字列)

  • --substrate_file

    • 説明: 基板のCIFファイルパス。

    • デフォルト: GaN.cif

  • --film_file

    • 説明: 膜のCIFファイルパス。

    • デフォルト: AlN.cif

  • --fix

    • 説明: 固定するパラメータ（カンマ区切り、例: x,relax）。

    • デフォルト: "" (空文字列)

  • --nmaxiter

    • 説明: 最大反復回数。

    • デフォルト: 1000

    • 型: 整数

  • --tol

    • 説明: 収束判定の許容誤差。

    • デフォルト: 1e-7

    • 型: 浮動小数点数

  • --yscale

    • 説明: プロットのY軸スケール。

    • デフォルト: log

    • 選択肢: linear, log

  • --residual_scale

    • 説明: 残差計算に使用するスケール。

    • デフォルト: log

    • 選択肢: linear, log

  • --guess_low

    • 説明: guess モードでの解析開始角度 [deg]。

    • デフォルト: 16.0

    • 型: 浮動小数点数

  • --guess_high

    • 説明: guess モードでの解析終了角度 [deg]。

    • デフォルト: 17.3

    • 型: 浮動小数点数

  • --nsmooth_points

    • 説明: guess モードでの平滑化ウィンドウ点数。

    • デフォルト: 31

    • 型: 整数

  • --nsmooth_order

    • 説明: guess モードでの平滑化多項式次数。

    • デフォルト: 3

    • 型: 整数

  • --nguess_keep

    • 説明: guess モードで保持する膜厚候補の数。

    • デフォルト: 5

    • 型: 整数

  • --cluster_gap_factor

    • 説明: フリンジクラスター判定用のギャップ係数。

    • デフォルト: 1.6

    • 型: 浮動小数点数

  • --pso_nparticles

    • 説明: PSOの粒子数。

    • デフォルト: 12

    • 型: 整数

  • --pso_w

    • 説明: PSOの慣性重み。

    • デフォルト: 0.72

    • 型: 浮動小数点数

  • --pso_c1

    • 説明: PSOの自己学習係数。

    • デフォルト: 1.49

    • 型: 浮動小数点数

  • --pso_c2

    • 説明: PSOの社会学習係数。

    • デフォルト: 1.49

    • 型: 浮動小数点数

  • --pso_stall_max

    • 説明: 改善がない場合にPSOを停止する最大反復数。

    • デフォルト: 15

    • 型: 整数

  • --pso_spread_rtol

    • 説明: 粒子の分散に基づく停止条件の相対許容誤差。

    • デフォルト: 0.10

    • 型: 浮動小数点数

initialize(parser)

コマンドライン引数を解析し、結果を返します。

パラメータ:

  • parser (argparse.ArgumentParser): argparse.ArgumentParser オブジェクト。

戻り値:

  • argparse.Namespace: 解析された引数を含むオブジェクト。

入出力ファイル

入力ファイル

  • データファイル: --infile オプションで指定される2theta-intensityデータを含むテキストファイルです。各行に2theta角度と強度値がスペース区切りで記述されていることが期待されます。ファイルが指定されない場合 (--infile "")、プログラムは模擬データを生成します。

  • CIFファイル:

    • --substrate_file オプションで指定される基板の結晶情報ファイル (CIF形式)。デフォルトは GaN.cif です。

    • --film_file オプションで指定される膜の結晶情報ファイル (CIF形式)。デフォルトは AlN.cif です。

  • パラメータファイル: 過去のフィッティング結果や初期パラメータが保存されたCSVファイルです。ファイル名は --infile で指定されたデータファイル名に基づいて自動生成されます (例: your_data-parameters.csv)。このファイルはプログラム起動時に読み込まれ、存在しない場合はデフォルトのパラメータが使用されます。

出力ファイル

  • パラメータファイル: フィッティングや膜厚推定の結果、最適化されたパラメータがCSV形式で保存されます。ファイル名は入力ファイル名に基づいて自動生成されます (例: your_data-parameters.csv)。

  • 膜厚推定ピークファイル: guess モードで検出されたフリンジピークの詳細情報がCSV形式で保存されます。ファイル名は入力ファイル名に基づいて自動生成されます (例: your_data-guess-peaks.csv)。ヘッダー行は cluster_id, n, q, 2theta, used_stage1, used_stage2, resid_stage1, resid_stage2 です。

  • 膜厚推定クラスターファイル: guess モードで解析されたフリンジクラスター（膜厚候補）のサマリーがCSV形式で保存されます。ファイル名は入力ファイル名に基づいて自動生成されます (例: your_data-guess-clusters.csv)。ヘッダー行は cluster_id, npeaks, dq_est, thick_fft, thick_reg, confidence です。

  • プロット: 各実行モードやフィッティングの進捗に応じて、MatplotlibによるXRDパターンや解析結果のプロットが画面に表示されます。

主要機能

1. 材料 / モデル準備

prepare_materials() : CIFファイルから基板と膜の材料オブジェクトを準備し、弾性定数を設定します。Hexagonal対称性を持ち、弾性テンソルが未定義の場合はデフォルトの六方晶系弾性定数が割り当てられます。

make_scan_axis() : XRDシミュレーション用のデフォルトの角度軸 (2theta, omega) を生成します。範囲は TWOTHETA_MIN から TWOTHETA_MAX (デフォルト: 32.0～38.0 deg)、点数は NPOINTS (デフォルト: 200) です。

model(substrate, film, x, relax, thick, energy) : 指定されたパラメータ (組成 x、緩和度 relax、膜厚 thick) で動的XRDシミュレーションモデルを構築します。xrayutilities の Layer オブジェクトと PseudomorphicStack001 を使用します。

simulate(dyn_model, omega) : 構築された動的理論モデルを使用してXRD強度分布を計算します。

2. データ入出力

read_text_data(infile) : テキストファイルから2列データ (2theta, intensity) を読み込みます。ファイルが存在しない場合やフォーマットが不正な場合はエラーで終了します。

read_data(infile, substrate, film, energy) : XRDデータファイルを読み込むか、ファイルが指定されていない場合は模擬データを生成します。模擬データは TARGET_X, TARGET_RELAX, TARGET_THICK (デフォルト: 0.2, 0.0, 1500.0) で定義されたターゲットパラメータを使用して生成されます。

3. パラメータ管理

プログラムは、組成 x、緩和度 relax、膜厚 thick の3つのパラメータを管理します。これらのパラメータは、辞書形式で保持され、それぞれの値 (value) と最適化対象フラグ (optid) を含みます。

make_default_parameter_set() : 単一のパラメータセット（組成、緩和度、膜厚）の初期辞書を作成します。初期値は定数 TRY_X, TRY_RELAX, TRY_THICK (デフォルト: 0.0, 1.0, 1500.0) から取得され、全て最適化対象として設定されます。

read_parameters(parameter_file) : CSVファイルからパラメータ設定を読み込みます。ファイルが存在しない場合はデフォルト値を返します。

save_parameters(parameter_file, param_sets) : 現在のパラメータセットをCSVファイルに書き出します。複数のパラメータセット（例: PSOの粒子）も保存可能です。

apply_fix_list(param_sets, fix_list) : 指定されたパラメータの最適化フラグ (optid) をオフ (0) に設定し、最適化から除外します。

4. 実行モード

main() 関数は、--mode コマンドライン引数に応じて以下のいずれかの処理を実行します。

a. read モード

指定された --infile からXRDデータを読み込み、プロットして表示します。

b. sim モード

現在のパラメータセット (デフォルトは DEFAULT_PRIMARY_SET) を使用してXRDパターンをシミュレートし、プロットして表示します。 --infile が指定されている場合は、実験データとシミュレーション結果を比較してプロットします。

c. guess モード

guess_thickness() 関数を実行し、XRDフリンジ解析に基づいて膜厚を推定します。

  1. 指定された角度範囲 (--guess_low ～ --guess_high) でデータの一部を切り出します。

  2. Savitzky-Golayフィルタ (--nsmooth_points, --nsmooth_order) でエンベロープを除去し、残差信号を抽出します。

  3. 残差信号にFFTを適用し、主要な周波数成分から膜厚の初期候補 (Δq_est) を算出します。

  4. 残差信号からフリンジピークを検出し、Δq_estとギャップ係数 (--cluster_gap_factor) に基づいてピークをクラスターに分割します。

  5. 各クラスター内でフリンジ次数を割り当て、2段階の線形回帰分析を行い、最終的な膜厚候補を算出します。

  6. 検出されたピーク情報 (-guess-peaks.csv) とクラスター情報 (-guess-clusters.csv) をCSVファイルに保存します。

  7. FFTと線形回帰の両方から得られた膜厚候補をスコア順にソートし、上位の候補をコンソールに表示します。

  8. 最もスコアの高い膜厚候補をプライマリパラメータセットの膜厚値として設定し、上位の候補はPSO粒子としてパラメータファイルに保存されます。

  9. 解析の主要なステップ（信号・残差、FFTスペクトル、n-qプロット）を視覚化します。

d. fit モード

--infile で指定された実験データに、構造パラメータ (組成 x、緩和度 relax、膜厚 thick) をフィッティングして最適化します。最適化の進捗はライブプロットでリアルタイムに表示されます。

i. random (ランダム探索)

fit_random() 関数を実行します。現在の最適パラメータセットからランダムに少しずつパラメータを変化させ、残差が改善されればその新しいパラメータセットを採用するという手順を繰り返します。一定回数改善が見られない場合や、残差が LIMIT (デフォルト: 0.01) 以下になれば停止します。

ii. nelder-mead, bfgs, cg (SciPyの最適化アルゴリズム)

fit_scipy() 関数を実行します。 scipy.optimize.minimize 関数を利用し、指定された最適化手法でパラメータを調整します。目的関数は物理的な制約へのペナルティを含みます。最大反復回数 (--nmaxiter) と収束判定の許容誤差 (--tol) を設定できます。

iii. pso (粒子群最適化)

fit_pso() 関数を実行します。複数の「粒子」が解空間を探索する粒子群最適化アルゴリズムを実装しています。各粒子は、自身の最良の位置 (pbest) と群全体の最良の位置 (gbest) に基づいて速度と位置を更新します。一定期間の改善なし (--pso_stall_max) または粒子の位置の分散が閾値以下になった場合 (--pso_spread_rtol) に早期停止します。粒子の数 (--pso_nparticles)、慣性重み (--pso_w)、自己学習係数 (--pso_c1)、社会学習係数 (--pso_c2) などのパラメータを設定できます。

5. ユーティリティ関数

clamp_values(x, relax, thick) : 組成 x (0.0～1.0)、緩和度 relax (0.0～1.0)、膜厚 thick (1.0以上) のパラメータを物理的に妥当な範囲にクランプします。

calc_residual(int_target, int_try, residual_scale="log") : ターゲット強度とシミュレーション強度の残差 (L2ノルム) を計算します。 residual_scale が log の場合、強度は対数スケールに変換されてから残差が計算されます。

plot_xrd(omega, intensity_list, labels, title, yscale="log", text_lines=None, wait=False) : 複数のXRDパターンをプロットし表示します。Y軸のスケール (linear または log) とプロットのタイトルを設定でき、追加のテキスト行を表示することも可能です。

make_live_plot(...), update_live_plot(...), show_final_live_plot_wait(fig) : フィッティングの進捗をリアルタイムで表示するためのインタラクティブなライブプロットを管理します。

コード例

1. ヘルプメッセージの表示

python xrd_fit_xrayutilities.py --help

2. XRDデータの読み込みと表示 (read モード)

test.txt という名前のデータファイルが存在する場合:

python xrd_fit_xrayutilities.py --mode read --infile test.txt

3. XRDパターンのシミュレーションと表示 (sim モード)

デフォルトのパラメータでシミュレーションを実行します。

python xrd_fit_xrayutilities.py --mode sim

test.txt と比較しながらシミュレーションを実行します。

python xrd_fit_xrayutilities.py --mode sim --infile test.txt

4. 膜厚の自動推定 (guess モード)

test.txt のデータを用いて膜厚を推定します。推定結果は test-parameters.csv に保存され、ピークやクラスターの詳細は test-guess-peaks.csv および test-guess-clusters.csv に保存されます。

python xrd_fit_xrayutilities.py --mode guess --infile test.txt

5. パラメータの最適化 (fit モード)

a. PSOアルゴリズムによるフィッティング

test.txt のデータに対して、粒子群最適化 (PSO) アルゴリズムでパラメータをフィッティングします。

python xrd_fit_xrayutilities.py --mode fit --method pso --infile test.txt

組成 x を固定し、緩和度 relax と膜厚 thick のみを最適化する場合:

python xrd_fit_xrayutilities.py --mode fit --method pso --infile test.txt --fix x

b. Nelder-Mead法によるフィッティング

test.txt のデータに対して、Nelder-Mead法でパラメータをフィッティングします。

python xrd_fit_xrayutilities.py --mode fit --method nelder-mead --infile test.txt