Main Content


Create single electrochemical battery cell


Use Cell to construct a battery object that represents a single electrochemical cell. You can use this object as an input to the ParallelAssembly object.

Use the properties of this object to describe the basic characteristics of a physical battery cell and link this object to a Simscape™ cell model block for Simscape simulation. This object only supports the specification of conditional parameters. You can modify the run-time parameters for this model block, such as the battery cell resistance or the battery open-circuit voltage, after you create the model.

An electrochemical battery cell is the fundamental building block in the manufacturing 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. By using the ParallelAssembly, Module, ModuleAssembly, and Pack objects, you can connect the cell model block in parallel and/or in series and scale it up to generate larger battery system models.

Pack models are required 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.

A battery cell is an electrochemical energy storage device that provides electrical energy from stored chemical energy. Cells have three main formats:

  • Cylindrical — The electrode layers are typically rolled into a jelly roll through a winding process. The jelly roll is then secured inside a rigid cylindrical can of stainless steel or another suitable material. Cylindrical cells offer good gravimetric energy density and retention against volume expansion. To model a cylindrical battery cell, specify a CylindricalGeometry object as the Geometry property.

  • Prismatic — Rolled or stacked electrode layers pressed in metallic cubic containers. Prismatic cells are usually cooled along their height or z-axis in the direction of increasing thermal conductivity. To model a prismatic battery cell, specify a PrismaticGeometry object as the Geometry property.

  • Pouch — Stacked electrodes and separators pressed in a metallized foil pouch. Packs of pouch cells can fit the available space of a device better than the other packs but they tend to expand and delaminate. To model a pouch battery cell, specify a PouchGeometry object as the Geometry property.

To visualize a battery Cell object and the associated geometry, you must first specify a geometry object by using the Geometry property. You can then plot the Cell object by using the BatteryChart object, which displays objects in a 3-D Cartesian coordinate system based on the world coordinate system. The height of a Cell object is aligned with the z-axis of the reference frame.

The cell Geometry property is not essential for system simulation except in use cases where you must consider detailed thermal and electrical design.



import simscape.battery.builder.*; batteryCell = Cell creates a single battery cell with default property values. The object is linked to the Battery (Table-Based) block.


import simscape.battery.builder.*; batteryCell = Cell(Name=Value) creates a single battery cell and sets Properties using one or more name-value arguments. For example, batteryCell = Cell(Geometry=CylindricalGeometry,Mass=simscape.Value(1,"kg")) creates a cylindrical battery cell with a mass of 1 kg.


expand all

Set of cell geometrical parameters associated with a specific cell format, specified as a CylindricalGeometry object, a PouchGeometry object, or a PrismaticGeometry object.

Example: batteryCell.Geometry = CylindricalGeometry()

Conditional parameters of the cell component model block used for simulation, specified as a CellModelBlock object. By default, the cell component model block is the Battery (Table-Based) block.

Mass of the battery cell, specified as a simscape.Value object that represents a scalar with a unit of length. The value of this property must be strictly positive and lower than 100 kg.

If you set this property directly with a positive scalar value instead of using a simscape.Value object, the object converts the value to a simscape.Value object with kg as its physical unit.

Example: batteryCell.Mass = simscape.Value(0.5,"kg")

Preferential stacking direction for the arrangement of battery cells in a 2-D Cartesian coordinate system, specified as "X" or "Y".

This figure shows the global coordinate system for batteries.

Example: batteryCell.StackingAxis = "Y"

Location of the battery cell in a 3-D Cartesian coordinate system, specified as a vector of real and finite entries. When you link the Cell object to a parent battery object, such as a ParallelAssembly object, the parent object overwrites this position.

Example: batteryCell.Position = [0 0 0]

Name of the battery cell, specified as a string.

Example: batteryCell.Name = "Cell2"

This property is read-only.

Volume of the battery, returned as a simscape.Value object with a unit of volume.

This property is read-only.

Cumulative mass of the battery, returned as a simscape.Value object with a unit of mass.

This property is read-only.

Number of cell model blocks used for simulation, returned as a positive scalar.

This property is read-only.

Geometrical format of the battery cell, returned as "Pouch", "Prismatic", or "Cylindrical". This object derives this property value from the Geometry property.

This property is read-only.

Option to use or omit a lumped thermal mass model during the simulation, returned as "omit" or "model".

This property is read-only.

Type of battery object, returned as "Cell".


collapse all

Create a Cell object with a cylindrical geometry.

batteryCell = Cell(Geometry = CylindricalGeometry())

Double the radius of the cell.

batteryCell.Geometry.Radius = 2*batteryCell.Geometry.Radius 

Modify the position of the cell.

batteryCell.Position = [1 1 1]

Visualize the cell by using a BatteryChart object.

cellChart = BatteryChart(Battery = batteryCell)

Version History

Introduced in R2022b