docs/tutorials/InterfacingOtherMathSystems.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "nbsphinx": "hidden"
   },
   "source": [
    "This notebook is part of the `clifford` documentation: https://clifford.readthedocs.io/."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Interfacing Other Mathematical Systems\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Geometric Algebra is known as a *universal algebra* because it subsumes several other mathematical systems.\n",
    "Two algebras commonly used by engineers and scientists are complex numbers and quaternions.\n",
    "These algebras can be subsumed as the even sub-algebras of 2 and 3 dimensional geometric algebras, respectively.\n",
    "This notebook demonstrates how `clifford` can be used to incorporate data created with these systems into geometric algebra."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##  Complex Numbers"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Given a two dimensional GA with the orthonormal basis,\n",
    "\n",
    "$$e_{i}\\cdot e_{j}=\\delta_{ij}$$\n",
    " \n",
    "\n",
    "The geometric algebra consists of scalars, two vectors, and a bivector, \n",
    "\n",
    "$$\\{\\quad\\underbrace{\\alpha,}_{\\mbox{scalar}}\\qquad\\underbrace{e_{1},\\qquad e_{2},}_{\\mbox{vector}}\\qquad\\underbrace{e_{12}}_{\\mbox{bivector}}\\quad\\}$$\n",
    " \n",
    "\n",
    "\n",
    "A complex number can be directly associated with a 2D spinor in the $e_{12}$-plane, \n",
    "\n",
    "$$\\underbrace{\\mathbf{z}=\\alpha+\\beta i}_{\\mbox{complex number}}\\quad\\Longrightarrow\\quad\\underbrace{Z=\\alpha+\\beta e_{12}}_{\\mbox{2D spinor}}$$\n",
    "\n",
    "\n",
    " \n",
    "The even subalgebra of a two dimensional geometric algebra is isomorphic to the complex numbers.\n",
    "We can setup translating functions which converts a 2D spinor into a complex number and vice-versa. In two dimensions the spinor can be also be mapped into vectors if desired. \n",
    "\n",
    "Below is an illustration of the three different planes, the later two being contained within the geometric algebra of two dimensions, $G_2$.\n",
    "Both spinors and vectors in $G_2$ can be modeled as points on a plane, but they have distinct algebraic properties.",
    "\n",
    "![](../_static/2dmap.svg)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import clifford as cf\n",
    "layout, blades = cf.Cl(2) # instantiate a 2D- GA\n",
    "locals().update(blades)   # put all blades into local namespace\n",
    "\n",
    "\n",
    "def c2s(z):\n",
    "    '''convert a complex number to a spinor'''\n",
    "    return z.real + z.imag*e12\n",
    "\n",
    "def s2c(S):\n",
    "    '''convert a spinor to a complex number'''\n",
    "    S0 = float(S(0))\n",
    "    S2 = float(-S|e12)\n",
    "    return S0 + S2*1j"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Convert a complex number to a spinor "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "c2s(1+2j)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Convert a spinor to a complex number"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s2c(1+2*e12)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Make sure we get what we started with when we make a round trip"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s2c(c2s(1+2j)) == 1+2j"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The spinor is then mapped to a vector by choosing a reference direction. This may be done by left multiplying with $e_{1}$\n",
    " .\n",
    "\n",
    "$$Z\\Longrightarrow e_{1}Z=e_{1}\\alpha+\\beta e_{1}e_{12}=\\underbrace{\\alpha e_{1}+\\beta e_{2}}_{\\mbox{vector}}$$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s = 1+2*e12\n",
    "e1*s"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Geometrically, this is interpreted as  having the spinor rotate a specific vector, in this case $e_1$. Building off of the previously defined functions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def c2v(c):\n",
    "    '''convert a complex number to a vector'''\n",
    "    return e1*c2s(c)\n",
    "\n",
    "def v2c(v):\n",
    "    '''convert a vector to a complex number'''\n",
    "    return s2c(e1*v)  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "c2v(1+2j)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "v2c(1*e1+2*e2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Depending on your applications, you may wish to have the bivector be an argument to the `c2s` and `s2c` functions.\n",
    "This allows you to map input data given in the form of complex number onto the planes of your choice.\n",
    "For example, in three dimensional space there are three bivector-planes; $e_{12}, e_{23}$ and $e_{13}$, so there are many bivectors which could be interpreted as the unit imaginary. \n",
    "\n",
    "Complex numbers mapped in this way can be used to enact rotations within the specified planes. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import clifford as cf\n",
    "layout, blades = cf.Cl(3)\n",
    "locals().update(blades)\n",
    "\n",
    "def c2s(z,B):\n",
    "    '''convert a complex number to a spinor'''\n",
    "    return z.real + z.imag*B\n",
    "\n",
    "def s2c(S,B):\n",
    "    '''convert a spinor to a complex number'''\n",
    "    S0 = float(S(0))\n",
    "    S2 = float(-S|B)\n",
    "    return S0 + S2*1j"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "c2s(1+2j, e23)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "c2s(3+4j, e13)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This brings us to the subject of quaternions, which are used to handle rotations in three dimensions much like complex numbers do in two dimensions.  With geometric algebra, they are just spinors acting in a different geometry. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Quaternions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "<div class=\"alert alert-info\">\n",
    "\n",
    "**Note:**\n",
    "\n",
    "There is support for quaternions in numpy through the package [quaternion](https://github.com/moble/quaternion).\n",
    "\n",
    "</div>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For some reason people think quaternions ([wiki page](https://en.wikipedia.org/wiki/Quaternion)) are mystical or something.\n",
    "They are just spinors in a three dimensional geometric algebra.\n",
    "\n",
    "In either case, we can pass the `names` parameters to `Cl()` to explicitly label the bivectors `i,j,` and `k`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import clifford as cf\n",
    "\n",
    "# the vector/bivector order is reversed because Hamilton defined quaternions using a\n",
    "# left-handed frame. wtf.\n",
    "names = ['', 'z', 'y', 'x', 'k', 'j', 'i', 'I'] \n",
    "\n",
    "layout, blades = cf.Cl(3, names=names)\n",
    "locals().update(blades)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This leads to the commutations relations familiar to quaternion users"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for m in [i, j, k]:\n",
    "    for n in [i, j, k]:\n",
    "        print ('{}*{}={}'.format(m, n, m*n))                        "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Quaternion data could be stored in a variety of ways. Assuming you have the scalar components for the quaternion, all you will need to do is setup a map each component to the correct bivector. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def q2S(*args):\n",
    "    '''convert tuple of quaternion coefficients to a spinor'''\n",
    "    q = args\n",
    "    return q[0] + q[1]*i + q[2]*j + q[3]*k "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then all the quaternion computations can be done using GA"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "q1 = q2S(1,2,3,4)\n",
    "q1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This prints $i,j$ and $k$ in reverse order but whatever, "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 'scalar' part \n",
    "q1(0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 'vector' part (more like bivector part!)\n",
    "q1(2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*quaternion conjugation* is implemented with reversion "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "~q1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The norm"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "abs(q1) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Taking the `dual()` of the \"vector\" part actually returns a vector,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "q1(2).dual()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "q1 = q2S(1, 2, 3, 4)\n",
    "q2 = q2S(5, 6, 7, 8)\n",
    "\n",
    "# quaternion product\n",
    "q1*q2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you want to keep using a left-handed frame and names like $i,j$ and $k$ to label the planes in 3D space, ok.\n",
    "If you think it makes more sense to use the consistent and transparent approach provided by GA, we think you have good taste.\n",
    "If we make this switch, the basis and `q2S()` functions will be changed to "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import clifford as cf\n",
    "layout, blades = cf.Cl(3)\n",
    "locals().update(blades)\n",
    "\n",
    "blades"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def q2S(*args):\n",
    "    '''\n",
    "    convert tuple of quaternion coefficients to a spinor'''\n",
    "    q = args\n",
    "    return q[0] + q[1]*e13 +q[2]*e23 + q[3]*e12\n",
    "\n",
    "q1 = q2S(1,2,3,4)\n",
    "q1"
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "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.5.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}