Build a Simple Model of a Battery Module in MATLAB and Simscape

Open Live Script

This example shows how to create and build a Simscape™ system model of a battery module in Simscape™ Battery™. The battery module is a 48 V battery for an electric bike application. 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, 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 cylindrical format.

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

The CylindricalGeometry object allows you to define the cylindrical geometrical arrangement of the battery cell. You can specify the height and radius of the cell by setting 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: [1x1 simscape.battery.builder.CylindricalGeometry]
    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 parameter 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 four cylindrical cells stacked in a square topology over four rows.

To create the ParallelAssembly object, use the Cell object you created before and specify the NumParallelCells, Rows, and Topology properties according to your design.

batteryParallelAssembly = ParallelAssembly(Cell = batteryCell,...
    NumParallelCells = 4, ...
    Rows = 4, ...
    Topology = "Square", ...
    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 13 parallel assemblies with an intergap between each assembly of 0.005 meters. You also define the model resolution of the module and add an ambient thermal boundary condition.

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

batteryModule = Module(ParallelAssembly = batteryParallelAssembly,...
    NumSeriesAssemblies = 13, ...
    InterParallelAssemblyGap = simscape.Value(0.005,"m"), ...
    ModelResolution = "Detailed", ...
    AmbientThermalPath = "CellBasedThermalResistance")

batteryModule = 
  Module with properties:

    NumSeriesAssemblies: 13
       ParallelAssembly: [1x1 simscape.battery.builder.ParallelAssembly]
        ModelResolution: "Detailed"
         SeriesGrouping: [1 1 1 1 1 1 1 1 1 1 1 1 1]
       ParallelGrouping: [4 4 4 4 4 4 4 4 4 4 4 4 4]

Show all properties

For more information, see the Module documentation page.

Visualize Battery Module and Check Model Resolution

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

disp(batteryModule.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.

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

nexttile(tl)
batteryModuleChart1 = BatteryChart(Parent = tl, Battery = batteryModule);
nexttile(tl)
batteryModuleChart2 = BatteryChart(Parent = tl, Battery = batteryModule, 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(batteryModule,"LibraryName","moduleLibrary");

Generating Simulink library 'moduleLibrary_lib' in the current directory '/tmp/Bdoc22b_2134332_1821819/tpacc0024e/simscapebattery-ex57213451' ...

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

To build a battery pack model, see the Build a Simple Model of a Battery Pack in MATLAB and Simscape example.