Main Content

BatterySimulationChart

Dynamically visualize battery objects

Since R2023b

Description

Use BatterySimulationChart to construct a dynamic version of the BatteryChart object. Use the dynamic version of the battery chart to visualize the time-series data of a dynamic variable that you store inside a BatterySimulationLog object.

Use this object with a BatterySimulationLog object to visualize how the relevant states of a specific battery block are impacted by the electro-thermal design and battery architecture, including cell temperature, current, or state of charge.

The BatterySimulationChart object scales the variable values on a colormap by using the maximum and minimum values of that variable over the course of the entire simulation. The software then uses this colormap to update the colors of a BatteryChart object respecting the battery model resolution and the location of each cell within the battery design. The software overlays the colormap with a 3-D battery representation for every cell within that battery at every desired timestep.

If you set the ModelResolution property of the battery to "Lumped", the colors of all the battery cells in the visualization are the same. Conversely, if you set the ModelResolution property of the battery to "Detailed", the colors of each battery cell in the visualization differ depending on parameters and the dynamic simulation settings, including different thermal boundary conditions.

Creation

Description

Note

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

import simscape.battery.builder.*; 

example

chart = BatterySimulationChart(Name=Value) creates a BatterySimulationChart object that displays the time-series data from the BatterySimulationLog property in the container you specify in the Parent property. This syntax also sets further Properties using one or more name-value arguments.

Properties

expand all

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

Simulation data to visualize on the battery chart, specified as a BatterySimulationLog object.

Current simulation time that the battery chart displays, specified as a positive scalar.

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

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

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

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

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

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

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

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

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

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

Option to visualize the simulation strategy on the chart, specified as "on" or "off".

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 NameShort NameRGB TripletHexadecimal Color CodeAppearance
'red''r'[1 0 0]'#FF0000'

Sample of the color red

'green''g'[0 1 0]'#00FF00'

Sample of the color green

'blue''b'[0 0 1]'#0000FF'

Sample of the color blue

'cyan' 'c'[0 1 1]'#00FFFF'

Sample of the color cyan

'magenta''m'[1 0 1]'#FF00FF'

Sample of the color magenta

'yellow''y'[1 1 0]'#FFFF00'

Sample of the color yellow

'black''k'[0 0 0]'#000000'

Sample of the color black

'white''w'[1 1 1]'#FFFFFF'

Sample of the color white

'none'Not applicableNot applicableNot applicableNo color

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

RGB TripletHexadecimal Color CodeAppearance
[0 0.4470 0.7410]'#0072BD'

Sample of RGB triplet [0 0.4470 0.7410], which appears as dark blue

[0.8500 0.3250 0.0980]'#D95319'

Sample of RGB triplet [0.8500 0.3250 0.0980], which appears as dark orange

[0.9290 0.6940 0.1250]'#EDB120'

Sample of RGB triplet [0.9290 0.6940 0.1250], which appears as dark yellow

[0.4940 0.1840 0.5560]'#7E2F8E'

Sample of RGB triplet [0.4940 0.1840 0.5560], which appears as dark purple

[0.4660 0.6740 0.1880]'#77AC30'

Sample of RGB triplet [0.4660 0.6740 0.1880], which appears as medium green

[0.3010 0.7450 0.9330]'#4DBEEE'

Sample of RGB triplet [0.3010 0.7450 0.9330], which appears as light blue

[0.6350 0.0780 0.1840]'#A2142F'

Sample of RGB triplet [0.6350 0.0780 0.1840], which appears as dark red

Line style for the simulation strategy display, specified as a character vector or string scalar containing symbols.

Example: '--' is a dashed line

Line StyleDescriptionResulting Line
'-'Solid line

Sample of solid line

'--'Dashed line

Sample of dashed line

':'Dotted line

Sample of dotted line

'-.'Dash-dotted line

Sample of dash-dotted line, with alternating dashes and dots

Line width for the simulation strategy display, specified as a positive scalar in points, where one point is 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.

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 NameShort NameRGB TripletHexadecimal Color CodeAppearance
'red''r'[1 0 0]'#FF0000'

Sample of the color red

'green''g'[0 1 0]'#00FF00'

Sample of the color green

'blue''b'[0 0 1]'#0000FF'

Sample of the color blue

'cyan' 'c'[0 1 1]'#00FFFF'

Sample of the color cyan

'magenta''m'[1 0 1]'#FF00FF'

Sample of the color magenta

'yellow''y'[1 1 0]'#FFFF00'

Sample of the color yellow

'black''k'[0 0 0]'#000000'

Sample of the color black

'white''w'[1 1 1]'#FFFFFF'

Sample of the color white

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

RGB TripletHexadecimal Color CodeAppearance
[0 0.4470 0.7410]'#0072BD'

Sample of RGB triplet [0 0.4470 0.7410], which appears as dark blue

[0.8500 0.3250 0.0980]'#D95319'

Sample of RGB triplet [0.8500 0.3250 0.0980], which appears as dark orange

[0.9290 0.6940 0.1250]'#EDB120'

Sample of RGB triplet [0.9290 0.6940 0.1250], which appears as dark yellow

[0.4940 0.1840 0.5560]'#7E2F8E'

Sample of RGB triplet [0.4940 0.1840 0.5560], which appears as dark purple

[0.4660 0.6740 0.1880]'#77AC30'

Sample of RGB triplet [0.4660 0.6740 0.1880], which appears as medium green

[0.3010 0.7450 0.9330]'#4DBEEE'

Sample of RGB triplet [0.3010 0.7450 0.9330], which appears as light blue

[0.6350 0.0780 0.1840]'#A2142F'

Sample of RGB triplet [0.6350 0.0780 0.1840], which appears as dark red

Example: 'green'

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.

Location of the 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]

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

collapse all

Create the Simscape Battery block.

import simscape.battery.builder.*
batterycell = Cell(Geometry = CylindricalGeometry);
batterycell.CellModelOptions.BlockParameters.thermal_port = "model";
batteryparallelAssembly = ParallelAssembly(Cell=batterycell,...
    NumParallelCells=15,Rows=3);
batterymodule = Module(ParallelAssembly = batteryparallelAssembly, ...
    ModelResolution = "Detailed", ...
    AmbientThermalPath="CellBasedThermalResistance");
libraryname = "Batteries";
buildBattery(batterymodule,"LibraryName",libraryname);

Create and open the Simulink battery model.

modelname = "batterymodel";
open_system(new_system(modelname));

Name and add the required blocks to the mode.

batteryBlockPath           = strcat(modelname,"/","Module1");
electricalRefBlockPath     = strcat(modelname,"/","ElectricalReference");
solverConfigBlockPath      = strcat(modelname,"/","Solver");
currentSourceBlockPath     = strcat(modelname,"/","Current Source");
temperatureSourceBlockPath = strcat(modelname,"/","Temperature Source");

% Add blocks to the model
add_block( strcat(libraryname,"_lib/", batterymodule.Name), batteryBlockPath,'position', [150,100,300,250]);
add_block( "fl_lib/Electrical/Electrical Elements/Electrical Reference",electricalRefBlockPath,'position', [215,320,235,340], 'orientation', "down");
add_block( "nesl_utility/Solver Configuration",solverConfigBlockPath,'position', [-80,280,-30,320]);
add_block( "fl_lib/Electrical/Electrical Sources/DC Current Source",currentSourceBlockPath,'position', [-30,150,0,200],'orientation',"down" ,'i0', num2str(-500));
add_block( "fl_lib/Thermal/Thermal Sources/Temperature Source",temperatureSourceBlockPath,'position', [80,160,120,200],'orientation',"left");

Get the handles to the block ports and connect all blocks.

batteryBlockPortHandles           = get_param(batteryBlockPath,'PortHandles');
electricalRefBlockPortHandles     = get_param(electricalRefBlockPath,'PortHandles');
solverConfigBlockPortHandles      = get_param(solverConfigBlockPath,'PortHandles');
currentSourceBlockPortHandles     = get_param(currentSourceBlockPath,'PortHandles');
temperatureSourceBlockPortHandles = get_param(temperatureSourceBlockPath,'PortHandles');

% Connect all blocks
add_line(modelname, batteryBlockPortHandles.RConn, currentSourceBlockPortHandles.RConn, autorouting='smart');
add_line(modelname, batteryBlockPortHandles.LConn(2), currentSourceBlockPortHandles.LConn, autorouting='smart');
add_line(modelname, batteryBlockPortHandles.RConn, electricalRefBlockPortHandles.LConn, autorouting='smart');
add_line(modelname, batteryBlockPortHandles.RConn, solverConfigBlockPortHandles.RConn, autorouting='smart');
add_line(modelname, batteryBlockPortHandles.LConn(1), temperatureSourceBlockPortHandles.LConn, autorouting='smart');

Enable the logged simulation data for your model.

set_param(modelname,"SimscapeLogType",'all')
set_param(batteryBlockPath, "AmbientResistance", strcat("[",num2str((60-1).*rand(15,1)' + 1),"]"));

Simulate the model.

out = sim(modelname,'StartTime','0','StopTime','160');

Create a BatterySimulationLog object.

batterySimLog = BatterySimulationLog( batterymodule,  out.simlog.Module1);

Select the variable for visualization, then display the object.

batterySimLog.SelectedVariable = "temperatureCell";
disp(batterySimLog)
  BatterySimulationLog with properties:

                 Battery: [1×1 simscape.battery.builder.Module]
                  SimLog: [1×1 simscape.logging.Node]
        SelectedVariable: "temperatureCell"
    SelectedVariableUnit: "K"
          ModelVariables: ["vCell"    "temperatureCell"    "iCell"    "numCyclesCell"    "socCell"]

Visualize the selected variable using the BatterySimulationChart object.

f = uifigure("Color","w");
g = uigridlayout(f, [1,1]);
moduleChart = BatterySimulationChart(Parent = g, ...
    BatterySimulationLog = batterySimLog);
moduleChartColorBar = colorbar(moduleChart);
ylabel( moduleChartColorBar, strcat(batterySimLog.SelectedVariable, " (", batterySimLog.SelectedVariableUnit,")") );

Version History

Introduced in R2023b