> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionworks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# パイプライン入門
> DirectEntry、Calculation、DataFit、Validation の各要素を連結し、バッテリーパラメータを変換して実験データにモデルをフィットさせます
バッテリーパラメータ化は、入力パラメータを出力パラメータに変換する **パイプライン要素 (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 リファレンス](https://pipeline.docs.ionworks.com/source/api/index.html) を参照してください。
```python theme={null}
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)
```
各要素は以下を行います。
1. パラメータ辞書から入力パラメータを取得
2. 計算を実行
3. 後続の要素から利用可能な出力パラメータを返す
パイプラインをプログラムから組み立てて送信する方法については、Documentation タブの [Pipelines → Overview](/ja/pipelines/overview) を参照してください。
## Naming conventions
Use descriptive parameter names with units: `"Electrode capacity [A.h]"` not `"cap"`
Be explicit about unit conversions; use SI units internally
## Built-in Calculations
Electrode geometry, mass, capacity, cyclable lithium, and microstructure
Heat capacity, Arrhenius temperature dependence, and thermal modeling
Smooth piecewise functions for SOC and temperature-dependent parameters
## パイプライン失敗への対処
パイプライン要素は順番に実行されます。ある要素が失敗すると、パイプラインはエラーを報告し、後続の要素は停止します。原因は要素に `error_code` として記録されます。
| `error_code` | 意味 |
| ------------------- | ---------------------------------------------- |
| `SUBMISSION_FAILED` | 要素をワーカーに投入できませんでした（例: 一時的なインフラの問題）。再投入しても安全です。 |
| `EXECUTION_TIMEOUT` | 要素が実行時間の上限を超えました。再試行する前に構成を調整してください。 |
| `INTERNAL_ERROR` | 要素の実行中に予期しないサーバー側のエラーが発生しました。 |
### 失敗したパイプラインの再投入
最初に失敗した要素の `error_code` が `SUBMISSION_FAILED` の場合、パイプラインを再投入できます。再投入はその要素をリセットし、パイプラインが停止した箇所から実行を再開します — 完了済みの要素は再実行されません。
パイプライン詳細ページを開きます。先頭の失敗が投入エラーの場合、ページ上部の失敗要素のアラートに **Resubmit** ボタンが表示されます。これをクリックすると、パイプラインをその場で再試行できます。
再投入は汎用のジョブエンドポイントを経由し、パイプラインはそのジョブ ID で識別されます（`client.pipeline.get(...)` に渡すものと同じ ID です）。
```bash theme={null}
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` 要素はパイプラインを最適化ループでラップします。
* 最適化器がパラメータ値を提案する
* パイプラインがその値でモデルを実行する
* 目的関数が予測とデータの一致度を評価する
* ベストフィットのパラメータが得られるまで繰り返す
Cost functions, identifiability, regularization, and other theory.
Configure and submit data fits with `ionworks-schema` + `ionworks-api`.
## パイプラインのエラー
パイプライン要素が失敗すると、Studio はその要素を **Failed** 状態で表示し、エラーメッセージと機械可読な **エラーコード** を併せて示します。パイプライン一覧でステータスチップにカーソルを合わせるとコードが表示され、失敗した要素を展開すると完全なメッセージを確認できます。
同じフィールドは、失敗したジョブやパイプライン要素の API レスポンスでも返されます:
```json theme={null}
{
"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` ハンドラもそのまま動作します。
```python theme={null}
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` を直接キャッチすれば、ユーザー側で修正可能なプロトコルの問題と、内部のソルバーバグを区別できます。
```python theme={null}
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 経由で確認する失敗したパイプライン要素にも反映されます。