Main Content

Module

Create module of battery parallel assemblies

Since R2022b

expand all in page

Description

Use Module to create a battery module object that represents a number of battery parallel assemblies connected electrically in series. You can use this object as an input to the ModuleAssembly object to create larger battery models.

To define the number of parallel assemblies or cells connected in series, use the NumSeriesAssemblies property. To generate a Simscape™ model of your Module object, use the buildBattery function. This object only supports the definition of structural or design parameters. You can modify the run-time parameters for this model block and its constituent cells after you create the model.

The Module object is the third stage of a battery pack system model in a bottom-up approach. Pack models are required for architecture evaluation in early development stages, software and hardware development, system integration and requirement evaluation, cooling system design, control strategy development hardware-in-the-loop, and many more applications.

By default, the parallel assemblies or cells are stacked along the y-axis of a Cartesian coordinate system and replicated a number of times equal to the value of the NumSeriesAssemblies property. To stack the parallel assemblies along the x-axis, set the StackingAxis property to "X".

Specify Model Resolution

The recommended model resolution for a Module object is "Lumped". You can increase or decrease the local resolution for a Module object by using the ModelResolution property. If you set the ModelResolution property to "Grouped", you can define a custom model resolution by using the SeriesGrouping and ParallelGrouping properties. For example, consider a battery architecture that comprises six parallel assemblies connected in series (NumSeriesAssemblies = 6). Each parallel assembly comprises six cells. This architecture requires at least 36 electrical battery models for simulation. To improve model speed and optimize the compilation times, you can choose to use only three electrical models by setting the SeriesGrouping property to [1 4 1]. The first and third submodules comprise one parallel assembly. The second submodule comprises the remaining four parallel assemblies.

Alternatively, you can choose to have further resolution for every parallel assembly by changing SeriesGrouping to [1 1 2 1 1].

For the submodules with a single parallel assembly, you can further discretize the electrical and thermal models to obtain the resolution for each cell by setting the ParallelGrouping property to [6 1 6] and [6 6 1 6 6], respectively.

For more information about model resolution and simulation strategy, see the SeriesGrouping and ParallelGrouping properties.

Thermal Boundary Conditions

Thermal boundary conditions define the specific heat transfer mechanisms that occur at each interface of a cell thermal model and its surroundings. In battery systems, cells are typically thermally coupled to different heat sources and sinks, all of which have an effect on the battery cell temperature. The number and type of thermal boundary conditions for a cell model depends on the thermal and mechanical design of the battery system.

For example, you can place cells on an aluminium cooling plate to enhance heat removal and, at the same time, join them together mechanically with a potting compound that effectively eliminates or decreases the inter-cell heat exchange path. The cell temperature has a direct impact on battery performance and lifetime. Therefore, it is crucial to predict this state in dynamic simulation.

Inside a battery object, you can set up a thermal network of lumped-thermal-mass cell models to simultaneously capture the thermal paths to the ambient, the coolant, and/or the cooling plate:

These options are not mutually exclusive. For example, your battery model can combine both the coolant thermal path and the cooling thermal plates to model individual thermal resistances between the individual cells and the sections of the cooling plate.

For more information about thermal paths, see the AmbientThermalPath, CoolantThermalPath, and CoolingPlate properties.

You can also model direct cell-to-cell heat exchange. This is important when you want to simulate more detailed thermal management strategies or even thermal propagation scenarios where inter-cell heat transfer happens at faster rates than ambient or coolant rates. In the battery industry, you can link battery cells to each other through many different means. For example, you can link cylindrical cells by using potting compounds for mechanical rigidity, stability, and thermal isolation, or other types of thermal interface materials. You can also use dielectric fluids or other compounds to heat or cool down cylindrical cells, as well as forced air convection.

You can define the thermal parameters for the inter-cell heat exchange after you create the battery model. You can find these parameters from first principles calculations and more detailed 3D simulations.

These options are not mutually exclusive.

For more information about inter-cell thermal paths, see the InterCellThermalPath and InterCellRadiativeThermalPath properties.

Creation

Syntax

import simscape.battery.builder.*; batteryModule = Module
import simscape.battery.builder.*; batteryModule = Module(Name=Value)

Description

import simscape.battery.builder.*; batteryModule = Module creates a battery module that comprises parallel assemblies with default property values.

example

import simscape.battery.builder.*; batteryModule = Module(Name=Value) sets Properties using one or more name-value arguments. For example, create a module with four default parallel assemblies stacked along the y-axis with a gap between the parallel assemblies equal to 0.05 m.

module = Module(...
    ParallelAssembly=ParallelAssembly(), ...
    NumSeriesAssemblies=4, ...
    StackingAxis="Y",... 
    InterParallelAssemblyGap=simscape.Value(0.05,"m"));

Properties

expand all

Parallel assembly component in the module, specified as a ParallelAssembly object. The Module object creates this component and then electrically connects it in series a number of times equal to the value of the NumSeriesAssemblies property.

Example: batteryModule.ParallelAssembly = ParallelAssembly

Number of parallel assemblies connected in series inside the module, specified as a strictly positive and finite integer. The value of this property must be less than 150.

Example: batteryModule.NumSeriesAssemblies = 48

Model resolution or fidelity in the simulation, specified as:

  • "Lumped" — Choose this value for the lowest fidelity. The module uses only one electrical mode. To obtain the fastest compilation time and running time, use this value.

  • "Detailed" — Choose this value for the highest fidelity. The module uses one electrical model and one thermal model for each battery cell.

  • "Grouped" — Choose this value to use a custom simulation strategy based on the SeriesGrouping and ParallelGrouping properties.

Example: batteryModule.ModelResolution = "Detailed"

Modeling strategy for the module along the series connections, specified as a row vector of positive integers.

The length of this vector specifies the number of individual electrical models required. Each entry specifies how many parallel assemblies are lumped within the specified electrical model. For example, if your module comprises four parallel assemblies (NumSeriesAssemblies = 4) and you set this property to [2 1 1], the object discretizes the module in three individual electrical models. The first model comprises two of the original parallel assemblies.

The sum of the entries in this vector must be equal to the value of the NumSeriesAssemblies property.

Example: batteryModule.SeriesGrouping = [2 1 1]

Dependencies

To enable this property, set the ModelResolution property to "Grouped".

Modeling strategy for every parallel assembly defined in the SeriesGrouping property, specified as a vector of positive integers. The length of this vector must be equal to the length of the SeriesGrouping property value.

Each entry of this vector specifies the number of individual electrical models for entry of the SeriesGrouping property. The values of the entries must be 1 or the value of the NumParallelCells property.

For example, assume that your module comprises these elements:

  • Four parallel assemblies (NumSeriesAssemblies = 4)

  • 48 cylindrical cells for each parallel assembly (NumParallelCells = 48)

  • Three individual electrical models, in which the first model comprises two of the original parallel assemblies (SeriesGrouping = [2 1 1])

If you set this property to [1 1 48], the object discretizes the module into 50 individual electrical models, where each cell of the fourth parallel assembly has an electrical model.

The value of an entry in this property must be 1 if the value of the corresponding entry of the SeriesGrouping property is larger than 1.

Example: batteryModule.ParallelGrouping = [1 1 48]

Dependencies

To enable this property, set the ModelResolution property to "Grouped".

Shortest distance between parallel assemblies inside the module, specified as a positive scalar or a simscape.Value object that represents a positive scalar with a unit of length. The value of this property must be less than 0.1 m.

If you set this property directly with a positive scalar value instead of using a simscape.Value object, the object converts the value to a simscape.Value object with meter as its physical unit.

Example: batteryModule.InterParallelAssemblyGap = simscape.Value(0.01,"m")

Example: batteryModule.InterParallelAssemblyGap = 0.01

State-of-charge balancing strategy for the module, specified as "None" or "Passive". Set this property to "Passive" to add an array of ideal balancing circuits electrically connected in parallel to every parallel assembly and a physical port of size equal to the value of the NumSeriesAssemblies property used for switch control. The switch is open when the control signal is equal to 0. The switch is closed when the control signal is equal to 1.

Example: batteryModule.BalancingStrategy = "Passive"

Option to use a simple thermal resistance block connected between the cells and a Simscape thermal network, specified as "CellBasedThermalResistance" or "None".

Note

Setting this property automatically propagates its value to all the subcomponent battery objects inside this Module object. However, this change does not propagate to the other battery objects in your MATLAB workspace.

Example: batteryModule.AmbientThermalPath = "CellBasedThermalResistance"

Option to use a simple thermal resistance block connected between the cells and a Simscape thermal network, specified as "CellBasedThermalResistance" or "None".

If you also define a cooling plate surface, the object connects the thermal resistance block between each battery thermal model and its corresponding element in the array of thermal nodes.

Note

Setting this property automatically propagates its value to all the subcomponent battery objects inside this Module object. However, this change does not propagate to the other battery objects in your MATLAB workspace.

Example: batteryModule.CoolantThermalPath = "CellBasedThermalResistance"

Option to use a cooling plate component at a specific surface boundary, specified as "Top", "Bottom", or "None".

Note

Setting this property automatically propagates its value to all the subcomponent battery objects inside this Module object. However, this change does not propagate to the other battery objects in your MATLAB workspace.

Example: batteryModule.CoolingPlate = "Top"

Since R2023a

Option to specify which cooling plate block you want to assign to the Module object at the boundary defined by the CoolingPlate property, specified as "batt_lib/Thermal/Edge Cooling", "batt_lib/Thermal/Parallel Channels", ""batt_lib/Thermal/U-Shaped Channels"", or "None".

Note

Setting this property automatically propagates its value to all the subcomponent battery objects inside this Module object. However, this change does not propagate to the other battery objects in your MATLAB workspace.

Example: batteryModule.CoolingPlateBlockPath = "batt_lib/Thermal/Edge Cooling"

Location of the battery object in a 3-D Cartesian coordinate system, specified as a vector of real and finite entries.

Example: batteryModule.Position = [0 0 0]

Name of the battery module, specified as a string.

Example: batteryModule.Name = "Module2"

Preferential stacking direction for the arrangement of battery cells in a 2-D Cartesian coordinate system, specified as "X" or "Y".

This figure shows the global coordinate system for batteries.

To plot the module object in the direction of the x-axis, set this property to "X" before creating the BatteryChart object.

Example: batteryModule.StackingAxis = "Y"

Additional non-cell-related mass added to the module by components such as busbars, tabs, and collector plates, specified as a strictly positive double greater than or equal to 1.

Example: batteryModule.MassFactor = 1.2

Option to use electrical resistance blocks to represent additional electrical resistances from non-cell components, specified as 'off', 'on', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

Example: batteryModule.NonCellResistance = 'on'

Since R2023a

Option to use thermal resistance blocks to represent a linear cell-to-cell heat transfer path between adjacent battery cells, specified as 'off', 'on', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

Enabling the inter-cell thermal path is useful only when you have selected a cell thermal model and more than one cell or cell model exists inside the battery.

You can define the value for the thermal resistance parameter after model creation.

If you set this property to 'on', you cannot set the InterCellRadiativeThermalPath property to 'on'.

Note

Setting this property automatically propagates its value to all the subcomponent battery objects inside this Module object. However, this change does not propagate to the other battery objects in your MATLAB workspace.

Example: batteryModule.InterCellThermalPath = "on"

Since R2023a

Option to use thermal resistance blocks to represent a radiative cell-to-cell heat transfer path between adjacent battery cells, specified as 'off', 'on', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

Enabling the inter-cell radiative thermal path is useful only when you have selected a cell thermal model and more than one cell or cell model exists inside the battery.

You can define the value for the radiation heat transfer parameters after model creation.

If you set this property to 'on', you cannot set the InterCellThermalPath property to 'on'.

Note

Setting this property automatically propagates its value to all the subcomponent battery objects inside this Module object. However, this change does not propagate to the other battery objects in your MATLAB workspace.

Example: batteryModule.InterCellRadiativeThermalPath = "on"

This property is read-only.

Volume of the battery, returned as a simscape.Value object with unit of volume.

This property is read-only.

Cumulative mass of the battery, returned as a simscape.Value object with a unit of mass.

Since R2023a

This property is read-only.

Cumulative cell capacity of the battery, returned as a simscape.Value object with unit of current multiplied by time.

The value of this property is equal to the individual cell capacity multiplied by the number of cells electrically connected in parallel inside this battery object.

Since R2023a

This property is read-only.

Cumulative cell energy of the battery, returned as a simscape.Value object with unit of energy.

The value of this property is equal to the individual cell energy multiplied by the total number of cells inside this battery object.

This property is read-only.

Number of cell model blocks in the simulation, returned as a double.

Since R2023a

This property is read-only.

Number of the internal thermal connections between the cells, returned as an integer.

Since R2023a

This property is read-only.

Number of the internal thermal connections between the parallel assemblies, returned as an integer.

Since R2023a

This property is read-only.

2-D map of the internal connections between the cells, returned as a matrix of integer.

The cell numbering convention refers to the Layout property. To understand the number assigned to each cell and how they relate to the their neighbors,see the Layout property.

For example, for a battery module with three parallel assemblies of four pouch cells each, this property is equal to:

Since R2023a

This property is read-only.

2-D map of the internal connections between the parallel assemblies, returned as a matrix of integer.

The parallel assembly numbering increases in the direction of the stacking axis.

For example, for a battery module with three parallel assemblies of four pouch cells each, this property is equal to:

Since R2023a

This property is read-only.

2-D map of the internal connections between the individual battery cell models inside each parallel assembly to their corresponding neighbor in the neighboring parallel assembly, returned as a matrix of integer.

The cell numbering convention for the mapping is related to the Layout property of each individual parallel assembly.

This property is read-only.

Numbering for all of the cells inside of the battery, returned as a structure.

This property is read-only.

Vectorized thermal node information for external boundary conditions, returned as a structure. This information comprise XY location, XY dimensions, and number of thermal nodes. If you do not define a battery cell geometry, this property is an empty structure.

Since R2023a

This property is read-only.

2-D distribution of sub-components or cells within the parent, returned as a matrix of integer.

This property depends on the StackingAxis property and on the number of cells.

This property is read-only.

Type of battery object, returned as "Module".

Examples

collapse all

Create a Cell object with a pouch geometry.

batteryCell = Cell(Geometry=PouchGeometry)

Create a ParallelAssembly object of three cells with the default topology.

pSet = ParallelAssembly(Cell=batteryCell,NumParallelCells=3)

Use this ParallelAssembly object to create a Module object of 10 parallel assemblies connected in series.

batteryModule = Module(ParallelAssembly=pSet,NumSeriesAssemblies=10)

Visualize the module by using a BatteryChart object.

moduleChart = BatteryChart(Battery=batteryModule);

Create a Cell object and use it to create a ParallelAssembly object.

batteryCell = Cell(Geometry=CylindricalGeometry)
pSet = ParallelAssembly(Cell=batteryCell,NumParallelCells=4,Rows=4)

Use this ParallelAssembly object to create a Module object of 10 parallel assemblies connected in series.

batteryModule = Module(ParallelAssembly=pSet,NumSeriesAssemblies=10)

Discretize this module in three individual electrical models. The second model comprises eight of the original parallel assemblies of the module.

batteryModule.SeriesGrouping = [1 8 1]

To verify your modeling resolution, visualize the module by using the BatteryChart object and click on the "Show/hide simulation strategy" button on the top-right corner of the plot.

moduleChart = BatteryChart(Battery=module);

Version History

Introduced in R2022b

See Also

Apps

Objects

Functions

Simscape Blocks

Topics