Accelerated UFuncs
==================

.. raw:: html

    <p>Variants of some Numpy UFuncs that use Intel&#8217;s Vector Math Library (VML) are
    found in the <code class="docutils literal"><span class="pre">accelerate.mkl</span></code> package in the <code class="docutils literal"><span class="pre">ufuncs</span></code> object. In comparison
    to Numpy&#8217;s built-in UFuncs, Accelerated UFuncs have the following properties:</p>
    <dl class="docutils">
    <dt><em>Performance</em></dt>
    <dd>Because Accelerated UFuncs call functions from VML, which is a library
    optimised for high performance using multiple threads and SIMD instructions,
    performance may be increased when calling Accelerated UFuncs in comparison to
    calling Numpy UFuncs. The performance increase will only be obtained for
    contiguous arguments. For non-contiguous arguments, performance comparable to
    Numpy&#8217;s will be observed.</dd>
    <dt><em>Accuracy</em></dt>
    <dd><ul class="first last simple">
    <li>Accelerated UFuncs produce similar results to their Numpy equivalents for
    the range of finite values, up to a given relative tolerance.</li>
    <li>The tolerance varies between functions and data types, and is specified for
    each combination in the following section.</li>
    <li>For the range of infinite and NaN values, the majority of results computed
    by Accelerated UFuncs will be equal to those computed by their Numpy
    counterparts. However, this is not guaranteed; for example, an input for
    which the Numpy UFunc produces a result of <code class="docutils literal"><span class="pre">x</span> <span class="pre">+</span> <span class="pre">inf*j</span></code>, the equivalent
    Accelerated UFunc may produce a result of <code class="docutils literal"><span class="pre">y</span> <span class="pre">+</span> <span class="pre">inf*j</span></code>, where <code class="docutils literal"><span class="pre">x</span> <span class="pre">!=</span> <span class="pre">y</span></code>.</li>
    <li>Towards the edge of the domain of a data type (e.g. near <code class="docutils literal"><span class="pre">3.4e+38</span></code> for
    <code class="docutils literal"><span class="pre">float</span></code> and <code class="docutils literal"><span class="pre">1.79e+308</span></code> for <code class="docutils literal"><span class="pre">double</span></code> and values of similar magnitude
    at the negative end of the domain) some Accelerated UFuncs may produce
    results which differ from Numpy UFuncs, or may raise <code class="docutils literal"><span class="pre">FloatingPointError</span></code>
    or <code class="docutils literal"><span class="pre">ZeroDivisionError</span></code> exceptions. These functions are marked <cite>domain
    edge warning</cite> in the <cite>Accuracy</cite> column of the tables in the following
    sections.</li>
    <li>Denormal input values may be treated as zero by Accelerated UFuncs, and
    denormal output values may be flushed to zero.</li>
    </ul>
    </dd>
    <dt><em>Exception handling</em></dt>
    <dd>For the range of finite values, exceptions will not be raised by Accelerated
    UFuncs, just as they would not by Numpy. For the infinite and NaN ranges,
    Accelerated UFuncs may raise <code class="docutils literal"><span class="pre">FloatingPointError</span></code> or <code class="docutils literal"><span class="pre">ZeroDivisionError</span></code>
    exceptions in cases when Numpy would not, and vice-versa.</dd>
    </dl>
    <p>Supported functions are described in the following sections.</p>
    <div class="section" id="arithmetic-functions">
    <h2>Arithmetic Functions<a class="headerlink" href="#arithmetic-functions" title="Permalink to this headline">¶</a></h2>
    <table border="1" class="docutils">
    <colgroup>
    <col width="32%" />
    <col width="12%" />
    <col width="56%" />
    </colgroup>
    <thead valign="bottom">
    <tr class="row-odd"><th class="head">Function</th>
    <th class="head">Type</th>
    <th class="head">Accuracy</th>
    </tr>
    </thead>
    <tbody valign="top">
    <tr class="row-even"><td rowspan="4"><code class="docutils literal"><span class="pre">add(x,</span> <span class="pre">y)</span></code></td>
    <td><code class="docutils literal"><span class="pre">f4</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.0e-7</span></code></td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">f8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.0e-15</span></code></td>
    </tr>
    <tr class="row-even"><td><code class="docutils literal"><span class="pre">c8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.0e-7</span></code></td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">c16</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.0e-15</span></code></td>
    </tr>
    <tr class="row-even"><td rowspan="4"><code class="docutils literal"><span class="pre">subtract(x,</span> <span class="pre">y)</span></code></td>
    <td><code class="docutils literal"><span class="pre">f4</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-7</span></code></td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">f8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-15</span></code></td>
    </tr>
    <tr class="row-even"><td><code class="docutils literal"><span class="pre">c8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-7</span></code></td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">c16</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-15</span></code></td>
    </tr>
    <tr class="row-even"><td rowspan="2"><code class="docutils literal"><span class="pre">square(x)</span></code></td>
    <td><code class="docutils literal"><span class="pre">f4</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-7</span></code></td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">f8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-15</span></code></td>
    </tr>
    <tr class="row-even"><td rowspan="4"><code class="docutils literal"><span class="pre">multiply(x,</span> <span class="pre">y)</span></code></td>
    <td><code class="docutils literal"><span class="pre">f4</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-7</span></code></td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">f8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-15</span></code></td>
    </tr>
    <tr class="row-even"><td><code class="docutils literal"><span class="pre">c8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-6</span></code></td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">c16</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-15</span></code></td>
    </tr>
    <tr class="row-even"><td rowspan="2"><code class="docutils literal"><span class="pre">absolute(x)</span></code></td>
    <td><code class="docutils literal"><span class="pre">f4</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-6</span></code></td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">f8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-15</span></code></td>
    </tr>
    </tbody>
    </table>
    </div>
    <div class="section" id="power-and-root-functions">
    <h2>Power and Root Functions<a class="headerlink" href="#power-and-root-functions" title="Permalink to this headline">¶</a></h2>
    <table border="1" class="docutils">
    <colgroup>
    <col width="32%" />
    <col width="12%" />
    <col width="56%" />
    </colgroup>
    <thead valign="bottom">
    <tr class="row-odd"><th class="head">Function</th>
    <th class="head">Type</th>
    <th class="head">Accuracy</th>
    </tr>
    </thead>
    <tbody valign="top">
    <tr class="row-even"><td rowspan="2"><code class="docutils literal"><span class="pre">reciprocal(x)</span></code></td>
    <td><code class="docutils literal"><span class="pre">f4</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-7</span></code></td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">f8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-15</span></code></td>
    </tr>
    <tr class="row-even"><td rowspan="4"><code class="docutils literal"><span class="pre">true_divide(x,</span> <span class="pre">y)</span></code></td>
    <td><code class="docutils literal"><span class="pre">f4</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-7</span></code></td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">f8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-15</span></code></td>
    </tr>
    <tr class="row-even"><td><code class="docutils literal"><span class="pre">c8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-7</span></code></td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">c16</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-15</span></code></td>
    </tr>
    <tr class="row-even"><td rowspan="4"><code class="docutils literal"><span class="pre">sqrt(x,</span> <span class="pre">y)</span></code></td>
    <td><code class="docutils literal"><span class="pre">f4</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-6</span></code></td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">f8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-15</span></code></td>
    </tr>
    <tr class="row-even"><td><code class="docutils literal"><span class="pre">c8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-6</span></code>, domain edge warning</td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">c16</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-15</span></code>, domain edge warning</td>
    </tr>
    <tr class="row-even"><td rowspan="2"><code class="docutils literal"><span class="pre">power(x,</span> <span class="pre">y)</span></code></td>
    <td><code class="docutils literal"><span class="pre">f4</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-7</span></code></td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">f8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-15</span></code></td>
    </tr>
    <tr class="row-even"><td rowspan="2"><code class="docutils literal"><span class="pre">hypot(x,</span> <span class="pre">y)</span></code></td>
    <td><code class="docutils literal"><span class="pre">f4</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-7</span></code></td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">f8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-15</span></code></td>
    </tr>
    </tbody>
    </table>
    </div>
    <div class="section" id="exponential-and-logarithmic-functions">
    <h2>Exponential and Logarithmic Functions<a class="headerlink" href="#exponential-and-logarithmic-functions" title="Permalink to this headline">¶</a></h2>
    <table border="1" class="docutils">
    <colgroup>
    <col width="32%" />
    <col width="12%" />
    <col width="56%" />
    </colgroup>
    <thead valign="bottom">
    <tr class="row-odd"><th class="head">Function</th>
    <th class="head">Type</th>
    <th class="head">Accuracy</th>
    </tr>
    </thead>
    <tbody valign="top">
    <tr class="row-even"><td rowspan="4"><code class="docutils literal"><span class="pre">exp(x,</span> <span class="pre">y)</span></code></td>
    <td><code class="docutils literal"><span class="pre">f4</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-6</span></code></td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">f8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-15</span></code></td>
    </tr>
    <tr class="row-even"><td><code class="docutils literal"><span class="pre">c8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-6</span></code>, domain edge warning</td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">c16</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-15</span></code>, domain edge warning</td>
    </tr>
    <tr class="row-even"><td rowspan="2"><code class="docutils literal"><span class="pre">expm1(x,</span> <span class="pre">y)</span></code></td>
    <td><code class="docutils literal"><span class="pre">f4</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-6</span></code></td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">f8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-15</span></code></td>
    </tr>
    <tr class="row-even"><td rowspan="4"><code class="docutils literal"><span class="pre">log(x,</span> <span class="pre">y)</span></code></td>
    <td><code class="docutils literal"><span class="pre">f4</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-6</span></code></td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">f8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-15</span></code></td>
    </tr>
    <tr class="row-even"><td><code class="docutils literal"><span class="pre">c8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-5</span></code></td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">c16</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-13</span></code></td>
    </tr>
    <tr class="row-even"><td rowspan="4"><code class="docutils literal"><span class="pre">log10(x,</span> <span class="pre">y)</span></code></td>
    <td><code class="docutils literal"><span class="pre">f4</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-6</span></code></td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">f8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-15</span></code></td>
    </tr>
    <tr class="row-even"><td><code class="docutils literal"><span class="pre">c8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-5</span></code>, domain edge warning</td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">c16</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-13</span></code>, domain edge warning</td>
    </tr>
    <tr class="row-even"><td rowspan="2"><code class="docutils literal"><span class="pre">log1p(x,</span> <span class="pre">y)</span></code></td>
    <td><code class="docutils literal"><span class="pre">f4</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-6</span></code></td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">f8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-15</span></code></td>
    </tr>
    </tbody>
    </table>
    </div>
    <div class="section" id="trigonometric-functions">
    <h2>Trigonometric Functions<a class="headerlink" href="#trigonometric-functions" title="Permalink to this headline">¶</a></h2>
    <table border="1" class="docutils">
    <colgroup>
    <col width="32%" />
    <col width="12%" />
    <col width="56%" />
    </colgroup>
    <thead valign="bottom">
    <tr class="row-odd"><th class="head">Function</th>
    <th class="head">Type</th>
    <th class="head">Accuracy</th>
    </tr>
    </thead>
    <tbody valign="top">
    <tr class="row-even"><td rowspan="4"><code class="docutils literal"><span class="pre">cos(x,</span> <span class="pre">y)</span></code></td>
    <td><code class="docutils literal"><span class="pre">f4</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-6</span></code>, domain edge warning</td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">f8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-15</span></code>, domain edge warning</td>
    </tr>
    <tr class="row-even"><td><code class="docutils literal"><span class="pre">c8</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-6</span></code>, domain edge warning</td>
    </tr>
    <tr class="row-odd"><td><code class="docutils literal"><span class="pre">c16</span></code></td>
    <td><code class="docutils literal"><span class="pre">rtol=1.e-15</span></code>, domain edge warning</td>
    </tr>
    </tbody>
    </table>
