Main Content

ModuleAssembly

Create assembly of battery modules

expand all in page

Description

Use ModuleAssembly to create a module assembly object that represents a number of Module objects connected electrically in series or in parallel. You can use this object as an input to the Pack object to create larger battery models.

To generate a Simscape™ model of your ModuleAssembly object, use the buildBattery function.

The ModuleAssembly object only supports the definition of structural or design parameters. You can modify the run-time parameters for this object and its constituent module models after you create the model. The ModuleAssembly object keeps track of its unique constituent module models and generates parameters for these models instead of doing it for every model instance. You can generate a script that contains all the parameters of the ModuleAssembly object by specifying the MaskParameters argument in the buildBattery function. A unique module model is characterized by having the same properties (such as NumSeriesAssemblies and ModelResolution) and the same constituent cell properties (such as name, format, and weight).

The ModuleAssembly object is the fourth element 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.

To specify the number and attributes of the modules, use the Module property.

This figure shows a module assembly that comprises two modules made of four parallel assemblies of 48 parallel cylindrical cells each.

Creation

Syntax

import simscape.battery.builder.*; batteryModuleAssembly = ModuleAssembly
import simscape.battery.builder.*; batteryModuleAssembly = ModuleAssembly(Name=Value)

Description

import simscape.battery.builder.*; batteryModuleAssembly = ModuleAssembly creates a battery module assembly that comprises modules with default property values.

example

import simscape.battery.builder.*; batteryModuleAssembly = ModuleAssembly(Name=Value) sets Properties using one or more name-value arguments. For example, create a battery module assembly with two default modules that are connected in series and stacked along the y-axis, with a gap of 0.05 m between each module.

batteryModuleAssembly = ModuleAssembly(...
    Module=repmat(Module,1,2), ...
    StackingAxis="Y",... 
    InterModuleGap=simscape.Value(0.005,"m"));

You can define the number and types of modules in the Module property. If your module assembly comprises many modules with the same property values, you can use the repmat function to specify the Module property. Otherwise, specify an array of distinct modules.

Properties

expand all

Set of battery modules in the module assembly, specified as a Module object or an array of Module objects. The ModuleAssembly object electrically connects the modules in series or in parallel according to the CircuitConnection property. If your module assembly comprises many modules with exactly the same property values, you can use the repmat function to specify this property. Otherwise, specify an array of distinct modules.

Note

The array dimensions of the Module input (rows:columns) do not affect how the ModuleAssembly object stacks the modules. Only the StackingAxis and NumLevels properties influence the stacking strategy.

Example: batteryModule.Module = repmat(Module,1,2)

Example: batteryModule.Module = [repmat(module1,1,2),module2]

Shortest distance between modules inside the module 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, this object converts the value to a simscape.Value object with meter as its physical unit.

Example: batteryModuleAssembly.InterModuleGap = simscape.Value(0.01,"m")

Example: batteryModuleAssembly.InterModuleGap = 0.01

Type of electrical connection between modules, specified as either "Series or "Parallel".

Example: batteryModuleAssembly.CircuitConnection = "Series"

Number of levels, tiers, or floors of the module assembly, specified as a positive integer. The value of this property must be equal to or less than the number of modules in the module assembly.

The ModuleAssembly object stacks the modules symmetrically according to the number of levels and modules in the assembly.

For example, this figure shows how the ModuleAssembly object stacks four identical modules when you set this property to 2.

This figure shows how the ModuleAssembly object stacks five identical modules when you still set this property to 2.

This figure shows how the ModuleAssembly object stacks five identical modules when you set this property to 3 instead.

Example: batteryModuleAssembly.NumLevels = 1

State-of-charge balancing strategy for the module assembly, specified as "" or "Passive". Set this property to "Passive" to add an ideal balancing circuit connected in parallel to every parallel assembly inside the ModuleAssembly Simscape model and a physical port of size equal to NumSeriesAssemblies*numel(Module) for switch control.

Note

Modifying this property in this object also modifies this property in the Cell, ParallelAssembly, and Module subcomponents of this object.

Example: batteryModuleAssembly.BalancingStrategy = "Passive"

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

Note

Modifying this property in this object also modifies this property in the Cell, ParallelAssembly, and Module subcomponents of this object.

Example: batteryModuleAssembly.AmbientThermalPath = "CellBasedThermalResistance"

Option to use a simple thermal resistance block connected between the cells and a Simscape thermal network, specified as "CellBasedThermalResistance" or "". If you use a cooling plate, the object connects the thermal resistance block between the cells and the cooling plate block by using an array of thermal nodes.

Note

Modifying this property in this object also modifies this property in the Cell, ParallelAssembly, and Module subcomponents of this object.

Example: batteryModuleAssembly.CoolantThermalPath = "CellBasedThermalResistance"

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

This figure shows the global coordinate system for batteries.

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

Example: batteryModuleAssembly.StackingAxis = "Y"

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

Example: batteryModuleAssembly.MassFactor = 1.2

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

Example: batteryModuleAssembly.Position = [0 0 0]

Name of the battery module assembly, specified as a string.

Example: batteryModuleAssembly.Name = "ModuleAssembly2"

Option to use electrical resistance blocks to represent additional electrical resistances from non-cell components, specified as "No" or "Yes".

Example: batteryModuleAssembly.NonCellResistance = "Yes"

This property is read-only.

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

This property is read-only.

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

This property is read-only.

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

This property is read-only.

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

This property is read-only.

Vectorized thermal node information for external boundary conditions, returned as a structure. This information comprise XY location, XY dimensions, and number of thermal nodes.

This property is read-only.

Type of battery, returned as "ModuleAssembly".

Examples

collapse all

Create a Cell object with a pouch geometry.

batteryCell = Cell(Geometry=PouchGeometry)

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

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

Use this ParallelAssembly object to create a Module object of 10 parallel assemblies connected in series.

batteryModule = Module(ParallelAssembly=pSet,NumSeriesAssemblies=10)

Use this batteryModule object to create a ModuleAssembly object of four identical modules connected in series.

batteryModuleAssembly = ModuleAssembly(Module=repmat(batteryModule,1,4))

Visualize the module assembly by using a BatteryChart object.

moduleAssemblyChart = BatteryChart(Battery=batteryModuleAssembly);

Version History

Introduced in R2022b

See Also

Objects

Functions