Re: [boost] [Review][PQS] Review

From: Andy Little (andy_at_[hidden])
Date: 2006-06-09 09:42:58

Hi John,

"John Phillips" wrote
>    Andy, Fred and all
>    Here are my thoughts on the PQS (which I agree is not a good name).
> Some of them have become redundant since I began jotting them down, but
> I'll add my voice even though Andy already knows about the issues. I
> wish I had time to be more complete, but this is all I have time to do
> at the moment.
>    I also notice that although I was looking at the PDF version of the
> documentation, there is an html version, that I have not looked at
> closely enough to have any opinion on whether it is better.

FWIW, the pdf version was only intended to complement the html version, to help
if anyone wanted to print it. It being automatically generated without much
thought, there is a lot wrong with it including poor format and broken links. It
is clear though that it was a popular download !

> About the documentation
>
> First an issue of ordering.
>    I think the Getting Started section is quite useful, but it is buried
> a bit too far into the documents. My guess is that a typical user will
> want this before anything else, so it should be front and center. This
> can repair itself when the documents are done as hyper-linked text for a
> browser instead of a PDF file, since a navigation area can highlight the
> easy access to this information.

Yes, many reviews have said similarly.

>    Also, the Definition of Terms section is a Glossary, and is probably
> better placed at the end instead of at the beginning. An understanding
> of these terms is useful when digging through the details of the
> library, but not nearly as useful for the causal user. Placed before the
> Getting Started section, it will make many users wonder if this is going
> to be too much work for the return.

FWIW my review manager, suggested moving the Glossary to the back before the
review started, but I knew better at the time!
but yes, it looks like it should be at the back.

> Next one of convenience
>    The Predefined t1_quantities list is not yet very useful. It is also
> likely to be difficult to maintain, as your list of available units gets
> longer if it is made useful.
>    What is it missing?
>    A way to decide what is actually available and how to use it.

This is dependent on whether you use the pdf or html docs. If you look in the
html docs they should provide the information on units.

>    By browsing the headers, I find that in some cases, you have a true
> wealth of possibilities. Your measures of length include such things as
> rods and Astronomical Units, for example. (It also includes some things
> that I don't understand putting in that header (such as acres), but
> possibly you have a reason for this.)

I do... I mistakenly added acres  in my local database as a length unit as well
as an area unit. The file generation machinery has faithfully reproduced it in
docs and headers.

> However, the documentation does
> not yet give me any way to know what the available possibilities are. It
> also doesn't tell me what the scales are for the various non-SI units,
> so I have no way to decide that some non-SI unit might better represent
> the scale of my problem.
>    Unfortunately, fixing this problem will make the documentation quite
> unwieldy for you to maintain. Just a table listing the name, notation in
> the pqs and scale for each of the length units would currently have 19
> entry rows (counting one for meters, but not including acres or
> acre-feet). As other units are included, this format is far too likely
> to be painful for you. I don't yet have a good idea for an alternative,
> but I think one needs to be found.

As regards what represents completeness the aim is to include all and only the
quantities and units listed in  appendix B8 and B9 of the Guide for the
International System of Units.

> One about consistency
>    In the Concepts section, you have a reasonable framework for
> describing each concept. Unfortunately, there are formatting issues that
> make the concept descriptions hard to follow. The concept names are not
> differentiated from the subsections of the concept descriptions in a
> visually obvious way. Some use of a different font size or indentation
> will make browsing the list for a concept description much easier.
>    The first couple of descriptions have a consistent and complete
> style, that quickly disappears in the latter concept descriptions. I
> think this is probably just because you ran out of time for writing
> them, but I want to make sure it isn't missed latter.

Yes.  the entire Concepts section needs to be restarted.

> About "Getting Started"
>    The pqs includes an all_types.hpp header, that is a one stop include
> for all of the available types. Unfortunately, I see no place in the
> documentation where you mention this. Instead, you include long lists of
> includes when you want to use multiple types. Most new users will
> probably find this a barrier, since the first concern will be using the
> library, and only later will the users turn to reducing compile times
> and sizes (if needed). I think the first couple of examples should just
> use the all_types.hpp header, and in a later example point out that the
> user can choose to only include the segments of the library that are
> needed. Maybe even create an "all_types.hpp" at a higher directory level
> that includes the types, the I/O capabilities and the whole thing. This
> is not a good solution for the tightest include lists possible, but it
> is great for someone who doesn't want to have to figure out which pieces
> are where for the first few uses of the library.

The problem is that the number of quantities in all_types.hpp could get very
large. The first effect is slow compilation. The second is the compiler running
out of storage, or indices or keys or whatever, so though I understand the point
I am slightly wary of doing this. The other issue is that slow compilation
reflects badly on the library, especially for first time users.

>    The examples in the Getting Started section are fine for getting the
> basic uses of the library across. It is clear that the additional typing
> is minimal and that the code really does become more clear. This could
> be improved somewhat by showing how to convert a couple of toy
> calculations in the section. Start from what might have been written
> originally, and show how it is more readable with minimal intrusion and
> improved error checking after conversion. Many of the first time users
> will be people who are struggling with unit problems in a partially
> constructed code, so make the Getting Started section reflect likely
> user experiences.

OK. It is difficult to pick the right level. I should maybe also add some info
or links regarding units , dimensional analysis and so on.

> About the examples
>    After the Getting Started section, the next place someone is likely
> to go is the "Examples." I would like to see them accessible from the
> documentation, with capsule explanations of what is important in each
> one, so the new user can pick and choose what is important for the
> current uses.

Yes. That should be added.

>    The examples themselves are nice. They just need an easy entry for
> the user.

OK.

>
> About the implementation
>
>    The implementation appears reasonable, though I have not been able to
> put the time into it that would be required to understand all of the
> details. My primary issue is with the attachment between specific units
> and prefixes. For example, in the length units, the prefixes for powers
> of ten are connected only to the meters units. In my work, attaching
> them to other units (such as MeV for mega electron volts or Gpc for
> Giga-parsecs) is quite common. Without developing a detailed
> understanding of the implementation, I have no suggestion for how to
> decouple the prefixes from the specific units, but it is a question
> worth considering. The prefixes are in common use with a wide range of
> base units, so some method of decoupling strikes me as a good choice.

The library only deals in SI units and not natural units, except in their
relation to SI units and as constants expressed in SI units. This is a weakness
of the library, but reflects the fact that I have no experience in natural units
or other unit systems and how they are combined and operate.

I am aware that Walter Browns original SI units could be used with various unit
systems and units could even be converted between them, but in PQS I have
(rightly or wrongly ) opted to only cover SI units to limit the scope of the
project to something manageable. I realise that this is disappointing  however
there are enough problems within one
system ( such as the problem of linear algebra on quantities discussed in
another thread), that I would prefer to solve them satisfactorily for one system
rather than try to create a half-finished solution to cover every
system.

The most pertinent question that I dont know the answer to is whether there are
benefits in practise to using physical quantities in large scale systems over
using floating point types or not. It may well be that using quantities is
impractical for various
reasons (incompatibility of libraries, compilation times) or others unknown as
yet.

I should however try to ensure that the library can potentially be extended to
other unit systems as far as possible, and currently it is weak in that area.

>    In use, the impact of the names for the quantities is not a problem
> for me. There is increased typing in some places, but the added clarity
> and the reduced need for additional descriptive comments in the code
> convince me that it is worth it.

Yes.  At least in simple use the library does seem to be a win over use of
traditional floats.

> My use of the library
>
>    I only had a couple of hours to give to this, so I did not get to do
> anything more than read the documentation, skim the implementation and
> try a few of the examples. I would like to rework a couple of pieces of
> simulation code to use this, but I just can't give that time at the
> moment. From my small experience of it, I think it is a good starting place.
>    In compiling the examples, I have had a few issues. I'm waiting to
> report them until I have the time to formulate a small example that
> displays them, or even better to find the problem. I get compiler errors
> in some cases, using OSX 10.3.9 and gcc 3.3.

OK. The library could benefit from the substantial Boost test infrastructure if
accepted  too.

> My one request
>
>    I think this will become a reality with the addition of the type_of
> library, but I strongly request an easy way to add new units. In my work
> writing physical simulations, most of the time I use simulation units
> instead of any standard physical unit. This is done for the usual reason
> of keeping the numbers in the calculation as close to order 1 as
> possible, to minimize the numeric issues.

Having spent time with SI units, I am unclear what you mean. Is it possible to
demonstrate with an example?

> Only rarely is there a
> convenient physical unit for this, so simulation units and various
> dimensionless quantities are the rule for me. As such, I will often have
> the need to define new units when using this system, so I would like it
> to be as simple as possible.

OK. I am ware that the whole rigmarole involved in defining types and units
could be improved. Composition with Boost Typeof would help as well as improved
Concept docs perhaps.

> My understanding of the problem domain
>
>    I have a reasonable understanding of the issues encountered while
> writing physical simulations, and only a passing understanding of the
> implementation issues involved in writing a library of this sort.
>
> Recommendation
>
>    I am in favor of including this library in Boost. As noted above,
> there are issues I would like to see addressed, but on the whole I think
> this is a good piece of work and fills a very large need in the
> computational science and engineering community.

Great. I suspect that the answers I gave arent totally satisfactory, especially
regarding moving beyond the SI system, but at least I shall try to make PQS
extensible to other systems

Thanks for your review.

regards
Andy Little