Build Model of Hybrid-Cell Battery Pack

This example shows how to build a Simscape™ system model of a hybrid-cell battery pack with two sets of cell run-time parameters. The generated battery pack model contains two types of battery modules, each with different battery cell components inside. Use this example to analyze the performance effects of combining different battery cells within a single battery system, such as power capability versus range.

To create the system model of a battery pack, you must first create the Cell, ParallelAssembly, Module, and ModuleAssembly objects that comprise the battery pack, and then use the buildBattery function. The buildBattery function creates a library in your working folder that contains a system model block of a battery pack 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. If you specify the MaskParameters argument, the function also generates a parameterization script that helps you managing the run-time parameters of the different modules and cells inside the pack.

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

import simscape.battery.builder.*

Create Battery Pack Object in MATLAB

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

This figure shows the overall process to create a battery pack object in a bottom-up approach:

A battery pack comprises multiple module assemblies. These module assemblies, in turn, comprise a number of battery modules connected electrically in series or in parallel. The battery modules are made of multiple parallel assemblies which, in turn, comprise a number of battery cells connected electrically in parallel under a specific topological configuration or geometrical arrangement.

Create Cell Objects

To create the battery Pack object, first create a Cell object of prismatic format.

prismaticgeometry = PrismaticGeometry(Height=simscape.Value(0.2,"m"),...
    Length=simscape.Value(0.35,"m"),Thickness=simscape.Value(0.07,"m"));

The PrismaticGeometry object allows you to define the pouch geometrical arrangement of the battery cell. You can specify the height, length, and thickness of the cell by setting the Height, Length, and Thickness properties of the PrismaticGeometry object. For more information on the possible geometrical arrangements of a battery cell, see the CylindricalGeometry and PouchGeometry documentation pages.

Now use this PrismaticGeometry object to create a prismatic battery cell and assign its name.

batterycell1 = Cell(Geometry=prismaticgeometry)

batterycell1 = 
  Cell with properties:

            Geometry: [1×1 simscape.battery.builder.PrismaticGeometry]
    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

batterycell1.Name = "CellChemistryType1";

To create a Module object with a different set of cell parameters, create a Cell object of prismatic format and change its name.

batterycell2 = Cell(Geometry=prismaticgeometry)

batterycell2 = 
  Cell with properties:

            Geometry: [1×1 simscape.battery.builder.PrismaticGeometry]
    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

batterycell2.Name = "CellChemistryType2";

For more information, see the Cell documentation page.

Create ParallelAssembly Objects

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 two parallel assemblies of one prismatic cell each.

To create the ParallelAssembly objects, use the Cell objects and specify the NumParallelCells property according to your design.

batteryparallelassembly1 = ParallelAssembly(Cell=batterycell1,...
    NumParallelCells=1)

batteryparallelassembly1 = 
  ParallelAssembly with properties:

    NumParallelCells: 1
                Cell: [1×1 simscape.battery.builder.Cell]
            Topology: "SingleStack"
                Rows: 1
     ModelResolution: "Lumped"

Show all properties

batteryparallelassembly2 = ParallelAssembly(Cell=batterycell2,...
    NumParallelCells=1)

batteryparallelassembly2 = 
  ParallelAssembly with properties:

    NumParallelCells: 1
                Cell: [1×1 simscape.battery.builder.Cell]
            Topology: "SingleStack"
                Rows: 1
     ModelResolution: "Lumped"

Show all properties

For more information, see the ParallelAssembly documentation page.

Create Module Objects

A battery module comprises multiple parallel assemblies connected in series. In this example, you create two battery modules of four parallel assemblies each, with an intergap between each assembly of 0.005 meters.

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

batterymodule1 = Module(ParallelAssembly=batteryparallelassembly1,...
    NumSeriesAssemblies=4, ...
    InterParallelAssemblyGap=simscape.Value(0.005,"m"), ...
    ModelResolution="Lumped", ...
    StackingAxis="X")

batterymodule1 = 
  Module with properties:

    NumSeriesAssemblies: 4
       ParallelAssembly: [1×1 simscape.battery.builder.ParallelAssembly]
        ModelResolution: "Lumped"
         SeriesGrouping: 4
       ParallelGrouping: 1

Show all properties

batterymodule2 = Module(ParallelAssembly=batteryparallelassembly2,...
    NumSeriesAssemblies=4, ...
    InterParallelAssemblyGap=simscape.Value(0.005,"m"), ...
    ModelResolution="Lumped", ...
    StackingAxis="X")

batterymodule2 = 
  Module with properties:

    NumSeriesAssemblies: 4
       ParallelAssembly: [1×1 simscape.battery.builder.ParallelAssembly]
        ModelResolution: "Lumped"
         SeriesGrouping: 4
       ParallelGrouping: 1

Show all properties

For more information, see the Module documentation page.

Create ModuleAssembly Object

A battery module assembly comprises multiple battery modules connected in series or in parallel. The battery module assembly in this example comprises the two modules you created before twice in an alternating sequence. By default, the ModuleAssembly object electrically connects the modules in series.

To create the ModuleAssembly object, use the Module objects and specify the InterModuleGap and NumLevels properties.

batterymoduleassembly = ModuleAssembly(Module=[batterymodule1,batterymodule2,batterymodule1,batterymodule2],...
    InterModuleGap=simscape.Value(0.02,"m"), ...
    NumLevels=1)

batterymoduleassembly = 
  ModuleAssembly with properties:

    Module: [1×4 simscape.battery.builder.Module]

Show all properties

For more information, see the ModuleAssembly documentation page.

Create Pack Object

You now have all the foundational elements to create your hybrid battery pack. A battery pack comprises multiple module assemblies connected in series or in parallel. In this example, you create a battery pack of two module assemblies.

To create the Pack object, use the ModuleAssembly object.

batterypack = Pack(ModuleAssembly=repmat(batterymoduleassembly,1,2),...
    StackingAxis="Y");

For more information, see the Pack documentation page.

Visualize Battery Pack

To visualize the battery pack before you build the system model, use the BatteryChart object. To add default axis labels to the battery plot, use the setDefaultLabels method of the BatteryChart object.

batterypackchart = BatteryChart(Battery=batterypack);
batterypackchart.setDefaultLabels

For more information, see the BatteryChart documentation page.

Build Simscape Model for Battery Pack Object

After you create 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 Pack object you created in this example, use the buildBattery function and set the MaskInitialTargets and MaskParameters arguments. The MaskInitialTargets and MaskParameters arguments allow you to choose between default numeric values or variable names for the parameters in each Module and Parallel Assembly block in the generated library. If you set these arguments to "VariableNamesByInstance", the function generates a script with all the run-time parameters and initial conditions required for simulation.

buildBattery(batterypack,LibraryName="hybridBatteryPack",...
    MaskInitialTargets="VariableNamesByInstance",...
    MaskParameters="VariableNamesByInstance");

The buildBattery function creates the hybridBatteryPack_lib and hybridBatteryPack SLX library files in your working directory. The hybridBatteryPack_lib library contains the Modules and ParallelAssemblies sublibraries.

To access the Simscape models of your Module and ParallelAssembly objects, open the hybridBatteryPack_lib SLX file, double-click the sublibrary, and drag the Simscape blocks in your model.

The hybridBatteryPack library contains the Simscape models of your ModuleAssembly and Pack objects.

The Simscape models of your ModuleAssembly and Pack objects are subsystems. You can look inside these subsystems by opening the hybridBatteryPack_lib SLX file and double-click the subsystem.

MaskParameters and MaskInitialTargets

The MaskInitialTargets and MaskParameters arguments allow you to choose between default numeric values or variable names for the parameters and initial conditions in each Module and Parallel Assembly block in the generated library.

By setting the MaskParameters argument to VariableNamesByInstance, the buildBattery function generates a hybridBatteryPack_param.m file where you can individually assign all the module and cell parameters, like the resistance, the open circuit voltage, and other parameters, for all the types of battery modules inside your battery pack. If you also set the MaskInitialTargets argument to VariableNamesByInstance, then the generated file contains the mask parameter definition at the beginning.

By setting the MaskInitialTargets argument to VariableNamesByInstance, the buildBattery function generates a hybridBatteryPack_param.m file where you can individually assign the initial temperature, state-of-charge, and other conditions, for all your battery modules in your battery pack. If you also set the MaskParameters argument to VariableNamesByInstance, then the generated file contains the initial targets definition at the end.

Check the effect of setting the MaskParameters and the MaskInitialTargets arguments to VariableNames. Open the hybridBatteryPack_lib SLX file and navigate to the ModuleAssembly1 subsystem by double-clicking the Pack1 subsystem. Double-click on the Module1 block to open the Property Inspector.

A specific variable name is associated to the values of each parameter in the Main section of the Module1 block. You can then easily specify these values inside the hybridBatteryPack_param.m file without having to change them inside the model by opening the Property Inspector of each block individually.