pybop.models.lithium_ion#

Submodules#

Classes#

DFN

Wraps the Doyle-Fuller-Newman (DFN) model for simulating lithium-ion batteries, as implemented in PyBaMM.

EChemBaseModel

Overwrites and extends BaseModel class for electrochemical PyBaMM models.

GroupedSPM

Represents the grouped-parameter version of the Single Particle Model.

GroupedSPMe

Represents the grouped-parameter version of the Single Particle Model with Electrolyte (SPMe).

MPM

Wraps the Many Particle Model (MPM) for simulating lithium-ion batteries, as implemented in PyBaMM.

MSMR

Wraps the Multi-Species Multi-Reaction (MSMR) model for simulating lithium-ion batteries, as implemented in PyBaMM.

SPDiffusion

Represents the Single Particle Diffusion Model for GITT pulses.

SPM

Wraps the Single Particle Model (SPM) for simulating lithium-ion batteries, as implemented in PyBaMM.

SPMe

Represents the Single Particle Model with Electrolyte (SPMe) for lithium-ion batteries.

WeppnerHuggins

Represents the Weppner & Huggins model for GITT pulses.

Package Contents#

class pybop.models.lithium_ion.DFN(name='Doyle-Fuller-Newman Model', eis: bool = False, **model_kwargs)[source]#

Bases: pybop.models.lithium_ion.base_echem.EChemBaseModel

Wraps the Doyle-Fuller-Newman (DFN) model for simulating lithium-ion batteries, as implemented in PyBaMM.

The DFN represents lithium-ion battery dynamics using multiple spherical particles to simulate the behaviour of the negative and positive electrodes. This model includes electrolyte dynamics, solid-phase diffusion, and Butler-Volmer kinetics. This model is the full-order representation used to reduce to the SPM, and SPMe models.

Parameters:

  • name (str, optional) – A name for the model instance, defaulting to “Doyle-Fuller-Newman Model”.

  • eis (bool, optional) – A flag to build the forward model for EIS predictions. Defaults to False.

  • **model_kwargs (optional) –

    Valid PyBaMM model option keys and their values, for example: parameter_set : pybamm.ParameterValues or dict, optional

    The parameters for the model. If None, default parameters provided by PyBaMM are used.

    geometrydict, optional

    The geometry definitions for the model. If None, default geometry from PyBaMM is used.

    submesh_typesdict, optional

    The types of submeshes to use. If None, default submesh types from PyBaMM are used.

    var_ptsdict, optional

    The discretization points for each variable in the model. If None, default points from PyBaMM are used.

    spatial_methodsdict, optional

    The spatial methods used for discretization. If None, default spatial methods from PyBaMM are used.

    solverpybamm.Solver, optional

    The solver to use for simulating the model. If None, the default solver from PyBaMM is used.

    buildbool, optional

    If True, the model is built upon creation (default: False).

    optionsdict, optional

    A dictionary of options to customise the behaviour of the PyBaMM model.

class pybop.models.lithium_ion.EChemBaseModel(pybamm_model, name='Electrochemical Base Model', parameter_set=None, geometry=None, submesh_types=None, var_pts=None, spatial_methods=None, solver=None, eis=False, **model_kwargs)[source]#

Bases: pybop.models.base_model.BaseModel

Overwrites and extends BaseModel class for electrochemical PyBaMM models.

Parameters:

  • pybamm_model (pybamm.BaseModel) – A subclass of the pybamm Base Model.

  • name (str, optional) – The name for the model instance, defaulting to “Electrochemical Base Model”.

  • parameter_set (pybamm.ParameterValues or dict, optional) – The parameters for the model. If None, default parameters provided by PyBaMM are used.

  • geometry (dict, optional) – The geometry definitions for the model. If None, default geometry from PyBaMM is used.

  • submesh_types (dict, optional) – The types of submeshes to use. If None, default submesh types from PyBaMM are used.

  • var_pts (dict, optional) – The discretization points for each variable in the model. If None, default points from PyBaMM are used.

  • spatial_methods (dict, optional) – The spatial methods used for discretization. If None, default spatial methods from PyBaMM are used.

  • solver (pybamm.Solver, optional) – The solver to use for simulating the model. If None, the default solver from PyBaMM is used.

  • eis (bool, optional) – A flag to build the forward model for EIS predictions. Defaults to False.

  • **model_kwargs (optional) –

    Valid PyBaMM model option keys and their values. For example, build : bool, optional

    If True, the model is built upon creation (default: False).

    optionsdict, optional

    A dictionary of options to customise the behaviour of the PyBaMM model.

_check_params(inputs: pybop.models.base_model.Inputs, parameter_set: pybop.parameters.parameter_set.ParameterSet, allow_infeasible_solutions: bool = True)[source]#

Check compatibility of the model parameters.

Parameters:

  • inputs (Inputs) – The input parameters for the simulation.

  • parameter_set (pybop.ParameterSet) – A PyBOP parameter set object or a dictionary containing the parameter values.

  • allow_infeasible_solutions (bool, optional) – If True, infeasible parameter values will be allowed in the optimisation (default: True).

Returns:

A boolean which signifies whether the parameters are compatible.

Return type:

bool

_set_initial_state(initial_state: dict, inputs: pybop.models.base_model.Inputs | None = None)[source]#

Set the initial state of charge or concentrations for the battery model.

Parameters:

  • initial_state (dict) – A valid initial state, e.g. the initial state of charge or open-circuit voltage.

  • inputs (Inputs) – The input parameters to be used when building the model.

approximate_capacity(parameter_set: pybop.parameters.parameter_set.ParameterSet | None = None)[source]#

Calculate an estimate for the nominal cell capacity. The estimate is computed by estimating the capacity of the positive electrode that lies between the stoichiometric limits corresponding to the upper and lower voltage limits.

Parameters:

parameter_set (dict, optional) – A dictionary containing the parameter values necessary for the calculation.

Returns:

The estimate of the nominal cell capacity [A.h].

Return type:

float

cell_mass(parameter_set: pybop.parameters.parameter_set.ParameterSet | None = None)[source]#

Calculate the total cell mass in kilograms.

This method uses the provided parameter set to calculate the mass of different components of the cell, such as electrodes, separator, and current collectors, based on their densities, porosities, and thicknesses. It then calculates the total mass by summing the mass of each component.

Parameters:

parameter_set (dict, optional) – A dictionary containing the parameter values necessary for the calculation.

Returns:

The total mass of the cell in kilograms.

Return type:

float

cell_volume(parameter_set: pybop.parameters.parameter_set.ParameterSet | None = None)[source]#

Calculate the total cell volume in m3.

This method uses the provided parameter set to calculate the total thickness of the cell including electrodes, separator, and current collectors. It then calculates the volume by multiplying by the cross-sectional area.

Parameters:

parameter_set (dict, optional) – A dictionary containing the parameter values necessary for the calculation.

Returns:

The total volume of the cell in m3.

Return type:

float

set_geometric_parameters()[source]#

Sets the parameters that can be changed when rebuilding the model.

Returns:

A dictionary of parameters that can be changed when rebuilding the model.

Return type:

dict

_built_initial_soc = None#
_built_model = None#
_disc = None#
_electrode_soh#
_electrode_soh_half_cell#
_geometry#
_mesh = None#
_model_with_set_params = None#
_parameter_set#
_spatial_methods#
_submesh_types#
_unprocessed_model#
_unprocessed_parameter_set#
_var_pts#
default_parameter_values#
geometric_parameters#
pybamm_model#
class pybop.models.lithium_ion.GroupedSPM(name='Grouped Single Particle Model', eis=False, **model_kwargs)[source]#

Bases: pybop.models.lithium_ion.base_echem.EChemBaseModel

Represents the grouped-parameter version of the Single Particle Model.

Parameters:

  • name (str, optional) – A name for the model instance, defaulting to “Grouped Single Particle Model”.

  • **model_kwargs (optional) –

    Valid PyBaMM model option keys and their values, for example: parameter_set : pybamm.ParameterValues or dict, optional

    The parameters for the model. If None, default parameters provided by PyBaMM are used.

    geometrydict, optional

    The geometry definitions for the model. If None, default geometry from PyBaMM is used.

    submesh_typesdict, optional

    The types of submeshes to use. If None, default submesh types from PyBaMM are used.

    var_ptsdict, optional

    The discretization points for each variable in the model. If None, default points from PyBaMM are used.

    spatial_methodsdict, optional

    The spatial methods used for discretization. If None, default spatial methods from PyBaMM are used.

    solverpybamm.Solver, optional

    The solver to use for simulating the model. If None, the default solver from PyBaMM is used.

    optionsdict, optional

    A dictionary of options to customise the behaviour of the PyBaMM model.

_check_params(inputs, parameter_set, allow_infeasible_solutions)[source]#

Check compatibility of the model parameters.

Parameters:

  • inputs (Inputs) – The input parameters for the simulation.

  • parameter_set (pybop.ParameterSet) – A PyBOP parameter set object or a dictionary containing the parameter values.

  • allow_infeasible_solutions (bool, optional) – If True, infeasible parameter values will be allowed in the optimisation (default: True).

Returns:

A boolean which signifies whether the parameters are compatible.

Return type:

bool

_set_initial_state(initial_state: dict, inputs=None)[source]#

Set the initial state of charge for the grouped SPMe. Inputs are not used.

Parameters:

  • initial_state (dict) – A valid initial state, e.g. the initial state of charge or open-circuit voltage.

  • inputs (Inputs, optional) – The input parameters to be used when building the model.

apply_parameter_grouping()[source]#
class pybop.models.lithium_ion.GroupedSPMe(name='Grouped Single Particle Model with Electrolyte', eis=False, **model_kwargs)[source]#

Bases: pybop.models.lithium_ion.base_echem.EChemBaseModel

Represents the grouped-parameter version of the Single Particle Model with Electrolyte (SPMe).

Parameters:

  • name (str, optional) – A name for the model instance, defaulting to “Grouped Single Particle Model with Electrolyte”.

  • **model_kwargs (optional) –

    Valid PyBaMM model option keys and their values, for example: parameter_set : pybamm.ParameterValues or dict, optional

    The parameters for the model. If None, default parameters provided by PyBaMM are used.

    geometrydict, optional

    The geometry definitions for the model. If None, default geometry from PyBaMM is used.

    submesh_typesdict, optional

    The types of submeshes to use. If None, default submesh types from PyBaMM are used.

    var_ptsdict, optional

    The discretization points for each variable in the model. If None, default points from PyBaMM are used.

    spatial_methodsdict, optional

    The spatial methods used for discretization. If None, default spatial methods from PyBaMM are used.

    solverpybamm.Solver, optional

    The solver to use for simulating the model. If None, the default solver from PyBaMM is used.

    optionsdict, optional

    A dictionary of options to customise the behaviour of the PyBaMM model.

_check_params(inputs, parameter_set, allow_infeasible_solutions)[source]#

Check compatibility of the model parameters.

Parameters:

  • inputs (Inputs) – The input parameters for the simulation.

  • parameter_set (pybop.ParameterSet) – A PyBOP parameter set object or a dictionary containing the parameter values.

  • allow_infeasible_solutions (bool, optional) – If True, infeasible parameter values will be allowed in the optimisation (default: True).

Returns:

A boolean which signifies whether the parameters are compatible.

Return type:

bool

_set_initial_state(initial_state: dict, inputs=None)[source]#

Set the initial state of charge for the grouped SPMe. Inputs are not used.

Parameters:

  • initial_state (dict) – A valid initial state, e.g. the initial state of charge or open-circuit voltage.

  • inputs (Inputs, optional) – The input parameters to be used when building the model.

apply_parameter_grouping()[source]#
class pybop.models.lithium_ion.MPM(name='Many Particle Model', eis: bool = False, **model_kwargs)[source]#

Bases: pybop.models.lithium_ion.base_echem.EChemBaseModel

Wraps the Many Particle Model (MPM) for simulating lithium-ion batteries, as implemented in PyBaMM.

The MPM represents lithium-ion battery dynamics using a distribution of spherical particles for each electrode. This model inherits the SPM class.

Parameters:

  • name (str, optional) – A name for the model instance, defaulting to “Many Particle Model”.

  • eis (bool, optional) – A flag to build the forward model for EIS predictions. Defaults to False.

  • **model_kwargs (optional) –

    Valid PyBaMM model option keys and their values, for example: parameter_set : pybamm.ParameterValues or dict, optional

    The parameters for the model. If None, default parameters provided by PyBaMM are used.

    geometrydict, optional

    The geometry definitions for the model. If None, default geometry from PyBaMM is used.

    submesh_typesdict, optional

    The types of submeshes to use. If None, default submesh types from PyBaMM are used.

    var_ptsdict, optional

    The discretization points for each variable in the model. If None, default points from PyBaMM are used.

    spatial_methodsdict, optional

    The spatial methods used for discretization. If None, default spatial methods from PyBaMM are used.

    solverpybamm.Solver, optional

    The solver to use for simulating the model. If None, the default solver from PyBaMM is used.

    buildbool, optional

    If True, the model is built upon creation (default: False).

    optionsdict, optional

    A dictionary of options to customise the behaviour of the PyBaMM model.

class pybop.models.lithium_ion.MSMR(name='Multi-Species Multi-Reaction Model', eis: bool = False, **model_kwargs)[source]#

Bases: pybop.models.lithium_ion.base_echem.EChemBaseModel

Wraps the Multi-Species Multi-Reaction (MSMR) model for simulating lithium-ion batteries, as implemented in PyBaMM.

The MSMR represents lithium-ion battery dynamics using a distribution of spherical particles for each electrode. This model inherits the DFN class.

Parameters:

  • name (str, optional) – A name for the model instance, defaulting to “Multi-Species Multi-Reaction Model”.

  • eis (bool, optional) – A flag to build the forward model for EIS predictions. Defaults to False.

  • **model_kwargs (optional) –

    Valid PyBaMM model option keys and their values, for example: parameter_set : pybamm.ParameterValues or dict, optional

    The parameters for the model. If None, default parameters provided by PyBaMM are used.

    geometrydict, optional

    The geometry definitions for the model. If None, default geometry from PyBaMM is used.

    submesh_typesdict, optional

    The types of submeshes to use. If None, default submesh types from PyBaMM are used.

    var_ptsdict, optional

    The discretization points for each variable in the model. If None, default points from PyBaMM are used.

    spatial_methodsdict, optional

    The spatial methods used for discretization. If None, default spatial methods from PyBaMM are used.

    solverpybamm.Solver, optional

    The solver to use for simulating the model. If None, the default solver from PyBaMM is used.

    buildbool, optional

    If True, the model is built upon creation (default: False).

    optionsdict, optional

    A dictionary of options to customise the behaviour of the PyBaMM model.

class pybop.models.lithium_ion.SPDiffusion(name='Single Particle Diffusion Model', eis: bool = False, **model_kwargs)[source]#

Bases: pybop.models.lithium_ion.base_echem.EChemBaseModel

Represents the Single Particle Diffusion Model for GITT pulses.

Parameters:

  • name (str, optional) – A name for the model instance, defaulting to “Single Particle Diffusion Model”.

  • eis (bool, optional) – A flag to build the forward model for EIS predictions. Defaults to False.

  • **model_kwargs (optional) –

    Valid PyBaMM model option keys and their values, for example: parameter_set : pybamm.ParameterValues or dict, optional

    The parameters for the model. If None, default parameters provided by PyBaMM are used.

    optionsdict, optional

    A dictionary of options to customise the behaviour of the PyBaMM model.

_check_params(inputs, parameter_set, allow_infeasible_solutions)[source]#

Check compatibility of the model parameters.

Parameters:

  • inputs (Inputs) – The input parameters for the simulation.

  • parameter_set (pybop.ParameterSet) – A PyBOP parameter set object or a dictionary containing the parameter values.

  • allow_infeasible_solutions (bool, optional) – If True, infeasible parameter values will be allowed in the optimisation (default: True).

Returns:

A boolean which signifies whether the parameters are compatible.

Return type:

bool

_set_initial_state(initial_state: dict, inputs=None)[source]#

Set the initial state of charge for the grouped SPMe. Inputs are not used.

Parameters:

  • initial_state (dict) – A valid initial state, e.g. the initial state of charge or open-circuit voltage.

  • inputs (Inputs, optional) – The input parameters to be used when building the model.

apply_parameter_grouping(electrode)[source]#
class pybop.models.lithium_ion.SPM(name='Single Particle Model', eis: bool = False, **model_kwargs)[source]#

Bases: pybop.models.lithium_ion.base_echem.EChemBaseModel

Wraps the Single Particle Model (SPM) for simulating lithium-ion batteries, as implemented in PyBaMM.

The SPM is a simplified physics-based model that represents a lithium-ion cell using a single spherical particle to simulate the behaviour of the negative and positive electrodes.

Parameters:

  • name (str, optional) – A name for the model instance, defaulting to “Single Particle Model”.

  • eis (bool, optional) – A flag to build the forward model for EIS predictions. Defaults to False.

  • **model_kwargs (optional) –

    Valid PyBaMM model option keys and their values, for example: parameter_set : pybamm.ParameterValues or dict, optional

    The parameters for the model. If None, default parameters provided by PyBaMM are used.

    geometrydict, optional

    The geometry definitions for the model. If None, default geometry from PyBaMM is used.

    submesh_typesdict, optional

    The types of submeshes to use. If None, default submesh types from PyBaMM are used.

    var_ptsdict, optional

    The discretization points for each variable in the model. If None, default points from PyBaMM are used.

    spatial_methodsdict, optional

    The spatial methods used for discretization. If None, default spatial methods from PyBaMM are used.

    solverpybamm.Solver, optional

    The solver to use for simulating the model. If None, the default solver from PyBaMM is used.

    buildbool, optional

    If True, the model is built upon creation (default: False).

    optionsdict, optional

    A dictionary of options to customise the behaviour of the PyBaMM model.

class pybop.models.lithium_ion.SPMe(name='Single Particle Model with Electrolyte', eis: bool = False, **model_kwargs)[source]#

Bases: pybop.models.lithium_ion.base_echem.EChemBaseModel

Represents the Single Particle Model with Electrolyte (SPMe) for lithium-ion batteries.

The SPMe extends the basic Single Particle Model (SPM) by incorporating electrolyte dynamics, making it suitable for simulations where electrolyte effects are non-negligible. This class provides a framework to define the model parameters, geometry, mesh types, discretization points, spatial methods, and numerical solvers for simulation within the PyBaMM ecosystem.

Parameters:

  • name (str, optional) – A name for the model instance, defaulting to “Single Particle Model with Electrolyte”.

  • eis (bool, optional) – A flag to build the forward model for EIS predictions. Defaults to False.

  • **model_kwargs (optional) –

    Valid PyBaMM model option keys and their values, for example: parameter_set : pybamm.ParameterValues or dict, optional

    The parameters for the model. If None, default parameters provided by PyBaMM are used.

    geometrydict, optional

    The geometry definitions for the model. If None, default geometry from PyBaMM is used.

    submesh_typesdict, optional

    The types of submeshes to use. If None, default submesh types from PyBaMM are used.

    var_ptsdict, optional

    The discretization points for each variable in the model. If None, default points from PyBaMM are used.

    spatial_methodsdict, optional

    The spatial methods used for discretization. If None, default spatial methods from PyBaMM are used.

    solverpybamm.Solver, optional

    The solver to use for simulating the model. If None, the default solver from PyBaMM is used.

    buildbool, optional

    If True, the model is built upon creation (default: False).

    optionsdict, optional

    A dictionary of options to customise the behaviour of the PyBaMM model.

class pybop.models.lithium_ion.WeppnerHuggins(name='Weppner & Huggins Model', eis: bool = False, **model_kwargs)[source]#

Bases: pybop.models.lithium_ion.base_echem.EChemBaseModel

Represents the Weppner & Huggins model for GITT pulses.

Parameters:

  • name (str, optional) – A name for the model instance, defaulting to “Weppner & Huggins Model”.

  • eis (bool, optional) – A flag to build the forward model for EIS predictions. Defaults to False.

  • **model_kwargs (optional) –

    Valid PyBaMM model option keys and their values, for example: parameter_set : pybamm.ParameterValues or dict, optional

    The parameters for the model. If None, default parameters provided by PyBaMM are used.

    optionsdict, optional

    A dictionary of options to customise the behaviour of the PyBaMM model.

_check_params(inputs, parameter_set, allow_infeasible_solutions)[source]#

Check compatibility of the model parameters.

Parameters:

  • inputs (Inputs) – The input parameters for the simulation.

  • parameter_set (pybop.ParameterSet) – A PyBOP parameter set object or a dictionary containing the parameter values.

  • allow_infeasible_solutions (bool, optional) – If True, infeasible parameter values will be allowed in the optimisation (default: True).

Returns:

A boolean which signifies whether the parameters are compatible.

Return type:

bool

apply_parameter_grouping(electrode)[source]#