Interfacing to the (C)BLAS math library
=======================================

  Rev 0.11: Now works, added example1 from CBLAS distribution
  Rev 0.10: Initial release


This is an extension which uses Tcl to generate its own CriTcl binding.
There's a script ("cblas/massage.tcl") which reads the "cblas.h" header
and generates a Tcl script representing all CBLAS routine definitions.

After that, things are relatively straightforward: cblas.tcl is a Tcl
package, which uses the generated Tcl script to produce tons of calls
to critcl::ccommand.  Each defines one Tcl command, named "cblas::...".

The mechanism for dealing with data is tricky (but efficient).  Where
an input array is needed, you should give the name of a variable which
contains a bytearray with the proper data.  Where an output array is
needed, you need to supply a variable which has been preset to a byte
array of the proper size.  That can be a "binary format d* {...}" to
provide data, or by creating a blank buffer ("binary format x32" sets
up a 32-byte buffer).

Tcl does offer a nice convenience: where an enum is expected (of type
Order, Transpose, Uplo, Diag, or Side), you supply the setting as a
string (i.e. specify row order as "R", "Row", or "RowMajor").  This is
efficient (as are scalar numeric arguments) due to Tcl's dual objects.

Here's CBLAS example 1, in Tcl:
    package require cblas
    set m 4
    set n 4
    set lda 4
    set incx 1
    set incy 1
    set alpha 1
    set beta 0
    set a [binary format d*d*d*d* {1 2 3 4} \
                                  {1 1 1 1} \
				  {3 4 5 6} \
				  {5 6 7 8}]
    set x [binary format d* {1 2 1 1}]
    set y [binary format d* {0 0 0 0}]
    cblas::dgemv C N $m $n $alpha a $lda x $incx $beta y $incy
    binary scan $y d* out
    puts $out

The following routines were disabled during my trial, because I do not
seem to have all the required BLAS routines and got linker errors:
        drotm   drotmg   dsdot   sdsdot   srotm   srotmg  

The CBLAS code has not been modified, but a "-fPIC" option was added to
the makefile, so CriTcl can link this package as shared library.

This package is still experimental.  As some other packages in CritLib,
it is working code but also an example of what "CriTcl-coding" can do.