/usr/share/doc/racket/math/utils.html is in racket-doc 6.7-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"/><title>10 Stuff That Doesn't Belong Anywhere Else</title><link rel="stylesheet" type="text/css" href="../scribble.css" title="default"/><link rel="stylesheet" type="text/css" href="../racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-style.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../manual-racket.css" title="default"/><link rel="stylesheet" type="text/css" href="../doc-site.css" title="default"/><script type="text/javascript" src="../scribble-common.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../manual-racket.js"></script><script type="text/javascript" src="../doc-site.js"></script><script type="text/javascript" src="../local-redirect/local-redirect.js"></script><script type="text/javascript" src="../local-redirect/local-user-redirect.js"></script><!--[if IE 6]><style type="text/css">.SIEHidden { overflow: hidden; }</style><![endif]--></head><body id="doc-racket-lang-org"><div class="tocset"><div class="tocview"><div class="tocviewlist tocviewlisttopspace"><div class="tocviewtitle"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_0");">▼</a></td><td></td><td><a href="index.html" class="tocviewlink" data-pltdoc="x">Math Library</a></td></tr></table></div><div class="tocviewsublisttop" style="display: block;" id="tocview_0"><table cellspacing="0" cellpadding="0"><tr><td align="right">1 </td><td><a href="base.html" class="tocviewlink" data-pltdoc="x">Constants and Elementary Functions</a></td></tr><tr><td align="right">2 </td><td><a href="flonum.html" class="tocviewlink" data-pltdoc="x">Flonums</a></td></tr><tr><td align="right">3 </td><td><a href="special.html" class="tocviewlink" data-pltdoc="x">Special Functions</a></td></tr><tr><td align="right">4 </td><td><a href="number-theory.html" class="tocviewlink" data-pltdoc="x">Number Theory</a></td></tr><tr><td align="right">5 </td><td><a href="bigfloat.html" class="tocviewlink" data-pltdoc="x">Arbitrary-<wbr></wbr>Precision Floating-<wbr></wbr>Point Numbers (<a name="(tech._bigfloat)"></a><span style="font-style: italic">Bigfloats</span>)</a></td></tr><tr><td align="right">6 </td><td><a href="array.html" class="tocviewlink" data-pltdoc="x">Arrays</a></td></tr><tr><td align="right">7 </td><td><a href="matrices.html" class="tocviewlink" data-pltdoc="x">Matrices and Linear Algebra</a></td></tr><tr><td align="right">8 </td><td><a href="stats.html" class="tocviewlink" data-pltdoc="x">Statistics Functions</a></td></tr><tr><td align="right">9 </td><td><a href="dist.html" class="tocviewlink" data-pltdoc="x">Probability Distributions</a></td></tr><tr><td align="right">10 </td><td><a href="" class="tocviewselflink" data-pltdoc="x">Stuff That Doesn’t Belong Anywhere Else</a></td></tr></table></div></div><div class="tocviewlist"><table cellspacing="0" cellpadding="0"><tr><td style="width: 1em;"><a href="javascript:void(0);" title="Expand/Collapse" class="tocviewtoggle" onclick="TocviewToggle(this,"tocview_1");">►</a></td><td>10 </td><td><a href="" class="tocviewselflink" data-pltdoc="x">Stuff That Doesn’t Belong Anywhere Else</a></td></tr></table><div class="tocviewsublistbottom" style="display: none;" id="tocview_1"><table cellspacing="0" cellpadding="0"><tr><td align="right">10.1 </td><td><a href="#%28part._utils~3aparallel%29" class="tocviewlink" data-pltdoc="x">Parallelization</a></td></tr><tr><td align="right">10.2 </td><td><a href="#%28part._utils~3adft%29" class="tocviewlink" data-pltdoc="x">Discrete Fourier Transform Conventions</a></td></tr><tr><td align="right">10.3 </td><td><a href="#%28part._utils~3afpu-test%29" class="tocviewlink" data-pltdoc="x">Floating-<wbr></wbr>Point Compliance Testing</a></td></tr></table></div></div></div><div class="tocsub"><div class="tocsubtitle">On this page:</div><table class="tocsublist" cellspacing="0"><tr><td><span class="tocsublinknumber">10.1<tt> </tt></span><a href="#%28part._utils~3aparallel%29" class="tocsubseclink" data-pltdoc="x">Parallelization</a></td></tr><tr><td><a href="#%28def._%28%28lib._math%2Futils..rkt%29._max-math-threads%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">max-<wbr></wbr>math-<wbr></wbr>threads</span></span></a></td></tr><tr><td><span class="tocsublinknumber">10.2<tt> </tt></span><a href="#%28part._utils~3adft%29" class="tocsubseclink" data-pltdoc="x">Discrete Fourier Transform Conventions</a></td></tr><tr><td><a href="#%28def._%28%28lib._math%2Futils..rkt%29._dft-convention%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">dft-<wbr></wbr>convention</span></span></a></td></tr><tr><td><a href="#%28def._%28%28lib._math%2Futils..rkt%29._dft-inverse-convention%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">dft-<wbr></wbr>inverse-<wbr></wbr>convention</span></span></a></td></tr><tr><td><span class="tocsublinknumber">10.3<tt> </tt></span><a href="#%28part._utils~3afpu-test%29" class="tocsubseclink" data-pltdoc="x">Floating-<wbr></wbr>Point Compliance Testing</a></td></tr><tr><td><a href="#%28def._%28%28lib._math%2Futils..rkt%29._test-floating-point%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">test-<wbr></wbr>floating-<wbr></wbr>point</span></span></a></td></tr><tr><td><a href="#%28def._%28%28lib._math%2Futils..rkt%29._print-fp-test-progress~3f%29%29" class="tocsubnonseclink" data-pltdoc="x"><span class="RktSym"><span class="RktValLink">print-<wbr></wbr>fp-<wbr></wbr>test-<wbr></wbr>progress?</span></span></a></td></tr></table></div></div><div class="maincolumn"><div class="main"><div class="versionbox"><span class="version">6.7</span></div><div class="navsettop"><span class="navleft"><form class="searchform"><input class="searchbox" style="color: #888;" type="text" value="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "6.7", "../");" onfocus="this.style.color="black"; this.style.textAlign="left"; if (this.value == "...search manuals...") this.value="";" onblur="if (this.value.match(/^ *$/)) { this.style.color="#888"; this.style.textAlign="center"; this.value="...search manuals..."; }"/></form> <a href="../index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("6.7");">top</a></span><span class="navright"> <a href="dist_flonum.html" title="backward to "9.6 Low-Level Distribution Functions"" data-pltdoc="x">← prev</a> <a href="index.html" title="up to "Math Library"" data-pltdoc="x">up</a> <span class="nonavigation">next →</span></span> </div><h3 x-source-module="(lib "math/scribblings/math.scrbl")" x-source-pkg="math-doc" x-part-tag=""utils"">10<tt> </tt><a name="(part._utils)"></a><a name="(mod-path._math/utils)"></a>Stuff That Doesn’t Belong Anywhere Else</h3><div class="SAuthorListBox"><span class="SAuthorList"><p class="author">Neil Toronto <<a href="mailto:ntoronto@racket-lang.org">ntoronto@racket-lang.org</a>></p></span></div><p><table cellspacing="0" cellpadding="0" class="defmodule"><tr><td align="left"><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=require.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fbase..rkt%2529._require%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">require</a></span><span class="stt"> </span><a href="" class="RktModLink" data-pltdoc="x"><span class="RktSym">math/utils</span></a><span class="RktPn">)</span></td><td align="right"><span class="RpackageSpec"><span class="Smaller"> package:</span> <span class="stt">math-lib</span></span></td></tr></table></p><h4 x-source-module="(lib "math/scribblings/math.scrbl")" x-source-pkg="math-doc" x-part-tag=""utils:parallel"">10.1<tt> </tt><a name="(part._utils~3aparallel)"></a>Parallelization</h4><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>parameter</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._math/utils..rkt)._max-math-threads))"></a><span title="Provided from: math/utils | Package: math-lib"><span class="RktSym"><a href="#%28def._%28%28lib._math%2Futils..rkt%29._max-math-threads%29%29" class="RktValDef RktValLink" data-pltdoc="x">max-math-threads</a></span></span><span class="RktPn"></span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=ts-reference&rel=type-ref.html%23%2528form._%2528%2528lib._typed-racket%252Fbase-env%252Fbase-types..rkt%2529._.Positive-.Integer%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">Positive-Integer</a></span></p></blockquote></td></tr><tr><td><span class="RktPn">(</span><span title="Provided from: math/utils | Package: math-lib"><span class="RktSym"><a href="#%28def._%28%28lib._math%2Futils..rkt%29._max-math-threads%29%29" class="RktValDef RktValLink" data-pltdoc="x">max-math-threads</a></span></span><span class="hspace"> </span><span class="RktVar">num</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=void.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._void%7E3f%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">void?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">num</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=ts-reference&rel=type-ref.html%23%2528form._%2528%2528lib._typed-racket%252Fbase-env%252Fbase-types..rkt%2529._.Positive-.Integer%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">Positive-Integer</a></span></td></tr></table></blockquote></div><div class="SIntrapara">The maximum number of threads a parallelized <a href="index.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">math</span></a> function
will use. The default value is <span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=generic-numbers.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._max%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">max</a></span><span class="stt"> </span><span class="RktVal">1</span><span class="stt"> </span><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=futures.html%23%2528def._%2528%2528lib._racket%252Ffuture..rkt%2529._processor-count%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">processor-count</a></span><span class="RktPn">)</span><span class="RktPn">)</span>.</div></p><h4 x-source-module="(lib "math/scribblings/math.scrbl")" x-source-pkg="math-doc" x-part-tag=""utils:dft"">10.2<tt> </tt><a name="(part._utils~3adft)"></a>Discrete Fourier Transform Conventions</h4><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>parameter</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._math/utils..rkt)._dft-convention))"></a><span title="Provided from: math/utils | Package: math-lib"><span class="RktSym"><a href="#%28def._%28%28lib._math%2Futils..rkt%29._dft-convention%29%29" class="RktValDef RktValLink" data-pltdoc="x">dft-convention</a></span></span><span class="RktPn"></span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=ts-reference&rel=type-ref.html%23%2528form._%2528%2528lib._typed-racket%252Fbase-env%252Fbase-types-extra..rkt%2529._.List%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">List</a></span><span class="hspace"> </span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=ts-reference&rel=type-ref.html%23%2528form._%2528%2528lib._typed-racket%252Fbase-env%252Fbase-types..rkt%2529._.Real%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">Real</a></span><span class="hspace"> </span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=ts-reference&rel=type-ref.html%23%2528form._%2528%2528lib._typed-racket%252Fbase-env%252Fbase-types..rkt%2529._.Real%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">Real</a></span><span class="RktPn">)</span></p></blockquote></td></tr><tr><td><span class="RktPn">(</span><span title="Provided from: math/utils | Package: math-lib"><span class="RktSym"><a href="#%28def._%28%28lib._math%2Futils..rkt%29._dft-convention%29%29" class="RktValDef RktValLink" data-pltdoc="x">dft-convention</a></span></span><span class="hspace"> </span><span class="RktVar">lst</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=void.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._void%7E3f%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">void?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">lst</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=ts-reference&rel=type-ref.html%23%2528form._%2528%2528lib._typed-racket%252Fbase-env%252Fbase-types-extra..rkt%2529._.List%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">List</a></span><span class="hspace"> </span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=ts-reference&rel=type-ref.html%23%2528form._%2528%2528lib._typed-racket%252Fbase-env%252Fbase-types..rkt%2529._.Real%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">Real</a></span><span class="hspace"> </span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=ts-reference&rel=type-ref.html%23%2528form._%2528%2528lib._typed-racket%252Fbase-env%252Fbase-types..rkt%2529._.Real%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">Real</a></span><span class="RktPn">)</span></td></tr></table></blockquote></div><div class="SIntrapara">A parameter controlling the convention used for scaling discrete Fourier transforms, such as those
performed by <span class="RktSym"><a href="array_other.html#%28def._%28%28lib._math%2Farray..rkt%29._array-fft%29%29" class="RktValLink" data-pltdoc="x">array-fft</a></span>. The default value is <span class="RktVal">'</span><span class="RktVal">(</span><span class="RktVal">1</span><span class="stt"> </span><span class="RktVal"><span class="nobreak">-1</span></span><span class="RktVal">)</span>, which represents the convention
used in signal processing.</div></p><p><div class="SIntrapara">In general, if <span class="RktVar">lst</span> is <span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=pairs.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._list%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">list</a></span><span class="stt"> </span><span class="RktSym">a</span><span class="stt"> </span><span class="RktSym">b</span><span class="RktPn">)</span> and <span class="RktSym">n</span> is the length of a transformed
array axis or vector, then
</div><div class="SIntrapara"><ul><li><p>Each sum is scaled by <span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=generic-numbers.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._expt%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">expt</a></span><span class="stt"> </span><span class="RktSym">n</span><span class="stt"> </span><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=generic-numbers.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._%252F%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">/</a></span><span class="stt"> </span><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=generic-numbers.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._-%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x"><span class="nobreak">-</span></a></span><span class="stt"> </span><span class="RktSym">a</span><span class="stt"> </span><span class="RktVal">1</span><span class="RktPn">)</span><span class="stt"> </span><span class="RktVal">2</span><span class="RktPn">)</span><span class="RktPn">)</span>.</p></li><li><p>Each exponential in the sum has its argument scaled by <span class="RktSym">b</span>.</p></li></ul></div><div class="SIntrapara">Conveniently, a Fourier transform with convention <span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=pairs.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._list%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">list</a></span><span class="stt"> </span><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=generic-numbers.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._-%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x"><span class="nobreak">-</span></a></span><span class="stt"> </span><span class="RktSym">a</span><span class="RktPn">)</span><span class="stt"> </span><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=generic-numbers.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._-%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x"><span class="nobreak">-</span></a></span><span class="stt"> </span><span class="RktSym">b</span><span class="RktPn">)</span><span class="RktPn">)</span> is the inverse
of a Fourier transform with convention <span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=pairs.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._list%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">list</a></span><span class="stt"> </span><span class="RktSym">a</span><span class="stt"> </span><span class="RktSym">b</span><span class="RktPn">)</span>.</div></p><p>See Mathematica’s
<a href="http://reference.wolfram.com/mathematica/tutorial/FourierTransforms.html">documentation
on <span class="stt">Fourier</span></a>, from which this excellent idea was stolen.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._math/utils..rkt)._dft-inverse-convention))"></a><span title="Provided from: math/utils | Package: math-lib"><span class="RktSym"><a href="#%28def._%28%28lib._math%2Futils..rkt%29._dft-inverse-convention%29%29" class="RktValDef RktValLink" data-pltdoc="x">dft-inverse-convention</a></span></span><span class="RktPn"></span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=ts-reference&rel=type-ref.html%23%2528form._%2528%2528lib._typed-racket%252Fbase-env%252Fbase-types-extra..rkt%2529._.List%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">List</a></span><span class="hspace"> </span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=ts-reference&rel=type-ref.html%23%2528form._%2528%2528lib._typed-racket%252Fbase-env%252Fbase-types..rkt%2529._.Real%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">Real</a></span><span class="hspace"> </span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=ts-reference&rel=type-ref.html%23%2528form._%2528%2528lib._typed-racket%252Fbase-env%252Fbase-types..rkt%2529._.Real%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">Real</a></span><span class="RktPn">)</span></p></blockquote></td></tr></table></blockquote></div><div class="SIntrapara">Returns the convention used for inverse Fourier transforms, given the current convention.</div></p><h4 x-source-module="(lib "math/scribblings/math.scrbl")" x-source-pkg="math-doc" x-part-tag=""utils:fpu-test"">10.3<tt> </tt><a name="(part._utils~3afpu-test)"></a>Floating-Point Compliance Testing</h4><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>procedure</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._math/utils..rkt)._test-floating-point))"></a><span title="Provided from: math/utils | Package: math-lib"><span class="RktSym"><a href="#%28def._%28%28lib._math%2Futils..rkt%29._test-floating-point%29%29" class="RktValDef RktValLink" data-pltdoc="x">test-floating-point</a></span></span><span class="hspace"> </span><span class="RktVar">n</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=ts-reference&rel=type-ref.html%23%2528form._%2528%2528lib._typed-racket%252Fbase-env%252Fbase-types..rkt%2529._.Listof%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">Listof</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=ts-reference&rel=type-ref.html%23%2528form._%2528%2528lib._typed-racket%252Fbase-env%252Fbase-types-extra..rkt%2529._.List%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">List</a></span><span class="hspace"> </span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=ts-reference&rel=type-ref.html%23%2528form._%2528%2528lib._typed-racket%252Fbase-env%252Fbase-types..rkt%2529._.Any%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">Any</a></span><span class="hspace"> </span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=ts-reference&rel=type-ref.html%23%2528form._%2528%2528lib._typed-racket%252Fbase-env%252Fbase-types..rkt%2529._.Any%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">Any</a></span><span class="RktPn">)</span><span class="RktPn">)</span></p></blockquote></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">n</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=ts-reference&rel=type-ref.html%23%2528form._%2528%2528lib._typed-racket%252Fbase-env%252Fbase-types..rkt%2529._.Natural%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">Natural</a></span></td></tr></table></blockquote></div><div class="SIntrapara">Runs a comprehensive test of the system’s IEEE 754 (floating-point) compliance, and reports
unexpected inaccuracies and errors.</div></p><p>In each test, a function is applied to some carefully chosen values, as well as <span class="RktVar">n</span> additional
random values.
Its corresponding <a href="bigfloat.html#%28tech._bigfloat%29" class="techoutside" data-pltdoc="x"><span class="techinside">bigfloat</span></a> function is applied to the same values, and the answers are
compared.
Each test returns a list of failures, which are appended and returned.</p><p><div class="SIntrapara">Each failure in a failure list is formatted
</div><div class="SIntrapara"><blockquote class="SCodeFlow"><p><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=pairs.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._list%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">list</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=pairs.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._list%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">list</a></span><span class="hspace"> </span><span class="RktSym">name</span><span class="hspace"> </span><span class="RktSym">args</span><span class="hspace"> </span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=stx-patterns.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fstxcase-scheme..rkt%2529._......%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">...</a></span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktSym">reason</span><span class="RktPn">)</span></p></blockquote></div><div class="SIntrapara">where <span class="RktSym">name</span> is the name of a function, such as <span class="RktVal">'</span><span class="RktVal">fl+</span>, <span class="RktSym">args</span><span class="stt"> </span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=stx-patterns.html%23%2528form._%2528%2528lib._racket%252Fprivate%252Fstxcase-scheme..rkt%2529._......%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">...</a></span> are the
arguments it was applied to, and <span class="RktSym">reason</span> is the reason for the failure.</div></p><p><div class="SIntrapara">If <span class="RktSym">reason</span> is a flonum, the failure was due to inaccuracy. For example,
</div><div class="SIntrapara"><blockquote class="SCodeFlow"><p><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=pairs.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._list%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">list</a></span><span class="hspace"> </span><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=pairs.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._list%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">list</a></span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">fl+</span><span class="hspace"> </span><span class="RktVal">4.5</span><span class="hspace"> </span><span class="RktVal">2.3</span><span class="RktPn">)</span><span class="hspace"> </span><span class="RktVal">0.76</span><span class="RktPn">)</span></p></blockquote></div><div class="SIntrapara">means the result of <span class="RktPn">(</span><span class="RktSym"><a href="flonum.html#%28def._%28%28lib._math%2Fflonum..rkt%29._lg%2A%29%29" class="RktValLink" data-pltdoc="x">fl+</a></span><span class="stt"> </span><span class="RktVal">4.5</span><span class="stt"> </span><span class="RktVal">2.3</span><span class="RktPn">)</span> was off by <span class="RktVal">0.76</span> <a href="flonum.html#%28tech._ulp%29" class="techoutside" data-pltdoc="x"><span class="techinside">ulps</span></a>.</div></p><p>The threshold for reporting unexpected inaccuracy depends on the function tested.
All the arithmetic and irrational functions exported by <a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=flonums.html&version=6.7" class="RktModLink Sq" data-pltdoc="x"><span class="RktSym">racket/flonum</span></a>, for example,
must have no more than <span class="RktVal">0.5</span> ulps error in order to be compliant.</p><p><div class="SIntrapara">Two other possible failure reasons are
</div><div class="SIntrapara"><blockquote class="SCodeFlow"><table cellspacing="0" cellpadding="0" class="RktBlk"><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=pairs.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._list%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">list</a></span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">different-zero</span><span class="hspace"> </span><span class="RktVal">0.0</span><span class="hspace"> </span><span class="RktVal"><span class="nobreak">-0</span>.0</span><span class="RktPn">)</span></td></tr><tr><td><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=pairs.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._list%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">list</a></span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">different-zero</span><span class="hspace"> </span><span class="RktVal"><span class="nobreak">-0</span>.0</span><span class="hspace"> </span><span class="RktVal">0.0</span><span class="RktPn">)</span></td></tr></table></blockquote></div><div class="SIntrapara">The first zero is the answer returned by the function, and the second zero is the expected answer.</div></p><p><div class="SIntrapara">Other possible failure reasons have the form
</div><div class="SIntrapara"><blockquote class="SCodeFlow"><p><span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=pairs.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._list%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">list</a></span><span class="hspace"> </span><span class="RktVal">'</span><span class="RktVal">not-fl2?</span><span class="hspace"> </span><span class="RktSym">x</span><span class="hspace"> </span><span class="RktSym">y</span><span class="RktPn">)</span></p></blockquote></div><div class="SIntrapara">meaning that the result <span class="RktPn">(</span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=values.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._values%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">values</a></span><span class="stt"> </span><span class="RktSym">x</span><span class="stt"> </span><span class="RktSym">y</span><span class="RktPn">)</span> is not a valid flonum expansion.
Such reasons are only given for failures of functions whose names begin with <span class="stt">fl2</span> or contain
<span class="stt">/error</span>.
These functions are currently undocumented, but are used to implement many
<a href="flonum.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">math/flonum</span></a>, <a href="special.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">math/special-functions</span></a>, and
<a href="dist.html" class="RktModLink" data-pltdoc="x"><span class="RktSym">math/distributions</span></a> functions.</div></p><p>Tests of functions that operate on and return flonum expansions are the strictest tests, requiring
hardware arithmetic to be perfectly IEEE 754 compliant.
They reliably fail on seemingly innocuous noncompliant behavior, such as computing intermediate
results with 80-bit precision.</p><p><div class="SIntrapara"><blockquote class="SVInsetFlow"><table cellspacing="0" cellpadding="0" class="boxed RBoxed"><tr><td><blockquote class="SubFlow"><div class="RBackgroundLabel SIEHidden"><div class="RBackgroundLabelInner"><p>parameter</p></div></div><p class="RForeground"><span class="RktPn">(</span><a name="(def._((lib._math/utils..rkt)._print-fp-test-progress~3f))"></a><span title="Provided from: math/utils | Package: math-lib"><span class="RktSym"><a href="#%28def._%28%28lib._math%2Futils..rkt%29._print-fp-test-progress~3f%29%29" class="RktValDef RktValLink" data-pltdoc="x">print-fp-test-progress?</a></span></span><span class="RktPn"></span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=ts-reference&rel=type-ref.html%23%2528form._%2528%2528lib._typed-racket%252Fbase-env%252Fbase-types..rkt%2529._.Boolean%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">Boolean</a></span></p></blockquote></td></tr><tr><td><span class="RktPn">(</span><span title="Provided from: math/utils | Package: math-lib"><span class="RktSym"><a href="#%28def._%28%28lib._math%2Futils..rkt%29._print-fp-test-progress~3f%29%29" class="RktValDef RktValLink" data-pltdoc="x">print-fp-test-progress?</a></span></span><span class="hspace"> </span><span class="RktVar">print?</span><span class="RktPn">)</span><span class="hspace"> </span>→<span class="hspace"> </span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=reference&rel=void.html%23%2528def._%2528%2528quote._%7E23%7E25kernel%2529._void%7E3f%2529%2529&version=6.7" class="RktValLink Sq" data-pltdoc="x">void?</a></span></td></tr><tr><td><span class="hspace"> </span><span class="RktVar">print?</span><span class="hspace"> </span>:<span class="hspace"> </span><span class="RktSym"><a href="https://download.racket-lang.org/docs/6.7/html/local-redirect/index.html?doc=ts-reference&rel=type-ref.html%23%2528form._%2528%2528lib._typed-racket%252Fbase-env%252Fbase-types..rkt%2529._.Boolean%2529%2529&version=6.7" class="RktStxLink Sq" data-pltdoc="x">Boolean</a></span></td></tr></table></blockquote></div><div class="SIntrapara">When <span class="RktPn">(</span><span class="RktSym"><a href="#%28def._%28%28lib._math%2Futils..rkt%29._print-fp-test-progress~3f%29%29" class="RktValLink" data-pltdoc="x">print-fp-test-progress?</a></span><span class="RktPn">)</span> is <span class="RktVal">#t</span>, floating-point tests print and flush a
representation of their progress as they run. The default value is <span class="RktVal">#t</span>.</div></p><div class="navsetbottom"><span class="navleft"><form class="searchform"><input class="searchbox" style="color: #888;" type="text" value="...search manuals..." title="Enter a search string to search the manuals" onkeypress="return DoSearchKey(event, this, "6.7", "../");" onfocus="this.style.color="black"; this.style.textAlign="left"; if (this.value == "...search manuals...") this.value="";" onblur="if (this.value.match(/^ *$/)) { this.style.color="#888"; this.style.textAlign="center"; this.value="...search manuals..."; }"/></form> <a href="../index.html" title="up to the documentation top" data-pltdoc="x" onclick="return GotoPLTRoot("6.7");">top</a></span><span class="navright"> <a href="dist_flonum.html" title="backward to "9.6 Low-Level Distribution Functions"" data-pltdoc="x">← prev</a> <a href="index.html" title="up to "Math Library"" data-pltdoc="x">up</a> <span class="nonavigation">next →</span></span> </div></div></div><div id="contextindicator"> </div></body></html>
|