Manage Battery Run-Time Parameters with Centralized Script

Simscape™ Battery™ models that you create by using the battery pack builder objects comprise conditional and run-time parameters. When you create the battery objects, you can specify the conditional parameters of the generated battery models by using the CellModelBlock property of the underlying Cell object. The software defines the run-time parameters for these models, such as the battery cell impedance or the battery open-circuit voltage, after you create the model. You therefore cannot define the run-time parameters by using the battery pack builder objects.

To define the run-time parameters, 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 as "VariableNamesByType" or "VariableNamesByInstance", the function also generates a parameterization script that you can use to manage the run-time parameters of the modules and cells inside your system.

Manage Parameters and Initial Targets

Use the MaskInitialTargets and MaskParameters arguments of the buildBattery function to choose between default numeric values or variable names for the parameters and initial conditions in each Module (Generated Block) and ParallelAssembly (Generated Block) block in the generated library.

When you set the MaskParameters argument to "VariableNamesByType", the buildBattery function generates a script. Use this script to set each module and cell parameters, including the resistance and the open-circuit voltage, for all the battery modules in your battery pack. This option is useful when you want to change the parameters of all instances of a battery object type at once. If you also set the MaskInitialTargets argument to "VariableNamesByInstance", then the generated file contains the mask parameter definitions at the beginning.

If you want to parameterize each single instance of module or parallel assembly inside the generated library separately, set the MaskParameters argument to "VariableNamesByInstance". The buildBattery function then generates a script that contains a set of parameters for each instances of the same type of battery object. For example if a ModuleAssembly block contains five Module blocks of the same type, the function generates five different sets of parameters for the five module instances in the generated library. (since R2023b)

When you set the MaskInitialTargets argument to "VariableNamesByInstance", the buildBattery function generates a script. Use this script to set each of the initial values such as the initial temperature and state of charge for all the battery modules in your battery pack. If you also set the MaskParameters argument to "VariableNamesByType" or "VariableNamesByInstance", then the generated file contains the initial targets definitions at the end.

Create Battery Pack and Manage Run-Time Parameters

In this example, you create a simple battery pack and check the effects of setting the MaskParameters and the MaskInitialTargets arguments of the buildBattery function to "VariableNamesByType" and "VariableNamesByInstance".

Create a Pack object by creating Cell, ParallelAssembly, Module, and ModuleAssembly objects, in this order.

import simscape.battery.builder.*;
batteryCell = Cell(Geometry=CylindricalGeometry);
pSet = ParallelAssembly(Cell=batteryCell,NumParallelCells=48,Topology="Hexagonal",Rows=4);
module = Module(ParallelAssembly=pSet,NumSeriesAssemblies=4);
moduleAssembly = ModuleAssembly(Module=repmat(module,1,2));
pack = Pack(ModuleAssembly=repmat(moduleAssembly,1,4),BalancingStrategy="Passive");

pack = 

  Pack with properties:

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

Type-Specific Parameterization

Use the buildBattery function to build the library file from the Pack object. Set the LibraryName name-value argument of the function to give the library a meaningful name. Then, set MaskInitialTargets to "VariableNamesByInstance"and MaskParameters to "VariableNamesByType" to generate a parameterization script that you can use to manage the run-time parameters of the modules and parallel assemblies in the pack.

buildBattery(pack,LibraryName="batteriesVariableNames",...
MaskInitialTargets="VariableNamesByInstance",...
MaskParameters="VariableNamesByType")

Generating Simulink library 'batteriesVariableNames_lib' in the current directory 'C:\Work\' ...

This figure shows the content of the folder after the function generates the library files:

Open the generated library batteriesVariableNames SLX file to access the ModuleAssembly and Pack objects as Simscape subsystems.

Navigate to the ModuleAssembly1 subsystem by double-clicking the Pack1 subsystem. Double-click the Module1 and Module2 blocks to open the Property Inspector.

The software associates the same specific variable name to the values of each parameter in the Main section of both Module1 and Module2 blocks. You can specify these values inside the batteryVariableNames_param script without having to change them inside the model by opening the Property Inspector of each block individually.

Instance-Specific Parameterization (since R2023b)

The buildBattery function also allows you to parameterize each single instance of module or parallel assembly inside the generated library separately. Use the buildBattery function to build the library file from the Pack object again but, this time, set the MaskParameters argument to "VariableNamesByInstance". The function then generates a script that contains a set of parameters for each instances of the modules in the module assemblies inside the pack.

buildBattery(pack,LibraryName="batteriesVariableNamesByInstance",...
MaskInitialTargets="VariableNamesByInstance",...
MaskParameters="VariableNamesByInstance")

Generating Simulink library 'batteriesVariableNamesByInstance_lib' in the current directory 'C:\Work\' ...

Open the generated library batteriesVariableNamesByInstance SLX file to access the ModuleAssembly and Pack objects as Simscape subsystems.

Navigate to the ModuleAssembly1 subsystem by double-clicking the Pack1 subsystem. Double-click the Module1 and Module2 block2 to open the Property Inspector.

The software associates a specific different variable name to the values of each parameter in the Main section of the Module1 and Module2 blocks. You can specify these values inside the batteryVariableNamesByInstance_param script without having to change them inside the model by opening the Property Inspector of each block individually.