ichthyo/LUMIERA.clone
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
LUMIERA.clone/src/lib/rational.hpp

194 lines
7.1 KiB
C++
Raw Normal View History

Timeline: complete specification of ZoomWindow expected behaviour Writing this specification unveiled a limitation of our internal time base implementation, which is a 64bit microsecond grid. As it turns out, any grid based time representation will always be not precise enough to handle some relevant time specifications, which are defined by a divisor. Most notably this affects the precise display of frame duration in the GUI, and even more relevant, the sample accurate editing of sound in the timeline. Thus I decided to perform the internal computation in ZoomWindow as rational numbers, based on boost::rational Note: implementation stubbed only, test fails
2022-11-04 03:40:36 +01:00
/*
RATIONAL.hpp - support for precise rational arithmetics
Copyright (C) Lumiera.org
2022, Hermann Vosseler <Ichthyostega@web.de>
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 2 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, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/
/** @file rational.hpp
** Rational number support, based on `boost::rational`.
** As an extension to integral arithmetics, rational numbers can be defined
** as a pair (numerator, denominator); since most calculations imply multiplication
** by common factors, each calculation will be followed by normalisation to greatest
** common denominator, to keep numbers within value range. Obviously, this incurs
** a significant performance penalty — while on the other hand allowing for lossless
** computations on fractional scales, which can be notoriously difficult to handle
** with floating point numbers. The primary motivation for using this number format
** is for handling fractional time values properly, e.g 1/30 sec or 1/44100 sec.
**
** The underlying implementation from boost::rational can be parametrised with various
** integral data types; since our time handling is based on 64bit integers, we mainly
** use the specialisation `boost::rational<int64_t>`.
**
** @note all compatible integral types can be automatically converted to rational
** numbers, which is a lossless conversion. The opposite is not true: to get
** a "ordinary" number — be it integral or floating point — an explicit
** conversion using `rational_cast<NUM> (fraction)` is necessary, which
** performs the division of `numerator/denominator` in the target value domain.
**
Timeline: investigate problem with numeric overflow in fractional arithmetic Extensive tests with corner cases soon highlighted this problem inherent to integer calculations with fractional numbers: it is possible to derail the calculation by numeric overflow with values not excessively large, but using large numbers as denominator. This problem is typically triggered by addition and subtraction, where you'd naively not expect any problems. Thus changed the approach in the normalisation function, relying on an explicitly coded test rather, and performing the adjustment only after conversion back to simple integral micro-tick scale.
2022-11-06 23:56:56 +01:00
** # Perils of fractional arithmetics
**
** While the always precise results of integral numbers might seem compelling, the
** danger of _numeric overflow_ is significantly increased by fractional computations.
** Most notably, this danger is *not limited to large numbers*. Adding two fractional
** number requires multiplications with both denominators, which can overflow easily.
** Thus, for every given fractional number, there is a class of »dangerous counterparts«
** which can not be added without derailing the computation, leading to arbitrary wrong
** results without detectable failure. And these problematic counterparts are distributed
** _over the whole valid numeric range._ To give an extreme example, any numbers of the
** form `n / INT_MAX` can not be added or subtracted with any other rational number > 1,
** while being themselves perfectly valid and representable.
** \par rule of thumb
** Use fractional arithmetics only where it is possible to control the denominators involved.
** Never use them for computations drawing from arbitrary (external) input.
**
Lib: test coverage for rational-int corner cases and integer-log - detailed documentation of known problematic behaviour when working with rational fractions - demonstrate the heuristic predicate to detect dangerous numbers - add extensive coverage and microbenchmarks for the integer-logarithm implementation, based on an example on Stackoverflow. Surprising result: The std::ilog(double) function is of comparable speed, at least for GCC-8 on Debian-Buster.
2022-11-14 05:20:37 +01:00
** @see Rational_test
Timeline: complete specification of ZoomWindow expected behaviour Writing this specification unveiled a limitation of our internal time base implementation, which is a 64bit microsecond grid. As it turns out, any grid based time representation will always be not precise enough to handle some relevant time specifications, which are defined by a divisor. Most notably this affects the precise display of frame duration in the GUI, and even more relevant, the sample accurate editing of sound in the timeline. Thus I decided to perform the internal computation in ZoomWindow as rational numbers, based on boost::rational Note: implementation stubbed only, test fails
2022-11-04 03:40:36 +01:00
** @see zoom-window.hpp
** @see timevalue.hpp
*/
#ifndef LIB_RATIONAL_H
#define LIB_RATIONAL_H
Lib: consider method to sanitise a poisonous rational Especially rational numbers with large denominator can be insidious, since they might cause numeric overflow on seemingly harmless operations, like adding a small number. A solution might be to *requantise* the number into a different, way smaller denominator. Obviously this is a lossy operation; yet a small and controlled numeric error is always better than an uncontrolled numeric wrap-around.
2022-11-13 16:52:12 +01:00
#include <cmath>
#include <limits>
Timeline: complete specification of ZoomWindow expected behaviour Writing this specification unveiled a limitation of our internal time base implementation, which is a 64bit microsecond grid. As it turns out, any grid based time representation will always be not precise enough to handle some relevant time specifications, which are defined by a divisor. Most notably this affects the precise display of frame duration in the GUI, and even more relevant, the sample accurate editing of sound in the timeline. Thus I decided to perform the internal computation in ZoomWindow as rational numbers, based on boost::rational Note: implementation stubbed only, test fails
2022-11-04 03:40:36 +01:00
#include <stdint.h>
#include <boost/rational.hpp>
namespace util {
using Rat = boost::rational<int64_t>;
using boost::rational_cast;
Lib: consider method to sanitise a poisonous rational Especially rational numbers with large denominator can be insidious, since they might cause numeric overflow on seemingly harmless operations, like adding a small number. A solution might be to *requantise* the number into a different, way smaller denominator. Obviously this is a lossy operation; yet a small and controlled numeric error is always better than an uncontrolled numeric wrap-around.
2022-11-13 16:52:12 +01:00
using std::abs;
Timeline: complete specification of ZoomWindow expected behaviour Writing this specification unveiled a limitation of our internal time base implementation, which is a 64bit microsecond grid. As it turns out, any grid based time representation will always be not precise enough to handle some relevant time specifications, which are defined by a divisor. Most notably this affects the precise display of frame duration in the GUI, and even more relevant, the sample accurate editing of sound in the timeline. Thus I decided to perform the internal computation in ZoomWindow as rational numbers, based on boost::rational Note: implementation stubbed only, test fails
2022-11-04 03:40:36 +01:00
Lib: test coverage for rational-int corner cases and integer-log - detailed documentation of known problematic behaviour when working with rational fractions - demonstrate the heuristic predicate to detect dangerous numbers - add extensive coverage and microbenchmarks for the integer-logarithm implementation, based on an example on Stackoverflow. Surprising result: The std::ilog(double) function is of comparable speed, at least for GCC-8 on Debian-Buster.
2022-11-14 05:20:37 +01:00
// these are neither standard C++ nor POSIX, yet pretty much common place...
using uchar = unsigned char;
using uint = unsigned int;
Lib: consider method to sanitise a poisonous rational Especially rational numbers with large denominator can be insidious, since they might cause numeric overflow on seemingly harmless operations, like adding a small number. A solution might be to *requantise* the number into a different, way smaller denominator. Obviously this is a lossy operation; yet a small and controlled numeric error is always better than an uncontrolled numeric wrap-around.
2022-11-13 16:52:12 +01:00
/**
* Integral binary logarithm (disregarding fractional part)
* @return index of the largest bit set in `num`; -1 for `num==0`
* @todo C++20 will provide `std::bit_width(i)` — run a microbenchmark!
* @remark The implementation uses an unrolled loop to break down the given number
* in a logarithmic search, subtracting away the larger powers of 2 first.
* Explained 10/2021 by user «[ToddLehman]» in this [stackoverflow].
Lib: test coverage for rational-int corner cases and integer-log - detailed documentation of known problematic behaviour when working with rational fractions - demonstrate the heuristic predicate to detect dangerous numbers - add extensive coverage and microbenchmarks for the integer-logarithm implementation, based on an example on Stackoverflow. Surprising result: The std::ilog(double) function is of comparable speed, at least for GCC-8 on Debian-Buster.
2022-11-14 05:20:37 +01:00
* @note Microbenchmarks indicate that this function and `std::ilogb(double)` perform
* in the same order of magnitude (which is surprising). This function gets
* slightly faster for smaller data types. The naive bitshift-count implementation
* is always significantly slower (8 times for int64_t, 1.6 times for int8_t)
Lib: cover re-quantisation helper ...which I intend to use for sanitising poisonous rational numbers, as prerequisite for handling divisor based time scales in the ZoomWindow
2022-11-15 02:13:57 +01:00
* @see Rational_test::verify_intLog2()
Lib: consider method to sanitise a poisonous rational Especially rational numbers with large denominator can be insidious, since they might cause numeric overflow on seemingly harmless operations, like adding a small number. A solution might be to *requantise* the number into a different, way smaller denominator. Obviously this is a lossy operation; yet a small and controlled numeric error is always better than an uncontrolled numeric wrap-around.
2022-11-13 16:52:12 +01:00
* @see ZoomWindow_test
*
* [ToddLehman]: https://stackoverflow.com/users/267551/todd-lehman
* [stackoverflow]: https://stackoverflow.com/a/24748637 "How to do an integer log2()"
*/
Lib: test coverage for rational-int corner cases and integer-log - detailed documentation of known problematic behaviour when working with rational fractions - demonstrate the heuristic predicate to detect dangerous numbers - add extensive coverage and microbenchmarks for the integer-logarithm implementation, based on an example on Stackoverflow. Surprising result: The std::ilog(double) function is of comparable speed, at least for GCC-8 on Debian-Buster.
2022-11-14 05:20:37 +01:00
template<typename I>
Lib: consider method to sanitise a poisonous rational Especially rational numbers with large denominator can be insidious, since they might cause numeric overflow on seemingly harmless operations, like adding a small number. A solution might be to *requantise* the number into a different, way smaller denominator. Obviously this is a lossy operation; yet a small and controlled numeric error is always better than an uncontrolled numeric wrap-around.
2022-11-13 16:52:12 +01:00
inline int
Lib: test coverage for rational-int corner cases and integer-log - detailed documentation of known problematic behaviour when working with rational fractions - demonstrate the heuristic predicate to detect dangerous numbers - add extensive coverage and microbenchmarks for the integer-logarithm implementation, based on an example on Stackoverflow. Surprising result: The std::ilog(double) function is of comparable speed, at least for GCC-8 on Debian-Buster.
2022-11-14 05:20:37 +01:00
ilog2 (I num)
Lib: consider method to sanitise a poisonous rational Especially rational numbers with large denominator can be insidious, since they might cause numeric overflow on seemingly harmless operations, like adding a small number. A solution might be to *requantise* the number into a different, way smaller denominator. Obviously this is a lossy operation; yet a small and controlled numeric error is always better than an uncontrolled numeric wrap-around.
2022-11-13 16:52:12 +01:00
{
Lib: test coverage for rational-int corner cases and integer-log - detailed documentation of known problematic behaviour when working with rational fractions - demonstrate the heuristic predicate to detect dangerous numbers - add extensive coverage and microbenchmarks for the integer-logarithm implementation, based on an example on Stackoverflow. Surprising result: The std::ilog(double) function is of comparable speed, at least for GCC-8 on Debian-Buster.
2022-11-14 05:20:37 +01:00
if (num <= 0)
return -1;
const I MAX_POW = sizeof(I)*CHAR_BIT - 1;
Lib: consider method to sanitise a poisonous rational Especially rational numbers with large denominator can be insidious, since they might cause numeric overflow on seemingly harmless operations, like adding a small number. A solution might be to *requantise* the number into a different, way smaller denominator. Obviously this is a lossy operation; yet a small and controlled numeric error is always better than an uncontrolled numeric wrap-around.
2022-11-13 16:52:12 +01:00
int logB{0};
Lib: test coverage for rational-int corner cases and integer-log - detailed documentation of known problematic behaviour when working with rational fractions - demonstrate the heuristic predicate to detect dangerous numbers - add extensive coverage and microbenchmarks for the integer-logarithm implementation, based on an example on Stackoverflow. Surprising result: The std::ilog(double) function is of comparable speed, at least for GCC-8 on Debian-Buster.
2022-11-14 05:20:37 +01:00
auto remove_power = [&](I pow)
Lib: consider method to sanitise a poisonous rational Especially rational numbers with large denominator can be insidious, since they might cause numeric overflow on seemingly harmless operations, like adding a small number. A solution might be to *requantise* the number into a different, way smaller denominator. Obviously this is a lossy operation; yet a small and controlled numeric error is always better than an uncontrolled numeric wrap-around.
2022-11-13 16:52:12 +01:00
{
Lib: test coverage for rational-int corner cases and integer-log - detailed documentation of known problematic behaviour when working with rational fractions - demonstrate the heuristic predicate to detect dangerous numbers - add extensive coverage and microbenchmarks for the integer-logarithm implementation, based on an example on Stackoverflow. Surprising result: The std::ilog(double) function is of comparable speed, at least for GCC-8 on Debian-Buster.
2022-11-14 05:20:37 +01:00
if (pow > MAX_POW) return;
if (num >= I{1} << pow)
Lib: consider method to sanitise a poisonous rational Especially rational numbers with large denominator can be insidious, since they might cause numeric overflow on seemingly harmless operations, like adding a small number. A solution might be to *requantise* the number into a different, way smaller denominator. Obviously this is a lossy operation; yet a small and controlled numeric error is always better than an uncontrolled numeric wrap-around.
2022-11-13 16:52:12 +01:00
{
logB += pow;
num >>= pow;
}
};
remove_power(32);
remove_power(16);
remove_power (8);
remove_power (4);
remove_power (2);
remove_power (1);
return logB;
}
inline bool
can_represent_Product (int64_t a, int64_t b)
{
Lib: test coverage for rational-int corner cases and integer-log - detailed documentation of known problematic behaviour when working with rational fractions - demonstrate the heuristic predicate to detect dangerous numbers - add extensive coverage and microbenchmarks for the integer-logarithm implementation, based on an example on Stackoverflow. Surprising result: The std::ilog(double) function is of comparable speed, at least for GCC-8 on Debian-Buster.
2022-11-14 05:20:37 +01:00
return ilog2(abs(a))+1
+ ilog2(abs(b))+1
Lib: consider method to sanitise a poisonous rational Especially rational numbers with large denominator can be insidious, since they might cause numeric overflow on seemingly harmless operations, like adding a small number. A solution might be to *requantise* the number into a different, way smaller denominator. Obviously this is a lossy operation; yet a small and controlled numeric error is always better than an uncontrolled numeric wrap-around.
2022-11-13 16:52:12 +01:00
< 63;
}
inline bool
can_represent_Sum (Rat a, Rat b)
{
return can_represent_Product(a.numerator(), b.denominator())
and can_represent_Product(b.numerator(), a.denominator());
}
/**
* re-Quantise a rational number to a (typically smaller) denominator.
* @param u the new denominator to use
* @warning this is a lossy operation and possibly introduces an error
* of up to 1/u
* @remark Rational numbers with large numerators can be »poisonous«,
* causing numeric overflow when used, even just additively.
* This function can thus be used to _"sanitise"_ a number,
* and thus accept a small error while preventing overflow.
Lib: cover re-quantisation helper ...which I intend to use for sanitising poisonous rational numbers, as prerequisite for handling divisor based time scales in the ZoomWindow
2022-11-15 02:13:57 +01:00
* @note using extended-precision floating point to get close to the
* quantiser even for large denominator. Some platforms
* fall back to double, leading to extended error bounds
Lib: consider method to sanitise a poisonous rational Especially rational numbers with large denominator can be insidious, since they might cause numeric overflow on seemingly harmless operations, like adding a small number. A solution might be to *requantise* the number into a different, way smaller denominator. Obviously this is a lossy operation; yet a small and controlled numeric error is always better than an uncontrolled numeric wrap-around.
2022-11-13 16:52:12 +01:00
*/
inline Rat
reQuant (Rat src, int64_t u)
{
int64_t d = rational_cast<int64_t> (src);
int64_t r = src.numerator() % src.denominator();
Lib: cover re-quantisation helper ...which I intend to use for sanitising poisonous rational numbers, as prerequisite for handling divisor based time scales in the ZoomWindow
2022-11-15 02:13:57 +01:00
using f128 = long double;
Lib: consider method to sanitise a poisonous rational Especially rational numbers with large denominator can be insidious, since they might cause numeric overflow on seemingly harmless operations, like adding a small number. A solution might be to *requantise* the number into a different, way smaller denominator. Obviously this is a lossy operation; yet a small and controlled numeric error is always better than an uncontrolled numeric wrap-around.
2022-11-13 16:52:12 +01:00
// construct approximation quantised to 1/u
Lib: cover re-quantisation helper ...which I intend to use for sanitising poisonous rational numbers, as prerequisite for handling divisor based time scales in the ZoomWindow
2022-11-15 02:13:57 +01:00
f128 frac = rational_cast<f128> (Rat{r, src.denominator()});
Lib: consider method to sanitise a poisonous rational Especially rational numbers with large denominator can be insidious, since they might cause numeric overflow on seemingly harmless operations, like adding a small number. A solution might be to *requantise* the number into a different, way smaller denominator. Obviously this is a lossy operation; yet a small and controlled numeric error is always better than an uncontrolled numeric wrap-around.
2022-11-13 16:52:12 +01:00
Rat res = d + int64_t(frac*u) / Rat(u);
Lib: cover re-quantisation helper ...which I intend to use for sanitising poisonous rational numbers, as prerequisite for handling divisor based time scales in the ZoomWindow
2022-11-15 02:13:57 +01:00
ENSURE (abs (rational_cast<f128>(src) - rational_cast<f128>(res)) <= 1.0/abs(u));
Lib: consider method to sanitise a poisonous rational Especially rational numbers with large denominator can be insidious, since they might cause numeric overflow on seemingly harmless operations, like adding a small number. A solution might be to *requantise* the number into a different, way smaller denominator. Obviously this is a lossy operation; yet a small and controlled numeric error is always better than an uncontrolled numeric wrap-around.
2022-11-13 16:52:12 +01:00
return res;
}
Timeline: complete specification of ZoomWindow expected behaviour Writing this specification unveiled a limitation of our internal time base implementation, which is a 64bit microsecond grid. As it turns out, any grid based time representation will always be not precise enough to handle some relevant time specifications, which are defined by a divisor. Most notably this affects the precise display of frame duration in the GUI, and even more relevant, the sample accurate editing of sound in the timeline. Thus I decided to perform the internal computation in ZoomWindow as rational numbers, based on boost::rational Note: implementation stubbed only, test fails
2022-11-04 03:40:36 +01:00
} // namespace util
Lib: consider method to sanitise a poisonous rational Especially rational numbers with large denominator can be insidious, since they might cause numeric overflow on seemingly harmless operations, like adding a small number. A solution might be to *requantise* the number into a different, way smaller denominator. Obviously this is a lossy operation; yet a small and controlled numeric error is always better than an uncontrolled numeric wrap-around.
2022-11-13 16:52:12 +01:00
Timeline: investigate problem with numeric overflow in fractional arithmetic Extensive tests with corner cases soon highlighted this problem inherent to integer calculations with fractional numbers: it is possible to derail the calculation by numeric overflow with values not excessively large, but using large numbers as denominator. This problem is typically triggered by addition and subtraction, where you'd naively not expect any problems. Thus changed the approach in the normalisation function, relying on an explicitly coded test rather, and performing the adjustment only after conversion back to simple integral micro-tick scale.
2022-11-06 23:56:56 +01:00
/**
Timeline: complete specification of ZoomWindow expected behaviour Writing this specification unveiled a limitation of our internal time base implementation, which is a 64bit microsecond grid. As it turns out, any grid based time representation will always be not precise enough to handle some relevant time specifications, which are defined by a divisor. Most notably this affects the precise display of frame duration in the GUI, and even more relevant, the sample accurate editing of sound in the timeline. Thus I decided to perform the internal computation in ZoomWindow as rational numbers, based on boost::rational Note: implementation stubbed only, test fails
2022-11-04 03:40:36 +01:00
* user defined literal for constant rational numbers.
* \code
* Rat twoThirds = 2_r/3;
Timeline: investigate problem with numeric overflow in fractional arithmetic Extensive tests with corner cases soon highlighted this problem inherent to integer calculations with fractional numbers: it is possible to derail the calculation by numeric overflow with values not excessively large, but using large numbers as denominator. This problem is typically triggered by addition and subtraction, where you'd naively not expect any problems. Thus changed the approach in the normalisation function, relying on an explicitly coded test rather, and performing the adjustment only after conversion back to simple integral micro-tick scale.
2022-11-06 23:56:56 +01:00
* \endcode
Timeline: complete specification of ZoomWindow expected behaviour Writing this specification unveiled a limitation of our internal time base implementation, which is a 64bit microsecond grid. As it turns out, any grid based time representation will always be not precise enough to handle some relevant time specifications, which are defined by a divisor. Most notably this affects the precise display of frame duration in the GUI, and even more relevant, the sample accurate editing of sound in the timeline. Thus I decided to perform the internal computation in ZoomWindow as rational numbers, based on boost::rational Note: implementation stubbed only, test fails
2022-11-04 03:40:36 +01:00
*/
inline util::Rat
operator""_r (unsigned long long num)
{
return util::Rat{num};
}
#endif /*LIB_RATIONAL_H*/
Reference in a new issue Copy permalink