ecm

R2026b

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 100 0.0125 1000] (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

InterpolationMethod — Interpolation option for computing model parameters from test data

"linear" (default) | "nearest"

Since R2026b

Interpolation option to control how the ECM object computes the model parameters from the test data at the specified SOC and temperature breakpoints. Linear interpolation produces physically meaningful values between measurements.

Data Types: char | string

ExtrapolationMethod — Extrapolation option for computing model parameters from test data

"nearest" (default) | "linear"

Since R2026b

Extrapolation option to control how the ECM object computes the model parameters from the test data at the specified SOC and temperature breakpoints. Nearest extrapolation prevents negative values when extrapolating outside the measured range. If linear extrapolation produces negative values, the ECM object issues a warning and automatically falls back to nearest extrapolation.

Data Types: char | string

PercentError — Normalized fit quality

Read-only: column vector

This property is read-only.

Normalized fit quality between the model output and measured voltage data, returned as a column vector with one element for each pulse.

The software computes each element in the vector as:

$$\%\text{Error}=100\frac{1-\Vert \text{residuals}\Vert }{\Vert y-\text{mean}\left(y\right)\Vert }$$

where residuals is the difference between the measured voltage and the model-predicted voltage, and y is the measured voltage. A value of 100 indicates a perfect fit.

The fitECM function sets this property after parameter estimation. If you set the FittingMethod argument to "mbc", the fitting method estimates the parameters globally rather than for each pulse, so all elements in the vector have the same value.

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.

The table contains these columns:

• ID — Pulse identifier.

• Directionality — Direction of the current pulse, specified as "Discharge" or "Charge".

• Temperature_degC — Cell temperature during the pulse, in degrees Celsius.

• Current_A — Applied current during the pulse, in amperes. Negative values indicate discharge.

• SOC — State of charge at the start of the pulse, in the range [0, 1].

• OpenCircuitVoltage — Estimated open-circuit voltage at the operating point, in volts.

• Rn, Taun, Cn — Resistance in ohms, time constant in seconds, and capacitance in farads of the nth RC parallel pair. The number of RC column groups matches the value of the NumRCPairs property. For example, a 2-RC model has R1, Tau1, C1, R2, Tau2, and C2 columns.

• FitPc — Normalized fit quality for the pulse, as a percentage. For more information, see the PercentError property. If you set the NumRCPairs to 0, the values in this column are always equal to 100 as the software calculates the normalized fit quality directly from the data.

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 and obtain real and imaginary impedance

Version History

Introduced in R2025a

R2026b: Specify interpolation and extrapolation options

Use the InterpolationMethod and ExtrapolationMethod properties to control how the ECM object computes the model parameters from the test data at the specified SOC and temperature breakpoints. Linear interpolation produces physically meaningful values between measurements. Nearest extrapolation prevents negative values when extrapolating outside the measured range. If the linear extrapolation produces negative resistance or capacitance values, the ECM object issues a warning and automatically falls back to nearest extrapolation.