pybop.observers.unscented_kalman

Classes

SigmaPoint	A sigma point is a point in the state space that is used to estimate the mean and covariance of a random variable.
SquareRootUKF	van der Menve, R., & Wan, E. A. (2001). THE SQUARE-ROOT UNSCENTED KALMAN FILTER FOR STATE AND PARAMETER-ESTIMATION.
UnscentedKalmanFilterObserver	An observer using the unscented Kalman filter. This is a wrapper class for PyBOP, see class SquareRootUKF for more details on the method.

Module Contents

class pybop.observers.unscented_kalman.SigmaPoint

A sigma point is a point in the state space that is used to estimate the mean and covariance of a random variable.

w_c: float

w_m: float

x: numpy.ndarray

class pybop.observers.unscented_kalman.SquareRootUKF(x0: numpy.ndarray, P0: numpy.ndarray, Rp: numpy.ndarray, Rm: numpy.ndarray, f: callable, h: callable)

van der Menve, R., & Wan, E. A. (2001). THE SQUARE-ROOT UNSCENTED KALMAN FILTER FOR STATE AND PARAMETER-ESTIMATION. https://doi.org/10.1109/ICASSP.2001.940586

We implement a square root unscented Kalman filter (UKF) with additive process and measurement noise.

The square root UKF is a variant of the UKF that is more numerically stable and has better performance.

Parameters:

• x0 (np.ndarray) – The initial state vector

• P0 (np.ndarray) – The initial covariance matrix

• Rp (np.ndarray) – The covariance matrix of the process noise

• Rm (np.ndarray) – The covariance matrix of the measurement noise

• f (callable) – The state transition function

• h (callable) – The measurement function

static cholupdate(R: numpy.ndarray, x: numpy.ndarray, w: float) → numpy.ndarray

Updates the Cholesky decomposition of a matrix (see modusdatascience/choldate)

Note: will be in scipy soon so replace with this: scipy/scipy#16499

TODO: need to replace with something more low-level

Parameters:

• R (np.ndarray) – The Cholesky decomposition of the matrix

• x (np.ndarray) – The vector to add to the matrix

• w (float) – The weight of the vector

Returns:

The updated Cholesky decomposition

Return type:

np.ndarray

static filtered_cholupdate(R: numpy.ndarray, x: numpy.ndarray, w: float, states: numpy.ndarray) → numpy.ndarray

static gen_sigma_points(x: numpy.ndarray, S: numpy.ndarray, alpha: float, beta: float, states: numpy.ndarray) → tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

Generates 2L+1 sigma points for the unscented transform, where L is the number of states.

Parameters:

• x (np.ndarray) – The state vector

• S (np.ndarray) – The square root of the covariance matrix

• alpha (float) – The spread of the sigma points. Typically 1e-4 < alpha < 1

• beta (float) – The prior knowledge of the distribution. Typically 2 for a Gaussian distribution

• states (np.ndarray) – array of indices of states to use for the sigma points

Returns:

• list[np.ndarray] – The sigma points

• list[float] – The weights of the sigma points

• list[float] – The weights of the covariance of the sigma points

hypot(x: float, sign: float) → float

reset(x: numpy.ndarray, S: numpy.ndarray) → None

step(y: numpy.ndarray) → float

Steps the filter forward one step using a measurement. Returns the log likelihood of the measurement.

Parameters:

y (np.ndarray) – The measurement vector

Returns:

The log likelihood of the measurement

Return type:

float

static unscented_transform(sigma_points: numpy.ndarray, w_m: numpy.ndarray, w_c: numpy.ndarray, sqrtR: numpy.ndarray, states: numpy.ndarray | None = None) → tuple[numpy.ndarray, numpy.ndarray]

Performs the unscented transform

Parameters:

• sigma_points (list[SigmaPoint]) – The sigma points

• sqrtR (np.ndarray) – The square root of the covariance matrix

• states (np.ndarray) – array of indices of states to use for the transform

Returns:

The mean and square-root covariance of the sigma points

Return type:

Tuple[np.ndarray, np.ndarray]

S

alpha = 0.001

beta = 2

bool_mask = ()

f

h

sqrtRm

sqrtRp

states

x

class pybop.observers.unscented_kalman.UnscentedKalmanFilterObserver(parameters: list[pybop.parameters.parameter.Parameter], model: pybop.models.base_model.BaseModel, sigma0: Covariance | float, process: Covariance | float, measure: Covariance | float, dataset: pybop._dataset.Dataset | None = None, check_model: bool = True, signal: list[str] | None = None, additional_variables: list[str] | None = None, initial_state: float | None = None)

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 (Parameters) – The parameters for 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.

• initial_state (dict, optional) – A valid initial state, e.g. the initial open-circuit voltage (default: None).

get_current_covariance() → Covariance

Returns the current covariance of the model.

observe(time: float, value: numpy.ndarray) → float

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

Covariance

_process

_sigma0

_ukf