Re: [eigen] documentation: the long tutorial

[Benoit Jacob <jacob.benoit.1@xxxxxxxxx>]

2010/6/20 Carlos Becker <carlosbecker@xxxxxxxxx>:
> Some new stuff:
>
> Arithmetic
> ops: http://carlosbecker.com.ar/eigen/doc/TutorialMatrixArithmetic.html

Thanks. My main comment is that this needs a better structuring. For
example, the first example already shows the comma-initializer without
an explanation and already shows various products. I think the
comma-initializer deserves a short paragraph for itself (which is OK
to put in this page) and products totally deserve a paragraph for
themselves before you do any (except scalar-matrix product, that is OK
to do without a former explanation).

It's good to explain right away that Matrix is only for linear algebra
and to forward-link to Array for coeff-wise ops. But rowwise and
colwise addition and substraction are actually available for matrices
as well (rowwise() is in DenseBase, not in ArrayBase) so that's not
the right example ;) since you just mentioned scalar+array, stick to
that example.

In the paragraph "Combining operators in a single statement" you give
an example of how that allows to avoid useless temporaries, but in
that example, actually, that temporary is not useless at all (write
down the computation yourself on pen&paper, for

    tempMatrix = m + n/2;
    v = tempMatrix * v;

you'll see that doing the temporary actually reduces complexity) and
Eigen is clever enough to understand that, so actually in the 2nd
version in one line, Eigen internally uses such a temporary.

If you want a good example of combining arithmetic operations into a
big expression to avoid temporaries, the easiest way to get a good
example is to just use additions and scalar-matrix multiplications.

But I would not mention that at the top of this page, I'd rather put
at the end of it, since it's an advanced topic.

In short: we need this page to expose all the basic arithmetic in a
rational, systematic, and progressive way, treating one thing at a
time, and deferring the advanced topics to the end.

Also, regarding your first FIXME, you can remove for now the
navigation links at the top.

Benoit

> Array class: http://carlosbecker.com.ar/eigen/doc/TutorialArrayClass.html
>
> The Array class part is quite incomplete I guess. I am wondering whether
> more details should be added or if this is enough. I think that the examples
> found in http://eigen.tuxfamily.org/dox/TutorialCore.html are quite useful,
> does anyone know in which .dox file they are found?
> All feedback welcome.
> Carlos