# 汎用最適化フレームワーク tkoptimize_flex  
設計概要・利用方法・拡張機能（尤度評価・進化的最適化・最適化アルゴリズム）ガイド

---

## 1. はじめに

本ドキュメントは、  
`tklib.tksci.tkoptimize_flex` を核とする **汎用最適化フレームワーク**について、

- 全体構造と設計思想  
- 提供される主要機能  
- 起動方法・基本的な引数体系  
- 新しい最適化プログラムを作成する際のファイル構成  
- **尤度関数によるパラメータ誤差評価機能**  
- **GA / Swarm / レプリカ交換モンテカルロ（REMC）等の進化的最適化**  
- **利用可能な最適化アルゴリズムの体系**

を体系的に説明します。

本フレームワークは「研究用・実験解析用」に設計されており、  
**最適化結果の解釈・再現性・可視化**を重視しています。

---

## 2. フレームワーク全体構成

---

### 2.1 レイヤ構造（概念）

本フレームワークは、以下のレイヤに分離されています。

- アプリケーション層（用途特化）
- 共通仕様アダプタ層
- 最適化フレームワーク核
- フィッティングエンジン抽象
- モデル API 層
- 物理モデル実装層

---

### 2.2 代表的なファイル構成

---

- optimize_xxx.py  
  用途特化の最適化アプリケーション（CLI・モード分岐）

- optimize_xxx_mf.py  
  フレームワーク共通仕様との接続用アダプタ

- tklib.tksci.tkoptimize_flex.py  
  汎用最適化フレームワークの核

- tklib.tksci.tkFit_mxy_flex.py  
  多変数最適化エンジン抽象クラス

- model_xxx_model.py  
  最適化用モデル API（y(x) を返す）

- model_xxx.py  
  物理モデル実装・分解・可視化

---

### 2.3 設計思想（重要）

---

本フレームワークは、以下の思想に基づいて設計されています。

1. **最適化アルゴリズムと物理モデルの完全分離**
2. **設定・履歴・結果の完全な再現性**
3. **線形＋非線形のハイブリッド最適化**
4. **人間が途中介入できる探索プロセス**
5. **HPC・長時間計算を前提とした運用**
6. **正規分布仮定に依らない誤差評価**

---

## 3. tkoptimize_flex の主な機能

---

### 3.1 提供される最適化モード

---

- 非線形最小二乗フィッティング
- 線形最小二乗（部分線形化）
- Lasso / Ridge による変数選択
- 単一変数最適化（fit1）
- パラメータスキャン（scan / mapping）
- ランダムサンプリング
- シミュレーションモード（最適化なし）

---

### 3.2 履歴・再現性管理

---

- history.xlsx  
  各反復のパラメータと評価値を保存

- fitXXXX.xlsx  
  特定反復時点の入出力データ保存

- ini / prm / csv  
  設定とフィッティングパラメータの分離保存

---

### 3.3 可視化・対話機能

---

- matplotlib / tkinter 両対応
- 実データ・初期値・最適化結果の同時表示
- 探索途中の停止
- パラメータ依存性の逐次可視化

---

## 4. 利用可能な最適化アルゴリズム

---

本フレームワークでは、**単一の最適化アルゴリズムに依存せず**、  
目的・モデルの性質に応じて複数の手法を選択できます。

---

### 4.1 SciPy minimize() に基づく非線形最適化

---

`scipy.optimize.minimize()` をラップする形で、  
以下のアルゴリズムが利用可能です（SciPy の仕様に準拠）。

- Nelder–Mead  
- Powell  
- CG  
- BFGS  
- L-BFGS-B  
- TNC  
- COBYLA  
- SLSQP  

これらは主に、

- 連続パラメータ
- 比較的滑らかな目的関数
- 局所最適解探索

に適しています。

---

### 4.2 線形最小二乗法（Linear Least Squares）

---

本フレームワークは、  
**線形最小二乗法を非線形最適化と統合**しています。

- モデル中の「線形係数」を自動抽出
- 非線形パラメータを固定した上で線形最小二乗を実行
- 係数を元のパラメータ配列に再統合

これにより、

- 非線形最適化の次元削減
- 初期値依存性の低減
- 計算安定性の向上

が得られます。

---

### 4.3 独自実装 SIMPLEX 法

---

SciPy 実装とは別に、  
**独自実装の SIMPLEX 法（Nelder–Mead 系）**が組み込まれています。

特徴は以下の通りです。

- 初期 simplex を明示的に制御可能
- 反復過程の詳細な可視化
- 途中停止・再開が容易
- 研究用途向けの挙動制御

特に、

- 非滑らかな目的関数
- 勾配が不安定な物理モデル
- 初期値依存性を調べたい場合

に有効です。

---

### 4.4 アルゴリズム選択の指針

---

| 問題の性質 | 推奨アルゴリズム |
|---|---|
| 線形モデル | 線形最小二乗 |
| 弱非線形 | BFGS / L-BFGS-B |
| 強非線形 | SIMPLEX / Nelder–Mead |
| 多峰性 | GA / Swarm |
| 誤差評価 | 尤度スキャン |

---

## 5. 尤度関数によるパラメータ誤差評価

---

### 5.1 基本的な考え方

---

本フレームワークで最小化される評価関数は、

$$
f(\mathbf{x})
=
\sum_i w_i \left(
y_i^{\mathrm{obs}} - y_i^{\mathrm{cal}}(\mathbf{x})
\right)^2
+
\text{penalty}
$$

であり、ガウス誤差を仮定すると

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

に相当します。

---

### 5.2 共分散行列を用いない理由

---

- 非線形モデルでは尤度分布が非対称になりやすい  
- 指数関数・べき則・乗算型モデルでは  
  ガウス近似が破綻しやすい  

そのため、本フレームワークでは  
**共分散行列による誤差評価を必須機能としていません**。

---

### 5.3 1変数尤度スキャン（Profile Likelihood）

---

各パラメータについて、以下を評価します。

$$
\Delta f(x_i)
=
\min_{\mathbf{x}_{j \neq i}} f(\mathbf{x})
-
f_{\min}
$$

この方法により、

- 非対称な誤差分布
- 裾の重い分布
- 非線形性に起因する歪み

を直接可視化できます。

---

### 5.4 実装状況と注記

---

- 尤度関数自体は **完全に定義済み**
- scan / mapping 機構により  
  **実質的な尤度スキャンは可能**
- 専用モード（profile / likelihood）は **未整理**

#### 未完成の注記

---

- Δf = 1 等の信頼区間ガイド線
- 自動正規化
- 専用プロット形式

これらは今後の整理・拡張対象です。

---

## 6. 進化的・確率的最適化手法

---

### 6.1 遺伝的アルゴリズム（GA）

---

- 集団ベース探索
- 突然変異
- 世代更新

は **実装済み**です。

#### 注記

---

- 標準 GA API としては未整理
- 最適化・サンプリングモードと統合された形で提供

---

### 6.2 Swarm / 粒子群最適化

---

- 多点並列探索
- 広域探索能力
- 局所最適解回避

は **実用レベルで使用可能**です。

#### 注記

---

- PSO として明示的に分離された API は未整備
- 実体は population-based optimizer

---

### 6.3 レプリカ交換モンテカルロ（REMC）

---

#### 実装思想

---

- 多初期条件
- 並列探索
- 探索空間ジャンプ

という **REMC 的思想は組み込まれています**。

#### 未完成の注記

---

- 温度スケジュールの明示的実装なし
- detailed balance は未保証
- 現状は  
  **「REMC 的挙動を示す進化的最適化」**

として理解してください。

---

## 7. 新しい最適化プログラムを作成する手順

---

### 7.1 作成が必要なファイル

---

- optimize_xxx.py  
- optimize_xxx_mf.py  
- model_xxx_model.py  
- model_xxx.py  
- *_fit_config.xlsx  
- *_arg_config.xlsx  

---

### 7.2 推奨開発フロー

---

1. 物理モデル単体で動作確認  
2. モデル API を作成  
3. mf アダプタを最小構成で実装  
4. メインプログラムで mode 分岐  
5. 必要に応じて尤度スキャン・進化的探索を追加  

---

## 8. おわりに

---

本フレームワークは、

- 最適解探索
- 非線形物理モデル理解
- 誤差分布の可視化

を **一貫した思想のもとで扱う研究基盤**です。

尤度評価、進化的最適化、  
多様な最適化アルゴリズムを組み合わせることで、  
単なる数値最適化を超えた解析が可能になります。

本ドキュメントが、  
本フレームワークを用いた新しい最適化プログラム開発の  
確かな指針となることを願っています。

---