MooseUnits Class Reference

Physical unit management class with runtime unit string parsing, unit checking, unit conversion, and output. More...

#include <Units.h>

Public Member Functions
	MooseUnits (const std::string &unit_string)
	MooseUnits (Real f)
	MooseUnits (Real f, Real s, std::vector< std::pair< MooseUnits::BaseUnit, int > > b)
bool	conformsTo (const MooseUnits &) const
	checks if the units are dimensionally conforming (i.e. the describe the same physical quanitity)
Real	convert (Real from_value, const MooseUnits &from_unit) const
	Converts from_value in units of from_units to value this units.
void	parse (const std::string &unit_string)
	parse a unit string into a MooseUnits object
void	simplify ()
	simplify into the canonical form that permits comparisons
MooseUnits	operator* (const Real f) const
	Unit prefactor scaling.
bool	operator== (const MooseUnits &rhs) const
bool	operator== (const Real rhs) const
	operator Real () const
	cast of units representing pure numbers
bool	isLength () const
	query the nature of the unit
bool	isTime () const
bool	isMass () const
bool	isCurrent () const
bool	isTemperature () const
MooseUnits	operator* (const MooseUnits &rhs) const
	Unit combination operators for unit pairs zero out the shift.
MooseUnits	operator/ (const MooseUnits &rhs) const

Static Public Member Functions
static std::ostream &	latex (std::ostream &os)
	iostream manipulators
static std::ostream &	text (std::ostream &os)

Static Public Attributes
static const std::map< std::string, Real >	_si_prefix
	data tables with SI prefixes and known units
static const std::vector< std::pair< std::string, MooseUnits > >	_unit_table

Protected Member Functions
template<typename... Args>
void	parseError (const std::string &unit_string, std::string::const_iterator it, Args... args)
	helper function to generate a pretty mooseError
bool	isBase (const MooseUnits::BaseUnit) const
	check if the unit has a pure base

Static Protected Member Functions
static int	geti ()
	iosteam manipulator helper to toggle latex / text output

Protected Attributes
Real	_factor
	conversion factor w.r.t. the base SI units
Real	_shift
	additive shift (for Celsius and Fahrenheit)
std::vector< std::pair< BaseUnit, int > >	_base
	base SI units and their exponents

Private Types
enum class	BaseUnit {   METER , KILOGRAM , SECOND , AMPERE ,   KELVIN , COUNT , CANDELA }

Friends
std::ostream &	operator<< (std::ostream &os, const MooseUnits &dt)
MooseUnits	std::pow (const MooseUnits &, int)

Detailed Description

Physical unit management class with runtime unit string parsing, unit checking, unit conversion, and output.

Definition at line 32 of file Units.h.

Member Enumeration Documentation

BaseUnit

enum class MooseUnits::BaseUnit

strongprivate

Enumerator
METER
KILOGRAM
SECOND
AMPERE
KELVIN
COUNT
CANDELA

Definition at line 34 of file Units.h.

  {
    METER,
    KILOGRAM,
    SECOND,
    AMPERE,
    KELVIN,
    COUNT,
    CANDELA
  };

Constructor & Destructor Documentation

MooseUnits() [1/3]

MooseUnits::MooseUnits

(

const std::string &

unit_string

)

Definition at line 207 of file Units.C.

                                                    : _factor(1.0), _shift(0.0), _base()
{
  // parse the passed in unit string
  parse(unit_string);
}

MooseUnits() [2/3]

MooseUnits::MooseUnits ( Real  f )

inline

Definition at line 47 of file Units.h.

: _factor(f), _shift(), _base() {}

MooseUnits() [3/3]

MooseUnits::MooseUnits ( Real  f, Real  s, std::vector< std::pair< MooseUnits::BaseUnit, int > >  b  )

inline

Definition at line 48 of file Units.h.

    : _factor(f), _shift(s), _base(b)
  {
  }

Member Function Documentation

conformsTo()

bool MooseUnits::conformsTo

(

const MooseUnits &

u

)

const

checks if the units are dimensionally conforming (i.e. the describe the same physical quanitity)

Definition at line 214 of file Units.C.

{
  if (_base.size() != u._base.size())
    return false;
  for (std::size_t i = 0; i < _base.size(); ++i)
    if (_base[i] != u._base[i])
      return false;
 
  return true;
}

Referenced by convert(), and operator==().

convert()

Real MooseUnits::convert	(	Real	from_value,
		const MooseUnits &	from_unit
	)		const

Converts from_value in units of from_units to value this units.

Definition at line 226 of file Units.C.

{
  if (!conformsTo(from_unit))
    mooseError("Cannot convert between non-conforming units '", *this, "' and '", from_unit, "'.");
  return ((from_value + from_unit._shift) * from_unit._factor) / _factor - _shift;
}

geti()

int MooseUnits::geti ( )

staticprotected

iosteam manipulator helper to toggle latex / text output

Definition at line 562 of file Units.C.

{
  static int i = std::ios_base::xalloc();
  return i;
}

Referenced by latex(), and text().

isBase()

bool MooseUnits::isBase ( const MooseUnits::BaseUnit  base ) const

protected

check if the unit has a pure base

Definition at line 520 of file Units.C.

{
  // must have only one base unit
  if (_base.size() != 1)
    return false;
 
  // its exponent must be one
  if (_base[0].second != 1)
    return false;
 
  // and it has to be the right base unit
  return (_base[0].first == base);
}

Referenced by isCurrent(), isLength(), isMass(), isTemperature(), and isTime().

isCurrent()

bool MooseUnits::isCurrent ( ) const

inline

Definition at line 74 of file Units.h.

{ return isBase(BaseUnit::AMPERE); }

isLength()

bool MooseUnits::isLength ( ) const

inline

query the nature of the unit

Definition at line 71 of file Units.h.

{ return isBase(BaseUnit::METER); }

isMass()

bool MooseUnits::isMass ( ) const

inline

Definition at line 73 of file Units.h.

{ return isBase(BaseUnit::KILOGRAM); }

isTemperature()

bool MooseUnits::isTemperature ( ) const

inline

Definition at line 75 of file Units.h.

{ return isBase(BaseUnit::KELVIN); }

isTime()

bool MooseUnits::isTime ( ) const

inline

Definition at line 72 of file Units.h.

{ return isBase(BaseUnit::SECOND); }

latex()

std::ostream & MooseUnits::latex ( std::ostream &  os )

static

iostream manipulators

Definition at line 549 of file Units.C.

{
  os.iword(geti()) = 1;
  return os;
}

operator Real()

MooseUnits::operator Real ( ) const

explicit

cast of units representing pure numbers

Definition at line 492 of file Units.C.

{
  if (!_base.empty())
    mooseError("Unit '", *this, "' is not a pure number.");
  return _factor;
}

operator*() [1/2]

MooseUnits MooseUnits::operator*

(

const MooseUnits &

rhs

)

const

Unit combination operators for unit pairs zero out the shift.

e.g. temperatures are interpreted as temperature differentials

Definition at line 455 of file Units.C.

{
  MooseUnits u = rhs;
  u._factor *= _factor;
  u._base.insert(u._base.end(), _base.begin(), _base.end());
  u._shift = 0.0;
  u.simplify();
  return u;
}

operator*() [2/2]

MooseUnits MooseUnits::operator*

(

const Real

f

)

const

Unit prefactor scaling.

Definition at line 446 of file Units.C.

{
  MooseUnits u = *this;
  u._factor *= f;
  u._shift *= f;
  return u;
}

operator/()

MooseUnits MooseUnits::operator/

(

const MooseUnits &

rhs

)

const

Definition at line 466 of file Units.C.

{
  MooseUnits u = rhs;
  u._factor = _factor / u._factor;
  for (auto & b : u._base)
    b.second *= -1;
  u._base.insert(u._base.end(), _base.begin(), _base.end());
  u._shift = 0.0;
  u.simplify();
  return u;
}

operator==() [1/2]

bool MooseUnits::operator==

(

const MooseUnits &

rhs

)

const

Definition at line 479 of file Units.C.

{
  if (_factor != rhs._factor || _shift != rhs._shift)
    return false;
  return conformsTo(rhs);
}

operator==() [2/2]

bool MooseUnits::operator==

(

const Real

rhs

)

const

Definition at line 487 of file Units.C.

{
  return (_factor == rhs && _shift == 0.0 && _base.empty());
}

parse()

void MooseUnits::parse

(

const std::string &

unit_string

)

parse a unit string into a MooseUnits object

Definition at line 234 of file Units.C.

{
  // we need to understand * / ^int ( ) string
  // m^2*kg/(N*s)^2
  // no numerical expressions are permitted (e.g. no 1/2 0.5 4*2)
 
  // parse stack
  std::stack<std::vector<std::pair<MooseUnits::BaseUnit, int>>> stack;
  std::stack<char> op_stack;
  std::stack<MooseUnits> out;
 
  auto it = unit_string.begin();
  const auto end = unit_string.end();
 
  do
  {
    // skip whitespace
    if (*it == ' ')
    {
      it++;
      continue;
    }
    // opening parenthesis
    else if (*it == '(')
      op_stack.push(*(it++));
    // multiply or divide
    else if (*it == '*' || *it == '/')
    {
      // pop */ off
      while (!op_stack.empty() && (op_stack.top() == '*' || op_stack.top() == '/'))
      {
        auto top = op_stack.top();
        op_stack.pop();
 
        if (out.size() < 2)
          parseError(
              unit_string, it, "Applying ", top, " but don't have enough items on the stack.");
        auto rhs = out.top();
        out.pop();
        if (top == '*')
          out.top() = out.top() * rhs;
        else
          out.top() = out.top() / rhs;
      }
 
      op_stack.push(*(it++));
    }
    // closing parenthesis
    else if (*it == ')')
    {
      do
      {
        if (op_stack.empty())
          parseError(unit_string, it, "Mismatching right parenthesis.");
 
        auto top = op_stack.top();
        op_stack.pop();
 
        if (top == '(')
          break;
 
        if (top == '*' || top == '/')
        {
          if (out.size() < 2)
            parseError(
                unit_string, it, "Applying ", top, " but don't have enough items on the stack.");
          auto rhs = out.top();
          out.pop();
          if (top == '*')
            out.top() = out.top() * rhs;
          else
            out.top() = out.top() / rhs;
        }
      } while (true);
      it++;
    }
    // exponent
    else if (*it == '^')
    {
      // check for sign
      int sign = 1;
      ++it;
      if (it != end && *it == '-')
      {
        sign = -1;
        it++;
      }
 
      int num = 0;
      bool valid = false;
      while (*it >= '0' && *it <= '9')
      {
        num *= 10;
        num += *(it++) - '0';
        valid = true;
      }
 
      // error
      if (!valid)
      {
        if (it == end)
          parseError(unit_string, it, "Expected a number but found end of string.");
        else
          parseError(unit_string, it, "Expected a number but got '", (*it), "'.");
      }
 
      // exponents do not get pushed on the stack, but are applied immediately
      if (out.empty())
        parseError(unit_string, it, "Applying an exponent, but found no units in front of it.");
      out.top() = std::pow(out.top(), sign * num);
    }
    else
    {
      std::string unit;
      while (it != end && ((*it >= 'a' && *it <= 'z') || (*it >= 'A' && *it <= 'Z') ||
                           (*it >= '0' && *it <= '9') || *it == '.' || *it == '-'))
        unit += *(it++);
 
      // check if a number prefix is present
      Real si_factor;
      std::stringstream ss(unit);
      if ((ss >> si_factor).fail() || !std::isfinite(si_factor))
        si_factor = 1.0;
      else
      {
        if (ss.eof())
        {
          out.push(MooseUnits(si_factor));
          continue;
        }
        ss >> unit;
      }
 
      // parse the unit and a potential SI prefix
      auto len = unit.length();
      if (len == 0)
      {
        if (it == end)
          parseError(unit_string, it, "Expected unit but found end of string.");
        else
          parseError(unit_string, it, "Expected unit but found '", *it, "'.");
      }
 
      unsigned int i = 0;
      for (; i < _unit_table.size(); ++i)
      {
        const auto & s = _unit_table[i].first;
        const auto slen = s.length();
        if (slen <= len && unit.substr(len - slen) == s)
          break;
      }
 
      // invalid unit
      if (i == _unit_table.size())
        parseError(unit_string, it, "Unknown unit '", unit, "'.");
 
      // get prefix
      const auto & s = _unit_table[i].first;
      const auto slen = s.length();
      if (slen < len)
      {
        const auto prefix = unit.substr(0, len - slen);
        auto jt = _si_prefix.find(prefix);
        if (jt != _si_prefix.end())
          si_factor = jt->second;
        else
          parseError(unit_string, it, "Unknown SI prefix '", prefix, "' on unit '", unit, "'.");
      }
 
      // construct a unit object and push to the output stack
      MooseUnits d = _unit_table[i].second * si_factor;
      out.push(d);
    }
  } while (it != end);
 
  // unwind operator stack
  while (!op_stack.empty())
  {
    auto top = op_stack.top();
    op_stack.pop();
 
    if (top == '(' || top == ')')
      parseError(unit_string, it, "Unit string contains unmatched parenthesis.");
 
    if (top == '*' || top == '/')
    {
      if (out.size() < 2)
        parseError(unit_string,
                   it,
                   "Applying ",
                   top,
                   " but don't have enough items on the stack.",
                   out.size());
      auto rhs = out.top();
      out.pop();
      if (top == '*')
        out.top() = out.top() * rhs;
      else
        out.top() = out.top() / rhs;
    }
  }
 
  // consistency check
  if (out.size() != 1)
    mooseError("Internal parse error. Remaining output stack size should be 1, but is ",
               out.size());
 
  *this = out.top();
  simplify();
}

Referenced by MooseUnits().

parseError()

template<typename... Args>

void MooseUnits::parseError ( const std::string &  unit_string, std::string::const_iterator  it, Args...  args  )

protected

helper function to generate a pretty mooseError

Definition at line 126 of file Units.h.

{
  auto d = std::distance(unit_string.begin(), it);
  mooseError("At position ", d, " in ", unit_string, ": ", std::forward<Args>(args)...);
}

Referenced by parse().

simplify()

void MooseUnits::simplify

(

)

simplify into the canonical form that permits comparisons

Definition at line 500 of file Units.C.

{
  std::map<BaseUnit, int> base_map;
  for (auto & b : _base)
  {
    auto j = base_map.find(b.first);
    if (j == base_map.end())
      base_map.insert(b);
    else
      j->second += b.second;
  }
 
  // replace base vector with map contents
  _base.clear();
  for (auto & u : base_map)
    if (u.second != 0)
      _base.push_back(u);
}

Referenced by operator*(), operator/(), and parse().

text()

std::ostream & MooseUnits::text ( std::ostream &  os )

static

Definition at line 555 of file Units.C.

{
  os.iword(geti()) = 0;
  return os;
}

Friends And Related Symbol Documentation

operator<<

std::ostream & operator<< ( std::ostream &  os, const MooseUnits &  dt  )

friend

Definition at line 568 of file Units.C.

{
  bool latex = (os.iword(MooseUnits::geti()) == 1);
  static const std::vector<std::string> base_unit = {"m", "kg", "s", "A", "K", "at", "cd"};
 
  if (u._factor != 1.0 || u._base.empty())
  {
    os << u._factor;
    if (!u._base.empty())
      os << ' ';
  }
 
  for (const auto i : index_range(u._base))
  {
    os << (i ? (latex ? "\\cdot " : "*") : "");
 
    const auto & unit = base_unit[int(u._base[i].first)];
    if (latex)
      os << "\\text{" << unit << "}";
    else
      os << unit;
 
    if (u._base[i].second != 1)
    {
      if (latex)
        os << "^{" << u._base[i].second << '}';
      else
        os << '^' << u._base[i].second;
    }
  }
 
  return os;
}

std::pow

MooseUnits std::pow ( const MooseUnits &  , int    )

friend

Member Data Documentation

_base

std::vector<std::pair<BaseUnit, int> > MooseUnits::_base

protected

base SI units and their exponents

Definition at line 118 of file Units.h.

Referenced by conformsTo(), isBase(), operator*(), operator/(), operator==(), std::pow(), and simplify().

_factor

Real MooseUnits::_factor

protected

conversion factor w.r.t. the base SI units

Definition at line 109 of file Units.h.

Referenced by convert(), operator*(), operator*(), operator/(), operator==(), operator==(), and std::pow().

_shift

Real MooseUnits::_shift

protected

additive shift (for Celsius and Fahrenheit)

Definition at line 112 of file Units.h.

Referenced by convert(), operator*(), operator*(), operator/(), operator==(), operator==(), and std::pow().

_si_prefix

const std::map< std::string, Real > MooseUnits::_si_prefix

static

Initial value:

= {
    {"Y", 1e24}, {"Z", 1e21},  {"E", 1e18},  {"P", 1e15},  {"T", 1e12},  {"G", 1e9},  {"M", 1e6},
    {"k", 1e3},  {"h", 1e2},   {"da", 1e1},  {"d", 1e-1},  {"c", 1e-2},  {"m", 1e-3}, {"mu", 1e-6},
    {"n", 1e-9}, {"p", 1e-12}, {"f", 1e-15}, {"a", 1e-18}, {"z", 1e-21}, {"y", 1e-24}}

data tables with SI prefixes and known units

Definition at line 17 of file Units.h.

Referenced by parse().

_unit_table

const std::vector< std::pair< std::string, MooseUnits > > MooseUnits::_unit_table

static

Definition at line 22 of file Units.h.

{
  enum class BaseUnit
  {
    METER,
    KILOGRAM,
    SECOND,
    AMPERE,
    KELVIN,
    COUNT,
    CANDELA
  };
 
public:
  MooseUnits(const std::string & unit_string);
  MooseUnits(Real f) : _factor(f), _shift(), _base() {}
  MooseUnits(Real f, Real s, std::vector<std::pair<MooseUnits::BaseUnit, int>> b)
    : _factor(f), _shift(s), _base(b)
  {
  }
 
  bool conformsTo(const MooseUnits &) const;
 
  Real convert(Real from_value, const MooseUnits & from_unit) const;
 
  void parse(const std::string & unit_string);
 
  void simplify();
 
  static const std::map<std::string, Real> _si_prefix;
  static const std::vector<std::pair<std::string, MooseUnits>> _unit_table;
 
  bool isLength() const { return isBase(BaseUnit::METER); }
  bool isTime() const { return isBase(BaseUnit::SECOND); }
  bool isMass() const { return isBase(BaseUnit::KILOGRAM); }
  bool isCurrent() const { return isBase(BaseUnit::AMPERE); }
  bool isTemperature() const { return isBase(BaseUnit::KELVIN); }
 
  MooseUnits operator*(const Real f) const;
 
  MooseUnits operator*(const MooseUnits & rhs) const;
  MooseUnits operator/(const MooseUnits & rhs) const;
 
  bool operator==(const MooseUnits & rhs) const;
  bool operator==(const Real rhs) const;
 
  explicit operator Real() const;
 
  friend std::ostream & operator<<(std::ostream & os, const MooseUnits & dt);
  friend MooseUnits std::pow(const MooseUnits &, int);
 
  static std::ostream & latex(std::ostream & os);
  static std::ostream & text(std::ostream & os);
 
protected:
  template <typename... Args>
  void parseError(const std::string & unit_string, std::string::const_iterator it, Args... args);
 
  Real _factor;
 
  Real _shift;
 
  bool isBase(const MooseUnits::BaseUnit) const;
 
  std::vector<std::pair<BaseUnit, int>> _base;
 
  static int geti();
};
 
template <typename... Args>
void
MooseUnits::parseError(const std::string & unit_string,
                       std::string::const_iterator it,
                       Args... args)
{
  auto d = std::distance(unit_string.begin(), it);
  mooseError("At position ", d, " in ", unit_string, ": ", std::forward<Args>(args)...);
}

Referenced by parse().

---

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

• include/utils/Units.h
• src/utils/Units.C