iws.DataFit はパラメータフィッティングを記述します。どの実験と比較するか、どのパラメータを自由にするか、どう探索するかを指定し、パイプラインの 1 要素として送信します。理論(コスト関数、識別可能性、マルチスタート)は データフィッティング (英語ガイド) を参照してください。
最小構成のフィット
DataFit 内の設定ミス(誤ったパラメータ名、不正な目的関数など)は UserConfigurationError として表面化します。ジョブ分類器はこれを Studio 上の Configuration error にマッピングするため、ソルバー失敗と簡単に区別できます。複数の目的関数
複数の目的関数を渡せば、複数の実験(異なる C レートや温度での放電など)に同時にフィットできます。オプティマイザ
iws.optimizers は DataFit で利用可能なオプティマイザを提供します。問題に合うものを選んでください。
コスト関数の選択肢は 目的関数 を参照してください。
サロゲートオプティマイザ(これらは遅延インポートされるため、集団ベースまたは SciPy のオプティマイザのみを使用するインストールでは、この依存関係のコストは発生しません。
BayesianOptimization、TuRBO、SOBER)はオプションの surrogate インストールエクストラが必要で、torch、botorch、gpytorch が追加されます。高コストな並列問題向けの TuRBO
各評価が高コストで、利用可能なワーカーがある場合、TuRBO は 1 ラウンドごとに候補のバッチを提案し、現在の最良点の周囲に信頼領域を適応させます。ワーカー数は実行エンジンが所有するようになったため(下記の注記を参照)、最初のラウンドで利用可能なワーカーをすべて活用できるよう、ウォームアップ(n_initial)を DataFit.run(execution=ExecutionConfig(...)) に渡すキャパシティに合わせてください。
DataFit は parallel、num_workers、max_batch_size を受け付けなくなりました(また AskTellOptimizer は async_mode を受け付けません)。並列性は実行エンジンが所有し、実行時に DataFit.run(execution=ExecutionConfig(...)) で構成します。削除されたフィールドを含む保存済みコンフィグはパース時に自動的に移行されるため、既存の保存済みフィットに対する対応は不要です。algorithm_options のキーには、n_initial(ウォームアップサンプル数)、noise_floor("low"、"standard"、または (lo, hi) の区間)、TuRBO 用の信頼領域制御(tr_length_init、tr_length_min、tr_length_max、tr_success_tolerance、tr_failure_tolerance、n_candidates)があります。
厳密なオプション検証
algorithm_options は選択したオプティマイザに対して検証されます。未知のキー(タイポを含む)はサイレントに無視されるのではなく、投入時に拒否されるため、誤設定されたフィットがデフォルト動作のまま実行されることはなく、早期に失敗します。
CMAESOptions、PSOOptions、DEOptions、XNESOptions(XNES オプティマイザ用。iws.optimizers.XNES() / AskTellOptimizer(method="XNES") で利用可能)、BayesianOptimizationOptions、SOBEROptions、TuRBOOptions)を渡しても同じように適用されます。エディタの自動補完と各オプションのインラインドキュメントが利用できるため、型付きラッパーの使用を推奨します。唯一の例外は CMAESOptions で、こちらは pycma 自体のオプション体系へのパススルーのままです。
ネイティブオプティマイザは SciPy 形式のキーワード引数を受け付けません
ネイティブな ask/tell オプティマイザ(CMAES、DifferentialEvolution、PSO、XNES、BayesianOptimization、TuRBO、SOBER、および基盤となる AskTellOptimizer)は、コンストラクタの未知のトップレベルキーワード引数を拒否します。maxiter、popsize、seed、tol といった SciPy 形式のキーは受け付けられません。以前はこれらは何の効果もありませんでしたが、現在はコンストラクタで直ちに検証エラーになるため、設定ミスのあるフィットは黙って見過ごされず即座に表面化します:
ScipyMinimize、ScipyLeastSquares、ScipyDifferentialEvolution)に対して使用します。これらは内部の SciPy 呼び出しにそのまま転送されます:
max_iterations、population_size、population_convergence_tol)に、アルゴリズム内部の設定は algorithm_options に、SciPy のキーワードは Scipy* オプティマイザに、というように使い分けてください。
目的関数 (objective) の厳密な検証
DataFit.objectives(および Validation.objectives)は、各エントリを目的関数の type をキーとする判別共用体 (discriminated union) に対して検証します。設定ミスは送信時に明確な ValidationError として拒否され、黙って無視されたり、後続の不明瞭なランタイムクラッシュとして現れたりすることはありません。
目的関数の インスタンス(例: iws.objectives.CurrentDriven(...))はこれまで通り動作します。位置引数・キーワード引数のどちらのコンストラクタも維持されています。厳密検証のルールは生の設定 辞書 を渡したときに適用され、これは JSON からロードした設定や to_config() で生成した設定でよく使われます:
生の設定辞書では、データのキーは
data_input ではなく data です。Python コンストラクタは data_input キーワード引数として公開しますが、to_config() はこれを data にシリアライズします。そのため、手書きの辞書や JSON 設定では data を使用してください。辞書で data_input を渡すと、未知のキーとして拒否されるようになりました。DesignObjective の設定は DataFit のランタイムパスでは受け付けられません。これらは独立した design-optimization パイプラインで実行されます。DesignObjective 辞書を DataFit.from_schema に渡すと、後段でクラッシュする代わりに UserConfigurationError が発生し、design-optimization パイプラインを案内します。
マルチスタート
複数の局所最小を持つ問題では、異なる初期点から複数回最適化を実行します。初期推測サンプラーの選択
デフォルトのマルチスタートはラテン超方格(Latin Hypercube)サンプリングを使い、パラメータ境界全体に初期推測を均等に分散させます。別のサンプリング方式に変えたい場合は、initial_guess_sampler でサンプラーを指定します。たとえばベースライン比較として一様サンプリングを使う場合:
サンプラーは送信時に識別ユニオン(discriminated union)で検証されます。未知のサンプラー
type や認識されないキーを渡すと、ランの途中でなく送信時点で即座に ValidationError が送出されます。
ネスト型(変数射影)フィット
iws.optimizers.Nested は二段構成のオプティマイザです。外側オプティマイザは選んだパラメータ部分集合を探索し、外側の各試行点ごとに内側オプティマイザが残りのパラメータについて最適化まで実行されます。これは変数射影(variable projection)の定式化で、外側は集約された目的関数 を見ることになり、内側は条件付きで容易にフィットできるパラメータを吸収します。
Nested を使うのは以下のような場合です:
- あるパラメータ部分集合がモデルに線形(またはほぼ線形)に入り、境界付き最小二乗の内側ソルブで閉形式的に解けて、残りが非線形である場合。
- 完全な同時探索が悪条件で遅いが、縮約された外側問題は素直に振る舞う場合。
- 大域的な外側探索(例: CMA-ES や
Nelder-Mead)と、各点における高速な局所内側改良を組み合わせたい場合。
parameters は、このレベルの外側オプティマイザが制御するフィットパラメータ名を並べます。DataFit の残りすべての自由パラメータは inner に委譲されます。inner はさらに深いネストのために、それ自体が Nested になっていても構いません。
集約目的関数は、内側最適解が一意でない箇所で非平滑になり得ます。そのため外側スロットには導関数フリーまたは有限差分のオプティマイザ(
Nelder-Mead、CMAES、DifferentialEvolution)が推奨されます。サンプラーは構築時に拒否されます — 両スロットともオプティマイザである必要があります。ScipyLsqLinear による境界付き線形内側ソルブ
内側パラメータが残差に線形に入る場合(例: 境界付き係数と基底関数の線形結合)には、Nested の内側ソルバーに iws.optimizers.ScipyLsqLinear を組み合わせます。Gauss-Newton で反復するのではなく、scipy.optimize.lsq_linear を一度呼ぶだけで境界付き最適解に到達し、連続する外側評価をまたいでアクティブ集合をウォームスタートするので、集約目的関数は平滑に保たれます:
ScipyLsqLinear は残差が本当に内側パラメータについて線形なときにのみ使ってください。内側残差が非線形な場合は ScipyLeastSquares のままにしてください。
解析的パラメータ Jacobian
外側または内側スロットが最小二乗オプティマイザ(ScipyLeastSquares または ScipyLsqLinear)である場合、パイプラインはモデルのパラメータ感度から構築した解析的な残差 Jacobian を供給します。これが SciPy の有限差分 Jacobian を置き換えるので、各イテレーションは 回のソルブではなく、1 回のソルブと 1 回の感度評価で済みます。実務上、これにより勾配ベースの最小二乗フィットは大幅に高速かつロバストになり、特に Nested の変数射影ループ内でノイジーな有限差分ステップの影響を受けにくくなります。
設定は不要です — 目的関数とモデルが対応している場合には解析的 Jacobian が自動的に使用され、そうでない場合はフィットが透過的に有限差分にフォールバックします。有効化されているかはフィットログの using analytic residual Jacobian で確認できます。
ランタイムオプション
iws.DataFit はスキーマを変更せずに最適化ループを調整できる options dict を受け付けます。すべてのキーは任意です。
Ionworks クラスタに送信されるパイプラインは、シミュレーション負荷を抑えるため
skip_objective_callbacks をデフォルトで有効にします。初期および最終フィットのシミュレーション結果を取得したい場合は、options 内で明示的に False を指定してください。目的関数レベルの並列性
DataFit はトップレベルフィールドとして objective_parallelism を公開しており、目的関数レベルのスケジューリングをデバッグ用に上書きできます。これは DataFit の直接の引数であり、ランタイムオプション の options キーではありません。
"auto" のままにしてください。この設定はスケジューリングにのみ影響し、オプティマイザが受け取るコストは変わりません。
モデル失敗のトラブルシューティング
フィット中に目的関数のモデルがセットアップできない、または評価に失敗した場合 — たとえばパラメータセットが不完全、カスタムモデルが離散化できない、初期 SOC 設定に失敗した、などの場合 — パイプラインは該当する目的関数名と原因を明示したModelError を発生させます:
ModelError は汎用の CONFIGURATION_ERROR とは区別されます。失敗したジョブには専用の MODEL_ERROR コードが付与されるため、内部のエラーモニタリングを経由せず、メッセージをそのまま確認できます。修正は通常、欠落しているパラメータの追加、非現実的な境界の見直し、目的関数のモデルオプションの調整など、フィット設定側で行うものであり、Ionworks に報告するものではありません。
すでに分かりやすいエラーはそのまま伝播します: ソルバ側の数値的な失敗は引き続き pybamm.SolverError / SOLVER_ERROR として、パラメータルックアップの失敗は引き続き ParameterNotFoundError として表示されます。これらが評価中に発生した場合は、これまで通りオプティマイザのフォールバック(NaN コスト、ステップのスキップ)で処理されるため、一度の不正な反復でフィット全体が停止することはありません。
結果の取得
result.element_results["fit"] はデータフィットの出力(最適パラメータ値、最終コスト、ログ化された軌跡など)をキーとする dict です。エンドツーエンドの例は packages/ionworks-api/examples/pipeline/datafit.py を参照してください。
データフィッティング (理論)
コスト関数の数学、識別可能性、マルチスタート戦略 (英語ガイド)。
目的関数
データ形状に応じたコストの選び方。
正則化
ガウス事前分布でフィットを安定化。
感度解析
実際に拘束されているパラメータを定量化。