{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Unit handling and unit conversions in `qha-cij`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For the convenience of calculation, the physical quantities in `qha-cij` are all stored in [Rydberg atomic units](https://faculty.kfupm.edu.sa/phys/aanaqvi/rydberg.pdf).  But to make things easier for user, we use units that is reported by scientists. Natually, there is a lot of unit handling involved. This tutorial will demostrate how unit conversions are done in `qha-cij`, so that if there is a need for you to address units issues on your own, you will not be lost."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The `units` module\n",
    "\n",
    "The units module is provided in `cij.util`. Based on the [pint](https://pint.readthedocs.io/en/0.10.1/) package, the `units` is a instance of Pint `UnitRegistry` that will maintain a list of units. The atomic units are by [default](https://github.com/hgrecco/pint/blob/master/pint/default_en.txt) loaded and available after Pint `0.10.0` we will stick to that. A single `UnitRegistry` instance is supposed to be shared among the entire program."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The type of `units` is actually a instance of <class 'pint.registry.UnitRegistry'>\n"
     ]
    }
   ],
   "source": [
    "from cij.util import units\n",
    "\n",
    "print(\"The type of `units` is actually a instance of\", repr(type(units)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Declaring quantity\n",
    "\n",
    "The physical variables are declared using `Quantity` to include the phyisical units"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1 meter\n",
      "1 rydberg\n"
     ]
    }
   ],
   "source": [
    "print(units.Quantity(1, units.m))\n",
    "print(units.Quantity(1, units.rydberg))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Conversion between units with `to()`\n",
    "\n",
    "Units are converted by create a `Quantity` with unit, and convert the unit with `to()`, and the the value number is obtained using the `.magnitude` property.\n",
    "\n",
    "Here we convert three terms:\n",
    "\n",
    "- Length: 1 Å = 0.529177 bohr\n",
    "- Volume: 1 Å$^3$ = 0.148184 bohr$^3$\n",
    "- Pressure: 1 Ryd / bohr$^3$ = 14710 GPa"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "- Length:\t 0.5291772109039774\n",
      "- Volume:\t 0.14818471147298387\n",
      "- Pressure:\t 14710.50784817977\n"
     ]
    }
   ],
   "source": [
    "print(\"- Length:\\t\", units.Quantity(1, units.bohr).to(units.angstrom).magnitude)\n",
    "print(\"- Volume:\\t\", units.Quantity(1, units.bohr ** 3).to(units.angstrom ** 3).magnitude)\n",
    "print(\"- Pressure:\\t\", units.Quantity(1, units.rydberg / units.bohr ** 3).to(units.GPa).magnitude)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Helper functions to make it even better\n",
    "\n",
    "To make unit conversion even easier, I have create a function called `convert_unit`. It takes three parameters, the original unit to convert from, the target unit to convert to, and the value."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Convert unit by calling convert_unit directly:\n",
      "- Length:\t 0.5291772109039774\n",
      "- Volume:\t 0.14818471147298387\n",
      "- Pressure:\t 14710.50784817977\n"
     ]
    }
   ],
   "source": [
    "from cij.util import convert_unit\n",
    "\n",
    "print(\"Convert unit by calling convert_unit directly:\")\n",
    "\n",
    "print(\"- Length:\\t\",   convert_unit(units.bohr, units.angstrom, 1))\n",
    "print(\"- Volume:\\t\",   convert_unit(units.bohr ** 3, units.angstrom ** 3, 1))\n",
    "print(\"- Pressure:\\t\", convert_unit(units.rydberg / units.bohr ** 3, units.GPa, 1))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Omit the `value` field you will get a function for method conversion required."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Convert unit by creating a unit conversion function first:\n",
      "- Pressure:\t 14710.50784817977\n"
     ]
    }
   ],
   "source": [
    "print(\"Convert unit by creating a unit conversion function first:\")\n",
    "\n",
    "_to_gpa = convert_unit(units.rydberg / units.bohr ** 3, units.GPa)\n",
    "\n",
    "print(\"- Pressure:\\t\", convert_unit(units.rydberg / units.bohr ** 3, units.GPa, 1))"
   ]
  }
 ],
 "metadata": {
  "file_extension": ".py",
  "kernelspec": {
   "display_name": "Python 3.6.8 64-bit ('3.6.8': pyenv)",
   "language": "python",
   "name": "python36864bit368pyenvd6afb3362fb64a40b8bf674afd00b7cc"
  },
  "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.6.8"
  },
  "mimetype": "text/x-python",
  "name": "python",
  "npconvert_exporter": "python",
  "pygments_lexer": "ipython3",
  "version": 3
 },
 "nbformat": 4,
 "nbformat_minor": 2
}