Re: [ublas] [bindings][lapack] Interface design

Subject: Re: [ublas] [bindings][lapack] Interface design
From: Rutger ter Borg (rutger_at_[hidden])
Date: 2008-12-03 12:34:35

Karl, Thomas, 

thanks for your answers, they certainly got me thinking :-). I think the
comment of Thomas around the left and right eigenvectors got me to the idea
laid out next. 

Suppose we take LAPACK's problem type as a base, not their actual driver
routines (Thomas' suggestion of 'xxev.hpp' is along this line). See LAPACK
User's Guide, especially tables 2.2, 2.3, 2.4, 2.5, etc.. In other words,
we might have functions called similar to these problem types (I've
included some suggestions after 'or'):

 * for linear equations: lapack::sv( ... ) or lapack::solve( ... )
 * for linear least squares: lapack::lls or lapack::least_squares( ... )
 * for symmetric eigenproblems: lapack::sep( ... ) or lapack::eigen( ... )
 * for QR decompositions: lapack::qr( ... )
 * etc.

Next, let's take the difficult case mentioned by Thomas, geevx. I think we
can achieve an easy and consistent interface by compile-time
type-decoration of our variables. Herewith some examples which might not be
perfect at their first shot, it's for the idea, suppose we just say

lapack::eigen( A, left_eigen_values( vl ) );
lapack::eigen( A, right_eigen_values( vl ) );
lapack::eigen( A, right_eigen_values( vr ), left_eigen_values( vl ),
eigen_vectors( W ) );
lapack::eigen( symmetric_lower( A ), left_eigen_values( vl ) );
lapack::eigen( hermitian_upper( A ), right_eigen( v ) );

Now, why I am happy with this?

 * it is very readable
 * we might dispatch not only to xgeevx: other algorithms may be selected at
compile-time, like the divide-and-conquer algorithm
 * no expert lapack-knowledge is required by the user (a part of the posts
to this list is actually about finding the right lapack driver)
 * there is zero performance penalty in spite of the clear syntax (exploit
power of C++)
 
Now, if a user wants to have more flexibility and/or access to the
implementation details, we can offer them the stuff generated by the
bindings generator, that may be used for low-level C++ calls to lapack:

 * templated calls to all driver / computational routines, by calling
   detail::xxxxx( .... ) (or without detail::, since the actual interface
   has other names)
 * detail::optimal_workspace_xxxx( .... );
 * detail::minimal_workspace_xxxx( .... );
 * etc.

What do you think? Let's figure out a good set of names for decoration...

Kind regards,

Rutger