パイプライン入門

バッテリーパラメータ化は、入力パラメータを出力パラメータに変換する パイプライン要素 (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

ここに挙げたパイプライン要素の種類および組み込みの計算は網羅的ではありません。設定項目の全容は Pipelines API を参照してください。

たとえば容量パイプラインでは、各電極の電極容量計算に、サイクル可能リチウムと電極 SOH の計算を連結します。各要素は前段の要素が生成したパラメータを消費します。各要素は以下を行います。

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

パイプラインをプログラムから組み立てて送信する方法については、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 で設定エラーをキャッチする

設定に問題のあるパイプラインを送信しても、送信時点では失敗しません — ジョブは受け付けられ、実行されて初めて問題の要素が error_code = CONFIGURATION_ERROR で失敗します（上記の表を参照）。SDK の wait_for_completion でパイプラインの完了を待つと、この失敗は IonworksError として発生します。

from ionworks.errors import IonworksError

try:
    client.pipeline.wait_for_completion(pipeline_id)
except IonworksError as err:
    print(f"Pipeline failed: {err}")

例外メッセージには根本的な失敗の内容が格納されます。パラメータ欠落の場合は、上記と同じ pybamm のパラメータ参照メッセージ（例: "'Negative electrode loading [A.h.cm-2]' not found. Best matches are [...]"）です。構造化された error_code はこの例外には含まれません。それを確認するには、例外メッセージを解析するのではなく、ジョブ上の失敗した要素のステータス（上記の JSON）を参照してください。 UCP プロトコルが記述どおりにシミュレーションできない場合 — 例えば、名前で参照したドライブサイクルが供給されていない、goto ターゲットが解決できない、終了条件の文字列がパースできない、初期 SOC が [0, 100] を外れている、未初期化の変数を参照する式があるなど — 失敗したパイプライン要素には CONFIGURATION_ERROR コードが付与され、そのメッセージが API 経由でそのまま表示されます。これにより、ユーザー側で修正可能なプロトコルの問題（プロトコル、ドライブサイクル、入力を修正して再実行してください）と、INTERNAL_ERROR として報告される予期しない内部エラーとを区別できます。

はじめに

Batteries 101

モデリング