Module
Description
Use Module
to create a battery module object that represents a
number of battery parallel assemblies connected electrically in series. You can use this
object as an input to the ModuleAssembly
object to create larger battery models.
To define the number of parallel assemblies or cells connected in series, use the
NumSeriesAssemblies
property. To generate a Simscape™ model of your Module
object, use the buildBattery
function. This object only supports the definition of structural or design parameters. You can
modify the run-time parameters for this model block and its constituent cells after you create
the model.
The Module
object is the third stage of a battery pack system model in a
bottom-up approach. Pack models are required 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.
By default, the parallel assemblies or cells are stacked along the
y-axis of a Cartesian coordinate system and replicated a number of times
equal to the value of the NumSeriesAssemblies
property. To stack the
parallel assemblies along the x-axis, set the
StackingAxis
property to "X"
.
Specify Model Resolution
The recommended model resolution for a Module
object is
"Lumped"
. You can increase or decrease the local resolution for a
Module
object by using the ModelResolution
property.
If you set the ModelResolution
property to
"Grouped"
, you can define a custom model resolution by using the
SeriesGrouping
and ParallelGrouping
properties.
For example, consider a battery architecture that comprises six parallel assemblies connected
in series (NumSeriesAssemblies
= 6). Each parallel assembly comprises six
cells. This architecture requires at least 36 electrical battery models for simulation. To
improve model speed and optimize the compilation times, you can choose to use only three
electrical models by setting the SeriesGrouping
property to [1 4
1]
. The first and third submodules comprise one parallel assembly. The second
submodule comprises the remaining four parallel assemblies.
Alternatively, you can choose to have further resolution for every parallel assembly by
changing SeriesGrouping
to [1 1 2 1 1]
.
For the submodules with a single parallel assembly, you can further discretize the
electrical and thermal models to obtain the resolution for each cell by setting the
ParallelGrouping
property to [6 1 6] and [6 6 1 6 6], respectively.
For more information about model resolution and simulation strategy, see the SeriesGrouping and ParallelGrouping properties.
Thermal Boundary Conditions
Thermal boundary conditions define the specific heat transfer mechanisms that occur at each interface of a cell thermal model and its surroundings. In battery systems, cells are typically thermally coupled to different heat sources and sinks, all of which have an effect on the battery cell temperature. The number and type of thermal boundary conditions for a cell model depends on the thermal and mechanical design of the battery system.
For example, you can place cells on an aluminium cooling plate to enhance heat removal and, at the same time, join them together mechanically with a potting compound that effectively eliminates or decreases the inter-cell heat exchange path. The cell temperature has a direct impact on battery performance and lifetime. Therefore, it is crucial to predict this state in dynamic simulation.
Inside a battery object, you can set up a thermal network of lumped-thermal-mass cell models to simultaneously capture the thermal paths to the ambient, the coolant, and/or the cooling plate:
These options are not mutually exclusive. For example, your battery model can combine both the coolant thermal path and the cooling thermal plates to model individual thermal resistances between the individual cells and the sections of the cooling plate.
For more information about thermal paths, see the AmbientThermalPath, CoolantThermalPath, and CoolingPlate properties.
Cell-to-Cell Heat Exchange
You can also model direct cell-to-cell heat exchange. This is important when you want to simulate more detailed thermal management strategies or even thermal propagation scenarios where inter-cell heat transfer happens at faster rates than ambient or coolant rates. In the battery industry, you can link battery cells to each other through many different means. For example, you can link cylindrical cells by using potting compounds for mechanical rigidity, stability, and thermal isolation, or other types of thermal interface materials. You can also use dielectric fluids or other compounds to heat or cool down cylindrical cells, as well as forced air convection.
You can define the thermal parameters for the inter-cell heat exchange after you create the battery model. You can find these parameters from first principles calculations and more detailed 3D simulations.
These options are not mutually exclusive.
For more information about inter-cell thermal paths, see the InterCellThermalPath and InterCellRadiativeThermalPath properties.
Thermal Nodes at Surface Boundaries (since R2024a)
For a more detailed thermal modeling of the battery cells in the battery pack environment, you can also expose the thermal nodes for the cells located at the surface boundaries of the module:
To expose the thermal nodes at a specific surface boundary, specify the
XminThermalNodes
, XmaxThermalNodes
,
YminThermalNodes
, and YmaxThermalNodes
properties
accordingly.
For modules with hexagonal cylindrical cells, you can also enable the heat transfer
between the cells of the module and a serpentine cooling plate. To expose the thermal nodes at
a serpentine cooling plate inside the module, specify the
SerpentineCoolingPlate
property. You can then further define the
fraction of the circumference and height of the cylindrical cells used as heat exchange
interface in serpentine cooling plates by specifying the
FractionOfCellCircumferenceForHeatExchange
and
FractionOfCellHeightForHeatExchange
properties.
This table shows the relationship between the surface thermal boundaries and the affected cells:
Module Thermal Boundary | Model and Simulation Output | Layout | |
---|---|---|---|
Model Resolution: Detailed |
| Layout 1 5 9 13 2 6 10 14 3 7 11 15 4 8 12 16 17 21 25 29 18 22 26 30 19 23 27 31 20 24 28 32 33 37 41 45 34 38 42 46 35 39 43 47 36 40 44 48 CellsAtXminBoundary 1 5 9 13 | |
Model Resolution: Detailed |
| CellsAtXmaxBoundary 36 40 44 48 | |
Model Resolution: Detailed |
| Layout 1 5 9 13 17 21 25 29 33 37 41 45 2 6 10 14 18 22 26 30 34 38 42 46 3 7 11 15 19 23 27 31 35 39 43 47 4 8 12 16 20 24 28 32 36 40 44 48 CellsAtYminBoundary 1 2 3 4 | |
Model Resolution: Detailed |
| Layout 1 5 9 13 17 21 25 29 33 37 41 45 2 6 10 14 18 22 26 30 34 38 42 46 3 7 11 15 19 23 27 31 35 39 43 47 4 8 12 16 20 24 28 32 36 40 44 48 CellsAtYmaxBoundary 45 46 47 48 | |
Model Resolution: Detailed |
| CellsAtXminBoundary 1 5 9 13 17 21 25 29 33 37 41 45 CellsAtXmaxBoundary 4 8 12 16 20 24 28 32 36 40 44 48 CellsAtYminBoundary 1 2 3 4 CellsAtYmaxBoundary 45 46 47 48 |
For an example on how to implement scalar and vectorized thermal boundary conditions, see Add Vectorized and Scalar Thermal Boundary Conditions to Battery Models.
Creation
Description
Note
To quickly create a Module
object, use the batteryModule
function. By using this function, you avoid importing the
namespace, using the full class name, or dealing only with name-value arguments when
creating the object. (since R2024a)
To use this object, at the MATLAB® Command Window, run this command at least once each MATLAB session:
import simscape.battery.builder.*;
creates a battery
module that comprises parallel assemblies with default property values.batteryModule
= Module
sets Properties using one or more name-value
arguments. For example, create a module with four default parallel assemblies stacked
along the y-axis with a gap between the parallel assemblies equal to
0.05 m.batteryModule
= Module(Name=Value
)
module = Module(... ParallelAssembly=ParallelAssembly(), ... NumSeriesAssemblies=4, ... StackingAxis="Y",... InterParallelAssemblyGap=simscape.Value(0.05,"m"));
Properties
Examples
Version History
Introduced in R2022bSee Also
Apps
Objects
Functions
Simscape Blocks
Topics
- Battery Modeling Workflow
- Build Simple Model of Battery Pack in MATLAB and Simscape
- Build Detailed Model of Battery Pack from Pouch Cells
- Apply Parameter Variation to Cells in Module
- Add Vectorized and Scalar Thermal Boundary Conditions to Battery Models
- Apply Temperature-Dependent Cell Parameter Variation in Battery Module