# ``mu_fit_tklsq.py`` ドキュメント

## はじめに

このドキュメントは、Pythonプログラム ``mu_fit_tklsq.py`` のソースコードを解析し、Sphinx（MyST）でビルド可能なMarkdown形式で記述したものです。

## 概要

``mu_fit_tklsq.py`` は、ホール効果移動度の解析およびフィッティングを行うためのツールです。移動度データの温度依存性を、複数の散乱機構（光学フォノン、音響フォノン、中性不純物、電離不純物、粒界）を考慮したモデルでフィッティングし、各散乱機構の寄与やパラメータを評価します。

フィッティングには ``tkminfit`` ライブラリを使用しており、特に新しい ``callback(q)`` インターフェースに対応しています。これにより、フィッティング過程のリアルタイム描画やアニメーション保存が可能です。

## 特徴

*   ``scipy.optimize.minimize`` を直接呼び出す代わりに、``tkminfit.minimize_lsq`` を使用。
*   ``tkminfit`` の新しい ``callback(q)`` 仕様に対応。
*   ``callback`` 内でのイテレーション管理、パラメータの展開 (``unpack(q)``)、目的関数評価 (``objective(q)``)、リアルタイム描画、GIF用フレーム保存をアプリケーション側で実装。
*   フィッティング対象パラメータ (``optid=1``) は、線形フィッティングフラグ (``optid_lin``) の値に関わらずすべて最適化変数 ``q`` に含める。
*   元コードと同様に、``y=log10(mu)`` とし、``log10`` 移動度残差を最小化。

## 依存ライブラリ

### 標準ライブラリ

*   ``argparse``: コマンドライン引数の解析に使用。
*   ``json``: JSON形式でのデータ出力に使用。
*   ``os``: オペレーティングシステムとのインターフェース（環境変数の読み込み、パス操作など）に使用。
*   ``sys``: システム固有のパラメータや関数へのアクセス（モジュール検索パスの操作など）に使用。
*   ``traceback``: 例外発生時のスタックトレース出力に使用。
*   ``pathlib.Path``: オブジェクト指向パス操作に使用。
*   ``typing.Dict``, ``typing.Mapping``, ``typing.Sequence``, ``typing.Tuple``: 型ヒントに使用。

### 非標準ライブラリ

*   ``numpy``: 数値計算（配列操作、数学関数など）に使用。
*   ``pandas``: データフレーム操作、Excel出力に使用。
*   ``matplotlib.pyplot``: グラフ描画に使用。
*   ``matplotlib.animation.FuncAnimation``, ``matplotlib.animation.PillowWriter``: アニメーション作成に使用。
*   ``tklsq`` (ローカルモジュール):
    *   ``tklsq.tkdataio``: データファイルの読み書きに使用。
    *   ``tklsq.tkparamio``: パラメータファイルの読み書きに使用。
    *   ``tklsq.tklsq``: 線形最小二乗法アルゴリズムに使用。
    *   ``tklsq.tknlsq``: コード中では ``import`` されていますが、直接の呼び出しは確認できません。
    *   ``tklsq.tkfitdiag``: フィッティング診断（共分散行列の解析など）に使用。
    *   ``tklsq.tkminfit``: 非線形最小二乗法フィッティングの中核を担うモジュールに使用。

    注: ``tklsq`` は、環境変数 ``tkprog_X_path`` が設定されている場合、そのパスに含まれる ``regression`` ディレクトリが ``sys.path`` に追加されることでロードされます。これは、ローカル開発環境での使用を想定したものです。

## インストール

``numpy``, ``pandas``, ``matplotlib`` は ``pip`` を用いてインストールできます。

```bash
pip install numpy pandas matplotlib

tklsq はこのスクリプトに同梱されているか、ローカル開発環境のパスを通じてロードされることを想定しています。標準的な pip でのインストール方法はコードからは確認できません。

使用方法

コマンドライン引数

mu_fit_tklsq.py は、以下のコマンドライン引数をサポートしています。

引数名	型	デフォルト値	説明
`--mode`	`str`	(必須)	実行モードを指定します。選択肢: `read`, `sim`, `lfit`, `llsq`, `fit`, `model_select`, `weight`.
`--infile`	`str`	(必須)	入力データファイルのパス (CSV/TSV/TXT/XLSX)。
`--save`	`int`	`1`	結果をファイルに保存するかどうか (`0`: 保存しない, `1`: 保存する)。
`--show`	`int`	`1`	グラフを表示するかどうか (`0`: 表示しない, `1`: 表示する)。
`--paramfile`	`str`	`None`	パラメータファイルのパス。指定しない場合、`<infile_stem>_params.csv` が自動生成されます。
`--outfile`	`str`	`None`	出力ファイル名のステム。指定しない場合、`<infile_stem>` が自動生成されます。
`--nplot_interval`	`int`	`10`	フィッティングアニメーション用のフレームを保存するイテレーション間隔。
`--method`	`str`	`Nelder-Mead`	非線形最適化に使用するアルゴリズム。
`--maxiter`	`int`	`5000`	非線形最適化の最大イテレーション数。
`--temp_col`	`str` / `int`	`0`	温度データを含む列のインデックス (0-based) または列名。
`--mu_col`	`str` / `int`	`2`	移動度データを含む列のインデックス (0-based) または列名。
`--sheet_name`	`str` / `int`	`0`	Excelファイルの場合のシート名またはシートインデックス (0-based)。
`--eop`	`float`	`0.045`	光学フォノンエネルギー (単位: eV)。
`--fix`	`str`	`""`	パラメータファイルが未作成の場合に有効。固定するパラメータ名をカンマ区切りで指定 (例: `aop,a1`)。
`--Tfitmin`	`float`	`-1e100`	フィッティングに使用する温度範囲の下限 (非線形フィット用)。
`--Tfitmax`	`float`	`+1e100`	フィッティングに使用する温度範囲の上限 (非線形フィット用)。
`--Tfitmin_read`	`float`	`-1e100`	データ読み込み時に適用される温度範囲の下限。
`--Tfitmax_read`	`float`	`+1e100`	データ読み込み時に適用される温度範囲の上限。
`--band_sigma`	`float`	`1.0`	予測バンドの計算に使用するシグマ値 (例: `1.0` で1σバンド)。
`--jac_relstep`	`float`	`1e-6`	ヤコビアン計算の相対ステップサイズ。
`--jac_absstep`	`float`	`1e-12`	ヤコビアン計算の絶対ステップサイズ。
`--p0_aop`	`float`	`None`	パラメータ `aop` の初期値。
`--p0_a1`	`float`	`None`	パラメータ `a1` の初期値。
`--p0_a2`	`float`	`None`	パラメータ `a2` の初期値。
`--p0_a3`	`float`	`None`	パラメータ `a3` の初期値。
`--p0_VB`	`float`	`None`	パラメータ `VB` の初期値。

基本的な使い方

プログラムのヘルプメッセージを表示するには、以下のコマンドを実行します。

python mu_fit_tklsq.py --help

各 `--mode` の詳細

`read` モード

入力データ (温度 T と移動度 mu) を読み込み、log10(mu) を温度に対してプロットします。フィッティングは行わず、データの表示と初期確認が目的です。

出力ファイル:

<outfile_stem>_read.png: 読み込んだデータをプロットしたPNG画像。

`lfit` / `llsq` モード

線形最小二乗法 (LLSQ) を用いて初期フィッティングを行います。このモードでは、粒界散乱 (VB) を固定し、他のパラメータ (aop, a1, a2, a3) を線形的に決定します。

出力ファイル:

<outfile_stem>_params.csv: LLSQで得られたパラメータが保存されたCSVファイル (--save 1 の場合)。
<outfile_stem>_lfit.png: LLSQによるフィッティング結果と残差をプロットしたPNG画像 (--save 1 の場合)。

`fit` モード

非線形最小二乗法を用いて、移動度モデルの全パラメータをフィッティングします。--method 引数で最適化アルゴリズムを指定でき、--maxiter で最大イテレーション数を設定できます。フィッティングの進捗はリアルタイムで描画され、GIFアニメーションとしても保存されます。

出力ファイル:

<outfile_stem>_params.csv: フィッティングで得られた最終パラメータと標準誤差が保存されたCSVファイル (--save 1 の場合)。
<outfile_stem>_fit.png: 最終フィッティング結果、予測バンド、および残差をプロットしたPNG画像 (--save 1 の場合)。
<outfile_stem>_fit_animation.gif: フィッティングの進行状況を示すGIFアニメーション (--save 1 の場合)。
<outfile_stem>_fit.xlsx: フィッティング結果の詳細データ (実測値、フィット値、残差、予測バンド)、パラメータ、共分散行列、診断情報を含むExcelファイル (--save 1 の場合)。
<outfile_stem>_fit_diagnostics.json: フィッティング診断情報 (成功/失敗、RSS、自由度、共分散行列の条件数と固有値など) を含むJSONファイル (--save 1 の場合)。

`sim` モード

現在のパラメータファイルに記述されているパラメータを用いて、移動度モデルからシミュレーション結果を計算し、元のデータと共にプロットします。フィッティングは行いません。

出力ファイル:

<outfile_stem>_sim.png: シミュレーション結果と元のデータをプロットしたPNG画像 (--save 1 の場合)。

`weight` モード

現在のパラメータファイルに記述されているパラメータを用いて、各散乱機構が全移動度散乱にどれだけ寄与しているかをパーセンテージで計算し、温度依存性をプロットします。

出力ファイル:

<outfile_stem>_weight.png: 各散乱機構の寄与率をプロットしたPNG画像 (--save 1 の場合)。

`model_select` モード

現在のHall移動度モデルでは、このモードは fit モードと同じ動作をします。コードからは、モデル選択の特別なロジックは確認できません。

入出力ファイル

入力データファイル

--infile 引数で指定します。以下の形式をサポートしています。

CSV (Comma-Separated Values)
TSV (Tab-Separated Values)
TXT (テキストファイル、区切り文字は自動判別)
XLSX (Microsoft Excelファイル)

データファイルは、温度 (--temp_col で指定) とホール移動度 (--mu_col で指定) の列を含む必要があります。これらの列は、0から始まるインデックスまたは列名で指定できます。Excelファイルの場合、--sheet_name でシートを指定できます。

パラメータファイル

--paramfile 引数で指定するか、<infile_stem>_params.csv という名前で自動生成されます。このファイルは、フィッティングパラメータの初期値、最適化の有無、スケール (log/linear)、制約などの情報を保持します。

パラメータ定義の例:

[
    {"varname": "aop", "optid": 1, "optid_lin": 0, "p0": 1e-3, "pscale": "log", "dp": 1e-6, "pmin": 1e-300, "pmax": "", "kpenalty": 1e12},
    {"varname": "a1",  "optid": 1, "optid_lin": 0, "p0": 1e-7, "pscale": "log", "dp": 1e-10, "pmin": 1e-300, "pmax": "", "kpenalty": 1e12},
    {"varname": "a2",  "optid": 1, "optid_lin": 0, "p0": 1e-4, "pscale": "log", "dp": 1e-7, "pmin": 1e-300, "pmax": "", "kpenalty": 1e12},
    {"varname": "a3",  "optid": 1, "optid_lin": 0, "p0": 1e1,  "pscale": "log", "dp": 1e-2, "pmin": 1e-300, "pmax": "", "kpenalty": 1e12},
    {"varname": "VB",  "optid": 1, "optid_lin": 0, "p0": 0.0,  "pscale": "linear", "dp": 1e-4, "pmin": "", "pmax": "", "kpenalty": 1e12},
]

各要素の意味は以下の通りです。

varname: パラメータ名。
optid: 非線形フィッティングでこのパラメータを最適化するか (1: する, 0: しない)。
optid_lin: 線形フィッティングでこのパラメータを最適化するか (コード中では optid=1 のパラメータは optid_lin の値に関わらず非線形フィッティング対象となるため、この値は事実上無視されます)。
p0: パラメータの初期値。
pscale: パラメータのスケール ("log" または "linear")。
dp: 数値微分におけるステップサイズ (コード中では jac_relstep / jac_absstep が使用され、この dp は直接は使われていないようです)。
pmin: パラメータの最小値。
pmax: パラメータの最大値。
kpenalty: 境界ペナルティの係数。

出力ファイル

--outfile で指定されたステム名に基づいて、以下のファイルが生成されます (--save 1 の場合)。

拡張子	形式	内容	モード
`_read.png`	PNG	読み込んだ移動度データ (`log10(mu)` vs. `T`)	`read`
`_lfit.png`	PNG	線形フィッティング結果と残差	`lfit` / `llsq`
`_fit.png`	PNG	非線形フィッティング最終結果、予測バンド、残差	`fit`
`_fit_animation.gif`	GIF	非線形フィッティングのリアルタイム進捗アニメーション	`fit`
`_fit.xlsx`	XLSX	フィッティング詳細データ、パラメータ、共分散、診断情報	`fit`
`_fit_diagnostics.json`	JSON	フィッティングの診断情報 (成功、RSS、共分散行列情報など)	`fit`
`_weight.png`	PNG	各散乱機構の移動度に対する寄与率 (%)	`weight`
`_sim.png`	PNG	現在のパラメータによるシミュレーション結果と実測値の比較	`sim`
`_params.csv`	CSV	パラメータの初期値、最適化結果、標準誤差、制約などの情報	全モード (`read` と `weight` 以外)

アルゴリズムとモデル

ホール移動度モデル

このプログラムで使用されるホール移動度モデルは、以下の散乱機構を考慮に入れています。移動度の逆数 (1/mu) が、これらの散乱機構の寄与の合計として表現されます。

\frac{1}{\mu_{total}} = \frac{1}{\mu_{OP}} + \frac{1}{\mu_{AC}} + \frac{1}{\mu_{NI}} + \frac{1}{\mu_{II}} + \frac{1}{\mu_{GB}}

または、コード中で inv_mu_bulk と inv_mu_total の関係として以下のように記述されています。

\frac{1}{\mu_{total}} = \left( \frac{1}{\mu_{OP}} + \frac{1}{\mu_{AC}} + \frac{1}{\mu_{NI}} + \frac{1}{\mu_{II}} \right) \exp\left( \frac{V_B}{k_B T} \right)

ここで、VB は粒界散乱 (Grain Boundary) に関連するパラメータです。

各散乱機構の温度依存性は以下の通りです。

光学フォノン散乱 (Optical Phonon): 1/mu_OP = aop / (exp(Eop / (K_B * T)) - 1)
- aop: パラメータ aop
- Eop: 光学フォノンエネルギー (--eop で指定、デフォルト 0.045 eV)
- K_B: ボルツマン定数
- T: 温度
音響フォノン散乱 (Acoustic Phonon): 1/mu_AC = a1 * T^1.5
- a1: パラメータ a1
中性不純物散乱 (Neutral Impurity): 1/mu_NI = a2 * 1
- a2: パラメータ a2 (温度に依存しない定数項)
電離不純物散乱 (Ionized Impurity): 1/mu_II = a3 * T^-1.5
- a3: パラメータ a3
粒界散乱 (Grain Boundary): このモデルでは、粒界散乱は exp(VB / (K_B * T)) の因子として、他の散乱機構の合計に乗算されます。 1/mu_GB は、1/mu_total - 1/mu_bulk として計算されます。
- VB: パラメータ VB

フィッティングの目的関数は log10 移動度残差の二乗和を最小化するように設計されています。

\text{Minimize} \sum \left( \log_{10}(\mu_{exp}) - \log_{10}(\mu_{model}) \right)^2

フィッティングアルゴリズム

線形最小二乗法 (LLSQ): mode_lfit() で使用され、tklsq.tklsq.linear_lsq() を呼び出します。このモードでは、VB が固定され、残りの係数 (aop, a1, a2, a3) が線形に決定されます。
非線形最小二乗法: mode_fit() で使用され、tkminfit.minimize_lsq() を呼び出します。これは、非線形な移動度モデルのパラメータを最適化するためのものです。目的関数は、log10 移動度残差の二乗和にパラメータの境界ペナルティを加えたものです。最適化手法は --method 引数で指定できます (デフォルト Nelder-Mead)。ヤコビアンの計算には、--jac_relstep と --jac_absstep で指定される有限差分法が用いられます。

パラメータのスケーリング

パラメータファイル (_params.csv) で pscale が "log" と指定されたパラメータは、フィッティングの内部では log10 変換された値で扱われます。これにより、値が大きく変動する可能性のあるパラメータでも安定したフィッティングが可能になります。

pscale="log": パラメータ p は内部的に log10(p) として扱われます。初期値 p0 が 0 以下の場合や NaN の場合、pmin またはデフォルト値 (1e-300) にクリップされます。標準誤差 (stderr) は、q 空間 (log10 変換後) で計算された後、値空間に近似的に変換されます。
pscale="linear": パラメータ p はそのままの値で扱われます。

関数リファレンス

K_B: ボルツマン定数 (8.617333262e-5 eV/K)。
PARAM_NAMES: モデルで使用されるパラメータ名のリスト (["aop", "a1", "a2", "a3", "VB"])。
DEFAULT_PARAMS: パラメータファイルの初期値として使用される辞書型リスト。各パラメータの varname, optid, p0, pscale, pmin などのデフォルト設定を定義します。

`stem_from_infile(infile: str | Path) -> str`

入力ファイルパスから拡張子を除いたファイル名ステムを返します。

引数:
- infile: 入力ファイルパス。
戻り値: ファイル名ステム。

`auto_paramfile(infile: str | Path) -> str`

入力ファイル名ステムに基づいて、自動生成されるパラメータファイルのパスを返します (例: <infile_stem>_params.csv)。

引数:
- infile: 入力ファイルパス。
戻り値: パラメータファイルパス。

`auto_outfile(infile: str | Path) -> str`

入力ファイル名ステムに基づいて、自動生成される出力ファイルのベース名を返します (例: <infile_stem>)。

引数:
- infile: 入力ファイルパス。
戻り値: 出力ファイルベース名。

`save_log(path: str | Path) -> Path`

指定されたパスの親ディレクトリを作成し、保存ログメッセージを出力します。

引数:
- path: 保存先のパス。
戻り値: 作成された Path オブジェクト。

`save_done(path: str | Path) -> None`

保存完了メッセージを出力します。

引数:
- path: 保存されたファイルのパス。

`read_xy_hall(args) -> Tuple[np.ndarray, np.ndarray, str, str]`

コマンドライン引数に基づいて、指定された入力ファイルから温度 T と移動度 mu のデータを読み込みます。無効な行 (NaN, 負の値) は除外されます。

引数:
- args: コマンドライン引数オブジェクト。
戻り値: (T, mu, xlabel, ylabel) のタプル。

`get_inv_mu_components(T: np.ndarray, p: Mapping[str, float], Eop: float) -> Tuple[Dict[str, float], np.ndarray]`

与えられた温度 T とパラメータ p に基づいて、各散乱機構の移動度逆数成分を計算します。

引数:
- T: 温度のNumPy配列。
- p: パラメータ名と値の辞書。
- Eop: 光学フォノンエネルギー。
戻り値: (components, inv_mu_total) のタプル。
- components: 各散乱機構名とその移動度逆数成分の辞書。
- inv_mu_total: 全移動度の逆数。

`mobility_model(T: np.ndarray, p: Mapping[str, float]) -> np.ndarray`

与えられた温度 T とパラメータ p に基づいて、総移動度を計算します。

引数:
- T: 温度のNumPy配列。
- p: パラメータ名と値の辞書。
戻り値: 計算された移動度のNumPy配列。

`model(x: np.ndarray, p: Mapping[str, float]) -> np.ndarray`

フィッティング用のモデル関数です。mobility_model() の結果を log10 変換して返します。

引数:
- x: 温度のNumPy配列。
- p: パラメータ名と値の辞書。
戻り値: log10 変換された移動度のNumPy配列。

`lfit_design_matrix(T: np.ndarray, Eop: float) -> np.ndarray`

線形フィッティング用のデザイン行列 X を作成します。T^1.5, 1, T^-1.5, 1/(exp(Eop/(K_B*T))-1) などの項が含まれます。

引数:
- T: 温度のNumPy配列。
- Eop: 光学フォノンエネルギー。
戻り値: デザイン行列のNumPy配列。

`fit_mask(T: np.ndarray, tmin: float, tmax: float) -> np.ndarray`

指定された温度範囲 tmin から tmax 内のデータを選択するためのブールマスクを生成します。

引数:
- T: 温度のNumPy配列。
- tmin: 最小温度。
- tmax: 最大温度。
戻り値: ブールマスクのNumPy配列。

`values_from_params(params) -> Dict[str, float]`

パラメータ定義の辞書から、各パラメータの初期値 (p0) を抽出して辞書として返します。

引数:
- params: パラメータ定義の辞書。
戻り値: パラメータ名と値の辞書。

`optid1_names(params) -> list[str]`

optid が 1 に設定されているパラメータの名前のリストを返します。これらのパラメータは非線形フィッティングで最適化されます。

引数:
- params: パラメータ定義の辞書。
戻り値: 最適化対象パラメータ名のリスト。

`pscale_of(params, name: str) -> str`

指定されたパラメータの pscale ("log" または "linear") を返します。

引数:
- params: パラメータ定義の辞書。
- name: パラメータ名。
戻り値: スケール文字列。

`positive_floor_from_param(params, name: str, default: float = 1e-300) -> float`

pscale="log" のパラメータに対して、正の最小値を決定します。パラメータ定義の pmin が 0 より大きい場合はそれが使われ、そうでなければ default 値が使われます。

引数:
- params: パラメータ定義の辞書。
- name: パラメータ名。
- default: デフォルトの最小値。
戻り値: 決定された最小正値。

`pack(values: Mapping[str, float], names: Sequence[str], params) -> np.ndarray`

物理パラメータ値の辞書とパラメータ定義に基づき、フィッティングアルゴリズムの内部で使用される q 空間のベクトルにパックします。pscale="log" のパラメータは log10 変換されます。

引数:
- values: パラメータ名と値の辞書。
- names: パックするパラメータ名のシーケンス。
- params: パラメータ定義の辞書。
戻り値: パックされた q ベクトル。

`unpack_factory(base_values: Mapping[str, float], names: Sequence[str], params, eop: float) -> Callable[[Sequence[float]], Dict[str, float]]`

q 空間のベクトルから物理パラメータ値の辞書にアンパックする関数を生成するファクトリ関数です。pscale="log" のパラメータは 10**q 変換されます。

引数:
- base_values: 変更されない基本パラメータ値の辞書。
- names: アンパックするパラメータ名のシーケンス。
- params: パラメータ定義の辞書。
- eop: 光学フォノンエネルギー。
戻り値: unpack(q) 関数。

`apply_cli_defaults(defaults, args) -> list[dict]`

コマンドライン引数で指定された初期値 (--p0_...) や固定パラメータ (--fix) をデフォルトのパラメータ定義に適用します。

引数:
- defaults: デフォルトパラメータ定義のリスト。
- args: コマンドライン引数オブジェクト。
戻り値: 適用後のパラメータ定義のリスト。

`read_params(args) -> Tuple[dict, str]`

パラメータファイルを読み込みます。ファイルが存在しない場合は、デフォルト値に基づいて新規作成し保存します。

引数:
- args: コマンドライン引数オブジェクト。
戻り値: (params_dict, paramfile_path) のタプル。
- params_dict: 読み込まれたパラメータ定義の辞書。
- paramfile_path: パラメータファイルのパス。

`prediction_band_delta(x: np.ndarray, p_fit: Mapping[str, float], free_names: Sequence[str], cov, params, nsigma: float, rel_step: float, abs_step: float) -> Tuple[np.ndarray, Optional[np.ndarray], Optional[np.ndarray], Optional[np.ndarray]]`

フィッティング結果に基づいて予測バンドを計算します。ヤコビアン行列を数値的に計算し、共分散行列と組み合わせて予測の不確かさを推定します。

引数:
- x: 予測対象の独立変数 (温度)。
- p_fit: フィッティングされたパラメータの辞書。
- free_names: 最適化されたパラメータ名のシーケンス。
- cov: パラメータの共分散行列。
- params: パラメータ定義の辞書。
- nsigma: 予測バンドのシグマ値 (例: 1.0 で1σ)。
- rel_step: ヤコビアン計算の相対ステップサイズ。
- abs_step: ヤコビアン計算の絶対ステップサイズ。
戻り値: (y0, y_lower, y_upper, sigma_y) のタプル。
- y0: モデルの予測値。
- y_lower: 予測バンドの下限。
- y_upper: 予測バンドの上限。
- sigma_y: 予測の標準偏差。

`setup_fit_axes(title: str) -> Tuple[plt.Figure, plt.Axes, plt.Axes]`

フィッティング結果と残差をプロットするための matplotlib の図と2つの軸 (上段: フィット、下段: 残差) をセットアップします。

引数:
- title: グラフのタイトル。
戻り値: (fig, ax1, ax2) のタプル。

`draw_fit_residual(fig, ax1, ax2, x, y, y_fit, residual, title=None, y_lower=None, y_upper=None) -> None`

フィッティング結果と残差を既存の matplotlib の図と軸に描画します。予測バンドもオプションで描画できます。

引数:
- fig, ax1, ax2: 描画対象の matplotlib オブジェクト。
- x: 独立変数 (温度)。
- y: 実測従属変数 (log10 移動度)。
- y_fit: フィットされた従属変数。
- residual: 残差。
- title: グラフタイトル (オプション)。
- y_lower, y_upper: 予測バンドの下限・上限 (オプション)。

`save_fit_png(path, x, y, y_fit, residual, title, show, y_lower=None, y_upper=None) -> None`

フィッティング結果のPNG画像を保存し、オプションで表示します。

引数:
- path: 保存パス。
- x, y, y_fit, residual, title, show, y_lower, y_upper: draw_fit_residual() と同様。

`save_animation(path, x, y, frames) -> None`

フィッティングの進捗を示すアニメーションGIFを保存します。

引数:
- path: 保存パス。
- x: 独立変数 (温度)。
- y: 実測従属変数 (log10 移動度)。
- frames: 各イテレーションの描画データを格納した辞書のリスト。

`write_excel(path, tables) -> None`

複数のPandasデータフレームをExcelファイルの異なるシートに書き込みます。

引数:
- path: 保存パス。
- tables: シート名とPandasデータフレームの辞書。

`write_params(path, params, values=None, stderr=None) -> None`

パラメータファイル (CSV) を書き込みます。フィッティング結果のパラメータ値や標準誤差を含めることができます。

引数:
- path: 保存パス。
- params: パラメータ定義の辞書。
- values: フィットされたパラメータ値の辞書 (オプション)。
- stderr: 各パラメータの標準誤差の辞書 (オプション)。

`make_stderr_value_space(stderr_q, p_fit, free_names, params) -> Dict[str, Optional[float]]`

q 空間で計算された標準誤差を、物理パラメータの値空間に近似的に変換します。特に pscale="log" のパラメータで重要です。

引数:
- stderr_q: q 空間の標準誤差のリスト。
- p_fit: フィッティングされた物理パラメータの辞書。
- free_names: 最適化されたパラメータ名のシーケンス。
- params: パラメータ定義の辞書。
戻り値: パラメータ名と値空間の標準誤差の辞書。

`mode_read(args, x, mu) -> None`

read モードの処理を実行します。データを読み込み、プロットしてPNG画像を保存します。

引数:
- args: コマンドライン引数オブジェクト。
- x: 温度のNumPy配列。
- mu: 移動度のNumPy配列。

`mode_lfit(args, x, mu, params, paramfile) -> None`

lfit モードの処理を実行します。線形最小二乗法でフィッティングを行い、パラメータファイルとPNG画像を保存します。

引数:
- args: コマンドライン引数オブジェクト。
- x: 温度のNumPy配列。
- mu: 移動度のNumPy配列。
- params: パラメータ定義の辞書。
- paramfile: パラメータファイルのパス。

`mode_fit(args, x_all, mu_all, params, paramfile) -> None`

fit モードの処理を実行します。非線形最小二乗法でフィッティングを行い、結果、アニメーション、診断情報を保存します。

引数:
- args: コマンドライン引数オブジェクト。
- x_all: 全温度データ。
- mu_all: 全移動度データ。
- params: パラメータ定義の辞書。
- paramfile: パラメータファイルのパス。

`mode_weight(args, x, mu, params) -> None`

weight モードの処理を実行します。各散乱機構の寄与率を計算し、プロットしてPNG画像を保存します。

引数:
- args: コマンドライン引数オブジェクト。
- x: 温度のNumPy配列。
- mu: 移動度のNumPy配列。
- params: パラメータ定義の辞書。

`mode_sim(args, x, mu, params) -> None`

sim モードの処理を実行します。現在のパラメータでシミュレーションを行い、結果をプロットしてPNG画像を保存します。

引数:
- args: コマンドライン引数オブジェクト。
- x: 温度のNumPy配列。
- mu: 移動度のNumPy配列。
- params: パラメータ定義の辞書。

`mode_model_select(args, x, mu, params) -> None`

model_select モードの処理を実行します。現在は mode_fit() を呼び出します。

引数:
- args: コマンドライン引数オブジェクト。
- x: 温度のNumPy配列。
- mu: 移動度のNumPy配列。
- params: パラメータ定義の辞書。

`build_parser() -> argparse.ArgumentParser`

コマンドライン引数パーサーを構築し、返します。

戻り値: argparse.ArgumentParser オブジェクト。

`main() -> None`

プログラムのエントリポイントです。コマンドライン引数を解析し、指定されたモードに応じて適切な処理関数を呼び出します。

ライセンス

コードからはライセンス情報は確認できません。

著者

コードからは著者情報は確認できません。

使用方法

コマンドライン引数

基本的な使い方

各 --mode の詳細

read モード

lfit / llsq モード

fit モード

sim モード

weight モード

model_select モード

入出力ファイル

入力データファイル

パラメータファイル

出力ファイル

アルゴリズムとモデル

ホール移動度モデル

フィッティングアルゴリズム

パラメータのスケーリング

関数リファレンス

stem_from_infile(infile: str | Path) -> str

auto_paramfile(infile: str | Path) -> str

auto_outfile(infile: str | Path) -> str

save_log(path: str | Path) -> Path

save_done(path: str | Path) -> None

read_xy_hall(args) -> Tuple[np.ndarray, np.ndarray, str, str]

get_inv_mu_components(T: np.ndarray, p: Mapping[str, float], Eop: float) -> Tuple[Dict[str, float], np.ndarray]

mobility_model(T: np.ndarray, p: Mapping[str, float]) -> np.ndarray

model(x: np.ndarray, p: Mapping[str, float]) -> np.ndarray

lfit_design_matrix(T: np.ndarray, Eop: float) -> np.ndarray

fit_mask(T: np.ndarray, tmin: float, tmax: float) -> np.ndarray

values_from_params(params) -> Dict[str, float]

optid1_names(params) -> list[str]

pscale_of(params, name: str) -> str

positive_floor_from_param(params, name: str, default: float = 1e-300) -> float

pack(values: Mapping[str, float], names: Sequence[str], params) -> np.ndarray

unpack_factory(base_values: Mapping[str, float], names: Sequence[str], params, eop: float) -> Callable[[Sequence[float]], Dict[str, float]]

apply_cli_defaults(defaults, args) -> list[dict]

read_params(args) -> Tuple[dict, str]

prediction_band_delta(x: np.ndarray, p_fit: Mapping[str, float], free_names: Sequence[str], cov, params, nsigma: float, rel_step: float, abs_step: float) -> Tuple[np.ndarray, Optional[np.ndarray], Optional[np.ndarray], Optional[np.ndarray]]

setup_fit_axes(title: str) -> Tuple[plt.Figure, plt.Axes, plt.Axes]

draw_fit_residual(fig, ax1, ax2, x, y, y_fit, residual, title=None, y_lower=None, y_upper=None) -> None

save_fit_png(path, x, y, y_fit, residual, title, show, y_lower=None, y_upper=None) -> None

save_animation(path, x, y, frames) -> None

write_excel(path, tables) -> None

write_params(path, params, values=None, stderr=None) -> None

make_stderr_value_space(stderr_q, p_fit, free_names, params) -> Dict[str, Optional[float]]

mode_read(args, x, mu) -> None

mode_lfit(args, x, mu, params, paramfile) -> None

mode_fit(args, x_all, mu_all, params, paramfile) -> None

mode_weight(args, x, mu, params) -> None

mode_sim(args, x, mu, params) -> None

mode_model_select(args, x, mu, params) -> None

build_parser() -> argparse.ArgumentParser

main() -> None

ライセンス

著者

各 `--mode` の詳細

`read` モード

`lfit` / `llsq` モード

`fit` モード

`sim` モード

`weight` モード

`model_select` モード

`stem_from_infile(infile: str | Path) -> str`

`auto_paramfile(infile: str | Path) -> str`

`auto_outfile(infile: str | Path) -> str`

`save_log(path: str | Path) -> Path`

`save_done(path: str | Path) -> None`

`read_xy_hall(args) -> Tuple[np.ndarray, np.ndarray, str, str]`

`get_inv_mu_components(T: np.ndarray, p: Mapping[str, float], Eop: float) -> Tuple[Dict[str, float], np.ndarray]`

`mobility_model(T: np.ndarray, p: Mapping[str, float]) -> np.ndarray`

`model(x: np.ndarray, p: Mapping[str, float]) -> np.ndarray`

`lfit_design_matrix(T: np.ndarray, Eop: float) -> np.ndarray`

`fit_mask(T: np.ndarray, tmin: float, tmax: float) -> np.ndarray`

`values_from_params(params) -> Dict[str, float]`

`optid1_names(params) -> list[str]`

`pscale_of(params, name: str) -> str`

`positive_floor_from_param(params, name: str, default: float = 1e-300) -> float`

`pack(values: Mapping[str, float], names: Sequence[str], params) -> np.ndarray`

`unpack_factory(base_values: Mapping[str, float], names: Sequence[str], params, eop: float) -> Callable[[Sequence[float]], Dict[str, float]]`

`apply_cli_defaults(defaults, args) -> list[dict]`

`read_params(args) -> Tuple[dict, str]`

`prediction_band_delta(x: np.ndarray, p_fit: Mapping[str, float], free_names: Sequence[str], cov, params, nsigma: float, rel_step: float, abs_step: float) -> Tuple[np.ndarray, Optional[np.ndarray], Optional[np.ndarray], Optional[np.ndarray]]`

`setup_fit_axes(title: str) -> Tuple[plt.Figure, plt.Axes, plt.Axes]`

`draw_fit_residual(fig, ax1, ax2, x, y, y_fit, residual, title=None, y_lower=None, y_upper=None) -> None`

`save_fit_png(path, x, y, y_fit, residual, title, show, y_lower=None, y_upper=None) -> None`

`save_animation(path, x, y, frames) -> None`

`write_excel(path, tables) -> None`

`write_params(path, params, values=None, stderr=None) -> None`

`make_stderr_value_space(stderr_q, p_fit, free_names, params) -> Dict[str, Optional[float]]`

`mode_read(args, x, mu) -> None`

`mode_lfit(args, x, mu, params, paramfile) -> None`

`mode_fit(args, x_all, mu_all, params, paramfile) -> None`

`mode_weight(args, x, mu, params) -> None`

`mode_sim(args, x, mu, params) -> None`

`mode_model_select(args, x, mu, params) -> None`

`build_parser() -> argparse.ArgumentParser`

`main() -> None`