epyt_control.signal_processing.state_estimation

epyt_control.signal_processing.state_estimation.kalman_filters

This module contains implementations of various Kalman filters.

class epyt_control.signal_processing.state_estimation.kalman_filters.ExtendedKalmanFilter(state_dim: int, obs_dim: int, init_state: ndarray, measurement_func: Callable[[ndarray], ndarray], measurement_func_grad: Callable[[ndarray], ndarray], state_transition_func: Callable[[ndarray], ndarray], state_transition_func_grad: Callable[[ndarray], ndarray], init_state_uncertainty_cov: ndarray | None = None, measurement_uncertainty_cov: ndarray | None = None, system_uncertainty_cov: ndarray | None = None)

Bases: KalmanFilterBase

Class implementing the extended multivariate Kalman filter.

Parameters:

• state_dim (int) – Dimensionality of states.

• obs_dim (int) – Dimensionality of observations.

• init_state (numpy.ndarray) – Initial state.

• measurement_func – Measurement function – i.e. a function for mapping a system state to an observation.

• measurement_func_grad – Gradient/Jacobian (w.r.t. a system state) of the measurement function.

• state_transition_func – State transition function – i.e. a function evolving a system state to the next time step.

• state_transition_func_grad – Gradient/Jacobian (w.r.t. a system state) of the state transition function.

• init_state_uncertainty_cov –

  Covariance matrix of the initial state uncertainty. If None, the identity matrix will be used.

  The default is None.

• measurement_uncertainty_cov –

  Covariance matrix of the measurement/observation uncertainty. If None, the identity matrix will be used.

  The default is None.

• system_uncertainty_cov –

  Covariance matrix of the system uncertainty. If None, the identity matrix will be used.

  The default is None.

property init_state_uncertainty_cov: ndarray

Returns the covariance matrix of the initial state uncertainty.

Returns:

Covariance matrix.

Return type:

numpy.ndarray

property measurement_func: Callable[[ndarray], ndarray]

Returns the measurement function – i.e. a function for mapping a system state to an observation.

Returns:

Measurement function.

Return type:

Callable[[numpy.ndarray], numpy.ndarray]

property measurement_func_grad: Callable[[ndarray], ndarray]

Returns the gradient/Jacobian (w.r.t. a system state) of the measurement function.

Returns:

Gradient/Jacobian of the the measurement function.

Return type:

Callable[[numpy.ndarray], numpy.ndarray]

property measurement_uncertainty_cov: ndarray

Returns the covariance matrix of the measurement/observation uncertainty.

Returns:

Covariance matrix.

Return type:

numpy.ndarray

reset() → None

Resets the filter to the initial state.

property state_transition_func: Callable[[ndarray], ndarray]

Returns the state transition function – i.e. a function evolving a system state to the next time step.

Returns:

State transition function.

Return type:

Callable[[numpy.ndarray], numpy.ndarray]

property state_transition_func_grad: Callable[[ndarray], ndarray]

Returns the gradient/Jacobian (w.r.t. a system state) of the state transition function.

Returns:

Gradient of the state transition function.

Return type:

Callable[[numpy.ndarray], numpy.ndarray]

step(observation: ndarray) → tuple[ndarray, ndarray]

Predicts the current state (incl. it’s uncertainty) based on a given current observation. Also, updates all other internal states of the Kalman filter.

Parameters:

observation – Current observation.

Returns:

Tuple of predicted system state and uncertainty covariance matrix.

Return type:

tuple[numpy.ndarray, numpy.ndarray]

property system_uncertainty_cov: ndarray

Returns the covariance matrix of the system uncertainty.

Returns:

Covariance matrix.

Return type:

numpy.ndarray

class epyt_control.signal_processing.state_estimation.kalman_filters.KalmanFilter(state_dim: int, obs_dim: int, init_state: ndarray, measurement_func: ndarray, state_transition_func: ndarray, init_state_uncertainty_cov: ndarray | None = None, measurement_uncertainty_cov: ndarray | None = None, system_uncertainty_cov: ndarray | None = None)

Bases: KalmanFilterBase

Class implementing the multivariate Kalman filter.

Parameters:

• state_dim (int) – Dimensionality of states.

• obs_dim (int) – Dimensionality of observations.

• init_state – Initial state.

• measurement_func – Measurement function – i.e. matrix that is converting a state into an observation.

• state_transition_func – State transition function – i.e. matrix moving from a given state to the next state.

• init_state_uncertainty_cov –

  Covariance matrix of the initial state uncertainty. If None, the identity matrix will be used.

  The default is None.

• measurement_uncertainty_cov –

  Covariance matrix of the measurement/observation uncertainty. If None, the identity matrix will be used.

  The default is None.

• system_uncertainty_cov –

  Covariance matrix of the system uncertainty. If None, the identity matrix will be used.

  The default is None.

property init_state_uncertainty_cov: ndarray

Returns the covariance matrix of the initial state uncertainty.

Returns:

Covariance matrix.

Return type:

numpy.ndarray

property measurement_func: ndarray

Returns the measurement function – i.e. matrix for converting a state into an observation.

Returns:

Measurement function/matrix.

Return type:

numpy.ndarray

property measurement_uncertainty_cov: ndarray

Returns the covariance matrix of the measurement/observation uncertainty.

Returns:

Covariance matrix.

Return type:

numpy.ndarray

reset() → None

Resets the filter to the initial state.

property state_transition_func: ndarray

Returns the state transition function – i.e. matrix for moving from a given state to the next state.

Returns:

State transition matrix.

Return type:

numpy.ndarray

step(observation: ndarray) → tuple[ndarray, ndarray]

Predicts the current state (incl. it’s uncertainty) based on a given current observation. Also, updates all other internal states of the Kalman filter.

Parameters:

observation – Current observation.

Returns:

Tuple of predicted system state and uncertainty covariance matrix.

Return type:

tuple[numpy.ndarray, numpy.ndarray]

property system_uncertainty_cov: ndarray

Returns the covariance matrix of the system uncertainty.

Returns:

Covariance matrix.

Return type:

numpy.ndarray

class epyt_control.signal_processing.state_estimation.kalman_filters.KalmanFilterBase(state_dim: int, obs_dim: int, init_state: ndarray)

Bases: ABC

Base class for Kalman filters.

Parameters:

• state_dim (int) – Dimensionality of states.

• obs_dim (int) – Dimensionality of observations.

• init_state – Initial state.

property init_state: ndarray

Returns the initial state.

Returns:

Initial state.

Return type:

numpy.ndarray

property obs_dim: int

Returns the dimensionality of observations.

Returns:

Dimensionality.

Return type:

int

reset() → None

Resets the filter to the initial state.

property state_dim: int

Returns the dimensionality of states.

Returns:

Dimensionality.

Return type:

int

abstract step(observation: ndarray) → tuple[ndarray, ndarray]

Predicts the current state (incl. it’s uncertainty) based on a given current observation. Also, updates all other internal states of the Kalman filter.

class epyt_control.signal_processing.state_estimation.kalman_filters.TimeVaryingExtendedKalmanFilter(state_dim: int, obs_dim: int, init_state: ndarray, get_state_transition_func: Callable[[int], Callable[[ndarray], ndarray]], get_state_transition_func_grad: Callable[[int], Callable[[ndarray], ndarray]], get_measurement_func_grad: Callable[[int], Callable[[ndarray], ndarray]], get_measurement_func: Callable[[int], Callable[[ndarray], ndarray]], **kwds)

Bases: ExtendedKalmanFilter

Implementing the timevarying extended multivariate Kalman filter – i.e. state transition and measurement functions may depend on time.

Parameters:

• state_dim (int) – Dimensionality of states.

• obs_dim (int) – Dimensionality of observations.

• init_state – Initial state.

• get_state_transition_func (Callable[[int], Callable[[numpy.ndarray], numpy.ndarray]]) – A function that maps time to the curresponding state transition function (a function evolving a given system state to the next time step).

• get_state_transition_func_grad (Callable[[int], Callable[[numpy.ndarray], numpy.ndarray]]) – A function that maps time to the curresponding function for computing the gradient/Jacobian (w.r.t. a system state) of the state transition function.

• get_measurement_func_grad (Callable[[int], Callable[[numpy.ndarray], numpy.ndarray]]) – A function that maps time to the curresponding function for computing the gradient/Jacobian (w.r.t. a system state) of the measurement function.

• get_measurement_func (Callable[[int], Callable[[numpy.ndarray], numpy.ndarray]]) – A function that maps time to the curresponding measurement function (a function for mapping a system state to an observation).

reset() → None

Resets the filter to the initial state.

step(observation: ndarray) → tuple[ndarray, ndarray]

Predicts the current state (incl. it’s uncertainty) based on a given current observation. Also, updates all other internal states of the Kalman filter.

Parameters:

observation – Current observation.

Returns:

Tuple of predicted system state and uncertainty covariance matrix.

Return type:

tuple[numpy.ndarray, numpy.ndarray]

class epyt_control.signal_processing.state_estimation.kalman_filters.TimeVaryingKalmanFilter(state_dim: int, obs_dim: int, init_state: ndarray, measurement_func: ndarray, state_transition_func: Callable[[int], ndarray], init_state_uncertainty_cov: ndarray | None = None, measurement_uncertainty_cov: Callable[[int], ndarray] | None = None, system_uncertainty_cov: Callable[[int], ndarray] | None = None)

Bases: KalmanFilter

Implementation of the time varying Kalman filter – i.e. transition matrix, system uncertainty, and measurement uncertainty depend on time.

Parameters:

• state_dim (int) – Dimensionality of states.

• obs_dim (int) – Dimensionality of observations.

• init_state – Initial state.

• measurement_func – Measurement function – i.e. matrix that is converting a state into an observation.

• state_transition_func – Function mapping time (integer) to the time dependent state transition function – i.e. matrix moving from a given state to the next state.

• init_state_uncertainty_cov –

  Covariance matrix of the initial state uncertainty. If None, the identity matrix will be used.

  The default is None.

• measurement_uncertainty_cov –

  Function mapping time (integer) to the time dependent covariance matrix of the measurement/observation uncertainty. If None, the identity matrix will be used in all time steps.

  The default is None.

• system_uncertainty_cov –

  Function mapping time (integer) to the time dependent covariance matrix of the system uncertainty. If None, the identity matrix will be used in all time steps.

  The default is None.

reset() → None

Resets the filter to the initial state.

step(observation: ndarray) → tuple[ndarray, ndarray]

Predicts the current state (incl. it’s uncertainty) based on a given current observation. Also, updates all other internal states of the Kalman filter.

Parameters:

observation – Current observation.

Returns:

Tuple of predicted system state and uncertainty covariance matrix.

Return type:

tuple[numpy.ndarray, numpy.ndarray]

epyt_control.signal_processing.state_estimation.smoothers

This module contains several smoothing methods for improving filters.

class epyt_control.signal_processing.state_estimation.smoothers.RauchTungStriebelSmoother(time_window_length: int, state_dim: int, obs_dim: int, init_state: ndarray, measurement_func: ndarray, state_transition_func: ndarray, init_state_uncertainty_cov: ndarray | None, measurement_uncertainty_cov: ndarray | None, system_uncertainty_cov: ndarray | None)

Bases: KalmanFilter

Implementation of the Rauch-Tung-Striebel Kalman filter smoother.

Parameters:

• time_window_length (int) – Length of the time window which is considered for smoothing.

• state_dim (int) – Dimensionality of states.

• obs_dim (int) – Dimensionality of observations.

• init_state – Initial state.

• measurement_func – Measurement function – i.e. matrix that is converting a state into an observation.

• state_transition_func – State transition function – i.e. matrix moving from a given state to the next state.

• init_state_uncertainty_cov –

  Covariance matrix of the initial state uncertainty. If None, the identity matrix will be used.

  The default is None.

• measurement_uncertainty_cov –

  Covariance matrix of the measurement/observation uncertainty. If None, the identity matrix will be used.

  The default is None.

• system_uncertainty_cov –

  Covariance matrix of the system uncertainty. If None, the identity matrix will be used.

  The default is None.

step(observation: ndarray) → tuple[list[ndarray], list[ndarray]]

Predicts the current state (incl. it’s uncertainty) based on a given time window of observations. Also, updates all other internal states of the Kalman filter.

Parameters:

observation – Time window of observations.

Returns:

Lists of predicted system states and uncertainty covariance matrices.

Return type:

tuple[list[numpy.ndarray], list[numpy.ndarray]]

property time_window_length: int

Returns the length of the time window.

Returns:

Time window length.

Return type:

int

class epyt_control.signal_processing.state_estimation.smoothers.TimeVaryingRauchTungStriebelSmoother(time_window_length: int, state_dim: int, obs_dim: int, init_state: ndarray, measurement_func: ndarray, state_transition_func: Callable[[int], ndarray], init_state_uncertainty_cov: ndarray | None, measurement_uncertainty_cov: Callable[[int], ndarray] | None, system_uncertainty_cov: Callable[[int], ndarray] | None)

Bases: TimeVaryingKalmanFilter

Implementation of the time varying Rauch-Tung-Striebel Kalman filter smoother.

Parameters:

• time_window_length (int) – Length of the time window which is considered for smoothing.

• state_dim (int) – Dimensionality of states.

• obs_dim (int) – Dimensionality of observations.

• init_state – Initial state.

• measurement_func – Measurement function – i.e. matrix that is converting a state into an observation.

• state_transition_func – Function mapping time (integer) to the time dependent state transition function – i.e. matrix moving from a given state to the next state.

• init_state_uncertainty_cov –

  Covariance matrix of the initial state uncertainty. If None, the identity matrix will be used.

  The default is None.

• measurement_uncertainty_cov –

  Function mapping time (integer) to the time dependent covariance matrix of the measurement/observation uncertainty. If None, the identity matrix will be used in all time steps.

  The default is None.

• system_uncertainty_cov –

  Function mapping time (integer) to the time dependent covariance matrix of the system uncertainty. If None, the identity matrix will be used in all time steps.

  The default is None.

step(observation: ndarray) → tuple[list[ndarray], list[ndarray]]

Predicts the current state (incl. it’s uncertainty) based on a given time window of observations. Also, updates all other internal states of the Kalman filter.

Parameters:

observation – Time window of observations.

Returns:

List of predicted system states and uncertainty covariance matrices.

Return type:

tuple[list[numpy.ndarray], list[numpy.ndarray]]

property time_window_length: int

Returns the length of the time window.

Returns:

Time window length.

Return type:

int