Quantities and dimensions

Quantities, measurements, dimensions, and conversion results.

using snt::puq::ExponentVariant = std::variant<int, Exponent>

using snt::puq::ValueVariant = std::variant<double, val::BaseValue::PointerType>: Variant accepted for scalar or polymorphic value storage.

inline Exponent snt::puq::operator+(Exponent a, const int &i)

Add an integer to an exponent.

Parameters:

a – Exponent value.
i – Integer exponent increment.

inline Exponent snt::puq::operator+(const int &i, Exponent a)

Add an integer to an exponent.

Parameters:

i – Integer exponent increment.
a – Exponent value.

inline Exponent snt::puq::operator+(Exponent a, const Exponent &b)

Add two exponents.

Parameters:

a – First operand.
b – Second operand.

inline Exponent snt::puq::operator-(Exponent a, const int &i)

Subtract an integer from an exponent.

Parameters:

a – Exponent value.
i – Integer exponent decrement.

inline Exponent snt::puq::operator-(int i, const Exponent &a)

Subtract an exponent from an integer.

Parameters:

i – Integer exponent value.
a – Exponent to subtract.

inline Exponent snt::puq::operator-(Exponent a, const Exponent &b)

Subtract two exponents.

Parameters:

a – First operand.
b – Second operand.

inline Exponent snt::puq::operator*(const Exponent &e, const int &i)

Multiply an exponent by an integer.

Parameters:

e – Exponent value.
i – Integer multiplier.

inline Exponent snt::puq::operator*(const int &i, const Exponent &e)

Multiply an integer by an exponent.

Parameters:

i – Integer multiplier.
e – Exponent value.

inline void snt::puq::operator*=(Exponent &e, const int &i)

Multiply an exponent by an integer in place.

Parameters:

e – Exponent value.
i – Integer multiplier.

inline ExponentVariant snt::puq::add_exp(const ExponentVariant &x, const ExponentVariant &y)

inline ExponentVariant snt::puq::mul_exp(const ExponentVariant &x, const ExponentVariant &y)

inline double snt::puq::exponent_to_float(const ExponentVariant &exp)

class Dimensions

#include <dimensions.h>

Public Functions

Dimensions()

Dimensions(const Result &n)

inline Dimensions(const Result &n, const BaseDimensions &p)

Dimensions(const double m, const double e)

inline Dimensions(const double m, const double e, const BaseDimensions &p)

std::string to_string(const UnitFormat &format = UnitFormat()) const

Format the object as text.

Parameters:: format – Formatting options controlling the textual representation.

bool has_dimensions() const

Test if there are physical dimensions

Returns:: Returns true if there are some physical dimensions; otherwise returns false

bool operator==(const Dimensions &d) const

Compare two dimension descriptors, including numerical and physical parts.

Parameters:: d – Dimension descriptor to compare.

bool operator!=(const Dimensions &d) const

Compare two dimension descriptors for inequality.

Parameters:: d – Dimension descriptor to compare.

Public Members

Result numerical

BaseDimensions physical

std::vector<std::string> symbols

Utype utype

Friends

friend std::ostream &operator<<(std::ostream &os, const Dimensions &d)

class Exception : public snt::core::Exception

#include <exceptions.h>

Subclassed by snt::puq::ConverterException, snt::puq::MissingException, snt::puq::ParserException, snt::puq::PybindException, snt::puq::SystemException, snt::puq::UnitException

Public Functions

inline explicit Exception(core::ExceptionInfo info)

inline explicit Exception(std::string message, std::string details, std::string suggestion, std::string origin_file, size_t origin_line)

class Exponent

#include <exponent.h>

Rational exponent represented by an integer numerator and denominator.

Public Functions

inline Exponent()

inline Exponent(const int n[2])

inline Exponent(const int &n)

inline Exponent(const int &n, const int &d)

Exponent operator-() const

void operator+=(const Exponent &e)

Add the right-hand value in place.

Parameters:: e – Exponent value.

void operator-=(const Exponent &e)

Subtract the right-hand value in place.

Parameters:: e – Exponent value.

void operator*=(const Exponent &e)

Multiply by the right-hand value in place.

Parameters:: e – Exponent value.

void operator/=(const Exponent &e)

Divide by the right-hand value in place.

Parameters:: e – Exponent value.

bool operator==(const Exponent &e) const

Compare the two values for equality.

Parameters:: e – Exponent value.

bool operator!=(const Exponent &e) const

Compare the two values for inequality.

Parameters:: e – Exponent value.

bool operator==(const int &e) const

Compare the two values for equality.

Parameters:: e – Exponent value.

bool operator!=(const int &e) const

Compare the two values for inequality.

Parameters:: e – Exponent value.

bool operator==(const double e) const

bool operator!=(const double e) const

double to_float() const

operator double() const

std::string to_string(const UnitFormat &format = UnitFormat()) const

Format the object as text.

Parameters:: format – Formatting options controlling the textual representation.

void reduce()

Public Members

int numerator

int denominator

Friends

friend Exponent operator*(Exponent e1, const Exponent &e2)

friend Exponent operator/(Exponent e1, const Exponent &e2)

friend std::ostream &operator<<(std::ostream &os, const Exponent &e)

class Measurement

#include <measurement.h>

Numerical estimate and absolute uncertainty associated with physical base units.

The result and baseunits members describe one object: arithmetic propagates uncertainty and combines dimensions, while conversion changes only the unit representation and numerical scale.

Public Functions

inline Measurement()

Measurement(const std::string &str)

Measurement(const double est, const std::string &str)

inline Measurement(const double est)

Measurement(const double est, const Dimensions &dim)

inline Measurement(const double est, const BaseUnits &bun)

inline Measurement(const double est, const BaseUnits::ListType &bun)

Measurement(const double est, const double unc, const std::string &str)

inline Measurement(const double est, const double unc)

inline Measurement(const double est, const double unc, const BaseUnits &bun)

inline Measurement(const double est, const double unc, const BaseUnits::ListType &bun)

Measurement(val::BaseValue::PointerType est, const std::string &str)

inline Measurement(val::BaseValue::PointerType est)

inline Measurement(val::BaseValue::PointerType est, const BaseUnits &bun)

inline Measurement(val::BaseValue::PointerType est, const BaseUnits::ListType &bun)

Measurement(val::BaseValue::PointerType est, val::BaseValue::PointerType unc, const std::string &str)

inline Measurement(val::BaseValue::PointerType est, val::BaseValue::PointerType unc)

inline Measurement(val::BaseValue::PointerType est, val::BaseValue::PointerType unc, const BaseUnits &bun)

inline Measurement(val::BaseValue::PointerType est, val::BaseValue::PointerType unc, const BaseUnits::ListType &bun)

inline Measurement(const Result &est)

Measurement(const Result &est, const std::string &str)

Measurement(const Result &est, const Dimensions &dim)

inline Measurement(const Result &est, const BaseUnits &bun)

inline Measurement(const Result &est, const BaseUnits::ListType &bun)

Measurement(const Measurement &msr) = default

Measurement(const Measurement &msr, const std::string &str)

Measurement(const Measurement &msr, const Dimensions &dim)

inline Measurement(const Measurement &msr, const BaseUnits &bun)

inline Measurement(const Measurement &msr, const BaseUnits::ListType &bun)

std::size_t size() const: Return the number of stored values.

val::Array::ShapeType shape() const: Return the value shape.

std::string to_string(const UnitFormat &format = UnitFormat()) const: Format the measurement and its units.

void operator+=(const Measurement &msr)

Add the right-hand value in place.

Parameters:: msr – Measurement whose units or value are used.

void operator-=(const Measurement &msr)

Subtract the right-hand value in place.

Parameters:: msr – Measurement whose units or value are used.

void operator*=(const Measurement &msr)

Multiply by the right-hand value in place.

Parameters:: msr – Measurement whose units or value are used.

void operator/=(const Measurement &msr)

Divide by the right-hand value in place.

Parameters:: msr – Measurement whose units or value are used.

Measurement convert(const Format::Base &format) const: Convert to a selected base-unit representation.

Measurement convert(const std::string &str) const: Convert to units parsed from a string.

Measurement convert(const BaseUnits &bun) const: Convert to explicit base units.

Measurement convert(const Measurement &msr) const: Convert to another measurement’s units.

Measurement rebase_prefixes()

Measurement rebase_dimensions()

Public Members

Result result: Estimate and optional absolute uncertainty; arrays retain their shape.

BaseUnits baseunits: Physical dimensions and units attached to the estimate.

Public Static Functions

static double abs_to_rel(const double v, const double a)

Convert an absolute uncertainty to a relative uncertainty.

Parameters:

v – Central value.
a – Absolute uncertainty in the same units as v.

static double rel_to_abs(const double v, const double r)

Convert a relative uncertainty to an absolute uncertainty.

Parameters:

v – Central value.
r – Relative uncertainty expressed as a fraction of v.

static val::BaseValue::PointerType abs_to_rel(val::BaseValue::PointerType v, val::BaseValue::PointerType a)

static val::BaseValue::PointerType rel_to_abs(val::BaseValue::PointerType v, val::BaseValue::PointerType r)

Friends

friend bool operator==(const Measurement &msr1, const Measurement &msr2)

friend bool operator!=(const Measurement &msr1, const Measurement &msr2)

friend Measurement operator+(const Measurement &msr1, const Measurement &msr2)

friend Measurement operator-(const Measurement &msr1, const Measurement &msr2)

friend Measurement operator*(const Measurement &msr1, const Measurement &msr2)

friend Measurement operator/(const Measurement &msr1, const Measurement &msr2)

friend Measurement operator+(const Measurement &msr)

friend Measurement operator-(const Measurement &msr)

friend std::ostream &operator<<(std::ostream &os, const Measurement &msr)

class MissingException : public snt::puq::Exception 

#include <exceptions.h>

Missing exception is triggered when functionality is not implemented yet

Public Functions

inline MissingException(std::string message, std::string file, std::size_t line)

class ParserException : public snt::puq::Exception : #include <exceptions.h>

Parser exceptions occurs when internal PUQ parsers fails

class PybindException : public snt::puq::Exception : #include <exceptions.h>

Pybind exceptions are thrown during incorrect Python binding

class Quantity

#include <quantity.h>

A numerical value with optional uncertainty, physical units, and a unit system.

Quantities preserve the shape of the underlying VAL value. Arithmetic combines values and derives dimensions according to the unit algebra; addition and subtraction require compatible dimensions. Conversions return a new quantity.

Public Functions

inline Quantity(): Construct a dimensionless quantity with value one in the current unit system.

Quantity(std::string s, const SystemType system = SystemType::NONE)

Parse a quantity expression such as "3.2 m/s".

Parameters:

s – Quantity expression containing a value and unit expression.
system – Unit system used for resolving unit names; NONE selects the current system.

Quantity(const Measurement &v, const SystemType system = UnitSystem::current.type)

Construct a quantity from an existing measurement.

Parameters:

v – Measurement providing value, uncertainty, and units.
system – Unit system associated with the quantity.

Quantity(const Result &m, std::string s, const SystemType system = SystemType::NONE)

Construct from a numerical result and parse the target unit expression.

Parameters:

m – Estimate and optional uncertainty.
s – Unit or quantity expression.
system – Unit system used to resolve s.

Quantity(const Result &m, const SystemType system = UnitSystem::current.type)

Construct from a result using the current unit system.

Parameters:

m – Estimate and optional uncertainty.
system – Unit system associated with the quantity.

Quantity(const Result &m, const BaseUnits::ListType &bu, const SystemType system = UnitSystem::current.type)

Construct from a result and explicit base-unit components.

Parameters:

m – Estimate and optional uncertainty.
bu – Base-unit components describing the dimensions.
system – Unit system associated with the quantity.

Quantity(const double m, std::string s, const SystemType system = SystemType::NONE)

Construct a quantity from a scalar and a unit expression.

Parameters:

m – Numerical estimate.
s – Unit or quantity expression.
system – Unit system used to resolve s.

Quantity(const double m, const SystemType system = UnitSystem::current.type)

Construct a dimensionless scalar quantity.

Parameters:

m – Numerical estimate.
system – Unit system associated with the quantity.

Quantity(const double m, const BaseUnits::ListType &bu, const SystemType system = UnitSystem::current.type)

Construct a scalar quantity from explicit base-unit components.

Parameters:

m – Numerical estimate.
bu – Base-unit components describing the dimensions.
system – Unit system associated with the quantity.

Quantity(const double m, const double e, std::string s, const SystemType system = SystemType::NONE)

Construct a quantity from an estimate, absolute uncertainty, and unit expression.

Parameters:

m – Numerical estimate.
e – Absolute uncertainty in the same units as m.
s – Unit or quantity expression.
system – Unit system used to resolve s.

Quantity(const double m, const double e, const SystemType system = UnitSystem::current.type)

Construct a dimensionless quantity with an absolute uncertainty.

Parameters:

m – Numerical estimate.
e – Absolute uncertainty matching m.
system – Unit system associated with the quantity.

Quantity(const double m, const double e, const BaseUnits::ListType &bu, const SystemType system = UnitSystem::current.type)

Quantity(val::BaseValue::PointerType m, std::string s, const SystemType system = SystemType::NONE)

Quantity(val::BaseValue::PointerType m, const SystemType system = UnitSystem::current.type)

Quantity(val::BaseValue::PointerType m, const BaseUnits::ListType &bu, const SystemType system = UnitSystem::current.type)

Quantity(val::BaseValue::PointerType m, val::BaseValue::PointerType e, std::string s, const SystemType system = SystemType::NONE)

Quantity(val::BaseValue::PointerType m, val::BaseValue::PointerType e, const SystemType system = UnitSystem::current.type)

Quantity(val::BaseValue::PointerType m, val::BaseValue::PointerType e, const BaseUnits::ListType &bu, const SystemType system = UnitSystem::current.type)

std::string unit_system() const: Return the active unit system name.

std::size_t size() const: Return the number of stored values.

val::Array::ShapeType shape() const: Return the shape of the stored value.

std::string info() const: Return a human-readable description of the quantity.

std::string to_string(const UnitFormat &format = UnitFormat()) const: Format the quantity using the requested options.

void operator+=(Quantity &q)

Add the right-hand value in place.

Parameters:: q – Quantity name or expression.

void operator-=(Quantity &q)

Subtract the right-hand value in place.

Parameters:: q – Quantity name or expression.

void operator*=(Quantity &q)

Multiply by the right-hand value in place.

Parameters:: q – Quantity name or expression.

void operator/=(Quantity &q)

Divide by the right-hand value in place.

Parameters:: q – Quantity name or expression.

Quantity convert(const Format::Base &format, SystemType system = SystemType::NONE) const

Convert to a base-unit representation in the selected system.

Parameters:

format – Base-unit formatting mode.
system – Target unit system.

Returns:

Converted quantity.

Quantity convert(const Quantity &q) const

Convert to the units represented by another quantity.

Parameters:: q – Quantity providing the target units.
Returns:: Converted quantity.

Quantity convert(const Measurement &uv) const

Convert to the units represented by a measurement.

Parameters:: uv – Measurement whose units define the target dimensions and scale.
Returns:: A converted copy; the source quantity is unchanged.

Quantity convert(const Measurement &uv, const SystemType system, const std::string &q = "") const

Convert using explicit target units and an optional unit-system context.

Parameters:

uv – Measurement whose units define the target dimensions and scale.
system – Unit system used while resolving contextual conversions.
q – Optional quantity name used by contextual conversion rules.

Returns:

A converted copy; throws when dimensions are incompatible.

Quantity convert(const BaseUnits &bu) const: Convert to explicit base units, preserving the numerical value’s shape.

Quantity convert(const BaseUnits &bu, const SystemType system, const std::string &q = "") const

Convert to explicit base units in a selected system.

Parameters:

bu – Target base-unit expression.
system – Unit system used for contextual conversion rules.
q – Optional quantity name for contextual conversions.

Returns:

A converted copy; throws when dimensions are incompatible.

Quantity convert(std::string s, SystemType system = SystemType::NONE, const std::string &q = "") const

Parse target units and convert to them.

Parameters:

s – Unit or quantity expression describing the target units.
system – Unit system used to resolve the expression.
q – Optional quantity name for contextual conversion rules.

Returns:

A converted copy; throws for invalid or incompatible units.

Quantity rebase_prefixes(): Re-express units using their base prefixes.

Quantity rebase_dimensions(): Re-express units using base dimensions.

Public Members

SystemType stype: Unit system used to parse and format this quantity.

Measurement measurement: Value and absolute uncertainty together with its base units.

Friends

friend Quantity operator+(const Quantity &q1, const Quantity &q2)

friend Quantity operator-(const Quantity &q1, const Quantity &q2)

friend Quantity operator*(const Quantity &q1, const Quantity &q2)

friend Quantity operator/(const Quantity &q1, const Quantity &q2)

friend bool operator==(const Quantity &q1, const Quantity &q2)

friend bool operator!=(const Quantity &q1, const Quantity &q2)

friend Quantity operator+(const double m, const Quantity &q)

friend Quantity operator-(const double m, const Quantity &q)

friend Quantity operator*(const double m, const Quantity &q)

friend Quantity operator/(const double m, const Quantity &q)

friend Quantity operator+(const Quantity &q, const double m)

friend Quantity operator-(const Quantity &q, const double m)

friend Quantity operator*(const Quantity &q, const double m)

friend Quantity operator/(const Quantity &q, const double m)

friend Quantity operator+(val::BaseValue::PointerType a, const Quantity &q)

friend Quantity operator-(val::BaseValue::PointerType a, const Quantity &q)

friend Quantity operator*(val::BaseValue::PointerType a, const Quantity &q)

friend Quantity operator/(val::BaseValue::PointerType a, const Quantity &q)

friend Quantity operator+(const Quantity &q, val::BaseValue::PointerType a)

friend Quantity operator-(const Quantity &q, val::BaseValue::PointerType a)

friend Quantity operator*(const Quantity &q, val::BaseValue::PointerType a)

friend Quantity operator/(const Quantity &q, val::BaseValue::PointerType a)

friend Quantity operator+(const Quantity &q)

friend Quantity operator-(const Quantity &q)

friend std::ostream &operator<<(std::ostream &os, const Quantity &q)

class Result

#include <result.h>

Numerical estimate with an optional absolute uncertainty.

Values may be scalars or VAL arrays. When present, uncertainty is an absolute uncertainty in the same units and shape as estimate.

Public Functions

inline Result(const Result &other)

inline Result &operator=(const Result &other)

Assign the right-hand result to this object.

Parameters:: other – Other value used in the operation.

Result(Result&&) noexcept = default

Result &operator=(Result&&) noexcept = default

inline Result()

inline Result(const double m)

inline Result(const double m, const double e)

Result(val::BaseValue::PointerType m)

Result(val::BaseValue::PointerType m, val::BaseValue::PointerType e)

std::size_t size() const: Return the number of stored estimates.

val::Array::ShapeType shape() const: Return the estimate array shape.

std::string to_string(const UnitFormat &format = UnitFormat()) const: Format the estimate and uncertainty.

void operator+=(const Result &m)

Add the right-hand result in place and propagate its uncertainty.

Parameters:: m – Result with a compatible shape.

void operator-=(const Result &m)

Subtract the right-hand result in place and propagate its uncertainty.

Parameters:: m – Result with a compatible shape.

void operator*=(const Result &m)

Multiply by the right-hand result in place and propagate its uncertainty.

Parameters:: m – Result with a compatible shape.

void operator/=(const Result &m)

Divide by the right-hand result in place and propagate its uncertainty.

Parameters:: m – Result with a compatible shape.

bool operator==(const Result &a) const

Compare the two values for equality.

Parameters:: a – First operand.

bool operator!=(const Result &a) const

Compare the two values for inequality.

Parameters:: a – First operand.

void pow(const ExponentVariant &e): Raise the result to an exponent.

Public Members

val::BaseValue::PointerType estimate: Estimated scalar or array value.

val::BaseValue::PointerType uncertainty: Optional absolute uncertainty matching estimate.

Public Static Functions

static double abs_to_rel(const double v, const double a)

Convert an absolute uncertainty to a relative uncertainty.

Parameters:

v – Central value.
a – Absolute uncertainty matching v.

static double rel_to_abs(const double v, const double r)

Convert a relative uncertainty to an absolute uncertainty.

Parameters:

v – Central value.
r – Relative uncertainty expressed as a fraction of v.

static val::BaseValue::PointerType abs_to_rel(val::BaseValue::PointerType v, val::BaseValue::PointerType a)

static val::BaseValue::PointerType rel_to_abs(val::BaseValue::PointerType v, val::BaseValue::PointerType r)

Friends

friend Result operator-(const Result &m1)

friend Result operator+(const Result &m1, const Result &m2)

friend Result operator-(const Result &m1, const Result &m2)

friend Result operator*(const Result &m1, const Result &m2)

friend Result operator/(const Result &m1, const Result &m2)

friend std::ostream &operator<<(std::ostream &os, const Result &m)

class SystemException : public snt::puq::Exception : #include <exceptions.h>

Unit system exceptions indicate problems with unit systems

class UnitException : public snt::puq::Exception : #include <exceptions.h>

Unit exceptions indicate problems with units, conversions and operations