dimnum

[overview]

[download]

[table]

[examples]

Overview

The dimnum library contains templated C++ classes for storage and manipulation of dimensionful numbers, as encountered in physics and engineering. It very roughly follows an idea explained by Barton and Nackman (see "Scientific and Engineering C++", section 16.5), with various extensions. Due to the use of templates, there is no size or speed penalty with respect to normal variables (the latter depends on compiler optimisations; in practise the GNU compiler produces slightly slower code when dimnum numbers are used).

The dimnum library code is available under the terms of the GNU General Public License.

The SIunits library does something similar, but there are a few differences

1. In both dimnum and SIunits, numbers are represented in a given base (ie. you can for instance declare a length object which is expressed in meters). In SIunits this base unit ("one meter") is fixed at compile time (ie. all values are represented in meters), while in dimnum it is a template parameter. In dimnum you can have (in one program) both values expressed in the SI basis and in, for instance, the British foot/inch/... basis, while in SIunits you have to make a choice.
2. Dimnum uses a different treatment of models in which dimensions 'merge' (for instance the 'high energy physics' model, in which the speed of light and Planck's constant are put equal to one). In dimnum models can be mixed, in SIunits you have to choose one.
3. Treatment of I/O differs (dimnum's method uses more static data where SIunits uses dynamical switches); a bit hard to explain in one or two lines.
4. Dimnum's actual code (i.e. excluding the constant lists and the dimensionful number declarations) is also a bit smaller.

Whether or not any of this is important for you depends on the application. I wrote most of dimnum before I knew about SIunits.

Dimnum has appeared on Sweetcode.

Download and install

You need the following additional software in order to compile and use dimnum:

• My C++ helper library proj++ (which takes care of building shared libraries and provides timers).
• A decent C++ compiler; gcc 2.95.3 and higher will do.

Then download and install dimnum.tar.gz. The current version is 1.16 dated 2006-04-10. The usual GNU installation instructions apply.

Usage

Upon including dimnum.hh several templated classes are available which represent the seven basic units,

dn::length<class representation, class base>

dn::mass<class representation, class base>

dn::time<class representation, class base>

dn::current<class representation, class base>

dn::temperature<class representation, class base>

dn::amount_of_substance<class representation, class base>

dn::luminous_intensity<class representation, class base>

The representation template parameter should be a numerical class, e.g. double. The base parameter is a class which represents the base unit in which the numerical value should be interpreted (taken from the unit:: namespace, see below). Many other classes are available as well (for eg. energy, entropy and so on); see the bottom of dimnum.hh for a complete list.

Actual unit classes (representing a conversion factor to the SI system) are available in separate header files. For instance, upon including the si.hh header, the following classes and object instances are available:

unit::meter	A class that can serve as the base parameter of the dn::length<...> class.
unit::centimeter	Another such base class.
si::length<class rep, class base=unit::meter>	A templated class for storage of lengths, by default expressed in meter units.
si::meter	An object representing the dimensionful number ``1 meter''.
si::centimeter	Ditto for ``1 centimeter''

It is important to understand the above difference between number classes (object types for storage of dimensionful numbers), unit classes (conversion factors to the SI system) and explicit instances (representing "1" in the given units).

In most applications, the only thing you need to know is how to declare an object for a dimensionful value, and how to access a static object that represents ``one'' in the given units. These are both taken from the namespace representing the measuring system, e.g.

// an length object measured in meters.
si::length mylength;

// set it equal to the si equivalent of a foot.
mylength=british::foot;

Known dimensions and constants

Currently the list of dimensions and known constants is still a bit small, though easily extended through addition of the required conversion factors to the header files. The following header files are present:

file	description
si.hh	SI units and prefixed ones
british.hh	British length units
typesetting.hh	Typesetting length units (point, didot, ...)
hep.hh	High-energy physics units in which the speed of light and Planck's constant are both set to 1.
constants.hh	Various physical constants.

Sample uses

The following is a minimal program to illustrate the use of the dimnum library. For more complicated uses please refer to the tst.cc program in the distribution tarball.

#include <dimnum/dimnum.hh>
#include <dimnum/si.hh>
#include <dimnum/british.hh>

int main()
   {
   si::length<double> mylen(3.0);
   std::cout << mylen << " equals " << british::length<double>(mylen) << std::endl;
   }

which produces the output

3 m equals 118.11 in