R/RcppExports.R

In eddelbuettel/rcppkalman: 'RcppArmadillo'-Based Kalman Filtering

# This file was generated by Rcpp::compileAttributes
# Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393

#' This function computes the exponential of a matrix.
#'
#' This functions calls the \code{expm} function from the eponymous package 
#' \pkg{expm}. This is implemented via a registered function call, and does
#' not required explicit linking at the C level. However, the \pkg{expm} package
#' is imported in order to access its registered function at the C level.
#' 
#' As the documentation of package \pkg{expm} states, the underlying implementation
#' borrows from the \pkg{Matrix} package which itself takes it from GNU Octave.
#' @title Compute the exponential of a matrix
#' @param x An numeric matrix
#' @return A numeric matrix
#' @author Dirk Eddelbuettel
#' @seealso The \pkg{expm} package and its documentation.
#' @examples 
#' 
#' ## example is from the vignette in package expm
#' M <- matrix(c(4, 1, 1, 2, 4, 1, 0, 1, 4), 3, 3)
#' 
#' ## expected output
#' expM <- matrix(c(147.8666, 127.7811, 127.7811, 183.7651, 183.7651,
#'                  163.6796, 71.79703, 91.88257, 111.96811), 3, 3)
#' 
#' ## we only have the expected result to about six digits
#' all.equal(expm(M), expM, tolerance=1.0e-6)
expm <- function(x) {
    .Call('RcppKalman_expm', PACKAGE = 'RcppKalman', x)
}

#' This function performs the Kalman Filter prediction step
#' 
#' @title Kalman Filter Prediction step
#' @param x An N x 1 mean state estimate of previous step
#' @param P An N x N state covariance of previous step
#' @param A (Optional, default idendity) transition matrix of the discrete model 
#' @param Q (Optional, default zero) process noise of discrete model
#' @param B (Optional, default idendity) input effect matrix  
#' @param u (Optional, default empty) constant input
#' @return A list with two elements
#' \describe{
#'   \item{X}{the predicted state mean, and}
#'   \item{P}{the predicted state covariance.}
#' }   
#' @seealso \link{kfUpdate}, \link{ltiDisc} and 
#' the documentation for the EKF/UKF toolbox at
#' \url{http://becs.aalto.fi/en/research/bayes/ekfukf}
#' @author The EKF/UKF Toolbox was written by Simo Särkkä, Jouni Hartikainen,
#' and Arno Solin.
#'
#' Dirk Eddelbuettel is porting this package to R and C++, and maintaing it.
kfPredict <- function(x, P, A, Q, B, u) {
    .Call('RcppKalman_kfPredict', PACKAGE = 'RcppKalman', x, P, A, Q, B, u)
}

#' This function performs the Kalman Filter measurement update step
#' 
#' This functions performs the Kalman Filter measurement update step.
#' @title Kalman Filter measurement update step
#' @param x An N x 1 mean state estimate after prediction step
#' @param P An N x N state covariance after prediction step
#' @param y A D x 1 measurement vector.
#' @param H Measurement matrix.
#' @param R Measurement noise covariance.
#' @return A list with elements
#' \describe{
#'   \item{X}{the update state mean,}
#'   \item{P}{the update state covariance,}
#'   \item{K}{the computed Kalman gain,}
#'   \item{IM}{the mean of the predictive distribution of Y, and}
#'   \item{IS}{the covariance of the predictive distribution of Y}
#' }
#' @seealso \link{kfPredict} and 
#' the documentation for the EKF/UKF toolbox at
#' \url{http://becs.aalto.fi/en/research/bayes/ekfukf}
#' @author The EKF/UKF Toolbox was written by Simo Särkkä, Jouni Hartikainen,
#' and Arno Solin.
#'
#' Dirk Eddelbuettel is porting this package to R and C++, and maintaing it.
kfUpdate <- function(x, P, y, H, R) {
    .Call('RcppKalman_kfUpdate', PACKAGE = 'RcppKalman', x, P, y, H, R)
}

#' Discretize Linear Time-Invariant ODE with Gaussian Noise
#'
#' This function discretizes the linear time-invariant (LTI)
#' ordinary differential equation (ODE).
#' @title Discretize Linear Time-Invariant ODE
#' @param F An N x N feedback matrix
#' @param L (Optional, default idendity) N x L noise effect matrix
#' @param Q (Optionalm default zeros) L x L diagonal spectral density
#' @param dt (Option, default one) time step
#' @return A list with elements
#' \describe{
#'   \item{A}{the transition matrix, and}
#'   \item{Q}{the discrete process covariance}
#' }
#' @seealso The documentation for the EKF/UKF toolbox at
#' \url{http://becs.aalto.fi/en/research/bayes/ekfukf}
#' @author The EKF/UKF Toolbox was written by Simo Särkkä, Jouni Hartikainen,
#' and Arno Solin.
#'
#' Dirk Eddelbuettel is porting this package to R and C++, and maintaing it.
ltiDisc <- function(F, L, Q, dt) {
    .Call('RcppKalman_ltiDisc', PACKAGE = 'RcppKalman', F, L, Q, dt)
}

#' This function computes the Rauch-Tung-Striebel smoother.
#'
#' This function implements the Rauch-Tung-Striebel smoother algorithm which
#' calculate a \dQuote{smoothed} sequence from the given Kalman filter output 
#' sequence by conditioning all steps to all measurements.
#'
#' @title Rauch-Tung-Striebel smoother
#' @param M An N x K matrix of K mean estimates from the Kalman Filter
#' @param P An N x N x K cube length K with N x N state covariances matrices 
#' from the Kalman Filter
#' @param A An N x N state transition matrix (or in the more general case a
#' list of K such matrices; not yet implemented)
#' @param Q An N x N noise covariance matrix  (or in the more general case a
#' list of K such matrices; not yet implemented)
#' @return A list with three elements
#' \describe{
#'   \item{SM}{the smoothed mean sequence,}
#'   \item{SP}{the smooted state covariance sequence,and }
#'   \item{D}{the smoothed gain sequence.}
#' }
#' @seealso \link{kfPredict}, \link{kfUpdate}, and 
#' the documentation for the EKF/UKF toolbox at
#' \url{http://becs.aalto.fi/en/research/bayes/ekfukf}
#' @author The EKF/UKF Toolbox was written by Simo Särkkä, Jouni Hartikainen,
#' and Arno Solin.
#'
#' Dirk Eddelbuettel is porting this package to R and C++, and maintaing it.
rtsSmoother <- function(M, P, A, Q) {
    .Call('RcppKalman_rtsSmoother', PACKAGE = 'RcppKalman', M, P, A, Q)
}

#' This function computes the \sQuote{Two filter-based} Smoother
#'
#' This function implements the two filter linear smoother which calculates
#' a \dQuote{smoothed} sequence from the given Kalman filter output sequence
#' by conditioning all steps to all measurements.
#'
#' @title Two-filter Smoother
#' @param M An N x K matrix of K mean estimates from Kalman filter
#' @param P An N x N x K matrix of K state covariances from Kalman Filter
#' @param Y A D x K matrix of K measurement sequences
#' @param A A N x N state transition matrix.
#' @param Q A N x N process noise covariance matrix.
#' @param H A D x N measurement matrix.
#' @param R A D x D measurement noise covariance.
#' @param useinf An optional boolean variable indicating if information
#' filter should be used (with default \code{true}). 
#' @return A list with two elements
#' \describe{
#'   \item{M}{the smoothed state mean sequence, and}
#'   \item{P}{the smoothes state covariance sequence.}
#' }   
#' @seealso \link{kfPredict}, \link{kfUpdate}, and 
#' the documentation for the EKF/UKF toolbox at
#' \url{http://becs.aalto.fi/en/research/bayes/ekfukf}
#' @author The EKF/UKF Toolbox was written by Simo Särkkä, Jouni Hartikainen,
#' and Arno Solin.
#'
#' Dirk Eddelbuettel is porting this package to R and C++, and maintaing it.
tfSmoother <- function(M, P, Y, A, Q, H, R, useinf) {
    .Call('RcppKalman_tfSmoother', PACKAGE = 'RcppKalman', M, P, Y, A, Q, H, R, useinf)
}