Cantera 2.6.0

Units.h
Go to the documentation of this file.
1/**
2 * @file Units.h
3 * Header for unit conversion utilities, which are used to translate
4 * user input from input files (See \ref inputfiles and
5 * class \link Cantera::Units Units\endlink).
6 */
7
8// This file is part of Cantera. See License.txt in the top-level directory or
9// at https://cantera.org/license.txt for license and copyright information.
10
11#ifndef CT_UNITS_H
12#define CT_UNITS_H
13
14#include "cantera/base/ct_defs.h"
15
16 namespace Cantera
17{
18
19 class AnyValue;
20 class AnyMap;
21
22//! A representation of the units associated with a dimensional quantity.
23/*!
24 * Used for converting quantities between unit systems and checking for
25 * dimensional consistency. Units objects are mainly used within UnitSystem
26 * class to convert values from a user-specified Unit system to Cantera's
27 * base units (SI + kmol).
28 */
29 class Units
30{
31 public:
32 //! Create a Units object with the specified dimensions.
33 explicit Units(double factor=1.0, double mass=0, double length=0,
34 double time=0, double temperature=0, double current=0,
35 double quantity=0);
36
37 //! Create an object with the specified dimensions
38 //! @param units A string representation of the units. See UnitSystem
39 //! for a description of the formatting options.
40 //! @param force_unity ensure that conversion factor is equal to one
41 explicit Units(const std::string& units, bool force_unity=false);
42
43 //! Returns `true` if the specified Units are dimensionally consistent
44 bool convertible(const Units& other) const;
45
46 //! Return the factor for converting from this unit to Cantera's base
47 //! units.
48 double factor() const { return m_factor; }
49
50 //! Multiply two Units objects, combining their conversion factors and
51 //! dimensions
52 Units& operator*=(const Units& other);
53
54 //! Provide a string representation of these Units
55 //! @param skip_unity do not print '1' if conversion factor is equal to one
56 std::string str(bool skip_unity=true) const;
57
58 //! Raise these Units to a power, changing both the conversion factor and
59 //! the dimensions of these Units.
60 Units pow(double exponent) const;
61
62 bool operator==(const Units& other) const;
63
64 //! Return dimension of primary unit component
65 //! ("mass", "length", "time", "temperature", "current" or "quantity")
66 double dimension(const std::string& primary) const;
67
68 private:
69 //! Scale the unit by the factor `k`
70 void scale(double k) { m_factor *= k; }
71
72 double m_factor; //!< conversion factor to Cantera base units
73 double m_mass_dim;
74 double m_length_dim;
75 double m_time_dim;
76 double m_temperature_dim;
77 double m_current_dim;
78 double m_quantity_dim;
79 double m_pressure_dim; //!< pseudo-dimension to track explicit pressure units
80 double m_energy_dim; //!< pseudo-dimension to track explicit energy units
81
82 friend class UnitSystem;
83};
84
85
86//! Unit aggregation utility
87/*!
88 * Provides functions for updating and calculating effective units from a stack
89 * of unit-exponent pairs. Matching units are aggregated, where a standard unit
90 * simplifies access when joining exponents. The utility is used in the context
91 * of effective reaction rate units.
92 *
93 * @internal Helper utility class.
94 *
95 * @warning This class is an experimental part of the %Cantera API and
96 * may be changed or removed without notice.
97 */
98 struct UnitStack
99{
100 UnitStack(const Units& standardUnits) {
101 stack.reserve(2); // covers memory requirements for most applications
102 stack.emplace_back(standardUnits, 0.);
103 }
104
105 //! Alternative constructor allows for direct assignment of vector
106 UnitStack(std::initializer_list<std::pair<Units, double>> units)
107 : stack(units) {}
108
109 //! Size of UnitStack
110 size_t size() const { return stack.size(); }
111
112 //! Get standard unit used by UnitStack
113 Units standardUnits() const;
114
115 //! Set standard units
116 void setStandardUnits(Units& standardUnits);
117
118 //! Effective exponent of standard unit
119 double standardExponent() const;
120
121 //! Join (update) exponent of standard units, where the updated exponent is
122 //! the sum of the pre-existing exponent and the exponent passed as the argument.
123 void join(double exponent);
124
125 //! Update exponent of item with matching units; if it does not exist,
126 //! add unit-exponent pair at end of stack
127 void update(const Units& units, double exponent);
128
129 //! Calculate product of units-exponent stack
130 Units product() const;
131
132 std::vector<std::pair<Units, double>> stack; //!< Stack uses vector of pairs
133};
134
135
136//! Unit conversion utility
137/*!
138 * Provides functions for converting dimensional values from a given unit system.
139 * The main use is for converting values specified in input files to Cantera's
140 * native unit system, which is SI units except for the use of kmol as the base
141 * unit of quantity, that is, kilogram, meter, second, kelvin, ampere, and kmol.
142 *
143 * String representations of units can be written using multiplication,
144 * division, and exponentiation. Spaces are ignored. Positive, negative, and
145 * decimal exponents are permitted. Examples:
146 *
147 * kg*m/s^2
148 * J/kmol
149 * m*s^-2
150 * J/kg/K
151 *
152 * Metric prefixes are recognized for all units, such as nm, hPa, mg, EJ, mL, kcal.
153 *
154 * Special functions for converting activation energies allow these values to be
155 * expressed as either energy per quantity, energy (for example, eV), or temperature by
156 * applying a factor of the Avogadro number or the gas constant where needed.
157 *
158 * @ingroup inputfiles
159 */
160 class UnitSystem
161{
162 public:
163 //! Create a unit system with the specified default units
164 UnitSystem(std::initializer_list<std::string> units);
165
166 //! Default constructor for unit system (needed as VS2019 does not
167 //! recognize an optional argument with a default value)
168 UnitSystem() : UnitSystem({}) {}
169
170 //! Return default units used by the unit system
171 std::map<std::string, std::string> defaults() const;
172
173 //! Set the default units to convert from when explicit units are not
174 //! provided. Defaults can be set for mass, length, time, quantity, energy,
175 //! and pressure. Conversion using the pressure or energy units is done only
176 //! when the target units explicitly contain pressure or energy units.
177 //!
178 //! * To use SI+kmol: `setDefaults({"kg", "m", "s", "Pa", "J", "kmol"});`
179 //! * To use CGS+mol: `setDefaults({"cm", "g", "dyn/cm^2", "erg", "mol"});`
180 void setDefaults(std::initializer_list<std::string> units);
181
182 //! Set the default units using a map of dimension to unit pairs.
183 //!
184 //! Defaults for dimensions not specified will be left unchanged. To use
185 //! Cantera's default units:
186 //! ```
187 //! UnitSystem system;
188 //! std::map<string, string> defaults{
189 //! {"length", "m"}, {"mass", "kg"}, {"time", "s"},
190 //! {"quantity", "kmol"}, {"pressure", "Pa"}, {"energy", "J"},
191 //! {"activation-energy", "J/kmol"}
192 //! };
193 //! setDefaults(defaults);
194 //! ```
195 void setDefaults(const std::map<std::string, std::string>& units);
196
197 //! Set the default units to convert from when using the
198 //! `convertActivationEnergy` function.
199 void setDefaultActivationEnergy(const std::string& e_units);
200
201 //! Convert `value` from the units of `src` to the units of `dest`.
202 double convert(double value, const std::string& src,
203 const std::string& dest) const;
204 double convert(double value, const Units& src, const Units& dest) const;
205
206 //! Convert `value` to the specified `dest` units from the appropriate units
207 //! for this unit system (defined by `setDefaults`)
208 double convertTo(double value, const std::string& dest) const;
209 double convertTo(double value, const Units& dest) const;
210
211 //! Convert `value` from the specified `src` units to units appropriate for
212 //! this unit system (defined by `setDefaults`)
213 double convertFrom(double value, const std::string& src) const;
214 double convertFrom(double value, const Units& src) const;
215
216 //! Convert a generic AnyValue node to the units specified in `dest`. If the
217 //! input is a double, convert it using the default units. If the input is a
218 //! string, treat this as a dimensioned value, such as '988 kg/m^3' and convert
219 //! from the specified units.
220 double convert(const AnyValue& val, const std::string& dest) const;
221 double convert(const AnyValue& val, const Units& dest) const;
222
223 //! Convert an array of AnyValue nodes to the units specified in `dest`. For
224 //! each node, if the value is a double, convert it using the default units,
225 //! and if it is a string, treat it as a value with the given dimensions.
226 vector_fp convert(const std::vector<AnyValue>& vals,
227 const std::string& dest) const;
228 vector_fp convert(const std::vector<AnyValue>& vals,
229 const Units& dest) const;
230
231 //! Convert `value` from the units of `src` to the units of `dest`, allowing
232 //! for the different dimensions that can be used for activation energies
233 double convertActivationEnergy(double value, const std::string& src,
234 const std::string& dest) const;
235
236 //! Convert `value` to the units specified by `dest` from the default
237 //! activation energy units
238 double convertActivationEnergyTo(double value, const std::string& dest) const;
239 double convertActivationEnergyTo(double value, const Units& dest) const;
240
241 //! Convert `value` from the units specified by `src` to the default
242 //! activation energy units
243 double convertActivationEnergyFrom(double value, const std::string& src) const;
244
245 //! Convert a generic AnyValue node to the units specified in `dest`. If the
246 //! input is a double, convert it using the default units. If the input is a
247 //! string, treat this as a dimensioned value, such as '2.7e4 J/kmol', and
248 //! convert from the specified units.
249 double convertActivationEnergy(const AnyValue& val,
250 const std::string& dest) const;
251
252 //! Get the changes to the defaults from `other` to this UnitSystem
253 AnyMap getDelta(const UnitSystem& other) const;
254
255 private:
256 //! Factor to convert mass from this unit system to kg
257 double m_mass_factor;
258
259 //! Factor to convert length from this unit system to meters
260 double m_length_factor;
261
262 //! Factor to convert time from this unit system to seconds
263 double m_time_factor;
264
265 //! Factor to convert pressure from this unit system to Pa
266 double m_pressure_factor;
267
268 //! Factor to convert energy from this unit system to J
269 double m_energy_factor;
270
271 //! Factor to convert activation energy from this unit system to J/kmol
272 double m_activation_energy_factor;
273
274 //! Factor to convert quantity from this unit system to kmol
275 double m_quantity_factor;
276
277 //! True if activation energy units are set explicitly, rather than as a
278 //! combination of energy and quantity units
279 bool m_explicit_activation_energy;
280
281 //! Map of dimensions (mass, length, etc.) to names of specified default
282 //! units
283 std::map<std::string, std::string> m_defaults;
284};
285
286}
287
288#endif
Cantera::UnitSystem
Unit conversion utility.
Definition: Units.h:161
Cantera::UnitSystem::m_activation_energy_factor
double m_activation_energy_factor
Factor to convert activation energy from this unit system to J/kmol.
Definition: Units.h:272
Cantera::UnitSystem::m_explicit_activation_energy
bool m_explicit_activation_energy
True if activation energy units are set explicitly, rather than as a combination of energy and quanti...
Definition: Units.h:279
Cantera::UnitSystem::m_time_factor
double m_time_factor
Factor to convert time from this unit system to seconds.
Definition: Units.h:263
Cantera::UnitSystem::m_pressure_factor
double m_pressure_factor
Factor to convert pressure from this unit system to Pa.
Definition: Units.h:266
Cantera::UnitSystem::UnitSystem
UnitSystem()
Default constructor for unit system (needed as VS2019 does not recognize an optional argument with a ...
Definition: Units.h:168
Cantera::UnitSystem::m_energy_factor
double m_energy_factor
Factor to convert energy from this unit system to J.
Definition: Units.h:269
Cantera::UnitSystem::m_length_factor
double m_length_factor
Factor to convert length from this unit system to meters.
Definition: Units.h:260
Cantera::UnitSystem::convert
double convert(double value, const std::string &src, const std::string &dest) const
Convert value from the units of src to the units of dest.
Definition: Units.cpp:558
Cantera::UnitSystem::setDefaultActivationEnergy
void setDefaultActivationEnergy(const std::string &e_units)
Set the default units to convert from when using the convertActivationEnergy function.
Definition: Units.cpp:541
Cantera::UnitSystem::convertFrom
double convertFrom(double value, const std::string &src) const
Convert value from the specified src units to units appropriate for this unit system (defined by setD...
Definition: Units.cpp:591
Cantera::UnitSystem::convertActivationEnergy
double convertActivationEnergy(double value, const std::string &src, const std::string &dest) const
Convert value from the units of src to the units of dest, allowing for the different dimensions that ...
Definition: Units.cpp:658
Cantera::UnitSystem::defaults
std::map< std::string, std::string > defaults() const
Return default units used by the unit system.
Definition: Units.cpp:417
Cantera::UnitSystem::m_mass_factor
double m_mass_factor
Factor to convert mass from this unit system to kg.
Definition: Units.h:257
Cantera::UnitSystem::convertTo
double convertTo(double value, const std::string &dest) const
Convert value to the specified dest units from the appropriate units for this unit system (defined by...
Definition: Units.cpp:575
Cantera::UnitSystem::m_quantity_factor
double m_quantity_factor
Factor to convert quantity from this unit system to kmol.
Definition: Units.h:275
Cantera::UnitSystem::convertActivationEnergyTo
double convertActivationEnergyTo(double value, const std::string &dest) const
Convert value to the units specified by dest from the default activation energy units.
Definition: Units.cpp:690
Cantera::UnitSystem::setDefaults
void setDefaults(std::initializer_list< std::string > units)
Set the default units to convert from when explicit units are not provided.
Definition: Units.cpp:447
Cantera::UnitSystem::convertActivationEnergyFrom
double convertActivationEnergyFrom(double value, const std::string &src) const
Convert value from the units specified by src to the default activation energy units.
Definition: Units.cpp:711
Cantera::UnitSystem::getDelta
AnyMap getDelta(const UnitSystem &other) const
Get the changes to the defaults from other to this UnitSystem.
Definition: Units.cpp:740
Cantera::UnitSystem::m_defaults
std::map< std::string, std::string > m_defaults
Map of dimensions (mass, length, etc.) to names of specified default units.
Definition: Units.h:283
Cantera::Units
A representation of the units associated with a dimensional quantity.
Definition: Units.h:30
Cantera::Units::m_energy_dim
double m_energy_dim
pseudo-dimension to track explicit energy units
Definition: Units.h:80
Cantera::Units::str
std::string str(bool skip_unity=true) const
Provide a string representation of these Units.
Definition: Units.cpp:245
Cantera::Units::m_pressure_dim
double m_pressure_dim
pseudo-dimension to track explicit pressure units
Definition: Units.h:79
Cantera::Units::scale
void scale(double k)
Scale the unit by the factor k
Definition: Units.h:70
Cantera::Units::m_factor
double m_factor
conversion factor to Cantera base units
Definition: Units.h:72
Cantera::Units::pow
Units pow(double exponent) const
Raise these Units to a power, changing both the conversion factor and the dimensions of these Units.
Definition: Units.cpp:234
Cantera::Units::operator*=
Units & operator*=(const Units &other)
Multiply two Units objects, combining their conversion factors and dimensions.
Definition: Units.cpp:220
Cantera::Units::convertible
bool convertible(const Units &other) const
Returns true if the specified Units are dimensionally consistent.
Definition: Units.cpp:210
Cantera::Units::dimension
double dimension(const std::string &primary) const
Return dimension of primary unit component ("mass", "length", "time", "temperature",...
Definition: Units.cpp:314
Cantera::Units::factor
double factor() const
Return the factor for converting from this unit to Cantera's base units.
Definition: Units.h:48
Cantera::Units::Units
Units(double factor=1.0, double mass=0, double length=0, double time=0, double temperature=0, double current=0, double quantity=0)
Create a Units object with the specified dimensions.
Definition: Units.cpp:109
ct_defs.h
This file contains definitions of constants, types and terms that are used in internal routines and a...
Cantera
Namespace for the Cantera kernel.
Definition: AnyMap.cpp:557
Cantera::vector_fp
std::vector< double > vector_fp
Turn on the use of stl vectors for the basic array type within cantera Vector of doubles.
Definition: ct_defs.h:184
Cantera::UnitStack
Unit aggregation utility.
Definition: Units.h:99
Cantera::UnitStack::standardExponent
double standardExponent() const
Effective exponent of standard unit.
Definition: Units.cpp:355
Cantera::UnitStack::size
size_t size() const
Size of UnitStack.
Definition: Units.h:110
Cantera::UnitStack::update
void update(const Units &units, double exponent)
Update exponent of item with matching units; if it does not exist, add unit-exponent pair at end of s...
Definition: Units.cpp:373
Cantera::UnitStack::standardUnits
Units standardUnits() const
Get standard unit used by UnitStack.
Definition: Units.cpp:334
Cantera::UnitStack::UnitStack
UnitStack(std::initializer_list< std::pair< Units, double > > units)
Alternative constructor allows for direct assignment of vector.
Definition: Units.h:106
Cantera::UnitStack::product
Units product() const
Calculate product of units-exponent stack.
Definition: Units.cpp:388
Cantera::UnitStack::join
void join(double exponent)
Join (update) exponent of standard units, where the updated exponent is the sum of the pre-existing e...
Definition: Units.cpp:363
Cantera::UnitStack::stack
std::vector< std::pair< Units, double > > stack
Stack uses vector of pairs.
Definition: Units.h:132
Cantera::UnitStack::setStandardUnits
void setStandardUnits(Units &standardUnits)
Set standard units.
Definition: Units.cpp:342