ParallelAssembly

Create parallel assembly of battery cells

Since R2022b

Description

Use ParallelAssembly to create a battery parallel assembly object that represents a number of cells connected electrically in parallel under a specific topological configuration or geometrical arrangement. You can use this object as an input to the Module object.

To specify the number of cells connected in parallel, use the NumParallelCells property. To generate a Simscape™ model of your ParallelAssembly 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 ParallelAssembly object is the second 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.

Topology of Parallel Assembly

To meet battery system packaging and space requirements, you can arrange the battery cells in many different topologies or geometrical configurations. Use the Topology property of the ParallelAssembly object to define the geometrical arrangement of your battery in a 3-D Cartesian coordinate system.

The topology of the parallel assembly depends on the format of the battery cells that comprise the assembly. Depending on the value of the Topology property, you can modify the Rows property to best represent your specific design. The Rows property is defined with respect to the x-axis of the Cartesian coordinate system. By default, the cells are stacked along the y-axis.

This figure shows the different topologies of a parallel assembly according to the format of the battery cells that comprise the assembly:

To modify the number of cells connected in parallel, use the NumParallelCells property. You can modify the topology of the parallel assembly by using the Topology property, which depends on the cell format. The Rows property is defined with respect to the x-axis of the Cartesian system. By default, cells are stacked along the y-axis.

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 parallel assembly:

To expose the thermal nodes at a specific surface boundary, specify the XminThermalNodes, XmaxThermalNodes, YminThermalNodes, and YmaxThermalNodes properties accordingly.

For parallel assemblies with hexagonal cylindrical cells, you can also enable the heat transfer between the cells of the parallel assembly and a serpentine cooling plate. To expose the thermal nodes at a serpentine cooling plate inside the parallel assembly, 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:

Parallel Assembly Thermal Boundary	Model	Simulation Output	Layout
`XminThermalNodes` = `"Scalar"` Model Resolution: Detailed			Layout 1 6 11 16 21 26 2 7 12 17 22 27 3 8 13 18 23 28 4 9 14 19 24 29 5 10 15 20 25 30 CellsAtXminBoundary 1 6 11 16 21 26
`XmaxThermalNodes` = `"Scalar"` Model Resolution: Detailed			CellsAtXmaxBoundary 5 10 15 20 25 30
`XminThermalNodes` = `"Scalar"` `XmaxThermalNodes` = `"Scalar"` `YminThermalNodes` = `"Scalar"` `YmaxThermalNodes` = `"Scalar"` Model Resolution: Detailed			CellsAtXminBoundary 1 6 11 16 21 26 CellsAtXmaxBoundary 5 10 15 20 25 30 CellsAtYminBoundary 1 2 3 4 5 CellsAtYmaxBoundary 26 27 28 29 30
`XminThermalNodes` = `"Scalar"` Model Resolution: Lumped			CellsAtXminBoundary 1 6 11 16 21 26
`XminThermalNodes` = `"Vectorized"` Model Resolution: Detailed			Layout 1 6 11 16 21 26 2 7 12 17 22 27 3 8 13 18 23 28 4 9 14 19 24 29 5 10 15 20 25 30 CellsAtXminBoundary 1 6 11 16 21 26
`XmaxThermalNodes` = `"Vectorized"` Model Resolution: Detailed			CellsAtXmaxBoundary 5 10 15 20 25 30
`XminThermalNodes` = `"Vectorized"` `XmaxThermalNodes` = `"Vectorized"` `YminThermalNodes` = `"Vectorized"` `YmaxThermalNodes` = `"Vectorized"` Model Resolution: Detailed			CellsAtXminBoundary 1 6 11 16 21 26 CellsAtXmaxBoundary 5 10 15 20 25 30 CellsAtYminBoundary 1 2 3 4 5 CellsAtYmaxBoundary 26 27 28 29 30

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

Syntax

batteryParallelAssembly = ParallelAssembly

batteryParallelAssembly = ParallelAssembly(Name=Value)

Description

Note

To quickly create a ParallelAssembly object, use the batteryParallelAssembly 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.*;

All properties are exposed as name-value arguments in this object.

batteryParallelAssembly = ParallelAssembly creates a parallel assembly that comprises battery cells with default property values.

batteryParallelAssembly = ParallelAssembly(Name=Value) sets Properties using one or more name-value arguments. For example, create a parallel assembly with 48 cylindrical cells stacked in a square topology over four rows with an intercell gap equal to 0.001 m.

parallelAssembly = ParallelAssembly(...
    NumParallelCells=48, ...
    Cell=Cell(Geometry=CylindricalGeometry), ...
    Topology="Square", ...
    Rows=4, ...
    InterCellGap=simscape.Value(0.001,"m"));

example

Properties

expand all

`Cell` — Cell component in parallel assembly
`Cell` object (default)

Cell component in the parallel assembly, specified as a Cell object. The ParallelAssembly object creates this component and then electrically connects it in parallel a number of times equal to the value of the NumParallelCells property.

`NumParallelCells` — Number of cells connected in parallel
1 (default) | positive integer

Number of cells connected in parallel inside the parallel assembly, specified as a strictly positive and finite integer. The value of this property must be less than 150.

`Rows` — Number of rows of parallel assembly
1 (default) | positive integer

Number of rows of the parallel assembly parallel to the stacking axis, specified as a strictly positive integer. The value of this property must be less than 50 and less than the value of the NumParallelCells property.

`Topology` — Geometrical arrangement of cells
`"None"` (default) | `"Square"` | `"Hexagonal"` | `"SingleStack"` | `"NStack"`

Geometrical arrangement of the cells relative to the cell format, specified as either "Square" or "Hexagonal" for cylindrical cells, "SingleStack" or "NStack" for prismatic cells, or "SingleStack" for pouch cells.

`ModelResolution` — Model resolution in simulation
`"Lumped"` (default) | `"Detailed"`

Model resolution or fidelity in the simulation, specified as:

"Lumped" — Choose this value for the lowest fidelity. The assembly uses only one electrical model. To obtain the fastest model compilation and running time, set the model resolution to this value.
"Detailed" — Choose this value for the highest fidelity. The assembly uses one electrical model and one thermal model for each battery cell in the parallel assembly.

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

`BalancingStrategy` — State-of-charge balancing strategy
`"None"` (default) | `"Passive"` | `"External"`

State-of-charge balancing strategy for the parallel assembly, specified as "None", "Passive", or "External".

Set this property to "Passive" to add an ideal balancing circuit connected in parallel to the ParallelAssembly Simscape model and a physical port used for switch control. The switch is open when the control signal is equal to 0. The switch is closed when the control signal is equal to 1.

To specify and model an external cell balancing strategy, set this property to "External". The ParallelAssembly (Generated Block) then exposes two electrical array-of-nodes ports, +BUS and -BUS. For desktop simulations and hardware-in-the-loop battery emulation hardware, use this option in conjunction with the Passive Balancing Interface block.

Example: batteryParallelAssembly.BalancingStrategy = "Passive"

`AmbientThermalPath` — Option to use simple thermal resistance block
`"None"` (default) | `"CellBasedThermalResistance"`

Option to use a simple thermal resistance block connected between the cells and a Simscape thermal network, specified as "CellBasedThermalResistance" or "None".

Note

Setting this property automatically propagates its value to all the subcomponent battery objects inside this ParallelAssembly object. However, this change does not propagate to the other battery objects in your MATLAB workspace. If you do not set this property when you create this ParallelAssembly object, then the default value is automatically propagated to all its subcomponent battery objects.

Example: batteryParallelAssembly.AmbientThermalPath = "CellBasedThermalResistance"

`CoolantThermalPath` — Option to use simple thermal resistance block
`"None"` (default) | `"CellBasedThermalResistance"`

Option to use a simple thermal resistance block connected between the cells and a Simscape thermal network, specified as "CellBasedThermalResistance" or "None".

If you also define a cooling plate surface, the object connects the thermal resistance block between each battery thermal model and its corresponding element in the array of thermal nodes. You can use this thermal resistance to capture conductive and convective heat transfer mechanisms related to the cell and cooling system design.

Note

Example: batteryParallelAssembly.CoolantThermalPath = "CellBasedThermalResistance"

`CoolingPlate` — Option to use cooling plate component
`"None"` (default) | `"Top"` | `"Bottom"`

Option to use a cooling plate component at a specific surface boundary, specified as "Top", "Bottom", or "None".

This option adds a vectorized array of thermal nodes connector to the ParallelAssembly object. The object connects each element of the array of thermal nodes to each thermal model. If you also select a coolant thermal path, the object connects a Thermal Resistance block between each battery thermal model and its corresponding element in the array of thermal nodes. If you define a cell geometry, the ThermalNodes property contains the number of thermal nodes, their dimensions, and their locations in a 2-D Cartesian plane.

Note

Example: batteryParallelAssembly.CoolingPlate = "Top"

`CoolingPlateBlockPath` — Option to specify which cooling plate block to assign
`"None"` (default) | `"batt_lib/Thermal/Edge Cooling"` | `"batt_lib/Thermal/Parallel Channels"` | `"batt_lib/Thermal/U-Shaped Channels"`

Since R2023a

Option to specify which cooling plate block you want to assign to the ParallelAssembly object at the boundary defined by the CoolingPlate property, specified as "batt_lib/Thermal/Edge Cooling", "batt_lib/Thermal/Parallel Channels", ""batt_lib/Thermal/U-Shaped Channels"", or "None".

Note

Example: batteryParallelAssembly.CoolingPlateBlockPath = "batt_lib/Thermal/Edge Cooling"

`XminThermalNodes` — Option to expose thermal nodes at Xmin surface boundary
`"None"` (default) | `"Scalar"` | `"Vectorized"`

Since R2024a

Option to expose thermal nodes at the minimum X-axis surface boundary of the ParallelAssembly object, specified as:

"None" — Do not expose thermal nodes.
"Scalar" — Expose a lumped thermal node at the minimum X-axis surface boundary.
"Vectorized" — Expose an array of thermal nodes at the minimum X-axis surface boundary.

Note

Example: batteryParallelAssembly.XminThermalNodes = "Scalar"

`XmaxThermalNodes` — Option to expose thermal nodes at Xmax surface boundary
`"None"` (default) | `"Scalar"` | `"Vectorized"`

Since R2024a

Option to expose thermal nodes at the maximum X-axis surface boundary of the ParallelAssembly object, specified as:

"None" — Do not expose thermal nodes.
"Scalar" — Expose a lumped thermal node at the maximum X-axis surface boundary.
"Vectorized" — Expose an array of thermal nodes at the maximum X-axis surface boundary.

Note

Example: batteryParallelAssembly.XmaxThermalNodes = "Scalar"

`YminThermalNodes` — Option to expose thermal nodes at Ymin surface boundary
`"None"` (default) | `"Scalar"` | `"Vectorized"`

Since R2024a

Option to expose thermal nodes at the minimum Y-axis surface boundary of the ParallelAssembly object, specified as:

"None" — Do not expose thermal nodes.
"Scalar" — Expose a lumped thermal node at the minimum Y-axis surface boundary.
"Vectorized" — Expose an array of thermal nodes at the minimum Y-axis surface boundary.

Note

Example: batteryParallelAssembly.YminThermalNodes = "Scalar"

`YmaxThermalNodes` — Option to expose thermal nodes at Ymax surface boundary
`"None"` (default) | `"Scalar"` | `"Vectorized"`

Since R2024a

Option to expose thermal nodes at the maximum Y-axis surface boundary of the ParallelAssembly object, specified as:

"None" — Do not expose thermal nodes.
"Scalar" — Expose a lumped thermal node at the maximum Y-axis surface boundary.
"Vectorized" — Expose an array of thermal nodes at the maximum Y-axis surface boundary.

Note

Example: batteryParallelAssembly.YmaxThermalNodes = "Scalar"

`SerpentineCoolingPlate` — Option to expose array of thermal nodes at serpentine cooling plate
`"None"` (default) | `"SingleSidedAlongStackingAxis"` | `"DoubleSidedAlongStackingAxis"`

Since R2024a

Option to expose an array of thermal nodes at a serpentine cooling plate interface for batteries that contain cylindrical cells in hexagonal topology, specified as "None", "SingleSidedAlongStackingAxis", or "DoubleSidedAlongStackingAxis".

This figure shows the configuration of the serpentine cooling plate if you set this property to either "SingleSidedAlongStackingAxis" or "DoubleSidedAlongStackingAxis":

Note

Example: batteryParallelAssembly.SerpentineCoolingPlate = "SingleSidedAlongStackingAxis"

`FractionOfCellCircumferenceForHeatExchange` — Fraction of circumference of cylindrical cell used as heat exchange interface
`0.25` (default) | double in the range (0,0.5)

Since R2024a

Fraction of the circumference of a cylindrical cell used as heat exchange interface, specified as a double in the range (0,0.5). This property is only relevant to serpentine cooling plates.

Example: batteryParallelAssembly.FractionOfCellCircumferenceForHeatExchange = 0.3

`FractionOfCellHeightForHeatExchange` — Fraction of height of cylindrical cell used as heat exchange interface
`0.6` (default) | double in the range (0,1)

Since R2024a

Fraction of the height of a cylindrical cell used as heat exchange interface, specified as a double in the range (0,1). This property is only relevant to serpentine cooling plates.

Example: batteryParallelAssembly.FractionOfCellHeightForHeatExchange = 0.8

`InterCellGap` — Shortest distance between cells
`simscape.Value(0.001,"m")` (default) | `simscape.Value(positive scalar,"Length unit")` | positive scalar

Shortest distance between the cells inside the parallel assembly, specified as a positive scalar or a simscape.Value object that represents a positive scalar with a unit of length. The value of this property must be less than 0.1 m.

If you set this property directly with a positive scalar value instead of using a simscape.Value object, the object converts the value to a simscape.Value object with meter as its physical unit.

Example: batteryParallelAssembly.InterCellGap = simscape.Value(0.01,"m")

Example: batteryParallelAssembly.InterCellGap = 0.01

`Position` — Location of battery object
`[0 0 0]` (default) | vector of real and finite entries

Location of the battery object in a 3-D Cartesian coordinate system, specified as a vector of real and finite entries.

Example: batteryParallelAssembly.Position = [0 0 0]

`Name` — Name of parallel assembly
`"ParallelAssembly1"` (default) | string

Name of the parallel assembly, specified as a string.

Example: batteryParallelAssembly.Name = "ParallelAssembly2"

`MassFactor` — Additional non-cell-related mass
`1` (default) | positive double

Additional non-cell-related mass added to the parallel assembly by components such as busbars, tabs, and collector plates, specified as a strictly positive double greater than or equal to 1.

Example: batteryParallelAssembly.MassFactor = 1.2

`StackingAxis` — Preferential stacking direction
`"Y"` (default) | `"X"`

Preferential stacking direction for the arrangement of battery cells in a 2-D Cartesian coordinate system, specified as either "X" or "Y".

This figure shows the global coordinate system for batteries.

To plot the parallel assembly object in the direction of the x-axis, set this property to "X" before creating the BatteryChart object.

Example: batteryParallelAssembly.StackingAxis = "Y"

`NonCellResistance` — Option to use electrical resistance blocks
`'off'` (default) | on/off logical value

Option to use electrical resistance blocks to represent additional electrical resistances from non-cell components, specified as 'off', 'on', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

Example: batteryParallelAssembly.NonCellResistance = 'on'

`InterCellThermalPath` — Option to use simple thermal resistance block for inter cell heat
`'off'` (default) | on/off logical value

Since R2023a

Option to use thermal resistance blocks to represent a linear cell-to-cell heat transfer path between adjacent battery cells, specified as 'off', 'on', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

Enabling the inter-cell thermal path is useful only when you have selected a cell thermal model and more than one cell or cell model exists inside the battery.

You can define the value for the thermal resistance parameter after model creation.

If you set this property to 'on', you cannot set the InterCellRadiativeThermalPath property to 'on'.

Note

Example: batteryParallelAssembly.InterCellThermalPath = "on"

`InterCellRadiativeThermalPath` — Option to use simple thermal resistance block for inter cell heat
`'off'` (default) | on/off logical value

Since R2023a

Option to use thermal resistance blocks to represent a radiative cell-to-cell heat transfer path between adjacent battery cells, specified as 'off', 'on', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

Enabling the inter-cell radiative thermal path is useful only when you have selected a cell thermal model and more than one cell or cell model exists inside the battery.

You can define the value for the radiation heat transfer parameters after model creation.

If you set this property to 'on', you cannot set the InterCellThermalPath property to 'on'.

Note

Example: batteryParallelAssembly.InterCellRadiativeThermalPath = "on"

`CellParameterVariation` — Option to model cell-to-cell parameter variation in generated block
`"NoVariation"` (default) | `"PercentDeviation"`

Since R2023b

Option to model cell-to-cell parameter variation in the ParallelAssembly block that you generate when you build this object, specified as "NoVariation", or "PercentDeviation".

If you set this property to "PercentDeviation", the cell parameters in the generated ParallelAssembly block have an associated Percent deviation parameter that specifies the percent deviation of the value of corresponding cell parameter for each cell model in the battery. Cell parameters of type enumeration or boolean do not have an associated Percent deviation parameter.

The value of the corresponding cell parameter with the deviation applied is equal to:

$cellParameter = 1 + (\frac{cellParameterDeviation}{100}) * exposedCellParameter .$

For more information about cell-to-cell parameter variation, see the Apply Temperature-Dependent Cell Parameter Variations to Battery Module example.

Example: batteryParallelAssembly.CellParameterVariation = "PercentDeviation"

Dependencies

To enable this property, set ModelResolution to "Detailed".

`PackagingVolume` — Volume of battery
Read-only: `simscape.Value([],"m^3")` (default) | `simscape.Value` object

This property is read-only.

Volume of the battery, returned as a simscape.Value object with a unit of volume.

`CumulativeMass` — Cumulative mass of battery
Read-only: `simscape.Value` object

This property is read-only.

Cumulative mass of the battery, returned as a simscape.Value object with a unit of mass.

`CumulativeCellCapacity` — Cumulative cell capacity of battery
Read-only: `simscape.Value` object

Since R2023a

This property is read-only.

Cumulative cell capacity of the battery, returned as a simscape.Value object with unit of current multiplied by time.

The value of this property is equal to the individual cell capacity multiplied by the number of cells electrically connected in parallel inside this battery object.

`CumulativeCellEnergy` — Cumulative cell energy of battery
Read-only: `simscape.Value` object

Since R2023a

This property is read-only.

Cumulative cell energy of the battery, returned as a simscape.Value object with unit of energy.

The value of this property is equal to the individual cell energy multiplied by the total number of cells inside this battery object.

`NumModels` — Number of cell model blocks
Read-only: double

This property is read-only.

Number of cell model blocks in the simulation, returned as a double.

`NumInterCellThermalConnections` — Number of internal thermal connections between cells
Read-only: integer

Since R2023a

This property is read-only.

Number of the internal thermal connections between the cells, returned as an integer.

`InterCellConnectionsMapping` — 2-D map of inter-cell connections
Read-only: matrix of integer

Since R2023a

This property is read-only.

2-D map of the internal connections between the cells, returned as a matrix of integer.

The cell numbering convention refers to the Layout property. To understand the number assigned to each cell and how they relate to their neighbors, see the Layout property.

For example, for a battery module with three parallel assemblies of four pouch cells each, this property is equal to:

`CellNumbering` — Numbering for all cells
Read-only: structure

This property is read-only.

Numbering for all of the cells inside of the battery, returned as a structure.

`ThermalNodes` — Vectorized thermal node information
Read-only: structure

This property is read-only.

Vectorized thermal node information for external boundary conditions, returned as a structure. This information comprises the XY location, XY dimensions, and number of thermal nodes. If you do not define a battery cell geometry, this property is an empty structure.

`Layout` — 2-D distribution of sub-components in parent
Read-only: matrix of integer

Since R2023a

This property is read-only.

2-D distribution of sub-components or cells within the parent, returned as a matrix of integer.

This property depends on the StackingAxis property and on the number of cells.

`CellsAtXminBoundary` — Indexes of cells at Xmin surface boundary
Read-only: vector of integer

Since R2024a

This property is read-only.

Indexes of the cells at the minimum X-axis surface boundary, returned as a vector of integers.

`CellsAtXmaxBoundary` — Indexes of cells at Xmax surface boundary
Read-only: vector of integer

Since R2024a

This property is read-only.

Indexes of the cells at the maximum X-axis surface boundary, returned as a vector of integers.

`CellsAtYminBoundary` — Indexes of cells at Ymin surface boundary
Read-only: vector of integer

Since R2024a

This property is read-only.

Indexes of the cells at the minimum Y-axis surface boundary, returned as a vector of integers.

`CellsAtYmaxBoundary` — Indexes of cells at Ymax surface boundary
Read-only: vector of integer

Since R2024a

This property is read-only.

Indexes of the cells at the maximum Y-axis surface boundary, returned as a vector of integers.

`CellsAtSerpentineBoundary` — Indexes of cells at serpentine boundary
Read-only: vector of integer

Since R2024a

This property is read-only.

Indexes of the cells at the serpentine boundary, returned as a vector of integers.

`Type` — Type of battery
Read-only: `"ParallelAssembly"`

This property is read-only.

Type of battery object, returned as "ParallelAssembly".

Examples

collapse all

Create Parallel Assembly Object from Three Pouch Cells

Create a Cell object with a pouch geometry.

batteryCell = Cell(Geometry=PouchGeometry)

Create a ParallelAssembly object of three cells with the default topology.

pSet = ParallelAssembly(Cell=batteryCell,NumParallelCells=3)

Create Parallel Assembly of 46 Cylindrical Cells with Custom Topology

Create a Cell object with a cylindrical geometry.

batteryCell = Cell(Geometry=CylindricalGeometry)

Create a ParallelAssembly object of 46 cells stacked in 14 rows.

pSet = ParallelAssembly(Cell=batteryCell,NumParallelCells=46,Rows=14)

Set the topology of the parallel assembly to "Square".

pSet.Topology = "Square";

Visualize the parallel assembly by using a BatteryChart object.

pSetChart = BatteryChart(Battery=pSet)

Version History

Introduced in R2022b

expand all

R2024a: Specify an external balancing cell strategy

You can now specify an external balancing cell strategy for the ParallelAssembly object.

To specify and model an external cell balancing strategy, set the BalancingStrategy property to "External". The ParallelAssembly (Generated Block) then exposes two electrical array-of-nodes ports, +BUS and -BUS. For desktop simulations and hardware-in-the-loop battery emulation hardware, use this option in conjunction with the Passive Balancing Interface block.

R2024a: Expose thermal nodes at specific surface boundaries

For a more detailed thermal modeling of the battery cells in the battery pack environment, you can now expose the thermal nodes for the cells located at the surface boundaries of the parallel assembly. To expose these thermal nodes, specify the XminThermalNodes, XmaxThermalNodes, YminThermalNodes, and YmaxThermalNodes properties accordingly.

Then, the generated ParallelAssembly block exposes thermal conserving ports associated with the surface boundaries you have specified in the ParallelAssembly object.

R2023b: Enable parameter variation between cell models to support specific cell parameterization in the generated ParallelAssembly block

You have now the option to enable the variation of the parameters between individual cell models inside the battery system. To support specific cell parameterization, set the CellParameterDeviation property to "PercentDeviation". Then, the cell parameters in the generated ParallelAssembly block have an associated Percent deviation parameter that specifies the percent deviation of the value of corresponding cell parameter for each cell model in the battery. Cell parameters of type enumeration or boolean do not have an associated Percent deviation parameter.

ParallelAssembly

Description

Creation

Syntax

Description

Properties

Cell — Cell component in parallel assembly Cell object (default)

NumParallelCells — Number of cells connected in parallel 1 (default) | positive integer

Rows — Number of rows of parallel assembly 1 (default) | positive integer

Topology — Geometrical arrangement of cells "None" (default) | "Square" | "Hexagonal" | "SingleStack" | "NStack"

ModelResolution — Model resolution in simulation "Lumped" (default) | "Detailed"

BalancingStrategy — State-of-charge balancing strategy "None" (default) | "Passive" | "External"

AmbientThermalPath — Option to use simple thermal resistance block "None" (default) | "CellBasedThermalResistance"

CoolantThermalPath — Option to use simple thermal resistance block "None" (default) | "CellBasedThermalResistance"

CoolingPlate — Option to use cooling plate component "None" (default) | "Top" | "Bottom"

CoolingPlateBlockPath — Option to specify which cooling plate block to assign "None" (default) | "batt_lib/Thermal/Edge Cooling" | "batt_lib/Thermal/Parallel Channels" | "batt_lib/Thermal/U-Shaped Channels"

XminThermalNodes — Option to expose thermal nodes at Xmin surface boundary "None" (default) | "Scalar" | "Vectorized"

XmaxThermalNodes — Option to expose thermal nodes at Xmax surface boundary "None" (default) | "Scalar" | "Vectorized"

YminThermalNodes — Option to expose thermal nodes at Ymin surface boundary "None" (default) | "Scalar" | "Vectorized"

YmaxThermalNodes — Option to expose thermal nodes at Ymax surface boundary "None" (default) | "Scalar" | "Vectorized"

SerpentineCoolingPlate — Option to expose array of thermal nodes at serpentine cooling plate "None" (default) | "SingleSidedAlongStackingAxis" | "DoubleSidedAlongStackingAxis"

FractionOfCellCircumferenceForHeatExchange — Fraction of circumference of cylindrical cell used as heat exchange interface 0.25 (default) | double in the range (0,0.5)

FractionOfCellHeightForHeatExchange — Fraction of height of cylindrical cell used as heat exchange interface 0.6 (default) | double in the range (0,1)

InterCellGap — Shortest distance between cells simscape.Value(0.001,"m") (default) | simscape.Value(positive scalar,"Length unit") | positive scalar

Position — Location of battery object [0 0 0] (default) | vector of real and finite entries

Name — Name of parallel assembly "ParallelAssembly1" (default) | string

MassFactor — Additional non-cell-related mass 1 (default) | positive double

StackingAxis — Preferential stacking direction "Y" (default) | "X"

NonCellResistance — Option to use electrical resistance blocks 'off' (default) | on/off logical value

InterCellThermalPath — Option to use simple thermal resistance block for inter cell heat 'off' (default) | on/off logical value

InterCellRadiativeThermalPath — Option to use simple thermal resistance block for inter cell heat 'off' (default) | on/off logical value

CellParameterVariation — Option to model cell-to-cell parameter variation in generated block "NoVariation" (default) | "PercentDeviation"

Dependencies

PackagingVolume — Volume of battery Read-only: simscape.Value([],"m^3") (default) | simscape.Value object

CumulativeMass — Cumulative mass of battery Read-only: simscape.Value object

CumulativeCellCapacity — Cumulative cell capacity of battery Read-only: simscape.Value object

CumulativeCellEnergy — Cumulative cell energy of battery Read-only: simscape.Value object

NumModels — Number of cell model blocks Read-only: double

NumInterCellThermalConnections — Number of internal thermal connections between cells Read-only: integer

InterCellConnectionsMapping — 2-D map of inter-cell connections Read-only: matrix of integer

CellNumbering — Numbering for all cells Read-only: structure

ThermalNodes — Vectorized thermal node information Read-only: structure

Layout — 2-D distribution of sub-components in parent Read-only: matrix of integer

CellsAtXminBoundary — Indexes of cells at Xmin surface boundary Read-only: vector of integer

CellsAtXmaxBoundary — Indexes of cells at Xmax surface boundary Read-only: vector of integer

CellsAtYminBoundary — Indexes of cells at Ymin surface boundary Read-only: vector of integer

CellsAtYmaxBoundary — Indexes of cells at Ymax surface boundary Read-only: vector of integer

CellsAtSerpentineBoundary — Indexes of cells at serpentine boundary Read-only: vector of integer

Type — Type of battery Read-only: "ParallelAssembly"

Examples

Create Parallel Assembly Object from Three Pouch Cells

Create Parallel Assembly of 46 Cylindrical Cells with Custom Topology

Version History

R2024a: Specify an external balancing cell strategy

R2024a: Expose thermal nodes at specific surface boundaries

R2023b: Enable parameter variation between cell models to support specific cell parameterization in the generated ParallelAssembly block

See Also

Apps

Objects

Functions

Simscape Blocks

Topics

`Cell` — Cell component in parallel assembly
`Cell` object (default)

`NumParallelCells` — Number of cells connected in parallel
1 (default) | positive integer

`Rows` — Number of rows of parallel assembly
1 (default) | positive integer

`Topology` — Geometrical arrangement of cells
`"None"` (default) | `"Square"` | `"Hexagonal"` | `"SingleStack"` | `"NStack"`

`ModelResolution` — Model resolution in simulation
`"Lumped"` (default) | `"Detailed"`

`BalancingStrategy` — State-of-charge balancing strategy
`"None"` (default) | `"Passive"` | `"External"`

`AmbientThermalPath` — Option to use simple thermal resistance block
`"None"` (default) | `"CellBasedThermalResistance"`

`CoolantThermalPath` — Option to use simple thermal resistance block
`"None"` (default) | `"CellBasedThermalResistance"`

`CoolingPlate` — Option to use cooling plate component
`"None"` (default) | `"Top"` | `"Bottom"`

`CoolingPlateBlockPath` — Option to specify which cooling plate block to assign
`"None"` (default) | `"batt_lib/Thermal/Edge Cooling"` | `"batt_lib/Thermal/Parallel Channels"` | `"batt_lib/Thermal/U-Shaped Channels"`

`XminThermalNodes` — Option to expose thermal nodes at Xmin surface boundary
`"None"` (default) | `"Scalar"` | `"Vectorized"`

`XmaxThermalNodes` — Option to expose thermal nodes at Xmax surface boundary
`"None"` (default) | `"Scalar"` | `"Vectorized"`

`YminThermalNodes` — Option to expose thermal nodes at Ymin surface boundary
`"None"` (default) | `"Scalar"` | `"Vectorized"`

`YmaxThermalNodes` — Option to expose thermal nodes at Ymax surface boundary
`"None"` (default) | `"Scalar"` | `"Vectorized"`

`SerpentineCoolingPlate` — Option to expose array of thermal nodes at serpentine cooling plate
`"None"` (default) | `"SingleSidedAlongStackingAxis"` | `"DoubleSidedAlongStackingAxis"`

`FractionOfCellCircumferenceForHeatExchange` — Fraction of circumference of cylindrical cell used as heat exchange interface
`0.25` (default) | double in the range (0,0.5)

`FractionOfCellHeightForHeatExchange` — Fraction of height of cylindrical cell used as heat exchange interface
`0.6` (default) | double in the range (0,1)

`InterCellGap` — Shortest distance between cells
`simscape.Value(0.001,"m")` (default) | `simscape.Value(positive scalar,"Length unit")` | positive scalar

`Position` — Location of battery object
`[0 0 0]` (default) | vector of real and finite entries

`Name` — Name of parallel assembly
`"ParallelAssembly1"` (default) | string

`MassFactor` — Additional non-cell-related mass
`1` (default) | positive double

`StackingAxis` — Preferential stacking direction
`"Y"` (default) | `"X"`

`NonCellResistance` — Option to use electrical resistance blocks
`'off'` (default) | on/off logical value

`InterCellThermalPath` — Option to use simple thermal resistance block for inter cell heat
`'off'` (default) | on/off logical value

`InterCellRadiativeThermalPath` — Option to use simple thermal resistance block for inter cell heat
`'off'` (default) | on/off logical value

`CellParameterVariation` — Option to model cell-to-cell parameter variation in generated block
`"NoVariation"` (default) | `"PercentDeviation"`

`PackagingVolume` — Volume of battery
Read-only: `simscape.Value([],"m^3")` (default) | `simscape.Value` object

`CumulativeMass` — Cumulative mass of battery
Read-only: `simscape.Value` object

`CumulativeCellCapacity` — Cumulative cell capacity of battery
Read-only: `simscape.Value` object

`CumulativeCellEnergy` — Cumulative cell energy of battery
Read-only: `simscape.Value` object

`NumModels` — Number of cell model blocks
Read-only: double

`NumInterCellThermalConnections` — Number of internal thermal connections between cells
Read-only: integer

`InterCellConnectionsMapping` — 2-D map of inter-cell connections
Read-only: matrix of integer

`CellNumbering` — Numbering for all cells
Read-only: structure

`ThermalNodes` — Vectorized thermal node information
Read-only: structure

`Layout` — 2-D distribution of sub-components in parent
Read-only: matrix of integer

`CellsAtXminBoundary` — Indexes of cells at Xmin surface boundary
Read-only: vector of integer

`CellsAtXmaxBoundary` — Indexes of cells at Xmax surface boundary
Read-only: vector of integer

`CellsAtYminBoundary` — Indexes of cells at Ymin surface boundary
Read-only: vector of integer

`CellsAtYmaxBoundary` — Indexes of cells at Ymax surface boundary
Read-only: vector of integer

`CellsAtSerpentineBoundary` — Indexes of cells at serpentine boundary
Read-only: vector of integer

`Type` — Type of battery
Read-only: `"ParallelAssembly"`