Structures and traits for rotation mathematics ( SO(3) group )

[ChristopherRabotin]

High level description

Rotations are a key component of attitude and orientation parameters. At first, ANISE only supports Direct Cosine Matrix math. This is a redundant representation of rotations and therefore not an optimal one.

The purpose of this issue is to design and implement a correct SO(3) group for use in ANISE. Currently, work by Greg and Chris in commit 04b719f, have an early draft of what is needed for rotations in src/math/rotation/mod.rs.

Some useful resources:

• Wikipedia on SO(3)
• RigidBodyKinematic.py is Basilisk's set of conversions between different attitude representations
• Sophus (C++) is a Lie group implementation in C++
• Mathoverflow
• PyQuat is an excellent resource for quaternion math (uses the Shulster notation)
• This PDF seems to provide good information on how to derive different representations.

Requirements

1. Rotation structures shall be composable
   1. Composition between different representations shall be supported
   2. Composition between different representations shall use the most efficient calculation that maintains accuracy (efficient as "least number of instructions", as determined by iai/cachegrind)
2. Rotations shall check the source and destination frames to prevent invalid rotations (this can probably not be done at compile time)
3. The following representations shall be supported at a minimum:
   1. Direct Cosine Matrix (DCM)
   2. Quaternions shall be supported in their "natural" form (i, j, k, scalar), but a conversion to and from Shuster notation shall also be supported (https://possiblywrong.wordpress.com/2021/05/10/beware-the-natural-quaternion/)
   3. Modified Rodrigez Parameters (cf. Springer and Schaub)
   4. Representations shall be unambiguous on initialization and getters (e.g. a quaterion shall not be publicly indexable because that's confusion to the user who might not remember the storage order)
4. All representations shall provide relevant helpers
   1. Quaternions shall provide at a minimum a conjugate function and a "short direction" function
   2. MRPs shall provide at a minimum a shadow set representation
5. All computations shall be checked for math domain errors and return AniseError::MathError where relevant.
6. All representation shall allow for rotation of both vectors and matrices (and ensure that matrices are rotated using C^T * A * C)
7. _More? Should we this also provide the time-derivatives of each representation? That could be useful)

Test plans

How do we test that these requirements are fulfilled correctly? What are some edge cases we should be aware of when developing the test code.

Design

This is the design section. Each subsection has its own subsection in the quality assurance document.

Algorithm demonstration

If this issue requires a change in an algorithm, it should be described here. This algorithm should be described thoroughly enough to be used as documentation. This section may also simply refer to an algorithm in the literature or in another piece of software that has been validated. The quality of that reference will be determined case by case.

API definition

Define how the ANISE APIs will be affect by this: what are new functions available, do any previous function change their definition, why call these functions by that name, etc.

High level architecture

Document, discuss, and optionally upload design diagram into this section.

Detailed design

The detailed design *will be used in the documentation of how ANISE works.

Feel free to fill out additional QA sections here, but these will typically be determined during the development, including the release in which this issue will be tackled.

[ChristopherRabotin]

TODO

• Euler Parameters
• MRPs
• DCM to/from quaternions
• DCMs via Euler rotations as 1, 2, 3, and pitch/yaw/roll
• Frame checking on composition
• Derivative of MRPs
• Derivative DCM
• Derivative of Euler Parameter
• For EP, MRPs, and DCMs, add an r1, r2, and r3 shortcut that rotates vectors by - angle like in Nyx utils.
• Multiplication of a quaternion or MRP with a vector should return a rotated vector
• ~~Encoding and decoding of Euler Parameters to/from DER ~~ Will add if this becomes important
• Compute rotations from BPC data High fidelity rotation information (binary PCK conversion) #33
• Compute rotations from planetary data imported from PCK files High fidelity rotation information (binary PCK conversion) #33

[ChristopherRabotin]

https://chat.openai.com/share/2f397ea3-c3bb-4d08-bc61-901c1fba623b