path: root/docs/numpy.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "NumPy Support\n",
    "=============\n",
    "\n",
    "The magnitude of a Pint quantity can be of any numerical scalar type, and you are free\n",
    "to choose it according to your needs. For numerical applications requiring arrays, it is\n",
    "quite convenient to use [NumPy ndarray](http://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html) (or [ndarray-like types supporting NEP-18](https://numpy.org/neps/nep-0018-array-function-protocol.html)),\n",
    "and therefore these are the array types supported by Pint.\n",
    "\n",
    "First, we import the relevant packages:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Import NumPy\n",
    "import numpy as np\n",
    "\n",
    "# Disable Pint's old fallback behavior (must come before importing Pint)\n",
    "import os\n",
    "os.environ['PINT_ARRAY_PROTOCOL_FALLBACK'] = \"0\"\n",
    "\n",
    "# Import Pint\n",
    "import pint\n",
    "ureg = pint.UnitRegistry()\n",
    "Q_ = ureg.Quantity\n",
    "\n",
    "# Silence NEP 18 warning\n",
    "import warnings\n",
    "with warnings.catch_warnings():\n",
    "    warnings.simplefilter(\"ignore\")\n",
    "    Q_([])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and then we create a quantity the standard way"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[3.0 4.0] meter\n"
     ]
    }
   ],
   "source": [
    "legs1 = Q_(np.asarray([3., 4.]), 'meter')\n",
    "print(legs1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[3.0 4.0] meter\n"
     ]
    }
   ],
   "source": [
    "legs1 = [3., 4.] * ureg.meter\n",
    "print(legs1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All usual Pint methods can be used with this quantity. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[0.003 0.004] kilometer\n"
     ]
    }
   ],
   "source": [
    "print(legs1.to('kilometer'))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[length]\n"
     ]
    }
   ],
   "source": [
    "print(legs1.dimensionality)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Cannot convert from 'meter' ([length]) to 'joule' ([length] ** 2 * [mass] / [time] ** 2)\n"
     ]
    }
   ],
   "source": [
    "try:\n",
    "    legs1.to('joule')\n",
    "except pint.DimensionalityError as exc:\n",
    "    print(exc)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "NumPy functions are supported by Pint. For example if we define:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[400.0 300.0] centimeter\n"
     ]
    }
   ],
   "source": [
    "legs2 = [400., 300.] * ureg.centimeter\n",
    "print(legs2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "we can calculate the hypotenuse of the right triangles with legs1 and legs2."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[5.0 5.0] meter\n"
     ]
    }
   ],
   "source": [
    "hyps = np.hypot(legs1, legs2)\n",
    "print(hyps)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that before the `np.hypot` was used, the numerical value of legs2 was\n",
    "internally converted to the units of legs1 as expected.\n",
    "\n",
    "Similarly, when you apply a function that expects angles in radians, a conversion\n",
    "is applied before the requested calculation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[0.6435011087932843 0.9272952180016123] radian\n"
     ]
    }
   ],
   "source": [
    "angles = np.arccos(legs2/hyps)\n",
    "print(angles)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can convert the result to degrees using usual unit conversion:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[36.86989764584401 53.13010235415599] degree\n"
     ]
    }
   ],
   "source": [
    "print(angles.to('degree'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Applying a function that expects angles to a quantity with a different dimensionality\n",
    "results in an error:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Cannot convert from 'centimeter' ([length]) to 'dimensionless' (dimensionless)\n"
     ]
    }
   ],
   "source": [
    "try:\n",
    "    np.arccos(legs2)\n",
    "except pint.DimensionalityError as exc:\n",
    "    print(exc)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Function/Method Support\n",
    "-----------------------\n",
    "\n",
    "The following [ufuncs](http://docs.scipy.org/doc/numpy/reference/ufuncs.html) can be applied to a Quantity object:\n",
    "\n",
    "- **Math operations**: `add`, `subtract`, `multiply`, `divide`, `logaddexp`, `logaddexp2`, `true_divide`, `floor_divide`, `negative`, `remainder`, `mod`, `fmod`, `absolute`, `rint`, `sign`, `conj`, `exp`, `exp2`, `log`, `log2`, `log10`, `expm1`, `log1p`, `sqrt`, `square`, `cbrt`, `reciprocal`\n",
    "- **Trigonometric functions**: `sin`, `cos`, `tan`, `arcsin`, `arccos`, `arctan`, `arctan2`, `hypot`, `sinh`, `cosh`, `tanh`, `arcsinh`, `arccosh`, `arctanh`\n",
    "- **Comparison functions**: `greater`, `greater_equal`, `less`, `less_equal`, `not_equal`, `equal`\n",
    "- **Floating functions**: `isreal`, `iscomplex`, `isfinite`, `isinf`, `isnan`, `signbit`, `copysign`, `nextafter`, `modf`, `ldexp`, `frexp`, `fmod`, `floor`, `ceil`, `trunc`\n",
    "\n",
    "And the following NumPy functions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['alen', 'all', 'allclose', 'amax', 'amin', 'any', 'append', 'argmax', 'argmin', 'argsort', 'around', 'atleast_1d', 'atleast_2d', 'atleast_3d', 'average', 'block', 'broadcast_to', 'clip', 'column_stack', 'compress', 'concatenate', 'copy', 'copyto', 'count_nonzero', 'cross', 'cumprod', 'cumproduct', 'cumsum', 'diagonal', 'diff', 'dot', 'dstack', 'ediff1d', 'einsum', 'empty_like', 'expand_dims', 'fix', 'flip', 'full_like', 'gradient', 'hstack', 'insert', 'interp', 'intersect1d', 'isclose', 'iscomplex', 'isin', 'isreal', 'linalg.solve', 'linspace', 'mean', 'median', 'meshgrid', 'moveaxis', 'nan_to_num', 'nanargmax', 'nanargmin', 'nancumprod', 'nancumsum', 'nanmax', 'nanmean', 'nanmedian', 'nanmin', 'nanpercentile', 'nanstd', 'nansum', 'nanvar', 'ndim', 'nonzero', 'ones_like', 'pad', 'percentile', 'ptp', 'ravel', 'reshape', 'resize', 'result_type', 'rollaxis', 'rot90', 'round_', 'searchsorted', 'shape', 'size', 'sort', 'squeeze', 'stack', 'std', 'sum', 'swapaxes', 'tile', 'transpose', 'trapz', 'trim_zeros', 'unwrap', 'var', 'vstack', 'where', 'zeros_like']\n"
     ]
    }
   ],
   "source": [
    "from pint.numpy_func import HANDLED_FUNCTIONS\n",
    "print(sorted(list(HANDLED_FUNCTIONS)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And the following [NumPy ndarray methods](http://docs.scipy.org/doc/numpy/reference/arrays.ndarray.html#array-methods):\n",
    "\n",
    "- `argmax`, `argmin`, `argsort`, `astype`, `clip`, `compress`, `conj`, `conjugate`, `cumprod`, `cumsum`, `diagonal`, `dot`, `fill`, `flatten`, `flatten`, `item`, `max`, `mean`, `min`, `nonzero`, `prod`, `ptp`, `put`, `ravel`, `repeat`, `reshape`, `round`, `searchsorted`, `sort`, `squeeze`, `std`, `sum`, `take`, `trace`, `transpose`, `var`\n",
    "\n",
    "Pull requests are welcome for any NumPy function, ufunc, or method that is not currently\n",
    "supported.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Array Type Support\n",
    "------------------\n",
    "\n",
    "### Overview\n",
    "\n",
    "When not wrapping a scalar type, a Pint `Quantity` can be considered a [\"duck array\"](https://numpy.org/neps/nep-0022-ndarray-duck-typing-overview.html), that is, an array-like type that implements (all or most of) NumPy's API for `ndarray`. Many other such duck arrays exist in the Python ecosystem, and Pint aims to work with as many of them as reasonably possible. To date, the following are specifically tested and known to work:\n",
    "\n",
    "- xarray: `DataArray`, `Dataset`, and `Variable`\n",
    "- Sparse: `COO`\n",
    "\n",
    "and the following have partial support, with full integration planned:\n",
    "\n",
    "- NumPy masked arrays (NOTE: Masked Array compatibility has changed with Pint 0.10 and versions of NumPy up to at least 1.18, see the example below)\n",
    "- Dask arrays\n",
    "- CuPy arrays\n",
    "\n",
    "### Technical Commentary\n",
    "\n",
    "Starting with version 0.10, Pint aims to interoperate with other duck arrays in a well-defined and well-supported fashion. Part of this support lies in implementing [`__array_ufunc__` to support NumPy ufuncs](https://numpy.org/neps/nep-0013-ufunc-overrides.html) and [`__array_function__` to support NumPy functions](https://numpy.org/neps/nep-0018-array-function-protocol.html). However, the central component to this interoperability is respecting a [type casting hierarchy](https://numpy.org/neps/nep-0018-array-function-protocol.html) of duck arrays. When all types in the hierarchy properly defer to those above it (in wrapping, arithmetic, and NumPy operations), a well-defined nesting and operator precedence order exists. When they don't, the graph of relations becomes cyclic, and the expected result of mixed-type operations becomes ambiguous.\n",
    "\n",
    "For Pint, following this hierarchy means declaring a list of types that are above it in the hierarchy and to which it defers (\"upcast types\") and assuming all others are below it and wrappable by it (\"downcast types\"). To date, Pint's declared upcast types are:\n",
    "\n",
    "- `PintArray`, as defined by pint-pandas\n",
    "- `Series`, as defined by Pandas\n",
    "- `DataArray`, `Dataset`, and `Variable`, as defined by xarray\n",
    "\n",
    "(Note: if your application requires extension of this collection of types, it is available in Pint's API at `pint.compat.upcast_types`.)\n",
    "\n",
    "While Pint assumes it can wrap any other duck array (meaning, for now, those that implement `__array_function__`, `shape`, `ndim`, and `dtype`, at least until [NEP 30](https://numpy.org/neps/nep-0030-duck-array-protocol.html) is implemented), there are a few common types that Pint explicitly tests (or plans to test) for optimal interoperability. These are listed above in the overview section and included in the below chart.\n",
    "\n",
    "This type casting hierarchy of ndarray-like types can be shown by the below acyclic graph, where solid lines represent declared support, and dashed lines represent planned support:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/svg+xml": [
       "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"no\"?>\n",
       "<!DOCTYPE svg PUBLIC \"-//W3C//DTD SVG 1.1//EN\"\n",
       " \"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd\">\n",
       "<!-- Generated by graphviz version 2.38.0 (20140413.2041)\n",
       " -->\n",
       "<!-- Title: %3 Pages: 1 -->\n",
       "<svg width=\"576pt\" height=\"288pt\"\n",
       " viewBox=\"0.00 0.00 576.00 288.25\" xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\">\n",
       "<g id=\"graph0\" class=\"graph\" transform=\"scale(0.86823 0.86823) rotate(0) translate(4 328)\">\n",
       "<title>%3</title>\n",
       "<polygon fill=\"white\" stroke=\"none\" points=\"-4,4 -4,-328 659.419,-328 659.419,4 -4,4\"/>\n",
       "<!-- Dask array -->\n",
       "<g id=\"node1\" class=\"node\"><title>Dask array</title>\n",
       "<ellipse fill=\"none\" stroke=\"black\" cx=\"186.393\" cy=\"-162\" rx=\"64.189\" ry=\"18\"/>\n",
       "<text text-anchor=\"middle\" x=\"186.393\" y=\"-158.3\" font-family=\"Courier,monospace\" font-size=\"14.00\">Dask array</text>\n",
       "</g>\n",
       "<!-- NumPy ndarray -->\n",
       "<g id=\"node2\" class=\"node\"><title>NumPy ndarray</title>\n",
       "<ellipse fill=\"none\" stroke=\"black\" cx=\"362.393\" cy=\"-18\" rx=\"80.6858\" ry=\"18\"/>\n",
       "<text text-anchor=\"middle\" x=\"362.393\" y=\"-14.3\" font-family=\"Courier,monospace\" font-size=\"14.00\">NumPy ndarray</text>\n",
       "</g>\n",
       "<!-- Dask array&#45;&gt;NumPy ndarray -->\n",
       "<g id=\"edge1\" class=\"edge\"><title>Dask array&#45;&gt;NumPy ndarray</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M183.487,-143.823C181.189,-124.181 180.714,-92.1479 197.393,-72 217.389,-47.8459 248.45,-34.5744 278.253,-27.3279\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"279.293,-30.6823 288.294,-25.0944 277.773,-23.8493 279.293,-30.6823\"/>\n",
       "</g>\n",
       "<!-- CuPy ndarray -->\n",
       "<g id=\"node3\" class=\"node\"><title>CuPy ndarray</title>\n",
       "<ellipse fill=\"none\" stroke=\"black\" cx=\"75.3933\" cy=\"-90\" rx=\"75.2868\" ry=\"18\"/>\n",
       "<text text-anchor=\"middle\" x=\"75.3933\" y=\"-86.3\" font-family=\"Courier,monospace\" font-size=\"14.00\">CuPy ndarray</text>\n",
       "</g>\n",
       "<!-- Dask array&#45;&gt;CuPy ndarray -->\n",
       "<g id=\"edge2\" class=\"edge\"><title>Dask array&#45;&gt;CuPy ndarray</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M161.483,-145.291C146.133,-135.611 126.244,-123.068 109.45,-112.477\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"111.316,-109.516 100.991,-107.142 107.582,-115.437 111.316,-109.516\"/>\n",
       "</g>\n",
       "<!-- Sparse COO -->\n",
       "<g id=\"node4\" class=\"node\"><title>Sparse COO</title>\n",
       "<ellipse fill=\"none\" stroke=\"black\" cx=\"270.393\" cy=\"-90\" rx=\"64.189\" ry=\"18\"/>\n",
       "<text text-anchor=\"middle\" x=\"270.393\" y=\"-86.3\" font-family=\"Courier,monospace\" font-size=\"14.00\">Sparse COO</text>\n",
       "</g>\n",
       "<!-- Dask array&#45;&gt;Sparse COO -->\n",
       "<g id=\"edge3\" class=\"edge\"><title>Dask array&#45;&gt;Sparse COO</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M205.876,-144.765C216.823,-135.642 230.668,-124.105 242.723,-114.059\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"245.284,-116.48 250.726,-107.39 240.803,-111.103 245.284,-116.48\"/>\n",
       "</g>\n",
       "<!-- NumPy masked array -->\n",
       "<g id=\"node5\" class=\"node\"><title>NumPy masked array</title>\n",
       "<ellipse fill=\"none\" stroke=\"black\" cx=\"497.393\" cy=\"-90\" rx=\"107.482\" ry=\"18\"/>\n",
       "<text text-anchor=\"middle\" x=\"497.393\" y=\"-86.3\" font-family=\"Courier,monospace\" font-size=\"14.00\">NumPy masked array</text>\n",
       "</g>\n",
       "<!-- Dask array&#45;&gt;NumPy masked array -->\n",
       "<g id=\"edge4\" class=\"edge\"><title>Dask array&#45;&gt;NumPy masked array</title>\n",
       "<path fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" d=\"M234.987,-150.062C286.262,-138.522 367.594,-120.215 426.124,-107.041\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"427.055,-110.419 436.043,-104.809 425.518,-103.59 427.055,-110.419\"/>\n",
       "</g>\n",
       "<!-- CuPy ndarray&#45;&gt;NumPy ndarray -->\n",
       "<g id=\"edge5\" class=\"edge\"><title>CuPy ndarray&#45;&gt;NumPy ndarray</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M126.043,-76.6465C174.571,-64.8104 247.927,-46.9187 300.028,-34.211\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"300.939,-37.5915 309.825,-31.8216 299.28,-30.7909 300.939,-37.5915\"/>\n",
       "</g>\n",
       "<!-- Sparse COO&#45;&gt;NumPy ndarray -->\n",
       "<g id=\"edge6\" class=\"edge\"><title>Sparse COO&#45;&gt;NumPy ndarray</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M291.731,-72.7646C303.952,-63.4665 319.469,-51.6599 332.847,-41.4806\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"335.013,-44.2305 340.852,-35.3898 330.775,-38.6596 335.013,-44.2305\"/>\n",
       "</g>\n",
       "<!-- NumPy masked array&#45;&gt;NumPy ndarray -->\n",
       "<g id=\"edge7\" class=\"edge\"><title>NumPy masked array&#45;&gt;NumPy ndarray</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M466.082,-72.7646C447.034,-62.8879 422.527,-50.1806 402.122,-39.5999\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"403.558,-36.402 393.069,-34.906 400.336,-42.6163 403.558,-36.402\"/>\n",
       "</g>\n",
       "<!-- Jax array -->\n",
       "<g id=\"node6\" class=\"node\"><title>Jax array</title>\n",
       "<ellipse fill=\"none\" stroke=\"black\" cx=\"583.393\" cy=\"-162\" rx=\"59.2899\" ry=\"18\"/>\n",
       "<text text-anchor=\"middle\" x=\"583.393\" y=\"-158.3\" font-family=\"Courier,monospace\" font-size=\"14.00\">Jax array</text>\n",
       "</g>\n",
       "<!-- Jax array&#45;&gt;NumPy ndarray -->\n",
       "<g id=\"edge8\" class=\"edge\"><title>Jax array&#45;&gt;NumPy ndarray</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M597.707,-144.223C612.335,-124.957 630.647,-93.2771 613.393,-72 592.658,-46.4286 512.161,-32.7163 447.843,-25.6941\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"447.982,-22.1895 437.671,-24.6237 447.25,-29.1511 447.982,-22.1895\"/>\n",
       "</g>\n",
       "<!-- Pint Quantity -->\n",
       "<g id=\"node7\" class=\"node\"><title>Pint Quantity</title>\n",
       "<ellipse fill=\"none\" stroke=\"black\" cx=\"387.393\" cy=\"-234\" rx=\"80.6858\" ry=\"18\"/>\n",
       "<text text-anchor=\"middle\" x=\"387.393\" y=\"-230.3\" font-family=\"Courier,monospace\" font-size=\"14.00\">Pint Quantity</text>\n",
       "</g>\n",
       "<!-- Pint Quantity&#45;&gt;Dask array -->\n",
       "<g id=\"edge9\" class=\"edge\"><title>Pint Quantity&#45;&gt;Dask array</title>\n",
       "<path fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" d=\"M345.746,-218.496C313.407,-207.234 268.515,-191.599 234.617,-179.794\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"235.518,-176.402 224.923,-176.418 233.216,-183.013 235.518,-176.402\"/>\n",
       "</g>\n",
       "<!-- Pint Quantity&#45;&gt;NumPy ndarray -->\n",
       "<g id=\"edge10\" class=\"edge\"><title>Pint Quantity&#45;&gt;NumPy ndarray</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M385.39,-215.849C381.065,-178.832 370.826,-91.1809 365.593,-46.3863\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"369.043,-45.7588 364.406,-36.2325 362.091,-46.5711 369.043,-45.7588\"/>\n",
       "</g>\n",
       "<!-- Pint Quantity&#45;&gt;CuPy ndarray -->\n",
       "<g id=\"edge11\" class=\"edge\"><title>Pint Quantity&#45;&gt;CuPy ndarray</title>\n",
       "<path fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" d=\"M313.751,-226.537C243.355,-219.009 143.6,-204.386 113.393,-180 94.4685,-164.722 84.7957,-138.263 79.9628,-118.154\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"83.371,-117.354 77.8533,-108.31 76.5264,-118.821 83.371,-117.354\"/>\n",
       "</g>\n",
       "<!-- Pint Quantity&#45;&gt;Sparse COO -->\n",
       "<g id=\"edge12\" class=\"edge\"><title>Pint Quantity&#45;&gt;Sparse COO</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M373.512,-216.153C353.018,-191.279 314.535,-144.574 290.817,-115.788\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"293.316,-113.317 284.256,-107.825 287.914,-117.768 293.316,-113.317\"/>\n",
       "</g>\n",
       "<!-- Pint Quantity&#45;&gt;NumPy masked array -->\n",
       "<g id=\"edge13\" class=\"edge\"><title>Pint Quantity&#45;&gt;NumPy masked array</title>\n",
       "<path fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" d=\"M400.444,-216.153C419.609,-191.413 455.504,-145.075 477.831,-116.253\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"480.66,-118.317 484.017,-108.268 475.126,-114.03 480.66,-118.317\"/>\n",
       "</g>\n",
       "<!-- xarray Dataset/DataArray/Variable -->\n",
       "<g id=\"node8\" class=\"node\"><title>xarray Dataset/DataArray/Variable</title>\n",
       "<ellipse fill=\"none\" stroke=\"black\" cx=\"387.393\" cy=\"-306\" rx=\"187.667\" ry=\"18\"/>\n",
       "<text text-anchor=\"middle\" x=\"387.393\" y=\"-302.3\" font-family=\"Courier,monospace\" font-size=\"14.00\">xarray Dataset/DataArray/Variable</text>\n",
       "</g>\n",
       "<!-- xarray Dataset/DataArray/Variable&#45;&gt;Dask array -->\n",
       "<g id=\"edge14\" class=\"edge\"><title>xarray Dataset/DataArray/Variable&#45;&gt;Dask array</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M335.932,-288.68C312.798,-279.919 285.922,-267.664 264.393,-252 239.936,-234.205 217.813,-207.445 203.428,-187.915\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"206.25,-185.844 197.568,-179.772 200.569,-189.933 206.25,-185.844\"/>\n",
       "</g>\n",
       "<!-- xarray Dataset/DataArray/Variable&#45;&gt;NumPy ndarray -->\n",
       "<g id=\"edge17\" class=\"edge\"><title>xarray Dataset/DataArray/Variable&#45;&gt;NumPy ndarray</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M445.846,-288.873C475.49,-279.738 511.635,-267.11 542.393,-252 594.504,-226.401 623.889,-231.131 651.393,-180 658.973,-165.909 653.554,-159.853 651.393,-144 646.908,-111.093 655.757,-94.57 631.393,-72 604.934,-47.4892 515.533,-33.4248 446.983,-26.0284\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"447.341,-22.5468 437.031,-24.985 446.611,-29.5086 447.341,-22.5468\"/>\n",
       "</g>\n",
       "<!-- xarray Dataset/DataArray/Variable&#45;&gt;CuPy ndarray -->\n",
       "<g id=\"edge15\" class=\"edge\"><title>xarray Dataset/DataArray/Variable&#45;&gt;CuPy ndarray</title>\n",
       "<path fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" d=\"M281.369,-291.128C212.822,-276.089 128.448,-244.835 84.3933,-180 72.1516,-161.984 70.6221,-136.994 71.7416,-118.08\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"75.2375,-118.278 72.6151,-108.013 68.2637,-117.673 75.2375,-118.278\"/>\n",
       "</g>\n",
       "<!-- xarray Dataset/DataArray/Variable&#45;&gt;Sparse COO -->\n",
       "<g id=\"edge16\" class=\"edge\"><title>xarray Dataset/DataArray/Variable&#45;&gt;Sparse COO</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M342.591,-288.285C325.913,-279.869 308.387,-267.987 297.393,-252 269.717,-211.751 267.068,-152.724 268.293,-118.445\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"271.799,-118.402 268.799,-108.241 264.808,-118.055 271.799,-118.402\"/>\n",
       "</g>\n",
       "<!-- xarray Dataset/DataArray/Variable&#45;&gt;NumPy masked array -->\n",
       "<g id=\"edge18\" class=\"edge\"><title>xarray Dataset/DataArray/Variable&#45;&gt;NumPy masked array</title>\n",
       "<path fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" d=\"M432.544,-288.519C449.273,-280.137 466.743,-268.218 477.393,-252 504.041,-211.424 503.873,-152.51 500.918,-118.34\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"504.378,-117.768 499.891,-108.17 497.414,-118.472 504.378,-117.768\"/>\n",
       "</g>\n",
       "<!-- xarray Dataset/DataArray/Variable&#45;&gt;Jax array -->\n",
       "<g id=\"edge20\" class=\"edge\"><title>xarray Dataset/DataArray/Variable&#45;&gt;Jax array</title>\n",
       "<path fill=\"none\" stroke=\"black\" stroke-dasharray=\"5,2\" d=\"M440.005,-288.657C462.977,-279.982 489.402,-267.804 510.393,-252 533.791,-234.384 554.324,-207.77 567.604,-188.233\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"570.577,-190.082 573.179,-179.812 564.74,-186.218 570.577,-190.082\"/>\n",
       "</g>\n",
       "<!-- xarray Dataset/DataArray/Variable&#45;&gt;Pint Quantity -->\n",
       "<g id=\"edge19\" class=\"edge\"><title>xarray Dataset/DataArray/Variable&#45;&gt;Pint Quantity</title>\n",
       "<path fill=\"none\" stroke=\"black\" d=\"M387.393,-287.697C387.393,-279.983 387.393,-270.712 387.393,-262.112\"/>\n",
       "<polygon fill=\"black\" stroke=\"black\" points=\"390.893,-262.104 387.393,-252.104 383.893,-262.104 390.893,-262.104\"/>\n",
       "</g>\n",
       "</g>\n",
       "</svg>\n"
      ],
      "text/plain": [
       "<graphviz.dot.Digraph at 0x7f68cc084208>"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from graphviz import Digraph\n",
    "\n",
    "g = Digraph(graph_attr={'size': '8,5'}, node_attr={'fontname': 'courier'})\n",
    "g.edge('Dask array', 'NumPy ndarray')\n",
    "g.edge('Dask array', 'CuPy ndarray')\n",
    "g.edge('Dask array', 'Sparse COO')\n",
    "g.edge('Dask array', 'NumPy masked array', style='dashed')\n",
    "g.edge('CuPy ndarray', 'NumPy ndarray')\n",
    "g.edge('Sparse COO', 'NumPy ndarray')\n",
    "g.edge('NumPy masked array', 'NumPy ndarray')\n",
    "g.edge('Jax array', 'NumPy ndarray')\n",
    "g.edge('Pint Quantity', 'Dask array', style='dashed')\n",
    "g.edge('Pint Quantity', 'NumPy ndarray')\n",
    "g.edge('Pint Quantity', 'CuPy ndarray', style='dashed')\n",
    "g.edge('Pint Quantity', 'Sparse COO')\n",
    "g.edge('Pint Quantity', 'NumPy masked array', style='dashed')\n",
    "g.edge('xarray Dataset/DataArray/Variable', 'Dask array')\n",
    "g.edge('xarray Dataset/DataArray/Variable', 'CuPy ndarray', style='dashed')\n",
    "g.edge('xarray Dataset/DataArray/Variable', 'Sparse COO')\n",
    "g.edge('xarray Dataset/DataArray/Variable', 'NumPy ndarray')\n",
    "g.edge('xarray Dataset/DataArray/Variable', 'NumPy masked array', style='dashed')\n",
    "g.edge('xarray Dataset/DataArray/Variable', 'Pint Quantity')\n",
    "g.edge('xarray Dataset/DataArray/Variable', 'Jax array', style='dashed')\n",
    "g"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Examples\n",
    "\n",
    "**xarray wrapping Pint Quantity**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<xarray.DataArray 'air' (lat: 25, lon: 53)>\n",
      "<Quantity([[241.2     242.5     243.5     ... 232.79999 235.5     238.59999]\n",
      " [243.79999 244.5     244.7     ... 232.79999 235.29999 239.29999]\n",
      " [250.      249.79999 248.89    ... 233.2     236.39    241.7    ]\n",
      " ...\n",
      " [296.6     296.19998 296.4     ... 295.4     295.1     294.69998]\n",
      " [295.9     296.19998 296.79    ... 295.9     295.9     295.19998]\n",
      " [296.29    296.79    297.1     ... 296.9     296.79    296.6    ]], 'kelvin')>\n",
      "Coordinates:\n",
      "  * lat      (lat) float32 75.0 72.5 70.0 67.5 65.0 ... 25.0 22.5 20.0 17.5 15.0\n",
      "  * lon      (lon) float32 200.0 202.5 205.0 207.5 ... 322.5 325.0 327.5 330.0\n",
      "    time     datetime64[ns] 2013-01-01\n",
      "Attributes:\n",
      "    long_name:     4xDaily Air temperature at sigma level 995\n",
      "    precision:     2\n",
      "    GRIB_id:       11\n",
      "    GRIB_name:     TMP\n",
      "    var_desc:      Air temperature\n",
      "    dataset:       NMC Reanalysis\n",
      "    level_desc:    Surface\n",
      "    statistic:     Individual Obs\n",
      "    parent_stat:   Other\n",
      "    actual_range:  [185.16 322.1 ]\n",
      "\n",
      "<xarray.DataArray 'air' ()>\n",
      "<Quantity(302.6000061035156, 'kelvin')>\n",
      "Coordinates:\n",
      "    time     datetime64[ns] 2013-01-01\n"
     ]
    }
   ],
   "source": [
    "import xarray as xr\n",
    "\n",
    "# Load tutorial data\n",
    "air = xr.tutorial.load_dataset('air_temperature')['air'][0]\n",
    "\n",
    "# Convert to Quantity\n",
    "air.data = Q_(air.data, air.attrs.pop('units', ''))\n",
    "\n",
    "print(air)\n",
    "print()\n",
    "print(air.max())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Pint Quantity wrapping Sparse COO**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<COO: shape=(100, 100, 100), dtype=float64, nnz=99598, fill_value=0.0> meter\n",
      "\n",
      "0.09462606529121113 meter\n"
     ]
    }
   ],
   "source": [
    "from sparse import COO\n",
    "\n",
    "np.random.seed(80243963)\n",
    "\n",
    "x = np.random.random((100, 100, 100))\n",
    "x[x < 0.9] = 0  # fill most of the array with zeros\n",
    "s = COO(x)\n",
    "\n",
    "q = s * ureg.m\n",
    "\n",
    "print(q)\n",
    "print()\n",
    "print(np.mean(q))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Pint Quantity wrapping NumPy Masked Array**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<Quantity([2 -- 5 --], 'meter')>\n",
      "\n",
      "masked_array(data=[<Quantity(2, 'meter')>, --, <Quantity(5, 'meter')>, --],\n",
      "             mask=[False,  True, False,  True],\n",
      "       fill_value='?',\n",
      "            dtype=object)\n"
     ]
    }
   ],
   "source": [
    "m = np.ma.masked_array([2, 3, 5, 7], mask=[False, True, False, True])\n",
    "\n",
    "# Must create using Quantity class\n",
    "print(repr(ureg.Quantity(m, 'm')))\n",
    "print()\n",
    "\n",
    "# DO NOT create using multiplication until\n",
    "# https://github.com/numpy/numpy/issues/15200 is resolved, as\n",
    "# unexpected behavior may result\n",
    "print(repr(m * ureg.m))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**xarray wrapping Pint Quantity wrapping Dask array wrapping Sparse COO**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<xarray.DataArray 'test' (z: 100, y: 100, x: 100)>\n",
      "<Quantity(dask.array<COO, shape=(100, 100, 100), dtype=float64, chunksize=(100, 1, 1), chunktype=sparse.COO>, 'meter')>\n",
      "Coordinates:\n",
      "  * z        (z) int64 0 1 2 3 4 5 6 7 8 9 10 ... 90 91 92 93 94 95 96 97 98 99\n",
      "  * y        (y) int64 -50 -49 -48 -47 -46 -45 -44 -43 ... 43 44 45 46 47 48 49\n",
      "  * x        (x) float64 -20.0 -18.5 -17.0 -15.5 ... 124.0 125.5 127.0 128.5\n",
      "\n",
      "<xarray.DataArray 'test' ()>\n",
      "<Quantity(dask.array<mean_agg-aggregate, shape=(), dtype=float64, chunksize=(), chunktype=numpy.ndarray>, 'meter')>\n",
      "Coordinates:\n",
      "    y        int64 -46\n",
      "    x        float64 125.5\n"
     ]
    }
   ],
   "source": [
    "import dask.array as da\n",
    "\n",
    "x = da.random.random((100, 100, 100), chunks=(100, 1, 1))\n",
    "x[x < 0.95] = 0\n",
    "\n",
    "data = xr.DataArray(\n",
    "    Q_(x.map_blocks(COO), 'm'),\n",
    "    dims=('z', 'y', 'x'),\n",
    "    coords={\n",
    "        'z': np.arange(100),\n",
    "        'y': np.arange(100) - 50,\n",
    "        'x': np.arange(100) * 1.5 - 20\n",
    "    },\n",
    "    name='test'\n",
    ")\n",
    "\n",
    "print(data)\n",
    "print()\n",
    "print(data.sel(x=125.5, y=-46).mean())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Compatibility Packages\n",
    "\n",
    "To aid in integration between various array types and Pint (such as by providing convenience methods), the following compatibility packages are available:\n",
    "\n",
    "- [pint-pandas](https://github.com/hgrecco/pint-pandas)\n",
    "- pint-xarray ([in development](https://github.com/hgrecco/pint/issues/849), initial alpha release planned for January 2020)\n",
    "\n",
    "(Note: if you have developed a compatibility package for Pint, please submit a pull request to add it to this list!)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Additional Comments\n",
    "\n",
    "What follows is a short discussion about how NumPy support is implemented in Pint's `Quantity` Object.\n",
    "\n",
    "For the supported functions, Pint expects certain units and attempts to convert the input (or inputs). For example, the argument of the exponential function (`numpy.exp`) must be dimensionless. Units will be simplified (converting the magnitude appropriately) and `numpy.exp` will be applied to the resulting magnitude. If the input is not dimensionless, a `DimensionalityError` exception will be raised.\n",
    "\n",
    "In some functions that take 2 or more arguments (e.g. `arctan2`), the second argument is converted to the units of the first. Again, a `DimensionalityError` exception will be raised if this is not possible. ndarray or downcast type arguments are generally treated as if they were dimensionless quantities, whereas Pint defers to its declared upcast types by always returning `NotImplemented` when they are encountered (see above).\n",
    "\n",
    "To achive these function and ufunc overrides, Pint uses the ``__array_function__`` and ``__array_ufunc__`` protocols respectively, as recommened by NumPy. This means that functions and ufuncs that Pint does not explicitly handle will error, rather than return a value with units stripped (in contrast to Pint's behavior prior to v0.10). For more\n",
    "information on these protocols, see <https://docs.scipy.org/doc/numpy-1.17.0/user/basics.dispatch.html>.\n",
    "\n",
    "This behaviour introduces some performance penalties and increased memory usage. Quantities that must be converted to other units require additional memory and CPU cycles. Therefore, for numerically intensive code, you might want to convert the objects first and then use directly the magnitude, such as by using Pint's `wraps` utility (see [wrapping](wrapping.rst)).\n",
    "\n",
    "Array interface protocol attributes (such as `__array_struct__` and\n",
    "`__array_interface__`) are available on Pint Quantities by deferring to the corresponding `__array_*` attribute on the magnitude as casted to an ndarray. This has been found to be potentially incorrect and to cause unexpected behavior, and has therefore been deprecated. As of the next minor version of Pint (or when the `PINT_ARRAY_PROTOCOL_FALLBACK` environment variable is set to 0 prior to importing Pint as done at the beginning of this page), attempting to access these attributes will instead raise an AttributeError."
   ]
  }
 ],
 "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.6.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}