diff options
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-library-fpu.tex')
-rw-r--r-- | graphics/pgf/base/doc/pgfmanual-en-library-fpu.tex | 714 |
1 files changed, 714 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-library-fpu.tex b/graphics/pgf/base/doc/pgfmanual-en-library-fpu.tex new file mode 100644 index 0000000000..b6fa991127 --- /dev/null +++ b/graphics/pgf/base/doc/pgfmanual-en-library-fpu.tex @@ -0,0 +1,714 @@ +% Copyright 2019 by Christian Feuersaenger +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Free Documentation License. +% +% See the file doc/generic/pgf/licenses/LICENSE for more details. + + +\section{Floating Point Unit Library} +\label{pgfmath-floatunit} +\label{section-library-fpu} + +{\noindent {\emph{by Christian Feuersänger}}} + +\begingroup +\pgfqkeys{/pgf/number format}{sci} +\pgfkeys{/pgf/fpu} + +\begin{pgflibrary}{fpu} + The floating point unit (fpu) allows the full data range of scientific + computing for use in \pgfname. Its core is the \pgfname\ math routines for + mantissa operations, leading to a reasonable trade-off between speed and + accuracy. It does not require any third-party packages or external + programs. +\end{pgflibrary} + + +\subsection{Overview} + +The fpu provides a replacement set of math commands which can be installed in +isolated placed to achieve large data ranges at reasonable accuracy. It +provides at least% + \footnote{To be more precise, the FPU's exponent is currently a 32-bit + integer. That means it supports a significantly larger data range than an + IEEE double precision number -- but if a future \TeX\ version may provide + low-level access to doubles, this may change.}% +the IEEE double precision data range, $\pgfmathprintnumber{-1e+324}, \dotsc, +\pgfmathprintnumber{+1e324}$. The absolute smallest number bigger than zero is +$\pgfmathprintnumber{1e-324}$. The FPU's relative precision is at least +$\pgfmathprintnumber{1e-4}$ although operations like addition have a relative +precision of $\pgfmathprintnumber{1e-6}$. + +Note that the library has not really been tested together with any drawing +operations. It should be used to work with arbitrary input data which is then +transformed somehow into \pgfname\ precision. This, in turn, can be processed +by \pgfname. + + +\subsection{Usage} + +\begin{key}{/pgf/fpu=\marg{boolean} (default true)} + This key installs or uninstalls the FPU. The installation exchanges any + routines of the standard math parser with those of the FPU: |\pgfmathadd| + will be replaced with |\pgfmathfloatadd| and so on. Furthermore, any number + will be parsed with |\pgfmathfloatparsenumber|. + % +\begin{codeexample}[preamble={\usepgflibrary{fpu}}] +\pgfkeys{/pgf/fpu} +\pgfmathparse{1+1}\pgfmathresult +\end{codeexample} + % + \noindent The FPU uses a low-level number representation consisting of + flags, mantissa and exponent% + \footnote{Users should \emph{always} use high + level routines to manipulate floating point numbers as the format may + change in a future release.}.% + To avoid unnecessary format conversions, |\pgfmathresult| will usually + contain such a cryptic number. Depending on the context, the result may + need to be converted into something which is suitable for \pgfname\ + processing (like coordinates) or may need to be typeset. The FPU provides + such methods as well. + +%-------------------------------------------------- +% TODOsp: codeexamples: Why is this example commented? +% \begin{codeexample}[preamble={\usepgflibrary{fpu}}] +% \begin{tikzpicture} +% \fill[red,fpu,/pgf/fpu/scale results=1e-10] (*1.234e10,*1e10) -- (*2e10,*2e10); +% \end{tikzpicture} +% \end{codeexample} +%-------------------------------------------------- + + Use |fpu=false| to deactivate the FPU. This will restore any change. Please + note that this is not necessary if the FPU is used inside of a \TeX\ group + -- it will be deactivated afterwards anyway. + + It does not hurt to call |fpu=true| or |fpu=false| multiple times. + + Please note that if the |fixedpointarithmetic| library of \pgfname\ will + be activated after the FPU, the FPU will be deactivated automatically. +\end{key} + +\begin{key}{/pgf/fpu/output format=\mchoice{float,sci,fixed} (initially float)} + This key allows to change the number format in which the FPU assigns + |\pgfmathresult|. + + The predefined choice |float| uses the low-level format used by the FPU. + This is useful for further processing inside of any library. + % +\begin{codeexample}[preamble={\usepgflibrary{fpu}}] +\pgfkeys{/pgf/fpu,/pgf/fpu/output format=float} +\pgfmathparse{exp(50)*42}\pgfmathresult +\end{codeexample} + + The choice |sci| returns numbers in the format + \meta{mantissa}|e|\meta{exponent}. It provides almost no computational + overhead. + % +\begin{codeexample}[preamble={\usepgflibrary{fpu}}] +\pgfkeys{/pgf/fpu,/pgf/fpu/output format=sci} +\pgfmathparse{4.22e-8^-2}\pgfmathresult +\end{codeexample} + + The choice |fixed| returns normal fixed point numbers and provides the + highest compatibility with the \pgfname\ engine. It is activated + automatically in case the FPU scales results. + % +\begin{codeexample}[preamble={\usepgflibrary{fpu}}] +\pgfkeys{/pgf/fpu,/pgf/fpu/output format=fixed} +\pgfmathparse{sqrt(1e-12)}\pgfmathresult +\end{codeexample} + % +\end{key} + +\begin{key}{/pgf/fpu/scale results=\marg{scale}} + A feature which allows semi-automatic result scaling. Setting this key has + two effects: first, the output format for \emph{any} computation will be + set to |fixed| (assuming results will be processed by \pgfname's kernel). + Second, any expression which starts with a star, |*|, will be multiplied + with \meta{scale}. +\end{key} + +\begin{keylist}{ + /pgf/fpu/scale file plot x=\marg{scale},% + /pgf/fpu/scale file plot y=\marg{scale},% + /pgf/fpu/scale file plot z=\marg{scale}% +} + These keys will patch \pgfname's |plot file| command to automatically scale + single coordinates by \meta{scale}. + + The initial setting does not scale |plot file|. +\end{keylist} + +\begin{command}{\pgflibraryfpuifactive\marg{true-code}\marg{false-code}} + This command can be used to execute either \meta{true-code} or + \meta{false-code}, depending on whether the FPU has been activated or not. +\end{command} + +\begin{key}{/pgf/fpu/install only=\marg{list of names}} + \label{fpu-install-only} + Unfortunately, the FPU is currently incompatible with drawing operations. + However, it can still be useful to replace single definitions with FPU + counterparts to avoid errors of the kind |Dimension too large| which tend + to happen when transformation matrices are inverted. + + This key allows to specify a list of definitions to be pulled into the + current scope. \emph{Note that there is no reverse operation to uninstall + these definitions at the moment}, so it is advisable to do this in a group. + Conveniently, \tikzname{} paths form an implicit group, so you can use this + key on a path as well. + + You have to be aware of the limitations that the FPU imposes. It will not + magically give \TeX{} better precision, but it will avoid overflow or + underflow situations for large or small operands by rescaling them. In the + following example, in the first case the FPU variant performs much better + than the normal variant, however, in the second case where a rescaling + would not in fact be needed the rescaling introduces a small round-off + error. + % +\begin{codeexample}[ + preamble={\usepgflibrary{fpu}}, + pre={\pgfkeys{/pgf/fpu=false}}, +] +\begingroup +\pgfkeys{/pgf/fpu/install only={divide}} +\pgfmathparse{12.34/0.001234}\pgfmathresult (good) +\pgfmathparse{12/4}\pgfmathresult (bad) +\endgroup +\end{codeexample} + % + This key is introduced in \pgfname v3.1.6 and marked stable since \pgfname + v3.1.8. +\end{key} + + +\subsection{Comparison to the fixed point arithmetics library} + +There are other ways to increase the data range and/or the precision of +\pgfname's math parser. One of them is the |fp| package, preferable combined +with \pgfname's |fixedpointarithmetic| library. The differences between the FPU +and |fp| are: +% +\begin{itemize} + \item The FPU supports at least the complete IEEE double precision number + range, while |fp| covers only numbers of magnitude + $\pm\pgfmathprintnumber{1e17}$. + \item The FPU has a uniform relative precision of about 4--5 correct + digits. The fixed point library has an absolute precision which may + perform good in many cases -- but will fail at the ends of the data + range (as every fixed point routines does). + \item The FPU has potential to be faster than |fp| as it has access to fast + mantissa operations using \pgfname's math capabilities (which use \TeX\ + registers). +\end{itemize} + + +\subsection{Command Reference and Programmer's Manual} + +\subsubsection{Creating and Converting Floats} + +\begin{command}{\pgfmathfloatparsenumber\marg{x}} + Reads a number of arbitrary magnitude and precision and stores its result + into |\pgfmathresult| as floating point number $m \cdot 10^e$ with mantissa + and exponent base~$10$. + + The algorithm and the storage format is purely text-based. The number is + stored as a triple of flags, a positive mantissa and an exponent, such as + % +\begin{codeexample}[] +\pgfmathfloatparsenumber{2} +\pgfmathresult +\end{codeexample} + % + Please do not rely on the low-level representation here, use + |\pgfmathfloattomacro| (and its variants) and |\pgfmathfloatcreate| if you + want to work with these components. + + The flags encoded in |\pgfmathresult| are represented as a digit where + `$0$' stands for the number $\pm 0\cdot 10^0$, `$1$' stands for a positive + sign, `$2$' means a negative sign, `$3$' stands for `not a number', `$4$' + means $+\infty$ and `$5$' stands for $-\infty$. + + The mantissa is a normalized real number $m \in \mathbb{R}$, $1 \le m < + 10$. It always contains a period and at least one digit after the period. + The exponent is an integer. + + Examples: + % +\begin{codeexample}[] +\pgfmathfloatparsenumber{0} +\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} +Flags: \F; Mantissa \M; Exponent \E. +\end{codeexample} + +\begin{codeexample}[] +\pgfmathfloatparsenumber{0.2} +\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} +Flags: \F; Mantissa \M; Exponent \E. +\end{codeexample} + +\begin{codeexample}[] +\pgfmathfloatparsenumber{42} +\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} +Flags: \F; Mantissa \M; Exponent \E. +\end{codeexample} + +\begin{codeexample}[] +\pgfmathfloatparsenumber{20.5E+2} +\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} +Flags: \F; Mantissa \M; Exponent \E. +\end{codeexample} + +\begin{codeexample}[] +\pgfmathfloatparsenumber{1e6} +\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} +Flags: \F; Mantissa \M; Exponent \E. +\end{codeexample} + +\begin{codeexample}[] +\pgfmathfloatparsenumber{5.21513e-11} +\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} +Flags: \F; Mantissa \M; Exponent \E. +\end{codeexample} + % + The argument \meta{x} may be given in fixed point format or the scientific + ``e'' (or ``E'') notation. The scientific notation does not necessarily + need to be normalized. The supported exponent range is (currently) only + limited by the \TeX-integer range (which uses 31 bit integer numbers). +\end{command} + +\begin{key}{/pgf/fpu/handlers/empty number=\marg{input}\marg{unreadable part}} + This command key is invoked in case an empty string is parsed inside of + |\pgfmathfloatparsenumber|. You can overwrite it to assign a replacement + |\pgfmathresult| (in float!). + + The initial setting is to invoke |invalid number|, see below. +\end{key} + +\begin{key}{/pgf/fpu/handlers/invalid number=\marg{input}\marg{unreadable part}} + This command key is invoked in case an invalid string is parsed inside of + |\pgfmathfloatparsenumber|. You can overwrite it to assign a replacement + |\pgfmathresult| (in float!). + + The initial setting is to generate an error message. +\end{key} + +\begin{key}{/pgf/fpu/handlers/wrong lowlevel format=\marg{input}\marg{unreadable part}} + This command key is invoked whenever |\pgfmathfloattoregisters| or its + variants encounter something which is not a properly formatted low-level + floating point number. As for |invalid number|, this key may assign a new + |\pgfmathresult| (in floating point) which will be used instead of the + offending \meta{input}. + + The initial setting is to generate an error message. +\end{key} + +\begin{command}{\pgfmathfloatqparsenumber\marg{x}} + The same as |\pgfmathfloatparsenumber|, but does not perform sanity checking. +\end{command} + +\begin{command}{\pgfmathfloattofixed{\marg{x}}} + Converts a number in floating point representation to a fixed point number. + It is a counterpart to |\pgfmathfloatparsenumber|. The algorithm is purely + text based and defines |\pgfmathresult| as a string sequence which + represents the floating point number \meta{x} as a fixed point number (of + arbitrary precision). + % +\begin{codeexample}[] +\pgfmathfloatparsenumber{0.00052} +\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} +Flags: \F; Mantissa \M; Exponent \E +$\to$ +\pgfmathfloattofixed{\pgfmathresult} +\pgfmathresult +\end{codeexample} + +\begin{codeexample}[] +\pgfmathfloatparsenumber{123.456e4} +\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} +Flags: \F; Mantissa \M; Exponent \E +$\to$ +\pgfmathfloattofixed{\pgfmathresult} +\pgfmathresult +\end{codeexample} + % +\end{command} + +\begin{command}{\pgfmathfloattoint\marg{x}} + Converts a number from low-level floating point representation to an + integer (by truncating the fractional part). + % +\begin{codeexample}[] +\pgfmathfloatparsenumber{123456} +\pgfmathfloattoint{\pgfmathresult} +\pgfmathresult +\end{codeexample} + + See also |\pgfmathfloatint| which returns the result as float. +\end{command} + +\begin{command}{\pgfmathfloattosci\marg{float}} + Converts a number from low-level floating point representation to + scientific format, $1.234e4$. The result will be assigned to the macro + |\pgfmathresult|. +\end{command} + +\begin{command}{\pgfmathfloatvalueof\marg{float}} + Expands a number from low-level floating point representation to scientific + format, $1.234e4$. + + Use |\pgfmathfloatvalueof| in contexts where only expandable macros are + allowed. +\end{command} + +\begin{command}{\pgfmathfloatcreate{\marg{flags}}{\marg{mantissa}}{\marg{exponent}}} + Defines |\pgfmathresult| as the floating point number encoded by + \meta{flags}, \meta{mantissa} and \meta{exponent}. + + All arguments are characters and will be expanded using |\edef|. + % +\begin{codeexample}[] +\pgfmathfloatcreate{1}{1.0}{327} +\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E} +Flags: \F; Mantissa \M; Exponent \E +\end{codeexample} + % +\end{command} + +\begin{command}{\pgfmathfloatifflags\marg{floating point number}\marg{flag}\marg{true-code}\marg{false-code}} + Invokes \meta{true-code} if the flag of \meta{floating point number} equals + \meta{flag} and \meta{false-code} otherwise. + + The argument \meta{flag} can be one of + % + \begin{description} + \item[0] to test for zero, + \item[1] to test for positive numbers, + \item[+] to test for positive numbers, + \item[2] to test for negative numbers, + \item[-] to test for negative numbers, + \item[3] for ``not-a-number'', + \item[4] for $+\infty$, + \item[5] for $-\infty$. + \end{description} + % +\begin{codeexample}[preamble={\usetikzlibrary{fpu}}] +\pgfmathfloatparsenumber{42} +\pgfmathfloatifflags{\pgfmathresult}{0}{It's zero!}{It's not zero!} +\pgfmathfloatifflags{\pgfmathresult}{1}{It's positive!}{It's not positive!} +\pgfmathfloatifflags{\pgfmathresult}{2}{It's negative!}{It's not negative!} + +% or, equivalently +\pgfmathfloatifflags{\pgfmathresult}{+}{It's positive!}{It's not positive!} +\pgfmathfloatifflags{\pgfmathresult}{-}{It's negative!}{It's not negative!} +\end{codeexample} + % +\end{command} + +\begin{command}{\pgfmathfloattomacro{\marg{x}}{\marg{flagsmacro}}{\marg{mantissamacro}}{\marg{exponentmacro}}} + Extracts the flags of a floating point number \meta{x} to + \meta{flagsmacro}, the mantissa to \meta{mantissamacro} and the exponent to + \meta{exponentmacro}. +\end{command} + +\begin{command}{\pgfmathfloattoregisters{\marg{x}}{\marg{flagscount}}{\marg{mantissadimen}}{\marg{exponentcount}}} + Takes a floating point number \meta{x} as input and writes flags to count + register \meta{flagscount}, mantissa to dimen register \meta{mantissadimen} + and exponent to count register \meta{exponentcount}. + + Please note that this method rounds the mantissa to \TeX-precision. +\end{command} + +\begin{command}{\pgfmathfloattoregisterstok{\marg{x}}{\marg{flagscount}}{\marg{mantissatoks}}{\marg{exponentcount}}} + A variant of |\pgfmathfloattoregisters| which writes the mantissa into a + token register. It maintains the full input precision. +\end{command} + +\begin{command}{\pgfmathfloatgetflags{\marg{x}}{\marg{flagscount}}} + Extracts the flags of \meta{x} into the count register \meta{flagscount}. +\end{command} + +\begin{command}{\pgfmathfloatgetflagstomacro{\marg{x}}{\marg{macro}}} + Extracts the flags of \meta{x} into the macro \meta{macro}. +\end{command} + +\begin{command}{\pgfmathfloatgetmantissa{\marg{x}}{\marg{mantissadimen}}} + Extracts the mantissa of \meta{x} into the dimen register + \meta{mantissadimen}. +\end{command} + +\begin{command}{\pgfmathfloatgetmantissatok{\marg{x}}{\marg{mantissatoks}}} + Extracts the mantissa of \meta{x} into the token register + \meta{mantissatoks}. +\end{command} + +\begin{command}{\pgfmathfloatgetexponent{\marg{x}}{\marg{exponentcount}}} + Extracts the exponent of \meta{x} into the count register + \meta{exponentcount}. +\end{command} + + +\subsubsection{Symbolic Rounding Operations} + +Commands in this section constitute the basic level implementations of the +rounding routines. They work symbolically, i.e.\ they operate on text, not on +numbers and allow arbitrarily large numbers. + +\begin{command}{\pgfmathroundto{\marg{x}}} + Rounds a fixed point number to prescribed precision and writes the result + to |\pgfmathresult|. + + The desired precision can be configured with + |/pgf/number format/precision|, see section~\ref{pgfmath-numberprinting}. + This section does also contain application examples. + + Any trailing zeros after the period are discarded. The algorithm is purely + text based and allows to deal with precisions beyond \TeX's fixed point + support. + + As a side effect, the global boolean |\ifpgfmathfloatroundhasperiod| will + be set to true if and only if the resulting mantissa has a period. + Furthermore, |\ifpgfmathfloatroundmayneedrenormalize| will be set to true + if and only if the rounding result's floating point representation would + have a larger exponent than \meta{x}. + % +\begin{codeexample}[] +\pgfmathroundto{1} +\pgfmathresult +\end{codeexample} + % +\begin{codeexample}[] +\pgfmathroundto{4.685} +\pgfmathresult +\end{codeexample} + % +\begin{codeexample}[] +\pgfmathroundto{19999.9996} +\pgfmathresult +\end{codeexample} + % +\end{command} + +\begin{command}{\pgfmathroundtozerofill{\marg{x}}} + A variant of |\pgfmathroundto| which always uses a fixed number of digits + behind the period. It fills missing digits with zeros. + % +\begin{codeexample}[] +\pgfmathroundtozerofill{1} +\pgfmathresult +\end{codeexample} + % +\begin{codeexample}[] +\pgfmathroundto{4.685} +\pgfmathresult +\end{codeexample} + % +\begin{codeexample}[] +\pgfmathroundtozerofill{19999.9996} +\pgfmathresult +\end{codeexample} + % +\end{command} + +\begin{command}{\pgfmathfloatround{\marg{x}}} + Rounds a normalized floating point number to a prescribed precision and + writes the result to |\pgfmathresult|. + + The desired precision can be configured with + |/pgf/number format/precision|, see section~\ref{pgfmath-numberprinting}. + + This method employs |\pgfmathroundto| to round the mantissa and applies + renormalization if necessary. + + As a side effect, the global boolean |\ifpgfmathfloatroundhasperiod| will + be set to true if and only if the resulting mantissa has a period. + % +\begin{codeexample}[] +\pgfmathfloatparsenumber{52.5864} +\pgfmathfloatround{\pgfmathresult} +\pgfmathfloattosci{\pgfmathresult} +\pgfmathresult +\end{codeexample} + % +\begin{codeexample}[] +\pgfmathfloatparsenumber{9.995} +\pgfmathfloatround{\pgfmathresult} +\pgfmathfloattosci{\pgfmathresult} +\pgfmathresult +\end{codeexample} + % +\end{command} + +\begin{command}{\pgfmathfloatroundzerofill{\marg{x}}} + A variant of |\pgfmathfloatround| produces always the same number of digits + after the period (it includes zeros if necessary). + % +\begin{codeexample}[] +\pgfmathfloatparsenumber{52.5864} +\pgfmathfloatroundzerofill{\pgfmathresult} +\pgfmathfloattosci{\pgfmathresult} +\pgfmathresult +\end{codeexample} + % +\begin{codeexample}[] +\pgfmathfloatparsenumber{9.995} +\pgfmathfloatroundzerofill{\pgfmathresult} +\pgfmathfloattosci{\pgfmathresult} +\pgfmathresult +\end{codeexample} + % +\end{command} + + +\subsubsection{Math Operations Commands} + +This section describes some of the replacement commands in more detail. + +Please note that these commands can be used even if the |fpu| as such has not +been activated -- it is sufficient to load the library. + +\begin{command}{\pgfmathfloat\meta{op}} + Methods of this form constitute the replacement operations where \meta{op} + can be any of the well-known math operations. + + Thus, \declareandlabel{\pgfmathfloatadd} is the counterpart for + |\pgfmathadd| and so on. The semantics and number of arguments is the same, + but all input and output arguments are \emph{expected} to be floating point + numbers. +\end{command} + +\begin{command}{\pgfmathfloattoextentedprecision{\marg{x}}} + Renormalizes \meta{x} to extended precision mantissa, meaning $100 \le m < + 1000$ instead of $1 \le m < 10$. + + The ``extended precision'' means we have higher accuracy when we apply + pgfmath operations to mantissas. + + The input argument is expected to be a normalized floating point number; + the output argument is a non-normalized floating point number (well, + normalized to extended precision). + + The operation is supposed to be very fast. +\end{command} + +\begin{command}{\pgfmathfloatsetextprecision\marg{shift}} + Sets the precision used inside of |\pgfmathfloattoextentedprecision| to + \meta{shift}. + + The different choices are + + \begin{tabular}{llrll} + 0 & normalization to & $0$ & $\le m < 1$ & (disable extended precision) \\ + 1 & normalization to & $10$ & $\le m < 100$ & \\ + 2 & normalization to & $100$ & $\le m < 1000$ & (default of |\pgfmathfloattoextentedprecision|) \\ + 3 & normalization to & $1000$ & $\le m < 10000$ & \\ + \end{tabular} +\end{command} + +\begin{command}{\pgfmathfloatlessthan{\marg{x}}{\marg{y}}} + Defines |\pgfmathresult| as $1.0$ if $\meta{x} < \meta{y}$, but $0.0$ + otherwise. It also sets the global \TeX-boolean |\pgfmathfloatcomparison| + accordingly. The arguments \meta{x} and \meta{y} are expected to be numbers + which have already been processed by |\pgfmathfloatparsenumber|. Arithmetic + is carried out using \TeX-registers for exponent- and mantissa comparison. +\end{command} + +\begin{command}{\pgfmathfloatmultiplyfixed\marg{float}\marg{fixed}} + Defines |\pgfmathresult| to be $\meta{float} \cdot \meta{fixed}$ where + \meta{float} is a floating point number and \meta{fixed} is a fixed point + number. The computation is performed in floating point arithmetics, that + means we compute $m \cdot \meta{fixed}$ and renormalize the result where + $m$ is the mantissa of \meta{float}. + + This operation renormalizes \meta{float} with + |\pgfmathfloattoextentedprecision| before the operation, that means it is + intended for relatively small arguments of \meta{fixed}. The result is a + floating point number. +\end{command} + +\begin{command}{\pgfmathfloatifapproxequalrel\marg{a}\marg{b}\marg{true-code}\marg{false-code}} + Computes the relative error between \meta{a} and \meta{b} (assuming + \meta{b}$\neq 0$) and invokes \meta{true-code} if the relative error is + below |/pgf/fpu/rel thresh| and \meta{false-code} if that is not the case. + + The input arguments will be parsed with |\pgfmathfloatparsenumber|. + + \begin{key}{/pgf/fpu/rel thresh=\marg{number} (initially 1e-4)} + A threshold used by |\pgfmathfloatifapproxequalrel| to decide whether + numbers are approximately equal. + \end{key} +\end{command} + +\begin{command}{\pgfmathfloatshift{\marg{x}}{\marg{num}}} + Defines |\pgfmathresult| to be $\meta{x} \cdot 10^{\meta{num}}$. The + operation is an arithmetic shift base ten and modifies only the exponent of + \meta{x}. The argument \meta{num} is expected to be a (positive or + negative) integer. +\end{command} + +\begin{command}{\pgfmathfloatabserror\marg{x}\marg{y}} + Defines |\pgfmathresult| to be the absolute error between two floating + point numbers $x$ and $y$, $\lvert x - y\rvert $ and returns the result as + floating point number. +\end{command} + +\begin{command}{\pgfmathfloatrelerror\marg{x}\marg{y}} + Defines |\pgfmathresult| to be the relative error between two floating + point numbers $x$ and $y$, $\lvert x - y\rvert / \lvert y \rvert$ and + returns the result as floating point number. +\end{command} + +\begin{command}{\pgfmathfloatint\marg{x}} + Returns the integer part of the floating point number \meta{x}, by + truncating any digits after the period. This methods truncates the absolute + value $\rvert x \lvert$ to the next smaller integer and restores the + original sign afterwards. + + The result is returned as floating point number as well. + + See also |\pgfmathfloattoint| which returns the number in integer format. +\end{command} + +\begin{command}{\pgfmathlog{\marg{x}}} + Defines |\pgfmathresult| to be the natural logarithm of \meta{x}, + $\ln(\meta{x})$. This method is logically the same as |\pgfmathln|, but it + applies floating point arithmetics to read number \meta{x} and employs the + logarithm identity \[ \ln(m \cdot 10^e) = \ln(m) + e \cdot \ln(10) \] to + get the result. The factor $\ln(10)$ is a constant, so only $\ln(m)$ with + $1 \le m < 10$ needs to be computed. This is done using standard pgf math + operations. + + Please note that \meta{x} needs to be a number, expression parsing is not + possible here. + + If \meta{x} is \emph{not} a bounded positive real number (for example + $\meta{x} \le 0$), |\pgfmathresult| will be \emph{empty}, no error message + will be generated. + % +\begin{codeexample}[preamble={\usetikzlibrary{fpu}}] +\pgfmathlog{1.452e-7} +\pgfmathresult +\end{codeexample} + % +\begin{codeexample}[preamble={\usetikzlibrary{fpu}}] +\pgfmathlog{6.426e+8} +\pgfmathresult +\end{codeexample} + % +\end{command} + + +\subsubsection{Accessing the Original Math Routines for Programmers} + +As soon as the library is loaded, every private math routine will be copied to +a new name. This allows library and package authors to access the \TeX-register +based math routines even if the FPU is activated. And, of course, it allows the +FPU as such to perform its own mantissa computations. + +The private implementations of \pgfname\ math commands, which are of the form +|\pgfmath|\meta{name}|@|, will be available as|\pgfmath@basic@|\meta{name}|@| +as soon as the library is loaded. + +\endgroup |