pybop.costs.error_measures#

Classes#

ErrorMeasure

Base fitting cost (error measure).

MeanAbsoluteError

Mean absolute error (MAE) cost function.

MeanSquaredError

Mean square error (MSE) cost function.

Minkowski

The Minkowski distance is a generalisation of several distance metrics,

RootMeanSquaredError

Root mean square error (RMSE) cost function.

SumOfPower

The Sum of Power [1] is a generalised cost function based on the p-th power

SumSquaredError

Sum of squared error (SSE) cost function.

Module Contents#

class pybop.costs.error_measures.ErrorMeasure(dataset: pybop.processing.dataset.Dataset, target: str | list[str] = None, weighting: float | str | numpy.ndarray = None)[source]#

Bases: pybop.costs.base_cost.BaseCost

Base fitting cost (error measure).

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 model predictions and the target data, with a lower cost value indicating a better fit.

Parameters:

  • dataset (pybop.Dataset) – Dataset object containing the target data.

  • target (list[str]) – The name(s) of the target variable(s).

  • weighting (Union[str, np.ndarray], optional) – The type of weighting to use when taking the sum or mean of the error measure.

dataset#

The dictionary from a Dataset object containing the target data.

Type:

dictionary

domain#

The name of the domain (default: “Time [s]”).

Type:

str

domain_data#

The domain points in the dataset.

Type:

np.ndarray

n_data#

The number of domain points.

Type:

int

target_data#

The target values of the output variables.

Type:

np.ndarray

abstractmethod __call__(r: numpy.ndarray, dy: numpy.ndarray | None = None, inputs: pybop.parameters.parameter.Inputs | None = None) → float | tuple[float, numpy.ndarray][source]#

Computes the cost function for the given predictions.

Parameters:

  • r (np.ndarray) – The residual difference between the model prediction and the target. The dimensions of r are (len(target), len(domain_data)).

  • dy (dict[str, np.ndarray], optional) – The corresponding gradients dy/dx(t) for each output variable y with respect to each parameter x over the domain t. The dictionary keys are the parameter names and the arrays are of dimensions (len(target), len(domain_data)).

Returns:

If dy is not None, returns a tuple containing the cost (float) and the gradient with dimension (len(parameters)), otherwise returns only the cost.

Return type:

np.float64 or tuple[np.float64, np.ndarray[np.float64]]

evaluate(solution: pybop.simulators.solution.Solution | pybamm.Solution | pybop.simulators.failed_solution.FailedSolution, inputs: pybop.parameters.parameter.Inputs | None = None, calculate_sensitivities: bool = False) → float | tuple[float, numpy.ndarray][source]#

Computes the cost function for the given predictions.

Parameters:

  • solution (pybop.Solution | pybamm.Solution) – The simulation result.

  • inputs (Inputs, optional) – Input parameters (default: None).

  • calculate_sensitivities (bool) – Whether to also return the sensitivities (default: False).

Returns:

If the solution has sensitivities, returns a tuple containing the cost (float) and the gradient with dimension (len(parameters)), otherwise returns only the cost.

Return type:

np.float64 or tuple[np.float64, np.ndarray[np.float64]]

set_weighting(weighting: float | str | numpy.ndarray)[source]#
verify_prediction(solution: pybop.simulators.solution.Solution)[source]#

Verify that the prediction matches the target data.

Parameters:

solution (pybop.Solution | pybamm.Solution) – The simulation result.

Returns:

True if the prediction matches the target data, otherwise False.

Return type:

bool

class pybop.costs.error_measures.MeanAbsoluteError(dataset: pybop.processing.dataset.Dataset, target: str | list[str] = None, weighting: float | str | numpy.ndarray = None)[source]#

Bases: ErrorMeasure

Mean absolute error (MAE) cost function.

Computes the mean absolute error (MAE) between model predictions and target data. The MAE is a measure of the average magnitude of errors in a set of predictions, without considering their direction.

__call__(r: numpy.ndarray, dy: numpy.ndarray | None = None, inputs: pybop.parameters.parameter.Inputs | None = None) → float | tuple[float, numpy.ndarray][source]#

Computes the cost function for the given predictions.

Parameters:

  • r (np.ndarray) – The residual difference between the model prediction and the target. The dimensions of r are (len(target), len(domain_data)).

  • dy (dict[str, np.ndarray], optional) – The corresponding gradients dy/dx(t) for each output variable y with respect to each parameter x over the domain t. The dictionary keys are the parameter names and the arrays are of dimensions (len(target), len(domain_data)).

Returns:

If dy is not None, returns a tuple containing the cost (float) and the gradient with dimension (len(parameters)), otherwise returns only the cost.

Return type:

np.float64 or tuple[np.float64, np.ndarray[np.float64]]

class pybop.costs.error_measures.MeanSquaredError(dataset: pybop.processing.dataset.Dataset, target: str | list[str] = None, weighting: float | str | numpy.ndarray = None)[source]#

Bases: ErrorMeasure

Mean square error (MSE) cost function.

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

__call__(r: numpy.ndarray, dy: numpy.ndarray | None = None, inputs: pybop.parameters.parameter.Inputs | None = None) → float | tuple[float, numpy.ndarray][source]#

Computes the cost function for the given predictions.

Parameters:

  • r (np.ndarray) – The residual difference between the model prediction and the target. The dimensions of r are (len(target), len(domain_data)).

  • dy (dict[str, np.ndarray], optional) – The corresponding gradients dy/dx(t) for each output variable y with respect to each parameter x over the domain t. The dictionary keys are the parameter names and the arrays are of dimensions (len(target), len(domain_data)).

Returns:

If dy is not None, returns a tuple containing the cost (float) and the gradient with dimension (len(parameters)), otherwise returns only the cost.

Return type:

np.float64 or tuple[np.float64, np.ndarray[np.float64]]

class pybop.costs.error_measures.Minkowski(dataset: pybop.processing.dataset.Dataset, p: float = 2.0, target: str | list[str] = None, weighting: str | numpy.ndarray = None)[source]#

Bases: ErrorMeasure

The Minkowski distance is a generalisation of several distance metrics, including the Euclidean and Manhattan distances. It is defined as:

\[L_p(x, y) = ( \sum_i |x_i - y_i|^p )^(1/p)\]

where p > 0 is the order of the Minkowski distance. For p ≥ 1, the Minkowski distance is a metric. For 0 < p < 1, it is not a metric, as it does not satisfy the triangle inequality, although a metric can be obtained by removing the (1/p) exponent.

Special cases:

  • p = 1: Manhattan distance

  • p = 2: Euclidean distance

  • p → ∞: Chebyshev distance (not implemented as yet)

This class implements the Minkowski distance as a cost function for optimisation problems, allowing for flexible distance-based optimisation across various problem domains.

Additional Attributes#

pfloat, optional

The order of the Minkowski distance.

__call__(r: numpy.ndarray, dy: numpy.ndarray | None = None, inputs: pybop.parameters.parameter.Inputs | None = None) → float | tuple[float, numpy.ndarray][source]#

Computes the cost function for the given predictions.

Parameters:

  • r (np.ndarray) – The residual difference between the model prediction and the target. The dimensions of r are (len(target), len(domain_data)).

  • dy (dict[str, np.ndarray], optional) – The corresponding gradients dy/dx(t) for each output variable y with respect to each parameter x over the domain t. The dictionary keys are the parameter names and the arrays are of dimensions (len(target), len(domain_data)).

Returns:

If dy is not None, returns a tuple containing the cost (float) and the gradient with dimension (len(parameters)), otherwise returns only the cost.

Return type:

np.float64 or tuple[np.float64, np.ndarray[np.float64]]

property __name__#
p#
class pybop.costs.error_measures.RootMeanSquaredError(dataset: pybop.processing.dataset.Dataset, target: str | list[str] = None, weighting: float | str | numpy.ndarray = None)[source]#

Bases: ErrorMeasure

Root mean square error (RMSE) 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.

__call__(r: numpy.ndarray, dy: numpy.ndarray | None = None, inputs: pybop.parameters.parameter.Inputs | None = None) → float | tuple[float, numpy.ndarray][source]#

Computes the cost function for the given predictions.

Parameters:

  • r (np.ndarray) – The residual difference between the model prediction and the target. The dimensions of r are (len(target), len(domain_data)).

  • dy (dict[str, np.ndarray], optional) – The corresponding gradients dy/dx(t) for each output variable y with respect to each parameter x over the domain t. The dictionary keys are the parameter names and the arrays are of dimensions (len(target), len(domain_data)).

Returns:

If dy is not None, returns a tuple containing the cost (float) and the gradient with dimension (len(parameters)), otherwise returns only the cost.

Return type:

np.float64 or tuple[np.float64, np.ndarray[np.float64]]

class pybop.costs.error_measures.SumOfPower(dataset: pybop.processing.dataset.Dataset, p: float = 2.0, target: str | list[str] = None, weighting: str | numpy.ndarray = None)[source]#

Bases: ErrorMeasure

The Sum of Power [1] is a generalised cost function based on the p-th power of absolute differences between two vectors. It is defined as:

\[C_p(x, y) = \sum_i |x_i - y_i|^p\]

where p ≥ 0 is the power order.

This class implements the Sum of Power as a cost function for optimisation problems, allowing for flexible power-based optimisation across various problem domains.

Special cases:

  • p = 1: Sum of Absolute Differences

  • p = 2: Sum of Squared Differences

  • p → ∞: Maximum Absolute Difference

Note that this is not normalised, unlike distance metrics. To get a distance metric, you would need to take the p-th root of the result.

[1]: https://mathworld.wolfram.com/PowerSum.html

Additional Attributes#

pfloat, optional

The power order for Sum of Power.

__call__(r: numpy.ndarray, dy: numpy.ndarray | None = None, inputs: pybop.parameters.parameter.Inputs | None = None) → float | tuple[float, numpy.ndarray][source]#

Computes the cost function for the given predictions.

Parameters:

  • r (np.ndarray) – The residual difference between the model prediction and the target. The dimensions of r are (len(target), len(domain_data)).

  • dy (dict[str, np.ndarray], optional) – The corresponding gradients dy/dx(t) for each output variable y with respect to each parameter x over the domain t. The dictionary keys are the parameter names and the arrays are of dimensions (len(target), len(domain_data)).

Returns:

If dy is not None, returns a tuple containing the cost (float) and the gradient with dimension (len(parameters)), otherwise returns only the cost.

Return type:

np.float64 or tuple[np.float64, np.ndarray[np.float64]]

__name__()#
p#
class pybop.costs.error_measures.SumSquaredError(dataset: pybop.processing.dataset.Dataset, target: str | list[str] = None, weighting: float | str | numpy.ndarray = None)[source]#

Bases: ErrorMeasure

Sum of squared error (SSE) 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.

__call__(r: numpy.ndarray, dy: numpy.ndarray | None = None, inputs: pybop.parameters.parameter.Inputs | None = None) → float | tuple[float, numpy.ndarray][source]#

Computes the cost function for the given predictions.

Parameters:

  • r (np.ndarray) – The residual difference between the model prediction and the target. The dimensions of r are (len(target), len(domain_data)).

  • dy (dict[str, np.ndarray], optional) – The corresponding gradients dy/dx(t) for each output variable y with respect to each parameter x over the domain t. The dictionary keys are the parameter names and the arrays are of dimensions (len(target), len(domain_data)).

Returns:

If dy is not None, returns a tuple containing the cost (float) and the gradient with dimension (len(parameters)), otherwise returns only the cost.

Return type:

np.float64 or tuple[np.float64, np.ndarray[np.float64]]