Fix incorrect math function output for scaled dimensionless types

As reported in issue #284, some functions produce incorrect results when passed certain dimensionless quantites. For example, this program from the issue, slightly modified for brevity and to try to make a later point clearer:

#include "units.h"
#include <iostream>
#include <cmath>
using namespace units::literals;
int main()
{
    const auto c = 1.0_um * (-1 / 1.0_m);
    std::cout << "c                   : " << c << std::endl ;
    std::cout << "units::math::exp(c) : " << units::math::exp(c) << std::endl ;
    std::cout << "std::exp(c.value()) : " << std::exp(c.value()) << std::endl ;
    return EXIT_SUCCESS ;
}

Outputs:

c                   : -1e-06
units::math::exp(c) : 0.367879
std::exp(c.value()) : 0.999999

value() is basically to<>(), but with the template parameter hard-coded to underlying_type, and to<>() is one of the documented ways to pass something to a non-unit-enabled API, so getting different results this way is rather surprising.

The proximate cause of this difference is the use of operator()() instead of value() or to<>() by (some?) functions in units::math. In the case of the example above:

template<class ScalarUnit>
dimensionless::scalar_t exp(const ScalarUnit x) noexcept
{
    static_assert(traits::is_dimensionless_unit<ScalarUnit>::value, "Type `ScalarUnit` must be a dimensionless unit derived from `unit_t`.");
    return dimensionless::scalar_t(std::exp(x()));
    // operator()() instead of value()/to()  ^^
}

The use of operator()() means that std::exp() is fed a different input than when value() is used, as demonstrated by the output from an appropriately modified version of the example program:

c                   : -1e-06
c()                 : -1
c.value()           : -1e-06
units::math::exp(c) : 0.367879
std::exp(c.value()) : 0.999999

However, this problem does not for all possible inputs. If the expression for c is changed as such:

// const auto c = 1.0_um * (-1 / 1.0_m);
const auto c = -1.0_um / 1.0_m;

The issue appears to vanish:

c                   : -1e-06
c()                 : -1e-06
c.value()           : -1e-06
units::math::exp(c) : 0.999999
std::exp(c.value()) : 0.999999

I believe this is because the different calculations result in objects with different types:

# const auto c = 1.0_um * (-1 / 1.0_m);
(lldb) p c
(const units::unit_t<units::unit<std::ratio<1, 1000000>, units::base_unit<std::ratio<0, 1>, std::ratio<0, 1>, std::ratio<0, 1>, std::ratio<0, 1>, std::ratio<0, 1>, std::ratio<0, 1>, std::ratio<0, 1>, std::ratio<0, 1>, std::ratio<0, 1> >, std::ratio<0, 1>, std::ratio<0, 1> >, double, units::linear_scale>) $0 = {
  units::linear_scale<double> = (m_value = -1)
}

# const auto c = 1.0_um / 1.0_m;
(lldb) p c
(const units::dimensionless::scalar_t) $0 = {
  units::linear_scale<double> = (m_value = 9.9999999999999995E-7)
}

Where the latter is equivalent to:

# const auto c = 1.0_um / 1.0_m;
(lldb) p c
(const units::unit_t<units::unit<std::ratio<1, 1>, units::base_unit<std::ratio<0, 1>, std::ratio<0, 1>, std::ratio<0, 1>, std::ratio<0, 1>, std::ratio<0, 1>, std::ratio<0, 1>, std::ratio<0, 1>, std::ratio<0, 1>, std::ratio<0, 1> >, std::ratio<0, 1>, std::ratio<0, 1> >, double, units::linear_scale>) $0 = {
  units::linear_scale<double> = (m_value = 9.9999999999999995E-7)
}

The difference in the results amounts to the "new" calculation having the "correct" value directly in m_value, whereas the "old" calculation has some information in the type, which could be described as the exponent in the type and the mantissa in m_value. Floating-point errors aside, they are equal.

This points to the ultimate cause of the issue: operator()() and value()/to<>() appear to consider different information when producing their results. operator()() fully discards information encoded in the type, directly returning the "raw" underlying value (modified for the decibel scale if needed), while for dimensionless types value() and to<>() account for both information encoded in the type and the "raw" underlying value in their return values. This is apparent in their implementations, where operator()() has no awareness of the units::unit tag, but value()/to<>() delegate to the conversion operator for dimensionless quantities, which explicitly "normalizes" the underlying value using units::convert<>() before returning it:

template<class Units, typename T = UNIT_LIBDEFAULT_TYPE, template<typename> class NonLinearScale = linear_scale>
class unit_t : public NonLinearScale<T>, units::detail::_unit_t
{
public:
    typedef T underlying_type;

    inline constexpr underlying_type value() const noexcept
    {
        return static_cast<underlying_type>(*this);
    }

    template<typename Ty, class = std::enable_if_t<std::is_arithmetic<Ty>::value>>
    inline constexpr Ty to() const noexcept
    {
        return static_cast<Ty>(*this);
    }

    template<class Ty, std::enable_if_t<traits::is_dimensionless_unit<Units>::value && std::is_arithmetic<Ty>::value, int> = 0>
    inline constexpr operator Ty() const noexcept
    {
        // this conversion also resolves any PI exponents, by converting from a non-zero PI ratio to a zero-pi ratio.
        return static_cast<Ty>(units::convert<Units, unit<std::ratio<1>, units::category::scalar_unit>>((*this)()));
    }
};

template<typename T>
struct linear_scale
{
    inline constexpr T operator()() const noexcept { return m_value; }
    T m_value;
};

template<typename T>
struct decibel_scale
{
    inline constexpr T operator()() const noexcept { return 10 * std::log10(m_value); }
    T m_value;
};

As a result, the problem is clear: the functions using operator()() to obtain a value to pass to std::math functions are incorrect and should be changed to use value() so relevant information is not thrown away.

nholthaus / units

Fix incorrect math function output for scaled dimensionless types #288