Re: [eigen] A modest start with the documentation

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

Hi,

2010/6/17 Jitse Niesen <jitse@xxxxxxxxxxxxxxxxx>:
> Hello,
>
> Thanks for all the comments. I updated the Getting Started guide in the
> light of it; as you can see on
>   http://www.amsta.leeds.ac.uk/~jitse/eigen/GettingStarted.html

Thanks for the update, it looks really great!

>
>
> On Tue, 15 Jun 2010, Benoit Jacob wrote:
>
>> In this paragraph could you also mention that the header files are not
>> configured headers, and are the same for all platforms.
>
> I don't understand what you mean with "configured" here.

I meant a header that's generated at configure-time, e.g. in CMake
it's the configure_file() command. But since you didn't understand
that word, we shouldn't use it. This paragraph already is perfect now.

>
>> "A simple first program"
>>
>> I would not use rightCols() here, if only because it's one of these
>> function names that i'm only 99% happy about: it might sound strange.
>
> Hmm, I notice now that I used columnIndex, writing out "column" in full.
> Perhaps that is a sign. For the rest I don't see anything wrong with the
> name rightCols.

Oh, my concern wasn't about the abbreviation of 'columns' into 'cols'.
It's standard enough. I just wasn't too sure how self-explanatory it
was that m.rightCols(n) meant what it does.

I like the new version, but perhaps rowIndex is a bit too long, how
about just row and column? (Or even col, as you want). That would have
the advantage of using fewer pixels of width: right now we are using
more than 1100 pixels with my default font. This kind of tutorial is
the kind of thing that people might enjoy reading on small gadgets
with just 800 pixels of width.


>
>> Also because I feel that block operatios can be deferred for the
>> bigger tutorial. Some basic coeff access and arithmetic should be
>> enough here.
>
> Yes, I was torn between that and showing that the Eigen API can do some
> non-trivial stuff. It's gone now.

OK, thanks.

The 2 arithmetic operations shown here are scalar-matrix and
matrix-vector product. It would be nice to throw in some addition for
good measure. Maybe, in the second example, introduce a second vector
w that you set using operator()(index), as it's also very important to
demonstrate this index-based access, and then do m*(v+w) ?

These are just vague ideas, do what you want with them :)

>
>> [...]
>> ---> actually I think that this short tutorial needs to give a second
>> example with VectorXd.
>
> Added.

Great, thanks.

By the way, since the 1st example doesn't use VectorXd, it doesn't need to do
    using Eigen::VectorXd;

>
>> The explanation about the Dense/Core headers can be deferred to the
>> longer tutorial. This room can be used for the VectorXd example, and
>> even, why not, for a 3rd example showing some fixed-size Matrix2d.
>
> Hmm, I'd like to keep it to two examples. And I'm not sure how necessary it
> is for users to learn about fixed-size types. The main advantage is that
> they're faster, but I think getting the best performance out of Eigen is too
> advanced a topic to treat in the short GettingStarted tutorial.
>
> In the end, I decided to give a dynamic-size and fixed-size program
> side-by-side, so that we still have only two examples.

Great idea: it's even better!

I feel that having the fixed-size version is really useful to get a
feel that Eigen is not just about dynamic-size objects, and also keep
in mind that the question "does Eigen allow fixed sizes and how do I
do it" is one that 50% of our users will be most interested in right
away (and they would discard Eigen if they grew the impression that it
was yet another lib that focuses primarily on dynamic size).

There is a tiny discrepancy between 'program' and 'example':
    Explanation of the first program
    Explanation of the second example

Benoit



>
>
> Jitse
>
>
>