A 3x3 covariance matrix, backed by an Nx tensor.
Used to express uncertainty over a 3-vector quantity such as an accelerometer reading, an angular velocity, or a position. The matrix is mathematically expected to be symmetric and positive semi-definite; this module does not enforce those invariants on construction (zero matrices, in particular, are legitimate "unknown variance" placeholders and must remain constructible).
Unlike BB.Math.Vec3, BB.Math.Quaternion and BB.Math.Transform, this is
still tensor-backed. Those three are read and written on every sample, so
their Nx dispatch cost dominated; a covariance is constructed from a tensor
and handed back as one, and no driver in the ecosystem populates it per
reading. Holding it as anything else would add a conversion to both ends of
its only path.
Examples
iex> c = BB.Math.Covariance3.diagonal([0.01, 0.01, 0.02])
iex> BB.Math.Covariance3.get(c, 0, 0)
0.01Summary
Functions
Builds a diagonal covariance from a list of three variances or a
{3} tensor.
Wraps an existing {3, 3} tensor without validation. Convenience
alias for new/1 matching the convention used by BB.Math.Transform.
Reads a scalar element at row/column (i, j).
Returns the 3x3 identity matrix as a covariance.
Creates a covariance from a {3, 3} tensor.
Returns the underlying tensor.
Returns the zero covariance - all variances and correlations zero.
Types
@type t() :: %BB.Math.Covariance3{tensor: Nx.Tensor.t()}
Functions
@spec diagonal([number()] | Nx.Tensor.t()) :: t()
Builds a diagonal covariance from a list of three variances or a
{3} tensor.
Examples
iex> c = BB.Math.Covariance3.diagonal([0.1, 0.2, 0.3])
iex> {BB.Math.Covariance3.get(c, 0, 0), BB.Math.Covariance3.get(c, 1, 1), BB.Math.Covariance3.get(c, 2, 2)}
{0.1, 0.2, 0.3}@spec from_tensor(Nx.Tensor.t()) :: t()
Wraps an existing {3, 3} tensor without validation. Convenience
alias for new/1 matching the convention used by BB.Math.Transform.
Reads a scalar element at row/column (i, j).
Examples
iex> c = BB.Math.Covariance3.diagonal([0.5, 1.5, 2.5])
iex> BB.Math.Covariance3.get(c, 2, 2)
2.5@spec identity() :: t()
Returns the 3x3 identity matrix as a covariance.
Examples
iex> c = BB.Math.Covariance3.identity()
iex> {BB.Math.Covariance3.get(c, 0, 0), BB.Math.Covariance3.get(c, 0, 1)}
{1.0, 0.0}@spec new(Nx.Tensor.t()) :: t()
Creates a covariance from a {3, 3} tensor.
Examples
iex> tensor = Nx.tensor([[1.0, 0.0, 0.0], [0.0, 2.0, 0.0], [0.0, 0.0, 3.0]])
iex> c = BB.Math.Covariance3.new(tensor)
iex> BB.Math.Covariance3.get(c, 1, 1)
2.0@spec to_tensor(t()) :: Nx.Tensor.t()
Returns the underlying tensor.
@spec zero() :: t()
Returns the zero covariance - all variances and correlations zero.
Examples
iex> c = BB.Math.Covariance3.zero()
iex> BB.Math.Covariance3.get(c, 0, 0)
0.0