TBTK::UnitHandler Class Reference

Handles conversion between different units. More...

#include <UnitHandler.h>

Static Public Member Functions
static double	getConstantInBaseUnits (const std::string &name)
static double	getConstantInNaturalUnits (const std::string &name)
static void	setScales (const std::vector< std::string > &scales)
template<typename Quantity >
static double	convertNaturalToBase (double value)
template<typename Quantity >
static double	convertBaseToNatural (double value)
static std::string	getUnitString (const std::string &constantName)
Convert arbitrary to base
Convert from arbitrary units to base units.
template<typename Quantity >
static std::enable_if< Quantity::IsBaseQuantity::value, double >::type	convertArbitraryToBase (double value, typename Quantity::Unit unit)
template<typename Quantity >
static std::enable_if< !Quantity::IsBaseQuantity::value, double >::type	convertArbitraryToBase (double value, typename Quantity::Unit unit)
Convert base to arbitrary
Convert from base units to arbitrary units.
template<typename Quantity >
static std::enable_if< Quantity::IsBaseQuantity::value, double >::type	convertBaseToArbitrary (double value, typename Quantity::Unit unit)
template<typename Quantity >
static std::enable_if< !Quantity::IsBaseQuantity::value, double >::type	convertBaseToArbitrary (double value, typename Quantity::Unit unit)
Convert arbitrary to natural
Convert from arbitrary units to natural units.
template<typename Quantity >
static std::enable_if< Quantity::IsBaseQuantity::value, double >::type	convertArbitraryToNatural (double value, typename Quantity::Unit unit)
template<typename Quantity >
static std::enable_if< !Quantity::IsBaseQuantity::value, double >::type	convertArbitraryToNatural (double value, typename Quantity::Unit unit)
Convert natural to arbitrary
Convert from natural units to arbitrary units.
template<typename Quantity >
static std::enable_if< Quantity::IsBaseQuantity::value, double >::type	convertNaturalToArbitrary (double value, typename Quantity::Unit unit)
template<typename Quantity >
static std::enable_if< !Quantity::IsBaseQuantity::value, double >::type	convertNaturalToArbitrary (double value, typename Quantity::Unit unit)
Get unit string for quantity
Get the unit string for the given Quantity in the currently set base units. Returns string representation of the currently set unit for the given Quantity.
template<typename Quantity >
static std::enable_if< Quantity::IsBaseQuantity::value, std::string >::type	getUnitString ()
template<typename Quantity >
static std::enable_if< !Quantity::IsBaseQuantity::value, std::string >::type	getUnitString ()

Friends
void	Initialize ()

Detailed Description

Handles conversion between different units.

Base units and natural units

TBTK does not enforce the use of a specific set of units. Instead it defines the seven base quantities angle, charge, count, energy, length, temperature, and time. The UnitHandler allows for seven corresponding base and natural units to be set for these quantities.

For example, in the following example the base units are set to radians (rad), Colomb (C), pieces (pcs), milli electron Volt (meV), meter (m), Kelvin (K), and femtosecond (fs).

UnitHandler::setScales(
  {"1 rad", "1.5 C", "5 pcs", "1 meV", "0.3048 m", "1 K", "15 fs"}
);

The natural units are similar to the base units, but also take into account the scale factor in front of the unit symbols. This means that 3 Colomb corresponds to three base units, but only two natural units.

In TBTK, all numbers are interpreted in terms of natural units. This means that TBTK assumes that any number passed to one of its functions is given in natural units. The default natural units are 1 rad, 1 C, 1 pcs, 1 eV, 1 m, 1 K, and 1 s. If another set of natural units is preferred, the call to UnitHandler::setScales() should occur at the start of the program, just after TBTK has been initialized.

Base units

TBTK defines a number of base units for the six Base Qauntities. Each can be refered to using its string representation as above, or using an enum class variable. The later is used in functions that are potentially performance critical. For exampel, it is possible to use either Joule (J) or (eV) as base unit for the Base Quantity Energy. The string representations for these are "J" and "eV", while the corresponding enum class representations are Quantity::Energy::Unit::J and Quantity::Energy::Unit::eV. For a complete list of base units, see the documentation for Quantity::Base.

Derived units

In addition to the base units, TBTK also defines derived units for Derived Quantities such as mass and voltage. The units are called derived since they can be defined in terms of base units. For example, kg ~ eV m^-2 s^2 and V = eV/e. Some derived units also have string and enum class representations, such as Quantity::Mass::Unit::kg and "kg" for mass or Quantity::Voltage::Unit::V and "V" for voltage. A full list of derived quantities and their corresponding units, see the documentation for Quantity::Derived.

Requesting constants

It is possible to request the value of constants in the currently set base and natural units using

double boltzmannConstantInBaseUnits
  = UnitHandler::getConstantInBaseUnits("k_B");
double boltzmannConstantInNaturalUnits
  = UnitHandler::getConstantInNaturalUnits("k_B");

The value in base and natural units will differ by a product of scale factors that accounts for the difference between the two types of units. The currently available constants are

Constant	Symbol	Source*
Unit charge (positive)	"e"	1
Speed of light	"c"	1
Avogadros number	"N_A"	1
Bohr radius	"a_0"	1
Planck constant	"h"	1
Boltzmann constant	"k_B"	1
Electron mass	"m_e"	2
Proton mass	"m_p"	2
Vacuum permeability	"mu_0"	2
Vacuum permittivity	"epsilon_0"	2
Reduced Planck constant	"hbar"	3
Bohr magneton	"mu_B"	3
Nuclear magneton	"mu_N"	3

*The sources for the constants are:

1. The International System of Units (SI) 9th Edition. Bureau International des Poids et Mesures. 2019.
2. The NIST reference on Constants, Units, and Uncertainty. https://physics.nist.gov/cuu/Constants/index.html.
3. Calculated from the other constants.

Converting between base and natural units.

Assume that the scales have been set such that the base unit is 1 m and the natural unit is 1 foot (0.3048 m). It is then possible to convert between the two units as follows.

double tenMetersInFeet
  = UnitHandler::convertBaseToNatural<Quantity::Length>(10);
double tenFeetInMeters
  = UnitHandler::convertNaturalToBase<Quantity::Length>(10);

Similar calls can be used to convert between other quantities between base and natural units by replacing Quantity::Length with the corresponding Quantity.

Conversion between arbitrary units and base and natural units

It is also posible to convert between an arbitrary (not currently set) unit and the (currently set) base and natural units. For example, from "nm" to "ft", or "V" to C^-1 meV. The functions for this are

double oneVoltInBaseUnits
  = UnitHandler::convertArbitraryToBase<Quantity::Voltage>(
    1,
    Quantity::Voltage::Unit::V
  );
double oneVoltInNaturalUnits
  = UnitHandler::convertArbitraryToNatural<Quantity::Voltage>(
    1,
    Quantity::Voltage::Unit::V
  );
double oneBaseUnitOfVoltageInVolt
  = UnitHandler::convertBaseToVoltage<Quantity::Voltage>(
    1,
    Quantity::Voltage::Unit::V
  );
double oneNaturalVoltageUnitInVolt
  = UnitHandler::convertNaturalToArbitrary<Quantity::Voltage>(
    1,
    Quantity::Voltage::Unit::V
  );

Unit strings

The UnitHandler also allows for a string representation of the base unit for constants and Quantities to be extracted. Since natural units can come with an arbitrary numerical factor, unit strings can not be obtained for natural units. This is on of the reasons why conversion to and from base units is of interest. All calculations are done in natural units, but automatic generation of unit strings can only be done for base units. Note, however, that as long as no scale factor is used, the base and natural units are the same.

For example, the unit string for Boltzmann constant can be obtained using

std::string unitString = UnitHandler::getUnitString("k_B");

The unit string for voltage can be obtained using

std::string unitString = UnitHandler::getUnitString<Quantity::Voltage>();

Example

#include "TBTK/UnitHandler.h"
#include "TBTK/Streams.h"
#include "TBTK/TBTK.h"
 
using namespace TBTK;
 
int main(){
    Initialize();
 
    //Initialize the scales. The base units are set to rad, C, pcs, eV, m,
    //K, and s. The natural length scale is set to 1 feet.
    UnitHandler::setScales(
        {"1 rad", "1 C", "1 pcs", "1 eV", "0.3048 m", "1 K", "1 s"}
    );
 
    //Print the speed of light in the base units (m/s).
    Streams::out << "The speed of light is "
        << UnitHandler::getConstantInBaseUnits("c") << " "
        << UnitHandler::getUnitString("c") << ".\n";
 
    //Print the speed of light in the natural units (ft/s).
    Streams::out << "The speed of light is "
        << UnitHandler::getConstantInNaturalUnits("c")
        << " ft s^-1.\n";
 
    //Convert from natural to base units.
    Streams::out << "10 m is equal to "
        << UnitHandler::convertBaseToNatural<Quantity::Length>(10)
        << " ft.\n";
 
    //Convert from base to natural units.
    Streams::out << "10 ft is equal to "
        << UnitHandler::convertNaturalToBase<Quantity::Length>(10)
        << UnitHandler::getUnitString<Quantity::Length>() << ".\n";
 
    //Print the reduced Planck constant in base units.
    Streams::out << "The reduced Planck constant is "
        << UnitHandler::getConstantInBaseUnits("hbar") << " "
        << UnitHandler::getUnitString("hbar") << "\n";
 
    //Convert 1 V to base units.
    Streams::out << "1 V is equal to "
        << UnitHandler::convertArbitraryToBase<Quantity::Voltage>(
            1,
            Quantity::Voltage::Unit::V
        ) << " " << UnitHandler::getUnitString<Quantity::Voltage>()
        << ".\n";
 
    //Convert one natural unit of voltage to V.
    Streams::out << "1 natural unit of voltage is equal to "
        << UnitHandler::convertNaturalToArbitrary<Quantity::Voltage>(
            1,
            Quantity::Voltage::Unit::V
        ) << " V\n.";
}

Output

The speed of light is 2.99792e+08 m s^-1.
The speed of light is 9.83571e+08 ft s^-1.
10 m is equal to 32.8084 ft.
10 ft is equal to 3.048m.
The reduced Planck constant is 6.58212e-16 eV s
1 V is equal to 6.24151e+18 C^-1 eV.
1 natural unit of voltage is equal to 1.60218e-19 V

Member Function Documentation

convertBaseToNatural()

template<typename Quantity >

double TBTK::UnitHandler::convertBaseToNatural ( double  value )

static

Convert from base units to natural units.

convertNaturalToBase()

template<typename Quantity >

double TBTK::UnitHandler::convertNaturalToBase ( double  value )

static

Convert from natural units to base units.

getConstantInBaseUnits()

static double TBTK::UnitHandler::getConstantInBaseUnits ( const std::string &  name )

static

Get physical constant in base units.

getConstantInNaturalUnits()

static double TBTK::UnitHandler::getConstantInNaturalUnits ( const std::string &  name )

static

Get physical constant in natural units.

getUnitString()

static std::string TBTK::UnitHandler::getUnitString ( const std::string &  constantName )

static

Get the unit string for the given constant.

Parameters

constantName

The name of the constant.

Returns

The unit string in the current base units.

setScales()

void TBTK::UnitHandler::setScales ( const std::vector< std::string > &  scales )

inlinestatic

Set scales.

Friends And Related Function Documentation

Initialize

void Initialize ( )

friend

The Context is a friend of the UnitHandler to allow it to initialize the UnitHandler.

---

The documentation for this class was generated from the following file:

• /TBTK/Lib/include/Utilities/TBTK/UnitHandler.h