Skip to main content
The pybamm.equivalent_circuit module provides data-driven equivalent circuit models (ECMs). These are faster than physics-based models and are commonly used in BMS applications.

​
Available models

ClassDescription
TheveninClassical Thevenin ECM with OCV, resistance, and RC elements

​
pybamm.equivalent_circuit.Thevenin

The Thevenin ECM consists of:
  • An OCV element — open-circuit voltage as a function of SoC.
  • A series resistor — R0 (Element-0).
  • One or more RC elements — each with a resistance and capacitance in parallel.
  • An optional diffusion element.
  • A lumped thermal model for cell and jig temperatures.
pybamm.equivalent_circuit.Thevenin(
    name="Thevenin Equivalent Circuit Model",
    options=None,
    build=True,
)
​
name
str
default:"Thevenin Equivalent Circuit Model"
Human-readable model name.
​
options
dict
Model options. See Options reference below.
​
build
bool
default:"true"
Build the model on instantiation. Pass False to modify sub-models first.
Default parameter set: pybamm.ParameterValues("ECM_Example")

​
Options reference

​
number of rc elements
str | int
default:"1"
Number of RC elements to add to the model. Must be a positive integer (passed as a string or int, e.g. "2" or 2).
​
diffusion element
str
default:"false"
Whether to include a diffusion (Warburg) element. "false" or "true".
​
operating mode
str
default:"current"
How the applied current is determined. Options:
  • "current" — current is supplied directly
  • "voltage" — algebraic solve for current at fixed voltage
  • "power" — algebraic solve for current at fixed power
  • "differential power" — ODE for power
  • "resistance" — algebraic solve for current at fixed resistance
  • "differential resistance" — ODE for resistance
  • "CCCV" — constant-current constant-voltage via ODE for current
  • callable — user-defined algebraic residual
​
calculate discharge energy
str
default:"false"
Whether to calculate discharge energy, throughput energy, and throughput capacity. "false" or "true".

​
Default quick-plot variables

When sim.plot() is called without arguments, the Thevenin model plots:
  • "Current [A]"
  • "Voltage [V]" and "Open-circuit voltage [V]"
  • "SoC"
  • "Power [W]"
  • Cell, jig, and ambient temperatures
  • Total, reversible, and irreversible heat generation

​
Examples

import pybamm

model = pybamm.equivalent_circuit.Thevenin()
param = pybamm.ParameterValues("ECM_Example")

sim = pybamm.Simulation(model, parameter_values=param)
sim.solve([0, 3600])

sol = sim.solution
print(sol["Voltage [V]"].entries)
print(sol["SoC"].entries)
The Thevenin model requires OCV, resistance, and RC parameter functions to be defined as functions of SoC in ParameterValues. The built-in "ECM_Example" set provides these for testing.

Build docs developers (and LLMs) love

Get started for freeTalk to us