Main Content

Build Model of Battery Module with Inter-Cell Heat Exchange

This example shows how to create and build a Simscape™ system model of a battery module with inter-cell heat exchange in Simscape™ Battery™. Inter-cell heat transfer mechanisms are relevant in the design of battery systems, including analyzing battery thermal propagation and evaluating electro-thermal load cycles in virtual verification. The heat transfer mechanisms supported in Simscape™ Battery™ are conduction, convection, and radiation. To create the system model of a battery module, you must first create the Cell and ParallelAssembly objects that comprise the battery module, and then use the buildBattery function. The buildBattery function generates Simscape models for these Simscape Battery objects:

This function creates a library in your working folder that contains a system model block of a battery module. Use this model as reference in your simulations. You can modify the run-time parameters for this model block, such as the battery cell resistance or the battery open-circuit voltage, after you create the model. To define the run-time parameters, specify them in the block mask of the generated Simscape models or use the MaskParameters argument of the buildBattery function.

To use the functions and objects in Simscape Battery, first import the required Simscape Battery package:

import simscape.battery.builder.*

Create Battery Module Object in MATLAB

To create a battery module object, you must first design and create the foundational elements of the battery module.

This figure shows the hierarchy of a battery pack object in a bottom-up view:

A battery module comprises multiple parallel assemblies. These parallel assemblies, in turn, comprise a number of battery cells connected electrically in parallel under a specific topological configuration or geometrical arrangement.

Create Cell Object

To create the Module object, first create a Cell object with the cylindrical geometry.

cylindricalGeometry = CylindricalGeometry(Height=simscape.Value(0.07,"m"),...

The CylindricalGeometry object defines the cylindrical geometrical arrangement of the battery cell. To specify the height and radius of the cell, set the Height and Radius properties of the CylindricalGeometry object. For more information on the possible geometrical arrangements of a battery cell, see the PouchGeometry and PrismaticGeometry documentation pages.

Now use this CylindricalGeometry object to create a cylindrical battery cell.

batteryCell = Cell(Geometry=cylindricalGeometry)
batteryCell = 
  Cell with properties:

            Geometry: [1×1 simscape.battery.builder.CylindricalGeometry]
    CellModelOptions: [1×1 simscape.battery.builder.CellModelBlock]
                Mass: [1×1 simscape.Value]
            Capacity: [1×1 simscape.Value]
              Energy: [1×1 simscape.Value]

Show all properties

The Cell object allows you to simulate the thermal effects of the battery cell by using a simple 1-D model. To simulate the thermal effects of the battery cell, in the BlockParameters property of the CellModelOptions property of the Cell object, set the thermal_port property to "model".

batteryCell.CellModelOptions.BlockParameters.thermal_port = "model";

Create ParallelAssembly Object

A battery parallel assembly comprises multiple battery cells connected electrically in parallel under a specific topological configuration or geometrical arrangement. In this example, you create a parallel assembly of three cylindrical cells stacked in a square topology over three rows.

To create the ParallelAssembly object, use the Cell object and specify the NumParallelCells, StackingAxis, and Topology properties according to your design.

batteryParallelAssembly = ParallelAssembly(Cell=batteryCell,...
    NumParallelCells=3, ...
    StackingAxis="X", ...

Create Module Object

You now have all the foundational elements to create your battery module. A battery module comprises multiple parallel assemblies connected in series. In this example, you create a battery module of six parallel assemblies. You also define the model resolution of the module.

To create the Module object, use the ParallelAssembly object and specify the NumSeriesAssemblies, InterParallelAssemblyGap, and the ModelResolution properties.

batteryModule = Module(ParallelAssembly=batteryParallelAssembly,...
    NumSeriesAssemblies=6, ...

Enable Inter-Cell Thermal Path

To enable cell-to-cell heat conduction paths, set the InterCellThermalPath property of the batteryModule object to "on". The battery cell model block must enable a valid thermal model with at least one thermal domain port.

batteryModule.InterCellThermalPath = "on";

The Module and ParallelAssembly objects simulate thermal interactions between adjacent battery cells by creating a thermal domain network. In this thermal domain network, the thermal model of every battery cell is inter-connected to each of their neighbors. Enabling the InterCellThermalPath property thermally connects adjacent cells by using a Simscape™ thermal resistance block. You can set the Thermal resistance parameter after you build the Simscape™ battery block. You can set a different value for every thermal connection between two adjacent cells.

View Information on Inter-Cell Thermal Path Connectivity

To view the total number of inter-cell thermal connections inside the Module object, use the NumInterCellThermalConnections property. This property is the sum of all inter-cell thermal connections inside every parallel assembly in the module.


To view the number of thermal connections between adjacent ParallelAssemblies objects, use the NumInterParallelAssemblyThermalConnections property.


To visualize the cell-to-cell thermal connections, use the InterCellConnectionsMapping property. The InterCellConnectionsMapping is a 2-D matrix that shows the connections between adjacent battery cell models. For each column, the first row of the InterCellConnectionsMapping property shows the cell index in a specific parallel assembly from which the thermal connection originates from. The second row contains the index of the corresponding destination cell. This thermal connection is bidirectional as with all thermal domain connections in Simscape™. For a Module object, the indexes are based only on the number of cells connected in parallel in the parallel assembly.

     1     2     1     2     1     2     1     2     1     2     1     2
     2     3     2     3     2     3     2     3     2     3     2     3

To visualize the parallelAssembly-to-parallelAssembly thermal connections, use the InterParallelAssemblyConnectionsMapping property. The InterParallelAssemblyConnectionsMapping is a 2-D matrix that shows the connections between adjacent battery cell models from adjacent parallel assemblies inside the module. For each column, the first row of the InterParallelAssemblyConnectionsMapping shows the ParallelAssembly index inside the Module from which the thermal connection originates from. The second row contains the index of the corresponding destination ParallelAssembly.

     1     1     1     1     1     1     1     2     2     2     2     2     2     2     3     3     3     3     3     3     3     4     4     4     4     4     4     4     5     5     5     5     5     5     5
     2     2     2     2     2     2     2     3     3     3     3     3     3     3     4     4     4     4     4     4     4     5     5     5     5     5     5     5     6     6     6     6     6     6     6

The battery builder in Simscape Battery also supports radiation heat exchange between cells. Enabling the InterCellRadiativeThermalPath property thermally connects adjacent cell models by using a Simscape™ radiation block. This figure shows a comparison between the two methods:

Visualize Battery Module and Check Model Resolution

To obtain the number of Simscape Battery(Table-based) blocks used for the module simulation, use the NumModels property of your Module object.


To visualize the battery module before you build the system model and to view its model resolution, use the BatteryChart object. Create the figure where you want to visualize your battery module.

f = uifigure(Color="w");
tl = tiledlayout(1,2,"Parent",f,"TileSpacing","Compact");

Then use the BatteryChart object to visualize the battery module. To view the model resolution of the module, set the SimulationStrategyVisible property of the BatteryChart object to "On".

batteryModuleChart1 = BatteryChart(Parent=tl,Battery=batteryModule);
batteryModuleChart2 = BatteryChart(Parent=tl,Battery=batteryModule,SimulationStrategyVisible="On");

Build Simscape Model of Module Object

After you create your battery objects, you need to convert them into Simscape models to use them in block diagrams. You can then use these models as reference for your system integration and requirement evaluation, cooling system design, control strategy development, hardware-in-the-loop, and many more applications.

To create a library that contains the Simscape Battery model of the Module object, use the buildBattery function.


This function creates a library named interCellHeatExchangeModule_lib in your working folder. Open this model to access your battery objects as Simscape blocks.

See Also

Related Examples

More About