Documentation of Quantities - C++ Classes for Quantity Calculus
Version 1.2.2+
Introduction
Quantity calculus concerns calculations with numbers that are associated with a unit of measure and are characterized by a dimension. Such a number is a quantity. Quantity calculus supports the use of appropriate units for a given quantity, the correct transformation of the quantity's value if different units are valid for the same quantity, and the consistent application of dimensional analysis if quantities are combined in calculations. The importance of quantity calculus has been demonstrated in various contexts, ranging from correct, consistent, and unambiguous labeling of graph axes and table headings [White_1998], to the spectacular failure of a spacecraft caused by the inadvertent mix-up of units [Hall_2002].Quantities implements quantity calculus within C++ and provides classes to define appropriate objects that do not only encapsulate a numerical value but also a dimension and a unit. The objects may be used in calculations just as doubles or ints are used in a classical C++ program. Quantities are advantageous in, but not necessarily restricted to, scientific calculations. Quantity objects could also be used in any kind of numerical treatment where dimensions and units are important.
Quantities enforces the consistent use of units according to the internationally acknowledged Système International d'Unités (SI), which is a "recommended practical system of units of measurement" [BIPM] and is widely used in science and technology (for more information in the wider context of metrology, see [VIM]; for a brief account on the occassion of the 50th anniversary, see [Mills_2010]). A quantity may have several associated units, which are conventionally used for this type of quantity [Cohen/Cvitas/etal_2007]. Its numerical value changes if we substitute one of these units by another one. Idiosyncrasies of some particular SI quantities and/or their units are taken into account. For example, the different temperature units are implemented. Non-SI units are provided if these are accepted to be used in conjunction with the SI. Since the conversion of numerical values of a quantity between different associated units is so important in science, such transformations are supported within Quantities in a safe way.
With Quantities it can be assured that the result of a calculation is consistent with respect to the quantities' dimensions. Dimensional analysis and checks for correctness are implemented within expressions between quantities objects. Different quantities constitute different C++ types. Consequently, Quantities allows the type safe use of quantities within a program. Run time overhead is minimized by the use of the template possibilities of the C++ language. The quantity types are fully integrated into the C++ type system.
The Quantities package provides headers and libraries that implement variables, constants, and unique constants. While variables may attain any acceptable value and may change their value during program execution, constants have a value assigned at construction time, which can not be changed later. Unique constants have a fixed value which is defined at compile time and which can not be changed at all by the user. For example, natural constants can be implemented as unique constants.
Quantities provides a home page and a repository for code is located at sourceforge.
The idea to use C++, its template facilities, as well as object oriented analysis and design in the context of dimensional analysis and unit conversion has been reported several times. Some ideas go back to Barton and Nackman [Barton/Nackman_1994] as well as [Meyers].
The Boost library [Boost] has included a package related to quantities: the Units library included into Boost with version 1.36.0. On the other hand, the Physical Quantities System was rejected [PQS] during the Boost review process, but it seems to be available at Sourceforge as project Quan according to this source). The Boost MPL library [MPL] has also been used for dimensional analysis [MPL tutorial].
Both these libraries seem to be heavily centered around the `unit' and 'dimensional analysis' concepts, while in Quantities, the quantity is the starting point. Insufficient separation of the concepts 'quantity', 'unit' and 'dimension' may lead to ambiguities (see, Concepts). Moreover, their definition of commensurability (see Concepts) seems to mix the use of dimensions and units, which may lead to ambiguities. Consequently, in contrast, it is suggested heres to avoid such problems by clearly use `quantity' as the most basic and independent concept see also the discussion of Wallot's ideas [deBoer_1995](p. 408) declaring physical quantities as "the primary concepts") and to view a 'unit' and a 'dimension' as its properties. Thus, a 'unit' will not be defined as a special type of quantity as proposed by Maxwell [deBoer_1995].
Furthermore, the following projects are related:
- Unum (a Python module)
- the Units Conversion Library
- JQuantity (in Java)
- dimnum (in C++)
There used to be a SIunits library [Brown_2001][Brown_2003]. However, presently, this link seems to be outdated for some time now (see [SIunits experience?]).
The Quantities software package is composed of several parts:
- Quantity - a collection of basic (mostly template) classes for quantity calculus, including larger aggregates of quantities, like vectors, and vector tuples (for details, see the Quantity documentation).
- GeneralQuantities - a collection of classes for general quantities (for details, see the GeneralQuantities documentation).
- PhysicalQuantities - a collection of classes for specific physical quantities, such as e.g. time, electric potential etc., according to IUPAC conventions (for details, see the PhysicalQuantities documentation).
- MathematicalQuantities - a collection of classes for mathematical quantities and constants, such as e.g. pi. (for details, see the MathematicalQuantities documentation").
- GUI - a collection of classes to build a graphical user interface to quantities (for details see the Quantities GUI documentation).
Typographical Conventions
In this documentation, we will use bold face for names of packages, modules, and software,typewriter text for computer code, commands etc. Text in italics is reserved for items in a command oder in code which have to be substituted by an appropriate value depending on context (e.g., a directory name). Also, emphasized words are written in italics.Please contact the author of the program at berndspeiser@users.sourceforge.net if you have specific questions about the software. Also, let us know if you use Quantities in your projects and work. We are interested in your experience with this software.
References
[White_1998] M.A. White, J. Chem. Educ. 75, 607 - 609 (1998).[Hall_2002] B.D. White, Software Support for Physical Quantities, presented at the 9th Electronics New Zealand Conference, University of Otago, Dunedin, 14-15 Nov, 2002; http://www.irl.cri.nz/msl/MST/phy_quant.html
[Cohen/Cvitas/etal_2007] E.R. Cohen, T. Cvitas, J.G. Frey, B. Holmström, K. Kuchitsu, R. Marquardt, I. Mills, F. Pavese, M. Quack, J. Stohner, H.L. Strauss, M. Takami, and A.J. Thor, Quantities, Units and Symbols in Physical Chemistry, 3rd ed., Blackwell Science, Oxford, 2007.
[BIPM] http://www1.bipm.org/en/si/ (web-site of the Bureau International des Poids et Mesures).
[VIM] http://www.bipm.org/en/publications/guides/vim.html (International Vocabulary of Metrology - Basic and General Concepts and Associated Terms (VIM), document produced by Working Group 2 of the Joint Committee for Guides in Metrology (JCGM/WG 2), 2008).
[Mills_2010] I. Mills, Chem. Intl. 32(6), 3 (2010).
[Barton/Nackman_1994] J.J. Barton and L.R. Nackman, Scientific and engineering C++: an introduction with advanced techniques and examples, Addison-Wesley, Reading, 1994.
[Meyers] http://www.aristeia.com/sdnotes_frames.html, 10 Cool Things in C++ -- Plus Something Wicked.
[Boost] http://www.boost.org
[Units] http://www.boost.org/doc/libs/1_45_0/doc/html/boost_units.html
[PQS] http://lists.boost.org/boost-announce/2006/06/0096.php
[MPL] http://www.boost.org/doc/libs/1_45_0/libs/mpl/doc/index.html
[MPL tutorial] http://www.boost.org/libs/mpl/doc/tutorial/dimensional-analysis.html
[Brown_2001] W.E. Brown, Applied Template Metaprogramming in SIunits: the Library of Unit-Based Computation, Proceedings of the Second Workshop on C++ Template Programming, Oct. 14, 2001, Tampa Bay, Fla., USA; the document can be downloaded here.
[Brown_2003] W.E. Brown, A Case for Template Aliasing, Document WG21/N1451 = J16/03-0034; the document can be downloaded here.
[deBoer_1995] J. de Boer, Metrologia 31, 405 - 429 (1994/95).
[Siunits experience?] http://www.codesourcery.com/archives/pooma-dev/msg01801.html
