mu_fit プログラム仕様

Hall効果移動度解析・フィッティングツール (mu_fit.py)

このモジュールは、Hall効果測定から得られた温度依存移動度データを、 各種散乱メカニズム（光学フォノン、音響フォノン、中性不純物、イオン化不純物、粒界散乱） の物理モデルに基づいてフィッティングし、パラメータの最適化および誤差評価を行います。

主な機能:

• 実験データの読み込み（CSV/Excel）

• 線形最小二乗法（LLSQ）による初期値推定

• 非線形最適化によるパラメータ抽出

• 誤差伝播法によるモデルの不確かさ（1σ範囲）の算出

• 共分散行列・相関係数・固有値解析によるパラメータ感度診断

関連ドキュメント:

• usage

• physics_models

注釈

フィッティングの目的関数は、移動度の対数スケールでの残差二乗和を最小化します。

build_full_params(init_full, optimize_indices, p_opt)

最適化対象のパラメータと固定パラメータを統合し、全5パラメータのリストを作成する。

初期値/固定値のリストと、最適化によって得られた変動パラメータのリストを組み合わせ、 完全なパラメータセットを再構築する。

パラメータ:

• init_full (list) -- 初期/固定値を含む全パラメータリスト。

• optimize_indices (list) -- 最適化対象のインデックス。

• p_opt (list) -- 最適化されたパラメータ値のリスト。

戻り値:

統合された全パラメータリスト。

戻り値の型:

list

cov_to_corr(cov)

共分散行列を相関係数行列に変換する。

共分散行列から標準偏差を計算し、その情報を用いて相関係数行列を生成する。 対角要素は1.0とし、ゼロ除算を避ける処理を含む。

パラメータ:

cov (numpy.ndarray) -- 共分散行列。

戻り値:

相関係数行列と標準偏差の配列。

戻り値の型:

(numpy.ndarray, numpy.ndarray)

eigen_sorted_sym(A)

対称行列の固有値分解を行い、固有値の降順でソートして返す。

numpyの`eigh`関数で対称行列の固有値と固有ベクトルを計算し、 固有値の降順でソートして返す。

パラメータ:

A (numpy.ndarray) -- 対象とする対称行列。

戻り値:

降順ソートされた固有値と対応する固有ベクトル。

戻り値の型:

(numpy.ndarray, numpy.ndarray)

fit_mask(T, Tfitmin=-1e+100, Tfitmax=1e+100)

指定された温度範囲に基づいてデータのマスクを作成する。

温度配列`T`の中から、`Tfitmin`と`Tfitmax`の範囲内にある要素に対応する真偽値マスクを生成する。

パラメータ:

• T (numpy.ndarray) -- 温度 [K] の配列。

• Tfitmin (float) -- フィットに使用する最小温度。

• Tfitmax (float) -- フィットに使用する最大温度。

戻り値:

指定範囲内のデータを示すブール値配列。

戻り値の型:

numpy.ndarray

get_inv_mu_components(T, params, Eop)

各散乱メカニズムの逆移動度の寄与と、合計の逆移動度を計算する。

Matthiessenの則に基づき、光学フォノン、音響フォノン、中性不純物、イオン化不純物の 各散乱成分の逆移動度を計算し、さらに粒界散乱の効果を指数関数的に適用して合計逆移動度を算出する。

パラメータ:

• T (numpy.ndarray) -- 温度 [K] の配列。

• params (list) -- パラメータリスト [aop, a1, a2, a3, VB]。

• Eop (float) -- 光学フォノンエネルギー [eV]。

戻り値:

各成分の辞書と、合計逆移動度の配列。

戻り値の型:

(dict, numpy.ndarray)

load_hall_data(file_path)

Hall効果の測定データをファイルから読み込む。

指定されたパスのファイル（CSVまたはExcel）をPandas DataFrameとして読み込む。 ファイルが存在しない場合はエラーメッセージを表示し、Noneを返す。

パラメータ:

file_path (str) -- 読み込むファイルのパス (.csv または .xlsx)。

戻り値:

読み込まれたデータフレーム。失敗した場合は None。

戻り値の型:

pandas.DataFrame or None

load_params(filename='fit_params.json')

JSONファイルからフィッティングパラメータを読み込む。

指定されたJSONファイルからパラメータを読み込む。ファイルが存在しない場合は、 `llsq_params.json`を試行し、それもなければデフォルトの初期値を返す。

パラメータ:

filename (str) -- 読み込み先ファイル名。

戻り値:

パラメータ名と値の辞書。

戻り値の型:

dict

main()

コマンドライン引数を解析し、Hall効果移動度の解析・フィッティング処理を実行するエントリーポイント。

`argparse`を使用してコマンドライン引数を処理し、指定されたモード （データ読み込み、LLSQ初期推定、非線形フィット、寄与度可視化）に応じて、 Hall効果測定データのフィッティングと結果の保存・可視化を行う。 パラメータ固定、誤差推定、フィッティング温度範囲の指定など、詳細なオプションに対応する。

戻り値:

None

numerical_jacobian(fun_vec, p, rel_step=1e-06, abs_step=1e-12)

中心差分法を用いてベクトル値関数のヤコビ行列を数値的に計算する。

各パラメータについて、微小なステップで関数値を perturbed し、その差分から偏微分を近似することで ヤコビ行列を構築する。

パラメータ:

• fun_vec (callable) -- 残差ベクトルを返す関数。

• p (numpy.ndarray) -- パラメータベクトル。

• rel_step (float) -- 数値微分の相対ステップ。

• abs_step (float) -- 数値微分の絶対ステップ。

戻り値:

ヤコビ行列 (N, M)。

戻り値の型:

numpy.ndarray

param_covariance(residual_vec, J, dof)

線形近似に基づき、最適化パラメータの共分散行列と標準誤差を推定する。

最適化後の残差とヤコビ行列を用いて、非線形最小二乗法におけるパラメータの共分散行列を計算し、 それから標準誤差を導出する。

パラメータ:

• residual_vec (numpy.ndarray) -- 最適化後の残差ベクトル。

• J (numpy.ndarray) -- ヤコビ行列。

• dof (int) -- 自由度 (データ数 - パラメータ数)。

戻り値:

共分散行列と標準誤差の配列のタプル。

戻り値の型:

(numpy.ndarray, numpy.ndarray)

prediction_band_log10_mu(T, params_full, Eop, optimize_indices, cov_opt, nsigma=1.0, rel_step=1e-06, abs_step=1e-12)

デルタ法（誤差伝播）を用いて、モデルの対数移動度における予測誤差帯を計算する。

最適化されたパラメータの共分散行列と、モデル関数のパラメータに対する数値的な勾配を用いて、 モデル予測値の不確かさ（標準偏差）を計算し、予測帯の上限と下限を導出する。

パラメータ:

• T (numpy.ndarray) -- 温度 [K] の配列。

• params_full (list) -- 全パラメータのリスト。

• Eop (float) -- 光学フォノンエネルギー [eV]。

• optimize_indices (list) -- 最適化対象のインデックス。

• cov_opt (numpy.ndarray) -- 最適化パラメータの共分散行列。

• nsigma (float) -- 誤差帯のシグマ倍率。

• rel_step (float) -- 勾配算出用の相対ステップ。

• abs_step (float) -- 勾配算出用の絶対ステップ。

戻り値:

(平均値, 下限, 上限) の各配列。

戻り値の型:

(numpy.ndarray, numpy.ndarray, numpy.ndarray)

propose_fix_candidates(names, values, stderr, corr, evals_cov=None, evecs_cov=None, corr_thr=0.95, relerr_thr=0.5, topn=3)

数値的な不安定性（大きな誤差や強相関）に基づき、固定を検討すべきパラメータを提案する。

パラメータの相対誤差、相関係数、および共分散行列の固有分析結果を総合的に評価し、 最適化の収束を改善するために固定することが推奨されるパラメータ候補をスコア付けして提示する。

パラメータ:

• names (list) -- パラメータ名のリスト。

• values (numpy.ndarray) -- 最適化された値。

• stderr (numpy.ndarray) -- 標準誤差。

• corr (numpy.ndarray) -- 相関係数行列。

• evals_cov (numpy.ndarray) -- 共分散行列の固有値（オプション）。

• evecs_cov (numpy.ndarray) -- 共分散行列の固有ベクトル（オプション）。

• corr_thr (float) -- 強相関とみなす閾値。

• relerr_thr (float) -- 相対誤差が大きいとみなす閾値。

• topn (int) -- 提案する最大数。

戻り値:

提案パラメータと理由を含む辞書のリスト。

戻り値の型:

list

residuals_log10(T, mu_exp, params_full, Eop)

移動度の対数値(log10)における実測値とモデル値の残差を計算する。

実測移動度と、現在のパラメータで計算されるモデル移動度の常用対数を取り、その差を計算する。 数値的な安定性のため、移動度が非常に小さい場合はクリッピングを行う。

パラメータ:

• T (numpy.ndarray) -- 温度 [K] の配列。

• mu_exp (numpy.ndarray) -- 実測移動度の配列。

• params_full (list) -- 全5パラメータのリスト。

• Eop (float) -- 光学フォノンエネルギー [eV]。

戻り値:

log10(mu_exp) - log10(mu_model) の残差配列。

戻り値の型:

numpy.ndarray

save_params(params, filename='fit_params.json')

フィッティングパラメータまたは診断結果をJSON形式で保存する。

辞書形式のデータを指定されたファイル名でJSONファイルとして保存する。

パラメータ:

• params (dict) -- 保存するパラメータの辞書。

• filename (str) -- 保存先ファイル名。

戻り値:

None

solve_llsq(T, mu_exp, Eop)

線形最小二乗法を用いて散乱係数(a_i)の初期値を推定する。

VB（粒界散乱障壁）を0と仮定し、逆移動度に対して線形フィットを行います。 推定された係数は負の値にならないようクリッピングされます。

パラメータ:

• T (numpy.ndarray) -- 温度 [K] の配列。

• mu_exp (numpy.ndarray) -- 実測移動度 [cm^2/Vs] の配列。

• Eop (float) -- 光学フォノンエネルギー [eV]。

戻り値:

推定された係数配列 [aop, a1, a2, a3]。

戻り値の型:

numpy.ndarray

summarize_eigenvectors(evals, evecs, names, topk=3, compk=3)

固有ベクトルを人間が読みやすい形式（パラメータ成分の寄与度）で要約する。

共分散行列の固有値と固有ベクトルから、どのパラメータが不確かさの主要な方向に 強く寄与しているかをランク付けして表示する。

パラメータ:

• evals (numpy.ndarray) -- 固有値の配列。

• evecs (numpy.ndarray) -- 固有ベクトルの行列。

• names (list) -- パラメータ名のリスト。

• topk (int) -- 出力する固有値の数。

• compk (int) -- 各固有ベクトルについて表示する成分の数。

戻り値:

ランクごとの固有値と成分寄与度を含む辞書のリスト。

戻り値の型:

list

visualize_fit(T, mu_exp, mu_fit=None, mu_lo=None, mu_hi=None, title='Hall Mobility Fit', save_name='plot.png')

実験データ、モデルのフィット曲線、および誤差帯をプロットして保存する。

実測移動度、フィットされたモデル移動度、およびその誤差帯を対数スケールでグラフ化し、 指定されたファイル名で画像として保存し、表示する。

パラメータ:

• T (numpy.ndarray) -- 温度 [K]。

• mu_exp (numpy.ndarray) -- 実測移動度。

• mu_fit (numpy.ndarray) -- モデルによるフィット値（オプション）。

• mu_lo (numpy.ndarray) -- 誤差帯の下限（オプション）。

• mu_hi (numpy.ndarray) -- 誤差帯の上限（オプション）。

• title (str) -- グラフのタイトル。

• save_name (str) -- 保存ファイル名。

戻り値:

None

visualize_weights(T, components, total, save_name='weight_plot.png')

各散乱メカニズムが全体の散乱（逆移動度）に占める割合（寄与度）を可視化する。

温度に対して、各散乱メカニズム（光学フォノン、音響フォノン、不純物、粒界）が 合計の逆移動度（散乱）に占める割合をパーセンテージでプロットする。

パラメータ:

• T (numpy.ndarray) -- 温度 [K]。

• components (dict) -- 各成分の逆移動度。

• total (numpy.ndarray) -- 合計逆移動度。

• save_name (str) -- 保存ファイル名。

戻り値:

None