Re: [boost] [Review] ODEInt review/comments

Subject: Re: [boost] [Review] ODEInt review/comments
From: Karsten Ahnert (karsten.ahnert_at_[hidden])
Date: 2012-09-28 08:22:18

Hi Sylwester,

thank you for your review and of course for your corrections and
suggestion to the docs.

>> - What is your evaluation of the documentation?
> 
> My feeling is that it is on par (or even more complete) than several
> other Boost documentations I have used, and it is rich in examples. In
> principle, it does allow to use the library without digging into the
> code or contacting the authors.
> 
> However, it seems as it has grown quite a bit since the initial
> structuring into chapters and sections, and perhaps it deserves at least
> some reordering. In particular, I'd suggest promoting all subsections of
> the "Special topics" section to separate sections of the Tutorial chapter.

Ok, thank you for that advice. You are right and we will restructize the
tutorial chapter. There are some further issues (like binding of member
methods) which need some explanation and which will be included.
> 
> Some other minor comments:
> 
> * Tables 1.1, 1.2 and 1.7 as well as tables 1.3/1.4 and 1.8/1.9 seem to
> be identical?

Yes. This is redundant, but I think in this case it is ok. (The tables
itself come from the same source file ).

> * The table 1.1 in the "Overview" includes headers naming non-previously
> mentioned subjects such as Concepts, System Concept. A paragraph briefly
> explaining these and referring to subsections of the "odeint in detail"
> chapter would be appropriate just before the table.

ok, we will include a paragraph.

> 
> * Tables in the "Concepts" chapter are not numbered

Ok, we will change this too.

> * The fusion_algebra is missing from the table listing all algebras in
> doc/concepts/state_algebra_operations.qbk

Ok, we will be added.

> * Most of the tables in the "Concepts" chapter have their first column
> named "Name" while "Synopsis" or "Purpose" would probably reflect better
> the contents.

Ok, we will change them.

> * There is a catalogue of references in the Tutorial, but it does not
> list all the references (e.g. the Ott's book referenced in the chapter
> on Lyapunov exponents). There is no unified way of referring to (and
> hyperlinkig) the references in the text. Why not a separate chapter
> "References" for the whole documentation?

Yes, this is a good suggestion.

> * The README and the CHANGELOG files seem forgotten, but perhaps they
> are simply not needed if accepted into Boost

Yes, they are not up to date. Maybe we should remove them.

> * The "Caution" "Using Boost.Units works nicely but compilation can be
> very time and memory consuming. For example the unit test for
> Boost.Units take up to 4 GB of memory at compilation." would probably
> need some more specific information on the compiler used... or less
> specific statement on the amount of memory. Trying with gcc 4.7 and
> clang 3.1 I've recorded 1.8G and 1.1G, respectively (default Boost
> compiler options).

Ok, this will be included.

> * in some parts the documentation addresses the reader per "You", and in
> others using "one may ..." constructs

Ok,

> 
> * Some other Boost libraries contain "Reference" sections in the docs
> listing (e.g.
> http://www.boost.org/doc/libs/1_51_0/doc/html/boost_units/Reference.html).
> It would be useful for odeint as well in my opinion.

You are right. This is maybe the largest point on our ToDo list and we
will try to provide the reference as soon as possible.

> * I think that the "Concepts" chapter requires an opening section
> (Overview?) explaining the concept of concepts.

Ok, good hint.

> 
> * I've placed some other suggestions/typo fixes for the documentation in
> a github pull request:
> https://github.com/slayoo/odeint-v2/commit/5eec7bf86321af185b4547a4825c0751e5637b07

Thank you very much for this work.

>> - What is your evaluation of the potential usefulness of the library?
> 
> I find it potentially very useful. Primarily in scientific/engineering
> context, but perhaps also in other domains - game design, GUI design.
> 
> In comparison with other ODE solvers, the library seems quite versatile
> - it supports both implicit and explicit methods, both adaptive and
> non-adaptive solutions, algorithms for stiff and non-stiff systems, and
> as mentioned above, numerous "backends" ranging from GPU-stored POD
> arrays to resizable vectors of objects.
> 
>> - Did you try to use the library?  With what compiler?  Did you have any
>> problems?
> 
> I'm using the library for more than half year in my PhD project (IIRC,
> I've found it by googling "GPU ODE solver"). There we use odeint for two
> purposes:
> - solutions of simple 1-dimensional equations employing Boost.units
> (latent heat production during cloud droplet condensation/evaporation)
> - aerosol/cloud/drizzle/rain particle tracking within a fluid flow model
> (parallel solutions of ~milions of equations of motion, condensation,
> chemical reactions, etc) using Thrust (OpenMP only up to now). We've
> used clang 3.1 and several newer versions of gcc.
> Here's an example animation from a (quite naive) simulation of
> precipitation formation in a stratocumulus cloud:
> http://www.igf.fuw.edu.pl/~slayoo/temp/todo_sdm_E10.gif

Very impressive, it looks a bit like Rayleigh-Taylor instability
interfering with some kind of avalanche process.