FilterEx.Utils (filter_ex v0.2.3)
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
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)
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'')
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.
ravel(tensor)
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)
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])
to_scalar(mat)
Get scalar number from a 1, 2, or 3 dimension tensor from zeroth index.
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]])