<lol/math/real.h>

View this file in the source browser: trunk/src/lol/math/real.h

Real numbers are a custom class that stores floating-point numbers with approximately 150 digits of precision.

Bug warning: it is not yet possible to change the precision without recompiling everything.

Care has been taken to make the use of the real object as close as possible to float or double.

Usage

Support for real numbers is straightforward:

#include <lol/math/real.h>
using lol::real;

If you are not using the full Lol Engine but a stripped down version such as LolRemez, make sure you compile real.cpp together with your application.

If you do not wish to have a using declaration, simply use lol::real everywhere instead of real.

Creation

You can create a real number using numeric literals:

real x = 1.25, y = 2.0f;
real z = 0x100000;
real w(5);

It is also possible to use a string representation:

real w = "1.202056903159594285399738161511449990764986292";

Warning: it is critical that you understand the difference between "0.1" and 0.1 here:

real correct = "0.1";
real wrong = 0.1;

When you write 0.1 the compiler understands this as a double precision floating point literal whose actual value is 0.1000000000000000055511151231257827021181583404541015625, so you only get 17 digits of precision. When you write "0.1" the real number constructor will understand what you mean and will create an object with the highest possible precision.

Note that parsing a string to build a real number is expensive. Whenever possible, try to initialise reused variables only once, or use the constants provided by the real class.

Constants

Some commonly used constants are provided by the real class. They are similar to the M_PI, M_E etc. variables provided by the <math.h> header except they have the R_ prefix for “real”.

R_0 the integer value 0
R_1 the integer value 1
R_2 the integer value 2
R_3 the integer value 3
R_10 the integer value 10
R_E Euler’s number e
R_LOG2E the reciprocal of ln(2)
R_LOG10E the reciprocal of ln(10)
R_LN2 ln(2), the natural logarithm of 2
R_LN10 ln(10), the natural logarithm of 10
R_PI Archimede’s constant pi
R_PI_2 pi divided by 2
R_PI_3 pi divided by 3
R_PI_4 pi divided by 4
R_1_PI the reciprocal of pi
R_2_PI 2 divided by pi
R_2_SQRTPI 2 divided by the square root of pi
R_SQRT2 Pythagoras’ constant, the square root of 2
R_SQRT3 Theodorus’ constant, the square root of 3
R_SQRT1_2 the square root of 1/2

All these constants are accurate up to the full precision of the real number class.

Conversions

Real numbers can be cast implicitly to numeric types with basically the same rules as float or double:

real r ("1.5");
float f = r;

double d = real::R_LN10;

You can also print a real number to stdout with an arbitrary number of decimals:

real r("3.1415");
r.print(10);
3.141500000

Bug warning: it is not yet possible to output a real number to a standard C++ stream.

Operators

Most expected operators are available for real numbers:

  • +, -, *, /
  • unary +, unary -
  • +=, -=, *=, /=
  • ==, !=, <, <=, >, >=
  • implicit boolean conversion and ! operator

Example

Compute the first 150 digits of the golden ratio as the quotient of two very large Fibonacci numbers:

real a0(1), a1(1);
for (int i = 0; i < 400; i++)
{
    real tmp = a0 + a1;
    a0 = a1; a1 = tmp;
}
(a0 / a1).print(150);
6.18033988749894848204586834365638117720309179805762862135448622705260462818902449707207204189391137484754088075386891752126633862223536931793180060766e-1

Functions

Most expected <math.h> functions are available for real numbers, even those only introduced in the C99 standard.

Trigonometric functions

sin sine function
cos cosine function
tan tangent function
asin arcsine function
acos arccosine function
atan arctangent function
atan2 two-argument arctangent

Hyperbolic functions

sinh hyperbolic sine
cosh hyperbolic cosine
tanh hyperbolic tangent

Exponentials and logarithms

exp(x) exponential
exp2(x) base-2 exponential
log(x) natural logarithm
log2(x) base-2 logarithm
log10(x) base-10 logarithm
frexp(x,&exp) split number into a normalised fraction and an exponent
ldexp(x,exp) multiply x by two to the power of exp
modf(x) split x into an integral part and a fractional part
ulp(x) return the smallest real e such that x+e != x
nextafter(x,y) return the next representable real following x in the direction of y

Power functions

re reciprocal: 1 divided by x
sqrt square root
cbrt cubic root
pow x raised to the power y
gamma the gamma function

Bug warning: as of now, the gamma function is only accurate to about 100 decimals instead of the expected 150.

Rounding, absolute value, remainder etc.

ceil the ceiling function
copysign copy x’s sign to y
floor the floor function
fabs absolute value
round the rounding function
fmod modulo: remainder of dividing x by y

Example

Find the solution to cos(x) = x³ using Newton-Raphson:

real x(0.5);
for (int i = 0; i < 10; i++)
    x = x - (cos(x) - x * x * x) / (-sin(x) - real::R_3 * x * x);
x.print(150);
8.65474033101614446620685901186228747792911931818935500889279915855447006056021560514064272319562802280528781987092146472497110319687730308211712150975e-1

Tips

Multiplication by powers of two

For fast multiplication or division by a power of two, use ldexp or integer operands:

real a = real::R_PI * (real)8; /* DO NOT USE: SLOW! */
real b = real::R_PI * 8.0f;    /* DO NOT USE: SLOW! */
real c = real::R_PI * 8;       /* OK, will be optimised */
real d = ldexp(real::R_PI, 3); /* OK, even better than above */

Multiplication by an integer type (int, long int etc.) detects powers of two automatically.

General speed observations

The Lol Engine real numbers target accuracy rather than speed: we expect functions such as sin, exp or pow to always be accurate to the last digit of precision. However, they may be very slow.

The table shows the relative timings you may expect from various operations:

operation speed (milliseconds)
+ (real) 0.14
* (real) 0.54
/ (real) 6.50
sin (real) 90.00
exp (real) 160.00

As a comparison, here are some values for floats:

operation speed (milliseconds)
/ (float) 0.001
sin (float) 0.40
exp (float) 0.08
Last modified 4 years ago Last modified on Jan 24, 2013, 1:03:17 PM