Module
说明
使用 Module 创建一个电池模组对象，该对象代表多个电连接的电池并联组件。您可以将此对象作为 ModuleAssembly 对象的输入，以创建更大的电池模型。
要定义并联组件或串联电芯的数量，请使用 NumSeriesAssemblies 属性。要生成 Module 对象的 Simscape™ 模型，请使用 buildBattery 函数。此对象仅支持结构或设计参数的定义。创建模型后，您可以修改此模型模块及其组成电芯的运行时参数。
Module 对象是自下而上方法中的电池包系统模型的第三阶段。在早期开发阶段、软件和硬件开发、系统集成和需求评估、冷却系统设计、控制策略开发硬件在环等许多应用中，都需要使用包模型进行架构评估。
默认情况下，并联组件或电芯沿笛卡尔坐标系的 y 轴堆叠，并复制 NumSeriesAssemblies 属性的值所指定的次数。要沿 x 轴堆叠并联组件，请将 StackingAxis 属性设置为 "X"。
指定模型分辨率
Module 对象的推荐模型分辨率为 "Lumped"。您可以使用 ModelResolution 属性增加或减少 Module 对象的本地分辨率。如果将 ModelResolution 属性设置为 "Grouped"，则可以使用 SeriesGrouping 和 ParallelGrouping 属性定义自定义模型分辨率。例如，考虑一个由六个并联组件串联组成的电池架构（NumSeriesAssemblies = 6）。每个并联组件都由六个电芯组成。该架构至少需要 36 个电池模型进行仿真。为了提高模型速度并优化编译时间，您可以通过将 SeriesGrouping 属性设置为 [1 4 1] 来选择仅使用三个电气模型。第一和第三子模组组成一个并联组件。第二个子模组包括剩余的四个并联组件。
或者，您可以通过将 SeriesGrouping 更改为 [1 1 2 1 1] 来为每个并联组件选择更高的分辨率。
对于具有单个并联组件的子模组，您可以通过将 ParallelGrouping 属性分别设置为 [6 1 6] 和 [6 6 1 6 6]，进一步离散化电气和热模型，以获得每个电芯的分辨率。
有关模型分辨率和仿真策略的详细信息，请参阅 SeriesGrouping 和 ParallelGrouping 属性。
热边界条件
热边界条件定义了电芯热模型与其周围环境的每个接触面发生的特定传热机制。在电池系统中，电池电芯通常与不同的热源和散热器进行热耦合，这些热源和散热器都会影响电池电芯的温度。电芯模型的热边界条件的数量和类型取决于电池系统的热设计和机械设计。
例如，您可以将电芯放置在铝制冷却板上以增强散热效果，同时使用灌封化合物将电芯机械连接在一起，从而有效消除或减少电芯之间的热交换路径。电芯温度对电池性能和使用寿命有直接影响。因此，在动态仿真中预测此状态至关重要。
在电池对象内，您可以设置集总热质量电芯模型的热网络，以同时捕获到环境、冷却液和/或冷却板的热路径：
这些选项并不互斥。例如，电池模型可以结合冷却液热路径和冷却热板来建模各个电芯与冷却板各部分之间的热阻。
有关热路径的详细信息，请参阅 AmbientThermalPath、CoolantThermalPath 和 CoolingPlate 属性。
电芯间的热交换
您还可以对电芯间的直接热交换建模。当您想要仿真更详细的热管理策略，甚至热传播场景（其中电芯之间的热传递速度快于环境或冷却液的速度）时，这一点非常重要。在电池行业，可以通过多种不同方式将电池电芯相互连接起来。例如，您可以使用灌封化合物来提高圆柱形电芯的机械刚性、稳定性和隔热性，或使用其他类型的热界面材料。您还可以使用介电流体或其他化合物以及强制空气对流来加热或冷却圆柱形电芯。
创建电池模型后，您可以定义电芯间热交换的热参数。您可以从第一性原理计算和更详细的三维仿真中找到这些参数。
这些选项并不互斥。
有关电芯间热路径的更多信息，请参阅 InterCellThermalPath 和 InterCellRadiativeThermalPath 属性。
表面边界处的热节点 (自 R2024a 起)
为了更详细地对电池包环境中的电池电芯进行热建模，您还可以暴露位于模组表面边界处的电芯热节点：
要暴露特定表面边界上的热节点，请相应地指定 XminThermalNodes、XmaxThermalNodes、YminThermalNodes 和 YmaxThermalNodes 属性。
对于包含六边形圆柱电芯的模组，还可以在模组电芯和蛇形冷却板之间进行热传导。要在模组内部的蛇形冷却板上显示热节点，请指定 SerpentineCoolingPlate 属性。然后，通过指定 FractionOfCellCircumferenceForHeatExchange 和 FractionOfCellHeightForHeatExchange 属性，可以进一步定义用于蛇形冷却板中的热交换界面的圆柱形电芯的周长和高度的比例。
下表显示了表面热边界与受影响电芯之间的关系：
| 模组热边界 | 模型与仿真输出 | 布局 | |
|---|---|---|---|
模型分辨率：详细 |
| 布局 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 | |
模型分辨率：详细 |
| CellsAtXmaxBoundary 36 40 44 48 | |
模型分辨率：详细 |
| 布局 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 | |
模型分辨率：详细 |
| 布局 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 | |
模型分辨率：详细 |
| 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 | |
有关如何实现标量和向量化热边界条件的示例，请参阅 向电池模型添加向量化和标量热边界条件。
创建对象
描述
注意
要快速创建一个 Module 对象，请使用 batteryModule 函数。使用此函数，您无需导入命名空间、使用完整类名或在创建对象时仅处理名称-值参量。 (自 R2024a 起)
要使用此对象，请在 MATLAB® 命令行窗口中，在每个 MATLAB 会话中至少运行一次以下命令：
import simscape.battery.builder.*;
batteryModule = Module
属性
模组中的并联组件，指定为 ParallelAssembly 对象。Module 对象创建此组件，然后将其电连接成与 NumSeriesAssemblies 属性的值相等的串联次数。
模组内串联的并联组件数量，指定为严格为正且有限的整数。此属性的值必须小于 150。
仿真中的模型分辨率或保真度，指定为：
"Lumped" - 选择此值可获得最低保真度。该模组仅使用一个电气模型。要获得最短的编译时间和运行时间，请使用该值。
"Detailed" - 选择此值可获得最高保真度。该模组为每个电池电芯使用一个电气模型和一个热模型。
"Grouped" - 选择此值以使用基于
SeriesGrouping和ParallelGrouping属性的自定义仿真策略。
沿串联连接的模组建模策略，指定为正整数的行向量。
该向量的长度指定所需的单独电气模型数量。每个条目指定指定电气模型中包含多少个并联组件。例如，如果模组由四个并联组件（NumSeriesAssemblies = 4）组成，并将此属性设置为 [2 1 1]，则对象将模组离散为三个单独的电气模型。第一个模型由两个原始的并联组件组成。
此向量中的条目之和必须等于 NumSeriesAssemblies 属性的值。
依赖关系
要启用此属性，请将 ModelResolution 属性设置为 "Grouped"。
SeriesGrouping 属性中定义的每个并联组件的建模策略，指定为正整数的向量。该向量的长度必须与 SeriesGrouping 属性的值的长度相等。
该向量的每个条目指定了用于输入 SeriesGrouping 属性的单独电气模型的数量。条目的值必须为 1 或 NumParallelCells 属性的值。
例如，假设您的模组包含以下元素：
四个并联组件 (
NumSeriesAssemblies=4)每个并联组件有 48 个圆柱形电芯（
NumParallelCells=48）三个单独的电气模型，其中第一个模型包括两个原始并联组件（
SeriesGrouping=[2 1 1]）
如果将此属性设置为 [1 1 48]，则对象将模组离散为 50 个单独的电气模型，其中第四个并联组件的每个电芯都有一个电气模型。
如果 SeriesGrouping 属性的相应条目的值大于 1，则此属性中的条目值必须为 1。
依赖关系
要启用此属性，请将 ModelResolution 属性设置为 "Grouped"。
模组内并联组件之间的最短距离，指定为正标量或 simscape.Value 对象，该对象表示一个以长度为单位的标量。该属性的值必须小于 0.1 米。
如果直接使用正标量值设置此属性，而不是使用 simscape.Value 对象，则对象将值转换为以米为物理单位的 simscape.Value 对象。
模组的荷电状态平衡策略，指定为 "None"、"Passive" 或 "External"。
将此属性设置为 "Passive"，以添加一个理想平衡电路数组，该数组与每个并联组件和物理端口电连接，其大小与用于开关控制的 NumSeriesAssemblies 属性的值相同。当控制信号等于0时，开关处于断开状态。当控制信号等于1时，开关处于闭合状态。
要指定外部电池平衡策略对其建模，请将此属性设置为 "External"。然后，Module (Generated Block) 会暴露两个电气节点数组端口，即 +BUS 和 -BUS。对于桌面仿真和硬件在环电池仿真硬件，请将此选项与 Passive Balancing Interface 模块结合使用。
注意
设置该属性会自动将其值传播到该 Module 对象内的所有子组件电池对象。但是，这一更改不会传播到 MATLAB 工作区中的其他电池对象。如果在创建此 Module 对象时未设置此属性，则默认值会自动传播到其所有子组件电池对象。
示例: batteryModule.BalancingStrategy = "Passive"
选项：在电芯和 Simscape 热网络之间连接一个简单的热阻模块，指定为 "CellBasedThermalResistance" 或 "None"。
注意
设置该属性会自动将其值传播到该 Module 对象内的所有子组件电池对象。但是，这一更改不会传播到 MATLAB 工作区中的其他电池对象。如果在创建此 Module 对象时未设置此属性，则默认值会自动传播到其所有子组件电池对象。
示例: batteryModule.AmbientThermalPath = "CellBasedThermalResistance"
选项：在电芯和 Simscape 热网络之间连接一个简单的热阻模块，指定为 "CellBasedThermalResistance" 或 "None"。
如果您还定义了冷却板表面，则对象将每个电池热模型与热节点数组中的相应元素之间的热阻模块连接起来。
注意
设置该属性会自动将其值传播到该 Module 对象内的所有子组件电池对象。但是，这一更改不会传播到 MATLAB 工作区中的其他电池对象。如果在创建此 Module 对象时未设置此属性，则默认值会自动传播到其所有子组件电池对象。
示例: batteryModule.CoolantThermalPath = "CellBasedThermalResistance"
在特定表面边界使用冷却板组件的选项，指定为 "Top"、"Bottom" 或 "None"。
注意
设置该属性会自动将其值传播到该 Module 对象内的所有子组件电池对象。但是，这一更改不会传播到 MATLAB 工作区中的其他电池对象。如果在创建此 Module 对象时未设置此属性，则默认值会自动传播到其所有子组件电池对象。
示例: batteryModule.CoolingPlate = "Top"
自 R2023a 起
指定要将哪个冷却板模块分配给由 CoolingPlate 属性定义的边界上的 Module 对象，指定为 "batt_lib/Thermal/Edge Cooling"、"batt_lib/Thermal/Parallel Channels"、"batt_lib/Thermal/U-Shaped Channels" 或 "None"。
注意
设置该属性会自动将其值传播到该 Module 对象内的所有子组件电池对象。但是，这一更改不会传播到 MATLAB 工作区中的其他电池对象。如果在创建此 Module 对象时未设置此属性，则默认值会自动传播到其所有子组件电池对象。
示例: batteryModule.CoolingPlateBlockPath = "batt_lib/Thermal/Edge Cooling"
自 R2024a 起
在 Module 对象的最小 X 轴表面边界处显示热节点的选项，指定为：
"None" - 不暴露热节点。
"Scalar" - 在 X 轴表面边界上的最小位置暴露一个集总热节点。
"Vectorized" - 在最小 X 轴表面边界处显示热节点数组。
注意
设置该属性会自动将其值传播到该 Module 对象内的所有子组件电池对象。但是，这一更改不会传播到 MATLAB 工作区中的其他电池对象。如果在创建此 Module 对象时未设置此属性，则默认值会自动传播到其所有子组件电池对象。
示例: batteryModule.XminThermalNodes = "Scalar"
自 R2024a 起
将热节点暴露在 Module 对象的最大 X 轴表面边界上的选项，指定为：
"None" - 不暴露热节点。
"Scalar" - 在 X 轴表面边界处暴露一个集总热节点。
"Vectorized" - 在最大 X 轴表面边界处显示热节点数组。
注意
设置该属性会自动将其值传播到该 Module 对象内的所有子组件电池对象。但是，这一更改不会传播到 MATLAB 工作区中的其他电池对象。如果在创建此 Module 对象时未设置此属性，则默认值会自动传播到其所有子组件电池对象。
示例: batteryModule.XmaxThermalNodes = "Scalar"
自 R2024a 起
将热节点暴露在 Module 对象的最小 Y 轴表面边界上的选项，指定为：
"None" - 不暴露热节点。
"Scalar" - 在 Y 轴表面边界上的最小位置暴露一个集总热节点。
"Vectorized" - 在最小 Y 轴表面边界处显示热节点数组。
注意
设置该属性会自动将其值传播到该 Module 对象内的所有子组件电池对象。但是，这一更改不会传播到 MATLAB 工作区中的其他电池对象。如果在创建此 Module 对象时未设置此属性，则默认值会自动传播到其所有子组件电池对象。
示例: batteryModule.YminThermalNodes = "Scalar"
自 R2024a 起
将热节点暴露在 Module 对象的最大 Y 轴表面边界上的选项，指定为：
"None" - 不暴露热节点。
"Scalar" - 在 Y 轴表面边界最大处暴露一个集总热节点。
"Vectorized" - 在最大 Y 轴表面边界处显示热节点数组。
注意
设置该属性会自动将其值传播到该 Module 对象内的所有子组件电池对象。但是，这一更改不会传播到 MATLAB 工作区中的其他电池对象。如果在创建此 Module 对象时未设置此属性，则默认值会自动传播到其所有子组件电池对象。
示例: batteryModule.YmaxThermalNodes = "Scalar"
自 R2024a 起
选项，用于在蛇形冷却板接口处暴露热节点数组，适用于包含六角形拓扑结构圆柱形电池的电池，指定为 "None"、"SingleSidedAlongStackingAxis" 或 "DoubleSidedAlongStackingAxis"。
此图显示了将此属性设置为 "SingleSidedAlongStackingAxis" 或 "DoubleSidedAlongStackingAxis" 时，蛇形冷却板的配置：
注意
设置该属性会自动将其值传播到该 Module 对象内的所有子组件电池对象。但是，这一更改不会传播到 MATLAB 工作区中的其他电池对象。如果在创建此 Module 对象时未设置此属性，则默认值会自动传播到其所有子组件电池对象。
示例: batteryModule.SerpentineCoolingPlate = "SingleSidedAlongStackingAxis"
自 R2024a 起
用作热交换界面的圆柱形电芯周长的一部分，以双精度数在 (0,0.5) 范围内指定。该属性仅适用于蛇形冷却板。
示例: batteryModule.FractionOfCellCircumferenceForHeatExchange = 0.3
自 R2024a 起
用作热交换界面的圆柱形电芯高度的百分比，以双精度数在 (0,1) 范围内指定。该属性仅适用于蛇形冷却板。
示例: batteryModule.FractionOfCellHeightForHeatExchange = 0.8
电池对象在三维笛卡尔坐标系中的位置，指定为实数和有限条目的向量。
示例: batteryModule.Position = [0 0 0]
电池模组的名称，指定为字符串。
示例: batteryModule.Name = "Module2"
二维笛卡尔坐标系中电池电芯排列的优先堆叠方向，指定为 "X" 或 "Y"。
下图显示了电池的全球坐标系。
要在 x 轴方向绘制模组对象，请在创建 BatteryChart 对象之前将此属性设置为 "X"。
示例: batteryModule.StackingAxis = "Y"
由母线、选项卡和集流板等组件添加到模组中的与电芯无关的附加质量，以大于或等于 1 的正双精度数指定。
示例: batteryModule.MassFactor = 1.2
使用电阻模块表示非电芯组件的附加电阻的选项，指定为 'off'、'on' 或数字或逻辑 1 (true) 或 0 (false)。'on' 的值等效于 true，而 'off' 的值等效于 false。因此，您可以将此属性的值用作逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。
示例: batteryModule.NonCellResistance = 'on'
自 R2023a 起
使用热阻模块来表示相邻电池电芯之间的线性电芯间热传递路径的选项，指定为 'off'、'on' 或数字或逻辑 1 (true) 或 0 (false)。'on' 的值等效于 true，而 'off' 的值等效于 false。因此，您可以将此属性的值用作逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。
只有当您选择了电芯热模型且电池内存在多个电芯或电芯模型时，启用电池电芯间热路径才有用。
您可以在创建模型后定义热阻参数值。
如果将该属性设置为 'on'，则不能将 InterCellRadiativeThermalPath 属性设置为 'on'。
注意
设置该属性会自动将其值传播到该 Module 对象内的所有子组件电池对象。但是，这一更改不会传播到 MATLAB 工作区中的其他电池对象。如果在创建此 Module 对象时未设置此属性，则默认值会自动传播到其所有子组件电池对象。
示例: batteryModule.InterCellThermalPath = "on"
自 R2023a 起
使用热阻模块来表示相邻电池电芯之间的辐射式电芯间热传递路径的选项，指定为 'off'、'on' 或数字或逻辑值 1（true）或 0 (false)。'on' 的值等效于 true，而 'off' 的值等效于 false。因此，您可以将此属性的值用作逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。
只有当您选择了电芯热模型且电池内存在多个电芯或电芯模型时，启用电芯间辐射热路径才有用。
您可以在创建模型后定义辐射热传参数值。
如果将该属性设置为 'on'，则不能将 InterCellThermalPath 属性设置为 'on'。
注意
设置该属性会自动将其值传播到该 Module 对象内的所有子组件电池对象。但是，这一更改不会传播到 MATLAB 工作区中的其他电池对象。如果在创建此 Module 对象时未设置此属性，则默认值会自动传播到其所有子组件电池对象。
示例: batteryModule.InterCellRadiativeThermalPath = "on"
自 R2023b 起
在构建此对象时生成的 Module 模块中，可选择对电芯到电芯参数变化进行建模，指定为 "NoVariation" 或 "PercentDeviation"。
如果将此属性设置为 "PercentDeviation"，则生成的 Module 模块中的电池电芯参数将具有一个关联的百分比偏差参数，该参数指定电池中每个电池模型对应电池电芯参数值的百分比偏差。枚举或布尔类型的电芯参数没有关联的百分比偏差参数。
应用偏差后，相应电芯参数的值等于：
有关电芯与电芯参数变化的详细信息，请参阅 Apply Temperature-Dependent Cell Parameter Variations to Battery Module 示例。
示例: batteryModule.CellParameterVariation = "PercentDeviation"
依赖关系
要启用此属性，请将 ModelResolution 设置为 "Detailed" 或 "Grouped"。
此 属性 为只读。
电池体积，以 simscape.Value 对象形式返回，该对象以体积为单位。
此 属性 为只读。
电池的累积质量，以 simscape.Value 对象形式返回，该对象以质量为单位。
此 属性 为只读。
仿真中的电芯模型模块数，以双精度数返回。
自 R2023a 起
此 属性 为只读。
电芯之间的内部热连接数量，以整数返回。
自 R2023a 起
此 属性 为只读。
并联组件之间的内部热连接数，以整数形式返回。
自 R2023a 起
此 属性 为只读。
电芯之间的内部连接的二维地图，以整数矩阵的形式返回。
电芯编号约定是指 Layout 属性。要了解分配给每个电芯的编号及其与相邻电芯的关系，请参阅 Layout 属性。
例如，如果一个电池模组有三个并联组件，每个组件有四个软包电芯，则该属性等于：
自 R2023a 起
此 属性 为只读。
并联组件之间的内部连接的二维地图，以整数矩阵的形式返回。
并联组件的编号沿堆叠轴方向递增。
例如，如果一个电池模组有三个并联组件，每个组件有四个软包电芯，则该属性等于：
自 R2023a 起
此 属性 为只读。
每个并联组件内各个电池电芯模型与其相邻并联组件中相应邻居之间的内部连接的二维映射，以整数矩阵的形式返回。
映射的电芯编号约定与每个单独并联组件的 Layout 属性相关。
此 属性 为只读。
电池内部所有电芯的编号，以结构体形式返回。
此 属性 为只读。
外部边界条件的向量化热节点信息，以结构体形式返回。该信息包括 XY 位置、XY 维度和热节点数。如果未定义电池电芯的几何形状，则此属性为空结构体。
自 R2023a 起
此 属性 为只读。
母体中的子组件或电芯的二维分布，以整数矩阵的形式返回。
此属性取决于 StackingAxis 属性以及电芯数量。
自 R2024a 起
此 属性 为只读。
最小 X 轴表面边界处的电芯索引，以整数向量形式返回。
自 R2024a 起
此 属性 为只读。
最大 X 轴表面边界处的电芯索引，以整数向量返回。
自 R2024a 起
此 属性 为只读。
最小 Y 轴表面边界处的电芯索引，以整数向量返回。
自 R2024a 起
此 属性 为只读。
最大 Y 轴表面边界处的电芯索引，以整数向量形式返回。
自 R2024a 起
此 属性 为只读。
蛇形边界上的电芯索引，以整数向量形式返回。
此 属性 为只读。
电池对象类型，返回为 "Module"。
示例
创建一个具有软包几何形状的 Cell 对象。
batteryCell = Cell(Geometry=PouchGeometry)
创建一个具有默认拓扑结构的三个电芯的 ParallelAssembly 对象。
pSet = ParallelAssembly(Cell=batteryCell,NumParallelCells=3)
使用该 ParallelAssembly 对象创建一个由 10 个串联的并联组件组成的 Module 对象。
batteryModule = Module(ParallelAssembly=pSet,NumSeriesAssemblies=10)
使用 BatteryChart 对象可视化该模组。
moduleChart = BatteryChart(Battery=batteryModule);
创建一个 Cell 对象，并使用它来创建一个 ParallelAssembly 对象。
batteryCell = Cell(Geometry=CylindricalGeometry)
pSet = ParallelAssembly(Cell=batteryCell,NumParallelCells=6,Rows=3,Topology = "Square")使用此 ParallelAssembly 对象创建一个由 6 个并联组件串联的 Module 对象。
batteryModule = Module(ParallelAssembly=pSet,NumSeriesAssemblies=6,InterParallelAssemblyGap=simscape.Value(0.005,"m"))将该模组离散为三个单独的电气模型。第二个模型由四个原始模组的并联组件组成。
batteryModule.SeriesGrouping = [1 4 1]
要验证建模分辨率，请使用 BatteryChart 对象可视化模组，然后点击图右上角的“显示/隐藏仿真策略”按钮。
moduleChart = BatteryChart(Battery=batteryModule);
