Main Content

Build Detailed Model of Battery Pack from Cylindrical Cells

Open Live Script

This example shows how to create and build Simscape™ system models for various battery designs and configurations based on cylindrical battery cells in Simscape™ Battery™. 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 pack. 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.

During the first half of this example, you first define the key properties of a cylindrical battery cell and block model. You then use this cylindrical battery cell as a fundamental repeating unit inside a parallel assembly component. In the industry, this component is also called a "sub-module", a "super-cell", a "P-set", or just a "cell". You later employ this parallel assembly to define a battery module, which is then used to create a module assembly and finally a battery pack. These larger battery systems all use the battery cell as a fundamental repeating unit. Throughout the workflow, you visualize the geometry and the relative positioning of these battery systems by using the batterychart function.

In the second half of the example, you modify the modeling methodology and the model resolution of the Module, ModuleAssemblies, and Pack objects before generating the final Simscape battery model. You can perform the geometrical aggregation or stacking of any battery object along the sequence either along the X or Y axis. These axis mirror the Coordinate Systems in Vehicle Dynamics Blockset (Vehicle Dynamics Blockset).

Create and Visualize Battery Objects 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 and Visualize Battery Cell Object

A battery cell is an electrochemical energy storage device that provides electrical energy from stored chemical energy. An electrochemical battery cell is the fundamental building block in the manufacturing of larger battery systems. To obtain the required energy and voltage levels, multiple battery cells are typically connected electrically in parallel and/or in series.

To meet the battery packaging and space requirements, you can arrange the battery cells in three main geometrical arrangements: cylindrical, pouch, or prismatic. To visualize a single battery cell, you must first define its geometry.

Define a cylindrical geometry by using the batteryCylindricalGeometry function.

cylindricalGeometry = batteryCylindricalGeometry();

The CylindricalGeometry object has two properties:

  • Radius — Radius of the cylindrical geometry, specified as a simscape.Value object that represents a scalar with a unit of length.

  • Height — Height of the cylindrical geometry, specified as a simscape.Value object that represents a scalar with a unit of length.

Specify custom values for the Radius and Height properties of the cylindrical geometry.

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

For more information on the possible geometrical arrangements of a battery cell, see the PouchGeometry and PrismaticGeometry documentation pages.

To mirror the real-world behavior, the Simscape Battery™ Cell object is the foundational element for the creation of a battery pack system model. To create a battery cell with the specified cylindrical geometry use the batteryCell function and specify the cylindricalGeometry object as the first argument.

cylindricalCell = batteryCell(cylindricalGeometry);

Specify a custom value for the mass of the battery cell by using the Mass property.

cylindricalCell.Mass = simscape.Value(0.07,"kg");
disp(cylindricalCell)
  Cell with properties:

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

Show all properties

Visualize the battery cell by using the batteryChart function. Create the figure where you want to visualize your battery cell.

f = figure("Color","white");

Then use the batteryChart function to visualize the battery cell.

cellChart = batteryChart(f,cylindricalCell);
title(cellChart,"Cylindrical Cell")

For more information, see the batteryChart documentation page.

By default, the Battery (Table-Based) block is the electrical and thermal model used to represent and simulate this battery cell in Simscape. When scaled up into larger battery systems like a parallel assembly or a module, this model is also scaled up accordingly depending on the model resolution. To display the information about the cell model block, use the CellModelOptions property of the batterycell object.

disp(cylindricalCell.CellModelOptions.CellModelBlockPath);
batt_lib/Cells/Battery (Table-Based)

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 parameter to "model".

cylindricalCell.CellModelOptions.BlockParameters.thermal_port = "model";

You can modify all the conditional parameters of the Battery (Table-Based) block by using the CellModelOptions property.

disp(cylindricalCell.CellModelOptions.BlockParameters);
              SOC_port: no
          T_dependence: no
           prm_age_OCV: OCV
      prm_age_capacity: disabled
      prm_age_modeling: equation
    prm_age_resistance: disabled
               prm_dir: noCurrentDirectionality
               prm_dyn: off
              prm_fade: disabled
              prm_leak: disabled
          thermal_port: model

Create and Visualize Battery ParallelAssembly Object

A battery parallel assembly comprises multiple battery cells connected electrically in parallel under a specific topological configuration or geometrical arrangement. To create a parallel assembly, use the batteryParallelAssembly function. Specify the cell as the first argument and the number of cells connected in parallel as the second argument.

In this example, you create a parallel assembly using 48 cylindrical cells, stacked in a square topology over four rows.

parallelAssembly = batteryParallelAssembly(...
    cylindricalCell,48,...
    Topology="Square", ...
    Rows=4, ...
    InterCellGap=simscape.Value(0.001,"m"));

The Topology property is a function of the cell format. For cylindrical cells, the available topologies are "Hexagonal" and "Square". By default, the ParallelAssembly object stacks the cells along the Y axis.

Visualize the battery parallel assembly. Create the figure where you want to visualize your battery parallel assembly and use the batteryChart function.

f = figure("Color","white");
parallelAssemblyChart = batteryChart(f,parallelAssembly);
title(parallelAssemblyChart,"Parallel Assembly Chart")

You can modify all the public properties inside the parallel assembly after its creation. For example, you can set the topology of the parallel assembly to the more space-efficient hexagonal configuration. Set the Topology property of the ParallelAssembly object to "Hexagonal".

parallelAssembly.Topology = "Hexagonal";

Visualize the hexagonal parallel assembly.

f = figure("Color", "white");
parallelAssemblyChart = batteryChart(f,parallelAssembly);
title(parallelAssemblyChart,"Parallel Assembly Chart")

You can check the cell packaging volume and the mass of any battery by accessing the PackagingVolume and CumulativeMass properties.

disp(parallelAssembly.PackagingVolume)
    0.0015 (m^3)

disp(parallelAssembly.CumulativeMass)
    3.3600 (kg)

Create and Visualize Battery Module Object

A battery module comprises multiple parallel assemblies connected in series. To create a module, use the batteryModule function. Specify the parallel assembly as the first argument and the number of parallel assemblies connected in series as the second argument. You can stack or geometrically assemble batteries along the X or Y axis of a Cartesian coordinate system by using the StackingAxis name-value argument.

In this example, you create a battery module using four parallel assemblies, stacked along the X axis, with an intergap between each assembly equal to 0.0001 meters.

module = batteryModule(...
    parallelAssembly,4, ...
    StackingAxis="X",... 
    InterParallelAssemblyGap=simscape.Value(0.0001, "m"));

Visualize the battery Module object. Create the figure where you want to visualize your battery module and use the batteryChart function.

f = figure("Color", "white");
modulechart = batteryChart(f, module);
title(modulechart, "Module Chart")

Display the total packaging volume and cumulative mass of your battery module.

disp(module.PackagingVolume)
    0.0058 (m^3)

disp(module.CumulativeMass)
   13.4400 (kg)

You can modify all the public properties inside the module after its creation. For example, modify the gap between parallel assemblies and check how the packaging volume increases due to this change. Set the InterParallelAssemblyGap property of the Module object to 0.005 m and visualize the object.

module.InterParallelAssemblyGap = simscape.Value(0.005,"m");

f = figure("Color","white");
moduleChart = batteryChart(f,module);
title(moduleChart,"Module Chart")

Now check the new packaging volume of your battery module.

disp(module.PackagingVolume)
    0.0061 (m^3)

The packaging volume increased due to the increase in gap between parallel assemblies.

Reset the InterParallelAssemblyGap property back to its original value.

module.InterParallelAssemblyGap = simscape.Value(0.001,"m");

Create and Visualize Battery ModuleAssembly Object

A battery module assembly comprises multiple battery modules connected in series or in parallel. To create a module assembly, use the batteryModuleAssembly function and specify the modules as the first argument. If a module assembly comprises many identical modules, use the repmat function. Otherwise use an array of distinct modules.

In this example, you create a battery module assembly by using two identical Module objects, stacked along the Y axis, with an intergap between each module equal to 0.005 meters. By default, the ModuleAssembly object electrically connects the modules in series.

moduleAssembly = batteryModuleAssembly(...
    repmat(module,1,2), ...
    StackingAxis="Y",... 
    InterModuleGap=simscape.Value(0.005, "m"), ...
    CircuitConnection="Series");

Visualize the battery ModuleAssembly object. Create the figure where you want to visualize your battery module assembly and use the batteryChart function.

f = figure("Color","white");
moduleAssemblyChart = batteryChart(f,moduleAssembly);
title(moduleAssemblyChart,"Module Assembly Chart")

All battery objects, including modules, have a Name property. The ModuleAssembly object automatically assigns a unique name to all of its modules. To display the name of each module in your ModuleAssembly object, use the Name property.

disp(moduleAssembly.Module(1).Name);
Module1

disp(moduleAssembly.Module(2).Name);
Module2

You can modify the Name property to rename any of the modules inside a module assembly. Specify a new name for the two modules in your battery module assembly.

moduleAssembly.Module(1).Name = "MyModuleA";
moduleAssembly.Module(2).Name = "MyModuleB";
disp(moduleAssembly.Module(1).Name);
MyModuleA

disp(moduleAssembly.Module(2).Name);
MyModuleB

A ModuleAssembly battery object also allows you to stack the modules along the Z axis. To stack modules along the Z axis, use the NumLevels name-value argument. It defines the number of levels, tiers, or floors of the module assembly. The ModuleAssembly object stacks the modules symmetrically according to the number of levels and modules in the assembly.

For example, create a new module assembly object that comprises four identical modules stacked along the Z axis on two levels.

zStackedModuleAssembly = batteryModuleAssembly(...
    repmat(module,1,4), ...
    StackingAxis="Y",...
    NumLevel=2,...
    InterModuleGap=simscape.Value(0.01,"m"));

Visualize the ModuleAssembly object, zStackedModuleAssembly.

f = figure("Color","white");
moduleAssemblyChart = batteryChart(f,zStackedModuleAssembly);
title(moduleAssemblyChart,"Module Assembly Chart")

Create and Visualize Battery 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. To create a pack, use the batteryPack function and specify the module assemblies as the first argument. If a pack comprises many identical module assemblies, use the repmat function. Otherwise use an array of distinct module assemblies.

In this example, you create a battery pack of three module assemblies. The first module assembly is the module assembly stacked along the Z axis, zStackedModuleAssembly. The other two module assemblies are two identical module assemblies.

pack = batteryPack(...
    [zStackedModuleAssembly,repmat(moduleAssembly,1,2)], ...
    StackingAxis="X",...
    InterModuleAssemblyGap=simscape.Value(0.005, "m"));

Visualize the battery Pack object. Create the figure where you want to visualize your battery pack and use the batteryChart function.

f = figure("Color", "white");
packChart = batteryChart(f,pack);
title(packChart,"Pack Chart")

The Pack object automatically assigns a unique name to all of its module assemblies upon creation. To display the name of each module assembly in your Pack object, use the Name property.

disp(pack.ModuleAssembly(1).Name);
ModuleAssembly1

disp(pack.ModuleAssembly(2).Name);
ModuleAssembly2

You can use a Pack object to define a common cell balancing strategy for all the modules inside the pack by specifying the BalancingStrategy property. 

pack.BalancingStrategy = "Passive";

Modifying this property at this level automatically modifies the same property inside all of the underlying module components in the battery pack. Check the balancing strategy of the modules inside your battery pack.

disp(pack.ModuleAssembly(1).Module(1).BalancingStrategy);
Passive

disp(pack.ModuleAssembly(1).Module(2).BalancingStrategy);
Passive

The BalancingStrategy property of each module in the pack updated to reflect the change you have applied to the BalancingStrategy property of your Pack object.

Use the PackagingVolume and CumulativeMass properties to display the cumulative pack mass and packaging volume of your battery pack.

disp(pack.PackagingVolume)
    0.0486 (m^3)

disp(pack.CumulativeMass)
  107.5200 (kg)

Modify Model Resolution of Battery Objects

The ParallelAssembly and Module objects have a ModelResolution property that allows you to set the level of fidelity of the generated Simscape model used in simulations. You can specify the ModelResolution property to either:

  • Lumped — Lowest fidelity. The battery object uses only one electrical model. To obtain the fastest compilation time and running time, use this value.

  • Detailed — Highest fidelity. The battery object uses one electrical model and one thermal model for each battery cell.

  • Grouped — Custom simulation strategy, available only to Module objects.

You can view the simulation strategy by using the SimulationStrategyVisible property of the batteryChart function.

Modify Model Resolution for ParallelAssembly Object

A ParallelAssembly object uses a single battery Cell object as a foundational repeating unit upon its creation.

Create a new ParallelAssembly object with the battery cell that you created at the beginning of this example. By default, the ModelResoultion property of a ParallelAssembly object is set to "Lumped".

lumpedParallelAssembly = batteryParallelAssembly(...
    cylindricalCell,48, ...
    Rows=4, ...
    InterCellGap=simscape.Value(0.001,"m"));

Visualize the ParallelAssembly object and check the model resolution by setting the SimulationStrategyVisible property to "on".

f = figure("Color","white");
lumpedParallelAssemblyChart = batteryChart(f,lumpedParallelAssembly,SimulationStrategyVisible="on");

Only one single cell model block represents all the cell components inside the orange box.

If you set the ModelResolution property of the parallel assembly to "Detailed", the ParallelAssembly object instantiates a number of cell model blocks equal to the value of the NumParallelCells property and connects them electrically in parallel in Simscape.

Change the model resolution of the previous ParallelAssembly object to "Detailed" and visualize it by using the BatteryChart object with the name-value argument SimulationStrategyVisible specified as "on".

detailedParallelAssembly = lumpedParallelAssembly;
detailedParallelAssembly.ModelResolution = "Detailed";
f = figure("Color","white");
detailedParallelAssemblyChart = batteryChart(f,detailedParallelAssembly,SimulationStrategyVisible="on");

A number of cell model blocks equal to the value of the NumParallelCells property represents each cell component.

Modify Model Resolution for Module Object

Lumped Module Resolution

By default, the model resolution in modules and parallel assemblies is set to "Lumped". This means that the generated battery model in Simscape only uses one electrical model to electrically simulate all the battery cells within that system.

Check how the lumped module resolution works in Module objects. Create a Module object that comprises four parallel assemblies stacked along the X axis. 

lumpedModule = batteryModule(...
    lumpedParallelAssembly,4, ...
    StackingAxis="X",... 
    InterParallelAssemblyGap=simscape.Value(0.0001,"m"));

Visualize the Module object and check the model resolution by specifying the SimulationStrategyVisible name-value pair as "on".

f = figure("Color","white");
lumpedModuleChart = batteryChart(f,lumpedModule,SimulationStrategyVisible="on");

One electrical cell model simulates all the cells contained in the dotted orange box.

Add thermal boundary conditions to your module. To define a thermal path to ambient, set the AmbientThermalPath property to "CellBasedThermalResistance".

lumpedModule.AmbientThermalPath = "CellBasedThermalResistance";

Detailed Module Resolution

Now change the model resolution of the previous Module object to "Detailed" and visualize it by using the batteryChart function with the name-value pair SimulationStrategyVisible specified as "on".

detailedModule = lumpedModule;
detailedModule.ParallelAssembly.ModelResolution = "Detailed";
detailedModule.ModelResolution = "Detailed";

For cylindrical modules, the detailed model resolution is not recommended as many cells are present and it is important to keep the total number of models between 30 and 50.

f = figure("Color","white");
detailedModuleChart = batteryChart(f,detailedModule,SimulationStrategyVisible="on");

A number of cell model blocks equal to the value of the NumParallelCells property represents each cell component.

Add thermal boundary conditions to your detailed battery module. To define the location of a cooling plate, set the CoolingPlate property to "Bottom".

detailedModule.CoolingPlate = "Bottom";

Grouped Module Resolution

For battery modules, you can also set the ModelResolution property to "Grouped". This simulation strategy helps increasing the model performance.

module.ModelResolution = "Grouped";

When you set the ModelResolution property of a module to "Grouped", you can define an additional simulation strategy by using the SeriesGrouping and ParallelGrouping properties:

  • SeriesGrouping — Custom modeling strategy for the module along the series connections, specified as a strictly positive array of doubles. The length of the array of this property specifies the number of individual electrical models required. Each element value of this array specifies how many parallel assemblies are lumped within the specified electrical model. The sum of the elements in the array must be equal to value of the NumSeriesAssemblies property. For example, if your module comprises four parallel assemblies (NumSeriesAssemblies = 4) and you set this property to [2 1 1], the module is discretized in three individual electrical models where the first model comprises two of the original parallel assemblies.

module.SeriesGrouping = [1,2,1];
f = figure("Color","white");
groupedModuleChart = batteryChart(f,module,SimulationStrategyVisible="on");

  • ParallelGrouping — Custom modeling strategy for the module for every parallel assembly defined in the SeriesGrouping property, specified as a strictly positive array of doubles. The length of the array of this property must be equal to the length of the array of the SeriesGrouping property. Each element of this array specifies the number of individual electrical models for every element in the array of the SeriesGrouping property. The values of the elements of this array can be equal only to either 1 or the value of the NumParallelCells property. For example, if your module comprises four parallel assemblies (NumSeriesAssemblies = 4), 48 cylindrical cells for each parallel assembly (NumParallelCells = 48), and three individual electrical models where the first model comprises two of the original parallel assemblies (SeriesGrouping = [2 1 1]), then if you set this property to [1 1 48], the module is discretized in 50 individual electrical models where each cell of the fourth parallel assembly has an electrical model.

Assign Model Resolution for ModuleAssembly Object

Creating a ModuleAssembly object retains the model resolutions of the specified battery modules.

Create a ModuleAssembly object by using the lumpedmodule Module object that you created in the previous step.

lumpedModuleAssembly = batteryModuleAssembly(...
    repmat(lumpedModule,1,2), ...
    StackingAxis="Y",... 
    InterModuleGap=simscape.Value(0.005,"m"));

Then visualize the ModuleAssembly object and check the model resolution by specifying the name-value pair SimulationStrategyVisible as "on".

f = figure("Color","white");
lumpedModuleAssemblyChart = batteryChart(f,lumpedModuleAssembly,SimulationStrategyVisible="on");
title(lumpedModuleAssemblyChart,"Module Assembly Lumped Simulation Strategy Chart")

The model resolution of each module is retained as "Lumped".

Assign Model Resolution for Pack Object

Creating a Pack object retains the model resolutions of the Modules in the specified Module Assemblies.

Create a Pack object containing the moduleassemblylumped object.

lumpedPack = batteryPack(...
    repmat(lumpedModuleAssembly,1,4), ...
    StackingAxis="X",... 
    InterModuleAssemblyGap=simscape.Value(0.01,"m"));

Then visualize the Pack object and check the model resolution by specifying the name-value pair SimulationStrategyVisible as "on".

f = figure("Color","white");
lumpedPackChart = batteryChart(f,lumpedPack,SimulationStrategyVisible="on");
title(lumpedPackChart,"Pack Lumped Simulation Strategy Chart")

The model resolution of each module within the Pack is retained as "Lumped".

Build Simscape Model for the Battery Objects

After you create 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.

To create a library that contains the Simscape Battery model of all the batteries object in this example, use the buildBattery function.

buildBattery(lumpedPack,LibraryName="cylindricalPackExample");

This function creates the cylindricalPackExample_lib and cylindricalPackExample SLX library files in your working directory. The cylindricalPackExample_lib library contains the modules and parallel assemblies sublibraries.

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

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

Pack.png

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.

For more information, see the buildBattery documentation page.

See Also

Related Examples

More About