Re: [boost] [review] pqs

From: Andy Little (andy_at_[hidden])
Date: 2006-06-07 17:16:54

"Beth Jacobson" wrote
> Andy Little wrote:
>> Hi David,
>>
>> "David A. Greene" wrote
> For me, the real bar to comprehensibility is the signs on the exponents.
> When I see kg.m+2.s-2, I read it as kg-dot-m plus 2-dot-s minus 2. If it
> could it be written like this:
>
> kg.m2_div_s2
>
> it would be much clearer.

The use of dots and signs is again based on the SI.  See for example section 
6.1.6 in the 'Guide for the use of the International System of Units'.
The +ve sign is redundant but I liked the symmetry and it felt better that 
leaving it out. and IMO underbars are overused in C++ already.

>>>  - What is your evaluation of the documentation?
>>>
>>> This needs a lot of work.  It seems to assume a deep understanding of
>>> SI standards and terminology (beyond the unit names and what they
>>> mean) and introduces lots of terms itself (abstract_quantity,
>>> named_quantity, concrete_quantity, etc.).  The presentation is
>>> overwhelming.
>>
>> As discussed before, I think moving the definition of terms to the back of 
>> the
>> docs will go a good way to solve this.
>
> I disagree. First, David's criticism ("It seems to assume a deep
> understanding of SI standards and terminology") doesn't apply only to
> the glossary. You can't get through the first paragraph of "Basic
> Useage", (shouldn't that be "Usage"?) without encountering "t1_quantity
> specification", "concrete_quantities", and "named_quantity". These terms
> are going to send a lot of people straight to the definitions page
> wherever it's located. Those concepts may be necessary for a complete
> understanding of pqs, but I suspect that someone could use the library
> in a simple implementation without knowing much about them. If that's
> true, they should also be able to read the basic usage section without
> encountering that terminology. It might also be helpful to have a
> "Physical Quantities Concepts" page, with a concrete example of some
> object or system which would illustrate the terms. This would
> familiarize readers with the necessary terminology in a straightforward,
> easily comprehensible way, reducing their reliance on the definitions page.
>
> Second, the definitions themselves are sometimes rough going. Dimension,
> for example, is defined like this: "The dimension of a physical_quantity
> is comprised of the powers of each of its base_dimensions."
> Physical_quantity quantity is defined as "A measurable physical
> phenomenon," and base_dimension as "A simple, measurable and essentially
> irreducible physical phenomenon." This means that base_dimension is
> really a simple and essentially irreducible physical_quantity (i.e. a
> base physical_quantity) which suggests that 'physical_quantity' and
> 'dimension' are interchangeable, but the definition of dimension
> suggests that it's an attribute of physical_quantity having to do with
> powers. Even after browsing most of the documentation, including the
> definitions page, I still don't really understand the distinction
> between dimensions and physical quantities.
>
> The definitions page also describes coherent_unit as "essentially units
> designed as part of the SI", and incoherent_unit as "essentially a unit
> outside the SI." That being the case, why not just use SI and non-SI, in
> place of coherent, and incoherent?

The whole definitions section is obviously problematic. Originally the entities 
reffered to appeared out of the bottom-up style the library was written in. 
Trying to explain them to anyone else is not my forte. It is difficult to 
describe the semantics without them however. I wonder if the library can claim 
to have the most complicated operation semantics of any C++ library in 
existence!

>>> I found the colored links to the terms all over the documentation to
>>> be distracting.  It really interrupted the flow of the text.  It would
>>> be better to make these links that look like ordinary text but are
>>> highlighted/underlined when the cursor moves over them.  The links
>>> need to be there but they should be less intrusive.
> >
>> OK.  I would guess that is a CSS issue.
>
>
> I'm not convinced they really do need to be there. The BGL doc, for
> example, has an introductory section explaining terms like vertex,
> edge, etc., and then uses those terms throughout, without links to
> definitions. If the pqs doc did the same, at least with basic terms like
> 'dimensions', 'units', etc, it would reduce the number of links
> enormously. It might be nice to have a standard definition-link style in
> the Boost CSS anyway, but I don't think that's essential.

Its worth experimenting with surely.

>>>  My suggestion would be
>>>     to organize the rationale like this:
>>
>>> * Increases programmer satisfaction and enhances productivity.
>>>    * Strong type checking enforces dimensional integrity, catching
>>>      calculation errors at compile time.
>>>    * Automated unit conversion reduces drudgery.
>>>    * Self documenting, helps code clarity.
>>
>
> I'd leave off the first sentence altogether. When I read that pqs
> catches errors, eliminates the need for tedious (and error-prone)
> explicit conversions, and improves code clarity, I immediately recognize
> those as Very Good Things. I don't need the docs to tell me I'll be more
> satisfied and productive as a result.

OK.

> A few more observations:
>
> The "Introduction to pqs" page is not very helpful. The first thing I
> want a library doc to tell me is what the library does and whether it's
> worth investigating further. The introduction instead starts out with an
> "Overview", which mostly talks about what pqs will eventually do in the
> future. While interesting, that doesn't really belong in the
> introduction. I'd much rather see something like the 'Description'
> section of Fred Bertsch's review announcement post:
>
> "PQS (Physical Quantities System) is designed to replace the use of
> floating point types for modelling physical quantities in C++
> programs. Advantages include automated dimensional analysis checking,
> automatic unit conversions, self documentation of code and uniform
> mechanisms for dealing with physical quantities overall, allowing
> better interoperability, accuracy and repeatability among engineering,
> physics and trade applications."
>
> From just that one paragraph I've already got a pretty good idea about
> whether pqs is going to be useful to me.

OK.

> A tutorial with a simplified real-world example of a pqs-enabled program
> would also be very helpful. The "Getting started" page contains a lot of
> code snippets but most of them illustrate only declarations and simple
> operations. I realize that encompasses most of what pqs does, but it
> would still be nice to see them in different contexts, e.g. std
> containers of physical quantities, functions with physical quantities as
> parameters, etc. I'd particularly like to see an example of pqs
> interoperating with boost.date_time. They'll be a natural combination
> for many applications, so it would be nice to see code that converts
> between them.

OK. I will try to incorporate some bigger examples.

Thanks for the comments.

regards
Andy Little