{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# `uarray`: A Generic Override Framework for Methods\n",
"\n",
"`uarray` is an override framework for methods in Python. In the scientific Python ecosystem, and in other similar places, there has been one recurring problem: That similar tools to do a job have existed, but don't conform to a single, well-defined API. `uarray` tries to solve this problem in general, but also for the scientific Python ecosystem in particular, by defining APIs independent of their implementations.\n",
"\n",
"## Array Libraries in the Scientific Python Ecosystem\n",
"When SciPy was created, and Numeric and Numarray unified into NumPy, it jump-started Python's data science community. The ecosystem grew quickly: Academics started moving to SciPy, and the Scikits that popped up made the transition all the more smooth.\n",
"\n",
"However, the scientific Python community also shifted during that time: GPUs and distributed computing emerged. Also, there were old ideas that couldn't really be used with NumPy's API, such as sparse arrays. To solve these problems, various libraries emerged:\n",
"\n",
"- Dask, for distributed NumPy\n",
"- CuPy, for NumPy on Nvidia-branded GPUs.\n",
"- PyData/Sparse, a project started to make sparse arrays conform to the NumPy API\n",
"- Xnd, which extends the type system and the universal function concept found in NumPy\n",
"\n",
"\n",
"\n",
"There were yet other libraries that emerged: PyTorch, which mimics NumPy to a certain degree; TensorFlow, which defines its own API; and MXNet, which is another deep learning framework that mimics NumPy.\n",
"\n",
"## The Problem\n",
"The problem is, stated simply: How do we use all of these libraries in tandem, moving seamlessly from one to the other, without actually changing the API, or even the imports? How do we take functions written for one library and allow it to be used by another, without, as Travis Oliphant so eloquently puts it, \"re-writing the world\"?\n",
"\n",
"In my mind, the goals are (stated abstractly):\n",
"\n",
"1. Methods that are not tied to a specific implementation.\n",
" * For example `np.arange`\n",
"2. Backends that implement these methods.\n",
" * NumPy, Dask, PyTorch are all examples of this.\n",
"3. Coercion of objects to other forms to move between backends.\n",
" * This means converting a NumPy array to a Dask array, and vice versa.\n",
"\n",
"In addition, we wanted to be able to do this for arbitrary objects. So `dtype`s, `ufunc`s etc. should also be dispatchable and coercible.\n",
"\n",
"## The Solution?\n",
"With that said, let's dive into `uarray`. If you're not interested in the gory details, you can jump down to this section."
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [],
"source": [
"import uarray as ua\n",
"\n",
"# Let's ignore this for now\n",
"def myfunc_rd(a, kw, d):\n",
" return a, kw\n",
"\n",
"# We define a multimethod\n",
"@ua.create_multimethod(myfunc_rd)\n",
"def myfunc():\n",
" return () # Let's also ignore this for now\n",
"\n",
"\n",
"# Now let's define two backends!\n",
"be1 = ua.Backend()\n",
"be2 = ua.Backend()\n",
"\n",
"# And register their implementations for the method!\n",
"@ua.register_implementation(myfunc, backend=be1)\n",
"def myfunc_be1(): # Note that it has exactly the same signature\n",
" return \"Potato\"\n",
"\n",
"@ua.register_implementation(myfunc, backend=be2)\n",
"def myfunc_be2(): # Note that it has exactly the same signature\n",
" return \"Strawberry\""
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Potato\n"
]
}
],
"source": [
"with ua.set_backend(be1):\n",
" print(myfunc())"
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Strawberry\n"
]
}
],
"source": [
"with ua.set_backend(be2):\n",
" print(myfunc())"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"As we can clearly see: We have already provided a way to do (1) and (2) above. But then we run across the problem: How do we decide between these backends? How do we move between them? Let's go ahead and register both of these backends for permanent use. And see what happens when we want to implement both of their methods!"
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {},
"outputs": [],
"source": [
"ua.register_backend(be1)\n",
"ua.register_backend(be2)"
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Potato\n"
]
}
],
"source": [
"print(myfunc())"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"As we see, we get only the first backend's answer. In general, it's indeterminate what backend will be selected. But, this is a special case: We're not passing arguments in! What if we change one of these to return `NotImplemented`?"
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {},
"outputs": [],
"source": [
"# We redefine the multimethod so it's new again\n",
"@ua.create_multimethod(myfunc_rd)\n",
"def myfunc():\n",
" return ()\n",
"\n",
"\n",
"# Now let's redefine the two backends!\n",
"be1 = ua.Backend()\n",
"be2 = ua.Backend()\n",
"\n",
"# And register their implementations for the method!\n",
"@ua.register_implementation(myfunc, backend=be1)\n",
"def myfunc_be1(): # Note that it has exactly the same signature\n",
" return NotImplemented\n",
"\n",
"@ua.register_implementation(myfunc, backend=be2)\n",
"def myfunc_be2(): # Note that it has exactly the same signature\n",
" return \"Strawberry\"\n",
"\n",
"ua.register_backend(be1)\n",
"ua.register_backend(be2)"
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Strawberry\n"
]
}
],
"source": [
"with ua.set_backend(be1):\n",
" print(myfunc())"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Wait... What? Didn't we just set the first `Backend`? Ahh, but, you see... It's signalling that it has *no* implementation for `myfunc`. The same would happen if you simply didn't register one. To force a `Backend`, we must use `only=True` or `coerce=True`, the difference will be explained in just a moment."
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {},
"outputs": [
{
"ename": "BackendNotImplementedError",
"evalue": "No selected backends had an implementation for this method.",
"output_type": "error",
"traceback": [
"\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
"\u001b[0;31mBackendNotImplementedError\u001b[0m Traceback (most recent call last)",
"\u001b[0;32m\u001b[0m in \u001b[0;36m\u001b[0;34m\u001b[0m\n\u001b[1;32m 1\u001b[0m \u001b[0;32mwith\u001b[0m \u001b[0mua\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mset_backend\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mbe1\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0monly\u001b[0m\u001b[0;34m=\u001b[0m\u001b[0;32mTrue\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 2\u001b[0;31m \u001b[0mprint\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mmyfunc\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
"\u001b[0;32m~/Quansight/uarray/uarray/backend.py\u001b[0m in \u001b[0;36m__call__\u001b[0;34m(self, *args, **kwargs)\u001b[0m\n\u001b[1;32m 108\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m 109\u001b[0m \u001b[0;32mif\u001b[0m \u001b[0mresult\u001b[0m \u001b[0;32mis\u001b[0m \u001b[0mNotImplemented\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m--> 110\u001b[0;31m \u001b[0;32mraise\u001b[0m \u001b[0mBackendNotImplementedError\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m'No selected backends had an implementation for this method.'\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m 111\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m 112\u001b[0m \u001b[0;32mreturn\u001b[0m \u001b[0mresult\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
"\u001b[0;31mBackendNotImplementedError\u001b[0m: No selected backends had an implementation for this method."
]
}
],
"source": [
"with ua.set_backend(be1, only=True):\n",
" print(myfunc())"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now we are told that no backends had an implementation for this function (which is nice, good error messages are nice!)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Coercion and passing between backends\n",
"Let's say we had two `Backend`s. Let's choose the completely useless example of one storing a number as an `int` and one as a `float`."
]
},
{
"cell_type": "code",
"execution_count": 9,
"metadata": {},
"outputs": [],
"source": [
"class Number(ua.DispatchableInstance):\n",
" pass\n",
"\n",
"def myfunc_rd(args, kwargs, dispatchable_args):\n",
" # Here, we're \"replacing\" the dispatchable args with the ones supplied.\n",
" # In general, this may be more complex, like inserting them in between\n",
" # other args and kwargs.\n",
" return dispatchable_args, kwargs\n",
"\n",
"@ua.create_multimethod(myfunc_rd)\n",
"def myfunc(a):\n",
" # Here, we're marking a as a Number, and saying that \"we want to dispatch/convert over this\"\n",
" # We return as a tuple as there may be more dispatchable arguments\n",
" return (Number(a),)\n",
"\n",
"\n",
"Number.register_convertor(be1, lambda x: int(x))\n",
"Number.register_convertor(be2, lambda x: str(x))"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Let's also define a \"catch-all\" method. This catches all implementations of methods not already registered."
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {},
"outputs": [],
"source": [
"# This can be arbitrarily complex\n",
"def gen_impl1(method, args, kwargs, dispatchable_args):\n",
" if not all(isinstance(a, Number) and isinstance(a.value, int) for a in dispatchable_args):\n",
" return NotImplemented\n",
" \n",
" return args[0]\n",
"\n",
"# This can be arbitrarily complex\n",
"def gen_impl2(method, args, kwargs, dispatchable_args):\n",
" if not all(isinstance(a, Number) and isinstance(a.value, str) for a in dispatchable_args):\n",
" return NotImplemented\n",
" \n",
" return args[0]\n",
"\n",
"be1.register_implementation(None, gen_impl1)\n",
"be2.register_implementation(None, gen_impl2)"
]
},
{
"cell_type": "code",
"execution_count": 11,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"'1'"
]
},
"execution_count": 11,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"myfunc('1') # This calls the second implementation"
]
},
{
"cell_type": "code",
"execution_count": 12,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"1"
]
},
"execution_count": 12,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"myfunc(1) # This calls the first implementation"
]
},
{
"cell_type": "code",
"execution_count": 13,
"metadata": {},
"outputs": [
{
"ename": "BackendNotImplementedError",
"evalue": "No selected backends had an implementation for this method.",
"output_type": "error",
"traceback": [
"\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
"\u001b[0;31mBackendNotImplementedError\u001b[0m Traceback (most recent call last)",
"\u001b[0;32m\u001b[0m in \u001b[0;36m\u001b[0;34m\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0mmyfunc\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;36m1.0\u001b[0m\u001b[0;34m)\u001b[0m \u001b[0;31m# This fails\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
"\u001b[0;32m~/Quansight/uarray/uarray/backend.py\u001b[0m in \u001b[0;36m__call__\u001b[0;34m(self, *args, **kwargs)\u001b[0m\n\u001b[1;32m 108\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m 109\u001b[0m \u001b[0;32mif\u001b[0m \u001b[0mresult\u001b[0m \u001b[0;32mis\u001b[0m \u001b[0mNotImplemented\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m--> 110\u001b[0;31m \u001b[0;32mraise\u001b[0m \u001b[0mBackendNotImplementedError\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m'No selected backends had an implementation for this method.'\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m 111\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m 112\u001b[0m \u001b[0;32mreturn\u001b[0m \u001b[0mresult\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
"\u001b[0;31mBackendNotImplementedError\u001b[0m: No selected backends had an implementation for this method."
]
}
],
"source": [
"myfunc(1.0) # This fails"
]
},
{
"cell_type": "code",
"execution_count": 14,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n",
"\n"
]
}
],
"source": [
"# But works if we do this:\n",
"\n",
"with ua.set_backend(be1, coerce=True):\n",
" print(type(myfunc(1.0)))\n",
"\n",
"with ua.set_backend(be2, coerce=True):\n",
" print(type(myfunc(1.0)))"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"This may seem like too much work, but remember that it's broken down into a lot of small steps:\n",
"\n",
"1. Extract the dispatchable arguments.\n",
"2. Realise the types of the dispatchable arguments.\n",
"3. Convert them.\n",
"4. Place them back into args/kwargs\n",
"5. Call the right function.\n",
"\n",
"Note that `only=True` does not coerce, just enforces the backend strictly."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"With this, we have solved problem (3). Now remains the grunt-work of actually retrofitting the NumPy API into `unumpy` and extracting the right values from it."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## How To Use It Today\n",
"\n",
"`unumpy` is a set of NumPy-related multimethods built on top of `uarray`. You can use them as follows:"
]
},
{
"cell_type": "code",
"execution_count": 15,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"\n"
]
}
],
"source": [
"import unumpy as np # Note the changed import statement\n",
"from unumpy.xnd_backend import XndBackend\n",
"\n",
"with ua.set_backend(XndBackend):\n",
" print(type(np.arange(0, 100, 1)))"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"And, as you can see, we get back an Xnd array when using a NumPy-like API. Currently, there are three back-ends: NumPy, Xnd and PyTorch. The NumPy and Xnd backends have feature parity, while the PyTorch backend is still being worked on.\n",
"\n",
"We are also working on supporting more of the NumPy API, and dispatching over dtypes.\n",
"\n",
"Feel free to browse the source and open issues at: https://github.com/Quansight-Labs/uarray or shoot me an email at habbasi@quansight.com if you want to contact me directly. You can also find the full documentation at https://uarray.readthedocs.io/en/latest/."
]
}
],
"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.9.10"
},
"nikola": {
"author": "Hameer Abbasi",
"date": "2019-04-30 00:04:40 CEST",
"slug": "uarray-intro",
"tags": "uarray, NumPy",
"title": "uarray: A Generic Override Framework for Methods"
}
},
"nbformat": 4,
"nbformat_minor": 2
}