Using Parameter Sets

Learn how to load built-in parameter sets, modify individual parameters, define custom parameter functions, and load parameters from BPX files.

pybamm.ParameterValues holds all the numerical values that define a specific battery cell — geometry, material properties, transport coefficients, kinetic parameters, and more. Every parameter in PyBaMM carries SI units in its name.

Loading a built-in parameter set

PyBaMM ships with a collection of published parameter sets. Pass the name as a string:

import pybamm

param = pybamm.ParameterValues("Chen2020")

You can also load from a dict or copy from another ParameterValues object:

# From a dict
param = pybamm.ParameterValues({"Current function [A]": 1.0, ...})

# Copy from existing
param2 = pybamm.ParameterValues(param)

Available parameter sets

Lithium-ion

Chen2020

LG M50 NMC/graphite cell. A widely used general-purpose parameter set.

param = pybamm.ParameterValues("Chen2020")

Marquis2019

NMC/graphite cell from the DFN model derivation paper. Used in many PyBaMM examples.

param = pybamm.ParameterValues("Marquis2019")

OKane2022

Graphite/NMC cell with degradation parameters (SEI, lithium plating).

param = pybamm.ParameterValues("OKane2022")

ORegan2022

NMC/graphite cell with thermal and mechanical parameters.

param = pybamm.ParameterValues("ORegan2022")

Ecker2015

Kokam NMC/graphite cell with full porous-electrode parameters.

param = pybamm.ParameterValues("Ecker2015")

Ai2020

NMC/graphite cell with mechanical parameters for stress-driven LAM.

param = pybamm.ParameterValues("Ai2020")

Mohtat2020

NMC/graphite with aging parameters.

param = pybamm.ParameterValues("Mohtat2020")

NCA_Kim2011

NCA/graphite cell.

param = pybamm.ParameterValues("NCA_Kim2011")

Prada2013

LFP/graphite A123 cell.

param = pybamm.ParameterValues("Prada2013")

Ramadass2004

Sony US18650 cell, one of the earliest complete DFN parameter sets.

param = pybamm.ParameterValues("Ramadass2004")

Xu2019

NMC/graphite pouch cell.

param = pybamm.ParameterValues("Xu2019")

Chen2020_composite

Composite graphite-SiOx/NMC cell (multi-phase negative electrode).

param = pybamm.ParameterValues("Chen2020_composite")

Half-cell parameter sets

param = pybamm.ParameterValues("Ecker2015_graphite_halfcell")
param = pybamm.ParameterValues("OKane2022_graphite_SiOx_halfcell")

Other chemistries

# Lead-acid
param = pybamm.ParameterValues("Sulzer2019")

# Equivalent circuit model
param = pybamm.ParameterValues("ECM_Example")

# MSMR model
param = pybamm.ParameterValues("MSMR_Example")

# Sodium-ion
param = pybamm.ParameterValues("Chayambuka2022")

Exploring parameters

param = pybamm.ParameterValues("Chen2020")

# Access a single parameter
print(param["Nominal cell capacity [A.h]"])

# List all keys
print(list(param.keys()))

# Get parameter metadata (units, category, etc.)
info = param.get_info("Reference temperature [K]")
print(info.units)  # 'K'

# List parameters by category
neg_electrode_params = param.list_by_category("negative electrode")

Updating parameters

Update individual values with dict-style assignment:

param = pybamm.ParameterValues("Chen2020")

# Set constant current
param["Current function [A]"] = 5.0

# Change cell geometry
param["Electrode height [m]"] = 0.065
param["Electrode width [m]"] = 1.58

# Update multiple values at once
param.update({
    "Negative electrode thickness [m]": 75e-6,
    "Positive electrode thickness [m]": 70e-6,
    "Separator thickness [m]": 25e-6,
})

Custom parameter functions

Many parameters are functions (e.g. diffusivity as a function of concentration and temperature). Define them as Python callables:

import pybamm

# Diffusivity as a function of concentration and temperature
def my_diffusivity(c_e, T):
    return 1.0e-10 * pybamm.exp(-500 / T)

param = pybamm.ParameterValues("Chen2020")
param["Electrolyte diffusivity [m2.s-1]"] = my_diffusivity

The function arguments must use pybamm symbolic expressions so they can be differentiated and compiled.

Drive cycle (time-varying current)

Use an Interpolant to define a current from data:

import numpy as np
import pybamm

# Time [s] and current [A] arrays
times = np.array([0, 100, 200, 300, 400, 500])
currents = np.array([1.0, 2.0, 1.5, 0.5, -1.0, -2.0])

current_interpolant = pybamm.Interpolant(times, currents, pybamm.t)

param = pybamm.ParameterValues("Chen2020")
param["Current function [A]"] = current_interpolant

sim = pybamm.Simulation(model, parameter_values=param)
sol = sim.solve()  # t_eval is inferred from the data

BPX format

PyBaMM supports the Battery Parameter eXchange (BPX) format, a standardised JSON schema for battery parameters.

BPX support requires the optional bpx dependency: pip install pybamm[bpx]

Loading from a BPX file

param = pybamm.ParameterValues.create_from_bpx("my_cell.json")

# Load at a specific target SOC
param = pybamm.ParameterValues.create_from_bpx("my_cell.json", target_soc=0.8)

Loading from a BPX dict object

bpx_dict = {
    "Header": {...},
    "Cell": {...},
    "Parameterisation": {...},
}
param = pybamm.ParameterValues.create_from_bpx_obj(bpx_dict)

Setting initial state of charge

You can set the initial lithium distribution to correspond to a target SOC:

param = pybamm.ParameterValues("Chen2020")
model = pybamm.lithium_ion.SPM()

sim = pybamm.Simulation(model, parameter_values=param)

# Solve starting at 50% SOC
sol = sim.solve([0, 3600], initial_soc=0.5)

Alternatively, set it before solving:

sim.build()
sim.set_initial_state(0.5)
sol = sim.solve([0, 3600])

Input parameters

For parameter sweeps or sensitivity analysis, mark a parameter as an "[input]" to pass it at solve time without rebuilding the model:

param = pybamm.ParameterValues("Chen2020")
param["Current function [A]"] = "[input]"

model = pybamm.lithium_ion.SPM()
sim = pybamm.Simulation(model, parameter_values=param)
sim.build()

# Solve with different currents without rebuilding
for current in [1.0, 2.0, 5.0]:
    sol = sim.solve([0, 3600], inputs={"Current function [A]": current})
    print(current, sol["Battery voltage [V]"].entries[-1])