namespace rgpot::units

Overview

Physical constants, unit conversion factors, and runtime unit parser. More…

namespace units {
 
// typedefs
 
typedef std::unique_ptr<UnitExpr> UnitExprPtr;
 
// enums
 
enum DimIndex;
enum TokenType;
 
// structs
 
struct Dimension;
struct Token;
struct UnitExpr;
struct UnitValue;
 
// global variables
 
static const Dimension DIM_LENGTH = {{1, 0, 0, 0, 0}};
static const Dimension DIM_TIME = {{0, 1, 0, 0, 0}};
static const Dimension DIM_MASS = {{0, 0, 1, 0, 0}};
static const Dimension DIM_CHARGE = {{0, 0, 0, 1, 0}};
static const Dimension DIM_ENERGY = {{2, -2, 1, 0, 0}};
static const Dimension DIM_NONE = {{0, 0, 0, 0, 0}};
static const auto BASE_UNITS;
static const auto QUANTITY_DIMS = std::unordered_map<std::string, Dimension>{     {“length”, DIM_LENGTH},     {“energy”, DIM_ENERGY},     {“force”, {{1, -2, 1, 0, 0}}},     {“pressure”, {{-1, -2, 1, 0, 0}}},     {“momentum”, {{1, -1, 1, 0, 0}}},     {“mass”, DIM_MASS},     {“velocity”, {{1, -1, 0, 0, 0}}},     {“charge”, DIM_CHARGE}, };
double BOHR_TO_ANGSTROM = 0.529177210903;
double ANGSTROM_TO_BOHR = 1.0 / BOHR_TO_ANGSTROM;
double HARTREE_TO_EV = 27.211386245988;
double EV_TO_HARTREE = 1.0 / HARTREE_TO_EV;
double HARTREE_BOHR_TO_EV_ANGSTROM =     HARTREE_TO_EV / BOHR_TO_ANGSTROM;
double NEG_GRAD_TO_FORCE = -HARTREE_BOHR_TO_EV_ANGSTROM;
double KB_HARTREE = 3.1668115634556e-6;
double KB_EV = 8.617333262e-5;
 
// global functions
 
static std::string to_lower(std::string s);
static std::vector<Token> tokenize(const std::string& unit);
static std::vector<Token> shunting_yard(const std::vector<Token>& tokens);
static UnitExprPtr read_expr(std::vector<Token>& stream);
static UnitValue parse_unit_expression(const std::string& unit);
double unit_conversion_factor(const std::string& from_unit, const std::string& to_unit);
void validate_unit(const std::string& quantity, const std::string& unit);
 
} // namespace units

Detailed Documentation

Physical constants, unit conversion factors, and runtime unit parser.

Compile-time constants use CODATA 2018 recommended values. rgpot’s native unit system: energy = eV, length = Angstrom, force = eV/Angstrom.

The runtime expression parser (unit_conversion_factor) is derived from metatomic-torch (https://github.com/metatensor/metatomic), specifically PR #173 by Rohit Goswami. Original code: BSD-3-Clause licensed, copyright metatensor developers. The parser uses the Shunting-Yard algorithm for compound unit expressions like “kJ/mol/A^2” or “(eV*u)^(1/2)” with SI-based dimensional analysis.

Global Functions

double unit_conversion_factor(const std::string& from_unit, const std::string& to_unit)

Get the multiplicative conversion factor from from_unit to to_unit.

Both arguments are parsed as compound unit expressions. Operators: * (multiply), / (divide), ^ (power), () (grouping). Whitespace is ignored, lookup is case-insensitive.

Examples:

  • unit_conversion_factor("angstrom", "bohr") length

  • unit_conversion_factor("eV/A", "hartree/bohr") force

  • unit_conversion_factor("kJ/mol", "eV") energy per particle

  • unit_conversion_factor("(eV*u)^(1/2)", "u*A/fs") momentum

Supported base units:

  • Length: angstrom (A), bohr, nanometer (nm), meter (m), cm, mm, um

  • Energy: eV, meV, Hartree, Ry, Joule (J), kcal, kJ

  • Time: second (s), ms, us, ns, ps, femtosecond (fs)

  • Mass: dalton (u), kilogram (kg), gram (g), electron_mass (m_e)

  • Charge: e, coulomb (c)

  • Dimensionless: mol

  • Derived: hbar

Throws std::invalid_argument on dimension mismatch or unknown unit.

Note

Derived from metatomic-torch (metatensor/metatomic PR #173).

void validate_unit(const std::string& quantity, const std::string& unit)

Check that unit is a valid expression with dimensions matching quantity. Known quantities: “length”, “energy”, “force”, “pressure”, “momentum”, “mass”, “velocity”, “charge”.

Throws std::invalid_argument on mismatch or parse error.