Battery Builder
Description
Use the Battery Builder app to create Simscape™ battery models by interactively creating, modifying, and visualizing MATLAB® battery objects. You can use these MATLAB objects to define your own battery design specifications, visualize your battery in a 3-D plot, customize the modeling resolution during simulation, and generate a Simulink® library that contains your custom battery blocks. You can use these blocks to assist with virtual battery design and verification, develop battery control algorithms using Simulink, explore design sensitivities, and design thermal management strategies.
With the Battery Builder app, you can:
Import existing battery objects from your workspace or MAT file.
Create new
Cell,ParallelAssembly,Module,ModuleAssembly, andPackobjects. Each battery object has its own properties and parameters. For information about the properties of the battery objects, see theCell,ParallelAssembly,Module,ModuleAssembly, andPackdocumentation pages.Generate a 3-D plot of the battery object, edit the plotting options, and export the plot to a file.
Inspect the hierarchy of a battery object and visualize all of its subcomponents.
Edit the properties of a battery object, such as geometrical data and thermal boundary conditions.
Export objects you create in the app to your workspace, a MAT file, or an STL file.
Create a Simscape battery model from an object.
Open the Battery Builder App
MATLAB Toolstrip: On the Apps tab, under Simscape, click the Battery Builder icon.
MATLAB command prompt: Enter
batteryBuilder.
Examples
To import the battery objects from your workspace or from a MAT file, under the Battery Builder tab, in the Import section of the toolstrip, click Import. Then click Import from Workspace or Import from MAT-file.
Note
When you import an object, the app also automatically imports all its subcomponent battery objects.
To create a new battery object, under the Battery Builder tab, in the Create section of the toolstrip, click Cell, Parallel Assembly, Module, Module Assembly, or Pack to create the battery object. This action creates the corresponding battery object with default property values.
The Battery Browser panel on the left of the app now contains the new object. You can select this object, visualize it in the Selected Battery tab, check its hierarchy and child objects in the Battery Hierarchy panel, and edit its properties in the Properties panel on the right of the app.
To visualize a battery object, under the Battery Builder tab, in the Battery Browser panel, select the object you want to visualize. The Selected Battery tab now displays a 3-D plot of the object.
You can edit multiple properties of the plot under the Battery Chart tab, such as the axes labels, axes direction, title of the plot, and lights. You can also check the current simulation strategy and model resolution of the selected battery object. To visualize the simulation strategy in the plot, in the Simulation Strategy section of the toolstrip, check the Visible box.
To edit a battery object, select it in the left Battery Browser panel of the app. The Properties panel on the right of the app now displays all the editable properties of the object.
To apply any changes, you must refresh the object by clicking Apply.
Each battery object has its own properties and parameters. For information about the
properties of the battery objects, see the Cell,
ParallelAssembly, Module,
ModuleAssembly, and Pack
documentation pages.
Note
To display the relevant unit for relevant properties, including those of type
Simscape.Value, point on the edit field of the property.
The Properties panel of the app contains the properties of the
ParallelAssembly, Module,
ModuleAssembly, and Pack objects in six sections.
Read-Only Properties — Data about the total mass, volume, energy, and capacity of the battery. You cannot modify these properties.
Identifier — Name of the object. Modify this property to modify the name of the object as it appears in the left Battery Browser panel of the app.
Geometry — Geometrical information about the object, such as the position inside the chart and the stacking axis of the battery.
Properties — Structural information about the object, including the subcomponent object from which the parent object is created, how these children objects are stacked, and the gap between the objects.
Model Options — Modeling information about the object, such as options to enable non-cell resistances or a balancing strategy.
Thermal Model Options — Information that defines the thermal boundary conditions of the object.
When you create a ParallelAssembly, Module,
ModuleAssembly, or Pack object,
you must specify its defining subcomponent in parallel and/or in series and scale it up
to generate larger battery system models.
For example, a battery module comprises multiple parallel assemblies in series. When
you create a Module object, you must assign to this
Module object the associated ParallelAssembly
subcomponent object that forms the parent module.
To assign a child component to its parent component, first select the parent component to which you want to assign a child component in the Battery Browser panel. Then, in the Properties panel on the right of the app, in the Properties section, search for the property with the name of the child component you want to assign and click Select.
In the new window, select all the child components and click Add.
You can duplicate, delete, or move the components you add by clicking the respective buttons on the right of the window.
Once you add the child component, click OK. This action assigns a copy of the child component to the parent component. You can visualize the hierarchy of your battery object in the Battery Hierarchy panel on the bottom left of the app.
Note
When you assign a child component to a parent component, the parent component creates an internal instance that has no connection to the original child component in the Battery Browser panel. If you modify the original child component in Battery Browser panel and you want to apply these changes to the parent component, you must assign it again.
You can visualize all the subcomponents of a specific battery object in the Battery Hierarchy panel of the app. Select a subcomponent inside the Battery Hierarchy panel to show a 3-D plot of the object in the Selected Battery panel and its properties in the Properties panel on the right of the app.
You cannot modify any of the properties of the subcomponent objects that you select in the Battery Hierarchy panel. To modify the objects, select them in the Battery Browser panel first.
Since R2026a
The Battery Builder app allows you to easily identify the index of a cell model block or specific subcomponent of your battery objects.
The number of cell model blocks in your battery depends on the model resolution you
choose to model your battery at. By default, the model resolution is
Lumped. This resolution indicates that only one “scaled-up”
equivalent circuit model represents your system. If you increase the model resolution to
Grouped, you can customize the number of electrical and
thermal models. If you require a very detailed battery model, you can choose to simulate
every single cell inside your battery at a greater performance cost.
To visualize the number of cell model blocks in your battery, select the object you want to visualize in the Battery Hierarchy or Battery Browser panel. Then, under the Battery Chart tab, in the Simulation Strategy section of the toolstrip, click Cell Model Numbering and select one of these options:
Independent — Restart numbering at 1 for the cell model blocks of each battery object in the Battery Hierarchy panel.
Cumulative — Maintain sequential numbering for cell model blocks across all battery objects in the Battery Hierarchy panel.
This table shows how the Battery Builder app visualizes the
cell model numbering on a module assembly with two modules and a
"Lumped" module resolution when you select
Independent or
Cumulative.
| Selected Battery Object in Battery Hierarchy | Cell Model Numbering | |
|---|---|---|
| Independent | Cumulative | |
Module assembly
| The numbering of the cell model blocks starts at 1.
| |
Module 1
| The numbering of the cell model blocks starts at 1.
| |
Module 2
| The numbering of the cell model blocks starts at 1.
| The numbering of the cell model blocks continues from the previous Module 1 and starts at 2.
|
To visualize the index of a specific subcomponent inside your battery object, select the object you want to visualize in the Battery Hierarchy or Battery Browser panel. Then, under the Battery Chart tab, in the Simulation Strategy section of the toolstrip, click Battery Numbering and select one of these options:
Independent — Restart numbering at 1 for the cells in each subcomponent of the selected parent battery object.
Local Cumulative — Maintain sequential numbering only inside the currently displayed subcomponent.
Global Cumulative — Maintain sequential numbering across all subcomponents of the highest parent battery object.
This table shows how the Battery Builder app visualizes the
battery numbering on a module assembly with two modules when you select
Independent, Local Cumulative,
or Global Cumulative. Each module comprises three parallel
assemblies of six cells.
Note
In the displayed object, C stands for cell, P stands for parallel assembly, M stands for module, and MA stands for module assembly.
| Selected Battery Object in Battery Hierarchy | Battery Numbering | ||
|---|---|---|---|
| Independent | Local Cumulative | Global Cumulative | |
Module assembly
| For the first and second module of the module assembly, the Battery Builder app starts numbering P at 1 and C at 1. | The battery numbering is cumulative
across all subcomponents of the module assembly and counts each module,
parallel assembly, and cell individually. As this is the highest parent
battery object, the | |
|
| ||
Module 1
| The battery numbering is independent of the direct parent object. The app restarts numbering C at 1 for each parallel assembly inside the module. | The battery numbering is sequential inside the displayed battery object for both the parallel assemblies and the cells. | The battery numbering is sequential across all subcomponents of the
module assembly. This is the first module of the module assembly so the
displayed numbers are identical to the numbers of the |
|
|
| |
Module 2
| The battery numbering is independent of the direct parent object. The app restarts numbering C at 1 for each parallel assembly inside the module. | The battery numbering is sequential inside the displayed battery object for both the parallel assemblies and the cells. | The battery numbering is sequential across all subcomponents of the module assembly. This is the second module of the module assembly so the numbering continues from the numbers of the previous module. |
|
|
| |
The information you obtain from the cell model blocks and battery numbering is important to perform different tasks on your battery object, including fault injection and thermal and thermal boundary modeling. This table shows the information required to perform a specific task and how to obtain it in the Battery Builder app.
| Task | Required Information | Battery Builder App | Related Examples |
|---|---|---|---|
| Thermal modeling | Cumulative number of cell model blocks. | Under the Battery Chart tab, in the
Simulation Strategy section of the toolstrip, click
Cell Model Numbering and select
"Cumulative". | |
| Thermal boundary nodes | Cumulative number of cells inside the specific battery |
| |
| Fault injection |
ModelResolution =
"Detailed" |
| |
| Independent number of a cell inside the specific battery | |||
ModelResolution = "Lumped" or
"Grouped" |
| ||
| Independent number of cell model blocks | |||
| Passive cell balancing | Global cumulative number of parallel assemblies. The size of the CB port of the generated battery blocks is equal to the number of parallel assemblies inside the block (regardless of the model resolution). | Under the Battery Chart tab, in the
Simulation Strategy section of the toolstrip, click
Battery Numbering and select "Global
Cumulative". |
The Battery Builder app allows you to manage your work by duplicating, deleting, or recovering your battery objects.
To duplicate a battery object, first select it in the Battery Browser panel on the left of the app. Then, under the Battery Builder tab, in the Browser section of the toolstrip, click Duplicate. This action creates an identical copy of the selected object inside your battery browser. This duplicate object is not linked to any of the parent objects of the original object.
Alternatively, in the Battery Hierarchy panel on the left of the app, right-click the object that you want to duplicate, and click Copy to browser.
To delete a battery object, first select it in the Battery Browser panel on the left of the app. Then, under the Battery Builder tab, in the Browser section of the toolstrip, click Delete. This action deletes the object from the battery browser but does not unlink that object from any parent object that is using it.
You can recover an object that you previously deleted if this object is a subcomponent of an existing parent object in your battery browser. To recover a deleted battery object that is still linked inside another parent object, first select the parent object that still contains this deleted subcomponent in the Battery Browser panel on the left of the app. Then, in the Battery Hierarchy panel, right-click the object that you want to recover, and click Copy to browser.
To export a battery object to your workspace, a MAT file, or an STL file, first select it in the Battery Browser panel on the left of the app. Then, under the Battery Builder tab, in the Export section of the toolstrip, click Export. Finally, click Export to Workspace, Export to MAT-file, or Export to STL file. You cannot export cooling plates to STL files.
When you create a library model of one of your battery objects, the Battery Builder app also automatically exports the specified battery object to a MAT file.
Note
The battery objects that you edit in the app are not automatically saved in your workspace. If you close the app, you lose the session and the objects you create.
To export the battery chart of a battery object to a file, such as a FIG, JPG, or PNG file, first select the battery object in the Battery Browser panel. Then, under the Battery Chart tab, in the Export section of the toolstrip, click Export Chart.
To create a library model from the ParallelAssembly, Module,
ModuleAssembly, or Pack
objects, under the Battery Builder tab, in the
Library section of the toolstrip, click Create
Library.
In the new window, specify the folder in which you want to save the library, the
library name, whether to use numeric values or variable names for the mask parameters
and mask initial targets, and whether to display command line output. For more
information about each of these fields, see the buildBattery documentation page.
Click the Create Library button to generate both the library model and a MAT file of your battery object in the specified folder.
Open this model to access your battery objects as Simscape blocks that you can use as a starting point 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.
