Skip to main content
The pybamm.lithium_ion module provides several electrochemical models of increasing complexity for lithium-ion cells. All models share the same options parameter interface and default parameter sets.

​
Available models

ClassFull nameComplexity
SPMSingle Particle ModelLowest
SPMeSingle Particle Model with electrolyteLow
DFNDoyle-Fuller-NewmanHigh (full-order)
MPMMany Particle ModelMedium
MSMRMulti-Species Multi-ReactionMedium
NewmanTobiasNewman-TobiasMedium
Yang2017Yang 2017Medium
Basic educational implementations are also available: BasicSPM, BasicDFN, BasicDFNHalfCell, BasicDFNComposite, BasicDFN2D, Basic3DThermalSPM, SplitOCVR.

​
pybamm.lithium_ion.SPM

Single Particle Model — the simplest lithium-ion model. Uses x-averaged kinetics and ignores electrolyte transport. Suitable for low C-rates. 
pybamm.lithium_ion.SPM(options=None, name="Single Particle Model", build=True)
​
options
dict
Model options dict. See Options reference below.
​
name
str
default:"Single Particle Model"
Human-readable model name.
​
build
bool
default:"true"
Build the model on instantiation. Set to False to modify sub-models before building.
Default parameter set: pybamm.ParameterValues("Marquis2019")

​
pybamm.lithium_ion.SPMe

Single Particle Model with electrolyte — extends SPM with leading-order electrolyte effects. Good balance of speed and accuracy. 
pybamm.lithium_ion.SPMe(options=None, name="Single Particle Model with electrolyte", build=True)
Default parameter set: pybamm.ParameterValues("Marquis2019")

​
pybamm.lithium_ion.DFN

Doyle-Fuller-Newman model — the full-order porous electrode model. Resolves electrolyte concentration and potential throughout the cell. Recommended for higher C-rates and degradation studies. 
pybamm.lithium_ion.DFN(options=None, name="Doyle-Fuller-Newman model", build=True)
Default parameter set: pybamm.ParameterValues("Marquis2019")
DFN is the most physically faithful standard model. Use it when SPM or SPMe predictions diverge from expected behaviour.

​
pybamm.lithium_ion.MPM

Many Particle Model — accounts for a statistical distribution of particle sizes at each macroscale location. 
pybamm.lithium_ion.MPM(options=None, name="Many Particle Model", build=True)

​
pybamm.lithium_ion.MSMR

Multi-Species Multi-Reaction model — resolves multiple lithiation reactions per electrode using the MSMR thermodynamic framework. 
pybamm.lithium_ion.MSMR(options=None, name="Multi-species multi-reaction model", build=True)

​
pybamm.lithium_ion.NewmanTobias

Newman-Tobias model — a simplified DFN variant that uses linear concentration profiles in the electrolyte. 
pybamm.lithium_ion.NewmanTobias(options=None, name="Newman-Tobias model", build=True)

​
pybamm.lithium_ion.Yang2017

Yang 2017 model — includes coupled mechanical effects (particle swelling, SEI) following Yang et al. (2017). 
pybamm.lithium_ion.Yang2017(options=None, name="Yang2017", build=True)

​
Options reference

All lithium-ion models accept an options dict. Below are the most commonly used keys. A 2-tuple can be provided for most string options to specify different values for the negative and positive electrodes.
OptionValid valuesDefault
"particle""Fickian diffusion", "uniform profile", "quadratic profile", "quartic profile", "MSMR""Fickian diffusion"
"particle shape""spherical", "no particles""spherical"
"particle size""single", "distribution""single"
"particle phases""1", "2""1"
"particle mechanics""none", "swelling only", "swelling and cracking""none"
"stress-induced diffusion""false", "true""false" (or "true" if mechanics enabled)
OptionValid valuesDefault
"intercalation kinetics""symmetric Butler-Volmer", "asymmetric Butler-Volmer", "linear", "Marcus", "Marcus-Hush-Chidsey", "MSMR""symmetric Butler-Volmer"
"exchange-current density""single", "current sigmoid""single"
"interface utilisation""full", "constant", "current-driven""full"
"open-circuit potential""single", "current sigmoid", "one-state hysteresis", "one-state differential capacity hysteresis", "MSMR""single"
OptionValid valuesDefault
"electrolyte conductivity""default", "full", "leading order", "composite", "integrated""default"
"surface form""false", "differential", "algebraic""false"
"diffusivity""single", "current sigmoid""single"
OptionValid valuesDefault
"SEI""none", "constant", "reaction limited", "reaction limited (asymmetric)", "solvent-diffusion limited", "electron-migration limited", "interstitial-diffusion limited", "ec reaction limited", "ec reaction limited (asymmetric)", "VonKolzenberg2020", "tunnelling limited""none"
"SEI film resistance""none", "distributed", "average""none" (or "distributed" if SEI is enabled)
"SEI on cracks""false", "true""false"
"SEI porosity change""false", "true""false"
OptionValid valuesDefault
"lithium plating""none", "reversible", "partially reversible", "irreversible""none"
"lithium plating porosity change""false", "true""false"
OptionValid valuesDefault
"loss of active material""none", "stress-driven", "asymmetric stress-driven", "reaction-driven", "current-driven", "stress and reaction-driven", "asymmetric stress and reaction-driven""none"
OptionValid valuesDefault
"thermal""isothermal", "lumped", "x-lumped", "x-full""isothermal"
"cell geometry""arbitrary", "pouch", "cylindrical""arbitrary"
"dimensionality"0, 1, 20
"calculate heat source for isothermal models""false", "true""false"
"use lumped thermal capacity""false", "true""false"
OptionValid valuesDefault
"operating mode""current", "voltage", "power", "resistance", "differential power", "differential resistance", "explicit power", "explicit resistance", "CCCV", callable"current"
"working electrode""both", "positive""both"
"current collector""uniform", "potential pair", "potential pair quite conductive""uniform"
"calculate discharge energy""false", "true""false"
"contact resistance""false", "true""false"
OptionValid valuesDefault
"x-average side reactions""false", "true""true" for SPM/MPM, "false" otherwise
"total interfacial current density as a state""false", "true""false"
"voltage as a state""false", "true""false"

​
Default parameter sets

ModelDefault ParameterValues key
SPM, SPMe, DFN"Marquis2019"
MPM"Marquis2019"
MSMR"Xu2019"
Yang2017"Yang2017"
Other commonly used parameter sets: "Chen2020", "Ecker2015", "NCA_Kim2011", "OKane2022", "Prada2013", "Ramadass2004", "MSMR_Example".

​
Examples

import pybamm

model = pybamm.lithium_ion.DFN(
    options={
        "SEI": "reaction limited",
        "SEI porosity change": "true",
        "lithium plating": "none",
    }
)

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

Build docs developers (and LLMs) love

Get started for freeTalk to us