units.qbk

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

    template<class S> struct is_heterogeneous_system< heterogeneous_system<S> >;

    template<class Dim,class System> struct is_unit< unit<Dim,System> >;
    template<class Dim,class System> struct is_unit_of_system< unit<Dim,System>,System >;
    template<class Dim,class System> struct is_unit_of_dimension< unit<Dim,System>,Dim >;

    template<class Unit,class Y> struct is_quantity< quantity<Unit,Y> >;
    template<class Dim,class System,class Y> struct is_quantity_of_system< quantity<unit<Dim,System>,Y>,System >;
    template<class Dim,class System,class Y> struct is_quantity_of_dimension< quantity<unit<Dim,System>,Y>,Dim >;

    template<class System> struct is_dimensionless< unit<dimensionless_type,System> >;
    template<class System> struct is_dimensionless_unit< unit<dimensionless_type,System> >;
    template<class System,class Y> struct is_dimensionless< quantity<unit<dimensionless_type,System>,Y> >;
    template<class System,class Y> struct is_dimensionless_quantity< quantity<unit<dimensionless_type,System>,Y> >; 

[endsect]

[endsect]

[section:Reference Reference]

[xinclude units_reference.xml]

[xinclude dimensions_reference.xml]
[xinclude si_reference.xml]
[xinclude cgs_reference.xml]
[xinclude trig_reference.xml]
[xinclude temperature_reference.xml]
[xinclude abstract_reference.xml]

[section Base Units by Category]

[xinclude angle_base_units_reference.xml]
[xinclude astronomical_base_units_reference.xml]
[xinclude cgs_base_units_reference.xml]
[xinclude imperial_base_units_reference.xml]
[xinclude metric_base_units_reference.xml]
[xinclude si_base_units_reference.xml]
[xinclude temperature_base_units_reference.xml]
[xinclude us_base_units_reference.xml]

[endsect]

[section Alphabetical Listing of Base Units]
[include base_units.qbk]
[endsect]

[endsect]

[section:Installation Installation]

The core header files are located in `boost/units`. Unit system headers are 
located in `<boost/units/systems>`. There are no source files for the library
itself - the library is header-only. Example programs demonstrating various aspects of the library can be found in 
`boost/libs/units/example`. Programs for unit testing are provided in `boost/libs/units/test`.

[endsect]

[section:FAQ FAQ]

[section:Distinguishing_Quantities_With_Same_Units
How does one distinguish between quantities that are physically different but have the same units (such as 
energy and torque)?]

Because Boost.Units includes plane and solid angle units in the SI system, torque and energy 
are, in fact, distinguishable (see [@http://en.wikipedia.org/wiki/SI_units torque]). 
In addition, energy is a true
[@http://mathworld.wolfram.com/Scalar.html scalar] quantity, while torque, despite
having the same units as energy if plane angle is not included, is in fact a 
[@http://mathworld.wolfram.com/Pseudovector.html pseudovector]. Thus, a value type representing pseudovectors 
and encapsulating their algebra could also be implemented. 

There are,
however, a few SI units that are dimensionally indistinguishable within the SI system. These
include the [@http://en.wikipedia.org/wiki/Becquerel becquerel], which has units identical to
frequency (Hz), and the [@http://en.wikipedia.org/wiki/Sievert sievert], which is degenerate
with the [@http://en.wikipedia.org/wiki/Gray_%28unit%29 gray]. In cases such as this, 
the proper way to treat this difference is to recognize that expanding the set of base dimensions
can provide disambiguation.  For example, adding a base dimension for radioactive decays would 
allow the becquerel to be written as decays/second, differentiating it from the signature of hertz,
which is simply 1/second.

[endsect]

[section:Angle_Are_Units Angles are treated as units]

If you don't like this, you can just ignore the angle units and 
go on your merry way (periodically screwing up when a routine wants degrees and you give it 
radians instead...)

[endsect]

[section:Why_Homogeneous_Systems Why are there homogeneous systems?  Aren't heterogeneous systems sufficient?]

Consider the following code:

    cout << sin(asin(180.0 * degrees));

What should this print?  If only heterogeneous
systems are available it would print 3.14159+ rad
Why?  Well, `asin` would return a `quantity<dimensionless>`
effectively losing the information that degrees
are being used.  In order to propogate this extra information
we need homogeneous systems.

[endsect]

[section:NoConstructorFromValueType Why can't I construct a quantity directly from the value type?]

This only breaks generic code--which ought to break anyway.  The only
literal value that ought to be converted to a quantity by generic code
is zero, which should be handled by the default constructor. In addition,
consider the search and replace problem allowing this poses:

	quantity<si::length>    q(1.0);
	
Here, the intent is clear - we want a length of one in the SI system, which is one meter. However,
imagine some well-intentioned coder attempting to reuse this code, but to have it perform the
calculations in the CGS unit system instead. After searching for `si::` and replacing it with `cgs::` ,
we have:

	quantity<cgs::length>	q(1.0);
	
Unfortunately, the meaning of this statement has suddenly changed from one meter to one centimeter. In
contrast, as implemented, we begin with:

	quantity<si::length>	q(1.0*si::meter);
	
and, after search and replace:

	quantity<cgs::length>	q(1.0*cgs::meter);
	
which gives us an error. Even if the code has a @using namespace boost::units::si; declaration, the latter
is still safe, with:

	using namespace boost::units::si;
	quantity<length>	q(1.0*meter);
	
going to

	using namespace boost::units::cgs;
	quantity<length>	q(1.0*meter);
	
The latter will involve an explicit conversion from meters to centimeters, but the value remains correct.

[endsect]

[section:ExplicitConversions Why are conversions explicit by default?]

Safety and the potential for unintended conversions leading to precision loss and hidden performance costs.
Options are provided for forcing implicit conversions between specific units to be allowed.

[endsect]

[endsect]

[section:Acknowledgements Acknowledgements]

Matthias C. Schabel would like to acknowledge the Department of Defense for its support of this work under 
the Prostate Cancer Research Program New Investigator Award W81XWH-04-1-0042 and the National Institutes of Health for their
support of this work under the NIBIB Mentored Quantitative Research Development Award K25EB005077.

Thanks to David Walthall for his assistance in debugging and testing on a variety of platforms and Torsten Maehne for
his work on interfacing the Boost Units and Boost Lambda libraries.

Thanks to:

* Paul Bristow, 
* Michael Fawcett, 
* Ben FrantzDale, 
* Ron Garcia,
* David Greene,
* Peder Holt,
* Janek Kozicki, 
* Andy Little,
* Kevin Lynch,
* Torsten Maehne
* Noah Roberts,
* Andrey Semashev,
* David Walthall,
* Deane Yang, 

and all the members of the Boost mailing list who provided their input into 
the design and implementation of this library.

[endsect]

[section:HelpWanted Help Wanted]

 Any help in the following areas would be much appreciated:

* testing on other compilers and operating systems
* performance testing on various architectures
* tutorials 

[endsect]

[section:ReleaseNotes Release Notes]

1.0.0 (August 1, 2008) :

* Initial release with Boost 1.36

0.7.1 (March 14, 2007) :

* Boost.Typeof emulation support
* attempting to rebind a heterogeneous_system to a different set of dimensions now fails.
* cmath.hpp now works with como-win32
* minor changes to the tests and examples to make msvc 7.1 happy

0.7.0 (March 13, 2007) :

* heterogeneous and mixed system functionality added
* added fine-grained implicit unit conversion on a per fundamental dimension basis
* added a number of utility metafunction classes and predicates
* [headerref boost/units/operators.hpp] now uses `BOOST_TYPEOF` when possible
* angular units added in [headerref boost/units/systems/trig.hpp] - implicit conversion
    of radians between trigonometric, SI, and CGS systems allowed
* a variety of [___unit] and [___quantity] tests added
* examples now provide self-tests

0.6.2 (February 22, 2007) :

*  changed template order in `unit` so dimension precedes unit system
*  added `homogeneous_system<S>` for unit systems
*  incorporated changes to [headerref boost/units/dimension.hpp] (compile-time sorting by predicate), 
   [headerref boost/units/conversion.hpp] (thread-safe implementation of quantity conversions), 
   and [headerref boost/units/io.hpp] (now works with any `std::basic_ostream`) by SW
* added abstract units in [headerref boost/units/systems/abstract.hpp] to allow abstract dimensional
  analysis
* new example demonstrating implementation of code based on requirements from 
  Michael Fawcett ([@../../libs/units/example/radar_beam_height.cpp radar_beam_height.cpp])

0.6.1 (February 13, 2007) :

* added metafunctions to test if a type is 
    * a valid dimension list (`is_dimension_list<D>`)
    * a unit (`is_unit<T>` and `is_unit_of_system<U,System>`)
    * a quantity (`is_quantity<T>` and `is_quantity_of_system<Q,System>`) 
* quantity conversion factor is now computed at compile time 
* static constants now avoid ODR problems
* unit_example_14.cpp now uses Boost.Timer
* numerous minor fixes suggested by SW

0.6.0 (February 8, 2007) :

* incorporated Steven Watanabe's optimized code for dimension.hpp, leading to *dramatic*
  decreases in compilation time (nearly a factor of 10 for unit_example_4.cpp in my tests).

0.5.8 (February 7, 2007) :

* fixed `#include` in [headerref boost/units/systems/si/base.hpp] (thanks to Michael Fawcett and 
  Steven Watanabe)
* removed references to obsolete `base_type` in [___unit_info] (thanks to Michael Fawcett)
* moved functions in [headerref boost/units/cmath.hpp] into `boost::units` namespace 
  (thanks to Steven Watanabe)
* fixed `#include` guards to be consistently named `BOOST_UNITS_XXX` (thanks to Steven 
  Watanabe)

0.5.7 (February 5, 2007) :

* changed quantity conversion helper to increase flexibility
* minor documentation changes
* submitted for formal review as a Boost library

0.5.6 (January 22, 2007) :

* added IEEE 1541 standard binary prefixes along with SI prefixes to and extended algebra of
  `scale` and `scaled_value` classes (thanks to Kevin Lynch)
* split SI units into separate header files to minimize the "kitchen sink" include problem
  (thanks to Janek Kozicki)
* added convenience classes for declaring fundamental dimensions and composite dimensions 
   with integral powers (`fundamental_dimension` and `composite_dimension` respectively)

0.5.5 (January 18, 2007) :

* template parameter order in `quantity` switched and default `value_type` of `double` added
  (thanks to Andrey Semashev and Paul Bristow)
* added implicit `value_type` conversion where allowed (thanks to Andrey Semashev)
* added `quantity_cast` for three cases (thanks to Andrey Semashev):
    * constructing `quantity` from raw `value_type`
    * casting from one `value_type` to another
    * casting from one `unit` to another (where conversion is allowed) 
* added` metre` and `metres` and related constants to the SI system for the convenience of
  our Commonwealth friends...

0.5.4 (January 12, 2007) :

* completely reimplemented unit conversion to allow for arbitrary unit conversions
  between systems
* strict quantity construction is default; quantities can be constructed from bare values 
  by using static member `from_value`

0.5.3 (December 12, 2006) :

* added Boost.Serialization support to `unit` and `quantity` classes
* added option to enforce strict construction of quantities (only constructible
  by multiplication of scalar by unit or quantity by unit) by preprocessor
  `MCS_STRICT_QUANTITY_CONSTRUCTION` switch

0.5.2 (December 4, 2006) :

* added `<cmath>` wrappers in the `std` namespace for functions that can support quantities 

0.5.1 (November 3, 2006) :

* converted to Boost Software License
* boostified directory structure and file paths

0.5 (November 2, 2006) :

* completely reimplemented SI and CGS unit systems and changed syntax for quantities
* significantly streamlined `pow` and `root` so for most applications it is only
  necessary to define `power_typeof_helper` and `root_typeof_helper` to gain this
  functionality
* added a selection of physical constants from the CODATA tables
* added a skeleton `complex` class that correctly supports both `complex<quantity<Y,Unit> >`
  and `quantity<complex<Y>,Unit>` as an example
* investigate using Boost.Typeof for compilers that do not support `typeof`

0.4 (October 13, 2006) : 

* `pow<R>` and `root<R>` improved for user-defined types
* added unary + and unary - operators
* added new example of interfacing with `boost::math::quaternion`
* added optional preprocessor switch to enable implicit unit conversions
  (`BOOST_UNITS_ENABLE_IMPLICIT_UNIT_CONVERSIONS`) 

0.3 (September 6, 2006) :

* Support for `op(X x,Y y)` for g++ added. This is automatically
  active when compiling with gcc and can be optionally enabled by defining the preprocessor
  constant `BOOST_UNITS_HAS_TYPEOF`

0.2 (September 4, 2006) : Second alpha release based on slightly modified code from 0.1 release

0.1 (December 13, 2003)  : written as a Boost demonstration of MPL-based dimensional analysis
in 2003.

[endsect]

[section:TODO TODO]

* Document concepts
* Implementation of I/O is rudimentary; consider methods of i18n using facets
* Consider runtime variant, perhaps using overload like `quantity<runtime,Y>`

[endsect]