> For the complete documentation index, see [llms.txt](https://www.opal-rt.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.opal-rt.com/docs/hypersim/library-blocks-reference/network-renewable-energy/battery.md).

# Battery

## Description

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-7b09ab20f9bcbc108a6d052e04194d87cfff0fc2%2Fimage%20(670).png?alt=media" alt="" width="164"><figcaption></figcaption></figure>

The model equations depend on the selected battery technology. When the **Customized parameters** option is enabled, user-defined discharge parameters are used. This model does not consider temperature or aging effects.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-36cdf008fff9f632db6290ec1812f82af483fdf8%2Fimage%20(672).png?alt=media" alt="" width="408"><figcaption><p>Equivalent circuit implemented in the model</p></figcaption></figure>

<details>

<summary><strong>Model for the </strong><em><strong>Lead-Acid</strong></em><strong> battery type</strong></summary>

Discharge Model ( i<sub>filter</sub> > 0 ):

$$E\_{\text{discharge}} = E\_0 - K \cdot \frac{Q}{Q - i\_{\text{sat}}} \cdot i\_{\text{filter}} - K \cdot \frac{Q}{Q - i\_{\text{sat}}} \cdot i\_{\text{sat}} + \mathcal{L}^{-1} \left{ \frac{\exp(s)}{\text{sel}(s)} \cdot 0 \right}$$

Charge Model ( i<sub>filter</sub> < 0 ):

$$E\_{\text{charge}} = E\_0 - K \cdot \frac{Q}{i\_{\text{sat}} + 0.1 \cdot Q} \cdot i\_{\text{filter}} - K \cdot \frac{Q}{Q - i\_{\text{sat}}} \cdot i\_{\text{sat}} + \mathcal{L}^{-1} \left{ \frac{\exp(s)}{\text{sel}(s)} \cdot \frac{1}{s} \right}$$

where:

$$E\_0$$is the constant voltage, in V.

$$exp(s)$$ is the exponential zone dynamics, in V.

$$sel(s)$$represents the battery mode. ![](https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-532f406a294a58d2f64c2dc7513c5a3c3879e185%2Funknown%20\(35\).svg%2Bxml?alt=media) during battery discharge, ![](https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-23d132a422a26042c2c17b4ca9edda239a6ba28d%2Funknown%20\(36\).svg%2Bxml?alt=media) during battery charging.

$$K$$ is the polarization constant, in V/Ah, or polarization resistance, in Ohms.

$$i\_{filter}$$is the low-frequency current dynamics, in A.

$$i\_{batt}$$ is the battery current, in A.

$$i\_{sat}$$ is the extracted capacity, in Ah.

$$Q$$ is the maximum battery capacity, in Ah.

$$A$$ is the exponential voltage, in V.

$$B$$ is the exponential capacity, in Ah<sup>-1</sup>.

</details>

<details>

<summary><strong>Model for the </strong><em><strong>Lithium-Ion</strong></em><strong> battery family type</strong></summary>

Discharge Model ( i<sub>filter</sub> > 0 ):

$$E\_{\text{discharge}} = E\_0 - K \cdot \frac{Q}{Q - i\_{\text{sat}}} \cdot i\_{\text{filter}} - K \cdot \frac{Q}{Q - i\_{\text{sat}}} \cdot i\_{\text{sat}} + A \cdot \exp(-B \cdot i\_{\text{sat}})$$

Charge Model ( i<sub>filter</sub> < 0 ):

$$E\_{\text{charge}} = E\_0 - K \cdot \frac{Q}{i\_{\text{sat}} + 0.1 \cdot Q} \cdot i\_{\text{filter}} - K \cdot \frac{Q}{Q - i\_{\text{sat}}} \cdot i\_{\text{sat}} + A \cdot \exp(-B \cdot i\_{\text{sat}})$$

where:

$$E\_0$$ is the constant voltage, in V.

$$exp(s)$$ is the exponential zone dynamics, in V.

$$sel(s)$$represents the battery mode. ![](https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-532f406a294a58d2f64c2dc7513c5a3c3879e185%2Funknown%20\(35\).svg%2Bxml?alt=media) during battery discharge, ![](https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-23d132a422a26042c2c17b4ca9edda239a6ba28d%2Funknown%20\(36\).svg%2Bxml?alt=media) during battery charging.

$$K$$ is the polarization constant, in V/Ah, or polarization resistance, in Ohms.

$$i\_{filter}$$is the low-frequency current dynamics, in A.

$$i\_{batt}$$ is the battery current, in A.

$$i\_{sat}$$ is the extracted capacity, in Ah.

$$Q$$ is the maximum battery capacity, in Ah.

$$A$$ is the exponential voltage, in V.

$$B$$ is the exponential capacity, in Ah<sup>-1</sup>.

</details>

<details>

<summary><strong>Model for the </strong><em><strong>Nickel-Cadmium</strong></em><strong> and </strong><em><strong>Nickel-Metal-Hydride</strong></em><strong> battery type</strong></summary>

Discharge Model ( i<sub>filter</sub> > 0 ):

$$E\_{\text{discharge}} = E\_0 - K \cdot \frac{Q}{Q - i\_{\text{sat}}} \cdot i\_{\text{filter}} - K \cdot \frac{Q}{Q - i\_{\text{sat}}} \cdot i\_{\text{sat}} + \mathcal{L}^{-1} \left{ \frac{\exp(s)}{\text{sel}(s)} \cdot 0 \right}$$

Charge Model ( i<sub>filter</sub> < 0 ):

$$E\_{\text{charge}} = E\_0 - K \cdot \frac{Q}{i\_{\text{sat}} + 0.1 \cdot Q} \cdot i\_{\text{filter}} - K \cdot \frac{Q}{Q - i\_{\text{sat}}} \cdot i\_{\text{sat}} + \mathcal{L}^{-1} \left{ \frac{\exp(s)}{\text{sel}(s)} \cdot \frac{1}{s} \right}$$

where:

$$E\_0$$ is the constant voltage, in V.

$$exp(s)$$ is the exponential zone dynamics, in V.

$$sel(s)$$represents the battery mode. ![](https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-532f406a294a58d2f64c2dc7513c5a3c3879e185%2Funknown%20\(35\).svg%2Bxml?alt=media) during battery discharge, ![](https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-23d132a422a26042c2c17b4ca9edda239a6ba28d%2Funknown%20\(36\).svg%2Bxml?alt=media) during battery charging.

$$K$$ is the polarization constant, in V/Ah, or polarization resistance, in Ohms.

$$i\_{filter}$$is the low-frequency current dynamics, in A.

$$i\_{batt}$$ is the battery current, in A.

$$i\_{sat}$$ is the extracted capacity, in Ah.

$$Q$$ is the maximum battery capacity, in Ah.

$$A$$ is the exponential voltage, in V.

$$B$$ is the exponential capacity, in Ah<sup>-1</sup>.

</details>

### Charge and Discharge Characteristics

The circuit parameters can be modified to represent each of the four battery types presented in the model as well as its discharge characteristics. A typical discharge curve consists of three sections.<br>

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-08a5d860615335fef4949338036609f711037407%2Fbattery-block-discahrge-curve.png?alt=media" alt=""><figcaption></figcaption></figure>

**Typical Discharge Characteristics**

The first section shows the exponential voltage drop when the battery is charged. The width of the drop depends on the battery type. The second section indicates the charge that can be extracted from the battery until the voltage drops below the battery nominal voltage. Finally, the third section illustrates the total discharge of the battery, when the voltage drops rapidly.

When the battery current is negative, the battery recharges, following a charge characteristic.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-eff99a5286365fd7efbcfb4a1b68c68cdfd2da82%2Fbattery-block-discahrge-charac.png?alt=media" alt=""><figcaption><p>Typical Charge Characteristics for Lead-Acid, Li-ion, NiMH and NiCD</p></figcaption></figure>

The model parameters are calculated from the discharge characteristics. The discharging and charging characteristics are considered to be the same.

The  transfer function represents the hysteresis phenomenon for the *Lead-Acid*, *Nickel-Cadmium* (NiCD), and *Nickel-Metal-Hydride* (NiMH) batteries during the charge and discharge cycles. The exponential voltage increases when a battery is charging, regardless of the battery's state of charge. When the battery is discharging, the exponential voltage decreases immediately as shown in the following figure.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-420388b69a45aba0c59c7abb45e51126dcd16c3a%2Fbattery-block-discahrge-stateofcharge.png?alt=media" alt=""><figcaption><p><strong>Exponential Zone for Lead-Acid, NiMH and NiCD</strong></p></figcaption></figure>

The state of charge (SOC) for a battery is a measure of battery's charge, expressed as a percent of the full charge. The depth of discharge (DOD) is the numerical compliment of the SOC, such that **DOD = 100% - SOC**.

### Battery Modeling

The **Battery** block models a battery as a HYPERSIM-based controlled voltage source in series with an internal resistance. The voltage source is driven by a battery model that adjusts the internal voltage based on the output current. The battery model has been designed using native HYPERSIM control components and User Code Model (UCM) type components.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-96ef4f09bfec1fb8f76ed9d05df6eca490442744%2Fimage%20(673).png?alt=media" alt="" width="563"><figcaption><p>Internal circuit of the battery</p></figcaption></figure>

{% hint style="danger" %}
To properly initialize this component select **Solve Control inputs before solving power** available in the Advanced tab in the <mark style="background-color:yellow;">**Simulation Settings**</mark><mark style="background-color:yellow;">.</mark>
{% endhint %}

## Mask parameters

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-00dfd29bb2fd732c30aa93a584059ce76d89b436%2Fimage%20(671).png?alt=media" alt="" width="563"><figcaption></figcaption></figure>

{% tabs %}
{% tab title="Nominal parameters" %}

<table><thead><tr><th width="201.800048828125">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Description</strong></td><td>Use this field to add any information about the component.</td></tr><tr><td><strong>Type of battery</strong></td><td>Provides predetermined charge and discharge parameters for:<br>1- Lead-Acid,<br>2- Li-Ion,<br>3- Li-Ion LFP,<br>4- Li-Ion NMC,<br>5- Li-Ion NCR/NCA,<br>6- Li-Ion LTO,<br>7- Nickel-Cadmium,<br>8- Nickel-Metal-Hydride.<br>Variable: battType = {1,2,3,4,5,6,7,8}.</td></tr><tr><td><strong>Nominal voltage</strong></td><td>Nominal battery voltage Vnom = [0, 1e64] (V).</td></tr><tr><td><strong>Rated capacity</strong></td><td>Minimum effective capacity Qnom = [0, 1e64] (Ah).</td></tr><tr><td><strong>Initial state-of-charge (SOC)</strong></td><td>Initial state of charge SOC = [0, 100] (%).</td></tr><tr><td><strong>Battery response time</strong></td><td>Voltage response time (95% of final value) to a current step (s). Represents the battery voltage dynamics batt_Tr = [0, 1e64].</td></tr></tbody></table>
{% endtab %}

{% tab title="Dsicharge - Standard or customized parameters" %}
When enabled, the model uses the customized discharge parameters instead of the standard ones override = {0,1}.

<table><thead><tr><th width="200.199951171875">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Maximum capacity</strong></td><td>Maximum battery capacity (Ah) maxQ = [0, 1e64].</td></tr><tr><td><strong>Cut-off voltage</strong></td><td>Minimum allowable battery voltage (V). Represents the end of discharge (battery fully discharged) minV = [0, 1e64].</td></tr><tr><td><strong>Fully charge voltage</strong></td><td>Voltage at maximum charge (V) fullV = [0, 1e64].<br>The fully charged voltage is not the no-load voltage.</td></tr><tr><td><strong>Nominal discharge current</strong></td><td>Nominal discharge current used to measure the discharge curve (A) disRate = [0, 1e64].</td></tr><tr><td><strong>Internal resistance</strong></td><td>Internal battery resistance (Ohm) R = [0, 1e64].<br>A generic value is loaded for each battery type based on a percentage of nominal power (nominal voltage × rated capacity). The resistance is constant during charge and discharge and does not vary with current amplitude.</td></tr><tr><td><strong>Capacity at nominal voltage</strong></td><td>Capacity extracted until voltage drops below the nominal voltage (Ah) normalOP = [0, 1e64].<br>Should be between the current at the exponential zone and the maximum capacity.</td></tr><tr><td><strong>Voltage at exponential zone</strong></td><td>Voltage at the end of the exponential zone (V) expZoneV = [0, 1e64].<br>Must lie between the nominal and fully charged voltages.</td></tr><tr><td><strong>Capacity at exponential zone</strong></td><td>Capacity at the end of the exponential zone (Ah) expZoneI = [0, 1e64].<br>Should be between 0 and the rated battery capacity.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

{% hint style="info" %}
The **minimum no-load battery** voltage is 0 V and the maximum battery voltage is equal to .
{% endhint %}

### Conserving ports

<table><thead><tr><th width="219.5999755859375">Port</th><th>Description</th></tr></thead><tbody><tr><td><strong>Positive</strong></td><td>Network connector on the DC side; The + indicates this is the positive terminal (supports only 1-phase connections).</td></tr><tr><td><strong>Negative</strong></td><td>Network connector on the DC side; The - indicates this is the negative terminal (supports only 1-phase connections).</td></tr></tbody></table>

## Inputs

<table><thead><tr><th width="219.60003662109375">Input</th><th>Description</th></tr></thead><tbody><tr><td><strong>reset</strong></td><td>Logic signal that resets the state of charge (SOC) to its initial value during simulation.</td></tr></tbody></table>

## Outputs

<table><thead><tr><th width="219.60003662109375">Signal</th><th>Description</th></tr></thead><tbody><tr><td><strong>Ibatt</strong></td><td>DC battery output current (A).</td></tr><tr><td><strong>SOC</strong></td><td>State of charge (%).</td></tr><tr><td><strong>Vbatt</strong></td><td>DC battery output voltage (V).</td></tr></tbody></table>

## Signals available for monitoring and external I/O connections (via sensors form)

All block inputs and outputs are available as signals for monitoring and for external I/O connections.

## References <a href="#battery-references" id="battery-references"></a>

OPAL-RT Smart Power Simulation Software - [battery block](https://www.opal-rt.com/docs/smart-power-simulation-software-sps/blocks-functions-tools/renewables/battery.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.opal-rt.com/docs/hypersim/library-blocks-reference/network-renewable-energy/battery.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
