Tutorial 01: Introduction to OpenGNC

Welcome to the OpenGNC, a comprehensive Python library designed for spacecraft Guidance, Navigation, and Control (GNC) simulation and analysis.

Theory Prerequisites

Quaternion Attitude Representation

Spacecraft attitude is frequently parameterized using quaternions to avoid coordinate singularities (e.g., Gimbal lock in Euler angles). A quaternion \(q\) is defined as a vector in \(\mathbb{R}^4\) with a scalar part \(q_s\) and a vector part \(q_v = [q_x, q_y, q_z]^T\):

\[\begin{split} q = \begin{bmatrix} q_v \\ q_s \end{bmatrix} \end{split}\]

For pure rotations, we use unit quaternions (\(|q| = 1\)). To rotate a 3D vector \(v\) by a quaternion \(q\), we treat \(v\) as a pure quaternion \(v_q = [v^T, 0]^T\) and compute:

\[ v' = q \otimes v_q \otimes q^* \]
where \(\otimes\) denotes quaternion multiplication and \(q^*\) is the conjugate of \(q\).

import numpy as np
from opengnc.utils.quat_utils import axis_angle_to_quat, quat_rot

# 1. Define rotation axis and angle
axis = np.array([0, 0, 1.0]) # Rotation about Z-axis
angle = np.deg2rad(45)       # 45 degrees in radians

# 2. Convert to Unit Quaternion
q = axis_angle_to_quat(axis * angle)
print(f"Quaternion [q_x, q_y, q_z, q_w]:\n{q}")

# 3. Set a vector to rotate
v = np.array([1, 0, 0])      # Vector along X-axis

# 4. Rotate vector using OpenGNC
v_rot = quat_rot(q, v)
print(f"\nOriginal vector: {v}")
print(f"Rotated vector after 45 deg Z-rotation: {v_rot}")

# 5. Check Norm Preservation
print(f"\nNorm Preserved: {np.isclose(np.linalg.norm(v), np.linalg.norm(v_rot))}")

Quaternion [q_x, q_y, q_z, q_w]:
[0.         0.         0.38268343 0.92387953]

Original vector: [1 0 0]
Rotated vector after 45 deg Z-rotation: [0.70710678 0.70710678 0.        ]

Norm Preserved: True

Core Modules

  • environment: High-fidelity models for atmosphere (e.g., drag), magnetic fields (e.g., IGFR), and gravity (e.g., EGM2008).

  • disturbances: Dynamic perturbation calculations like Solar Radiation Pressure (SRP) and Air Drag.

  • kalman_filters: High-performance orbit and attitude state estimation (EKF, UKF, MEKF).

  • guidance: Classical Maneuver analysis (Hohmann), Continuous thrust Indirect/Direct collocation control solvers.

  • utils: Core transformations accounting for Frame Conversions & kinematics tensors.