Re: [boost] [Review][PQS] Physical Quantities System review (May31through June 9)

From: Andy Little (andy_at_[hidden])
Date: 2006-06-06 16:33:10

Hi Paul,

"Paul A Bristow" <pbristow_at_[hidden]> wrote in message
news:E1FneN9-00014T-OY_at_he303war.uk.vianw.net...
>|  -----Original Message-----
> |  From: boost-bounces_at_[hidden]
> |  [mailto:boost-bounces_at_[hidden]] On Behalf Of fred bertsch
> |  Sent: 31 May 2006 18:07
> |  To: boost_at_[hidden]
> |  Subject: [boost] [Review][PQS] Physical Quantities System
> |  review (May 31through June 9)
> |
> |  The review of Andy Little's Physical Quantities System
> |
> |   - What is your evaluation of the design?
>
> Examples suggest that it should meet many needs of many users.

It may be worth noting that the potential users are scientific, engineering and
education, which may be slightly different from regular boosters, but is still a
wide user base

> I like that it handles rational power units that some users really do need.

FWIW the inclusion of rational powers of dimension did initially increase
compile time, so I had to spend considerable time customising this to get
compile times down again.

> |   - What is your evaluation of the implementation?
>
> Not very qualified to judge.
>
> Seems complicated, but I fear this is necessary, and badly needs typeof to
> complete it,

Yes. Boost.Typeof becoming available in the next Boost release will really help
to simplify use for 'auto' variables for intermediate results of complicated
calculations and also faciliate composition of ones own quantity types, which
can be a bit cumbersome at the moment without it. I need examples of that though
too.... when Typeof comes out.

> but it is best effort so far, and worth getting more people to try it 'in
> anger'.

Thanks. I have had some feedback that it seems to work well in refactoring at
least small projects.
Philosophically the library is an experiment in strong type checking. Its not
painless. It does
remain to be seen whether that scales or not though.
Ultimately I need to emphasise that the library presented will need supporting
classes. matrices, vectors, complex quaternion, entities representing (say) a
force vector at a position etc , etc. for scaleability. Or ways to exit the type
checking of course.

> As noted before, I would very strongly prefer this called Boost.Units rather
> than PQS,
> (I am not convinced that it is limited to 'physical' quantities).
>
> (Note plural UnitS to avoid any confusion with singular Unit Test, now
> Boost.Test).

I know that you previously didnt like the suggestion si_units, because some
units arent SI , however my position is that we are being encouraged to move
away from non-si units so calling the library si_units or SI_units does make
sense to me. One might question the logic of:

si_unit::length::in

for inches though, implying that inches is an SI unit which it isnt.

I could call the library PQSunits or some such ?

> AND I think a more descriptive name(s) for "t1_quantity" etc is needed.

I know its bad!. I have been trying to come up with other names without much
success so far though.

> |   - What is your evaluation of the documentation?
>
> Useable, but badly needs some editorial work on spelling, punctuation etc.

OK. Unfortunately I dont find doocumentation easy or fun, but I will have to
keep at it. I think it is getting better slowly.

> I would put a QuickStart item at the very top with a typical example, and
> links to your examples, the link name showing its 'feature'.

Yes.  There needs to be a reorgansiation of the layout.

> ERD should be spelt out in full.

OK.

 > Many very helpful and persuasive examples - but not referenced with links
> from the docs?

OK.

BTW As a general Question relating to Boost... I was confused for some time as
to whether the  <libs/examples> and
<boost/progheader.hpp> directories are always meant to be in the same relation.
Is that laid down anywhere so that headers can be linked in docs?

> I didn't spot any examples of ex-Imperial Non-SI units, beloved of the
> ex-Colonial US ;-)

OK. I will add one :-)

> BUT examples would be more helpful with the output shown both inline as
> comment(s), like
>
>   std::cout << angle::rad(angle::deg(180)) <<'\n'; // 3.14159 rad
>
> AND all output appended to the code as a comment, for example:
>
> /*
>
> Output is:
>
> A current of 5 mA
> through a voltage of 5 V
> requires a resistance of 1 kR
> and produces 25 mW of heat
> total energy used in 1 s is 25 mJ
> Press any key to continue . . .
>
> */

OK.

> It is very helpful (and worth copying by all Boost authors, especially of
> examples)
> that the feature(s) being exemplified (angle) is/are enumerated thus:
>
> using boost::pqs::angle;
>
> angle::rad  a = angle::pi;
>
> ...
>
> (but sadly often not done this ideal-for-the-reader way!)

OK. One could also argue that all headers required should
be included so that copy pasting, then compiling, works. Any feedback on that
appreciated...

> |   - What is your evaluation of the potential usefulness of the library?
>
> Invaluable in most walks of real life.  (SI) Units long recognized as a
> vital library function for Boost.

Yes. This is why I am a bit sad that there havent been some more reviews so far,
(and thanks to everyone that has contributed a review).
PQS is not a particularly cool ,bleeding edge or *sexy* library but it does come
up in everyones
everyday life time and again.. There is a lot of potential for standardisation
and not reinventing the wheel ( just as with math constants) in this field.

> |   - Did you try to use the library? Briefly. With what compiler? MSVC 8
>
> Did you have any problems? NO - examples build and run OK.
>
> |   - How much effort did you put into your evaluation?
>
> A quick skirmish ;-)
>
> I'd like to see examples of real use in anger - but I fear we may not get
> that until it is accepted into Boost (chicken/egg problem?).
>
> |   - Are you knowledgeable about the problem domain?
>
> Somewhat.
>
> I vote for acceptance.

Great. Thanks Paul!

> Paul
>
> PS A few queries:
>
> 1  Can value_type include rationals - so that (only) fractional lengths
> (say) like 1/2, 1/4, 1/8, 3/4, 3/8, 5/4, 9/16 ... could be handled?

Some experimentation suggests that they can but its brittle and needs
Boost.Typeof:

#include <boost/pqs/typeof_register.hpp>
#include <boost/pqs/t1_quantity/types/out/length.hpp>
#ifndef BOOST_PQS_USE_BOOST_TYPEOF_BINARY_OPERATION
#error need to have Boost.Typeof library and #define
BOOST_PQS_USE_BOOST_TYPEOF_BINARY_OPERATION in <boost/pqs/config.hpp>
#endif
#include <boost/rational.hpp>

#include BOOST_TYPEOF_INCREMENT_REGISTRATION_GROUP()
BOOST_TYPEOF_REGISTER_TEMPLATE(boost::rational, 1);

int main()
{
    typedef boost::rational<int> rat;
    typedef boost::pqs::length_<rat >::in rat_inches;

    rat_inches length1(rat(1));
    rat_inches length2(rat(1,2));
    rat_inches result = length1 + length2;
    std::cout << result << '\n';
}

tested in CVC7.1 only
however rational +int value_types fails in a horrendous cascade of errors. I
dont know if it can be made to work, but its now on the todo list FWIW.

> 2  If math is the abbreviation for math constants, then physics doesn't
> match.  physical better? Only one letter longer.

Some users have expressed an interest in removing the physic(s)(al) sub
namespace altogether so these constants would be in namespace pqs(or whatever it
ends up being called)

pqs::boltzmanns_constant::K

etc.

In this case the quantities namespace would stand in for the physic(s)(al)
namespace. The rationale being that the form of the constants need the
quantities machinery anyway. OTOH maybe phys || physics || physic || physical
could replace pqs...

> 3  dimensionful is a new word on me - dimensioned (opposite of
> dimensionless).

OK. It look like I'm not going to get away with adding words to the English
language :-)

Does 'dimensioned' adequately convey "not including dimensionless"? Or is it 
inclusive of that?

> 4  It isn't immediately obvious to me how to ensure output in SI
> 'engineering' multiples, depending on the value.
> For example, 0.123 m outputs as 1.23 mm, but 1234.5 m outputs as 1.2345 km.

OK. I should document it. As it stands its simply dependent on the current
output flags for the quantity value_type, however the whole area of input/output
is not adequately documented so far.

Thanks again for your review and your vote too.

regards
Andy Little