Debian Codegraph @

docs/index.md

raw
1 # Welcome to autoray's documentation!
2
3 [![tests](https://github.com/jcmgray/autoray/actions/workflows/tests.yml/badge.svg)](https://github.com/jcmgray/autoray/actions/workflows/tests.yml)
4 [![codecov](https://codecov.io/gh/jcmgray/autoray/branch/main/graph/badge.svg?token=Q5evNiuT9S)](https://codecov.io/gh/jcmgray/autoray)
5 [![Codacy Badge](https://app.codacy.com/project/badge/Grade/ba896d74c4954dd58da01df30c7bf326)](https://app.codacy.com/gh/jcmgray/autoray/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
6 [![Docs](https://readthedocs.org/projects/autoray/badge/?version=latest)](https://autoray.readthedocs.io)
7 [![PyPI](https://img.shields.io/pypi/v/autoray?color=teal)](https://pypi.org/project/autoray/)
8 [![Anaconda-Server Badge](https://anaconda.org/conda-forge/autoray/badges/version.svg)](https://anaconda.org/conda-forge/autoray)
9
10 [`autoray`](autoray) is a lightweight python AUTOmatic-arRAY library for
11 abstracting your tensor operations. Primarily it provides an
12 [*automatic* dispatch mechanism](automatic_dispatch) that means you can
13 write backend agnostic code that works for:
14
15 * [numpy](https://github.com/numpy/numpy)
16 * [pytorch](https://pytorch.org/)
17 * [jax](https://github.com/google/jax)
18 * [cupy](https://github.com/cupy/cupy)
19 * [dask](https://github.com/dask/dask)
20 * [autograd](https://github.com/HIPS/autograd)
21 * [tensorflow](https://github.com/tensorflow/tensorflow)
22 * [sparse](https://sparse.pydata.org/)
23 * [paddle](https://github.com/paddlepaddle/paddle)
24 * [mars](https://github.com/mars-project/mars)
25 * ... and indeed **any** library that provides a numpy-*ish* api, even if it
26 knows nothing about `autoray`.
27
28 Beyond that, abstracting the array interface allows you to:
29
30 * *swap [custom versions of functions](automatic_dispatch.md#functions)
31 for specific backends*
32 * *trace through computations [lazily](lazy_computation) without actually
33 running them*
34 * *automatically [share intermediates and fold constants](lazy_computation)
35 in computations*
36 * *compile functions with a [unified interface](compilation) for different
37 backends*
38
39
40 ## Basic usage
41
42 The main function of `autoray` is [`do`](autoray.do), which takes a function
43 name followed by `*args` and `**kwargs`, and automatically looks up (and
44 caches) the correct function to match the equivalent numpy call:
45
46 ```python
47 import autoray as ar
48
49 def noised_svd(x):
50 # automatic dispatch based on supplied array
51 U, s, VH = ar.do('linalg.svd', x)
52
53 # automatic dispatch based on different array
54 sn = s + 0.1 * ar.do('random.normal', size=ar.shape(s), like=s)
55
56 # automatic dispatch for multiple arrays for certain functions
57 return ar.do('einsum', 'ij,j,jk->ik', U, sn, VH)
58
59 # explicit backend given by string
60 x = ar.do('random.uniform', size=(100, 100), like="torch")
61
62 # this function now works for any backend
63 y = noised_svd(x)
64
65 # explicit inference of backend from array
66 ar.infer_backend(y)
67 # 'torch'
68 ```
69
70 If you don't like the explicit [`do`](autoray.do) syntax, or simply want a
71 drop-in replacement for existing code, you can also import the `autoray.numpy`
72 module:
73
74 ```{code-block} python
75 from autoray import numpy as np
76
77 # set a temporary default backend
78 with ar.backend_like('cupy'):
79 z = np.ones((3, 4), dtype='float32')
80
81 np.exp(z)
82 # array([[2.7182817, 2.7182817, 2.7182817, 2.7182817],
83 # [2.7182817, 2.7182817, 2.7182817, 2.7182817],
84 # [2.7182817, 2.7182817, 2.7182817, 2.7182817]], dtype=float32)
85 ```
86
87 Alternatively you can use `autoray.get_namespace` to get a backend specific
88 (with optional default device and dtype) namespace object, (c.f. the Python
89 Array Api):
90
91 ```python
92 xp = ar.get_namespace(z)
93 xp.einsum("ii->i", z)
94 ```
95
96 Custom backends and functions can be dynamically registered with:
97
98 * [`register_backend`](autoray.register_backend)
99 * [`register_function`](autoray.register_function)
100
101 ---
102
103 ## Advanced details
104
105 ```{toctree}
106 :caption: Guides
107 :maxdepth: 2
108
109 installation.md
110 automatic_dispatch.md
111 lazy_computation.ipynb
112 compilation.ipynb
113 development.md
114 ```
115
116 ```{toctree}
117 :caption: Links
118 :hidden:
119
120 GitHub Repository <https://github.com/jcmgray/autoray>
121 ```