Build Model of Battery Pack with Cell Aging

This example shows how to create and build a Simscape™ system model of a battery pack that includes cell aging in Simscape™ Battery™. Predicting the lifetime of battery cells under a specific application is fundamental to assess warranty risk, develop second-life applications, and perform virtual design verification.

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.

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.

Once you have created your battery pack object, the buildBattery function creates a library in your working folder that contains a system model block of the battery pack. 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 buildBattery function.

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

This section shows how to programmatically generate a battery Pack object from the MATLAB® Command Window.

Create Cell Object and Specify Aging Effects

To create the battery Module object, first create a Cell object of pouch format.

pouchgeometry = PouchGeometry()

pouchgeometry = 
  PouchGeometry with properties:

         Length: [1×1 simscape.Value]
      Thickness: [1×1 simscape.Value]
    TabLocation: "Standard"
       TabWidth: [1×1 simscape.Value]
      TabHeight: [1×1 simscape.Value]
         Height: [1×1 simscape.Value]

The PouchGeometry object allows you to define the pouch geometrical arrangement of the battery cell. 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: [1×1 simscape.battery.builder.PouchGeometry]
    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 aging effects of the battery cell by specifying these properties:

• prm_age_capacity — Capacity calendar aging. This property allows you to decide whether to model the calendar aging effects on the capacity of a battery cell.

• prm_age_resistance — Internal resistance calendar aging. This property allows you to decide whether to model the calendar aging effects on the internal resistance of a battery cell.

• prm_age_modeling — Modeling option. This property allows you to specify how to mathematically model the aging effects on the capacity and internal resistance of a battery cell.

To simulate the cycling aging effects of the battery cell, in the BlockParameters property of the CellModelOptions property of the Cell object, set the prm_fade property to "equations".

batterycell.CellModelOptions.BlockParameters.prm_fade = "equations";

The Cell object also 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".

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 three pouch cells.

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

batteryparallelassembly = ParallelAssembly(Cell=batterycell,...
    NumParallelCells=3,StackingAxis="X");

For more information, see the ParallelAssembly documentation page.

Create Module Object

A battery module comprises multiple parallel assemblies connected in series. In this example, you create a battery module of 4 parallel assemblies stacked along the X axis, with an intergap between each assembly of 0.005 meters.

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

batterymodule = Module(ParallelAssembly=batteryparallelassembly,...
    NumSeriesAssemblies=4, ...
    InterParallelAssemblyGap=simscape.Value(0.005,"m"), ...
    StackingAxis="X");

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. In this example, you create a battery module assembly of five identical modules with an intergap between each module equal to 0.1 meters. By default, the ModuleAssembly object electrically connects the modules in series.

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

batterymoduleassembly = ModuleAssembly(Module=repmat(batterymodule,1,5),...
    InterModuleGap=simscape.Value(0.1,"m"), ...
    StackingAxis="Y");

For more information, see the ModuleAssembly documentation page.

Create Pack Object

You now have all the foundational elements to create your battery pack. A battery pack comprises multiple module assemblies connected in series or in parallel. In this example, you create a battery pack of five identical module assemblies with an intergap between each module assembly of 0.01 meters and a coolant thermal path.

To create the Pack object, use the ModuleAssembly object and specify the InterModuleAssemblyGap and CoolantThermalPath properties. Setting the CoolantThermalPath property automatically propagates its value to all the subcomponent battery objects inside this Pack object. However, this change does not propagate to the other battery objects in your MATLAB workspace.

batterypack = Pack(ModuleAssembly=repmat(batterymoduleassembly,1,5),...
    InterModuleAssemblyGap=simscape.Value(0.01,"m"),...
    CoolantThermalPath="CellBasedThermalResistance");

For more information, see the Pack documentation page.

Visualize Battery Pack and Check Model Resolution

To visualize the battery pack 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 pack.

f = uifigure(Color="w");

Then use the BatteryChart object to visualize the battery pack. To view the model resolution of the module, set the SimulationStrategyVisible property of the BatteryChart object to "On".

batterypackchart = BatteryChart(Parent=f,Battery=batterypack, ...
    SimulationStrategyVisible="on");

To add default axis labels to the battery plot, use the setDefaultLabels method of the BatteryChart object.

For more information about the BatteryChart object, see the BatteryChart documentation page.

Build Simscape Model for the Battery Pack Object

After you have created your battery objects, you need to convert them into Simscape models 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.

buildBattery(batterypack,LibraryName="packAgingExample")

This function creates the packAgingExample_lib and packAgingExample SLX library files in your working directory. The packAgingExample_lib library contains the Modules and ParallelAssemblies sublibraries.

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

The packAgingExample 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 packLibrary SLX file and double-click the subsystem.

To see how to evaluate a new and end-of-life (EOL) lithium-ion battery pack, see the Thermal Analysis for New and Aged Battery Packs example.

Explore Battery Pack and Build Model in Battery Builder App

In this example, you programmatically created the battery pack 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 pack that you created in this example. Open the Battery Builder app.

batteryBuilder

Import the battery pack object from the packAgingExample 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 packAgingExample MAT file.

The Battery Builder app now comprises a Pack 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 Pack 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.