BatteryChart

Visualize battery objects

Since R2022b

Description

Use BatteryChart to construct a battery chart for visualizing a Simscape™ Battery™ object.

Note

The BatteryChart object stores an independent copy of the object it displays and does not modify any of its properties.

The BatteryChart object displays the battery object according to the global coordinate system for batteries:

To enable these labels in your chart, use the setDefaultLabels function. For more information about setting labels, see Set Labels for BatteryChart Object.

The BatteryChart object also allows you to check the current simulation strategy and model resolution of the battery component. To visualize the simulation strategy in the chart, set the SimulationStrategyVisible property to "on" or click on the "Show/hide simulation strategy" button on the top-right corner of the chart.

For example, if you set the ModelResolution property of a ParallelAssembly object to "Lumped", the object automatically scales the electrical parameters of the cell model blocks by using the NumParallelCells property. This figure shows the simulation strategy for a lumped parallel assembly:

Only one cell model block represents all the cell components inside the orange box.

If you set the ModelResolution property of a ParallelAssembly object to "Grouped", a number of cell model blocks equal to the value of the NumParallelCells property represents each cell component instead.

Creation

Syntax

chart = BatteryChart(Name=Value)

Description

Note

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

import simscape.battery.builder.*; 

chart = BatteryChart(Name=Value) creates a BatteryChart object that visualizes the battery object specified in the Battery property, in the container specified in the Parent property. This syntax also sets further Properties using one or more name-value arguments.

Properties

Parent — Container for battery visualization

Figure object (default)

Container for the visualization of the battery, specified as a Figure object.

Battery — Battery object to visualize

Cell object | ParallelAssembly object | Module object | ModuleAssembly object | Pack object

Battery object to visualize, specified as a Cell, ParallelAssembly, Module, ModuleAssembly, or Pack object.

AxesVisible — Option to visualize axes of chart

"on" (default) | "off"

Option to visualize the axes of the chart, specified as "on" or "off".

AxesXDir — Direction of increasing values along x-axis

"normal" (default) | "reverse"

Direction of increasing values along the x-axis, specified as:

• "normal" — Values increase outward from the center of the chart.

• "reverse" — Values decrease outward from the center of the chart.

AxesYDir — Direction of increasing values along y-axis

"normal" (default) | "reverse"

Direction of increasing values along the y-axis, specified as:

• "normal" — Values increase outward from the center of the chart.

• "reverse" — Values decrease outward from the center of the chart.

AxesZDir — Direction of increasing values along z-axis

"normal" (default) | "reverse"

Direction of increasing values along the z-axis, specified as:

• "normal" — Values increase outward from the center of the chart.

• "reverse" — Values decrease outward from the center of the chart.

SimulationStrategyVisible — Option to visualize axes of chart

"on" (default) | "off"

Visibility of the simulation strategy highlighted on the chart, specified as "on" or "off".

SimulationStrategyLineColor — Color of line for simulation strategy

[0.8500 0.3250 0.0980] (default) | RGB triplet | hexadecimal color code | 'r' | 'g' | 'b' | ...

Color of the line for the simulation strategy highlighted on the chart, specified as an RGB triplet, a hexadecimal color code, a color name, or a short name.

For a custom color, specify an RGB triplet or a hexadecimal color code.

• An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1]; for example, [0.4 0.6 0.7].

• A hexadecimal color code is a character vector or a string scalar that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Thus, the color codes '#FF8800', '#ff8800', '#F80', and '#f80' are equivalent.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
'red'	'r'	[1 0 0]	'#FF0000'
'green'	'g'	[0 1 0]	'#00FF00'
'blue'	'b'	[0 0 1]	'#0000FF'
'cyan'	'c'	[0 1 1]	'#00FFFF'
'magenta'	'm'	[1 0 1]	'#FF00FF'
'yellow'	'y'	[1 1 0]	'#FFFF00'
'black'	'k'	[0 0 0]	'#000000'
'white'	'w'	[1 1 1]	'#FFFFFF'
'none'	Not applicable	Not applicable	Not applicable	No color

Here are the RGB triplets and hexadecimal color codes for the default colors.

RGB Triplet	Hexadecimal Color Code	Appearance
[0 0.4470 0.7410]	'#0072BD'
[0.8500 0.3250 0.0980]	'#D95319'
[0.9290 0.6940 0.1250]	'#EDB120'
[0.4940 0.1840 0.5560]	'#7E2F8E'
[0.4660 0.6740 0.1880]	'#77AC30'
[0.3010 0.7450 0.9330]	'#4DBEEE'
[0.6350 0.0780 0.1840]	'#A2142F'

SimulationStrategyLineStyle — Style of line for simulation strategy

":" (default) | character vector | string

Style of the line for the simulation strategy highlighted on the chart, specified as a character vector or string containing symbols.

Example: '--' is a dashed line

Line Style	Description	Resulting Line
'-'	Solid line
'--'	Dashed line
':'	Dotted line
'-.'	Dash-dotted line

SimulationStrategyLineWidth — Width of line for simulation strategy

1.5 (default) | positive value

Width of the line for the simulation strategy highlighted on the chart, specified as a positive value in points, where 1 point = 1/72 of an inch.

The line width cannot be thinner than the width of a pixel. If you set the line width to a value that is less than the width of a pixel on your system, the line displays as one pixel wide.

LightColor — Color of light

[1 1 1] (default) | RGB triplet | hexadecimal color code | 'r' | 'g' | 'b' | ...

Color of light, specified as an RGB triplet, a hexadecimal color code, a color name, or a short name. The default RGB triplet of [1 1 1] corresponds to white.

RGB triplets and hexadecimal color codes are useful for specifying custom colors.

• An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1]; for example, [0.4 0.6 0.7].

• A hexadecimal color code is a character vector or a string scalar that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Thus, the color codes '#FF8800', '#ff8800', '#F80', and '#f80' are equivalent.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code	Appearance
'red'	'r'	[1 0 0]	'#FF0000'
'green'	'g'	[0 1 0]	'#00FF00'
'blue'	'b'	[0 0 1]	'#0000FF'
'cyan'	'c'	[0 1 1]	'#00FFFF'
'magenta'	'm'	[1 0 1]	'#FF00FF'
'yellow'	'y'	[1 1 0]	'#FFFF00'
'black'	'k'	[0 0 0]	'#000000'
'white'	'w'	[1 1 1]	'#FFFFFF'

Here are the RGB triplets and hexadecimal color codes for the default colors.

RGB Triplet	Hexadecimal Color Code	Appearance
[0 0.4470 0.7410]	'#0072BD'
[0.8500 0.3250 0.0980]	'#D95319'
[0.9290 0.6940 0.1250]	'#EDB120'
[0.4940 0.1840 0.5560]	'#7E2F8E'
[0.4660 0.6740 0.1880]	'#77AC30'
[0.3010 0.7450 0.9330]	'#4DBEEE'
[0.6350 0.0780 0.1840]	'#A2142F'

Example: 'green'

LightStyle — Type of light source

'infinite' (default) | 'local'

Type of light source, specified as:

• 'infinite' — Place the light at infinity. Use the LightPosition property to specify the direction from which the light shines in parallel rays.

• 'local' — Place the light at the location specified by the LightPosition property. The light is a point source that radiates from the location in all directions.

LightPosition — Location of light source

[-1 -1 1] (default) | three-element vector of the form [x y z]

Location of light source, specified as a three-element vector of the form [x y z]. Define the vector elements in data units from the axes origin to the (x, y, z) coordinate. The actual location of the light depends on the value of the LightStyle property.

Example: [-40 -4 140]

LightVisible — Visibility of light from light source

'on' (default) | on/off logical value

Visibility of light from light source, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this property as a logical value.

Examples

Visualize Cell Object with Cylindrical Geometry

Create a cylindrical Cell object.

batteryCell = Cell(Geometry=CylindricalGeometry)

Modify the position of the cell.

batteryCell.Position = [1 1 1]

Use the BatteryChart object to visualize the Cell object.

cellChart = BatteryChart(Battery=batteryCell)

Set Labels for BatteryChart Object

To set the labels for a BatteryChart object, follow the steps in Visualize Cell Object with Cylindrical Geometry to create a BatteryChart object and then use the setDefaultLabels method.

cellChart.setDefaultLabels

Version History

Introduced in R2022b