pybop#

Subpackages#

Submodules#

Attributes#

`FLOAT_FORMAT`
`Inputs`
`__version__`
`script_path`

Classes#

`Adam`	Implements the Adam optimization algorithm.
`BaseCost`	Base class for defining cost functions.
`BaseLikelihood`	Base class for likelihoods
`BaseModel`	A base class for constructing and simulating models using PyBaMM.
`BaseOptimiser`	A base class for defining optimisation methods.
`BaseProblem`	Base class for defining a problem within the PyBOP framework, compatible with PINTS.
`CMAES`	Adapter for the Covariance Matrix Adaptation Evolution Strategy (CMA-ES) optimiser in PINTS.
`Dataset`	Represents a collection of experimental observations.
`DesignCost`	Overwrites and extends BaseCost class for design-related cost functions.
`DesignProblem`	Problem class for design optimization problems.
`Experiment`	Wraps the Experiment class for generating experiment conditions for PyBaMM models.
`Exponential`	Represents an exponential distribution with a specified scale parameter.
`FittingProblem`	Problem class for fitting (parameter estimation) problems.
`Gaussian`	Represents a Gaussian (normal) distribution with a given mean and standard deviation.
`GaussianLogLikelihood`	This class represents a Gaussian Log Likelihood, which assumes that the
`GaussianLogLikelihoodKnownSigma`	This class represents a Gaussian Log Likelihood with a known sigma,
`GradientDescent`	Implements a simple gradient descent optimization algorithm.
`GravimetricEnergyDensity`	Represents the gravimetric energy density of a battery cell, calculated based
`IRPropMin`	Implements the iRpropMin optimization algorithm.
`Observer`	An observer of a time series state. Observers:
`ObserverCost`	Observer cost function.
`Optimisation`	A class for conducting optimization using PyBOP or PINTS optimisers.
`PSO`	Implements a particle swarm optimization (PSO) algorithm.
`Parameter`	Represents a parameter within the PyBOP framework.
`ParameterSet`	Handles the import and export of parameter sets for battery models.
`PlotlyManager`	Manages the installation and configuration of Plotly for generating visualizations.
`RootMeanSquaredError`	Root mean square error cost function.
`SNES`	Implements the stochastic natural evolution strategy (SNES) optimization algorithm.
`SciPyDifferentialEvolution`	Adapts SciPy's differential_evolution function for global optimization.
`SciPyMinimize`	Adapts SciPy's minimize function for use as an optimization strategy.
`StandardPlot`	A class for creating and displaying interactive Plotly figures.
`StandardSubplot`	A class for creating and displaying a set of interactive Plotly figures in a grid layout.
`SumSquaredError`	Sum of squared errors cost function.
`TimeSeriesState`	The current state of a time series model that is a pybamm model
`Uniform`	Represents a uniform distribution over a specified interval.
`UnscentedKalmanFilterObserver`	An observer using the unscented Kalman filter. This is a wrapper class for PyBOP, see class SquareRootUKF for more details on the method.
`VolumetricEnergyDensity`	Represents the volumetric energy density of a battery cell, calculated based
`XNES`	Implements the Exponential Natural Evolution Strategy (XNES) optimiser from PINTS.

Functions#

`is_numeric`(x)	Check if a variable is numeric.
`plot2d`(cost_or_optim[, gradient, bounds, steps, show])	Plot a 2D visualisation of a cost landscape using Plotly.
`plot_convergence`(optim[, show])	Plot the convergence of the optimisation algorithm.
`plot_dataset`(dataset[, signal, trace_names, show])	Quickly plot a PyBOP Dataset using Plotly.
`plot_parameters`(optim[, show])	Plot the evolution of parameters during the optimization process using Plotly.
`plot_trajectories`(x, y[, trace_names, show])	Quickly plot one or more trajectories using Plotly.
`quick_plot`(problem[, parameter_values, show])	Quickly plot the target dataset against optimised model output.

Package Contents#

class pybop.Adam(x0, sigma0=0.1, bounds=None)[source]#

Bases: pints.Adam

Implements the Adam optimization algorithm.

This class extends the Adam optimiser from the PINTS library, which combines ideas from RMSProp and Stochastic Gradient Descent with momentum. Note that this optimiser does not support boundary constraints.

Parameters:

x0 (array_like) – Initial position from which optimization will start.
sigma0 (float, optional) – Initial step size (default is 0.1).
bounds (sequence or Bounds, optional) – Ignored by this optimiser, provided for API consistency.

See also

pints.Adam: The PINTS implementation this class is based on.

class pybop.BaseCost(problem=None, sigma=None)[source]#

Base class for defining cost functions.

This class is intended to be subclassed to create specific cost functions for evaluating model predictions against a set of data. The cost function quantifies the goodness-of-fit between the model predictions and the observed data, with a lower cost value indicating a better fit.

Parameters:

problem (object) – A problem instance containing the data and functions necessary for evaluating the cost function.
_target (array-like) – An array containing the target data to fit.
x0 (array-like) – The initial guess for the model parameters.
bounds (tuple) – The bounds for the model parameters.
sigma0 (scalar or array) – Initial standard deviation around x0. Either a scalar value (one standard deviation for all coordinates) or an array with one entry per dimension. Not all methods will use this information.
_n_parameters (int) – The number of parameters in the model.
n_outputs (int) – The number of outputs in the model.

__call__(x, grad=None)[source]#: Call the evaluate function for a given set of parameters.

abstract _evaluate(x, grad=None)[source]#

Calculate the cost function value for a given set of parameters.

This method must be implemented by subclasses.

Parameters:

x (array-like) – The parameters for which to evaluate the cost.
grad (array-like, optional) – An array to store the gradient of the cost function with respect to the parameters.

Returns:

The calculated cost function value.

Return type:

float

Raises:

NotImplementedError – If the method has not been implemented by the subclass.

abstract _evaluateS1(x)[source]#

Compute the cost and its gradient with respect to the parameters.

Parameters:: x (array-like) – The parameters for which to compute the cost and gradient.
Returns:: A tuple containing the cost and the gradient. The cost is a float, and the gradient is an array-like of the same length as x.
Return type:: tuple
Raises:: NotImplementedError – If the method has not been implemented by the subclass.

evaluate(x, grad=None)[source]#

Call the evaluate function for a given set of parameters.

Parameters:

x (array-like) – The parameters for which to evaluate the cost.
grad (array-like, optional) – An array to store the gradient of the cost function with respect to the parameters.

Returns:

The calculated cost function value.

Return type:

float

Raises:

ValueError – If an error occurs during the calculation of the cost.

evaluateS1(x)[source]#

Call _evaluateS1 for a given set of parameters.

Parameters:: x (array-like) – The parameters for which to compute the cost and gradient.
Returns:: A tuple containing the cost and the gradient. The cost is a float, and the gradient is an array-like of the same length as x.
Return type:: tuple
Raises:: ValueError – If an error occurs during the calculation of the cost or gradient.

property n_parameters#

class pybop.BaseLikelihood(problem, sigma=None)[source]#

Bases: pybop.costs.base_cost.BaseCost

Base class for likelihoods

get_n_parameters()[source]#: Returns the number of parameters

get_sigma()[source]#: Getter for sigma parameter

set_sigma(sigma)[source]#: Setter for sigma parameter

class pybop.BaseModel(name='Base Model')[source]#

A base class for constructing and simulating models using PyBaMM.

This class serves as a foundation for building specific models in PyBaMM. 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 behavior.

_check_params(inputs=None, allow_infeasible_solutions=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 (dict) – The input parameters for the simulation.
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

abstract approximate_capacity(x)[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:: x (array-like) – An array of values representing the model inputs.
Raises:: NotImplementedError – If the method has not been implemented by the subclass.

build(dataset=None, parameters=None, check_model=True, init_soc=None)[source]#

Construct the PyBaMM model if not already built, and set parameters.

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:

dataset (pybamm.Dataset, optional) – The dataset to be used in the model construction.
parameters (dict, optional) – A dictionary containing parameter values to apply to the model.
check_model (bool, optional) – If True, the model will be checked for correctness after construction.
init_soc (float, optional) – The initial state of charge to be used in simulations.

abstract cell_mass(parameter_set=None)[source]#

Calculate the cell mass in kilograms.

This method must be implemented by subclasses.

Parameters:: parameter_set (dict, optional) – A dictionary containing the parameter values necessary for the mass calculations.
Raises:: NotImplementedError – If the method has not been implemented by the subclass.

abstract cell_volume(parameter_set=None)[source]#

Calculate the cell volume in m3.

This method must be implemented by subclasses.

Parameters:: parameter_set (dict, optional) – A dictionary containing the parameter values necessary for the volume calculation.
Raises:: NotImplementedError – If the method has not been implemented by the subclass.

check_params(inputs=None, parameter_set=None, allow_infeasible_solutions=True)[source]#

Check compatibility of the model parameters.

Parameters:

inputs (dict) – The input parameters for the simulation.
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

classify_and_update_parameters(parameters)[source]#

Update the parameter values according to their classification as either ‘matched_parameters’ which require a model rebuild and ‘non_matched_parameters’ which are standard inputs.

Parameters:: parameters (pybop.ParameterSet)

copy()[source]#

Return a copy of the model.

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

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

predict(inputs=None, t_eval=None, parameter_set=None, experiment=None, init_soc=None)[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 (if any), and initial state of charge (if provided). It then solves the simulation and returns the resulting solution object.

Parameters:

inputs (dict or array-like, optional) – Input parameters for the simulation. If the input is array-like, it is converted to a dictionary using the model’s fitting keys. 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 (pybamm.ParameterValues, optional) – A PyBaMM ParameterValues object or a dictionary 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.
init_soc (float, optional) – The initial state of charge for the simulation, as a fraction (between 0 and 1). Defaults to None.

Returns:

The solution object returned after solving the simulation.

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.

rebuild(dataset=None, parameters=None, parameter_set=None, check_model=True, init_soc=None)[source]#

Rebuild the PyBaMM model for a given parameter set.

This method requires the self.build() method to be called first, and then rebuilds the model for a given parameter set. Specifically, this method applies the given parameters, sets up the mesh and discretisation if needed, and prepares the model for simulations.

Parameters:

dataset (pybamm.Dataset, optional) – The dataset to be used in the model construction.
parameters (dict, optional) – A dictionary containing parameter values to apply to the model.
parameter_set (pybop.parameter_set, optional) – A PyBOP parameter set object or a dictionary containing the parameter values
check_model (bool, optional) – If True, the model will be checked for correctness after construction.
init_soc (float, optional) – The initial state of charge to be used in simulations.

reinit(inputs: 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_init_soc(init_soc)[source]#

Set the initial state of charge for the battery model.

Parameters:: init_soc (float) – The initial state of charge to be used in the model.

set_params(rebuild=False)[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.

simulate(inputs, t_eval) → numpy.ndarray[numpy.float64][source]#

Execute the forward model simulation 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.
t_eval (array-like) – An array of time 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, t_eval)[source]#

Perform the forward model simulation with sensitivities.

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.
t_eval (array-like) – An array of time points at which to evaluate the solution and its sensitivities.

Returns:

A tuple containing the simulation result and the sensitivities.

Return type:

tuple

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)

property built_model#

property geometry#

property mesh#

property model_with_set_params#

property parameter_set#

property solver#

property spatial_methods#

property submesh_types#

property var_pts#

class pybop.BaseOptimiser(bounds=None)[source]#

A base class for defining optimisation methods.

This class serves as a template for creating optimisers. It provides a basic structure for an optimisation algorithm, including the initial setup and a method stub for performing the optimisation process. Child classes should override the optimise and _runoptimise methods with specific algorithms.

_runoptimise(cost_function, x0=None)[source]#

Contains the logic for the optimisation algorithm.

This method should be implemented by child classes to perform the actual optimisation.

Parameters:

cost_function (callable) – The cost function to be minimised by the optimiser.
x0 (ndarray, optional) – Initial guess for the parameters. Default is None.

Returns:

This method is expected to return the result of the optimisation, the format of which
will be determined by the child class implementation.

name()[source]#

Returns the name of the optimiser.

Returns:: The name of the optimiser, which is “BaseOptimiser” for this base class.
Return type:: str

optimise(cost_function, x0=None, maxiter=None)[source]#

Initiates the optimisation process.

This method should be overridden by child classes with the specific optimisation algorithm.

Parameters:

cost_function (callable) – The cost function to be minimised by the optimiser.
x0 (ndarray, optional) – Initial guess for the parameters. Default is None.
maxiter (int, optional) – Maximum number of iterations to perform. Default is None.

Return type:

The result of the optimisation process. The specific type of this result will depend on the child implementation.

class pybop.BaseProblem(parameters, model=None, check_model=True, signal=['Voltage [V]'], additional_variables=[], init_soc=None, x0=None)[source]#

Base class for defining a problem within the PyBOP framework, compatible with PINTS.

Parameters:

parameters (list) – List of parameters for the problem.
model (object, optional) – The model to be used for the problem (default: None).
check_model (bool, optional) – Flag to indicate if the model should be checked (default: True).
signal (List[str]) – The signal to observe.
additional_variables (List[str], optional) – Additional variables to observe and store in the solution (default: []).
init_soc (float, optional) – Initial state of charge (default: None).
x0 (np.ndarray, optional) – Initial parameter values (default: None).

abstract evaluate(x)[source]#

Evaluate the model with the given parameters and return the signal.

Parameters:: x (np.ndarray) – Parameter values to evaluate the model at.
Raises:: NotImplementedError – This method must be implemented by subclasses.

abstract evaluateS1(x)[source]#

Evaluate the model with the given parameters and return the signal and its derivatives.

Parameters:: x (np.ndarray) – Parameter values to evaluate the model at.
Raises:: NotImplementedError – This method must be implemented by subclasses.

target()[source]#

Return the target dataset.

Returns:: The target dataset array.
Return type:: np.ndarray

time_data()[source]#

Returns the time data.

Returns:: The time array.
Return type:: np.ndarray

property model#

class pybop.CMAES(x0, sigma0=0.1, bounds=None)[source]#

Bases: pints.CMAES

Adapter for the Covariance Matrix Adaptation Evolution Strategy (CMA-ES) optimiser in PINTS.

CMA-ES is an evolutionary algorithm for difficult non-linear non-convex optimization problems. It adapts the covariance matrix of a multivariate normal distribution to capture the shape of the cost landscape.

Parameters:

x0 (array_like) – The initial parameter vector to optimize.
sigma0 (float, optional) – Initial standard deviation of the sampling distribution, defaults to 0.1.
bounds (dict, optional) – A dictionary with ‘lower’ and ‘upper’ keys containing arrays for lower and upper bounds on the parameters. If None, no bounds are enforced.

See also

pints.CMAES: PINTS implementation of CMA-ES algorithm.

class pybop.Dataset(data_dictionary)[source]#

Represents a collection of experimental observations.

This class provides a structured way to store and work with experimental data, which may include applying operations such as interpolation.

Parameters:: data_dictionary (dict or instance of pybamm.solvers.solution.Solution) – The experimental data to store within the dataset.

Interpolant()[source]#

Create an interpolation function of the dataset based on the independent variable.

Currently, only time-based interpolation is supported. This method modifies the instance’s Interpolant attribute to be an interpolation function that can be evaluated at different points in time.

Raises:: NotImplementedError – If the independent variable for interpolation is not supported.

__getitem__(key)[source]#

Return the data corresponding to a particular key.

Parameters:: key (str) – The name of a data series within the dataset.
Returns:: The data series corresonding to the key.
Return type:: list or np.ndarray
Raises:: ValueError – The key must exist in the dataset.

__repr__()[source]#

Return a string representation of the Dataset instance.

Returns:: A string that includes the type and contents of the dataset.
Return type:: str

check(signal=['Voltage [V]'])[source]#

Check the consistency of a PyBOP Dataset against the expected format.

Returns:: If True, the dataset has the expected attributes.
Return type:: bool
Raises:: ValueError – If the time series and the data series are not consistent.

class pybop.DesignCost(problem, update_capacity=False)[source]#

Bases: pybop.costs.base_cost.BaseCost

Overwrites and extends BaseCost class for design-related cost functions.

Inherits all parameters and attributes from BaseCost.

Additional Attributes#

problemobject: The associated problem containing model and evaluation methods.
parameter_setobject): The set of parameters from the problem’s model.
dtfloat: The time step size used in the simulation.

abstract _evaluate(x, grad=None)[source]#

Computes the value of the cost function.

This method must be implemented by subclasses.

Parameters:

x (array) – The parameter set for which to compute the cost.
grad (array, optional) – Gradient information, not used in this method.

Raises:

NotImplementedError – If the method has not been implemented by the subclass.

update_simulation_data(initial_conditions)[source]#

Updates the simulation data based on the initial conditions.

Parameters:: initial_conditions (array) – The initial conditions for the simulation.

class pybop.DesignProblem(model, parameters, experiment, check_model=True, signal=['Voltage [V]'], additional_variables=[], init_soc=None, x0=None)[source]#

Bases: BaseProblem

Problem class for design optimization problems.

Extends BaseProblem with specifics for applying a model to an experimental design.

Parameters:

model (object) – The model to apply the design to.
parameters (list) – List of parameters for the problem.
experiment (object) – The experimental setup to apply the model to.
check_model (bool, optional) – Flag to indicate if the model parameters should be checked for feasibility each iteration (default: True).
signal (str, optional) – The signal to fit (default: “Voltage [V]”).
additional_variables (List[str], optional) – Additional variables to observe and store in the solution (default additions are: [“Time [s]”, “Current [A]”]).
init_soc (float, optional) – Initial state of charge (default: None).
x0 (np.ndarray, optional) – Initial parameter values (default: None).

evaluate(x)[source]#

Evaluate the model with the given parameters and return the signal.

Parameters:: x (np.ndarray) – Parameter values to evaluate the model at.
Returns:: y – The model output y(t) simulated with inputs x.
Return type:: np.ndarray

class pybop.Experiment(operating_conditions, period='1 minute', temperature=None, termination=None, drive_cycles=None, cccv_handling=None)[source]#

Bases: Experiment

Wraps the Experiment class for generating experiment conditions for PyBaMM models. Credit: PyBaMM

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) – List of 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, optional) – List of conditions under which 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).

class pybop.Exponential(scale)[source]#

Represents an exponential distribution with a specified scale parameter.

This class provides methods to calculate the pdf, the log pdf, and to generate random variates from the distribution.

Parameters:: scale (float) – The scale parameter (lambda) of the exponential distribution.

__repr__()[source]#: Returns a string representation of the Uniform object.

logpdf(x)[source]#

Calculates the logarithm of the pdf of the exponential distribution at x.

Parameters:: x (float) – The point at which to evaluate the log pdf.
Returns:: The log of the probability density function value at x.
Return type:: float

pdf(x)[source]#

Calculates the probability density function of the exponential distribution at x.

Parameters:: x (float) – The point at which to evaluate the pdf.
Returns:: The probability density function value at x.
Return type:: float

rvs(size)[source]#

Generates random variates from the exponential distribution.

Parameters:: size (int) – The number of random variates to generate.
Returns:: An array of random variates from the exponential distribution.
Return type:: array_like
Raises:: ValueError – If the size parameter is negative.

property mean#
Returns the mean of the distribution.

property sigma#
Returns the standard deviation of the distribution.

class pybop.FittingProblem(model, parameters, dataset, check_model=True, signal=['Voltage [V]'], additional_variables=[], init_soc=None, x0=None)[source]#

Bases: BaseProblem

Problem class for fitting (parameter estimation) problems.

Extends BaseProblem with specifics for fitting a model to a dataset.

Parameters:

model (object) – The model to fit.
parameters (list) – List of parameters for the problem.
dataset (Dataset) – Dataset object containing the data to fit the model to.
signal (str, optional) – The variable used for fitting (default: “Voltage [V]”).
additional_variables (List[str], optional) – Additional variables to observe and store in the solution (default additions are: [“Time [s]”]).
init_soc (float, optional) – Initial state of charge (default: None).
x0 (np.ndarray, optional) – Initial parameter values (default: None).

evaluate(x)[source]#

Evaluate the model with the given parameters and return the signal.

Parameters:: x (np.ndarray) – Parameter values to evaluate the model at.
Returns:: y – The model output y(t) simulated with inputs x.
Return type:: np.ndarray

evaluateS1(x)[source]#

Evaluate the model with the given parameters and return the signal and its derivatives.

Parameters:: x (np.ndarray) – Parameter values to evaluate the model at.
Returns:: A tuple containing the simulation result y(t) and the sensitivities dy/dx(t) evaluated with given inputs x.
Return type:: tuple

class pybop.Gaussian(mean, sigma)[source]#

Represents a Gaussian (normal) distribution with a given mean and standard deviation.

This class provides methods to calculate the probability density function (pdf), the logarithm of the pdf, and to generate random variates (rvs) from the distribution.

Parameters:

mean (float) – The mean (mu) of the Gaussian distribution.
sigma (float) – The standard deviation (sigma) of the Gaussian distribution.

__repr__()[source]#: Returns a string representation of the Gaussian object.

logpdf(x)[source]#

Calculates the logarithm of the probability density function of the Gaussian distribution at x.

Parameters:: x (float) – The point at which to evaluate the log pdf.
Returns:: The logarithm of the probability density function value at x.
Return type:: float

pdf(x)[source]#

Calculates the probability density function of the Gaussian distribution at x.

Parameters:: x (float) – The point at which to evaluate the pdf.
Returns:: The probability density function value at x.
Return type:: float

rvs(size)[source]#

Generates random variates from the Gaussian distribution.

Parameters:: size (int) – The number of random variates to generate.
Returns:: An array of random variates from the Gaussian distribution.
Return type:: array_like
Raises:: ValueError – If the size parameter is negative.

class pybop.GaussianLogLikelihood(problem)[source]#

Bases: BaseLikelihood

This class represents a Gaussian Log Likelihood, which assumes that the data follows a Gaussian distribution and computes the log-likelihood of observed data under this assumption.

_logpi#

Precomputed offset value for the log-likelihood function.

Type:: float

_evaluate(x, grad=None)[source]#

Evaluates the Gaussian log-likelihood for the given parameters.

Parameters:: x (array_like) – The parameters for which to evaluate the log-likelihood. The last self.n_outputs elements are assumed to be the standard deviations of the Gaussian distributions.
Returns:: The log-likelihood value, or -inf if the standard deviations are received as non-positive.
Return type:: float

_evaluateS1(x, grad=None)[source]#: Calls the problem.evaluateS1 method and calculates the log-likelihood

class pybop.GaussianLogLikelihoodKnownSigma(problem, sigma)[source]#

Bases: BaseLikelihood

This class represents a Gaussian Log Likelihood with a known sigma, which assumes that the data follows a Gaussian distribution and computes the log-likelihood of observed data under this assumption.

_logpi#

Precomputed offset value for the log-likelihood function.

Type:: float

_evaluate(x, grad=None)[source]#: Calls the problem.evaluate method and calculates the log-likelihood

_evaluateS1(x, grad=None)[source]#: Calls the problem.evaluateS1 method and calculates the log-likelihood

class pybop.GradientDescent(x0, sigma0=0.1, bounds=None)[source]#

Bases: pints.GradientDescent

Implements a simple gradient descent optimization algorithm.

This class extends the gradient descent optimiser from the PINTS library, designed to minimize a scalar function of one or more variables. Note that this optimiser does not support boundary constraints.

Parameters:

x0 (array_like) – Initial position from which optimization will start.
sigma0 (float, optional) – Initial step size (default is 0.1).
bounds (sequence or Bounds, optional) – Ignored by this optimiser, provided for API consistency.

See also

pints.GradientDescent: The PINTS implementation this class is based on.

class pybop.GravimetricEnergyDensity(problem, update_capacity=False)[source]#

Bases: DesignCost

Represents the gravimetric energy density of a battery cell, calculated based on a normalised discharge from upper to lower voltage limits. The goal is to maximise the energy density, which is achieved by minimizing the negative energy density reported by this class.

Inherits all parameters and attributes from DesignCost.

_evaluate(x, grad=None)[source]#

Computes the cost function for the energy density.

Parameters:

x (array) – The parameter set for which to compute the cost.
grad (array, optional) – Gradient information, not used in this method.

Returns:

The negative gravimetric energy density or infinity in case of infeasible parameters.

Return type:

float

class pybop.IRPropMin(x0, sigma0=0.1, bounds=None)[source]#

Bases: pints.IRPropMin

Implements the iRpropMin optimization algorithm.

This class inherits from the PINTS IRPropMin class, which is an optimiser that uses resilient backpropagation with weight-backtracking. It is designed to handle problems with large plateaus, noisy gradients, and local minima.

Parameters:

x0 (array_like) – Initial position from which optimization will start.
sigma0 (float, optional) – Initial step size (default is 0.1).
bounds (dict, optional) – Lower and upper bounds for each optimization parameter.

See also

pints.IRPropMin: The PINTS implementation this class is based on.

class pybop.Observer(parameters: List[pybop.parameters.parameter.Parameter], model: pybop.models.base_model.BaseModel, check_model=True, signal=['Voltage [V]'], additional_variables=[], init_soc=None, x0=None)[source]#

Bases: pybop._problem.BaseProblem

An observer of a time series state. Observers:

keep track of the distribution of a current time series model state
predict forward in time the distribution of the state
update the distribution of the state with new observations

Parameters:

parameters (list) – List of parameters for the problem.
model (BaseModel) – The model to observe.
check_model (bool, optional) – Flag to indicate if the model should be checked (default: True).
signal (List[str]) – The signal to observe.
additional_variables (List[str], optional) – Additional variables to observe and store in the solution (default: []).
init_soc (float, optional) – Initial state of charge (default: None).
x0 (np.ndarray, optional) – Initial parameter values (default: None).

evaluate(x)[source]#

Evaluate the model with the given parameters and return the signal.

Parameters:: x (np.ndarray) – Parameter values to evaluate the model at.
Returns:: y – The model output y(t) simulated with inputs x.
Return type:: np.ndarray

get_current_covariance() → Covariance[source]#: Returns the current covariance of the model.

get_current_measure() → numpy.ndarray[source]#: Returns the current measurement.

get_current_state() → pybop.models.base_model.TimeSeriesState[source]#: Returns the current state of the model.

get_current_time() → float[source]#: Returns the current time.

get_measure(x: pybop.models.base_model.TimeSeriesState) → numpy.ndarray[source]#

log_likelihood(values: dict, times: numpy.ndarray, inputs: pybop.models.base_model.Inputs) → float[source]#

Returns the log likelihood of the model given the values and inputs.

Parameters:

values (np.ndarray) – The values of the model.
times (np.ndarray) – The times at which to observe the model.
inputs (Inputs) – The inputs to the model.

observe(time: float, value: numpy.ndarray | None = None) → float[source]#

Predict the time series model until t = time and optionally observe the measurement value.

Returns the log likelihood of the model given the value and inputs. If no value is given, the log likelihood is 0.

The base observer does not perform any value observation and always returns 0.

Parameters:

time (float) – The time of the new observation.
value (np.ndarray (optional)) – The new observation.

reset(inputs: pybop.models.base_model.Inputs) → None[source]#

Covariance#

class pybop.ObserverCost(observer: pybop.observers.observer.Observer)[source]#

Bases: pybop.costs.base_cost.BaseCost

Observer cost function.

Computes the cost function for an observer model, which is log likelihood of the data points given the model parameters.

Inherits all parameters and attributes from BaseCost.

_evaluate(x, grad=None)[source]#

Calculate the observer cost for a given set of parameters.

Parameters:

x (array-like) – The parameters for which to evaluate the cost.
grad (array-like, optional) – An array to store the gradient of the cost function with respect to the parameters.

Returns:

The observer cost (negative of the log likelihood).

Return type:

float

abstract evaluateS1(x)[source]#

Compute the cost and its gradient with respect to the parameters.

Parameters:: x (array-like) – The parameters for which to compute the cost and gradient.
Returns:: A tuple containing the cost and the gradient. The cost is a float, and the gradient is an array-like of the same length as x.
Return type:: tuple
Raises:: ValueError – If an error occurs during the calculation of the cost or gradient.

class pybop.Optimisation(cost, x0=None, optimiser=None, sigma0=None, verbose=False, physical_viability=True, allow_infeasible_solutions=True)[source]#

A class for conducting optimization using PyBOP or PINTS optimisers.

Parameters:

cost (pybop.BaseCost or pints.ErrorMeasure) – An objective function to be optimized, which can be either a pybop.Cost or PINTS error measure
optimiser (pybop.Optimiser or subclass of pybop.BaseOptimiser, optional) – An optimiser from either the PINTS or PyBOP framework to perform the optimization (default: None).
sigma0 (float or sequence, optional) – Initial step size or standard deviation for the optimiser (default: None).
verbose (bool, optional) – If True, the optimization progress is printed (default: False).
physical_viability (bool, optional) – If True, the feasibility of the optimised parameters is checked (default: True).
allow_infeasible_solutions (bool, optional) – If True, infeasible parameter values will be allowed in the optimisation (default: True).

x0#

Initial parameter values for the optimization.

Type:: numpy.ndarray

bounds#

Dictionary containing the parameter bounds with keys ‘lower’ and ‘upper’.

Type:: dict

_n_parameters#

Number of parameters in the optimization problem.

Type:: int

sigma0#

Initial step size or standard deviation for the optimiser.

Type:: float or sequence

log#

Log of the optimization process.

Type:: list

_run_pints()[source]#

Internal method to run the optimization using a PINTS optimiser.

Returns:

x (numpy.ndarray) – The best parameter set found by the optimization.
final_cost (float) – The final cost associated with the best parameters.

See also

This

_run_pybop()[source]#

Internal method to run the optimization using a PyBOP optimiser.

Returns:

x (numpy.ndarray) – The best parameter set found by the optimization.
final_cost (float) – The final cost associated with the best parameters.

check_optimal_parameters(x)[source]#: Check if the optimised parameters are physically viable.

f_guessed_tracking()[source]#

Check if f_guessed instead of f_best is being tracked. Credit: PINTS

Returns:: True if f_guessed is being tracked, False otherwise.
Return type:: bool

run()[source]#

Run the optimization and return the optimized parameters and final cost.

Returns:

x (numpy.ndarray) – The best parameter set found by the optimization.
final_cost (float) – The final cost associated with the best parameters.

set_f_guessed_tracking(use_f_guessed=False)[source]#

Set the method used to track the optimiser progress. Credit: PINTS

Parameters:: use_f_guessed (bool, optional) – If True, track f_guessed; otherwise, track f_best (default: False).

set_max_evaluations(evaluations=None)[source]#

Set a maximum number of evaluations stopping criterion. Credit: PINTS

Parameters:: evaluations (int, optional) – The maximum number of evaluations after which to stop the optimization (default: None).

set_max_iterations(iterations=1000)[source]#

Set the maximum number of iterations as a stopping criterion. Credit: PINTS

Parameters:: iterations (int, optional) – The maximum number of iterations to run (default is 1000). Set to None to remove this stopping criterion.

set_max_unchanged_iterations(iterations=15, threshold=1e-05)[source]#

Set the maximum number of iterations without significant change as a stopping criterion. Credit: PINTS

Parameters:

iterations (int, optional) – The maximum number of unchanged iterations to run (default is 15). Set to None to remove this stopping criterion.
threshold (float, optional) – The minimum significant change in the objective function value that resets the unchanged iteration counter (default is 1e-5).

set_min_iterations(iterations=2)[source]#

Set the minimum number of iterations as a stopping criterion.

Parameters:: iterations (int, optional) – The minimum number of iterations to run (default is 100). Set to None to remove this stopping criterion.

set_parallel(parallel=False)[source]#

Enable or disable parallel evaluation. Credit: PINTS

Parameters:: parallel (bool or int, optional) – If True, use as many worker processes as there are CPU cores. If an integer, use that many workers. If False or 0, disable parallelism (default: False).

store_optimised_parameters(x)[source]#

Update the problem parameters with optimized values.

The optimized parameter values are stored within the associated PyBOP parameter class.

Parameters:: x (array-like) – Optimized parameter values.

class pybop.PSO(x0, sigma0=0.1, bounds=None)[source]#

Bases: pints.PSO

Implements a particle swarm optimization (PSO) algorithm.

This class extends the PSO optimiser from the PINTS library. PSO is a metaheuristic optimization method inspired by the social behavior of birds flocking or fish schooling, suitable for global optimization problems.

Parameters:

x0 (array_like) – Initial positions of particles, which the optimization will use.
sigma0 (float, optional) – Spread of the initial particle positions (default is 0.1).
bounds (dict, optional) – Lower and upper bounds for each optimization parameter.

See also

pints.PSO: The PINTS implementation this class is based on.

class pybop.Parameter(name, initial_value=None, true_value=None, prior=None, bounds=None)[source]#

Represents a parameter within the PyBOP framework.

This class encapsulates the definition of a parameter, including its name, prior distribution, initial value, bounds, and a margin to ensure the parameter stays within feasible limits during optimization or sampling.

Parameters:

name (str) – The name of the parameter.
initial_value (float, optional) – The initial value to be assigned to the parameter. Defaults to None.
prior (scipy.stats distribution, optional) – The prior distribution from which parameter values are drawn. Defaults to None.
bounds (tuple, optional) – A tuple defining the lower and upper bounds for the parameter. Defaults to None.

Raises:

ValueError – If the lower bound is not strictly less than the upper bound, or if the margin is set outside the interval (0, 1).

__repr__()[source]#

Return a string representation of the Parameter instance.

Returns:: A string including the parameter’s name, prior, bounds, and current value.
Return type:: str

rvs(n_samples)[source]#

Draw random samples from the parameter’s prior distribution.

The samples are constrained to be within the parameter’s bounds, excluding a predefined margin at the boundaries.

Parameters:: n_samples (int) – The number of samples to draw.
Returns:: An array of samples drawn from the prior distribution within the parameter’s bounds.
Return type:: array-like

set_bounds(bounds=None)[source]#

Set the upper and lower bounds.

Parameters:: bounds (tuple, optional) – A tuple defining the lower and upper bounds for the parameter. Defaults to None.
Raises:: ValueError – If the lower bound is not strictly less than the upper bound, or if the margin is set outside the interval (0, 1).

set_margin(margin)[source]#

Set the margin to a specified positive value less than 1.

The margin is used to ensure parameter samples are not drawn exactly at the bounds, which may be problematic in some optimization or sampling algorithms.

Parameters:: margin (float) – The new margin value to be used, which must be in the interval (0, 1).
Raises:: ValueError – If the margin is not between 0 and 1.

update(value=None, initial_value=None)[source]#

Update the parameter’s current value.

Parameters:: value (float) – The new value to be assigned to the parameter.

class pybop.ParameterSet(json_path=None, params_dict=None)[source]#

Handles the import and export of parameter sets for battery models.

This class provides methods to load parameters from a JSON file and to export them back to a JSON file. It also includes custom logic to handle special cases, such as parameter values that require specific initialization.

Parameters:

json_path (str, optional) – Path to a JSON file containing parameter data. If provided, parameters will be imported from this file during initialization.
params_dict (dict, optional) – A dictionary of parameters to initialize the ParameterSet with. If not provided, an empty dictionary is used.

_handle_special_cases()[source]#

Processes special cases for parameter values that require custom handling.

For example, if the open-circuit voltage is specified as ‘default’, it will fetch the default value from the PyBaMM empirical Thevenin model.

export_parameters(output_json_path, fit_params=None)[source]#

Exports parameters to a JSON file specified by output_json_path.

The current state of the params attribute is written to the file. If fit_params is provided, these parameters are updated before export. Non-serializable values are handled and noted in the output JSON.

Parameters:

output_json_path (str) – The file path where the JSON output will be saved.
fit_params (list of fitted parameter objects, optional) – Parameters that have been fitted and need to be included in the export.

Raises:

ValueError – If there are no parameters to export.

import_parameters(json_path=None)[source]#

Imports parameters from a JSON file specified by the json_path attribute.

If a json_path is provided at initialization or as an argument, that JSON file is loaded and the parameters are stored in the params attribute. Special cases are handled appropriately.

Parameters:: json_path (str, optional) – Path to the JSON file from which to import parameters. If provided, it overrides the instance’s json_path.
Returns:: The dictionary containing the imported parameters.
Return type:: dict
Raises:: FileNotFoundError – If the specified JSON file cannot be found.

is_json_serializable(value)[source]#

Determines if the given value can be serialized to JSON format.

Parameters:: value (any) – The value to check for JSON serializability.
Returns:: True if the value is JSON serializable, False otherwise.
Return type:: bool

classmethod pybamm(name)[source]#

Retrieves a PyBaMM parameter set by name.

Parameters:: name (str) – The name of the PyBaMM parameter set to retrieve.
Returns:: A PyBaMM parameter set corresponding to the provided name.
Return type:: pybamm.ParameterValues

class pybop.PlotlyManager[source]#

Manages the installation and configuration of Plotly for generating visualizations.

This class ensures that Plotly is installed and properly configured to display plots in a web browser.

Upon instantiation, it checks for Plotly’s presence, installs it if missing, and configures the default renderer and browser settings.

go#

The Plotly graph_objects module for creating figures.

Type:: module

pio#

The Plotly input/output module for configuring the renderer.

Type:: module

make_subplots#

The function from Plotly for creating subplot figures.

Type:: function

Examples

>>> plotly_manager = PlotlyManager()

check_browser_availability()[source]#: Confirm a web browser is available for Plotly’s ‘browser’ renderer; provide guidance if not.

check_renderer_settings()[source]#: Check and provide information on setting the Plotly renderer if it’s not already set.

ensure_plotly_installed()[source]#: Check if Plotly is installed and import necessary modules; prompt for installation if missing.

install_plotly()[source]#: Install the Plotly package using pip. Exit if installation fails.

post_install_setup()[source]#: Import Plotly modules and set the default renderer after installation.

prompt_for_plotly_installation()[source]#: Prompt the user for Plotly installation and install it upon agreement.

class pybop.RootMeanSquaredError(problem)[source]#

Bases: pybop.costs.base_cost.BaseCost

Root mean square error cost function.

Computes the root mean square error between model predictions and the target data, providing a measure of the differences between predicted values and observed values.

Inherits all parameters and attributes from BaseCost.

_evaluate(x, grad=None)[source]#

Calculate the root mean square error for a given set of parameters.

Parameters:

x (array-like) – The parameters for which to evaluate the cost.
grad (array-like, optional) – An array to store the gradient of the cost function with respect to the parameters.

Returns:

The root mean square error.

Return type:

float

_evaluateS1(x)[source]#

Compute the cost and its gradient with respect to the parameters.

Parameters:: x (array-like) – The parameters for which to compute the cost and gradient.
Returns:: A tuple containing the cost and the gradient. The cost is a float, and the gradient is an array-like of the same length as x.
Return type:: tuple
Raises:: ValueError – If an error occurs during the calculation of the cost or gradient.

set_fail_gradient(de)[source]#

Set the fail gradient to a specified value.

The fail gradient is used if an error occurs during the calculation of the gradient. This method allows updating the default gradient value.

Parameters:: de (float) – The new fail gradient value to be used.

class pybop.SNES(x0, sigma0=0.1, bounds=None)[source]#

Bases: pints.SNES

Implements the stochastic natural evolution strategy (SNES) optimization algorithm.

Inheriting from the PINTS SNES class, this optimiser is an evolutionary algorithm that evolves a probability distribution on the parameter space, guiding the search for the optimum based on the natural gradient of expected fitness.

Parameters:

x0 (array_like) – Initial position from which optimization will start.
sigma0 (float, optional) – Initial standard deviation of the sampling distribution, defaults to 0.1.
bounds (dict, optional) – Lower and upper bounds for each optimization parameter.

See also

pints.SNES: The PINTS implementation this class is based on.

class pybop.SciPyDifferentialEvolution(bounds=None, strategy='best1bin', maxiter=1000, popsize=15, tol=1e-05)[source]#

Bases: pybop.optimisers.base_optimiser.BaseOptimiser

Adapts SciPy’s differential_evolution function for global optimization.

This class provides a global optimization strategy based on differential evolution, useful for problems involving continuous parameters and potentially multiple local minima.

Parameters:

bounds (sequence or Bounds) – Bounds for variables. Must be provided as it is essential for differential evolution.
strategy (str, optional) – The differential evolution strategy to use. Defaults to ‘best1bin’.
maxiter (int, optional) – Maximum number of iterations to perform. Defaults to 1000.
popsize (int, optional) – The number of individuals in the population. Defaults to 15.

_runoptimise(cost_function, x0=None)[source]#

Executes the optimization process using SciPy’s differential_evolution function.

Parameters:

cost_function (callable) – The objective function to minimize.
x0 (array_like, optional) – Ignored parameter, provided for API consistency.

Returns:

A tuple (x, final_cost) containing the optimized parameters and the value of cost_function at the optimum.

Return type:

tuple

name()[source]#

Provides the name of the optimization strategy.

Returns:: The name ‘SciPyDifferentialEvolution’.
Return type:: str

needs_sensitivities()[source]#

Determines if the optimization algorithm requires gradient information.

Returns:: False, indicating that gradient information is not required for differential evolution.
Return type:: bool

set_population_size(population_size=None)[source]#: Sets a population size to use in this optimisation. Credit: PINTS

class pybop.SciPyMinimize(method=None, bounds=None, maxiter=None, tol=1e-05)[source]#

Bases: pybop.optimisers.base_optimiser.BaseOptimiser

Adapts SciPy’s minimize function for use as an optimization strategy.

This class provides an interface to various scalar minimization algorithms implemented in SciPy, allowing fine-tuning of the optimization process through method selection and option configuration.

Parameters:

method (str, optional) – The type of solver to use. If not specified, defaults to ‘Nelder-Mead’. Options: ‘Nelder-Mead’, ‘Powell’, ‘CG’, ‘BFGS’, ‘Newton-CG’, ‘L-BFGS-B’, ‘TNC’, ‘COBYLA’, ‘SLSQP’, ‘trust-constr’, ‘dogleg’, ‘trust-ncg’, ‘trust-exact’, ‘trust-krylov’.
bounds (sequence or Bounds, optional) – Bounds for variables as supported by the selected method.
maxiter (int, optional) – Maximum number of iterations to perform.

_runoptimise(cost_function, x0)[source]#

Executes the optimization process using SciPy’s minimize function.

Parameters:

cost_function (callable) – The objective function to minimize.
x0 (array_like) – Initial guess for the parameters.

Returns:

A tuple (x, final_cost) containing the optimized parameters and the value of cost_function at the optimum.

Return type:

tuple

name()[source]#

Provides the name of the optimization strategy.

Returns:: The name ‘SciPyMinimize’.
Return type:: str

needs_sensitivities()[source]#

Determines if the optimization algorithm requires gradient information.

Returns:: False, indicating that gradient information is not required.
Return type:: bool

class pybop.StandardPlot(x, y, layout=None, layout_options=DEFAULT_LAYOUT_OPTIONS, trace_options=DEFAULT_TRACE_OPTIONS, trace_names=None, trace_name_width=40)[source]#

A class for creating and displaying interactive Plotly figures.

Parameters:

x (list or np.ndarray) – X-axis data points.
y (list or np.ndarray) – Primary Y-axis data points for simulated model output.
layout (Plotly layout, optional) – A layout for the figure, overrides the layout options (default: None).
layout_options (dict, optional) – Settings to modify the default layout (default: DEFAULT_LAYOUT_OPTIONS).
trace_options (dict, optional) – Settings to modify the default trace type (default: DEFAULT_TRACE_OPTIONS).
trace_names (str, optional) – Name(s) for the primary trace(s) (default: None).
trace_name_width (int, optional) – Maximum length of the trace names before text wrapping is used (default: 40).

Returns:

The generated Plotly figure.

Return type:

plotly.graph_objs.Figure

__call__(show=True)[source]#

Generate and show the figure.

Parameters:: show (bool, optional) – If True, the figure is shown upon creation (default: True).

create_trace(x, y, **trace_options)[source]#

Create a trace for the Plotly figure.

Returns:: A trace for a Plotly figure.
Return type:: plotly.graph_objs.Scatter

static remove_brackets(s)[source]#: Remove square brackets from a string and replace with forward slashes as per section 7.1 of the SI Handbook

static wrap_text(text, width)[source]#

Wrap text to a specified width with HTML line breaks.

Parameters:

text (str) – The text to wrap.
width (int) – The width to wrap the text to.

Returns:

The wrapped text.

Return type:

str

class pybop.StandardSubplot(x, y, num_rows=None, num_cols=None, axis_titles=None, layout=None, layout_options=DEFAULT_LAYOUT_OPTIONS, subplot_options=DEFAULT_SUBPLOT_OPTIONS, trace_options=DEFAULT_SUBPLOT_TRACE_OPTIONS, trace_names=None, trace_name_width=40)[source]#

Bases: StandardPlot

A class for creating and displaying a set of interactive Plotly figures in a grid layout.

Parameters:

x (list or np.ndarray) – X-axis data points.
y (list or np.ndarray) – Primary Y-axis data points for simulated model output.
num_rows (int, optional) – Number of rows of subplots, can be set automatically (default: None).
num_cols (int, optional) – Number of columns of subplots, can be set automatically (default: None).
layout (Plotly layout, optional) – A layout for the figure, overrides the layout options (default: None).
layout_options (dict, optional) – Settings to modify the default layout (default: DEFAULT_LAYOUT_OPTIONS).
trace_options (dict, optional) – Settings to modify the default trace type (default: DEFAULT_TRACE_OPTIONS).
trace_names (str, optional) – Name(s) for the primary trace(s) (default: None).
trace_name_width (int, optional) – Maximum length of the trace names before text wrapping is used (default: 40).

Returns:

The generated Plotly figure.

Return type:

plotly.graph_objs.Figure

__call__(show)[source]#

Generate and show the set of figures.

Parameters:: show (bool, optional) – If True, the figure is shown upon creation (default: True).

class pybop.SumSquaredError(problem)[source]#

Bases: pybop.costs.base_cost.BaseCost

Sum of squared errors cost function.

Computes the sum of the squares of the differences between model predictions and target data, which serves as a measure of the total error between the predicted and observed values.

Inherits all parameters and attributes from BaseCost.

Additional Attributes#

_defloat: The gradient of the cost function to use if an error occurs during evaluation. Defaults to 1.0.

_evaluate(x, grad=None)[source]#

Calculate the sum of squared errors for a given set of parameters.

Parameters:

x (array-like) – The parameters for which to evaluate the cost.
grad (array-like, optional) – An array to store the gradient of the cost function with respect to the parameters.

Returns:

The sum of squared errors.

Return type:

float

_evaluateS1(x)[source]#

Compute the cost and its gradient with respect to the parameters.

Parameters:: x (array-like) – The parameters for which to compute the cost and gradient.
Returns:: A tuple containing the cost and the gradient. The cost is a float, and the gradient is an array-like of the same length as x.
Return type:: tuple
Raises:: ValueError – If an error occurs during the calculation of the cost or gradient.

set_fail_gradient(de)[source]#

Set the fail gradient to a specified value.

The fail gradient is used if an error occurs during the calculation of the gradient. This method allows updating the default gradient value.

Parameters:: de (float) – The new fail gradient value to be used.

class pybop.TimeSeriesState[source]#

Bases: object

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

__len__()[source]#

as_ndarray() → numpy.ndarray[source]#

inputs: Inputs#

sol: pybamm.Solution#

t: float = 0.0#

class pybop.Uniform(lower, upper)[source]#

Represents a uniform distribution over a specified interval.

This class provides methods to calculate the pdf, the log pdf, and to generate random variates from the distribution.

Parameters:

lower (float) – The lower bound of the distribution.
upper (float) – The upper bound of the distribution.

__repr__()[source]#: Returns a string representation of the Uniform object.

logpdf(x)[source]#

Calculates the logarithm of the pdf of the uniform distribution at x.

Parameters:: x (float) – The point at which to evaluate the log pdf.
Returns:: The log of the probability density function value at x.
Return type:: float

pdf(x)[source]#

Calculates the probability density function of the uniform distribution at x.

Parameters:: x (float) – The point at which to evaluate the pdf.
Returns:: The probability density function value at x.
Return type:: float

rvs(size)[source]#

Generates random variates from the uniform distribution.

Parameters:: size (int) – The number of random variates to generate.
Returns:: An array of random variates from the uniform distribution.
Return type:: array_like
Raises:: ValueError – If the size parameter is negative.

property mean#
Returns the mean of the distribution.

property sigma#
Returns the standard deviation of the distribution.

class pybop.UnscentedKalmanFilterObserver(parameters: List[pybop.parameters.parameter.Parameter], model: pybop.models.base_model.BaseModel, sigma0: Covariance | float, process: Covariance | float, measure: Covariance | float, dataset=None, check_model=True, signal=['Voltage [V]'], additional_variables=[], init_soc=None, x0=None)[source]#

Bases: pybop.observers.observer.Observer

An observer using the unscented Kalman filter. This is a wrapper class for PyBOP, see class SquareRootUKF for more details on the method.

Parameters:

parameters (List[Parameters]) – The inputs to the model.
model (BaseModel) – The model to observe.
sigma0 (np.ndarray | float) – The covariance matrix of the initial state. If a float is provided, the covariance matrix is set to sigma0 * np.eye(n), where n is the number of states. To remove a state from the filter, set the corresponding row and col to zero in both sigma0 and process.
process (np.ndarray | float) – The covariance matrix of the process noise. If a float is provided, the covariance matrix is set to process * np.eye(n), where n is the number of states. To remove a state from the filter, set the corresponding row and col to zero in both sigma0 and process.
measure (np.ndarray | float) – The covariance matrix of the measurement noise. If a float is provided, the covariance matrix is set to measure * np.eye(m), where m is the number of measurements.
dataset (Dataset) – Dataset object containing the data to fit the model to.
check_model (bool, optional) – Flag to indicate if the model should be checked (default: True).
signal (str) – The signal to observe.
init_soc (float, optional) – Initial state of charge (default: None).
x0 (np.ndarray, optional) – Initial parameter values (default: None).

get_current_covariance() → Covariance[source]#: Returns the current covariance of the model.

observe(time: float, value: numpy.ndarray) → float[source]#

Predict the time series model until t = time and optionally observe the measurement value.

Returns the log likelihood of the model given the value and inputs. If no value is given, the log likelihood is 0.

The base observer does not perform any value observation and always returns 0.

Parameters:

time (float) – The time of the new observation.
value (np.ndarray (optional)) – The new observation.

reset(inputs: pybop.models.base_model.Inputs) → None[source]#

Covariance#

class pybop.VolumetricEnergyDensity(problem, update_capacity=False)[source]#

Bases: DesignCost

Represents the volumetric energy density of a battery cell, calculated based on a normalised discharge from upper to lower voltage limits. The goal is to maximise the energy density, which is achieved by minimizing the negative energy density reported by this class.

Inherits all parameters and attributes from DesignCost.

_evaluate(x, grad=None)[source]#

Computes the cost function for the energy density.

Parameters:

x (array) – The parameter set for which to compute the cost.
grad (array, optional) – Gradient information, not used in this method.

Returns:

The negative volumetric energy density or infinity in case of infeasible parameters.

Return type:

float

class pybop.XNES(x0, sigma0=0.1, bounds=None)[source]#

Bases: pints.XNES

Implements the Exponential Natural Evolution Strategy (XNES) optimiser from PINTS.

XNES is an evolutionary algorithm that samples from a multivariate normal distribution, which is updated iteratively to fit the distribution of successful solutions.

Parameters:

x0 (array_like) – The initial parameter vector to optimize.
sigma0 (float, optional) – Initial standard deviation of the sampling distribution, defaults to 0.1.
bounds (dict, optional) – A dictionary with ‘lower’ and ‘upper’ keys containing arrays for lower and upper bounds on the parameters. If None, no bounds are enforced.

See also

pints.XNES: PINTS implementation of XNES algorithm.

pybop.is_numeric(x)[source]#: Check if a variable is numeric.

pybop.plot2d(cost_or_optim, gradient=False, bounds=None, steps=10, show=True, **layout_kwargs)[source]#

Plot a 2D visualisation of a cost landscape using Plotly.

This function generates a contour plot representing the cost landscape for a provided callable cost function over a grid of parameter values within the specified bounds.

Parameters:

cost_or_optim (a callable cost function, pybop Cost or Optimisation object) – Either: - the cost function to be evaluated. Must accept a list of parameter values and return a cost value. - an Optimisation object which provides a specific optimisation trace overlaid on the cost landscape.
gradient (bool, optional) – If True, the gradient is shown (default: False).
bounds (numpy.ndarray, optional) – A 2x2 array specifying the [min, max] bounds for each parameter. If None, uses get_param_bounds.
steps (int, optional) – The number of intervals to divide the parameter space into along each dimension (default is 10).
show (bool, optional) – If True, the figure is shown upon creation (default: True).
**layout_kwargs (optional) – Valid Plotly layout keys and their values, e.g. xaxis_title=”Time [s]” or xaxis={“title”: “Time [s]”, “titlefont_size”: 18}.

Returns:

The Plotly figure object containing the cost landscape plot.

Return type:

plotly.graph_objs.Figure

Raises:

ValueError – If the cost function does not return a valid cost when called with a parameter list.

pybop.plot_convergence(optim, show=True, **layout_kwargs)[source]#

Plot the convergence of the optimisation algorithm.

Parameters:

optim (object) – Optimisation object containing the cost function and optimiser.
show (bool, optional) – If True, the figure is shown upon creation (default: True).
**layout_kwargs (optional) – Valid Plotly layout keys and their values, e.g. xaxis_title=”Time [s]” or xaxis={“title”: “Time [s]”, “titlefont_size”: 18}.

Returns:

fig – The Plotly figure object for the convergence plot.

Return type:

plotly.graph_objs.Figure

pybop.plot_dataset(dataset, signal=['Voltage [V]'], trace_names=None, show=True, **layout_kwargs)[source]#

Quickly plot a PyBOP Dataset using Plotly.

Parameters:

dataset (object) – A PyBOP dataset.
signal (list or str, optional) – The name of the time series to plot (default: “Voltage [V]”).
trace_names (list or str, optional) – Name(s) for the trace(s) (default: “Data”).
show (bool, optional) – If True, the figure is shown upon creation (default: True).
**layout_kwargs (optional) – Valid Plotly layout keys and their values, e.g. xaxis_title=”Time / s” or xaxis={“title”: “Time / s”, “titlefont_size”: 18}.

Returns:

The Plotly figure object for the scatter plot.

Return type:

plotly.graph_objs.Figure

pybop.plot_parameters(optim, show=True, **layout_kwargs)[source]#

Plot the evolution of parameters during the optimization process using Plotly.

Parameters:

optim (object) – Optimisation object containing the history of parameter values and associated cost.
show (bool, optional) – If True, the figure is shown upon creation (default: True).
**layout_kwargs (optional) – Valid Plotly layout keys and their values, e.g. xaxis_title=”Time [s]” or xaxis={“title”: “Time [s]”, “titlefont_size”: 18}.

Returns:

A Plotly figure object showing the parameter evolution over iterations.

Return type:

plotly.graph_objs.Figure

pybop.plot_trajectories(x, y, trace_names=None, show=True, **layout_kwargs)[source]#

Quickly plot one or more trajectories using Plotly.

Parameters:

x (list or np.ndarray) – X-axis data points.
y (list or np.ndarray) – Y-axis data points for each trajectory.
trace_names (list or str, optional) – Name(s) for the trace(s) (default: None).
**layout_kwargs (optional) – Valid Plotly layout keys and their values, e.g. xaxis_title=”Time / s” or xaxis={“title”: “Time / s”, “titlefont_size”: 18}.

Returns:

The Plotly figure object for the scatter plot.

Return type:

plotly.graph_objs.Figure

pybop.quick_plot(problem, parameter_values=None, show=True, **layout_kwargs)[source]#

Quickly plot the target dataset against optimised model output.

Generates an interactive plot comparing the simulated model output with an optional target dataset and visualises uncertainty.

Parameters:

problem (object) – Problem object with dataset and signal attributes.
parameter_values (array-like) – Optimised (or example) parameter values.
show (bool, optional) – If True, the figure is shown upon creation (default: True).
**layout_kwargs (optional) – Valid Plotly layout keys and their values, e.g. xaxis_title=”Time / s” or xaxis={“title”: “Time / s”, “titlefont_size”: 18}.

Returns:

The Plotly figure object for the scatter plot.

Return type:

plotly.graph_objs.Figure

pybop.FLOAT_FORMAT = '{: .17e}'[source]#

pybop.Inputs[source]#

pybop.__version__[source]#

pybop.script_path[source]#