From 800f58430fdc577a2edd717d27b5902f75a1b1e4 Mon Sep 17 00:00:00 2001 From: Ben Hilburn Date: Fri, 27 Jun 2014 17:44:04 -0700 Subject: math: Added a new uhd::math namespace + float comparison routines * Float comparison is applied to tuning logic in DSP cores. * Properly using INT_MAX/MIN constants, defined in utils/math.hpp --- host/include/uhd/utils/CMakeLists.txt | 1 + host/include/uhd/utils/algorithm.hpp | 9 +- host/include/uhd/utils/fp_compare_delta.ipp | 175 ++++++++++++++++++ host/include/uhd/utils/fp_compare_epsilon.ipp | 177 ++++++++++++++++++ host/include/uhd/utils/math.hpp | 246 ++++++++++++++++++++++++++ 5 files changed, 604 insertions(+), 4 deletions(-) create mode 100644 host/include/uhd/utils/fp_compare_delta.ipp create mode 100644 host/include/uhd/utils/fp_compare_epsilon.ipp create mode 100644 host/include/uhd/utils/math.hpp (limited to 'host/include') diff --git a/host/include/uhd/utils/CMakeLists.txt b/host/include/uhd/utils/CMakeLists.txt index e9633286f..c308c9cde 100644 --- a/host/include/uhd/utils/CMakeLists.txt +++ b/host/include/uhd/utils/CMakeLists.txt @@ -27,6 +27,7 @@ UHD_INSTALL(FILES gain_group.hpp images.hpp log.hpp + math.hpp msg.hpp msg_task.hpp paths.hpp diff --git a/host/include/uhd/utils/algorithm.hpp b/host/include/uhd/utils/algorithm.hpp index 5598d862b..704d745d9 100644 --- a/host/include/uhd/utils/algorithm.hpp +++ b/host/include/uhd/utils/algorithm.hpp @@ -1,5 +1,5 @@ // -// Copyright 2010-2011 Ettus Research LLC +// Copyright 2010-2014 Ettus Research LLC // // This program is free software: you can redistribute it and/or modify // it under the terms of the GNU General Public License as published by @@ -19,15 +19,16 @@ #define INCLUDED_UHD_UTILS_ALGORITHM_HPP #include +#include #include #include /*! - * Useful templated functions and classes that I like to pretend are part of stl. - * Many of the range wrapper functions come with recent versions of boost (1.43). + * Useful templated functions, classes, and constants. Some of these overlap + * with the STL, but these are created with Boost for portability. + * Many of the range wrapper functions come with versions of boost >= 1.43. */ namespace uhd{ - /*! * A wrapper around std::sort that takes a range instead of an iterator. * diff --git a/host/include/uhd/utils/fp_compare_delta.ipp b/host/include/uhd/utils/fp_compare_delta.ipp new file mode 100644 index 000000000..092ade6e9 --- /dev/null +++ b/host/include/uhd/utils/fp_compare_delta.ipp @@ -0,0 +1,175 @@ +// +// Copyright 2014 Ettus Research LLC +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with this program. If not, see . +// + +#include +#include +#include + +#ifndef INCLUDED_UHD_UTILS_FLOAT_COMPARE_DELTA_IPP +#define INCLUDED_UHD_UTILS_FLOAT_COMPARE_DELTA_IPP + + +namespace uhd { namespace math { namespace fp_compare { + + template UHD_INLINE + float_t fp_compare_select_delta(float_t lhs_delta, float_t rhs_delta) { + return ((lhs_delta < rhs_delta) ? lhs_delta : rhs_delta); + } + + template<> UHD_INLINE + fp_compare_delta::fp_compare_delta(float value) { + + _value = value; + _delta = SINGLE_PRECISION_DELTA; + } + + template<> UHD_INLINE + fp_compare_delta::fp_compare_delta(double value) { + _value = value; + _delta = DOUBLE_PRECISION_DELTA; + } + + template UHD_INLINE + fp_compare_delta::fp_compare_delta(float_t value, float_t delta) + : _value(value), + _delta(delta) + { /* NOP */ } + + template UHD_INLINE + fp_compare_delta::fp_compare_delta(const fp_compare_delta& copy) + : _value(copy._value), + _delta(copy._delta) + { /* NOP */ } + + template UHD_INLINE + fp_compare_delta::~fp_compare_delta() + { /* NOP */ } + + template UHD_INLINE + void fp_compare_delta::operator=(const fp_compare_delta& copy) { + _value = copy._value; + _delta = copy._delta; + } + + template UHD_INLINE + bool operator==(fp_compare_delta lhs, fp_compare_delta rhs) { + float_t delta = fp_compare_select_delta(lhs._delta, rhs._delta); + return (std::fabs(lhs._value - rhs._value) < delta); + } + + template UHD_INLINE + bool operator!=(fp_compare_delta lhs, fp_compare_delta rhs) { + return !(lhs == rhs); + } + + template UHD_INLINE + bool operator<(fp_compare_delta lhs, fp_compare_delta rhs) { + float_t delta = fp_compare_select_delta(lhs._delta, rhs._delta); + return ((rhs._value - lhs._value) > delta); + } + + template UHD_INLINE + bool operator<=(fp_compare_delta lhs, fp_compare_delta rhs) { + return !(lhs > rhs); + } + + template UHD_INLINE + bool operator>(fp_compare_delta lhs, fp_compare_delta rhs) { + float_t delta = fp_compare_select_delta(lhs._delta, rhs._delta); + return ((lhs._value - rhs._value) > delta); + } + + template UHD_INLINE + bool operator>=(fp_compare_delta lhs, fp_compare_delta rhs) { + return !(lhs < rhs); + } + + template UHD_INLINE + bool operator==(fp_compare_delta lhs, double rhs) { + float_t delta = fp_compare_select_delta(double(lhs._delta), + DOUBLE_PRECISION_DELTA); + return (std::fabs(lhs._value - rhs) < delta); + } + + template UHD_INLINE + bool operator!=(fp_compare_delta lhs, double rhs) { + return !(lhs == rhs); + } + + template UHD_INLINE + bool operator<(fp_compare_delta lhs, double rhs) { + float_t delta = fp_compare_select_delta(double(lhs._delta), + DOUBLE_PRECISION_DELTA); + return ((rhs - lhs._value) > delta); + } + + template UHD_INLINE + bool operator<=(fp_compare_delta lhs, double rhs) { + return !(lhs > rhs); + } + + template UHD_INLINE + bool operator>(fp_compare_delta lhs, double rhs) { + float_t delta = fp_compare_select_delta(double(lhs._delta), + DOUBLE_PRECISION_DELTA); + return ((lhs._value - rhs) > delta); + } + + template UHD_INLINE + bool operator>=(fp_compare_delta lhs, double rhs) { + return !(lhs < rhs); + } + + template UHD_INLINE + bool operator==(double lhs, fp_compare_delta rhs) { + float_t delta = fp_compare_select_delta(DOUBLE_PRECISION_DELTA, + double(rhs._delta)); + return (std::fabs(lhs - rhs._value) < delta); + } + + template UHD_INLINE + bool operator!=(double lhs, fp_compare_delta rhs) { + return !(lhs == rhs); + } + + template UHD_INLINE + bool operator<(double lhs, fp_compare_delta rhs) { + float_t delta = fp_compare_select_delta(DOUBLE_PRECISION_DELTA, + double(rhs._delta)); + return ((rhs._value - lhs) > delta); + } + + template UHD_INLINE + bool operator<=(double lhs, fp_compare_delta rhs) { + return !(lhs > rhs); + } + + template UHD_INLINE + bool operator>(double lhs, fp_compare_delta rhs) { + float_t delta = fp_compare_select_delta(DOUBLE_PRECISION_DELTA, + double(rhs._delta)); + return ((lhs - rhs._value) > delta); + } + + template UHD_INLINE + bool operator>=(double lhs, fp_compare_delta rhs) { + return !(lhs < rhs); + } + +} } } //namespace uhd::math::fp_compare + +#endif /* INCLUDED_UHD_UTILS_FLOAT_COMPARE_DELTA_IPP */ diff --git a/host/include/uhd/utils/fp_compare_epsilon.ipp b/host/include/uhd/utils/fp_compare_epsilon.ipp new file mode 100644 index 000000000..ff2d585db --- /dev/null +++ b/host/include/uhd/utils/fp_compare_epsilon.ipp @@ -0,0 +1,177 @@ +// +// Copyright 2014 Ettus Research LLC +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with this program. If not, see . +// + +#include +#include +#include + +#ifndef INCLUDED_UHD_UTILS_FP_COMPARE_EPSILON_IPP +#define INCLUDED_UHD_UTILS_FP_COMPARE_EPSILON_IPP + + +namespace uhd { namespace math { namespace fp_compare { + + template<> UHD_INLINE + fp_compare_epsilon::fp_compare_epsilon(float value) { + + _value = value; + _epsilon = SINGLE_PRECISION_EPSILON; + } + + template<> UHD_INLINE + fp_compare_epsilon::fp_compare_epsilon(double value) { + _value = value; + _epsilon = DOUBLE_PRECISION_EPSILON; + } + + template UHD_INLINE + fp_compare_epsilon::fp_compare_epsilon(float_t value, float_t epsilon) + : _value(value), + _epsilon(epsilon) + { /* NOP */ } + + template UHD_INLINE + fp_compare_epsilon::fp_compare_epsilon(const fp_compare_epsilon& copy) + : _value(copy._value), + _epsilon(copy._epsilon) + { /* NOP */ } + + template UHD_INLINE + fp_compare_epsilon::~fp_compare_epsilon() + { /* NOP */ } + + template UHD_INLINE + void fp_compare_epsilon::operator=(const fp_compare_epsilon& copy) { + _value = copy._value; + _epsilon = copy._epsilon; + } + + template UHD_INLINE + bool operator==(fp_compare_epsilon lhs, fp_compare_epsilon rhs) { + + bool lhs_compare = ((std::fabs(lhs._value - rhs._value) / std::fabs(lhs._value)) + <= lhs._epsilon); + bool rhs_compare = ((std::fabs(lhs._value - rhs._value) / std::fabs(rhs._value)) + <= rhs._epsilon); + + return (lhs_compare && rhs_compare); + } + + template UHD_INLINE + bool operator!=(fp_compare_epsilon lhs, fp_compare_epsilon rhs) { + return !(lhs == rhs); + } + + template UHD_INLINE + bool operator<(fp_compare_epsilon lhs, fp_compare_epsilon rhs) { + return (lhs._value + lhs._epsilon) < (rhs._value - rhs._epsilon); + } + + template UHD_INLINE + bool operator<=(fp_compare_epsilon lhs, fp_compare_epsilon rhs) { + return !(lhs > rhs); + } + + template UHD_INLINE + bool operator>(fp_compare_epsilon lhs, fp_compare_epsilon rhs) { + return (lhs._value - lhs._epsilon) > (rhs._value + rhs._epsilon); + } + + template UHD_INLINE + bool operator>=(fp_compare_epsilon lhs, fp_compare_epsilon rhs) { + return !(lhs < rhs); + } + + template UHD_INLINE + bool operator==(fp_compare_epsilon lhs, double rhs) { + + bool lhs_compare = ((std::fabs(lhs._value - rhs) / std::fabs(lhs._value)) + <= lhs._epsilon); + bool rhs_compare = ((std::fabs(lhs._value - rhs) / std::fabs(rhs)) + <= DOUBLE_PRECISION_EPSILON); + + return (lhs_compare && rhs_compare); + } + + template UHD_INLINE + bool operator!=(fp_compare_epsilon lhs, double rhs) { + return !(lhs == rhs); + } + + template UHD_INLINE + bool operator<(fp_compare_epsilon lhs, double rhs) { + + return (lhs._value + lhs._epsilon) < (rhs - DOUBLE_PRECISION_EPSILON); + } + + template UHD_INLINE + bool operator<=(fp_compare_epsilon lhs, double rhs) { + return !(lhs > rhs); + } + + template UHD_INLINE + bool operator>(fp_compare_epsilon lhs, double rhs) { + + return (lhs._value - lhs._epsilon) > (rhs + DOUBLE_PRECISION_EPSILON); + } + + template UHD_INLINE + bool operator>=(fp_compare_epsilon lhs, double rhs) { + return !(lhs < rhs); + } + + template UHD_INLINE + bool operator==(double lhs, fp_compare_epsilon rhs) { + + bool lhs_compare = ((std::fabs(lhs - rhs._value) / std::fabs(lhs)) + <= DOUBLE_PRECISION_EPSILON); + bool rhs_compare = ((std::fabs(lhs - rhs._value) / std::fabs(rhs._value)) + <= rhs._epsilon); + + return (lhs_compare && rhs_compare); + } + + template UHD_INLINE + bool operator!=(double lhs, fp_compare_epsilon rhs) { + return !(lhs == rhs); + } + + template UHD_INLINE + bool operator<(double lhs, fp_compare_epsilon rhs) { + + return (lhs + DOUBLE_PRECISION_EPSILON) < (rhs._value - rhs._epsilon); + } + + template UHD_INLINE + bool operator<=(double lhs, fp_compare_epsilon rhs) { + return !(lhs > rhs); + } + + template UHD_INLINE + bool operator>(double lhs, fp_compare_epsilon rhs) { + + return (lhs - DOUBLE_PRECISION_EPSILON) > (rhs._value + rhs._epsilon); + } + + template UHD_INLINE + bool operator>=(double lhs, fp_compare_epsilon rhs) { + return !(lhs < rhs); + } + +} } } //namespace uhd::math::fp_compare + +#endif /* INCLUDED_UHD_UTILS_FP_COMPARE_EPSILON_IPP */ diff --git a/host/include/uhd/utils/math.hpp b/host/include/uhd/utils/math.hpp new file mode 100644 index 000000000..21825c3dc --- /dev/null +++ b/host/include/uhd/utils/math.hpp @@ -0,0 +1,246 @@ +// +// Copyright 2014 Ettus Research LLC +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU General Public License as published by +// the Free Software Foundation, either version 3 of the License, or +// (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU General Public License for more details. +// +// You should have received a copy of the GNU General Public License +// along with this program. If not, see . +// + +#ifndef INCLUDED_UHD_UTILS_MATH_HPP +#define INCLUDED_UHD_UTILS_MATH_HPP + +#include +#include +#include + + +namespace uhd { + +/*! + * Contains useful mathematical functions, classes, and constants, which should + * be used in UHD when portable / `std` options are not available. + */ +namespace math { + + /*! + * Numeric limits of certain types. + * + * There are many sources for getting these, including std::numeric_limts, + * , , and Boost. The option is preferable as it + * gives us fixed-width constants, but unfortunately is new as of C++11. + * Since this isn't available on many systems, we need to use one of the + * other options. We will use the Boost option, here, since we use Boost + * data types for portability across UHD. + */ + static const boost::int32_t BOOST_INT32_MAX = boost::numeric::bounds::highest(); + static const boost::int32_t BOOST_INT32_MIN = boost::numeric::bounds::lowest(); + + /*! + * Define epsilon values for floating point comparisons. + * + * There are a lot of different sources for epsilon values that we could use + * for this. For single-precision (f32), most machines will report an + * epsilon of 1.192e-7, and for double-precision (f64) most machines will + * report an epsilon of 2.220e-16. The issue is that these are not always + * appropriate, depending on the scale of the operands and how they have + * been rounded in previous calculations. The values defined here are + * defaults, but should be overridden for calculations depending on the + * application. + * + * If a particular comparison is operating using very small or very large + * values, a custom epsilon should be defined for those computations. This + * use-case is provided for in the `fp_compare_epsilon` class constructor. + */ + static const float SINGLE_PRECISION_EPSILON = 1.19e-7; + static const double DOUBLE_PRECISION_EPSILON = 2.22e-16; + +namespace fp_compare { + + /*! + * Class for floating-point comparisons using an epsilon. + * + * At construction, you can specify the epsilon to use for the comparisons. + * This class, combined with the operators under it, allow for + * epsilon-comparisons of floats. An example is: + * + * // Compare floats 'x' and 'y'. + * bool x_equals_y = (fp_compare_epsilon(x) == y); + * + * // Compare doubles 'x' and 'y'. + * bool x_equals_y = (fp_compare_epsilon(x) == y); + */ + template class fp_compare_epsilon { + public: + UHD_INLINE fp_compare_epsilon(float_t value); + UHD_INLINE fp_compare_epsilon(float_t value, float_t epsilon); + UHD_INLINE fp_compare_epsilon(const fp_compare_epsilon& copy); + UHD_INLINE ~fp_compare_epsilon(); + UHD_INLINE void operator=(const fp_compare_epsilon& copy); + + float_t _value; + float_t _epsilon; + }; + + /* A Note on Floating Point Equality with Epsilons + * + * There are obviously a lot of strategies for defining floating point + * equality, and in the end it all comes down to the domain at hand. UHD's + * floating-point-with-epsilon comparison algorithm is based on the method + * presented in Knuth's "The Art of Computer Science" called "very close + * with tolerance epsilon". + * + * [(|u - v| / |u|) <= e] && [(|u - v| / |v|) <= e] + * + * UHD's modification to this algorithm is using the denominator's epsilon + * value (since each float_t object has its own epsilon) for each + * comparison. + */ + + template UHD_INLINE + bool operator==(fp_compare_epsilon lhs, fp_compare_epsilon rhs); + template UHD_INLINE + bool operator!=(fp_compare_epsilon lhs, fp_compare_epsilon rhs); + template UHD_INLINE + bool operator<(fp_compare_epsilon lhs, fp_compare_epsilon rhs); + template UHD_INLINE + bool operator<=(fp_compare_epsilon lhs, fp_compare_epsilon rhs); + template UHD_INLINE + bool operator>(fp_compare_epsilon lhs, fp_compare_epsilon rhs); + template UHD_INLINE + bool operator>=(fp_compare_epsilon lhs, fp_compare_epsilon rhs); + + /* If these operators are used with floats, we rely on type promotion to + * double. */ + template UHD_INLINE + bool operator==(fp_compare_epsilon lhs, double rhs); + template UHD_INLINE + bool operator!=(fp_compare_epsilon lhs, double rhs); + template UHD_INLINE + bool operator<(fp_compare_epsilon lhs, double rhs); + template UHD_INLINE + bool operator<=(fp_compare_epsilon lhs, double rhs); + template UHD_INLINE + bool operator>(fp_compare_epsilon lhs, double rhs); + template UHD_INLINE + bool operator>=(fp_compare_epsilon lhs, double rhs); + + template UHD_INLINE + bool operator==(double lhs, fp_compare_epsilon rhs); + template UHD_INLINE + bool operator!=(double lhs, fp_compare_epsilon rhs); + template UHD_INLINE + bool operator<(double lhs, fp_compare_epsilon rhs); + template UHD_INLINE + bool operator<=(double lhs, fp_compare_epsilon rhs); + template UHD_INLINE + bool operator>(double lhs, fp_compare_epsilon rhs); + template UHD_INLINE + bool operator>=(double lhs, fp_compare_epsilon rhs); + +} // namespace fp_compare + + + /*! + * Define delta values for floating point comparisons. + * + * These are the default deltas used by the 'fp_compare_delta' class for + * single and double-precision floating point comparisons. + */ + static const float SINGLE_PRECISION_DELTA = 1e-3; + static const double DOUBLE_PRECISION_DELTA = 1e-5; + + /*! Floating-point delta to use for frequency comparisons. */ + static const double FREQ_COMPARISON_DELTA_HZ = 0.1; + + +namespace fp_compare { + +/*! + * Class for floating-point comparisons using a delta. + * + * At construction, you can specify the delta to use for the comparisons. + * This class, combined with the operators under it, allow for + * delta-comparisons of floats. An example is: + * + * // Compare floats 'x' and 'y'. + * bool x_equals_y = (fp_compare_delta(x) == y); + * + * // Compare doubles 'x' and 'y'. + * bool x_equals_y = (fp_compare_delta(x) == y); + */ + template class fp_compare_delta { + public: + UHD_INLINE fp_compare_delta(float_t value); + UHD_INLINE fp_compare_delta(float_t value, float_t delta); + UHD_INLINE fp_compare_delta(const fp_compare_delta& copy); + UHD_INLINE ~fp_compare_delta(); + UHD_INLINE void operator=(const fp_compare_delta& copy); + + float_t _value; + float_t _delta; + }; + + template UHD_INLINE + bool operator==(fp_compare_delta lhs, fp_compare_delta rhs); + template UHD_INLINE + bool operator!=(fp_compare_delta lhs, fp_compare_delta rhs); + template UHD_INLINE + bool operator<(fp_compare_delta lhs, fp_compare_delta rhs); + template UHD_INLINE + bool operator<=(fp_compare_delta lhs, fp_compare_delta rhs); + template UHD_INLINE + bool operator>(fp_compare_delta lhs, fp_compare_delta rhs); + template UHD_INLINE + bool operator>=(fp_compare_delta lhs, fp_compare_delta rhs); + + /* If these operators are used with floats, we rely on type promotion to + * double. */ + template UHD_INLINE + bool operator==(fp_compare_delta lhs, double rhs); + template UHD_INLINE + bool operator!=(fp_compare_delta lhs, double rhs); + template UHD_INLINE + bool operator<(fp_compare_delta lhs, double rhs); + template UHD_INLINE + bool operator<=(fp_compare_delta lhs, double rhs); + template UHD_INLINE + bool operator>(fp_compare_delta lhs, double rhs); + template UHD_INLINE + bool operator>=(fp_compare_delta lhs, double rhs); + + template UHD_INLINE + bool operator==(double lhs, fp_compare_delta rhs); + template UHD_INLINE + bool operator!=(double lhs, fp_compare_delta rhs); + template UHD_INLINE + bool operator<(double lhs, fp_compare_delta rhs); + template UHD_INLINE + bool operator<=(double lhs, fp_compare_delta rhs); + template UHD_INLINE + bool operator>(double lhs, fp_compare_delta rhs); + template UHD_INLINE + bool operator>=(double lhs, fp_compare_delta rhs); + +} // namespace fp_compare + + UHD_INLINE bool frequencies_are_equal(double lhs, double rhs) { + return(fp_compare::fp_compare_delta(lhs, FREQ_COMPARISON_DELTA_HZ) + == fp_compare::fp_compare_delta(rhs, FREQ_COMPARISON_DELTA_HZ)); + } + +} // namespace math +} // namespace uhd + +#include "fp_compare_epsilon.ipp" +#include "fp_compare_delta.ipp" + +#endif /* INCLUDED_UHD_UTILS_MATH_HPP */ -- cgit v1.2.3