Unit conversion utility. More...

#include <Units.h>

Detailed Description

Unit conversion utility.

Provides functions for converting dimensional values from a given unit system. The main use is for converting values specified in input files to Cantera's native unit system, which is SI units except for the use of kmol as the base unit of quantity, that is, kilogram, meter, second, kelvin, ampere, and kmol.

String representations of units can be written using multiplication, division, and exponentiation. Spaces are ignored. Positive, negative, and decimal exponents are permitted. Examples:

kg*m/s^2
J/kmol
m*s^-2
J/kg/K

Metric prefixes are recognized for all units, such as nm, hPa, mg, EJ, mL, kcal.

Special functions for converting activation energies allow these values to be expressed as either energy per quantity, energy (for example, eV), or temperature by applying a factor of the Avogadro number or the gas constant where needed.

Definition at line 168 of file Units.h.

Public Member Functions
	UnitSystem (std::initializer_list< string > units)
	Create a unit system with the specified default units. More...

	UnitSystem ()
	Default constructor for unit system (needed as VS2019 does not recognize an optional argument with a default value) More...

map< string, string >	defaults () const
	Return default units used by the unit system. More...

void	setDefaults (std::initializer_list< string > units)
	Set the default units to convert from when explicit units are not provided. More...

void	setDefaults (const map< string, string > &units)
	Set the default units using a map of dimension to unit pairs. More...

void	setDefaultActivationEnergy (const string &e_units)
	Set the default units to convert from when using the `convertActivationEnergy` function. More...

double	convert (double value, const string &src, const string &dest) const
	Convert `value` from the units of `src` to the units of `dest`. More...

double	convert (double value, const Units &src, const Units &dest) const

double	convertTo (double value, const string &dest) const
	Convert `value` to the specified `dest` units from the appropriate units for this unit system (defined by `setDefaults`) More...

double	convertTo (double value, const Units &dest) const

double	convertFrom (double value, const string &src) const
	Convert `value` from the specified `src` units to units appropriate for this unit system (defined by `setDefaults`) More...

double	convertFrom (double value, const Units &src) const

double	convert (const AnyValue &val, const string &dest) const
	Convert a generic AnyValue node to the units specified in `dest`. More...

double	convert (const AnyValue &val, const Units &dest) const

double	convertRateCoeff (const AnyValue &val, const Units &dest) const
	Convert a generic AnyValue node representing a reaction rate coefficient to the units specified in `dest`. More...

vector< double >	convert (const vector< AnyValue > &vals, const string &dest) const
	Convert an array of AnyValue nodes to the units specified in `dest`. More...

vector< double >	convert (const vector< AnyValue > &vals, const Units &dest) const

double	convertActivationEnergy (double value, const string &src, const string &dest) const
	Convert `value` from the units of `src` to the units of `dest`, allowing for the different dimensions that can be used for activation energies. More...

double	convertActivationEnergyTo (double value, const string &dest) const
	Convert `value` to the units specified by `dest` from the default activation energy units. More...

double	convertActivationEnergyTo (double value, const Units &dest) const

double	convertActivationEnergyFrom (double value, const string &src) const
	Convert `value` from the units specified by `src` to the default activation energy units. More...

double	convertActivationEnergy (const AnyValue &val, const string &dest) const
	Convert a generic AnyValue node to the units specified in `dest`. More...

AnyMap	getDelta (const UnitSystem &other) const
	Get the changes to the defaults from `other` to this UnitSystem. More...

Private Attributes
double	m_mass_factor = 1.0
	Factor to convert mass from this unit system to kg. More...

double	m_length_factor = 1.0
	Factor to convert length from this unit system to meters. More...

double	m_time_factor = 1.0
	Factor to convert time from this unit system to seconds. More...

double	m_pressure_factor = 1.0
	Factor to convert pressure from this unit system to Pa. More...

double	m_energy_factor = 1.0
	Factor to convert energy from this unit system to J. More...

double	m_activation_energy_factor = 1.0
	Factor to convert activation energy from this unit system to J/kmol. More...

double	m_quantity_factor = 1.0
	Factor to convert quantity from this unit system to kmol. More...

bool	m_explicit_activation_energy = false
	True if activation energy units are set explicitly, rather than as a combination of energy and quantity units. More...

map< string, string >	m_defaults
	Map of dimensions (mass, length, etc.) to names of specified default units. More...

Constructor & Destructor Documentation

◆ UnitSystem() [1/2]

UnitSystem ( std::initializer_list< string > units )

Create a unit system with the specified default units.

Definition at line 393 of file Units.cpp.

◆ UnitSystem() [2/2]

UnitSystem ( )

inline

Default constructor for unit system (needed as VS2019 does not recognize an optional argument with a default value)

Definition at line 176 of file Units.h.

Member Function Documentation

◆ defaults()

map< string, string > defaults ( ) const

Return default units used by the unit system.

Definition at line 398 of file Units.cpp.

◆ setDefaults() [1/2]

void setDefaults ( std::initializer_list< string > units )

Set the default units to convert from when explicit units are not provided.

Defaults can be set for mass, length, time, quantity, energy, and pressure. Conversion using the pressure or energy units is done only when the target units explicitly contain pressure or energy units.

To use SI+kmol: setDefaults({"kg", "m", "s", "Pa", "J", "kmol"});
To use CGS+mol: setDefaults({"cm", "g", "dyn/cm^2", "erg", "mol"});

Definition at line 428 of file Units.cpp.

◆ setDefaults() [2/2]

void setDefaults ( const map< string, string > & units )

Set the default units using a map of dimension to unit pairs.

Defaults for dimensions not specified will be left unchanged. To use Cantera's default units:

UnitSystem system;
map<string, string> defaults{
    {"length", "m"}, {"mass", "kg"}, {"time", "s"},
    {"quantity", "kmol"}, {"pressure", "Pa"}, {"energy", "J"},
    {"activation-energy", "J/kmol"}
};
setDefaults(defaults);

Definition at line 472 of file Units.cpp.

◆ setDefaultActivationEnergy()

void setDefaultActivationEnergy ( const string & e_units )

Set the default units to convert from when using the convertActivationEnergy function.

Definition at line 521 of file Units.cpp.

◆ convert() [1/3]

double convert	(	double	value,
		const string &	src,
		const string &	dest
	)		const

Convert value from the units of src to the units of dest.

Definition at line 538 of file Units.cpp.

◆ convertTo()

double convertTo	(	double	value,
		const string &	dest
	)		const

Convert value to the specified dest units from the appropriate units for this unit system (defined by setDefaults)

Definition at line 554 of file Units.cpp.

◆ convertFrom()

double convertFrom	(	double	value,
		const string &	src
	)		const

Convert value from the specified src units to units appropriate for this unit system (defined by setDefaults)

Definition at line 570 of file Units.cpp.

◆ convert() [2/3]

double convert	(	const AnyValue &	val,
		const string &	dest
	)		const

Convert a generic AnyValue node to the units specified in dest.

If the input is a double, convert it using the default units. If the input is a string, treat this as a dimensioned value, such as '988 kg/m^3' and convert from the specified units.

Definition at line 604 of file Units.cpp.

◆ convertRateCoeff()

double convertRateCoeff	(	const AnyValue &	val,
		const Units &	dest
	)		const

Convert a generic AnyValue node representing a reaction rate coefficient to the units specified in dest.

Works like convert(AnyValue&, Units&) but with special handling for the case where the destination units are undefined.

Since: New in Cantera 3.0

Definition at line 631 of file Units.cpp.

◆ convert() [3/3]

vector< double > convert	(	const vector< AnyValue > &	vals,
		const string &	dest
	)		const

Convert an array of AnyValue nodes to the units specified in dest.

For each node, if the value is a double, convert it using the default units, and if it is a string, treat it as a value with the given dimensions.

Definition at line 657 of file Units.cpp.

◆ convertActivationEnergy() [1/2]

double convertActivationEnergy	(	double	value,
		const string &	src,
		const string &	dest
	)		const

Convert value from the units of src to the units of dest, allowing for the different dimensions that can be used for activation energies.

Definition at line 673 of file Units.cpp.

◆ convertActivationEnergyTo()

double convertActivationEnergyTo	(	double	value,
		const string &	dest
	)		const

Convert value to the units specified by dest from the default activation energy units.

Definition at line 705 of file Units.cpp.

◆ convertActivationEnergyFrom()

double convertActivationEnergyFrom	(	double	value,
		const string &	src
	)		const

Convert value from the units specified by src to the default activation energy units.

Definition at line 725 of file Units.cpp.

◆ convertActivationEnergy() [2/2]

double convertActivationEnergy	(	const AnyValue &	val,
		const string &	dest
	)		const

Convert a generic AnyValue node to the units specified in dest.

If the input is a double, convert it using the default units. If the input is a string, treat this as a dimensioned value, such as '2.7e4 J/kmol', and convert from the specified units.

Definition at line 740 of file Units.cpp.

◆ getDelta()

AnyMap getDelta ( const UnitSystem & other ) const

Get the changes to the defaults from other to this UnitSystem.

Definition at line 757 of file Units.cpp.

Member Data Documentation

◆ m_mass_factor

double m_mass_factor = 1.0

private

Factor to convert mass from this unit system to kg.

Definition at line 268 of file Units.h.

◆ m_length_factor

double m_length_factor = 1.0

private

Factor to convert length from this unit system to meters.

Definition at line 271 of file Units.h.

◆ m_time_factor

double m_time_factor = 1.0

private

Factor to convert time from this unit system to seconds.

Definition at line 274 of file Units.h.

◆ m_pressure_factor

double m_pressure_factor = 1.0

private

Factor to convert pressure from this unit system to Pa.

Definition at line 277 of file Units.h.

◆ m_energy_factor

double m_energy_factor = 1.0

private

Factor to convert energy from this unit system to J.

Definition at line 280 of file Units.h.

◆ m_activation_energy_factor

double m_activation_energy_factor = 1.0

private

Factor to convert activation energy from this unit system to J/kmol.

Definition at line 283 of file Units.h.

◆ m_quantity_factor

double m_quantity_factor = 1.0

private

Factor to convert quantity from this unit system to kmol.

Definition at line 286 of file Units.h.

◆ m_explicit_activation_energy

bool m_explicit_activation_energy = false

private

True if activation energy units are set explicitly, rather than as a combination of energy and quantity units.

Definition at line 290 of file Units.h.

◆ m_defaults

map<string, string> m_defaults

private

Map of dimensions (mass, length, etc.) to names of specified default units.

Definition at line 294 of file Units.h.

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

Detailed Description

Public Member Functions

Private Attributes

Constructor & Destructor Documentation

◆ UnitSystem() [1/2]

◆ UnitSystem() [2/2]

Member Function Documentation

◆ defaults()

◆ setDefaults() [1/2]

◆ setDefaults() [2/2]

◆ setDefaultActivationEnergy()

◆ convert() [1/3]

◆ convertTo()

◆ convertFrom()

◆ convert() [2/3]

◆ convertRateCoeff()

◆ convert() [3/3]

◆ convertActivationEnergy() [1/2]

◆ convertActivationEnergyTo()

◆ convertActivationEnergyFrom()

◆ convertActivationEnergy() [2/2]

◆ getDelta()

Member Data Documentation

◆ m_mass_factor

◆ m_length_factor

◆ m_time_factor

◆ m_pressure_factor

◆ m_energy_factor

◆ m_activation_energy_factor

◆ m_quantity_factor

◆ m_explicit_activation_energy

◆ m_defaults