# 可変パラメータ最適化プログラム作成手順書  
― tkoptimize_flex フレームワークによる複数ピーク・モデル数未定問題 ―

---

## 1. 本手順書の目的

本手順書は、  
`tklib.tksci.tkoptimize_flex` フレームワークを用いて、

- **パラメータ数が事前に決まらない**
- **データからモデル構造（ピーク数など）を決定する**
- **線形＋非線形の混在した最適化問題**

を扱う **可変パラメータ最適化プログラム**を新規に作成するための  
**実践的な開発手順**をまとめたものです。

対象例としては、

- 複数ピークのスペクトルフィッティング
- 成分数不明の分解問題
- イベント数未定の時系列解析

などを想定しています。

---

## 2. 固定次元最適化との違い（重要）

---

### 2.1 固定次元最適化

- パラメータ数が事前に決まっている
- fit_config.xlsx により定義
- optimize_mup.py 型

---

### 2.2 可変次元最適化

- パラメータ数が **データ依存**
- モデル構造を **最適化前に決定**
- fit_config.xlsx を使わない
- optimize_peakfit.py 型

👉  
**「最適化する前に、まずモデルを作る」**  
という発想が最重要です。

---

## 3. 全体構造（可変次元版）

---

可変パラメータ最適化では、以下の構成を取ります。

---

- optimize_xxx.py  
  メインプログラム（最適化シナリオ）

- optimize_xxx_mf.py  
  可変次元対応 mf（共通仕様アダプタ）

- model_xxx.py  
  モデル定義・ピーク探索・数式実装

- （任意）peaksearch 等の補助ライブラリ  
  データ解析用

---

## 4. 開発全体の流れ（概要）

---

1. **データ解析によりモデル構造を決定**
2. **フィッティングパラメータを動的に生成**
3. **mf 層に可変パラメータ情報を渡す**
4. **tkoptimize_flex で最適化を実行**
5. **尤度・履歴・結果を可視化**

---

## 5. Step 1  
## モデル定義ライブラリ（model_xxx.py）の作成

---

### 5.1 このファイルの役割

model_xxx.py は、

- データからモデル構造を決定
- フィッティングパラメータを生成
- 最適化用の関数 y(x) を定義

する **可変次元最適化の核心**です。

---

### 5.2 必須要素

---

#### (1) モデル関数

例（複数ピーク）：

$$
y(x)
=
c_0
+
\sum_{i=1}^{N_{\mathrm{peak}}}
I_i \, f(x; x_{c,i}, w_i)
$$

ここで、

- \( N_{\mathrm{peak}} \) は **データから決定**
- \( I_i \) は線形係数
- \( x_{c,i}, w_i \) は非線形パラメータ

---

#### (2) ピーク探索（モデル構造決定）

- スムージング
- 微分
- 閾値判定

などにより、

- ピーク数
- 初期位置
- 初期幅

を推定します。

---

#### (3) フィッティングパラメータ生成関数

以下を **リストとして動的に生成**します。

---

- varname  
- unit  
- pk_scale  
- optid  
- linid  
- x0  
- dx  
- kmin  
- kmax  
- kpenalty  

👉  
**fit_config.xlsx は使いません**

---

#### (4) y(x) 計算関数

最適化エンジンから唯一呼ばれる関数です。

---

- 入力：全パラメータ配列  
- 出力：y 値リスト（2次元リスト）

---

## 6. Step 2  
## 可変次元 mf（optimize_xxx_mf.py）の作成

---

### 6.1 mf の役割（固定次元との違い）

---

| 項目 | 固定次元 mf | 可変次元 mf |
|---|---|---|
| パラメータ定義 | ファイル | **モデル生成** |
| fit_config.xlsx | 使用 | **使用しない** |
| varname | 固定 | **動的** |
| 初期値 | ファイル | **データ由来** |

---

### 6.2 必須関数

---

- initialize(app)
- initialize_minimize_func(app)
- init_fit(app, cfg)
- read_input_data(app, infile, cfg)
- cal_ylist(app, xk_all, x_list, ...)

---

### 6.3 核心：init_fit の実装方針

---

init_fit では、

1. tkFit_mxy オブジェクトを生成
2. model_xxx.py で生成した
   - varname
   - x0
   - optid
   - linid
   - 制約
   を fit にコピー
3. 初期 simplex を **パラメータ数に応じて自動生成**

---

👉  
**tkoptimize_flex 側は「次元が変わることを知らない」**

---

## 7. Step 3  
## メインプログラム（optimize_xxx.py）の作成

---

### 7.1 このファイルの役割

---

- CLI 引数定義
- mode 分岐
- 最適化シナリオ制御
- 可視化・後処理

---

### 7.2 推奨 mode 構成

---

- plot  
  入力データ表示

- search  
  モデル構造（ピーク数）決定

- init  
  初期化（履歴クリア等）

- fit  
  非線形最適化

- lfit  
  線形最小二乗のみ

- scan  
  パラメータスキャン（尤度評価）

---

### 7.3 CLI 引数の動的追加（重要）

---

可変次元の場合、

- varname が実行時に決まる

ため、以下を行います。

---

- モデル生成後に
- for ループで
- app.add_argument を追加

---

👉  
**ピーク数が変わっても CLI から制御可能**

---

## 8. Step 4  
## 最適化の実行とアルゴリズム選択

---

### 8.1 利用可能な手法

---

- 線形最小二乗法
- 独自 SIMPLEX 法
- SciPy minimize（Nelder–Mead 等）
- GA / Swarm / 多点探索

---

### 8.2 可変次元問題での推奨

---

| 段階 | 推奨手法 |
|---|---|
| 初期探索 | peak search |
| 初期安定化 | 線形最小二乗 |
| 非線形最適化 | SIMPLEX |
| 多峰性 | GA / Swarm |

---

## 9. Step 5  
## 尤度関数による誤差評価（重要）

---

### 9.1 考え方

---

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

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

と解釈できます。

---

### 9.2 可変次元でも有効な方法

---

- 共分散行列は使用しない
- 各パラメータを固定してスキャン
- 他パラメータは再最適化

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

---

👉  
**非線形・非対称な誤差分布をそのまま可視化可能**

---

## 10. 開発時の実践的注意点

---

- 自動化しすぎない  
  → search 結果は必ず目視確認
- 初期値の妥当性を重視
- dx（simplex サイズ）を適切に設定
- ピーク数が多すぎる場合は人間が介入

---

## 11. まとめ

---

可変パラメータ最適化は、

- 単なる数値最適化ではなく
- **モデル構造決定＋最適化の問題**

です。

tkoptimize_flex フレームワークは、

- 可変次元
- 線形＋非線形
- 尤度評価
- 探索と最適化の分離

を **自然に扱えるよう設計されています**。

本手順書に従えば、

> 「ピーク数が分からない問題を、  
> 破綻せず・再現性を保って解く」

最適化プログラムを構築できます。

---