Skip to main content
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.
Control how many RC parallel branches are included. The default is 1 (one RC pair).
OptionValuesDefault
"number of rc elements"Any positive integer as a string1
# Two RC elements for better relaxation modelling
model = pybamm.equivalent_circuit.Thevenin(
    options={"number of rc elements": 2}
)
Add a Warburg-like diffusion element to capture long-timescale concentration effects.
OptionValuesDefault
"diffusion element""false", "true""false"
model = pybamm.equivalent_circuit.Thevenin(
    options={"diffusion element": "true"}
)
Same operating modes as physics-based models are supported.
OptionValuesDefault
"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"}
)
Optionally compute throughput energy and throughput capacity in addition to discharge capacity.
OptionValuesDefault
"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:
ParameterDescription
Open-circuit voltage (OCV)Lookup table or function of SOC
R0Series (ohmic) resistance
R1, R2, …RC branch resistances
C1, C2, …RC branch capacitances
Cell heat capacityFor thermal model
Jig heat capacityFor 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us