Build Model of Battery Module with Thermal Effects
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";
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.
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);
42
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");
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.