Equivalent Circuit Models

Equivalent circuit models (ECMs) in PyBaMM, including the Thevenin model with configurable RC elements, thermal submodel, and diffusion element.

Equivalent circuit models (ECMs) represent battery behaviour using electrical circuit analogues — resistors, capacitors, and a voltage source — rather than the partial differential equations of physics-based models. PyBaMM provides ECMs under the pybamm.equivalent_circuit namespace.

When to use ECMs vs physics-based models

Use ECMs when

• Computational speed is critical (e.g. real-time BMS)
• Only terminal voltage and current are available for calibration
• A simple, interpretable model is preferred
• Running large-scale multi-cell pack simulations

Use physics-based models when

• Internal state variables (SOC, concentration, temperature gradients) are needed
• Degradation mechanisms (SEI, plating) must be captured
• Electrode-level design and optimisation is the goal
• High-accuracy predictions over wide operating ranges are required

---

Available models

Thevenin

The Thevenin model is the classical Thevenin equivalent circuit model. It consists of:

• An OCV element representing the open-circuit voltage as a function of state of charge
• A series resistor (R0) representing instantaneous ohmic resistance
• One or more RC elements (R1-C1, R2-C2, …) representing diffusion-related relaxation dynamics
• An optional diffusion element for additional concentration polarisation
• A lumped thermal model for cell and jig temperatures, with heat generation terms from each element

Heat generation follows the formulation in Nieto et al. (2012), with contributions from each circuit element.

Reference: Barletta, G., et al. (2022). Thevenin equivalent circuit model characterisation of lithium-ion batteries.

import pybamm

model = pybamm.equivalent_circuit.Thevenin()
print(model.name)  # 'Thevenin Equivalent Circuit Model'

# Default parameters use the ECM_Example parameter set
param = model.default_parameter_values
sim = pybamm.Simulation(model, parameter_values=param)
sim.solve([0, 3600])
sim.plot()

---

Model options

All options are passed as a dictionary to the options argument at instantiation.

Number of RC elements

Control how many RC parallel branches are included. The default is 1 (one RC pair).

Option	Values	Default
"number of rc elements"	Any positive integer as a string	1

# Two RC elements for better relaxation modelling
model = pybamm.equivalent_circuit.Thevenin(
    options={"number of rc elements": 2}
)

Diffusion element

Add a Warburg-like diffusion element to capture long-timescale concentration effects.

Option	Values	Default
"diffusion element"	"false", "true"	"false"

model = pybamm.equivalent_circuit.Thevenin(
    options={"diffusion element": "true"}
)

Operating mode

Same operating modes as physics-based models are supported.

Option	Values	Default
"operating mode"	"current", "voltage", "power", "differential power", "resistance", "differential resistance", "CCCV", callable	"current"

# Simulate at constant voltage
model = pybamm.equivalent_circuit.Thevenin(
    options={"operating mode": "voltage"}
)

Discharge energy tracking

Optionally compute throughput energy and throughput capacity in addition to discharge capacity.

Option	Values	Default
"calculate discharge energy"	"false", "true"	"false"

model = pybamm.equivalent_circuit.Thevenin(
    options={"calculate discharge energy": "true"}
)

---

ECM parameters

The Thevenin model uses pybamm.EcmParameters and defaults to the ECM_Example parameter set. Key parameters include:

Parameter	Description
Open-circuit voltage (OCV)	Lookup table or function of SOC
R0	Series (ohmic) resistance
R1, R2, …	RC branch resistances
C1, C2, …	RC branch capacitances
Cell heat capacity	For thermal model
Jig heat capacity	For jig thermal model

import pybamm

param = pybamm.ParameterValues("ECM_Example")
print(param.keys())

---

Extended example

import pybamm

# Thevenin model with 2 RC elements and a diffusion element
model = pybamm.equivalent_circuit.Thevenin(
    options={
        "number of rc elements": 2,
        "diffusion element": "true",
        "calculate discharge energy": "true",
    }
)

param = model.default_parameter_values

experiment = pybamm.Experiment([
    "Discharge at 1C until 2.5 V",
    "Rest for 1 hour",
    "Charge at 1C until 4.2 V",
])

sim = pybamm.Simulation(model, parameter_values=param, experiment=experiment)
sim.solve()
sim.plot()

The Thevenin model’s default_quick_plot_variables includes current, voltage, OCV, SoC, power, temperatures, and heat generation terms — all available immediately after solving.