FilterEx.Utils (filter_ex v0.2.1)

Summary

Functions

Creates a block diagonal matrix from a list of matrices using Nx.

Given a matrix Q, ordered assuming state space

Returns the Q matrix for the Discrete Constant White Noise Model. dim may be either 2, 3, or 4 dt is the time step, and sigma is the variance in the noise.

Flattens the input tensor into a 1D tensor using Nx.

ensure z is a (dim_z, 1) shaped vector

Get scalar number from a 1, 2, or 3 dimension tensor from zeroth index.

Convert scalar, list, 1d-tensor to a 2d tensor.

Functions

Link to this function

block_diag(matrices)

Creates a block diagonal matrix from a list of matrices using Nx.

Examples

iex> qQ = Nx.tensor([[1, 2], [3, 4]], type: :f32) ...> matrices = [qQ, qQ, qQ] # List of matrices to place on the diagonal ...> FilterEx.Utils.block_diag(matrices) Nx.tensor([ [1.0, 2.0, 0.0, 0.0, 0.0, 0.0], [3.0, 4.0, 0.0, 0.0, 0.0, 0.0], [0.0, 0.0, 1.0, 2.0, 0.0, 0.0], [0.0, 0.0, 3.0, 4.0, 0.0, 0.0], [0.0, 0.0, 0.0, 0.0, 1.0, 2.0], [0.0, 0.0, 0.0, 0.0, 3.0, 4.0] ], type: :f32)

Link to this function

order_by_derivative(qQ, dim, block_size)

Given a matrix Q, ordered assuming state space

  [x y z x' y' z' x'' y'' z''...]

return a reordered matrix assuming an ordering of

 [ x x' x'' y y' y'' z z' y'']

This works for any covariance matrix or state transition function

Parameters

Q : np.array, square

  The matrix to reorder

dim : int >= 1

 number of independent state variables. 3 for x, y, z

block_size : int >= 0

  Size of derivatives. Second derivative would be a block size of 3
  (x, x', x'')
Link to this function

q_discrete_white_noise(dim, opts)

Returns the Q matrix for the Discrete Constant White Noise Model. dim may be either 2, 3, or 4 dt is the time step, and sigma is the variance in the noise.

Q is computed as the G G^T variance, where G is the process noise per time step. In other words, G = [[.5dt^2][dt]]^T for the constant velocity model.

Parameters

dim : int (2, 3, or 4)

dimension for Q, where the final dimension is (dim x dim)

dt : float, default=1.0

time step in whatever units your filter is using for time. i.e. the
amount of time between innovations

var : float, default=1.0

variance in the noise

block_size : int >= 1

If your state variable contains more than one dimension, such as
a 3d constant velocity model [x x' y y' z z']^T, then Q must be
a block diagonal matrix.

order_by_dim : bool, default=True

Defines ordering of variables in the state vector. `True` orders
by keeping all derivatives of each dimensions)

[x x' x'' y y' y'']

whereas `False` interleaves the dimensions

[x y z x' y' z' x'' y'' z'']

Examples

iex> # constant velocity model in a 3D world with a 10 Hz update rate ...> FilterEx.Utils.q_discrete_white_noise(2, dt: 0.1, var: 1.0, block_size: 3) Nx.tensor([[0.000025, 0.0005 , 0.0 , 0.0 , 0.0 , 0.0 ],

       [0.0005  , 0.01    , 0.0      , 0.0      , 0.0      , 0.0      ],
       [0.0      , 0.0      , 0.000025, 0.0005  , 0.0      , 0.0      ],
       [0.0      , 0.0      , 0.0005  , 0.01    , 0.0      , 0.0      ],
       [0.0      , 0.0      , 0.0      , 0.0      , 0.000025, 0.0005  ],
       [0.0      , 0.0      , 0.0      , 0.0      , 0.0005  , 0.01    ]

], type: :f32)

iex> FilterEx.Utils.q_discrete_white_noise(2, dt: 0.1, var: 1.0, block_size: 3, order_by_dim: false) Nx.tensor([

[2.499999936844688e-5, 0.0, 0.0, 5.000000237487257e-4, 0.0, 0.0],
[0.0, 2.499999936844688e-5, 0.0, 0.0, 5.000000237487257e-4, 0.0],
[0.0, 0.0, 2.499999936844688e-5, 0.0, 0.0, 5.000000237487257e-4],
[5.000000237487257e-4, 0.0, 0.0, 0.009999999776482582, 0.0, 0.0],
[0.0, 5.000000237487257e-4, 0.0, 0.0, 0.009999999776482582, 0.0],
[0.0, 0.0, 5.000000237487257e-4, 0.0, 0.0, 0.009999999776482582]

], type: :f32)

References

Bar-Shalom. "Estimation with Applications To Tracking and Navigation". John Wiley & Sons, 2001. Page 274.

Flattens the input tensor into a 1D tensor using Nx.

Examples

iex> Nx.tensor([[1, 2, 3], [4, 5, 6]], type: :f32) |> FilterEx.Utils.ravel() Nx.tensor([1.0, 2.0, 3.0, 4.0, 5.0, 6.0], type: :f32)

Link to this function

reshape_z(z, dim_z, ndim)

ensure z is a (dim_z, 1) shaped vector

## Examples

iex> FilterEx.Utils.reshape_z(3.0, 1, 1)
Nx.tensor([ 3.0 ], names: [:x])

iex> FilterEx.Utils.reshape_z(3.0, 1, 2)
Nx.tensor([[ 3.0 ]], names: [:x, :y])

iex> FilterEx.Utils.reshape_z([3.0], 1, 1)
Nx.tensor([ 3.0 ], names: [:x])

iex> FilterEx.Utils.reshape_z([3.0], 1, 2)
Nx.tensor([[3.0]], names: [:x, :y])

iex> FilterEx.Utils.reshape_z([3.0,2.0], 2, 1)
Nx.tensor([3.0, 2.0], names: [:x])

iex> FilterEx.Utils.reshape_z([3.0,2.0], 2, 2)
Nx.tensor([[3.0], [2.0]], names: [:x, :y])

Get scalar number from a 1, 2, or 3 dimension tensor from zeroth index.

Link to this function

to_tensor_2d(value)

Convert scalar, list, 1d-tensor to a 2d tensor.

iex> 1.0 |> FilterEx.Utils.to_tensor_2d() Nx.tensor([[1.0]])

iex> [1.0, 2.0] |> FilterEx.Utils.to_tensor_2d() Nx.tensor([[1.0], [2.0]])

iex> [[1.0, 2.0], [3.0, 4.0]] |> FilterEx.Utils.to_tensor_2d() Nx.tensor([[1.0, 2.0], [3.0, 4.0]])

Link to this function

zeros(arg, def \\ 0.0)