メインコンテンツへスキップ
iws.DataFit はパラメータフィッティングを記述します。どの実験と比較するか、どのパラメータを自由にするか、どう探索するかを指定し、パイプラインの 1 要素として送信します。理論(コスト関数、識別可能性、マルチスタート)は データフィッティング (英語ガイド) を参照してください。

最小構成のフィット

DataFit 内の設定ミス(誤ったパラメータ名、不正な目的関数など)は UserConfigurationError として表面化します。ジョブ分類器はこれを Studio 上の Configuration error にマッピングするため、ソルバー失敗と簡単に区別できます。

複数の目的関数

複数の目的関数を渡せば、複数の実験(異なる C レートや温度での放電など)に同時にフィットできます。
各目的関数は単一の結合コストに寄与します。

オプティマイザ

iws.optimizersDataFit で利用可能なオプティマイザを提供します。問題に合うものを選んでください。 コスト関数の選択肢は 目的関数 を参照してください。
サロゲートオプティマイザ(BayesianOptimizationTuRBOSOBER)はオプションの surrogate インストールエクストラが必要で、torchbotorchgpytorch が追加されます。
これらは遅延インポートされるため、集団ベースまたは SciPy のオプティマイザのみを使用するインストールでは、この依存関係のコストは発生しません。

高コストな並列問題向けの TuRBO

各評価が高コストで、利用可能なワーカーがある場合、TuRBO は 1 ラウンドごとに候補のバッチを提案し、現在の最良点の周囲に信頼領域を適応させます。ワーカー数は実行エンジンが所有するようになったため(下記の注記を参照)、最初のラウンドで利用可能なワーカーをすべて活用できるよう、ウォームアップ(n_initial)を DataFit.run(execution=ExecutionConfig(...)) に渡すキャパシティに合わせてください。
DataFitparallelnum_workersmax_batch_size を受け付けなくなりました(また AskTellOptimizerasync_mode を受け付けません)。並列性は実行エンジンが所有し、実行時に DataFit.run(execution=ExecutionConfig(...)) で構成します。削除されたフィールドを含む保存済みコンフィグはパース時に自動的に移行されるため、既存の保存済みフィットに対する対応は不要です。
サロゲートオプティマイザで有用な algorithm_options のキーには、n_initial(ウォームアップサンプル数)、noise_floor"low""standard"、または (lo, hi) の区間)、TuRBO 用の信頼領域制御(tr_length_inittr_length_mintr_length_maxtr_success_tolerancetr_failure_tolerancen_candidates)があります。

厳密なオプション検証

algorithm_options は選択したオプティマイザに対して検証されます。未知のキー(タイポを含む)はサイレントに無視されるのではなく、投入時に拒否されるため、誤設定されたフィットがデフォルト動作のまま実行されることはなく、早期に失敗します。
この検証は、生の辞書を渡しても型付きラッパー(CMAESOptionsPSOOptionsDEOptionsXNESOptionsXNES オプティマイザ用。iws.optimizers.XNES() / AskTellOptimizer(method="XNES") で利用可能)、BayesianOptimizationOptionsSOBEROptionsTuRBOOptions)を渡しても同じように適用されます。エディタの自動補完と各オプションのインラインドキュメントが利用できるため、型付きラッパーの使用を推奨します。唯一の例外は CMAESOptions で、こちらは pycma 自体のオプション体系へのパススルーのままです。

ネイティブオプティマイザは SciPy 形式のキーワード引数を受け付けません

ネイティブな ask/tell オプティマイザ(CMAESDifferentialEvolutionPSOXNESBayesianOptimizationTuRBOSOBER、および基盤となる AskTellOptimizer)は、コンストラクタの未知のトップレベルキーワード引数を拒否します。maxiterpopsizeseedtol といった SciPy 形式のキーは受け付けられません。以前はこれらは何の効果もありませんでしたが、現在はコンストラクタで直ちに検証エラーになるため、設定ミスのあるフィットは黙って見過ごされず即座に表面化します:
SciPy 形式のキーは引き続き SciPy パススルーのオプティマイザ(ScipyMinimizeScipyLeastSquaresScipyDifferentialEvolution)に対して使用します。これらは内部の SciPy 呼び出しにそのまま転送されます:
要点としては、反復回数・個体数・許容誤差の上限は名前付きの ask/tell 引数(max_iterationspopulation_sizepopulation_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)の定式化で、外側は集約された目的関数 g(xouter)=minxinnerf(xouter,xinner)g(x_\text{outer}) = \min_{x_\text{inner}} f(x_\text{outer}, x_\text{inner}) を見ることになり、内側は条件付きで容易にフィットできるパラメータを吸収します。 Nested を使うのは以下のような場合です:
  • あるパラメータ部分集合がモデルに線形(またはほぼ線形)に入り、境界付き最小二乗の内側ソルブで閉形式的に解けて、残りが非線形である場合。
  • 完全な同時探索が悪条件で遅いが、縮約された外側問題は素直に振る舞う場合。
  • 大域的な外側探索(例: CMA-ES や Nelder-Mead)と、各点における高速な局所内側改良を組み合わせたい場合。
parameters は、このレベルの外側オプティマイザが制御するフィットパラメータ名を並べます。DataFit の残りすべての自由パラメータは inner に委譲されます。inner はさらに深いネストのために、それ自体が Nested になっていても構いません。
集約目的関数は、内側最適解が一意でない箇所で非平滑になり得ます。そのため外側スロットには導関数フリーまたは有限差分のオプティマイザ(Nelder-MeadCMAESDifferentialEvolution)が推奨されます。サンプラーは構築時に拒否されます — 両スロットともオプティマイザである必要があります。

ScipyLsqLinear による境界付き線形内側ソルブ

内側パラメータが残差に線形に入る場合(例: 境界付き係数と基底関数の線形結合)には、Nested の内側ソルバーに iws.optimizers.ScipyLsqLinear を組み合わせます。Gauss-Newton で反復するのではなく、scipy.optimize.lsq_linear を一度呼ぶだけで境界付き最適解に到達し、連続する外側評価をまたいでアクティブ集合をウォームスタートするので、集約目的関数は平滑に保たれます:
ScipyLsqLinear は残差が本当に内側パラメータについて線形なときにのみ使ってください。内側残差が非線形な場合は ScipyLeastSquares のままにしてください。

解析的パラメータ Jacobian

外側または内側スロットが最小二乗オプティマイザ(ScipyLeastSquares または ScipyLsqLinear)である場合、パイプラインはモデルのパラメータ感度から構築した解析的な残差 Jacobian J(x)=r/xJ(x) = \partial r / \partial x を供給します。これが SciPy の有限差分 Jacobian を置き換えるので、各イテレーションは O(nparams)O(n_\text{params}) 回のソルブではなく、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 を参照してください。

データフィッティング (理論)

コスト関数の数学、識別可能性、マルチスタート戦略 (英語ガイド)。

目的関数

データ形状に応じたコストの選び方。

正則化

ガウス事前分布でフィットを安定化。

感度解析

実際に拘束されているパラメータを定量化。