PyBaMM documentation #

Convert to CasADi#

class pybamm.CasadiConverter(casadi_symbols=None)[source]#

convert(symbol, t, y, y_dot, inputs)[source]#

This function recurses down the tree, converting the PyBaMM expression tree to a CasADi expression tree

Parameters:

symbol (pybamm.Symbol) – The symbol to convert
t (casadi.MX) – A casadi symbol representing time
y (casadi.MX) – A casadi symbol representing state vectors
y_dot (casadi.MX) – A casadi symbol representing time derivatives of state vectors
inputs (dict) – A dictionary of casadi symbols representing parameters

Returns:

The converted symbol

Return type:

casadi.MX

Serialise#

class pybamm.expression_tree.operations.serialise.Serialise[source]#

Converts a discretised model to and from a JSON file.

load_model(filename: str, battery_model: BaseModel | None = None) → BaseModel[source]#

Loads a discretised, ready to solve model into PyBaMM.

A new pybamm battery model instance will be created, which can be solved and the results plotted as usual.

Currently only available for pybamm models which have previously been written out using the save_model() option.

Warning: This only loads in discretised models. If you wish to make edits to the model or initial conditions, a new model will need to be constructed seperately.

Parameters:

filename (str) – Path to the JSON file containing the serialised model file
battery_model (pybamm.BaseModel (optional)) – PyBaMM model to be created (e.g. pybamm.lithium_ion.SPM), which will override any model names within the file. If None, the function will look for the saved object path, present if the original model came from PyBaMM.

Returns:

A PyBaMM model object, of type specified either in the JSON or in battery_model.

Return type:

pybamm.BaseModel

save_model(model: BaseModel, mesh: Mesh | None = None, variables: FuzzyDict | None = None, filename: str | None = None)[source]#

Saves a discretised model to a JSON file.

As the model is discretised and ready to solve, only the right hand side, algebraic and initial condition variables are saved.

Parameters:

model (pybamm.BaseModel) – The discretised model to be saved
mesh (pybamm.Mesh (optional)) – The mesh the model has been discretised over. Not neccesary to solve the model when read in, but required to use pybamm’s plotting tools.
variables (pybamm.FuzzyDict (optional)) – The discretised model varaibles. Not necessary to solve a model, but required to use pybamm’s plotting tools.
filename (str (optional)) – The desired name of the JSON file. If no name is provided, one will be created based on the model name, and the current datetime.

Symbol Unpacker#

class pybamm.SymbolUnpacker(classes_to_find, unpacked_symbols=None)[source]#

Helper class to unpack a (set of) symbol(s) to find all instances of a class. Uses caching to speed up the process.

Parameters:

classes_to_find (list of pybamm classes) – Classes to identify in the equations
unpacked_symbols (set, optional) – cached unpacked equations

unpack_list_of_symbols(list_of_symbols)[source]#

Unpack a list of symbols. See SymbolUnpacker.unpack()

Parameters:: list_of_symbols (list of pybamm.Symbol) – List of symbols to unpack
Returns:: Set of unpacked symbols with class in self.classes_to_find
Return type:: list of pybamm.Symbol

unpack_symbol(symbol)[source]#

This function recurses down the tree, unpacking the symbols and saving the ones that have a class in self.classes_to_find.

Parameters:: symbol (list of pybamm.Symbol) – The symbols to unpack
Returns:: List of unpacked symbols with class in self.classes_to_find
Return type:: list of pybamm.Symbol

Models#

Below is an overview of all the battery models included in PyBaMM. Each of the pre-built models contains a reference to the paper in which it is derived.

The models can be customised using the options dictionary defined in the pybamm.BaseBatteryModel (which also provides information on which options and models are compatible) Visit our examples page to see how these models can be solved, and compared, using PyBaMM.

Base Models#

Base Model#

class pybamm.BaseModel(name='Unnamed model')[source]#

Base model class for other models to extend.

name#

A string giving the name of the model.

Type:: str

options#

A dictionary of options to be passed to the model.

Type:: dict

submodels#

A dictionary of submodels that the model is composed of.

Type:: dict

rhs#

A dictionary that maps expressions (variables) to expressions that represent the rhs.

Type:: dict

algebraic#

A dictionary that maps expressions (variables) to expressions that represent the algebraic equations. The algebraic expressions are assumed to equate to zero. Note that all the variables in the model must exist in the keys of rhs or algebraic.

Type:: dict

initial_conditions#

A dictionary that maps expressions (variables) to expressions that represent the initial conditions for the state variables y. The initial conditions for algebraic variables are provided as initial guesses to a root finding algorithm that calculates consistent initial conditions.

Type:: dict

boundary_conditions#

A dictionary that maps expressions (variables) to expressions that represent the boundary conditions.

Type:: dict

variables#

A dictionary that maps strings to expressions that represent the useful variables.

Type:: dict

events#

A list of events. Each event can either cause the solver to terminate (e.g. concentration goes negative), or be used to inform the solver of the existance of a discontinuity (e.g. discontinuity in the input current).

Type:: list of pybamm.Event

concatenated_rhs#

After discretisation, contains the expressions representing the rhs equations concatenated into a single expression.

Type:: pybamm.Concatenation

concatenated_algebraic#

After discretisation, contains the expressions representing the algebraic equations concatenated into a single expression.

Type:: pybamm.Concatenation

concatenated_initial_conditions#

After discretisation, contains the vector of initial conditions.

Type:: numpy.array

mass_matrix#

After discretisation, contains the mass matrix for the model. This is computed automatically.

Type:: pybamm.Matrix

mass_matrix_inv#

After discretisation, contains the inverse mass matrix for the differential (rhs) part of model. This is computed automatically.

Type:: pybamm.Matrix

jacobian#

Contains the Jacobian for the model. If model.use_jacobian is True, the Jacobian is computed automatically during solver set up.

Type:: pybamm.Concatenation

jacobian_rhs#

Contains the Jacobian for the part of the model which contains time derivatives. If model.use_jacobian is True, the Jacobian is computed automatically during solver set up.

Type:: pybamm.Concatenation

jacobian_algebraic#

Contains the Jacobian for the algebraic part of the model. This may be used by the solver when calculating consistent initial conditions. If model.use_jacobian is True, the Jacobian is computed automatically during solver set up.

Type:: pybamm.Concatenation

use_jacobian#

Whether to use the Jacobian when solving the model (default is True).

Type:: bool

convert_to_format#

Whether to convert the expression trees representing the rhs and algebraic equations, Jacobain (if using) and events into a different format:

None: keep PyBaMM expression tree structure.
“python”: convert into pure python code that will calculate the result of calling evaluate(t, y) on the given expression treeself.
“casadi”: convert into CasADi expression tree, which then uses CasADi’s algorithm to calculate the Jacobian.

Default is “casadi”.

Type:: str

check_algebraic_equations(post_discretisation)[source]#: Check that the algebraic equations are well-posed. After discretisation, there must be at least one StateVector in each algebraic equation.

check_discretised_or_discretise_inplace_if_0D()[source]#: Discretise model if it isn’t already discretised This only works with purely 0D models, as otherwise the mesh and spatial method should be specified by the user

check_ics_bcs()[source]#: Check that the initial and boundary conditions are well-posed.

check_no_repeated_keys()[source]#: Check that no equation keys are repeated.

check_well_determined(post_discretisation)[source]#: Check that the model is not under- or over-determined.

check_well_posedness(post_discretisation=False)[source]#

Check that the model is well-posed by executing the following tests: - Model is not over- or underdetermined, by comparing keys and equations in rhs and algebraic. Overdetermined if more equations than variables, underdetermined if more variables than equations. - There is an initial condition in self.initial_conditions for each variable/equation pair in self.rhs - There are appropriate boundary conditions in self.boundary_conditions for each variable/equation pair in self.rhs and self.algebraic

Parameters:: post_discretisation (boolean) – A flag indicating tests to be skipped after discretisation

property default_solver#: Return default solver based on whether model is ODE/DAE or algebraic

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

export_casadi_objects(variable_names, input_parameter_order=None)[source]#

Export the constituent parts of the model (rhs, algebraic, initial conditions, etc) as casadi objects.

Parameters:

variable_names (list) – Variables to be exported alongside the model structure
input_parameter_order (list, optional) – Order in which the input parameters should be stacked. If input_parameter_order=None and len(self.input_parameters) > 1, a ValueError is raised (this helps to avoid accidentally using the wrong order)

Returns:

casadi_dict – Dictionary of {str: casadi object} pairs representing the model in casadi format

Return type:

generate(filename, variable_names, input_parameter_order=None, cg_options=None)[source]#

Generate the model in C, using CasADi.

Parameters:

filename (str) – Name of the file to which to save the code
variable_names (list) – Variables to be exported alongside the model structure
input_parameter_order (list, optional) – Order in which the input parameters should be stacked. If input_parameter_order=None and len(self.input_parameters) > 1, a ValueError is raised (this helps to avoid accidentally using the wrong order)
cg_options (dict) – Options to pass to the code generator. See https://web.casadi.org/docs/#generating-c-code

get_parameter_info()[source]#: Extracts the parameter information and returns it as a dictionary. To get a list of all parameter-like objects without extra information, use model.parameters.

info(symbol_name)[source]#

Provides helpful summary information for a symbol.

Parameters:: parameter_name (str) –

property input_parameters#: Returns all the input parameters in the model

latexify(filename=None, newline=True, output_variables=None)[source]#

Converts all model equations in latex.

Parameters:

filename (str (optional)) – Accepted file formats - any image format, pdf and tex Default is None, When None returns all model equations in latex If not None, returns all model equations in given file format.
newline (bool (optional)) – Default is True, If True, returns every equation in a new line. If False, returns the list of all the equations.
model (Load) –
pybamm.lithium_ion.SPM() (>>> model =) –
png (This will returns all model equations in) –
model.latexify("equations.png") (>>>) –
latex (This will return all the model equations in) –
model.latexify() (>>>) –
equations (This will return first five model) –
model.latexify(newline=False) (>>>) –
equations –
model.latexify(newline=False)[1 (>>>) –

new_copy()[source]#: Creates a copy of the model, explicitly copying all the mutable attributes to avoid issues with shared objects.

property parameters#: Returns all the parameters in the model

print_parameter_info()[source]#: Print parameter information in a formatted table from a dictionary of parameters

process_parameters_and_discretise(symbol, parameter_values, disc)[source]#

Process parameters and discretise a symbol using supplied parameter values and discretisation. Note: care should be taken if using spatial operators on dimensional symbols. Operators in pybamm are written in non-dimensional form, so may need to be scaled by the appropriate length scale. It is recommended to use this method on non-dimensional symbols.

Parameters:

symbol (pybamm.Symbol) – Symbol to be processed
parameter_values (pybamm.ParameterValues) – The parameter values to use during processing
disc (pybamm.Discretisation) – The discrisation to use

Returns:

Processed symbol

Return type:

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_initial_conditions_from(solution, inplace=True, return_type='model')[source]#

Update initial conditions with the final states from a Solution object or from a dictionary. This assumes that, for each variable in self.initial_conditions, there is a corresponding variable in the solution with the same name and size.

Parameters:

solution (pybamm.Solution, or dict) – The solution to use to initialize the model
inplace (bool, optional) – Whether to modify the model inplace or create a new model (default True)
return_type (str, optional) – Whether to return the model (default) or initial conditions (“ics”)

update(*submodels)[source]#

Update model to add new physics from submodels

Parameters:: submodel (iterable of pybamm.BaseModel) – The submodels from which to create new model

property variables_and_events#: Returns variables and events in a single dictionary

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

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

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”, 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” 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”.

“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”.

“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.

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

Event#

class pybamm.Event(name, expression, event_type=EventType.TERMINATION)[source]#

Defines an event for use within a pybamm model

name#

A string giving the name of the event.

Type:: str

expression#

An expression that defines when the event occurs.

Type:: pybamm.Symbol

event_type#

An enum defining the type of event. By default it is set to TERMINATION.

Type:: pybamm.EventType (optional)

evaluate(t=None, y=None, y_dot=None, inputs=None)[source]#: Acts as a drop-in replacement for pybamm.Symbol.evaluate()

to_json()[source]#

Method to serialise an Event object into JSON.

The expression is written out seperately, See pybamm.Serialise._SymbolEncoder.default()

class pybamm.EventType(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Defines the type of event, see pybamm.Event

TERMINATION indicates an event that will terminate the solver, the expression should return 0 when the event is triggered

DISCONTINUITY indicates an expected discontinuity in the solution, the expression should return the time that the discontinuity occurs. The solver will integrate up to the discontinuity and then restart just after the discontinuity.

INTERPOLANT_EXTRAPOLATION indicates that a pybamm.Interpolant object has been evaluated outside of the range.

SWITCH indicates an event switch that is used in CasADI “fast with events” model.

Extends: enum.Enum

Lithium-ion Models#

Base Lithium-ion Model#

class pybamm.lithium_ion.BaseModel(options=None, name='Unnamed lithium-ion model', build=False)#

Overwrites default parameters from Base Model with default parameters for lithium-ion models

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”.
build (bool, optional) – Whether to build the model on instantiation. Default is True. Setting this option to False allows users to change any number of the submodels before building the complete model (submodels cannot be changed after the model is built).

Extends: pybamm.models.full_battery_models.base_battery_model.BaseBatteryModel

insert_reference_electrode(position=None)#

Insert a reference electrode to measure the electrolyte potential at a given position in space. Adds model variables for the electrolyte potential at the reference electrode and for the potential difference between the electrode potentials measured at the electrode/current collector interface and the reference electrode. Only implemented for 1D models (i.e. where the ‘dimensionality’ option is 0).

Parameters:: position (pybamm.Symbol, optional) – The position in space at which to measure the electrolyte potential. If None, defaults to the mid-point of the separator.

set_degradation_variables()#: Sets variables that quantify degradation (LAM, LLI, etc)

set_summary_variables()#: Sets the default summary variables.

Single Particle Model (SPM)#

class pybamm.lithium_ion.SPM(options=None, name='Single Particle Model', build=True)#

Single Particle Model (SPM) of a lithium-ion battery, from Marquis et al.[1]. See pybamm.lithium_ion.BaseModel for more details.

Examples

>>> model = pybamm.lithium_ion.SPM()
>>> model.name
'Single Particle Model'

Extends: pybamm.models.full_battery_models.lithium_ion.base_lithium_ion_model.BaseModel

class pybamm.lithium_ion.BasicSPM(name='Single Particle Model')#

Single Particle Model (SPM) model of a lithium-ion battery, from Marquis et al.[1].

This class differs from the pybamm.lithium_ion.SPM model class in that it shows the whole model in a single class. This comes at the cost of flexibility in combining different physical effects, and in general the main SPM class should be used instead.

Parameters:: name (str, optional) – The name of the model.

Extends: pybamm.models.full_battery_models.lithium_ion.base_lithium_ion_model.BaseModel

References

Single Particle Model with Electrolyte (SPMe)#

class pybamm.lithium_ion.SPMe(options=None, name='Single Particle Model with electrolyte', build=True)#

Single Particle Model with Electrolyte (SPMe) of a lithium-ion battery, from Marquis et al.[1]. Inherits most submodels from SPM, only modifies potentials and electrolyte. See pybamm.lithium_ion.BaseModel for more details.

Examples

>>> model = pybamm.lithium_ion.SPMe()
>>> model.name
'Single Particle Model with electrolyte'

Extends: pybamm.models.full_battery_models.lithium_ion.spm.SPM

References

Many Particle Model (MPM)#

class pybamm.lithium_ion.MPM(options=None, name='Many-Particle Model', build=True)#

Many-Particle Model (MPM) of a lithium-ion battery with particle-size distributions for each electrode, from Kirk et al.[1]. See pybamm.lithium_ion.BaseModel for more details.

Examples

>>> model = pybamm.lithium_ion.MPM()
>>> model.name
'Many-Particle Model'

Extends: pybamm.models.full_battery_models.lithium_ion.spm.SPM

References

Doyle-Fuller-Newman (DFN)#

class pybamm.lithium_ion.DFN(options=None, name='Doyle-Fuller-Newman model', build=True)#

Doyle-Fuller-Newman (DFN) model of a lithium-ion battery, from Marquis et al.[1]. See pybamm.lithium_ion.BaseModel for more details.

Examples

>>> model = pybamm.lithium_ion.DFN()
>>> model.name
'Doyle-Fuller-Newman model'

Extends: pybamm.models.full_battery_models.lithium_ion.base_lithium_ion_model.BaseModel

class pybamm.lithium_ion.BasicDFN(name='Doyle-Fuller-Newman model')#

Doyle-Fuller-Newman (DFN) model of a lithium-ion battery, from Marquis et al.[1].

This class differs from the pybamm.lithium_ion.DFN model class in that it shows the whole model in a single class. This comes at the cost of flexibility in comparing different physical effects, and in general the main DFN class should be used instead.

Parameters:: name (str, optional) – The name of the model.

Extends: pybamm.models.full_battery_models.lithium_ion.base_lithium_ion_model.BaseModel

class pybamm.lithium_ion.BasicDFNComposite(name='Composite graphite/silicon Doyle-Fuller-Newman model')#

Doyle-Fuller-Newman (DFN) model of a lithium-ion battery with composite particles of graphite and silicon, from Ai et al.[2].

Parameters:: name (str, optional) – The name of the model.

Extends: pybamm.models.full_battery_models.lithium_ion.base_lithium_ion_model.BaseModel

class pybamm.lithium_ion.BasicDFNHalfCell(options=None, name='Doyle-Fuller-Newman half cell model')#

Doyle-Fuller-Newman (DFN) model of a lithium-ion battery with lithium counter electrode, adapted from Doyle et al.[3].

This class differs from the pybamm.lithium_ion.BasicDFN model class in that it is for a cell with a lithium counter electrode (half cell). This is a feature under development (for example, it cannot be used with the Experiment class for the moment) and in the future it will be incorporated as a standard model with the full functionality.

The electrode labeled “positive electrode” is the working electrode, and the electrode labeled “negative electrode” is the counter electrode. This facilitates compatibility with the full-cell models.

Parameters:

options (dict) – A dictionary of options to be passed to the model. For the half cell it should include which is the working electrode.
name (str, optional) – The name of the model.

Extends: pybamm.models.full_battery_models.lithium_ion.base_lithium_ion_model.BaseModel

References

Newman-Tobias#

class pybamm.lithium_ion.NewmanTobias(options=None, name='Newman-Tobias model', build=True)#

Newman-Tobias model of a lithium-ion battery based on the formulation in Newman and Tobias[1]. This model assumes a uniform concentration profile in the electrolyte. Unlike the model posed in Newman and Tobias[1], this model accounts for nonlinear Butler-Volmer kinetics. It also tracks the average concentration in the solid phase in each electrode, which is equivalent to including an equation for the local state of charge as in Chu et al.[2]. The user can pass the “particle” option to include mass transport in the particles.

See pybamm.lithium_ion.BaseModel for more details.

Extends: pybamm.models.full_battery_models.lithium_ion.dfn.DFN

References

Multi-Species Multi-Reaction (MSMR) Model#

class pybamm.lithium_ion.MSMR(options=None, name='MSMR', build=True)#: View inheritance diagram for this model

Yang et al 2017#

class pybamm.lithium_ion.Yang2017(options=None, name='Yang2017', build=True)#: View inheritance diagram for this model

Electrode SOH models#

class pybamm.lithium_ion.ElectrodeSOHSolver(parameter_values, param=None, known_value='cyclable lithium capacity', options=None)#

Class used to check if the electrode SOH model is feasible, and solve it if it is.

Parameters:

parameter_values (pybamm.ParameterValues.Parameters) – The parameters of the simulation
param (pybamm.LithiumIonParameters, optional) – Specific instance of the symbolic lithium-ion parameter class. If not provided, the default set of symbolic lithium-ion parameters will be used.
known_value (str, optional) – The known value needed to complete the electrode SOH model. Can be “cyclable lithium capacity” (default) or “cell capacity”.
options (dict-like, optional) – A dictionary of options to be passed to the model, see pybamm.BatteryModelOptions.

get_initial_ocps(initial_value)#

Calculate initial open-circuit potentials to start off the simulation at a particular state of charge, given voltage limits, open-circuit potentials, etc defined by parameter_values

Parameters:: initial_value (float) – Target SOC, must be between 0 and 1.
Returns:: The initial open-circuit potentials at the desired initial state of charge
Return type:: Un, Up

get_initial_stoichiometries(initial_value)#

Calculate initial stoichiometries to start off the simulation at a particular state of charge, given voltage limits, open-circuit potentials, etc defined by parameter_values

Parameters:: initial_value (float) – Target initial value. If integer, interpreted as SOC, must be between 0 and 1. If string e.g. “4 V”, interpreted as voltage, must be between V_min and V_max.
Returns:: The initial stoichiometries that give the desired initial state of charge
Return type:: x, y

get_min_max_ocps()#

Calculate min/max open-circuit potentials given voltage limits, open-circuit potentials, etc defined by parameter_values

Returns:: The min/max ocps
Return type:: Un_0, Un_100, Up_100, Up_0

get_min_max_stoichiometries()#

Calculate min/max stoichiometries given voltage limits, open-circuit potentials, etc defined by parameter_values

Returns:: The min/max stoichiometries
Return type:: x_0, x_100, y_100, y_0

pybamm.lithium_ion.get_initial_stoichiometries(initial_value, parameter_values, param=None, known_value='cyclable lithium capacity', options=None)#

Calculate initial stoichiometries to start off the simulation at a particular state of charge, given voltage limits, open-circuit potentials, etc defined by parameter_values

Parameters:

initial_value (float) – Target initial value. If integer, interpreted as SOC, must be between 0 and 1. If string e.g. “4 V”, interpreted as voltage, must be between V_min and V_max.
parameter_values (pybamm.ParameterValues) – The parameter values class that will be used for the simulation. Required for calculating appropriate initial stoichiometries.
param (pybamm.LithiumIonParameters, optional) – The symbolic parameter set to use for the simulation. If not provided, the default parameter set will be used.
known_value (str, optional) – The known value needed to complete the electrode SOH model. Can be “cyclable lithium capacity” (default) or “cell capacity”.
options (dict-like, optional) – A dictionary of options to be passed to the model, see pybamm.BatteryModelOptions.

Returns:

The initial stoichiometries that give the desired initial state of charge

Return type:

x, y

pybamm.lithium_ion.get_min_max_stoichiometries(parameter_values, param=None, known_value='cyclable lithium capacity', options=None)#

Calculate min/max stoichiometries given voltage limits, open-circuit potentials, etc defined by parameter_values

Parameters:

parameter_values (pybamm.ParameterValues) – The parameter values class that will be used for the simulation. Required for calculating appropriate initial stoichiometries.
param (pybamm.LithiumIonParameters, optional) – The symbolic parameter set to use for the simulation. If not provided, the default parameter set will be used.
known_value (str, optional) – The known value needed to complete the electrode SOH model. Can be “cyclable lithium capacity” (default) or “cell capacity”.
options (dict-like, optional) – A dictionary of options to be passed to the model, see pybamm.BatteryModelOptions.

Returns:

The min/max stoichiometries

Return type:

x_0, x_100, y_100, y_0

pybamm.lithium_ion.get_initial_ocps(initial_value, parameter_values, param=None, known_value='cyclable lithium capacity', options=None)#

Calculate initial open-circuit potentials to start off the simulation at a particular state of charge, given voltage limits, open-circuit potentials, etc defined by parameter_values

Parameters:

initial_value (float) – Target initial value. If integer, interpreted as SOC, must be between 0 and 1. If string e.g. “4 V”, interpreted as voltage, must be between V_min and V_max.
parameter_values (pybamm.ParameterValues) – The parameter values class that will be used for the simulation. Required for calculating appropriate initial stoichiometries.
param (pybamm.LithiumIonParameters, optional) – The symbolic parameter set to use for the simulation. If not provided, the default parameter set will be used.
known_value (str, optional) – The known value needed to complete the electrode SOH model. Can be “cyclable lithium capacity” (default) or “cell capacity”.
options (dict-like, optional) – A dictionary of options to be passed to the model, see pybamm.BatteryModelOptions.

Returns:

The initial electrode OCPs that give the desired initial state of charge

Return type:

Un, Up

pybamm.lithium_ion.get_min_max_ocps(parameter_values, param=None, known_value='cyclable lithium capacity', options=None)#

Calculate min/max open-circuit potentials given voltage limits, open-circuit potentials, etc defined by parameter_values

Parameters:

parameter_values (pybamm.ParameterValues) – The parameter values class that will be used for the simulation. Required for calculating appropriate initial open-circuit potentials.
param (pybamm.LithiumIonParameters, optional) – The symbolic parameter set to use for the simulation. If not provided, the default parameter set will be used.
known_value (str, optional) – The known value needed to complete the electrode SOH model. Can be “cyclable lithium capacity” (default) or “cell capacity”.
options (dict-like, optional) – A dictionary of options to be passed to the model, see pybamm.BatteryModelOptions.

Returns:

The min/max OCPs

Return type:

Un_0, Un_100, Up_100, Up_0

Lead Acid Models#

Base Model#

class pybamm.lead_acid.BaseModel(options=None, name='Unnamed lead-acid model', build=False)#

Overwrites default parameters from Base Model with default parameters for lead-acid models

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”.
build (bool, optional) – Whether to build the model on instantiation. Default is True. Setting this option to False allows users to change any number of the submodels before building the complete model (submodels cannot be changed after the model is built).

Extends: pybamm.models.full_battery_models.base_battery_model.BaseBatteryModel

set_soc_variables()#: Set variables relating to the state of charge.

Leading-Order Quasi-Static Model#

class pybamm.lead_acid.LOQS(options=None, name='LOQS model', build=True)#

Leading-Order Quasi-Static model for lead-acid, from Sulzer et al.[1]. See pybamm.lead_acid.BaseModel for more details.

Extends: pybamm.models.full_battery_models.lead_acid.base_lead_acid_model.BaseModel

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

References

Full Model#

class pybamm.lead_acid.Full(options=None, name='Full model', build=True)#

Porous electrode model for lead-acid, from Sulzer et al.[1], based on the Newman-Tiedemann model. See pybamm.lead_acid.BaseModel for more details.

Extends: pybamm.models.full_battery_models.lead_acid.base_lead_acid_model.BaseModel

class pybamm.lead_acid.BasicFull(name='Basic full model')#

Porous electrode model for lead-acid, from Sulzer et al.[1].

This class differs from the pybamm.lead_acid.Full model class in that it shows the whole model in a single class. This comes at the cost of flexibility in comparing different physical effects, and in general the main DFN class should be used instead.

Parameters:: name (str, optional) – The name of the model.

Extends: pybamm.models.full_battery_models.lead_acid.base_lead_acid_model.BaseModel

References

Equivalent Circuit Models#

Thevenin Model#

class pybamm.equivalent_circuit.Thevenin(name='Thevenin Equivalent Circuit Model', options=None, build=True)#

The classical Thevenin Equivalent Circuit Model of a battery as described in, for example, Barletta et al.[1].

This equivalent circuit model consists of an OCV element, a resistor element, and a number of RC elements (by default 1). The model is coupled to two lumped thermal models, one for the cell and one for the surrounding jig. Heat generation terms for each element follow equation (1) of Nieto et al.[2].

Parameters:

name (str, optional) – The name of the model. The default is “Thevenin Equivalent Circuit Model”.
options (dict, optional) –
A dictionary of options to be passed to the model. The default is None. Possible options are:
- ”number of rc elements”str
  The number of RC elements to be added to the model. The default is 1.
- ”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.
- ”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
  
  ”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.
build (bool, optional) – Whether to build the model on instantiation. Default is True. Setting this option to False allows users to change any number of the submodels before building the complete model (submodels cannot be changed after the model is built).

Examples

>>> model = pybamm.equivalent_circuit.Thevenin()
>>> model.name
'Thevenin Equivalent Circuit Model'

Extends: pybamm.models.base_model.BaseModel

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

References

Submodels#

Base Submodel#

class pybamm.BaseSubModel(param, domain=None, name='Unnamed submodel', external=False, options=None, phase=None)[source]#

The base class for all submodels. All submodels inherit from this class and must only provide public methods which overwrite those in this base class. Any methods added to a submodel that do not overwrite those in this bass class are made private with the prefix ‘_’, providing a consistent public interface for all submodels.

Parameters:

param (parameter class) – The model parameter symbols
domain (str) – The domain of the model either ‘Negative’ or ‘Positive’
name (str) – A string giving the name of the submodel
external (bool, optional) – Whether the variables defined by the submodel will be provided externally by the users. Default is ‘False’.
options (dict) – A dictionary of options to be passed to the model. See pybamm.BaseBatteryModel
phase (str, optional) – Phase of the particle (default is None).

param#

The model parameter symbols

Type:: parameter class

rhs#

A dictionary that maps expressions (variables) to expressions that represent the rhs

Type:: dict

algebraic#

Type:: dict

initial_conditions#

Type:: dict

boundary_conditions#

A dictionary that maps expressions (variables) to expressions that represent the boundary conditions

Type:: dict

variables#

A dictionary that maps strings to expressions that represent the useful variables

Type:: dict

events#

Type:: list

Extends: pybamm.models.base_model.BaseModel

get_coupled_variables(variables)[source]#

A public method that creates and returns the variables in a submodel which require variables in other submodels to be set first. For example, the exchange current density requires the concentration in the electrolyte to be created before it can be created. If a variable can be created independent of other submodels then it should be created in ‘get_fundamental_variables’ instead of this method.

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()[source]#

A public method that creates and returns the variables in a submodel which can be created independent of other submodels. For example, the electrolyte concentration variables can be created independent of whether any other variables have been defined in the model. As a rule, if a variable can be created without variables from other submodels, then it should be placed in this method.

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_algebraic(variables)[source]#

A method to set the differential equations which do not contain a time derivative. Note: this method modifies the state of self.algebraic. Unless overwritten by a submodel, the default behaviour of ‘pass’ is used as implemented in pybamm.BaseSubModel.

Parameters:: variables (dict) – The variables in the whole model.

set_boundary_conditions(variables)[source]#

A method to set the boundary conditions for the submodel. Note: this method modifies the state of self.boundary_conditions. Unless overwritten by a submodel, the default behaviour of ‘pass’ is used as implemented in pybamm.BaseSubModel.

Parameters:: variables (dict) – The variables in the whole model.

set_events(variables)[source]#

A method to set events related to the state of submodel variable. Note: this method modifies the state of self.events. Unless overwritten by a submodel, the default behaviour of ‘pass’ is used as implemented in pybamm.BaseSubModel.

Parameters:: variables (dict) – The variables in the whole model.

set_initial_conditions(variables)[source]#

A method to set the initial conditions for the submodel. Note: this method modifies the state of self.initial_conditions. Unless overwritten by a submodel, the default behaviour of ‘pass’ is used as implemented in pybamm.BaseSubModel.

Parameters:: variables (dict) – The variables in the whole model.

set_rhs(variables)[source]#

A method to set the right hand side of the differential equations which contain a time derivative. Note: this method modifies the state of self.rhs. Unless overwritten by a submodel, the default behaviour of ‘pass’ is used as implemented in pybamm.BaseSubModel.

Parameters:: variables (dict) – The variables in the whole model.

Active Material#

Submodels for (loss of) active material

Base Model#

class pybamm.active_material.BaseModel(param, domain, options, phase='primary')#

Base class for active material volume fraction

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str) – The domain of the model either ‘Negative’ or ‘Positive’
options (dict) – Additional options to pass to the model
phase (str, optional) – Phase of the particle (default is “primary”)

Extends: pybamm.models.submodels.base_submodel.BaseSubModel

Constant Active Material#

class pybamm.active_material.Constant(param, domain, options, phase='primary')#

Submodel for constant active material

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str) – The domain of the model either ‘Negative’ or ‘Positive’
options (dict) – Additional options to pass to the model
phase (str, optional) – Phase of the particle (default is “primary”)

Extends: pybamm.models.submodels.active_material.base_active_material.BaseModel

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

Loss of Active Material#

class pybamm.active_material.LossActiveMaterial(param, domain, options, x_average)#

Submodel for varying active material volume fraction from Ai et al.[1] and Reniers et al.[2].

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str) – The domain of the model either ‘Negative’ or ‘Positive’
options (dict) – Additional options to pass to the model
x_average (bool) – Whether to use x-averaged variables (SPM, SPMe, etc) or full variables (DFN)

Extends: pybamm.models.submodels.active_material.base_active_material.BaseModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

References

Current Collector#

Base Model#

class pybamm.current_collector.BaseModel(param)#

Base class for current collector submodels

Parameters:: param (parameter class) – The parameters to use for this submodel

Extends: pybamm.models.submodels.base_submodel.BaseSubModel

Effective Current collector Resistance models#

class pybamm.current_collector.EffectiveResistance(options=None, name='Effective resistance in current collector model')#

A model which calculates the effective Ohmic resistance of the current collectors in the limit of large electrical conductivity. For details see Timms et al.[1]. Note that this formulation assumes uniform potential across the tabs. See pybamm.AlternativeEffectiveResistance2D for the formulation that assumes a uniform current density at the tabs (in 1D the two formulations are equivalent).

Parameters:

options (dict) –
A dictionary of options to be passed to the model. The options that can be set are listed below.
- ”dimensionality”int, optional
  Sets the dimension of the current collector problem. Can be 1 (default) or 2.
name (str, optional) – The name of the model.

Extends: pybamm.models.submodels.current_collector.effective_resistance_current_collector.BaseEffectiveResistance

post_process(solution, param_values, V_av, I_av)#: Calculates the potentials in the current collector and the terminal voltage given the average voltage and current. Note: This takes in the processed V_av and I_av from a 1D simulation representing the average cell behaviour and returns a dictionary of processed potentials.

class pybamm.current_collector.AlternativeEffectiveResistance2D#

A model which calculates the effective Ohmic resistance of the 2D current collectors in the limit of large electrical conductivity. This model assumes a uniform current density at the tabs and the solution is computed by first solving and auxilliary problem which is the related to the resistances.

Extends: pybamm.models.submodels.current_collector.effective_resistance_current_collector.BaseEffectiveResistance

post_process(solution, param_values, V_av, I_av)#: Calculates the potentials in the current collector given the average voltage and current. Note: This takes in the processed V_av and I_av from a 1D simulation representing the average cell behaviour and returns a dictionary of processed potentials.

References

Uniform#

class pybamm.current_collector.Uniform(param)#

A submodel for uniform potential in the current collectors which is valid in the limit of fast conductivity in the current collectors.

Parameters:: param (parameter class) – The parameters to use for this submodel

Extends: pybamm.models.submodels.current_collector.base_current_collector.BaseModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

Potential Pair models#

class pybamm.current_collector.BasePotentialPair(param)#

A submodel for Ohm’s law plus conservation of current in the current collectors. For details on the potential pair formulation see Timms et al.[1] and Marquis[2].

Parameters:: param (parameter class) – The parameters to use for this submodel

Extends: pybamm.models.submodels.current_collector.base_current_collector.BaseModel

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_algebraic(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

class pybamm.current_collector.PotentialPair2plus1D(param)#

Base class for a 2+1D potential pair model

Extends: pybamm.models.submodels.current_collector.potential_pair.BasePotentialPair

set_boundary_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

class pybamm.current_collector.PotentialPair1plus1D(param)#

Base class for a 1+1D potential pair model.

Extends: pybamm.models.submodels.current_collector.potential_pair.BasePotentialPair

set_boundary_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

References

Convection#

The convection submodels are split up into “through-cell”, which is the x-direction problem in the electrode domains, and “transverse”, which is the z-direction problem in the separator domain

Base Convection#

class pybamm.convection.BaseModel(param, options=None)#

Base class for convection submodels.

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.base_submodel.BaseSubModel

Through-cell Convection#

Base Model#

class pybamm.convection.through_cell.BaseThroughCellModel(param, options=None)#

Base class for convection submodels in the through-cell direction.

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.convection.base_convection.BaseModel

No Convection#

class pybamm.convection.through_cell.NoConvection(param, options=None)#

A submodel for case where there is no convection.

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.convection.through_cell.base_through_cell_convection.BaseThroughCellModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

Leading-Order Through-cell Model#

class pybamm.convection.through_cell.Explicit(param)#

A submodel for the leading-order approximation of pressure-driven convection

Parameters:: param (parameter class) – The parameters to use for this submodel

Extends: pybamm.models.submodels.convection.through_cell.base_through_cell_convection.BaseThroughCellModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

Full Through-cell Model#

class pybamm.convection.through_cell.Full(param)#

Submodel for the full model of pressure-driven convection

Parameters:: param (parameter class) – The parameters to use for this submodel

Extends: pybamm.models.submodels.convection.through_cell.base_through_cell_convection.BaseThroughCellModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_algebraic(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_boundary_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

Transverse Convection#

Base Model#

class pybamm.convection.transverse.BaseTransverseModel(param, options=None)#

Base class for convection submodels in transverse directions.

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.convection.base_convection.BaseModel

No Transverse Convection#

class pybamm.convection.transverse.NoConvection(param, options=None)#

Submodel for no convection in transverse directions

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.convection.transverse.base_transverse_convection.BaseTransverseModel

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

Uniform Transverse Model#

class pybamm.convection.transverse.Uniform(param)#

Submodel for uniform convection in transverse directions

Parameters:: param (parameter class) – The parameters to use for this submodel

Extends: pybamm.models.submodels.convection.transverse.base_transverse_convection.BaseTransverseModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

Full Transverse Convection#

class pybamm.convection.transverse.Full(param)#

Submodel for the full model of pressure-driven convection in transverse directions

Parameters:: param (parameter class) – The parameters to use for this submodel

Extends: pybamm.models.submodels.convection.transverse.base_transverse_convection.BaseTransverseModel

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_algebraic(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_boundary_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

Electrode#

Electrode Base Model#

class pybamm.electrode.BaseElectrode(param, domain, options=None, set_positive_potential=True)#

Base class for electrode submodels.

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str) – Either ‘negative’ or ‘positive’
options (dict, optional) – A dictionary of options to be passed to the model.
set_positive_potential (bool, optional) – If True the battery model sets the positive potential based on the current. If False, the potential is specified by the user. Default is True.

Extends: pybamm.models.submodels.base_submodel.BaseSubModel

Ohmic#

Base Model#

class pybamm.electrode.ohm.BaseModel(param, domain, options=None, set_positive_potential=True)#

A base class for electrode submodels that employ Ohm’s law.

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str) – Either ‘negative’ or ‘positive’
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.electrode.base_electrode.BaseElectrode

set_boundary_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

Leading Order Model#

class pybamm.electrode.ohm.LeadingOrder(param, domain, options=None, set_positive_potential=True)#

An electrode submodel that employs Ohm’s law the leading-order approximation to governing equations.

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str) – Either ‘negative’ or ‘positive’
options (dict, optional) – A dictionary of options to be passed to the model.
set_positive_potential (bool, optional) – If True the battery model sets the positve potential based on the current. If False, the potential is specified by the user. Default is True.

Extends: pybamm.models.submodels.electrode.ohm.base_ohm.BaseModel

get_coupled_variables(variables)#: Returns variables which are derived from the fundamental variables in the model.

set_boundary_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

Composite Model#

class pybamm.electrode.ohm.Composite(param, domain, options=None)#

An explicit composite leading and first order solution to solid phase current conservation with ohm’s law. Note that the returned current density is only the leading order approximation.

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str) – Either ‘Negative electrode’ or ‘Positive electrode’
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.electrode.ohm.base_ohm.BaseModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

set_boundary_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

Full Model#

class pybamm.electrode.ohm.Full(param, domain, options=None)#

Full model of electrode employing Ohm’s law.

Extends: pybamm.models.submodels.electrode.ohm.base_ohm.BaseModel

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str) – Either ‘negative’ or ‘positive’
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.electrode.ohm.base_ohm.BaseModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_algebraic(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_boundary_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

Surface Form#

class pybamm.electrode.ohm.SurfaceForm(param, domain, options=None)#

A submodel for the electrode with Ohm’s law in the surface potential formulation.

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str) – Either ‘negative’ or ‘positive’
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.electrode.ohm.base_ohm.BaseModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

Explicit potential drop for lithium metal#

class pybamm.electrode.ohm.LithiumMetalExplicit(param, domain, options=None)#

Explicit model for potential drop across a lithium metal electrode.

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.electrode.ohm.li_metal.LithiumMetalBaseModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

Electrolyte Conductivity#

Base Electrolyte Conductivity Submodel#

class pybamm.electrolyte_conductivity.BaseElectrolyteConductivity(param, domain=None, options=None)#

Base class for conservation of charge in the electrolyte.

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str, optional) – The domain in which the model holds
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.base_submodel.BaseSubModel

set_boundary_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

Leading Order Model#

class pybamm.electrolyte_conductivity.LeadingOrder(param, domain=None, options=None)#

Leading-order model for conservation of charge in the electrolyte employing the Stefan-Maxwell constitutive equations. (Leading refers to leading-order in the asymptotic reduction)

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str, optional) – The domain in which the model holds
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.electrolyte_conductivity.base_electrolyte_conductivity.BaseElectrolyteConductivity

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

Composite Model#

class pybamm.electrolyte_conductivity.Composite(param, domain=None, options=None)#

Base class for conservation of charge in the electrolyte employing the Stefan-Maxwell constitutive equations.

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str, optional) – The domain in which the model holds
options (dict, optional) – A dictionary of options to be passed to the model.
higher_order_terms (str) – What kind of higher-order terms to use (‘composite’ or ‘first-order’)

Extends: pybamm.models.submodels.electrolyte_conductivity.base_electrolyte_conductivity.BaseElectrolyteConductivity

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

Integrated Model#

class pybamm.electrolyte_conductivity.Integrated(param, domain=None, options=None)#

Integrated model for conservation of charge in the electrolyte derived from integrating the Stefan-Maxwell constitutive equations, from Brosa Planella et al.[1].

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str, optional) – The domain in which the model holds
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.electrolyte_conductivity.base_electrolyte_conductivity.BaseElectrolyteConductivity

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

References

Full Model#

class pybamm.electrolyte_conductivity.Full(param, options=None)#

Full model for conservation of charge in the electrolyte employing the Stefan-Maxwell constitutive equations. (Full refers to unreduced by asymptotic methods)

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.electrolyte_conductivity.base_electrolyte_conductivity.BaseElectrolyteConductivity

check_algebraic_equations(post_discretisation)#: Check that the algebraic equations are well-posed. After discretisation, there must be at least one StateVector in each algebraic equation.

check_discretised_or_discretise_inplace_if_0D()#: Discretise model if it isn’t already discretised This only works with purely 0D models, as otherwise the mesh and spatial method should be specified by the user

check_ics_bcs()#: Check that the initial and boundary conditions are well-posed.

check_no_repeated_keys()#: Check that no equation keys are repeated.

check_well_determined(post_discretisation)#: Check that the model is not under- or over-determined.

check_well_posedness(post_discretisation=False)#

Parameters:: post_discretisation (boolean) – A flag indicating tests to be skipped after discretisation

property default_solver#: Return default solver based on whether model is ODE/DAE or algebraic

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

export_casadi_objects(variable_names, input_parameter_order=None)#

Export the constituent parts of the model (rhs, algebraic, initial conditions, etc) as casadi objects.

Parameters:

variable_names (list) – Variables to be exported alongside the model structure
input_parameter_order (list, optional) – Order in which the input parameters should be stacked. If input_parameter_order=None and len(self.input_parameters) > 1, a ValueError is raised (this helps to avoid accidentally using the wrong order)

Returns:

casadi_dict – Dictionary of {str: casadi object} pairs representing the model in casadi format

Return type:

generate(filename, variable_names, input_parameter_order=None, cg_options=None)#

Generate the model in C, using CasADi.

Parameters:

filename (str) – Name of the file to which to save the code
variable_names (list) – Variables to be exported alongside the model structure
input_parameter_order (list, optional) – Order in which the input parameters should be stacked. If input_parameter_order=None and len(self.input_parameters) > 1, a ValueError is raised (this helps to avoid accidentally using the wrong order)
cg_options (dict) – Options to pass to the code generator. See https://web.casadi.org/docs/#generating-c-code

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

get_parameter_info()#: Extracts the parameter information and returns it as a dictionary. To get a list of all parameter-like objects without extra information, use model.parameters.

info(symbol_name)#

Provides helpful summary information for a symbol.

Parameters:: parameter_name (str) –

property input_parameters#: Returns all the input parameters in the model

latexify(filename=None, newline=True, output_variables=None)#

Converts all model equations in latex.

Parameters:

filename (str (optional)) – Accepted file formats - any image format, pdf and tex Default is None, When None returns all model equations in latex If not None, returns all model equations in given file format.
newline (bool (optional)) – Default is True, If True, returns every equation in a new line. If False, returns the list of all the equations.
model (Load) –
pybamm.lithium_ion.SPM() (>>> model =) –
png (This will returns all model equations in) –
model.latexify("equations.png") (>>>) –
latex (This will return all the model equations in) –
model.latexify() (>>>) –
equations (This will return first five model) –
model.latexify(newline=False) (>>>) –
equations –
model.latexify(newline=False)[1 (>>>) –

new_copy()#: Creates a copy of the model, explicitly copying all the mutable attributes to avoid issues with shared objects.

property parameters#: Returns all the parameters in the model

print_parameter_info()#: Print parameter information in a formatted table from a dictionary of parameters

process_parameters_and_discretise(symbol, parameter_values, disc)#

Parameters:

symbol (pybamm.Symbol) – Symbol to be processed
parameter_values (pybamm.ParameterValues) – The parameter values to use during processing
disc (pybamm.Discretisation) – The discrisation to use

Returns:

Processed symbol

Return type:

save_model(filename=None, mesh=None, variables=None)#

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_algebraic(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_boundary_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_events(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_initial_conditions_from(solution, inplace=True, return_type='model')#

Parameters:

solution (pybamm.Solution, or dict) – The solution to use to initialize the model
inplace (bool, optional) – Whether to modify the model inplace or create a new model (default True)
return_type (str, optional) – Whether to return the model (default) or initial conditions (“ics”)

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

update(*submodels)#

Update model to add new physics from submodels

Parameters:: submodel (iterable of pybamm.BaseModel) – The submodels from which to create new model

property variables_and_events#: Returns variables and events in a single dictionary

Surface Form#

Full Model#

class pybamm.electrolyte_conductivity.surface_potential_form.FullDifferential(param, domain, options=None)#

Full model for conservation of charge in the electrolyte employing the Stefan-Maxwell constitutive equations and where capacitance is present. (Full refers to unreduced by asymptotic methods)

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.electrolyte_conductivity.surface_potential_form.full_surface_form_conductivity.BaseModel

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

class pybamm.electrolyte_conductivity.surface_potential_form.FullAlgebraic(param, domain, options=None)#

Full model for conservation of charge in the electrolyte employing the Stefan-Maxwell constitutive equations. (Full refers to unreduced by asymptotic methods)

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.electrolyte_conductivity.surface_potential_form.full_surface_form_conductivity.BaseModel

set_algebraic(variables)#

Parameters:: variables (dict) – The variables in the whole model.

Leading Order Model#

class pybamm.electrolyte_conductivity.surface_potential_form.LeadingOrderDifferential(param, domain, options=None)#

Leading-order model for conservation of charge in the electrolyte employing the Stefan-Maxwell constitutive equations employing the surface potential difference formulation and where capacitance is present.

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.electrolyte_conductivity.surface_potential_form.leading_surface_form_conductivity.BaseLeadingOrderSurfaceForm

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

class pybamm.electrolyte_conductivity.surface_potential_form.LeadingOrderAlgebraic(param, domain, options=None)#

Leading-order model for conservation of charge in the electrolyte employing the Stefan-Maxwell constitutive equations employing the surface potential difference formulation.

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.electrolyte_conductivity.surface_potential_form.leading_surface_form_conductivity.BaseLeadingOrderSurfaceForm

set_algebraic(variables)#

Parameters:: variables (dict) – The variables in the whole model.

Explicit Model#

class pybamm.electrolyte_conductivity.surface_potential_form.Explicit(param, domain, options)#

Class for deriving surface potential difference variables from the electrode and electrolyte potentials

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str) – The domain in which the model holds
options (dict) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.electrolyte_conductivity.base_electrolyte_conductivity.BaseElectrolyteConductivity

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

set_boundary_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

Electrolyte Diffusion#

Base Electrolyte Diffusion Submodel#

class pybamm.electrolyte_diffusion.BaseElectrolyteDiffusion(param, options=None)#

Base class for conservation of mass in the electrolyte.

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.base_submodel.BaseSubModel

Constant Concentration#

class pybamm.electrolyte_diffusion.ConstantConcentration(param, options=None)#

Class for constant concentration of electrolyte

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.electrolyte_diffusion.base_electrolyte_diffusion.BaseElectrolyteDiffusion

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_boundary_conditions(variables)#: We provide boundary conditions even though the concentration is constant so that the gradient of the concentration has the correct shape after discretisation.

set_events(variables)#

Parameters:: variables (dict) – The variables in the whole model.

Leading Order Model#

class pybamm.electrolyte_diffusion.LeadingOrder(param)#

Class for conservation of mass in the electrolyte employing the Stefan-Maxwell constitutive equations. (Leading refers to leading order of asymptotic reduction)

Parameters:: param (parameter class) – The parameters to use for this submodel

Extends: pybamm.models.submodels.electrolyte_diffusion.base_electrolyte_diffusion.BaseElectrolyteDiffusion

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

Full Model#

class pybamm.electrolyte_diffusion.Full(param, options=None)#

Class for conservation of mass in the electrolyte employing the Stefan-Maxwell constitutive equations. (Full refers to unreduced by asymptotic methods)

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.electrolyte_diffusion.base_electrolyte_diffusion.BaseElectrolyteDiffusion

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_boundary_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

External circuit#

Models to enforce different boundary conditions (as imposed by an imaginary external circuit) such as constant current, constant voltage, constant power, or any other relationship between the current and voltage. “Current control” enforces these directly through boundary conditions, while “Function control” submodels add an algebraic equation (for the current) and hence can be used to set any variable to be constant.

Explicit control external circuit#

Current is explicitly specified, either by a function or in terms of other variables.

class pybamm.external_circuit.ExplicitCurrentControl(param, options)#

External circuit with current control.

Extends: pybamm.models.submodels.external_circuit.base_external_circuit.BaseModel

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

class pybamm.external_circuit.ExplicitPowerControl(param, options)#

External circuit with current set explicitly to hit target power.

Extends: pybamm.models.submodels.external_circuit.base_external_circuit.BaseModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

class pybamm.external_circuit.ExplicitResistanceControl(param, options)#

External circuit with current set explicitly to hit target resistance.

Extends: pybamm.models.submodels.external_circuit.base_external_circuit.BaseModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

Function control external circuit#

class pybamm.external_circuit.FunctionControl(param, external_circuit_function, options, control='algebraic')#

External circuit with an arbitrary function, implemented as a control on the current either via an algebraic equation, or a differential equation.

Parameters:

param (parameter class) – The parameters to use for this submodel
external_circuit_function (callable) – The function that controls the current
options (dict) – Dictionary of options to use for the submodel
control (str, optional) – The type of control to use. Must be one of ‘algebraic’ (default) or ‘differential’.

Extends: pybamm.models.submodels.external_circuit.base_external_circuit.BaseModel

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_algebraic(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

class pybamm.external_circuit.VoltageFunctionControl(param, options)#

External circuit with voltage control, implemented as an extra algebraic equation.

Extends: pybamm.models.submodels.external_circuit.function_control_external_circuit.FunctionControl

class pybamm.external_circuit.PowerFunctionControl(param, options, control='algebraic')#

External circuit with power control.

Extends: pybamm.models.submodels.external_circuit.function_control_external_circuit.FunctionControl

class pybamm.external_circuit.ResistanceFunctionControl(param, options, control)#

External circuit with resistance control.

Extends: pybamm.models.submodels.external_circuit.function_control_external_circuit.FunctionControl

class pybamm.external_circuit.CCCVFunctionControl(param, options)#

External circuit with constant-current constant-voltage control, as implemented in Mohtat et al.[1].

References

Extends: pybamm.models.submodels.external_circuit.function_control_external_circuit.FunctionControl

Interface#

Interface Base Model#

class pybamm.interface.BaseInterface(param, domain, reaction, options, phase='primary')#

Base class for interfacial currents

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str) – The domain to implement the model, either: ‘Negative’ or ‘Positive’.
reaction (str) – The name of the reaction being implemented
options (dict) – A dictionary of options to be passed to the model. See pybamm.BaseBatteryModel
phase (str, optional) – Phase of the particle (default is “primary”)

Extends: pybamm.models.submodels.base_submodel.BaseSubModel

Total Interfacial Current Model#

class pybamm.interface.TotalInterfacialCurrent(param, chemistry, options)#

Total interfacial current, summing up contributions from all reactions

Parameters:

param – model parameters
chemistry (str) – The name of the battery chemistry whose reactions need to be summed up
options (dict) – A dictionary of options to be passed to the model. See pybamm.BaseBatteryModel

Extends: pybamm.models.submodels.base_submodel.BaseSubModel

get_coupled_variables(variables)#: Get variables associated with interfacial current over the whole cell domain This function also creates the “total source term” variables by summing all the reactions.

Interface Utilisation#

Utilisation Base Model#

class pybamm.interface.interface_utilisation.BaseModel(param, domain, options)#

Base class for interface utilisation

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str) – Either ‘negative’ or ‘positive’
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.base_submodel.BaseSubModel

Constant Utilisation#

class pybamm.interface.interface_utilisation.Constant(param, domain, options)#

Submodel for constant interface utilisation

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str) – Either ‘negative’ or ‘positive’
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.interface.interface_utilisation.base_utilisation.BaseModel

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

CurrentDriven Utilisation#

class pybamm.interface.interface_utilisation.CurrentDriven(param, domain, options, reaction_loc)#

Current-driven ODE for interface utilisation

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str) – Either ‘negative’ or ‘positive’
options (dict, optional) – A dictionary of options to be passed to the model.
reaction_loc (str) – Where the reaction happens: “x-average” (SPM, SPMe, etc), “full electrode” (full DFN), or “interface” (half-cell model)

Extends: pybamm.models.submodels.interface.interface_utilisation.base_utilisation.BaseModel

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_events(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

Full Utilisation#

class pybamm.interface.interface_utilisation.Full(param, domain, options)#

Submodel for constant interface utilisation

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str) – Either ‘negative’ or ‘positive’
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.interface.interface_utilisation.base_utilisation.BaseModel

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

Kinetics#

Base Kinetics#

class pybamm.kinetics.BaseKinetics(param, domain, reaction, options, phase='primary')#

Base submodel for kinetics

Parameters:

param – model parameters
domain (str) – The domain to implement the model, either: ‘Negative’ or ‘Positive’.
reaction (str) – The name of the reaction being implemented
options (dict) – A dictionary of options to be passed to the model. See pybamm.BaseBatteryModel
phase (str, optional) – Phase of the particle (default is “primary”)

Extends: pybamm.models.submodels.interface.base_interface.BaseInterface

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_algebraic(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

Butler Volmer#

class pybamm.kinetics.SymmetricButlerVolmer(param, domain, reaction, options, phase='primary')#

Submodel which implements the symmetric forward Butler-Volmer equation:

\[j = 2 * j_0(c) * \sinh(ne * F * \eta_r(c) / RT)\]

Parameters:

param (parameter class) – model parameters
domain (str) – The domain to implement the model, either: ‘Negative’ or ‘Positive’.
reaction (str) – The name of the reaction being implemented
options (dict) – A dictionary of options to be passed to the model. See pybamm.BaseBatteryModel
phase (str, optional) – Phase of the particle (default is “primary”)

Extends: pybamm.models.submodels.interface.kinetics.base_kinetics.BaseKinetics

class pybamm.kinetics.AsymmetricButlerVolmer(param, domain, reaction, options, phase='primary')#

Submodel which implements the asymmetric forward Butler-Volmer equation

Parameters:

param (parameter class) – model parameters
domain (str) – The domain to implement the model, either: ‘Negative’ or ‘Positive’.
reaction (str) – The name of the reaction being implemented
options (dict) – A dictionary of options to be passed to the model. See pybamm.BaseBatteryModel
phase (str, optional) – Phase of the particle (default is “primary”)

Extends: pybamm.models.submodels.interface.kinetics.base_kinetics.BaseKinetics

Diffusion-limited#

class pybamm.kinetics.DiffusionLimited(param, domain, reaction, options, order)#

Submodel for diffusion-limited kinetics

Parameters:

param – model parameters
domain (str) – The domain to implement the model, either: ‘Negative’ or ‘Positive’.
reaction (str) – The name of the reaction being implemented
options (dict) – A dictionary of options to be passed to the model. See pybamm.BaseBatteryModel
order (str) – The order of the model (“leading” or “full”)

Extends: pybamm.models.submodels.interface.base_interface.BaseInterface

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

Linear#

class pybamm.kinetics.Linear(param, domain, reaction, options, phase='primary')#

Submodel which implements linear kinetics. Valid for small overpotentials/currents.

Parameters:

param (parameter class) – model parameters
domain (str) – The domain to implement the model, either: ‘Negative’ or ‘Positive’.
reaction (str) – The name of the reaction being implemented
options (dict) – A dictionary of options to be passed to the model. See pybamm.BaseBatteryModel
phase (str, optional) – Phase of the particle (default is “primary”)

Extends: pybamm.models.submodels.interface.kinetics.base_kinetics.BaseKinetics

Marcus#

class pybamm.kinetics.Marcus(param, domain, reaction, options, phase='primary')#

Submodel which implements Marcus kinetics.

Parameters:

param (parameter class) – model parameters
domain (str) – The domain to implement the model, either: ‘Negative’ or ‘Positive’.
reaction (str) – The name of the reaction being implemented
options (dict) – A dictionary of options to be passed to the model. See pybamm.BaseBatteryModel
phase (str, optional) – Phase of the particle (default is “primary”)

Extends: pybamm.models.submodels.interface.kinetics.base_kinetics.BaseKinetics

NoReaction#

class pybamm.kinetics.NoReaction(param, domain, reaction, options, phase='primary')#

Base submodel for when no reaction occurs

Parameters:

param – model parameters
domain (str) – The domain to implement the model, either: ‘Negative’ or ‘Positive’.
reaction (str) – The name of the reaction being implemented
options (dict) – A dictionary of options to be passed to the model. See pybamm.BaseBatteryModel
phase (str, optional) – Phase of the particle (default is “primary”)

Extends: pybamm.models.submodels.interface.base_interface.BaseInterface

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

Tafel#

class pybamm.kinetics.ForwardTafel(param, domain, reaction, options, phase='primary')#

Base submodel which implements the forward Tafel equation:

\[j = u * j_0(c) * \exp((ne * alpha * F * \eta_r(c) / RT)\]

Parameters:

param – model parameters
domain (str) – The domain to implement the model, either: ‘Negative’ or ‘Positive’.
reaction (str) – The name of the reaction being implemented
options (dict) – A dictionary of options to be passed to the model. See pybamm.BaseBatteryModel
phase (str, optional) – Phase of the particle (default is “primary”)

Extends: pybamm.models.submodels.interface.kinetics.base_kinetics.BaseKinetics

MSMR Butler Volmer#

class pybamm.kinetics.MSMRButlerVolmer(param, domain, reaction, options, phase='primary')#

Submodel which implements the forward Butler-Volmer equation in the MSMR formulation in which the interfacial current density is summed over all reactions.

Parameters:

param (parameter class) – model parameters
domain (str) – The domain to implement the model, either: ‘Negative’ or ‘Positive’.
reaction (str) – The name of the reaction being implemented
options (dict) – A dictionary of options to be passed to the model. See pybamm.BaseBatteryModel
phase (str, optional) – Phase of the particle (default is “primary”)

Extends: pybamm.models.submodels.interface.kinetics.base_kinetics.BaseKinetics

Total Main Kinetics#

class pybamm.kinetics.TotalMainKinetics(param, domain, reaction, options)#

Class summing up contributions to the main (e.g. intercalation) reaction for cases with primary, secondary, … reactions e.g. silicon-graphite

Parameters:

param – model parameters
domain (str) – The domain to implement the model, either: ‘Negative’ or ‘Positive’.
reaction (str) – The name of the reaction being implemented
options (dict) – A dictionary of options to be passed to the model. See pybamm.BaseBatteryModel

Extends: pybamm.models.submodels.base_submodel.BaseSubModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

Inverse Kinetics#

Inverse Butler-Volmer#

class pybamm.kinetics.InverseButlerVolmer(param, domain, reaction, options=None)#

A submodel that implements the inverted form of the Butler-Volmer relation to solve for the reaction overpotential.

Parameters:

param – Model parameters
domain (iter of str, optional) – The domain(s) in which to compute the interfacial current.
reaction (str) – The name of the reaction being implemented
options (dict) – A dictionary of options to be passed to the model. In this case “SEI film resistance” is the important option. See pybamm.BaseBatteryModel

Extends: pybamm.models.submodels.interface.base_interface.BaseInterface

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

Lithium Plating#

Base Plating#

class pybamm.lithium_plating.BasePlating(param, domain, options=None)#

Base class for lithium plating models, from O’Kane et al.[1] and O’Kane et al.[2].

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.interface.base_interface.BaseInterface

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

References

No Plating#

class pybamm.lithium_plating.NoPlating(param, domain, options=None)#

Base class for no lithium plating/stripping.

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.interface.lithium_plating.base_plating.BasePlating

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

Plating#

class pybamm.lithium_plating.Plating(param, domain, x_average, options)#

Class for lithium plating, from O’Kane et al.[1] and O’Kane et al.[2].

Parameters:

param (parameter class) – The parameters to use for this submodel
x_average (bool) – Whether to use x-averaged variables (SPM, SPMe, etc) or full variables (DFN)
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.interface.lithium_plating.base_plating.BasePlating

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

References

Open-circuit potential models#

Base Open Circuit Potential#

class pybamm.open_circuit_potential.BaseOpenCircuitPotential(param, domain, reaction, options, phase='primary')#

Base class for open-circuit potentials

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str) – The domain to implement the model, either: ‘Negative’ or ‘Positive’.
reaction (str) – The name of the reaction being implemented
options (dict) – A dictionary of options to be passed to the model. See pybamm.BaseBatteryModel
phase (str, optional) – Phase of the particle (default is “primary”)

Extends: pybamm.models.submodels.interface.base_interface.BaseInterface

Current Sigmoid Open Circuit Potential#

class pybamm.open_circuit_potential.CurrentSigmoidOpenCircuitPotential(param, domain, reaction, options, phase='primary')#

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

Single Open Circuit Potential#

class pybamm.open_circuit_potential.SingleOpenCircuitPotential(param, domain, reaction, options, phase='primary')#

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

MSMR Open Circuit Potential#

class pybamm.open_circuit_potential.MSMROpenCircuitPotential(param, domain, reaction, options, phase='primary')#

Class for open-circuit potential within the Multi-Species Multi-Reaction framework Baker and Verbrugge[1]. The thermodynamic model is presented in Verbrugge et al.[2], along with parameter values for a number of substitutional materials.

Extends: pybamm.models.submodels.interface.open_circuit_potential.base_ocp.BaseOpenCircuitPotential

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

References

SEI models#

SEI Base Model#

class pybamm.sei.BaseModel(param, domain, options, phase='primary', cracks=False)#

Base class for SEI models.

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict) – A dictionary of options to be passed to the model.
phase (str, optional) – Phase of the particle (default is “primary”)
cracks (bool, optional) – Whether this is a submodel for standard SEI or SEI on cracks

Extends: pybamm.models.submodels.interface.base_interface.BaseInterface

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

Constant SEI#

class pybamm.sei.ConstantSEI(param, domain, options, phase='primary')#

Class for SEI with constant thickness.

Note that there is no SEI current, so we don’t need to update the “sum of interfacial current densities” variables from pybamm.interface.BaseInterface

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict) – A dictionary of options to be passed to the model.
phase (str, optional) – Phase of the particle (default is “primary”)

Extends: pybamm.models.submodels.interface.sei.base_sei.BaseModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

No SEI#

class pybamm.sei.NoSEI(param, domain, options, phase='primary', cracks=False)#

Class for no SEI.

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict) – A dictionary of options to be passed to the model.
phase (str, optional) – Phase of the particle (default is “primary”)
cracks (bool, optional) – Whether this is a submodel for standard SEI or SEI on cracks

Extends: pybamm.models.submodels.interface.sei.base_sei.BaseModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

SEI Growth#

class pybamm.sei.SEIGrowth(param, domain, reaction_loc, options, phase='primary', cracks=False)#

Class for SEI growth.

Most of the models are from Section 5.6.4 of Marquis[1] and references therein.

The ec reaction limited model is from Yang et al.[2].

Parameters:

param (parameter class) – The parameters to use for this submodel
reaction_loc (str) – Where the reaction happens: “x-average” (SPM, SPMe, etc), “full electrode” (full DFN), or “interface” (half-cell model)
options (dict) – A dictionary of options to be passed to the model.
phase (str, optional) – Phase of the particle (default is “primary”)
cracks (bool, optional) – Whether this is a submodel for standard SEI or SEI on cracks

Extends: pybamm.models.submodels.interface.sei.base_sei.BaseModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

References

Total SEI#

class pybamm.sei.TotalSEI(param, domain, options, cracks=False)#

Class summing up contributions to the SEI reaction for cases with primary, secondary, … reactions e.g. silicon-graphite

Parameters:

param – model parameters
options (dict) – A dictionary of options to be passed to the model. See pybamm.BaseBatteryModel

Extends: pybamm.models.submodels.base_submodel.BaseSubModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

Oxygen Diffusion#

Base Model#

class pybamm.oxygen_diffusion.BaseModel(param)#

Base class for conservation of mass of oxygen.

Parameters:: param (parameter class) – The parameters to use for this submodel

Extends: pybamm.models.submodels.base_submodel.BaseSubModel

Full Model#

class pybamm.oxygen_diffusion.Full(param)#

Class for conservation of mass of oxygen. (Full refers to unreduced by asymptotic methods) In this model, extremely fast oxygen kinetics in the negative electrode imposes zero oxygen concentration there, and so the oxygen variable only lives in the separator and positive electrode. The boundary condition at the negative electrode/ separator interface is homogeneous Dirichlet.

Parameters:: param (parameter class) – The parameters to use for this submodel

Extends: pybamm.models.submodels.oxygen_diffusion.base_oxygen_diffusion.BaseModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_boundary_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

Leading Order Model#

class pybamm.oxygen_diffusion.LeadingOrder(param)#

Class for conservation of mass of oxygen. (Leading refers to leading order of asymptotic reduction)

Parameters:: param (parameter class) – The parameters to use for this submodel

Extends: pybamm.models.submodels.oxygen_diffusion.base_oxygen_diffusion.BaseModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

No Oxygen#

class pybamm.oxygen_diffusion.NoOxygen(param)#

Class for when there is no oxygen

Parameters:: param (parameter class) – The parameters to use for this submodel

Extends: pybamm.models.submodels.oxygen_diffusion.base_oxygen_diffusion.BaseModel

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

Particle#

Particle Base Model#

class pybamm.particle.BaseParticle(param, domain, options, phase='primary')#

Base class for molar conservation in particles.

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str) – The domain of the model either ‘Negative’ or ‘Positive’
options (dict) – A dictionary of options to be passed to the model. See pybamm.BaseBatteryModel
phase (str, optional) – Phase of the particle (default is “primary”)

Extends: pybamm.models.submodels.base_submodel.BaseSubModel

class pybamm.particle.TotalConcentration(param, domain, options, phase='primary')#

Class to calculate total particle concentrations

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str) – The domain of the model either ‘Negative’ or ‘Positive’
options (dict) – A dictionary of options to be passed to the model. See pybamm.BaseBatteryModel
phase (str, optional) – Phase of the particle (default is “primary”)

Extends: pybamm.models.submodels.particle.base_particle.BaseParticle

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

Fickian Diffusion#

class pybamm.particle.FickianDiffusion(param, domain, options, phase='primary', x_average=False)#

Class for molar conservation in particles, employing Fick’s law

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str) – The domain of the model either ‘Negative’ or ‘Positive’
options (dict) – A dictionary of options to be passed to the model. See pybamm.BaseBatteryModel
phase (str, optional) – Phase of the particle (default is “primary”)
x_average (bool) – Whether the particle concentration is averaged over the x-direction

Extends: pybamm.models.submodels.particle.base_particle.BaseParticle

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_boundary_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

Polynomial Profile#

class pybamm.particle.PolynomialProfile(param, domain, options, phase='primary')#

Class for molar conservation in particles employing Fick’s law, assuming a polynomial concentration profile in r, and allowing variation in the electrode domain. Model equations from Subramanian et al.[1].

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str) – The domain of the model either ‘Negative’ or ‘Positive’
options (dict) – A dictionary of options to be passed to the model. See pybamm.BaseBatteryModel
phase (str, optional) – Phase of the particle (default is “primary”)

Extends: pybamm.models.submodels.particle.base_particle.BaseParticle

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_algebraic(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

References

X-averaged Polynomial Profile#

class pybamm.particle.XAveragedPolynomialProfile(param, domain, options, phase='primary')#

Class for molar conservation in a single x-averaged particle employing Fick’s law, with an assumed polynomial concentration profile in r. Model equations from Subramanian et al.[1].

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str) – The domain of the model either ‘Negative’ or ‘Positive’
options (dict) – A dictionary of options to be passed to the model. See pybamm.BaseBatteryModel
phase (str, optional) – Phase of the particle (default is “primary”)

Extends: pybamm.models.submodels.particle.polynomial_profile.PolynomialProfile

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_algebraic(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_initial_conditions(variables)#: For single or x-averaged particle models, initial conditions can’t depend on x or r so we take the r- and x-average of the initial conditions.

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

References

MSMR Diffusion#

class pybamm.particle.MSMRDiffusion(param, domain, options, phase='primary', x_average=False)#

Class for molar conservation in particles within the Multi-Species Multi-Reaction framework Baker and Verbrugge[1]. The thermodynamic model is presented in Verbrugge et al.[2], along with parameter values for a number of substitutional materials.

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str) – The domain of the model either ‘Negative’ or ‘Positive’
options (dict) – A dictionary of options to be passed to the model. See pybamm.BaseBatteryModel
phase (str, optional) – Phase of the particle (default is “primary”)
x_average (bool) – Whether the particle concentration is averaged over the x-direction

Extends: pybamm.models.submodels.particle.base_particle.BaseParticle

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_boundary_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

References

Particle Cracking#

Base Particle Mechanics Model#

class pybamm.particle_mechanics.BaseMechanics(param, domain, options, phase='primary')#

Base class for particle mechanics models, referenced from Ai et al.[1] and Deshpande et al.[2].

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (dict, optional) – Dictionary of either the electrode for “positive” or “Negative”
options (dict) – A dictionary of options to be passed to the model. See pybamm.BaseBatteryModel
phase (str, optional) – Phase of the particle (default is “primary”)

Extends: pybamm.models.submodels.base_submodel.BaseSubModel

References

Crack Propagation Model#

class pybamm.particle_mechanics.CrackPropagation(param, domain, x_average, options, phase='primary')#

Cracking behaviour in electrode particles. See Ai et al.[1] for mechanical model (thickness change) and Deshpande et al.[2] for cracking model.

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str) – The domain of the model either ‘Negative’ or ‘Positive’
x_average (bool) – Whether to use x-averaged variables (SPM, SPMe, etc) or full variables (DFN)
options (dict) – A dictionary of options to be passed to the model. See pybamm.BaseBatteryModel
phase (str, optional) – Phase of the particle (default is “primary”)

Extends: pybamm.models.submodels.particle_mechanics.base_mechanics.BaseMechanics

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_events(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

References

Swelling Only Model#

class pybamm.particle_mechanics.SwellingOnly(param, domain, options, phase='primary')#

Class for swelling only (no cracking), from Ai et al.[1].

Parameters:

param (parameter class) – The parameters to use for this submodel
domain (str) – The domain of the model either ‘Negative’ or ‘Positive’
options (dict) – A dictionary of options to be passed to the model. See pybamm.BaseBatteryModel
phase (str, optional) – Phase of the particle (default is “primary”)

Extends: pybamm.models.submodels.particle_mechanics.base_mechanics.BaseMechanics

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

References

Porosity#

Base Model#

class pybamm.porosity.BaseModel(param, options)#

Base class for porosity

Parameters:: param (parameter class) – The parameters to use for this submodel

Extends: pybamm.models.submodels.base_submodel.BaseSubModel

Constant Porosity#

class pybamm.porosity.Constant(param, options)#

Submodel for constant porosity

Parameters:: param (parameter class) – The parameters to use for this submodel

Extends: pybamm.models.submodels.porosity.base_porosity.BaseModel

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_events(variables)#

Parameters:: variables (dict) – The variables in the whole model.

Reaction-driven Model#

class pybamm.porosity.ReactionDriven(param, options, x_average)#

Reaction-driven porosity changes as a multiple of SEI/plating thicknesses

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict) – Options dictionary passed from the full model
x_average (bool) – Whether to use x-averaged variables (SPM, SPMe, etc) or full variables (DFN)

Extends: pybamm.models.submodels.porosity.base_porosity.BaseModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

set_events(variables)#

Parameters:: variables (dict) – The variables in the whole model.

Reaction-driven Model as an ODE#

class pybamm.porosity.ReactionDrivenODE(param, options, x_average)#

Reaction-driven porosity changes as an ODE

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict) – Options dictionary passed from the full model
x_average (bool) – Whether to use x-averaged variables (SPM, SPMe, etc) or full variables (DFN)

Extends: pybamm.models.submodels.porosity.base_porosity.BaseModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_events(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

Thermal#

Base Thermal#

class pybamm.thermal.BaseThermal(param, options=None)#

Base class for thermal effects

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.base_submodel.BaseSubModel

Isothermal Model#

class pybamm.thermal.isothermal.Isothermal(param, options=None)#

Class for isothermal submodel.

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.thermal.base_thermal.BaseThermal

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

Lumped Model#

class pybamm.thermal.lumped.Lumped(param, options=None)#

Class for lumped thermal submodel. For more information see Timms et al.[1] and Marquis[2].

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.thermal.base_thermal.BaseThermal

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

References

Pouch Cell#

One Dimensional Model#

class pybamm.thermal.pouch_cell.x_full.OneDimensionalX(param, options=None)#

Class for one-dimensional (x-direction) thermal submodel. Note: this model assumes infinitely large electrical and thermal conductivity in the current collectors, so that the contribution to the Ohmic heating from the current collectors is zero and the boundary conditions are applied at the edges of the electrodes (at x=0 and x=1, in non-dimensional coordinates). For more information see Timms et al.[1] and Marquis[2].

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.thermal.base_thermal.BaseThermal

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_boundary_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

References

Thermal Model for “1+1D” Pouch Cell#

class pybamm.thermal.pouch_cell.CurrentCollector1D(param, options=None)#

Class for one-dimensional thermal submodel for use in the “1+1D” pouch cell model. The thermal model is averaged in the x-direction and is therefore referred to as ‘x-lumped’. For more information see Timms et al.[1] and Marquis[2].

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.thermal.base_thermal.BaseThermal

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_boundary_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

References

Thermal Model for “2+1D” Pouch Cell#

class pybamm.thermal.pouch_cell.CurrentCollector2D(param, options=None)#

Class for two-dimensional thermal submodel for use in the “2+1D” pouch cell model. The thermal model is averaged in the x-direction and is therefore referred to as ‘x-lumped’. For more information see Timms et al.[1] and Marquis[2].

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.thermal.base_thermal.BaseThermal

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_boundary_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

References

transport_efficiency#

Base Model#

class pybamm.transport_efficiency.BaseModel(param, component, options=None)#

Base class for transport_efficiency

Parameters:

param (parameter class) – The parameters to use for this submodel
component (str) – The material for the model (‘electrolyte’ or ‘electrode’).
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.base_submodel.BaseSubModel

Bruggeman Model#

class pybamm.transport_efficiency.Bruggeman(param, component, options=None)#

Submodel for Bruggeman transport_efficiency

Parameters:

param (parameter class) – The parameters to use for this submodel
component (str) – The material for the model (‘electrolyte’ or ‘electrode’).
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.transport_efficiency.base_transport_efficiency.BaseModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

Equivalent Circuit Elements#

OCV Element#

class pybamm.equivalent_circuit_elements.OCVElement(param, options=None)#

Open-circuit Voltage (OCV) element for equivalent circuits.

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.base_submodel.BaseSubModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_events(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

Resistor Element#

class pybamm.equivalent_circuit_elements.ResistorElement(param, options=None)#

Resistor element for equivalent circuits.

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.base_submodel.BaseSubModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

RC Element#

class pybamm.equivalent_circuit_elements.RCElement(param, element_number, options=None)#

Parallel Resistor-Capacitor (RC) element for equivalent circuits.

Parameters:

param (parameter class) – The parameters to use for this submodel
element_number (int) – The number of the element (i.e. whether it is the first, second, third, etc. element)
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.base_submodel.BaseSubModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

Thermal SubModel#

class pybamm.equivalent_circuit_elements.ThermalSubModel(param, options=None)#

Thermal SubModel for use with equivalent circuits.

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.base_submodel.BaseSubModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

get_fundamental_variables()#

Returns:: The variables created by the submodel which are independent of variables in other submodels.
Return type:: dict

set_initial_conditions(variables)#

Parameters:: variables (dict) – The variables in the whole model.

set_rhs(variables)#

Parameters:: variables (dict) – The variables in the whole model.

Voltage Model#

class pybamm.equivalent_circuit_elements.VoltageModel(param, options=None)#

Voltage model for use with equivalent circuits. This model is used to calculate the voltage and total overpotentials from the other elements in the circuit.

Parameters:

param (parameter class) – The parameters to use for this submodel
options (dict, optional) – A dictionary of options to be passed to the model.

Extends: pybamm.models.submodels.base_submodel.BaseSubModel

get_coupled_variables(variables)#

Parameters:: variables (dict) – The variables in the whole model.
Returns:: The variables created in this submodel which depend on variables in other submodels.
Return type:: dict

set_events(variables)#

Parameters:: variables (dict) – The variables in the whole model.

Parameters#

Parameter Values#

class pybamm.ParameterValues(values, chemistry=None)[source]#

The parameter values for a simulation.

Note that this class does not inherit directly from the python dictionary class as this causes issues with saving and loading simulations.

Parameters:: values (dict or string) – Explicit set of parameters, or reference to an inbuilt parameter set If string and matches one of the inbuilt parameter sets, returns that parameter set.

Examples

>>> values = {"some parameter": 1, "another parameter": 2}
>>> param = pybamm.ParameterValues(values)
>>> param["some parameter"]
1
>>> param = pybamm.ParameterValues("Marquis2019")
>>> param["Reference temperature [K]"]
298.15

copy()[source]#: Returns a copy of the parameter values. Makes sure to copy the internal dictionary.

static create_from_bpx(filename, target_soc=1)[source]#

Parameters:

filename (str) – The filename of the bpx file
target_soc (float, optional) – Target state of charge. Must be between 0 and 1. Default is 1.

Returns:

A parameter values object with the parameters in the bpx file

Return type:

ParameterValues

evaluate(symbol)[source]#

Process and evaluate a symbol.

Parameters:: symbol (pybamm.Symbol) – Symbol or Expression tree to evaluate
Returns:: The evaluated symbol
Return type:: number or array

get(key, default=None)[source]#: Return item corresponding to key if it exists, otherwise return default

items()[source]#: Get the items of the dictionary

keys()[source]#: Get the keys of the dictionary

print_evaluated_parameters(evaluated_parameters, output_file)[source]#

Print a dictionary of evaluated parameters to an output file

Parameters:

evaluated_parameters (defaultdict) – The evaluated parameters, for further processing if needed
output_file (string, optional) – The file to print parameters to. If None, the parameters are not printed, and this function simply acts as a test that all the parameters can be evaluated

print_parameters(parameters, output_file=None)[source]#

Return dictionary of evaluated parameters, and optionally print these evaluated parameters to an output file.

Parameters:

parameters (class or dict containing pybamm.Parameter objects) – Class or dictionary containing all the parameters to be evaluated
output_file (string, optional) – The file to print parameters to. If None, the parameters are not printed, and this function simply acts as a test that all the parameters can be evaluated, and returns the dictionary of evaluated parameters.

Returns:

evaluated_parameters – The evaluated parameters, for further processing if needed

Return type:

defaultdict

Notes

A C-rate of 1 C is the current required to fully discharge the battery in 1 hour, 2 C is current to discharge the battery in 0.5 hours, etc

process_boundary_conditions(model)[source]#: Process boundary conditions for a model Boundary conditions are dictionaries {“left”: left bc, “right”: right bc} in general, but may be imposed on the tabs (or not on the tab) for a small number of variables, e.g. {“negative tab”: neg. tab bc, “positive tab”: pos. tab bc “no tab”: no tab bc}.

process_geometry(geometry)[source]#

Assign parameter values to a geometry (inplace).

Parameters:: geometry (dict) – Geometry specs to assign parameter values to

process_model(unprocessed_model, inplace=True)[source]#

Assign parameter values to a model. Currently inplace, could be changed to return a new model.

Parameters:

unprocessed_model (pybamm.BaseModel) – Model to assign parameter values for
inplace (bool, optional) – If True, replace the parameters in the model in place. Otherwise, return a new model with parameter values set. Default is True.

Raises:

pybamm.ModelError – If an empty model is passed (model.rhs = {} and model.algebraic = {} and model.variables = {})

process_symbol(symbol)[source]#

Walk through the symbol and replace any Parameter with a Value. If a symbol has already been processed, the stored value is returned.

Parameters:: symbol (pybamm.Symbol) – Symbol or Expression tree to set parameters for
Returns:: symbol – Symbol with Parameter instances replaced by Value
Return type:: pybamm.Symbol

search(key, print_values=True)[source]#

Search dictionary for keys containing ‘key’.

See pybamm.FuzzyDict.search().

set_initial_ocps(initial_value, param=None, known_value='cyclable lithium capacity', inplace=True, options=None)[source]#: Set the initial OCP of each electrode, based on the initial SOC or voltage

set_initial_stoichiometries(initial_value, param=None, known_value='cyclable lithium capacity', inplace=True, options=None)[source]#: Set the initial stoichiometry of each electrode, based on the initial SOC or voltage

set_initial_stoichiometry_half_cell(initial_value, param=None, known_value='cyclable lithium capacity', inplace=True, options=None)[source]#: Set the initial stoichiometry of the working electrode, based on the initial SOC or voltage

update(values, check_conflict=False, check_already_exists=True, path='')[source]#

Update parameter dictionary, while also performing some basic checks.

Parameters:

values (dict) – Dictionary of parameter values to update parameter dictionary with
check_conflict (bool, optional) – Whether to check that a parameter in values has not already been defined in the parameter class when updating it, and if so that its value does not change. This is set to True during initialisation, when parameters are combined from different sources, and is False by default otherwise
check_already_exists (bool, optional) – Whether to check that a parameter in values already exists when trying to update it. This is to avoid cases where an intended change in the parameters is ignored due a typo in the parameter name, and is True by default but can be manually overridden.
path (string, optional) – Path from which to load functions

values()[source]#: Get the values of the dictionary

Geometric Parameters#

class pybamm.GeometricParameters(options=None)[source]#

Standard geometric parameters

Extends: pybamm.parameters.base_parameters.BaseParameters

Electrical Parameters#

class pybamm.ElectricalParameters[source]#

Standard electrical parameters

Extends: pybamm.parameters.base_parameters.BaseParameters

Thermal Parameters#

class pybamm.ThermalParameters[source]#

Standard thermal parameters

Extends: pybamm.parameters.base_parameters.BaseParameters

Lithium-ion Parameters#

class pybamm.LithiumIonParameters(options=None)[source]#

Standard parameters for lithium-ion battery models

Parameters:: options (dict, optional) – A dictionary of options to be passed to the parameters, see pybamm.BatteryModelOptions.

Extends: pybamm.parameters.base_parameters.BaseParameters

Lead-Acid Parameters#

class pybamm.LeadAcidParameters[source]#

Standard Parameters for lead-acid battery models

Extends: pybamm.parameters.base_parameters.BaseParameters

Parameters Sets#

PyBaMM provides pre-defined parameters for common chemistries, as well as, a growing set of third-party parameter sets.

class pybamm.parameters.parameter_sets.ParameterSets[source]#

Dict-like interface for accessing registered pybamm parameter sets. Access via pybamm.parameter_sets

Examples

Listing available parameter sets:

>>> list(pybamm.parameter_sets)
['Ai2020', 'Chen2020', ...]

Get the docstring for a parameter set:

>>> print(pybamm.parameter_sets.get_docstring("Ai2020"))

Parameters for the Enertech cell (Ai2020), from the papers :footcite:t:`Ai2019`,
:footcite:t:`rieger2016new` and references therein.
...

Adding Parameter Sets#

Parameter sets can be added to PyBaMM by creating a python package, and registering a entry point to pybamm_parameter_sets. At a minimum, the package (cell_parameters) should consist of the following:

cell_parameters
├── pyproject.toml        # and/or setup.cfg, setup.py
└── src
    └── cell_parameters
        └── cell_alpha.py

The actual parameter set is defined within cell_alpha.py, as shown below. For an example, see the Marquis2019 parameter sets.

import pybamm


def get_parameter_values():
    """Doc string for cell-alpha"""
    return {
        "chemistry": "lithium_ion",
        "citation": "@book{van1995python, title={Python reference manual}}",
        # ...
    }

Then register get_parameter_values to pybamm_parameter_sets in pyproject.toml:

[project.entry-points.pybamm_parameter_sets]
cell_alpha = "cell_parameters.cell_alpha:get_parameter_values"

If you are using setup.py or setup.cfg to setup your package, please see SetupTools’ documentation for registering entry points.

If you’re willing to open-source your parameter set, let us know, and we can add an entry to Third-Party Parameter Sets.

Third-Party Parameter Sets#

Registered a new parameter set to pybamm_parameter_sets? Let us know, and we’ll update our list.

Bundled Parameter Sets#

PyBaMM provides pre-defined parameter sets for several common chemistries, listed below. See Adding Parameter Sets for information on registering new parameter sets with PyBaMM.

Lead-acid Parameter Sets#

Sulzer2019#

Parameters for BBOXX lead-acid cells, from the paper Sulzer et al.[1] and references therein.

Lithium-ion Parameter Sets#

Ai2020#

Parameters for the Enertech cell (Ai2020), from the papers Ai et al.[2], Rieger et al.[3] and references therein.

SEI parameters are example parameters for SEI growth from the papers Ramadass et al.[4], Ploehn et al.[5], Single et al.[6], Safari et al.[7], and Yang et al.[8]

Note

This parameter set does not claim to be representative of the true parameter values. Instead these are parameter values that were used to fit SEI models to observed experimental data in the referenced papers.

Chen2020#

Parameters for an LG M50 cell, from the paper Chen et al.[9] and references therein.

SEI parameters are example parameters for SEI growth from the papers Ramadass et al.[4], Ploehn et al.[5], Single et al.[6], Safari et al.[7], and Yang et al.[8]

Note

Chen2020_composite#

Parameters for a composite graphite/silicon negative electrode, from the paper Ai et al.[10], based on the paper Chen et al.[9], and references therein.

SEI parameters are example parameters for composite SEI on silicon/graphite. Both phases use the same values, from the paper Yang et al.[8]

Ecker2015#

Parameters for a Kokam SLPB 75106100 cell, from the papers Ecker et al.[11] and Ecker et al.[12]

The tab placement parameters are taken from measurements in Hales et al.[13]

The thermal material properties are for a 5 Ah power pouch cell by Kokam. The data are extracted from Zhao et al.[14]

Graphite negative electrode parameters#

The fits to data for the electrode and electrolyte properties are those provided by Dr. Simon O’Kane in the paper Richardson et al.[15]

SEI parameters are example parameters for SEI growth from the papers Ramadass et al.[4], Ploehn et al.[5], Single et al.[6], Safari et al.[7], and Yang et al.[8]

Note

Ecker2015_graphite_halfcell#

Parameters for a graphite half-cell based on a Kokam SLPB 75106100 cell, from papers

Ecker, Madeleine, et al. “Parameterization of a physico-chemical model of a lithium-ion battery I. determination of parameters.” Journal of the Electrochemical Society 162.9 (2015): A1836-A1848.

Ecker, Madeleine, et al. “Parameterization of a physico-chemical model of a lithium-ion battery II. Model validation.” Journal of The Electrochemical Society 162.9 (2015): A1849-A1857.

The tab placement parameters are taken from measurements in

Hales, Alastair, et al. “The cell cooling coefficient: a standard to define heat rejection from lithium-ion batteries.” Journal of The Electrochemical Society 166.12 (2019): A2383.

The thermal material properties are for a 5 Ah power pouch cell by Kokam. The data are extracted from

Zhao, Y., et al. “Modeling the effects of thermal gradients induced by tab and surface cooling on lithium ion cell performance.”” Journal of The Electrochemical Society, 165.13 (2018): A3169-A3178.

Graphite electrode parameters#

The fits to data for the electrode and electrolyte properties are those provided by Dr. Simon O’Kane in the paper:

Richardson, Giles, et. al. “Generalised single particle models for high-rate operation of graded lithium-ion electrodes: Systematic derivation and validation.” Electrochemica Acta 339 (2020): 135862

SEI parameters are example parameters for SEI growth from the papers:

Ramadass, P., Haran, B., Gomadam, P. M., White, R., & Popov, B. N. (2004). Development of first principles capacity fade model for Li-ion cells. Journal of the Electrochemical Society, 151(2), A196-A203.

Ploehn, H. J., Ramadass, P., & White, R. E. (2004). Solvent diffusion model for aging of lithium-ion battery cells. Journal of The Electrochemical Society, 151(3), A456-A462.

Single, F., Latz, A., & Horstmann, B. (2018). Identifying the mechanism of continued growth of the solid-electrolyte interphase. ChemSusChem, 11(12), 1950-1955.

Safari, M., Morcrette, M., Teyssot, A., & Delacour, C. (2009). Multimodal Physics- Based Aging Model for Life Prediction of Li-Ion Batteries. Journal of The Electrochemical Society, 156(3),

Yang, X., Leng, Y., Zhang, G., Ge, S., Wang, C. (2017). Modeling of lithium plating induced aging of lithium-ion batteries: Transition from linear to nonlinear aging. Journal of Power Sources, 360, 28-40.

Note: this parameter set does not claim to be representative of the true parameter values. Instead these are parameter values that were used to fit SEI models to observed experimental data in the referenced papers.

MSMR_Example#

Example parameter values for use with MSMR models. The thermodynamic parameters are for Graphite and NMC622, and are taken from Table 1 of the paper

Mark Verbrugge, Daniel Baker, Brian Koch, Xingcheng Xiao and Wentian Gu. Thermodynamic Model for Substitutional Materials: Application to Lithiated Graphite, Spinel Manganese Oxide, Iron Phosphate, and Layered Nickel-Manganese-Cobalt Oxide. Journal of The Electrochemical Society, 164(11):3243-3253, 2017. doi:10.1149/2.0341708jes.

The remaining value are based on a parameterization of the LG M50 cell, from the paper

Chang-Hui Chen, Ferran Brosa Planella, Kieran O’Regan, Dominika Gastol, W. Dhammika Widanage, and Emma Kendrick. Development of Experimental Techniques for Parameterization of Multi-scale Lithium-ion Battery Models. Journal of The Electrochemical Society, 167(8):080534, 2020. doi:10.1149/1945-7111/ab9050.

and references therein. Verbrugge et al. (2017) does not provide kinetic parameters so we set the reference exchange current density to 5 A.m-2 for the positive electrode reactions and 2.7 A.m-2 for the negative electrode reactions, which are the values used in the Chen et al. (2020) paper. We also assume that the exchange-current density is symmetric. Note: the 4th reaction in the positive electrode gave unphysical results so we set the reference exchange current density and symmetry factor to 1e6 and 1, respectively. The parameter values are intended to serve as an example set to use with the MSMR model and do not claim to match any experimental cycling data.

Marquis2019#

Parameters for a Kokam SLPB78205130H cell, from the paper Marquis et al.[16] and references therein.

SEI parameters are example parameters for SEI growth from the papers Ramadass et al.[4], Ploehn et al.[5], Single et al.[6], Safari et al.[7], and Yang et al.[8]

Note

Mohtat2020#

Parameters for a graphite/NMC532 pouch cell from the paper Mohtat et al.[17] and references therein.

SEI parameters are example parameters for SEI growth from the papers Ramadass et al.[4], Ploehn et al.[5], Single et al.[6], Safari et al.[7], and Yang et al.[8]

SEI parameters#

Parameters for lithium plating are from the paper Yang et al.[8]

Note

NCA_Kim2011#

Parameters for a “Nominal Design” graphite/NCA pouch cell, from the paper Kim et al.[18]

Note

Only an effective cell volumetric heat capacity is provided in the paper. We therefore used the values for the density and specific heat capacity reported in the Marquis2019 parameter set in each region and multiplied each density by the ratio of the volumetric heat capacity provided in smith to the calculated value. This ensures that the values produce the same effective cell volumetric heat capacity. This works fine for thermal models that are averaged over the x-direction but not for full (PDE in x direction) thermal models. We do the same for the planar effective thermal conductivity.

SEI parameters are example parameters for SEI growth from the papers Ramadass et al.[4], Ploehn et al.[5], Single et al.[6], Safari et al.[7], and Yang et al.[8]

Note

OKane2022#

Parameters for an LG M50 cell, from the paper O’Kane et al.[19], based on the paper Chen et al.[9] and references therein.

Note

OKane2022_graphite_SiOx_halfcell#

Parameters for the graphite+SiOx negative electrode of a LG M50 cell, from the paper

Simon E. J. O’Kane, Weilong Ai, Ganesh Madabattula, Diego Alonso-Alvarez, Robert Timms, Valentin Sulzer, Jacqueline Sophie Edge, Billy Wu, Gregory J. Offer, and Monica Marinescu. Lithium-ion battery degradation: how to model it. Phys. Chem. Chem. Phys., 24:7909-7922, 2022. URL: http://dx.doi.org/10.1039/D2CP00417H, doi:10.1039/D2CP00417H.

based on the paper

Chang-Hui Chen, Ferran Brosa Planella, Kieran O’Regan, Dominika Gastol, W. Dhammika Widanage, and Emma Kendrick. Development of Experimental Techniques for Parameterization of Multi-scale Lithium-ion Battery Models. Journal of The Electrochemical Society, 167(8):080534, 2020. doi:10.1149/1945-7111/ab9050.

and references therein.

Note: the SEI, plating and mechanical parameters do not claim to be representative of the true parameter values. These are merely the parameter values that were used in the referenced papers.

ORegan2022#

Parameters for an LG M50 cell, from the paper O’Regan et al.[20]

Parameters for a LiPF6 in EC:EMC (3:7 w:w) electrolyte are from the paper Landesfeind and Gasteiger[21] and references therein.

Prada2013#

Parameters for an LFP cell, from the paper Prada et al.[22]

Ramadass2004#

Ramadass2004 parameter set. This is a bit of a Frankenstein parameter set and should be used with caution.

Parameters for a graphite negative electrode, Lithium Cobalt Oxide positive electrode, and LiPF6 electrolyte are from the papers Marquis et al.[16], Ramadass et al.[4], and references therein.

Parameters for the separator are from the papers Ecker et al.[11]

The thermal material properties are for a 5 Ah power pouch cell by Kokam. The data are extracted from Lithium Cobalt Oxide positive electrode parameters in Zhao et al.[14]

Parameters for SEI growth are from the papers Ramadass et al.[4] and Safari et al.[7]

Note

Ramadass 2004 has mistakes in units and values of SEI parameters, corrected by Safari2009.

Xu2019#

Parameters for a Kokam SLPB78205130H half-cell, from the paper Xu et al.[23] and references therein. Anode is graphite MCMB 2528. Separator is Celgard 2325. Cathode is lithium Cobalt Oxide. Electrolyte is LiPF6.

Parameters for a LiPF6 electrolyte are from the paper Valøen and Reimers[24]

1C discharge from full#

SEI parameters are example parameters for SEI growth from the papers Ramadass et al.[4], Ploehn et al.[5], Single et al.[6], Safari et al.[7], and Yang et al.[8].

Note

References

Process Parameter Data#

pybamm.parameters.process_1D_data(name, path=None)[source]#: Process 1D data from a csv file

pybamm.parameters.process_2D_data(name, path=None)[source]#: Process 2D data from a JSON file

pybamm.parameters.process_2D_data_csv(name, path=None)[source]#

Process 2D data from a csv file. Assumes data is in the form of a three columns and that all data points lie on a regular grid. The first column is assumed to be the ‘slowest’ changing variable and the second column the ‘fastest’ changing variable, which is the C convention for indexing multidimensional arrays (as opposed to the Fortran convention where the ‘fastest’ changing variable comes first).

Parameters:

name (str) – The name to be given to the function
path (str) – The path to the file where the three dimensional data is stored.

Returns:

formatted_data – A tuple containing the name of the function and the data formatted correctly for use within three-dimensional interpolants.

Return type:

tuple

pybamm.parameters.process_3D_data_csv(name, path=None)[source]#

Process 3D data from a csv file. Assumes data is in the form of four columns and that all data points lie on a regular grid. The first column is assumed to be the ‘slowest’ changing variable and the third column the ‘fastest’ changing variable, which is the C convention for indexing multidimensional arrays (as opposed to the Fortran convention where the ‘fastest’ changing variable comes first).

Parameters:

name (str) – The name to be given to the function
path (str) – The path to the file where the three dimensional data is stored.

Returns:

formatted_data – A tuple containing the name of the function and the data formatted correctly for use within three-dimensional interpolants.

Return type:

tuple

Geometry#

class pybamm.Geometry(geometry)[source]#

A geometry class to store the details features of the cell geometry.

The values assigned to each domain are dictionaries containing the spatial variables in that domain, along with expression trees giving their min and maximum extents. For example, the following dictionary structure would represent a Geometry with a single domain “negative electrode”, defined using the variable x_n which has a range from 0 to the pre-defined parameter l_n.

{"negative electrode": {x_n: {"min": pybamm.Scalar(0), "max": l_n}}}

Parameters:: geometries (dict) – The dictionary to create the geometry with

Extends: builtins.dict

property parameters#: Returns all the parameters in the geometry

print_parameter_info()[source]#: Prints all the parameters’ information

Battery Geometry#

pybamm.battery_geometry(include_particles=True, options=None, form_factor='pouch')[source]#

A convenience function to create battery geometries.

Parameters:

include_particles (bool, optional) – Whether to include particle domains. Can be True (default) or False.
options (dict, optional) – Dictionary of model options. Necessary for “particle-size geometry”, relevant for lithium-ion chemistries.
form_factor (str, optional) – The form factor of the cell. Can be “pouch” (default) or “cylindrical”.

Returns:

A geometry class for the battery

Return type:

pybamm.Geometry

Meshes#

class pybamm.Mesh(geometry, submesh_types, var_pts)[source]#

Mesh contains a list of submeshes on each subdomain.

Parameters:

geometry – contains the geometry of the problem.
submesh_types (dict) – contains the types of submeshes to use (e.g. Uniform1DSubMesh)
submesh_pts (dict) – contains the number of points on each subdomain

Extends: builtins.dict

add_ghost_meshes()[source]#: Create meshes for potential ghost nodes on either side of each submesh, using self.submeshclass This will be useful for calculating the gradient with Dirichlet BCs.

combine_submeshes(*submeshnames)[source]#

Combine submeshes into a new submesh, using self.submeshclass Raises pybamm.DomainError if submeshes to be combined do not match up (edges are not aligned).

Parameters:: submeshnames (list of str) – The names of the submeshes to be combined
Returns:: submesh – A new submesh with the class defined by self.submeshclass
Return type:: self.submeshclass

class pybamm.SubMesh[source]#: Base submesh class. Contains the position of the nodes, the number of mesh points, and (optionally) information about the tab locations.

class pybamm.MeshGenerator(submesh_type, submesh_params=None)[source]#

Base class for mesh generator objects that are used to generate submeshes.

Parameters:

submesh_type (pybamm.SubMesh) – The type of submesh to use (e.g. Uniform1DSubMesh).
submesh_params (dict, optional) – Contains any parameters required by the submesh.

0D Sub Mesh#

class pybamm.SubMesh0D(position, npts=None)[source]#

0D submesh class. Contains the position of the node.

Parameters:

position (dict) – A dictionary that contains the position of the 0D submesh (a signle point) in space
npts (dict, optional) – Number of points to be used. Included for compatibility with other meshes, but ignored by this mesh class

Extends: pybamm.meshes.meshes.SubMesh

1D Sub Meshes#

class pybamm.SubMesh1D(edges, coord_sys, tabs=None)[source]#

1D submesh class. Contains the position of the nodes, the number of mesh points, and (optionally) information about the tab locations.

Parameters:

edges (array_like) – An array containing the points corresponding to the edges of the submesh
coord_sys (string) – The coordinate system of the submesh
tabs (dict, optional) – A dictionary that contains information about the size and location of the tabs

Extends: pybamm.meshes.meshes.SubMesh

class pybamm.Uniform1DSubMesh(lims, npts)[source]#

A class to generate a uniform submesh on a 1D domain

Parameters:

lims (dict) – A dictionary that contains the limits of the spatial variables
npts (dict) – A dictionary that contains the number of points to be used on each spatial variable. Note: the number of nodes (located at the cell centres) is npts, and the number of edges is npts+1.

Extends: pybamm.meshes.one_dimensional_submeshes.SubMesh1D

class pybamm.Exponential1DSubMesh(lims, npts, side='symmetric', stretch=None)[source]#

A class to generate a submesh on a 1D domain in which the points are clustered close to one or both of boundaries using an exponential formula on the interval [a,b].

If side is “left”, the gridpoints are given by

\[x_{k} = (b-a) + \frac{\mathrm{e}^{\alpha k / N} - 1}{\mathrm{e}^{\alpha} - 1} + a,\]

for k = 1, …, N, where N is the number of nodes.

Is side is “right”, the gridpoints are given by

\[x_{k} = (b-a) + \frac{\mathrm{e}^{-\alpha k / N} - 1}{\mathrm{e}^{-\alpha} - 1} + a,\]

for k = 1, …, N.

If side is “symmetric”, the first half of the interval is meshed using the gridpoints

\[x_{k} = (b/2-a) + \frac{\mathrm{e}^{\alpha k / N} - 1}{\mathrm{e}^{\alpha} - 1} + a,\]

for k = 1, …, N. The grid spacing is then reflected to contruct the grid on the full interval [a,b].

In the above, alpha is a stretching factor. As the number of gridpoints tends to infinity, the ratio of the largest and smallest grid cells tends to exp(alpha).

Parameters:

lims (dict) – A dictionary that contains the limits of the spatial variables
npts (dict) – A dictionary that contains the number of points to be used on each spatial variable. Note: the number of nodes (located at the cell centres) is npts, and the number of edges is npts+1.
side (str, optional) – Whether the points are clustered near to the left or right boundary, or both boundaries. Can be “left”, “right” or “symmetric”. Default is “symmetric”
stretch (float, optional) – The factor (alpha) which appears in the exponential. If side is “symmetric” then the default stretch is 1.15. If side is “left” or “right” then the default stretch is 2.3.

Extends: pybamm.meshes.one_dimensional_submeshes.SubMesh1D

class pybamm.Chebyshev1DSubMesh(lims, npts, tabs=None)[source]#

A class to generate a submesh on a 1D domain using Chebyshev nodes on the interval (a, b), given by

\[x_{k} = \frac{1}{2}(a+b) + \frac{1}{2}(b-a) \cos(\frac{2k-1}{2N}\pi),\]

for k = 1, …, N, where N is the number of nodes. Note: this mesh then appends the boundary edges, so that the mesh edges are given by

\[a < x_{1} < ... < x_{N} < b.\]

Parameters:

lims (dict) – A dictionary that contains the limits of the spatial variables
npts (dict) – A dictionary that contains the number of points to be used on each spatial variable. Note: the number of nodes (located at the cell centres) is npts, and the number of edges is npts+1.
tabs (dict, optional) – A dictionary that contains information about the size and location of the tabs

Extends: pybamm.meshes.one_dimensional_submeshes.SubMesh1D

class pybamm.UserSupplied1DSubMesh(lims, npts, edges=None)[source]#

A class to generate a submesh on a 1D domain from a user supplied array of edges.

Parameters:

lims (dict) – A dictionary that contains the limits of the spatial variables
npts (dict) – A dictionary that contains the number of points to be used on each spatial variable. Note: the number of nodes (located at the cell centres) is npts, and the number of edges is npts+1.
edges (array_like) – The array of points which correspond to the edges of the mesh.

Extends: pybamm.meshes.one_dimensional_submeshes.SubMesh1D

2D Sub Meshes#

class pybamm.ScikitSubMesh2D(edges, coord_sys, tabs)[source]#

2D submesh class. Contains information about the 2D finite element mesh. Note: This class only allows for the use of piecewise-linear triangular finite elements.

Parameters:

edges (array_like) – An array containing the points corresponding to the edges of the submesh
coord_sys (string) – The coordinate system of the submesh
tabs (dict, optional) – A dictionary that contains information about the size and location of the tabs

Extends: pybamm.meshes.meshes.SubMesh

on_boundary(y, z, tab)[source]#: A method to get the degrees of freedom corresponding to the subdomains for the tabs.

class pybamm.ScikitUniform2DSubMesh(lims, npts)[source]#

Contains information about the 2D finite element mesh with uniform grid spacing (can be different spacing in y and z). Note: This class only allows for the use of piecewise-linear triangular finite elements.

Parameters:

lims (dict) – A dictionary that contains the limits of each spatial variable
npts (dict) – A dictionary that contains the number of points to be used on each spatial variable

Extends: pybamm.meshes.scikit_fem_submeshes.ScikitSubMesh2D

class pybamm.ScikitExponential2DSubMesh(lims, npts, side='top', stretch=2.3)[source]#

Contains information about the 2D finite element mesh generated by taking the tensor product of a uniformly spaced grid in the y direction, and a unequally spaced grid in the z direction in which the points are clustered close to the top boundary using an exponential formula on the interval [a,b]. The gridpoints in the z direction are given by

\[z_{k} = (b-a) + \frac{\exp{-\alpha k / N} - 1}{\exp{-\alpha} - 1} + a,\]

for k = 1, …, N, where N is the number of nodes. Here alpha is a stretching factor. As the number of gridpoints tends to infinity, the ratio of the largest and smallest grid cells tends to exp(alpha).

Note: in the future this will be extended to allow points to be clustered near any of the boundaries.

Parameters:

lims (dict) – A dictionary that contains the limits of each spatial variable
npts (dict) – A dictionary that contains the number of points to be used on each spatial variable
side (str, optional) – Whether the points are clustered near to a particular boundary. At present, can only be “top”. Default is “top”.
stretch (float, optional) – The factor (alpha) which appears in the exponential. Default is 2.3.

Extends: pybamm.meshes.scikit_fem_submeshes.ScikitSubMesh2D

class pybamm.ScikitChebyshev2DSubMesh(lims, npts)[source]#

Contains information about the 2D finite element mesh generated by taking the tensor product of two 1D meshes which use Chebyshev nodes on the interval (a, b), given by

\[x_{k} = \frac{1}{2}(a+b) + \frac{1}{2}(b-a) \cos(\frac{2k-1}{2N}\pi),\]

for k = 1, …, N, where N is the number of nodes. Note: this mesh then appends the boundary edgess, so that the 1D mesh edges are given by

\[a < x_{1} < ... < x_{N} < b.\]

Note: This class only allows for the use of piecewise-linear triangular finite elements.

Parameters:

lims (dict) – A dictionary that contains the limits of each spatial variable
npts (dict) – A dictionary that contains the number of points to be used on each spatial variable

Extends: pybamm.meshes.scikit_fem_submeshes.ScikitSubMesh2D

class pybamm.UserSupplied2DSubMesh(lims, npts, y_edges=None, z_edges=None)[source]#

A class to generate a tensor product submesh on a 2D domain by using two user supplied vectors of edges: one for the y-direction and one for the z-direction. Note: this mesh should be created using UserSupplied2DSubMeshGenerator.

Parameters:

lims (dict) – A dictionary that contains the limits of the spatial variables
npts (dict) – A dictionary that contains the number of points to be used on each spatial variable. Note: the number of nodes (located at the cell centres) is npts, and the number of edges is npts+1.
y_edges (array_like) – The array of points which correspond to the edges in the y direction of the mesh.
z_edges (array_like) – The array of points which correspond to the edges in the z direction of the mesh.

Extends: pybamm.meshes.scikit_fem_submeshes.ScikitSubMesh2D

Discretisation and spatial methods#

Discretisation#

class pybamm.Discretisation(mesh=None, spatial_methods=None)[source]#

The discretisation class, with methods to process a model and replace Spatial Operators with Matrices and Variables with StateVectors

Parameters:

mesh (pybamm.Mesh) – contains all submeshes to be used on each domain
spatial_methods (dict) – a dictionary of the spatial methods to be used on each domain. The keys correspond to the model domains and the values to the spatial method.

check_model(model)[source]#: Perform some basic checks to make sure the discretised model makes sense.

check_tab_conditions(symbol, bcs)[source]#

Check any boundary conditions applied on “negative tab”, “positive tab” and “no tab”. For 1D current collector meshes, these conditions are converted into boundary conditions on “left” (tab at z=0) or “right” (tab at z=l_z) depending on the tab location stored in the mesh. For 2D current collector meshes, the boundary conditions can be applied on the tabs directly.

Parameters:

symbol (pybamm.expression_tree.symbol.Symbol) – The symbol on which the boundary conditions are applied.
bcs (dict) – The dictionary of boundary conditions (a dict of {side: equation}).

Returns:

The dictionary of boundary conditions, with the keys changed to “left” and “right” where necessary.

Return type:

check_variables(model)[source]#: Check variables in variable list against rhs. Be lenient with size check if the variable in model.variables is broadcasted, or a concatenation (if broadcasted, variable is a multiplication with a vector of ones)

create_mass_matrix(model)[source]#

Creates mass matrix of the discretised model. Note that the model is assumed to be of the form M*y_dot = f(t,y), where M is the (possibly singular) mass matrix.

Parameters:

model (pybamm.BaseModel) – Discretised model. Must have attributes rhs, initial_conditions and boundary_conditions (all dicts of {variable: equation})

Returns:

pybamm.Matrix – The mass matrix
pybamm.Matrix – The inverse of the ode part of the mass matrix (required by solvers which only accept the ODEs in explicit form)

process_boundary_conditions(model)[source]#

Discretise model boundary_conditions, also converting keys to ids

Parameters:: model (pybamm.BaseModel) – Model to dicretise. Must have attributes rhs, initial_conditions and boundary_conditions (all dicts of {variable: equation})
Returns:: Dictionary of processed boundary conditions
Return type:: dict

process_dict(var_eqn_dict, ics=False)[source]#

Discretise a dictionary of {variable: equation}, broadcasting if necessary (can be model.rhs, model.algebraic, model.initial_conditions or model.variables).

Parameters:

var_eqn_dict (dict) – Equations ({variable: equation} dict) to dicretise (can be model.rhs, model.algebraic, model.initial_conditions or model.variables)
ics (bool, optional) – Whether the equations are initial conditions. If True, the equations are scaled by the reference value of the variable, if given

Returns:

new_var_eqn_dict – Discretised equations

Return type:

pybamm.MatrixMultiplication

process_initial_conditions(model)[source]#

Discretise model initial_conditions.

Parameters:: model (pybamm.BaseModel) – Model to dicretise. Must have attributes rhs, initial_conditions and boundary_conditions (all dicts of {variable: equation})
Returns:: Tuple of processed_initial_conditions (dict of initial conditions) and concatenated_initial_conditions (numpy array of concatenated initial conditions)
Return type:: tuple

process_model(model, inplace=True, check_model=True, remove_independent_variables_from_rhs=True)[source]#

Discretise a model. Currently inplace, could be changed to return a new model.

Parameters:

model (pybamm.BaseModel) – Model to dicretise. Must have attributes rhs, initial_conditions and boundary_conditions (all dicts of {variable: equation})
inplace (bool, optional) – If True, discretise the model in place. Otherwise, return a new discretised model. Default is True.
check_model (bool, optional) – If True, model checks are performed after discretisation. For large systems these checks can be slow, so can be skipped by setting this option to False. When developing, testing or debugging it is recommended to leave this option as True as it may help to identify any errors. Default is True.
remove_independent_variables_from_rhs (bool, optional) – If True, model checks to see whether any variables from the RHS are used in any other equation. If a variable meets all of the following criteria (not used anywhere in the model, len(rhs)>1), then the variable is moved to be explicitly integrated when called by the solution object. Default is True.

Returns:

model_disc – The discretised model. Note that if inplace is True, model will have also been discretised in place so model == model_disc. If inplace is False, model != model_disc

Return type:

pybamm.BaseModel

Raises:

pybamm.ModelError – If an empty model is passed (model.rhs = {} and model.algebraic = {} and model.variables = {})

process_rhs_and_algebraic(model)[source]#

Discretise model equations - differential (‘rhs’) and algebraic.

Parameters:: model (pybamm.BaseModel) – Model to dicretise. Must have attributes rhs, initial_conditions and boundary_conditions (all dicts of {variable: equation})
Returns:: Tuple of processed_rhs (dict of processed differential equations), processed_concatenated_rhs, processed_algebraic (dict of processed algebraic equations) and processed_concatenated_algebraic
Return type:: tuple

process_symbol(symbol)[source]#

Discretise operators in model equations. If a symbol has already been discretised, the stored value is returned.

Parameters:: symbol (pybamm.expression_tree.symbol.Symbol) – Symbol to discretise
Returns:: Discretised symbol
Return type:: pybamm.expression_tree.symbol.Symbol

set_internal_boundary_conditions(model)[source]#: A method to set the internal boundary conditions for the submodel. These are required to properly calculate the gradient. Note: this method modifies the state of self.boundary_conditions.

set_variable_slices(variables)[source]#

Sets the slicing for variables.

Parameters:: variables (iterable of pybamm.Variables) – The variables for which to set slices

Spatial Method#

class pybamm.SpatialMethod(options=None)[source]#

A general spatial methods class, with default (trivial) behaviour for some spatial operations. All spatial methods will follow the general form of SpatialMethod in that they contain a method for broadcasting variables onto a mesh, a gradient operator, and a divergence operator.

Parameters:: mesh – Contains all the submeshes for discretisation

boundary_integral(child, discretised_child, region)[source]#

Implements the boundary integral for a spatial method.

Parameters:

child (pybamm.Symbol) – The symbol to which is being integrated
discretised_child (pybamm.Symbol) – The discretised symbol of the correct size
region (str) – The region of the boundary over which to integrate. If region is None (default) the integration is carried out over the entire boundary. If region is negative tab or positive tab then the integration is only carried out over the appropriate part of the boundary corresponding to the tab.

Returns:

Contains the result of acting the discretised boundary integral on the child discretised_symbol

Return type:

boundary_value_or_flux(symbol, discretised_child, bcs=None)[source]#

Returns the boundary value or flux using the appropriate expression for the spatial method. To do this, we create a sparse vector ‘bv_vector’ that extracts either the first (for side=”left”) or last (for side=”right”) point from ‘discretised_child’.

Parameters:

symbol (pybamm.Symbol) – The boundary value or flux symbol
discretised_child (pybamm.StateVector) – The discretised variable from which to calculate the boundary value
bcs (dict (optional)) – The boundary conditions. If these are supplied and “use bcs” is True in the options, then these will be used to improve the accuracy of the extrapolation.

Returns:

The variable representing the surface value.

Return type:

broadcast(symbol, domains, broadcast_type)[source]#

Broadcast symbol to a specified domain.

Parameters:

symbol (pybamm.Symbol) – The symbol to be broadcasted
domains (dict of strings) – The domains for broadcasting
broadcast_type (str) – The type of broadcast: ‘primary to node’, ‘primary to edges’, ‘secondary to nodes’, ‘secondary to edges’, ‘tertiary to nodes’, ‘tertiary to edges’, ‘full to nodes’ or ‘full to edges’

Returns:

broadcasted_symbol – The discretised symbol of the correct size for the spatial method

Return type:

concatenation(disc_children)[source]#

Discrete concatenation object.

Parameters:: disc_children (list) – List of discretised children
Returns:: Concatenation of the discretised children
Return type:: pybamm.DomainConcatenation

delta_function(symbol, discretised_symbol)[source]#

Implements the delta function on the approriate side for a spatial method.

Parameters:

symbol (pybamm.Symbol) – The symbol to which is being integrated
discretised_symbol (pybamm.Symbol) – The discretised symbol of the correct size

divergence(symbol, discretised_symbol, boundary_conditions)[source]#

Implements the divergence for a spatial method.

Parameters:

symbol (pybamm.Symbol) – The symbol that we will take the gradient of.
discretised_symbol (pybamm.Symbol) – The discretised symbol of the correct size
boundary_conditions (dict) – The boundary conditions of the model ({symbol: {“left”: left bc, “right”: right bc}})

Returns:

Contains the result of acting the discretised divergence on the child discretised_symbol

Return type:

evaluate_at(symbol, discretised_child, position)[source]#

Returns the symbol evaluated at a given position in space.

Parameters:

symbol (pybamm.Symbol) – The boundary value or flux symbol
discretised_child (pybamm.StateVector) – The discretised variable from which to calculate the boundary value
position (pybamm.Scalar) – The point in one-dimensional space at which to evaluate the symbol.

Returns:

The variable representing the value at the given point.

Return type:

pybamm.MatrixMultiplication

gradient(symbol, discretised_symbol, boundary_conditions)[source]#

Implements the gradient for a spatial method.

Parameters:

symbol (pybamm.Symbol) – The symbol that we will take the gradient of.
discretised_symbol (pybamm.Symbol) – The discretised symbol of the correct size
boundary_conditions (dict) – The boundary conditions of the model ({symbol: {“left”: left bc, “right”: right bc}})

Returns:

Contains the result of acting the discretised gradient on the child discretised_symbol

Return type:

gradient_squared(symbol, discretised_symbol, boundary_conditions)[source]#

Implements the inner product of the gradient with itself for a spatial method.

Parameters:

symbol (pybamm.Symbol) – The symbol that we will take the gradient of.
discretised_symbol (pybamm.Symbol) – The discretised symbol of the correct size
boundary_conditions (dict) – The boundary conditions of the model ({symbol: {“left”: left bc, “right”: right bc}})

Returns:

Contains the result of taking the inner product of the result of acting the discretised gradient on the child discretised_symbol with itself

Return type:

indefinite_integral(child, discretised_child, direction)[source]#

Implements the indefinite integral for a spatial method.

Parameters:

child (pybamm.Symbol) – The symbol to which is being integrated
discretised_child (pybamm.Symbol) – The discretised symbol of the correct size
direction (str) – The direction of integration

Returns:

Contains the result of acting the discretised indefinite integral on the child discretised_symbol

Return type:

integral(child, discretised_child, integration_dimension)[source]#

Implements the integral for a spatial method.

Parameters:

child (pybamm.Symbol) – The symbol to which is being integrated
discretised_child (pybamm.Symbol) – The discretised symbol of the correct size
integration_dimension (str, optional) – The dimension in which to integrate (default is “primary”)

Returns:

Contains the result of acting the discretised integral on the child discretised_symbol

Return type:

internal_neumann_condition(left_symbol_disc, right_symbol_disc, left_mesh, right_mesh)[source]#

A method to find the internal Neumann conditions between two symbols on adjacent subdomains.

Parameters:

left_symbol_disc (pybamm.Symbol) – The discretised symbol on the left subdomain
right_symbol_disc (pybamm.Symbol) – The discretised symbol on the right subdomain
left_mesh (list) – The mesh on the left subdomain
right_mesh (list) – The mesh on the right subdomain

laplacian(symbol, discretised_symbol, boundary_conditions)[source]#

Implements the Laplacian for a spatial method.

Parameters:

symbol (pybamm.Symbol) – The symbol that we will take the gradient of.
discretised_symbol (pybamm.Symbol) – The discretised symbol of the correct size
boundary_conditions (dict) – The boundary conditions of the model ({symbol: {“left”: left bc, “right”: right bc}})

Returns:

Contains the result of acting the discretised Laplacian on the child discretised_symbol

Return type:

mass_matrix(symbol, boundary_conditions)[source]#

Calculates the mass matrix for a spatial method.

Parameters:

symbol (pybamm.Variable) – The variable corresponding to the equation for which we are calculating the mass matrix.
boundary_conditions (dict) – The boundary conditions of the model ({symbol: {“left”: left bc, “right”: right bc}})

Returns:

The (sparse) mass matrix for the spatial method.

Return type:

process_binary_operators(bin_op, left, right, disc_left, disc_right)[source]#

Discretise binary operators in model equations. Default behaviour is to return a new binary operator with the discretised children.

Parameters:

bin_op (pybamm.BinaryOperator) – Binary operator to discretise
left (pybamm.Symbol) – The left child of bin_op
right (pybamm.Symbol) – The right child of bin_op
disc_left (pybamm.Symbol) – The discretised left child of bin_op
disc_right (pybamm.Symbol) – The discretised right child of bin_op

Returns:

Discretised binary operator

Return type:

pybamm.BinaryOperator

spatial_variable(symbol)[source]#

Convert a pybamm.SpatialVariable node to a linear algebra object that can be evaluated (here, a pybamm.Vector on either the nodes or the edges).

Parameters:: symbol (pybamm.SpatialVariable) – The spatial variable to be discretised.
Returns:: Contains the discretised spatial variable
Return type:: pybamm.Vector

Finite Volume#

class pybamm.FiniteVolume(options=None)[source]#

A class which implements the steps specific to the finite volume method during discretisation.

For broadcast and mass_matrix, we follow the default behaviour from SpatialMethod.

Parameters:: mesh (pybamm.Mesh) – Contains all the submeshes for discretisation

Extends: pybamm.spatial_methods.spatial_method.SpatialMethod

add_ghost_nodes(symbol, discretised_symbol, bcs)[source]#

Add ghost nodes to a symbol.

For Dirichlet bcs, for a boundary condition “y = a at the left-hand boundary”, we concatenate a ghost node to the start of the vector y with value “2*a - y1” where y1 is the value of the first node. Similarly for the right-hand boundary condition.

For Neumann bcs no ghost nodes are added. Instead, the exact value provided by the boundary condition is used at the cell edge when calculating the gradient (see pybamm.FiniteVolume.add_neumann_values()).

Parameters:

symbol (pybamm.SpatialVariable) – The variable to be discretised
discretised_symbol (pybamm.Vector) – Contains the discretised variable
bcs (dict of tuples (pybamm.Scalar, str)) – Dictionary (with keys “left” and “right”) of boundary conditions. Each boundary condition consists of a value and a flag indicating its type (e.g. “Dirichlet”)

Returns:

Matrix @ discretised_symbol + bcs_vector. When evaluated, this gives the discretised_symbol, with appropriate ghost nodes concatenated at each end.

Return type:

add_neumann_values(symbol, discretised_gradient, bcs, domain)[source]#

Add the known values of the gradient from Neumann boundary conditions to the discretised gradient.

Dirichlet bcs are implemented using ghost nodes, see pybamm.FiniteVolume.add_ghost_nodes().

Parameters:

symbol (pybamm.SpatialVariable) – The variable to be discretised
discretised_gradient (pybamm.Vector) – Contains the discretised gradient of symbol
bcs (dict of tuples (pybamm.Scalar, str)) – Dictionary (with keys “left” and “right”) of boundary conditions. Each boundary condition consists of a value and a flag indicating its type (e.g. “Dirichlet”)
domain (list of strings) – The domain of the gradient of the symbol (may include ghost nodes)

Returns:

Matrix @ discretised_gradient + bcs_vector. When evaluated, this gives the discretised_gradient, with the values of the Neumann boundary conditions concatenated at each end (if given).

Return type:

boundary_value_or_flux(symbol, discretised_child, bcs=None)[source]#

Uses extrapolation to get the boundary value or flux of a variable in the Finite Volume Method.

See pybamm.SpatialMethod.boundary_value()

concatenation(disc_children)[source]#: Discrete concatenation, taking edge_to_node for children that evaluate on edges. See pybamm.SpatialMethod.concatenation()

definite_integral_matrix(child, vector_type='row', integration_dimension='primary')[source]#

Matrix for finite-volume implementation of the definite integral in the primary dimension

\[I = \int_{a}^{b}\!f(s)\,ds\]

for where $a$ and $b$ are the left-hand and right-hand boundaries of the domain respectively

Parameters:

child (pybamm.Symbol) – The symbol being integrated
vector_type (str, optional) – Whether to return a row or column vector in the primary dimension (default is row)
integration_dimension (str, optional) – The dimension in which to integrate (default is “primary”)

Returns:

The finite volume integral matrix for the domain

Return type:

See pybamm.SpatialMethod.delta_function()

delta_function(symbol, discretised_symbol)[source]#

Delta function. Implemented as a vector whose only non-zero element is the first (if symbol.side = “left”) or last (if symbol.side = “right”), with appropriate value so that the integral of the delta function across the whole domain is the same as the integral of the discretised symbol across the whole domain.

divergence(symbol, discretised_symbol, boundary_conditions)[source]#: Matrix-vector multiplication to implement the divergence operator. See pybamm.SpatialMethod.divergence()

divergence_matrix(domains)[source]#

Divergence matrix for finite volumes in the appropriate domain. Equivalent to div(N) = (N[1:] - N[:-1])/dx

Parameters:: domains (dict) – The domain(s) and auxiliary domain in which to compute the divergence matrix
Returns:: The (sparse) finite volume divergence matrix for the domain
Return type:: pybamm.Matrix

edge_to_node(discretised_symbol, method='arithmetic')[source]#: Convert a discretised symbol evaluated on the cell edges to a discretised symbol evaluated on the cell nodes. See pybamm.FiniteVolume.shift()

evaluate_at(symbol, discretised_child, position)[source]#

Returns the symbol evaluated at a given position in space.

Parameters:

symbol (pybamm.Symbol) – The boundary value or flux symbol
discretised_child (pybamm.StateVector) – The discretised variable from which to calculate the boundary value
position (pybamm.Scalar) – The point in one-dimensional space at which to evaluate the symbol.

Returns:

The variable representing the value at the given point.

Return type:

pybamm.MatrixMultiplication

gradient(symbol, discretised_symbol, boundary_conditions)[source]#: Matrix-vector multiplication to implement the gradient operator. See pybamm.SpatialMethod.gradient()

gradient_matrix(domain, domains)[source]#

Gradient matrix for finite volumes in the appropriate domain. Equivalent to grad(y) = (y[1:] - y[:-1])/dx

Parameters:: domains (list) – The domain in which to compute the gradient matrix, including ghost nodes
Returns:: The (sparse) finite volume gradient matrix for the domain
Return type:: pybamm.Matrix

indefinite_integral(child, discretised_child, direction)[source]#: Implementation of the indefinite integral operator.

indefinite_integral_matrix_edges(domains, direction)[source]#

Matrix for finite-volume implementation of the indefinite integral where the integrand is evaluated on mesh edges (shape (n+1, 1)). The integral will then be evaluated on mesh nodes (shape (n, 1)).

Parameters:

domains (dict) – The domain(s) and auxiliary domains of integration
direction (str) – The direction of integration (forward or backward). See notes.

Returns:

The finite volume integral matrix for the domain

Return type:

Notes

Forward integral

\[F(x) = \int_0^x\!f(u)\,du\]

The indefinite integral must satisfy the following conditions:

$F(0) = 0$
$f(x) = \frac{dF}{dx}$

or, in discrete form,

BoundaryValue(F, “left”) = 0, i.e. $3*F_0 - F_1 = 0$
$f_{i+1/2} = (F_{i+1} - F_i) / dx_{i+1/2}$

Hence we must have

$F_0 = du_{1/2} * f_{1/2} / 2$
$F_{i+1} = F_i + du_{i+1/2} * f_{i+1/2}$

Note that $f_{-1/2}$ and $f_{end+1/2}$ are included in the discrete integrand vector f, so we add a column of zeros at each end of the indefinite integral matrix to ignore these.

Backward integral

\[F(x) = \int_x^{end}\!f(u)\,du\]

The indefinite integral must satisfy the following conditions:

$F(end) = 0$
$f(x) = -\frac{dF}{dx}$

or, in discrete form,

BoundaryValue(F, “right”) = 0, i.e. $3*F_{end} - F_{end-1} = 0$
$f_{i+1/2} = -(F_{i+1} - F_i) / dx_{i+1/2}$

Hence we must have

$F_{end} = du_{end+1/2} * f_{end-1/2} / 2$
$F_{i-1} = F_i + du_{i-1/2} * f_{i-1/2}$

Note that $f_{-1/2}$ and $f_{end+1/2}$ are included in the discrete integrand vector f, so we add a column of zeros at each end of the indefinite integral matrix to ignore these.

indefinite_integral_matrix_nodes(domains, direction)[source]#

Matrix for finite-volume implementation of the (backward) indefinite integral where the integrand is evaluated on mesh nodes (shape (n, 1)). The integral will then be evaluated on mesh edges (shape (n+1, 1)). This is just a straightforward (backward) cumulative sum of the integrand

Parameters:

domains (dict) – The domain(s) and auxiliary domains of integration
direction (str) – The direction of integration (forward or backward)

Returns:

The finite volume integral matrix for the domain

Return type:

integral(child, discretised_child, integration_dimension)[source]#: Vector-vector dot product to implement the integral operator.

internal_neumann_condition(left_symbol_disc, right_symbol_disc, left_mesh, right_mesh)[source]#

A method to find the internal Neumann conditions between two symbols on adjacent subdomains.

Parameters:

left_symbol_disc (pybamm.Symbol) – The discretised symbol on the left subdomain
right_symbol_disc (pybamm.Symbol) – The discretised symbol on the right subdomain
left_mesh (list) – The mesh on the left subdomain
right_mesh (list) – The mesh on the right subdomain

laplacian(symbol, discretised_symbol, boundary_conditions)[source]#: Laplacian operator, implemented as div(grad(.)) See pybamm.SpatialMethod.laplacian()

node_to_edge(discretised_symbol, method='arithmetic')[source]#: Convert a discretised symbol evaluated on the cell nodes to a discretised symbol evaluated on the cell edges. See pybamm.FiniteVolume.shift()

process_binary_operators(bin_op, left, right, disc_left, disc_right)[source]#

Discretise binary operators in model equations. Performs appropriate averaging of diffusivities if one of the children is a gradient operator, so that discretised sizes match up. For this averaging we use the harmonic mean [1].

[1] Recktenwald, Gerald. “The control-volume finite-difference approximation to the diffusion equation.” (2012).

Parameters:

bin_op (pybamm.BinaryOperator) – Binary operator to discretise
left (pybamm.Symbol) – The left child of bin_op
right (pybamm.Symbol) – The right child of bin_op
disc_left (pybamm.Symbol) – The discretised left child of bin_op
disc_right (pybamm.Symbol) – The discretised right child of bin_op

Returns:

Discretised binary operator

Return type:

pybamm.BinaryOperator

shift(discretised_symbol, shift_key, method)[source]#

Convert a discretised symbol evaluated at edges/nodes, to a discretised symbol evaluated at nodes/edges. Can be the arithmetic mean or the harmonic mean.

Note: when computing fluxes at cell edges it is better to take the harmonic mean based on [1].

[1] Recktenwald, Gerald. “The control-volume finite-difference approximation to the diffusion equation.” (2012).

Parameters:

discretised_symbol (pybamm.Symbol) – Symbol to be averaged. When evaluated, this symbol returns either a scalar or an array of shape (n,) or (n+1,), where n is the number of points in the mesh for the symbol’s domain (n = self.mesh[symbol.domain].npts)
shift_key (str) – Whether to shift from nodes to edges (“node to edge”), or from edges to nodes (“edge to node”)
method (str) – Whether to use the “arithmetic” or “harmonic” mean

Returns:

Averaged symbol. When evaluated, this returns either a scalar or an array of shape (n+1,) (if shift_key = “node to edge”) or (n,) (if shift_key = “edge to node”)

Return type:

spatial_variable(symbol)[source]#

Creates a discretised spatial variable compatible with the FiniteVolume method.

Parameters:: symbol (pybamm.SpatialVariable) – The spatial variable to be discretised.
Returns:: Contains the discretised spatial variable
Return type:: pybamm.Vector

upwind_or_downwind(symbol, discretised_symbol, bcs, direction)[source]#

Implement an upwinding operator. Currently, this requires the symbol to have a Dirichlet boundary condition on the left side (for upwinding) or right side (for downwinding).

Parameters:

symbol (pybamm.SpatialVariable) – The variable to be discretised
discretised_gradient (pybamm.Vector) – Contains the discretised gradient of symbol
bcs (dict of tuples (pybamm.Scalar, str)) – Dictionary (with keys “left” and “right”) of boundary conditions. Each boundary condition consists of a value and a flag indicating its type (e.g. “Dirichlet”)
direction (str) – Direction in which to apply the operator (upwind or downwind)

Spectral Volume#

class pybamm.SpectralVolume(options=None, order=2)[source]#

A class which implements the steps specific to the Spectral Volume discretisation. It is implemented in such a way that it is very similar to FiniteVolume; that comes at the cost that it is only compatible with the SpectralVolume1DSubMesh (which is a certain subdivision of any 1D mesh, so it shouldn’t be a problem).

For broadcast and mass_matrix, we follow the default behaviour from SpatialMethod. For spatial_variable, divergence, divergence_matrix, laplacian, integral, definite_integral_matrix, indefinite_integral, indefinite_integral_matrix, indefinite_integral_matrix_nodes, indefinite_integral_matrix_edges, delta_function we follow the behaviour from FiniteVolume. This is possible since the node values are integral averages with Spectral Volume, just as with Finite Volume. delta_function assigns the integral value to a CV instead of a SV this way, but that doesn’t matter too much. Additional methods that are inherited by FiniteVolume which technically are not suitable for Spectral Volume are boundary_value_or_flux, process_binary_operators, concatenation, node_to_edge, edge_to_node and shift. While node_to_edge (as well as boundary_value_or_flux and process_binary_operators) could utilize the reconstruction approach of Spectral Volume, the inverse edge_to_node would still have to fall back to the Finite Volume behaviour. So these are simply inherited for consistency. boundary_value_or_flux might not benefit from the reconstruction approach at all, as it seems to only preprocess symbols.

Parameters:: mesh (pybamm.Mesh) – Contains all the submeshes for discretisation

Extends: pybamm.spatial_methods.finite_volume.FiniteVolume

chebyshev_collocation_points(noe, a=-1.0, b=1.0)[source]#

Calculates Chebyshev collocation points in descending order.

Parameters:

noe (integer) – The number of the collocation points. “number of edges”
a (float) – Left end of the interval on which the Chebyshev collocation points are constructed. Default is -1.
b (float) – Right end of the interval on which the Chebyshev collocation points are constructed. Default is 1.

Returns:

numpy.array
Chebyshev collocation points on [a,b].

chebyshev_differentiation_matrices(noe, dod)[source]#

Chebyshev differentiation matrices, from Baltensperger and Trummer[1].

Parameters:

noe (integer) – The number of the collocation points. “number of edges”
dod (integer) – The maximum order of differentiation for which a differentiation matrix shall be calculated. Note that it has to be smaller than ‘noe’. “degrees of differentiation”

Returns:

The differentiation matrices in ascending order of differentiation order. With exact arithmetic, the diff. matrix of order p would just be the pth matrix power of the diff. matrix of order 1. This method computes the higher orders in a more numerically stable way.

Return type:

list(numpy.array)

cv_boundary_reconstruction_matrix(domains)[source]#

“Broadcasts” the basic edge value reconstruction matrix to the actual shape of the discretised symbols. Note that the product of this and a discretised symbol is a vector which represents duplicate values for all inner SV edges. These are the reconstructed values from both sides.

Parameters:: domains (dict) – The domains in which to compute the gradient matrix
Returns:: The (sparse) CV reconstruction matrix for the domain
Return type:: pybamm.Matrix

cv_boundary_reconstruction_sub_matrix()[source]#: Coefficients for reconstruction of a function through averages. The resulting matrix is scale-invariant Wang[2].

gradient(symbol, discretised_symbol, boundary_conditions)[source]#: Matrix-vector multiplication to implement the gradient operator. See pybamm.SpatialMethod.gradient()

gradient_matrix(domain, domains)[source]#

Gradient matrix for Spectral Volume in the appropriate domain. Note that it contains the averaging of the duplicate SV edge gradient values, such that the product of it and a reconstructed discretised symbol simply represents CV edge values. On its own, it only works on non-concatenated domains, since only then the boundary conditions ensure correct behaviour. More generally, it only works if gradients are a result of boundary conditions rather than continuity conditions. For example, two adjacent SVs with gradient zero in each of them but with different variable values will have zero gradient between them. This is fixed with “penalty_matrix”.

Parameters:: domains (dict) – The domains in which to compute the gradient matrix
Returns:: The (sparse) Spectral Volume gradient matrix for the domain
Return type:: pybamm.Matrix

penalty_matrix(domains)[source]#

Penalty matrix for Spectral Volume in the appropriate domain. This works the same as the “gradient_matrix” of FiniteVolume does, just between SVs and not between CVs. Think of it as a continuity penalty.

Parameters:: domains (dict) – The domains in which to compute the gradient matrix
Returns:: The (sparse) Spectral Volume penalty matrix for the domain
Return type:: pybamm.Matrix

replace_dirichlet_values(symbol, discretised_symbol, bcs)[source]#

Replace the reconstructed value at Dirichlet boundaries with the boundary condition.

Parameters:

symbol (pybamm.SpatialVariable) – The variable to be discretised
discretised_symbol (pybamm.Vector) – Contains the discretised variable
bcs (dict of tuples (pybamm.Scalar, str)) – Dictionary (with keys “left” and “right”) of boundary conditions. Each boundary condition consists of a value and a flag indicating its type (e.g. “Dirichlet”)

Returns:

Matrix @ discretised_symbol + bcs_vector. When evaluated, this gives the discretised_symbol, with its boundary values replaced by the Dirichlet boundary conditions.

Return type:

replace_neumann_values(symbol, discretised_gradient, bcs)[source]#

Replace the known values of the gradient from Neumann boundary conditions into the discretised gradient.

Parameters:

symbol (pybamm.SpatialVariable) – The variable to be discretised
discretised_gradient (pybamm.Vector) – Contains the discretised gradient of symbol
bcs (dict of tuples (pybamm.Scalar, str)) – Dictionary (with keys “left” and “right”) of boundary conditions. Each boundary condition consists of a value and a flag indicating its type (e.g. “Dirichlet”)

Returns:

Matrix @ discretised_gradient + bcs_vector. When evaluated, this gives the discretised_gradient, with its boundary values replaced by the Neumann boundary conditions.

Return type:

References

Scikit Finite Elements#

class pybamm.ScikitFiniteElement(options=None)[source]#

A class which implements the steps specific to the finite element method during discretisation. The class uses scikit-fem to discretise the problem to obtain the mass and stiffness matrices. At present, this class is only used for solving the Poisson problem -grad^2 u = f in the y-z plane (i.e. not the through-cell direction).

For broadcast we follow the default behaviour from SpatialMethod.

Parameters:: mesh (pybamm.Mesh) – Contains all the submeshes for discretisation

Extends: pybamm.spatial_methods.spatial_method.SpatialMethod

assemble_mass_form(symbol, boundary_conditions, region='interior')[source]#

Assembles the form of the finite element mass matrix over the domain interior or boundary.

Parameters:

symbol (pybamm.Variable) – The variable corresponding to the equation for which we are calculating the mass matrix.
boundary_conditions (dict) – The boundary conditions of the model ({symbol: {“negative tab”: neg. tab bc, “positive tab”: pos. tab bc}})
region (str, optional) – The domain over which to assemble the mass matrix form. Can be “interior” (default) or “boundary”.

Returns:

The (sparse) mass matrix for the spatial method.

Return type:

bc_apply(M, boundary, zero=False)[source]#

Adjusts the assemled finite element matrices to account for boundary conditons.

Parameters:

M (scipy.sparse.coo_matrix) – The assemled finite element matrix to adjust.
boundary (numpy.array) – Array of the indicies which correspond to the boundary.
zero (bool, optional) – If True, the rows of M given by the indicies in boundary are set to zero. If False, the diagonal element is set to one. default is False.

boundary_integral(child, discretised_child, region)[source]#: Implementation of the boundary integral operator. See pybamm.SpatialMethod.boundary_integral()

boundary_integral_vector(domain, region)[source]#

A node in the expression tree representing an integral operator over the boundary of a domain

\[I = \int_{\partial a}\!f(u)\,du,\]

where $\partial a$ is the boundary of the domain, and $u\in\text{domain boundary}$.

Parameters:

domain (list) – The domain(s) of the variable in the integrand
region (str) – The region of the boundary over which to integrate. If region is entire the integration is carried out over the entire boundary. If region is negative tab or positive tab then the integration is only carried out over the appropriate part of the boundary corresponding to the tab.

Returns:

The finite element integral vector for the domain

Return type:

boundary_mass_matrix(symbol, boundary_conditions)[source]#

Calculates the mass matrix for the finite element method assembled over the boundary.

Parameters:

symbol (pybamm.Variable) – The variable corresponding to the equation for which we are calculating the mass matrix.
boundary_conditions (dict) – The boundary conditions of the model ({symbol: {“negative tab”: neg. tab bc, “positive tab”: pos. tab bc}})

Returns:

The (sparse) mass matrix for the spatial method.

Return type:

boundary_value_or_flux(symbol, discretised_child, bcs=None)[source]#

Returns the average value of the symbol over the negative tab (“negative tab”) or the positive tab (“positive tab”) in the Finite Element Method.

Overwrites the default pybamm.SpatialMethod.boundary_value()

definite_integral_matrix(child, vector_type='row')[source]#

Matrix for finite-element implementation of the definite integral over the entire domain

\[I = \int_{\Omega}\!f(s)\,dx\]

for where $\Omega$ is the domain.

Parameters:

child (pybamm.Symbol) – The symbol being integrated
vector_type (str, optional) – Whether to return a row or column vector (default is row)

Returns:

The finite element integral vector for the domain

Return type:

divergence(symbol, discretised_symbol, boundary_conditions)[source]#: Matrix-vector multiplication to implement the divergence operator. See pybamm.SpatialMethod.divergence()

gradient(symbol, discretised_symbol, boundary_conditions)[source]#

Matrix-vector multiplication to implement the gradient operator. The gradient w of the function u is approximated by the finite element method using the same function space as u, i.e. we solve w = grad(u), which corresponds to the weak form w*v*dx = grad(u)*v*dx, where v is a suitable test function.

Parameters:

symbol (pybamm.Symbol) – The symbol that we will take the Laplacian of.
discretised_symbol (pybamm.Symbol) – The discretised symbol of the correct size
boundary_conditions (dict) – The boundary conditions of the model ({symbol: {“negative tab”: neg. tab bc, “positive tab”: pos. tab bc}})

Returns:

A concatenation that contains the result of acting the discretised gradient on the child discretised_symbol. The first column corresponds to the y-component of the gradient and the second column corresponds to the z component of the gradient.

Return type:

gradient_matrix(symbol, boundary_conditions)[source]#

Gradient matrix for finite elements in the appropriate domain.

Parameters:

symbol (pybamm.Symbol) – The symbol for which we want to calculate the gradient matrix
boundary_conditions (dict) – The boundary conditions of the model ({symbol: {“negative tab”: neg. tab bc, “positive tab”: pos. tab bc}})

Returns:

The (sparse) finite element gradient matrix for the domain

Return type:

gradient_squared(symbol, discretised_symbol, boundary_conditions)[source]#: Multiplication to implement the inner product of the gradient operator with itself. See pybamm.SpatialMethod.gradient_squared()

indefinite_integral(child, discretised_child, direction)[source]#: Implementation of the indefinite integral operator. The input discretised child must be defined on the internal mesh edges. See pybamm.SpatialMethod.indefinite_integral()

integral(child, discretised_child, integration_dimension)[source]#: Vector-vector dot product to implement the integral operator. See pybamm.SpatialMethod.integral()

laplacian(symbol, discretised_symbol, boundary_conditions)[source]#

Matrix-vector multiplication to implement the Laplacian operator.

Parameters:

symbol (pybamm.Symbol) – The symbol that we will take the Laplacian of.
discretised_symbol (pybamm.Symbol) – The discretised symbol of the correct size
boundary_conditions (dict) – The boundary conditions of the model ({symbol: {“negative tab”: neg. tab bc, “positive tab”: pos. tab bc}})

Returns:

Contains the result of acting the discretised gradient on the child discretised_symbol

Return type:

mass_matrix(symbol, boundary_conditions)[source]#

Calculates the mass matrix for the finite element method.

Parameters:

symbol (pybamm.Variable) – The variable corresponding to the equation for which we are calculating the mass matrix.
boundary_conditions (dict) – The boundary conditions of the model ({symbol: {“negative tab”: neg. tab bc, “positive tab”: pos. tab bc}})

Returns:

The (sparse) mass matrix for the spatial method.

Return type:

spatial_variable(symbol)[source]#

Creates a discretised spatial variable compatible with the FiniteElement method.

Parameters:: symbol (pybamm.SpatialVariable) – The spatial variable to be discretised.
Returns:: Contains the discretised spatial variable
Return type:: pybamm.Vector

stiffness_matrix(symbol, boundary_conditions)[source]#

Laplacian (stiffness) matrix for finite elements in the appropriate domain.

Parameters:

symbol (pybamm.Symbol) – The symbol for which we want to calculate the Laplacian matrix
boundary_conditions (dict) – The boundary conditions of the model ({symbol: {“negative tab”: neg. tab bc, “positive tab”: pos. tab bc}})

Returns:

The (sparse) finite element stiffness matrix for the domain

Return type:

Zero Dimensional Spatial Method#

class pybamm.ZeroDimensionalSpatialMethod(options=None)[source]#

A discretisation class for the zero dimensional mesh

Parameters:: mesh – Contains all the submeshes for discretisation

Extends: pybamm.spatial_methods.spatial_method.SpatialMethod

boundary_value_or_flux(symbol, discretised_child, bcs=None)[source]#: In 0D, the boundary value is the identity operator. See SpatialMethod.boundary_value_or_flux()

indefinite_integral(child, discretised_child, direction)[source]#: Calculates the zero-dimensional indefinite integral. If ‘direction’ is forward, this is the identity operator. If ‘direction’ is backward, this is the negation operator.

integral(child, discretised_child, integration_dimension)[source]#: Calculates the zero-dimensional integral, i.e. the identity operator

mass_matrix(symbol, boundary_conditions)[source]#: Calculates the mass matrix for a spatial method. Since the spatial method is zero dimensional, this is simply the number 1.

Solvers#

Base Solver#

class pybamm.BaseSolver(method=None, rtol=1e-06, atol=1e-06, root_method=None, root_tol=1e-06, extrap_tol=None, output_variables=[])[source]#

Solve a discretised model.

Parameters:

method (str, optional) – The method to use for integration, specific to each solver
rtol (float, optional) – The relative tolerance for the solver (default is 1e-6).
atol (float, optional) – The absolute tolerance for the solver (default is 1e-6).
root_method (str or pybamm algebraic solver class, optional) – The method to use to find initial conditions (for DAE solvers). If a solver class, must be an algebraic solver class. If “casadi”, the solver uses casadi’s Newton rootfinding algorithm to find initial conditions. Otherwise, the solver uses ‘scipy.optimize.root’ with method specified by ‘root_method’ (e.g. “lm”, “hybr”, …)
root_tol (float, optional) – The tolerance for the initial-condition solver (default is 1e-6).
extrap_tol (float, optional) – The tolerance to assert whether extrapolation occurs or not. Default is 0.
output_variables (list[str], optional) – List of variables to calculate and return. If none are specified then the complete state vector is returned (can be very large) (default is [])

calculate_consistent_state(model, time=0, inputs=None)[source]#

Calculate consistent state for the algebraic equations through root-finding. model.y0 is used as the initial guess for rootfinding

Parameters:

model (pybamm.BaseModel) – The model for which to calculate initial conditions.
time (float) – The time at which to calculate the states
inputs (dict, optional) – Any input parameters to pass to the model when solving

Returns:

y0_consistent – Initial conditions that are consistent with the algebraic equations (roots of the algebraic equations). If self.root_method == None then returns model.y0.

Return type:

array-like, same shape as y0_guess

check_extrapolation(solution, events)[source]#

Check if extrapolation occurred for any of the interpolants. Note that with the current approach (evaluating all the events at the solution times) some extrapolations might not be found if they only occurred for a small period of time.

Parameters:

solution (pybamm.Solution) – The solution object
events (dict) – Dictionary of events

copy()[source]#: Returns a copy of the solver

get_termination_reason(solution, events)[source]#

Identify the cause for termination. In particular, if the solver terminated due to an event, (try to) pinpoint which event was responsible. If an event occurs the event time and state are added to the solution object. Note that the current approach (evaluating all the events and then finding which one is smallest at the final timestep) is pretty crude, but is the easiest one that works for all the different solvers.

Parameters:

solution (pybamm.Solution) – The solution object
events (dict) – Dictionary of events

set_up(model, inputs=None, t_eval=None, ics_only=False)[source]#

Unpack model, perform checks, and calculate jacobian.

Parameters:

model (pybamm.BaseModel) – The model whose solution to calculate. Must have attributes rhs and initial_conditions
inputs (dict, optional) – Any input parameters to pass to the model when solving
t_eval (numeric type, optional) – The times (in seconds) at which to compute the solution

solve(model, t_eval=None, inputs=None, nproc=None, calculate_sensitivities=False)[source]#

Execute the solver setup and calculate the solution of the model at specified times.

Parameters:

model (pybamm.BaseModel) – The model whose solution to calculate. Must have attributes rhs and initial_conditions. All calls to solve must pass in the same model or an error is raised
t_eval (numeric type) – The times (in seconds) at which to compute the solution
inputs (dict or list, optional) – A dictionary or list of dictionaries describing any input parameters to pass to the model when solving
nproc (int, optional) – Number of processes to use when solving for more than one set of input parameters. Defaults to value returned by “os.cpu_count()”.
calculate_sensitivities (list of str or bool) – If true, solver calculates sensitivities of all input parameters. If only a subset of sensitivities are required, can also pass a list of input parameter names

Returns:

If type of inputs is list, return a list of corresponding pybamm.Solution objects.

Return type:

pybamm.Solution or list of pybamm.Solution objects.

Raises:

pybamm.ModelError – If an empty model is passed (model.rhs = {} and model.algebraic={} and model.variables = {})
RuntimeError – If multiple calls to solve pass in different models

step(old_solution, model, dt, npts=2, inputs=None, save=True)[source]#

Step the solution of the model forward by a given time increment. The first time this method is called it executes the necessary setup by calling self.set_up(model).

Parameters:

old_solution (pybamm.Solution or None) – The previous solution to be added to. If None, a new solution is created.
model (pybamm.BaseModel) – The model whose solution to calculate. Must have attributes rhs and initial_conditions
dt (numeric type) – The timestep (in seconds) over which to step the solution
npts (int, optional) – The number of points at which the solution will be returned during the step dt. default is 2 (returns the solution at t0 and t0 + dt).
inputs (dict, optional) – Any input parameters to pass to the model when solving
save (bool) – Turn on to store the solution of all previous timesteps

Raises:

pybamm.ModelError – If an empty model is passed (model.rhs = {} and model.algebraic = {} and model.variables = {})

Dummy Solver#

class pybamm.DummySolver[source]#

Dummy solver class for empty models.

Extends: pybamm.solvers.base_solver.BaseSolver

Scipy Solver#

class pybamm.ScipySolver(method='BDF', rtol=1e-06, atol=1e-06, extrap_tol=None, extra_options=None)[source]#

Solve a discretised model, using scipy.integrate.solve_ivp.

Parameters:

method (str, optional) – The method to use in solve_ivp (default is “BDF”)
rtol (float, optional) – The relative tolerance for the solver (default is 1e-6).
atol (float, optional) – The absolute tolerance for the solver (default is 1e-6).
extrap_tol (float, optional) – The tolerance to assert whether extrapolation occurs or not (default is 0).
extra_options (dict, optional) – Any options to pass to the solver. Please consult SciPy documentation for details.

Extends: pybamm.solvers.base_solver.BaseSolver

JAX Solver#

class pybamm.JaxSolver(method='RK45', root_method=None, rtol=1e-06, atol=1e-06, extrap_tol=None, extra_options=None)[source]#

Solve a discretised model using a JAX compiled solver.

Note: this solver will not work with models that have: termination events or are not converted to jax format

Raises:

RuntimeError – if model has any termination events
RuntimeError – if model.convert_to_format != ‘jax’

Parameters:

method (str) – ‘RK45’ (default) uses jax.experimental.odeint ‘BDF’ uses custom jax_bdf_integrate (see jax_bdf_integrate.py for details)
root_method (str, optional) – Method to use to calculate consistent initial conditions. By default this uses the newton chord method internal to the jax bdf solver, otherwise choose from the set of default options defined in docs for pybamm.BaseSolver
rtol (float, optional) – The relative tolerance for the solver (default is 1e-6).
atol (float, optional) – The absolute tolerance for the solver (default is 1e-6).
extrap_tol (float, optional) – The tolerance to assert whether extrapolation occurs or not (default is 0).
extra_options (dict, optional) – Any options to pass to the solver. Please consult JAX documentation for details.

Extends: pybamm.solvers.base_solver.BaseSolver

create_solve(model, t_eval)[source]#

Return a compiled JAX function that solves an ode model with input arguments.

Parameters:

model (pybamm.BaseModel) – The model whose solution to calculate.
t_eval (numpy.array, size (k,)) – The times at which to compute the solution

Returns:

A function with signature f(inputs), where inputs are a dict containing any input parameters to pass to the model when solving

Return type:

function

get_solve(model, t_eval)[source]#

Return a compiled JAX function that solves an ode model with input arguments.

Parameters:

model (pybamm.BaseModel) – The model whose solution to calculate.
t_eval (numpy.array, size (k,)) – The times at which to compute the solution

Returns:

A function with signature f(inputs), where inputs are a dict containing any input parameters to pass to the model when solving

Return type:

function

pybamm.jax_bdf_integrate(func, y0, t_eval, *args, rtol=1e-06, atol=1e-06, mass=None)[source]#

Backward Difference formula (BDF) implicit multistep integrator. The basic algorithm is derived in Byrne and Hindmarsh[1]. This particular implementation follows that implemented in the Matlab routine ode15s described in Shampine and Reichelt[2] and the SciPy implementation Virtanen et al.[3] which features the NDF formulas for improved stability, with associated differences in the error constants, and calculates the jacobian at J(t_{n+1}, y^0_{n+1}). This implementation was based on that implemented in the SciPy library Virtanen et al.[3], which also mainly follows Shampine and Reichelt[2] but uses the more standard jacobian update.

Parameters:

func (callable) – function to evaluate the time derivative of the solution y at time t as func(y, t, *args), producing the same shape/structure as y0.
y0 (ndarray) – initial state vector
t_eval (ndarray) – time points to evaluate the solution, has shape (m,)
args ((optional)) – tuple of additional arguments for fun, which must be arrays scalars, or (nested) standard Python containers (tuples, lists, dicts, namedtuples, i.e. pytrees) of those types.
rtol ((optional) float) – relative tolerance for the solver
atol ((optional) float) – absolute tolerance for the solver
mass ((optional) ndarray) – diagonal of the mass matrix with shape (n,)

Returns:

y – calculated state vector at each of the m time points

Return type:

ndarray with shape (n, m)

References

IDAKLU Solver#

class pybamm.IDAKLUSolver(rtol=1e-06, atol=1e-06, root_method='casadi', root_tol=1e-06, extrap_tol=None, output_variables=[], options=None)[source]#

Solve a discretised model, using sundials with the KLU sparse linear solver.

Parameters:

rtol (float, optional) – The relative tolerance for the solver (default is 1e-6).
atol (float, optional) – The absolute tolerance for the solver (default is 1e-6).
root_method (str or pybamm algebraic solver class, optional) – The method to use to find initial conditions (for DAE solvers). If a solver class, must be an algebraic solver class. If “casadi”, the solver uses casadi’s Newton rootfinding algorithm to find initial conditions. Otherwise, the solver uses ‘scipy.optimize.root’ with method specified by ‘root_method’ (e.g. “lm”, “hybr”, …)
root_tol (float, optional) – The tolerance for the initial-condition solver (default is 1e-6).
extrap_tol (float, optional) – The tolerance to assert whether extrapolation occurs or not (default is 0).
output_variables (list[str], optional) – List of variables to calculate and return. If none are specified then the complete state vector is returned (can be very large) (default is [])

options (dict, optional) –

Addititional options to pass to the solver, by default:

options = {
    # print statistics of the solver after every solve
    "print_stats": False,
    # jacobian form, can be "none", "dense",
    # "banded", "sparse", "matrix-free"
    "jacobian": "sparse",
    # name of sundials linear solver to use options are: "SUNLinSol_KLU",
    # "SUNLinSol_Dense", "SUNLinSol_Band", "SUNLinSol_SPBCGS",
    # "SUNLinSol_SPFGMR", "SUNLinSol_SPGMR", "SUNLinSol_SPTFQMR",
    "linear_solver": "SUNLinSol_KLU",
    # preconditioner for iterative solvers, can be "none", "BBDP"
    "preconditioner": "BBDP",
    # for iterative linear solvers, max number of iterations
    "linsol_max_iterations": 5,
    # for iterative linear solver preconditioner, bandwidth of
    # approximate jacobian
    "precon_half_bandwidth": 5,
    # for iterative linear solver preconditioner, bandwidth of
    # approximate jacobian that is kept
    "precon_half_bandwidth_keep": 5,
    # Number of threads available for OpenMP
    "num_threads": 1,
}

Note: These options only have an effect if model.convert_to_format == ‘casadi’

Extends: pybamm.solvers.base_solver.BaseSolver

set_up(model, inputs=None, t_eval=None, ics_only=False)[source]#

Unpack model, perform checks, and calculate jacobian.

Parameters:

model (pybamm.BaseModel) – The model whose solution to calculate. Must have attributes rhs and initial_conditions
inputs (dict, optional) – Any input parameters to pass to the model when solving
t_eval (numeric type, optional) – The times (in seconds) at which to compute the solution

Scikits.odes Solvers#

class pybamm.ScikitsOdeSolver(method='cvode', rtol=1e-06, atol=1e-06, extrap_tol=None, extra_options=None)[source]#

Solve a discretised model, using scikits.odes.

Parameters:

method (str, optional) – The method to use in solve_ivp (default is “BDF”)
rtol (float, optional) – The relative tolerance for the solver (default is 1e-6).
atol (float, optional) – The absolute tolerance for the solver (default is 1e-6).
extrap_tol (float, optional) – The tolerance to assert whether extrapolation occurs or not (default is 0).
extra_options (dict, optional) –
Any options to pass to the solver. Please consult scikits.odes documentation for details. Some common keys:
- ’linsolver’: can be ‘dense’ (= default), ‘lapackdense’, ‘spgmr’, ‘spbcgs’, ‘sptfqmr’

Extends: pybamm.solvers.base_solver.BaseSolver

class pybamm.ScikitsDaeSolver(method='ida', rtol=1e-06, atol=1e-06, root_method='casadi', root_tol=1e-06, extrap_tol=None, extra_options=None)[source]#

Solve a discretised model, using scikits.odes.

Parameters:

method (str, optional) – The method to use in solve_ivp (default is “BDF”)
rtol (float, optional) – The relative tolerance for the solver (default is 1e-6).
atol (float, optional) – The absolute tolerance for the solver (default is 1e-6).
root_method (str or pybamm algebraic solver class, optional) – The method to use to find initial conditions (for DAE solvers). If a solver class, must be an algebraic solver class. If “casadi”, the solver uses casadi’s Newton rootfinding algorithm to find initial conditions. Otherwise, the solver uses ‘scipy.optimize.root’ with method specified by ‘root_method’ (e.g. “lm”, “hybr”, …)
root_tol (float, optional) – The tolerance for the initial-condition solver (default is 1e-6).
extrap_tol (float, optional) – The tolerance to assert whether extrapolation occurs or not (default is 0).
extra_options (dict, optional) –
Any options to pass to the solver. Please consult scikits.odes documentation for details. Some common keys:
- ’max_steps’: maximum (int) number of steps the solver can take

Extends: pybamm.solvers.base_solver.BaseSolver

Casadi Solver#

class pybamm.CasadiSolver(mode='safe', rtol=1e-06, atol=1e-06, root_method='casadi', root_tol=1e-06, max_step_decrease_count=5, dt_max=None, extrap_tol=None, extra_options_setup=None, extra_options_call=None, return_solution_if_failed_early=False, perturb_algebraic_initial_conditions=None, integrators_maxcount=100)[source]#

Solve a discretised model, using CasADi.

Parameters:

mode (str) –
How to solve the model (default is “safe”):
- ”fast”: perform direct integration, without accounting for events. Recommended when simulating a drive cycle or other simulation where no events should be triggered.
- ”fast with events”: perform direct integration of the whole timespan, then go back and check where events were crossed. Experimental only.
- ”safe”: perform step-and-check integration in global steps of size dt_max, checking whether events have been triggered. Recommended for simulations of a full charge or discharge.
- ”safe without grid”: perform step-and-check integration step-by-step. Takes more steps than “safe” mode, but doesn’t require creating the grid each time, so may be faster. Experimental only.
rtol (float, optional) – The relative tolerance for the solver (default is 1e-6).
atol (float, optional) – The absolute tolerance for the solver (default is 1e-6).
root_method (str or pybamm algebraic solver class, optional) – The method to use to find initial conditions (for DAE solvers). If a solver class, must be an algebraic solver class. If “casadi”, the solver uses casadi’s Newton rootfinding algorithm to find initial conditions. Otherwise, the solver uses ‘scipy.optimize.root’ with method specified by ‘root_method’ (e.g. “lm”, “hybr”, …)
root_tol (float, optional) – The tolerance for root-finding. Default is 1e-6.
max_step_decrease_count (float, optional) – The maximum number of times step size can be decreased before an error is raised. Default is 5.
dt_max (float, optional) – The maximum global step size (in seconds) used in “safe” mode. If None the default value is 600 seconds.
extrap_tol (float, optional) – The tolerance to assert whether extrapolation occurs or not. Default is 0.
extra_options_setup (dict, optional) –
Any options to pass to the CasADi integrator when creating the integrator. Please consult CasADi documentation for details. Some useful options:
- ”max_num_steps”: Maximum number of integrator steps
- ”print_stats”: Print out statistics after integration
extra_options_call (dict, optional) –
Any options to pass to the CasADi integrator when calling the integrator. Please consult CasADi documentation for details.
return_solution_if_failed_early (bool, optional) – Whether to return a Solution object if the solver fails to reach the end of the simulation, but managed to take some successful steps. Default is False.
perturb_algebraic_initial_conditions (bool, optional) – Whether to perturb algebraic initial conditions to avoid a singularity. This can sometimes slow down the solver, but is kept True as default for “safe” mode as it seems to be more robust (False by default for other modes).
integrators_maxcount (int, optional) – The maximum number of integrators that the solver will retain before ejecting past integrators using an LRU methodology. A value of 0 or None leaves the number of integrators unbound. Default is 100.

Extends: pybamm.solvers.base_solver.BaseSolver

create_integrator(model, inputs, t_eval=None, use_event_switch=False)[source]#: Method to create a casadi integrator object. If t_eval is provided, the integrator uses t_eval to make the grid. Otherwise, the integrator has grid [0,1].

Algebraic Solvers#

class pybamm.AlgebraicSolver(method='lm', tol=1e-06, extra_options=None)[source]#

Solve a discretised model which contains only (time independent) algebraic equations using a root finding algorithm. Uses scipy.optimize.root. Note: this solver could be extended for quasi-static models, or models in which the time derivative is manually discretised and results in a (possibly nonlinear) algebaric system at each time level.

Parameters:

method (str, optional) – The method to use to solve the system (default is “lm”). If it starts with “lsq”, least-squares minimization is used. The method for least-squares can be specified in the form “lsq_methodname”
tol (float, optional) – The tolerance for the solver (default is 1e-6).
extra_options (dict, optional) – Any options to pass to the rootfinder. Vary depending on which method is chosen. Please consult SciPy documentation for details.

Extends: pybamm.solvers.base_solver.BaseSolver

class pybamm.CasadiAlgebraicSolver(tol=1e-06, extra_options=None)[source]#

Solve a discretised model which contains only (time independent) algebraic equations using CasADi’s root finding algorithm. Note: this solver could be extended for quasi-static models, or models in which the time derivative is manually discretised and results in a (possibly nonlinear) algebaric system at each time level.

Parameters:

tol (float, optional) – The tolerance for the solver (default is 1e-6).
extra_options (dict, optional) – Any options to pass to the CasADi rootfinder. Please consult CasADi documentation for details.

Extends: pybamm.solvers.base_solver.BaseSolver

Solutions#

class pybamm.Solution(all_ts, all_ys, all_models, all_inputs, t_event=None, y_event=None, termination='final time', sensitivities=False, check_solution=True)[source]#

Class containing the solution of, and various attributes associated with, a PyBaMM model.

Parameters:

all_ts (numpy.array, size (n,) (or list of these)) – A one-dimensional array containing the times at which the solution is evaluated. A list of times can be provided instead to initialize a solution with sub-solutions.
all_ys (numpy.array, size (m, n) (or list of these)) – A two-dimensional array containing the values of the solution. y[i, :] is the vector of solutions at time t[i]. A list of ys can be provided instead to initialize a solution with sub-solutions.
all_models (pybamm.BaseModel) – The model that was used to calculate the solution. A list of models can be provided instead to initialize a solution with sub-solutions that have been calculated using those models.
all_inputs (dict (or list of these)) – The inputs that were used to calculate the solution A list of inputs can be provided instead to initialize a solution with sub-solutions.
t_event (numpy.array, size (1,)) – A zero-dimensional array containing the time at which the event happens.
y_event (numpy.array, size (m,)) – A one-dimensional array containing the value of the solution at the time when the event happens.
termination (str) – String to indicate why the solution terminated
sensitivities (bool or dict) – True if sensitivities included as the solution of the explicit forwards equations. False if no sensitivities included/wanted. Dict if sensitivities are provided as a dict of {parameter: sensitivities} pairs.

property all_models#: Model(s) used for solution

property first_state#: A Solution object that only contains the first state. This is faster to evaluate than the full solution when only the first state is needed (e.g. to initialize a model with the solution)

get_data_dict(variables=None, short_names=None, cycles_and_steps=True)[source]#

Construct a (standard python) dictionary of the solution data containing the variables in variables. If variables is None then all variables are returned. Any variable names in short_names are replaced with the corresponding short name.

If the solution has cycles, then the cycle numbers and step numbers are also returned in the dictionary.

Parameters:

variables (list, optional) – List of variables to return. If None, returns all variables in solution.data
short_names (dict, optional) – Dictionary of shortened names to use when saving.
cycles_and_steps (bool, optional) – Whether to include the cycle numbers and step numbers in the dictionary

Returns:

A dictionary of the solution data

Return type:

property last_state#: A Solution object that only contains the final state. This is faster to evaluate than the full solution when only the final state is needed (e.g. to initialize a model with the solution)

plot(output_variables=None, **kwargs)[source]#

A method to quickly plot the outputs of the solution. Creates a pybamm.QuickPlot object (with keyword arguments ‘kwargs’) and then calls pybamm.QuickPlot.dynamic_plot().

Parameters:

output_variables (list, optional) – A list of the variables to plot.
**kwargs – Additional keyword arguments passed to pybamm.QuickPlot.dynamic_plot(). For a list of all possible keyword arguments see pybamm.QuickPlot.

save(filename)[source]#: Save the whole solution using pickle

save_data(filename=None, variables=None, to_format='pickle', short_names=None)[source]#

Save solution data only (raw arrays)

Parameters:

filename (str, optional) – The name of the file to save data to. If None, then a str is returned
variables (list, optional) – List of variables to save. If None, saves all of the variables that have been created so far
to_format (str, optional) –
The format to save to. Options are:
- ’pickle’ (default): creates a pickle file with the data dictionary
- ’matlab’: creates a .mat file, for loading in matlab
- ’csv’: creates a csv file (0D variables only)
- ’json’: creates a json file
short_names (dict, optional) – Dictionary of shortened names to use when saving. This may be necessary when saving to MATLAB, since no spaces or special characters are allowed in MATLAB variable names. Note that not all the variables need to be given a short name.

Returns:

data – str if ‘csv’ or ‘json’ is chosen and filename is None, otherwise None

Return type:

str, optional

property sensitivities#

np_array

Type:: Values of the sensitivities. Returns a dict of param_name

property sub_solutions#: List of sub solutions that have been concatenated to form the full solution

property t#: Times at which the solution is evaluated

property t_event#: Time at which the event happens

property termination#: Reason for termination

update(variables)[source]#: Add ProcessedVariables to the dictionary of variables in the solution

property y#: Values of the solution

property y_event#: Value of the solution at the time of the event

Post-Process Variables#

class pybamm.ProcessedVariable(base_variables, base_variables_casadi, solution, warn=True, cumtrapz_ic=None)[source]#

An object that can be evaluated at arbitrary (scalars or vectors) t and x, and returns the (interpolated) value of the base variable at that t and x.

Parameters:

base_variables (list of pybamm.Symbol) – A list of base variables with a method evaluate(t,y), each entry of which returns the value of that variable for that particular sub-solution. A Solution can be comprised of sub-solutions which are the solutions of different models. Note that this can be any kind of node in the expression tree, not just a pybamm.Variable. When evaluated, returns an array of size (m,n)
base_variable_casadis (list of casadi.Function) – A list of casadi functions. When evaluated, returns the same thing as base_Variable.evaluate (but more efficiently).
solution (pybamm.Solution) – The solution object to be used to create the processed variables
warn (bool, optional) – Whether to raise warnings when trying to evaluate time and length scales. Default is True.

property data#: Same as entries, but different name

initialise_2D()[source]#: Initialise a 2D object that depends on x and r, x and z, x and R, or R and r.

initialise_sensitivity_explicit_forward()[source]#: Set up the sensitivity dictionary

property sensitivities#: Returns a dictionary of sensitivities for each input parameter. The keys are the input parameters, and the value is a matrix of size (n_x * n_t, n_p), where n_x is the number of states, n_t is the number of time points, and n_p is the size of the input parameter

Experiments#

Classes to help set operating conditions for some standard battery modelling experiments

Base Experiment Class#

class pybamm.Experiment(operating_conditions: list[str], period: str = '1 minute', temperature: float | None = None, termination: list[str] | None = None, drive_cycles=None, cccv_handling=None)[source]#

Base class for experimental conditions under which to run the model. In general, a list of operating conditions should be passed in. Each operating condition should be either a pybamm.step._Step class, created using one of the methods pybamm.step.current, pybamm.step.c_rate, pybamm.step.voltage , pybamm.step.power, pybamm.step.resistance, or pybamm.step.string, or a string, in which case the string is passed to pybamm.step.string.

Parameters:

operating_conditions (list[str]) – List of strings representing the operating conditions.
period (string, optional) – Period (1/frequency) at which to record outputs. Default is 1 minute. Can be overwritten by individual operating conditions.
temperature (float, optional) – The ambient air temperature in degrees Celsius at which to run the experiment. Default is None whereby the ambient temperature is taken from the parameter set. This value is overwritten if the temperature is specified in a step.
termination (list[str], optional) – List of strings representing the conditions to terminate the experiment. Default is None. This is different from the termination for individual steps. Termination for individual steps is specified in the step itself, and the simulation moves to the next step when the termination condition is met (e.g. 2.5V discharge cut-off). Termination for the experiment as a whole is specified here, and the simulation stops when the termination condition is met (e.g. 80% capacity).

read_termination(termination)[source]#: Read the termination reason. If this condition is hit, the experiment will stop.

search_tag(tag)[source]#

Search for a tag in the experiment and return the cycles in which it appears.

Parameters:: tag (str) – The tag to search for
Returns:: A list of cycles in which the tag appears
Return type:: list

Experiment step functions#

The following functions can be used to define steps in an experiment.

pybamm.step.string(string, **kwargs)#

Create a step from a string.

Parameters:

string (str) – The string to parse. Each operating condition should be of the form “Do this for this long” or “Do this until this happens”. For example, “Charge at 1 C for 1 hour”, or “Charge at 1 C until 4.2 V”, or “Charge at 1 C for 1 hour or until 4.2 V”. The instructions can be of the form “(Dis)charge at x A/C/W”, “Rest”, or “Hold at x V until y A”. The running time should be a time in seconds, minutes or hours, e.g. “10 seconds”, “3 minutes” or “1 hour”. The stopping conditions should be a circuit state, e.g. “1 A”, “C/50” or “3 V”.
**kwargs – Any other keyword arguments are passed to the pybamm.step._Step class.

Returns:

A step parsed from the string.

Return type:

pybamm.step.current(value, **kwargs)#

Create a current-controlled step. Current is positive for discharge and negative for charge.

Parameters:

value (float) – The current value in A. It can be a number or a 2-column array (for drive cycles).
**kwargs – Any other keyword arguments are passed to the pybamm.step._Step class.

Returns:

A current-controlled step.

Return type:

pybamm.step.voltage(value, **kwargs)#

Create a voltage-controlled step. Voltage should always be positive.

Parameters:

value (float) – The voltage value in V. It can be a number or a 2-column array (for drive cycles).
**kwargs – Any other keyword arguments are passed to the pybamm.step._Step class.

Returns:

A voltage-controlled step.

Return type:

pybamm.step.power(value, **kwargs)#

Create a power-controlled step. Power is positive for discharge and negative for charge.

Parameters:

value (float) – The power value in W. It can be a number or a 2-column array (for drive cycles).
**kwargs – Any other keyword arguments are passed to the pybamm.step._Step class.

Returns:

A power-controlled step.

Return type:

pybamm.step.resistance(value, **kwargs)#

Create a resistance-controlled step. Resistance is positive for discharge and negative for charge.

Parameters:

value (float) – The resistance value in Ohm. It can be a number or a 2-column array (for drive cycles).
**kwargs – Any other keyword arguments are passed to the pybamm.step._Step class.

Returns:

A resistance-controlled step.

Return type: