search

nyx-space / anise

ANISE provides a toolkit and files for Attitude, Navigation, Instrument, Spacecraft, and Ephemeris data. It's a modern replacement of the NAIF SPICE toolkit.
Mozilla Public License 2.0
54 stars 12 forks source link

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

Closed ChristopherRabotin closed 1 year ago

ChristopherRabotin commented 1 year ago

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 04b719f76a36d97be31941e4480f2da6a18c1381, have an early draft of what is needed for rotations in src/math/rotation/mod.rs.

Some useful resources:

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 commented 1 year ago

TODO

ChristopherRabotin commented 1 year ago

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