NAG C Library Function Document

nag_kalman_sqrt_filt_info_var (g13ecc)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

1:    $\mathbf{n}$ – IntegerInput

On entry: the actual state dimension, $n$, i.e., the order of the matrices $S_i$ and $A_i^{-1}$.

Constraint: $\mathbf{n}\ge 1$.

2:    $\mathbf{m}$ – IntegerInput

On entry: the actual input dimension, $m$, i.e., the order of the matrix $Q_i^{-1/2}$.

Constraint: $\mathbf{m}\ge 1$.

3:    $\mathbf{p}$ – IntegerInput

On entry: the actual output dimension, $p$, i.e., the order of the matrix $R_{i+1}^{-1/2}$.

Constraint: $\mathbf{p}\ge 1$.

4:    $\mathbf{inp\_ab}$ – Nag_ab_inputInput

On entry: indicates how the matrix $B_i$ is to be passed to the function.

$\mathbf{inp\_ab}=\mathrm{Nag\_ab\_prod}$

Array b must contain the product $A_i^{-1}{B}_i$.

$\mathbf{inp\_ab}=\mathrm{Nag\_ab\_sep}$

Then array b must contain $B_i$.

5:    $\mathbf{t}\left[\mathbf{n}\times \mathbf{tdt}\right]$ – doubleInput/Output

Note: the $\left(i,j\right)$th element of the matrix $T$ is stored in $\mathbf{t}\left[\left(i-1\right)\times \mathbf{tdt}+j-1\right]$.

On entry: the leading $n$ by $n$ upper triangular part of this array must contain $S_i^{-1}$ the square root of the inverse of the state covariance matrix $P_{i\mid i}$.

On exit: the leading $n$ by $n$ upper triangular part of this array contains $S_{i+1}^{-1}$, the square root of the inverse of the of the state covariance matrix $P_{i+1\mid i+1}$.

6:    $\mathbf{tdt}$ – IntegerInput

On entry: the stride separating matrix column elements in the array t.

Constraint: $\mathbf{tdt}\ge \mathbf{n}$.

7:    $\mathbf{ainv}\left[\mathbf{n}\times \mathbf{tda}\right]$ – const doubleInput

Note: the $\left(i,j\right)$th element of the matrix is stored in $\mathbf{ainv}\left[\left(i-1\right)\times \mathbf{tda}+j-1\right]$.

On entry: the leading $n$ by $n$ part of this array must contain $A_i^{-1}$ the inverse of the state transition matrix.

8:    $\mathbf{tda}$ – IntegerInput

On entry: the stride separating matrix column elements in the array ainv.

Constraint: $\mathbf{tda}\ge \mathbf{n}$.

9:    $\mathbf{b}\left[\mathbf{n}\times \mathbf{tdb}\right]$ – const doubleInput

Note: the $\left(i,j\right)$th element of the matrix $B$ is stored in $\mathbf{b}\left[\left(i-1\right)\times \mathbf{tdb}+j-1\right]$.

On entry: the leading $n$ by $m$ part of this array must contain $B_i$ (if $\mathbf{inp\_ab}=\mathrm{Nag\_ab\_sep}$) or its product with $A_i^{-1}$ (if $\mathbf{inp\_ab}=\mathrm{Nag\_ab\_prod}$).

10:  $\mathbf{tdb}$ – IntegerInput

On entry: the stride separating matrix column elements in the array b.

Constraint: $\mathbf{tdb}\ge \mathbf{m}$.

11:  $\mathbf{rinv}\left[\mathbf{p}\times \mathbf{tdr}\right]$ – const doubleInput

Note: the $\left(i,j\right)$th element of the matrix is stored in $\mathbf{rinv}\left[\left(i-1\right)\times \mathbf{tdr}+j-1\right]$.

On entry: if the measurement noise covariance matrix is to be supplied separately from the output weight matrix, then the leading $p$ by $p$ upper triangular part of this array must contain $R_{i+1}^{-1/2}$, the right Cholesky factor of the inverse of the measurement noise covariance matrix. If this information is not to be input separately from the output weight matrix (see below) then the array rinv must be set to NULL.

12:  $\mathbf{tdr}$ – IntegerInput

On entry: the stride separating matrix column elements in the array rinv.

Constraint: $\mathbf{tdr}\ge \mathbf{p}$ if rinv is defined.

13:  $\mathbf{c}\left[\mathbf{p}\times \mathbf{tdc}\right]$ – const doubleInput

Note: the $\left(i,j\right)$th element of the matrix $C$ is stored in $\mathbf{c}\left[\left(i-1\right)\times \mathbf{tdc}+j-1\right]$.

On entry: if the array rinv has been set to NULL then the leading $p$ by $n$ part of this array must contain $C_{i+1}$, the output weight matrix (or its product with $R_{i+1}^{-1/2}$) of the discrete system at instant $i+1$.

14:  $\mathbf{tdc}$ – IntegerInput

On entry: the stride separating matrix column elements in the array c.

Constraint: $\mathbf{tdc}\ge \mathbf{n}$.

15:  $\mathbf{qinv}\left[\mathbf{m}\times \mathbf{tdq}\right]$ – const doubleInput

Note: the $\left(i,j\right)$th element of the matrix is stored in $\mathbf{qinv}\left[\left(i-1\right)\times \mathbf{tdq}+j-1\right]$.

On entry: the leading $m$ by $m$ upper triangular part of this array must contain $Q_i^{-1/2}$ the right Cholesky factor of the inverse of the process noise covariance matrix.

16:  $\mathbf{tdq}$ – IntegerInput

On entry: the stride separating matrix column elements in the array qinv.

Constraint: $\mathbf{tdq}\ge \mathbf{m}$.

17:  $\mathbf{x}\left[\mathbf{n}\right]$ – doubleInput/Output

On entry: this array must contain the estimated state ${\hat{X}}_{i\mid i}$

On exit: the estimated state ${\hat{X}}_{i+1\mid i+1}$.

18:  $\mathbf{rinvy}\left[\mathbf{p}\right]$ – const doubleInput

On entry: this array must contain $R_{i+1}^{-1/2}{Y}_{i+1}$, the product of the upper triangular matrix $R_{i+1}^{-1/2}$ and the measured output $Y_{i+1}$.

19:  $\mathbf{z}\left[\mathbf{m}\right]$ – const doubleInput

On entry: this array must contain ${\stackrel{-}{w}}_i$, the mean value of the state process noise.

20:  $\mathbf{tol}$ – doubleInput

On entry: tol is used to test for near singularity of the matrix $S_{i+1}^{-1}$. If you set tol to be less than $n^2\times \epsilon$ then the tolerance is taken as $n^2\times \epsilon$, where $\epsilon$ is the machine precision.

21:  $\mathbf{fail}$ – NagError *Input/Output

The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

6

Error Indicators and Warnings

NE_2_INT_ARG_LT

On entry, $\mathbf{tda}=〈\mathit{\text{value}}〉$ while $\mathbf{n}=〈\mathit{\text{value}}〉$. These arguments must satisfy $\mathbf{tda}\ge \mathbf{n}$.

On entry, $\mathbf{tdb}=〈\mathit{\text{value}}〉$ while $\mathbf{m}=〈\mathit{\text{value}}〉$. These arguments must satisfy $\mathbf{tdb}\ge \mathbf{m}$.

On entry, $\mathbf{tdc}=〈\mathit{\text{value}}〉$ while $\mathbf{n}=〈\mathit{\text{value}}〉$. These arguments must satisfy $\mathbf{tdc}\ge \mathbf{n}$.

On entry, $\mathbf{tdq}=〈\mathit{\text{value}}〉$ while $\mathbf{m}=〈\mathit{\text{value}}〉$. These arguments must satisfy $\mathbf{tdq}\ge \mathbf{m}$.

On entry, $\mathbf{tdr}=〈\mathit{\text{value}}〉$ while $\mathbf{p}=〈\mathit{\text{value}}〉$. These arguments must satisfy $\mathbf{tdr}\ge \mathbf{p}$.

On entry, $\mathbf{tdt}=〈\mathit{\text{value}}〉$ while $\mathbf{n}=〈\mathit{\text{value}}〉$. These arguments must satisfy $\mathbf{tdt}\ge \mathbf{n}$.

NE_ALLOC_FAIL

Dynamic memory allocation failed.

NE_BAD_PARAM

On entry, argument inp_ab had an illegal value.

NE_INT_ARG_LT

On entry, $\mathbf{m}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{m}\ge 1$.

On entry, $\mathbf{n}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{n}\ge 1$.

On entry, $\mathbf{p}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{p}\ge 1$.

NE_MAT_SINGULAR

The matrix inverse(S) is singular.

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

Program Text (g13ecce.c)

10.2

Program Data

Program Data (g13ecce.d)

10.3

Program Results

Program Results (g13ecce.r)