Build Simple Model of Battery Module in MATLAB and Simscape
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
ParallelAssembly objects that comprise the battery module, and then use the
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.
After you create your battery module object, the
buildBattery function creates a library in your working folder that contains a system model block of a battery module. You can use this system model as a 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
To use the functions and objects in Simscape Battery, first import the required Simscape Battery package:
Module Object in MATLAB
This section shows how to programmatically generate a battery
Module object from the MATLAB® Command Window.
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"));
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
Radius properties of the
CylindricalGeometry object. For more information on the possible geometrical arrangements of a battery cell, see the
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
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
batterycell.CellModelOptions.BlockParameters.thermal_port = "model";
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 and specify the
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.
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 and specify the
batterymodule = Module(ParallelAssembly=batteryparallelassembly,... NumSeriesAssemblies=13, ... InterParallelAssemblyGap=simscape.Value(0.005,"m"), ... ModelResolution="Detailed", ... AmbientThermalPath="CellBasedThermalResistance")
batterymodule = Module with properties: NumSeriesAssemblies: 13 ParallelAssembly: [1×1 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
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
nexttile(tl) batteryModuleChart1 = BatteryChart(Parent=tl,Battery=batterymodule); nexttile(tl) batteryModuleChart2 = BatteryChart(Parent=tl,Battery=batterymodule,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 many more applications.
To create a library that contains the Simscape Battery model of the
Module object in this example, use the
This function creates a library named
moduleLibrary_lib in your working directory. This library contains the Simscape models of your M
To build a battery pack model, see the Build Simple Model of Battery Pack in MATLAB and Simscape example.
Explore Battery Module and Build Model in Battery Builder App
In this example, you programmatically created the battery module and all its subcomponents by calling the relevant objects and functions in the MATLAB Command Window. Alternatively, if you prefer a more interactive and visual approach, you can use the Battery Builder app. Using this app, you can interactively import existing battery objects or build them from scratch, explore and edit properties, and view the battery hierarchy and 3-D visualization. You can then build the Simscape system model of your objects and use it as a reference in your simulations. You can also export the objects in your workspace. To learn how to use the Battery Builder app to generate battery objects and build Simscape models, see the Get Started with Battery Builder App example.
Explore the battery module that you created in this example. Open the Battery Builder app.
Import the battery module object from the
moduleLibrary MAT file. Under the Battery Builder tab, in the Import section of the toolstrip, click Import. Then click Import from MAT-file and load the
moduleLibrary MAT file.
The Battery Builder app now comprises a
Module object and each of its subcomponents.
The Battery Browser panel on the left of the app contains all the battery objects in the current active session of the app. You can select an object, visualize it in the Selected Battery tab, check its hierarchy and child objects in the Battery Hierarchy panel, and edit its properties in the Properties panel on the right of the app.
You can edit properties of the plot under the Battery Chart tab, such as the axes labels, axes direction, title of the plot, and lights. You can also check the current simulation strategy and model resolution of the selected battery object. To visualize the simulation strategy in the plot, in the Simulation Strategy section of the toolstrip, check the Visible box.
Finally, if you modified your battery object and you want to create a library model of the updated M
odule object, under the Battery Builder tab, in the Library section of the toolstrip, click Create Library. In the new window, specify the folder in which you want to save the library, the library name, and whether to use numeric values or variable names for the mask parameters and mask initial targets.
Click Create Library to generate the updated library model of your battery object in the specified folder. Open this model to access your battery objects as Simscape blocks that you can use as a starting point 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.