guess_lattice_parameters プログラム仕様

class XRD.guess_lattice_parameters.Candidate(crystal_system: str, ls_code: int, params: dict[str, float], score_matches: int, score_rms_rel: float, selected_matches: list[dict], all_matches: list[dict])

ベースクラス: object

概要:

格子定数推定の候補結果を保持するデータクラスです。

属性:

param crystal_system:

候補の結晶系（例: "cubic", "tetragonal"）。

type crystal_system:

str

param ls_code:

結晶系に対応する最小二乗コード。

type ls_code:

int

param params:

格子定数と角度の辞書。

type params:

dict[str, float]

param score_matches:

マッチしたピークの数。

type score_matches:

int

param score_rms_rel:

相対RMS誤差。

type score_rms_rel:

float

param selected_matches:

推定に使用されたピークのマッチング詳細のリスト。

type selected_matches:

list[dict]

param all_matches:

全ての観測ピークのマッチング詳細のリスト。

type all_matches:

list[dict]

all_matches: list[dict]

crystal_system: str

ls_code: int

params: dict[str, float]

score_matches: int

score_rms_rel: float

selected_matches: list[dict]

class XRD.guess_lattice_parameters.Peak(index: int, two_theta: float, intensity: float, intensity_raw: float, fwhm_deg: float, inv_d2: float, d: float, q: float, ka_role: str = '', ka_pair_index: int | None = None, source: str = 'detected')

ベースクラス: object

概要:

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

属性:

param index:

データ配列におけるピークのインデックス。

type index:

int

param two_theta:

ピークの中心角度2θ（度）。

type two_theta:

float

param intensity:

スムージング後のピーク強度。

type intensity:

float

param intensity_raw:

元データのピーク強度。

type intensity_raw:

float

param fwhm_deg:

半値全幅（度）。

type fwhm_deg:

float

param inv_d2:

d間隔の二乗の逆数（1 / d^2）。

type inv_d2:

float

param d:

d間隔（オングストローム）。

type d:

float

param q:

散乱ベクトルq（A^-1）。

type q:

float

param ka_role:

Kα1またはKα2の役割を示す文字列（"ka1", "ka2", ""）。

type ka_role:

str

param ka_pair_index:

Kαペアの相手のピークのインデックス（存在しない場合はNone）。

type ka_pair_index:

int | None

param source:

ピークの検出元（"detected"またはファイルパス）。

type source:

str

d: float

fwhm_deg: float

index: int

intensity: float

intensity_raw: float

inv_d2: float

ka_pair_index: int | None = None

ka_role: str = ''

q: float

source: str = 'detected'

two_theta: float

XRD.guess_lattice_parameters.apply_x_range(x: ndarray, y: ndarray, xmin: float | None, xmax: float | None) → tuple[ndarray, ndarray]

概要:

X-YデータにX軸範囲のフィルタリングを適用します。

詳細説明:

X座標が xmin 以上 xmax 以下のデータポイントのみを保持するように numpy配列 x と y をフィルタリングします。 xmin または xmax がNoneの場合、その側のフィルタリングは適用されません。

引数:

param x:

X座標のnumpy配列。

type x:

numpy.ndarray

param y:

Y座標のnumpy配列。

type y:

numpy.ndarray

param xmin:

最小X値の閾値（オプション）。

type xmin:

float | None

param xmax:

最大X値の閾値（オプション）。

type xmax:

float | None

戻り値:

returns:

フィルタリングされたX値とY値のnumpy配列のタプル。

rtype:

tuple[numpy.ndarray, numpy.ndarray]

例外:

raises ValueError:

xmin/xmax適用後にデータポイントが残らない場合。

XRD.guess_lattice_parameters.assign_ka2(peaks: list[Peak], tol_deg: float = 0.06, ratio_min: float = 0.18, ratio_max: float = 0.75) → list[Peak]

概要:

検出されたピークにKα2の役割を割り当てます。

詳細説明:

Cu Kα1の波長に対応するピークに対して、Cu Kα2の波長で同じd間隔を持つピークを探索します。 2θ角度の許容範囲 (tol_deg) とKα2/Kα1強度比 (ratio_min, ratio_max) に基づいてペアを特定し、 それぞれのピークに "ka1" または "ka2" の役割を割り当てます。 最も強いピークから順に処理し、一度Kα2として使用されたピークは再利用されません。

引数:

param peaks:

Peakオブジェクトのリスト。

type peaks:

list[Peak]

param tol_deg:

Kα2ペアを識別するための2θ角度の許容誤差（度）。

type tol_deg:

float

param ratio_min:

Kα2ピークとKα1ピークの強度比の最小値。

type ratio_min:

float

param ratio_max:

Kα2ピークとKα1ピークの強度比の最大値。

type ratio_max:

float

戻り値:

returns:

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

rtype:

list[Peak]

XRD.guess_lattice_parameters.beta_from_params(system: str, params: dict[str, float]) → ndarray

概要:

格子定数の辞書から最小二乗法の係数 (beta) を計算します。

詳細説明:

与えられた結晶系と格子定数 (a, b, c) の辞書から、 inv_d2 (1 / d^2) の計算に必要な最小二乗係数 beta をnumpy配列として導出します。

引数:

param system:

結晶系名。

type system:

str

param params:

格子定数を含む辞書。

type params:

dict[str, float]

戻り値:

returns:

beta係数のnumpy配列。

rtype:

numpy.ndarray

例外:

raises ValueError:

サポートされていない結晶系が指定された場合。

XRD.guess_lattice_parameters.bragg_d(two_theta_deg: float, wavelength: float = 1.54056) → float

概要:

ブラッグの法則に基づいてd間隔を計算します。

詳細説明:

指定された2θ角度とX線波長から、ブラッグの法則 (n * lambda = 2 * d * sin(theta)) を用いて 回折面間隔dを計算します。thetaはtwo_theta_degの半分です。

引数:

param two_theta_deg:

回折角度2θ（度）。

type two_theta_deg:

float

param wavelength:

X線波長（オングストローム）。デフォルトはCU_KA1です。

type wavelength:

float

戻り値:

returns:

計算されたd間隔（オングストローム）。

rtype:

float

XRD.guess_lattice_parameters.build_argument_parser() → ArgumentParser

概要:

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

詳細説明:

ピーク探索、格子定数推定、比較などの機能に必要な全てのコマンドライン引数を定義します。 各引数には説明、型、デフォルト値、選択肢などが設定されています。 引数は、入力ファイル、モード、X線波長、ピーク探索オプション、インデクシング/比較オプション、 グリッド検索範囲、プロットオプションに分類されます。

戻り値:

returns:

構築されたArgumentParserオブジェクト。

rtype:

argparse.ArgumentParser

XRD.guess_lattice_parameters.candidate_from_lattice_args(args: Namespace) → Candidate

概要:

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

詳細説明:

--a, --b, --c, --alpha, --beta, --gamma などの引数から 格子定数情報を抽出し、Candidateオブジェクトを作成します。 指定された結晶系に基づいて、必要な格子定数が全て提供されているかを検証します。

引数:

param args:

コマンドライン引数を格納したNamespaceオブジェクト。

type args:

argparse.Namespace

戻り値:

returns:

生成されたCandidateオブジェクト。

rtype:

Candidate

例外:

raises ValueError:

結晶系の指定が適切でない、必要な格子定数が不足している、 または格子定数が正の値でない場合。

XRD.guess_lattice_parameters.candidate_from_summary_row(row: Series) → Candidate

概要:

サマリー行（Pandas Series）からCandidateオブジェクトを生成します。

詳細説明:

Excelファイルなどから読み込まれたサマリー行のデータを使って、 Candidateオブジェクトを再構築します。 結晶系と格子定数 (a, b, c, alpha, beta, gamma) を抽出し、 不足している角度はデフォルト値で補完します。

引数:

param row:

サマリー行を表すPandas Series。

type row:

pandas.Series

戻り値:

returns:

生成されたCandidateオブジェクト。

rtype:

Candidate

例外:

raises ValueError:

サポートされていない結晶系、または必要な格子定数が見つからない場合。

XRD.guess_lattice_parameters.candidate_to_summary_row(rank: int, c: Candidate, method: str = '') → dict[str, object]

概要:

Candidateオブジェクトをサマリー行（辞書）に変換します。

詳細説明:

Candidateオブジェクトの情報を、Excelなどのサマリーシートに適した辞書形式に変換します。 ランキング、メソッド、結晶系、マッチ数、RMS誤差、格子定数を含みます。

引数:

param rank:

候補の順位。

type rank:

int

param c:

Candidateオブジェクト。

type c:

Candidate

param method:

推定に使用されたメソッド（オプション）。

type method:

str

戻り値:

returns:

サマリー行を表す辞書。

rtype:

dict[str, object]

XRD.guess_lattice_parameters.compare_candidate_with_peaks(candidate: Candidate, peaks: list[Peak], hmax: int = 12, wavelength: float = 1.54056, xmin: float | None = None, xmax: float | None = None, tolerance_deg: float = 0.25) → tuple[DataFrame, DataFrame]

概要:

格子定数候補と観測ピークを比較し、割り当てを行います。

詳細説明:

与えられた格子定数候補 (candidate) と観測ピーク (peaks) を比較し、 理論的な回折線と観測ピークを割り当てます。 各観測ピークに対して最も近い理論的な回折線を見つけ、 指定された許容誤差 (tolerance_deg) 内であればマッチとみなします。 理論的回折線のデータフレームと、観測ピークと理論線の割り当て結果のデータフレームを返します。

引数:

param candidate:

格子定数候補。

type candidate:

Candidate

param peaks:

観測されたPeakオブジェクトのリスト。

type peaks:

list[Peak]

param hmax:

h, k, l指数の最大値。

type hmax:

int

param wavelength:

X線波長（オングストローム）。デフォルトはCU_KA1です。

type wavelength:

float

param xmin:

最小2θ角度（度）のフィルタリング閾値（オプション）。

type xmin:

float | None

param xmax:

最大2θ角度（度）のフィルタリング閾値（オプション）。

type xmax:

float | None

param tolerance_deg:

2θ角度の割り当て許容誤差（度）。

type tolerance_deg:

float

戻り値:

returns:

(理論的な回折線データフレーム, 観測ピークと理論線の割り当て結果データフレーム) のタプル。

rtype:

tuple[pandas.DataFrame, pandas.DataFrame]

XRD.guess_lattice_parameters.deduplicate_candidates(candidates: list[Candidate], ndigits: int = 4) → list[Candidate]

概要:

重複する格子定数候補をリストから除去します。

詳細説明:

Candidateオブジェクトの結晶系と、a, b, cの格子定数（ndigits桁で丸められたもの） に基づいて重複を判断します。 リストの順序を維持しつつ、最初に出現したユニークな候補のみを返します。

引数:

param candidates:

Candidateオブジェクトのリスト。

type candidates:

list[Candidate]

param ndigits:

格子定数を比較する際の丸め桁数。

type ndigits:

int

戻り値:

returns:

重複が除去されたCandidateオブジェクトのリスト。

rtype:

list[Candidate]

XRD.guess_lattice_parameters.default_guess_file_for_peak_file(peak_file: Path, base_input: Path | None = None) → Path

概要:

ピークファイル名に基づいてデフォルトの推定結果ファイル名を生成します。

詳細説明:

基本入力ファイル (base_input) が指定されている場合はそれを使用し、 そうでない場合はピークファイル名からピーク関連のサフィックスを除去し、 "-guess.xlsx" を追加したPathオブジェクトを返します。

引数:

param peak_file:

ピーク情報ファイルへのパス。

type peak_file:

Path

param base_input:

元の入力データファイルへのパス（オプション）。

type base_input:

Path | None

戻り値:

returns:

デフォルトの推定結果ファイルパス。

rtype:

Path

XRD.guess_lattice_parameters.default_peak_file_for_input(infile: Path) → Path

概要:

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

詳細説明:

入力ファイルのステムをサニタイズし、"-peaks.xlsx" を追加した Pathオブジェクトを返します。

引数:

param infile:

入力データファイルへのパス。

type infile:

Path

戻り値:

returns:

デフォルトのピークファイルパス。

rtype:

Path

XRD.guess_lattice_parameters.estimate_fwhm(x: ndarray, ysmooth: ndarray, idx: int, ydiff3: ndarray | None = None) → float | None

概要:

ピークの半値全幅（FWHM）を推定します。

詳細説明:

ピークトップの周辺のデータを用いてFWHMを計算します。 ydiff3（3次導関数）が提供されている場合、3次導関数のゼロ交差を境界として 局所的なFWHMを優先的に推定します。これにより、隣接するピークの影響を軽減します。 ydiff3が提供されない場合や、局所的な推定が不可能な場合は、 ピークトップの周辺の最小強度をベースラインとしてFWHMを計算します。

引数:

param x:

X座標のnumpy配列。

type x:

numpy.ndarray

param ysmooth:

スムージングされたY座標のnumpy配列。

type ysmooth:

numpy.ndarray

param idx:

FWHMを推定するピークトップのインデックス。

type idx:

int

param ydiff3:

3次導関数のnumpy配列。デフォルトはNone。

type ydiff3:

numpy.ndarray | None

戻り値:

returns:

推定されたFWHM（度）、または推定できなかった場合はNone。

rtype:

float | None

XRD.guess_lattice_parameters.estimate_lattice_limit_from_peaks(peaks: list[Peak], wavelength: float = 1.54056, factor: float = 1.2) → tuple[float, float, float]

概要:

観測ピークに基づいて格子定数の上限を推定します。

詳細説明:

観測されたピークの中で最も小さい2θ角度（Kα2ピークを除く）から、 対応する最大のd間隔を計算します。このd間隔に安全係数 (factor) を乗じて、 格子定数推定の妥当な上限値を決定します。この上限値は、低角度での回折線が 弱い、または欠落している可能性があるため、少し余裕を持たせるように設計されています。

引数:

param peaks:

Peakオブジェクトのリスト。

type peaks:

list[Peak]

param wavelength:

X線波長（オングストローム）。デフォルトはCU_KA1です。

type wavelength:

float

param factor:

d間隔に乗じる安全係数。

type factor:

float

戻り値:

returns:

(最小2θ角度, その角度でのd間隔, 推定された格子定数の上限) のタプル。

rtype:

tuple[float, float, float]

例外:

raises ValueError:

有効なピーク角度がない場合、またはd間隔の計算が不可能な場合。

XRD.guess_lattice_parameters.filter_candidates_by_lattice_max(candidates: list[Candidate], lattice_max: float | None, label: str = 'candidates', is_print: bool = True) → list[Candidate]

概要:

格子定数候補を格子定数上限値でフィルタリングします。

詳細説明:

lattice_max がNoneでない場合、その値を超える格子定数を持つCandidateオブジェクトを 候補リストから除外します。 除外された候補の数とラベルは、is_printがTrueの場合にコンソールに出力されます。

引数:

param candidates:

Candidateオブジェクトのリスト。

type candidates:

list[Candidate]

param lattice_max:

格子定数の上限値（オングストローム）、またはNone。

type lattice_max:

float | None

param label:

出力メッセージに使用する候補のラベル。

type label:

str

param is_print:

フィルタリング情報をコンソールに出力するかどうか。

type is_print:

bool

戻り値:

returns:

フィルタリングされたCandidateオブジェクトのリスト。

rtype:

list[Candidate]

XRD.guess_lattice_parameters.filter_theoretical_lines_for_plot(theoretical_df: DataFrame, mode: str = 'near', near_deg: float = 0.5) → DataFrame

概要:

プロット表示のために理論的な回折線をフィルタリングします。

詳細説明:

プロットモード (mode) に応じて、理論的な回折線データフレーム (theoretical_df) をフィルタリングします。 - "all": 全ての理論線を表示。 - "none": 全ての理論線を表示しない。 - "matched": 観測ピークにマッチした理論線のみ表示。 - "near": 観測ピークの近く（near_deg以内）にある理論線のみ表示。

引数:

param theoretical_df:

理論的な回折線情報を含むPandasデータフレーム。

type theoretical_df:

pandas.DataFrame

param mode:

フィルタリングモード（"near", "matched", "all", "none"）。

type mode:

str

param near_deg:

"near"モードで使用される2θ角度の許容範囲（度）。

type near_deg:

float

戻り値:

returns:

フィルタリングされた理論回折線データフレーム。

rtype:

pandas.DataFrame

例外:

raises ValueError:

サポートされていないプロットモードが指定された場合。

XRD.guess_lattice_parameters.frange_values(vmin: float, vmax: float, step: float) → ndarray

概要:

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

詳細説明:

numpy.arange のように動作しますが、浮動小数点数の丸め誤差を考慮して vmin から vmax までの値を step 間隔で生成します。

引数:

param vmin:

最小値。

type vmin:

float

param vmax:

最大値。

type vmax:

float

param step:

ステップサイズ。

type step:

float

戻り値:

returns:

生成された浮動小数点数のnumpy配列。

rtype:

numpy.ndarray

例外:

raises ValueError:

ステップが正でない、または最大値が最小値より小さい場合。

XRD.guess_lattice_parameters.guess_candidates(args: Namespace, peaks: list[Peak], crystal_systems: list[str]) → tuple[list[Candidate], list[Peak]]

概要:

与えられたピークと結晶系に基づいて格子定数候補を推定します。

詳細説明:

まず、最も強度の高い非Kα2ピークを args.npeak の数だけ選択します。 その後、args.method に応じて「組み合わせ探索」または「グリッド検索」を実行します。 グリッド検索は、明示的な範囲が指定されていない場合、組み合わせ探索で得られた 上位候補をシードとして使用できます。 格子定数上限 (args.resolved_lattice_max) も適用されます。

引数:

param args:

コマンドライン引数を格納したNamespaceオブジェクト。

type args:

argparse.Namespace

param peaks:

観測されたPeakオブジェクトのリスト。

type peaks:

list[Peak]

param crystal_systems:

探索する結晶系のリスト。

type crystal_systems:

list[str]

戻り値:

returns:

(評価されソートされたCandidateオブジェクトのリスト, 推定に使用されたピークのリスト) のタプル。

rtype:

tuple[list[Candidate], list[Peak]]

例外:

raises ValueError:

サポートされていない推定メソッドが指定された場合。

XRD.guess_lattice_parameters.has_explicit_lattice_params(args: Namespace) → bool

概要:

コマンドライン引数に明示的な格子定数が指定されているか確認します。

詳細説明:

args.a, args.b, args.c のいずれかがNoneでない場合にTrueを返します。

引数:

param args:

コマンドライン引数を格納したNamespaceオブジェクト。

type args:

argparse.Namespace

戻り値:

returns:

明示的な格子定数が指定されていればTrue、そうでなければFalse。

rtype:

bool

XRD.guess_lattice_parameters.import_lsq_module(path: Path)

概要:

指定されたパスからlsq_latt2モジュールを動的にインポートします。

詳細説明:

lsq_latt2.py スクリプトを動的に読み込み、その中の関数やクラスを 現在の実行コンテキストで利用できるようにします。

引数:

param path:

lsq_latt2.py スクリプトへのパス。

type path:

Path

戻り値:

returns:

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

rtype:

module

例外:

raises ImportError:

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

XRD.guess_lattice_parameters.inv_d2_from_two_theta(two_theta_deg: float, wavelength: float = 1.54056) → float

概要:

2θ角度からd間隔の二乗の逆数 (1 / d^2) を計算します。

詳細説明:

ブラッグの法則を用いてd間隔を計算し、その二乗の逆数を返します。

引数:

param two_theta_deg:

回折角度2θ（度）。

type two_theta_deg:

float

param wavelength:

X線波長（オングストローム）。デフォルトはCU_KA1です。

type wavelength:

float

戻り値:

returns:

d間隔の二乗の逆数（inv_d2）。

rtype:

float

XRD.guess_lattice_parameters.looks_like_raw_xrd_file(path: Path, min_rows: int = 50) → bool

概要:

ファイルが生のXRDデータファイルのように見えるかどうかをヒューリスティックに判断します。

詳細説明:

ファイルがピークリストではなく、高密度な生のXRD X-Yデータファイルであるかどうかを ヒューリスティックに判定します。 Excelファイルの場合、既知のピーク/推定シート名が含まれていないかを確認します。 ファイルの行数、列数、最初の数列に十分な数値データが含まれているかを確認します。 "two_theta_deg" のようなピークリスト特有の列名がないことも確認します。

引数:

param path:

ファイルパス。

type path:

Path

param min_rows:

生のXRDファイルと見なすための最小行数。

type min_rows:

int

戻り値:

returns:

ファイルが生のXRDデータファイルのように見える場合はTrue、そうでなければFalse。

rtype:

bool

XRD.guess_lattice_parameters.main() → int

概要:

スクリプトのメインエントリポイントです。

詳細説明:

コマンドライン引数を解析し、指定されたモード（search, guess, all, compare, calc）に基づいて 適切な処理関数を呼び出します。エラーが発生した場合は、エラーメッセージを標準エラー出力に表示します。

戻り値:

returns:

成功した場合は0、エラーの場合は非0の終了コード。

rtype:

int

例外:

raises SystemExit:

コマンドライン引数エラーや処理中の例外が発生した場合。

XRD.guess_lattice_parameters.normalize_mode(mode: str) → str

概要:

入力されたモード文字列を標準的なモード名に変換します。

詳細説明:

モード文字列から前後の空白を除去し、小文字に変換します。 スペルミス "seaerch" は "search" に修正され、古い "index" モードは "all" (search + guess) に変換されます。 サポートされていないモードが指定された場合はエラーを発生させます。

引数:

param mode:

入力されたモード文字列。

type mode:

str

戻り値:

returns:

標準化されたモード名。

rtype:

str

例外:

raises ValueError:

サポートされていないモードが指定された場合。

XRD.guess_lattice_parameters.params_from_beta(system: str, beta: ndarray) → dict[str, float]

概要:

最小二乗法の係数 (beta) から格子定数を計算します。

詳細説明:

inv_d2 = beta[0]*feat[0] + beta[1]*feat[1] + ... の形式で得られた 最小二乗法の係数 beta から、各結晶系に対応するa, b, c, alpha, beta, gammaの 格子定数を導出します。

引数:

param system:

結晶系名。

type system:

str

param beta:

最小二乗法で得られた係数のnumpy配列。

type beta:

numpy.ndarray

戻り値:

returns:

格子定数を含む辞書。

rtype:

dict[str, float]

例外:

raises ValueError:

サポートされていない結晶系が指定された場合。

XRD.guess_lattice_parameters.params_within_lattice_max(params: dict[str, float], system: str, lattice_max: float | None) → bool

概要:

格子定数セットが指定された上限値内に収まっているかを確認します。

詳細説明:

lattice_max がNoneでない場合、与えられた結晶系の主要な格子定数 (a, b, c) が lattice_max の値を超えていないかを検証します。

引数:

param params:

格子定数を含む辞書。

type params:

dict[str, float]

param system:

結晶系名。

type system:

str

param lattice_max:

格子定数の上限値（オングストローム）、またはNone。

type lattice_max:

float | None

戻り値:

returns:

全ての格子定数が上限値内であればTrue、そうでなければFalse。

rtype:

bool

XRD.guess_lattice_parameters.parse_crystal_systems(text: str) → list[str]

概要:

結晶系指定の文字列をパースし、サポートされている結晶系のリストを返します。

詳細説明:

カンマまたはセミコロンで区切られた結晶系名の文字列を処理します。 "auto" や "all" が指定された場合、全てのサポートされている結晶系 ("hexagonal", "orthorhombic", "tetragonal", "cubic") のリストを返します。エイリアスもサポートされます (例: "hex" -> "hexagonal")。 サポートされていない結晶系が指定された場合はエラーを発生させます。

引数:

param text:

結晶系指定の文字列。

type text:

str

戻り値:

returns:

サポートされている結晶系のリスト。

rtype:

list[str]

例外:

raises ValueError:

サポートされていない結晶系が指定された場合。

XRD.guess_lattice_parameters.peak_search_deriv3(x: ndarray, y: ndarray, nsmooth: int = 11, norder: int = 4, threshold: float = 1000.0, ydiff1_threshold: float = 0.01, fwhm_min_deg: float = 0.06, fwhm_max_deg: float = 1.0, is_print: bool = True) → tuple[list[Peak], dict[str, ndarray | float]]

概要:

Savitzky-Golayフィルターと3次導関数ゼロ交差法を用いてピークを探索します。

詳細説明:

入力X線回折データ (x, y) に対してSavitzky-Golayフィルターを適用し、 スムージングされたデータおよび1次、2次、3次導関数を計算します。 3次導関数のゼロ交差点をピーク候補点として抽出し、強度閾値、FWHM範囲、 2次導関数の符号などの基準でフィルタリングを行い、有効なピークを特定します。 重複するピークは強度に基づいてマージされます。

引数:

param x:

2θ角度のnumpy配列。

type x:

numpy.ndarray

param y:

強度のnumpy配列。

type y:

numpy.ndarray

param nsmooth:

Savitzky-Golayフィルターのウィンドウサイズ（奇数）。

type nsmooth:

int

param norder:

Savitzky-Golayフィルターの多項式の次数。

type norder:

int

param threshold:

ピーク強度の最小閾値。

type threshold:

float

param ydiff1_threshold:

1次導関数の相対閾値（診断用）。

type ydiff1_threshold:

float

param fwhm_min_deg:

許容されるFWHMの最小値（度）。

type fwhm_min_deg:

float

param fwhm_max_deg:

許容されるFWHMの最大値（度）。

type fwhm_max_deg:

float

param is_print:

診断情報をコンソールに出力するかどうか。

type is_print:

bool

戻り値:

returns:

検出されたPeakオブジェクトのリストと、スムージングデータや導関数などの診断情報の辞書。

rtype:

tuple[list[Peak], dict[str, numpy.ndarray | float]]

例外:

raises ValueError:

データポイントが不足している場合。

XRD.guess_lattice_parameters.peaks_to_frame(peaks: list[Peak]) → DataFrame

概要:

PeakオブジェクトのリストをPandasデータフレームに変換します。

詳細説明:

Peakオブジェクトの各属性をデータフレームの列にマッピングし、 各ピークに一意のID ("peak_id") を割り当てます。

引数:

param peaks:

Peakオブジェクトのリスト。

type peaks:

list[Peak]

戻り値:

returns:

Peak情報を含むPandasデータフレーム。

rtype:

pandas.DataFrame

XRD.guess_lattice_parameters.plot_compare_results(x: ndarray | None, y: ndarray | None, peaks: list[Peak], theoretical_df: DataFrame, assignment_df: DataFrame, candidate: Candidate, xmin: float, xmax: float, outpath: Path | None, show: bool = False, save: bool = True) → None

概要:

観測ピークと理論的な回折線の比較結果をプロットします。

詳細説明:

入力XRDデータ (x, y) があればそれをプロットし、観測されたピークを縦線で示します。 指定された格子定数候補に基づく理論的な回折線を、観測ピークの下部に棒グラフとして重ねて表示します。 理論線にはhkl指数が注釈され、マッチングされたものは強調されます。 グラフは画像ファイルとして保存でき、Matplotlibウィンドウに表示することも可能です。 mplcursorsがインストールされていれば、線にホバー注釈が表示されます。

引数:

param x:

2θ角度のnumpy配列（生のXRDデータ、オプション）。

type x:

numpy.ndarray | None

param y:

強度のnumpy配列（生のXRDデータ、オプション）。

type y:

numpy.ndarray | None

param peaks:

観測されたPeakオブジェクトのリスト。

type peaks:

list[Peak]

param theoretical_df:

理論的な回折線情報を含むPandasデータフレーム。

type theoretical_df:

pandas.DataFrame

param assignment_df:

観測ピークと理論線の割り当て結果データフレーム。

type assignment_df:

pandas.DataFrame

param candidate:

格子定数候補。

type candidate:

Candidate

param xmin:

プロットのX軸最小値（度）。

type xmin:

float

param xmax:

プロットのX軸最大値（度）。

type xmax:

float

param outpath:

プロットを保存するファイルパス（Noneの場合は保存しない）。

type outpath:

Path | None

param show:

プロットウィンドウを表示するかどうか。

type show:

bool

param save:

プロットをファイルに保存するかどうか。

type save:

bool

XRD.guess_lattice_parameters.plot_results(x: ndarray, y: ndarray, info: dict[str, ndarray | float], peaks: list[Peak], outpath: Path | None, show: bool = False, save: bool = True) → None

概要:

入力データ、スムージングされたデータ、検出されたピークをプロットします。

詳細説明:

生のXRDデータ (x, y) とスムージングされたデータ (info["ysmooth"]) を線グラフで表示し、 検出されたピークを縦線で示します。Kα2ピークは異なる色で強調表示されます。 グラフは画像ファイルとして保存でき、Matplotlibウィンドウに表示することも可能です。 mplcursorsがインストールされていれば、ピークの縦線にホバー注釈が表示されます。

引数:

param x:

2θ角度のnumpy配列。

type x:

numpy.ndarray

param y:

強度のnumpy配列。

type y:

numpy.ndarray

param info:

ピーク探索の診断情報を含む辞書（スムージングされたデータなど）。

type info:

dict[str, numpy.ndarray | float]

param peaks:

検出されたPeakオブジェクトのリスト。

type peaks:

list[Peak]

param outpath:

プロットを保存するファイルパス（Noneの場合は保存しない）。

type outpath:

Path | None

param show:

プロットウィンドウを表示するかどうか。

type show:

bool

param save:

プロットをファイルに保存するかどうか。

type save:

bool

XRD.guess_lattice_parameters.predicted_inv_d2(system: str, feat: Iterable[int], beta: ndarray) → float

概要:

結晶系、特徴量、最小二乗係数から予測されるd間隔の二乗の逆数 (inv_d2) を計算します。

詳細説明:

与えられた結晶系、hkl指数から導出される特徴量 feat、 および格子定数に相当する最小二乗係数 beta を用いて、 理論的な inv_d2 値を計算します。

引数:

param system:

結晶系名。

type system:

str

param feat:

hkl指数から導出される特徴量のイテラブル。

type feat:

Iterable[int]

param beta:

最小二乗法で得られた係数のnumpy配列。

type beta:

numpy.ndarray

戻り値:

returns:

予測されるinv_d2値。

rtype:

float

例外:

raises ValueError:

サポートされていない結晶系が指定された場合。

XRD.guess_lattice_parameters.print_peak_table(peaks: list[Peak], title: str) → None

概要:

ピーク情報を整形されたテーブル形式でコンソールに出力します。

詳細説明:

指定されたタイトルとともに、各ピークのID、2θ角度、強度、FWHM、Kα役割を 見やすい形式で標準出力に表示します。

引数:

param peaks:

Peakオブジェクトのリスト。

type peaks:

list[Peak]

param title:

テーブルのタイトル。

type title:

str

XRD.guess_lattice_parameters.read_candidate_from_guess_file(path: Path, rank: int) → Candidate

概要:

推定結果ファイルから特定の順位の格子定数候補を読み込みます。

詳細説明:

Excel形式の推定結果ファイルから "candidate_summary" シートを読み込み、 指定されたランク (rank) に対応する格子定数候補をCandidateオブジェクトとして返します。 ランクは1から始まります。

引数:

param path:

推定結果Excelファイルへのパス。

type path:

Path

param rank:

読み込む候補の順位（1から始まる）。

type rank:

int

戻り値:

returns:

指定された順位のCandidateオブジェクト。

rtype:

Candidate

例外:

raises ValueError:

Excelファイルでない場合、"candidate_summary" シートがない場合、 または指定されたランクの候補が見つからない場合。

XRD.guess_lattice_parameters.read_peaks_file(path: Path, wavelength: float = 1.54056) → list[Peak]

概要:

ピーク情報ファイルからPeakオブジェクトのリストを読み込みます。

詳細説明:

ExcelまたはCSV形式のピーク情報ファイルを読み込み、Pandasデータフレームとして扱います。 "two_theta_deg", "2theta", "inv_d2"などの一般的な列名から2θ角度またはinv_d2値を抽出し、 強度、FWHM、Kα役割などの情報をPeakオブジェクトに変換します。 ファイルにKα役割の割り当てがない場合は、assign_ka2関数を呼び出して割り当てを試みます。

引数:

param path:

ピーク情報ファイルへのパス。

type path:

Path

param wavelength:

X線波長（オングストローム）。デフォルトはCU_KA1です。

type wavelength:

float

戻り値:

returns:

読み込まれたPeakオブジェクトのリスト。

rtype:

list[Peak]

例外:

raises ValueError:

ファイルが空である場合、または回折角度の列が見つからない場合、 または利用可能なピークが見つからない場合。

XRD.guess_lattice_parameters.read_xy_data(path: Path) → tuple[ndarray, ndarray]

概要:

指定されたファイルからX-Yデータ（2θ-強度データ）を読み込みます。

詳細説明:

ファイルの種類（Excelまたはテキスト/CSV）を判別し、 最初の2列をそれぞれX（2θ）とY（強度）として読み込みます。 数値変換エラーや非有限値は除去され、X値でソートされます。

引数:

param path:

入力データファイルへのパス。

type path:

Path

戻り値:

returns:

X値のnumpy.ndarray、Y値のnumpy.ndarrayのタプル。

rtype:

tuple

例外:

raises ValueError:

スプレッドシートやテキストデータに必要な列数がない場合。

XRD.guess_lattice_parameters.refine_with_lsq(lsq_script: Path, candidate: Candidate, matched_rows: list[dict], wavelength: float = 1.54056)

概要:

最小二乗法 (lsq_latt2) を用いて格子定数を精密化します。

詳細説明:

外部スクリプト lsq_latt2.py をインポートし、与えられた格子定数候補 (candidate) と マッチングされた回折ピーク情報 (matched_rows) を使って、格子定数の最小二乗精密化を実行します。 精密化された格子定数と標準偏差、および各ピークの精密化結果を返します。

引数:

param lsq_script:

lsq_latt2.py スクリプトへのパス。

type lsq_script:

Path

param candidate:

精密化のベースとなる格子定数候補。

type candidate:

Candidate

param matched_rows:

マッチングされた回折ピークの情報のリスト。

type matched_rows:

list[dict]

param wavelength:

X線波長（オングストローム）。デフォルトはCU_KA1です。

type wavelength:

float

戻り値:

returns:

精密化された格子定数の要約辞書と、精密化されたマッチング結果のリストのタプル。 マッチングされた観測がない場合はNoneを返します。

rtype:

tuple[dict, list[dict]] | None

XRD.guess_lattice_parameters.resolve_lattice_max_limit(args: Namespace, peaks: list[Peak]) → float | None

概要:

格子定数推定に使用される格子定数の上限値を解決します。

詳細説明:

コマンドライン引数で --lattice-max が明示的に指定されている場合、その値を使用します。 指定がない場合、最も低角度の非Kα2ピークのd間隔に --lattice-max-factor を乗じて上限を推定します。 --lattice-max が0以下に設定されている場合、制限は無効化されます。

引数:

param args:

コマンドライン引数を格納したNamespaceオブジェクト。

type args:

argparse.Namespace

param peaks:

観測されたPeakオブジェクトのリスト。

type peaks:

list[Peak]

戻り値:

returns:

解決された格子定数上限値（オングストローム）、または制限が無効化されている場合はNone。

rtype:

float | None

例外:

raises ValueError:

--lattice-max-factor が正の値でない場合。

XRD.guess_lattice_parameters.resolve_mode_and_input(args: Namespace) → tuple[str, Path]

概要:

コマンドライン引数から実行モードと入力ファイルを解決します。

詳細説明:

位置指定引数 arg1 と arg2、および --mode オプションを解析し、 スクリプトの実行モードと主要な入力ファイルパスを決定します。 レガシーな位置指定モード ("search sample.TXT") にも対応しています。

引数:

param args:

コマンドライン引数を格納したNamespaceオブジェクト。

type args:

argparse.Namespace

戻り値:

returns:

(解決されたモード名, 入力ファイルパス) のタプル。

rtype:

tuple[str, Path]

例外:

raises SystemExit:

予期しない位置指定引数が指定された場合。

XRD.guess_lattice_parameters.run_compare(args: Namespace, infile: Path) → Path

概要:

比較モードまたは計算モードを実行します。

詳細説明:

観測されたピークと、指定された格子定数候補（推定ファイルから読み込むか、 コマンドライン引数で明示的に指定されたもの）を比較します。 観測ピークと理論的回折線をマッチングし、結果をコンソールに表示します。 また、結果のデータフレームとプロットをファイルに保存します。

引数:

param args:

コマンドライン引数を格納したNamespaceオブジェクト。

type args:

argparse.Namespace

param infile:

入力ファイルへのパス。

type infile:

Path

戻り値:

returns:

比較結果Excelファイルへのパス。

rtype:

Path

例外:

raises ValueError:

比較に利用可能なピークがない場合、 または候補が見つからない、またはランクが無効な場合。

XRD.guess_lattice_parameters.run_guess(args: Namespace, peak_file: Path, base_input: Path | None = None) → Path

概要:

格子定数推定モードを実行します。

詳細説明:

ピーク情報ファイル (peak_file) からピークを読み込み、指定された結晶系と 推定メソッド (args.method) に基づいて格子定数候補を推定します。 推定された候補はコンソールに表示され、最も良い候補に対しては lsq_latt2.py スクリプトを用いた精密化が試みられます。 結果はExcelワークブックとして保存されます。

引数:

param args:

コマンドライン引数を格納したNamespaceオブジェクト。

type args:

argparse.Namespace

param peak_file:

ピーク情報ファイルへのパス。

type peak_file:

Path

param base_input:

元の入力データファイルへのパス（オプション）。

type base_input:

Path | None

戻り値:

returns:

推定結果Excelファイルへのパス。

rtype:

Path

XRD.guess_lattice_parameters.run_search(args: Namespace, infile: Path) → tuple[list[Peak], Path, Path | None]

概要:

ピーク探索モードを実行します。

詳細説明:

入力XRDデータファイル (infile) を読み込み、ピーク探索アルゴリズム (peak_search_deriv3) を実行します。検出されたピークにKα2の役割を割り当て、結果をコンソールに表示します。 また、ピーク情報とプロットをファイルに保存します。

引数:

param args:

コマンドライン引数を格納したNamespaceオブジェクト。

type args:

argparse.Namespace

param infile:

入力データファイルへのパス。

type infile:

Path

戻り値:

returns:

(検出されたPeakオブジェクトのリスト, ピーク情報ファイルパス, プロットファイルパス) のタプル。

rtype:

tuple[list[Peak], Path, Path | None]

XRD.guess_lattice_parameters.sanitize_stem(text: str) → str

概要:

ファイル名として安全なステム文字列を生成します。

詳細説明:

入力された文字列から、ファイル名に使用できない特殊文字を除去し、 英数字、ハイフン、アンダースコア、ピリオドのみを含む文字列を返します。 連続するアンダースコアは1つにまとめられます。

引数:

param text:

処理する文字列。

type text:

str

戻り値:

returns:

サニタイズされたファイル名ステム。

rtype:

str

XRD.guess_lattice_parameters.save_workbook(path: Path, sheets: dict[str, DataFrame]) → None

概要:

複数のPandasデータフレームをExcelワークブックとして保存します。

詳細説明:

辞書で指定されたシート名とデータフレームのペアを、 OpenPyXLライブラリを使用して単一のExcelファイルに書き込みます。 各シートの最初の行は列ヘッダーとして太字で表示され、行が固定されます。 欠損値はExcelの空セルとして扱われます。

引数:

param path:

保存先のExcelファイルパス。

type path:

Path

param sheets:

シート名とPandasデータフレームの辞書。

type sheets:

dict[str, pandas.DataFrame]

XRD.guess_lattice_parameters.score_system(system: str, selected: list[Peak], all_peaks: list[Peak], hmax: int = 12) → Candidate | None

概要:

特定の結晶系に対して、観測ピークと理論的回折線を比較し、格子定数候補を評価します。

詳細説明:

この関数は、与えられた結晶系に対し、選択された観測ピーク (selected) を用いて 格子定数 (beta) を最小二乗法で推定します。 システム行 (system_rows) から特徴量行列を構築し、観測された inv_d2 値との 組み合わせでbetaを求めます。 beta値が正である組み合わせの中から、マッチするピークの数と相対RMS誤差を スコアとして最適な候補を選定します。 全ての観測ピーク (all_peaks) に対するマッチング情報も生成します。

引数:

param system:

結晶系名。

type system:

str

param selected:

格子定数推定に使用する、フィルタリングされたPeakオブジェクトのリスト。

type selected:

list[Peak]

param all_peaks:

全ての観測されたPeakオブジェクトのリスト。

type all_peaks:

list[Peak]

param hmax:

h, k, l指数の最大値。

type hmax:

int

戻り値:

returns:

最適な格子定数候補を表すCandidateオブジェクト、または見つからない場合はNone。

rtype:

Candidate | None

XRD.guess_lattice_parameters.score_system_grid(system: str, selected: list[Peak], all_peaks: list[Peak], ranges: dict[str, tuple[float, float, float]], hmax: int = 12, wavelength: float = 1.54056, tolerance_deg: float = 0.25, refine: int = 2, keep: int = 50, penalty_unassigned: float = 0.5, lattice_max: float | None = None) → list[Candidate]

概要:

グリッド検索法を用いて特定の結晶系の格子定数候補を評価します。

詳細説明:

指定された結晶系 (system) の格子定数範囲 (ranges) 内でグリッド検索を行い、 各格子定数セットに対して観測ピーク (selected) を割り当てて評価します。 割り当てられたピークから格子定数を繰り返し再フィット (refine回) し、 最もフィットの良い候補を絞り込みます。 未割り当てピークに対するペナルティ (penalty_unassigned) を適用し、 結果はスコアに基づいてソートされ、指定された数 (keep) の上位候補が返されます。 格子定数上限 (lattice_max) も考慮されます。

引数:

param system:

結晶系名。

type system:

str

param selected:

格子定数推定に使用する、フィルタリングされたPeakオブジェクトのリスト。

type selected:

list[Peak]

param all_peaks:

全ての観測されたPeakオブジェクトのリスト。

type all_peaks:

list[Peak]

param ranges:

各格子定数（a, b, c）の (最小値, 最大値, ステップ) を含む辞書。

type ranges:

dict[str, tuple[float, float, float]]

param hmax:

h, k, l指数の最大値。

type hmax:

int

param wavelength:

X線波長（オングストローム）。デフォルトはCU_KA1です。

type wavelength:

float

param tolerance_deg:

2θ角度の割り当て許容誤差（度）。

type tolerance_deg:

float

param refine:

グリッド検索での割り当てと再フィットの反復回数。

type refine:

int

param keep:

内部的に保持する候補の最大数。

type keep:

int

param penalty_unassigned:

未割り当てピークに対するペナルティスコア。

type penalty_unassigned:

float

param lattice_max:

格子定数の上限値（オングストローム）、またはNone。

type lattice_max:

float | None

戻り値:

returns:

評価され、ソートされたCandidateオブジェクトのリスト。

rtype:

list[Candidate]

XRD.guess_lattice_parameters.strip_peak_suffix(stem: str) → str

概要:

ファイル名のステムからピーク関連のサフィックスを除去します。

詳細説明:

ファイル名のステム (例: "sample-peaks") から、"-peaks", "_peaks", ".peaks", "-peak", "_peak" などのサフィックスを除去した文字列を返します。

引数:

param stem:

ファイル名のステム文字列。

type stem:

str

戻り値:

returns:

サフィックスが除去されたステム文字列。

rtype:

str

XRD.guess_lattice_parameters.system_rows(system: str, hmax: int = 12) → list[tuple[tuple[int, ...], tuple[int, int, int]]]

概要:

指定された結晶系とhkl指数に対して、格子定数計算のための特徴量とhklの組み合わせを生成します。

詳細説明:

立方晶、正方晶、六方晶、斜方晶の各結晶系について、hmaxまでのhkl指数を生成します。 各hkl組み合わせに対して、inv_d2 (1 / d^2) の計算に必要な特徴量タプル (feat) と、 実際のhkl指数タプルをペアとしてリストに格納します。 重複する特徴量を持つ組み合わせは除外され、特徴量の合計値でソートされます。

引数:

param system:

結晶系名（例: "cubic", "hexagonal"）。

type system:

str

param hmax:

h, k, l指数の最大値。

type hmax:

int

戻り値:

returns:

(特徴量タプル, hklタプル) のリスト。

rtype:

list[tuple[tuple[int, ...], tuple[int, int, int]]]

例外:

raises ValueError:

サポートされていない結晶系が指定された場合。

XRD.guess_lattice_parameters.theoretical_lines_for_candidate(candidate: Candidate, hmax: int = 12, wavelength: float = 1.54056, xmin: float | None = None, xmax: float | None = None) → DataFrame

概要:

指定された格子定数候補に基づいて理論的な回折線を計算します。

詳細説明:

Candidateオブジェクトの格子定数とhmaxで定義されるhkl指数範囲を用いて、 それぞれのhklに対する理論的な2θ角度、d間隔、inv_d2値を計算します。 結果はPandasデータフレームとして返され、オプションで2θ範囲 (xmin, xmax) でフィルタリングされます。

引数:

param candidate:

格子定数候補。

type candidate:

Candidate

param hmax:

h, k, l指数の最大値。

type hmax:

int

param wavelength:

X線波長（オングストローム）。デフォルトはCU_KA1です。

type wavelength:

float

param xmin:

最小2θ角度（度）のフィルタリング閾値（オプション）。

type xmin:

float | None

param xmax:

最大2θ角度（度）のフィルタリング閾値（オプション）。

type xmax:

float | None

戻り値:

returns:

理論的な回折線情報を含むPandasデータフレーム。

rtype:

pandas.DataFrame

XRD.guess_lattice_parameters.try_read_raw_xy_for_plot(path: Path) → tuple[ndarray | None, ndarray | None]

概要:

プロットのために生のX-Yデータを読み込みを試みます。

詳細説明:

指定されたファイルがピーク情報や推定結果のExcelワークブックでないことを確認し、 そうであれば read_xy_data を使って生のX-Yデータを読み込みます。 読み込みに失敗した場合や、ファイルが特定のワークブックである場合はNoneを返します。

引数:

param path:

データファイルへのパス。

type path:

Path

戻り値:

returns:

(Xデータnumpy配列, Yデータnumpy配列) のタプル、 または読み込みに失敗した場合は (None, None)。

rtype:

tuple[numpy.ndarray | None, numpy.ndarray | None]

XRD.guess_lattice_parameters.two_theta_from_d(d: float, wavelength: float = 1.54056) → float | None

概要:

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

詳細説明:

ブラッグの法則を逆算して、指定されたd間隔とX線波長に対応する回折角度2θを計算します。 2 * d * sin(theta) = wavelength の関係を使用します。

引数:

param d:

d間隔（オングストローム）。

type d:

float

param wavelength:

X線波長（オングストローム）。デフォルトはCU_KA1です。

type wavelength:

float

戻り値:

returns:

計算された2θ角度（度）、または回折が物理的に不可能な場合はNone。

rtype:

float | None

XRD.guess_lattice_parameters.two_theta_from_inv_d2(inv_d2: float, wavelength: float = 1.54056) → float | None

概要:

d間隔の二乗の逆数 (1 / d^2) から2θ角度を計算します。

詳細説明:

inv_d2値からd間隔を計算し、そのd間隔とX線波長に対応する2θ角度を返します。

引数:

param inv_d2:

d間隔の二乗の逆数。

type inv_d2:

float

param wavelength:

X線波長（オングストローム）。デフォルトはCU_KA1です。

type wavelength:

float

戻り値:

returns:

計算された2θ角度（度）、または計算が不可能な場合はNone。

rtype:

float | None