Showing with 241 additions and 2 deletions.
  1. +32 −1 genindex.html
  2. +208 −0 index.html
  3. BIN objects.inv
  4. +1 −1 searchindex.js
33 changes: 32 additions & 1 deletion genindex.html
Expand Up @@ -44,8 +44,39 @@ <h3>Navigation</h3>
<h1 id="index">Index</h1>

<div class="genindex-jumpbox">

<a href="#E"><strong>E</strong></a> | <a href="#F"><strong>F</strong></a> | <a href="#N"><strong>N</strong></a> | <a href="#U"><strong>U</strong></a>
</div>
<h2 id="E">E</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%" valign="top"><dl>
<dt><a href="index.html#pyfftw.FFTW.execute">execute() (pyfftw.FFTW method)</a></dt>
</dl></td>
</tr></table>

<h2 id="F">F</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%" valign="top"><dl>
<dt><a href="index.html#pyfftw.FFTW">FFTW (class in pyfftw)</a></dt>
</dl></td>
</tr></table>

<h2 id="N">N</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%" valign="top"><dl>
<dt><a href="index.html#pyfftw.n_byte_align">n_byte_align() (in module pyfftw)</a></dt>
</dl></td>
<td style="width: 33%" valign="top"><dl>
<dt><a href="index.html#pyfftw.n_byte_align_empty">n_byte_align_empty() (in module pyfftw)</a></dt>
</dl></td>
</tr></table>

<h2 id="U">U</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%" valign="top"><dl>
<dt><a href="index.html#pyfftw.FFTW.update_arrays">update_arrays() (pyfftw.FFTW method)</a></dt>
</dl></td>
</tr></table>



</div>
Expand Down
208 changes: 208 additions & 0 deletions index.html
Expand Up @@ -87,9 +87,217 @@ <h1>Welcome to pyFFTW&#8217;s documentation!<a class="headerlink" href="#welcome
FFTW. Simply renaming the class should be sufficient to migrate</strong></p>
<div class="section" id="fftw-class">
<span id="id1"></span><h2>FFTW Class<a class="headerlink" href="#fftw-class" title="Permalink to this headline"></a></h2>
<dl class="class">
<dt id="pyfftw.FFTW">
<em class="property">class </em><tt class="descclassname">pyfftw.</tt><tt class="descname">FFTW</tt><big>(</big><em>input_array, output_array, axes=[-1], direction='FFTW_FORWARD', flags=['FFTW_MEASURE']</em><big>)</big><a class="headerlink" href="#pyfftw.FFTW" title="Permalink to this definition"></a></dt>
<dd><p>FFTW is a class for computing the complex N-Dimensional DFT or
inverse DFT of an array using the FFTW library. The interface is
designed to be somewhat pythonic, with the correct transform being
inferred from the dtypes of the passed arrays.</p>
<p>On instantiation, the dtypes of the input arrays are compared to the
set of valid (and implemented) FFTW schemes. If a match is found,
the plan that corresponds to that scheme is created, operating on the
arrays that are passed in. If no scheme can be created, then
<tt class="docutils literal"><span class="pre">ValueError</span></tt> is raised.</p>
<p>The actual FFT or iFFT is performed by calling the
<a class="reference internal" href="#fftw-execute"><em>execute()</em></a> method.</p>
<p>The arrays can be updated by calling the
<a class="reference internal" href="#fftw-update-arrays"><em>update_arrays()</em></a> method.</p>
<p><tt class="docutils literal"><span class="pre">input_array</span></tt> and <tt class="docutils literal"><span class="pre">output_array</span></tt> should be numpy arrays.
The contents of these arrays will be destroyed by the planning
process during initialisation. Information on supported
dtypes for the arrays is given below.</p>
<p><tt class="docutils literal"><span class="pre">axes</span></tt> describes along which axes the DFT should be taken.
This should be a valid list of axes. Repeated axes are
only transformed once. Invalid axes will raise an
exception. This argument is equivalent to the same
argument in <tt class="docutils literal"><span class="pre">numpy.fft.fftn</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">direction</span></tt> should be a string and one of FFTW_FORWARD
or FFTW_BACKWARD, which dictate whether to take the
DFT (forwards) or the inverse DFT (backwards) respectively
(specifically, it dictates the sign of the exponent in the
DFT formulation).</p>
<p>Note that only the Complex schemes allow a free choice
for <tt class="docutils literal"><span class="pre">direction</span></tt>. The direction <em>must</em> agree with the
the table below if a Real scheme is used, otherwise a
<tt class="docutils literal"><span class="pre">ValueError</span></tt> is raised.</p>
<p><tt class="docutils literal"><span class="pre">flags</span></tt> is a list of strings and is a subset of the
flags that FFTW allows for the planners. Specifically,
FFTW_ESTIMATE, FFTW_MEASURE, FFTW_PATIENT and
FFTW_EXHAUSTIVE are supported. These describe the
increasing amount of effort spent during the planning
stage to create the fastest possible transform.
Usually, FFTW_MEASURE is a good compromise and is the
default.</p>
<p>In addition the FFTW_UNALIGNED flag is supported.
This tells FFTW not to assume anything about the
alignment of the data and disabling any SIMD capability
(see below).</p>
<p>The currently supported schemes are as follows:</p>
<table border="1" class="docutils">
<colgroup>
<col width="22%" />
<col width="31%" />
<col width="32%" />
<col width="15%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Type</th>
<th class="head"><tt class="docutils literal"><span class="pre">input_array.dtype</span></tt></th>
<th class="head"><tt class="docutils literal"><span class="pre">output_array.dtype</span></tt></th>
<th class="head">Direction</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>Complex</td>
<td><tt class="docutils literal"><span class="pre">complex64</span></tt></td>
<td><tt class="docutils literal"><span class="pre">complex64</span></tt></td>
<td>Both</td>
</tr>
<tr><td>Complex</td>
<td><tt class="docutils literal"><span class="pre">complex128</span></tt></td>
<td><tt class="docutils literal"><span class="pre">complex128</span></tt></td>
<td>Both</td>
</tr>
<tr><td>Complex</td>
<td><tt class="docutils literal"><span class="pre">clongdouble</span></tt></td>
<td><tt class="docutils literal"><span class="pre">clongdouble</span></tt></td>
<td>Both</td>
</tr>
<tr><td>Real</td>
<td><tt class="docutils literal"><span class="pre">float32</span></tt></td>
<td><tt class="docutils literal"><span class="pre">complex64</span></tt></td>
<td>Forwards</td>
</tr>
<tr><td>Real</td>
<td><tt class="docutils literal"><span class="pre">float64</span></tt></td>
<td><tt class="docutils literal"><span class="pre">complex128</span></tt></td>
<td>Forwards</td>
</tr>
<tr><td>Real</td>
<td><tt class="docutils literal"><span class="pre">longdouble</span></tt></td>
<td><tt class="docutils literal"><span class="pre">clongdouble</span></tt></td>
<td>Forwards</td>
</tr>
<tr><td>Real<sup>1</sup></td>
<td><tt class="docutils literal"><span class="pre">complex64</span></tt></td>
<td><tt class="docutils literal"><span class="pre">float32</span></tt></td>
<td>Backwards</td>
</tr>
<tr><td>Real<sup>1</sup></td>
<td><tt class="docutils literal"><span class="pre">complex128</span></tt></td>
<td><tt class="docutils literal"><span class="pre">float64</span></tt></td>
<td>Backwards</td>
</tr>
<tr><td>Real<sup>1</sup></td>
<td><tt class="docutils literal"><span class="pre">clongdouble</span></tt></td>
<td><tt class="docutils literal"><span class="pre">longdouble</span></tt></td>
<td>Backwards</td>
</tr>
</tbody>
</table>
<p><sup>1</sup> Note that the Backwards Real transform will destroy the
input array. This is inherent to FFTW and the only general
work-around for this is to copy the array prior to performing the
transform.</p>
<p><tt class="docutils literal"><span class="pre">clongdouble</span></tt> typically maps directly to <tt class="docutils literal"><span class="pre">complex256</span></tt>
or <tt class="docutils literal"><span class="pre">complex192</span></tt>, and <tt class="docutils literal"><span class="pre">longdouble</span></tt> to <tt class="docutils literal"><span class="pre">float128</span></tt> or <tt class="docutils literal"><span class="pre">float96</span></tt>,
dependent on platform.</p>
<p>The relative shapes of the arrays should be as follows:</p>
<ul class="simple">
<li>For a Complex transform, <tt class="docutils literal"><span class="pre">output_array.shape</span> <span class="pre">==</span> <span class="pre">input_array.shape</span></tt></li>
<li>For a Real transform in the Forwards direction, both the following
should be true:<ul>
<li><tt class="docutils literal"><span class="pre">output_array.shape[axes][-1]</span> <span class="pre">==</span> <span class="pre">input_array.shape[axes][-1]//2</span> <span class="pre">+</span> <span class="pre">1</span></tt></li>
<li>All the other axes should be equal in length.</li>
</ul>
</li>
<li>For a Real transform in the Backwards direction, both the following
should be true:<ul>
<li><tt class="docutils literal"><span class="pre">input_array.shape[axes][-1]</span> <span class="pre">==</span> <span class="pre">output_array.shape[axes][-1]//2</span> <span class="pre">+</span> <span class="pre">1</span></tt></li>
<li>All the other axes should be equal in length.</li>
</ul>
</li>
</ul>
<p>In the above expressions for the Real transform, the <tt class="docutils literal"><span class="pre">axes</span></tt>
arguments denotes the the unique set of axes on which we are taking
the FFT, in the order passed. It is the last of these axes that
is subject to the special case shown.</p>
<p>The shapes for the real transforms corresponds to those
stipulated by the FFTW library. Further information can be
found in the FFTW documentation on the <a class="reference external" href="http://www.fftw.org/fftw3_doc/Guru-Real_002ddata-DFTs.html">real DFT</a>.</p>
<p>The actual arrangement in memory is arbitrary and the scheme
can be planned for any set of strides on either the input
or the output. The user should not have to worry about this
and any valid numpy array should work just fine.</p>
<p>What is calculated is exactly what FFTW calculates.
Notably, this is an unnormalized transform so should
be scaled as necessary (fft followed by ifft will scale
the input by N, the product of the dimensions along which
the DFT is taken). For further information, see the
<a class="reference external" href="http://www.fftw.org/fftw3_doc/What-FFTW-Really-Computes.html">FFTW documentation</a>.</p>
<p>The FFTW library benefits greatly from the beginning of each
DFT axes being aligned on a 16-byte boundary, which enables
SIMD instructions. By default, if the data begins on a 16-byte
boundary, then FFTW will be allowed to try and enable
SIMD instructions. This means that all future changes to
the data arrays will be checked for similar alignment. SIMD
instructions can be explicitly disabled by setting the
FFTW_UNALIGNED flags, to allow for updates with unaligned
data.</p>
<p><a class="reference internal" href="#n-byte-align"><em>n_byte_align()</em></a> and
<a class="reference internal" href="#n-byte-align-empty"><em>n_byte_align_empty()</em></a> are two methods
included with this module for producing aligned arrays.</p>
<span class="target" id="fftw-update-arrays"></span><dl class="method">
<dt id="pyfftw.FFTW.update_arrays">
<tt class="descname">update_arrays</tt><big>(</big><em>new_input_array</em>, <em>new_output_array</em><big>)</big><a class="headerlink" href="#pyfftw.FFTW.update_arrays" title="Permalink to this definition"></a></dt>
<dd><p>Update the arrays upon which the DFT is taken.</p>
<p>The new arrays should be of the same dtypes as the originals, the
same shapes as the originals and
should have the same strides between axes. If the original
data was aligned so as to allow SIMD instructions (by being
aligned on a 16-byte boundary), then the new array
must also be aligned in the same way.</p>
<p>If all these conditions are not met, a <tt class="docutils literal"><span class="pre">ValueError</span></tt> will
be raised and the data will <em>not</em> be updated (though the
object will still be in a sane state).</p>
<p>Note that if the original array was not aligned on a 16-byte
boundary, then SIMD is disabled and the alignment of the new
array can be arbitrary.</p>
</dd></dl>

<span class="target" id="fftw-execute"></span><dl class="method">
<dt id="pyfftw.FFTW.execute">
<tt class="descname">execute</tt><big>(</big><big>)</big><a class="headerlink" href="#pyfftw.FFTW.execute" title="Permalink to this definition"></a></dt>
<dd><p>Execute the planned operation.</p>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="utility-functions">
<span id="utilityfunctions"></span><h2>Utility Functions<a class="headerlink" href="#utility-functions" title="Permalink to this headline"></a></h2>
<span class="target" id="n-byte-align"></span><dl class="function">
<dt id="pyfftw.n_byte_align">
<tt class="descclassname">pyfftw.</tt><tt class="descname">n_byte_align</tt><big>(</big><em>array</em>, <em>n</em><big>)</big><a class="headerlink" href="#pyfftw.n_byte_align" title="Permalink to this definition"></a></dt>
<dd><p>Function that takes a numpy array and
checks it is aligned on an n-byte boundary,
where <tt class="docutils literal"><span class="pre">n</span></tt> is a passed parameter. If it is,
the array is returned without further ado.
If it is not, a new array is created and
the data copied in, but aligned on the
n-byte boundary.</p>
</dd></dl>

<span class="target" id="n-byte-align-empty"></span><dl class="function">
<dt id="pyfftw.n_byte_align_empty">
<tt class="descclassname">pyfftw.</tt><tt class="descname">n_byte_align_empty</tt><big>(</big><em>shape</em>, <em>n</em>, <em>dtype='float64'</em>, <em>order='C'</em><big>)</big><a class="headerlink" href="#pyfftw.n_byte_align_empty" title="Permalink to this definition"></a></dt>
<dd><p>Function that returns an empty numpy array
that is n-byte aligned.</p>
<p>The alignment is given by the second argument, <tt class="docutils literal"><span class="pre">n</span></tt>.
The rest of the arguments are as per <tt class="docutils literal"><span class="pre">numpy.empty</span></tt>.</p>
</dd></dl>

</div>
</div>

Expand Down
Binary file modified objects.inv
Binary file not shown.
2 changes: 1 addition & 1 deletion searchindex.js

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.