Main Content

Cell

Create single electrochemical battery cell

Since R2022b

expand all in page

Description

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. The Simscape cell model block can be the Battery (Table-Based) block, the Battery Equivalent Circuit block, or a custom block with specific requirements. For more information, see the CellModelBlockPath property of the CellModelBlock object.

You can also choose to directly parameterize this object with one of the available built-in parameterizations. This pre-parameterization data allows you to set up the object to represent components by specific suppliers. The parameterizations of these batteries match the discharge curves in the manufacturer data sheets.

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.

Creation

Syntax

myBatteryCell = Cell
myBatteryCell = Cell(Name=Value)

Description

Note

To quickly create a Cell object, use the batteryCell function. By using this function, you avoid importing the namespace, using the full class name, or dealing only with name-value arguments when creating the object. (since R2024a)

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

import simscape.battery.builder.*;
All properties are exposed as name-value arguments in this object.

myBatteryCell = Cell creates a single battery cell with default property values. The object is linked to the Battery (Table-Based) block.

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

example

Properties

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.

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. You can also use your own cell component model block by specifying the CellModelBlockPath property of the CellModelBlock object accordingly.

Mass of the battery cell, specified as a simscape.Value object that represents a scalar with the specified unit of measure. 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.

Since R2023a

Capacity of the battery cell, specified as a simscape.Value object that represents a scalar with a unit of ampere-hour. The value of this property must be strictly positive. This value is not carried over into the generated battery model.

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 A*hr as its physical unit.

Since R2023a

Energy of the battery cell, specified as a simscape.Value object that represents a scalar with the specified unit of measure. The value of this property must be strictly positive. This value is not carried over into the generated battery model.

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 W*hr as its physical unit.

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.

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.

Name of the battery cell, specified as a string.

Since R2023a

Name of the supplier you want to parameterize the battery cell from, specified as a string. To apply the parameterization data to your cell, such as geometry, mass, capacity, and energy, use the applyCellDataFromPart function.

For a list of available parameterizations, see List of Pre-Parameterized Components (Simscape Electrical).

Dependencies

To enable this property, the CellModelBlockPath property of the CellModelBlock object you specified inside the CellModelOptions property of this cell must be equal to"batt_lib/Cells/Battery(Table-Based)" or "batt_lib/Cells/Battery Equivalent Circuit". In other words, the cell component model block of this object must be the Battery (Table-Based) block or the Battery Equivalent Circuit block.

Since R2023a

Part number of the pre-parameterized battery cell, specified as a string. You can only choose a part available to the supplier you specified in the ParameterizationManufacturer property. To apply the parameterization data to your cell, such as geometry, mass, capacity, and energy, use the applyCellDataFromPart function.

Note

The Cell object estimates the thermal mass of these pre-parameterized battery cells by assuming a value of 900 J/kg/K for the specific heat of the battery. The thermal mass is then equal to 900 times the weight of the battery in the manufacturer datasheet.

For a list of available parameterizations, see List of Pre-Parameterized Components (Simscape Electrical).

Dependencies

To enable this property, set ParameterizationManufacturer to any value other than "None".

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

Since R2023a

This property is read-only.

List of all parameterization part numbers available for the supplier you specified in the ParameterizationManufacturer property, returned as a vector of strings.

Since R2023a

This property is read-only.

List of all parameterization manufacturers available for the battery cell parameterization, returned as a vector of strings.

This property is read-only.

Type of battery object, returned as "Cell".

Object Functions

applyCellDataFromPartApply data from selected parameterization to Cell object

Examples

collapse all

Create a Cell object with a cylindrical geometry.

myBatteryCell = Cell(Geometry = CylindricalGeometry)

Double the radius of the cell.

myBatteryCell.Geometry.Radius = 2*myBatteryCell.Geometry.Radius

Modify the position of the cell.

myBatteryCell.Position = [1 1 1]

Visualize the cell by using a BatteryChart object.

cellChart = BatteryChart(Battery = myBatteryCell)

Create a Cell object with a cylindrical geometry.

myBatteryCell = Cell(Geometry = CylindricalGeometry);

Choose the parameterization for the cell. Set the ParameterizationManufacturer and ParameterizationPartNumber properties.

myBatteryCell.ParameterizationManufacturer = "A123";
myBatteryCell.ParameterizationPartNumber = "ALM12V7";

Apply the parameterization data by using the applyCellDataFromPart function.

myBatteryCell = myBatteryCell.applyCellDataFromPart;

Version History

Introduced in R2022b

See Also

Apps

Objects

Functions

Topics