Reference Manual

Introduction

The reference manual provides concise descriptions of the classes and their functionality available in Quantities.

Dimension

A dimension defines the relation of a quantity to the seven base quantities of the SI.

Unit

A unit provides a standard of measurement for a value within a quantity.

Unit Types

Three different types of units are available:

Unit Properties

Each unit has the following pre-defined properties:

The name, symbol, standard factor, SI and exactness status of a non-prefixable and a prefixable base unit must be defined when defining the unit. The respective properties of a prefixed unit are generated from the prefixable base unit and (if necessary) modified by consideration of the unit prefix. The properties of a compose base and a composed unit are automatically generated at compile time from the components' properties and (as regards the standard factor) the standard factor of the compose base unit.

Unit Symbol Grammar

A unit symbol is a character string determined by the following grammar (EBNF like, but not necessarily fully conformant, with some extensions used in the Spirit parser library; + = one or more occurences):

unit-symbol = primitive-symbol | composed;

composed = +(component, [' ']);

component = symbol, exponent;

exponent = [('^', numerator, '/', denominator) | ('^', numerator)];

numerator = long-integer;

denominator = unsigned-long-integer;

long-integer = ['-'], +digit;

unsigned-long-integer = +digit;

symbol = primitive-symbol | composed-symbol;

primitive-symbol = +alpha;

composed-symbol = '(', +unit-symbol, ')';

alpha = alphabetic character;

Unit symbols of non-prefixable and prefixed units are primitive symbols, consisting of alphabetical characters. A symbol of a composed unit, on the other hand, is composed of one or more components, separated by a space. A component consists of a symbol and an exponent. The latter is a rational number in fractional notation and purely optional, but if it is present, it starts with a `^' character followed by a numerator (a long integer). If a denominator is present, it is preceded by a '/'. The component symbol is either primitive (consisting of one or more alphanumerical characters), or it is a composed-symbol, which is enclosed in parentheses, and recursively contains other unit-symbols.

Unit Prefixes

In line with the SI, the following unit prefixes are defined:

prefix name prefix symbol prefix value
deci d 10e-1
centi c 10e-2
milli m 10e-3
micro u 10e-6
nano n 10e-9
pico p 10e-12
femto f 10e-15
atto a 10e-18
zepto z 10e-21
yocto y 10e-24
deca da 10
hecto h 10e2
kilo k 10e3
Mega M 10e6
Giga G 10e9
Tera T 10e12
Peta P 10e15
Exa E 10e18
Zetta Z 10e21
Yotta Y 10e24

Additionally, an empty prefix is defined:
prefix name prefix symbol prefix value
empty prefix - 1

Unit Functionality

Unit Properties Access

The following five static member functions retrieve the properties of a unit:

Unit Compile Time Functionality

The following structures provide compile time functionality to a unit:

These structures are supported by the following helpers:

Unit Run Time Functionality

The following structures provide run time functionality to a unit:

The functionality is supported by the following static helper functions and helper classes:

Unit Helper Structures and Classes

The following helper structures and classes are defined for a unit: ... describe all functions ...

Unit Exceptions

The follwing exceptions (all derived from unit::UnitError) are defined:

These exceptions can occur whenever run-time use is made of a unit symbol in dynamic (reverse) standardization.

Quantity

Variants of Quantities

Any kind of quantity is characterized by a certain set of features, most importantly its dimension and its associated units. In Quantities these characteristics are collected in the base quantities (not to be confused with the SI base quantities mentioned in the Concepts section). For each quantity type, one and only one base quantity exists.

On the other hand, for each base quantity, however, there may be several types, which have the same characteristic features, but differ in some other respect. For example, among electric charge quantities we might have variable or constant values. Moreover, we might have special electric charge quantities, which have fixed values in every context, for example, the electron and the proton charge. All the electric charge quantities share the dimension of electric charge and the units in which the values can be expressed. We will call such sub-types of quantities derived quantities (again not to be confused with the concept of SI derived quantities).

In many cases, a physical quantity can be regarded as a variable, which might attain different values in the course of the calculation. In some cases, the value must be fixed at first use, and not be changable thereafter. As discussed in the quantities concepts section, such a physical quantity will be denoted a constant. In still other cases, the value of a constant is universally fixed and can never be changed. A particular case of such unique constants are fundamental physical constants [Cohen/Cvitas/etal_2007] (p.111). We will refer to these also as natural constants. Recommended values for fundamental physical constants are compiled and accessible online [CODATA]. Their values may be experimentally determined (e.g., the elementary charge), calculated from other such constants' values (e.g., the Faraday constant), or defined (e.g., the zero of the Celsius scale) [Cohen/Cvitas/etal_2007] (p.111). The numerical values may be subject to changes with experimental progress.

A quantity may have various modes of accessibility. This will influence its use.

... storage type ... storage unit ...

... Dynamic ... Generated (generic?) -> do only consider dimension for convertibility, since coherent unit is used (special case!) ...

Quantity Properties in C++

Names and symbols of quantities should have some reasonably defined default value, which might be overwritten by the user when generating a quantity, or at some later stage.

It will turn out advantageously to group quantities together according to some of their basic properties: among others the dimension and the list of units which can be used with the quantity. Such quantities belonging to the same quantity type may differ for example in the particular unit in which the numerical value is measured, or in the way the numerical value is expressed (e.g., with or without a decimal point).

Operations with Quantities

In order to use quantity calculus within a computer program, in particular one that is written in a programming language such as C++, it might be advantageous to have available a mechanism to directly treat quantities in a way similar to the use of `normal' numbers, while observing the rules of quantity calculus. Thus, for example, if possible in terms of commensurability (see below) quantities at least the following operations should be available: construction/deletion, copying, assignment, state reporting, arithmetical calculations, mathematical functions, comparison, input and output, serialization. (add ... as appropriate ...)

A quantity will be realized a C++ object.

Conversions might be realized as copy (see above) or assignment (see below) operations.

Addition (common symbol: $+$) and multiplication (common symbol: $*$ or $\times$ or $\cdot$) are commutative operations. The two operands in an addition operation must be commensurable. The same is true for subtraction. On the other hand, no restriction is placed on the operands of multiplication and division operations in terms of commensurability.

... other arithmetical operations ...

Unary + and - operations work on the sign of a quantity, either leaving it as it is or changing it into the opposite. As a result, unary + does not change its operand at all. It was added to the ANSI C standard as a symmetry complement to unary - [Kernighan/Ritchie_1988](p. 204).

Increment and decrement operations should be designed in analogy to the predefined counterparts for for built-in types. Thus, prefix and postfix variants are considered. All these operations change the value of the quantity object. Consequently, only variable forms of a quantity can be incremented or decremented, and these operations are not defined for constant or unique-constant mode.

Unary + and - operations work on the sign of a quantity, either leaving it as it is or changing it into the opposite. As a result, unary + does not change its operand at all. It was added to the ANSI C standard as a symmetry complement to unary - [Kernighan/Ritchie_1988](p. 204).

Increment and decrement operations should be designed in analogy to the predefined counterparts for for built-in types. Thus, prefix and postfix variants are considered. All these operations change the value of the quantity object. Consequently, only variable forms of a quantity can be incremented or decremented, and these operations are not defined for constant or unique-constant mode.

... other arithmetical operations ...

... other concepts ...

The Quantities package provides header files and libraries which facilitate to write C++ programs incorporating quantity calculus. This is basically done by defining various types which have built-in abilities to follow and enforce the rules of quantity calculus. Thus, commensurability is tested for numerical and assignment operations, and units are taken into account. Furthermore, other operations are provided (Quantity library). There is also a collection of often used scientific (physical) quantities (see, Physical Quantities) in the PhysicalQuantities library, which is part of Quantities.

Once a C++ program has declared objects with the types mentioned, they can be used to perform quantity calculus. Such an object is generally referred to as a quantity object in the following. The type of such an object is the quantity type. We will further categorize quantity objects by their mode, i.e. whether they refer to a variable, a constant, a unique constant, or an unnamed transient variable.

Unnamed transient quantity objects are often internally created (generated quantity objects), for example as return values of a function. Such objects can be used in operations, but in lieu of a name within the program it is not possible to assign or change the value. Other sources of such quantity objects are certain constructor calls. If this is the constructor of a well-defined quantity, the resulting object carries full unit information. However, generated quantity objects have only limited knowledge about the unit in which the value is stored. In particular, it is assumed that the standardization factor of the unit is 1.0. Thus, generated quantity objects should be used with great care (see below).

In rare cases, dynamic quantity objects are generated and returned from a function. Such an object has a type Dynamic<ST>, where ST is the storage type used (see, quantitiesUserObjects). A dynamic quantity object's properties can not be tested a compile time, since they are only defined at run time. Thus, they are not subject to the usual rules within this package, and could result in errors, which are only detected when the program runs. Consequently, such objects should be avoided as far as possible. At least, they should be converted into or assigned to normal quantity objects as soon as possible after they are returned from a function.

Serialization

Serialization is the ``reversible deconstruction of ... data structures to a sequence of bytes'' (see, [BoostSerialization] ). Thus, the contents of the data structure is ``flattened'' [Serialization], exported, stored or transmitted and later used to reconstruct the object. In the context of Quantities, serialization is used to save the content of a quantity object to a file and later load it into an equivalent object within the same or a separate program run. This is not necessary for unique constants, since a quantity object of this mode has a defined value (and, consequently, a fixed state).

Special Values

For each quantity (except unique constants), four special values are defined:

Quantity Aggregates

A variable vector is a homogeneous collection of values, i.e. it consists of values based on the same quantity. This is different from a vector of quantity objects. The individual values can be set or retrieved from the variable vector in the form of quantity objects. Conversions are allowed between the units associated with the quantity on which the vector is based. For example, a number of time values (given in min) can be stored in a variable vector and time values in s may be appended to the vector, or some element in the vector may be retrieved as value in the unit h.

A VariableVectorTuple is a non-homogeneous collection of VariableVectors of equal length. Thus, the VariableVectors can be based on different types of quantities. Equal length ensures that it is always possible to retrieve a set of one value each from each vector as a common tuple of the corresponding quantities. An example would be the two or three coordinates of a point in a two- or three-dimensional space, respectively.

Other aggregates, which have not been implemented yet are a VariableMatrix and a VariableTable.

Variable Vector

A VariableVector is an ordered collection of one or more numerical values attributed to a certain quantity. Numerical values can be stored or retrieved from or to objects of that quantity or if conversion to the unit of that quantity is available. VariableVector member functions do never use objects of the storage type of the quantity.

A variable vector behaves in most situations much like a std::vector. However, all member functions of std::vector<> that use iterators or use vector elements as parameter(s) or return value are reimplemented, and their behavior differs from that of the corresponding std::vector functions.

A VariableVector is defined by the following template parameters:

Some physical quantities provide definitions of appropriate variable vectors.

VariableVector defines the following types:

(for the iterator types, see Variable vector iterators).

The types size_type and difference_type are taken from the underlying std::vector.

A VariableVector provides the following funtionality:

The following functionality differs from std::vector:

VariableVector supports the use of iterators with the following functions:

The iterators returned and decribed in more detail below (see, Variable vector iterators) return upon dereferencing variable objects rather than numerical values.

Variable vector iterators

Variable vector iterators are random access iterators [Josuttis_1999] derived from std::vector<> iterators with some additional properties. In particular, dereferencing of a variable vector iterator retrieves a quantity object rather than the numerical value stored in the variable vector at the respective place. Normal, const, reverse, and const reverse versions of a variable vector iterator are provided.

Dereferencing a VariableVectorIterator returns a reference to a Variable object, but not to the respective element in the underlying std::vector<>. It does not make sense to assign to this reference or otherwise manipulate it. This is different from a STL vector.

quantitiesReferenceManualReferences

[Dewhurst_2003] S.C. Dewhurst, C++ Gotchas, Addison-Wesley, Boston, 2003.

[Matta/Massa/etal_2010] C.F. Matta, L. Massa, A.V. Gubskaya and E. Knoll, J. Chem. Educ. 88, 67 - 70 (2010).

[Kernighan/Ritchie_1988] B.W. Kernighan and D.M. Ritchie, The C Programming Language, 2nd edition, Prentice Hall, Engelwood Cliffs, 1988.

[Josuttis_1999] N.M. Josuttis, The C++ Standard Library. A Tutorial and Reference, Addison-Wesley, Reading, 1999.

[BoostSerialization] http://www.boost.org/libs/serialization/doc/index.html [Serialization] http://www.parashift.com/c++-faq-lite/serialization.html

back to top

back to Quantities start page

Generated on Wed Apr 11 18:07:08 2012 for Quantities by  doxygen 1.5.6