Build Model of Battery Module with Thermal Effects

Open Live Script

This example shows how to create and build a Simscape™ system model of a battery module with thermal effects in Simscape™ Battery™. 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 allows you to automatically generate 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 that you can use as reference in your simulations. The run-time parameters for these models, such as the battery cell impedance or the battery open-circuit voltage, are defined after the model creation and are therefore not covered by the Battery Pack Builder classes. To define the run-time parameters, you can either 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 overall process to create a battery module object in a bottom-up approach:

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 battery Module object, first create a Cell object of pouch format.

pouchGeometry = PouchGeometry(Height = simscape.Value(0.1,"m"),...
    Length = simscape.Value(0.3,"m"), TabLocation = "Opposed" );

The PouchGeometry object allows you to define the cylindrical geometrical arrangement of the battery cell. You can specify the height, radius, and location of tabs of the cell by setting the Height, Radius, and TabLocation properties of the PouchGeometry object. For more information on the possible geometrical arrangements of a battery cell, see the CylindricalGeometry and PrismaticGeometry documentation pages.

Now use this PouchGeometry object to create a pouch battery cell.

batteryCell = Cell(Geometry = pouchGeometry)

batteryCell = 
  Cell with properties:

            Geometry: [1x1 simscape.battery.builder.PouchGeometry]
    CellModelOptions: [1x1 simscape.battery.builder.CellModelBlock]
                Mass: [1x1 simscape.Value]

Show all properties

For more information, see the Cell documentation page.

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" and the T_dependence property to "yes".

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

You can define the thermal boundary conditions for battery parallel assemblies and modules only if you have previously defined a thermal model at the cell level.

Create ParallelAssembly Object

A battery parallel assembly comprise 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 pouch cells.

To create the ParallelAssembly object, use the Cell object you created before and specify the NumParallelCells property.

batteryParallelAssembly = ParallelAssembly(Cell = batteryCell,...
    NumParallelCells = 3, ...
     ModelResolution = "Detailed");

For more information, see the ParallelAssembly documentation page.

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 14 parallel assemblies with an intergap between each assembly of 0.005 meters. You also define the model resolution of the module.

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

detailedBatteryModule = Module(ParallelAssembly = batteryParallelAssembly,...
    NumSeriesAssemblies = 14, ...
    InterParallelAssemblyGap = simscape.Value(0.005,"m"), ...
    ModelResolution = "Detailed");

For more information, see the Module documentation page.

Define Thermal Boundary Conditions

For your Module object, you can define the thermal paths to the ambient, the coolant, and the location of the cooling plate by using the AmbientThermalPath, CoolantThermalPath, and CoolingPlate properties.

Define Ambient Thermal Path

To define a thermal path to ambient, set the AmbientThermalPath property to "CellBasedThermalResistance".

detailedBatteryModule.AmbientThermalPath = "CellBasedThermalResistance";

This command adds and connects one Thermal Resistor block to every thermal port in a cell model. The other thermal ports from all resistors connect to a single thermal node. You can then connect this thermal node with a constant temperature source or other blocks in the Simscape libraries.

Define Coolant Thermal Path

To define a thermal path to ambient, set the CoolantThermalPath property to "CellBasedThermalResistance".

detailedBatteryModule.CoolantThermalPath = "CellBasedThermalResistance";

You can use the Thermal Resistor block to capture the conduction resistance relative to the cell, the thermal interface materials, and other materials along the path to the coolant. If you define a cooling system such as a cooling plate for the battery module, the other thermal port of the Thermal Resistor block is connected to an array of thermal nodes connector.

Define Cooling Plate Location

To define the location of the cooling plate on your battery module, set the CoolingPlate property to either "Top" or "Bottom".

detailedBatteryModule.CoolingPlate = "Bottom";

This command connects every thermal node of each cell model in your battery module to a corresponding element inside an array of thermal nodes connector. If a CoolantThermalPath has been enabled, then a thermal resistance will be added between each battery model and its corresponding element inside the arrary of thermal nodes.

The array of thermal nodes is exposed at the Module level as a single connector but is multi-dimensional. You can connect an array of thermal nodes only to another array of thermal nodes of the same size. You can add a Cooling Plate block from the Simscape Battery library as heat sink.

To facilitate multi-dimensional thermal domain connections, you can use the ThermalNodes property of your Module object as input to the Cooling Plate block. You can view the number of thermal nodes, dimensions, and locations of the thermal nodes of the underlying cell models by accesing the ThermalNodes property.

disp(detailedBatteryModule.ThermalNodes);

        Bottom: [1x1 struct]
     Locations: [42x2 double]
    Dimensions: [42x2 double]
      NumNodes: 42

Visualize Battery Module and Check Model Resolution

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

disp(detailedBatteryModule.NumModels);

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.

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

f = uifigure(Color="w");
tl = tiledlayout(1,2,"Parent",f,"TileSpacing","Compact");
nexttile(tl)
batteryModuleChart1 = BatteryChart(Parent = tl, Battery = detailedBatteryModule); 
nexttile(tl)
batteryModuleChart2 = BatteryChart(Parent = tl, Battery = detailedBatteryModule, SimulationStrategyVisible = "On");

{"String":"Figure contains objects of type simscape.battery.builder.batterychart.","Tex":[],"LaTex":[]}

For more information, see the BatteryChart documentation page.

Build Simscape Model for the Battery Module Object

After you have created your battery objects, you need to convert them into Simscape models to be able 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 much more.

To create a library that contains the Simscape Battery model of the Module object you created in this example, use the buildBattery function.

buildBattery(detailedBatteryModule,"LibraryName","moduleBTMSExample")

Generating Simulink library 'moduleBTMSExample_lib' in the current directory '/tmp/Bdoc22b_2134332_1821819/tpacc0024e/simscapebattery-ex62888892' ...

This function creates a library named moduleBTMSExample_lib in your working directory. This library contains the Simscape models of your Module and ParallelAssembly objects.

To build a more detailed model of a battery pack, see the Build Detailed Model of Battery Pack From Pouch Cells example.

To see an application of a battery thermal effects model with a coolant thermal path, see the Protect Battery During Charge and Discharge for Electric Vehicle example.