Changes between Initial Version and Version 1 of doc/lol/math/real.h


Ignore:
Timestamp:
Dec 28, 2011, 6:24:19 PM (9 years ago)
Author:
sam
Comment:

start the real class documentation

Legend:

Unmodified
Added
Removed
Modified
  • doc/lol/math/real.h

    v1 v1  
     1[[TOC]]
     2= Real numbers =
     3
     4Real numbers are a custom class that stores floating-point numbers with approximately 150 digits of precision.
     5
     6Care has been taken to make the use of the `real` object as close as possible to `float` or `double`.
     7
     8== Usage ==
     9
     10Support for real numbers is straightforward:
     11
     12{{{
     13#!cpp
     14#include <lol/math/real.h>
     15}}}
     16
     17If 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.
     18
     19== Creation ==
     20
     21You can create a real number using numeric literals:
     22
     23{{{
     24#!cpp
     25real x = 1.25, y = 2.0f;
     26real z = 0x100000;
     27real w(5);
     28}}}
     29
     30It is also possible to use a string representation:
     31
     32{{{
     33#!cpp
     34real w = "1.202056903159594285399738161511449990764986292";
     35}}}
     36
     37'''Warning''': it is critical that you understand the difference between `"0.1"` and `0.1` here:
     38
     39{{{
     40#!cpp
     41real right = "0.1";
     42real wrong = 0.1;
     43}}}
     44
     45When 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.
     46
     47Note 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.
     48
     49== Constants ==
     50
     51Some 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”.
     52
     53|| `R_0` || the integer value 0 ||
     54|| `R_1` || the integer value 1 ||
     55|| `R_2` || the integer value 2 ||
     56|| `R_3` || the integer value 3 ||
     57|| `R_10` || the integer value 10 ||
     58|| `R_E` || Euler’s number ''e'' ||
     59|| `R_LOG2E` || the reciprocal of ''ln(2)'' ||
     60|| `R_LOG10E` || the reciprocal of ''ln(10)''  ||
     61|| `R_LN2` || ''ln(2)'', the natural logarithm of 2 ||
     62|| `R_LN10` || ''ln(10)'', the natural logarithm of 10 ||
     63|| `R_PI` || Archimede’s constant ''pi'' ||
     64|| `R_PI_2` || ''pi'' divided by 2 ||
     65|| `R_PI_3` || ''pi'' divided by 3 ||
     66|| `R_PI_4` || ''pi'' divided by 4 ||
     67|| `R_1_PI` || the reciprocal of ''pi'' ||
     68|| `R_2_PI` || 2 divided by ''pi'' ||
     69|| `R_2_SQRTPI` || 2 divided by the square root of ''pi'' ||
     70|| `R_SQRT2` || Pythagoras’ constant, the square root of 2 ||
     71|| `R_SQRT3` || Theodorus’ constant, the square root of 3 ||
     72|| `R_SQRT1_2` || the square root of 1/2 ||
     73
     74== Conversions ==
     75
     76Real numbers can be cast implicitly to numeric types with basically the same rules as `float` or `double`:
     77
     78{{{
     79#!cpp
     80real r ("1.5");
     81float f = r;
     82
     83double d = real::R_LN10;
     84}}}
     85
     86You can also print a real number to `stdout` with an arbitrary number of decimals:
     87
     88{{{
     89#!cpp
     90real r("0.1");
     91r.print(10);
     92}}}
     93
     94'''Bug warning''': it is not yet possible to output a real number to a standard C++ stream.
     95
     96== Operators ==
     97
     98Most expected operators are available for real numbers:
     99
     100 * `+`, `-`, `*`, `/`
     101 * unary `+`, unary `-`
     102 * `+=`, `-=`, `*=`, `/=`
     103 * `==`, `!=`, `<`, `<=`, `>`, `>=`
     104 * implicit boolean conversion and `!` operator
     105
     106As an extension, the `<<`, `<<=`, `>>` and `>>=` operators are available for very fast division or multiplication by a power of two.
     107
     108'''Example''': compute the first 150 digits of the golden ratio as the quotient of two very large Fibonacci numbers:
     109
     110{{{
     111#!cpp
     112real a0(1), a1(1);
     113for (int i = 0; i < 400; i++)
     114{
     115    real tmp = a0 + a1;
     116    a0 = a1; a1 = tmp;
     117}
     118(a0 / a1).print(150);
     119}}}
     120
     121{{{
     1226.18033988749894848204586834365638117720309179805762862135448622705260462818902449707207204189391137484754088075386891752126633862223536931793180060766e-1
     123}}}
     124
     125== Functions ==
     126
     127Most expected `<math.h>` functions are available for real numbers, even those only introduced in the C99 standard.
     128
     129=== Trigonometric functions ===
     130
     131|| `sin` || sine function ||
     132|| `cos` || cosine function ||
     133|| `tan` || tangent function ||
     134|| `asin` || arcsine function ||
     135|| `acos` || arccosine function ||
     136|| `atan` || arctangent function ||
     137|| `atan2` || two-argument arctangent ||
     138
     139=== Hyperbolic functions ===
     140
     141|| `sinh` || hyperbolic sine ||
     142|| `cosh` || hyperbolic cosine ||
     143|| `tanh` || hyperbolic tangent ||
     144
     145=== Exponentials and logarithms ===
     146
     147|| `exp` || exponential ||
     148|| `exp2` || base-2 exponential ||
     149|| `log` || natural logarithm ||
     150|| `log2` || base-2 logarithm ||
     151|| `log10` || base-10 logarithm ||
     152|| `frexp` || split number into a normalised fraction and an exponent ||
     153|| `ldexp` || multiply ''x'' by two to the power of ''y'' ||
     154|| `modf` || split number into an integral part and a fractional part ||
     155
     156=== Power functions ===
     157
     158|| `re` || reciprocal: 1 divided by ''x'' ||
     159|| `sqrt` || square root ||
     160|| `cbrt` || cubic root ||
     161|| `pow` || ''x'' raised to the power ''y'' ||
     162|| `gamma` || the gamma function ||
     163
     164'''Bug warning''': as of now, the gamma function is only accurate to about 100 decimals instead of the expected 150.
     165
     166=== Rounding, absolute value, remainder etc. ===
     167
     168|| `ceil` || the ceiling function ||
     169|| `copysign` || copy ''x''’s sign to ''y'' ||
     170|| `floor` || the floor function ||
     171|| `fabs` || absolute value ||
     172|| `round` || the rounding function ||
     173|| `fmod` || modulo: remainder of dividing ''x'' by ''y'' ||
     174
     175'''Example''': find the solution to ''cos(x) = x³'' using [http://en.wikipedia.org/wiki/Newton's_method#Solution_of_cos.28x.29_.3D_x3 Newton-Raphson]:
     176
     177{{{
     178#!cpp
     179real x(0.5);
     180for (int i = 0; i < 10; i++)
     181    x = x - (cos(x) - x * x * x) / (-sin(x) - real::R_3 * x * x);
     182x.print(150);
     183}}}
     184
     185{{{
     1868.65474033101614446620685901186228747792911931818935500889279915855447006056021560514064272319562802280528781987092146472497110319687730308211712150975e-1
     187}}}
     188
     189== Tips ==
     190
     191The 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.
     192
     193The table shows the relative timings you may expect from various operations:
     194
     195|| '''operation''' || '''speed''' (milliseconds) ||
     196|| `+` (real) || 0.14 ||
     197|| `*` (real) || 0.54 ||
     198|| `/` (real) || 6.50 ||
     199|| `sin` (real) || 90.00 ||
     200|| `exp` (real) || 160.00 ||
     201
     202As a comparison, here are some values for floats:
     203
     204|| '''operation''' || '''speed''' (milliseconds) ||
     205|| `/` (float) || 0.001 ||
     206|| `sin` (float) || 0.40 ||
     207|| `exp` (float) || 0.08 ||