[python-dtcwt] 204/497: add in some documentation on how to use backends

[Ghislain Vaillant]

This is an automated email from the git hooks/post-receive script.

ghisvail-guest pushed a commit to branch debian/sid
in repository python-dtcwt.

commit 57b7b7130dbced08f8d760212e4a9eedf8aaf6bf
Author: Rich Wareham <rjw57 at cam.ac.uk>
Date:   Wed Nov 13 14:34:05 2013 +0000

    add in some documentation on how to use backends
---
 docs/backends.rst  | 43 ++++++++++++++++++++++++++++++++++++
 docs/index.rst     |  6 ++++-
 docs/reference.rst | 65 +++++++++++++++++++++++++++++-------------------------
 3 files changed, 83 insertions(+), 31 deletions(-)

diff --git a/docs/backends.rst b/docs/backends.rst
new file mode 100644
index 0000000..db0a5aa
--- /dev/null
+++ b/docs/backends.rst
@@ -0,0 +1,43 @@
+Multiple Backend Support
+========================
+
+The ``dtcwt`` library currently provides two backends for computing the wavelet
+transform: a `NumPy <http://www.numpy.org/>`_ based implementation and an OpenCL
+implementation which uses the `PyOpenCL <http://mathema.tician.de/software/pyopencl/>`_
+bindings for Python.
+
+Which backend should I use?
+'''''''''''''''''''''''''''
+
+The top-level transform routines, such as :py:func:`dtcwt.dtwavexfm2`, will
+automatically use the NumPy backend. If you are not primarily focussed on
+speed, this is the correct choice since the NumPy backend has the fullest
+feature support, is the best tested and behaves correctly given single- and
+double-precision input.
+
+If you care about speed and need only single-precision calculations, the OpenCL
+backend can provide significant speed-up. On the author's system, the 2D
+transform sees around a times 10 speed improvement.
+
+Using a backend
+'''''''''''''''
+
+The NumPy and OpenCL backends live in the :py:mod:`dtcwt.backend.backend_numpy`
+and :py:mod:`dtcwt.backend.backend_opencl` modules respectively. Both provide
+the same base API as defined in :py:mod:`dtcwt.backend.base`.
+
+Access to the 2D transform is via a :py:class:`Transform2d` instance. For
+example, to compute the 2D DT-CWT of the 2D real array in *X*::
+
+    >>> from dtcwt.backend.backend_numpy import Transform2d
+    >>> trans = Transform2d()           # You may optionally specify which wavelets to use here
+    >>> Y = trans.forward(X, nlevels=4) # Perform a 4-level transform of X
+    >>> imshow(Y.lowpass)               # Show coarsest scale low-pass image
+    >>> imshow(Y.subbands[-1][:,:,0])   # Show first coarsest scale subband
+
+In this case *Y* is an instance of a class which behaves like
+:py:class:`dtcwt.backend.base.TransformDomainSignal`. Backends are free to
+return whatever result they like as long as the result can be used like this
+base class. (For example, the OpenCL backend returns a
+:py:class:`dtcwt.backend.backend_opencl.TransformDomainSignal` instance which
+keeps the device-side results available.)
diff --git a/docs/index.rst b/docs/index.rst
index 917d17b..68b57f1 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,6 +14,9 @@ wavelet transform toolbox provided by `Prof. Nick Kingsbury
 <http://www-sigproc.eng.cam.ac.uk/~ngk/>`_. This library is intended to ease
 the porting of algorithms written using the original MATLAB toolbox to Python.
 
+The library also includes an OpenCL-based implementation of the wavelet
+transform which can accelerate computation even on CPU-only devices.
+
 Features of note
 ````````````````
 
@@ -32,8 +35,9 @@ Contents
     :maxdepth: 1
 
     gettingstarted
-    examples
     variant
+    backends
+    examples
     reference
 
 
diff --git a/docs/reference.rst b/docs/reference.rst
index d90b8db..dfd9387 100644
--- a/docs/reference.rst
+++ b/docs/reference.rst
@@ -4,34 +4,16 @@ API Reference
 Computing the DT-CWT
 ````````````````````
 
-.. automodule:: dtcwt
-    :members:
-
-Keypoint analysis
-`````````````````
-
-.. automodule:: dtcwt.keypoint
-    :members:
-
-Image sampling
-``````````````
-
-.. automodule:: dtcwt.sampling
-    :members:
-
-Miscellaneous utility functions
-```````````````````````````````
-
-.. automodule:: dtcwt.utils
-    :members:
+These functions provide API-level compatibility with MATLAB.
 
-Low-level support functions
-```````````````````````````
+.. note::
 
-A normal user should not need to call these functions but they are documented
-here just in case you do.
+    The functionality of ``dtwavexfm2b`` and ``dtwaveifm2b`` have been folded
+    into ``dtwavexfm2`` and ``dtwaveifm2``. For convenience of porting MATLAB
+    scripts, the original function names are available in the :py:mod:`dtcwt`
+    module as aliases but they should not be used in new code.
 
-.. automodule:: dtcwt.lowlevel
+.. automodule:: dtcwt
     :members:
 
 Backends
@@ -40,22 +22,45 @@ Backends
 .. automodule:: dtcwt.backend
     :members:
 
+Base classes
+''''''''''''
+
+.. automodule:: dtcwt.backend.base
+    :members:
+
 NumPy
 '''''
 
 .. automodule:: dtcwt.backend.backend_numpy
     :members:
-
-.. automodule:: dtcwt.backend.backend_numpy.transform2d
-    :members:
     :inherited-members:
 
 OpenCL
 ''''''
 
 .. automodule:: dtcwt.backend.backend_opencl
+    :inherited-members:
+
+Keypoint analysis
+`````````````````
+
+.. automodule:: dtcwt.keypoint
+    :members:
+
+Image sampling
+``````````````
+
+.. automodule:: dtcwt.sampling
+    :members:
+
+Miscellaneous and low-level support functions
+`````````````````````````````````````````````
+
+A normal user should not need to call these functions but they are documented
+here just in case you do.
+
+.. automodule:: dtcwt.utils
     :members:
 
-.. automodule:: dtcwt.backend.backend_opencl.transform2d
+.. automodule:: dtcwt.lowlevel
     :members:
-    :inherited-members:

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/python-dtcwt.git