Re: [ublas] [bindings] Which Bindings should I direct my users to? Boost proper?

Subject: Re: [ublas] [bindings] Which Bindings should I direct my users to? Boost proper?
From: Thomas Klimpel (Thomas.Klimpel_at_[hidden])
Date: 2010-06-21 05:15:40

Rutger ter Borg wrote:
> Help is very much welcomed, mainly for the documentation, e.g., by
> contributing a tutorial section, integrating/porting the existing
> documentation pieces for blas/lapack/mumps/umfpack/etc. to quickbook,
> working on the BLAS/LAPACK documentation generator, and/or (of course)
> testing the bindings.

I really tried to focus on the documentation this time, but...

First I read over the documentation, polished my quickbook installation, checked which boost version to use that generates identical html as the checked in (this proved to be impossible) and made some minor modifications and my first checkin.

I wrote:
> updated documentation:
> - support for tnt was removed, support for mumps, umfpack, eigen, glas and mtl will stay
> - the include path in the documentation accidentally omitted level1/level2/level3 for blas and driver/computational/auxiliary for lapack

Question: Which boost version (=quickbook version) should I use to generate the html? I suggest going with the latest released boost version (=1.43 currently), as that version won't at least not change daily.

Next I tried to address the issues recently reported by Peter Man (documentation can wait, you know). He had the crazy idea to include <boost/numeric/bindings/lapack.hpp> :-)
So I generated a list of obvious incomplete generated code issues, and started to clean lapack/driver. Then I modified the code generator to be more confident when deducing workspace requirements from the code, which fixed 9 incomplete code issues in lapack/computational, but not all (the unfixed can be found in the attached fixme.txt).

Looking at the workspace issue for clapack, I noticed an unused "work" argument for the optimal_workspace and minimal_workspace cases (easy to fix by just modifying the template). But I decided to first try to reduce the size of the generated files by trying to address the perfect forwarding issue. (Reducing the file size is a good idea, if somebody really wants to include <boost/numeric/bindings/lapack.hpp>). It turned out I was not clever enough (but David Abrahams was, see below), so I gave up and instead turned off generating overloads for "Vector" arguments. But because I still wanted to generate overloads for "Vector" arguments that support general strides, I introduced the name "VectorView" for these arguments (I settled for this name as it required the fewest changes to the code generator). I noticed that this also improved the documentation, as it was difficult before to know whether a vector argument was actually restricted to be a continuous region in memory (stride=1) or not. I also rejoiced when I noticed that the largest generated file was now ~100 kB, a significant reduction from the previous 10 MB.

But then somebody asked a question in the boost-mailing list about default arguments for templates, and David Abrahams answered that Boost.Parameter is able to solve this issue. So I tried to describe our problem (+current solution +attached syev.hpp to make it concrete) and expressed my doubts that Boost.Parameter would be able to help in this situation, but that I would be curious to learn about better solutions. Here is David Abrahams' answer: <http://lists.boost.org/Archives/boost/2010/06/168271.php>. So I immediately followed that suggestion in my next checkin.

I wrote:
>Changed the return type of the wrapper returning free functions from "wrapper" to "wrapper const", following the suggestion of David Abrahams. This allows them to bind against normal "template<typename T> XXX(T& t)" references (T will be deduced as const) without requiring an additional "template<typename T> XXX(const T& t)" overload.
>
> We still have to decide whether we want to omit the many overloads now.

Next I had noticed that some auxiliary routines from lapack were ending up classified as driver or computational, so I fixed this in the code generator. Finally I told the code generator to generate sections for "Driver Routines", "Computational Routines" and "Auxiliary Routines" in the Reference documentation for lapack, then did an additional cleanup checkin.

I wrote:
> - Introduced sections for "Level 1 BLAS", "Level 2 BLAS" and "Level 3 BLAS" in the Reference documentation for blas.
> - Added include of auxiliary.qbk to lapack.qbk and changed the include order of driver.qbk, computational.qbk and auxiliary.qbk.
> - Fixed some typos in numeric_bindings.qbk.

I the directory structure of the generated html is now quite different now from the previous version, but I first want to know which quickbook version to use before I check in the generated html.

Rutger ter Borg wrote:
> If you have further suggestions and/or questions,
> please feel free to fire away.

I have attached my current TODO list (fixme.txt), but I won't wait until it's empty before starting to write documentation.

Summary of questions from above:

- Which boost version (=quickbook version) should I use to generate the html?

- Do you approve the new name "VectorView" for "Vector" arguments that support general strides?

- Should we omit nearly all overloads, because they are no longer important now?

- Do you approve the sections for "Driver Routines", "Computational Routines" and "Auxiliary Routines" for lapack and "Level 1 BLAS", "Level 2 BLAS" and "Level 3 BLAS" for blas in the Reference documenation?

- How often should the generated html be checked in? I would tend to update it only very infrequently, as some GUID's always change and cause the checkin to be really huge.

Regards,
Thomas