Topology

R2026b

Create custom topology for battery cell arrangement

Since R2026b

expand all in page

Description

Use Topology to create a custom topology object that defines the geometric arrangement of battery cells. You can specify the center positions of individual cells and their grouping into parallel assemblies and series connections. You can use this object as an input to the Topology property of the ParallelAssembly and Module objects.

To specify the number of cells connected in parallel, use the NumParallelCells property. To specify the number of series assemblies, use the NumSeriesAssemblies property. To define the positions of cells, use the CellCenterPositions property.

The Topology object enables you to define arbitrary cell arrangements that go beyond the predefined topologies, such as square and hexagonal. You can specify cell center positions as either a table or a numeric array, giving you control over the placement of each cell in a 2-D Cartesian coordinate system.

Custom Cell Arrangement

The Topology object uses a table to store cell center positions. Each row in the table corresponds to a cell and contains the X and Y coordinates, a cell ID, and a parallel assembly ID. You can specify the cell positions directly or use the default positions.

The Topology object validates that cell placements do not overlap and that cells are within bounds.

Import and Export

To share and reuse custom topologies across projects, you can save a Topology object to a JSON file by using the saveToJson function and load a previously saved topology by using the importFromJson function.

Creation

Syntax

customTopology = Topology
customTopology = Topology(Name=Value)

Description

Note

To use this object, at the MATLAB® Command Window, run this command at least once each MATLAB session:

import simscape.battery.builder.*;

customTopology = Topology creates a custom topology object with default property values.

customTopology = Topology(Name=Value) also sets Properties using one or more name-value arguments. For example, Topology(NumParallelCells=4,NumSeriesAssemblies=3,BatteryCell=batteryCell(batteryCylindricalGeometry)) to create a custom topology with four cells in parallel and three series assemblies using a cylindrical cell geometry.

example

Properties

expand all

Name of the custom topology, specified as a character vector or string scalar.

Example: customTopology.Name = "MyTopology"

Center positions of all cells in the topology, specified as a table or a numeric array. The table must contain at least two columns representing the X and Y coordinates of each cell center. Optionally, the table can include columns for the cell and parallel assembly identifiers (ID).

If you specify a table with two columns, the object assigns default cell and parallel assembly IDs. If you specify a table with three columns, the object treats the third column as either cell or parallel assembly IDs depending on the variable names. If you specify a table with four columns, the object uses the columns that you specify in the XCoordVariable, YCoordVariable, CellIDVariable, and ParallelAssemblyIDVariable properties.

If you specify a numeric array, the object converts it to a table. A two-column array specifies X and Y coordinates. A three-column array adds cell IDs. A four-column array also adds parallel assembly IDs.

The object checks that cells do not overlap and are inside the bounds. Based on this check, the object sets invalid positions to NaN.

Example: customTopology.CellCenterPositions = table([0.01; 0.03; 0.05], [0.01; 0.01; 0.01], 'VariableNames',["X","Y"])

Number of parallel-connected cells in each parallel assembly, specified as a positive integer.

When you change the value of this property, the object updates the CellCenterPositions table. The object preserves existing valid cell positions and sets new cells with NaN coordinates.

Example: customTopology.NumParallelCells = 6

Number of series assemblies in the topology, specified as a positive integer between 1 and 1000.

When you change the value of this property, the object updates the CellCenterPositions table. The object preserves existing valid cell positions and sets new cells with NaN coordinates.

Example: customTopology.NumSeriesAssemblies = 4

Battery Cell object that defines the geometry of the cells in the topology, specified as a Cell object. The cell must have a valid geometry. The Topology object sets the value of the StackingAxis property of the Topology object equal to the value of the StackingAxis property of this cell object.

Example: customTopology.BatteryCell = batteryCell(batteryPouchGeometry)

Upper limit of the X-axis for cell placement, in meters, specified as a positive double. This property defines the length of the placement area along the X-axis.

Example: customTopology.XAxisLimit = 1.0

Upper limit of the Y-axis for cell placement, in meters, specified as a positive double. This property defines the length of the placement area along the Y-axis.

Example: customTopology.YAxisLimit = 1.0

Name of the X-coordinate variable in the CellCenterPositions table, specified as a character vector or string scalar. Use this property to map a column name from your input table to the X-coordinate values.

Example: customTopology.XCoordVariable = "XPosition"

Name of the Y-coordinate variable in the CellCenterPositions table, specified as a character vector or string scalar. Use this property to map a column name from your input table to the Y-coordinate values.

Example: customTopology.YCoordVariable = "YPosition"

Name of the cell ID variable in the CellCenterPositions table, specified as a character vector or string scalar. Use this property to map a column name from your input table to the cell ID.

Example: customTopology.CellIDVariable = "CellIndex"

Name of the parallel assembly ID variable in the CellCenterPositions table, specified as a character vector or string scalar. Use this property to map a column name from your input table to the parallel assembly ID.

Example: customTopology.ParallelAssemblyIDVariable = "AssemblyID"

This property is read-only.

Preferential stacking direction for the arrangement of battery cells in a 2-D Cartesian coordinate system, represented as "X" or "Y". The object derives this property from the BatteryCell property.

This property is read-only.

2-D distribution of cells in the topology, represented as a matrix of integers.

This property is read-only.

Physical size of the battery cell along the X-axis, in meters, represented as a positive double. The object uses the value of this property to validate that the cells are not out of bounds.

This property is read-only.

Physical size of the battery cell along the Y-axis, in meters, represented as a positive double. The object uses the value of this property to validate that the cells are not out of bounds.

This property is read-only.

Physical size of the battery cell along the Z-axis, in meters, returned as a positive double. The object uses the value of this property to validate that the cells are not out of bounds.

This property is read-only.

2-D vertices that define the outline shape of the battery cell, returned as a structure. The object uses the value of this property to render the cell shape in visualizations.

This property is read-only.

Geometry of the cells in the topology, returned as a CylindricalGeometry, PouchGeometry, or PrismaticGeometry object.

This property is read-only.

Number of rows in the topology layout, returned as a positive integer. The value of this property is equal to the number of rows of the Layout property.

This property is read-only.

Number of columns in the topology layout, returned as a positive integer. The value of this property is equal to the number of columns of the Layout property.

Object Functions

saveToJsonSave Topology object to JSON file
importFromJsonImport Topology object from JSON file
clearCellCenterPositionsClear X and Y coordinates of CellCenterPositions in Topology object

Examples

collapse all

Create a battery cell with cylindrical geometry.

myCell = batteryCell(batteryCylindricalGeometry);

Create a custom topology with six cells in parallel and two series assemblies.

customTopology = simscape.battery.builder.Topology(...
    Name="MyCustomLayout", ...
    NumParallelCells=6, ...
    NumSeriesAssemblies=2, ...
    BatteryCell=myCell)

Create a battery cell with cylindrical geometry.

myCell = batteryCell(batteryCylindricalGeometry);

Define the cell center positions as a table with X and Y coordinates.

positions = table( ...
    [0.02; 0.04; 0.08; 0.02; 0.04; 0.08], ...
    [0.02; 0.02; 0.02; 0.04; 0.04; 0.04], ...
    'VariableNames', ["X", "Y"]);

Create a custom topology using the specified cell positions.

customTopology = simscape.battery.builder.Topology(...
    NumParallelCells=3, ...
    NumSeriesAssemblies=2, ...
    BatteryCell=myCell, ...
    CellCenterPositions=positions)

Create a custom topology.

myCell = batteryCell(batteryPouchGeometry);
customTopology = simscape.battery.builder.Topology(...
    Name="PouchLayout", ...
    NumParallelCells=4, ...
    NumSeriesAssemblies=1, ...
    BatteryCell=myCell);

Save the topology to a JSON file.

saveToJson(customTopology,"pouchLayout.json")

Load the topology from the JSON file.

loadedTopology = simscape.battery.builder.Topology.importFromJson("pouchLayout.json")

Version History

Introduced in R2026b

See Also

Objects

Functions

Apps

Topics