ecm

Create equivalent circuit model object for estimating battery parameter from impedance data

Since R2025a

Description

Use ecm to create an equivalent circuit model ECM object. Use this object to perform battery parameter estimation from battery time-based impedance data.

You can obtain the impedance data at different operating conditions by using multiple techniques, such as hybrid pulse power characterization (HPPC). To select the topology of the equivalent circuit model, specify the amount of resistor-capacitor parallel pairs by using the NumRCPairs property.

This table shows the equivalent circuit model topology depending on the value of the NumRCPairs property.

Circuit Name	NumRCPairs Property Value	Topology and Parameters
Single resistor	0
Thevenin ECM or 1-RC branch ECM	1
2-RC branch ECM	2
3-RC branch ECM	3

To estimate model parameters, use this object and the HPPCTest object as inputs to the fitECM function. This figure shows the typical workflow to estimate the parameters of an equivalent circuit model from HPPC test data:

Creation

Syntax

equivalentCircuitModel = ecm

equivalentCircuitModel = ecm(NumRCPairs)

equivalentCircuitModel = ecm(NumRCPairs,PropertyName=Value)

Description

equivalentCircuitModel = ecm creates a default ECM object with default property values.

equivalentCircuitModel = ecm(NumRCPairs) creates an ECM object with an amount of resistor-capacitor parallel pairs equal to NumRCPairs.

equivalentCircuitModel = ecm(NumRCPairs,PropertyName=Value) specifies the equivalentCircuitModel properties using one or more name-value arguments.

Input Arguments

NumRCPairs — Number of resistor-capacitor pairs

2 (default) | scalar in the range [0,3]

Number of resistor-capacitor parallel pairs in the equivalent circuit model, specified as a scalar in the range [0,3].

This argument sets the NumRCPairs property.

Data Types: double

Properties

NumRCPairs — Number of resistor-capacitor pairs

2 (default) | scalar in the range [0,3]

Number of resistor-capacitor parallel pairs in the equivalent circuit model, specified as a scalar in the range [0,3].

Data Types: double

ParameterValues — Parameter values used for time-based simulation

[0.0250 0.0250 10 0.0125 100] (default) | vector of nonnegative elements

Parameter values used for time-based simulation when you use the simulateCurrentPulse function, specified as a vector of nonnegative elements.

Data Types: double

DCIRTimeFrames — Time frames for calculation of direct current internal resistance

[2 5 10 30 60] (default) | vector of positive elements

Time frames, specified as a vector, for the calculation of the direct current internal resistance (DCIR) when you specify the value of the NumRCPairs to 0 or 1. If the pulse duration is less than any of the time frames specified in this property, the fitting method ignores these time frames in the calculation.

Data Types: double

SOCBreakpoints — State-of-charge breakpoints for generating model open-circuit voltage parameters

simscape.Value([0, .1, .2, .3, .4, .5, .6, .7, .8, .9, 1],"1") (default) | vector of elements in the range [0,1] | simscape.Value object

State-of-charge breakpoints used for generating the model parameters for the open-circuit voltage parameters, specified as a vector or a simscape.Value object that represents a vector of elements in the range [0,1].

If you set this property directly with vector value instead of using a simscape.Value object, the object converts the value to a simscape.Value object.

Data Types: double

ResistanceSOCBreakpoints — State-of-charge breakpoints for generating model resistance parameters

simscape.Value([0, .1, .2, .3, .4, .5, .6, .7, .8, .9, 1],"1") (default) | vector of elements in the range [0,1] | simscape.Value object

State-of-charge breakpoints used for generating the model parameters for the resistance parameters, specified as a vector or a simscape.Value object that represents a vector of elements in the range [0,1].

If you set this property directly with vector value instead of using a simscape.Value object, the object converts the value to a simscape.Value object.

Data Types: double

ResistanceTemperatureBreakpoints — Temperature breakpoints for generating model resistance parameters

simscape.Value([278, 293, 313],"K") (default) | vector | simscape.Value object

Temperature breakpoints used for generating the model parameters for the resistance parameters, specified as a vector or a simscape.Value object that represents a vector of positive elements with a unit of Kelvin.

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

Data Types: double

TemperatureBreakpoints — Temperature breakpoints for generating model open-circuit voltage parameters

simscape.Value([278, 293, 313],"K") (default) | vector | simscape.Value object

Temperature breakpoints used for generating the model parameters for the open-circuit voltage parameters, specified as a vector or a simscape.Value object that represents a vector of positive elements with a unit of Kelvin.

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

Data Types: double

ResistanceCurrentBreakpoints — Current breakpoints for generating model resistance parameters

simscape.Value(1,"A") (default) | vector | simscape.Value object

Current breakpoints used for generating the model parameters for the resistance parameters, specified as a vector or a simscape.Value object that represents a vector with a unit of ampere.

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

Data Types: double

CurrentTol — Tolerance number for finding unique current breakpoints

1 (default) | nonnegative scalar

Tolerance breakpoints for finding unique current breakpoints in the test data, specified as a nonnegative scalar.

Data Types: double

TemperatureTol — Tolerance number for finding unique temperature breakpoints

0.05 (default) | nonnegative scalar

Tolerance breakpoints for finding unique temperature breakpoints in the test data, specified as a nonnegative scalar.

Data Types: double

SOCTol — Tolerance number for finding unique state-of-charge breakpoints

0.01 (default) | nonnegative scalar

Tolerance breakpoints for finding unique state-of-charge breakpoints in the test data, specified as a nonnegative scalar.

Data Types: double

PercentError — Error percentage from fitting method

Read-only: scalar

This property is read-only.

Error percentage from the fitting method, returned as a scalar.

Data Types: double

NumParameters — Total numbers of parameters in equivalent circuit model

Read-only: scalar

This property is read-only.

Total numbers of parameters in the equivalent circuit model, returned as a scalar.

Data Types: double

ModelParameterTables — Model parameter values over specified dimensions

Read-only: structure

This property is read-only.

Model parameter values over the specified dimensions, returned as a structure. The model-based parameters are interpolated to suit the breakpoints you specified in the SOCBreakpoints, ResistanceSOCBreakpoints, ResistanceTemperatureBreakpoints, TemperatureBreakpoints, and ResistanceCurrentBreakpoints properties.

Data Types: struct

TestParameterTables — Test parameter values over specified dimensions

Read-only: structure

This property is read-only.

Test parameter values over the specified dimensions, returned as a structure.

Data Types: struct

CircuitImpedance — Impedance expression as function of angular frequency

Read-only: string scalar | character vector

This property is read-only.

Impedance expression as a function of angular frequency, returned as a string scalar or character vector.

Data Types: char | string

ParameterList — List of parameters in equivalent circuit model

Read-only: string scalar | character vector

This property is read-only.

List of parameters in the equivalent circuit model, returned as a string scalar or character vector.

Data Types: char | string

ParameterSummary — Summary of parameters

Read-only: table

This property is read-only.

Summary of the parameters and related data, such as directionality, SOC, temperature, and current, returned as a table.

Object Functions

simulateCurrentPulse	Simulate circuit in time domain at given current pulses
mergeModelParameters	Merge parameters of multiple ECM objects
parameterizeEquivalentCircuitBlock	Parameterize Battery Equivalent Circuit block from ECM data
removePulseParameters	Remove parameter data for specific pulse from ECM object
plot	Plot measured and simulated voltage for pulse at specific index
simulateHPPCTest	Plot HPPC test measured voltage against simulated voltage of equivalent circuit model
plotModelParameters	Plot parameters of ECM object
simulateFrequencyResponse	Simulate circuit in frequency domain

Version History

Introduced in R2025a