ef_fit プログラム仕様
光電子分光スペクトルのフィッティング、シミュレーション、初期値推定を行うスクリプト。
測定された光電子分光スペクトルに対して、フェルミ・ディラック分布関数と状態密度、 そしてガウス関数で表現される装置関数を組み合わせたモデルを適用し、 非線形最小二乗法によるフィッティング、あるいはパラメータ指定によるシミュレーションを実行します。 また、フィッティングの初期値をスペクトルデータから自動推定する機能も提供します。
- PES.ef_fit.DOS(E: float | ndarray, DOSa: float) float | ndarray[ソース]
状態密度 (DOS) を計算する。
- 詳細説明:
ここでは単純な線形傾きを仮定し、(1.0 - DOSa * E) で状態密度を表現します。
- PES.ef_fit.app_func(E_kernel: float | ndarray, kG: float) float | ndarray[ソース]
ガウス関数カーネルを計算する (プロット用)。
- 詳細説明:
分散パラメータ kG を用いて、exp(-kG * E_kernel^2) のガウス関数を返します。 主にグラフ描画などの目的で使用されます。
- PES.ef_fit.calS(opt_params: ndarray, E: ndarray, I: ndarray, T: float, initial_params_dict: Dict[str, float], termination_state: List[bool | float]) float[ソース]
目的関数 (残差二乗和 S + ペナルティ項)。
- 詳細説明:
最適化対象のパラメータ opt_params を物理量に復元し、 それらを用いて model_spectrum を計算します。 測定データ I とモデルの差の二乗和 S を計算し、 パラメータが物理的な範囲外に逸脱した場合にペナルティを加算します。 termination_state フラグがTrueの場合、計算をスキップし、キャッシュされたエラー値を返します。 NaNやInfのような異常値が発生した場合も大きなエラー値を返します。
- パラメータ:
opt_params (numpy.ndarray) -- 最適化対象のパラメータ配列（対数変換されている場合あり）。
E (numpy.ndarray) -- フィットに使用するエネルギー配列。
I (numpy.ndarray) -- フィットに使用する測定強度配列。
T (float) -- 温度 [K]。
initial_params_dict (Dict[str, float]) -- 固定パラメータを含む、全てのパラメータの初期値辞書。
termination_state (List[Union[bool, float]]) -- 早期停止状態を表すフラグ (bool) と、その際のエラー値 (float) を格納するリスト。 [is_terminated, last_error_value] の形式。
- 戻り値:
残差二乗和とペナルティ項の合計値。
- 戻り値の型:
- PES.ef_fit.convert_params(params_dict: Dict[str, float]) ndarray[ソース]
全パラメータ辞書から、最適化対象のみを抽出し、logスケールに変換して配列として返す。
- 詳細説明:
fit_params に定義された optid が1のパラメータのみを抽出し、 convert 設定が "log" の場合は自然対数に変換します。
- PES.ef_fit.convolute_by_func_np(E: ndarray, I_phys: ndarray, w: float, kernel_range: float = 5.0) ndarray[ソース]
物理的なスペクトルをガウス関数で畳み込む (NumPy最適化版)。
- 詳細説明:
指定された半値全幅 w を持つガウス関数カーネルを生成し、numpy.convolve を使用して 物理的な強度 I_phys を効率的に畳み込みます。 カーネルの有効範囲は kernel_range * w で設定され、結果はカーネルの合計値で正規化されます。 w が非常に小さい場合 (1e-10以下) は畳み込みを行わず I_phys をそのまま返します。
- PES.ef_fit.convolute_by_func_original(E: ndarray, I_phys: ndarray, w: float) ndarray[ソース]
物理的なスペクトルをガウス関数で畳み込む (オリジナル版、ループ処理)。
- 詳細説明:
各点について、指定された半値全幅 w を持つガウス関数カーネルを用いて、 物理的な強度 I_phys を畳み込みます。この実装はPythonのループを使用するため、 NumPy最適化版 (convolute_by_func_np) よりも効率が低い可能性があります。 w が非常に小さい場合 (1e-10以下) は畳み込みを行わず I_phys をそのまま返します。
- パラメータ:
E (numpy.ndarray) -- エネルギー配列。
I_phys (numpy.ndarray) -- 物理的な信号強度配列。
w (float) -- ガウス関数の半値全幅。
- 戻り値:
畳み込み後の信号強度配列。
- 戻り値の型:
numpy.ndarray
- PES.ef_fit.fermi(E: float | ndarray, EF: float, T: float) float | ndarray[ソース]
フェルミ・ディラック分布関数を計算する。
- 詳細説明:
温度 T とフェルミ準位 EF を用いて、エネルギー E における占有確率を計算します。 数値的な安定性のために指数関数の引数をクリップし、オーバーフローやアンダーフローを防ぎます。
- PES.ef_fit.fit(args: Namespace, prm_csv_path: str, df_params: DataFrame) None[ソース]
光電子分光スペクトルのフィッティングを実行する。
- 詳細説明:
測定スペクトルを読み込み、指定されたフィット範囲でデータを抽出します。 初期パラメータはコマンドライン引数とCSVファイルから設定されます。 scipy.optimize.minimize を使用して calS (目的関数) を最小化し、最適化を行います。 最適化の進行状況は、ステップごとのコンソール出力とリアルタイムのグラフ更新で表示されます。 フィッティングが完了すると、最適化されたパラメータがパラメータCSVファイルに保存され、 元のデータ、初期モデル、最終モデルを含むExcelファイルが出力されます。
- パラメータ:
args (argparse.Namespace) -- コマンドライン引数。
prm_csv_path (str) -- パラメータCSVファイルのパス。
df_params (pandas.DataFrame) -- パラメータCSVから読み込まれたDataFrame。
- 戻り値:
None
- PES.ef_fit.fwhm2kG(w: float | ndarray) float | ndarray[ソース]
ガウス関数のFWHM wからkGに変換する。
- 詳細説明:
半値全幅 w からガウス関数 exp(-kG * E^2) の kG を計算します。 wが0以下の場合は数値的に非常に大きなkGを返します。 NumPy配列に対応しています。
- PES.ef_fit.get_prm_csv_path(filename: str) str[ソース]
元のデータファイル名から、対応するパラメータCSVファイルのパスを生成する。
- 詳細説明:
入力ファイル名の拡張子を除き、そこに "_parameters.csv" を付加して パラメータ保存用のCSVファイルパスを作成します。
- PES.ef_fit.init_params(args: Namespace, df_params: DataFrame) None[ソース]
スペクトルデータから主要なフィッティングパラメータの初期値を推定する。
- 詳細説明:
スペクトルデータを読み込み、指定されたフィット範囲内で以下のパラメータを推定します。 - BG (バックグラウンド): フィット範囲の最大エネルギー点での強度。 - I0 (信号強度): フィット範囲の最小エネルギー点での強度からBGを引いた値。 - EF (フェルミ準位): (BG + I0/2) の強度を与えるエネルギー点。 - w (装置関数FWHM): デフォルト値と温度による熱的幅から推定。 - DOSa (状態密度の線形傾き): デフォルト値。 推定結果はコンソールに表示され、パラメータCSVファイルに保存されます。 また、推定結果のスペクトルと元の測定スペクトルがプロットされます。
- パラメータ:
args (argparse.Namespace) -- コマンドライン引数。
df_params (pandas.DataFrame) -- パラメータCSVから読み込まれたDataFrame。
- 戻り値:
None
- 例外:
ValueError -- init モードで Efit_min または Efit_max が設定されていない場合、 またはフィット範囲が小さすぎるか無効な場合。
- PES.ef_fit.initialize() Namespace[ソース]
コマンドライン引数をパースし、設定をオブジェクトとして返す。
- 詳細説明:
argparse モジュールを使用して、入力ファイル名、モード（fit, sim, init）、 最適化アルゴリズム、温度、各パラメータの初期値、フィット範囲、 強度スケーリング係数、最大反復回数、ステップ出力間隔などを定義します。
- 戻り値:
コマンドライン引数を格納したNamespaceオブジェクト。
- 戻り値の型:
- PES.ef_fit.kG2fwhm(kG: float | ndarray) float | ndarray[ソース]
ガウス関数のピーク位置の分散を示すパラメータkGからFWHM wに変換する。
- 詳細説明:
ガウス関数 exp(-kG * E^2) の半値全幅を計算します。 kGが0以下の場合は数値的に非常に大きなFWHMを返します。 NumPy配列に対応しています。
- PES.ef_fit.kernel_func(dE: float | ndarray, plist: List[float]) float | ndarray[ソース]
スペクトル畳み込みに使用するガウス関数カーネルを計算する。
- 詳細説明:
plist の最初の要素である半値全幅 w から kG を計算し、 exp(-kG * dE^2) のガウス関数を返します。
- PES.ef_fit.load_params(prm_csv_path: str) DataFrame[ソース]
指定されたパスからパラメータ設定をCSVファイルとして読み込むか、存在しない場合はデフォルト値で初期化する。
- 詳細説明:
パラメータCSVファイルが存在し、読み込みに成功した場合はその内容をDataFrameとして返します。 読み込み失敗またはファイルが存在しない場合は、スクリプト内で定義されている fit_params の デフォルト値 (x0) を使用してDataFrameを生成し、返します。 この際、optid, convert, eps, min, max, kpenalty の各列も fit_params から補完されます。
- パラメータ:
prm_csv_path (str) -- パラメータCSVファイルのパス。
- 戻り値:
パラメータ設定を格納したDataFrame。
- 戻り値の型:
pandas.DataFrame
- PES.ef_fit.load_spectrum(filename: str, Escale: float = -1.0) Tuple[ndarray, ndarray][ソース]
データファイルを読み込み、エネルギーEと強度IをNumPy配列として返す。
- 詳細説明:
ファイルの拡張子 (.csv, .xlsx, .txt, .dat) に応じて適切なライブラリや関数を使用してデータを読み込みます。 .txt ファイルの場合は、カスタムパーサー read_haxpes_txt を使用します。 エネルギーデータには Escale を乗算してスケーリング（デフォルトは-1.0で反転）します。
- パラメータ:
- 戻り値:
エネルギーと強度のNumPy配列のタプル。
- 戻り値の型:
Tuple[numpy.ndarray, numpy.ndarray]
- 例外:
ValueError -- 未対応のファイル形式が指定された場合。
- PES.ef_fit.main()[ソース]
プログラムのエントリポイント。
- 詳細説明:
コマンドライン引数を処理し、指定されたモード（fit, sim, init）に応じて 適切な処理を呼び出します。 - 畳み込み関数を convolute_by_func_np に設定します。 - early_stop_flag は Nelder-Mead メソッドでない場合に True に設定されます。 - w と I0 のコマンドライン引数での正値チェックを行います。 - パラメータCSVファイルの読み込みと更新を管理します。
- 戻り値:
None
- 例外:
ValueError -- コマンドライン引数で w または I0 が正でない場合、 または未対応のモードが指定された場合。
- PES.ef_fit.model_spectrum(E: ndarray, EF: float, BG: float, kG: float, I0: float, DOSa: float, T: float) ndarray[ソース]
光電子分光スペクトルのモデルを計算する。
- 詳細説明:
状態密度 DOS とフェルミ・ディラック分布関数 fermi を乗算して物理的なスペクトル I_phys を生成し、 これを装置関数（ガウス関数）で畳み込みます。 最終的に、基底 BG と信号強度スケール I0 を適用してモデルスペクトルを完成させます。
- PES.ef_fit.print_params(message: str, params_dict: Dict[str, float]) None[ソース]
指定されたメッセージと共に、全パラメータの現在値をコンソールに出力する。
- 詳細説明:
ALL_PARAM_NAMES に従って各パラメータとその値を整形して表示します。 w が存在する場合は、対応する kG の値も併せて表示します。
- PES.ef_fit.read_hapes_xy(file_path: str, read_ndata: bool = True) Tuple[ndarray, ndarray][ソース]
ヘッダー情報が少ない（またはない）XY形式のデータファイルを読み込む。
- 詳細説明:
ファイルエンコーディングを自動検出します。 read_ndata がTrueの場合、ファイルの3行目からデータ読み込みを開始し、 Falseの場合は2行目からデータ読み込みを開始します。 各行はスペース区切りのエネルギーと信号強度の2列データとして解析されます。
- PES.ef_fit.read_haxpes_spring8(file_path: str) Tuple[ndarray, ndarray][ソース]
Spring-8 HAXPES装置の特定のフォーマット（[Info] ヘッダーを持つ）のデータファイルを読み込む。
- 詳細説明:
ファイルエンコーディングを自動検出します。 ヘッダー情報からデータの次元（行数、列数）を解析し、[Data 1] ブロックから エネルギーと平均信号強度を抽出します。複数列の強度データは平均化されます。
- パラメータ:
file_path (str) -- 読み込むファイルのパス。
- 戻り値:
エネルギーと平均信号強度のNumPy配列のタプル。
- 戻り値の型:
Tuple[numpy.ndarray, numpy.ndarray]
- PES.ef_fit.read_haxpes_txt(file_path: str) Tuple[ndarray, ndarray][ソース]
.txt 拡張子のデータファイルを読み込み、その内容に応じて適切なパーサーを呼び出す。
- 詳細説明:
ファイルの最初の数行を読み込み、以下の条件に基づいてパーサーを決定します。 - 1行目に [Info] が含まれる場合: read_haxpes_spring8 を呼び出す。 - 2行目が数字のみの場合: read_hapes_xy (引数 read_ndata=True) を呼び出す。 - それ以外の場合: read_hapes_xy (引数 read_ndata=False) を呼び出す。
- パラメータ:
file_path (str) -- 読み込むファイルのパス。
- 戻り値:
エネルギーと信号強度のNumPy配列のタプル。
- 戻り値の型:
Tuple[numpy.ndarray, numpy.ndarray]
- PES.ef_fit.recover_params(opt_params_array: ndarray, all_initial_params_dict: Dict[str, float]) List[float][ソース]
最適化パラメータ配列と、固定パラメータの初期値から、全パラメータの物理量リストを再構成。
- 詳細説明:
最適化されたパラメータ配列 opt_params_array を fit_params の convert 設定に基づいて 元の物理量スケール（指数関数など）に復元します。 固定パラメータは all_initial_params_dict から取得し、全てのパラメータを結合して ALL_PARAM_NAMES で定義された順序のリストとして返します。
- PES.ef_fit.save_params(prm_csv_path: str, df_params: DataFrame) None[ソース]
DataFrame形式のパラメータ設定をCSVファイルに保存する。
- パラメータ:
prm_csv_path (str) -- 保存先のパラメータCSVファイルのパス。
df_params (pandas.DataFrame) -- 保存するパラメータ設定を含むDataFrame。
- 戻り値:
None
- PES.ef_fit.simulate(args: Namespace, df_params: DataFrame) None[ソース]
指定されたパラメータと条件に基づいて光電子分光スペクトルをシミュレーションし、結果をプロットする。
- 詳細説明:
コマンドライン引数やCSVファイルから読み込んだパラメータを用いて、 model_spectrum 関数によりスペクトルを計算します。 計算されたモデルスペクトルと測定データ、およびモデルの構成要素 （状態密度 (DOS), フェルミ・ディラック分布関数 (fFD), DOSとfFDの積, 装置関数 (g_app)） をグラフに表示します。
- パラメータ:
args (argparse.Namespace) -- コマンドライン引数。
df_params (pandas.DataFrame) -- パラメータCSVから読み込まれたDataFrame。
- 戻り値:
None
- 例外:
ValueError -- w (FWHM) または I0 (シグナル強度) が正でない場合。
- PES.ef_fit.terminate()[ソース]
プログラムを終了する前にユーザー入力を待機する。
- 詳細説明:
ユーザーがEnterキーを押すまで処理をブロックし、その後プログラムを終了します。
- 戻り値:
None
- PES.ef_fit.update_params(args: Namespace, df_params: DataFrame) Dict[str, float][ソース]
コマンドライン引数、CSVファイルから全パラメータの初期値を決定し、辞書で返す。
- 詳細説明:
まず df_params から 'Value' 列の値を読み込み、その後コマンドライン引数 (args) で 指定された値があればそれらを優先して上書きします。 w と I0 が正の値であることを確認し、w から kG を計算して辞書に追加します。
- パラメータ:
args (argparse.Namespace) -- コマンドライン引数。
df_params (pandas.DataFrame) -- パラメータCSVから読み込まれたDataFrame。
- 戻り値:
更新された全パラメータの辞書。
- 戻り値の型:
- 例外:
ValueError -- w (FWHM) または I0 (シグナル強度) が正でない場合。