lsq_latt2 プログラム仕様

最小二乗法を用いた格子定数計算スクリプト。

このスクリプトは、X線回折データなどの回折データから結晶の格子定数を導出します。 様々な格子系に対応し、観測データの前処理、重み付け、最小二乗フィッティング、 そして最終的な格子定数（逆格子および実格子）の導出を行います。 外れ値の自動除去機能も備えています。

詳細説明: 入力ファイルは特定のフォーマットに従い、複数の計算ジョブを連続して処理できます。 各ジョブでは、格子系、補正フラグ、重み付けモード、回折位置の変換モードなどが 設定され、それに従って観測データが処理されます。 重み付き最小二乗法によりパラメータが決定され、その結果から逆格子定数と実格子定数、 およびそれらの標準偏差が計算されます。計算結果は整形されたレポートファイルとして出力されます。

関連リンク: 使用方法

class XRD.lsq_latt2.CellConstants(reciprocal_lengths: ndarray = <factory>, reciprocal_length_sigma: ndarray = <factory>, reciprocal_angles_deg: ndarray = <factory>, reciprocal_angle_sigma_deg: ndarray = <factory>, reciprocal_cosines: ndarray = <factory>, reciprocal_cosine_sigma: ndarray = <factory>, reciprocal_volume: float = 0.0, reciprocal_volume_sigma: float = 0.0, direct_lengths: ndarray = <factory>, direct_length_sigma: ndarray = <factory>, direct_angles_deg: ndarray = <factory>, direct_angle_sigma_deg: ndarray = <factory>, direct_cosines: ndarray = <factory>, direct_cosine_sigma: ndarray = <factory>, direct_volume: float = 0.0, direct_volume_sigma: float = 0.0)

ベースクラス: object

格子定数（逆格子および実格子）を保持するデータクラス。

詳細説明: 逆格子と実格子の両方について、長さ、角度（度数）、コサイン、 体積およびそれぞれの標準偏差を格納します。 デフォルト値としてゼロまたは標準的な値（角度90度）が設定されています。

パラメータ:

• reciprocal_lengths -- np.ndarray: 逆格子の長さ (a*, b*, c*) の配列。デフォルトは全て0.0。

• reciprocal_length_sigma -- np.ndarray: 逆格子の長さの標準偏差の配列。デフォルトは全て0.0。

• reciprocal_angles_deg -- np.ndarray: 逆格子の角度 (alpha*, beta*, gamma*) の配列（度数）。デフォルトは全て90.0。

• reciprocal_angle_sigma_deg -- np.ndarray: 逆格子の角度の標準偏差の配列（度数）。デフォルトは全て0.0。

• reciprocal_cosines -- np.ndarray: 逆格子の角度のコサイン (cos(alpha*), cos(beta*), cos(gamma*)) の配列。デフォルトは全て0.0。

• reciprocal_cosine_sigma -- np.ndarray: 逆格子の角度のコサインの標準偏差の配列。デフォルトは全て0.0。

• reciprocal_volume -- float: 逆格子の体積。デフォルトは0.0。

• reciprocal_volume_sigma -- float: 逆格子の体積の標準偏差。デフォルトは0.0。

• direct_lengths -- np.ndarray: 実格子の長さ (a, b, c) の配列。デフォルトは全て0.0。

• direct_length_sigma -- np.ndarray: 実格子の長さの標準偏差の配列。デフォルトは全て0.0。

• direct_angles_deg -- np.ndarray: 実格子の角度 (alpha, beta, gamma) の配列（度数）。デフォルトは全て90.0。

• direct_angle_sigma_deg -- np.ndarray: 実格子の角度の標準偏差の配列（度数）。デフォルトは全て0.0。

• direct_cosines -- np.ndarray: 実格子の角度のコサイン (cos(alpha), cos(beta), cos(gamma)) の配列。デフォルトは全て0.0。

• direct_cosine_sigma -- np.ndarray: 実格子の角度のコサインの標準偏差の配列。デフォルトは全て0.0。

• direct_volume -- float: 実格子の体積。デフォルトは0.0。

• direct_volume_sigma -- float: 実格子の体積の標準偏差。デフォルトは0.0。

direct_angle_sigma_deg: ndarray

direct_angles_deg: ndarray

direct_cosine_sigma: ndarray

direct_cosines: ndarray

direct_length_sigma: ndarray

direct_lengths: ndarray

direct_volume: float

direct_volume_sigma: float

reciprocal_angle_sigma_deg: ndarray

reciprocal_angles_deg: ndarray

reciprocal_cosine_sigma: ndarray

reciprocal_cosines: ndarray

reciprocal_length_sigma: ndarray

reciprocal_lengths: ndarray

reciprocal_volume: float

reciprocal_volume_sigma: float

class XRD.lsq_latt2.JobConfig(lattice_system: int, correction_flags: list[int], weight_mode: int, position_mode: int, profile_mode: int)

ベースクラス: object

格子定数計算ジョブの設定を保持するデータクラス。

詳細説明: このクラスは、計算に使用する格子系の種類、適用する補正の種類、 観測データの重み付け方法、回折位置の変換方法、およびプロファイルモードの 設定情報をカプセル化します。

パラメータ:

• lattice_system -- int: 格子系の種類を示す整数コード（例: 1=三斜晶, 4=直方晶など）。

• correction_flags -- list[int]: 5つの補正フラグのリスト。各フラグは特定の補正の適用有無を示す。

• weight_mode -- int: 観測データに適用する重み付けモード。

• position_mode -- int: 生の回折位置データを変換するモード。

• profile_mode -- int: プロファイル分析モード（このコードでは未使用だが、入力形式の一部）。

correction_flags: list[int]

lattice_system: int

position_mode: int

profile_mode: int

weight_mode: int

class XRD.lsq_latt2.JobData(title: str, config: JobConfig, observations: list[Observation], reference_wavelength: float)

ベースクラス: object

一つの格子定数計算ジョブに関する全てのデータを保持するデータクラス。

詳細説明: ジョブのタイトル、設定、処理する観測データのリスト、および 参照として使用される波長を含みます。

パラメータ:

• title -- str: ジョブのタイトル。

• config -- JobConfig: このジョブの設定情報。

• observations -- list[Observation]: このジョブで処理される観測データのリスト。

• reference_wavelength -- float: このジョブの参照波長。

config: JobConfig

observations: list[Observation]

reference_wavelength: float

title: str

exception XRD.lsq_latt2.LatticeCalculationError

ベースクラス: RuntimeError

格子定数計算におけるエラーを示す例外。

詳細説明: この例外は、入力データが無効な場合、または最小二乗問題の解決中に 計算上の問題（例: 特異行列）が発生した場合に発生します。

class XRD.lsq_latt2.LeastSquaresResult(parameters: ~numpy.ndarray, parameter_sigma: ~numpy.ndarray, fitted_y: ~numpy.ndarray, residuals: ~numpy.ndarray, observation_sigma: ~numpy.ndarray, kept_observations: list[~XRD.lsq_latt2.Observation], covariance: ~numpy.ndarray, rejected_observations: list[~XRD.lsq_latt2.Observation] = <factory>)

ベースクラス: object

最小二乗法の結果を保持するデータクラス。

詳細説明: このクラスは、最小二乗法によって計算されたパラメータ、それらの標準偏差、 フィットされたy値、残差、観測の標準偏差、および使用された観測データなどを 格納します。外れ値として除外された観測データも追跡されます。

パラメータ:

• parameters -- np.ndarray: フィットされたパラメータの配列。

• parameter_sigma -- np.ndarray: 各パラメータの標準偏差の配列。

• fitted_y -- np.ndarray: フィットモデルによって計算されたy値の配列。

• residuals -- np.ndarray: 実測y値とフィットされたy値の残差の配列。

• observation_sigma -- np.ndarray: 各観測の標準偏差の配列。

• kept_observations -- list[Observation]: 最小二乗法に使用された観測データのリスト。

• covariance -- np.ndarray: パラメータの共分散行列。

• rejected_observations -- list[Observation]: 外れ値として除外された観測データのリスト。デフォルトは空のリスト。

covariance: ndarray

fitted_y: ndarray

kept_observations: list[Observation]

observation_sigma: ndarray

parameter_sigma: ndarray

parameters: ndarray

rejected_observations: list[Observation]

residuals: ndarray

class XRD.lsq_latt2.LineReader(stream: TextIO)

ベースクラス: object

テキストストリームから行を読み込むためのヘルパークラス。

詳細説明: このクラスは、テキストファイルを一行ずつ読み込み、現在の行番号を追跡し、 ファイルの予期せぬ終端を検出する機能を提供します。 空行でない行を確実に読み込むためのメソッドも備えています。

パラメータ:

stream -- TextIO: 読み込むテキストストリーム。

read_line(*, allow_eof: bool = False) → str | None

ストリームから一行を読み込む。

詳細説明: ファイルの終端に達した場合、allow_eof が True であれば None を返します。 False の場合は EOFError を発生させます。読み込んだ行末の改行文字は除去されます。

パラメータ:

allow_eof -- bool: Trueの場合、ファイルの終端に達してもEOFErrorを発生させず、Noneを返す。デフォルトはFalse。

戻り値:

str | None: 読み込まれた行（末尾の改行文字は除去）。EOFでallow_eofがTrueの場合はNone。

例外:

EOFError -- `allow_eof`がFalseのときに、ファイルの予期せぬ終端に達した場合。

read_nonempty_line() → str

ストリームから空でない行を読み込む。

詳細説明: 空行をスキップし、最初に見つかった空でない行を返します。 ファイルの終端に達した場合は EOFError を発生させます。

戻り値:

str: 読み込まれた空でない行（末尾の改行文字は除去）。

例外:

• EOFError -- ファイルの終端に達した場合。

• AssertionError -- 読み込まれた行がNoneであった場合 (内部的なガード)。

class XRD.lsq_latt2.Observation(serial_index: int, h: int, k: int, l: int, raw_position: float, transformed_position: float, weight: float, design_row: ndarray, wavelength: float)

ベースクラス: object

一つの回折観測データを保持するデータクラス。

詳細説明: このクラスは、特定の回折面(hkl)に対応する生の回折位置、変換された位置、 計算で使用される重み、デザイン行列の行、および観測時の波長などの 詳細な情報を含みます。

パラメータ:

• serial_index -- int: 観測データの通し番号。

• h -- int: ミラー指数 h。

• k -- int: ミラー指数 k。

• l -- int: ミラー指数 l。

• raw_position -- float: 生の回折位置データ。

• transformed_position -- float: 変換された回折位置データ（最小二乗法に使用）。

• weight -- float: この観測データに対する重み。

• design_row -- np.ndarray: この観測データに対応するデザイン行列の行。

• wavelength -- float: この観測で使用されたX線の波長。

design_row: ndarray

h: int

k: int

l: int

raw_position: float

serial_index: int

transformed_position: float

wavelength: float

weight: float

class XRD.lsq_latt2.SigmaPropagator(values: Iterable[float], sigmas: Iterable[float])

ベースクラス: object

誤差伝播の計算を行うクラス。

詳細説明: このクラスは、複数の入力値とそれぞれの標準偏差が与えられたときに、 それらの入力値に依存する関数が返す値とその標準偏差を、 数値微分（摂動法）を用いて計算します。

パラメータ:

• values -- Iterable[float]: 関数に渡す入力値のシーケンス。

• sigmas -- Iterable[float]: 各入力値の標準偏差のシーケンス。

evaluate(func: Callable[[ndarray], float]) → tuple[float, float]

与えられた関数を評価し、その値と標準偏差を計算する。

詳細説明: 入力値の各要素を微小に摂動させ、その変化から数値微分を計算します。 これらの数値微分と各入力値の標準偏差を用いて、誤差伝播の法則により 関数の結果の標準偏差を導出します。

パラメータ:

func -- Callable[[np.ndarray], float]: 誤差伝播を計算する関数。 NumPy配列を受け取り、単一のfloatを返す必要があります。

戻り値:

tuple[float, float]: 関数の評価値と、その標準偏差のタプル。

class XRD.lsq_latt2.TeeStream(*streams: TextIO)

ベースクラス: object

ファイルとコンソールへ同時に書き込む簡易ストリーム。

詳細説明: このクラスは、複数の TextIO ストリーム（例: ファイルオブジェクトと sys.stdout）をラップし、 write メソッドが呼び出された際に、登録された全てのストリームにテキストを転送します。 これにより、計算結果をファイルに保存しつつ、同時にコンソールにも表示することができます。

パラメータ:

streams -- TextIO: 書き込み先の TextIO ストリームを可変長引数で指定。

flush() → None

全ての登録ストリームをフラッシュする。

詳細説明: 登録された全ての TextIO ストリームの flush メソッドを呼び出し、 バッファリングされたデータを強制的に出力します。

write(text: str) → int

全ての登録ストリームにテキストを書き込む。

詳細説明: write メソッドが呼び出されると、登録された全ての TextIO ストリームに対して 引数 text を書き込みます。また、各ストリームの flush メソッドも呼び出されます。

パラメータ:

text -- str: 書き込むテキスト。

戻り値:

int: 書き込まれた文字数 (入力 text の長さ)。

XRD.lsq_latt2.acos_deg(cosine: float) → float

コサイン値から角度を度数で計算する。

詳細説明: 入力されたコサイン値が有効な範囲 [-1, 1] 内にあることを保証するために、 clamp_unit 関数で値をクランプしてから math.acos を適用します。 結果はラジアンから度数に変換されます。

パラメータ:

cosine -- float: コサイン値。

戻り値:

float: 度数で表された角度。

XRD.lsq_latt2.base_design_terms(h: int, k: int, l: int) → ndarray

回折指数 (h, k, l) からデザイン行列の基本的な項を計算する。

詳細説明: 格子定数計算におけるデザイン行列を構築するための基本要素として、 h^2, k^2, l^2, 2kl, 2lh, 2hk の6つの項を計算します。 これらの項は、一般的な三斜晶系を含む様々な格子系のデザイン行列の基礎となります。

パラメータ:

• h -- int: ミラー指数h。

• k -- int: ミラー指数k。

• l -- int: ミラー指数l。

戻り値:

np.ndarray: 6つのデザイン行列項を含むNumPy配列。

XRD.lsq_latt2.build_argument_parser() → ArgumentParser

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

戻り値:

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

XRD.lsq_latt2.calc_fit_statistics(fit: LeastSquaresResult) → tuple[float, float, int]

フィットの統計情報（重み付き残差二乗和、RMS残差、自由度）を計算する。

パラメータ:

fit -- LeastSquaresResult: 最小二乗法のフィット結果。

戻り値:

tuple[float, float, int]: 重み付き残差二乗和、RMS残差、自由度のタプル。

XRD.lsq_latt2.calc_weight(weight_mode: int, transformed: float, sigma_or_weight: float | None) → float

指定された重みモードと変換された位置データに基づいて観測の重みを計算する。

詳細説明: 最小二乗法では、各観測データの信頼度に応じて重みを設定することで、 より信頼性の高いデータに大きな影響を与えることができます。 この関数は、異なる重み付けスキーム（一定、測定誤差に基づくなど）を実装しています。

重みモードの種類: - 0: シグマ・シータに基づく重み。transformed_positionがsin(theta)である場合、1/(sigma_theta^2 * 4 * sin^2(theta) * cos^2(theta)) に比例。 - 1: シグマ・ツーシータに基づく重み。transformed_positionがsin(theta)である場合、1/(sigma_2theta^2 * 4 * sin^2(theta) * cos^2(theta)) に比例。 - 2: 一定の重み (1.0)。 - 3: 直接指定された重み。 - 4: シグマ値の逆二乗に基づく重み (1/sigma^2)。

パラメータ:

• weight_mode -- int: 重み計算モード（0-4）。

• transformed -- float: 変換された回折位置データ（通常はsin(θ)）。

• sigma_or_weight -- float | None: モードによって、回折角度の標準偏差または直接指定される重み値。Noneの場合もある。

戻り値:

float: 計算された観測の重み。

例外:

LatticeCalculationError -- 重みモードに必要な追加データが提供されない場合。

XRD.lsq_latt2.clamp_unit(x: float) → float

値を -1.0 から 1.0 の範囲にクランプする。

詳細説明: 主に math.acos の引数が有効な範囲内にあることを保証するために使用されます。 入力値が -1.0 未満であれば -1.0 に、1.0 を超えれば 1.0 に丸めます。

パラメータ:

x -- float: クランプする値。

戻り値:

float: -1.0 から 1.0 の範囲にクランプされた値。

XRD.lsq_latt2.correction_metadata() → list[dict[str, str]]

補正項に関するメタデータ（名前、式、説明）のリストを返す。

詳細説明: 5種類の補正項それぞれについて、その名称、計算式、および物理的な意味に関する 暫定的な解釈を英語と日本語で提供します。ユーザーが解釈を確認する責任があります。

戻り値:

list[dict[str, str]]: 補正項のメタデータ辞書のリスト。

XRD.lsq_latt2.correction_terms(flags: list[int], transformed: float) → list[float]

指定された補正フラグと変換された位置データに基づいて補正項を計算する。

詳細説明: 回折データの測定には、様々な系統誤差（例:吸収、分極、ローレンツ因子など） が影響を与える可能性があります。この関数は、これらの誤差を補正するための 特定の補正項を計算し、最小二乗法のデザイン行列に追加できるようにします。 transformed は通常 sin(θ) に対応します。

パラメータ:

• flags -- list[int]: 5つの補正フラグのリスト。各フラグは特定の補正の有無を示す（0:なし、1:あり）。

• transformed -- float: 変換された回折位置データ（通常はsin(θ)）。

戻り値:

list[float]: 計算された補正項のリスト。

XRD.lsq_latt2.derive_cell_constants(lattice_system: int, params: ndarray, sigma: ndarray) → CellConstants

最小二乗法で得られたパラメータから逆格子および実格子の定数を導出する。

詳細説明: 最小二乗法によって決定された格子パラメータとそれらの標準偏差を受け取り、 指定された格子系の結晶学的な関係に基づいて、最終的な逆格子定数 (a*, b*, c*, alpha*, beta*, gamma*, V*) および実格子定数 (a, b, c, alpha, beta, gamma, V) を計算します。 各定数に対して誤差伝播法を用いて標準偏差も同時に計算されます。

パラメータ:

• lattice_system -- int: 格子系の種類を示す整数コード（1-8）。

• params -- np.ndarray: 最小二乗法で得られたパラメータの配列。

• sigma -- np.ndarray: パラメータの標準偏差の配列。

戻り値:

CellConstants: 導出された格子定数を含むオブジェクト。

例外:

LatticeCalculationError -- 未対応の格子系が指定された場合。

XRD.lsq_latt2.direct_cosine_from_reciprocal(values: ndarray) → float

逆格子のコサイン値から実格子のコサイン値を計算する。

詳細説明: 逆格子の角度 (alpha*, beta*, gamma*) のコサイン値から、 対応する実格子の角度 (alpha, beta, gamma) のコサイン値を導出します。 例えば、実格子の cos(alpha) は逆格子の cos(alpha*), cos(beta*), cos(gamma*) から計算されます。

パラメータ:

values -- np.ndarray: (cos_alpha_star, cos_beta_star, cos_gamma_star) を含むNumPy配列。

戻り値:

float: 対応する実格子のコサイン値。

XRD.lsq_latt2.direct_length_from_reciprocal(values: ndarray) → float

逆格子の長さとコサイン値から実格子の長さを計算する。

詳細説明: 逆格子定数 (a*, cos_alpha*, cos_beta*, cos_gamma*) から、 対応する実格子の長さ (a) を導出します。 例: 実格子の長さaは、逆格子のa*, cos(alpha*), cos(beta*), cos(gamma*) から計算されます。

パラメータ:

values -- np.ndarray: (a_star, cos_alpha_star, cos_beta_star, cos_gamma_star) を含むNumPy配列。

戻り値:

float: 対応する実格子の長さ。

XRD.lsq_latt2.direct_volume_from_reciprocal(values: ndarray) → float

逆格子の長さとコサイン値から実格子の体積を計算する。

詳細説明: 逆格子定数 (a*, b*, c*, cos_alpha*, cos_beta*, cos_gamma*) から 実格子の体積を導出します。実格子の体積は逆格子の体積の逆数です。

パラメータ:

values -- np.ndarray: (a_star, b_star, c_star, cos_alpha_star, cos_beta_star, cos_gamma_star) を含むNumPy配列。

戻り値:

float: 実格子の体積。

XRD.lsq_latt2.format_value_sigma(value: float, sigma: float, *, width: int = 14, prec: int = 7) → str

値と標準偏差を指定された書式で整形した文字列を生成する。

詳細説明: value と sigma を指定された桁数 (width) と精度 (prec) でフォーマットし、 "値 ± 標準偏差" の形式で返します。

パラメータ:

• value -- float: フォーマットする値。

• sigma -- float: フォーマットする標準偏差。

• width -- int: 数値部分の全体の幅。デフォルトは14。

• prec -- int: 小数点以下の精度。デフォルトは7。

戻り値:

str: 整形された文字列。

XRD.lsq_latt2.lattice_design_row(lattice_system: int, h: int, k: int, l: int) → ndarray

指定された格子系とミラー指数に基づいて、デザイン行列の行を構築する。

詳細説明: 各格子系（三斜晶、単斜晶、直方晶、正方晶、六方晶、立方晶、菱面体晶）は、 結晶学的に異なる格子定数の制約を持ちます。この関数は、その制約に基づいて、 base_design_terms から必要な項を選択・結合し、デザイン行列の1行を生成します。

格子系のコードと対応するパラメータ: - 1: 三斜晶 (triclinic): a*^2, b*^2, c*^2, 2b*c*cos(alpha*), 2c*a*cos(beta*), 2a*b*cos(gamma*) - 2: 単斜晶 (monoclinic, unique b): a*^2, b*^2, c*^2, 2c*a*cos(beta*) - 3: 単斜晶 (monoclinic, unique c): a*^2, b*^2, c*^2, 2a*b*cos(gamma*) (※コードではgamma*として実装されているが、入力形式によってはalpha*を意味する場合もある) - 4: 直方晶 (orthorhombic): a*^2, b*^2, c*^2 - 5: 正方晶 (tetragonal): a*^2, c*^2 (a*=b*, alpha*=beta*=gamma*=90deg) - 6: 立方晶 (cubic): a*^2 (a*=b*=c*, alpha*=beta*=gamma*=90deg) - 7: 菱面体晶 (rhombohedral, trigonal): a*^2+b*^2+c*^2, 2(kl+lh+hk) (a*=b*=c*, alpha*=beta*=gamma*) - 8: 六方晶 (hexagonal): a*^2, c*^2 (a*=b*, alpha*=beta*=90deg, gamma*=120deg)

パラメータ:

• lattice_system -- int: 格子系の種類を示す整数コード（1-8）。

• h -- int: ミラー指数h。

• k -- int: ミラー指数k。

• l -- int: ミラー指数l。

戻り値:

np.ndarray: 指定された格子系のデザイン行列の行。

例外:

LatticeCalculationError -- 未対応の格子系が指定された場合。

XRD.lsq_latt2.lattice_parameter_labels(lattice_system: int) → list[str]

指定された格子系の最小二乗フィットパラメータに対応するラベルのリストを返す。

詳細説明: 各格子系における結晶学的な制約に基づいて、フィットされたパラメータが何を表すかを 示す適切なラベル（例: "a*^2", "2 c* a* cos(beta*)"）を提供します。

パラメータ:

lattice_system -- int: 格子系の種類を示す整数コード。

戻り値:

list[str]: パラメータラベルのリスト。

XRD.lsq_latt2.lattice_system_name(code: int) → str

格子系のコードに対応する名前を日本語と英語で返す。

パラメータ:

code -- int: 格子系の整数コード。

戻り値:

str: 格子系の名前（例: "Triclinic / 三斜晶"）。

XRD.lsq_latt2.main() → int

スクリプトのエントリポイント。

詳細説明: コマンドライン引数を解析し、入力ファイルから格子定数計算ジョブを読み込みます。 各ジョブに対して重み付き最小二乗法を実行し、格子定数を導出します。 計算結果はレポートファイルとコンソールに表示され、各ジョブのプロットも生成・保存されます。

戻り値:

int: プログラムの終了コード。成功時は0。

XRD.lsq_latt2.make_default_output_path(input_path: Path) → Path

出力ファイルが未指定の場合、入力ファイルの拡張子を .out に置き換えたパスを生成する。

パラメータ:

input_path -- Path: 入力ファイルのパス。

戻り値:

Path: 生成された出力ファイルのパス。

XRD.lsq_latt2.mode_description_position(mode: int) → str

位置変換モードのコードに対応する説明を返す。

パラメータ:

mode -- int: 位置変換モードの整数コード。

戻り値:

str: モードの説明文字列。

XRD.lsq_latt2.mode_description_weight(mode: int) → str

重み付けモードのコードに対応する説明を返す。

パラメータ:

mode -- int: 重み付けモードの整数コード。

戻り値:

str: モードの説明文字列。

XRD.lsq_latt2.parameter_blocks(job: JobData, fit: LeastSquaresResult) → tuple[list[tuple[str, float, float]], list[tuple[str, float, float]]]

フィットされたパラメータを格子定数関連と補正項関連の2つのブロックに分割して返す。

詳細説明: 最小二乗法でフィットされた全パラメータを、格子系に特有のパラメータと、 有効化された補正項の係数とに分類し、それぞれのラベル、値、標準偏差の タプルリストとして返します。

パラメータ:

• job -- JobData: 現在の計算ジョブのデータ。

• fit -- LeastSquaresResult: 最小二乗法のフィット結果。

戻り値:

tuple[list[tuple[str, float, float]], list[tuple[str, float, float]]]: 格子パラメータのリストと補正項係数のリストのタプル。

XRD.lsq_latt2.parse_jobs(stream: TextIO) → list[JobData]

入力ストリームから複数の格子定数計算ジョブを解析する。

詳細説明: 入力ファイルは、一連の計算ジョブで構成されます。各ジョブはタイトル、 計算設定、および複数の回折観測データを含みます。この関数は、 ストリームの終端に達するか、特定の終了コード（h=1000`で次のジョブ、`job_code=0`で全体終了） が読み込まれるまで、ジョブを順次解析して `JobData オブジェクトのリストを生成します。

入力ファイルの主要なセクション: 1. ジョブタイトル 2. ジョブ設定パラメータ（格子系、補正フラグ、モードなど） 3. 波長と装置半径 4. 回折観測データのブロック (h k l raw_position)

• (position_mode=3の場合) zero_shift

• (weight_mode in {0,1,3,4}の場合) sigma_or_weight

• 特殊行: 2000 wavelength radius で波長と半径を更新

• 特殊行: 1000 ... で現在のジョブの終了を示す

5. ジョブ終了コード (0: 全体の終了, 1: 次のジョブへ)

パラメータ:

stream -- TextIO: 入力データを含むテキストストリーム。

戻り値:

list[JobData]: 解析されたJobDataオブジェクトのリスト。

例外:

• EOFError -- ファイルの予期せぬ終端に達した場合。

• LatticeCalculationError -- 入力ファイルの形式が無効な場合（例: ヘッダー情報不足、反射行のデータ不足）。

XRD.lsq_latt2.plot_job_result(job: JobData, fit: LeastSquaresResult, output_file: Path, job_index: int, *, show_plot: bool = True) → Path

各ジョブの Q-1/d プロットを生成し、画像ファイルとして保存する。

詳細説明: 観測された1/dと計算された1/dを散乱ベクトルQに対してプロットし、 誤差棒も表示します。右軸には1/dの標準偏差も表示されます。 生成されたプロットはPNG画像として保存され、オプションで表示も可能です。

パラメータ:

• job -- JobData: プロット対象のジョブデータ。

• fit -- LeastSquaresResult: プロットに使用するフィット結果。

• output_file -- Path: レポート出力ファイル。プロットのファイル名生成に使用される。

• job_index -- int: ジョブのインデックス（ファイル名に使用）。

• show_plot -- bool: Trueの場合、プロットウィンドウを表示する。デフォルトはTrue。

戻り値:

Path: 保存されたプロットファイルのパス。

XRD.lsq_latt2.read_numeric_line(reader: LineReader, expected: int) → list[float]

リーダーから一行を読み込み、指定された数の浮動小数点数に変換する。

詳細説明: 入力ファイルから設定値やパラメータを読み込む際に使用されるヘルパー関数。 読み込んだ行をスペースで分割し、最初の`expected`個の要素を浮動小数点数に変換します。

パラメータ:

• reader -- LineReader: 入力ファイルを読み込むためのLineReaderインスタンス。

• expected -- int: 期待される数値の最小数。

戻り値:

list[float]: 読み込まれた数値のリスト。

例外:

LatticeCalculationError -- 期待されるよりも少ない数値が読み込まれた場合。

XRD.lsq_latt2.reciprocal_volume_from_cosines(cosines: ndarray) → float

逆格子のコサイン値から逆格子単位胞体積の計算に用いる係数を計算する。

詳細説明: 逆格子単位胞体積 V* は、V* = a*b*c* * sqrt(1 - cos^2(alpha*) - cos^2(beta*) - cos^2(gamma*) + 2cos(alpha*)cos(beta*)cos(gamma*)) で与えられます。この関数は、上記式の sqrt(...) の部分を計算します。

パラメータ:

cosines -- np.ndarray: 逆格子の角度のコサイン値 (cos_alpha_star, cos_beta_star, cos_gamma_star) を含むNumPy配列。

戻り値:

float: 逆格子単位胞体積計算に使用される平方根の値。

XRD.lsq_latt2.safe_sqrt(x: float) → float

非負の引数に対して安全に平方根を計算する。

詳細説明: math.sqrt は負の引数に対して ValueError を発生させますが、 この関数は引数が負の場合でも0.0として処理することでエラーを回避し、 常に非負の値を返します。

パラメータ:

x -- float: 平方根を計算する値。

戻り値:

float: xの平方根。xが負の場合は0.0。

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

ファイル名として安全な文字列を生成するため、テキストから無効な文字を除去する。

詳細説明: 入力文字列から英数字、ハイフン、アンダースコア以外の文字をアンダースコアに置換し、 前後のアンダースコアを削除して返します。空文字列になった場合は 'job' を返します。 これにより、プラットフォーム間で互換性のあるファイル名を生成できます。

パラメータ:

text -- str: サニタイズする元の文字列。

戻り値:

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

XRD.lsq_latt2.transformed_position(raw_position: float, mode: int, wavelength: float, radius: float, zero_shift: float | None) → float

生の回折位置データを指定されたモードに基づいて変換する。

詳細説明: 回折角度（2θ）や距離などの生の観測データを、最小二乗法で格子定数を決定するために 適切な形式（例: sin(θ)^2 や 1/d^2 などに比例する値）に変換します。 各モードは異なる回折実験のセットアップや測定方法に対応します。

モードの種類: - 1: sin(θ) （θは度数で与えられる2θの半分） - 2: 生の位置データそのまま - 3: ゼロ点シフトを考慮したsin(θ)（デバイシェラー法などで使用、raw_positionは距離） - 4: sin(θ/2) （θは度数で与えられる2θの半分） - 5: λ/(2*d) または 1/d に関連する逆格子距離（例: raw_positionがdまたは2θを表す場合） - その他 (例えばモード6): tan(θ) / sqrt(1 + tan^2(θ)) のような変換（raw_positionが距離を表す場合）

パラメータ:

• raw_position -- float: 生の回折位置データ。単位はモードによって異なる（度数、mmなど）。

• mode -- int: 位置変換モード（1-6）。

• wavelength -- float: 使用されるX線の波長。

• radius -- float: 測定装置の半径（位置モード3などで使用）。

• zero_shift -- float | None: 位置モード3で使用されるゼロ点シフト値。それ以外ではNone。

戻り値:

float: 変換された位置データ。

例外:

LatticeCalculationError -- 位置モード3でゼロシフト値が提供されない場合。

XRD.lsq_latt2.trigonal_direct_cosine(values: ndarray) → float

三方晶系の逆格子のコサイン値から実格子のコサイン値を計算する。

詳細説明: 三方晶系において、逆格子のcos(alpha*)から実格子のcos(alpha)を導出します。

パラメータ:

values -- np.ndarray: (cos_alpha_star,) を含むNumPy配列。

戻り値:

float: 三方晶系における実格子のコサイン値cos(alpha)。

XRD.lsq_latt2.trigonal_direct_length(values: ndarray) → float

三方晶系の逆格子定数から実格子の長さを計算する。

詳細説明: 三方晶系において、逆格子のa*とcos(alpha*)から実格子の長さaを導出します。 等方的な格子定数を持つ三方晶系（菱面体晶）の特殊なケースに適用されます。

パラメータ:

values -- np.ndarray: (a_star, cos_alpha_star) を含むNumPy配列。

戻り値:

float: 三方晶系における実格子の長さa。

XRD.lsq_latt2.trigonal_direct_volume(values: ndarray) → float

三方晶系の逆格子定数から実格子の体積を計算する。

詳細説明: 三方晶系において、逆格子のa*とcos(alpha*)から実格子の体積Vを導出します。

パラメータ:

values -- np.ndarray: (a_star, cos_alpha_star) を含むNumPy配列。

戻り値:

float: 三方晶系における実格子の体積V。

XRD.lsq_latt2.weighted_least_squares(observations: list[Observation], output: TextIO) → LeastSquaresResult

観測データに対して重み付き最小二乗法を実行する。

詳細説明: 与えられた観測データに対し、重み付き最小二乗法を用いてモデルパラメータを推定します。 このプロセスには、計算された残差に基づいて外れ値を自動的に検出し、除去する機能が含まれます。 外れ値の除去は、安定したパラメータ推定値が得られるまで繰り返されます。 最終的なレポートは output ストリームに書き出されません。

パラメータ:

• observations -- list[Observation]: 最小二乗法に使用する観測データのリスト。

• output -- TextIO: 現在のところ、この関数からは直接出力されません。将来的なログ出力用。

戻り値:

LeastSquaresResult: 最小二乗法の計算結果、フィットされたパラメータ、残差、使用および除外された観測データを含むオブジェクト。

例外:

LatticeCalculationError -- 観測データが提供されない場合、またはデザイン行列が特異な場合。

XRD.lsq_latt2.write_job_report(output: TextIO, job: JobData, fit: LeastSquaresResult, cell: CellConstants) → None

単一の格子定数計算ジョブの結果を整形されたレポートとして出力する。

詳細説明: この関数は、ジョブの概要、実格子定数、逆格子定数、フィットされたパラメータ、 適用された補正モデル、そして各反射の詳細なテーブル（使用されたものと除外されたもの） を含む包括的なレポートを output ストリームに書き出します。

パラメータ:

• output -- TextIO: レポートを書き出すためのテキストストリーム。

• job -- JobData: 計算されたジョブの設定と観測データ。

• fit -- LeastSquaresResult: 最小二乗法のフィット結果。

• cell -- CellConstants: 導出された格子定数。

XRD.lsq_latt2.write_section_title(output: TextIO, title_en: str, title_ja: str) → None

レポートのセクションタイトルを英語と日本語で出力する。

パラメータ:

• output -- TextIO: 書き込み先のストリーム。

• title_en -- str: 英語のタイトル。

• title_ja -- str: 日本語のタイトル。