On Sun, Mar 21, 2010 at 8:01 AM, Ralf Gommers <ralf.gommers@googlemail.com> wrote:


On Sun, Mar 21, 2010 at 9:58 PM, Ralf Gommers <ralf.gommers@googlemail.com> wrote:


On Sun, Mar 21, 2010 at 9:51 PM, Alan G Isaac <aisaac@american.edu> wrote:
On 3/21/2010 12:54 AM, Ralf Gommers wrote:
> too many blank lines are needed

Please define "need" after seeing the compact example I posted.

You need 4 blank lines in your example. Now I tried adding a description for the first argument (q) like this:

q, r if mode = 'full' :
   - q : ndarray of float or complex, shape (M, K)
         Description of `q`.

   - r : ndarray of float or complex, shape (K, N)

That doesn't work, you need yet more blank lines (try this in the wiki editor).


I just changed the docstring to the following, looks much better in both plain text and html imho:


q : ndarray of float or complex, optional
    The orthonormal matrix, of shape (M, K). Only returned if
    ``mode='full'``.
r : ndarray of float or complex, optional
    The upper-triangular matrix, of shape (K, N) with K = min(M, N).
    Only returned when ``mode='full'`` or ``mode='r'``.
a2 : ndarray of float or complex, optional
    Array of shape (M, N), only returned when ``mode='economic``'.
    The  diagonal and the upper triangle of `a2` contains `r`, while
    the rest of the matrix is undefined.

This line in the code is fairly amusing by the way:
#  economic mode. Isn't actually economic.

Economic mode is very similar to 'r' mode anyway, what's the point?


Economic mode is what the low level algorithm likely returns, it contains the info needed to contruct q if  needed, or to efficiently apply q to different vectors without constructing q; constructing q adds to the computational and memory costs, as does pulling r out of the economic return. The situation is analogous to the LU decomposition where the natural form is to store both L and U in the original matrix. Other algorithms can then use that compact form to solve equations with different right hand sides.

Chuck