BLAS documentation

BLAS documentation

[Arthur K. Barnes]

Hi all,

Thanks for a great library. I notice that the GSL documentation for
the BLAS wrappers include function prototypes, but not a description
of what each function does.  Granted, it is possible to infer
functionality from the function name, and there is a link to the BLAS
documentation, but it still is a bit of a pain. I'm willing to produce
a patch for a completed version, but I'm curious if there is a reason
for referring to the BLAS documentation.

Thanks again,
-Art

-- 
Art Barnes
Dept. of Electrical and Computer Engineering
University of Florida - Gainesville
(352) 870-9039
http://www.ecel.ufl.edu/~barnes

Re: BLAS documentation

[Alxneit-Kamber Ivo]

[-- Attachment #1: Type: text/plain, Size: 1227 bytes --]

On Tue, 2006-03-14 at 23:34 -0500, Arthur K. Barnes wrote:
> Hi all,
> 
> Thanks for a great library. I notice that the GSL documentation for
> the BLAS wrappers include function prototypes, but not a description
> of what each function does.  Granted, it is possible to infer
> functionality from the function name, and there is a link to the BLAS
> documentation, but it still is a bit of a pain. I'm willing to produce
> a patch for a completed version, but I'm curious if there is a reason
> for referring to the BLAS documentation.
> 
> Thanks again,
> -Art
> 
i assume you refer to appendix d of the manual. you are right, only the
prototypes are listed. for the complete documentation refer to chapter
12. the naming convention is gsl_blas_function <-> cblas_function. the
only part that is not obvious are the dimensions of the various
matrices/vectors. they are contained in the gsl_matrix or gsl_vevtor but
have to be supplied for the wrapper.
-- 
Dr. Ivo Alxneit
Laboratory for Solar Technology   phone: +41 56 310 4092
Paul Scherrer Institute             fax: +41 56 310 2688
CH-5232 Villigen                   http://solar.web.psi.ch
Switzerland                   gnupg key: 0x515E30C7


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

Re: BLAS documentation

[Brian Gough]

Arthur K. Barnes writes:
 > Thanks for a great library. I notice that the GSL documentation for
 > the BLAS wrappers include function prototypes, but not a description
 > of what each function does.  Granted, it is possible to infer
 > functionality from the function name, and there is a link to the BLAS
 > documentation, but it still is a bit of a pain. I'm willing to produce
 > a patch for a completed version, but I'm curious if there is a reason
 > for referring to the BLAS documentation.

Just to save typing.  Some of the definitions are quite complicated,
e.g the modified Givens transformations has a long description in the
original papers if I remember correctly.  There is a quick reference
card on the Netlib blas page that does give the basic definitions -- I
usually use that.

Certainly if you want to have a go probably best to try a few
definitions and send them to me to have a look -- there is an
explanation of how to typeset the mathematics in Texinfo in
doc/gsl-design.texi now.

-- 
Brian Gough

Network Theory Ltd,
Publishing Free Software Manuals --- http://www.network-theory.co.uk/

Re: BLAS documentation

[James Bergstra]

On Wed, Mar 15, 2006 at 10:46:50AM +0100, Alxneit-Kamber Ivo wrote:
> On Tue, 2006-03-14 at 23:34 -0500, Arthur K. Barnes wrote:
> > Hi all,
> > 
> > Thanks for a great library. I notice that the GSL documentation for
> > the BLAS wrappers include function prototypes, but not a description
> > of what each function does.  Granted, it is possible to infer
> > functionality from the function name, and there is a link to the BLAS
> > documentation, but it still is a bit of a pain. I'm willing to produce
> > a patch for a completed version, but I'm curious if there is a reason
> > for referring to the BLAS documentation.
> > 
> > Thanks again,
> > -Art
> > 
> i assume you refer to appendix d of the manual. you are right, only the
> prototypes are listed. for the complete documentation refer to chapter
> 12. the naming convention is gsl_blas_function <-> cblas_function. the
> only part that is not obvious are the dimensions of the various
> matrices/vectors. they are contained in the gsl_matrix or gsl_vevtor but
> have to be supplied for the wrapper.
> -- 
> Dr. Ivo Alxneit
> Laboratory for Solar Technology   phone: +41 56 310 4092
> Paul Scherrer Institute             fax: +41 56 310 2688
> CH-5232 Villigen                   http://solar.web.psi.ch
> Switzerland                   gnupg key: 0x515E30C7
> 

There are actually more differences than that.  Lots of useful blas functions do
not appear as gsl_blas_xxxx (gbmv, tpmv, others?).  There are two tricky things
about such functions: how to store the elements of matrices in memory, and where
to put the various parameters in the call.  The original blas documentation is
pretty terse, so I can understand why it might be better to use GSL's
documentation to make it better.

On the other hand, there is a newer specification of the BLAS that doesn't seem
to be very popular with vendors, but it looks to me like a good extension!
(http://www.netlib.org/blas/blast-forum/)
In constrast to the original blas standard (the new document refers to it as
legacy blas) the new standard is very *well* documented.  Specifically, it
carefully documents the different storage techniques and parameter semantics for
the complicated Level2 and Level 3 functions.  The catch is that it documents
the new versions of the functions.  (The new ones are similar to the old ones
for the most part.)  

What would list readers think of:
- linking to the blast-forum documentation as a means of explaining how to use
  the legacy interface (which is implemented by GSL and others).
- actually implementing a reference library of the new standard as a companion
  (extension?) to the GSL.

PS. The newer standard is not totally unsupported by tuned implementations.
ATLAS already implements [ds]set and [ds]axpby, but exports them as catlas_xxx
instead of cblas_xxxxx.


-- 
james bergstra
http://www-etud.iro.umontreal.ca/~bergstrj

Re: BLAS documentation

[Brian Gough]

James Bergstra writes:
 > What would list readers think of:
 > - linking to the blast-forum documentation as a means of explaining how to use
 >   the legacy interface (which is implemented by GSL and others).

GNU documentation would be preferable.

 > - actually implementing a reference library of the new standard as a companion
 >   (extension?) to the GSL.

For most people the standard blas is probably enough.

-- 
Brian Gough