Use this file to discover all available pages before exploring further.
PyBaMM provides several physics-based lithium-ion battery models that span a wide range of fidelity and computational cost. All models are accessible from the pybamm.lithium_ion namespace.
The SPM reduces each electrode to a single representative spherical particle. Electrolyte concentration gradients are neglected, and the overpotential is determined from the leading-order electrolyte conductivity. This is the fastest lithium-ion model in PyBaMM.When to use: Rapid parameter studies, state estimation, control design, or situations where electrolyte dynamics are unimportant (low C-rates).Reference: Marquis, S. G., et al. (2019). An asymptotic derivation of a single particle model with electrolyte. Journal of The Electrochemical Society.
The SPMe extends the SPM by including corrections for electrolyte concentration and potential using a composite asymptotic expansion. It inherits particle submodels from the SPM and replaces only the electrolyte and electrode potential submodels.When to use: Simulations that need to capture electrolyte depletion effects without the full cost of DFN. A good default choice for moderate C-rates.Reference: Marquis, S. G., et al. (2019). An asymptotic derivation of a single particle model with electrolyte. Journal of The Electrochemical Society.
import pybammmodel = pybamm.lithium_ion.SPMe()print(model.name) # 'Single Particle Model with electrolyte'sim = pybamm.Simulation(model)sim.solve([0, 3600])sim.plot()
The DFN is the full porous-electrode model that resolves spatial distributions of electrolyte concentration, electrolyte potential, electrode potential, and particle concentration across the cell sandwich. This is the highest-fidelity standard model in PyBaMM.When to use: High-accuracy single-cell simulations, degradation studies (SEI, lithium plating), or whenever resolving spatial gradients is important (high C-rates, thick electrodes).Reference: Doyle, M., Fuller, T. F., & Newman, J. (1993). Modeling of galvanostatic charge and discharge of the lithium/polymer/insertion cell. Journal of The Electrochemical Society.
The MPM extends the SPM to include a distribution of particle sizes at each macroscale location. This captures heterogeneous utilisation and the effect of polydispersity on cell performance and degradation.When to use: Studies of electrode manufacturing variability, heterogeneous lithiation, or when a single representative particle size is insufficient.Reference: Kirk, T. L., et al. (2020). Modelling electrode heterogeneity in lithium-ion batteries: unimodal and bimodal particle-size distributions. SIAM Journal on Applied Mathematics.
The MPM requires a particle size distribution in the parameter values. Use pybamm.get_size_distribution_parameters to add distribution parameters to an existing parameter set.
The MSMR is built on top of the DFN and uses a thermodynamic site-occupancy formulation for the open-circuit potential, intercalation kinetics, and particle diffusion. Each electrode is described by a set of reaction sites with individual occupancy fractions, standard potentials, and ideality factors.When to use: When electrode thermodynamics are well-characterised by the MSMR formalism and greater accuracy in OCP shape is needed.
The number of MSMR reactions option is required. You must specify the number of reactions for each electrode as a 2-tuple, e.g. ("6", "4").
import pybammmodel = pybamm.lithium_ion.MSMR( options={"number of MSMR reactions": ("6", "4")})print(model.name) # 'MSMR'# Default parameter values use the MSMR_Example setparam = model.default_parameter_valuessim = pybamm.Simulation(model, parameter_values=param)sim.solve([0, 3600])sim.plot()
The NewmanTobias model is a DFN-class model that assumes a uniform electrolyte concentration (constant concentration approximation). Unlike the original Newman-Tobias formulation, it uses nonlinear Butler-Volmer kinetics and tracks average solid-phase concentration per electrode. Users may optionally add particle diffusion.When to use: Teaching or benchmarking purposes; situations where you want a DFN-like spatial structure without full electrolyte diffusion.References:
Newman, J. S., & Tobias, C. W. (1962). Theoretical analysis of current distribution in porous electrodes. Journal of The Electrochemical Society.
Chu, H. C., et al. (2020). A control-oriented electrochemical model for lithium-ion batteries.
The Yang2017 model is a DFN variant with pre-configured degradation options that model coupled SEI growth (EC reaction limited) and irreversible lithium plating in the negative electrode, including porosity change from both mechanisms.When to use: Capacity fade and degradation studies that combine SEI growth and lithium plating using the formulation from Yang et al. (2017).Reference: Yang, X.-G., et al. (2017). Modeling of lithium plating induced aging of lithium-ion batteries: transition from linear to nonlinear aging. Journal of Power Sources.
