Battery Builder

Define battery system and automatically generate dynamic models

Since R2023a

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, and Pack objects. 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.

• Generate a 3-D plot of the battery object, edit the plotting options, and export the plot to a FIG 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 or a MAT 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

Import Battery Objects from Workspace or MAT File

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.

Create New Battery Object

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.

Visualize Battery Object and Modify Plotting Options

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.

Edit Battery Object

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.

Assign Child Components to Parent Components

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.

Visualize Subcomponents of Battery Object in Battery Hierarchy Panel

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.

Duplicate, Delete, or Recover Battery Object

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.

Export Battery Objects or Battery Charts

To export a battery object to your workspace or to a MAT 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 or Export to MAT-file.

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 FIG 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.

Create Library Model from Battery Object

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, and whether to use numeric values or variable names for the mask parameters and mask initial targets. 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.

Related Examples

• Get Started with Battery Builder App

Version History

Introduced in R2023a