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