Skip to main content
PyBaMM models describe the electrochemical and thermal physics of a battery cell. Every model is built from a set of submodels — modular components that each represent a piece of the physics, such as particle diffusion, electrolyte transport, or SEI growth.

​
Model architecture

All battery models inherit from pybamm.BaseBatteryModel, which provides:
  • A submodels dictionary mapping submodel names to submodel objects
  • Default geometry, mesh, discretisation, and solver settings
  • A build() method that assembles the submodels into a system of equations
  • An options dictionary that controls which submodels are active
The Simulation class handles setting parameters, meshing, discretisation, and solving — so in most workflows you create a model and pass it directly to pybamm.Simulation.

​
Available lithium-ion models

Single Particle Model (SPM)The simplest electrochemical model. Each electrode is represented as a single spherical particle. The electrolyte concentration is assumed uniform (constant). Fast to solve, suitable for low C-rates.
model = pybamm.lithium_ion.SPM()
Reference: Marquis et al. (2019)

​
Other chemistries

Lead-acid

pybamm.lead_acid.Full() — full porous-electrode lead-acid modelpybamm.lead_acid.LOQS() — leading-order quasi-static model

Equivalent circuit

pybamm.equivalent_circuit.Thevenin() — RC equivalent circuit model

​
Instantiating models

Basic instantiation
import pybamm

# Default options
model = pybamm.lithium_ion.DFN()

# Custom name
model = pybamm.lithium_ion.SPM(name="My SPM")

# With options
model = pybamm.lithium_ion.DFN(options={"thermal": "lumped"})
The options dict is optional — every option has a default. You only need to supply the keys you want to change.

​
Model options

Options control which submodels are active and how physics is represented. The full set is documented in BatteryModelOptions. Key options are listed below.
Controls how heat generation and transfer are modelled.
ValueDescription
"isothermal" (default)No thermal effects
"lumped"Single lumped temperature ODE
"x-lumped"Lumped in through-cell direction, resolved in transverse
"x-full"Full thermal model (requires cell geometry: "pouch")
model = pybamm.lithium_ion.DFN(options={"thermal": "lumped"})
Sets the submodel used to describe lithium diffusion inside electrode particles.
ValueDescription
"Fickian diffusion" (default)Full spherical diffusion
"uniform profile"Uniform concentration within particle
"quadratic profile"Second-order polynomial approximation
"quartic profile"Fourth-order polynomial approximation
"MSMR"Multi-site multi-reaction diffusion
A 2-tuple sets different options per electrode:
model = pybamm.lithium_ion.DFN(
    options={"particle": ("Fickian diffusion", "uniform profile")}
)
Models the growth of the Solid Electrolyte Interface on the negative electrode.
ValueDescription
"none" (default)No SEI growth
"constant"Fixed SEI thickness
"reaction limited"SEI growth limited by electrochemical reaction
"solvent-diffusion limited"Growth limited by solvent diffusion
"electron-migration limited"Growth limited by electron migration
"ec reaction limited"Ethylene carbonate reduction
"VonKolzenberg2020"Multi-mechanism model
model = pybamm.lithium_ion.SPM(options={"SEI": "reaction limited"})
Models lithium metal deposition on the negative electrode.
ValueDescription
"none" (default)No plating
"reversible"Reversible plating
"partially reversible"Partial reversibility
"irreversible"Irreversible plating
model = pybamm.lithium_ion.DFN(options={"lithium plating": "irreversible"})
Models degradation of active material over cycling.
ValueDescription
"none" (default)No LAM
"stress-driven"Driven by mechanical stress
"reaction-driven"Driven by side reactions
"current-driven"Driven by current
"stress and reaction-driven"Combined
model = pybamm.lithium_ion.DFN(
    options={"loss of active material": "stress-driven"}
)
Sets the electrochemical kinetics model at the electrode-electrolyte interface.
ValueDescription
"symmetric Butler-Volmer" (default)Standard Butler-Volmer
"asymmetric Butler-Volmer"Asymmetric transfer coefficient
"linear"Linearised kinetics
"Marcus"Marcus theory
"Marcus-Hush-Chidsey"Asymptotic MHC
"MSMR"Multi-site kinetics
Models mechanical stresses and cracking in electrode particles.
ValueDescription
"none" (default)No mechanics
"swelling only"Particle swelling without cracking
"swelling and cracking"Full mechanics with cracking

​
Combining options

Multiple options can be combined in a single dict:
DFN with degradation
model = pybamm.lithium_ion.DFN(
    options={
        "thermal": "lumped",
        "SEI": "reaction limited",
        "lithium plating": "irreversible",
        "loss of active material": "stress-driven",
        "particle mechanics": "swelling and cracking",
    }
)
Not all combinations of options are valid. PyBaMM will raise an OptionError if incompatible options are combined — for example, specifying "MSMR" for the "particle" option without also setting "open-circuit potential": "MSMR".

​
Basic models for teaching

PyBaMM includes simplified implementations that expose the full equation derivation, suitable for learning and custom extensions: 
# Basic DFN with explicit equations (no submodel abstraction)
model = pybamm.lithium_ion.BasicDFN()

# Basic SPM
model = pybamm.lithium_ion.BasicSPM()

# DFN for a half-cell
model = pybamm.lithium_ion.BasicDFNHalfCell()

​
Checking what’s in a model

model = pybamm.lithium_ion.DFN()

# List all submodels
print(list(model.submodels.keys()))

# Check model options
print(model.options)

# List all output variables
print(list(model.variables.keys())[:10])

Build docs developers (and LLMs) love

Get started for freeTalk to us