Equivalent Circuit Models API

Thevenin and other equivalent circuit models available in pybamm.equivalent_circuit.

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

Class	Description
Thevenin	Classical 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

Basic Thevenin discharge

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.