从 MATLAB 运行 PyBaMM：扩展电池仿真能力

简介

在许多行业中，电池建模都是设计电池管理系统的关键环节。电池模型作为实时荷电状态估计算法的一部分，嵌入在电池控制软件中。这些模型可用于电池控制策略的快速原型开发，可在研发活动中探究设计敏感性，还可在电池产品设计周期中执行虚拟设计和验证。所有这些任务都可以使用 MATLAB^®、Simulink^® 和 Simscape™ 完成。它们为电池虚拟测试提供了强大的环境，可将控制软件与系统的其余部分集成在一起。

PyBaMM 是一款领先的开源工具，提供了一个电池模型库，其中的模型具有多种复杂度级别，可根据您的需求选用。这些详细的高分辨率电化学电池模型内置了老化效应，既可以直接从 MATLAB 脚本运行，也可以嵌入 Simulink 中。此外，您还可以将 PyBaMM 参数集直接导入 Simscape Battery™ 模块。这些模块支持代码生成、电池组模型自动创建、电热系统建模，以及完全非因果的建模工作流。

本文介绍如何直接从 MATLAB 运行 PyBaMM、将 PyBaMM 电池模型导入 Simulink，以及将 PyBaMM 电池模型中的参数导入等效的 Simscape Battery 模块。本文配套文件可供下载。

安装 PyBaMM

要在 MATLAB 中运行 PyBaMM，您必须先设置一个可从 MATLAB 访问的 Python 环境。（查看各 MATLAB 版本兼容的 Python 版本。）本示例使用的是 MATLAB R2025a 和 Python 3.11。

要在 Python 环境中安装 PyBaMM，请按照 PyBaMM 网站上的说明操作。

准备好已安装 PyBaMM 的兼容 Python 环境后，即可在 MATLAB 中运行 PyBaMM 仿真。如果您的计算机上安装了多个 Python（或者您在使用虚拟环境），请将 MATLAB 指向您希望使用的 Python 可执行文件：

% pe = pyenv("Version", "<path_to_Python.exe>");

要获取 Python 环境中 Python 可执行文件的路径，请在 Python 命令提示符下运行以下命令：

>>> import sys
>>> print(sys.executable)

要检查 MATLAB 当前使用的 Python 环境中是否已安装 PyBaMM，请在 MATLAB 命令行中运行以下命令：

tf = check_pybamm_install()

tf = logical
     1

确认 MATLAB 使用的 Python 环境已安装 PyBaMM 后，即可在 MATLAB 中运行 PyBaMM 仿真。

在 MATLAB 中运行 PyBaMM

在 MATLAB 中运行 PyBaMM 实验与在 Python 中运行的方式类似。本文使用的是 PyBaMM 文档中的一个示例。

首先，导入 PyBaMM 模块，并设置模型和仿真对象。然后运行仿真（本例中以 90 秒为时间步长运行 1 小时），获取求解结果：

pybamm = py.importlib.import_module('pybamm');
model = pybamm.lithium_ion.SPMe();
simulation = pybamm.Simulation(model);
solution = simulation.solve(0:90:3600);

接下来，从求解结果对象中提取您关注的变量。先将这些变量（本例中为时间和电压）填充到求解结果数据字典中，然后再将其转换为可在 MATLAB 中使用的 double 数据类型：

variables = py.list({'Time [s]', 'Voltage [V]'});
solution.update(variables);
t = double(solution.data.get('Time [s]'));
v = double(solution.data.get('Voltage [V]'));

现在，t 和 v 变量已是 MATLAB 数组，可以使用常规 MATLAB 语法绘图：

figure; hold on;
plot(t, v, "-");
plot(t, v, ".", "MarkerSize", 5);
grid on; xlabel("Time (s)"); ylabel("Voltage (V)");

在 Simulink 中运行 PyBaMM

从 MATLAB R2025a 开始，可以使用 Python Code 模块在 Simulink 中运行 Python 代码。用户可以使用该模块编写原生 Python 代码，并在 Simulink 模型中执行。

用户可以通过 Python Code 模块编写在模型初始化、模型步进和仿真终止时执行的 Python 代码。用户还可以为 Python 代码定义端口和参数，从而使该模块能够与 Simulink 中的其他模块交互，并像对 Simulink 画布上的其他模块一样对该模块进行参数化。

在本示例中，我们输入电流负载，输出 PyBaMM 仿真的电压响应，同时允许用户定义电芯模型的初始荷电状态。

端口和参数

端口和参数如图 4 所示，其定义如下：

• current_in 是输入，用于定义电芯的电流负载。在 PyBaMM 中，正电流输入表示放电。
• voltage_out 是输出，包含电芯的电压响应。
• StepSize 是一个参数，用于确定 PyBaMM 求解器推进仿真时使用的固定时间步长。
• InitialStateOfCharge 是一个参数，用于设置仿真开始时的初始荷电状态。
• simulation 是一个持久变量，可使该参数在仿真的不同阶段始终保留在内存中。

其中四个端口和参数定义为“double”数据类型。它们会自动转换为 Python float 数据类型。simulation 参数定义为 PythonObject，因为它是一个 PyBaMM 类。

初始化

“初始化”选项卡包含在 Simulink 仿真开始时执行一次的代码。我们用它来定义 PyBaMM 模型并设置初始条件。

在这里，我们导入 PyBaMM 模型，并定义要使用的电芯模型（本例中为 SPMe 模型）。我们创建 PyBaMM Simulation 对象，并将其存储在 simulation 变量中（该变量定义为持久参数）。然后，我们将电流函数设置为输入，并将 simulation 对象的初始荷电状态设置为用户定义的值。

输出

“输出”选项卡定义在 Simulink 求解器每一步执行的代码。

在本示例中，我们使用 current_in 端口的最新值更新电流输入，并按 StepSize 参数定义的值推进仿真。然后，我们从 PyBaMM 求解结果对象生成的结果字典中获取端电压值，并通过 voltage_out 端口返回最新的时间序列值。

Python Code 模块参数化

在上文的“端口和参数”部分中，我们为 Python Code 模块定义了两个参数。这些参数随后会显示在模块对话框参数中（如下所示）。

PyBaMM 使用自己的求解器进行仿真。因此，必须与 Simulink 求解器步长保持同步。本例使用时间步长为 0.1 秒的定步长求解器（因此我们将 StepSize 参数定义为 0.1）。

Python Code 模块也有自己的采样时间参数。本例中，该参数也需要设置为 0.1。

运行仿真

完成 PyBaMM 仿真的参数化后，即可像往常一样运行仿真。

在本示例中，电芯的初始荷电状态为 50%，仿真进行到 5 秒时对其施加 10 A 负载。正电流输入值会使电池放电。由此得到的电压响应如图 9 所示。

这是在 Simulink 中运行 PyBaMM 仿真所需的最简配置。

将 PyBaMM 参数集导入 Simscape 模块

PyBaMM 针对常见电池化学体系提供了多个预定义的参数集，这些参数集均取自学术文献。在 PyBaMM 中，这些参数集被定义为 ParameterSets 类型的类对象。要在 MATLAB Simscape 模块中使用其中某个参数集，必须先创建一个“等效”的 Simscape 电化学模型模块。在本示例中，导入的参数集将用于 Simscape Battery Single Particle 模块，即含电解质的单粒子模型 (TSPMe)。该模块包含在 Simscape Battery 中。

此外，还需要一个能够执行以下操作的 MATLAB 脚本或对象类：

• 存储 TSPMe 参数。
• 将参数从标准 PyBaMM 约定转换为 Simscape 约定。
• 自动对 Simscape 模块进行参数化。

本文提供了一个 TSPMeParameterSet 自定义对象，用作 TSPMe 模块的参数容器，可将以下 PyBaMM 参数集导入 Battery Single Particle Simscape 模块：["Chen2020","Marquis2019","OKane2022","Ai2020"]。可以对该类进行扩展，以使用其他参数集，或对任何其他类型的模型（例如等效电路模型或 P2D 模型）进行参数化。要导入参数集，请先在 MATLAB 中定义所需的参数集名称：

ParameterSetName = "OKane2022";

要实例化参数容器对象并导入 PyBaMM 参数集，请在命令行窗口中运行以下命令：

SimscapeParameterSet = TSPMeParameterSet(ParameterSet = ParameterSetName);

Importing geometry parameters...Done.
Importing min/max stoichiometries...Done.
Importing OCP vectors...Done.
Importing electrode parameters...Done.
Importing electrolyte parameters...Done.
Importing electrolyte diffusion and electrolyte coefficients...Done.
Importing charge transfer rates...Done.
Importing thermal mass...Done.
Importing initial electrolyte concentration...Done.

现在，参数容器对象已包含来自 PyBaMM 的指定参数集。要自动对 Simscape 中的 Battery Single Particle 模块进行参数化，请在 MATLAB 命令行窗口中运行以下命令：

modelname = "PyBaMM_Simscape_Example";
batteryBlockPath = strcat(modelname,"/","Battery");
open_system(modelname);
parameterizeTSPMe(SimscapeParameterSet, batteryBlockPath);

上述代码片段应已完成对 Simscape 示例模型中 Battery 模块的参数化。

验证 Simscape TSPMe 输出

接下来，您可以分别使用 PyBaMM 和 Simscape 运行仿真并比较输出的电池端电压，以验证 Battery Single Particle 模块的参数化结果。首先，定义负载电流和边界条件：

BatteryCurrent = 2.5; % A
AmbientTemperature = 298.15; % K

PyBaMM 仿真

要在这些条件下运行 PyBaMM 仿真，首先需要创建并更新 PyBaMM 参数集。为此，请在 MATLAB 命令行中执行以下代码： 

PyBaMMParameterSet = pybamm.ParameterValues(ParameterSetName);
PyBaMMParameterSet.update(py.dict(dictionary("Ambient temperature [K]", AmbientTemperature)));
PyBaMMParameterSet.update(py.dict(dictionary("Current function [A]", BatteryCurrent)));

该 PyBaMM 参数集还包含与环境传热相关的参数，因此可将其用于这两个仿真。要提取这些参数以用于 Simscape 仿真，请在 MATLAB 命令行中执行以下代码：

CoolingSurfaceArea = PyBaMMParameterSet.get('Cell cooling surface area [m2]');
HeatTransferCoefficient = PyBaMMParameterSet.get('Total heat transfer coefficient [W.m-2.K-1]');

要运行 PyBaMM 仿真，请执行以下代码：

model = pybamm.lithium_ion.SPMe();
simulation = pybamm.Simulation(model,parameter_values=PyBaMMParameterSet);
solution = simulation.solve(0:10:3600*2);

Simscape 仿真

要在 Simscape 中运行相同的仿真，请执行以下代码：

set_param(modelname,"StopTime","3600*2")
set_param(modelname,"SimscapeLogType","all")
out = sim(modelname);

与前面一样，从 PyBaMM 求解结果对象中提取您关注的变量。先将变量（本例中为时间和电压）填充到求解结果数据字典中，然后再将其转换为可在 MATLAB 中使用的 double 数据类型：

variables = py.list({'Time [s]', 'Voltage [V]'});
solution.update(variables);
time = double(solution.data.get('Time [s]'));
voltage = double(solution.data.get('Voltage [V]'));

Simscape 仿真输出对象 out 包含电池电压以及 TSPMe 模块跟踪的所有其他变量。要绘制 PyBaMM 与 Simscape 的对比图，请运行以下命令：

figure;
plot(time, voltage, "o");
hold on
plot(out.simlog.Battery.batteryVoltage.series.time,out.simlog.Battery.batteryVoltage.series.values,"r");
grid on
xlabel("Time (s)")
ylabel("Voltage (V)")
legend(["PyBaMM","Simscape"])

请注意，验证误差会随所施加的 C 倍率和温度条件而变化。默认的 Simscape TSPMe 模块未考虑扩散系数和电解质电导率对浓度的依赖关系，而 PyBaMM 模型可以考虑这一点。因此，在较高 C 倍率下，端电压值之间的差异会更大。

从电芯到电池系统的规模扩展

要将 Simscape 模型从电芯扩展到系统，请使用 Simscape Battery Pack Builder 功能。首先，创建一个电芯对象，并将其链接到 Battery Single Particle 模型模块：

battCell = batteryCell();
battCell.CellModelOptions.CellModelBlockPath = "batt_lib/Cells/Electrochemical/Battery Single Particle";
battCell.CellModelOptions.BlockParameters.StoichiometryBreakpointsSpecification = "absolute";

定义好电芯对象后，运行以下 MATLAB 命令，将电芯模型扩展到模组级别：

battPSet = batteryParallelAssembly(battCell,4, "Rows",4);
battModule = batteryModule(battPSet,4, ...
    "ModelResolution", "Detailed",...
    "AmbientThermalPath","CellBasedThermalResistance");

将 ModelResolution 属性设置为“Detailed”，即可提高模型分辨率。要自动生成电池模型，请运行以下命令：

buildBattery(battModule, "MaskParameters", "VariableNamesByType");

上述代码片段应已生成一个电池库，其中包含您的电池模组模型模块，如图 12 所示。

运行这个新模型模块所需的参数存储在新生成的脚本中：Batteries_param.m。要将模组参数链接到 PyBaMM 参数集，请运行以下命令：

Module1 = SimscapeParameterSet.getModuleElectrochemicalParameters(SimscapeParameterSet);

现在，您可以使用这个新创建的电池模型模块，在 Simulink 环境中创建并运行电池恒定放电仿真。此外，您还可以使用 BatterySimulationChart 在整个仿真过程中动态可视化关键电池变量。要创建并运行仿真，请运行以下命令：

run("CreateAndRunBatterySimscapeModel.mlx")

结束语

本文介绍了将 PyBaMM 电池建模能力集成到 MATLAB、Simulink 和 Simscape 中的三种不同工作流。每种工作流各有优势，适用于不同的特定任务。例如，将 PyBaMM 与 Simulink 集成非常适合用于快速原型开发和电池管理系统开发。将 PyBaMM 参数集导入 Simscape 则非常适合创建非因果物理模型，这些模型可以高效地扩展，并纳入更大范围的电气和热仿真中。使用 Simscape Battery Pack Builder 功能，可以高效地将电芯模型扩展为系统模型。这种集成有助于增强 MATLAB 的原生功能，并可为业界使用的各种电池设计和开发工作流带来更多价值。

后续工作

本文介绍的方法简单易行，并且依托现有功能。这些方法还可以进一步完善和扩展，例如纳入更多 PyBaMM 电化学模型、支持其他参数集，以及增加复杂的系统级建模等。

今后，我们将在本文介绍的工作流基础上，展示这种集成如何支持实际的电池设计和验证活动。我们还将探索在 PyBaMM 与 MATLAB 之间建立连接的其他方法，并结合这些方法为目标电池应用带来的优势进行介绍。

未来可展示的方向包括： 

• 借助模组级和电池组级系统进行电池组设计与验证，在真实热条件下预测可用能量和功率能力
• 依托 PyBaMM 的电池老化模型库，增强电池系统老化和质保预测
• 简化 PyBaMM 参数集在更多种类 Simscape 模块中的使用
• 基于 PyBaMM 的模型如何支持 Simulink 中的控制器开发

致谢

特别感谢克兰菲尔德大学 (Cranfield University) 的 Daniel Auger 教授，感谢其与我们的合作、对未来工作方向的见解，以及就 MATLAB 与 PyBaMM 之间的连接方法及其在电池系统中的应用与我们进行的多次讨论。