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.

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.

The PrismaticGeometry object allows you to define the pouch geometrical arrangement of the battery cell. To create a CylindricalGeometry object, use the batteryCylindricalGeometry function. Specify the height as the first argument, the length as the second argument, and the thickness as the third argument.

prismaticGeometry = batteryPrismaticGeometry(simscape.Value(0.2,"m"),...
    simscape.Value(0.35,"m"),simscape.Value(0.07,"m"));

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.

prismaticCell1 = batteryCell(prismaticGeometry)

prismaticCell1 = 
  Cell with properties:

            Geometry: [1×1 simscape.battery.builder.PrismaticGeometry]
    CellModelOptions: [1×1 simscape.battery.builder.CellModelBlock]
                Mass: 0.1000 (kg)
            Capacity: 5 (A*hr)
              Energy: 50 (W*hr)

Show all properties

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

prismaticCell2 = batteryCell(prismaticGeometry)

prismaticCell2 = 
  Cell with properties:

            Geometry: [1×1 simscape.battery.builder.PrismaticGeometry]
    CellModelOptions: [1×1 simscape.battery.builder.CellModelBlock]
                Mass: 0.1000 (kg)
            Capacity: 5 (A*hr)
              Energy: 50 (W*hr)

Show all properties

prismaticCell2.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 batteryParallelAssembly function. Specify the Cell object as the first argument and the number of cells in parallel as the second argument.

parallelAssembly1 = batteryParallelAssembly(prismaticCell1,1)

parallelAssembly1 = 
  ParallelAssembly with properties:

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

Show all properties

parallelAssembly2 = batteryParallelAssembly(prismaticCell2,1)

parallelAssembly2 = 
  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 batteryModule function. Specify the ParallelAssembly object as the first argument and the number of parallel assemblies in series as the second argument. To define the gap between the parallel assemblies, use the name-value argument InterParallelAssemblyGap.

module1 = batteryModule(parallelAssembly1,4,...
    InterParallelAssemblyGap=simscape.Value(0.005,"m"), ...
    ModelResolution="Lumped", ...
    StackingAxis="X")

module1 = 
  Module with properties:

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

Show all properties

module2 = batteryModule(parallelAssembly2,4,...
    InterParallelAssemblyGap=simscape.Value(0.005,"m"), ...
    ModelResolution="Lumped", ...
    StackingAxis="X")

module2 = 
  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 batteryModuleAssembly function and specify the Module objects as the first argument. To define the additional properties, use the name-value arguments InterModuleGap and NumLevels.

moduleAssembly = batteryModuleAssembly([module1,module2,module1,module2],...
    InterModuleGap=simscape.Value(0.02,"m"), ...
    NumLevels=1)

moduleAssembly = 
  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 batteryModule function and specify the ModuleAssembly objects as the first argument.

pack = batteryPack(repmat(moduleAssembly,1,2),...
    StackingAxis="Y");

For more information, see the Pack documentation page.

Visualize Battery Pack

Visualize the battery pack before you build the system model with a BatteryChart object. To create the object use the batteryChart function. To add default axis labels to the battery plot, use the setDefaultLabels method of the BatteryChart object.

packChart = batteryChart(pack);
packChart.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(pack,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.