pybop.models.base_model#

Classes#

`BaseModel`	A base class for constructing and simulating models using PyBaMM.
`TimeSeriesState`	The current state of a time series model that is a pybamm model.

Module Contents#

class pybop.models.base_model.BaseModel(name: str = 'Base Model', parameter_set: pybop.ParameterSet | None = None, check_params: Callable = None, eis: bool = False)[source]#

A base class for constructing and simulating models using PyBaMM.

This class serves as a foundation for constructing models based on PyBaMM models. It provides methods to set up the model, define parameters, and perform simulations. The class is designed to be subclassed for creating models with custom behaviour.

This class is based on PyBaMM’s Simulation class. A PyBOP model is set up via a similar 3-step process. The pybamm_model attributes echoes the model attribute of a simulation, which tracks the model through the build process. Firstly, note that a PyBaMM model must first be built via build_model before a simulation or PyBOP model can be built. The 3-step process is then as follows.

The pybamm_model attribute is first defined as an instance of the imported PyBaMM model, using any given model options. This initial version of the model is saved as the _unprocessed_model for future reference. Next, the type of each parameter in the parameter set as well as the geometry of the model is set. Parameters may be set as an input, interpolant, functional or just a standard PyBaMM parameter. This version of the model is referred to as the model_with_set_params. After its creation, the pybamm_model attribute is updated to point at this version of the model. Finally, the model required for simulations is built by defining the mesh and processing the discretisation. The complete model is referred to as the built_model and this version is used to run simulations.

In order to rebuild a model with a different initial state or geometry, the built_model and the model_with_set_params must be cleared and the pybamm_model reset to the unprocessed_model in order to start the build process again.

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

A compatibility check for the model parameters which can be implemented by subclasses if required, otherwise it returns True by default.

Parameters:

inputs (Inputs) – The input parameters for the simulation.
parameter_set (Union[pybop.ParameterSet, pybamm.ParameterValues], optional) – A dict-like object 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

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

Calculate a new estimate for the nominal capacity based on the theoretical energy density and an average voltage.

This method must be implemented by subclasses.

Parameters:: parameter_set (Union[pybop.ParameterSet, pybamm.ParameterValues], optional) – A dict-like object containing the parameter values.
Raises:: NotImplementedError – If the method has not been implemented by the subclass.

build(parameters: pybop.Parameters | dict = None, inputs: pybop.parameters.parameter.Inputs | None = None, initial_state: dict | None = None, dataset: pybop.Dataset | None = None, check_model: bool = True) → None[source]#

Construct the PyBaMM model, if not already built or if there are changes to any rebuild_parameters or the initial state.

This method initializes the model components, applies the given parameters, sets up the mesh and discretisation if needed, and prepares the model for simulations.

Parameters:

parameters (pybop.Parameters or Dict, optional) – A pybop Parameters class or dictionary containing parameter values to apply to the model.
inputs (Inputs) – The input parameters to be used when building the model.
initial_state (dict, optional) – A valid initial state, e.g. the initial state of charge or open-circuit voltage. Defaults to None, indicating that the existing initial state of charge (for an ECM) or initial concentrations (for an EChem model) will be used. Accepted keys either “Initial open-circuit voltage [V]” or ``”Initial SoC”`
dataset (pybop.Dataset or dict, optional) – The dataset to be used in the model construction.
check_model (bool, optional) – If True, the model will be checked for correctness after construction.

calculate_impedance(frequency)[source]#

Calculate the impedance for a given frequency.

This method computes the system matrix, solves the linear system, and calculates the impedance based on the solution.

Parameters:: like) (frequency (np.ndarray | list)
Return type:: The calculated impedance (complex np.ndarray).

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

Calculate the cell mass in kilograms.

This method must be implemented by subclasses.

Parameters:: parameter_set (Union[pybop.ParameterSet, pybamm.ParameterValues], optional) – A dict-like object containing the parameter values.
Raises:: NotImplementedError – If the method has not been implemented by the subclass.

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

Calculate the cell volume in m3.

This method must be implemented by subclasses.

Parameters:: parameter_set (Union[pybop.ParameterSet, pybamm.ParameterValues], optional) – A dict-like object containing the parameter values.
Raises:: NotImplementedError – If the method has not been implemented by the subclass.

check_params(inputs: pybop.parameters.parameter.Inputs | None = None, parameter_set: pybop.ParameterSet | None = None, allow_infeasible_solutions: bool = True)[source]#

Check compatibility of the model parameters.

Parameters:

inputs (Inputs) – The input parameters for the simulation.
parameter_set (Union[pybop.ParameterSet, pybamm.ParameterValues], optional) – A dict-like object 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

check_sensitivities_available()[source]#: Check whether the solver can provide sensitivities and set the corresponding attribute.

classify_parameters(parameters: pybop.Parameters | None = None, inputs: pybop.parameters.parameter.Inputs | None = None)[source]#

Check for any ‘rebuild_parameters’ which require a model rebuild and update the unprocessed_parameter_set if a rebuild is required.

Parameters:

parameters (Parameters, optional) – The optimisation parameters. Defaults to None, resulting in the internal pybop.Parameters object to be used.
inputs (Inputs, optional) – The input parameters for the simulation (default: None).

clear()[source]#: Clear any built PyBaMM model.

convert_to_pybamm_initial_state(initial_state: dict)[source]#

Convert an initial state of charge into a float and an initial open-circuit voltage into a string ending in “V”.

Parameters:: initial_state (dict) – A valid initial state, e.g. the initial state of charge or open-circuit voltage.
Returns:: If float, this value is used as the initial state of charge (as a decimal between 0 and 1). If str ending in “V”, this value is used as the initial open-circuit voltage.
Return type:: float or str
Raises:: ValueError – If the input is not a dictionary with a single, valid key.

copy()[source]#

Return a copy of the model.

Returns:: A copy of the model.
Return type:: BaseModel

get_parameter_info(print_info: bool = False)[source]#: Extracts the parameter names and types and returns them as a dictionary.

get_state(inputs: pybop.parameters.parameter.Inputs, t: float, x: numpy.ndarray) → TimeSeriesState[source]#: Returns the given state for the problem (inputs are assumed constant since last reinit)

initialise_eis_simulation(inputs: pybop.parameters.parameter.Inputs | None = None)[source]#

Initialise the Electrochemical Impedance Spectroscopy (EIS) simulation.

This method sets up the mass matrix and solver, converts inputs to the appropriate format, extracts necessary attributes from the model, and prepares matrices for the simulation.

Parameters:: inputs (dict (optional)) – The input parameters for the simulation.

jaxify_solver(t_eval, calculate_sensitivities=False)[source]#: Jaxify the IDAKLU Solver and store a copy for future reconstruction. Handles sensitivity calculations during solver construction.

new_copy()[source]#

Return a new copy of the model, explicitly copying all the mutable attributes to avoid issues with shared objects.

Returns:: A new copy of the model.
Return type:: BaseModel

predict(inputs: pybop.parameters.parameter.Inputs | None = None, t_eval: numpy.array | None = None, parameter_set: pybop.ParameterSet | None = None, experiment: pybop.Experiment | None = None, initial_state: dict | None = None) → dict[str, numpy.ndarray[numpy.float64]][source]#

Solve the model using PyBaMM’s simulation framework and return the solution.

This method sets up a PyBaMM simulation by configuring the model, parameters, experiment or time vector, and initial state of charge (if provided). Either ‘t_eval’ or ‘experiment’ must be provided. It then solves the simulation and returns the resulting solution object.

Parameters:

inputs (Inputs, optional) – Input parameters for the simulation. Defaults to None, indicating that the default parameters should be used.
t_eval (array-like, optional) – An array of time points at which to evaluate the solution. Defaults to None, which means the time points need to be specified within experiment or elsewhere.
parameter_set (Union[pybop.ParameterSet, pybamm.ParameterValues], optional) – A dict-like object containing the parameter values to use for the simulation. Defaults to the model’s current ParameterValues if None.
experiment (pybamm.Experiment, optional) – A PyBaMM Experiment object specifying the experimental conditions under which the simulation should be run. Defaults to None, indicating no experiment.
initial_state (dict, optional) – A valid initial state, e.g. the initial state of charge or open-circuit voltage. Defaults to None, indicating that the existing initial state of charge (for an ECM) or initial concentrations (for an EChem model) will be used.

Returns:

The solution object returned by a PyBaMM simulation, or a pybamm error in the case where the parameter values are infeasible and infeasible solutions are not allowed.

Return type:

pybamm.Solution

Raises:

ValueError – If the model has not been configured properly before calling this method or if PyBaMM models are not supported by the current simulation method.

reinit(inputs: pybop.parameters.parameter.Inputs, t: float = 0.0, x: numpy.ndarray | None = None) → TimeSeriesState[source]#: Initialises the solver with the given inputs and returns the initial state of the problem

set_current_function(dataset: pybop.Dataset | dict)[source]#

Update the input current function according to the data.

Parameters:: dataset (pybop.Dataset or dict, optional) – The dataset to be used in the model construction.

set_initial_state(initial_state: dict, inputs: pybop.parameters.parameter.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.

set_parameters()[source]#

Assign the parameters to the model.

This method processes the model with the given parameters, sets up the geometry, and updates the model instance.

set_up_for_eis(model)[source]#

Set up the model for electrochemical impedance spectroscopy (EIS) simulations.

This method sets up the model for EIS simulations by adding the necessary algebraic equations and variables to the model. Originally developed by pybamm-eis: pybamm-team/pybamm-eis

Parameters:: model (pybamm.Model) – The PyBaMM model to be used for EIS simulations.

simulate(inputs: pybop.parameters.parameter.Inputs, t_eval: numpy.array, initial_state: dict | None = None) → pybamm.Solution | list[numpy.float64][source]#

Execute the forward model simulation and return the result.

Parameters:

inputs (Inputs) – The input parameters for the simulation.
t_eval (array-like) – An array of time points at which to evaluate the solution.
initial_state (dict, optional) – A valid initial state, e.g. the initial state of charge or open-circuit voltage. Defaults to None, indicating that the existing initial state of charge (for an ECM) or initial concentrations (for an EChem model) will be used.

Returns:

The solution object returned by a PyBaMM simulation, or a pybamm error in the case where the parameter values are infeasible and infeasible solutions are not allowed.

Return type:

pybamm.Solution

Raises:

ValueError – If the model has not been built before simulation.

simulateEIS(inputs: pybop.parameters.parameter.Inputs, f_eval: list, initial_state: dict | None = None) → dict[str, numpy.ndarray][source]#

Compute the forward model simulation with electrochemical impedance spectroscopy and return the result.

Parameters:

inputs (dict or array-like) – The input parameters for the simulation. If array-like, it will be converted to a dictionary using the model’s fit keys.
f_eval (array-like) – An array of frequency points at which to evaluate the solution.

Returns:

The simulation result corresponding to the specified signal.

Return type:

array-like

Raises:

ValueError – If the model has not been built before simulation.

simulateS1(inputs: pybop.parameters.parameter.Inputs, t_eval: numpy.array, initial_state: dict | None = None)[source]#

Perform the forward model simulation with sensitivities.

Parameters:

inputs (Inputs) – The input parameters for the simulation.
t_eval (array-like) – An array of time points at which to evaluate the solution and its sensitivities.
initial_state (dict, optional) – A valid initial state, e.g. the initial state of charge or open-circuit voltage. Defaults to None, indicating that the existing initial state of charge (for an ECM) or initial concentrations (for an EChem model) will be used.

Returns:

The solution object returned by a PyBaMM simulation, or a pybamm error in the case where the parameter values are infeasible and infeasible solutions are not allowed.

Return type:

pybamm.Solution

Raises:

ValueError – If the model has not been built before simulation.

step(state: TimeSeriesState, time: numpy.ndarray) → TimeSeriesState[source]#

Step forward in time from the given state until the given time.

Parameters:

state (TimeSeriesState) – The current state of the model
time (np.ndarray) – The time to simulate the system until (in whatever time units the model is in)

_calculate_sensitivities = False[source]#

_parameter_set = None[source]#

_pybamm_solution = None[source]#

_sensitivities_available = True[source]#

allow_infeasible_solutions = True[source]#

property built_initial_soc[source]#

property built_model[source]#

property calculate_sensitivities[source]#

property disc[source]#

eis = False[source]#

property geometry[source]#

property mesh[source]#

property model_with_set_params[source]#

name = 'Base Model'[source]#

param_check_counter = 0[source]#

param_checker = None[source]#

property parameter_set[source]#

parameters[source]#

pybamm_model = None[source]#

property pybamm_solution[source]#

property sensitivities_available[source]#: True if sensitivities are available.

property solver[source]#

property spatial_methods[source]#

property submesh_types[source]#

property var_pts[source]#

class pybop.models.base_model.TimeSeriesState[source]#

The current state of a time series model that is a pybamm model.

__len__()[source]#

as_ndarray() → numpy.ndarray[source]#

inputs: pybop.parameters.parameter.Inputs[source]#

sol: pybamm.Solution[source]#

t: float = 0.0[source]#