CellModelBlock

Set of conditional parameters for Cell object

Since R2022b

Description

Use CellModelBlock to construct the CellModelOptions property of a Cell object. This property contains the conditional parameters of the block that you specify in the CellModelBlockPath property.

By default, the CellModelBlockPath property uses the Battery Equivalent Circuit block, but you can also use the Battery (Table-Based) block or specify your own custom block. For more information, see the CellModelBlockPath property.

Note

A generated battery block always uses the default values of the parameters in the battery cell blocks that you specify in the CellModelBlockPath property of your battery object, regardless of how you modified them. The only parameters of the cell block that you can modify are the conditional parameters listed in the BlockParameters property.

Creation

Syntax

cellModelOpt = CellModelBlock

Description

Note

To quickly create a CellModelBlock object, use the batteryCellModelBlock 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 create a CellModelBlock object without using the batteryCellModelBlock function, at the MATLAB^® Command Window, you must run this command at least once each MATLAB session:

import simscape.battery.builder.*; 

All properties are exposed as name-value arguments in this object.

cellModelOpt = CellModelBlock sets default model options for the Cell object. To modify these options for your application, use dot notation.

Properties

CellModelBlockPath — Library path to Simscape battery cell block

"batt_lib/Cells/Battery Equivalent Circuit" (default) | "batt_lib/Cells/Battery(Table-Based)" | string

Library path to a Simscape battery cell block, specified as a string. The default component model block is the Battery Equivalent Circuit block.

You can also use the Battery (Table-Based) or specify your own custom cell block, as long as your custom block meets all of these requirements:

• The custom block must provide exactly two electrical conserving ports named n and p.

• All variables must be scalar-valued.

• The custom block cannot contain a variable or intermediate variable called power_dissipated.

You can connect the custom block to any number of thermal nodes. The software connects all nodes in parallel.

If you specify your own custom block, the fields of the BlockParameters structure depend on the parameters that you specified inside your custom block. To modify these options for your application, use dot notation.

For more information on how to build a battery model from a custom cell component, see the Build Battery Model from Custom Cell Component example. (since R2026a)

Input and Output Ports of Custom Blocks

Generated battery blocks that use a custom block as cell model block expose the same input ports (since R2026a) and output ports (since R2024b) of the custom block. Inputs and outputs are concatenated horizontally and they are physical signals for Parallel Assembly and Module generated blocks and Simulink^® signals for Module Assembly and Pack generated blocks.

Note

Generated battery blocks do not expose untyped inputs. For more information about component inputs, see inputs.

For example, create a custom cell block with a voltage output port:

% ...
    outputs   
        voltageCell; %voltage
    end

    equations
        voltageCell == [ParallelAssembly1(:).voltageCell]';
    end
% ...

Use this custom cell block to create the Cell, ParallelAssembly, Module, and ModuleAssembly objects and generate the ModuleAssembly block by using the buildBattery function. Then, the generated ModuleAssembly block exposes the voltage port:

BlockParameters — Conditional parameters of cell block

structure (default)

Conditional parameters of the cell block that you specify in the CellModelBlockPath property. These conditional parameters control the visibility of the component members of the cell block, such as parameters, variables, nodes, inputs, and outputs.

Note

This property does not include the run-time parameters of the specified cell block.

These are the conditional parameters for the Battery Equivalent Circuit block:

• CurrentDependence — Current dependence for resistance parameters

• SelfDischargeResistor — Self discharge

• RCPairs — Parallel resistor capacitor pairs

• CyclingAgingMethod — Cycling aging model

• CalendarAgeResistance — Resistance calendar aging

• CalendarAgeCapacity — Capacity calendar aging

• ThermalModel — Thermal model

• HysteresisModel — Hysteresis model

• ReversibleHeatModel — Reversible heat model

• CalendarAgingMethod — Modeling option

• StorageVariable — Storage condition

These are the conditional parameters for the Battery (Table-Based) block:

• T_dependence — Tabulate parameters over temperature

• thermal_port — Thermal port

• prm_age_OCV — Storage condition

• prm_age_capacity — Capacity calendar aging

• prm_age_resistance — Internal resistance calendar aging

• prm_age_modeling — Modeling option

• prm_dyn — Charge dynamics

• prm_dir — Current directionality

• prm_fade — Fade characteristic

• prm_leak — Self-discharge

If you specify a custom block in the CellModelBlockPath property, these fields might differ.

Example: cellModelOpt.BlockParameters.thermal_port = "model"

BlockExposesThermalNodes — Flag that states whether cell block exposes at least one thermal node

Read-only: true | false

Since R2024a

This property is read-only.

Flag that states whether the cell block exposes at least one thermal node, returned as true or false. To change conditionally exposed thermal nodes, update the relevant properties inside the BlockParameters property.

Examples

Set Default CellModelOptions Property

Create a default CellModelBlock option set.

import simscape.battery.builder.*; 
cellModelOpt = CellModelBlock

  CellModelBlock with properties:

    CellModelBlockPath: "batt_lib/Cells/Battery Equivalent Circuit"
       BlockParameters: [1×1 struct]

Show all properties

Show the BlockParameters property.

cellModelOpt.BlockParameters

struct with fields:
        CurrentDependence: Disabled
    SelfDischargeResistor: Disabled
                  RCPairs: noDynamics
       CyclingAgingMethod: disabled
    CalendarAgeResistance: Disabled
      CalendarAgeCapacity: Disabled
             ThermalModel: ConstantTemperature
          HysteresisModel: none
      ReversibleHeatModel: Disabled
      CalendarAgingMethod: equation
          StorageVariable: OCV

Specify options using dot notation.

cellModelOpt.BlockParameters.ThermalModel = "LumpedThermalMass";

Any property values you do not specify retain their default values.

Modify BlockParameters Property of a Cell Object

Create a default Cell object.

import simscape.battery.builder.*;
batteryCell = Cell

  batteryCell = 

    Cell with properties:

            Geometry: "None"
    CellModelOptions: [1×1 simscape.battery.builder.CellModelBlock]
                Mass: 0.1000 (kg)
            Capacity: 5 (A*hr)
              Energy: 50 (W*hr)

Show all properties

Show the BlockParameters property of the CellModelOptions object inside the Cell object.

batteryCell.CellModelOptions.BlockParameters

   struct with fields:
        
    CurrentDependence: Disabled
    SelfDischargeResistor: Disabled
                  RCPairs: noDynamics
       CyclingAgingMethod: disabled
    CalendarAgeResistance: Disabled
      CalendarAgeCapacity: Disabled
             ThermalModel: ConstantTemperature
          HysteresisModel: none
      ReversibleHeatModel: Disabled
      CalendarAgingMethod: equation
          StorageVariable: OCV

Specify options using dot notation.

batteryCell.CellModelOptions.BlockParameters.ThermalModel = "LumpedThermalMass";

Version History

Introduced in R2022b

R2026a: The default value of the CellModelBlockPath property has changed

The default value of the CellModelBlockPath property is now "batt_lib/Cells/Battery Equivalent Circuit".

As a result of this change, if you create a battery object without modifying this property, the Simscape cell model block of the object is the Battery Equivalent Circuit block. The generated battery block associated with this object then exposes the parameters for the Battery Equivalent Circuit block.

R2026a: Expose the cell-level input ports in parent battery blocks

The input ports of the cell model block that you specify in the CellModelBlockPath property are also exposed in the battery blocks that you generate by using this cell model block.

The generated battery blocks do not expose untyped inputs.

R2024b: Expose the cell-level output ports in parent battery blocks

The output ports of the cell model block that you specify in the CellModelBlockPath property are also exposed in the battery blocks that you generate by using this cell model block.

R2023b: Specify the Battery Equivalent Circuit block for the CellModelBlockPath property

The CellModelBlockPath property now supports the Battery Equivalent Circuit block.

R2023a: Specify a custom block for the CellModelBlockPath property

The CellModelBlockPath property now supports custom blocks. To use your own custom block, set the CellModelBlockPath property to the library path of your custom block.

To use a custom block, it must meet all these requirements:

• The custom block must provide exactly two electrical conserving ports named n and p.

• All variables must be scalar-valued.

• The custom block cannot contain a variable or intermediate variable called power_dissipated.