[Numpy-discussion] question about the documentation of linalg.solve

[Scott Sinclair]

2008/11/20 Charles R Harris <charlesr.harris at gmail.com>:
>
> On Wed, Nov 19, 2008 at 3:20 PM, Fabrice Silva <silva at lma.cnrs-mrs.fr>
> wrote:
>>
>> Le mercredi 19 novembre 2008 à 14:27 -0500, Alan G Isaac a écrit :
>> > So my question is not just what is the algorithm
>> > but also, what is the documentation goal?
>>
>> Concerning the algorithm (only):
>> in Joshua answer, you have might have seen that solve is a wrapper to
>> lapack routines *gesv (z* or d* depending on the input type).
>
> Which,  IIRC, calls *getrf to get the LU factorization of the lhs matrix A.
> Here:
>
> *  DGESV computes the solution to a real system of linear equations
> *     A * X = B,
> *  where A is an N-by-N matrix and X and B are N-by-NRHS matrices.
>
> *
> *  The LU decomposition with partial pivoting and row interchanges is
> *  used to factor A as
> *     A = P * L * U,
> *  where P is a permutation matrix, L is unit lower triangular, and U is
> *  upper triangular.  The factored form of A is then used to solve the
>
> *  system of equations A * X = B.
> *

It's not always fun to read the code in order to find out what a
function does. So I guess the documentation goal is to eventually add
sufficient detail, for those who want to know what's happening without
diving into the source code.

A Notes section giving an overview of the algorithm has been added to
the docstring http://docs.scipy.org/numpy/docs/numpy.linalg.linalg.solve/.

I didn't feel comfortable quoting directly from the LAPACK comments,
so maybe someone else can look into adding more detail.

Cheers,
Scott