diff options
author | Karl Berry <karl@freefriends.org> | 2019-01-05 22:40:38 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2019-01-05 22:40:38 +0000 |
commit | 22536bb2b5257046d271b1eaa11b4a275d5ec041 (patch) | |
tree | 2500eaf5c26b11e00ebd33a64fccfa332cd5a66c /Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fpu.tex | |
parent | cf794f0e2db6857972a9d48d4466a4f03a7057a0 (diff) |
pgf (5jan19)
git-svn-id: svn://tug.org/texlive/trunk@49607 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fpu.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fpu.tex | 660 |
1 files changed, 343 insertions, 317 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fpu.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fpu.tex index 7177e771b95..bdc58135ef0 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fpu.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-fpu.tex @@ -9,183 +9,197 @@ \section{Floating Point Unit Library} -{\noindent {\emph{by Christian Feuers\"anger}}} \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--of between speed and accuracy. It does not require any - third--party packages or external programs. + 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--of 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 - lowlevel 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. + +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{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}[] \pgfkeys{/pgf/fpu} \pgfmathparse{1+1}\pgfmathresult \end{codeexample} - \noindent The FPU uses a lowlevel 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. + % + \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. %-------------------------------------------------- % \begin{codeexample}[] % \begin{tikzpicture} -% \fill[red,fpu,/pgf/fpu/scale results=1e-10] (*1.234e10,*1e10) -- (*2e10,*2e10); +% \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. + 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. + It does not hurt to call |fpu=true| or |fpu=false| multiple times. - Please note that if the |fixed point arithmetics| library of - \pgfname\ will be activated after the FPU, the FPU will be - deactivated automatically. + Please note that if the |fixed point arithmetics| 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. + 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}[] \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. + The choice |sci| returns numbers in the format + \meta{mantissa}|e|\meta{exponent}. It provides almost no computational + overhead. + % \begin{codeexample}[] \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. + 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}[] \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}. + 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|. + /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. + 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} + \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 |fixed point arithmetic| library. The -differences between the FPU and |fp| are: + +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 |fixed point arithmetic| 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). + \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$. + 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 + 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: + % + 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} @@ -221,48 +235,50 @@ Flags: \F; Mantissa \M; Exponent \E. \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). + % + 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!). + 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. + 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!). + 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. + 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 - lowlevel 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}. + 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. + 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. + 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). - + 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} @@ -280,61 +296,67 @@ $\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). + 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. + 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|. + 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$. + Expands a number from low-level floating point representation to scientific + format, $1.234e4$. - Use |\pgfmathfloatvalueof| in contexts where only expandable macros are allowed. + 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|. + 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} - + 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}[] \pgfmathfloatparsenumber{42} \pgfmathfloatifflags{\pgfmathresult}{0}{It's zero!}{It's not zero!} @@ -345,307 +367,311 @@ Flags: \F; Mantissa \M; Exponent \E \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}. + 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}. + 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. + 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. + 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}. + 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}. + 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}. + 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}. + 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}. + 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. +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}. + 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. + 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. + 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). + 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. +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. +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. + 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. + 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. + 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} + 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. + 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}. + 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. + 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. + 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|. + 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} + \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. + 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. + 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. + 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. + 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. + The result is returned as floating point number as well. - See also |\pgfmathfloattoint| which returns the number in integer - format. + 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. + 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}[] \pgfmathlog{1.452e-7} \pgfmathresult \end{codeexample} + % \begin{codeexample}[] \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. +\subsubsection{Accessing the Original Math Routines for Programmers} -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. +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 |