guess_lattice_parameters.py

概要

guess_lattice_parameters.py は、粉末X線回折（XRD）データに対して、ピーク検出と格子定数予測を行うPythonスクリプトです。このスクリプトは、XRD生データファイルや既存のピーク情報ファイルから回折ピークを抽出し、そのピーク情報に基づいて様々な結晶系（立方晶、正方晶、六方晶、斜方晶）の格子定数を推定します。また、推定された格子定数と観測ピークのマッチングを比較する機能や、ユーザーが指定した格子定数と観測ピークを比較する機能も提供します。

要求事項

このプログラムを実行するには、Python 3.8以降のバージョンが必要です。

標準ライブラリ

以下の標準ライブラリが使用されています。

• argparse: コマンドライン引数の解析

• itertools: 効率的なループ操作のためのイテレータの作成

• importlib.util: モジュールを動的にインポートするためのユーティリティ

• io: I/Oストリームの操作

• math: 数学関数

• sys: システム固有のパラメータと関数

• dataclasses: データクラスの自動生成

• pathlib: ファイルシステムパスをオブジェクトとして操作

• typing: 型ヒントのサポート

非標準ライブラリ

以下の非標準ライブラリが必要です。

• matplotlib

• numpy

• pandas

• scipy.signal

• openpyxl

これらのライブラリは、通常 pip を使用してインストールできます。例えば、以下のように実行します。

pip install matplotlib numpy pandas scipy openpyxl

また、インタラクティブなプロットでホバーアノテーションを有効にするためには、mplcursors のインストールが推奨されています。

pip install mplcursors

格子定数の精密化には、外部スクリプト lsq_latt2.py が必要です。これは動的にインポートされます。

コマンドラインインターフェース（CLI）

このプログラムはコマンドライン引数を受け取ります。以下に主な引数とその説明を示します。

基本的な引数

• arg1: 入力データファイル、ピーク情報ファイル、または予測ワークブックのパス。 レガシーな用法として、「 search infile 」の形式も受け入れられます。

• arg2: レガシーな位置指定モードの入力ファイル（例： 「 search sample.TXT 」）。省略可能です。

• --mode {search,guess,all,compare,calc}: 実行モードを指定します。

  • search: ピーク検出のみを実行します。

  • guess: ピークファイルから格子定数を予測します。

  • all: ピーク検出と予測の両方を実行します（デフォルト）。

  • compare: ランク付けされた候補と観測ピークを比較します。

  • calc: ユーザーが指定した格子定数と比較します。 デフォルトは all です。

• --method {combinatorial,grid,both}: 格子定数予測の方法を指定します。

  • combinatorial: 高速なHHKL組み合わせ探索を行います。

  • grid: 明示的な範囲または組み合わせのシードを使用したグリッド探索を行います。

  • both: 両方の結果をマージします。 デフォルトは combinatorial です。

• --crystal-system {auto,all,cubic,tetragonal,hexagonal,orthorhombic}: テストする結晶系を指定します。 auto / all 、 cubic 、 tetragonal 、 hexagonal 、 orthorhombic 、 またはカンマ区切りの値を指定できます。デフォルトは auto です。

• --peak-file PATH: ピーク情報Excel/CSVファイルのパス。デフォルトは None です。

• --guess-file PATH: --mode compare で使用される予測ワークブックのパス。デフォルトは None です。

• --output-file PATH: guess / all / compare 結果の出力ワークブックのパス。デフォルトは None です。

• --plot-file PATH: 出力グラフのパス。デフォルトは None です。

• --candidate-rank INT: --mode compare で使用される候補のランク。デフォルトは 1 です。

• --wavelength FLOAT: X線波長をオングストローム単位で指定します。デフォルトは Cu Kα1 = 1.54056 です。

明示的な格子定数（ --mode calc または --mode compare で使用）

• --a FLOAT, --lattice-a FLOAT: 明示的な格子定数 a をオングストローム単位で指定します。デフォルトは None です。

• --b FLOAT, --lattice-b FLOAT: 明示的な格子定数 b をオングストローム単位で指定します。デフォルトは None です。

• --c FLOAT, --lattice-c FLOAT: 明示的な格子定数 c をオングストローム単位で指定します。デフォルトは None です。

• --alpha FLOAT: 明示的なアルファ角を度数単位で指定します。現在、出力に保存されます。デフォルトは None です。

• --beta FLOAT: 明示的なベータ角を度数単位で指定します。現在、出力に保存されます。デフォルトは None です。

• --gamma FLOAT: 明示的なガンマ角を度数単位で指定します。現在、出力に保存されます。デフォルトは None です。

生XRDデータ / ピーク検出オプション

• --xmin FLOAT: 2θ範囲の下限を指定します。デフォルトは None です。

• --xmax FLOAT: 2θ範囲の上限を指定します。デフォルトは None です。

• --threshold FLOAT: ピーク検出の最小強度しきい値を指定します。デフォルトは 1000.0 です。

• --nsmooth INT: Savitzky-Golayフィルターの窓サイズ。デフォルトは 11 です。

• --norder INT: Savitzky-Golayフィルターの多項式次数。デフォルトは 4 です。

• --ydiff1-threshold FLOAT: 一次導関数の比率しきい値。デフォルトは 1.0e-2 です。

• --fwhm-min-deg FLOAT: FWHMの最小値（度）。デフォルトは 0.06 です。

• --fwhm-max-deg FLOAT: FWHMの最大値（度）。デフォルトは 1.0 です。

結晶インデックス付け / 比較オプション

• --npeak INT: 格子定数予測に使用する最も強いピークの数。デフォルトは 10 です。

• --hmax INT: h, k, l 指数の最大絶対値。デフォルトは 12 です。

• --lattice-max FLOAT, --max-lattice FLOAT: 予測される格子定数の上限（オングストローム）。 デフォルトは「観測された非Kα2ピークの最小2θにおけるd間隔」に --lattice-max-factor を乗じた値です。 0以下の値を設定すると、この制限は無効になります。デフォルトは None です。

• --lattice-max-factor FLOAT: --lattice-max が省略された場合に、最小2θのd間隔に乗じる係数。デフォルトは 1.2 です。

• --tolerance-deg FLOAT: グリッド探索/比較における2θ割り当ての許容誤差（度）。デフォルトは 0.25 です。

• --penalty-unassigned FLOAT: 未割り当てピークに対するペナルティスコア。デフォルトは 0.5 です。

• --keep INT: 内部的に保持されるグリッド候補の数。デフォルトは 200 です。

• --grid-refine INT: グリッド探索における割り当て/再適合の反復回数。デフォルトは 2 です。

• --grid-margin FLOAT: グリッド探索における組み合わせシードの相対マージン。デフォルトは 0.05 です。

• --grid-seed-top INT: ローカルグリッド探索に使用されるシステムあたりの組み合わせシードの数。デフォルトは 3 です。

明示的なグリッド範囲（省略した場合、グリッド探索は組み合わせシードを使用）

• --amin FLOAT: 格子定数 a の最小値。デフォルトは None です。

• --amax FLOAT: 格子定数 a の最大値。デフォルトは None です。

• --astep FLOAT: 格子定数 a のグリッドステップ。デフォルトは 0.02 です。

• --bmin FLOAT: 格子定数 b の最小値。デフォルトは None です。

• --bmax FLOAT: 格子定数 b の最大値。デフォルトは None です。

• --bstep FLOAT: 格子定数 b のグリッドステップ。デフォルトは 0.02 です。

• --cmin FLOAT: 格子定数 c の最小値。デフォルトは None です。

• --cmax FLOAT: 格子定数 c の最大値。デフォルトは None です。

• --cstep FLOAT: 格子定数 c のグリッドステップ。デフォルトは 0.02 です。

その他のオプション

• --lsq-script PATH: 格子定数精密化に使用するスクリプト（例： lsq_latt2.py ）のパス。デフォルトは lsq_latt2.py です。

• --show {0,1}: Matplotlibグラフウィンドウを表示するかどうか。デフォルトは 0 です（表示しない）。

• --save {0,1}, --save-plot {0,1}: グラフ画像を保存するかどうか。デフォルトは 1 です（保存する）。

• --plot-theory {near,matched,all,none}: compare / calc プロットで描画する計算された理論線の種類。

  • near: --plot-near-deg 内で観測ピークに割り当てられた線のみを描画します。

  • matched: マッチングされた線のみを描画します。

  • all: すべての線をとても密に描画します（大きな単位格子の場合）。

  • none: 理論線を描画しません。 デフォルトは near です。

• --plot-near-deg FLOAT: --plot-theory near で使用される2θウィンドウ。デフォルトは 0.5 です。

• --no-show: レガシーオプション。 --show 0 と同等です。

使用例

デフォルト

ピーク探索と格子定数予測を実行します。

python guess_lattice_parameters.py sample.TXT

ピーク探索のみ

ピーク情報をExcelファイルに保存します。

python guess_lattice_parameters.py sample.TXT --mode search --threshold 1000

予測のみ

--mode search で保存されたピーク情報ファイルを読み込みます。

python guess_lattice_parameters.py sample-peaks.xlsx --mode guess --crystal-system cubic

レガシーな位置指定モード

これも受け入れられます。

python guess_lattice_parameters.py search sample.TXT

設定と定数

• CU_KA1: 1.54056 。Cu Kα1のX線波長（Å）。

• CU_KA2: 1.54439 。Cu Kα2のX線波長（Å）。

• ANGLE_EPS: 1.0e-12 。角度比較における微小な許容誤差。

• SUPPORTED_CRYSTAL_SYSTEMS: サポートされている結晶系のリスト。 ["hexagonal", "orthorhombic", "tetragonal", "cubic"] 。

• CRYSTAL_SYSTEM_ALIASES: 結晶系名のエイリアスマッピング。 auto, all, any は auto に、 hex, hexagonal は hexagonal に、といったようにマッピングされます。

• KNOWN_MODES: 認識されている実行モードのセット。 {"search", "guess", "all", "compare", "calc", "index", "seaerch"} 。 index は後方互換性のため all にマッピングされ、 seaerch はタイプミスを修正するために search にマッピングされます。

• SUPPORTED_METHODS: サポートされている格子定数予測方法のリスト。 ["combinatorial", "grid", "both"] 。

データクラス

Peak

検出された回折ピークの情報を保持するデータクラスです。

• index (int): ピークの元のデータ配列におけるインデックス。

• two_theta (float): ピークの2θ角度（度）。

• intensity (float): ピークの平滑化された強度。

• intensity_raw (float): ピークの生の強度。

• fwhm_deg (float): ピークの半値幅（度）。

• inv_d2 (float): ピークの 1/d^2 値。

• d (float): ピークのd間隔（Å）。

• q (float): ピークの散乱ベクトル q 値。

• ka_role (str, デフォルト: ""): ピークがKα1かKα2かを示す役割（例: "ka1", "ka2" ）。

• ka_pair_index (int | None, デフォルト: None): Kαペアの相手となるピークのインデックス。

• source (str, デフォルト: "detected"): ピークの検出元（例: "detected" またはファイルパス）。

Candidate

予測された格子定数の候補を保持するデータクラスです。

• crystal_system (str): 候補の結晶系。

• ls_code (int): 格子定数計算のための内部コード。

• params (dict[str, float]): 格子定数パラメータ（例: {"a": 3.9, "c": 5.0} ）。

• score_matches (int): 観測ピークとのマッチング数に基づいたスコア。

• score_rms_rel (float): 残差の相対二乗平均平方根（RMS）。

• selected_matches (list[dict]): 選択されたピークと計算されたHHKLのマッチング詳細のリスト。

• all_matches (list[dict]): すべての観測ピークと計算されたHHKLのマッチング詳細のリスト。

関数

bragg_d(two_theta_deg, wavelength=CU_KA1)

ブラッグの法則に基づいて、2θ角度からd間隔を計算します。

• パラメータ:

  • two_theta_deg (float): 2θ角度（度）。

  • wavelength (float, デフォルト: CU_KA1): 使用するX線の波長（Å）。

• 戻り値:

  • float: d間隔（Å）。 two_theta_deg が0以下の場合、 inf を返します。

inv_d2_from_two_theta(two_theta_deg, wavelength=CU_KA1)

2θ角度から 1/d^2 を計算します。

• パラメータ:

  • two_theta_deg (float): 2θ角度（度）。

  • wavelength (float, デフォルト: CU_KA1): 使用するX線の波長（Å）。

• 戻り値:

  • float: 1/d^2 値。d間隔が計算できない場合、 nan を返します。

two_theta_from_d(d, wavelength=CU_KA1)

d間隔から2θ角度を計算します。

• パラメータ:

  • d (float): d間隔（Å）。

  • wavelength (float, デフォルト: CU_KA1): 使用するX線の波長（Å）。

• 戻り値:

  • float | None: 2θ角度（度）。計算が不可能な場合、 None を返します。

two_theta_from_inv_d2(inv_d2, wavelength=CU_KA1)

1/d^2 から2θ角度を計算します。

• パラメータ:

  • inv_d2 (float): 1/d^2 値。

  • wavelength (float, デフォルト: CU_KA1): 使用するX線の波長（Å）。

• 戻り値:

  • float | None: 2θ角度（度）。 inv_d2 が0以下の場合、 None を返します。

sanitize_stem(text)

ファイル名に使用できない文字をアンダースコアに置き換え、クリーンなファイルステムを生成します。

• パラメータ:

  • text (str): 元のテキスト。

• 戻り値:

  • str: サニタイズされた文字列。

read_xy_data(path)

指定されたパスからXYデータを読み込みます。Excelファイル（ .xlsx, .xls ）またはCSV/テキストファイル（ .csv, 拡張子なしなど）に対応しています。

• パラメータ:

  • path (Path): 入力ファイルのパス。

• 戻り値:

  • tuple[np.ndarray, np.ndarray]: X座標とY座標のNumPy配列。

• 例外:

  • ValueError: スプレッドシート/テキストデータに2列以上のデータがない場合。

_interp_zero(x1, y1, x2, y2)

2点間の直線補間により、Y値が0になるX値を推定します。内部ヘルパー関数です。

• パラメータ:

  • x1 (float): 最初の点のX座標。

  • y1 (float): 最初の点のY座標。

  • x2 (float): 2番目の点のX座標。

  • y2 (float): 2番目の点のY座標。

• 戻り値:

  • float: Y値が0になるX座標。 y2 - y1 が非常に小さい場合、2点のX座標の平均を返します。

_find_zero_crossing_bounds(x, ydiff3, idx)

3次導関数のゼロ交差点を見つけて、特定のインデックス idx を囲む範囲を特定します。内部ヘルパー関数です。

• パラメータ:

  • x (np.ndarray): X座標の配列。

  • ydiff3 (np.ndarray): 3次導関数の配列。

  • idx (int): 現在のインデックス。

• 戻り値:

  • tuple[tuple[int, float] | None, tuple[int, float] | None]: 左と右のゼロ交差点情報（インデックス、X座標）のタプル。見つからない場合は None 。

estimate_fwhm(x, ysmooth, idx, ydiff3=None)

サビツキー・ゴレイ平滑化データとオプションで3次導関数ゼロ交差情報を使用してFWHM（半値幅）を推定します。

• パラメータ:

  • x (np.ndarray): X座標の配列。

  • ysmooth (np.ndarray): 平滑化されたY座標の配列。

  • idx (int): ピークの中心と推定されるインデックス。

  • ydiff3 (np.ndarray | None, デフォルト: None): 3次導関数の配列（オプション）。

• 戻り値:

  • float | None: FWHM（度）。推定できない場合は None 。

peak_search_deriv3(x, y, nsmooth=11, norder=4, threshold=1000.0, ydiff1_threshold=1.0e-2, fwhm_min_deg=0.06, fwhm_max_deg=1.0, is_print=True)

Savitzky-Golayフィルターで平滑化された3次導関数に基づいてピークを検出します。

• パラメータ:

  • x (np.ndarray): X座標（2θ角度）。

  • y (np.ndarray): Y座標（強度）。

  • nsmooth (int, デフォルト: 11): Savitzky-Golayフィルターの窓サイズ。

  • norder (int, デフォルト: 4): Savitzky-Golayフィルターの多項式次数。

  • threshold (float, デフォルト: 1000.0): ピークの最小強度しきい値。

  • ydiff1_threshold (float, デフォルト: 1.0e-2): 1次導関数の相対的なしきい値。

  • fwhm_min_deg (float, デフォルト: 0.06): FWHMの最小値（度）。

  • fwhm_max_deg (float, デフォルト: 1.0): FWHMの最大値（度）。

  • is_print (bool, デフォルト: True): 診断メッセージを標準出力に表示するかどうか。

• 戻り値:

  • tuple[list[Peak], dict[str, np.ndarray | float]]: 検出された Peak オブジェクトのリストと、平滑化データや導関数などの情報を含む辞書。

• 例外:

  • ValueError: データポイントが少なすぎる場合。

assign_ka2(peaks, tol_deg=0.06, ratio_min=0.18, ratio_max=0.75)

検出されたピーク群の中からCu Kα1/Kα2ペアを同定し、 Peak オブジェクトにその役割を割り当てます。

• パラメータ:

  • peaks (list[Peak]): 検出された Peak オブジェクトのリスト。

  • tol_deg (float, デフォルト: 0.06): Kα2ピークの2θ位置の許容誤差（度）。

  • ratio_min (float, デフォルト: 0.18): Kα2/Kα1強度比の最小値。

  • ratio_max (float, デフォルト: 0.75): Kα2/Kα1強度比の最大値。

• 戻り値:

  • list[Peak]: Kα役割が割り当てられた Peak オブジェクトのリスト。

system_rows(system, hmax=12)

与えられた結晶系（ cubic, tetragonal, hexagonal, orthorhombic ）に対して、計算される 1/d^2 値の「特徴量」（ h^2+k^2+l^2 など）と対応するHHKLインデックスのリストを生成します。

• パラメータ:

  • system (str): 結晶系名。

  • hmax (int, デフォルト: 12): HHKLインデックスの最大絶対値。

• 戻り値:

  • list[tuple[tuple[int, ...], tuple[int, int, int]]]: (特徴量タプル, (h, k, l)) の形式のタプルのリスト。

params_from_beta(system, beta)

格子定数予測で得られた係数（ beta ）から、物理的な格子定数（ a, b, c, 角度）を計算します。

• パラメータ:

  • system (str): 結晶系名。

  • beta (np.ndarray): 線形回帰で得られた係数のNumPy配列。

• 戻り値:

  • dict[str, float]: 格子定数パラメータの辞書。

predicted_inv_d2(system, feat, beta)

結晶系、特徴量（HHKLから導出される）、および係数 beta に基づいて 1/d^2 を予測します。

• パラメータ:

  • system (str): 結晶系名。

  • feat (Iterable[int]): HHKLから導出された特徴量（例: (h*h + k*k + l*l,) ）。

  • beta (np.ndarray): 線形回帰で得られた係数のNumPy配列。

• 戻り値:

  • float: 予測された 1/d^2 値。

score_system(system, selected, all_peaks, hmax=12)

与えられた結晶系に対して、組み合わせ探索アプローチで格子定数の候補を評価します。選択されたピークのサブセットを使用して、最小二乗法で格子定数を推定し、すべてのピークとのマッチングを評価します。

• パラメータ:

  • system (str): 結晶系名。

  • selected (list[Peak]): 格子定数予測に使用する選択されたピークのリスト。

  • all_peaks (list[Peak]): すべての観測ピークのリスト。

  • hmax (int, デフォルト: 12): HHKLインデックスの最大絶対値。

• 戻り値:

  • Candidate | None: 最適な格子定数候補、または見つからない場合は None 。

import_lsq_module(path)

指定されたパスからPythonモジュールを動的にインポートします。これは、 lsq_latt2.py のような外部の格子定数精密化スクリプトを読み込むために使用されます。

• パラメータ:

  • path (Path): インポートするモジュールファイルのパス。

• 戻り値:

  • module: インポートされたモジュールオブジェクト。

• 例外:

  • ImportError: モジュールをロードできない場合。

refine_with_lsq(lsq_script, candidate, matched_rows, wavelength=CU_KA1)

動的にインポートされた lsq_latt2.py スクリプトを使用して、格子定数を精密化します。

• パラメータ:

  • lsq_script (Path): lsq_latt2.py スクリプトのパス。

  • candidate (Candidate): 精密化の初期値として使用する格子定数候補。

  • matched_rows (list[dict]): 精密化に使用するマッチングされたピークのリスト。

  • wavelength (float, デフォルト: CU_KA1): X線波長（Å）。

• 戻り値:

  • tuple[dict, list[dict]] | None: 精密化された格子定数の要約と、精密化されたマッチングの詳細のリスト。マッチングが不可能な場合、または精密化が成功しない場合は None 。

_canonical_column_name(name)

データフレームの列名を正規化します（小文字化、スペース・記号の除去、アンダースコアへの置換など）。内部ヘルパー関数です。

• パラメータ:

  • name (object): 列名。

• 戻り値:

  • str: 正規化された列名。

_find_column(df, candidates)

与えられた候補リストの中から、データフレームに存在する列名を探します。内部ヘルパー関数です。

• パラメータ:

  • df (pd.DataFrame): 対象のデータフレーム。

  • candidates (set[str]): 正規化された列名の候補のセット。

• 戻り値:

  • str | None: 見つかった列名、または None 。

_read_peak_dataframe(path)

ピーク情報ファイル（ExcelまたはCSV）を pandas.DataFrame として読み込みます。Excelファイルの場合、特定のシート名を優先的に検索します。

• パラメータ:

  • path (Path): ピーク情報ファイルのパス。

• 戻り値:

  • pd.DataFrame: 読み込まれたデータフレーム。

read_peaks_file(path, wavelength=CU_KA1)

ピーク情報ファイルを読み込み、 Peak オブジェクトのリストを返します。 このスクリプトの --mode search で作成されたExcelファイルが推奨されます。 また、 two_theta_deg, 2theta, angle, または inv_d2_A-2 などの回折角度列を含むシンプルなCSV/テキストテーブルも受け入れられます。

• パラメータ:

  • path (Path): ピーク情報ファイルのパス。

  • wavelength (float, デフォルト: CU_KA1): X線波長（Å）。

• 戻り値:

  • list[Peak]: 読み込まれた Peak オブジェクトのリスト。

• 例外:

  • ValueError: ファイルが空であるか、使用可能なピークが見つからない場合。

normalize_mode(mode)

指定されたモード文字列を正規化します。レガシーな "index" やタイプミスの "seaerch" も対応します。

• パラメータ:

  • mode (str): 入力モード文字列。

• 戻り値:

  • str: 正規化されたモード文字列。

• 例外:

  • ValueError: 未サポートのモードの場合。

parse_crystal_systems(text)

カンマ区切り文字列から結晶系のリストを解析します。エイリアス（例: "hex" ）や "auto" / "all" もサポートします。

• パラメータ:

  • text (str): 結晶系名のカンマ区切り文字列。

• 戻り値:

  • list[str]: 解析された結晶系のリスト。

• 例外:

  • ValueError: 未サポートの結晶系の場合。

default_peak_file_for_input(infile)

入力ファイルに基づいて、デフォルトのピーク情報ファイルのパスを生成します。

• パラメータ:

  • infile (Path): 入力ファイルのパス。

• 戻り値:

  • Path: デフォルトのピーク情報ファイルパス。

strip_peak_suffix(stem)

ファイルステムから一般的なピークファイルサフィックス（例: -peaks ）を削除します。

• パラメータ:

  • stem (str): 元のファイルステム。

• 戻り値:

  • str: サフィックスが削除されたファイルステム。

default_guess_file_for_peak_file(peak_file, base_input=None)

ピーク情報ファイルまたは元の入力ファイルに基づいて、デフォルトの予測ファイルのパスを生成します。

• パラメータ:

  • peak_file (Path): ピーク情報ファイルのパス。

  • base_input (Path | None, デフォルト: None): 元の入力ファイルのパス（オプション）。

• 戻り値:

  • Path: デフォルトの予測ファイルパス。

peaks_to_frame(peaks)

Peak オブジェクトのリストを pandas.DataFrame に変換します。

• パラメータ:

  • peaks (list[Peak]): Peak オブジェクトのリスト。

• 戻り値:

  • pd.DataFrame: 変換されたデータフレーム。

print_peak_table(peaks, title)

検出されたピーク情報を整形されたテーブルとして標準出力に表示します。

• パラメータ:

  • peaks (list[Peak]): Peak オブジェクトのリスト。

  • title (str): テーブルのタイトル。

save_workbook(path, sheets)

複数の pandas.DataFrame をExcelワークブックの異なるシートとして保存します。

• パラメータ:

  • path (Path): 出力Excelファイルのパス。

  • sheets (dict[str, pd.DataFrame]): シート名をキー、対応するデータフレームを値とする辞書。

_maybe_install_mplcursors(artists, hover_texts)

mplcursors がインストールされている場合、Matplotlibのプロットにホバーアノテーションをアタッチします。内部ヘルパー関数です。

• パラメータ:

  • artists (list): アノテーションをアタッチするMatplotlibアーティストのリスト。

  • hover_texts (list[str]): 各アーティストに対応するホバーテキストのリスト。

_peak_hover_text(p, hkl_text=None, calc_two_theta=None, resid=None)

ピークプロットのホバーアノテーション用のテキストを生成します。内部ヘルパー関数です。

• パラメータ:

  • p (Peak): 対象の Peak オブジェクト。

  • hkl_text (str | None, デフォルト: None): HHKLテキスト（オプション）。

  • calc_two_theta (float | None, デフォルト: None): 計算された2θ角度（オプション）。

  • resid (float | None, デフォルト: None): 残差（オプション）。

• 戻り値:

  • str: 整形されたホバーテキスト。

plot_results(x, y, info, peaks, outpath, show=False, save=True)

XRDプロファイル、平滑化されたデータ、検出されたピークをプロットします。

• パラメータ:

  • x (np.ndarray): X座標（2θ角度）。

  • y (np.ndarray): Y座標（強度）。

  • info (dict[str, np.ndarray | float]): ピーク探索情報（平滑化データなど）。

  • peaks (list[Peak]): 検出された Peak オブジェクトのリスト。

  • outpath (Path | None): プロット画像の保存パス。

  • show (bool, デフォルト: False): プロットウィンドウを表示するかどうか。

  • save (bool, デフォルト: True): プロット画像を保存するかどうか。

beta_from_params(system, params)

物理的な格子定数パラメータから、格子定数予測で用いられる係数 beta を計算します。

• パラメータ:

  • system (str): 結晶系名。

  • params (dict[str, float]): 格子定数パラメータの辞書。

• 戻り値:

  • np.ndarray: 係数 beta のNumPy配列。

candidate_to_summary_row(rank, c, method="")

Candidate オブジェクトを要約行の辞書に変換します。これはデータフレームの行として使用されます。

• パラメータ:

  • rank (int): 候補のランク。

  • c (Candidate): 対象の Candidate オブジェクト。

  • method (str, デフォルト: ""): 予測方法（例: "combinatorial", "grid" ）。

• 戻り値:

  • dict[str, object]: 要約行の辞書。

candidate_from_summary_row(row)

pandas.Series （要約行）から Candidate オブジェクトを再構築します。

• パラメータ:

  • row (pd.Series): データフレームの要約行。

• 戻り値:

  • Candidate: 再構築された Candidate オブジェクト。

• 例外:

  • ValueError: 未サポートの結晶系、または必須の格子定数パラメータがない場合。

has_explicit_lattice_params(args)

コマンドライン引数に明示的な格子定数（ --a, --b, --c ）が指定されているかどうかをチェックします。

• パラメータ:

  • args (argparse.Namespace): 解析されたコマンドライン引数。

• 戻り値:

  • bool: 明示的な格子定数が存在すれば True 、そうでなければ False 。

candidate_from_lattice_args(args)

コマンドライン引数で指定された明示的な格子定数から Candidate オブジェクトを作成します。

• パラメータ:

  • args (argparse.Namespace): 解析されたコマンドライン引数。

• 戻り値:

  • Candidate: 作成された Candidate オブジェクト。

• 例外:

  • ValueError: 必須の格子定数パラメータが不足しているか、無効な値の場合。

filter_theoretical_lines_for_plot(theoretical_df, mode="near", near_deg=0.5)

プロット用に、計算された理論線のデータフレームをフィルターします。

• パラメータ:

  • theoretical_df (pd.DataFrame): 計算された理論線のデータフレーム。

  • mode (str, デフォルト: "near"): フィルターモード（ "near", "matched", "all", "none" ）。

  • near_deg (float, デフォルト: 0.5): "near" モードで使用される2θの許容誤差（度）。

• 戻り値:

  • pd.DataFrame: フィルターされた理論線のデータフレーム。

• 例外:

  • ValueError: 未サポートのフィルターモードの場合。

estimate_lattice_limit_from_peaks(peaks, wavelength=CU_KA1, factor=1.2)

ピーク情報から格子定数の推定上限を計算します。これは、最も低い角度の非Kα2ピークのd間隔に安全係数を乗じた値を使用します。

• パラメータ:

  • peaks (list[Peak]): 検出された Peak オブジェクトのリスト。

  • wavelength (float, デフォルト: CU_KA1): X線波長（Å）。

  • factor (float, デフォルト: 1.2): 安全係数。

• 戻り値:

  • tuple[float, float, float]: (最小2θ, その角度でのd間隔, デフォルトの格子上限) のタプル。

• 例外:

  • ValueError: 格子上限を推定できない場合。

resolve_lattice_max_limit(args, peaks)

コマンドライン引数とピーク情報に基づいて、格子定数の上限を解決します。

• パラメータ:

  • args (argparse.Namespace): 解析されたコマンドライン引数。

  • peaks (list[Peak]): 検出された Peak オブジェクトのリスト。

• 戻り値:

  • float | None: 解決された格子定数の上限、または制限が無効な場合は None 。

• 例外:

  • ValueError: --lattice-max-factor が0以下の場合。

params_within_lattice_max(params, system, lattice_max)

指定された格子定数パラメータが格子上限内にあるかどうかをチェックします。

• パラメータ:

  • params (dict[str, float]): 格子定数パラメータの辞書。

  • system (str): 結晶系名。

  • lattice_max (float | None): 格子定数の上限。

• 戻り値:

  • bool: 制限内であれば True 、そうでなければ False 。

filter_candidates_by_lattice_max(candidates, lattice_max, label="candidates", is_print=True)

格子定数の上限に基づいて、候補のリストをフィルターします。

• パラメータ:

  • candidates (list[Candidate]): 格子定数候補のリスト。

  • lattice_max (float | None): 格子定数の上限。

  • label (str, デフォルト: "candidates"): 出力メッセージに使用するラベル。

  • is_print (bool, デフォルト: True): フィルター情報を表示するかどうか。

• 戻り値:

  • list[Candidate]: フィルターされた候補のリスト。

theoretical_lines_for_candidate(candidate, hmax=12, wavelength=CU_KA1, xmin=None, xmax=None)

与えられた格子定数候補に基づいて、理論的な回折線（HHKL、2θ、d間隔、 1/d^2 ）を計算します。

• パラメータ:

  • candidate (Candidate): 対象の格子定数候補。

  • hmax (int, デフォルト: 12): HHKLインデックスの最大絶対値。

  • wavelength (float, デフォルト: CU_KA1): X線波長（Å）。

  • xmin (float | None, デフォルト: None): 2θ範囲の下限。

  • xmax (float | None, デフォルト: None): 2θ範囲の上限。

• 戻り値:

  • pd.DataFrame: 理論線のデータフレーム。

compare_candidate_with_peaks(candidate, peaks, hmax=12, wavelength=CU_KA1, xmin=None, xmax=None, tolerance_deg=0.25)

格子定数候補と観測ピークを比較し、HHKLの割り当てと残差を計算します。

• パラメータ:

  • candidate (Candidate): 対象の格子定数候補。

  • peaks (list[Peak]): 観測ピークのリスト。

  • hmax (int, デフォルト: 12): HHKLインデックスの最大絶対値。

  • wavelength (float, デフォルト: CU_KA1): X線波長（Å）。

  • xmin (float | None, デフォルト: None): 2θ範囲の下限。

  • xmax (float | None, デフォルト: None): 2θ範囲の上限。

  • tolerance_deg (float, デフォルト: 0.25): 2θ割り当ての許容誤差（度）。

• 戻り値:

  • tuple[pd.DataFrame, pd.DataFrame]: 計算された理論線のデータフレームと、観測ピークと計算線との割り当て詳細のデータフレーム。

plot_compare_results(x, y, peaks, theoretical_df, assignment_df, candidate, xmin, xmax, outpath, show=False, save=True)

観測XRDプロファイル、ピーク、理論線を比較プロットとして表示または保存します。

• パラメータ:

  • x (np.ndarray | None): XRDプロファイルのX座標（2θ角度）。 None の場合、ピークのみがプロットされます。

  • y (np.ndarray | None): XRDプロファイルのY座標（強度）。 None の場合、ピークのみがプロットされます。

  • peaks (list[Peak]): 観測ピークのリスト。

  • theoretical_df (pd.DataFrame): 計算された理論線のデータフレーム。

  • assignment_df (pd.DataFrame): 観測ピークと計算線との割り当て詳細のデータフレーム。

  • candidate (Candidate): 比較に使用された格子定数候補。

  • xmin (float): プロットの2θ範囲の下限。

  • xmax (float): プロットの2θ範囲の上限。

  • outpath (Path | None): プロット画像の保存パス。

  • show (bool, デフォルト: False): プロットウィンドウを表示するかどうか。

  • save (bool, デフォルト: True): プロット画像を保存するかどうか。

frange_values(vmin, vmax, step)

指定された範囲とステップで浮動小数点数の配列を生成します。

• パラメータ:

  • vmin (float): 最小値。

  • vmax (float): 最大値。

  • step (float): ステップサイズ。

• 戻り値:

  • np.ndarray: 浮動小数点数のNumPy配列。

• 例外:

  • ValueError: ステップが0以下、または vmax < vmin の場合。

_param_grid_for_system(system, ranges)

指定された結晶系と格子定数範囲に基づいて、格子定数パラメータのグリッドを生成します。内部ヘルパー関数です。

• パラメータ:

  • system (str): 結晶系名。

  • ranges (dict[str, tuple[float, float, float]]): 各格子定数（ "a", "b", "c" ）の (min, max, step) のタプルを含む辞書。

• 戻り値:

  • Iterable[dict[str, float]]: 格子定数パラメータの辞書のイテレータ。

_ranges_from_args_for_system(args, system)

コマンドライン引数から、グリッド探索に使用する格子定数範囲（ min, max, step ）を抽出します。内部ヘルパー関数です。

• パラメータ:

  • args (argparse.Namespace): 解析されたコマンドライン引数。

  • system (str): 結晶系名。

• 戻り値:

  • dict[str, tuple[float, float, float]] | None: 格子定数範囲の辞書、または範囲が指定されていない場合は None 。

_ranges_around_candidate(candidate, margin, args)

既存の格子定数候補の周りに、グリッド探索のための範囲（ min, max, step ）を生成します。内部ヘルパー関数です。

• パラメータ:

  • candidate (Candidate): 基準となる格子定数候補。

  • margin (float): 候補値からの相対マージン。

  • args (argparse.Namespace): 解析されたコマンドライン引数（ステップサイズ情報を取得するため）。

• 戻り値:

  • dict[str, tuple[float, float, float]]: 格子定数範囲の辞書。

_assign_peaks_for_params(peaks, system, params, hmax, wavelength, tolerance_deg)

与えられた格子定数パラメータに基づいて、ピークへのHHKL割り当てを試みます。内部ヘルパー関数です。

• パラメータ:

  • peaks (list[Peak]): 観測ピークのリスト。

  • system (str): 結晶系名。

  • params (dict[str, float]): 格子定数パラメータの辞書。

  • hmax (int): HHKLインデックスの最大絶対値。

  • wavelength (float): X線波長（Å）。

  • tolerance_deg (float): 2θ割り当ての許容誤差（度）。

• 戻り値:

  • tuple[list[dict], float, float, int]: 割り当て結果のリスト、RMS 2θ残差、RMS相対残差、マッチングされたピーク数。

_refit_params_from_assignment(system, rows)

ピーク割り当て結果から、格子定数を再適合します。内部ヘルパー関数です。

• パラメータ:

  • system (str): 結晶系名。

  • rows (list[dict]): 割り当て結果のリスト。

• 戻り値:

  • dict[str, float] | None: 再適合された格子定数パラメータの辞書、または再適合が不可能な場合は None 。

score_system_grid(system, selected, all_peaks, ranges, hmax=12, wavelength=CU_KA1, tolerance_deg=0.25, refine=2, keep=50, penalty_unassigned=0.5, lattice_max=None)

グリッド探索アプローチで格子定数候補を評価します。指定された範囲で格子定数を探索し、ピークとの割り当てと適合度を評価します。

• パラメータ:

  • system (str): 結晶系名。

  • selected (list[Peak]): 格子定数予測に使用する選択されたピークのリスト。

  • all_peaks (list[Peak]): すべての観測ピークのリスト。

  • ranges (dict[str, tuple[float, float, float]]): グリッド探索に使用する格子定数範囲の辞書。

  • hmax (int, デフォルト: 12): HHKLインデックスの最大絶対値。

  • wavelength (float, デフォルト: CU_KA1): X線波長（Å）。

  • tolerance_deg (float, デフォルト: 0.25): 2θ割り当ての許容誤差（度）。

  • refine (int, デフォルト: 2): 割り当て/再適合の反復回数。

  • keep (int, デフォルト: 50): 内部的に保持されるグリッド候補の数。

  • penalty_unassigned (float, デフォルト: 0.5): 未割り当てピークに対するペナルティスコア。

  • lattice_max (float | None, デフォルト: None): 格子定数の上限。

• 戻り値:

  • list[Candidate]: 評価された格子定数候補のリスト。

deduplicate_candidates(candidates, ndigits=4)

類似する格子定数を持つ候補を削除し、重複を排除します。

• パラメータ:

  • candidates (list[Candidate]): 格子定数候補のリスト。

  • ndigits (int, デフォルト: 4): 重複判定に使用する浮動小数点数の有効桁数。

• 戻り値:

  • list[Candidate]: 重複排除された候補のリスト。

guess_candidates(args, peaks, crystal_systems)

指定された引数とピーク情報に基づいて、格子定数候補を予測します。 combinatorial, grid, both のいずれかの方法を使用します。

• パラメータ:

  • args (argparse.Namespace): 解析されたコマンドライン引数。

  • peaks (list[Peak]): 観測ピークのリスト。

  • crystal_systems (list[str]): 予測対象の結晶系のリスト。

• 戻り値:

  • tuple[list[Candidate], list[Peak]]: 予測された格子定数候補のリストと、予測に使用された選択されたピークのリスト。

read_candidate_from_guess_file(path, rank)

予測ファイル（Excel）から、指定されたランクの格子定数候補を読み込みます。

• パラメータ:

  • path (Path): 予測ファイルのパス。

  • rank (int): 読み込む候補のランク。

• 戻り値:

  • Candidate: 読み込まれた Candidate オブジェクト。

• 例外:

  • ValueError: ファイル形式が不正であるか、指定されたランクの候補が見つからない場合。

try_read_raw_xy_for_plot(path)

プロットのために生XRD XYデータを読み込みを試みます。ピーク/予測ワークブックは生データとして扱われません。

• パラメータ:

  • path (Path): 入力ファイルのパス。

• 戻り値:

  • tuple[np.ndarray | None, np.ndarray | None]: XとYのNumPy配列、または読み込みに失敗した場合は (None, None) 。

looks_like_raw_xrd_file(path, min_rows=50)

ファイルが生のXRDデータファイルのように見えるかどうかをヒューリスティックに判定します。ピークリストとして解釈されるのを避けるためです。

• パラメータ:

  • path (Path): 入力ファイルのパス。

  • min_rows (int, デフォルト: 50): 生データと見なすための最小行数。

• 戻り値:

  • bool: 生XRDデータファイルのように見えれば True 、そうでなければ False 。

build_argument_parser()

コマンドライン引数を解析するための ArgumentParser オブジェクトを構築します。

• 戻り値:

  • argparse.ArgumentParser: 構築されたパーサー。

resolve_mode_and_input(args)

コマンドライン引数を解決し、実行モードと主要な入力ファイルパスを決定します。レガシーな位置指定引数もサポートします。

• パラメータ:

  • args (argparse.Namespace): 解析されたコマンドライン引数。

• 戻り値:

  • tuple[str, Path]: 解決されたモードと入力ファイルのパス。

• 例外:

  • SystemExit: 予期せぬ位置指定引数が存在する場合。

apply_x_range(x, y, xmin, xmax)

指定された xmin と xmax に基づいて、XYデータを範囲でフィルターします。

• パラメータ:

  • x (np.ndarray): X座標のNumPy配列。

  • y (np.ndarray): Y座標のNumPy配列。

  • xmin (float | None): X範囲の下限。

  • xmax (float | None): X範囲の上限。

• 戻り値:

  • tuple[np.ndarray, np.ndarray]: フィルターされたXとYのNumPy配列。

• 例外:

  • ValueError: フィルター適用後にデータポイントが残らない場合。

run_search(args, infile)

ピーク検出モードの主要なロジックを実行します。入力ファイルを読み込み、ピークを検出し、Kα2ペアを割り当て、結果をプロットしてExcelファイルに保存します。

• パラメータ:

  • args (argparse.Namespace): 解析されたコマンドライン引数。

  • infile (Path): 入力データファイルのパス。

• 戻り値:

  • tuple[list[Peak], Path, Path | None]: 検出されたピークのリスト、ピーク情報ファイルのパス、およびプロット画像のパス（保存された場合）。

run_guess(args, peak_file, base_input=None)

格子定数予測モードの主要なロジックを実行します。ピークファイルを読み込み、格子定数候補を予測し、結果を標準出力に表示し、Excelファイルに保存します。

• パラメータ:

  • args (argparse.Namespace): 解析されたコマンドライン引数。

  • peak_file (Path): ピーク情報ファイルのパス。

  • base_input (Path | None, デフォルト: None): 元の入力ファイルのパス（オプション）。

• 戻り値:

  • Path: 予測結果が保存されたExcelファイルのパス。

_load_peaks_for_compare(args, infile)

compare モードで使用するためにピーク情報を読み込みます。 --peak-file が指定されていればそれを、そうでなければ infile をピークファイルとして試行します。 infile が生XRDデータに見える場合は run_search() を呼び出してピークを検出します。内部ヘルパー関数です。

• パラメータ:

  • args (argparse.Namespace): 解析されたコマンドライン引数。

  • infile (Path): 入力ファイルのパス。

• 戻り値:

  • tuple[list[Peak], np.ndarray | None, np.ndarray | None, Path | None]: 検出されたピークのリスト、生XRDのX座標、Y座標（存在する場合）、および使用されたピークファイルのパス。

run_compare(args, infile)

比較モードの主要なロジックを実行します。候補を読み込み（明示的な格子定数、予測ファイル、またはその場で予測）、観測ピークと比較し、結果をプロットしてExcelファイルに保存します。

• パラメータ:

  • args (argparse.Namespace): 解析されたコマンドライン引数。

  • infile (Path): 入力ファイルのパス。

• 戻り値:

  • Path: 比較結果が保存されたExcelファイルのパス。

メイン実行フロー

main()

プログラムのエントリポイントです。

1. build_argument_parser() を使用してコマンドライン引数を解析します。

2. resolve_mode_and_input() を呼び出して、実行モードと入力ファイルを決定します。

3. 決定されたモードに基づいて、以下のいずれかの関数を呼び出します。

   • search モード: run_search() を呼び出します。

   • guess モード: run_guess() を呼び出します。

   • compare または calc モード: run_compare() を呼び出します。

   • all モード: まず run_search() を呼び出し、次にその結果を使用して run_guess() を呼び出します。

4. 例外が発生した場合、エラーメッセージを標準エラー出力に表示します。

5. Matplotlibのプロットが表示されている場合、ユーザーが ENTER キーを押すまでプログラムは終了しません。

このスクリプトは、ファイルとして直接実行されることを意図しており、if __name__ == "__main__": ブロック内で main() 関数が呼び出されます。

if __name__ == "__main__":
    raise SystemExit(main())