Base Battery Model#

class pybamm.BaseBatteryModel(options=None, name='Unnamed battery model')[source]#

Base model class with some default settings and required variables

Parameters:

options (dict-like, optional) – A dictionary of options to be passed to the model. If this is a dict (and not a subtype of dict), it will be processed by pybamm.BatteryModelOptions to ensure that the options are valid. If this is a subtype of dict, it is assumed that the options have already been processed and are valid. This allows for the use of custom options classes. The default options are given by pybamm.BatteryModelOptions.
name (str, optional) – The name of the model. The default is “Unnamed battery model”.

Extends: pybamm.models.base_model.BaseModel

property default_geometry#: Returns a dictionary of the default geometry for the model, which is empty by default.

property default_spatial_methods#: Returns a dictionary of the default spatial methods for the model, which is empty by default.

property default_submesh_types#: Returns a dictionary of the default submesh types for the model, which is empty by default.

property default_var_pts#: Returns a dictionary of the default variable points for the model, which is empty by default.

classmethod deserialise(properties: dict)[source]#: Create a model instance from a serialised object.

property options#: Returns the model options dictionary that allows customization of the model’s behavior.

save_model(filename=None, mesh=None, variables=None)[source]#

Write out a discretised model to a JSON file

Parameters:

filename (str, optional)
provided (The desired name of the JSON file. If no name is)
created (one will be)
name (based on the model)
datetime. (and the current)

set_degradation_variables()[source]#: Set variables that quantify degradation. This function is overriden by the base battery models

set_external_circuit_submodel()[source]#: Define how the external circuit defines the boundary conditions for the model, e.g. (not necessarily constant-) current, voltage, etc

set_soc_variables()[source]#: Set variables relating to the state of charge. This function is overriden by the base battery models

class pybamm.BatteryModelOptions(extra_options)[source]#

options#

A dictionary of options to be passed to the model. The options that can be set are listed below. Note that not all of the options are compatible with each other and with all of the models implemented in PyBaMM. Each option is optional and takes a default value if not provided. In general, the option provided must be a string, but there are some cases where a 2-tuple of strings can be provided instead to indicate a different option for the negative and positive electrodes.

“calculate discharge energy”: str
Whether to calculate the discharge energy, throughput energy and throughput capacity in addition to discharge capacity. Must be one of “true” or “false”. “false” is the default, since calculating discharge energy can be computationally expensive for simple models like SPM.

“cell geometry”str
Sets the geometry of the cell. Can be “arbitrary” (default) or “pouch”. The arbitrary geometry option solves a 1D electrochemical model with prescribed cell volume and cross-sectional area, and (if thermal effects are included) solves a lumped thermal model with prescribed surface area for cooling.

“calculate heat source for isothermal models”str
Whether to calculate the heat source terms during isothermal operation. Can be “true” or “false”. If “false”, the heat source terms are set to zero. Default is “false” since this option may require additional parameters not needed by the electrochemical model.

“convection”str
Whether to include the effects of convection in the model. Can be “none” (default), “uniform transverse” or “full transverse”. Must be “none” for lithium-ion models.

“current collector”str
Sets the current collector model to use. Can be “uniform” (default), “potential pair” or “potential pair quite conductive”.

“diffusivity”str
Sets the model for the diffusivity. Can be “single” (default) or “current sigmoid”. A 2-tuple can be provided for different behaviour in negative and positive electrodes.

“dimensionality”int
Sets the dimension of the current collector problem. Can be 0 (default), 1 or 2.

“electrolyte conductivity”str
Can be “default” (default), “full”, “leading order”, “composite” or “integrated”.

“exchange-current density”str
Sets the model for the exchange-current density. Can be “single” (default) or “current sigmoid”. A 2-tuple can be provided for different behaviour in negative and positive electrodes.

“hydrolysis”str
Whether to include hydrolysis in the model. Only implemented for lead-acid models. Can be “false” (default) or “true”. If “true”, then “surface form” cannot be ‘false’.

“intercalation kinetics”str
Model for intercalation kinetics. Can be “symmetric Butler-Volmer” (default), “asymmetric Butler-Volmer”, “linear”, “Marcus”, “Marcus-Hush-Chidsey” (which uses the asymptotic form from Zeng 2014), or “MSMR” (which uses the form from Baker 2018). A 2-tuple can be provided for different behaviour in negative and positive electrodes.

“interface utilisation”: str
Can be “full” (default), “constant”, or “current-driven”.

“lithium plating”str
Sets the model for lithium plating. Can be “none” (default), “reversible”, “partially reversible”, or “irreversible”.

“lithium plating porosity change”str
Whether to include porosity change due to lithium plating, can be “false” (default) or “true”.

“loss of active material”str
Sets the model for loss of active material. Can be “none” (default), “stress-driven”, “reaction-driven”, “current-driven”, or “stress and reaction-driven”. A 2-tuple can be provided for different behaviour in negative and positive electrodes.

“number of MSMR reactions”str
Sets the number of reactions to use in the MSMR model in each electrode. A 2-tuple can be provided to give a different number of reactions in the negative and positive electrodes. Default is “none”. Can be any 2-tuple of strings of integers. For example, set to (“6”, “4”) for a negative electrode with 6 reactions and a positive electrode with 4 reactions.

“open-circuit potential”str
Sets the model for the open circuit potential. Can be “single” (default), “current sigmoid”, “Wycisk”, “Axen”, or “MSMR”. If “MSMR” then the “particle” option must also be “MSMR”. A 2-tuple can be provided for different behaviour in negative and positive electrodes.

“operating mode”str
Sets the operating mode for the model. This determines how the current is set. Can be:

“current” (default) : the current is explicity supplied

“voltage”/”power”/”resistance” : solve an algebraic equation for current such that voltage/power/resistance is correct

“differential power”/”differential resistance” : solve a differential equation for the power or resistance

“explicit power”/”explicit resistance” : current is defined in terms of the voltage such that power/resistance is correct

“CCCV”: a special implementation of the common constant-current constant-voltage charging protocol, via an ODE for the current

callable : if a callable is given as this option, the function defines the residual of an algebraic equation. The applied current will be solved for such that the algebraic constraint is satisfied.

“particle”str
Sets the submodel to use to describe behaviour within the particle. Can be “Fickian diffusion” (default), “uniform profile”, “quadratic profile”, “quartic profile”, or “MSMR”. If “MSMR” then the “open-circuit potential” option must also be “MSMR”. A 2-tuple can be provided for different behaviour in negative and positive electrodes.

“particle mechanics”str
Sets the model to account for mechanical effects such as particle swelling and cracking. Can be “none” (default), “swelling only”, or “swelling and cracking”. A 2-tuple can be provided for different behaviour in negative and positive electrodes.

“particle phases”: str
Number of phases present in the electrode. A 2-tuple can be provided for different behaviour in negative and positive electrodes. For example, set to (“2”, “1”) for a negative electrode with 2 phases, e.g. graphite and silicon.

“particle shape”str
Sets the model shape of the electrode particles. This is used to calculate the surface area to volume ratio. Can be “spherical” (default), or “no particles”.

“particle size”str
Sets the model to include a single active particle size or a distribution of sizes at any macroscale location. Can be “single” (default) or “distribution”. Option applies to both electrodes.

“SEI”str
Set the SEI submodel to be used. Options are:

“none”: pybamm.sei.NoSEI (no SEI growth)

“constant”: pybamm.sei.Constant (constant SEI thickness)

“reaction limited”, “reaction limited (asymmetric)”, “solvent-diffusion limited”, “electron-migration limited”, “interstitial-diffusion limited”, “ec reaction limited” , “VonKolzenberg2020”, “tunnelling limited”, or “ec reaction limited (asymmetric)”: pybamm.sei.SEIGrowth

“SEI film resistance”str
Set the submodel for additional term in the overpotential due to SEI. The default value is “none” if the “SEI” option is “none”, and “distributed” otherwise. This is because the “distributed” model is more complex than the model with no additional resistance, which adds unnecessary complexity if there is no SEI in the first place

“none”: no additional resistance
\[\eta_r = \frac{F}{RT} * (\phi_s - \phi_e - U)\]

“distributed”: properly included additional resistance term
\[\eta_r = \frac{F}{RT} * (\phi_s - \phi_e - U - R_{sei} * L_{sei} * j)\]

“average”: constant additional resistance term (approximation to the true model). This model can give similar results to the “distributed” case without needing to make j an algebraic state
\[\eta_r = \frac{F}{RT} * (\phi_s - \phi_e - U - R_{sei} * L_{sei} * \frac{I}{aL})\]

“SEI on cracks”str
Whether to include SEI growth on particle cracks, can be “false” (default) or “true”.

“SEI porosity change”str
Whether to include porosity change due to SEI formation, can be “false” (default) or “true”.

“stress-induced diffusion”str
Whether to include stress-induced diffusion, can be “false” or “true”. The default is “false” if “particle mechanics” is “none” and “true” otherwise. A 2-tuple can be provided for different behaviour in negative and positive electrodes.

“surface form”str
Whether to use the surface formulation of the problem. Can be “false” (default), “differential” or “algebraic”.

“surface temperature”str
Sets the surface temperature model to use. Can be “ambient” (default), which sets the surface temperature equal to the ambient temperature, or “lumped”, which adds an ODE for the surface temperature (e.g. to model internal heating of a thermal chamber).

“thermal”str
Sets the thermal model to use. Can be “isothermal” (default), “lumped”, “x-lumped”, or “x-full”. The ‘cell geometry’ option must be set to ‘pouch’ for ‘x-lumped’ or ‘x-full’ to be valid. Using the ‘x-lumped’ option with ‘dimensionality’ set to 0 is equivalent to using the ‘lumped’ option.

“total interfacial current density as a state”str
Whether to make a state for the total interfacial current density and solve an algebraic equation for it. Default is “false”, unless “SEI film resistance” is distributed in which case it is automatically set to “true”.

“voltage as a state”str
Whether to make a state for the voltage and solve an algebraic equation for it. Default is “false”.

“working electrode”str
Can be “both” (default) for a standard battery or “positive” for a half-cell where the negative electrode is replaced with a lithium metal counter electrode.

“x-average side reactions”: str
Whether to average the side reactions (SEI growth, lithium plating and the respective porosity change) over the x-axis in Single Particle Models, can be “false” or “true”. Default is “false” for SPMe and “true” for SPM.

“use lumped thermal capacity”str
Whether to use a lumped capacity model for the thermal model. Can be “false” (default) or “true”. This is only available for the lumped thermal model.

Type:: dict

Extends: pybamm.util.FuzzyDict

property negative#: Returns the options for the negative electrode

property positive#: Returns the options for the positive electrode

print_detailed_options()[source]#: Print the docstring for Options

print_options()[source]#: Print the possible options with the ones currently selected