Configure

This guide explains how to configure a battery pack model, including some recommendations about model fidelity for different purposes.

Note that there is a separate guide on selecting a battery model to start from.

Where to configure the battery model

A battery model can be configured "in-place", as part of a system model. This can be useful for small models, and when experimenting with different configurations. However, this leads to a configuration that is local to that specific system model. When a battery model should be re-used in several places, it is instead recommended to create and pre-configure a separate battery model in the user model package. This allows multiple instances of the same battery model, which can be modified and maintained in a single place. This approach also makes it easier to manage a collection of multiple battery variants.

A new battery pack model can be created either by duplicating one of the Electrification.Batteries.Examples or by extending from one of the Electrification.Batteries.Templates. The model is then configured by redeclaring (selecting) the sub-components that represent different domains of the battery pack.

Ideal pack models

The Electrification.Batteries.Examples.Infinite and Electrification.Batteries.Examples.Nominal battery pack models have limited modularity. Not all of the components described in this guide can be configured for these models. Please refer to the documentation for each of these model for specific guidance on configuring and parametrizing these.

Number of cells in the battery pack

All battery pack models have the parameters ns and np that define how many cells the pack is made up of, and how many of them are electrically connected in series and parallel.

In general, when comparing one cell with the whole pack, the voltage scales with ns, the charge capacity scales with np, and energy and power capability scales with both. More guidance on this can be found in the separate sizing guide.

For models that are parametrized on pack level (Electrification.Batteries.Examples.Infinite and Electrification.Batteries.Examples.Nominal), changing the number of cells will not impact the electrical properties for the pack, only the result variables that are reported per cell. This can be useful for evaluating cell operating points given different number of cells.

Lumped or individual cells

For battery pack models based on the Electrification.Batteries.Templates.BatteryPackLumped template, all cells in the pack are represented with a single core model. This is the recommended configuration for most use cases.

Battery packs based on the Electrification.Batteries.Templates.BatteryPackArray template can also be configured to represent individual cells as separate core models. This is controlled via the cellGroups parameter. This is generally only recommended when the purpose is to simulate imbalances between individual cells. In all other cases, it is recommended to use a lumped pack, for faster simulation speed.

Note that the thermal domain is separately discretized into individual cells, independent of what pack model template is used.

For more information, please refer to the separate guide about Electrification.Batteries.Information.CellGroups.

Sub-components (domains) of the battery pack

The battery pack models are primarily configured by redeclaring the sub-components for the different domains. An overview of these domains is given in the general Information chapter. Each of the domain components can be redeclared more or less independently. This allows the model fidelity to be adapted separately for each domain, depending on what aspects are relevant to simulate. This also allows creating a custom model for one domain, while re-using a general one for another. More information about this architecture can be found in the Electrification.Information.UsersGuide.BasicConcepts.ComponentModelArchitecture.

There is a sub-package in the library for each domain, that contains different model options for the specific domain, as well as interfaces and templates for creating custom domain models. For more information about a specific domain or model option, please refer to the documentation in that package and model. This includes more guidance about what fidelities options are suitable for different applications.

The core model (specific cells)

The core model represents the electrical dynamics of the cells in the pack. The choice of core model depends both on the use case and what data is available for the specific cell.

Note that it is generally recommended to configure and parametrize the core models separately, in a similar way to what was described for the pack model in an earlier section.

Infinite cells

The only parameter of the Electrification.Batteries.Core.Examples.Infinite core model is the cell voltage. This model is useful for identifying operating points and requirements for the cells when nothing else than that is known about the cell.

Nominal cells

The Electrification.Batteries.Core.Examples.Nominal core model is useful when the operating requirements for the cells are known, but a specific cell type has not yet been chosen, or when only a rough level of detail is necessary. This model behaves exactly according to the nominal parameters, without non-ideal variations in voltage and impdeance. This model is parametrized per cell, as opposted to the Nominal pack model.

A "typical" cell of a specific chemistry

In some cases, it is desirable to model the typical characteristics of a certain cell chemistry, even if only nominal parameters is available about the actual cell to be used. In this situation, an existing model for the same type of cell can be re-scaled to fit the nominal parameters of the target cell.

The library comes with a number Electrification.Batteries.Core.Examples that have been pre-parametrized with data for specific cell chemistries, at different levels of fidelity. These can be used directly in a battery pack model, or be re-scaled to represent a similar cell with a different energy content and power capability.

Guidance about re-sizing a core model is described in the separate guide resizing a battery model.

Data for a specific cell

When data is available for a specific cell (datasheet or lab measurements), a custom core model can be parametrized from this data. For more information, please refer to the separate guide: Parametrize a battery model.

Thermal domain

The choice of thermal domain model depend on the required detail for the temperatures inside the battery pack. This can be a single temperature for the whole battery, or separate temperatures for individual cells.

For some use cases, it is not relevant to include temperature variations. Examples of this is when simulating very fast electrical dynamics, and when identifying heat losses under the assumption of ideal cooling. For such cases, it is recommended to select the simple Electrification.Batteries.Thermal.Examples.Lumped thermal model, and set the parameter fixed_temperature=true (at top level of the pack model). This avoids slowing down the simulation with unnecessary complexity.

Note that the discretization of the thermal domain is independent of whether lumped or individual cells are used for the core model. This allows modeling temperature variations within the pack, while assuming that this does not affect the electrical dynamics significantly.

There is a lot of variations between different battery packs and thermal management solutions. Because of this, users who want more detail than the most basic models provided with the library, will typically need to create a custom thermal model for their specific battery pack. The more detailed examples of thermal models can serve as a starting point for customized variants.

More information about the different options and customization is found in the Electrification.Batteries.Thermal.Information sub-package.

Electrical domain

The electrical domain model can include details of electrical routing in a specific battery pack. A few common models are provided in the Electrification.Batteries.Electrical.Pack package. These models include:

• Additional resistive losses of bus bars and connectors.
• Different ways of defining how the two poles of the battery pack relate to a common electrical ground potential. For example, it is common to have a known Electrification.Batteries.Electrical.Pack.SymmetricIsolated between the poles and the ground level.
• Contactors with pre-charge actuation (see the Electrification.Examples.ControlledStartup experiment).

The simple Electrification.Batteries.Electrical.Pack.Ideal model is generally the default choice if none of the above aspects are relevant.

An additional aspect to configure for array packs with individual cells, is how the cells are Electrification.Batteries.Electrical.Array.Cells.Routing in series and parallel. A few options are available in the Electrification.Batteries.Electrical.Array package. This also includes some examples of cell level loads, such as balancing circuits. However, for more than the basic cases, a custom electrical domain model would typically need to be created, to capture implementation aspects of a specific battery pack.

Controller domain

When no specific battery control functions are relevant to model, the Electrification.Batteries.Control.None controller can be selected. Some common uses cases when a controller model is needed are listed below:

1. When the battery should monitor and report its power limits (or other limits) to the loads in the system. This is the only way for the battery to ensure that its limits are not exceeded. The Electrification.Batteries.Control.LimitsFixed or Electrification.Batteries.Control.LimitsTabular example controllers could be used for this. The Electrification.Examples.BatteryCharging experiment demonstrates such an application.
2. When studying energy management control in a system, and the system controller needs information from the battery about its state. The Electrification.Batteries.Control.CellSensors controller is an example of this.
3. For model- or software-in-the-loop (MiL/SiL) function verification with a custom controller implementation. One such control function model is demonstrated in the Electrification.Batteries.Experiments.Imbalances.CellBalancing experiment. External control software can be included as imported FMUs.
4. When modeling a battery pack with actuators, e.g. for contactors with pre-charge, as is demonstrated in the Electrification.Examples.ControlledStartup experiment.

For general information about controller models, please refer to the Electrification.Information.UsersGuide.BasicConcepts.ControllersAndSignals.

Limits

A battery cell will generally have some limits of operation (voltage, current, power) that need to be respected to avoid damaging the cell. These limits are specified in the core model for the cell (in the Limits parameter tab).

Batteries are passive components that are not able to directly limit their output power. To ensure that the limits are not violated, the battery typically will have a BMS controller that communicates its limits to other controllers in the system that actuates the loads connected to the battery. This is demonstrated in the Electrification.Batteries.Experiments.Control.PowerLimits and Electrification.Examples.BatteryCharging experiments.

It can be useful to monitor if the specified operating limits are breached during a simulation. Such warnings and errors can be configured in the Limits tab at top level of the pack model. There, it is also possible to specify limits and monitoring for state of charge. An application of this is seen in the Electrification.Information.UsersGuide.Tutorials.GettingStarted.EnergyAndLosses, for running a simulation until the battery is depleted.

Temperature limits can be specified in the thermal domain model.

Initializing SoC

The SoC (State of Charge) of a battery is configured under the Initialization parameters tab. The SoC can be initialized either directly with the SOC_start parameter, or calculated indirectly from an open circuit voltage specified with OCV_start (when initialize_with_OCV=true). The later is useful for cases where the initial voltage is known more precisely than the SoC, for example when performing a simulation that should be matched against measurement data. This is demonstrated in the Electrification.Batteries.Experiments.Control.LimitedTimeSeries experiment.

The initialization parameters are defined in the battery interface class. This allows configuring the initialization in an experiment template, before a specific battery pack has been selected. An example of this is the Electrification.Batteries.Experiments.Verification.Templates.StaticDischarge, where the battery has been configured to start at 100 % SoC.