Add Vectorized and Scalar Thermal Boundary Conditions to Battery Models

Since R2024a

This example shows how to add vectorized and scalar thermal boundary conditions to battery models by using Simscape™ Battery™. These thermal boundary conditions affect the battery cells at the edges or boundaries of a battery system, which experience different thermal dynamics compared to the battery cells in the battery assembly. The Battery Pack Builder workflow in Simscape™ Battery™ supports module-level and parallel assembly-level thermal boundary conditions to capture dynamics such as inter-cell temperature spreads and more complex thermal interactions to the environment and neighboring battery pack components. You can expose vectorized or scalar thermal nodes for the battery cells located at the Xmin, Xmax, Ymin, and Ymax boundaries.

Create Battery Parallel Assembly

To create a battery parallel assembly object, you must first design and create the foundational battery cell element. To create the Cell object, use the batteryCell function and assign a default cylindrical geometry.

batterycell = batteryCell(batteryCylindricalGeometry);

You can link the Cell object to any Simscape battery cell model block by using the CellModelBlockPath property of the CellModelOptions property. This examples uses theBattery Equivalent Circuit block as the fundamental cell model.

batterycell.CellModelOptions.CellModelBlockPath = "batt_lib/Cells/Battery Equivalent Circuit";

To assign the thermal boundary conditions and to simulate the thermal effects of the battery cell, in the BlockParameters property of the CellModelOptions property of the Cell object, set the ThermalModel property to "LumpedThermalMass".

batterycell.CellModelOptions.BlockParameters.ThermalModel = "LumpedThermalMass";

A 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 consisting of fifteen cylindrical cells.

To create the ParallelAssembly object, use the batteryParallelAssembly function and specify the Cell object as the first argument and the number of parallel cells as the second argument. Additionally, specify the number of rows, the model resolution, and enable the inter cell thermal path with the optional name-value arguments.

batteryparallelAssembly = batteryParallelAssembly(batterycell,15,Rows=3,ModelResolution="Detailed",InterCellThermalPath="on");

To specify the thermal boundary conditions at a given boundary, use the XminThermalNodes, XmaxThermalNodes, YminThermalNodes, or the YmaxThermalNodes property. You can set these properties independently of each other and they can all be enabled at the same time. You can set these properties to either "Scalar" or "Vectorized". Use "Scalar" for setting static or constant temperature conditions that do not vary along the side of the battery, which means that they are equal for every battery cell. Use "Vectorized" to model a varying temperature source for each cell at the interface, such as cases where there is coolant flow.

Setting these properties add a thermal resistance between the cell thermal port and the interface. This figure shows the configuration of the battery cells when you enable different thermal boundary conditions.

Add a thermal boundary condition for Xmin. Set the XminThermalNodes property to "Scalar".

batteryparallelAssembly.XminThermalNodes = "Scalar";

To automatically generate a battery model from the ParallelAssembly object, first define a name for the generated battery library.

libraryName = "pSetScalarLibrary";

To generate the library, use the buildBattery function.

buildBattery(batteryparallelAssembly,"LibraryName",libraryName);

Simulate Parallel Assembly with Scalar Thermal Nodes

Configure the battery simulation using a constant temperature source. Define the name of the model.

modelName = "batteryPSetScalarModel";

Run the setUpBatterySimulation function in this example to automatically generate a simulation model.

setUpBatterySimulation(modelName,libraryName,batteryparallelAssembly,"Scalar")

Specify the XminThermalResistance and InterCellThermalResistance properties.

set_param(strcat(modelName,"/",batteryparallelAssembly.Name),"XminThermalResistance","10");
set_param(strcat(modelName,"/",batteryparallelAssembly.Name),"InterCellThermalResistance","15");

Simulate the model.

out = sim(modelName,'StartTime','0','StopTime','160');

To dynamically plot the simulation results, first create a batterySimulationLog object.

 batterySimLog = batterySimulationLog(batteryparallelAssembly,out.simlog.ParallelAssembly1);

Select the variable that you want to dynamically visualize.

batterySimLog.SelectedVariable = "batteryTemperature";
batterySimLog.SelectedVariableUnit = "degC";
disp(batterySimLog)

  BatterySimulationLog with properties:

                 Battery: [1×1 simscape.battery.builder.ParallelAssembly]
                  SimLog: [1×1 simscape.logging.Node]
        SelectedVariable: "batteryTemperature"
    SelectedVariableUnit: "degC"
          ModelVariables: ["batteryVoltage"    "batteryTemperature"    "batteryCurrent"    "numCycles"    "socCell"]

Now visualize the simulation results by using the batterySimulationChart function.

f = uifigure("Color","w");
g = uigridlayout(f, [1,1]);
parallelAssemblyChart = batterySimulationChart(batterySimLog, Parent = g);
parallelAssemblyChartColorBar = colorbar(parallelAssemblyChart);
ylabel( parallelAssemblyChartColorBar, strcat(batterySimLog.SelectedVariable, " (", batterySimLog.SelectedVariableUnit,")") );

Simulate Parallel Assembly with Vectorized Thermal Nodes

Add a vectorized thermal boundary condition to Xmin. Set the XminThermalNodes property to "Vectorized".

batteryparallelAssembly.XminThermalNodes = "Vectorized"

batteryparallelAssembly = 
  ParallelAssembly with properties:

    NumParallelCells: 15
                Cell: [1×1 simscape.battery.builder.Cell]
            Topology: "Hexagonal"
                Rows: 3
     ModelResolution: "Detailed"

Show all properties

Define a name for the generated battery library.

libraryName = "pSetVectorizedLibrary";

To generate the library, use the buildBattery function.

buildBattery(batteryparallelAssembly,"LibraryName",libraryName);

Define the name of the model.

modelName = "batteryPSetVectorizedModel";

Run the setUpBatterySimulation function in this example to automatically generate a simulation model.

setUpBatterySimulation(modelName,libraryName,batteryparallelAssembly,"Vectorized")

Specify the XminThermalResistance and InterCellThermalResistance properties.

set_param(strcat(modelName,"/",batteryparallelAssembly.Name),"XminThermalResistance","1");
set_param(strcat(modelName,"/",batteryparallelAssembly.Name),"InterCellThermalResistance","15");

Simulate the model.

out = sim(modelName,'StartTime','0','StopTime','160');

To dynamically plot the simulation results, first create a BatterySimulationLog object.

batterySimLog = batterySimulationLog(batteryparallelAssembly,out.simlog.ParallelAssembly1);

Select the variable that you want to dynamically visualize.

batterySimLog.SelectedVariable = "batteryTemperature";
batterySimLog.SelectedVariableUnit = "degC";
disp(batterySimLog)

  BatterySimulationLog with properties:

                 Battery: [1×1 simscape.battery.builder.ParallelAssembly]
                  SimLog: [1×1 simscape.logging.Node]
        SelectedVariable: "batteryTemperature"
    SelectedVariableUnit: "degC"
          ModelVariables: ["batteryVoltage"    "batteryTemperature"    "batteryCurrent"    "numCycles"    "socCell"]

Now visualize the simulation results by using the BatterySimulationChart function.

f = uifigure("Color","w");
g = uigridlayout(f,[1,1]);
parallelAssemblyChart = batterySimulationChart(batterySimLog,Parent = g);
parallelAssemblyChartColorBar = colorbar(parallelAssemblyChart);
ylabel(parallelAssemblyChartColorBar,strcat(batterySimLog.SelectedVariable," (", batterySimLog.SelectedVariableUnit,")"));

Every cell now has a different temperature because they each connect to a different temperature from the vectorized temperature source. To reset the thermal boundary condition, set the XminThermalNodes property to "None".

batteryparallelAssembly.XminThermalNodes = "None";

Create Battery Module

A battery module comprises multiple series-connected parallel assemblies. In this example, you create a battery module using the parallel assembly you defined in the previous section. To create a battery module, call the batteryModule function and specify the ParallelAssembly object as the first argument and the number of series assemblies as the second argument. Additionally, specify the model resolution and the inter-cell thermal path by using the optional name-value arguments.

batterymodule = batteryModule(batteryparallelAssembly, 2, ...
    ModelResolution = "Detailed", ...
    InterCellThermalPath = "on");

Simulate Module with Scalar Thermal Nodes

Add a scalar thermal boundary condition to the Xmax boundary. Set the XmaxThermalNodes property to "Scalar".

batterymodule.XmaxThermalNodes = "Scalar"

batterymodule = 
  Module with properties:

    NumSeriesAssemblies: 2
       ParallelAssembly: [1×1 simscape.battery.builder.ParallelAssembly]
        ModelResolution: "Detailed"
         SeriesGrouping: [1 1]
       ParallelGrouping: [15 15]

Show all properties

Define a name for the generated battery library.

libraryName = "moduleScalarLibrary";

To generate the library, use the buildBattery function.

buildBattery(batterymodule,"LibraryName",libraryName)

Define the name of the model.

modelName = "batteryModuleScalarModel";

Run the setUpBatterySimulation function in this example to automatically generate a simulation model.

setUpBatterySimulation(modelName,libraryName,batterymodule,"Scalar")

Specify the XmaxThermalResistance and InterCellThermalResistance properties.

set_param(strcat(modelName,"/",batterymodule.Name),"XmaxThermalResistance","1");
set_param(strcat(modelName,"/",batterymodule.Name),"InterCellThermalResistance","15");

Simulate the model.

out = sim(modelName,'StartTime','0','StopTime','160');

To dynamically plot the simulation results, first create a BatterySimulationLog object.

batterySimLog = batterySimulationLog(batterymodule,out.simlog.Module1);

Select the variable that you want to dynamically visualize.

batterySimLog.SelectedVariable = "batteryTemperature";
batterySimLog.SelectedVariableUnit = "degC";
disp(batterySimLog)

  BatterySimulationLog with properties:

                 Battery: [1×1 simscape.battery.builder.Module]
                  SimLog: [1×1 simscape.logging.Node]
        SelectedVariable: "batteryTemperature"
    SelectedVariableUnit: "degC"
          ModelVariables: ["batteryVoltage"    "batteryTemperature"    "batteryCurrent"    "numCycles"    "socCell"]

Now visualize the simulation results by using the BatterySimulationChart function.

f = uifigure("Color","w");
g = uigridlayout(f,[1,1]);
moduleChart = batterySimulationChart(batterySimLog,Parent = g);
moduleChartColorBar = colorbar(moduleChart);
ylabel(moduleChartColorBar,strcat(batterySimLog.SelectedVariable," (", batterySimLog.SelectedVariableUnit,")"));

Every cell now has a similar temperature because they each connect to the same constant temperature source. Temperature differences are caused by the enabled inter-cell heat exchange.

Setup vectorized thermal nodes battery simulation

Add a vectorized thermal boundary condition at the Xmax boundary. Set the XmaxThermalNodes property to "Vectorized".

batterymodule.XmaxThermalNodes = "Vectorized"

batterymodule = 
  Module with properties:

    NumSeriesAssemblies: 2
       ParallelAssembly: [1×1 simscape.battery.builder.ParallelAssembly]
        ModelResolution: "Detailed"
         SeriesGrouping: [1 1]
       ParallelGrouping: [15 15]

Show all properties

Define a name for the generated battery library that will contain the module model:

libraryName = "moduleVectorizedLibrary";

To generate the library, use the buildBattery function.

buildBattery(batterymodule,"LibraryName",libraryName)

Define the name of the model.

modelName = "batteryModuleVectorizedModel";

Run the setUpBatterySimulation function in this example to automatically generate a simulation model.

setUpBatterySimulation(modelName,libraryName,batterymodule,"Vectorized")

Specify the XmaxThermalResistance, InterCellThermalResistance, NumNodes, and Temperature properties.

set_param(strcat(modelName,"/", batterymodule.Name),"XmaxThermalResistance","1");
set_param(strcat(modelName,"/", batterymodule.Name),"InterCellThermalResistance","15");
set_param(strcat(modelName,"/Temperature Source"),"NumNodes","10");
set_param(strcat(modelName,"/Temperature Source"),"temperature","[293, 295, 297, 299, 302, 304, 304, 306, 308, 312]");

Simulate the model.

out = sim(modelName,'StartTime','0','StopTime','160');

To dynamically plot the simulation results, first create a BatterySimulationLog object.

batterySimLog = batterySimulationLog(batterymodule,out.simlog.Module1);

Select the variable that you want to dynamically visualize.

batterySimLog.SelectedVariable = "batteryTemperature";
batterySimLog.SelectedVariableUnit = "degC";
disp(batterySimLog)

  BatterySimulationLog with properties:

                 Battery: [1×1 simscape.battery.builder.Module]
                  SimLog: [1×1 simscape.logging.Node]
        SelectedVariable: "batteryTemperature"
    SelectedVariableUnit: "degC"
          ModelVariables: ["batteryVoltage"    "batteryTemperature"    "batteryCurrent"    "numCycles"    "socCell"]

Now visualize the simulation results by using the BatterySimulationChart function.

f = uifigure("Color","w");
g = uigridlayout(f,[1,1]);
moduleChart = batterySimulationChart(batterySimLog,Parent = g);
moduleChartColorBar = colorbar(moduleChart);
ylabel(moduleChartColorBar,strcat(batterySimLog.SelectedVariable," (", batterySimLog.SelectedVariableUnit,")"));

Every cell at the relevant boundary now has a different temperature because they each connect to a different temperature from the vectorized temperature source.