{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Physical units\n",
    "\n",
    "All variables in scipp have a physical unit.\n",
    "Variables are used for coordinates, labels, data, as well as attributes, i.e., all of these have a unit.\n",
    "\n",
    "When not specified explicitly the unit of a variable defaults to `scipp.units.dimensionless` (`scipp.units.one` is a shorter alias for this), i.e., the variable is considered dimensionless.\n",
    "\n",
    "`scipp.units` provides a number of pre-defined elementary units as well as operations between units.\n",
    "This can be used to create units that do not have a pre-defined identifier:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import scipp as sc\n",
    "\n",
    "length = sc.units.m\n",
    "area = length * length\n",
    "area"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "volume = length * length * length\n",
    "volume"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "speed = length / sc.units.s\n",
    "speed"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can get a list of all predefined units (accessible through `sc.units`) with"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "[unit for unit in dir(sc.units) if not unit.startswith('_')]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Units can also be created directly from strings:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.Unit('m/s')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.Unit('counts')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To convert data between compatible units, such as `m` to `mm`, see [sc.to_unit](../generated/functions/scipp.to_unit.rst#scipp.to_unit)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.to_unit(1 * sc.Unit('m'), 'mm')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Supported Units\n",
    "\n",
    "### Base Units\n",
    "All SI base units are supported with the following names:\n",
    "\n",
    "Name | Unit\n",
    "---|---\n",
    "'m' | meter\n",
    "'s' | second\n",
    "'kg' | kilogram\n",
    "'K' | kelvin\n",
    "'A' | ampere\n",
    "'mol' | mole\n",
    "'cd' | candela"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.Unit('K')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In addition, these base units are supported for cases not covered by SI:\n",
    "\n",
    "name | Unit\n",
    "---|---\n",
    "'rad' | radian\n",
    "'count' | single object counting\n",
    "\n",
    "### Derived units\n",
    "A great number of derived units can also be specified as arguments to `sc.Unit`.\n",
    "Some examples are\n",
    "\n",
    "Name | Unit\n",
    "---|---\n",
    "'Hz' | hertz\n",
    "'J' | joule\n",
    "'V' | volt\n",
    "'W' | watt\n",
    "'angstrom' / 'Å' | ångström\n",
    "'eV' | electron volt\n",
    "'L' | liter\n",
    "'min' | minute\n",
    "'D' / 'day' | day\n",
    "\n",
    "Units can be modified with SI prefixes, for instance"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(sc.Unit('mm'), sc.Unit('microsecond'), sc.Unit('micro s'), sc.Unit('MJ'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also specify exponents for units or exponentiate them explicitly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(sc.Unit('m^2'), sc.Unit('m**2'), sc.Unit('m')**2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Scipp units library is built on top of LLNL [Units](https://units.readthedocs.io/en/latest/index.html).\n",
    "You can take a look at the page on [Defined Units](https://units.readthedocs.io/en/latest/user-guide/defined_units.html) for a more complete list of supported units.\n",
    "However, this should be considered an implementation detail and it is best not to rely on the more specialized unit systems."
   ]
  }
 ],
 "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.7.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}