{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tutorial 01: Introduction to OpenGNC\n",
    "\n",
    "Welcome to the **OpenGNC**, a comprehensive Python library designed for spacecraft Guidance, Navigation, and Control (GNC) simulation and analysis.\n",
    "\n",
    "## Theory Prerequisites\n",
    "\n",
    "### Quaternion Attitude Representation\n",
    "Spacecraft attitude is frequently parameterized using quaternions to avoid coordinate singularities (e.g., Gimbal lock in Euler angles).\n",
    "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$:\n",
    "$$\n",
    "q = \\begin{bmatrix} q_v \\\\ q_s \\end{bmatrix}\n",
    "$$\n",
    "\n",
    "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:\n",
    "$$\n",
    "v' = q \\otimes v_q \\otimes q^*\n",
    "$$\n",
    "where $\\otimes$ denotes quaternion multiplication and $q^*$ is the conjugate of $q$.\n",
    "\n",
    "---"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Quaternion [q_x, q_y, q_z, q_w]:\n",
      "[0.         0.         0.38268343 0.92387953]\n",
      "\n",
      "Original vector: [1 0 0]\n",
      "Rotated vector after 45 deg Z-rotation: [0.70710678 0.70710678 0.        ]\n",
      "\n",
      "Norm Preserved: True\n"
     ]
    }
   ],
   "source": [
    "import numpy as np\n",
    "from opengnc.utils.quat_utils import axis_angle_to_quat, quat_rot\n",
    "\n",
    "# 1. Define rotation axis and angle\n",
    "axis = np.array([0, 0, 1.0]) # Rotation about Z-axis\n",
    "angle = np.deg2rad(45)       # 45 degrees in radians\n",
    "\n",
    "# 2. Convert to Unit Quaternion\n",
    "q = axis_angle_to_quat(axis * angle)\n",
    "print(f\"Quaternion [q_x, q_y, q_z, q_w]:\\n{q}\")\n",
    "\n",
    "# 3. Set a vector to rotate\n",
    "v = np.array([1, 0, 0])      # Vector along X-axis\n",
    "\n",
    "# 4. Rotate vector using OpenGNC\n",
    "v_rot = quat_rot(q, v)\n",
    "print(f\"\\nOriginal vector: {v}\")\n",
    "print(f\"Rotated vector after 45 deg Z-rotation: {v_rot}\")\n",
    "\n",
    "# 5. Check Norm Preservation\n",
    "print(f\"\\nNorm Preserved: {np.isclose(np.linalg.norm(v), np.linalg.norm(v_rot))}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Core Modules\n",
    "\n",
    "- **`environment`**: High-fidelity models for atmosphere (e.g., drag), magnetic fields (e.g., IGFR), and gravity (e.g., EGM2008).\n",
    "- **`disturbances`**: Dynamic perturbation calculations like Solar Radiation Pressure (SRP) and Air Drag.\n",
    "- **`kalman_filters`**: High-performance orbit and attitude state estimation (EKF, UKF, MEKF).\n",
    "- **`guidance`**: Classical Maneuver analysis (Hohmann), Continuous thrust Indirect/Direct collocation control solvers.\n",
    "- **`utils`**: Core transformations accounting for Frame Conversions & kinematics tensors."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}