{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# A module for rotation parametrization\n",
    "\n",
    "This document describes the implementation of generic vectorial parametrization of rotation matrices,  essentially following [[BAU03]](#References). This module is used in the [Nonlinear beam model in finite rotations](finite_rotation_nonlinear_beam.ipynb) tour.\n",
    "\n",
    "## Implementation aspects\n",
    "\n",
    "The module provides the `Skew` function, mapping a 3D vector to the corresponding skew-symmetric matrix.\n",
    "\n",
    "An abstract class handles the generic implementation of rotation parametrization based on the corresponding parametrization of the rotation angle $p(\\varphi)$. Considering a generic rotation vector which we denote by $\\boldsymbol{\\theta}$, [[BAU03]](#References) works with $\\varphi = \\|\\boldsymbol{\\theta}\\|$ and the unit-norm vector $\\boldsymbol{u} = \\boldsymbol{\\theta}/\\varphi$. Note that the involved expressions are usually ill-defined when $\\varphi \\to 0$. For this reason, the numerical implementation makes use of a regularized expression for the norm:\n",
    "\\begin{equation}\n",
    "\\varphi = \\sqrt{\\boldsymbol{\\theta}^2 + \\varepsilon}\n",
    "\\end{equation}\n",
    "with ${\\varepsilon}=$ DOLFIN_EPS in practice.\n",
    "\n",
    "The rotation parameter vector $\\boldsymbol{p}$ from [[BAU03]](#References) is given by the `rotation_parameter` attribute.\n",
    "\n",
    "The class then implements the following functions:\n",
    "\\begin{align}\n",
    "h_1(\\varphi) &= \\dfrac{\\nu(\\varphi)^2}{\\epsilon(\\varphi)}\\\\\n",
    "h_2(\\varphi) &= \\dfrac{\\nu(\\varphi)^2}{2}\\\\\n",
    "h_3(\\varphi) &= \\dfrac{\\mu(\\varphi)-h_1(\\varphi)}{p(\\varphi)^2}\\\\\n",
    "\\end{align}\n",
    "where $\\nu(\\varphi),\\epsilon(\\varphi)$ and $\\mu(\\varphi)$ are defined in [[BAU03]](#References).\n",
    "\n",
    "It then provides the expression for the corresponding rotation matrix $\\boldsymbol{R}$:\n",
    "\\begin{equation}\n",
    "\\boldsymbol{R} = \\boldsymbol{I} + h_1(\\varphi)\\boldsymbol{P} + h_2(\\varphi)\\boldsymbol{P}^2\n",
    "\\end{equation}\n",
    "where $\\boldsymbol{P} = \\operatorname{skew}(\\boldsymbol{p})$, as well as the associated rotation curvature matrix $\\boldsymbol{H}$ involved in the computation of the rotation rate:\n",
    "\\begin{equation}\n",
    "\\boldsymbol{H} = \\mu(\\varphi)\\boldsymbol{I} + h_2(\\varphi)\\boldsymbol{P} + h_3(\\varphi)\\boldsymbol{P}^2\n",
    "\\end{equation}\n",
    "\n",
    "## Available particular cases\n",
    "\n",
    "### `ExponentialMap` parametrization\n",
    "\n",
    "This parametrization corresponds to the simple choice:\n",
    "\\begin{equation}\n",
    "p(\\varphi)=\\varphi\n",
    "\\end{equation}\n",
    "The corresponding expression for the rotation matrix is the famous Euler-Rodrigues formula.\n",
    "\n",
    "### `EulerRodrigues` parametrization\n",
    "This parametrization corresponds to the simple choice:\n",
    "\\begin{equation}\n",
    "p(\\varphi)=2 sin(\\varphi/2)\n",
    "\\end{equation}\n",
    "\n",
    "### `SineFamily` parametrization\n",
    "\n",
    "This generic family for any integer $m$ corresponds to:\n",
    "\\begin{equation}\n",
    "p(\\varphi) = m \\sin\\left(\\frac{\\varphi}{m}\\right)\n",
    "\\end{equation}\n",
    "\n",
    "### `TangentFamily` parametrization\n",
    "\n",
    "This generic family for any integer $m$ corresponds to:\n",
    "\\begin{equation}\n",
    "p(\\varphi) = m \\tan\\left(\\frac{\\varphi}{m}\\right)\n",
    "\\end{equation}\n",
    "\n",
    "## Code"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "The corresponding module is available here :download:`rotation_parametrization.py`.\n",
    "\n",
    ".. literalinclude:: rotation_parametrization.py\n",
    "  :language: python"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## References\n",
    "\n",
    "[BAU03] Bauchau, O. A., & Trainelli, L. (2003). The vectorial parameterization of rotation. Nonlinear dynamics, 32(1), 71-92."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "celltoolbar": "Format de la Cellule Texte Brut",
  "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.8.10"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": false,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}