Skip to content

Class inertialsim::geometry::MatrixLieGroup

template <typename Derived, int GroupDimension, int AlgebraDimension>

ClassList > inertialsim > geometry > MatrixLieGroup

Abstract base class for matrix Lie groups. More...

  • #include <lie_group.h>

Inherited by the following classes: inertialsim::geometry::RigidTransformBase, inertialsim::geometry::RigidTransformBase, inertialsim::geometry::RigidTransformBase, inertialsim::geometry::RotationBase, inertialsim::geometry::RotationBase, inertialsim::geometry::VectorBase, inertialsim::geometry::VectorBase, inertialsim::geometry::VectorBase

Public Types

Type Name
typedef Eigen::Matrix< Scalar, AlgebraDimension, Eigen::Dynamic > AlgebraArray
Array of algebra elements.
typedef Eigen::Matrix< Scalar, AlgebraDimension, 1 > AlgebraElement
Algebra element type (vector).
typedef std::vector< GroupElement > GroupArray
Array of group elements.
typedef Eigen::Matrix< Scalar, GroupDimension, GroupDimension > GroupElement
Group element type (square matrix).
typedef Eigen::Matrix< Scalar, AlgebraDimension, AlgebraDimension > JacobianMatrix
Jacobian matrix (algebra to algebra).
typedef std::vector< JacobianMatrix > JacobianMatrixArray
Array of Jacobian matrices.

Public Functions

Type Name
Vector3D Apply (const Vector3D & vectors) const
Apply the group action to an array of vectors.
Derived Interpolate (const Timestamps & interp_time, Interpolator method=Interpolator::LINEAR) const
Interpolate at given times.
Derived Inverse () const
Invert an instance.
Derived Slice (int start, int end) const
Get a slice of elements.
AlgebraArray TimeDerivative (int order=1, int accuracy=4, const std::string & side="right") const
Compute time derivative using finite differences.
int num_elements () const
Number of elements stored in the instance.
Derived operator* (const Derived & rhs) const
Compose elements of the group.
Derived operator[] (int index) const
Get a single element by index.
const std::optional< Timestamps > & time () const
Time array corresponding to each element.
virtual ~MatrixLieGroup () = default

Public Static Functions

Type Name
Derived Compose (const std::vector< Derived > & instances)
Compose a sequence of instances (first to last).
Derived FromIdentity (int num_elements=1)
Create identity elements.
Derived FromRandom (int num_elements=1, std::optional< Eigen::numext::uint64_t > seed=std::nullopt)
Create random elements.

Protected Functions

Type Name
AlgebraArray AsAlgebra () const
Get the algebra elements.
GroupArray AsGroup () const
Get the group elements.
MatrixLieGroup (const std::optional< Timestamps > & time=std::nullopt)
Constructor.
int num_times () const

Protected Static Functions

Type Name
GroupElement Exp (const AlgebraElement & vector)
Exponential map from algebra to group.
Derived FromAlgebra (const AlgebraArray & elements, const std::optional< Timestamps > & time)
Create instance from algebra elements.
Derived FromGroup (const GroupArray & elements, const std::optional< Timestamps > & time)
Create instance from group elements.
JacobianMatrixArray Jacobian (const AlgebraArray & algebra, const std::string & side="left", bool inverse=false)
Calculate the Jacobian of the exponential map.
AlgebraElement Log (const GroupElement & element)
Logarithm map from group to algebra.

Detailed Description

Derived classes will inherit common Lie group operations such as composition, interpolation, etc.

See Reference [14], Reference [15], Reference [16], Reference [17], and Reference [18] for further details on Lie groups and their application to translations, rotations and rigid body motions.

Template parameters:

  • Derived The derived class type.
  • GroupDimension Dimension of the group matrix representation (e.g., 3 for SO(3) & T(3), 4 for SE(3)).
  • AlgebraDimension Dimension of the algebra representation (e.g., 3 for so(3) and t(4), 6 for se(3)).

Public Types Documentation

typedef AlgebraArray

Array of algebra elements. 

using inertialsim::geometry::MatrixLieGroup< Derived, GroupDimension, AlgebraDimension >::AlgebraArray =  Eigen::Matrix<Scalar, AlgebraDimension, Eigen::Dynamic>;

typedef AlgebraElement

Algebra element type (vector). 

using inertialsim::geometry::MatrixLieGroup< Derived, GroupDimension, AlgebraDimension >::AlgebraElement =  Eigen::Matrix<Scalar, AlgebraDimension, 1>;

typedef GroupArray

Array of group elements. 

using inertialsim::geometry::MatrixLieGroup< Derived, GroupDimension, AlgebraDimension >::GroupArray =  std::vector<GroupElement>;

typedef GroupElement

Group element type (square matrix). 

using inertialsim::geometry::MatrixLieGroup< Derived, GroupDimension, AlgebraDimension >::GroupElement =  Eigen::Matrix<Scalar, GroupDimension, GroupDimension>;

typedef JacobianMatrix

Jacobian matrix (algebra to algebra). 

using inertialsim::geometry::MatrixLieGroup< Derived, GroupDimension, AlgebraDimension >::JacobianMatrix =  Eigen::Matrix<Scalar, AlgebraDimension, AlgebraDimension>;

typedef JacobianMatrixArray

Array of Jacobian matrices. 

using inertialsim::geometry::MatrixLieGroup< Derived, GroupDimension, AlgebraDimension >::JacobianMatrixArray =  std::vector<JacobianMatrix>;

Public Functions Documentation

function Apply

Apply the group action to an array of vectors. 

inline Vector3D inertialsim::geometry::MatrixLieGroup::Apply (
    const  Vector3D & vectors
) const

Applies the action of the Lie group to the input vectors. For rotations, this rotates the vectors; for rigid transforms, this applies both rotation and translation. Supports broadcasting when the instance has a single element.

Parameters:

  • vectors Array of 3D vectors to transform.

Returns:

Array of transformed vectors.

Exception:

  • std::invalid_argument if dimensions are incompatible.

function Interpolate

Interpolate at given times. 

inline Derived inertialsim::geometry::MatrixLieGroup::Interpolate (
    const  Timestamps & interp_time,
    Interpolator method=Interpolator::LINEAR
) const

Interpolates group elements at the specified times using either linear or cubic interpolation on the Lie group manifold. The instance must have timestamps.

The time input can be any array of times or indices consistent with those used to construct the instance. Values outside the range of the original data will not be extrapolated but will return the end-points instead.

Example

An instance constructed with 2 elements at time indices [0, 1] can be interpolated for any set of values in [0, 1], e.g., [0.1, 0.73, 0.92, 1.0] including the end-points. Requests to interpolate (extrapolate) at [-0.5, 1.5] will return the end-point values at [0.0, 1.0] instead.

Cubic Spline Continuity

The CUBIC method uses a Hermite spline technique. The resulting interpolant will pass through each of the original data points with C1 continuity.

Parameters:

  • interp_time Times at which to interpolate. Must be unique and strictly increasing.
  • method Interpolation method: LINEAR or CUBIC.

Returns:

New instance with interpolated values at the specified times.

Exception:

  • std::invalid_argument if time is not set or method is invalid.

function Inverse

Invert an instance. 

inline Derived inertialsim::geometry::MatrixLieGroup::Inverse () const

Returns a new instance containing the inverse of each element in the current instance.

Returns:

New instance with inverted elements.

function Slice

Get a slice of elements. 

inline Derived inertialsim::geometry::MatrixLieGroup::Slice (
    int start,
    int end
) const

Returns a new instance containing elements from start (inclusive) to end (exclusive). If the instance has time values, the corresponding times are also included.

Parameters:

  • start Start index (inclusive).
  • end End index (exclusive).

Returns:

New instance containing the sliced elements.

Exception:

  • std::out_of_range if slice bounds are invalid.

function TimeDerivative

Compute time derivative using finite differences. 

inline AlgebraArray inertialsim::geometry::MatrixLieGroup::TimeDerivative (
    int order=1,
    int accuracy=4,
    const std::string & side="right"
) const

Calculates numerical derivatives with respect to time using finite differences. The instance must have at least two elements with timestamps.

Time derivatives on a Lie group have a common structure. The result is expressed in the Lie algebra (tangent space) at each time point.

Rigid motion groups

For rigid motion groups (e.g., SE(3) transforms with simultaneous rotation and translation components), the side = "left" and order > 1 input options may not produce physically meaningful results.

Parameters:

  • order Order of the derivative to calculate.
  • accuracy Desired accuracy of the finite difference approximation.
  • side One of "left" or "right". For rotation groups, left derivatives are expressed in the world/global frame and right derivatives are expressed in the body/sensor frame.

Returns:

Array of algebra derivatives.

Exception:

  • std::invalid_argument if timestamps are not set, fewer than 2 elements exist, or side is neither "left" nor "right".

function num_elements

Number of elements stored in the instance. 

inline int inertialsim::geometry::MatrixLieGroup::num_elements () const

Returns the total number of group elements stored. For instances with timestamps, this equals the number of time points.

Returns:

Number of elements.

function operator*

Compose elements of the group. 

inline Derived inertialsim::geometry::MatrixLieGroup::operator* (
    const  Derived & rhs
) const

Composes two instances of the group element-wise. Supports broadcasting: if either operand has size 1, it will be broadcast against all elements of the other operand. Times from both instances must be compatible (either both null, or equal within tolerance).

Parameters:

  • rhs Instance to compose with.

Returns:

New instance containing the composed elements.

Exception:

  • std::invalid_argument if group sizes are incompatible or times are inconsistent.

function operator[]

Get a single element by index. 

inline Derived inertialsim::geometry::MatrixLieGroup::operator[] (
    int index
) const

Returns a new instance containing only the element at the specified index. If the instance has time values, the corresponding time is also included.

Parameters:

  • index Index of the element to retrieve.

Returns:

New instance containing a single element.

Exception:

  • std::out_of_range if index is out of bounds.

function time

Time array corresponding to each element. 

inline const std::optional< Timestamps > & inertialsim::geometry::MatrixLieGroup::time () const

Returns the array of timestamps if set during construction, otherwise returns nullopt. When present, times are unique and strictly increasing.

Returns:

Optional time array.

function ~MatrixLieGroup

virtual inertialsim::geometry::MatrixLieGroup::~MatrixLieGroup () = default

Public Static Functions Documentation

function Compose

Compose a sequence of instances (first to last). 

static inline Derived inertialsim::geometry::MatrixLieGroup::Compose (
    const std::vector< Derived > & instances
)

Composes multiple instances of the group in order from first to last. All instances must have compatible dimensions and types.

Parameters:

  • instances Vector of instances to be composed.

Returns:

New instance containing the composed result.

Exception:

  • std::invalid_argument if instances is empty or dimensions are incompatible.

function FromIdentity

Create identity elements. 

static inline Derived inertialsim::geometry::MatrixLieGroup::FromIdentity (
    int num_elements=1
)

Returns an instance containing the specified number of identity elements of the group. For rotations, this is the identity rotation matrix; for translations, this is the zero translation vector.

Parameters:

  • num_elements Number of identity elements to create.

Returns:

Instance with identity elements.

function FromRandom

Create random elements. 

static inline Derived inertialsim::geometry::MatrixLieGroup::FromRandom (
    int num_elements=1,
    std::optional< Eigen::numext::uint64_t > seed=std::nullopt
)

Returns an instance containing the specified number of randomly generated elements of the group. The distribution depends on the derived class implementation.

Parameters:

  • num_elements Number of random elements to create.
  • seed Optional seed for the random number generator.

Returns:

Instance with random elements.

Protected Functions Documentation

function AsAlgebra

Get the algebra elements. 

inline AlgebraArray inertialsim::geometry::MatrixLieGroup::AsAlgebra () const

Converts the stored group elements to their Lie algebra representation by applying the logarithm map. The algebra elements are in the tangent space of the group.

Returns:

Array of algebra elements (AlgebraDimension x num_elements).

function AsGroup

Get the group elements. 

inline GroupArray inertialsim::geometry::MatrixLieGroup::AsGroup () const

Returns the array of group elements stored in this instance. For example, a Rotation instance returns rotation matrices.

Returns:

Array of group elements.

function MatrixLieGroup

Constructor. 

inline explicit inertialsim::geometry::MatrixLieGroup::MatrixLieGroup (
    const std::optional< Timestamps > & time=std::nullopt
)

Parameters:

  • time Optional time array. If provided, will be validated.

function num_times

inline int inertialsim::geometry::MatrixLieGroup::num_times () const

Protected Static Functions Documentation

function Exp

Exponential map from algebra to group. 

static inline GroupElement inertialsim::geometry::MatrixLieGroup::Exp (
    const  AlgebraElement & vector
)

Maps an element from the Lie algebra (tangent space) to the Lie group manifold.

Parameters:

  • vector Lie algebra element (e.g., rotation vector).

Returns:

Lie group element (e.g., rotation matrix).

function FromAlgebra

Create instance from algebra elements. 

static inline Derived inertialsim::geometry::MatrixLieGroup::FromAlgebra (
    const  AlgebraArray & elements,
    const std::optional< Timestamps > & time
)

Creates an instance of the derived class from an array of Lie algebra elements by applying the exponential map. The algebra elements are in the tangent space of the group.

Parameters:

  • elements Array of algebra elements (e.g., rotation vectors).
  • time Optional time array corresponding to each element.

Returns:

New instance of the derived class.

function FromGroup

Create instance from group elements. 

static inline Derived inertialsim::geometry::MatrixLieGroup::FromGroup (
    const  GroupArray & elements,
    const std::optional< Timestamps > & time
)

Creates an instance of the derived class from an array of Lie group elements. This is typically called internally after operations that produce group elements directly.

Parameters:

  • elements Array of group elements (e.g., rotation matrices).
  • time Optional time array corresponding to each element.

Returns:

New instance of the derived class.

function Jacobian

Calculate the Jacobian of the exponential map. 

static inline JacobianMatrixArray inertialsim::geometry::MatrixLieGroup::Jacobian (
    const  AlgebraArray & algebra,
    const std::string & side="left",
    bool inverse=false
)

Returns the first derivative of the exponential map with respect to the elements of the Lie algebra when composed on the specified side (left or right).

Parameters:

  • algebra Array of algebra elements.
  • side "left" for world frame, "right" for body frame.
  • inverse If true, compute the inverse Jacobian.

Returns:

Array of Jacobian matrices.

function Log

Logarithm map from group to algebra. 

static inline AlgebraElement inertialsim::geometry::MatrixLieGroup::Log (
    const  GroupElement & element
)

Maps an element from the Lie group manifold to the Lie algebra (tangent space).

Parameters:

  • element Lie group element (e.g., rotation matrix).

Returns:

Lie algebra element (e.g., rotation vector).

The documentation for this class was generated from the following file cpp/include/inertialsim/geometry/lie_group.h