シミュレーション設定

シミュレーション設定 (Simulation settings) は、PyBaMM の Simulation に渡すキーワード引数（var_pts、submesh_types、spatial_methods、 solver）をモデルまたはパラメータ化モデルに永続的に保存するオプションの設定バッグです。モデルが実行されるたびに Ionworks がこれらを自動的に再適用します。モデルの方程式自体はメッシュやソルバーに依存しませんが、フィット済みのパラメータセットが 必要とする 設定は依存する場合があります。例えば、表面近傍で急峻な勾配を持つ固相拡散係数をフィットすると、粒子メッシュを表面付近で細かくクラスタリングした細かいメッシュが必要になります。PyBaMM の粗いデフォルトに戻ってしまうと電圧が正しく再現されません。シミュレーション設定を使うと、こうした要件をモデルまたはパラメータセットに一度だけ紐付け、下流のすべてのシミュレーションがそのグリッドとソルバーで実行されるようにできます。

使いどころ

以下のいずれかに該当する場合にシミュレーション設定を付与します:

パラメータが非デフォルトのメッシュ（例: Chebyshev1DSubMesh を使った細かい粒子メッシュ）でフィットされていて、そのメッシュを対応するパラメータ化モデルの実行時に必ず適用したい場合。
特定のモデル構成が数値的な安定性のために特定のソルバーやソルバー許容誤差を必要とする場合。

モデルが PyBaMM のデフォルト設定で正しく動く場合は何も設定する必要はありません。simulation_settings を未設定（または None）のままにしておけば、PyBaMM 側の default_var_pts / default_submesh_types / default_spatial_methods / default_solver が使われます。

設定できる項目

すべてのフィールドはオプションで、省略した項目はモデルのデフォルトにフォールバックします。

フィールド	型	用途
`var_pts`	`{空間変数: int}`	空間変数ごとのメッシュ点数（例: `{"r_n": 16, "r_p": 16}`）。
`submesh_types`	`{ドメイン: submesh config}`	ドメイン（例: `"negative particle"`）ごとにシリアライズした `pybamm.MeshGenerator`。
`spatial_methods`	`{ドメイン: spatial method config}`	ドメインごとにシリアライズした `pybamm.SpatialMethod`。
`solver`	`dict` または `pybamm.BaseSolver`	シリアライズした `pybamm.BaseSolver.to_config()` ペイロード（ソルバークラス名 + 許容誤差 / オプション）。

保存されるブロックに含まれるクラス名は書き込み時に静的な許可リストと照合されます。下記に挙げられていないクラスは保存されずに BAD_REQUEST として拒否されます。 var_pts で許可される空間変数: x_n、x_s、x_p、r_n、r_p、R_n、 R_p、y、z、および複合電極用の _prim / _sec バリアント。値は正の整数でなければなりません。許可されている submesh クラス: Uniform1DSubMesh、Exponential1DSubMesh、 Chebyshev1DSubMesh、UserSupplied1DSubMesh、SpectralVolume1DSubMesh、 SymbolicUniform1DSubMesh、SubMesh0D。許可されている spatial method クラス: FiniteVolume、SpectralVolume、 ZeroDimensionalSpatialMethod。許可されているソルバークラス: IDAKLUSolver、AlgebraicSolver、 NonlinearSolver。CasadiSolver と ScipySolver は PyBaMM で非推奨になっており、永続化できません。ionworkspipeline.Simulation の背後で使われる高速なデフォルトソルバーについては Ionworks DAE ソルバーを参照してください。

geometry は永続化できません。ジオメトリのオーバーライドを保存しようとすると、書き込み時に simulation_settings.geometry is not supported として拒否されます。ジオメトリのデシリアライズは JSON から任意の PyBaMM 式ツリーシンボルを再構築するため、上記のクラス許可リストでは境界を定められないからです。代わりに var_pts / submesh_types / spatial_methods / solver を永続化し、ジオメトリのオーバーライドが必要な場合は実行時に simulation_kwargs で渡してください。

優先順位

シミュレーション時、Ionworks は次の固定された優先順位で永続化された設定をマージします。上位のレイヤーがキー単位で優先されます:

runtime simulation_kwargs  >  parameterized model  >  model  >  pybamm defaults

メッシュ系のキー（var_pts、submesh_types、spatial_methods）はキー単位でマージされます。さらにモデル自身の PyBaMM デフォルトの上にキー単位で重ねられるため、Simulation に渡されるマップは常に完全な形になります。したがってパラメータ化モデルはグリッド全体を再指定せずに r_n と r_p だけを細かくでき、実行時の simulation_kwargs が r_p のみを指定した場合も、永続化された r_n が失われることはなくその 1 エントリだけが上書きされます。
solver は最上位のレイヤーで丸ごと置き換えられます。部分的な solver は解釈が曖昧なためです。
実行時に明示的に渡された simulation_kwargs は常に優先されます。 1 回の実行をデバッグするために永続化された設定を書き換える必要はありません。

パイプラインの design objective（設計目的関数） のみ例外です。ここでは解決後の var_pts と solver だけが適用されます。design objective は design-optimization コンバータが組み込むシンボリックな submesh を必要とするため、永続化された submesh_types / spatial_methods は意図的に適用されません。プロトコルシミュレーションおよびモデル / パラメータ化モデルのシミュレーション経路では 4 つのキーすべてが適用されます。

API から設定を紐付ける

client.model と client.parameterized_model はどちらも create と update で simulation_settings フィールドを受け付けます。サブクライアントの詳細は Python API リファレンスを参照してください。

モデルに紐付ける

from ionworks import Ionworks

client = Ionworks()

model = client.model.create({
    "name": "DFN with refined particle mesh",
    "config": {"type": "DFN"},
    "simulation_settings": {
        "var_pts": {"r_n": 20, "r_p": 20},
    },
})

パラメータ化モデルに紐付ける

パラメータ固有の設定はベースモデルの設定より優先されるため、フィット済みパラメータのメッシュ細分化はここに置くのが一般的です:

param_model = client.parameterized_model.create("your-cell-spec-id", {
    "name": "NMC622 fitted parameters",
    "model_id": model.id,
    "parameters": {
        "Negative electrode diffusivity [m2.s-1]": 3.3e-14,
    },
    "simulation_settings": {
        "var_pts": {"r_n": 32, "r_p": 32},
        "solver": {
            "type": "IDAKLUSolver",
            "atol": 1e-8,
            "rtol": 1e-6,
        },
    },
})

後から設定を更新できます:

client.parameterized_model.update(
    "your-cell-spec-id",
    param_model.id,
    {"simulation_settings": {"var_pts": {"r_n": 40, "r_p": 40}}},
)

部分更新は フィールド 単位であり、simulation_settings の内部ではありません。送信した内容が保存済みブロック全体を置き換えます。上記の呼び出しでは、create 時に永続化した solver が破棄されます。1 つのキーだけを変更したい場合は、現在の設定を取得してローカルでマージし、ブロック全体を送信してください:

current = client.parameterized_model.get(param_model.id).simulation_settings or {}

client.parameterized_model.update(
    "your-cell-spec-id",
    param_model.id,
    {"simulation_settings": {**current, "var_pts": {"r_n": 40, "r_p": 40}}},
)

優先順位で説明したキー単位のマージは、シミュレーション時にモデル / パラメータ化モデル / 実行時という レイヤー 間で適用されるもので、書き込み対象の行に対して更新内容をマージするものではありません。

"simulation_settings": None を渡すとフィールドがクリアされ、ベースモデルの設定（ベースモデルにも無い場合は PyBaMM のデフォルト）を継承します。

パイプラインから設定を紐付ける

ionworks_schema のモデルクラス（GITTModel、MSMRFullCellModel、MSMRHalfCellModel、LumpedSPMR、 LumpedSPMeR、ECM など）は simulation_settings 引数を受け付け、パイプライン投入時にモデル設定と一緒にシリアライズされます:

import pybamm
import ionworks_schema as iws

model = iws.models.GITTModel(
    options={"working electrode": "positive"},
    simulation_settings=iws.models.SimulationSettings(
        var_pts={"r_p": 32},
        submesh_types={
            "positive particle": pybamm.MeshGenerator(
                pybamm.Chebyshev1DSubMesh,
            ),
        },
    ),
)

生の MeshGenerator / BaseSolver オブジェクトはパイプライン側で正規化された JSON 形式に自動的にシリアライズされるので、同じ設定が API を経由しても保持されます。

シリアライズされた形式

内部的にはシミュレーション設定はフラットな JSON dict として保存されます。これは client.model.get(...).simulation_settings が返す形式でもあり、データベース列に保存されている形式でもあります。典型的なブロックは次のようになります:

{
  "var_pts": {"r_n": 20, "r_p": 20},
  "submesh_types": {
    "negative particle": {
      "$type": "type",
      "class": "pybamm.meshes.one_dimensional_submeshes.Chebyshev1DSubMesh",
      "submesh_params": {}
    }
  },
  "solver": {
    "type": "IDAKLUSolver",
    "atol": 1e-8,
    "rtol": 1e-6
  }
}

この dict をそのまま渡すこともできますし、SimulationSettings スキーマクラスから to_config() を呼んで同じペイロードを生成させることもできます。

はじめに

基本コンセプト

運用

データ

モデル構築

パイプライン