PhysUnits C++11 (compile-time)

A small C++11 header-only library for compile-time dimensional analysis and unit/quantity manipulation and conversion.

This library is based on the quantity compile-time library by Michael S. Kenniston[1] and expanded and adapted for C++11 by Martin Moene.

Contents

• Hello quantity
• Dependencies
• Limitations
• Error handling
• Definition of terms
• Dimensions, units and literals
• Include files
• Configuration
• Types and declarations
• Operations and expressions
• Convenience functions
• Output variations
• Reported to work with
• Performance
• Ideas for improvement
• Mentions of library
• C++ standardization
• Other libraries
• References
• Appendix

Hello quantity

#include "phys/units/quantity.hpp"

using namespace phys::units;
using namespace phys::units::literals;

int main()
{
    quantity<speed_d> speed = 45_km / hour;
}

Dependencies

This library has no dependencies other than the standard C++ library.

Limitations

This library only supports the use of the SI unit system.

This library only supports integral powers of the dimensions.

Error handling

Error handling with respect to mixing incompatible dimensions occurs at compile-time.

Definition of terms

Adapted from Boost.Units:

• Base dimension: A base dimension is loosely defined as a measurable entity of interest; in conventional dimensional analysis, base dimensions include length ([L]), mass ([M]), time ([T]), etc.. Base dimensions are essentially a tag type and provide no dimensional analysis functionality themselves.
• Dimension: A collection of zero or more base dimensions, each potentially raised to a different rational power. For example, length = [L]^1, area = [L]^2, velocity = [L]^1/[T]^1, and energy = [M]^1 [L]^2/[T]^2 are all dimensions.
• Base unit: A base unit represents a specific measure of a dimension. For example, while length is an abstract measure of distance, the meter is a concrete base unit of distance. Conversions are defined using base units. Much like base dimensions, base units are a tag type used solely to define units and do not support dimensional analysis algebra.
• Unit: A set of base units raised to rational exponents, e.g. m^1, kg^1, m^1/s^2.
• System: A unit system is a collection of base units representing all the measurable entities of interest for a specific problem. For example, the SI unit system defines seven base units : length ([L]) in meters, mass ([M]) in kilograms, time ([T]) in seconds, current ([I]) in amperes, temperature ([theta]) in kelvin, amount ([N]) in moles, and luminous intensity ([J]) in candelas. All measurable entities within the SI system can be represented as products of various integer or rational powers of these seven base units.
• Quantity: A quantity represents a concrete amount of a unit. Thus, while the meter is the base unit of length in the SI system, 5.5 meters is a quantity of length in that system.

Dimensions, units and literals

The seven fundamental SI [2] dimensions are length, mass, time interval, electric current, thermodynamic temperature, quantity of substance and luminous intensity. The base units are meter (m), kilogram (kg), second (s), ampere (A), mole (mol) and candela (cd).

The library defines dimensions such as length_d and mass_d and it defines quantities that represent their units as meter and kilogram. The library also defines user-defined literal suffixes with prefixes ranging from yocto (1e-24L) through yotta (1e+24). Thus you can write quantity literals such as 1_ns and 42.195_km.

To use literals of non-base units, include the file io.hpp or io_symbols.hpp, or one or more of the following files named quantity_io_ unit .hpp where unit is becquerel, celsius, coulomb, farad, gray, henry, hertz, joule, lumen, lux, newton, ohm, pascal, radian, siemens, sievert, speed, steradian, tesla, volt, watt, weber.

Include files

• io.hpp - include all io-related include files.
• io_output.hpp - provide basic stream output in base dimensions.
• io_output_eng.hpp - provide stream output in engineering notation, using metric prefixes.
• io_symbols.hpp - include all files quantity_io_ unit .hpp
• other_units.hpp - units that are not approved for use with SI.
• physical_constants.hpp - Planck constant, speed of light etc.
• quantity.hpp - quantity, SI dimensions and units, base unit literals.
• quantity_io_ unit .hpp - name, symbol and literals for unit.

Configuration

-DPHYS_UNITS_REP_TYPE=double
Define this to the representation or value type for the magnitude of quantity. Default is double. You can change the type for all uses within a translation unit by defining PHYS_UNITS_REP_TYPE before inclusion of header quantity.hpp.

-DPHYS_UNITS_COLLAPSE_TO_REP=1
The library can collapse dimensionless results to the representation type or continue with type quantity<dimensionless_d>. Define PHYS_UNITS_COLLAPSE_TO_REP to 0 to allow dimensionless quantities. Default is 1.

Types and declarations

#include "phys/units/quantity.hpp"

using namespace phys::units;

quantity<mass_d> q_rep;           // magnitude has type Rep (PHYS_UNITS_REP_TYPE)
quantity<mass_d, float> q_float;  // magnitude has type float

The default representation or value type Rep for the magnitude of quantity is double. You can change the type for all uses within a translation unit by defining PHYS_UNITS_REP_TYPE before inclusion of header quantity.hpp.

Operations and expressions

• N is an integer constant
• num is an int, long, float, double, etc.
• quantity1 and quantity2 have different dimensions
• quantities with different magnitude types can be mixed

Operation	Operand Type(s)	Result Type
Construction	quantity()	quantity
	quantity( quantity )	quantity
Assignment	quantity = quantity	quantity &
Addition &	quantity += quantity	quantity &
Subtraction	quantity -= quantity	quantity &
	+quantity	quantity
	-quantity	quantity
	quantity + quantity	quantity
	quantity - quantity	quantity
Multiplication	quantity *= num	quantity &
	quantity * num	quantity
	num * quantity	quantity
	quantity1 * quantity1	quantity2
	quantity1 * quantity2	num or quantity3
Division	quantity /= num	quantity &
	quantity / num	quantity
	num / quantity1	quantity2
	quantity / quantity	num
	quantity1 / quantity2	quantity3
Powers	nth_power<N>( quantity1 )	num if N=0, quantity1 if N=1, quantity2 otherwise

Convenience functions

The following convenience functions are provided.

In namespace phys::units:

• DX dimension( quantity<DX, ...> const & q ) - the quantity's dimension.
• X magnitude( quantity<..., X> const & q ) - the quantity's magnitude.
• std::string to_magnitude( quantity<...> const & q ) - the quantity's magnitude represented as string.
• std::string to_unit_name( quantity<...> const & q ) - the quantity's unit name, e.g. 'hertz'.
• std::string to_unit_symbol( quantity<...> const & q ) - the quantity's unit symbol, e.g. 'Hz'.
• std::string to_string( long double const value ) - the value of a long double represented as string.

In namespace phys::units::io:

• std::string to_string( quantity<...> const & q ) - the quantity represented as string in scientific notation.
• std::ostream & operator<<( std::ostream & os, quantity<...> const & q ) - output the quantity to a stream in scientific notation.

In namespace phys::units::io::eng:

• std::string to_string( quantity<...> const & q ) - the quantity represented as string in engineering notation.
• std::ostream & operator<<( std::ostream & os, quantity<...> const & q ) - output the quantity to a stream in engineering notation.

Output variations

The following example shows the quantity type in the computation of work from force and distance and the printing of the result on standard output.

#include <iostream>

#include "phys/units/io.hpp"
#include "phys/units/quantity.hpp"

using namespace phys::units;
using namespace phys::units::io;
using namespace phys::units::literals;

quantity<energy_d>
work( const quantity<force_d> & F, const quantity<length_d> & dx )
{
    return F * dx; // Defines the relation: work = force * distance.
}

int main()
{
    // Test calculation of work.
    quantity<force_d>       F { 2_N           };  // Define a quantity of force.
    quantity<length_d>      dx{ 2_m           };  // and a distance,
    quantity<energy_d>      E { work( F, dx ) };  // and calculate the work done.

    std::cout << "F  = " << F  << std::endl
              << "dx = " << dx << std::endl
              << "E  = " << E  << std::endl;
}

The output produced is:

F  = 2 N
dx = 2 m
E  = 4 J

The following example demonstrates printing in default floating point notation and in engineering notation, using metric prefixes.

#include <iostream>

#include "phys/units/io.hpp"
#include "phys/units/quantity.hpp"

using namespace phys::units;
using namespace phys::units::literals;

int main()
{
    quantity<electric_resistance_d> R{ 4.7_kV / ampere };

    {
        using namespace phys::units::io;
        std::cout << "R = " << R << std::endl;
    }
    {
        using namespace p