parameter-optimization

パラメーター最適化

目標

材料シミュレーションのキャリブレーションに向けて、実験を設計し、パラメーターの影響度を順位付けし、最適化戦略を選択するワークフローを提供します。

要件

• Python 3.10 以降
• 外部依存関係なし（Python 標準ライブラリのみを使用）

収集する入力

スクリプトを実行する前に、ユーザーから次の情報を収集してください。

入力	説明	例
パラメーターの範囲	各パラメーターの単位付き最小値／最大値	kappa: [0.1, 10.0] W/mK
評価予算	許容されるシミュレーションの最大回数	50 runs
ノイズレベル	シミュレーション出力の確率性	low、medium、high
制約	実行可能性のルールまたは禁止領域	kappa + mobility < 5

判断の指針

DOE 手法の選択

Is dimension <= 3 AND full coverage needed?
├── YES → Use factorial
└── NO → Is sensitivity analysis the goal?
    ├── YES → Use quasi-random (preferred; "sobol" is accepted but deprecated)
    └── NO → Use lhs (Latin Hypercube)

手法	最適な用途	避けるべき場合
lhs	一般的な探索、中程度の次元数（3～20）	正確なグリッド網羅が必要な場合
quasi-random	感度分析、一様な網羅（推奨）	非常に高次元の場合（>20）
sobol	quasi-random の非推奨エイリアス（警告が表示されます）	新しいコード（quasi-random を使用してください）
factorial	低次元（<4）、すべての頂点が必要な場合	高次元（指数関数的に増加します）

Factorial のサンプル数： factorial グリッドでは、パラメーターごとに levels 個の等間隔の値を使用し、ちょうど levels ** params 個のサンプルが生成されます。--levels で解像度を明示的に設定してください（例：--params 2 --levels 4 -> 16 サンプル）。代わりに --budget を使うと、スクリプトは levels = round(budget ** (1/params)) を逆算し、実際のサンプル数が指定した予算と異なる場合は警告を表示します（例：--budget 20 --params 2 では実際に 16 サンプルが生成されます）。設計を正確にするには、完全累乗数（--budget 16）を指定するか、できれば --levels を使用してください。

オプティマイザーの選択

Is dimension <= 10 AND budget <= 100?
├── YES → Bayesian Optimization
└── NO → Is dimension <= 20?
    ├── YES → CMA-ES
    └── NO → Random Search with screening

ノイズレベル	推奨事項
低	導関数が利用できる場合は勾配ベース、利用できない場合はベイズ最適化
中	ノイズモデルを用いたベイズ最適化
高	進化的アルゴリズムまたはロバストなベイズ最適化

スクリプトの出力（JSON フィールド）

スクリプト	出力フィールド
scripts/doe_generator.py	samples、method、coverage（count、dimension。factorial の場合は levels とトップレベルの requested_budget／note も含む）
scripts/optimizer_selector.py	recommended、expected_evals、notes
scripts/sensitivity_summary.py	ranking、notes
scripts/surrogate_builder.py	model_type、metrics（mse、cv_error、output_variance）、notes

ワークフロー

1. scripts/doe_generator.py で DOE を生成します
2. DOE のサンプル点で シミュレーションを実行します（ユーザーが実施）
3. scripts/sensitivity_summary.py で 感度を要約します
4. scripts/optimizer_selector.py を使って オプティマイザーを選択します
5. （任意） scripts/surrogate_builder.py でサロゲートを適合させます

CLI の例

# Generate 20 LHS samples for 3 parameters
python3 scripts/doe_generator.py --params 3 --budget 20 --method lhs --json

# Full factorial with 4 levels per parameter (2 params -> 16 samples)
python3 scripts/doe_generator.py --params 2 --levels 4 --method factorial --json

# Rank parameters by sensitivity scores
python3 scripts/sensitivity_summary.py --scores 0.2,0.5,0.3 --names kappa,mobility,W --json

# Get optimizer recommendation for 3D problem with 50 eval budget
python3 scripts/optimizer_selector.py --dim 3 --budget 50 --noise low --json

# Build surrogate model from simulation data
python3 scripts/surrogate_builder.py --x 0,1,2 --y 10,12,15 --model rbf --json

対話型ワークフローの例

ユーザー：FEM シミュレーションの熱伝導率と熱拡散率をキャリブレーションする必要があります。シミュレーションは約 30 回実行できます。

エージェントのワークフロー：

1. パラメーターは 2 つと特定 → --params 2
2. 予算は 30 → --budget 30
3. 一般的な探索には LHS を使用します：

   python3 scripts/doe_generator.py --params 2 --budget 30 --method lhs --json
   

4. ユーザーがシミュレーションを実行し、出力を提供した後、感度を要約します：

   python3 scripts/sensitivity_summary.py --scores 0.7,0.3 --names conductivity,diffusivity --json
   

5. オプティマイザーを推奨します：

   python3 scripts/optimizer_selector.py --dim 2 --budget 30 --noise low --json
   

エラー処理

エラー	原因	解決方法
params must be positive	次元がゼロまたは負です	ユーザーに有効なパラメーター数を尋ねます
budget must be positive	予算がゼロまたは負です	ユーザーに現実的なシミュレーション予算を尋ねます
argument --method: invalid choice: <value> (choose from lhs, sobol, quasi-random, factorial)	無効なメソッドです（argparse）	意思決定ガイダンスを使って有効なメソッドを選びます
could not convert string to float: <token>	--scores／--x／--y に数値以外の値が含まれています	0.1,0.2,0.3 の形式に整えます
scores must be a comma-separated list	--scores の入力が空です	数値を少なくとも 1 つ指定します

検証チェックリスト

• doe_generator.py の coverage.count の正確な値を記録し、意図した設計と一致することを確認しました。factorial の場合は、count == levels ** params を確認し、note／requested_budget の不一致警告が出ていないこと（または実際の件数が許容範囲内であること）も確認しました。
• 選択した --method が、実際の次元／目的に対する意思決定ガイダンスに合致することを確認し、非推奨の sobol エイリアスではなく quasi-random を使用しました（出力に DeprecationWarning がないこと）。
• optimizer_selector.py の recommended 戦略と expected_evals を記録し、計画が提示された評価予算内で実行可能となるよう expected_evals <= budget を確認しました。
• sensitivity_summary.py の ranking を記録し、感度の上位値が < 0.1（「すべての感度が低い」という注記）かどうかを確認しました。その場合はランキングを過度に解釈せず、出力メトリックを見直しました。
• サロゲートのフィッティングでは、品質を学習データ内の mse ではなく、交差検証誤差である metrics.cv_error で判断しました。特に rbf では、構造上 mse がほぼゼロになるため注意し、cv_error を metrics.output_variance と比較して、サロゲートが定数平均のベースラインを上回ることを確認しました。
• 報告された cv_error が有限の数値（NaN ではない）であること、つまり、交差検証に十分なサンプルがあることを確認しました（poly：n > degree+1、rbf：n >= 3）。

よくある落とし穴と誤った判断

つい選びがちな近道	なぜ間違っているか／どうすべきか
「RBF サロゲートの mse が約 0 なので、モデルは優れています。」	RBF は厳密補間器です。学習データ内の mse は構造上ほぼゼロになるため、汎化性能については何も示しません。metrics.cv_error で適合度を判断し、output_variance と比較してください。
「--budget 20 で factorial を指定したので、サンプルを 20 個得られました。」	Factorial は予算ではなく levels ** params に従います。--budget 20 --params 2 では 16 個のサンプルが生成され、note／警告が出ます。意図した設計の件数を正確に指定するには --levels を使用してください。
「sobol を使えば、真の Sobol 低偏差列が得られます。」	sobol は非推奨のエイリアスであり、DeprecationWarning が出ます。真の Sobol 列ではなく、簡略化された黄金比加法漸化式を使用します。quasi-random を使用してください。本番環境で Sobol を使う場合は scipy.stats.qmc を使用してください。
「オプティマイザーの推奨は単なる助言なので、予算は関係ありません。」	推奨は次元と予算の両方に基づきます（BO は dim<=10 AND budget<=100 の場合のみ）。また、expected_evals は予算を上限とします。両方を記録し、計画が実際の予算内に収まることを確認してください。
「感度スコアが 1 つ最も高いので、そのパラメーターが支配的です。」	スクリプトは渡されたスコアを並べ替えるだけで、感度そのものは計算しません。上位スコアが < 0.1 の場合は、すべての感度が低いと示します。ランキングを信頼する前に、実際のスクリーニング／Sobol 解析からスコアを取得してください。
「エラーなく JSON が出力されたので、結果は有効です。」	正常終了が意味するのは、入力の解析に成功したことだけです。出力を信頼する前に、設計サイズ、expected_evals <= budget、有限の cv_error、およびサロゲートが output_variance を上回ることを確認してください。

セキュリティ

入力の検証

• sensitivity_summary.py は、--names を [a-zA-Z_][a-zA-Z0-9_ .-]*（最大 200 文字）で検証し、加工されたパラメーター名によるシェルのメタ文字の注入を防ぎます
• 数値リストの入力はすべて有限数として検証されます（NaN／Inf は拒否されます）
• カンマ区切りの値リストには上限が設けられています（スコアは 10,000 件、サロゲートデータは 100,000 件）。これにより、リソースの枯渇を防ぎます
• doe_generator.py は次元を 1,000、予算を 1,000,000 に制限します。optimizer_selector.py は次元を 100,000、予算を 10,000,000 に制限します
• --method は固定の許可リスト（lhs、quasi-random／sobol）に照らして検証されます。sobol は受け付けられますが、非推奨の quasi-random の別名です
• --noise は固定の許可リスト（low、medium、high）に照らして検証されます
• --model（サロゲートの種類）は固定の許可リスト（rbf、poly）に照らして検証されます
• --levels（要因計画のグリッド解像度）は、[2, 1000] の範囲の整数として検証されます

ファイルアクセス

• スクリプトは外部ファイルを読み込みません。すべての入力は CLI 引数で指定します
• スクリプトは stdout（JSON 出力）のみに書き込みます。エージェントが明示的に Write ツールを使用しない限り、ファイルは作成されません

ツールの制限

• Read：スクリプトのソース、参照資料、ユーザーデータファイルの確認に使用します
• Write：DOE のサンプル計画、感度ランキング、最適化アルゴリズムの推奨結果の保存に使用します。書き込み先はユーザーの作業ディレクトリ内に限定されます
• Grep/Glob：関連ファイルの特定や参照の検索に使用します
• スキルの allowed-tools から Bash を除外し、ユーザー指定のパラメーター名や制約を処理する際にエージェントが任意のコマンドを実行するのを防ぎます

安全対策

• eval()、exec()、動的なコード生成は使用しません
• すべてのサブプロセス呼び出しで明示的な引数リストを使用します（shell=True は使用しません）
• ツールの対象範囲を縮小し（Bash を使用不可にすることで）、エージェントの操作を読み取りと書き込みのみに制限します
• パラメーター名は使用前にサニタイズされ、加工された識別子によるインジェクションを防ぎます

制限事項

• リアルタイム最適化には対応していません：スクリプトは推奨結果を提示するものであり、ライブ最適化ループは実行しません
• サロゲートは軽量です：surrogate_builder.py は標準ライブラリのみを使用して、実際の 1 次元最小二乗多項式（poly）またはガウス RBF 補間（rbf）をフィッティングし、残差 mse、一つ抜き交差検証の cv_error、データの output_variance を正直に報告します。本番環境での使用には scipy／scikit-learn／GPyTorch をご利用ください。rbf では、構成上、サンプル内の mse はほぼゼロになります（厳密補間）。適合性の評価には cv_error を使用してください
• シミュレーションの自動実行には対応していません：ユーザーが外部でシミュレーションを実行し、その結果を提供する必要があります

参考資料

• references/doe_methods.md - DOE 手法の詳細な比較
• references/optimizer_selection.md - 最適化アルゴリズムの詳細
• references/sensitivity_guidelines.md - 感度分析結果の解釈
• references/surrogate_guidelines.md - サロゲートモデルの選択

バージョン履歴

• v1.2.2（2026-06-24）：DOE、最適化、感度、サロゲートの各スクリプトを根拠に基づいて使用できるよう、検証チェックリストとよくある落とし穴および誤った合理化のセクションを追加
• v1.2.0（2026-06-23）：サロゲートの実際のフィッティング（poly 最小二乗法、rbf 補間）と、正直な mse／cv_error／output_variance を導入。要因計画の --levels を明示し、予算との不一致に関する警告を追加。BO の次元上限を dim<=10 に統一。セキュリティ／エラー処理／出力フィールドのドキュメントをスクリプトの挙動に合わせて修正
• v1.1.0（2024-12-24）：ドキュメント、判断のガイダンス、会話形式の例を強化
• v1.0.0：主要スクリプトを含む初回リリース