See more details about the UnitHandler in the API

Units and constants

Most physical quantities have units, but computers work with unitless numbers. The units can be made implicit by specifying a software wide convention, but no single set of units are the most natural across all of quantum mechanics. Therefore, TBTK provides a UnitHandler that makes it possible to specify the units that are most natural for the given application. All numbers that are passed to TBTK functions are assumed to be given in these units. The UnitHandler also allows for physical constants to be requested in these natural units.

Base units

The UnitHandler borrows its terminology from the SI standard. Not by forcing the user to work in SI units, but through a clear division of units into base units and derived units. To understand what this means, consider distance and time. These are independent quantities that can be measured in meters (m) and seconds (s). In comparison, velocity is a derived quantity that is defined as distance per time and have the derived unit m/s.

In principle, nothing prevents us from instead considering time to be a quantity that is derived from distance and velocity. However, the fact remains that only two of these three quantities can be defined independently of each other. It turns out that in nature, only seven quantities can be defined independently of each other. If we, therefore, fix seven such quantities and assigning them base units, all other quantities acquire derived units.

The UnitHandler defines the base quantities to be angle, charge, count (amount), energy. length, temperature, and time. This is different from the SI system, which defines base units for luminocity, current, and mass instead of angle, charge, and energy. The choice to deviate from the SI system by making angle, charge, and energy base quantities is made since these are perceived to be of greater relevance in quantum mechanical calculations.

The UnitHandler also deviates from the SI system by only fixing the base quantities and not the base units. While the SI unit for length is meter (m), the UnitHandler allows the base unit for length to be set to, among other things, meter (m), millimeter (mm), nanometer (nm), and Ångström (Å). Similarly, Joule (J) and electronvolt (eV) are possible base units for energy, while Coulomb (C) and elementary charge (e) are examples of base units for charge.

Default base units

Quantity	Default base unit	UnitHandler symbol
Angle	rad (radians)	Angle
Charge	C (Coulomb)	Charge
Count	pcs (pieces)	Count
Energy	eV (electron Volt)	Energy
Length	m (meter)	Length
Temperature	K (Kelvin)	Temperature
Time	s (seconds)	Time

Available base units

Quantity	Available base units
Angle	rad, degree
Charge	kC, C, mC, uC, nC, pC, fC, aC, Te, Ge, Me, ke, e
Count	pcs, mol
Energy	GeV, MeV, keV, eV, meV, ueV, J
Length	m, mm, um, nm, pm, fm, am, Ao
Temperature	kK, K, mK, uK, nK
Time	s, ms, us, ns, ps, fs, as

Here Gx, Mx, kx, mx, etc. corresponds to giga, mega, kilo, milli, etc, while Ao means Ångström (Å), and pcs means pieces. Additional units can be added on request.

If base units other than the default ones are wanted, this should be specified at start of the application, just after TBTK has been initialized. This avoids ambiguities that otherwise can result from changing base units in the middle of the execution. To set the base units to rad, C, mol, meV, Å, mK, and ps, type

UnitHandler::setScales(
    {"1 rad", "1 C", "1 mol", "1 meV", "1 Ao", "1 mK", "1 ps"}
);

Note that the units in the brackets have to come in the order angle, charge, count, energy, length, temperature, and time.

Natural units

The UnitHandler extends the base unit concept to natural units by allowing for a numerical prefactor. For example, consider the following specification.

UnitHandler::setScales(
    {"1 rad ", "1 C", "1 pcs", "13.606 eV", "1 m", "1 K", "1 s"}
);

Here the natural energy unit is set to 13.606 eV. This means that any energy value that is passed to a TBTK function is interpreted to be given in terms of 13.606 eV. For example, the numeric value 1.5 is interpreted to mean 1.5*13.606 eV = 20.409 eV. Note the important distinction between base units and natural units: in base units the value is 20.409 eV, but in natural units it is 1.5.

Converting between base and natural units

To convert a length between base and natural units, the following functions can be used.

double lengthInBaseUnits
    = UnitHandler::convertNaturalToBase<Quantity::Length>(
        quantityInNaturalUnits
    );
double lengthInNaturalUnits
    = UnitHandler::convertBaseToNatural<Quantity::Length>(
        quantityInBaseUnits
    );

To convert other Quantities, replace Quantity::Length by the relevant Quantity.

It is also possible to convert between an arbitrary (not currently set) unit and the natural and base units. For example, we can convert energy between meV and the currently set base units as follows.

double energyInBaseUnits
    = UnitHandler::convertArbitraryToBase<Quantity::Energy>(
        energyInMilliElectronVolt,
        Quantity::Energy::Unit::meV
    );
double energyIntMilliElectronVolt
    = UnitHandler::convertBaseToArbitrary<Quantity::Energy>(
        energyInBaseUnits,
        Quantity::Energy::Unit::meV
    );

Similarly, it is possible to convert between arbitrary and natural units.

double energyInNaturalUnits
    = UnitHandler::convertArbitraryToNatural<Quantity::Energy>(
        energyInDerivedUnits,
        Quantity::Energy::Unit::meV
    );
double energyInMilliElectronVolt
    = UnitHandler::convertNaturalToArbitrary<Quantity::Energy>(
        energyInNaturalUnits,
        Quantity::Energy::Unit::meV
    );

Derived units

To aid conversion between different units, TBTK also defines units for several derived quantities. Please, do not hesitate to request additional derived units or quantities if needed.

Quantity	Available derived units	UnitHandler symbol
Mass	kg, g, mg, ug, ng, pg, fg, ag, u	Mass
Magnetic field strength	MT, kT, T, mT, uT, nT, GG, MG, kG, G, mG, uG	MagneticField
Voltage	GV, MV, kV, V, mV, uV, nV	Voltage

These quantities and units can be used together with the conversion functions explained above. For example, to convert mass in the derived units \(kg\) to and from base units, the follwoing functions can be called.

double massInBaseUnits = UnitHandler::convertArbitraryToBase<Quantity::Mass>(
    massInDerivedUnits,
    Quantity::Mass::Unit::kg
);
double massInDerivedUnits = UnitHandler::convertBaseToArbitrary(
    massInBaseUnits,
    Quantity::Mass::Unit::kg
);

Similarly, it is possible to convert between derived units and natural units.

double massInNaturalUnits
    = UnitHandler::convertArbitraryToNatural<Quantity::Mass>(
        massInKiloGram,
        Quantity::Mass::Unit::kg
    );
double massInKiloGram
    = UnitHandler::convertNaturalToArbitrary<Quantity::Mass>(
        massInNaturalUnits,
        Quantity::Mass::Unit::kg
    );

Constants

The following constants can be requested from the UnitHandler.

Name	Symbol	UnitHandler symbol
Planck constant	\(h\)	h
Reduced Planck constant	\(\hbar\)	Hbar
Boltzmann constant	\(k_B\)	k_B
Elementary charge	\(e\)	E
Speed of light	\(c\)	C
Avogadros number	\(N_A\)	N_A
Electron mass	\(m_e\)	M_e
Proton mass	\(m_p\)	M_p
Bohr magneton	\(\mu_B\)	Mu_B
Nuclear magneton	\(\mu_N\)	Mu_N
Vacuum permeability	\(\mu_0\)	Mu_0
Vacuum permittivity	\(\epsilon_0\)	Epsilon_0

We can, for example, get the Boltzmann constant in base and natural units as follows.

double constantValueInBaseUnits
    = UnitHandler::getConstantInBaseUnits("k_B");
double constantValueInNaturalUnits
    = UnitHandler::getConstantInNaturalUnits("k_B");

Please do not hesitate to request the addition of further constants.

Unit strings

To aid with printing values to the output, the UnitHandler provides methods for requesting the string representation of the base unit for a given quantity or constant. The unit string for a quantity can be obtained as follows.

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

The unit string for a constant can be obtained as follows.

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

Note: The unit string corresponds to the base units, so any output from TBTK should first be converted from natural units to base units before being printed together with the unit string.

Next: Indices