> ## 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.

# Universal Cycler Protocol

> Ionworks のバッテリーサイクル実験とプロトコルステップを定義する YAML ベースの言語 UCP の完全リファレンスです

Universal Cycler Protocol (UCP) は、バッテリーサイクル実験を定義するための柔軟な YAML ベースの言語です。プログラマティックな制御を備えた複雑な実験シーケンスを作成できます。

<Tip>
  UCP プロトコルは[プロトコルビルダー](/ja/simulate/protocol-builder)を使用して
  ビジュアルに作成・編集するか、[商用プロトコル](/ja/simulate/simulating-commercial-protocols)
  を UCP 形式に変換することができます。このページは、基盤となる UCP ファイル形式の
  完全なリファレンスです。
</Tip>

## グローバル設定

オプションの `global` キーの下で、プロトコル全体のグローバル設定を定義できます。

```yaml theme={null}
global:
  initial_temperature: 25
  initial_state_type: soc_percentage # or "voltage"
  initial_state_value: 100 # percent if soc_percentage, volts if voltage
  resolution:
    time: 60
```

* `initial_temperature`: 実験の開始温度（摂氏）。デフォルトは `25`。[設計最適化](/ja/optimize/running-optimization#define-the-experiment)で使用する場合、この値は自動的にケルビンに変換され、シミュレーションの初期温度と周囲温度の両方に適用されます。
* `initial_state_type`: セルの初期状態の定義方法。使用可能な値：
  * `soc_percentage`: `initial_state_value` を充電状態のパーセンテージ（0〜100）として解釈。
  * `voltage`: `initial_state_value` を開始電圧（ボルト）として解釈。
* `initial_state_value`: 選択したタイプの初期値。
* `resolution`: シミュレーション出力の時間分解能（秒）。デフォルトは `60`。

## 安全制限

シミュレーションのオプションの安全制限を定義できます。これらのいずれかが超過すると、現在のシミュレーションステップが終了します。

```yaml theme={null}
safety_limits:
  voltage_min: 2.5
  voltage_max: 4.2
  temperature_min: -20
  temperature_max: 60
  charge_current_max: 10 # Max charge current in Amps (positive value)
  discharge_current_max: 15 # Max discharge current in Amps (positive value)
```

<Note>
  ステップの終了条件（以下参照）がグローバルの `safety_limit` と同じ値を持つ場合、
  安全制限が優先されます。
</Note>

## シミュレーションステップ

各シミュレーションステップは、ステップの**方向**を定義する単一のキーを持つ辞書として定義されます。このキーの値は、ステップのパラメータを含む辞書です。

主要なステップ方向は以下の通りです：

* `Rest`: セルが休止状態。
* `Charge`: セルが充電中。
* `Discharge`: セルが放電中。
* `Drive`: ドライブサイクルステップ（以下参照）。
* `EIS`: 電気化学インピーダンス分光法ステップ（以下参照）。

### ステップパラメータ

* `mode`: ステップの制御モード（例：`C-rate`, `Current`, `Power`, `Voltage`）。`Rest` でない限り必須。
* `value`: 制御モードのセットポイント。固定値または動的な式が使用可能。
* `duration`: ステップの最大持続時間（秒）。
* `ends`: 1つ以上のカットオフ条件のリスト。ステップには `duration` または少なくとも1つの `ends` 条件が必要。
* `temperature`:（オプション）この特定のステップの周囲温度（摂氏）。グローバル設定をオーバーライド。
* `resolution`:（オプション）この特定のステップの時間分解能。グローバル設定をオーバーライド。
* `set_variable`:（オプション）ステップ完了\_後\_に計算・設定する変数のリスト。
* `note`:（オプション）情報提供用の文字列。

### `input['...']` によるパラメータ化ステップ

`value`、`duration`、`ends` フィールドで `input['...']` 構文を使用して、パラメータ化されたプロトコルを作成できます。プロトコル実行時に実際の値が提供されます。

```yaml theme={null}
steps:
  # Parameterized step value
  - Discharge:
      mode: C-rate
      value: input["C-rate"]
      ends:
        - Voltage < input["Cut-off voltage [V]"]

  # Parameterized duration
  - Rest:
      duration: input["Rest duration [s]"]

  # Parameterized duration in ends
  - Discharge:
      mode: Power
      value: 2
      ends:
        - "Duration > input['Cruise duration [s]']"
        - Voltage < 3.0

  # Expressions with inputs
  - Rest:
      duration: input["Duration [s]"] / 2
```

入力は `resolution`、`global` 設定、`set_variable` 式でも使用できます。完全な例については[実験テンプレート](/ja/simulate/experiment-templates)を参照してください。

### 終了条件（`ends`）

`ends` 条件は、ステップがいつ終了すべきかを定義します。

```yaml theme={null}
# Simple termination
ends:
  - "Voltage > 4.2"

# Derivative-based termination
ends:
  - "d/dt(Voltage) < 0.001"

# Termination with a `goto` to another step block
ends:
  - "Voltage < 2.7":
      goto: My_Next_Step

# テスト全体を終了する終了条件
ends:
  - "Voltage < 2.5":
      goto: End Test
```

* **サポートされるタイプ：** `Voltage`, `Current`, `C-rate`, `Capacity`, `Temperature`（大文字小文字を区別しない）。
* **サポートされる演算子：** `<` と `>`。
* **符号規則：** `Current`、`C-rate`、`Capacity` の終了条件では、常に正の値を指定してください。エンジンが内部の符号規則（例：充電時の負の電流）を自動的に処理します。`Voltage` と `Temperature` については、記述された通りの符号が使用されます。
* **微分終了条件：** 変数の変化率に基づいて終了するには、`"d/dt(Type) operator value"` の形式を使用します。

<Note>
  ステップの終了条件が最初から満たされている場合（例：既に4.2Vに達しているバッテリーを
  充電しようとする場合）、そのステップはスキップされます。その終了条件上の
  `goto` 遷移は実行**されません**。ただし、そのステップの `set_variable`
  はスキップされた場合でも評価されるため、ステップの最後に計算する
  アキュムレータや参照値は、ステップが実行されたかスキップされたかにかかわらず
  一貫した状態を保ちます。
</Note>

### 例：微分終了条件

微分ベースの終了条件は、信号の安定性に基づいてステップを終了するのに便利です。例えば、定電圧充電フェーズは電流が変化しなくなったとき（バッテリーが満充電であることを示す）に終了できます。

```yaml theme={null}
- CV Charge with Current Stability Check:
    - Charge:
        mode: Voltage
        value: 4.2 # Constant Voltage phase
        ends:
          - "d/dt(Current) < 0.001"
```

### 例：CCCV 充電

```yaml theme={null}
- CC Charge:
    - Charge:
        mode: C-rate
        value: 1
        ends:
          - "Voltage > 4.2"
- CV Charge:
    - Charge:
        mode: Voltage
        value: 4.2
        ends:
          - "Current < 0.05"
```

### Ambient Temperature ステップ

`Ambient Temperature` ステップは、プロトコルの途中で周囲（チャンバー）温度を変更します。これは瞬時的なステップで、チャンバー設定値を設定して即座に次のステップに進みます。シミュレーションは、別の `Ambient Temperature` ステップに到達するまで、新しい周囲温度で継続します。

* `temperature_setpoint`: 必須。新しい周囲温度（摂氏）。絶対零度より大きい必要があります。
* `temperature_ramp_rate`: （オプション）ランプレート（°C/分）。デフォルトは `2.0`。

```yaml theme={null}
- Soak at 45 C:
    - Ambient Temperature:
        temperature_setpoint: 45
    - Rest:
        duration: 3600
- Cool to 25 C:
    - Ambient Temperature:
        temperature_setpoint: 25
    - Rest:
        duration: 1800
```

熱ソークセグメント、固定基準温度で実行される RPT 診断、またはチャンバー設定値がテスト中に変化するプロトコルにこのステップを使用してください。

<Note>
  `Ambient Temperature` ステップは、その時点以降のプロトコルにおいて
  `global.initial_temperature` 設定（および前のステップの `temperature`
  オーバーライド）を上書きします。
</Note>

### EIS ステップ

`EIS` ステップは、セルの現在の状態で電気化学インピーダンス分光法の測定を実行します。

* `lower_frequency`: EIS スイープの下限周波数（Hz）。
* `upper_frequency`: EIS スイープの上限周波数（Hz）。

両方の周波数パラメータは固定値または動的な式が使用可能です。

EIS ステップは、物理ベースモデル（内部で `pybamm.EISSimulation` を使用）と等価回路モデル（ECM）の両方で実行されます。ECM ではインピーダンスを直列抵抗パラメータ `R0 [Ohm]` と各インデックス付き `R_rc (i) [Ohm]` / `C_rc (i) [F]` 並列ブランチから解析的に計算します。そのため、ECM を使用する Battery Cycler Simulator は、アップロードされたプロトコル（例: BioLogic の PEIS/GEIS テクニック）の EIS ステップを追加設定なしで実行できます。解析的な ECM EIS は抵抗とキャパシタンスのパラメータが定数であることを要求し、SOC や電流に依存する ECM パラメータは明確なエラーで拒否されます。

シミュレーション結果ビューでは、各 EIS ステップはインピーダンススイープが実行された瞬間の時間領域プロット上で縦線としてマーキングされます。マーカーにカーソルを合わせると **EIS step N** ツールチップが表示され、Nyquist トレースをサイクル履歴中の位置と対応付けできます。

#### 例：基本的な EIS

30分間の休止期間後に EIS 測定を実行します。

```yaml theme={null}
- Rest:
    - Rest:
        duration: 1800
- Impedance Measurement:
    - EIS:
        lower_frequency: 0.1
        upper_frequency: 1000
```

#### 例：動的周波数を使用した EIS

変数を使用して周波数を動的に計算できます。

```yaml theme={null}
- Set Up Frequencies:
    - Control:
        set_variable:
          - name: VAR_UPPER_FREQ
            eval: 10 * input['Frequency Multiplier']
- Perform EIS:
    - EIS:
        lower_frequency: VAR_UPPER_FREQ / 1000
        upper_frequency: VAR_UPPER_FREQ
```

<a id="control-steps" />

## 制御ステップ

制御ステップはプログラマティックなロジックに使用され、シミュレーションは実行しません。変数の設定や `goto` を使ったループの作成に最適です。

```yaml theme={null}
- Setup and Jump:
    - Control:
        set_variable:
          - name: VAR_C_RATE
            eval: 1.5
    - "Increment cycle number"
```

### 制御ステップのパラメータ

* `set_variable`:（オプション）設定する変数のリスト（[変数による動的動作](#dynamic-behavior-with-variables)を参照）。
* `goto`:（オプション）この制御ステップ実行後にジャンプするステップブロックの名前。これにより、変数の値に基づいて異なるステップに分岐するなど、非順次的な制御フローが可能になります。

```yaml theme={null}
- Assign C-rate and Continue:
    - Control:
        set_variable:
          - name: VAR_C_RATE
            eval: 0.33
        goto: Start_Discharge
```

特殊な文字列コマンドも使用可能です：

* `"Increment cycle number"`: 内部サイクルカウンターをインクリメント。
* `"End"` または `"Pause"`: シミュレーション全体を終了。

### 予約された `goto` ターゲット

`goto` は名前付きステップブロックへのジャンプに加え、予約ターゲット `End Test` を受け付けます。指定するとシミュレーションを直ちに停止します。ステップの終了条件（`ends`）と Control ステップの `goto` フィールドの両方で使用でき、サブスケジュール内でも有効です。サブスケジュールから `End Test` にジャンプすると、そのサブスケジュールだけでなく、テスト全体が終了します。

Control ステップの `goto` は、そのステップに入るたびに**無条件**で実行されます。
そのため、すでに分岐して到達したブランチを終了する用途に使用します。

```yaml theme={null}
# 無条件: この Control ステップに入ると常にテストを終了する
- Stop Here:
    - Control:
        goto: End Test
```

**条件付き**で終了するには、代わりにステップの終了条件に `goto` を付けます。
その条件が満たされた場合にのみジャンプが実行されます。

```yaml theme={null}
# 条件付き: 電圧が 2.8 V を下回ったときにのみ End Test へジャンプする
- Discharge until fault:
    Discharge:
      C-rate: 0.33
    ends:
      - "Voltage < 2.8":
          goto: End Test
```

フォールト条件やロジック分岐で、次のステップにフォールスルーするのではなく、実行を明示的に終了したい場合に `End Test` を使用してください。

<a id="dynamic-behavior-with-variables" />

## 変数による動的動作

`set_variable` を使用して変数を定義し、動的で応答性のあるプロトコルを作成できます。

* `name`: 変数の名前。`VAR_` で始まる必要があります。
* `eval`: 評価される Python 式。結果は数値でなければなりません。

`eval` 式では以下を使用できます：

* **ユーザー入力：** `input['...']`
* **他の変数：** 既に定義された任意の `VAR_` 変数。
* **特殊変数：** `t`（ステップ相対時間、秒単位）。
* **シミュレーション結果：** 前のステップの `Voltage`、`Current` など。
* **ヘルパー関数：** `first()`, `last()`, `mean()`, `abs()`, `sign()`, `min()`, `max()`, `ifelse()`。

### 例：時間変化する制御

1時間かけてC-rateを0.1から1.1まで線形にランプアップします。

```yaml theme={null}
- Ramp Discharge:
    - Discharge:
        mode: C-rate
        value: 0.1 + t / 3600
        duration: 3600
```

時間変化する値は、ステップ内で符号を変えることもできます。たとえば、`sign()` で構築されたピースワイズ電流波形は、最初の30秒間は充電し、次の30秒間は放電できます：

```yaml theme={null}
- Piecewise Current:
    - Charge:
        mode: Current
        value: sign(30 - t) * 1.0
        duration: 60
        ends:
          - Voltage > input["Upper voltage cut-off [V]"]
          - Voltage < input["Lower voltage cut-off [V]"]
```

<Note>
  ステップ値が `t` の明示的な関数である場合、波形は単一ステップ内でセルを両方向に駆動する可能性があります。`Charge` ステップは上限電圧カットオフのみ（`Discharge` ステップは下限電圧カットオフのみ）を持てるという通常のルールは、時間変化する値については緩和されているため、両側に安全カットオフを設定できます。
</Note>

### 例：条件付きロジック

`ifelse` ヘルパーを使用して条件付きロジックを作成します。この例では、前のステップの最終電圧に基づいて後続ステップの方向を定義します。

```yaml theme={null}
- Discharge and Check:
    - Discharge:
        mode: C-rate
        value: 1
        duration: 600
        set_variable:
          - name: VAR_NEEDS_CHARGE
            eval: ifelse(last(Voltage) < 3.5, 1, 0)

- Conditional Step:
    - Direction[ifelse(VAR_NEEDS_CHARGE == 1, "Charge", "Rest")]:
        mode: C-rate
        value: 1
        ends:
          - "Voltage > input['Upper voltage cut-off [V]']"
```

<a id="step-blocks" />

## ステップブロック

ステップは名前付きブロックにグループ化できます。これは `goto` ターゲットや、`repeat` キーワードを使用したステップシーケンスの繰り返しに不可欠です。

```yaml theme={null}
- Ten Pulses:
    - Discharge:
        mode: C-rate
        value: 5
        duration: 1
    - Rest:
        duration: 1
  repeat: 10
```

<Note>
  ブロックの名前は予約されたステップタイプ（`Charge`、`Discharge`、`Rest`、
  `Control` など）にすることはできません。予約済みの `goto` ターゲット
  `End Test` はジャンプ先としては使用できますが、ブロック名としては使用できません。
</Note>

## ドライブサイクル

Python コードの `solve_protocol` 関数にデータを渡し、YAML で参照することで、複雑なプロファイルにドライブサイクルを使用できます。

* **Python 側：** 値が2列の NumPy 配列（時間、値）である `drive_cycles` 辞書を渡します。
* **YAML 側：** `Drive` 方向を使用します。`value` は辞書からのドライブサイクルの名前です。持続時間はデータの時間列で定義されます。
* **`mode`：** データの2列目の解釈方法を制御します。電流プロファイル（アンペア）には `Current`（デフォルト）を、電力プロファイル（ワット）には `Power` を使用します。電圧のカットオフは `ends` を介してどちらのモードにも付与できます。

```yaml theme={null}
# 電流モードのドライブサイクル（値はアンペア）
- US06 Drive Cycle:
    - Drive:
        mode: Current
        value: US06

# 電力モードのドライブサイクル（値はワット）
- Power Profile:
    - Drive:
        mode: Power
        value: LoadProfile
        ends:
          - Voltage < input['Lower voltage cut-off [V]']
          - Voltage > input['Upper voltage cut-off [V]']
```

## サブルーチン

サブルーチンは、Python コードで定義され YAML プロトコルから呼び出される再利用可能なステップシーケンスです。CCCV 充電のような標準的な手順に便利です。

* **Python 側：** `solve_protocol` に `subroutines` 辞書を渡します。値はステップのリストです。
* **YAML 側：** 実行するサブルーチンの名前を持つ `Subroutine` ステップタイプを使用します。

```yaml theme={null}
# In your main protocol.yaml file
steps:
  - Initial Rest:
      - Rest:
          duration: 1800

  - "Increment cycle number"
  - Subroutine: CCCV # This calls the "CCCV" subroutine defined in Python
```

## 出力

プロトコルソルバーは、時間、電圧、電流、温度、サイクル番号、および `set_variable` で定義されたカスタム変数を含むシミュレーション結果の pandas DataFrame を返します。