パイプライン入門

バッテリーパラメータ化は、入力パラメータを出力パラメータに変換する パイプライン要素 (pipeline elements) と、それらを連結した パイプライン (pipeline) というシンプルな抽象化に基づいています。この設計により、単純な計算から複雑なデータフィッティングまで、あらゆるパラメータ化ワークフローに柔軟に対応できます。

Pipeline Elements

基本となる構成要素はパイプライン要素です。任意のパイプライン要素は（空でもよい）パラメータ値の集合を受け取り、別のパラメータ値の集合を返します。各要素を順に呼び出すことで、完全なパラメータ集合が得られます。パイプライン要素には 5 種類あります。

Type	Description
DirectEntry	The simplest type—ignores input parameters and returns pre-defined values (e.g., from literature or direct measurements)
Calculation	Computes new parameters based on provided inputs (e.g., calculating maximum particle concentration from capacity, volume fraction, and thickness)
DataFit	Estimates parameters by fitting a model to experimental data
ArrayDataFit	Fits the same model separately at each value of an independent variable (e.g., a separate fit per temperature or per pulse SOC)
Validation	Checks fitted parameters against held-out data

ここに挙げたパイプライン要素の種類および組み込みの計算は網羅的ではありません。詳細は API リファレンスを参照してください。

import ionworkspipeline as iwp

pipeline = iwp.Pipeline([
    iwp.calculations.Capacity("Positive"),
    iwp.calculations.Capacity("Negative"),
    iwp.calculations.CyclableLithium(),
    iwp.calculations.ElectrodeSOH(),
])

result = pipeline.run(parameter_values)

各要素は以下を行います。

パラメータ辞書から入力パラメータを取得
計算を実行
後続の要素から利用可能な出力パラメータを返す

パイプラインをプログラムから組み立てて送信する方法については、Documentation タブの Pipelines → Overview を参照してください。

Naming conventions

Clear Naming

Use descriptive parameter names with units: "Electrode capacity [A.h]" not "cap"

Unit Consistency

Be explicit about unit conversions; use SI units internally

Built-in Calculations

Geometry & Capacity

Electrode geometry, mass, capacity, cyclable lithium, and microstructure

Thermal Properties

Heat capacity, Arrhenius temperature dependence, and thermal modeling

Piecewise Interpolants

Smooth piecewise functions for SOC and temperature-dependent parameters

パイプライン失敗への対処

パイプライン要素は順番に実行されます。ある要素が失敗すると、パイプラインはエラーを報告し、後続の要素は停止します。原因は要素に error_code として記録されます。

`error_code`	意味
`SUBMISSION_FAILED`	要素をワーカーに投入できませんでした（例: 一時的なインフラの問題）。再投入しても安全です。
`EXECUTION_TIMEOUT`	要素が実行時間の上限を超えました。再試行する前に構成を調整してください。
`INTERNAL_ERROR`	要素の実行中に予期しないサーバー側のエラーが発生しました。

失敗したパイプラインの再投入

最初に失敗した要素の error_code が SUBMISSION_FAILED の場合、パイプラインを再投入できます。再投入はその要素をリセットし、パイプラインが停止した箇所から実行を再開します — 完了済みの要素は再実行されません。

Studio
REST API

パイプライン詳細ページを開きます。先頭の失敗が投入エラーの場合、ページ上部の失敗要素のアラートに Resubmit ボタンが表示されます。これをクリックすると、パイプラインをその場で再試行できます。

再投入は汎用のジョブエンドポイントを経由し、パイプラインはそのジョブ ID で識別されます（client.pipeline.get(...) に渡すものと同じ ID です）。

curl -X POST \
  -H "Authorization: Bearer $IONWORKS_API_KEY" \
  https://api.ionworks.com/jobs/{pipeline_id}/resubmit

応答は、要素を含む更新後のパイプラインです。最初に失敗した要素が SUBMISSION_FAILED 状態でない場合は 400 を、パイプラインが存在しない場合は 404 を返します。完全なスキーマについては API リファレンスを参照してください。

その他のエラーコード（タイムアウト、内部エラー、構成の問題）による失敗の場合は、再投入する代わりに、修正した構成で新しいパイプラインを作成してください。

Data Fitting

パイプラインの抽象化は、データフィッティング — モデル予測を実験データと比較することで未知パラメータを推定する処理 — も支えます。DataFit 要素はパイプラインを最適化ループでラップします。

最適化器がパラメータ値を提案する
パイプラインがその値でモデルを実行する
目的関数が予測とデータの一致度を評価する
ベストフィットのパラメータが得られるまで繰り返す

Data Fitting (theory)

Cost functions, identifiability, regularization, and other theory.

Data Fitting (how-to)

Configure and submit data fits with ionworks-schema + ionworks-api.

パイプラインのエラー

パイプライン要素が失敗すると、Studio はその要素を Failed 状態で表示し、エラーメッセージと機械可読な エラーコード を併せて示します。パイプライン一覧でステータスチップにカーソルを合わせるとコードが表示され、失敗した要素を展開すると完全なメッセージを確認できます。同じフィールドは、失敗したジョブやパイプライン要素の API レスポンスでも返されます:

{
  "status": "FAILED",
  "error": "'Negative electrode loading [A.h.cm-2]' not found. Best matches are [...]",
  "error_code": "CONFIGURATION_ERROR",
  "error_detail": {
    "exception_type": "ParameterNotFoundError"
  }
}

エラーコード

error_code フィールドを使うと、エラー文字列を解析することなく失敗の種類に応じて分岐できます:

コード	発生条件	対処方法
`CONFIGURATION_ERROR`	パイプラインまたは要素の設定が不正な場合 — 例: 必須パラメータの欠落、値が範囲外、フィールドの型が不正など。`ParameterValues` の参照で発生する `ParameterNotFoundError`、パイプライン/データフィットのパース時に投げられる `UserConfigurationError`、UCP プロトコルエンジンが投げる `ProtocolConfigurationError`（不正なステップ、未知の終了条件タイプ、欠落したドライブサイクル、解決できない `goto` ターゲット、`[0, 100]` を外れる初期 SOC など）も含まれます。	パイプライン設定または入力パラメータを修正してください。`error` メッセージに該当するフィールド名が含まれています。
`SOLVER_ERROR`	数値ソルバーが収束しなかった場合 (例: 電圧カットオフ違反、シミュレーション中の積分失敗)。	動作プロトコル、初期条件、パラメータ値が物理的に整合しているかを確認してください。
`EXECUTION_TIMEOUT`	ジョブが許容された実行時間を超えた場合。	問題のサイズを縮小する、モデルを単純化する、または実行を分割してください。
`SUBMISSION_FAILED`	ジョブをコンピュートバックエンドに送信できなかった場合。	ジョブを再実行してください。継続する場合はサポートまでご連絡ください。
`INTERNAL_ERROR`	プラットフォーム内部で予期しないエラーが発生した場合。生の例外メッセージは意図的にサニタイズされています。	ジョブを再実行してください。継続する場合はサポートまでご連絡ください。

Python で設定エラーをキャッチする

ionworkspipeline パッケージは ParameterNotFoundError を公開しているため、トレースバックやメッセージ文字列を調べることなく、パラメータの欠落による失敗をキャッチできます。KeyError を継承しているため、既存の except KeyError ハンドラもそのまま動作します。

import ionworkspipeline as iwp

try:
    pipeline.run(parameter_values)
except iwp.ParameterNotFoundError as err:
    print(f"Missing parameter: {err}")

ParameterNotFoundError は KeyError を継承しており、独自の属性は持ちません。メッセージは str(err) または err.args[0] で取得でき、pybamm のパラメータ参照が生成する完全なテキスト（例: "'Negative electrode loading [A.h.cm-2]' not found. Best matches are [...]"）が格納されます。欠落しているキー名と近い候補が示されるため、診断 UI の構築やパラメータセットの自動修正を行う際に便利です。パイプライン/データフィットのパース時に投げられるもう 1 つの設定エラー UserConfigurationError は、パッケージのルートには再エクスポートされていません — ルートで公開されているのは ParameterNotFoundError のみです。直接キャッチする必要がある場合はサブモジュールからインポートしてください: from ionworkspipeline.exceptions import UserConfigurationError。これは ValueError を継承しているため、except ValueError ハンドラでもキャッチできます。プロトコルエンジン側の失敗については、ionworks_ucp が ProtocolConfigurationError を投げます。これは UCP プロトコルが記述どおりにシミュレーションできない場合 — 例えば、名前で参照したドライブサイクルが供給されていない、goto ターゲットが解決できない、終了条件の文字列がパースできない、初期 SOC が [0, 100] を外れている、SetVar 式が未初期化の変数を参照しているなど — に発生します。この例外は ValueError を継承しているため、既存の except ValueError ハンドラはそのまま動作します。ProtocolConfigurationError を直接キャッチすれば、ユーザー側で修正可能なプロトコルの問題と、内部のソルバーバグを区別できます。

from ionworks_ucp.simulate_protocol import run_protocol_simulation
from ionworks_ucp.exceptions import ProtocolConfigurationError, SolverError

try:
    result = run_protocol_simulation(protocol, model, parameter_values)
except ProtocolConfigurationError as err:
    # ユーザー側で修正可能: プロトコル、ドライブサイクル、入力を修正して再実行してください。
    print(f"Protocol configuration error: {err}")
except SolverError as err:
    # ステップ中の数値的な失敗（例: 電圧カットオフ違反）。
    print(f"Solver error: {err}")

バックエンドのジョブは ProtocolConfigurationError を INTERNAL_ERROR ではなく CONFIGURATION_ERROR コードにルーティングし、そのメッセージをそのままユーザーに表示します。ローカルでキャッチするのと同じ例外が、API 経由で確認する失敗したパイプライン要素にも反映されます。

はじめに

Batteries 101

モデリング