# optimize_mup.py 使い方マニュアル  
― 移動度の温度依存性解析を例とした固定パラメータ数最適化 ―

---

## 1. はじめに

本マニュアルは、  
`tkoptimize_flex` フレームワークを用いた **固定パラメータ数の最適化プログラム**  
`optimize_mup.py` の使用方法をまとめたものです。

本プログラムは主に、

- 移動度 μ(T) の温度依存性解析
- 散乱機構モデル（phonon, impurity, grain boundary など）の同定
- 線形＋非線形ハイブリッド最適化
- 尤度関数に基づく誤差評価

を目的として設計されています。

---

## 2. プログラムの位置づけ

---

### 2.1 optimize_mup.py の役割

- **アプリケーション層**に相当
- 解析シナリオ（mode）を制御
- 入力データ・設定ファイルを受け取り、
  `optimize_mup_mf.py` を介して  
  `tkoptimize_flex` を起動

---

### 2.2 対応する問題設定

- パラメータ数は **事前に決まっている**
- 物理モデル（散乱モデル）は固定
- 可変次元最適化（peakfit）とは対照的

---

## 3. 必要なファイル構成

---

解析には、以下のファイルが必要です。

---

- optimize_mup.py  
  メインプログラム

- optimize_mup_mf.py  
  共通仕様アダプタ（mf）

- mobility_pi_model.py  
  最適化用モデル API

- mobility_pi.py  
  物理モデル実装

- *_fit_config.xlsx  
  フィッティングパラメータ定義ファイル

- *_arg_config.xlsx  
  起動時引数の既定値定義

- 入力データファイル（例：xlsx）

---

## 4. 基本的な起動形式

---

python optimize_mup.py [mode] [options]

---

mode により、実行内容が切り替わります。

---

## 5. Step 1  
## 入力データの確認（plot モード）

---

### 目的

- μ(T) データが正しく読めるか確認
- 温度範囲・単位の妥当性確認

---

### 起動例

---

python optimize_mup.py plot  
--infile mobility_data.xlsx  
--xlabel T  
--ylabel mu  

---

### この段階で確認すること

- 温度軸が昇順になっている
- 外れ値・欠損値がない
- 単位系がモデルと整合している

---

## 6. Step 2  
## 初期条件の確認（sim モード）

---

### 目的

- 最適化を行わず、
  現在のパラメータ設定で μ(T) を計算
- 初期値・モデル構造の妥当性を確認

---

### 起動例

---

python optimize_mup.py sim  
--infile mobility_data.xlsx  
--model pi  
--method simplex  

---

### 調整対象

- 初期値（fit_config.xlsx）
- パラメータ範囲（kmin / kmax）
- 有効な散乱機構の選択

---

### 注意

- この段階で大きく外れている場合、
  次に進まない

---

## 7. Step 3  
## 線形パラメータの最適化（lfit モード）

---

### 目的

- 線形パラメータ（prefactor 等）を安定化
- 非線形最適化の初期条件を改善

---

### 起動例

---

python optimize_mup.py lfit  
--infile mobility_data.xlsx  

---

### 内部処理

- 非線形パラメータを固定
- 線形最小二乗法で
  寄与係数を一括決定

---

### 確認ポイント

- 不自然な符号・値になっていないか
- 物理的に意味のあるスケールか

---

## 8. Step 4  
## 非線形最適化（fit モード）

---

### 目的

- 散乱モデル全体のパラメータを最適化
- 評価関数（尤度）を最小化

---

### 起動例（独自 SIMPLEX）

---

python optimize_mup.py fit  
--infile mobility_data.xlsx  
--method simplex  
--nmaxiter 500  
--tol 1.0e-6  

---

### SciPy 最適化を使う場合

---

python optimize_mup.py fit  
--infile mobility_data.xlsx  
--method nelder-mead  

---

### 多峰性が疑われる場合

---

python optimize_mup.py fit  
--infile mobility_data.xlsx  
--method ga  

---

### 実行中の注意点

- 履歴（history.xlsx）を確認
- 明らかな発散があれば停止

---

## 9. Step 5  
## パラメータスキャン・尤度評価（scan モード）

---

### 目的

- 非線形パラメータの誤差分布を評価
- 共分散行列に依らない誤差解析

---

### 起動例（1変数尤度スキャン）

---

python optimize_mup.py scan  
--infile mobility_data.xlsx  
--scan_param alpha  
--scan_min 0.1  
--scan_max 1.0  
--scan_n 50  

---

### 解釈

---

最小化している評価関数は、

$$
f(\mathbf{x}) \approx -2 \log \mathcal{L}(\mathbf{x})
$$

と解釈できるため、

$$
\Delta f(x_i)
=
f(x_i) - f_{\min}
$$

をプロットすることで、

- 非対称な誤差
- 上下で異なる信頼区間

を直接評価できます。

---

## 10. 推奨される実行順序

---

1. plot  
   → 入力データ確認  

2. sim  
   → 初期条件・モデル妥当性確認  

3. lfit  
   → 線形パラメータ安定化  

4. fit  
   → 非線形最適化  

5. scan  
   → 尤度による誤差評価  

---

## 11. peakfit との違い（参考）

---

| 項目 | optimize_mup | optimize_peakfit |
|---|---|---|
| パラメータ数 | 固定 | 可変 |
| fit_config.xlsx | 使用 | 使用しない |
| モデル決定 | 事前 | データ駆動 |
| 主用途 | 物理モデル解析 | データ分解 |

---

## 12. おわりに

---

optimize_mup.py は、

- 物理モデル主導
- 固定パラメータ数
- 厳密なモデル解釈

に適した最適化プログラムです。

optimize_peakfit.py と対で理解することで、  
`tkoptimize_flex` フレームワークの全体像がより明確になります。

本マニュアルが、  
移動度解析および関連する物性解析の  
再現性・信頼性向上に役立つことを願っています。

---