Class convert_units (o2scl)

O2scl : Class List

template<class fp_t = double>
class o2scl::convert_units

Convert units.

Allow the user to convert between two different units after specifying a conversion factor. This class will also automatically combine two conversion factors to create a new unit conversion (but it cannot combine more than two).

Conversions are performed by the convert() function. The run-time unit cache is initially filled with hard-coded conversions, and convert() searches this cache is searched for the requested conversion first. If the conversion is not found and if use_gnu_units is true, then convert() tries to open a pipe to open a shell to get the conversion factor from 'units'. If this is successful, then the conversion factor is returned and the conversion is added to the cache.

If the GNU units command is not in the local path, the user may modify units_cmd_string to specify the full pathname. One can also modify units_cmd_string to specify a different units.dat file.

Example:

convert_units cu;
cout << "A solar mass is " << cu.convert("Msun","g",1.0) 
<< " g. " << endl;

An object of this type is created by o2scl_settings (of type lib_settings_class) for several unit conversions used internally in .

Idea for Future:

Add G=1.

Note

Combining two conversions allows for some surprising apparent contradictions from numerical precision errors. If there are two matching unit conversion pairs which give the same requested conversion factor, then one can arrange a situation where the same conversion factor is reported with slightly different values after adding a related conversion to the table. One way to fix this is to force the class not to combine two conversions by setting combine_two_conv to false. Alternatively, one can ensure that no combination is necessary by manually adding the desired combination conversion to the cache after it is first computed.

Note

uses some unit aliases which are not used the the GNU or OSX units commands, like “Msun” for the solar mass and adds some units not present like “Rschwarz” for the Schwarzchild radius of a 1 solar mass black hole.

Note

Only the const versions, convert_const and convert_ret_const are guaranteed to be thread-safe, since they are not allowed to update the unit cache.

Idea for Future:

An in_cache() function to test to see if a conversion is currently in the cache.

Flags for natural units

bool c_is_1
bool hbar_is_1
bool kb_is_1
bool G_is_1
void set_vars(fp_t m, fp_t k, fp_t s, fp_t K, fp_t A, fp_t mol, fp_t cd, std::map<std::string, fp_t> &vars, bool test_vars = false) const

Set variables for the calculator object for convert_calc()

int convert_internal(std::string from, std::string to, fp_t val, fp_t &converted, fp_t &factor, bool &new_conv) const

The internal conversion function which tries the cache first and, if that failed, tries GNU units.

This function returns 0 if the conversion was successful. If the conversion fails and err_on_fail is true, then the error handler is called. If the conversion fails and err_on_fail is false, then the value o2scl::exc_enotfound is returned.

The public conversion functions in this class are basically just wrappers around this internal function.

int convert_gnu_units(std::string from, std::string to, fp_t val, fp_t &converted, fp_t &factor) const

Attempt to use GNU units to perform a conversion.

This function attempts to open a pipe to GNU units independent of the value of use_gnu_units. However, it will always return a non-zero value if HAVE_POPEN is not defined signaling that the popen() function is not available (but does not call the error handler in this case). The function returns 0 if the conversion was successful. If HAVE_POPEN is defined but the call to GNU units fails for some reason, then the error handler is called if err_on_fail is true.

Idea for Future:

Finer control on verbose=1 vs. verbose=2

int convert_cache(std::string from, std::string to, fp_t val, fp_t &converted, fp_t &factor) const

Attempt to construct a conversion from the internal unit cache.

This function returns 0 if the conversion was successful and o2scl::exc_efailed otherwise. This function does not call the error handler.

convert_units()

Create a unit-conversion object.

~convert_units()
void set_natural_units(bool c_is_one = true, bool hbar_is_one = true, bool kb_is_one = true)

Set natural units.

void test_unique()

Test to make sure all units are unique.

void print_units(std::ostream &out)

Print the units in the data base.

int convert_calc(std::string from, std::string to, fp_t val, fp_t &converted, fp_t &factor) const

Automatic unit conversion between SI-based units with a o2scl::calculator object.

Basic usage

fp_t convert(std::string from, std::string to, fp_t val)

Return the value val after converting using units from and to.

fp_t convert_const(std::string from, std::string to, fp_t val) const

Return the value val after converting using units from and to (const version)

User settings

int verbose

Verbosity (default 0)

bool use_gnu_units

If true, use a system call to units to derive new conversions (default true)

This also requires popen().

bool err_on_fail

If true, throw an exception when a conversion fails (default true)

bool combine_two_conv

If true, allow combinations of two conversions (default true)

std::string units_cmd_string

Command string to call units (default “units”)

Conversions which don’t throw exceptions

int convert_ret(std::string from, std::string to, fp_t val, fp_t &converted)

Return the value val after converting using units from and to, returning a non-zero value on failure.

int convert_ret_const(std::string from, std::string to, fp_t val, fp_t &converted) const

Return the value val after converting using units from and to, returning a non-zero value on failure (const version)

Manipulate cache and create units.dat files

void insert_cache(std::string from, std::string to, fp_t conv)

Manually insert a unit conversion into the cache.

void print_cache() const

Print the present unit cache to std::cout.

void test_cache_calc() const

Desc.

void remove_cache(std::string from, std::string to)

Manually remove a unit conversion into the cache.

void default_conversions()

Add default conversions.

Where possible, this uses templates from constants.h to define the conversions exactly in the user-specified floating-point type.

void make_units_dat(std::string fname, bool c_1 = false, bool hbar_1 = false, bool K_1 = false) const

Make a GNU units.dat file from the GSL constants.

If c_1 is true, then the second is defined in terms of meters so that the speed of light is unitless. If hbar_1 is true, then the kilogram is defined in terms of s/m^2 so that \( \hbar \) is unitless.

Note

While convert() generally works with the OSX version of ‘units’, the OSX version can’t read units.dat files created by this function.

Note

Not all of the GSL constants or the canonical GNU units conversions are given here.

int test_cache()

Exhaustive test the cache against GNU units.

Protected Types

typedef std::map<std::string, unit_t, std::greater<std::string>>::iterator miter

The iterator type.

typedef std::map<std::string, unit_t, std::greater<std::string>>::const_iterator mciter

The const iterator type.

typedef struct o2scl::convert_units::der_unit_s der_unit

Type of a derived unit.

Protected Attributes

std::map<std::string, unit_t, std::greater<std::string>> mcache

The cache where unit conversions are stored.

std::vector<std::string> prefixes

SI prefix labels.

std::vector<fp_t> prefix_facts

SI prefix factors.

std::vector<der_unit> SI

SI-like units which allow prefixes.

Set in constructor.

std::vector<der_unit> other

Other units which do not allow prefixing.

Set in constructor.

Protected Static Attributes

const size_t n_prefixes = 24

Number of SI prefixes.

struct der_unit_s

Type of a derived unit.

Public Members

std::string label

Unit label.

int m

Power of length.

int k

Power of mass.

int s

Power of time.

int K

Power of temperature.

int A

Power of current.

int mol

Power of moles.

int cd

Power of luminous intensity.

fp_t val

Value.

struct unit_t

The type for caching unit conversions.

Public Members

std::string f

The input unit.

std::string t

The output unit.

fp_t c

The conversion factor.