{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Units in MDMC\n",
    "\n",
    "## SYSTEM Units\n",
    "\n",
    "All quantities passed as arguments and returned as outputs in MDMC have units associated with them. In general, these units are consistent across all functions and are referred to as the `SYSTEM` units associated with a physical property:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from MDMC.common import units\n",
    "\n",
    "print(units.SYSTEM)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example, both the `Atom` and `Universe` expect units of `Ang` for `LENGTH` properties (the `position` and `dimensions` arguments respectively):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from MDMC.MD import Atom, Universe\n",
    "\n",
    "print(help(Atom))\n",
    "print(help(Universe))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Similarly, attributes returned also have the units documented. In this case, the unit for `velocity` is a compound unit for the properties `LENGTH` and `TIME` (`Ang` and `fs`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(Atom('H').velocity)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exceptional Cases\n",
    "\n",
    "There are some cases where the units expected by an MDMC object are not `SYSTEM` due to external conventions. For example, the `SYSTEM` unit for `ANGLE` is `deg`, but `HarmonicPotential` expects units of `kJ mol^-1 rad^-2` when used for a `BondAngle`. As before, this information is available from the help function:\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from MDMC.MD import HarmonicPotential\n",
    "\n",
    "print(help(HarmonicPotential))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Another example is `energy_resolution` being expected in units of `ueV` rather than the `meV` used for `ENERGY_TRANSFER` elsewhere:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from MDMC.control import Control\n",
    "\n",
    "print(help(Control))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Converting Units\n",
    "\n",
    "The conversion factor required to get to MDMC `SYSTEM` units from a general unit can be accessed by creating a new `Unit`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "general_unit = units.Unit('kcal / Ang mol')\n",
    "SYSTEM_unit = units.SYSTEM[general_unit.physical_property]\n",
    "print('To convert from `{0}` to `{1}`, multiply by a factor of {2}'\n",
    "      ''.format(general_unit, SYSTEM_unit, general_unit.conversion_factor))\n",
    "print('To convert from `{1}` to `{0}`, divide by a factor of {2}'\n",
    "      ''.format(general_unit, SYSTEM_unit, general_unit.conversion_factor))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example, to create an `Atom` with a position in `nm` rather `Ang`, then access that value in `m`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "position_nm = np.array([1., 1., 1.,])\n",
    "position_ang = position_nm * units.Unit('nm').conversion_factor\n",
    "atom = Atom('H', position=position_ang)\n",
    "print('Atom position in `m` is {}'.format(np.array(atom.position) / units.Unit('m').conversion_factor))"
   ]
  }
 ],
 "metadata": {
  "interpreter": {
   "hash": "add738a18a8c9080256f416f48e2f1975a0b0948846decec7f4bbc677823fdf5"
  },
  "kernelspec": {
   "display_name": "Python 3.7.4 32-bit ('mdmc-venv': virtualenv)",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": ""
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}