Changeset 39757 in project


Ignore:
Timestamp:
03/25/21 04:00:33 (4 weeks ago)
Author:
Diego
Message:

math: add docs for (math base)

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/5/math

    r39576 r39757  
    1010documentation, but tweaked for the CHICKEN implementation.
    1111
    12 ==== math.number-theory
     12=== Modules
     13
     14==== (math base)
     15
     16Constants and elementary functions
     17
     18===== Constants
     19
     20<constant>phi.0</constant>
     21
     22An approximation of φ, the [[https://en.wikipedia.org/wiki/Golden_ratio|golden ratio]].
     23
     24<enscript highlight="scheme">
     25> phi.0
     261.618033988749895
     27</enscript>
     28
     29<constant>euler.0</constant>
     30
     31An approximation of ''e'', or [[https://en.wikipedia.org/wiki/E_(mathematical_constant)|Euler's number]].
     32
     33<enscript highlight="scheme">
     34> euler.0
     352.718281828459045
     36> (exp 1)
     372.718281828459045
     38</enscript>
     39
     40<constant>catalan.0</constant>
     41
     42An approximation of ''G'', or [[https://en.wikipedia.org/wiki/Catalan's_constant|Catalan's constant]].
     43
     44<enscript highlight="scheme">
     45> catalan.0
     460.915965594177219
     47</enscript>
     48
     49===== Functions
     50
     51<procedure>(float-complex? v) -> boolean</procedure>
     52
     53; v : any
     54
     55Returns {{#t}} when {{v}} is an inexact complex number. Analogous to
     56[[https://wiki.call-cc.org/man/5/Module%20(chicken%20base)#flonum|flonum?]]
     57
     58<procedure>(number->float-complex x) -> cplxnum</procedure>
     59
     60; x : number
     61
     62Returns a new complex number with a flonum real part and a flonum imaginary
     63part. Analogous to {{exact->inexact}}.
     64
     65<procedure>(power-of-two? x) -> boolean</procedure>
     66
     67; x : number
     68
     69Returns {{#t}} when {{x}} is an integer power of 2.
     70
     71Examples:
     72<enscript highlight="scheme">
     73> (power-of-two? 1.0)
     74#t
     75> (power-of-two? 1/2)
     76#t
     77> (power-of-two? (flnext 2.0))
     78#f
     79</enscript>
     80
     81<procedure>(asinh z) -> number</procedure>
     82<procedure>(acosh z) -> number</procedure>
     83<procedure>(atanh z) -> number</procedure>
     84
     85; z : number
     86
     87The inverses of {{sinh}}, {{cosh}}, and {{tanh}}.
     88
     89<procedure>(sum xs) -> number</procedure>
     90
     91; xs : (list-of number)
     92
     93Like {{(apply + xs)}}, but incurs rounding error only once when adding inexact
     94numbers. (In fact, the inexact numbers in {{xs}} are summed separately using
     95{{fpsum}}).
     96
     97===== Random Number Generation
     98
     99<procedure>(random-natural k) -> integer</procedure>
     100
     101; k : integer
     102
     103Returns a random natural number less than {{k}}, which must be positive.
     104
     105<procedure>(random-integer a b) -> integer</procedure>
     106
     107; a : integer
     108; b : integer
     109
     110Returns a random integer n such that {{(<= a n)}} and {{(< n b)}}.
     111
     112<procedure>(random-bits num)</procedure>
     113
     114; num : integer
     115
     116Returns a random natural smaller than {{(expt 2 num)}}; {{num}} must be
     117positive. For powers of two, this is faster than using {{random-natural}},
     118which is implemented in terms of {{random-bits}}, using biased rejection
     119sampling.
     120
     121===== Measuring error
     122
     123<procedure>(absolute-error x r) -> number</procedure>
     124
     125; x : number
     126; r : number
     127
     128Usually computes {{(abs (- x r))}} using exact rationals, but handles
     129non-rational reals such as {{+inf.0}} specially.
     130
     131Examples:
     132<enscript highlight="scheme">
     133> (absolute-error 1/2 1/2)
     1340
     135> (absolute-error 0.14285714285714285 1/7)
     1367.93016446160826e-18
     137> (absolute-error +inf.0 +inf.0)
     1380.0
     139> (absolute-error +inf.0 +nan.0)
     140+inf.0
     141> (absolute-error 1e-20 0.0)
     1421e-20
     143> (absolute-error (- 1.0 (fl 4999999/5000000)) 1/5000000)
     1445.751132903242251e-18
     145</enscript>
     146
     147<procedure>(relative-error x r) -> number</procedure>
     148
     149; x : number
     150; r : number
     151
     152Measures how close an approximation {{x}} is to the correct value {{r}},
     153relative to the magnitude of {{r}}.
     154
     155This function usually computes {{(abs (/ (- x r) r))}} using exact rationals, but
     156handles non-rational reals such as {{+inf.0}} specially, as well as {{r = 0}}.
     157
     158<enscript highlight="scheme">
     159> (relative-error 1/2 1/2)
     1600
     161> (relative-error 0.14285714285714285 1/7)
     1625.551115123125783e-17
     163> (relative-error +inf.0 +inf.0)
     1640.0
     165> (relative-error +inf.0 +nan.0)
     166+inf.0
     167> (relative-error 1e-20 0.0)
     168+inf.0
     169> (relative-error (- 1.0 (fl 4999999/5000000)) 1/5000000)
     1702.8755664516211255e-11
     171</enscript>
     172
     173In the last two examples, relative error is high because the result is near
     174zero. (Compare the same examples with {{absolute-error}}.) Because flonums are
     175particularly dense near zero, this makes relative error better than absolute
     176error for measuring the error in a flonum approximation. An even better one is
     177error in ulps; see {{fpulp}} and {{fpulp-error}}.
     178
     179==== (math number-theory)
     180
     181Number-theoretic functions
    13182
    14183===== Congruences and modular arithmetic
     
    13351504
    13361505=== Version History
     1506
     1507; 0.3.0 : Finish (math base) and (math flonum), bug and typo fixes, credit original authors
     1508; 0.2.3 : Fix broken .egg file
     1509; 0.2.2 : Re-organize internals, add (math base constants)
     1510; 0.2.1 : Minor bug fixes
     1511; 0.2.0 : Update (math number-theory quadratic) to reflect upstream
     1512; 0.1.0 : Initial release
Note: See TracChangeset for help on using the changeset viewer.