目的関数 - Ionworks Studio

DataFit には 2 つの関連する要素があります。

目的関数 (iws.objectives.*) — どの実験でモデル出力と比較するか。
コスト (iws.costs.*) — 点ごとの差をどう 1 つのスカラに集約するか。

各コストの数学的背景は目的関数 (英語ガイド) を参照してください。

利用可能なコスト関数

スキーマ	数式	用途
`iws.costs.SSE()`	$\sum_i r_i^2$	デフォルト。全オプティマイザと互換
`iws.costs.MSE()`	$\frac{1}{N}\sum_i r_i^2$	スケールを意識した平均二乗残差
`iws.costs.RMSE()`	$\sqrt{\frac{1}{N}\sum_i r_i^2}$	解釈可能な単位。スカラのみ(残差配列型のオプティマイザでは使えない)
`iws.costs.MAE()`	$\frac{1}{N}\sum_i \lvert r_i \rvert$	外れ値に頑健
`iws.costs.Wasserstein()`	$\frac{1}{N}\sum_i \lvert \tilde y_{\text{model},i} - \tilde y_{\text{data},i} \rvert$	時系列の点ごとではなく分布(ソート済みサンプル)同士を一致させる。`position_variable` と `weight_variable` を設定すると重み付き点群モードに切り替わる

最尤推定には iws.costs.GaussianLogLikelihood を使用してください — 変数ごとのノイズ標準偏差を受け取るか、フィッティングパラメータと併せて推定することもできます。ベイズ推定や MAP 推定に適したガウス負対数尤度を生成します。

コストをフィットに組み込む

import ionworks_schema as iws

fit = iws.DataFit(
    objectives={
        "1C": iws.objectives.CurrentDriven(
            data_input="file:.../1C.csv",
            options={"model": {"type": "SPMe"}},
        ),
    },
    parameters={
        "Negative particle diffusivity [m2.s-1]": iws.Parameter(
            "Negative particle diffusivity [m2.s-1]",
            initial_value=2e-14,
            bounds=(1e-14, 1e-13),
        ),
    },
    cost=iws.costs.RMSE(),
)

cost を省略すると、オプティマイザのデフォルトコスト関数(通常は最小二乗形式)が使われます。

Wasserstein 重み付き点群モード

iws.costs.Wasserstein() はデフォルトでは目的変数ごとにモデルとデータのサンプルを比較します(ソート点ごとの比較、均一な重み)。position_variable と weight_variable を両方指定すると 重み付き点群モード に切り替わり、一方が位置を、もう一方が(符号を除去・再正規化した)重みを供給して、目的ごとに 1 回 Wasserstein-1 距離を計算します。 dQ/dV のピークを電圧上で揃えるなど、サンプル単位の値ではなく 位置で密度を一致させたい 場合に使います。

import ionworks_schema as iws

fit = iws.DataFit(
    objectives={
        "ocp": iws.objectives.MSMRFullCell(
            data_input="file:.../ocp.csv",
            options={
                "model": {"type": "MSMR"},
                "objective variables": [
                    "Differential capacity [Ah/V]",
                    "Voltage [V] (dQdU)",
                ],
            },
        ),
    },
    parameters={...},
    cost=iws.costs.Wasserstein(
        position_variable="Voltage [V] (dQdU)",
        weight_variable="Differential capacity [Ah/V]",
    ),
)

position_variable と weight_variable は同時に指定する必要があります — 片方だけ指定すると検証エラーになります。重みは絶対値が取られ内部で再正規化されるため、dQ/dV の符号規則は問題になりません。このモードでは残差配列出力は利用できません。

利用可能な目的関数

スキーマ	用途
`iws.objectives.CurrentDriven(data_input=..., options={...})`	電流駆動の時系列電圧データ(ドライブサイクル、カスタム負荷)
`iws.objectives.Pulse(data_input=..., options={...})`	パルス実験 — GITT、HPPC、ICI — 特徴量抽出のバリエーションも選択可能
`iws.objectives.OCPHalfCell(electrode=..., data_input=...)`	ハーフセル OCP 曲線
`iws.objectives.MSMRHalfCell(...)`	ハーフセルデータへの MSMR パラメータフィット
`iws.objectives.MSMRFullCell(...)`	フルセルデータへの MSMR パラメータフィット。目的変数として `Differential voltage [V/Ah]` と `Differential capacity [Ah/V]` をサポート
`iws.objectives.ElectrodeBalancing(...)`	フルセル放電からの化学量論窓
`iws.objectives.EIS(...)`	電気化学インピーダンススペクトル
`iws.objectives.Resistance(...)`	パルスデータから抽出した直流抵抗
`iws.objectives.CalendarAgeing(...)` / `iws.objectives.CycleAgeing(...)`	劣化曲線

複数を組み合わせるには DataFit.objectives に dict[str, objective] を渡します。

自動構築されるソルバーのチューニング

シミュレーションを伴う目的関数 (CurrentDriven、Pulse、CalendarAgeing、CycleAgeing、MSMRFullCell など) は、明示的な solver が指定されていない場合に IonworksSolver を自動構築します。チューニング済みのデフォルトをすべて書き直すことなく一部だけを上書きしたい場合は、simulation_kwargs の中で solver_kwargs を渡します:

ネストされた options はデフォルトの IDAKLU オプションにマージされます。例えば {"options": {"compile": True}} はモデルコンパイルだけを有効化し、他のチューニング済みオプションはそのまま維持します。
その他のトップレベルキー (atol、rtol、on_extrapolation など) は、対応するデフォルトのソルバー kwargs を上書きします。

solver_kwargs は、明示的な solver が指定された場合は警告とともに無視されます — その場合はソルバーインスタンス上で直接設定してください。また、モデルのデフォルトソルバーが IDAKLU ベースでない場合も無視されます。

import ionworks_schema as iws

fit = iws.DataFit(
    objectives={
        "1C": iws.objectives.CurrentDriven(
            data_input="file:.../1C.csv",
            options={
                "model": {"type": "SPMe"},
                "simulation_kwargs": {
                    "solver_kwargs": {
                        "options": {"compile": True},
                        "atol": 1e-8,
                    },
                },
            },
        ),
    },
    parameters={...},
)

事前に compile を有効化する ({"options": {"compile": True}}) と、一度きりのコンパイルコストと引き換えに繰り返しの評価が高速になります — 同じ目的関数をフィットやスイープ中に何度も解くようなケースで有効です。

ほとんどのオプティマイザでは SSE が最も無難です — 残差配列形式とスカラ形式の両方を持つため、すべてのアルゴリズムと互換性があります。スケール非依存の報告が必要な場合は MSE / RMSE を使用してください。

目的関数 (理論)

残差形式と正準形式、MLE の解釈 (英語ガイド)。

データフィッティング概要

目的関数・パラメータ・オプティマイザの組み合わせ方。

​利用可能なコスト関数

​コストをフィットに組み込む

​Wasserstein 重み付き点群モード

​利用可能な目的関数

​自動構築されるソルバーのチューニング

目的関数 (理論)

データフィッティング概要

利用可能なコスト関数

コストをフィットに組み込む

Wasserstein 重み付き点群モード

利用可能な目的関数

自動構築されるソルバーのチューニング