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

# カスタム変数

> PyBaMM 式を使用して、摂氏温度や電極電位などのカスタム出力量を定義し、シミュレーションや最適化で再利用する方法を説明します

カスタム変数を使うと、モデルの組み込み状態変数とパラメータから計算される新しい量を定義できます。シミュレーション結果でリクエストしたときに遅延評価されるため、シミュレーション自体の速度を低下させることはありません。

カスタム変数はモデルに保存され、そのモデルを使うすべてのシミュレーションと最適化で利用できます。

## 変数 vs カスタム変数

バッテリーモデルは、ソルバーが各タイムステップで計算する電圧、電流、温度などの量である数十の組み込み **変数** を解きます。**カスタム変数** は、これらの組み込み変数をパラメータと数学と組み合わせるためにユーザーが定義する式です。

|          | 変数                                            | カスタム変数                                     |
| -------- | --------------------------------------------- | ------------------------------------------ |
| **ソース**  | PyBaMM モデルが解く                                 | ユーザーが定義                                    |
| **例**    | `Voltage [V]`、`Current [A]`、`Temperature [K]` | `Temperature [degC]`、`Anode potential [V]` |
| **参照方法** | `CoupledVariable("name")`                     | 定義後は `CoupledVariable("name")` でも参照可能      |
| **編集可能** | いいえ                                           | 追加のみ — 作成後に編集や削除はできません                     |

<Note>
  評価された値はシミュレーション結果ファイルに保存されるため、カスタム変数は追加のみ可能です。シミュレーション実行後に変数を変更・削除すると、それらの結果が無効になります。
</Note>

## 事前設定されたカスタム変数

すべてのシステムモデル（SPM、SPMe、DFN、それらのコンポジットバリアント、LumpedSPMR、LumpedSPMeR、フルセルおよびハーフセル ECM）には、次のカスタム変数があらかじめ定義されています:

| 変数                      | 説明                            |
| ----------------------- | ----------------------------- |
| `Anode potential [V]`   | 各モデルタイプの適切な内部モデル変数から導出される負極電位 |
| `Cathode potential [V]` | 各モデルタイプの適切な内部モデル変数から導出される正極電位 |
| `Temperature [degC]`    | ケルビンから摂氏に変換されたセル温度            |

これらはシミュレーション結果で即座に利用できます — システムモデルを使うときに自分で追加する必要はありません。

<Info>
  システムモデルをクローンして新しいカスタムモデルを作成する場合、カスタム変数は自動的に引き継がれます。モデルをゼロから作成する場合は、必要なカスタム変数を手動で追加する必要があります。
</Info>

### モデルタイプ別の電極電位式

電極電位に使用される式はモデルタイプによって異なります:

| モデルタイプ                 | 負極電位式                                                                                           | 正極電位式                                                                                           |
| ---------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| フルセル (SPM、SPMe、DFN)    | `CoupledVariable("Negative electrode surface potential difference at separator interface [V]")` | `CoupledVariable("Positive electrode surface potential difference at separator interface [V]")` |
| ハーフセル (SPM、SPMe、DFN)   | `Scalar(0)`                                                                                     | `CoupledVariable("Voltage [V]")`                                                                |
| フルセル ECM               | `CoupledVariable("Anode potential [V]")`                                                        | `CoupledVariable("Cathode potential [V]")`                                                      |
| ハーフセル ECM              | `Scalar(0)`                                                                                     | `CoupledVariable("Voltage [V]")`                                                                |
| LumpedSPMR、LumpedSPMeR | `CoupledVariable("X-averaged negative electrode surface potential difference [V]")`             | `CoupledVariable("X-averaged positive electrode surface potential difference [V]")`             |

<Note>
  フルセル ECM は回路ベースであり、個別の電極電位を直接解きません。代わりに、**Anode overpotential fraction** パラメータを使用して総過電圧を負極と正極の間で分割することにより再構築します。詳細と BioLogic EWE/ECE 制御の再現などのユースケースは [Models の ECM](/ja/build/models#ionworks-models) を参照してください。ハーフセル ECM は作用電極を正極として扱う（負極電位 = 0 V）ため、セル電圧は正極電位と等しくなります。
</Note>

## 式の構文

カスタム変数の式は PyBaMM のビルディングブロックを使用します:

### 型

| 型                         | 目的                  | 例                                |
| ------------------------- | ------------------- | -------------------------------- |
| `CoupledVariable("name")` | モデル変数または別のカスタム変数を参照 | `CoupledVariable("Voltage [V]")` |
| `Parameter("name")`       | モデルパラメータを参照または作成    | `Parameter("C-rate")`            |
| 数値                        | 定数値 — 式中ではプレーン数値を使用 | `273.15`、`3600`                  |

### 数学演算

標準の算術: `+`、`-`、`*`、`/`、`**`（べき乗）

### 関数

`exp()`、`log()`、`sqrt()`、`tanh()`、`cosh()`、`sinh()`

## 例

**温度変換（ケルビンから摂氏）:**

```python theme={null}
CoupledVariable("Volume-averaged cell temperature [K]") - 273.15
```

**内部モデル変数からの電極電位:**

```python theme={null}
CoupledVariable("Negative electrode surface potential difference at separator interface [V]")
```

**式で使用するためにスケーリングされたパラメータ:**

```python theme={null}
Parameter("C-rate") * 3600
```

**電力出力（2 つのモデル変数の組み合わせ）:**

```python theme={null}
CoupledVariable("Voltage [V]") * CoupledVariable("Current [A]")
```

**数学関数の使用:**

```python theme={null}
exp(CoupledVariable("Overpotential [V]") / 0.026)
```

## 評価

カスタム変数は遅延評価されます — シミュレーション結果で表示されたときのみ評価されます。プロットや表示用にカスタム変数を選択すると、システムはバックグラウンドで評価ジョブを送信します。評価実行中はローディングインジケーターが進捗を示します。

評価が失敗した場合（一時的なエラーなど）、プロットは読み込みを続ける代わりにエラー状態を表示します。表示される **Retry** ボタンをクリックして評価ジョブを再送信してください。

## 検証

カスタム変数を追加すると、システムは式を検証します:

1. **有効な構文** — 式は有効な PyBaMM 式として解析できる必要があります
2. **参照が存在する** — すべての `CoupledVariable` 参照は、既存のモデル変数またはすでに定義した他のカスタム変数を指す必要があります
3. **循環参照なし** — カスタム変数 A は、B が A を参照する場合（直接または間接的に）B を参照できません
4. **パラメータ認識** — `Parameter("name")` を使う場合、システムは既存のモデルパラメータに一致するか新しいものを作成するかを知らせます。名前が完全に一致しない場合、類似する既存パラメータを提案します

## 制限事項

* **追加のみ** — カスタム変数は作成後に編集や削除はできません
* **アップロードされたモデルでは利用不可** — 組み込みの PyBaMM モデルタイプのみカスタム変数をサポートします
* **システムモデルは変更不可** — まずシステムモデルをクローンしてから、クローンにカスタム変数を追加してください