[ Thread Index |
Date Index
| More lists.tuxfamily.org/eigen Archives
]
On Sunday 12 October 2008 17:08:17 Scott Wheeler wrote:
> Benoît Jacob wrote:
> > "or \em dynamically by specifying \em Dynamic as the size."
> >
> > Here "size" is not precise enough, I'd say "as size template parameters".
>
> Does that really give more information?
Throughout Eigen, there are two kinds of sizes: the compile-time size passed
as template parameter, and the actual size which is store as a variable if
the compile-time size is Dynamic.
Since the above is before the description of the template parameters, I feel
that it was useful to clarify.
>
> > \param _Scalar Numeric type, i.e. float, double, int
> >
> > Here I prefered the old version which said:
> >
> > \param _Scalar the scalar type, i.e. the type of the coefficients
>
> Too technical. I've been reading papers on linear algebra applications
> for the last couple of weeks straight and that was unclear to me.
>
> This is kind of a common theme in my changes -- and perhaps a valid
> question: Who is the target audience of the docs? Mathematicians doing
> some C++ or C++ programmers doing some math? My changes are kind of
> optimized for the latter -- i.e. for people that have some basic
> familiarity with linear algebra, but aren't spending most of their time
> in that area.
We definitely aim at the latter, like you do: C++ programmers doing some math.
So all your input and suggestions in this respect are most welcome.
We just need to make sure that by simplifying and shortening the docs, we do
not introduce ambiguity.
I propose:
\param _Scalar The type of the coefficients, e.g. float
It seems to me that this is more explicit than "Numeric type". What do you
think?
> Yes, exactly. People scan API docs -- they don't read them like a book,
> so it's important for them to be concise. I completely missed that bit
> because there were too many words there. In my opinion, explanatory
> notes should be put down below.
> > Wasn't this more helpful ?
>
> No, because I stopped reading. :-) Now if I just glance at the docs I
> see what I need to do in either situation. This is of course, all in my
> opinion, but since I'm a little further back from the API (i.e. I didn't
> know how it was supposed to work) that perspective might be useful.
I get your point, thanks for your input.
> > "Dynamic matrices <em>do not</em> expand dynamically."
> >
> > what do you mean?
>
> Well, that they don't, for instance function like, i.e. std::map. It's
> probably obvious for someone looking at these though a mathematician's
> lens that such is not the case, but looking at it as a C++ programmer
> working with a container, "dynamic" in Eigen really means "fixed, just
> not at compile time".
Hm I see what you mean. But still I think that to many C++ programmers,
including me before you explained, it is not clear what this means.
Maybe rephrase it:
Dynamic just means that the array is dynamically allocated and its size is not
fixed at compile-time. If you want something behaving like std::map, what
you're after is a sparse matrix [link to Sparse module].
> > If p is a compile-time constant then the user may as well call other
> > convenience functions such as l1Norm() etc; if p is not, then we are
> > probably in the general case. I am reluctant to write code as above as it
> > could easily generate binary code for all paths. If such a form were
> > really needed i'd rather make p a template parameter and use a
> > meta-selector so only one path gets compiled.
>
> I've seen it done as a template parameter in at least one other
> framework. Since they're templates, and hence being inlined, a compiler
> should optimize out the if block in the case of a constant being used.
> I feel like having them rolled into one function would make the API
> easier to work with (less functions to scan), but of course the final
> decision is with you guys.
Indeed, a single template function lpNorm<p>() might be the way to go.
Just FYI, yes the compiler will ultimately emit code for only one path, but it
will still go over all paths at least in the front-end, making compilation
longer. This can be avoided by "meta-selectors" i.e. using template
specialization instead of if().
Cheers,
Benoit
---