Get Started with Battery Builder App

This example shows how to use the Battery Builder app to interactively create a battery pack with thermal effects and build a Simscape™ model that you can use as a starting point for your simulations.

Using this app, you can interactively import existing battery objects or build them from scratch, explore and edit properties, and view the battery hierarchy and 3-D visualization. You can then build the Simscape system model of your objects and use it as a reference in your simulations. You can also export the objects in your workspace.

Hierarchy of Battery Pack

To create the system model of a battery pack, you must first create the Cell, ParallelAssembly, Module, and ModuleAssembly objects that comprise the battery pack. After you create your battery pack according to your specifications, you can build it to generate a library in your working folder that contains a system model block of this battery pack. You can use this system model as a reference in your simulations.

This figure shows the hierarchy of a battery pack object in a bottom-up view:

A battery pack comprises multiple module assemblies. These module assemblies, in turn, comprise a number of battery modules connected electrically in series or in parallel. The battery modules are made of multiple parallel assemblies which, in turn, comprise a number of battery cells connected electrically in parallel under a specific topological configuration or geometrical arrangement.

Open Battery Builder App

Open the Battery Builder app. On the Apps tab, under Simscape, click the Battery Builder icon. Alternatively, you can open the app from the command line:

batteryBuilder;

The app automatically loads some example objects that you can explore to immediately gain some visual insight into the app functionalities. You can view the properties of these objects but you cannot modify them.

The Battery Builder app comprises six main components divided into four panels and two tabs.

• Battery Browser — Battery objects in the current active session of the app. This panels displays all the objects that you create or import inside the app. To edit the properties of an object or to visualize its hierarchy or 3-D plot, you must first select it from this panel.

• Battery Hierarchy — Hierarchy of the selected battery object. This panel displays all the subcomponents of the object. Selecting any object in this panel shows its 3-D chart and properties in the respective panels.

• Selected Battery — 3-D visualization of the selected battery object. To modify the visualization settings of this panel, use the options in the Battery Chart tab.

• Battery Properties — Properties of the selected battery object. This panel displays all the read-only and editable properties of the object. Each battery object comprises its own properties.

• Battery Builder — Tab that comprises the main functionalities of the app. Use the buttons in this tab to import, create, delete, duplicate, export, and build battery objects.

• Battery Chart — Tab that comprises the display options of the 3-D battery chart. In this tab, you can edit properties such as 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.

Create Cell

To create the Pack object, first create a Cell object with the pouch geometry. An electrochemical battery cell is the fundamental building block in the manufacturing process of larger battery systems. To obtain the required energy and voltage levels, multiple battery cells are typically connected electrically in parallel and/or in series. To meet the battery packaging and space requirements, you can arrange the battery cells in many different topologies or geometrical configurations.

To mirror real-world behavior, the Simscape Battery™ Cell object is the foundational element for the creation of a battery pack system model. To create a Cell object, under the Battery Builder tab, in the Create section of the toolstrip, select Cell.

The Battery Browser panel on the left now contains the Cell object.

To get started, you must first define a pouch geometry for this cell:

1. Select the NewCell object in the left Battery Browser panel of the app. Now the Properties panel on the right of the app displays all its properties.

2. In the right Cell Properties panel, in the Geometry section, set the Geometry property to Pouch.

With this action, you create a PouchGeometry object and link it to your Cell object. The Geometry section of the Cell Properties panel now displays properties related to the pouch geometry.

For this example, you create a pouch cell with a height of 0.1 m, a length of 0.3 m, and opposed tabs. In the Cell Properties panel, under the Geometry section, edit the Length, Height, and TabLocation properties accordingly.

You can also simulate the thermal effects of the battery cell by using a simple 1-D model. In the Cell Properties panel, expand the Cell Model Options section. The properties in this section depend on the cell block that you specify in the CellModelBlockPath property. The Battery Builder app links the battery Cell object you are defining now to this Simscape cell model block for Simscape simulation. The Simscape cell model block can be the Battery (Table-Based) block, the Battery Equivalent Circuit block, or a custom block with specific requirements.

By default, a Cell object uses the Battery (Table-Based) block as Simscape cell model block. The properties in the Cell Model Options section then define the conditional parameters that control the visibility of the component members of the cell block, such as parameters, variables, nodes, inputs, and outputs. For more information on these conditional parameters for the default Battery (Table-Based) block, see BlockParameters.

To simulate the thermal effects of the battery cell, in the Cell Properties panel, under the Cell Model Options section, set the thermal_port property to model and the T_dependence property to yes. The thermal_port property defines the visibility of the thermal port of the associated cell model block. The T_dependence property defines whether to tabulate the battery parameters over temperature. You can define the thermal boundary conditions for battery objects only if you define a thermal model at the cell level.

Finally, to apply your changes, click Apply.

The Selected Battery panel now shows a 3-D visualization of your pouch cell.

Create Parallel Assembly

A battery parallel assembly comprises multiple battery cells connected electrically in parallel under a specific topological configuration or geometrical arrangement.

To create the ParallelAssembly object, under the Battery Builder tab, in the Create section of the toolstrip, select Parallel Assembly.

You must now link the Cell object to this parallel assembly. In this example, the parallel assembly comprises three pouch cells.

1. In the Parallel Assembly Properties panel, under the ParallelAssembly Properties section, click the Select... button of the Cell property.

2. In the new window that appears, select the NewCell object and click OK.

3. In the Parallel Assembly Properties panel, under the Parallel Assembly Properties section, set the NumParallelCells property to 3.

4. Click Apply to apply your changes.

The NewCell object is now a subcomponent (or child component) of this parallel assembly. After you apply your changes, you can view the hierarchy of the ParallelAssembly object in the Battery Hierarchy panel.

The Selected Battery panel now shows a 3-D visualization of your parallel assembly.

Create Module

A battery module comprises multiple parallel assemblies connected in series.

To create the Module object, under the Battery Builder tab, in the Create section of the toolstrip, select Module.

You must now link the ParallelAssembly object to this module:

1. In the Module Properties panel, under the Module Properties section, click the Select... button of the ParallelAssembly property.

2. In the new window that appears, select the NewParallelAssembly object and click OK.

The NewParallelAssembly object is now a subcomponent (or child component) of this module. After you apply your changes, you can view the hierarchy of the Module object in the Battery Hierarchy panel.

In this example, the module comprises 14 parallel assemblies with a gap of 0.005 m between each assembly. In the Module Properties panel, under the Module Properties section, set the NumSeriesAssemblies property to 14 and the InterParallelAssemblyGap property to 0.005.

Finally, to apply your changes, click Apply.

The Selected Battery panel now shows a 3-D visualization of your module.

Create Module Assembly

A battery module assembly comprises multiple battery modules connected in series or in parallel. In this example, the battery module assembly comprises two identical modules with a gap of 0.1 m between each module. By default, the ModuleAssembly object electrically connects the modules in series

To create the ModuleAssembly object, under the Battery Builder tab, in the Create section of the toolstrip, select Module Assembly.

You must now link the Module object to this module assembly:

1. In the Module Assembly Properties panel, under the Module Assembly Properties section, click the Select... button of the Module property.

2. In the new window that appears, create a module assembly that comprises two identical modules by selecting the NewModule object and clicking Add twice.

Two NewModule objects are now subcomponents of this module assembly. After you apply your changes, you can view the hierarchy of the ModuleAssembly object in the Battery Hierarchy panel.

Now specify the gap between modules. In the Module Assembly Properties panel, under the Module Assembly Properties section, set the InterModuleGap property to 0.1.

Finally, to apply your changes, click Apply.

The Selected Battery panel now shows a 3-D visualization of your module assembly.

Create Pack

You now have all the foundational elements required to create your battery pack. A battery pack comprises multiple module assemblies connected in series or in parallel. In this example, you create a battery pack of five identical module assemblies with a gap of 0.01 m between each module assembly.

To create the Pack object, under the Battery Builder tab, in the Create section of the toolstrip, select Pack.

You must now link the ModuleAssembly object to this pack:

1. In the Pack Properties panel, under the Pack Properties section, click the Select... button of the ModuleAssembly property.

2. In the new window that appears, create a pack that comprises five identical module assemblies by selecting the NewModuleAssembly object and clicking Add five times.

Five NewModuleAssembly objects are now subcomponents of this pack. After you apply your changes, you can view the hierarchy of the Pack object in the Battery Hierarchy panel.

Now specify the gap between module assemblies. In the Pack Properties panel, under the Module Assembly Properties section, set the InterModuleAssemblyGap property to 0.01.

Finally, to apply your changes, click Apply.

The Selected Battery panel now shows a 3-D visualization of your pack.

Define Thermal Boundary Conditions

For your Pack object, you can define the thermal paths to the ambient air, the coolant, and the location of the cooling plate by specifying the AmbientThermalPath, CoolantThermalPath, and CoolingPlate properties, respectively.

Define Ambient Thermal Path

To define a thermal path to ambient air, in the Pack Properties panel, under the Thermal Model Options section, set the AmbientThermalPath property to CellBasedThermalResistance. The value you set automatically propagates to all the subcomponent battery objects inside this Pack object. However, this change does not propagate to the other battery objects in your Battery Builder app session.

This command adds and connects a Thermal Resistor block to every thermal port in a cell model. The other thermal ports from all the resistors connect to a single thermal node. You can then connect this thermal node to a constant temperature source or other blocks in the Simscape libraries.

Define Coolant Thermal Path

To define a thermal path from cells to the coolant, in the Pack Properties panel, under the Thermal Model Options section, set the CoolantThermalPath property to CellBasedThermalResistance. The value you set automatically propagates to all the subcomponent battery objects inside this Pack object. However, this change does not propagate to the other battery objects in your Battery Builder app session.

This command adds and connects one Thermal Resistor block to every thermal port in a cell model. The other thermal ports from all the resistors connect to a single thermal node. You can then connect this thermal node to a constant temperature source or other blocks in the Simscape libraries. You can individually parameterize each thermal resistance with a different value. You can use the Thermal Resistor block to model the conduction resistance relative to the cell, the thermal interface materials, and other materials along the path to the coolant.

If you define a cooling system, such as a cooling plate for the battery module, the software connects the other thermal port of the Thermal Resistor block to an array of thermal nodes connector.

Define Cooling Plate Location

To define the location of the cooling plate on your battery pack, in the Pack Properties panel, under the Thermal Model Options section, set the CoolingPlate property to Top or Bottom. Alternatively, specify both options at the same time. You can also specify which cooling plate block to assign to the Pack object at the boundary that the CoolingPlate property defines. Set the CoolingPlateBlockPath property to batt_lib/Thermal/Edge Cooling to automatically assign the Edge Cooling block when you build the Simscape model.

The value of this property automatically propagates to all the subcomponent battery objects inside this Pack object. However, this change does not propagate to the other battery objects in your Battery Builder app session.

This command connects each thermal node of each cell model in your battery pack to a corresponding element inside an array of thermal nodes connector.

View Model Resolution of Battery Pack

To obtain the number of Simscape Battery (Table-Based) blocks that the pack simulation uses, in the Pack Properties panel, under the Read-Only Properties section, view the NumModels property.

To view the model resolution of the pack, under the Battery Chart tab, in the Simulation Strategy section of the toolstrip, check the Visible box.

The 3-D plot in the Selected Battery panel now shows the simulation strategy for the Pack object. The pack uses one electrical model for each of its modules.

Build Simscape Model for Battery Pack Object

After you create your battery objects, you need to convert them into Simscape models to use them in block diagrams. You can then use these models as a reference 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 create a library that contains the Simscape Battery model of the Pack object you create in this example, in the Battery Browser panel, select the NewPack object. Then, under the Battery Builder tab, in the Library section of the toolstrip, select Create Library.

In the new window, specify the folder in which you want to save the library, the library name, and whether you want to generate scripts with all the run-time parameters and initial conditions required for simulation.

Click Create Library to generate the library model of your battery object in the specified folder. Open this model to access your battery objects as Simscape blocks.

To programmatically build a more detailed model of a battery pack, see Build Detailed Model of Battery Pack from Pouch Cells.