summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/pgfmanual-en-library-fpu.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-library-fpu.tex')
-rw-r--r--graphics/pgf/base/doc/pgfmanual-en-library-fpu.tex714
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