Module

Generated Simscape model of battery module

Since R2022b

Description

The Module block represents a custom generated system model of a battery module. You can create this Simscape™ block by using the buildBattery function with a Module object as an input argument. The Module generated block is inside the Simulink library that you specify in the LibraryName argument of the buildBattery function.

Note

To allow for structural changes and further customization, when you add the Module masked library block from the parent library to a Simulink^® model, the linked block does not contain the link or path to the parent library block. If you modify any of the battery structural properties, such as NumSeriesAssemblies or NumParallelCells, you must rebuild the original parent library and copy the block in your model again.

For more information about parent and linked blocks, see Linked Blocks.

Variables

To set the priority and initial target values for the block variables prior to simulation, use the Initial Targets section in the block dialog box or Property Inspector. For more information, see Set Priority and Initial Target for Block Variables.

For a detailed list of the variables in the ParallelAssembly block, see the Initial Targets (Variables) section.

Nominal values provide a way to specify the expected magnitude of a variable in a model. Using system scaling based on nominal values increases the simulation robustness. Nominal values can come from different sources, one of which is the Nominal Values section in the block dialog box or Property Inspector. For more information, see System Scaling by Nominal Values.

Examples

Build Simple Model of Battery Module in MATLAB and Simscape

Create and build a Simscape system model of a battery module with Simscape Battery™.

Open Live Script

Build Simple Model of Battery Pack in MATLAB and Simscape

Create and build a Simscape system model of a battery pack with Simscape Battery.

Open Live Script

Ports

Input

CB — Cell balancing, unitless

physical signal

Cell balancing port, specified as a physical signal.

Dependencies

To enable this port, set the BalancingStrategy property of the Module object to "Passive". Alternatively, set the BalancingStrategy property to "Passive" inside the parent object of which the Module object is a subcomponent.

Conserving

+ — Positive terminal

electrical

Electrical conserving port associated with the positive terminal of the battery module.

- — Negative terminal

electrical

Electrical conserving port associated with the negative terminal of the battery module.

AH — Ambient thermal port

thermal

Thermal conserving port associated with the ambient thermal path.

Dependencies

To enable this port, set the AmbientThermalPath property of the Module object to "CellBasedThermalResistance". Alternatively, set the AmbientThermalPath property to "CellBasedThermalResistance" inside the parent object of which the Module object is a subcomponent.

CH — Coolant thermal port

thermal

Thermal conserving port associated with the coolant thermal path.

Dependencies

To enable this port, set the CoolantThermalPath property of the Module object to "CellBasedThermalResistance". Alternatively, set the CoolantThermalPath property to "CellBasedThermalResistance" inside the parent object of which the Module object is a subcomponent.

Note

If you set the CoolingPlate property to either "Top" or "Bottom" inside the Module object or inside the top-level parent object of which the Module object is a subcomponent, then this port is not enabled.

CPT — Cooling plate top port

thermal array-of-nodes

Thermal conserving port used to connect the top side of the module with a cooling plate. The size of this port depends on the number of models in the system. If you set the ModelResolution property to “Lumped”, this port outputs a scalar. If you set the ModelResolution property to “Detailed”, this port outputs a vector of size equal to the number of cells in the system. If you set the ModelResolution property to “Grouped”, this port outputs a vector of size depending on the grouping strategy.

Dependencies

To enable this port, set the CoolingPlate property of the Module object to "Top". Alternatively, set the CoolingPlate property to "Top" inside the parent object of which the Module object is a subcomponent.

CPB — Cooling plate bottom port

thermal array-of-nodes

Thermal conserving port used to connect the bottom side of the module with a cooling plate. The size of this port depends on the number of models in the system. If you set the ModelResolution property to “Lumped”, this port outputs a scalar. If you set the ModelResolution property to “Detailed”, this port outputs a vector of size equal to the number of cells in the system. If you set the ModelResolution property to “Grouped”, this port outputs a vector of size depending on the grouping strategy.

Dependencies

To enable this port, set the CoolingPlate property of the Module object to "Bottom". Alternatively, set the CoolingPlate property to "Bottom" inside the parent object of which the Module object is a subcomponent.

Parameters

Note

The names of these parameters and variables depend on the block you have specified in the CellModelOptions property of the underlying Cell object that constitutes this module.

The names of the parameters and variables in this page refer to a Cell object with the Battery (Table-Based) block as the cell component model block. If you specify a custom block for the cell component model, the names of the parameters and variables might differ.

The parameters of this block need to be set for the cell-level and depend on how you define the Module object that you use to generate this custom model. The block parameters are divided into these sections:

• Main

• Dynamics

• Fade

• Calendar Aging

• Thermal

• Cell Balancing

The visibility of each section also depends on the generating Module object.

For a full list of the parameters in the Main, Dynamics, Fade, and Calender Aging sections, see the Battery (Table-Based) block.

Thermal

Thermal mass — Thermal mass

100 J/K (default) | positive scalar

Energy required to raise the temperature of the thermal port by one degree.

Cell level coolant thermal path resistance — Coolant thermal path resistance at cell level

1.2 K/W (default) | positive scalar | row vector of positive scalars

Resistance of the coolant thermal path at cell level. The size of this parameter is equal to the total number of electrical models in the system.

Dependencies

To enable this parameter, set the CoolantThermalPath property of the Module object to "CellBasedThermalResistance". Alternatively, set the CoolantThermalPath property to "CellBasedThermalResistance" inside the parent object of which the Module object is a subcomponent.

Cell level ambient thermal path resistance — Ambient thermal path resistance at cell level

25 K/W (default) | positive scalar | row vector of positive scalars

Resistance of the ambient thermal path at cell level. The size of this parameter is equal to the total number of electrical models in the system.

Dependencies

To enable this parameter, set the CoolantThermalPath property of the Module object to "CellBasedThermalResistance". Alternatively, set the CoolantThermalPath property to "CellBasedThermalResistance" inside the parent object of which the Module object is a subcomponent.

Inter-cell thermal path resistance — Thermal path resistance between cells

1 K/W (default) | scalar | row vector of scalars

Since R2023a

Resistance of the thermal path between the cells inside the module. The size of this parameter must be equal to the number of inter-cell thermal connections that this block models.

Dependencies

To enable this parameter, set the InterCellThermalPath property of the Module object to "On". Alternatively, set the InterCellThermalPath property to "On" inside the parent object of which the Module object is a subcomponent.

Inter-parallel assembly thermal path resistance — Thermal path resistance between parallel assemblies

1 K/W (default) | scalar | row vector of scalars

Since R2023a

Resistance of the thermal path between the parallel assemblies inside the module. The size of this parameter must be equal to the number of inter-parallel assembly thermal connections that this block models.

Dependencies

To enable this parameter, set the InterCellThermalPath property of the Module object to "On". Alternatively, set the InterCellThermalPath property to "On" inside the parent object of which the Module object is a subcomponent.

Inter-cell radiation heat transfer area — Transfer area of radiation heat between cells

1e-3 m^2 (default) | scalar | row vector of scalars

Since R2023a

Area of the radiation heat transfer between the cells inside the module. The size of this parameter must be equal to the number of inter-cell thermal connections that this block models.

Dependencies

To enable this parameter, set the InterCellRadiativeThermalPath property of the Module object to "On". Alternatively, set the InterCellRadiativeThermalPath property to "On" inside the parent object of which the Module object is a subcomponent.

Inter-cell radiation heat transfer coefficient — Coefficient of radiation heat transfer between cells

1e-6 W/(K^4*m^2) (default) | scalar | row vector of scalars

Since R2023a

Coefficient of the radiation heat transfer between the cells inside the module. The size of this parameter must be equal to the number of inter-cell thermal connections that this block models.

Dependencies

To enable this parameter, set the InterCellRadiativeThermalPath property of the Module object to "On". Alternatively, set the InterCellRadiativeThermalPath property to "On" inside the parent object of which the Module object is a subcomponent.

Inter-parallel assembly area for radiation heat transfer — Area of radiation heat transfer between parallel assemblies

1e-3 m^2 (default) | scalar | row vector of scalars

Since R2023a

Area of the radiation heat transfer between the parallel assemblies inside the module. The size of this parameter must be equal to the number of inter-parallel assemblies thermal connections that this block models.

Dependencies

To enable this parameter, set the InterCellRadiativeThermalPath property of the Module object to "On". Alternatively, set the InterCellRadiativeThermalPath property to "On" inside the parent object of which the Module object is a subcomponent.

Inter-parallel assembly coefficient for radiation heat transfer — Coefficient of radiation heat transfer between parallel assemblies

1e-6 W/(K^4*m^2) (default) | scalar | row vector of scalars

Since R2023a

Coefficient of the radiation heat transfer between the parallel assemblies inside the module. The size of this parameter must be equal to the number of inter-parallel assemblies thermal connections that this block models.

Dependencies

To enable this parameter, set the InterCellRadiativeThermalPath property of the Module object to "On". Alternatively, set the InterCellRadiativeThermalPath property to "On" inside the parent object of which the Module object is a subcomponent.

Parallel Assembly

Non-cell electrical resistance — Parallel assembly non-cell resistance

1 / 1000 Ohm (default) | positive scalar

Non-cell electrical resistance of each parallel assembly in the module.

Dependencies

To enable this parameter, set the NonCellResistance property of the Module object to "On". Alternatively, set the NonCellResistance property to "On" inside the parent object of which the Module object is a subcomponent.

Module

Non-cell electrical resistance — Module non-cell resistance

1 / 1000 Ohm (default) | positive scalar

Non-cell electrical resistance of the module.

Dependencies

To enable this parameter, set the NonCellResistance property of the Module object to "On". Alternatively, set the NonCellResistance property to "On" inside the parent object of which the Module object is a subcomponent.

Cell Balancing

Cell balancing switch closed resistance — Closed resistance of cell balancing switch

0.01 Ohm (default) | positive scalar

Closed resistance of the cell balancing switch.

Cell balancing switch open conductance — Open conductance of cell balancing switch

1e-8 1/Ohm (default) | positive scalar

Open conductance of the cell balancing switch.

Cell balancing switch operation threshold — Threshold for cell balancing switch operation

0.5 (default) | positive scalar

Threshold to activate the cell balancing switch operation.

Cell balancing shunt resistance — Resistance of cell balancing shunt

50 Ohm (default) | positive scalar

Resistance of the cell balancing shunt.

Initial Targets (Variables)

The size of these variables is equal to the total number of electrical models in the system. For example, in a Module block with 2 parallel assemblies and 2 series cells, the size of the variables depends on the ModelResolution property of the Module object and is equal to 4 for Detailed, 1 for Lumped, or 3 when the SeriesGrouping property is equal to [1 1] and the ParallelGrouping property is equal to [1 2].

Cell current (positive in) — Cell-level current, iCell

0 A (default) | scalar | vector

Current at the cell level. The size of this variable is equal to the total number of electrical models in the system.

Cell terminal voltage — Cell-level voltages, vCell

0 V (default) | scalar | vector

Voltages at the cell level. The size of this signal is equal to the total number of electrical models in the system.

Cell state of charge — Cell-level state of charge, socCell

1 (default) | scalar | vector

State of charge at cell level. The value of this variable typically varies between 0 and 1. The size of this signal is equal to the total number of electrical models in the system.

Cell discharge cycles — Cell-level number of cycles, numCyclesCell

0 (default) | scalar | vector

Cell-level number of cycles related to battery aging. The size of this signal is equal to the total number of electrical models in the system.

Cell temperature — Cell-level temperature, temperatureCell

298.15 K (default) | positive scalar

Temperature at the cell level. The size of this signal is equal to the total number of electrical models in the system.

Parallel Assembly Voltage — Parallel assembly-level voltages, vParallelAssembly

repmat(0,4,1) V (default) | scalar | vector

Voltages at the parallel assembly level. The size of this signal is equal to the total number of parallel assemblies in the module.

Parallel Assembly state of charge — State of charge at parallel assembly level, socParallelAssembly

repmat(1,4,1) (default) | scalar | vector

State of charge at the parallel assembly level. The size of this signal is equal to the total number of parallel assemblies in the module.

Version History

Introduced in R2022b